Epic: GemStack package family + standalone @gemstack/ai-sdk roadmap

[suleimansh]

GemStack package family + roadmap

Tracking epic for the GemStack package family and the work to stand @gemstack/ai-sdk on its own. See Architecture.md for the design rationale (naming rule, dependency direction, MCP taxonomy).

Origin / upstream pointer: this continues the spin-out planned in suleimansh/vike-data#194.

The family

The ai-* prefix means "depends on the agent runtime." A package that is AI-related but agent-agnostic is a peer of the family, not a member.

• @gemstack/ai-sdk - agent runtime (providers, agent loop, tools, streaming, middleware, structured output, memory). Landed; at 0.2.0 the core stands alone (only runtime dep is zod).
• @gemstack/ai-mcp - agent<->MCP bridge (mcpClientTools + mcpServerFromAgent). Depends on ai-sdk. First carve-out. Design: Design: @gemstack/ai-mcp (agent<->MCP bridge, first carve-out) #7. Landed — PR feat(ai-mcp): carve the agent<->MCP bridge into @gemstack/ai-mcp #14 merged; ai-mcp 0.1.0 + ai-sdk 0.2.0->0.3.0 (dropped ./mcp) in release PR chore: version packages #15.
• @gemstack/ai-skills - portable capability bundles (instructions + tools + resources). Depends on ai-sdk. Design: Design: @gemstack/ai-skills (portable capability bundles) #8. Landed — PR feat(ai-skills): add @gemstack/ai-skills — portable capability bundles #16 merged; SKILL.md loader + registry + compose + SkillfulAgent; ai-skills 0.1.0 in release PR chore: version packages #15.
• @gemstack/ai-autopilot - orchestration / autonomy (multi-agent, planning loops, handoffs). Depends on ai-sdk. Design: Design: @gemstack/ai-autopilot (orchestration / autonomy) #9. Landed — PR feat(ai-autopilot): add @gemstack/ai-autopilot — Supervisor orchestration #17 merged; seed slice = Supervisor (plan->dispatch->synthesize); ai-autopilot 0.1.0 in release PR chore: version packages #15. Durable resume + more topologies deferred behind optional seams.
• @gemstack/mcp (NOT ai-*) - standalone MCP server-authoring framework, agent-agnostic. A peer of the family. Design: Design: @gemstack/mcp — standalone MCP server framework (agent-agnostic peer) #18. Landed + published. Phase 1 (feat(mcp): add @gemstack/mcp — agent-agnostic MCP server framework (Phase 1) #22) = agnostic core at 0.1.0 (instance-scoped resolver DI, neutral node:http handler, generic verifyToken OAuth). Public API (Promote MCP server accessors + schema/uri helpers to public API (retire binding-local copies) #24) = 0.2.0 (McpServer.introspect() + zodToJsonSchema/matchUriTemplate). Rudder repoint (Build: @gemstack/mcp Phase 2 — repoint @rudderjs/mcp onto the core (thin binding) #20 / refactor(mcp): repoint @rudderjs/mcp onto @gemstack/mcp as a thin binding rudderjs/rudder#1448 + #1451) = @rudderjs/mcp 6.3.0 is now a thin binding over ^0.2.0, smoke-verified live. Docs (Build: @gemstack/mcp Phase 3 — framework-neutral quickstart/docs (optional) #21) = framework-neutral runnable quickstart (examples/mcp-quickstart).

Design decisions (recorded; all gated on family alignment before code lands)

• Design: @gemstack/ai-mcp (agent<->MCP bridge, first carve-out) #7 ai-mcp: promote to a package (honest optional-dep boundary); hard-move with no shim (ai-sdk 0.2.0 -> 0.3.0, drop ./mcp + the MCP SDK peer; ai-mcp starts 0.1.0; repoint the one internal consumer); bridge only - the server framework stays out.
• Design: @gemstack/ai-skills (portable capability bundles) #8 ai-skills: SKILL.md frontmatter manifest (matches boost/skills + Anthropic shape); reuse ai-sdk tool() directly via a co-located tools.ts; explicit trust boundary (no in-process sandbox); declarative skills() composition with the agent's own declarations authoritative.
• Design: @gemstack/ai-autopilot (orchestration / autonomy) #9 ai-autopilot: autopilot = policy, not mechanism (if a feature just calls a primitive it stays in ai-sdk); seed slice = Supervisor (plan -> dispatch -> synthesize); in-process first, durable runner deferred to an optional adapter.

Follow-up design options (low priority; revisit on demand)

• Design: optional TS-first skill authoring (defineSkill) alongside SKILL.md #11 - optional TS-first skill authoring (defineSkill) alongside SKILL.md.
• Design: optional skill-scoped tool wrapper (skillTool) over tool() #12 - optional skill-scoped tool wrapper (skillTool) over tool().
• Design: optional imperative agent.use(skill) runtime composition #13 - optional imperative agent.use(skill) runtime composition.

Dependency rule

skills, autopilot, ai-mcp all depend on ai-sdk; ai-sdk depends on none of them; nothing depends "up." If the arrows are not one-directional, the split is wrong.

Near-term work (agreed regardless of the family call)

• Phase 1: replace Rudder's packages/ai with a thin deprecated @rudderjs/ai re-export of @gemstack/ai-sdk; publish @gemstack/ai-sdk.
• Phase 2: decouple @gemstack/ai-sdk from @rudderjs/core/@rudderjs/orm behind a neutral, optional adapter seam (also unblocks typecheck/test in this repo).
• CI: scope to build-only until Phase 2 lands (the test suite still pulls broader @rudderjs/* packages).

Open decisions (both resolved - see the decision-record comment below)

• Where the Vike vike-ai binding lives -> vike-data, not gemstack. Already shipped as vike-ai (neutral port, twin of @universal-orm/core) + vike-ai-gemstack (adapter, twin of @universal-orm/rudder). No code enters gemstack; the family stays framework-agnostic.
• @rudderjs/ai "deprecation timeline" -> no removal. It is the living Rudder binding (ORM stores, AiProvider, doctor, make:agent/ai:eval) over the shared engine - the Rudder twin of vike-ai-gemstack, not a dying shim. "Deprecated" applies only to its thin re-export surface. Follow-up: repoint internal dependents (telescope, orm-prisma, orm-drizzle) off the re-export, and reword the stale flat-"[Deprecated]" header.

[suleimansh]

Phases 0-3 complete and published. @gemstack/ai-sdk@0.2.0 standalone (only runtime dep: zod); Rudder ships a deprecated re-export shim @rudderjs/ai@1.18.1 and its dependents (orm-prisma/orm-drizzle/telescope) consume @gemstack/ai-sdk directly; the Vike binding vike-ai-gemstack registers it behind the vike-ai port. Family design issues #7/#8/#9 remain pending alignment.