torus-ai 0.1.0

package/AGENT.md

@@ -0,0 +1,47 @@
+# AGENT.md — Torus (Layer 0: identity + map)
+
+You are operating inside **Torus**, a minimal Agent SDK whose architecture
+*is* the ICM folder structure. It is inspired by the Claude Agent SDK (agent loop,
+tools, in-process MCP, subagents, permissions) but follows the Interpretable Context
+Methodology: **folder structure as agent architecture, markdown contracts as code.**
+
+## Where am I?
+
+```
+torus-ai/
+├── AGENT.md            # Layer 0 — this file: identity + map
+├── CONTEXT.md          # Layer 1 — routing: which module/stage handles what
+├── src/                # the runtime (the engine that reads the folders)
+│   ├── types.ts        # plain-data wire types (the cross-layer interface)
+│   ├── loop.ts         # ★ the core agentic loop
+│   ├── tools.ts        # tool() + createSdkMcpServer() + ToolRegistry (namespacing)
+│   ├── builtins.ts     # read_file / write_file / list_dir
+│   ├── permissions.ts  # allowlist + canUseTool gate (deny → allow → callback)
+│   ├── subagents.ts    # parse markdown stage contracts (Layer 2)
+│   ├── context.ts      # layered context loader (Layers 0–4, scoped)
+│   ├── pipeline.ts     # sequential stage runner with review gates
+│   ├── index.ts        # public API: query(), runPipeline(), tool(), ...
+│   └── providers/      # MockProvider (offline) + AnthropicProvider (real)
+└── examples/
+    └── blog-pipeline/  # an actual ICM workspace this SDK runs (the "product")
+```
+
+## ICM ↔ Agent-SDK concept map
+
+| ICM layer / idea            | This SDK                                            |
+|-----------------------------|-----------------------------------------------------|
+| Layer 0 `AGENT.md`          | workspace identity, loaded into every stage system  |
+| Layer 1 `CONTEXT.md`        | routing doc, loaded into every stage system         |
+| Layer 2 `stages/NN/CONTEXT.md` | a **subagent**: Inputs / Process / Outputs / Tools |
+| Layer 3 references          | constraints (voice, conventions) — `_config/`, `references/` |
+| Layer 4 `output/`           | the handoff: stage NN's output is NN+1's input      |
+| Review gate                 | `reviewGate` callback between stages                |
+| "One stage, one job"        | one contract → one `runLoop` pass → one artifact    |
+| Scoped Inputs               | `loadStageContext` loads only the named files       |
+
+## Operating rules
+
+- Each stage loads **only** the files its contract names (ICM principle 3).
+- A stage's `## Tools` list is the source of truth for what tools it may call.
+- The runtime persists each stage's deliverable to `output/`; mechanical work
+  stays out of the model's job (ICM principle: "configure the factory, not the product").

package/CONTEXT.md

@@ -0,0 +1,26 @@
+# CONTEXT.md — routing (Layer 1)
+
+Which part of the system handles what. Start here, then jump to the named file.
+
+## "I want to understand the engine"
+- The loop itself → `src/loop.ts` (gather → call model → run tools → repeat)
+- How tools are defined and namespaced → `src/tools.ts`
+- How permissions gate a tool call → `src/permissions.ts`
+- How a model backend plugs in → `src/types.ts` (`ModelProvider`) + `src/providers/`
+
+## "I want to understand the ICM wiring"
+- How a markdown stage contract is parsed → `src/subagents.ts`
+- How layered context is assembled per stage → `src/context.ts`
+- How stages run in order with review gates → `src/pipeline.ts`
+
+## "I want to use the SDK"
+- Single agent run → `query()` in `src/index.ts`
+- Custom tool / in-process MCP → `tool()` + `createSdkMcpServer()` in `src/tools.ts`
+- Run a folder pipeline → `runPipeline()` in `src/pipeline.ts`
+- Working example → `examples/blog-pipeline/` (run with `npm run demo`)
+
+## "I want to add a stage"
+1. Create `examples/<ws>/stages/NN_verb/CONTEXT.md` using the contract shape
+   (`## Inputs` / `## Process` / `## Outputs`, optional `## Tools`).
+2. Name exact input files and tag each Layer 3 (reference) or Layer 4 (working).
+3. Re-run the pipeline; the runner discovers numbered stage folders automatically.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aenfr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# Torus
+
+> npm: `torus-ai` · repo: [aenfr/torus-ai](https://github.com/aenfr/torus-ai)
+
+[![CI](https://github.com/aenfr/torus-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/aenfr/torus-ai/actions/workflows/ci.yml)
+
+A minimal **Agent SDK** whose architecture *is* the [ICM](./AGENT.md) folder
+structure. Inspired by the Claude Agent SDK — same core ideas (agent loop, tools,
+in-process MCP, subagents, permissions, streaming) — but agents and pipelines are
+defined as **markdown contracts in folders**, not framework code.
+
+> Built on the Interpretable Context Methodology (ICM): *folder structure as agent
+> architecture, plain text as the interface, layered context loading.*
+
+## Quick start
+
+Requires **Node ≥ 22.6** (runs TypeScript natively — no build step).
+
+```bash
+node examples/blog-pipeline/run.ts     # or: npm run demo
+```
+
+This runs a 3-stage pipeline (`research → draft → polish`) with the offline
+`MockProvider` — no API key needed. Each stage writes an artifact to its `output/`
+folder; open them to inspect the handoff.
+
+## What's inside
+
+| Concept (Claude Agent SDK) | Here |
+|---|---|
+| The agentic loop | [`src/loop.ts`](./src/loop.ts) — gather → call model → run tools → repeat |
+| `tool()` / `createSdkMcpServer()` | [`src/tools.ts`](./src/tools.ts) — in-process MCP, `mcp__<server>__<tool>` namespacing |
+| Built-in tools | [`src/builtins.ts`](./src/builtins.ts) — `read_file` / `write_file` / `list_dir` |
+| Permissions / `canUseTool` | [`src/permissions.ts`](./src/permissions.ts) — allowlist + wildcard + callback gate |
+| Subagents | [`src/subagents.ts`](./src/subagents.ts) — markdown stage contracts (Layer 2) |
+| Context management | [`src/context.ts`](./src/context.ts) — layered, scoped loading (Layers 0–4) |
+| `query()` streaming | [`src/index.ts`](./src/index.ts) — single-shot run yielding events |
+| Pipeline orchestration | [`src/pipeline.ts`](./src/pipeline.ts) — sequential stages + review gates |
+| Model backends | [`src/providers/`](./src/providers/) — `MockProvider`, `AnthropicProvider` |
+
+## Three ways to use it
+
+**1. Single agent run** (`query`) — mirrors the Claude Agent SDK streaming shape:
+
+```ts
+import { query, MockProvider, tool, createSdkMcpServer } from "./src/index.ts";
+
+const time = tool("now", "Current ISO time", { type: "object", properties: {} },
+  () => ({ content: new Date().toISOString() }));
+const clock = createSdkMcpServer({ name: "clock", tools: [time] });
+
+for await (const ev of query("What time is it?", {
+  provider: new MockProvider(),
+  mcpServers: [clock],
+  permissions: { allowedTools: ["mcp__clock__*"] },
+})) {
+  if (ev.type === "result") console.log(ev.finalText);
+}
+```
+
+**2. Folder pipeline** (`runPipeline`) — the ICM workflow. Drop numbered stage
+folders with `CONTEXT.md` contracts under `stages/`, then run. See
+[`examples/blog-pipeline`](./examples/blog-pipeline).
+
+**3. Real model** — swap the provider and install the optional dep:
+
+```bash
+npm i @anthropic-ai/sdk        # Claude
+export ANTHROPIC_API_KEY=sk-ant-...
+# or
+npm i @google/genai            # Gemini
+export GOOGLE_API_KEY=...
+```
+```ts
+import { AnthropicProvider, GeminiProvider } from "torus-ai";
+const claude = new AnthropicProvider({ model: "claude-sonnet-4-6" });
+const gemini = new GeminiProvider({ model: "gemini-2.5-flash" });
+```
+
+## Providers & cost routing
+
+Two pluggable providers implement the same `ModelProvider` interface, so they
+drop into `query()`, `runPipeline()`, or `runLoop()` interchangeably:
+
+| Provider | Package | Env | Default |
+|---|---|---|---|
+| `AnthropicProvider` | `@anthropic-ai/sdk` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |
+| `GeminiProvider` | `@google/genai` | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
+
+Both support **intelligent cost routing** — set `route: true` and each request is
+classified (fast keyword/length heuristics first, then a structured-output "judge"
+call on the *cheap* model) and sent to the cheap or expensive model accordingly.
+The classifier never throws: on any failure it falls back to the expensive model.
+
+```ts
+const provider = new GeminiProvider({ route: true });
+//        cheap: gemini-2.5-flash-lite   expensive: gemini-2.5-pro
+// (AnthropicProvider({ route: true }) → claude-haiku-4-5 vs claude-sonnet-4-6)
+
+import { getRoutingStats } from "torus-ai";
+console.log(getRoutingStats()); // { cheap, expensive, cheapPct, expensivePct, total }
+```
+
+Model constants (`CHEAP_MODEL`, `EXPENSIVE_MODEL`, `GEMINI_CHEAP_MODEL`,
+`GEMINI_EXPENSIVE_MODEL`) and the low-level `selectModel` / `selectGeminiModel`
+are exported if you want to route outside the providers.
+
+## The stage contract (Layer 2)
+
+Each `stages/NN_verb/CONTEXT.md` is both the agent's instructions and human docs:
+
+```markdown
+# Stage 02 — draft
+
+## Inputs
+- Layer 4 (working):   ../01_research/output/research-output.md
+- Layer 3 (reference): ../../_config/voice.md
+
+## Process
+Turn the research brief into a ~300-word first draft in the house voice.
+
+## Outputs
+- draft.md -> output/
+
+## Tools          # optional — the stage's tool allowlist (source of truth)
+- mcp__research__lookup
+```
+
+The runner reads `## Inputs` to scope context (loads *only* those files), `## Tools`
+to gate what the loop may call, and `## Outputs` to name the artifact it persists.
+
+## Design notes
+
+- **The contract is the control point.** A stage loads only the files it names
+  (ICM principle 3) and may call only the tools it lists.
+- **`output/` is the handoff.** Stage `NN`'s output is stage `NN+1`'s input — the
+  coordination "logic" is one folder feeding the next.
+- **Observable by default.** No logging layer — open the folders. Re-run one stage
+  by itself; its `## Inputs` table *is* its dependency declaration.
+- **Provider-agnostic.** The loop only needs `ModelProvider.generate()`. Mock for
+  tests/offline, Anthropic for real, anything else you implement.
+
+MIT-licensed, like the ICM protocol it's built on.

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+type Role = "user" | "assistant";
+interface TextBlock {
+    type: "text";
+    text: string;
+}
+interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultBlock {
+    type: "tool_result";
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+}
+type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
+interface Message {
+    role: Role;
+    content: ContentBlock[];
+}
+type StopReason = "end_turn" | "tool_use" | "max_turns";
+interface ModelResponse {
+    content: ContentBlock[];
+    stopReason: StopReason;
+}
+type JSONSchema = Record<string, unknown>;
+interface ToolSchema {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+interface ModelRequest {
+    system: string;
+    messages: Message[];
+    tools: ToolSchema[];
+}
+/** The one capability the SDK needs from any model backend. Swap freely. */
+interface ModelProvider {
+    readonly name: string;
+    generate(req: ModelRequest): Promise<ModelResponse>;
+}
+interface ToolResultPayload {
+    content: string;
+    isError?: boolean;
+}
+interface ToolContext {
+    workspaceDir: string;
+    stageDir?: string;
+    signal?: AbortSignal;
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+    handler: (input: any, ctx: ToolContext) => Promise<ToolResultPayload> | ToolResultPayload;
+}
+/** An in-process MCP server: tools that run in this same process, no subprocess. */
+interface SdkMcpServer {
+    kind: "sdk-mcp";
+    name: string;
+    version: string;
+    tools: ToolDefinition[];
+}
+type PermissionDecision = {
+    behavior: "allow";
+    updatedInput?: Record<string, unknown>;
+} | {
+    behavior: "deny";
+    message: string;
+};
+type CanUseTool = (toolName: string, input: Record<string, unknown>) => Promise<PermissionDecision> | PermissionDecision;
+type AgentEvent = {
+    type: "assistant_text";
+    text: string;
+    stage?: string;
+} | {
+    type: "tool_use";
+    name: string;
+    input: Record<string, unknown>;
+    stage?: string;
+} | {
+    type: "tool_result";
+    name: string;
+    content: string;
+    isError: boolean;
+    stage?: string;
+} | {
+    type: "permission_denied";
+    name: string;
+    message: string;
+    stage?: string;
+} | {
+    type: "stage_start";
+    stage: string;
+} | {
+    type: "stage_output";
+    stage: string;
+    artifact: string;
+    path: string;
+} | {
+    type: "context_loaded";
+    stage?: string;
+    tokensEstimated: number;
+    files: string[];
+} | {
+    type: "result";
+    finalText: string;
+    turns: number;
+    stage?: string;
+};
+
+/**
+ * Define a custom tool. Mirrors `tool()` from the Claude Agent SDK.
+ *   tool("get_temp", "Get temperature", { type:"object", ... }, async (input, ctx) => ...)
+ */
+declare function tool(name: string, description: string, inputSchema: JSONSchema, handler: (input: any, ctx: ToolContext) => Promise<ToolResultPayload> | ToolResultPayload): ToolDefinition;
+/**
+ * Bundle tools into an in-process MCP server. Mirrors `createSdkMcpServer()`.
+ * Tools become namespaced `mcp__<name>__<tool>` when registered.
+ */
+declare function createSdkMcpServer(opts: {
+    name: string;
+    version?: string;
+    tools: ToolDefinition[];
+}): SdkMcpServer;
+interface RegisteredTool {
+    fullName: string;
+    def: ToolDefinition;
+}
+/** Holds the model-facing tool catalog and executes calls by namespaced name. */
+declare class ToolRegistry {
+    private map;
+    /** Built-ins register under their bare name (no namespace). */
+    addBuiltins(defs: ToolDefinition[]): this;
+    /** SDK MCP server tools register as mcp__<server>__<tool>. */
+    addServer(server: SdkMcpServer): this;
+    has(fullName: string): boolean;
+    list(): RegisteredTool[];
+    /** Tool schemas to hand the model, optionally filtered to a stage's allowlist. */
+    schemas(filter?: (fullName: string) => boolean): ToolSchema[];
+    execute(fullName: string, input: Record<string, unknown>, ctx: ToolContext): Promise<ToolResultPayload>;
+}
+
+/** Match a tool name against patterns supporting a trailing "*" wildcard. */
+declare function matchesAllow(name: string, patterns: string[]): boolean;
+interface PermissionConfig {
+    /** Allowlist (wildcards ok). If omitted, all tools allowed unless canUseTool vetoes. */
+    allowedTools?: string[];
+    /** Explicit denials, evaluated first. */
+    disallowedTools?: string[];
+    /** Final custom gate — can allow non-allowlisted tools, veto allowlisted ones, or rewrite input. */
+    canUseTool?: CanUseTool;
+}
+/**
+ * Evaluation order (mirrors the Agent SDK):
+ *   1. disallowedTools  → deny
+ *   2. allowedTools     → allow (if no canUseTool)
+ *   3. canUseTool       → final say
+ *   4. default          → allow when no allowlist, deny when allowlist set and unmatched
+ */
+declare class PermissionEngine {
+    private cfg;
+    constructor(cfg?: PermissionConfig);
+    check(name: string, input: Record<string, unknown>): Promise<PermissionDecision>;
+}
+
+interface LoopOptions {
+    provider: ModelProvider;
+    registry: ToolRegistry;
+    permissions: PermissionEngine;
+    system: string;
+    messages: Message[];
+    toolContext: ToolContext;
+    toolFilter?: (fullName: string) => boolean;
+    maxTurns?: number;
+    stage?: string;
+}
+interface LoopResult {
+    finalText: string;
+    turns: number;
+    messages: Message[];
+}
+declare function runLoop(opts: LoopOptions): AsyncGenerator<AgentEvent, LoopResult>;
+
+interface StageInput {
+    layer: 3 | 4;
+    path: string;
+    note?: string;
+}
+interface StageContract {
+    name: string;
+    order: number;
+    stageDir: string;
+    contractPath: string;
+    inputs: StageInput[];
+    process: string;
+    outputs: string[];
+    tools: string[];
+}
+declare function parseContract(name: string, stageDir: string, contractPath: string, body: string): StageContract;
+/** Discover and parse every numbered stage folder, in execution order. */
+declare function loadStages(workspaceDir: string): Promise<StageContract[]>;
+
+interface PipelineOptions {
+    workspaceDir: string;
+    provider: ModelProvider;
+    mcpServers?: SdkMcpServer[];
+    /** Global permission overlay. A stage's own "## Tools" list is the primary allowlist. */
+    permissions?: Pick<PermissionConfig, "canUseTool" | "disallowedTools">;
+    /** Called after each stage writes output. Return false to halt the pipeline. */
+    reviewGate?: (stage: StageContract, outputs: {
+        artifact: string;
+        path: string;
+        text: string;
+    }[]) => Promise<boolean> | boolean;
+    maxTurnsPerStage?: number;
+    contextBudgetTokens?: number;
+}
+declare function runPipeline(opts: PipelineOptions): AsyncGenerator<AgentEvent, void>;
+
+declare const readFileTool: ToolDefinition;
+declare const writeFileTool: ToolDefinition;
+declare const listDirTool: ToolDefinition;
+declare const builtinTools: ToolDefinition[];
+
+interface LoadedContext {
+    system: string;
+    files: string[];
+    tokensEstimated: number;
+}
+/**
+ * Build a stage's system prompt from the ICM layer hierarchy:
+ *   Layer 0  AGENT.md           (identity + map)
+ *   Layer 1  CONTEXT.md         (routing)
+ *   Layer 2  stage CONTEXT.md   (this stage's contract)
+ *   Layer 3  scoped references  (constraints — only files the contract names)
+ *   Layer 4  scoped working     (prior stage output — only files the contract names)
+ */
+declare function loadStageContext(workspaceDir: string, contract: StageContract): Promise<LoadedContext>;
+
+interface MockOptions {
+    /** Label stamped into outputs so mock-generated content is unmistakable. */
+    label?: string;
+}
+/**
+ * A deterministic, offline provider that exercises the full agent loop with no API
+ * key. Strategy: if tools are offered and none have been used yet, call the first
+ * tool once; otherwise synthesize a final answer from the system context + any tool
+ * results. It is intentionally dumb — its job is to prove the harness wiring, not to
+ * write good prose. Swap in AnthropicProvider for real output.
+ */
+declare class MockProvider implements ModelProvider {
+    readonly name = "mock";
+    private opts;
+    constructor(opts?: MockOptions);
+    generate(req: ModelRequest): Promise<ModelResponse>;
+    private sampleInput;
+    private synthesize;
+}
+
+interface AnthropicOptions {
+    model?: string;
+    apiKey?: string;
+    maxTokens?: number;
+    /**
+     * When true, the model is chosen per-request by the cost router (cheap vs
+     * expensive) based on query complexity, instead of using a fixed `model`.
+     */
+    route?: boolean;
+}
+/**
+ * Real provider backed by the Anthropic Messages API. Requires the optional
+ * `@anthropic-ai/sdk` dependency and an ANTHROPIC_API_KEY. The SDK is imported
+ * lazily so the package (and the mock demo) work without it installed.
+ */
+declare class AnthropicProvider implements ModelProvider {
+    readonly name = "anthropic";
+    private client;
+    private model;
+    private maxTokens;
+    private apiKey?;
+    private route;
+    constructor(opts?: AnthropicOptions);
+    private ensureClient;
+    generate(req: ModelRequest): Promise<ModelResponse>;
+}
+
+interface GeminiOptions {
+    model?: string;
+    apiKey?: string;
+    /**
+     * When true, the model is chosen per-request by the cost router (cheap vs
+     * expensive Gemini) based on query complexity, instead of a fixed `model`.
+     */
+    route?: boolean;
+}
+/**
+ * Provider backed by the Google Gemini API (@google/genai). Requires the
+ * optional `@google/genai` dependency and a GOOGLE_API_KEY (or GEMINI_API_KEY).
+ * The SDK is imported lazily so the package works without it installed.
+ */
+declare class GeminiProvider implements ModelProvider {
+    readonly name = "gemini";
+    private client;
+    private model;
+    private apiKey?;
+    private route;
+    constructor(opts?: GeminiOptions);
+    private ensureClient;
+    generate(req: ModelRequest): Promise<ModelResponse>;
+}
+
+declare const CHEAP_MODEL = "claude-haiku-4-5";
+declare const EXPENSIVE_MODEL = "claude-sonnet-4-6";
+declare const GEMINI_CHEAP_MODEL = "gemini-2.5-flash-lite";
+declare const GEMINI_EXPENSIVE_MODEL = "gemini-2.5-pro";
+type Complexity = "SIMPLE" | "COMPLEX";
+interface RouterOptions {
+    /** Reuse an existing provider SDK client (avoids a second client init). */
+    client?: any;
+    /** API key for a lazily-created client (defaults to the provider's env var). */
+    apiKey?: string;
+    /** Model used as the complexity judge. Defaults to the provider's cheap model. */
+    judgeModel?: string;
+}
+/**
+ * Cheap, deterministic pre-classification. Returns a verdict only when it's
+ * confident; otherwise null (defer to the judge).
+ */
+declare function fastHeuristic(prompt: string): Complexity | null;
+/** Grade complexity with Claude (structured output). May throw. */
+declare function judgeComplexity(prompt: string, opts?: RouterOptions): Promise<Complexity>;
+/** Grade complexity with Gemini (JSON structured output). May throw. */
+declare function judgeComplexityGemini(prompt: string, opts?: RouterOptions): Promise<Complexity>;
+/** Heuristics first, Claude judge second. May throw. */
+declare function classifyComplexity(prompt: string, opts?: RouterOptions): Promise<Complexity>;
+/** Heuristics first, Gemini judge second. May throw. */
+declare function classifyComplexityGemini(prompt: string, opts?: RouterOptions): Promise<Complexity>;
+/** Pick a Claude model for a prompt. Never throws (falls back to expensive). */
+declare function selectModel(prompt: string, opts?: RouterOptions): Promise<string>;
+/** Pick a Gemini model for a prompt. Never throws (falls back to expensive). */
+declare function selectGeminiModel(prompt: string, opts?: RouterOptions): Promise<string>;
+interface RoutingStats {
+    cheap: number;
+    expensive: number;
+    total: number;
+    cheapPct: number;
+    expensivePct: number;
+}
+declare function getRoutingStats(): RoutingStats;
+/** Extract the most recent user turn's text — what the router classifies on. */
+declare function latestUserText(messages: Message[]): string;
+
+interface QueryOptions {
+    provider: ModelProvider;
+    system?: string;
+    mcpServers?: SdkMcpServer[];
+    includeBuiltins?: boolean;
+    permissions?: PermissionConfig;
+    workspaceDir?: string;
+    maxTurns?: number;
+}
+/**
+ * Single-shot agent run (no pipeline). Mirrors the Claude Agent SDK's streaming
+ * `query()`: yields events as they happen and a final `result` event.
+ *
+ *   for await (const ev of query("Summarize X", { provider, mcpServers: [srv] })) { ... }
+ */
+declare function query(prompt: string, options: QueryOptions): AsyncGenerator<AgentEvent>;
+
+export { type AgentEvent, type AnthropicOptions, AnthropicProvider, CHEAP_MODEL, type CanUseTool, type Complexity, type ContentBlock, EXPENSIVE_MODEL, GEMINI_CHEAP_MODEL, GEMINI_EXPENSIVE_MODEL, type GeminiOptions, GeminiProvider, type JSONSchema, type LoadedContext, type LoopOptions, type LoopResult, type Message, type MockOptions, MockProvider, type ModelProvider, type ModelRequest, type ModelResponse, type PermissionConfig, type PermissionDecision, PermissionEngine, type PipelineOptions, type QueryOptions, type RegisteredTool, type Role, type RouterOptions, type RoutingStats, type SdkMcpServer, type StageContract, type StageInput, type StopReason, type TextBlock, type ToolContext, type ToolDefinition, ToolRegistry, type ToolResultBlock, type ToolResultPayload, type ToolSchema, type ToolUseBlock, builtinTools, classifyComplexity, classifyComplexityGemini, createSdkMcpServer, fastHeuristic, getRoutingStats, judgeComplexity, judgeComplexityGemini, latestUserText, listDirTool, loadStageContext, loadStages, matchesAllow, parseContract, query, readFileTool, runLoop, runPipeline, selectGeminiModel, selectModel, tool, writeFileTool };