[AI-stack P3] plugin-ai: ai runtime-registry codegen target for netscript generate

[rickylabs]

Wire plugins/ai into the shared runtime-registry codegen so netscript generate emits static _registry.ts maps for user-authored tools, agents, and skills, the same way plugins/workers and plugins/triggers already do.

Context

Part of epic #238 · cluster plugin-ai · wave v1-min · depends-on P2

This is the codegen-wiring slice for the plugins/ai thin manifest: it only exists once P2 has scaffolded the plugins/ai package shape and the userland ai/tools|agents|skills directories with their type contracts. It must land before any FA/FB fresh-ui or fresh/ai consumer slice can rely on a generated ai registry existing in a scaffolded project.

Problem / motivation

plugin-file-collector.ts and generate-runtime-registries.ts already run a shared generateRuntimeRegistries engine driven purely by a per-plugin scaffold.runtime.json manifest (see plugins/workers/scaffold.runtime.json for workers-job targets and plugins/triggers/scaffold.runtime.json for a map target). plugins/ai has no such manifest, so netscript generate does not discover user tool/agent/skill files or produce a typed lookup map for them. Without this, any runtime that needs to resolve a tool/agent/skill by id (chat backend, fresh/ai client, orchestration primitives) has to hand-roll discovery — the same anti-pattern eis-chat used before this stack existed, which this epic exists to retire.

Scope

Ships

• plugins/ai/scaffold.runtime.json with:
  • runtimeRegistryGenerator.command: "src/cli/generate-runtime-registries.ts" (or a thin re-export delegating to the shared engine — no forked copy)
  • runtimeRegistries: three "kind": "map" targets, one each for ai/tools, ai/agents, ai/skills, each with fileSuffixes: [".ts"], an exclude list covering _registry.ts/mod.ts/types.ts, a registryKey (id), a varPrefix, and a typeImport pointing at the contract types P2 exports (e.g. ToolDefinition, AgentDefinition, SkillDefinition)
  • default registryPath per target (i.e. ai/tools/_registry.ts, ai/agents/_registry.ts, ai/skills/_registry.ts), matching the triggers precedent rather than a .netscript/generated/... path
• Any thin CLI entry file under plugins/ai/src/cli/ needed only to invoke the shared generateRuntimeRegistries(options) engine with this plugin's manifest path

Out of scope

• The shared generateRuntimeRegistries engine itself, or any change to runtime-registry-generator.ts — P3 only supplies a manifest and consumes the existing engine
• The plugins/ai package scaffold, directory layout, and the ToolDefinition/AgentDefinition/SkillDefinition contract types the manifest imports — owned by P2
• SkillLoaderPort and Agent Skills management (blessed SKILL.md loading) — separate slice per the ratified Agent Skills decision
• Orchestration wiring that consumes the generated registries at runtime — owned by the ENGINE-cluster orchestration-primitives slice

Public surface

• New file: plugins/ai/scaffold.runtime.json
• Generated artifacts (build output, not hand-authored): ai/tools/_registry.ts, ai/agents/_registry.ts, ai/skills/_registry.ts, each exporting registry: Map<string, <ContractType>>
• No new package exports, no new subpaths

Acceptance & fitness gates

• deno task check passes for plugins/ai with --unstable-kv
• Running the generator against a scaffolded project with at least one file in each of ai/tools, ai/agents, ai/skills produces all three _registry.ts files with correct imports and a non-empty Map
• Running the generator against an empty/missing ai/* directory produces no output for that target (matches existing discoverRegistryFiles short-circuit — no crash)
• F-3: layering respected — the manifest and any thin CLI wrapper add no cross-layer imports; deno task arch:check clean
• F-13: no new runtime declarations required (this slice adds no state machines or background primitives)
• gate:e2e — scaffold.runtime E2E covers ai plugin add + generate the same way it already asserts workers/triggers/sagas/streams registry generation, confirming ai/tools|agents|skills _registry.ts files exist and type-check in the generated workspace

Dependencies

• Depends on P2 (GitHub numbers tracked in the epic: NetScript AI Stack — first-class AI runtime, chat & plugin seams (anchor #219) #238 DAG checklist) for the plugins/ai scaffold and the tool/agent/skill contract types this manifest's typeImport entries reference.

Size

S

[rickylabs]

Concrete context from eis-chat (the flagship consumer, rickylabs/eis-chat) — a showcase, not a recommendation. Built under app-level constraints (Fresh 2.3 + vite SSR, NetScript alpha.19, single-app embedded, hand-rolled because these seams did not exist yet). One data point to borrow / adapt / reject — the call is yours. — posted by the eis-chat coordinator agent.

No equivalent. eis-chat does no netscript generate codegen for an AI runtime-registry — provider/model/tool wiring is hand-written in app code (lib/llm.ts, lib/models.ts, routes/api/chat.ts), not generated from a manifest. So there is no codegen target or generated artifact to reference; this is a framework-internal seam we simply didn't have.

[rickylabs]

eis-chat matrix: P3 codegen — persisted MCP-server registry is a real consumer need

Matrix (.llm/tmp/run/ai-stack-238--impl/eischat-matrix.md, §20). eis-chat #113 (persisted mcp_servers write path) is a concrete input for the P3 ai runtime-registry codegen: a channel/app owns a persisted MCP-server registry that the generated runtime wiring must read. Design the netscript generate ai target so a persisted per-channel MCP-server list flows into the generated registry, not just static config.

Held behind P2 (#260 / PR #377) by DAG — fires on P2 merge. Reference: apps/dashboard/lib/mcp.ts (pool build from server list), eis-chat #90 (Aspire WithMcpServer — likely an apphost API gap, cross-filed to the deployment lane).