@netscript/plugin-ai-core

The contract-only core for the NetScript AI plugin: the oRPC /v1/ai route surface — an SSE-framed chat stream plus models, tools/{name}, embed, and transcribe — that a connector implements and the typed client calls. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and plugins return to the reference overview.

The package ships zero service implementation (Archetype 1 — Small Contract). It declares the route shapes and their Zod IO vocabulary; a connector (@netscript/plugin-ai) binds the contract to a host and the @netscript/fresh/ai client generates a typed caller from it. Every route schema mirrors an engine type from @netscript/ai/contracts, and a compile-time drift guard (z.ZodType<EngineType> = schema) asserts the mirror cannot silently diverge from the domain contract.

Entrypoints

The package publishes two entrypoints. Each is generated from its own deno doc surface.

The root path curates to the handles and IO types a typical consumer imports (staying within the ≤20-export doctrine budget); the ./contracts/v1 subpath exposes the complete schema and engine-vocabulary set a connector wires.

Root surface (@netscript/plugin-ai-core)

Contract handles and router helpers

Route IO and capability types

Full contract surface (@netscript/plugin-ai-core/contracts/v1)

The subpath re-exports both contract handles (aiContract, aiContractV1), every route IO type above, and the following additional symbols.

Zod IO schemas

Each schema is a named, explicitly-annotated Zod validator (annotated z.ZodType<EngineType> so the module fails to compile if it drifts from the engine contract it mirrors). A connector validates inbound bodies and outbound frames against these.

Engine-derived vocabulary types

The subpath re-exports the @netscript/ai/contracts streaming vocabulary verbatim, so a connector references the same domain types the schemas mirror without reaching into the engine package: AgentChunk, AudioContentPart, CompletionTokensDetails, ContentModality, ContentPart, ContentSource, DataContentSource, DocumentContentPart, DoneChunk, ErrorChunk, ImageContentPart, Message, MessageChunk, MessageContent, MessageRole, ModelCapabilities, ModelDescriptor, ModelId, ModelRef, ModelSelector, ModelsInput, PromptTokensDetails, ProviderUsageDetails, TextChunk, TextContentPart, ToolCall, ToolCallChunk, ToolCallState, ToolDescriptor, ToolResult, ToolResultChunk, ToolResultState, UrlContentSource, Usage, UsageChunk, UsageCostBreakdown, VideoContentPart, plus the AiContractDefinitionShape structural type.

The /v1/ai route surface

Route paths are relative; the /v1/ai prefix is applied where the service host mounts the router. The contract layers five plugin-specific routes onto the base seam describe route.

chat input

ChatInput carries the request the connector forwards to its provider adapter.

SSE chat contract (durable-CHAT)

chat is the streaming centerpiece. Its output is not a request/response pair but an oRPC eventIterator whose element type is ChatChunk — an alias of the engine AgentChunk union. Because the contract output type is an async event-iterator, a connector's chat handler must be an async generator that yields frames; a buffered single-response implementation does not type-check. Recoverable and terminal errors surface in-stream as the error chunk rather than as an oRPC error, matching the engine's streaming model — so the chat route (built with oc.route, not the base contract) carries an empty error map.

Event (chunk) shapes

Each streamed frame is one of seven discriminated shapes, keyed on type:

The contract declares frame shapes, not wire headers. @netscript/plugin-ai-core is a transport-agnostic oRPC contract: the text/event-stream wire framing (per-frame data: lines, the response content type) is produced by the oRPC handler at the host mount point when it serves an eventIterator output, not declared in this package. This page documents the event shapes the stream carries; the HTTP framing belongs to the connector's service host.

Base-contract extension

aiContract spreads BASE_PLUGIN_CONTRACT_ROUTES from @netscript/plugin/contract-base verbatim, so it inherits the mandatory describe route (GET /describe) unchanged. describe returns a marketplace-discoverable AiCapabilities document — a named alias of PluginCapabilities:

The non-streaming routes (models, invokeTool, embed, transcribe, describe) converge onto the shared plugin error vocabulary from BASE_PLUGIN_ERRORS:

Binding the contract (aiContractV1 / AiRouter)

A connector binds its host request context and implements each route handler. The precise per-route IO types check every handler; there is no erasure cast on the contract or the implementer.

aiContractV1.$context<TContext>() returns the contract-bound implementer — AiRouter is the type alias naming its default (empty-context) shape, and ContextualAiRouter<TContext> the context-parameterized one. The implementer is not an assembled handler map: each route on it exposes a .handler() call that binds one implementation function.

import { aiContractV1 } from '@netscript/plugin-ai-core';

// Bind the host request context; each route is then implemented individually.
const router = aiContractV1.$context<{ requestId: string }>();

// The `chat` output is an event-iterator, so the handler MUST stream frames.
const chat = router.chat.handler(async function* ({ input }) {
  for (const message of input.messages) {
    yield { type: 'text' as const, delta: `echo: ${JSON.stringify(message.content)}` };
  }
  yield { type: 'done' as const };
});
// models / invokeTool / embed / transcribe / describe bind the same way.

Assembling all six bound routes by hand is what createAiRouter exists to avoid: it wraps aiContractV1.$context(), binds a complete per-route implementation (AiRouterImplementation) in one call, and returns the bound handler map (BoundAiRouter):

import { createAiRouter } from '@netscript/plugin-ai-core';

const router = createAiRouter({
  describe: () => ({
    pluginName: '@netscript/plugin-ai',
    contractVersions: ['v1'],
    routeGroups: ['ai'],
    capabilities: ['chat'],
  }),
  async *chat() {
    yield { type: 'done' as const };
  },
  models: () => ({ models: [] }),
  invokeTool: () => ({ content: 'No tools registered.', state: 'error' as const }),
  embed: () => ({ embeddings: [] }),
  transcribe: () => ({ text: '' }),
});

Validating IO on the ./contracts/v1 subpath

The Zod validators let a connector parse an inbound request body against the contract and validate each frame before forwarding it down the stream:

import { ChatChunkSchema, ChatInputSchema } from '@netscript/plugin-ai-core/contracts/v1';

// Parse an inbound request body against the streamed-chat input contract.
const request = ChatInputSchema.parse({
  model: 'anthropic:claude-sonnet-4-5',
  messages: [{ role: 'user', content: 'Stream me a haiku.' }],
});

// Validate each frame a provider emits before forwarding it down the SSE stream.
const chunk = ChatChunkSchema.parse({ type: 'text', delta: 'silent...' });
console.log(request.model, chunk.type);

How the AI plugin stack consumes this contract

• Connector (@netscript/plugin-ai) — re-exports this contract surface from its own ./contracts/v1 (export * from '@netscript/plugin-ai-core/contracts/v1') and declares the loader on its manifest (withContractVersions), so a host binds the AI plugin against a single pinned /v1/ai contract. It binds aiContractV1.$context<Ctx>() and implements each route against a provider adapter.
• @netscript/fresh/ai client — imports aiContract and generates a typed caller, so a Fresh island streams chat chunks and calls models / embed / transcribe with full type inference and no hand-written request types.
• Marketplace tooling — reads the describe route's AiCapabilities document to introspect a running AI plugin without parsing source.

Back to the reference overview.