[AI-stack P2] @netscript/plugin-ai manifest + connector + scaffold + in-process emitters

[rickylabs]

Build @netscript/plugin-ai — the thin manifest, connector, and scaffold layer that wires @netscript/ai into a NetScript project with an in-process default topology.

Context

Part of epic #238 · cluster plugin-ai · wave v1-min · depends-on P1, E1, E2, E3, E4, E5, FA0, FA1, FA2, FB0.

This is the terminal integration slice for the v1-min wave: every core primitive (E1-E5), the streams proxy fix (FA0-FA2), and the fresh-ui ai collection (FB0) must exist before the plugin can scaffold a working chat route against them. It sits at the bottom of the DAG on purpose — it is the slice a user actually runs (plugin add ai).

Problem / motivation

Today there is no plugins/ai manifest at all; eis-chat wires @netscript/ai-shaped functionality by hand-rolling provider calls, token counting, and a chat route directly in userland, with no typed scaffold and no contract version negotiation. This repeats the exact anti-pattern the auth plugin split was built to eliminate: business logic and provider wiring living in the app instead of behind a thin, versioned manifest. Per the plugin-thinness law, plugins/ai must stay a manifest + connector + scaffolder — no runtime AI logic — with @netscript/ai and its subpath adapters (P1) doing the actual work.

Scope

Ships

• plugins/ai/mod.ts — manifest built via
  definePlugin('ai', ...).withRuntimeConfigTopics(['ai']).withContractVersions(...).build()
  (no default service, matching the workers reference — the plugin exposes scaffolders and
  runtime-config wiring, not a running service).
• plugins/ai/deno.json, scaffold.plugin.json, scaffold.runtime.json following the
  plugins/workers / plugins/sagas shape.
• plugins/ai/src/scaffolding/ — ItemScaffolders (mirroring
  plugins/workers/src/scaffolding/*-scaffolders.ts):
  • typed barrel (ai.ts re-exporting the configured @netscript/ai client/ports)
  • models.ts starter (provider + model id constants)
  • chat route stub (TanStack-consuming, matching the fresh-ui ai collection primitives from
    FB0)
  • stream-proxy stub (in-process call into @netscript/ai, not a network gateway hop)
  • tool stub and agent stub (thin wrappers over the E-series ports)
• Conditional scaffolders gated by scaffold flags: --mcp (emits an SkillLoaderPort-consuming
  MCP tool stub) and --persist-threads (emits thread-persistence wiring, app-owned per the
  MemoryPort-deferred decision — no bundled store).
• Default topology: in-process (direct @netscript/ai calls from the scaffolded route); no
  network hop, no gateway config emitted by default.

Out of scope

• Gateway topology / --gateway flag and any network-hop proxy config — deferred to a later
  gateway-focused slice (post v1-min, per the ratified in-process-default decision).
• A registry/marketplace target for plugin-ai scaffolds — owned by the marketplace
  plugin-install slice, not this issue.
• The core provider adapters, ports, and contracts themselves (@netscript/ai,
  @netscript/ai/anthropic, usage/OTel/skill-loader ports) — owned by P1 and E1-E5.
• The streams gzip/proxy fix and fresh-ui ai collection registration — owned by FA0-FA2 and FB0
  respectively; this slice only consumes their shipped surface.

Public surface

• plugins/ai/mod.ts exports: aiPlugin (the built manifest) and an AiPluginInspection /
  AiPluginManifest-style type set, matching the workersPlugin / WorkersPluginManifest
  naming convention in plugins/workers/mod.ts.
• plugins/ai/src/scaffolding/mod.ts re-exporting the ItemScaffolder set (barrel, models,
  chat-route, stream-proxy, tool, agent, and the conditional mcp/persist-threads scaffolders).
• plugins/ai/scaffold.plugin.json declaring the scaffold flags (--mcp,
  --persist-threads) and the emitted item list.

Acceptance & fitness gates

• F-3: layering respected — plugins/ai depends only on @netscript/plugin, @netscript/ai
  (and its subpaths), and @netscript/runtime-config; no reverse dependency from core into
  the plugin (deno task arch:check).
• F-5: plugins/ai/mod.ts carries @module JSDoc and stays within the <=20-export cap.
• F-6: publishes via deno task publish:dry-run WITHOUT --allow-slow-types.
• F-13: any long-running scaffolded pieces (stream-proxy stub) declare AbortSignal/stop()
  per the runtime-declaration gate.
• deno task check (with --unstable-kv where workspace code is touched) is green for
  plugins/ai.
• gate:e2e — a scaffold.runtime case that adds the ai plugin to a scaffolded project,
  runs its scaffolders (default topology plus --mcp and --persist-threads variants), and
  type-checks the generated workspace end to end.
• netscript plugin add ai resolves against local-source, and the generated chat route
  compiles against the fresh-ui ai collection primitives shipped in FB0.
• No gateway config, gateway flag, or registry-target code is emitted by any scaffolder in
  this slice.

Dependencies

Depends on P1, E1, E2, E3, E4, E5, FA0, FA1, FA2, FB0 (GitHub numbers tracked in the #238 DAG
checklist). Blocked by #239 (FA0/FA2 anchor bug) via the FA0/FA2 dependency chain.

Size

L

[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 has no plugins/ directory and no AI-gateway service — the engine is embedded in the single Fresh app, wired at the route level, not via a plugin manifest/connector/scaffold. Nothing to cite. Our embedded setup is a data point that a consumer can ship without the plugin manifest at all (the plugin being opt-in, per #238).

[rickylabs]

Scope note — v1-min P2 defers the --mcp/skill scaffolder (run ai-stack-238--impl, drift D5)

Architecture ruling (Fable, per the standing "architecture decisions are yours" directive; coordinator constraint = keep v1-min tight + defer cleanly/tracked):

The --mcp conditional scaffolder in this issue consumes SkillLoaderPort from E5 (deferred out of v1-min). Rather than pull E5 forward and expand the v1-min surface for a single opt-in flag, the --mcp scaffolder and its scaffold.runtime e2e variant are moved OUT of the v1-min P2 acceptance and tracked as a dedicated follow-up: #290.

v1-min P2 (#260) acceptance is now: manifest + deno.json + scaffold.plugin.json/scaffold.runtime.json + the barrel / models / chat-route / stream-proxy / tool / agent scaffolders + --persist-threads (app-owned, no E5 dep), with the default and --persist-threads e2e variants only.

Rationale: --mcp is opt-in and flag-gated — the default first-run plugin add ai a user runs is unchanged either way, so this is an internal sequencing call, not a release-surface/product change. P2 remains blocked on E3 (agent-loop, in flight) for the agent scaffolder; it unblocks the moment E3 lands.