@netscript/ai

The provider-agnostic AI engine core for NetScript: a composition root, a global model registry, the domain vocabulary and capability ports for chat/embeddings/vision/tools/agents/MCP, and a set of opt-in provider adapters. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The base @netscript/ai entrypoint takes no @netscript/* runtime dependency and pulls no provider SDK into the module graph. Provider adapters (Anthropic, OpenAI-compatible, OpenRouter, Ollama, OpenAI embeddings/vision) live on separate subpath exports and self-register into the shared registry as a side effect of being imported — so an application chooses its providers with one-line side-effect imports and only those SDKs enter the graph:

import "@netscript/ai/anthropic"; // self-registers the 'anthropic' provider
import { getModel } from "@netscript/ai";

const handle = await getModel("anthropic:claude-sonnet-4-5");

Export map

The package publishes the following entrypoints. Each is documented against its own deno doc surface.

Composition root and model registry (@netscript/ai)

The root entrypoint is the composition root plus the model-registry accessors. Model providers are resolved through a module-level registry (not stored on the runtime), so provider packages self-register independently of runtime construction.

Runtime capability ports and their defaults

createAiRuntime injects each capability port, defaulting any omitted field to a no-op or a throwing "unconfigured" port. Model providers are not on the runtime — they are resolved from the global registry.

Domain contracts (@netscript/ai/contracts)

The provider-neutral vocabulary. The tables below list the primary surface; the module is the source of truth via deno doc packages/ai/src/contracts/mod.ts.

Capability ports (@netscript/ai/ports)

The capability seams the engine is programmed against, their default implementations, and the model/embedding/vision registries. Primary surface:

Model providers

Each provider lives on its own subpath. Importing the subpath self-registers the provider under its stable id and re-exports the adapter class and config type for direct construction. All chat adapters translate the wrapped SDK to the owned chat vocabulary — no provider-SDK type escapes the public surface — and support per-turn cancellation through the chat client's stream(_, { signal }) option.

@netscript/ai/anthropic

Registry id "anthropic". Wraps @tanstack/ai-anthropic; the model catalog is taken verbatim from the wrapped package's ANTHROPIC_MODELS.

@netscript/ai/openai-compatible

Registry id "openai-compatible". Wraps @tanstack/ai-openai/compatible for any endpoint that speaks the OpenAI wire (its own base URL, key, and model list).

When baseURL or apiKey is missing, createChatClient throws AiNotConfiguredError (the provider still lists and reports its configured models).

@netscript/ai/openrouter

Registry id "openrouter". Reuses the OpenAI-compatible transport pinned to OpenRouter, with the one wire divergence being reasoning: OpenRouter expects a top-level reasoning: { effort } object.

@netscript/ai/ollama

Registry id "ollama". Reuses the OpenAI-compatible transport pinned to a local Ollama daemon at {host}/v1, with a reachability preflight and a placeholder key (Ollama ignores authorization).

@netscript/ai/openai-embeddings

Registry id "openai-embeddings", registered for both the embedding and vision capabilities. Speaks the OpenAI-compatible HTTP API directly with Web fetch (no provider SDK).

Tools (@netscript/ai/tools)

Define server-executable (or client-deferred) tools, validate their input with Standard Schema (bring any conforming schema — zod, valibot, arktype, or hand-written), and dispatch them through an in-memory registry that satisfies ToolRegistryPort. The core adds no schema DSL and takes no @netscript/* dependency.

Agent loop (@netscript/ai/agent)

The E3 agent loop drives a bounded, cancellable model/tool interaction and emits AgentChunks. It consumes its collaborators purely by factory injection — importing this subpath pulls no provider SDK.

The subpath also re-exports the seams the loop is programmed against (AgentLoopPort, ChatClientPort / ChatModelProviderPort and their event types, ToolRegistryPort) so it is a self-contained wiring surface.

MCP (@netscript/ai/mcp)

MCP transport adapters and tool registration: stdio, reconnectable Streamable-HTTP, injected auth modes, and lifecycle state.

Testing (@netscript/ai/testing)

Deterministic fakes for unit-testing code built on the ports. This subpath is excluded from the provider dependency graph.

Configuration

@netscript/ai reads no @netscript/* config surface — capabilities are wired through AiRuntimeConfig (see runtime capability ports) and providers through their config bags. Two adapters resolve an API key from the environment when apiKey is omitted:

The openai-compatible, openai-embeddings, and ollama providers do not read the environment. Pass apiKey (and baseURL/host) explicitly — commonly from Deno.env.get(...) in your composition code. Reading a key from the environment requires --allow-env for the variable in question.

Provider keys have no typed config surface — by design. Unlike service topology (typed through @netscript/config), AI provider credentials are not modelled in netscript.config.ts. Reading the key with raw Deno.env.get(...) (or letting the Anthropic / OpenRouter adapters resolve their env var) is the supported path — secrets stay out of the committed config and are injected by the runtime environment instead.

Examples

Compose a runtime

import { createAiRuntime } from "@netscript/ai";

const ai = createAiRuntime();
// Telemetry defaults to a no-op port — safe to call with nothing wired.
ai.telemetry.recordEvent("agent.start");

Register a provider and resolve a model

import "@netscript/ai/anthropic"; // self-registers the 'anthropic' provider
import { getModel } from "@netscript/ai";

const handle = await getModel("anthropic:claude-sonnet-4-5");

Configure an OpenAI-compatible endpoint

import "@netscript/ai/openai-compatible"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("openai-compatible", {
  baseURL: "https://api.deepseek.com/v1",
  apiKey: Deno.env.get("DEEPSEEK_KEY"),
  models: ["deepseek-chat", "deepseek-reasoner"],
});

Stream a reasoning turn through OpenRouter

import "@netscript/ai/openrouter"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("openrouter", {
  apiKey: Deno.env.get("OPENROUTER_API_KEY"),
  models: ["anthropic/claude-sonnet-4.5"],
  reasoningEffort: "high",
});

Preflight a local Ollama daemon

import { getModelProvider } from "@netscript/ai";
import { OllamaModelProvider } from "@netscript/ai/ollama"; // self-registers the provider

const provider = getModelProvider("ollama", { models: ["llama3.2"] }) as OllamaModelProvider;
const health = await provider.checkReachable();
if (!health.reachable) {
  console.warn(`Ollama is down: ${health.detail}`);
}

Define, register, and dispatch a tool

import { createToolRegistry, defineAiTool } from "@netscript/ai/tools";

const add = defineAiTool("add")
  .parameters({
    type: "object",
    properties: { a: { type: "number" }, b: { type: "number" } },
    required: ["a", "b"],
  })
  .input(myAddSchema) // any StandardSchemaV1<unknown, { a: number; b: number }>
  .server(({ a, b }) => ({ sum: a + b }));

const registry = createToolRegistry([add]);
const { output } = await registry.dispatch("add", { a: 2, b: 3 });

Drive a bounded, cancellable agent loop

import { createAgentLoop, slidingWindowHistory } from "@netscript/ai/agent";

const loop = createAgentLoop({
  modelProvider, // a ChatModelProviderPort
  tools, // a ToolRegistryPort
  history: slidingWindowHistory({ maxMessages: 12 }),
});

for await (const chunk of loop.run({ model: "anthropic:claude-sonnet-4-5", messages })) {
  if (chunk.type === "text") console.log(chunk.delta);
  if (chunk.type === "done") console.log(chunk.usage);
}

Register MCP tools over Streamable-HTTP

import { createMcpTransport, registerMcpTools } from "@netscript/ai/mcp";
import { createToolRegistry } from "@netscript/ai/tools";

const transport = createMcpTransport({
  kind: "streamable-http",
  serverId: "search",
  url: "https://mcp.example.com",
  auth: { mode: "api-token", token: "injected-at-runtime", scheme: "Bearer" },
});

const registry = createToolRegistry();
await registerMcpTools(registry, transport);

Opt-in Rate-Limit Retries

Wrap any concrete ChatClientPort or EmbeddingProviderPort with withRetryingChatClient / withRetryingEmbeddingProvider to add automatic exponential backoff with full jitter for rate limits.

Failure & Replay Contract:

• Only rate limit failures (HTTP 429 status code, AiRateLimitError, or errors classified by isRateLimitError) trigger a retry.
• Bounded delays respect Retry-After headers (in seconds or HTTP date formats) or fallback to exponential delay, capped by maxDelayMs.
• Chat Stream Safety: Chat streams are never replayed/retried after the first chunk has been successfully yielded to the caller. This ensures that half-written responses are not duplicated or restarted mid-stream.

import { getModelProvider, AiRateLimitError } from "@netscript/ai";
import { withRetryingChatClient, type AiRetryPolicy } from "@netscript/ai";

const baseProvider = getModelProvider("openrouter");
const baseClient = baseProvider.createChatClient("anthropic/claude-3-5-sonnet");

const retryPolicy: AiRetryPolicy = {
  maxAttempts: 3,
  initialDelayMs: 200,
  maxDelayMs: 3000,
  factor: 2,
};

const retryingClient = withRetryingChatClient(baseClient, retryPolicy);

try {
  const stream = retryingClient.stream({
    model: "anthropic/claude-3-5-sonnet",
    messages: [{ role: "user", content: "Hello!" }],
  }, {
    signal: new AbortController().signal,
  });
  
  for await (const event of stream) {
    if (event.type === "text") {
      console.log(event.delta);
    }
  }
} catch (error) {
  if (error instanceof AiRateLimitError) {
    console.error(`Rate limits exhausted after ${error.attempts} attempts.`);
  } else {
    throw error;
  }
}

Manage Token Budgets in Agent Loops

The tokenBudgetHistory strategy is a token-aware alternative to a simple sliding message window. It keeps the context window bounded by evaluating message token sizes and trimming the history.

Trimming Logic:

• Preserved System Messages: All leading system messages are always retained, even if their size alone exceeds the budget.
• Contiguous Suffix: The strategy scans backwards from the most recent message, keeping the newest contiguous suffix of messages that fits within the remaining token budget.
• Estimator: The default estimator assumes 1 token per 4 characters. You can supply a custom model-specific token estimator to precisely calculate tokens.

import { createAgentLoop, tokenBudgetHistory } from "@netscript/ai/agent";
import type { Message } from "@netscript/ai";

// 1. Choose budget (e.g., 4000 tokens) and define loop
const loop = createAgentLoop({
  modelProvider,
  tools,
  history: tokenBudgetHistory({
    budget: 4000,
    // Optional: a custom estimator using a model-specific tokenizer
    estimator: (message: Readonly<Message>) => {
      const text = typeof message.content === "string" 
        ? message.content 
        : JSON.stringify(message.content);
      return Math.ceil(text.length / 3.8); // approximate token count
    },
  }),
});

Citation-Ready RAG Retrieval

RetrieverPort provides a provider-neutral interface for retrieval augmented generation (RAG) that emits structured, citation-ready provenance details.

Key Requirements:

• Normalized Score: The relevance score is normalized to the range 0.0 to 1.0 (descending order).
• Matched By: The retrieval match channel must be one of "vector", "keyword", or "hybrid".
• Stable Source: Provenance must specify a stable sourceId to correctly associate the citation.
• Citation Span: Character spans use zero-based offsets with an exclusive end offset (span.end).

import type { RetrieverPort, RetrievalResult } from "@netscript/ai";

// 1. Implement RetrieverPort
class LocalDocumentRetriever implements RetrieverPort {
  async retrieve(query: string, k: number): Promise<readonly RetrievalResult[]> {
    const textSegment = "NetScript is built on Deno and uses V8 sandboxing.";
    const score = 0.89; // Normalized score [0-1]
    
    return [{
      id: "doc-v8-segment-1",
      content: textSegment,
      score,
      matchedBy: "hybrid",
      provenance: {
        sourceId: "netscript-sandbox-docs", // Stable source identity
        title: "NetScript Sandboxing Architecture",
        span: {
          start: 27,
          end: 48, // Exclusive end index (points to "V8 sandboxing.")
          text: "V8 sandboxing",
        },
      },
    }];
  }
}

// 2. Consume RetrieverPort
const retriever = new LocalDocumentRetriever();
const docs = await retriever.retrieve("sandboxing", 1);
for (const doc of docs) {
  console.log(`Matched by: ${doc.matchedBy} with score ${doc.score}`);
  console.log(`Source: ${doc.provenance.title} (ID: ${doc.provenance.sourceId})`);
  console.log(`Passage: "${doc.content}"`);
  console.log(`Exact Match span [${doc.provenance.span.start}-${doc.provenance.span.end}]: "${doc.provenance.span.text}"`);
}

Back to the reference overview.