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

[rickylabs]

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

Wires plugins/ai into the shared runtime-registry codegen so netscript generate emits static _registry.ts maps for user-authored AI resources, the same way plugins/workers/plugins/triggers do. Shared engine untouched — this slice only supplies a manifest + a thin CLI that delegates to renderRegistryModule from @netscript/plugin/cli.

Closes #261

What ships

• plugins/ai/scaffold.runtime.json — two targets consumed by the shared regenerateCopiedRuntimeRegistries collector:
  • ai-tools → ai/tools/*.ts → .netscript/generated/plugin-ai/tools.registry.ts, ReadonlyMap<string, AiToolDefinition> keyed by descriptor.name, type from @netscript/ai/tools.
  • ai-agents → ai/agents/*.ts → .netscript/generated/plugin-ai/agents.registry.ts, ReadonlyMap<string, () => AgentLoop> keyed by file stem, type from @netscript/ai/agent.
• src/cli/ai-registry-compiler.ts — owns only the AI specifics (discovered dir, import line, entry/map shape); delegates path math + module assembly to renderRegistryModule. No forked generator logic.
• src/cli/generate-runtime-registries.ts — thin CLI matching the triggers/workers pattern (--project-root/--manifest/--profile/--official-samples parity), loops manifest targets through the compiler.
• src/cli/ai-registry-compiler.test.ts — 3 in-memory unit tests: name-keyed tools (nested + _registry exclusion), stem-keyed agents (mod.ts exclusion), empty/missing-dir short-circuit; plus a generated-output no-unsound-cast assertion.

Grounded decisions (issue body predated P2; 3 assumptions corrected)

1. Skills target deferred to [AI-stack P2-follow] plugins/ai --mcp / skill scaffolder + e2e variant (needs E5 SkillLoaderPort) #290 — P2 ships no skill scaffolder / ai/skills dir / SkillDefinition type (README defers --mcp/skill-loader to [AI-stack P2-follow] plugins/ai --mcp / skill scaffolder + e2e variant (needs E5 SkillLoaderPort) #290, needs E7 SkillLoaderPort). Not invented here.
2. Agents ARE shipped (not deferred) — they are exported factory functions returning AgentLoop, so the registry is stem-keyed () => AgentLoop, which renderRegistryModule's callback design supports.
3. Tool type is AiToolDefinition from @netscript/ai/tools (issue guessed ToolDefinition).

• registryPath = .netscript/generated/plugin-ai/*.registry.ts for sibling-consistency with workers/triggers generated output.
• Soundness: no as/any in shipped runtime code — type-predicate guards only. The one JSON.parse(...) as RuntimeManifest in the CLI is the verbatim manifest-deserialization boundary pattern used by the merged triggers CLI (plugins/triggers/src/cli/generate-runtime-registries.ts:139).

Drift (for the record)

• Skills registry → [AI-stack P2-follow] plugins/ai --mcp / skill scaffolder + e2e variant (needs E5 SkillLoaderPort) #290 (no scaffolder exists yet).
• LocalProjectFiles.listFiles NotFound-on-iterate for a wholly-absent dir (Windows) would crash the generator; guarded locally (catch Deno.errors.NotFound → []) since the shared adapter is out of scope. Worth a follow-up fix in the shared adapter.
• P2's tool stub uses object-form defineAiTool, but the real builder is a string-arg fluent builder — noted, not in scope here.

Validation (author + independent separate-session eval both green)

• plugins/ai CLI tests: 3/3 pass; full plugins/ai suite: 14/14.
• Scoped run-deno-check on plugins/ai (28 files): 0 findings; author's full deno task check (2059 files): 0.
• Scoped run-deno-fmt / run-deno-lint: 0 findings each.
• deno task arch:check: ai FAIL=0 (pre-existing WARN/INFO only, none in new files).
• Author proved generated registries type-check against the real @netscript/ai/tools + @netscript/ai/agent types; missing/empty dir writes nothing (no crash); collector-exact invocation generates both registries.
• No deno.lock churn; diff = 1 manifest edit + 3 new CLI files.

Merge-readiness note

The expensive deno task e2e:cli run scaffold.runtime --cleanup gate (end-to-end collector wiring in a real scaffold) is the remaining merge-gate — recommend running it at merge time.

🤖 Generated with Claude Code

https://claude.ai/code/session_012wKHquACkXnWPDgJYhhFjN