# Theo — full documentation corpus

> Every page of https://docs.usetheo.dev inlined as plain text (llmstxt.org
> `llms-full.txt` convention). The curated index lives at /llms.txt. Generated
> from the MDX sources — code samples are verbatim; site-only React components
> were stripped. Pages: 982.

---

# Overview

Source: https://docs.usetheo.dev/paas

Build and ship apps and automations from a prompt.

**TheoCloud** is the managed runtime where your agent runs in production. From
your project to a live URL in **minutes** — with the code in your repo, the
stack you chose, and **no lock-in**.

A real app — code in your repo, running on real infrastructure — not a
generated preview.

## Install

```bash
curl -fsSL https://get.usetheo.dev | sh
```

The CLI auto-detects your shell and configures completions for `bash`, `zsh`,
and `fish`.

## Deploy

```bash
theo deploy
```

That is the entire workflow. The CLI builds your project, ships it to a
production environment, and hands you a live URL. The first deploy takes a few
minutes; subsequent deploys are seconds.

## What you get

## Quick start

```bash
# 1. Install the CLI
curl -fsSL https://get.usetheo.dev | sh

# 2. Authenticate
theo login

# 3. Initialize the project (one-time)
theo init

# 4. Deploy
theo deploy
```

That is the whole loop. The first run prints the live URL when the deploy
finishes; subsequent runs print the URL of the new version.

## How it fits the ecosystem

| You have | You run | You get |
|---|---|---|
| A blank repo | `npx create-theokit my-app` (TheoKit) | A working agent project |
| A project | `theo deploy` (TheoCloud) | A live URL |
| A live agent | Switch models, watch every call, keep state | Production at scale |

TheoCloud is the commercial managed runtime. The framework (TheoKit) and the
open-source primitives — including TheoKit-SDK and TheoUI — are Apache-2.0 and
run on any infrastructure. TheoCloud is opt-in: pay to skip operations, or
self-host with a commercial license.

## What `theo deploy` actually does

You give it a project. It gives you back a live URL. Between those two events
it builds your code, ships an immutable image, runs health checks, and routes
traffic with automatic rollback if anything fails — all of it scriptable, all
of it auditable, none of it your problem.

## Where to go next

---

# Overview

Source: https://docs.usetheo.dev/theo-guardrails

Composable inline guardrails for AI agents.

**Theo Guardrails** is the inline, synchronous enforcement layer of Theo's trust
plane — a stateless, dependency-light library that inspects agent input and
output before it flows through and can **allow**, **block**, or **modify** it.
Guardrails compose into a sequential pipeline that short-circuits on the first
`block` and chains rewritten content through `modify` steps. It is **fail-closed**
by design: a guardrail that throws becomes a `block` unless explicitly marked
`failOpen`.

Pre-release (`0.1.0`). The package `@usetheo/trust-guardrails` is Apache-2.0 and
**not yet published to npm**. It ships the pipeline engine plus credential
masking, PII redaction, and shell-pattern blocking; the shared policy taxonomy is
a later milestone.

## Quick start

```ts title="guardrails.ts"
import {
  createGuardrailPipeline,
  createCredentialMaskingGuardrail,
  createPiiGuardrail,
  createShellPatternGuardrail,
  type GuardrailEntry,
} from '@usetheo/trust-guardrails';

const entries: GuardrailEntry[] = [
  { guardrail: createShellPatternGuardrail(), options: { name: 'shell' } },
  { guardrail: createCredentialMaskingGuardrail(), options: { name: 'credentials' } },
  { guardrail: createPiiGuardrail({ strategy: 'redact' }), options: { name: 'pii' } },
];

const pipeline = createGuardrailPipeline(entries);

const result = await pipeline.run({
  direction: 'input', // 'input' | 'output' | 'tool_input' | 'tool_output'
  content: 'my key is sk-ant-XXXXXXXX and email a@b.com',
});

// result: { action: 'allow' | 'block' | 'modify', reason?, modified? }
if (result.action === 'block') reject(result.reason);
else if (result.action === 'modify') use(result.modified);
```

An empty pipeline allows; the first `block` short-circuits; a `modify` feeds its
rewritten content into the next guardrail; the caller's context is never mutated.

## Guardrails included

## Where to go next

---

# Overview

Source: https://docs.usetheo.dev/theo-knowledge

RAG with citations, on your own Postgres.

**Theo Knowledge** is the open-source RAG engine of the Theo ecosystem — drop
documents in, get **cited** answers out. It runs the whole pipeline
(`ingest → parse → chunk → embed → store → retrieve → answer`) on **your**
Postgres (with `pgvector`) and **your** LLM key: no proprietary vector database,
no vendor lock-in, Apache-2.0. Use it as a composable TypeScript library
(`@usetheo/rag`), a typed SDK, or a REST/MCP service — all validated by one Zod
contract.

Pre-release (`rc.60`). The core `ingest → retrieve → answer` flow is
feature-complete, but the package is **not yet on npm** — run it from source for
now. We don't claim it production-ready until backed by sustained usage evidence.

## Install

```bash
git clone https://github.com/usetheodev/theo-rag.git
cd theo-rag
pnpm install
```

Requires Node ≥ 20 and any Postgres with the `pgvector` extension. The core
library publishes as `@usetheo/rag` (with `@usetheo/rag-sdk` for the typed HTTP
client and `@usetheo/rag-mcp` for the MCP server).

## Quick start

Compose a pipeline from swappable stages and ask a question — the answer comes
back with the exact chunks it used:

```ts title="answer.ts"
import { Pool } from 'pg';
import { createUnpdfLoader } from '@usetheo/rag/loaders';
import { createTiktokenTokenizer, createRecursiveCharacterChunker } from '@usetheo/rag/chunkers';
import { createOpenAIEmbedder } from '@usetheo/rag/embedders';
import { createVectorRetriever } from '@usetheo/rag/retrievers';
import { createOpenAILlmProvider } from '@usetheo/rag/llm-providers';
import { createAnswerPipeline } from '@usetheo/rag/pipeline';

const pool = new Pool({ connectionString: process.env.THEORAG_PG_URI });
const embedder = createOpenAIEmbedder({ model: 'text-embedding-3-small' });

const pipeline = createAnswerPipeline({
  pool,
  loader: createUnpdfLoader(),
  chunker: createRecursiveCharacterChunker({
    tokenizer: createTiktokenTokenizer(),
    chunkSize: 512,
    chunkOverlap: 64,
  }),
  embedder,
  retriever: createVectorRetriever({ pool, embedder }),
  llmProvider: createOpenAILlmProvider({ apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o-mini' }),
});

const answer = await pipeline.answer('What is our refund window?');
// answer.citations → [{ document_id, chunk_id }]
```

Prefer HTTP? The `@usetheo/rag-sdk` `RagClient` mirrors the same surface
(`theo.answers.create(...)`, `theo.answers.stream(...)`), and the REST API
exposes `POST /v1/answers` returning `{ answer, citations, retrieved_chunks }`.

## What you get

## Where to go next

---

# Overview

Source: https://docs.usetheo.dev/theo-memory

Persistent memory for AI agents.

**Theo Memory** gives your agents long-term, scoped, searchable memory backed by
Postgres + `pgvector`. It exposes a four-verb API — **remember · recall · forget
· reflect** — across three tiers (`user` / `session` / `agent`), with hybrid
retrieval (semantic + BM25 + entity boost) and bi-temporal queries. It runs on
**your** Postgres and **your** LLM key (Apache-2.0), and is consumable as an SDK,
a REST API, an MCP server, or a CLI.

Published on npm as `@usetheo/memory` (`0.2.0`, pre-release). Feature-complete
for the core use case; the production-ready bar stays gated on sustained usage
evidence.

## Install

```bash
npm install @usetheo/memory
```

Requires Node ≥ 20 and a Postgres with `pgvector`. Ships two binaries —
`themory` (REST server + CLI) and `themory-mcp` (MCP server).

## Quick start

```ts title="memory.ts"
import { createLocalMemory } from '@usetheo/memory';

const memory = await createLocalMemory({ vectorStore, embedder, llm });

// Your agent remembers
await memory.user('alice').remember('Prefers dark mode. Speaks Portuguese.');

// Your agent recalls
const facts = await memory.user('alice').recall('UI preferences');
// → [{ text: 'Prefers dark mode', score: 0.94 }]

// Consolidate episodic → semantic
await memory.user('alice').reflect();
```

Run it as a service instead:

```bash
export THEOMEM_PG_URI=postgresql://themem:themem@localhost:5432/themem
npm run db:push        # apply schema
npx themory server     # REST API on :8080  (POST /v1/remember, /v1/recall, …)
```

## Core concepts

## Where to go next

---

# Overview

Source: https://docs.usetheo.dev/theo-prompts

Versioned prompts, resolved at runtime.

**Theo Prompts** manages your agent's prompts as **versioned, immutable
revisions** and resolves them at runtime — over REST, a TypeScript SDK, or MCP.
A prompt is identified by name and has N revisions; you point **environment
labels** (`prod`, `staging`) at a revision and **promote by moving the label**,
so the next resolution reflects the new prompt with **no redeploy**. All three
interfaces delegate to the same core (Postgres source of truth, optional Redis
cache), and `{{var}}` templating renders client-side so variable values never
leave your process.

Pre-1.0, in active development. The packages (`@usetheo/promptly-sdk`,
`@usetheo/promptly-api`, `@usetheo/promptly-mcp`) are **not yet published to
npm** — they run inside the workspace for now. API-key auth is required.

## Quick start

```ts title="prompts.ts"
import { PromptlyClient } from '@usetheo/promptly-sdk';

const client = new PromptlyClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.THEOPROMPTLY_API_KEY!, // required — blank throws at construction
  cacheTtlSeconds: 60,
});

await client.createPrompt('greet', 'hi {{name}}'); // registers revision v1
await client.assignLabel('greet', 'prod', 1);      // point prod → v1

const p = await client.getPrompt('greet', { label: 'prod', vars: { name: 'Theo' } });
p.content; // 'hi Theo' — rendered SDK-side; the value never reaches the server

// Later: promote to v2 with no app rebuild
await client.assignLabel('greet', 'prod', 2);
```

The REST API exposes the same surface (`POST /prompts`,
`GET /prompts/:name?label=prod`, `PUT /prompts/:name/labels/:label`,
`POST /prompts/:name/rollback`, `GET /openapi.json`), and the MCP server exposes
`get_prompt`, `list_revisions`, and `list_labels` as agent tools.

## Core concepts

## Where to go next

---

# Overview

Source: https://docs.usetheo.dev/theo-traces

OpenTelemetry-native trace explorer for AI agents.

**Theo Traces** is an OpenTelemetry-native trace explorer for AI agents — "Jaeger
for agents." Instrument a TypeScript/Node agent in a few lines and it emits OTLP
`gen_ai` spans to an API that persists them to Postgres and serves a React trace
explorer with session replay, cost, and tool analytics. Spans are the source of
truth; traces and sessions are aggregates recomputed from them.

Pre-1.0 (`0.0.0`). Apache-2.0 and Docker-first. The SDK `@usetheo/lens-sdk` is
**not yet published to npm** — run the stack with Docker and install the SDK from
a local tarball for now. Not claimed production-ready.

## Run the stack

```bash
git clone https://github.com/usetheodev/theo-lens.git
cd theo-lens
docker compose up -d   # Postgres + API + UI on http://localhost:4318
```

## Instrument your agent

```ts title="agent.ts"
import { initTheoLens, startAgent, recordToolCall } from '@usetheo/lens-sdk';

const theo = initTheoLens({ endpoint: 'http://localhost:4318', serviceName: 'checkout-agent' });

await startAgent(theo.tracer, 'checkout', async (span) => {
  span.setModel('gpt-4o').setProvider('openai').setUsage({ inputTokens: 12, outputTokens: 8 });
  recordToolCall(span, 'search-products', { query: 'running shoes' });
});

await theo.shutdown();
```

Instrumentation is **fail-open**: a telemetry-backend problem never crashes the
instrumented app, and `shutdown()` resolves even if the flush fails. Refresh
`http://localhost:4318` to see the trace.

## What you get

## Where to go next

---

# Overview

Source: https://docs.usetheo.dev/theodb

AI + vector search as SQL, inside Postgres.

**TheoDB** is a PostgreSQL 17 distribution that puts AI — embeddings, generation,
ranking, natural-language queries — and vector search into the database as plain
SQL functions. It is **not** a fork or a new engine: it composes upstream
PostgreSQL with a curated set of extensions (a customized `pgvector`,
`pgvectorscale`) plus its own Rust extension, so one `CREATE EXTENSION` exposes an
`ai.*` / `theodb.*` surface. You generate embeddings, run vector + hybrid search,
and call an LLM directly in SQL — against the same transactional rows as your
operational data, with **no ETL to a separate vector store**.

TheoDB is a **commercial** product, pre-1.0 and in active development. It is
available via **early access** — request access at
[usetheo.dev/theodb](https://usetheo.dev/theodb). No production-ready claim is
made yet, and TheoDB makes no speed/throughput superiority claim over `pgvector`
or ScaNN (parity at best on the recall × QPS frontier).

## The AI surface, in SQL

Once the extension is enabled, AI is just SQL. The database ships no model and
stores no keys — you point it at any OpenAI-compatible endpoint via session
settings.

```sql
CREATE EXTENSION IF NOT EXISTS theodb CASCADE;   -- pulls vector + vectorscale

-- Embeddings
SELECT theodb.embed('running shoes for trail');   -- → vector

-- Generation / classification, per row
SELECT ai.summarize(description)      AS gist,
       ai.analyze_sentiment(review)   AS mood
FROM products;
```

The unified query is the point — vector search, a relational JOIN, and an AI call
in **one** transaction:

```sql
SELECT p.id, p.description,
       ai.summarize(p.description) AS gist          -- AI leg
FROM products p
JOIN inventory i ON i.product_id = p.id             -- relational JOIN
WHERE i.in_stock AND p.category_id = 3              -- relational filter
ORDER BY p.embedding <=> '[0.1, 0.2, ...]'::vector   -- vector leg
LIMIT 5;
```

## Capabilities

  <Card title="Search modes" description="Semantic (`embedding <=> query`), hybrid (FTS + vector, RRF), and filtered (recall-preserving iterative scans)." />

Columnar / HTAP is on the roadmap (decided and benchmarked), not yet in the
shipped extension surface. AI calls are synchronous per row (one HTTP round-trip)
— plan for cost and latency accordingly.

## Where to go next

---

# Advanced

Source: https://docs.usetheo.dev/theokit/a2a/advanced

The MessageBus routing API, request timeouts, the A2AMessage shape and provenance, and how a2a relates to subagents and handoffs.

# Advanced A2A

Verified against `@theokit/sdk/a2a`.

## `MessageBus` — the router

`AgentMailbox` is a convenience wrapper; the bus is the primitive:

```ts
import { MessageBus } from "@theokit/sdk/a2a";

const bus = new MessageBus();
bus.register("worker", async (msg) => (msg.type === "ping" ? "pong" : undefined));
bus.unregister("worker");

await bus.send("supervisor", "worker", { type: "note", payload: "hi" });        // fire-and-forget
const reply = await bus.request("supervisor", "worker", { type: "ping", payload: null }); // → "pong"
```

Sending or requesting an **unregistered** agent throws (`Agent "<id>" not registered on MessageBus`).

## Request timeouts — `RequestOptions`

`request(..., { timeoutMs })` rejects if the target doesn't reply in time:

```ts
await mailbox.request("worker", { type: "translate", payload: "…" }, { timeoutMs: 2000 });
// throws: "A2A request timeout: worker did not respond within 2000ms"
```

Fire-and-forget `send` never waits; only `request` has a timeout.

## The message — `A2AMessage`

```ts
interface A2AMessage<T = unknown> {
  type: string;
  payload: T;
  from: string;
  to: string;
  origin: MessageOrigin;   // { kind: "peer", from } — provenance
}
```

`origin` is a thin projection of `from` (not a parallel system). A handler that turns a message into
an agent turn forwards it via `SendOptions.origin`, so `RunResult.origin` attributes the turn to the
peer that triggered it.

## Where a2a sits

`a2a` is the **substrate**; the higher-level patterns build on it:

- [Subagents](/theokit/subagents) — a supervisor delegates to a specialist and gets the answer back.
- [Handoffs](/theokit/handoffs) — one agent transfers control to another.
- [Squad](/theokit/squad) — a fixed sequential pipeline.

Reach for `MessageBus` / `AgentMailbox` directly when you need free-form peer messaging that those
patterns don't model — e.g. long-lived agents exchanging events.

## Reference

- [`MessageBus`](/theokit/reference/MessageBus) · [`AgentMailbox`](/theokit/reference/AgentMailbox) · [`A2AMessage`](/theokit/reference/A2AMessage) · [`MessageHandler`](/theokit/reference/MessageHandler) · [`RequestOptions`](/theokit/reference/RequestOptions)

---

# Overview

Source: https://docs.usetheo.dev/theokit/a2a

Agent-to-agent messaging — a mailbox and message bus so agents send each other work and carry provenance.

# A2A (agent-to-agent)

`@theokit/sdk/a2a` lets agents address and message each other directly — the substrate under
multi-agent patterns (a supervisor routing to workers, peers collaborating).

- **`AgentMailbox`** — each agent's inbox; other agents send `A2AMessage`s to it.
- **`MessageBus`** — routes messages between mailboxes (`RequestOptions` for request/response).
- **`MessageHandler`** — how an agent reacts to an incoming message.
- **Provenance** — turns triggered by a peer carry an `origin` (`{ kind: "peer", from }`), so you can
  attribute and route by who triggered them.

For the higher-level patterns built on this, see [Subagents](/theokit/subagents) and
[Handoffs](/theokit/handoffs).

## Next

- [Message another agent](/theokit/a2a/message-another-agent) — a runnable mailbox example.
- [Advanced](/theokit/a2a/advanced) — the bus API, request timeouts, and the message + provenance shape.

## Reference

- [`AgentMailbox`](/theokit/reference/AgentMailbox) · [`MessageBus`](/theokit/reference/MessageBus) · [`A2AMessage`](/theokit/reference/A2AMessage)

---

# Message another agent

Source: https://docs.usetheo.dev/theokit/a2a/message-another-agent

Register two mailboxes on a MessageBus and send fire-and-forget + request/response messages between them — deterministic, no LLM.

# Message another agent

`MessageBus` routes messages between agents by id; `AgentMailbox` wraps it with a per-agent
`send` / `request` / `onMessage` API. The whole exchange is in-process — deterministic, no LLM.

```ts title="run.ts"
import { AgentMailbox, MessageBus } from "@theokit/sdk/a2a";

const bus = new MessageBus();

// Worker: replies to "translate" requests.
const worker = new AgentMailbox("worker", bus);
worker.onMessage((msg) => {
  if (msg.type === "translate") return `[fr] ${String(msg.payload)}`;
});

// Supervisor: fire-and-forget, then request a reply.
const supervisor = new AgentMailbox("supervisor", bus);
await supervisor.send("worker", { type: "note", payload: "starting" });
const reply = await supervisor.request("worker", { type: "translate", payload: "good morning" });

console.log("reply:", reply);

worker.dispose();
supervisor.dispose();
```

## Output

Deterministic — the worker's handler return value is the request's reply:

```text
reply: [fr] good morning
```

## What it shows

- **`new AgentMailbox(id, bus)`** registers the agent on the bus; **`onMessage(handler)`** sets how it
  reacts to incoming `A2AMessage`s.
- **`send(to, { type, payload })`** is fire-and-forget; **`request(to, …)`** resolves to the handler's
  return value (with an optional timeout via `RequestOptions`).
- Each message carries **provenance** — `origin: { kind: "peer", from }` — so a receiver that turns a
  message into a turn can forward it via `SendOptions.origin`.

## Example

Full runnable source:
[`examples/a2a-mailbox`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/a2a-mailbox).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/acp/advanced

The full AcpServerOptions — permission mode and timeout, trusted tools, prompt-size cap, the initialize handshake, logging, and test seams.

# Advanced ACP

Verified against `@theokit/acp` (`serveAcp`, `AcpServerOptions`).

## `AcpServerOptions`

```ts
await serveAcp({
  agent,                          // required — SDKAgent | (sessionId) => SDKAgent
  info: { name, version },        // advertised in the ACP `initialize` handshake
  capabilities: { /* … */ },      // capability overrides for the handshake
  permissionDefault: "ask",       // permission mode — default "ask"
  permissionTimeoutMs: 60_000,     // veto a tool call if the editor doesn't answer in time
  trustedTools: ["read_file"],     // tool names that bypass "ask"
  maxPromptBytes: 2 * 1024 * 1024,  // cap on total prompt bytes (default 2 MiB)
  log: (msg) => process.stderr.write(`${msg}\n`), // logger (default stderr, per D359)
  stdin, stdout,                   // override the streams (test seam)
});
```

## Permission round-trips

With `permissionDefault: "ask"`, every tool call sends a `requestPermission` to the editor and waits
for the user's answer. If the editor doesn't reply within `permissionTimeoutMs` (default 60s), the
call is **vetoed** (fail-safe). List tool names in `trustedTools` to run them without asking.

## Per-session isolation

Passing a **factory** (`(sessionId) => SDKAgent`) rather than a single agent gives each ACP session
its own agent instance (D351) — separate conversation history, memory, and tool state. This is the
recommended shape for a multi-tab editor.

## Prompt-size cap

`maxPromptBytes` (default 2 MiB) bounds the total prompt an editor may send. Exceeding it throws
`PromptTooLargeError` rather than forwarding an oversized request to the model.

## The handshake

`info` (name + version) and `capabilities` are advertised in the ACP `initialize` exchange — how the
editor discovers what your agent is and what it can do. Both default to the package metadata / sane
capabilities when omitted.

## Reference

- [`serveAcp`](/theokit/reference/serveAcp) · [`AcpServerOptions`](/theokit/reference/AcpServerOptions) · [`AgentFactory`](/theokit/reference/AgentFactory) · [`AcpAgentInfo`](/theokit/reference/AcpAgentInfo) · [`PromptTooLargeError`](/theokit/reference/PromptTooLargeError)

---

# Overview

Source: https://docs.usetheo.dev/theokit/acp

Serve an agent over the Agent Client Protocol (ACP) so an editor like Zed can drive it — a stdio JSON-RPC server with per-session agent isolation.

# ACP server

**ACP** (Agent Client Protocol) is the protocol editors like Zed speak to drive an agent. `serveAcp`
(from **`@theokit/acp`**) hosts your agent as an ACP server over stdio JSON-RPC — the editor becomes
the front end for your `@theokit/sdk` agent.

```ts
import { serveAcp } from "@theokit/acp";
import { Agent } from "@theokit/sdk";

await serveAcp({
  // a single agent, or a factory that returns a fresh agent per session (isolation)
  agent: (sessionId) => Agent.create({ apiKey, model, systemPrompt: "You are a coding agent." }),
});
```

- **`serveAcp({ agent, … })`** — runs the server; blocks on stdio, translating ACP requests into
  `agent.send()` and streaming results back.
- **`agent`** — a single `SDKAgent` (shared) or a `(sessionId) => SDKAgent` factory (a fresh,
  isolated agent per editor session — the recommended pattern).
- **Permissions** — every tool call can round-trip a `requestPermission` to the editor; the default
  mode is `"ask"`.

## Next

- [Serve an ACP agent](/theokit/acp/serve-an-acp-agent) — the server entry point, and how an editor connects.
- [Advanced](/theokit/acp/advanced) — permission mode, trusted tools, prompt caps, and the handshake.

## Reference

- [`serveAcp`](/theokit/reference/serveAcp) · [`AcpServerOptions`](/theokit/reference/AcpServerOptions) · [`AgentFactory`](/theokit/reference/AgentFactory)

---

# Serve an ACP agent

Source: https://docs.usetheo.dev/theokit/acp/serve-an-acp-agent

Write a serveAcp entry point with a per-session agent factory, then point an editor at it over stdio.

# Serve an ACP agent

An ACP server is a stdio process an editor spawns. Give `serveAcp` a **factory** so each editor
session gets its own isolated agent, and it handles the ACP handshake, prompts, and tool-permission
round-trips.

```ts title="acp-server.ts"
import { serveAcp } from "@theokit/acp";
import { Agent, type SDKAgent } from "@theokit/sdk";

// A fresh agent per session — no shared state across editor tabs (D351).
async function createAgentForSession(sessionId: string): Promise<SDKAgent> {
  return Agent.create({
    apiKey: process.env.OPENROUTER_API_KEY,
    model: { id: "openai/gpt-4o-mini" },
    systemPrompt: "You are a coding agent.",
    local: { cwd: process.cwd(), settingSources: ["project"] }, // pick up project skills/hooks/MCP
  });
}

await serveAcp({
  agent: createAgentForSession,
  info: { name: "my-coding-agent", version: "1.0.0" },
  permissionDefault: "ask",       // tool calls prompt the editor for approval
  trustedTools: ["read_file"],     // …except these, which run without asking
});
```

Run it (`node acp-server.js` / `tsx acp-server.ts`) and register the command in your editor's ACP
agent settings — the editor spawns it and speaks ACP over its stdin/stdout.

## What it shows

- **A per-session factory** — `(sessionId) => Agent.create(...)` gives each editor session an isolated
  agent, so concurrent sessions don't share conversation state.
- **`serveAcp` blocks** — it owns the process's stdio and runs until the editor disconnects.
- **Permissions flow to the editor** — with `permissionDefault: "ask"`, each tool call round-trips a
  `requestPermission` the user approves in the editor; `trustedTools` skip the prompt.

ACP is a long-running stdio server driven by an editor, not a print-and-exit script — so it runs from
your own checkout (`@theokit/acp`), not the docs sandbox.

---

# ACP

Source: https://docs.usetheo.dev/theokit/acp

Drive an agent from an editor.

# ACP

The Agent Client Protocol adapter exposes an agent over stdio JSON-RPC, so editors like Zed, Cursor, and Claude Desktop can drive it.

| Capability | What it adds |
| --- | --- |
| `@theokit/acp` | stdio JSON-RPC server (`theokit-acp`) |

---

# Advanced

Source: https://docs.usetheo.dev/theokit/agents/advanced

The full agent surface — creation, running, continuation drivers, goal loops, forking, personalities, inspectors, lifecycle, and the cloud runtime.

# Advanced agents

The complete `Agent` (static namespace) and agent-handle (instance) surface. Most methods that touch
a whole capability (memory, subagents, guardrails…) have their own section; this page is the
exhaustive index and the agent-level controls that live nowhere else.

## Create, retrieve, manage — `Agent.*` (static)

| Call | What it does |
| --- | --- |
| `Agent.create(options)` | Create a fresh agent handle. |
| `Agent.getOrCreate(agentId, options)` | Idempotent — return the existing agent for that id, or create it. |
| `Agent.prompt(message, options)` | One-shot: create → send → dispose, returning the result. No persistent handle. |
| `Agent.builder()` | A fluent [`AgentBuilder`](/theokit/reference/AgentBuilder) for step-by-step configuration. |
| `Agent.resume(agentId, options?)` | Re-attach to a persisted agent/run and continue it. |
| `Agent.get(agentId, options?)` | Metadata for one agent (`SDKAgentInfo`). |
| `Agent.list(options?)` | Paginated list of agents. |
| `Agent.listRuns(agentId, options?)` / `Agent.getRun(runId, options?)` | Enumerate / fetch runs. |
| `Agent.archive(id)` · `Agent.unarchive(id)` · `Agent.delete(id)` | Lifecycle management. |
| `Agent.registry` | The live in-process agent registry. |

`Agent.get` / `Agent.resume` auto-detect runtime from the id prefix — `agent-…` local, `bc-…` cloud.

## Run

| Call | Returns |
| --- | --- |
| `agent.send(message, options?)` | A [`Run`](/theokit/reference/Run) — the core turn. |
| `agent.generate(message, { output })` | A validated, typed object (`{ object, result, raw, usage }`) — see [Structured output](/theokit/structured-output). |
| `Agent.generateObject(...)` / `Agent.streamObject(...)` | Static structured-output forms (buffered / streaming). |
| `Agent.batch(prompts, options)` | Run many prompts with bounded concurrency — see [Batch below](#batch). |

## Continuation drivers

A single `send()` can stop at the loop's iteration ceiling. These drive it to a genuine terminal
(`done` / `step_limit` / `no_progress`), re-prompting over the stateful session. **Local only** —
cloud agents throw `UnsupportedRunOperationError` (the cloud runtime manages continuation server-side).

| Call | Shape |
| --- | --- |
| `agent.runToCompletion(message, options?)` | Buffered — resolves to the final `RunToCompletionResult`. |
| `agent.streamToCompletion(message, options?)` | `AsyncGenerator` of `SDKMessage`s live; the result is the generator's return value. |

## Goal loops

- **`agent.runUntil(goal, options?)`** — an **ephemeral, per-call** goal-driven loop: `send → judge →
  continuation` until an auxiliary judge model returns `done`, the judge fails too often, max turns
  are exhausted, or you abort. Yields a `GoalEvent` per transition, returns a `GoalResult`. Local
  only. Pass the goal on every call — a no-goal `runUntil()` pauses. See [Goals](/theokit/goals).

> The durable, thread-scoped objective surface (`setObjective` / `getObjective` /
> `updateObjectiveOptions` / `clearObjective`, `AgentOptions.goal`) was **removed in v4.0**.

## Fork a sub-agent

**`agent.fork(options)`** spins up a short-lived sub-agent with the parent's credentials + a
byte-identical system prompt (cache hit) and a restricted tool whitelist (AsyncLocalStorage
isolation). Local only. For richer delegation see [Subagents](/theokit/subagents) and
[Handoffs](/theokit/handoffs).

## Personalities

**`agent.usePersonality(name, opts?)`** activates a personality preset for the next `send`. Reserved
names `"none"` / `"default"` / `"neutral"` clear it. `{ save: true }` persists across restarts
(`$THEOKIT_HOME/personality.json`); `{ reset: true }` also clears the session. Returns the resolved
`PersonalityPreset` (name, systemPrompt, tools, model, tags, source). Local only.

## Inspectors (read-only, conditionally populated)

| Property | Populated when | Surfaces |
| --- | --- | --- |
| `agent.context` | `AgentOptions.context` enabled | The `SDKContextManager`. |
| `agent.providers` | ≥ 1 provider route configured | Provider routing inspector. |
| `agent.skills` | project skills / `skills.enabled` | `list()` / `get(name)` of skills. |
| `agent.plugins` | project plugins / `plugins.enabled` | `list()` of plugin metadata. |
| `agent.memory` | a memory adapter registered via `plugins` | Direct `write` / `recall` / `delete` (fans out + dedupes across adapters). |

## Lifecycle & cache

- **`agent.dispose()`** / **`await using`** (`[Symbol.asyncDispose]`) — async, idempotent resource release.
- **`agent.close()`** — fire-and-forget disposal.
- **`agent.reload()`** — re-read filesystem config (context, hooks, project MCP, subagents) without disposing.
- **`agent.invalidateCache(reason, { applyNow? })`** — signal a prompt-cache rebuild. Deferred to the
  next `send` by default; a cache rebuild is a **cost regression** (the provider recharges full price),
  so use it deliberately.

## Batch

`Agent.batch(prompts, options)` runs many prompts with **bounded concurrency** (a positive integer)
— the primitive behind fan-out jobs. Invalid concurrency throws a `ConfigurationError`.

## Cloud runtime (pre-release)

Cloud agents (id prefix `bc-`) add cloud-only surfaces a local agent does not:
`agent.listArtifacts()` (local returns `[]`), `agent.downloadArtifact(path)` (local throws
`UnsupportedRunOperationError`), plus `cloudPayload` / `autoCreatePR` / `envVars`. The cloud runtime
depends on **Theo PaaS**, currently pre-release — the local runtime is the primary tested path.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`SDKAgent`](/theokit/reference/SDKAgent) · [`AgentOptions`](/theokit/reference/AgentOptions) · [`AgentFactory`](/theokit/reference/AgentFactory) · [`PersonalityPreset`](/theokit/reference/PersonalityPreset)

---

# Overview

Source: https://docs.usetheo.dev/theokit/agents

What an agent is, the parts it's made of, and the capabilities you attach to it.

# Agents

An **agent** is a model with instructions and tools that runs a task to completion.
You create one with `Agent.create()`, send it messages with `agent.send()`, and read or
stream the result. Everything else — memory, structured output, subagents, guardrails — is
a **capability you attach**, not a separate framework to learn.

## Anatomy of an agent

| Part | What it is | Configured via |
| --- | --- | --- |
| **Model** | the LLM and provider that reasons | `model` + `apiKey` |
| **Instructions** | the system prompt — static or resolved per send | `systemPrompt` |
| **Tools** | typed functions the model may call | `tools: [Tool.create(...)]` |
| **Memory** | durable facts recalled across sessions | `memory` |
| **Runtime** | where it executes — local (in-process) or cloud | `local` / a cloud key |

## What you can do

Each of these is a runnable how-to — open one and press **Run**:

| Task | Guide |
| --- | --- |
| Create an agent and read its reply | [Run an agent](/theokit/agents/run) |
| Consume the output as it arrives | [Stream a response](/theokit/streaming) |
| Get a validated, typed object back | [Return structured output](/theokit/structured-output) |

## Capabilities you attach

| Group | Capabilities |
| --- | --- |
| **Model & tools** | [Tools](/theokit/concepts/tools) · [Providers](/theokit/concepts/providers-bedrock-vertex) · Skills · Structured output |
| **Memory & context** | [Memory](/theokit/concepts/memory) · [Sessions](/theokit/concepts/sessions) |
| **Multi-agent** | Subagents · [Handoffs](/theokit/concepts/handoffs) · [Workflows](/theokit/concepts/workflows) |
| **Control & safety** | [Hooks](/theokit/concepts/hooks) · [Security](/theokit/concepts/security) · Guardrails |
| **Operations** | [Schedules](/theokit/concepts/cron) · [Evals](/theokit/concepts/eval) · [Observability](/theokit/concepts/telemetry) · [Budget](/theokit/concepts/budget) · [Cache](/theokit/concepts/cache) |
| **Connections** | [MCP](/theokit/concepts/mcp) · [Channels](/theokit/concepts/gateways) |

## Reference

- [`Agent`](/theokit/reference/Agent) — the factory and its options
- [`Run` / `RunResult`](/theokit/reference/Run) — the handle a send returns
- [`SDKMessage`](/theokit/reference/SDKMessage) — the streamed event union

---

# Run an agent

Source: https://docs.usetheo.dev/theokit/agents/run

Create a local agent, send it a message, and read the reply.

# Run an agent

Create an agent with `Agent.create()`, send it a message with `agent.send()`, and read
the reply from `run.wait()`. That is the whole loop.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  name: "explainer-bot",
  systemPrompt: "You are a concise assistant. Answer in at most two sentences.",
  // Local runtime, no sandbox — runs inline in this Node process.
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
});

const run = await agent.send("What is an AI agent? Answer for a developer.");
const result = await run.wait();

console.log("Status:", result.status);
console.log("Model: ", result.model);
console.log("Reply: ", result.result);
if (result.status === "error") {
  console.error("Error: ", JSON.stringify(result.error, null, 2));
}

await agent.dispose();
```

## Run

```bash
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys
pnpm install
pnpm run run
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Status: finished
Model:  { id: 'openai/gpt-4o-mini' }
Reply:  An AI agent is a software component that perceives its environment (e.g., via data,
sensors, or APIs), makes decisions using models or algorithms (often machine-learning or
reasoning), and takes actions to achieve defined goals autonomously or semi-autonomously.
Developers integrate agents by wiring up input adapters, a decision engine, and output
handlers that execute the chosen actions.
```

_Sample of a real run — the model is non-deterministic, so your output will read differently. Click **Run** above for a fresh one._

## What it shows

- `Agent.create({ apiKey, model, name, systemPrompt })` — the canonical factory. The
  runtime is chosen by the key you pass; `apiKey` + `local` selects the **local** runtime.
- `agent.send(message)` returns a `Run`; `await run.wait()` resolves to a `RunResult`.
- `RunResult` carries `result` (the text), `status` (`finished` | `error` | `cancelled`),
  `model`, `usage`, `cost`, and a typed `error` (populated only on `status: "error"`).
- `agent.dispose()` releases the agent's resources. Prefer
  `await using agent = await Agent.create(...)` when your TypeScript target supports it.

## Error handling

`run.wait()` does **not** throw on a provider error by default — it resolves with
`status: "error"` and a typed `error` object (e.g. an expired key surfaces as
`code: "auth_failed"`, HTTP 401). Inspect `result.status` before trusting `result.result`.
To make `send()` reject instead, pass `throwOnError: true` to `Agent.create`.

## Example

Full runnable source:
[`examples/agent-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/agent-basics).

## Next

- [Stream a response](/theokit/streaming) — consume the run as it happens.
- [Return structured output](/theokit/structured-output) — get a typed object back.

---

# Advanced

Source: https://docs.usetheo.dev/theokit/cache/advanced

Wire the cache as an agent plugin, tune threshold + TTL with an exclude regex, persist to JSON, read stats, and distinguish it from provider prompt-cache invalidation.

# Advanced cache

Verified against `@theokit/sdk-cache`.

## Transparent caching — `asPlugin()`

The explicit `consult` / `remember` API is one way in; the other is to let the cache work
transparently on every `send()`:

```ts
import { Cache, createLexicalEmbedder } from "@theokit/sdk-cache";

const cache = Cache.semantic({ embedder: createLexicalEmbedder() });

const agent = await Agent.create({
  apiKey, model,
  plugins: [cache.asPlugin()],   // caches responses on send(), serves hits automatically
});
```

`asPlugin()` is **memoized** — repeated calls return the same `Plugin`, so wiring it into multiple
agents shares one store.

## `Cache.semantic` options

```ts
Cache.semantic({
  embedder,                 // REQUIRED — no autoselect (avoids surprise API calls)
  threshold: 0.85,          // cosine distance 0..2; LOWER = stricter. Default 0.85
  ttl: { default: "1h" },   // TTL config (see below). Default { default: "1h" }
  namespace: "global",      // multi-tenant isolation. Default "global"
  modelId: "gpt-4o-mini",   // default modelId stamped on entries
  maxEntries: 1000,         // LRU eviction cap. Default 1000
  persistence: { backend: "memory" }, // or { backend: "json", dir }
});
```

## TTL + never-cache exclude

```ts
ttl: {
  default: "30m",              // "1h" | "30m" | 86400 (seconds)
  exclude: /weather|today|now/i, // queries matching this are NEVER cached
}
```

The `exclude` regex is the escape hatch for time-sensitive prompts — a "what's the weather now?" answer
should never be served stale.

## Persistence

```ts
persistence: { backend: "json", dir: "./.cache" } // survives restarts
```

`"memory"` (default) is process-local; `"json"` hydrates from `dir` on first lookup and persists
entries across runs.

## Stats + maintenance

```ts
cache.stats();          // { entries, kvHits, semanticHits, misses, excluded, evicted, embedderFailures }
cache.evictExpired();   // drop expired entries now; returns the count removed
await cache.clear();    // empty the store
```

## Not to be confused with provider prompt-cache — `agent.invalidateCache`

`@theokit/sdk-cache` caches **whole responses** by prompt similarity. Separately,
`agent.invalidateCache(reason, { applyNow? })` signals the *provider's* prompt-cache to rebuild — a
cost regression you trigger deliberately (e.g., after changing the system prompt). `applyNow: true`
disposes the agent immediately (recreate to continue); the default defers to the next `send()`. See
[Agents › Advanced](/theokit/agents/advanced).

## Reference

- [`Cache`](/theokit/reference/Cache) · [`CacheSemanticOptions`](/theokit/reference/CacheSemanticOptions) · [`CacheTTLConfig`](/theokit/reference/CacheTTLConfig) · [`CachePersistenceOptions`](/theokit/reference/CachePersistenceOptions) · [`CacheStats`](/theokit/reference/CacheStats)

---

# Cache similar prompts

Source: https://docs.usetheo.dev/theokit/cache/cache-similar-prompts

Store one answer and serve it for a similar prompt with Cache.semantic + the lexical embedder — no second LLM call. Deterministic.

# Cache similar prompts

`Cache.semantic` embeds prompts and serves a stored answer when a new prompt is *close enough*. Using
the dependency-free `createLexicalEmbedder`, the whole thing runs with **no network and no LLM** — an
exact prompt is a `kv` hit, a reworded one is a `semantic` hit, an unrelated one misses.

Cache lives in the companion package **`@theokit/sdk-cache`** — `npm i @theokit/sdk-cache`. (A release
compatible with `@theokit/sdk@3.0.0`'s SE36 API is pending, so this one runs from your own checkout
rather than the live sandbox.)

```ts title="run.ts"
import { Cache, createLexicalEmbedder } from "@theokit/sdk-cache";

const cache = Cache.semantic({
  embedder: createLexicalEmbedder(), // dependency-free — no API calls
  threshold: 0.5,                     // cosine distance; higher = more lenient match
});

await cache.remember("How do I deploy the app?", "Run the `ship` command.");

const exact = await cache.consult("How do I deploy the app?");
const similar = await cache.consult("How do I deploy my application?");
const miss = await cache.consult("What is the capital of France?");

console.log("exact:  ", exact.hit ? `${exact.source} hit -> ${exact.response}` : "miss");
console.log("similar:", similar.hit ? `${similar.source} hit -> ${similar.response}` : "miss");
console.log("miss:   ", miss.hit ? "hit" : "miss");

const s = cache.stats();
console.log(`stats:   kvHits=${s.kvHits} semanticHits=${s.semanticHits} misses=${s.misses}`);
```

## Output

Deterministic — the lexical embedder is fully offline:

```text
exact:   kv hit -> Run the `ship` command.
similar: semantic hit -> Run the `ship` command.
miss:    miss
stats:   kvHits=1 semanticHits=1 misses=1
```

## What it shows

- **`remember(prompt, response)`** feeds the cache; **`consult(prompt)`** looks it up and returns
  `{ hit, source: "kv" | "semantic", distance? }` or `{ hit: false }`.
- **`kv` vs `semantic`** — an identical prompt is a keyed hit; a reworded prompt within `threshold`
  cosine distance is a semantic hit and returns the *same* stored answer.
- **`stats()`** breaks hits down by kind (`kvHits`, `semanticHits`, `misses`) so you can measure the
  cache's real payoff.

## Example

Full runnable source:
[`examples/cache-semantic`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/cache-semantic).

---

# Overview

Source: https://docs.usetheo.dev/theokit/cache

A semantic LLM response cache — serve a cached answer when a new prompt is close enough, cutting cost and latency.

# Cache

`@theokit/sdk-cache` is a **semantic** response cache: it embeds prompts and serves a stored answer
when a new prompt is similar enough, instead of paying for another provider call.

```ts
import { Cache } from "@theokit/sdk-cache";

const cache = Cache.semantic({ /* CacheSemanticOptions */ });
await Agent.create({ /* … */, plugins: [cache.asPlugin()] });
```

- **`Cache.semantic(options)`** — build the cache (`embedder` is required; tune `threshold`, `ttl`,
  `namespace`, `maxEntries`, `persistence`).
- **`cache.asPlugin()`** — a `Plugin` you add to `Agent.create({ plugins })`; caching then happens
  transparently on `send()`.
- **`cache.consult(prompt)` / `cache.remember(prompt, response)`** — the explicit API: look up or feed
  the cache by hand (no agent required).
- **`createLexicalEmbedder()`** — a dependency-free lexical embedder for the similarity match (no API
  calls). Swap in a real embedding provider for production-grade semantics.
- **`cache.stats()`** — hit/miss counters (`CacheStats`: `kvHits`, `semanticHits`, `misses`, …).
- **`agent.invalidateCache(reason, { applyNow? })`** — signal a *provider* prompt-cache rebuild (a cost
  regression — use deliberately; see [Agents › Advanced](/theokit/agents/advanced)).

Cache ships as a separate package, **`@theokit/sdk-cache`**, and its factory is `Cache.semantic(...)`
(the embedding strategy is the constructor). Install it alongside `@theokit/sdk`.

## Next

- [Cache similar prompts](/theokit/cache/cache-similar-prompts) — a runnable `consult`/`remember` example.
- [Advanced](/theokit/cache/advanced) — the plugin path, threshold + TTL tuning, persistence, and stats.

## Reference

- [`Cache`](/theokit/reference/Cache) · [`CacheSemanticOptions`](/theokit/reference/CacheSemanticOptions) · [`CacheStats`](/theokit/reference/CacheStats) · [`createLexicalEmbedder`](/theokit/reference/createLexicalEmbedder)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/cloud/advanced

The full CloudOptions surface, cloud-only agent operations, the secret-handling boundary, and the typed cloud client.

# Advanced cloud

Verified against `@theokit/sdk` (`types/agent.ts`, cloud config serializer). The cloud runtime is
**pre-release** — this documents the contract.

## `CloudOptions`

```ts
cloud: {
  env: { type: "cloud" | "pool" | "machine", name?: string }, // which cloud environment runs the agent
  repos: [{ url, startingRef?, prUrl? }],  // repositories the agent works on
  workOnCurrentBranch: false,               // commit on the current branch vs a fresh one
  autoCreatePR: true,                        // open a PR when the agent finishes
  skipReviewerRequest: false,                // don't auto-request a reviewer on the PR
  envVars: { API_TOKEN: "…" },               // short-lived, agent-scoped secrets (names must not start with THEOKIT_)
}
```

## Cloud-only operations

A **local** agent does not have these — they throw `UnsupportedRunOperationError`:

- **`agent.listArtifacts()` / `agent.downloadArtifact(path)`** — files a run produced in the cloud
  workspace.
- **`autoCreatePR`** + `git` metadata on the result (branch, commit, PR url).
- **`cloud.envVars`** — encrypted at rest, scoped to the agent, deleted with it.

Conversely, some surfaces are **local-only** and throw on cloud (e.g. `usePersonality`, `fork`,
`runUntil`, `runToCompletion`) — the cloud runtime manages those server-side.

## Secret handling

The `cloudPayload` you can inspect is **redacted by design** — it never carries `envVars` or the raw
`env` selector. Those are transmitted **separately over TLS at create time**, encrypted at rest, and
deleted when the agent is removed. Never put a secret anywhere it would land in the per-run payload.

## The typed client — `@theokit/sdk/client`

`TheoKitClient` talks to the cloud runtime over the network with the same `send` contract:

```ts
import { TheoKitClient } from "@theokit/sdk/client";

const client = new TheoKitClient({ /* ClientOptions: baseUrl, apiKey, … */ });
const res = await client.send(agentId, message);  // SendResponse
for await (const ev of client.stream(agentId, message)) { /* StreamEvent */ }
```

Same discriminated `SDKMessage` / `StreamEvent` surface as the local runtime — the network is the only
difference. Enabled when Theo PaaS ships.

## Runtime detection

`Agent.get(id)` / `Agent.resume(id)` read the id prefix — `bc-` → cloud, `agent-` → local — and route
automatically. `Agent.list({ runtime: "cloud" })` scopes a listing to the cloud registry.

## Reference

- [`CloudOptions`](/theokit/reference/CloudOptions) · [`CloudEnv`](/theokit/reference/CloudEnv) · [`CloudRepo`](/theokit/reference/CloudRepo) · [`TheoKitClient`](/theokit/reference/TheoKitClient) · [`ClientOptions`](/theokit/reference/ClientOptions)

---

# Overview

Source: https://docs.usetheo.dev/theokit/cloud

The cloud runtime (pre-release) — run agents on Theo PaaS and reach them from a typed client.

# Cloud runtime

Pre-release. The cloud runtime depends on **Theo PaaS**, which is not yet a live endpoint. The
local runtime is the primary, tested path; this documents the contract for when PaaS ships.

Cloud agents carry the id prefix `bc-` (local agents are `agent-`), and `Agent.get` / `Agent.resume`
auto-detect the runtime from that prefix. Cloud-only surfaces (a local agent does not have these):

- `agent.listArtifacts()` / `agent.downloadArtifact(path)` — run artifacts.
- `cloud.envVars` — short-lived credentials sent to PaaS at create time over TLS (never in the
  redacted per-run `cloudPayload`).
- `autoCreatePR`, `git` metadata on results.

## The client — `@theokit/sdk/client`

`TheoKitClient` is the typed client for talking to the cloud runtime (`ClientOptions`,
`SendResponse`, `StreamEvent`) — the same `send` contract, over the network.

## Next

- [Inspect the cloud payload](/theokit/cloud/inspect-the-cloud-payload) — a runnable `cloudPayload` example.
- [Advanced](/theokit/cloud/advanced) — the full `CloudOptions`, cloud-only ops, secrets, and the client.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`CloudOptions`](/theokit/reference/CloudOptions) · [`TheoKitClient`](/theokit/reference/TheoKitClient) · [`Theokit`](/theokit/reference/Theokit)

---

# Inspect the cloud payload

Source: https://docs.usetheo.dev/theokit/cloud/inspect-the-cloud-payload

Passing cloud:{} builds a cloud agent whose redacted cloudPayload is serialized locally — inspect the exact contract sent to Theo PaaS. Deterministic, no network.

# Inspect the cloud payload

Passing `cloud: {...}` to `Agent.create` selects the **cloud runtime** — the agent id is prefixed
`bc-` and its config is serialized into a redacted `cloudPayload`. That serialization happens
**locally** (no network), so you can inspect the exact contract the SDK would send to Theo PaaS today,
even though the runtime itself is pre-release.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.THEOKIT_API_KEY ?? "theo_test_cloud",
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You are a release bot.",
  cloud: {
    env: { type: "cloud" },
    autoCreatePR: true,
    repos: [{ url: "https://github.com/acme/widget", startingRef: "main" }],
  },
});

const payload = (agent as { cloudPayload: any }).cloudPayload;

console.log("agentId prefix:", agent.agentId.slice(0, 3));   // bc- for cloud, agent- for local
console.log("schemaVersion: ", payload.schemaVersion);
console.log("autoCreatePR:  ", payload.cloud.autoCreatePR);
console.log("repo:          ", payload.cloud.repos[0].url);
console.log("model:         ", payload.model.id);

await agent.dispose?.();
```

## Output

Deterministic — the payload is built locally from your config:

```text
agentId prefix: bc-
schemaVersion:  1.0
autoCreatePR:   true
repo:           https://github.com/acme/widget
model:          openai/gpt-4o-mini
```

## What it shows

- **`cloud: {...}` picks the cloud runtime** — the id is `bc-…` (vs `agent-…` for local), and
  `Agent.get` / `Agent.resume` auto-detect the runtime from that prefix.
- **`cloudPayload`** is the redacted config the SDK sends to PaaS — repos, `autoCreatePR`, model,
  system prompt. **Secrets are never in it**: `cloud.envVars` and the `env` selector are sent
  separately over TLS at create time, never in this per-run payload.
- **No network** — building the agent and reading the payload is local; only `send()` would reach
  PaaS (pre-release).

The cloud runtime depends on **Theo PaaS**, which is not yet a live endpoint. This inspects the
contract; sending against cloud is enabled when PaaS ships.

## Example

Full runnable source:
[`examples/cloud-payload`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/cloud-payload).

---

# Use the typed client

Source: https://docs.usetheo.dev/theokit/cloud/use-the-client

Reach a hosted agent from a browser or another service with TheoKitClient — send a message or consume a live stream over HTTP.

# Use the typed client — `TheoKitClient`

`TheoKitClient` (from `@theokit/sdk/client`) is the HTTP client for reaching an agent served by the cloud runtime (or any endpoint that speaks the same contract) from outside the agent's process — a browser, an edge function, or another service.

```ts
import { TheoKitClient } from "@theokit/sdk/client";

const client = new TheoKitClient({
  baseUrl: "https://runtime.example.com",
  headers: { Authorization: `Bearer ${token}` },   // your auth — the client is transport-only
});
```

## Send a message

```ts
const res = await client.send("summarize the latest run");
// res: { status, output?, error? }
if (res.status === "finished") console.log(res.output);
```

## Consume a live stream

```ts
for await (const event of client.stream("write the release notes")) {
  // event: { type, text?, … } — discriminate on event.type
  if (event.type === "text") process.stdout.write(event.text ?? "");
}
```

## Options

| Option | Purpose |
| --- | --- |
| `baseUrl` | The runtime endpoint (required). |
| `basePath` | Path prefix if the API is mounted under a sub-path. |
| `headers` | Extra headers sent on every request — this is where your auth token goes. |

The client is deliberately thin and auth-agnostic: it carries whatever `headers` you give it, so it works with the [OAuth orchestrator](../server/auth), a bearer token, or a signed cookie — whatever your server expects.

> The cloud runtime is **pre-release** (Theo PaaS). The client contract is stable and documented here; the hosted endpoint ships with PaaS.

## Reference

- [`TheoKitClient`](/theokit/reference/TheoKitClient) · [`ClientOptions`](/theokit/reference/ClientOptions) · [`SendResponse`](/theokit/reference/SendResponse) · [`StreamEvent`](/theokit/reference/StreamEvent)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/compaction/advanced

Compact a transcript with a summary checkpoint, keep-recent vs keep-tokens windows, fail-safe summarization, and checkpoint filtering.

# Advanced compaction

Verified against `@theokit/sdk/compaction`. Everything here operates on a transcript
(`CompressibleMessage[]`) and never mutates the input.

## Compact a transcript — `compactTranscript`

```ts
import { compactTranscript, SUMMARY_TEMPLATE } from "@theokit/sdk/compaction";

const compacted = await compactTranscript(messages, {
  keepRecent: 6,                       // trailing turns kept verbatim by COUNT (default 6)
  summarize: async (older, template) => {
    // older = the window being compressed; template = SUMMARY_TEMPLATE by default
    const summary = await myLlm(template, older);
    return { role: "assistant", content: summary };
  },
});
```

- **Older window** is summarized via `summarize` (which receives the 7-section `SUMMARY_TEMPLATE`) and
  collapsed into one checkpoint turn. **Omit `summarize`** and the older window is simply *dropped*.
- **Recent window** is preserved verbatim, plus leading system prompts (in `keepRecent` mode).
- The result is `[...systemPrompts, summaryTurn, ...recent]` — a shorter transcript that keeps the thread.

## Two windowing modes

| Option | Mode | Behavior |
| --- | --- | --- |
| `keepRecent` (default `6`) | by COUNT | Keep the last N turns verbatim; preserve leading system prompts. |
| `keepTokens` | by TOKEN BUDGET | Keep trailing turns within a token budget; **takes precedence** over `keepRecent` and disables system-prompt special-casing. |

## Fail-safe summarization — `failSafe`

By default a thrown `summarize` **propagates** — the caller decides the fallback. Set `failSafe: true`
and a summarizer that throws returns the **original transcript unchanged** (with a redacted
`[compaction] summarizer failed` warning). Compaction becomes a pure optimization that can never lose
data:

```ts
await compactTranscript(messages, { summarize, failSafe: true });
// summarize threw ⇒ you get `messages` back, not an exception
```

## Checkpoints — `buildCheckpoint` / `filterFromLatestCheckpoint`

```ts
import {
  buildCheckpoint, filterFromLatestCheckpoint, CHECKPOINT_MARKER,
} from "@theokit/sdk/compaction";

const turn = buildCheckpoint(summaryText);          // prefixes CHECKPOINT_MARKER (custom marker optional)
const trimmed = filterFromLatestCheckpoint(messages); // drop everything before the last checkpoint
```

- **`CHECKPOINT_MARKER`** (`"[[theokit:checkpoint]] "`) tags a summary turn so it can be found later.
  Only `buildCheckpoint` should produce content starting with it.
- **`filterFromLatestCheckpoint`** scans for the marker and drops everything before the most recent
  one — useful to resume a session from its last checkpoint. A custom `marker` is honored on both.

## Detect provider overflow — `isContextOverflowError`

```ts
import { isContextOverflowError } from "@theokit/sdk/compaction";

try {
  await agent.send(hugePrompt);
} catch (err) {
  if (isContextOverflowError(err)) await compactAndRetry();
  else throw err;
}
```

Turns a provider's context-length error into a boolean so you can trigger compaction reactively
instead of pre-estimating every turn.

## The summary template — `SUMMARY_TEMPLATE`

`SUMMARY_TEMPLATE` is a 7-section shape (Goal / Constraints / Progress / Decisions / Next / Critical /
Files) with every header always present, so the summarizer cannot silently drop a section. Pass your
own via `summaryTemplate` to change the shape.

## Reference

- [`compaction`](/theokit/reference/index) — `compactTranscript`, `estimateTokens`, `shouldCompact`,
  `buildCheckpoint`, `filterFromLatestCheckpoint`, `isContextOverflowError`, `SUMMARY_TEMPLATE`, `CHECKPOINT_MARKER`

---

# Decide when to compact

Source: https://docs.usetheo.dev/theokit/compaction/decide-when-to-compact

Estimate a transcript's token count and check it against the model's window before the next request — deterministic, no network.

# Decide when to compact

Before you send the next turn, ask: *will it fit?* `estimateTokens` gives a cheap char-based token
estimate; `shouldCompact` compares an estimate to the model's window minus a reserved buffer. Both are
pure functions — no network, no LLM — so you can gate every turn for free.

```ts title="run.ts"
import { estimateTokens, shouldCompact } from "@theokit/sdk/compaction";

const transcript = "hello world ".repeat(50);

console.log("Estimated tokens:", estimateTokens(transcript));
console.log("Near limit? ", shouldCompact({ estimated: 9700, contextWindow: 10000, buffer: 500 }));
console.log("Room left?  ", shouldCompact({ estimated: 5000, contextWindow: 10000, buffer: 500 }));
```

## Output

Deterministic — no LLM, no network:

```text
Estimated tokens: 150
Near limit?  true
Room left?   false
```

## What it shows

- **`estimateTokens(text)`** → a char-based token estimate (roughly 4 chars per token). Cheap enough
  to run on every turn; not a replacement for a provider's exact tokenizer.
- **`shouldCompact({ estimated, contextWindow, buffer, maxOutput? })`** → `true` when
  `estimated >= contextWindow - buffer - maxOutput`. Reserve `buffer` as headroom and `maxOutput` for
  the response you still need room to generate.
- When it returns `true`, run [`compactTranscript`](/theokit/compaction/advanced) to summarize the
  older turns before the next request.

## Example

Full runnable source:
[`examples/compaction-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/compaction-basics).

---

# Overview

Source: https://docs.usetheo.dev/theokit/compaction

Compress a long conversation into a structured summary before it overflows the context window — losslessly by default.

# Compaction

Long sessions outgrow the context window. Compaction (`@theokit/sdk/compaction`) summarizes older
turns into a compact, structured checkpoint so the agent keeps its thread without blowing the budget.

- **`shouldCompact(input)`** / **`estimateTokens(text)`** — decide when to compact.
- **`buildCheckpoint(...)`** — produce a summary turn using `SUMMARY_TEMPLATE` (Goal / Constraints /
  Progress / Decisions / Next / Critical / Files); a custom `marker` (`CHECKPOINT_MARKER`) is honored.
- **`filterFromLatestCheckpoint(...)`** — drop everything before the last checkpoint.
- **`isContextOverflowError(err)`** — detect a provider context-overflow to trigger compaction.

By default a failed summarize **propagates** (the caller decides the fallback); `failSafe: true`
returns the original transcript unchanged — compaction as an optimization that never loses data.

## Next

- [Decide when to compact](/theokit/compaction/decide-when-to-compact) — a runnable `estimateTokens` +
  `shouldCompact` example.
- [Advanced](/theokit/compaction/advanced) — `compactTranscript`, windowing modes, fail-safe
  summarization, checkpoints, and overflow detection.

## Reference

- [`compaction`](/theokit/reference/index) · [`Agent`](/theokit/reference/Agent)

---

# Coming soon

Source: https://docs.usetheo.dev/theokit/concepts/_placeholder

Placeholder while Phase 3 lands the real concept pages.

This page is a placeholder. Real concept pages land in Phase 3 of the docs-site plan.

---

# ACP server

Source: https://docs.usetheo.dev/theokit/concepts/acp-server

Expose your @theokit/sdk agent as an Agent Client Protocol (ACP) server so Zed, Cursor, and Claude Desktop can drive it.

# ACP server

`@theokit/acp` exposes any `@theokit/sdk` `SDKAgent` over stdio JSON-RPC using the official [`@agentclientprotocol/sdk`](https://www.npmjs.com/package/@agentclientprotocol/sdk). Hosts like [Zed](https://zed.dev), Cursor, and Claude Desktop can then drive your agent as if it were a built-in coding agent — no glue code required.

ADRs: D349-D360. Status: v0.1 (server-only; ACP client deferred to v0.2).

## Quick start

```bash
npm i @theokit/acp @theokit/sdk @agentclientprotocol/sdk
```

Create an entry file that default-exports either an `SDKAgent` or a factory:

```ts title="src/index.ts"
import { Agent } from "@theokit/sdk";

export default async (sessionId: string) => {
  return Agent.create({
    apiKey: process.env.OPENROUTER_API_KEY,
    model: { id: "openai/gpt-4o-mini" },
    local: { cwd: process.cwd() },
    name: `acp-${sessionId}`,
  });
};
```

Launch the server:

```bash
npx theokit-acp --entry ./src/index.ts
```

Or programmatically:

```ts
import { Agent } from "@theokit/sdk";
import { serveAcp } from "@theokit/acp";

await serveAcp({
  agent: async (sessionId) => Agent.create({ /* ... */ }),
  permissionDefault: "ask",
});
```

## Session lifecycle (D352)

| ACP method               | SDK mapping                                         |
| ------------------------ | --------------------------------------------------- |
| `initialize`             | Capability advertisement                            |
| `new_session`            | `Agent.create({ local: { cwd } })`                  |
| `load_session`           | `Agent.resume(sessionId)`                           |
| `cancel`                 | `AbortController.abort()` on the session            |
| `prompt`                 | `agent.send(text, { signal }).stream()`             |
| `tool_call_permission_*` | `pre_tool_call` veto hook                           |
| `unstable_forkSession`   | Deferred to v0.2 — SDK fork is one-shot, not a split |

ACP `sessionId` is 1:1 with our SDK `agentId`. Override the mapping by writing a factory:

```ts
serveAcp({
  agent: (sessionId) =>
    Agent.resume(customMapSessionToAgentId(sessionId), { local: { cwd } }),
});
```

## Streaming translation (D353)

The translator maps every `SDKMessage` variant to the right ACP `SessionUpdate`. The switch is exhaustive — adding a new SDK message variant fails compile until the translator handles it.

| `SDKMessage.type` | ACP `SessionUpdate.sessionUpdate`            |
| ----------------- | -------------------------------------------- |
| `assistant`       | `agent_message_chunk` or `tool_call`         |
| `tool_call`       | `tool_call_update`                           |
| `thinking`        | `agent_thought_chunk` (or suppressed)        |
| `system`/`user`   | skipped (no ACP equivalent)                  |
| `status`/`task`   | skipped (cloud / milestones)                 |
| `request`         | routed via permission plugin                 |
| `object_delta`    | skipped in v0.1                              |

## Tool permissions (D355)

Three modes:

- `permissionDefault: "ask"` (default) — every tool call prompts the host UI.
- `permissionDefault: "auto"` — pass-through; no UI.
- `permissionDefault: "deny"` — reject every tool call (CI / headless).

`trustedTools` bypasses `ask` for known-safe names:

```ts
serveAcp({
  agent: factory,
  permissionDefault: "ask",
  trustedTools: ["read_file", "list_dir", "git_diff", "search_text"],
});
```

`permissionTimeoutMs` (default 60_000) prevents prompt-hang when the host doesn't respond. After timeout the tool call is auto-denied with a clear message.

## CLI flags

```text
theokit-acp [--entry <path>]
            [--permission ask|auto|deny]
            [--trusted-tools name1,name2]
            [--permission-timeout-ms 60000]
```

## Registry manifest

`@theokit/acp` ships a marketplace manifest at `packages/acp/registry/agent.json`. Install in Zed:

```bash
mkdir -p ~/.config/zed/external_agents/usetheo-sdk
cp node_modules/@theokit/acp/registry/agent.json ~/.config/zed/external_agents/usetheo-sdk/
cp node_modules/@theokit/acp/registry/icon.svg ~/.config/zed/external_agents/usetheo-sdk/
```

Edit the copied `agent.json` to point `distribution.args.[--entry]` at your entry file. Restart Zed → "Theokit SDK" appears in the External Agents palette.

## Caveats

- **Cancel cascade:** cancelling a session cancels every fork derived from it (D324 + D352). Intentional.
- **In-memory session store:** sessions live for the lifetime of the process. JSON-file persistence is on the v0.2 roadmap (D356).
- **CloudAgent + fork:** CloudAgent does not implement `agent.fork()` (D122/D169). Even when v0.2 ships `forkSession`, CloudAgent will surface `invalid_request` (EC-3).
- **Stdout reserved for JSON-RPC** (D359). Internal logs go to stderr. The `log` option accepts a custom sink.
- **2 MiB prompt cap** (D360, EC-DoS). Configurable via `maxPromptBytes`.
- **Serverless `load_session`:** session state lives in the native transcript on disk under `local.baseDir`. On a serverless restart with an ephemeral filesystem, that transcript is gone unless `baseDir` points at durable, shared storage — see [Session persistence](/theokit/guides/conversation-storage) (EC-6).

## See also

- [Session persistence](/theokit/guides/conversation-storage) — how the native transcript persists; relevant for serverless ACP deployments.
- [Tool hooks](/theokit/concepts/hooks#pre_tool_call) — what backs the permission flow.
- [Cookbook: serve as ACP agent](/theokit/guides/serve-as-acp-agent)

---

# Agent

Source: https://docs.usetheo.dev/theokit/concepts/agent

The agent loop — Agent.create, agent.send, lifecycle, persistence, LocalAgent vs CloudAgent.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — the source-of-truth file for every Agent option.

## What is an Agent

An `Agent` is a typed loop around a model, a set of tools, an optional memory store, and a session. You hand it a prompt; it decides whether to answer directly, call tools, hand off to another agent, or stream a response.

The SDK ships two flavours:

- **LocalAgent** — runs in your process. Backed by a local agent loop, MCP servers spawned via stdio, in-process tool registry, and a SQLite session store on disk. This is what you get from `Agent.create({ apiKey, model })`.
- **CloudAgent** — pointer to a remote agent running on TheoCloud (pre-release). Auto-detected when the agent id starts with `bc-` (vs `agent-` for local).

## Lifecycle

```
Agent.create(opts)  →  agent.send(prompt)  →  run.wait()  →  agent.dispose()
                              │
                              └──▶ (concurrent) run.stream()  →  AsyncIterator<SDKMessage>
```

1. **Create.** `Agent.create({ apiKey, model, tools?, mcpServers?, memory?, ... })` constructs the loop, resolves the provider, opens any MCP servers, and assigns an `agentId`. Returns a `Promise<SDKAgent>`.
2. **Send.** `agent.send(prompt, options?)` enqueues a turn. Returns a `Run` handle.
3. **Wait or stream.** `run.wait()` blocks until the agent finishes. `run.stream()` yields `SDKMessage` events as they happen (text deltas, tool calls, partials).
4. **Dispose.** `agent.dispose()` closes MCP servers, releases file handles, and stops background tasks. Use `await using` for automatic disposal:

   ```ts
   await using agent = await Agent.create({...});
   // ... auto-disposes at block exit
   ```

## Persistence

Every `LocalAgent` gets an `agentId` (e.g. `agent-7a3...`) and persists its session as a native Claude Code `.jsonl` transcript at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` (`baseDir` default `~/.theokit`; set `local.baseDir: "~/.claude"` for CLI `--continue`). Resume from a different process:

```ts
const agent = await Agent.resume(id);
```

The full message history, tool registry, and (if enabled) memory store rehydrate transparently. See [Sessions](./sessions) for the persistence contract.

## Multi-provider fallback

```ts
const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  providers: {
    routes: [{ provider: "openrouter" }],
    fallback: ["openai", "anthropic"],
  },
});
```

If `openrouter` returns a transient error, the SDK retries on `openai`, then `anthropic`. See [Providers](./providers-bedrock-vertex) for credential pools (multi-key rotation per provider).

## Common patterns

| Pattern | Where to read more |
|---|---|
| Define typed tools | [Tools](./tools) |
| Stream tokens as they arrive | [Streaming](./streaming) |
| Add MCP servers | [MCP](./mcp) |
| Run multiple prompts in parallel | `Agent.batch(prompts, options)` — see cookbook |
| Hand off to another agent | [Handoffs](./handoffs) |
| Compose multi-step pipelines | [Workflows](./workflows) |
| Cache repeated prompts | [Cache](./cache) |
| Add long-term memory | [Memory](./memory) |

## API reference

---

# Budget

Source: https://docs.usetheo.dev/theokit/concepts/budget

Track token usage + USD cost + enforce per-window spend limits.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `Budget` namespace.

The `Budget` namespace provides observable token usage, estimated USD cost, and per-window spend enforcement. Closes the last gap vs Hermes Agent's `agent/usage_pricing.py`.

ADRs: **D375-D388**. Edge cases absorbed: **EC-1..EC-22**.

## The pieces

```
TokenUsage  ← 5 buckets (input/output/cacheRead/cacheWrite/reasoning)
CostBreakdown ← amountUsd + status (actual/estimated/included/unknown) + source
Budget      ← lifecycle + 3 modes (audit/warn/block) + stacked windows
```

## Quick start

```ts
import { Budget } from "@theokit/sdk";

// Set up a daily + monthly budget
const handle = Budget.create({
  name: "production-api",
  scope: "process",
  mode: "warn",
  limits: [
    { window: "1d", limitUsd: 5 },
    { window: "30d", limitUsd: 100 },
  ],
  onThreshold: (e) => console.warn(`${e.budgetName} at ${e.threshold * 100}%`),
  onExceed: (e) => console.error(`${e.budgetName} exceeded ${e.window}`),
});

// Inspect at any time
console.log(handle.spentIn("1d"));      // current USD spent
console.log(handle.remainingIn("1d"));  // USD remaining

// Snapshot all budgets
const all = Budget.snapshot();
// → [{ name, window, spentUsd, limitUsd, ratio }, ...]
```

## The 3 modes (D383)

| Mode | Behavior |
|---|---|
| `audit` | Log only. Never throws. Never blocks. Use for rollout phase. |
| `warn` | Charges + invokes `onThreshold`/`onExceed`. Logs to stderr. Never throws. |
| `block` | `preflightCheck` throws `BudgetExceededError` BEFORE the LLM call when the upcoming charge would exceed any limit. |

Default mode is `warn` (D383).

## 4-status cost (D377)

`CostBreakdown.status` is a closed 4-value enum — show, don't lie:

- `actual` — provider billing API returned the figure (OpenRouter `/generation`).
- `estimated` — computed from bundled pricing snapshot.
- `included` — subscription route (Codex CLI, Claude Pro).
- `unknown` — no pricing data; `amountUsd` is `undefined`.

UI should render `~$1.23`, `$1.23`, `included`, or `n/a` accordingly. **Do not** default `unknown` to `$0` — that's a lie that hides untracked spend.

## 5 token buckets (D376)

```ts
interface TokenUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadTokens?: number;
  cacheWriteTokens?: number;
  reasoningTokens?: number;
  totalTokens: number;
  requests?: ReadonlyArray<Omit<TokenUsage, "requests">>;
}
```

Cache buckets matter for Anthropic prompt-caching (5min cache write × 1.25 base; 1h × 2 base; cache read × 0.10 base — see [Anthropic docs](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)). Reasoning bucket matters for OpenAI o-series models.

## Edge cases documented

### EC-18 — Emergency stop
Use `mode: 'block', limits: [{ window: '1d', limitUsd: 0 }]` to block ALL sends from a specific Budget. Functions as a kill switch.

### EC-19 — Informational-only tracking
Pass `limits: []` for pure registry-side tracking. Thresholds/onExceed never fire, but `Budget.snapshot()` accumulates spend.

### EC-20 — Delete-during-flight
`Budget.delete()` is safe during in-flight `agent.send` calls; the subsequent charge becomes a silent no-op + stderr warn.

### EC-21 — gpt-tokenizer optional peer
For strict `mode: 'block'` pre-call enforcement, install `gpt-tokenizer@^3.4.0` as a peer dep:

```bash
pnpm add gpt-tokenizer
```

Without it, block mode degrades to post-call enforce (charge happens after LLM call; budgets exceeded by the call still surface as `onExceed`).

### EC-22 — Pricing snapshot staleness
The bundled `pricing-data.json` is a hand-curated snapshot of [LiteLLM `model_prices_and_context_window.json`](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) as of 2026-05. The `pricingVersion` field on every `CostBreakdown` exposes the snapshot date so UI can warn on staleness. For live OpenRouter pricing, see the [OpenRouter API](https://openrouter.ai/api/v1/models) (snapshot is fallback only).

## v1.2 scope cut — caller-side composition

Auto-populate of `RunResult.usage` and `RunResult.cost` is deferred to v0.2. Today, callers compose explicitly:

```ts
import {
  Budget,
  computeCost,
  normalizeUsage,
  preflightCheck,
  chargeAndCheckThresholds,
} from "@theokit/sdk";

Budget.create({ name: "test", scope: "process", mode: "block", limits: [{ window: "1d", limitUsd: 1 }] });

// Pre-call enforcement (block mode)
preflightCheck("test", 0.10);

const run = await agent.send(prompt);
const result = await run.wait();

// Parse provider response → canonical 5-bucket usage
const usage = normalizeUsage(result.usage, { provider: "anthropic" });

// Apply pricing
const cost = computeCost({ provider: "anthropic", model: "claude-opus-4-7", usage });

// Charge + dispatch thresholds
if (cost.amountUsd !== undefined) {
  await chargeAndCheckThresholds("test", cost.amountUsd);
}
```

When v0.2 lands, `RunResult.usage` and `RunResult.cost` will be auto-populated and Budget enforcement integrated into `agent.send`.

## CLI inspector (v0.2)

A `theokit budget` subcommand is deferred to v0.2. Programmatic introspection via `Budget.snapshot()` covers in-process use today.

## Cloud rejection

`CloudAgent.send({ budget })` throws `UnsupportedBudgetOperationError` (D388). Cloud budget enforcement waits for TheoCloud GA.

## See also

- [Tasks](./tasks) — async work observability (paired primitive).
- [Cache](./cache) — semantic prompt caching (saves both tokens AND cost).
- [Agent](./agent) — the core `Agent.send` surface budgets attach to.

---

# Semantic cache

Source: https://docs.usetheo.dev/theokit/concepts/cache

Cache.semantic — embedding-based prompt cache with KV exact pre-filter.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Semantic cache (v1.18+)".

A cache that recognizes *semantically equivalent* prompts, not just byte-equal ones. Cuts cost 30-70% in workloads with repetitive queries.

## Plugin mode (recall + inject)

```ts
import { Cache, Agent } from "@theokit/sdk";

const cache = Cache.semantic({
  embedder: "openai/text-embedding-3-small",
  threshold: 0.85,
  ttl: 60 * 60 * 1000, // 1 hour
  namespace: "weather-bot",
});

const agent = await Agent.create({
  apiKey, model,
  plugins: [cache.asPlugin()],
});
```

When a prompt arrives, the cache:

1. Looks up exact KV match (composite key: `namespace:embedderId:modelId:hash(prompt)`).
2. If miss, embeds the prompt and runs vector similarity against stored entries.
3. If a match scores ≥ threshold, injects the cached response as a hint (the LLM still runs, but with a strong nudge).

## Direct mode (true short-circuit)

For zero-LLM-call short-circuit:

```ts
const cached = await cache.consult(prompt);
if (cached) return cached;

const result = await /* expensive LLM call */;
await cache.remember(prompt, result);
```

`consult` returns `null` on miss. `remember` stores after the fact.

## Composition

The composite key (ADR D253) ensures changing the embedder or model invalidates the cache automatically (ADR D258).

## Skipped automatically

The cache skips storing runs that invoked tools (ADR D266). Tool-use turns aren't semantically equivalent enough — they have side effects.

## Persistence

Default: in-memory LRU (1000 entries, ADR D261). JSON-on-disk opt-in:

```ts
Cache.semantic({
  // ...
  persistence: { backend: "json", dir: ".theokit/cache" },
});
```

## Telemetry

OTel events `cache.lookup` / `cache.store` with hit/miss labels (ADR D262).

## Composes with Anthropic prompt caching

Anthropic's prompt_caching (cache_control breakpoints) is orthogonal. The SDK semantic cache runs above that layer (ADR D263).

## API reference

---

# Configuration files

Source: https://docs.usetheo.dev/theokit/concepts/configuration

Markdown + YAML frontmatter format, auto-discovery, project-vs-user precedence.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Configuration files (v1.5+)" + ADR D74-D78, D150-D158.

The SDK reads several config files from `.theokit/` (project) and `~/.theokit/` (user). The format is **Markdown + YAML frontmatter** — same shape as `SKILL.md` / Claude Code (ADR D74).

## File formats

### Agents (`.theokit/agents/<name>.md`)

```markdown
---
name: weather-bot
model:
  id: openai/gpt-4o-mini
tools:
  - get_weather
---

You are a concise weather assistant. Use the get_weather tool when relevant.
```

The body is the system prompt; the frontmatter is options.

### Skills (`.theokit/skills/<name>.md`)

```markdown
---
name: morning-routine
description: Generate the morning briefing.
---

1. Check calendar for today.
2. Summarize unread emails.
3. Post to Slack #team.
```

### Personalities (`.theokit/personalities/<name>.md`)

```markdown
---
name: coder
description: Terse, code-first persona.
tools:
  - shell
  - read_file
---

You answer in code, with minimal prose. Always show working snippets.
```

ADR D161 enforces lowercase-only slug + Zod-validated frontmatter.

## One file = one entity (ADR D75)

The SDK does NOT support multi-entity files (no `agents.json` with N agents inside). Each agent / skill / personality is its own `.md`. To disable, rename to `<name>.md.disabled`.

## Validation

Every frontmatter is Zod-validated on load (ADR D76, D10). Invalid files emit a typed `ConfigurationError` — they don't break other files.

## Backward compat

The legacy JSON format (`.theokit/agents.json` etc.) still works but emits a deprecation warning. Sunset planned for v2.0 / Q2 2027 (ADR D77). Use the migration CLI:

```bash
pnpm exec theokit-migrate-config
```

Performs atomic write + timestamped backup (ADR D78).

## Auto-discovery (context files)

Beyond explicit config, the SDK auto-discovers context files via walk-up-to-git-root (ADR D151) — no `import` needed:

| File | Source |
|---|---|
| `.theokit/THEO.md` | Project-specific |
| `CLAUDE.md` | Claude Code standard |
| `AGENTS.md` | Multi-tool standard |
| `GEMINI.md` | Gemini Code Assist |
| `.cursor/rules/*.mdc` | Cursor IDE |

Merge is **concat-by-priority** (ADR D152) — not first-match-wins. All files contribute, ordered by priority.

### `@import` syntax (ADR D156)

`CLAUDE.md` and `GEMINI.md` support `@path/to/include.md` — the SDK resolves with 5-hop limit + per-import size cap.

### Size caps (ADR D155)

Per-file 40k, aggregate 120k. Over-limit → tie-break truncation, telemetry counter incremented (ADR D159).

## API reference

The configuration system is mostly transparent — you don't import a "config loader". The SDK reads files on `Agent.create` / `Skill.list` / `Personality.list`.

---

# Cron

Source: https://docs.usetheo.dev/theokit/concepts/cron

Schedule agent runs — Cron.create with croner-flavored expressions.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `Cron` namespace.

The `Cron` namespace lets you schedule recurring agent runs. Backed by [`croner`](https://github.com/Hexagon/croner) (ADR D7), persisted as JSON to `.theokit/cron/jobs.json` with atomic writes (ADR D8).

## Schedule a job

```ts
import { Cron } from "@theokit/sdk";

const job = await Cron.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  schedule: "0 9 * * *", // every day at 09:00 local
  prompt: "Summarize yesterday's logs and post to Slack.",
  agent: {
    model: { id: "openai/gpt-4o-mini" },
    name: "log-summarizer",
  },
});

console.log(job.id, job.nextFire); // "cron-abc...", "2026-05-24T09:00:00..."
```

## Persistence + restart

Jobs survive process restart. On next `Cron.list()` or `Cron.create()`, the persisted jobs reload and continue firing.

## List / cancel

```ts
const all = await Cron.list();
await Cron.cancel(job.id);
```

## Manual fire (testing)

```ts
await Cron.fire(job.id);
```

## Schedule expression

`croner` accepts:

- 5-field cron: `* * * * *` (min hour dom month dow)
- 6-field cron: `* * * * * *` (sec min hour dom month dow)
- Aliases: `@hourly`, `@daily`, `@weekly`, `@monthly`

## Caveats

- Process MUST be running when the schedule fires. Cron isn't a daemon — it's an in-process scheduler. Use a process supervisor (pm2, systemd, Cloudflare Cron Triggers, etc.) to keep your Node app alive.
- File lock via `proper-lockfile` (ADR D61) prevents two processes from corrupting `jobs.json`.

## API reference

---

# Errors

Source: https://docs.usetheo.dev/theokit/concepts/errors

Typed error hierarchy — TheokitAgentError + ErrorCode discriminator.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — error hierarchy + `ErrorMetadata`.

Every error thrown by the SDK extends `TheokitAgentError`. The hierarchy is closed (no dynamic subclassing) so `switch` on `error.code` is exhaustive.

## Base class

```ts
class TheokitAgentError extends Error {
  code: ErrorCode;        // exhaustive enum
  metadata?: ErrorMetadata; // optional structured context
}
```

`ErrorCode` is a finite literal union (ADR D66). `ErrorMetadata` is an optional field with `{ provider, endpoint, status, headers, body, rawTruncated }` shape (ADR D65, D73).

## Hierarchy

```
TheokitAgentError
├── AuthenticationError       (code: "auth_failed", "missing_api_key")
├── RateLimitError            (code: "rate_limit")
├── ConfigurationError        (code: "invalid_request", "transport_unavailable", ...)
│   └── IntegrationNotConnectedError  (MCP / OAuth not set up)
├── NetworkError              (code: "timeout", "server_error")
├── UnknownAgentError         (code: "unknown")
├── AgentRunError             (code: "agent_run_failed")
├── UnsupportedRunOperationError  (feature not available on this agent variant)
├── CredentialPoolExhaustedError  (all keys cooling down)
└── MemoryAdapterError        (code: MemoryAdapterErrorCode)
```

Plus feature-scoped errors that also extend `TheokitAgentError`:

`EvalAlreadyRunningError`, `GenerateObjectError`, `StreamObjectError`, `HandoffLoopError`, `HandoffNameCollisionError`, `HandoffPairLoopError`, `HandoffReceiverDisposedError`, `HandoffSelfReferenceError`, `CacheEmbedderError`, `CacheInvalidTtlError`, `WorkflowAlreadyRunningError`, `WorkflowCompensateNotImplementedError`, `WorkflowDuplicateStepIdError`, `WorkflowMaxIterationsExceededError`, `WorkflowNotSerializableError`, `WorkflowParallelError`, `WorkflowResumeStepNotFoundError`, `WorkflowSnapshotNotFoundError`.

## Exhaustive switch

```ts
import { TheokitAgentError } from "@theokit/sdk";

try {
  await agent.send("hi");
} catch (err) {
  if (!(err instanceof TheokitAgentError)) throw err;
  switch (err.code) {
    case "auth_failed":     return notify("Re-authenticate");
    case "rate_limit":      return retryWithBackoff(err);
    case "context_too_long": return startNewSession();
    // ... TS forces all cases handled
  }
}
```

## Provider-specific error mappers

Provider HTTP errors are mapped to canonical codes by per-dialect mappers (ADR D67, D300). Bedrock and Vertex have their own mappers; OpenAI and Anthropic share `shared.ts`. You don't call mappers directly — they run inside the LLM clients.

## Redaction

Errors carry `metadata.body` and `metadata.headers` for diagnosis. The SDK applies `redactSecrets` at output boundaries (ADR D73) — logs, telemetry attrs, transcript files. The error object itself contains raw fields; the OUTPUT is sanitized.

## API reference

---

# Eval suite

Source: https://docs.usetheo.dev/theokit/concepts/eval

Eval.create and Eval.run — eval-as-code with built-in scorers.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Eval suite (v1.15+)".

The `Eval` API lets you write evals as code (not as dashboards). Inspired by Braintrust + LangSmith but local-first.

## Define an eval

```ts
import { Eval, Scorers, Agent } from "@theokit/sdk";

const evaluation = Eval.create({
  name: "math-basics",
  dataset: [
    { input: "What is 2+2?", expected: "4" },
    { input: "What is 10*5?", expected: "50" },
    { input: "What is sqrt(16)?", expected: "4" },
  ],
  scorers: [
    Scorers.contains("expected"),
    Scorers.llmJudge({
      apiKey: process.env.OPENROUTER_API_KEY,
      prompt: "Is the output a correct numeric answer? Score 0-1.",
    }),
  ],
  agent: async (input) => {
    const agent = await Agent.create({
      apiKey: process.env.OPENROUTER_API_KEY,
      model: { id: "openai/gpt-4o-mini" },
    });
    try {
      const r = await (await agent.send(input)).wait();
      return r.result ?? "";
    } finally {
      await agent.dispose();
    }
  },
});

const run = await evaluation.run();
console.log(run.aggregate); // { meanScore, p50, p95, errorRows, tokensIn, tokensOut }
```

## Built-in scorers

| Scorer | Returns | Use |
|---|---|---|
| `Scorers.exactMatch("expected")` | 0 or 1 | Strict equality |
| `Scorers.contains("expected")` | 0 or 1 | Substring match |
| `Scorers.jsonValid()` | 0 or 1 | Is the output parseable JSON |
| `Scorers.lengthBetween(min, max)` | 0 or 1 | Length in range |
| `Scorers.llmJudge({ apiKey, prompt })` | 0..1 | LLM-as-judge with separate apiKey |

`Scorers.llmJudge` requires its own `apiKey` (ADR D205), separate from the agent under test — prevents cross-contamination of metrics.

## Parallelism

`Eval.run` internally uses `Agent.batch` (ADR D204) — default concurrency 4, per-prompt isolation (ADR D208), pool sharing via AsyncLocalStorage.

## Error isolation

If one row throws, the run continues — the row gets `error: { message }` in its result and `errorRows` increments in the aggregate. Plan accordingly.

## CLI

The `theokit` CLI wraps `Eval.run` (ADR D212):

```bash
theokit eval ./my-eval.ts
```

## Telemetry

Eval traces piggyback on the `Telemetry` namespace (D34) — `eval.run` and per-row spans. No separate tracer.

## API reference

---

# Gateways

Source: https://docs.usetheo.dev/theokit/concepts/gateways

Build agents that chat on Telegram, Discord, Slack, WhatsApp, Teams, and Email.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Slack gateway (v1.19+)".

A gateway is a channel adapter — it lets your agent receive messages from a platform (Telegram, Slack, ...) and reply, hiding platform-specific shape behind a portable `MessageEvent` union.

## Shipped adapters

| Package | Platform | Transport |
|---|---|---|
| `@theokit/gateway-telegram` | Telegram | long-polling + webhook |
| `@theokit/gateway-discord` | Discord | WebSocket Gateway |
| `@theokit/gateway-slack` | Slack | Socket Mode |
| `@theokit/gateway-whatsapp` | WhatsApp | Meta Cloud API webhook + whatsapp-web.js bridge |
| `@theokit/gateway-teams` | Microsoft Teams | `@microsoft/teams.apps` v2 SDK + Express webhook |
| `@theokit/gateway-email` | Email | IMAP IDLE inbound + SMTP outbound (nodemailer + imapflow + mailparser) |
| `@theokit/gateway-sms` | SMS | Twilio + Plivo + Vonage backends (HTTP webhook + REST outbound) |
| `@theokit/gateway-mattermost` | Mattermost | WebSocket gateway (`@mattermost/client` v9+) + REST v4 |
| `@theokit/gateway-line` | LINE Messaging API | Webhook-only (HMAC-SHA256 signed) + Reply/Push fallback |
| `@theokit/gateway-matrix` | Matrix protocol | Sync long-poll via `matrix-js-sdk` v32+; federated by default |

Each adapter is its own workspace package with peer-dep policy (ADR D171) — install only the ones you use.

The Matrix adapter (ADRs D413-D421) wraps `matrix-js-sdk@^32.0.0` (~2MB lazy-loaded peer-dep). Federation is transparent (D420) — your bot at `@bot:matrix.org` can be added to rooms by users on any homeserver and the protocol routes events automatically. DM detection (D416) uses the canonical heuristic `memberCount === 2 → dm`; else `group`. Aliases (`#general:matrix.org`) are resolved to room ids on first send + cached (D419). EC-3 absorbed: `matrix-js-sdk` initial sync delivers ~10 historical events per joined room (a 50-room bot would fire 500 LLM calls on boot); the adapter filters `event.getTs() < Date.now() - 60_000` so only live messages dispatch. E2EE rooms refused with a one-shot stderr warn (D418, deferred to v0.2). MSC4140 threads deferred to v0.2 (D417). See [`examples/matrix-bot/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/matrix-bot).

The LINE adapter (ADRs D405-D412) is webhook-only (D406 — LINE doesn't offer a WebSocket gateway). HMAC-SHA256 signature validation on every POST via `crypto.timingSafeEqual` (D408 — refuses unsigned mode at construction). `sendMessage` uses **Reply token first** (free, 60s TTL, one-shot) and falls back to **Push API** when token expired (D407) — `ReplyTokenCache` LRU(1000 entries) handles the lifecycle automatically. Source-type mapping (D410): `user` → `dm`, `group`/`room` → `group`. Mention guard (D409) uses LINE's out-of-band `event.message.mentionees: [{ userId }]` array (no inline-text confusion). EC-4 absorbed: webhook delivers 9 event types (`follow`, `unfollow`, `postback`, `beacon`, image/sticker/audio/video messages, etc.) — adapter filters at the top so handlers never see TypeError on `event.message.text` for non-text events. 5000-char surrogate-safe multipart split (D411). See [`examples/line-bot/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/line-bot).

The Mattermost adapter (ADRs D397-D404) uses the modern `@mattermost/client@^9.0.0` SDK with WebSocket gateway for real-time `posted` events and Client4 REST for outbound. Works with self-hosted Mattermost (any baseUrl) and Mattermost Cloud. PAT auth (D401); OAuth deferred to v0.2. Channel-type mapping: `D` → `dm`, `G`/`O`/`P` → `group` (raw type preserved in `event.mattermost.channelType`). Thread replies bidirectional via `root_id` ↔ `topicId` (D399). `requireMention: true` default for non-DM channels (D403). EC-2 absorbed: mention check prioritizes `metadata.mentions` array (unambiguous user-id list); text fallback uses word-boundary regex `\b@${botUsername}\b` so `@theory_dept` does NOT match a bot called `theo`. See [`examples/mattermost-bot/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/mattermost-bot).

The SMS adapter ships **three backends** (ADR D389): Twilio, Plivo, and Vonage. Pick via `backend: "twilio" | "plivo" | "vonage"`. Each backend validates inbound HMAC signatures BEFORE handler dispatch (ADR D392); webhook public endpoint without signing secret is refused at construction time (EC-1 absorbed). Outbound text is segmented into `(i/N)` parts at 1600 chars per part, grapheme-cluster-safe via `Intl.Segmenter` (ADR D393, EC-7). All phone numbers are normalized to E.164 via `libphonenumber-js` (D391). v0.1 covers texto only — MMS/group SMS/budget-per-message are deferred to v0.2. See [`examples/sms-bot/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/sms-bot).

The WhatsApp adapter ships **two backends** (ADR D303): the official Meta WhatsApp Business Cloud API (Bearer token + signed webhook) and the unofficial `whatsapp-web.js` subprocess bridge (personal accounts). Pick via `backend: "cloud" | "web"`.

The Microsoft Teams adapter is built on the **modern `@microsoft/teams.apps` v2 SDK** (ADR D315). The SDK handles JWT validation, mention stripping, and proactive send routing — we expose `BasePlatformAdapter` over it. Setup requires Azure AD App Registration + Azure Bot Service. See [`examples/teams-bot/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/teams-bot) for the 8-step walkthrough.

The Email adapter speaks the **2026 community-standard Node stack**: `nodemailer` for SMTP outbound, `imapflow` for IMAP IDLE inbound (RFC 2177 push, ~28-min auto-refresh), and `mailparser` for RFC 5322 parsing. Threading is reconstructed automatically from `Message-ID` / `In-Reply-To` / `References` (ADR D337, RFC 5322 §3.6.4) so replies land in the same thread in the user's inbox. The adapter ships hardened filters for own-address loopback (EC-1 CRITICAL), automated senders (`Auto-Submitted`, `Precedence: bulk|list`, `noreply@`, `postmaster@`), and an optional `allowedSenders` allowlist with bracket-form normalization (EC-3). Works with Gmail App Passwords, Outlook/Office 365, Yahoo, and Fastmail. See [`examples/email-bot/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/email-bot).

## Architecture

```
Platform (Telegram/Slack/...)
        │
        ▼
PlatformAdapter (per-platform package)
        │ MessageEvent (portable, discriminated by `platform`)
        ▼
SessionRouter   ←→   Agent.resume / Agent.getOrCreate
        │
        ▼
DeliveryRouter  ←→   Cron (for scheduled delivery)
```

The `BasePlatformAdapter` (ADR D172) handles lifecycle, retry, and hook plumbing. New adapters subclass it.

## Minimal Slack example

```ts
import { SlackAdapter } from "@theokit/gateway-slack";
import { Agent } from "@theokit/sdk";

const adapter = new SlackAdapter({
  appToken: process.env.SLACK_APP_TOKEN!,
  botToken: process.env.SLACK_BOT_TOKEN!,
});

adapter.onInbound(async (event) => {
  const agent = await Agent.getOrCreate({
    agentId: `slack-${event.slack!.channel.id}`,
    apiKey: process.env.OPENROUTER_API_KEY,
    model: { id: "openai/gpt-4o-mini" },
  });
  const reply = await (await agent.send(event.text)).wait();
  await adapter.send({ chatId: event.slack!.channel.id, text: reply.result! });
  await agent.dispose();
});

await adapter.connect();
```

## Portable vs platform-specific (ADR D180)

`MessageEvent` always has portable fields (`text`, `userId`, `topicId`). Platform-specific structures sit behind `event.{telegram,discord,slack}?.raw` — escape hatch for richer rendering (Adaptive Cards, Block Kit, etc.).

## Hooks (gateway-level)

Gateways expose their own hook contract (ADR D176) — separate from agent plugin hooks. Hook signature mirrors `pre_tool_call` veto pattern (ADR D177).

## Roadmap

v1.4 ships: ✅ `@theokit/gateway-whatsapp`, ✅ `@theokit/gateway-teams`, ✅ `@theokit/gateway-email` (this release). Next: `@theokit/skills-google-workspace`. See `CLAUDE.md` Adoption Roadmap.

## API reference

The gateway packages are separate from `@theokit/sdk` — see each package's README:
- [`@theokit/gateway-telegram`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/gateway-telegram)
- [`@theokit/gateway-discord`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/gateway-discord)
- [`@theokit/gateway-slack`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/gateway-slack)
- [`@theokit/gateway-whatsapp`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/gateway-whatsapp)
- [`@theokit/gateway-teams`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/gateway-teams)
- [`@theokit/gateway-email`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/gateway-email)

---

# Handoffs

Source: https://docs.usetheo.dev/theokit/concepts/handoffs

Peer-to-peer agent handoffs — declarative handoffs[] + Handoff.create.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Agent handoffs (v1.16+)".

Handoffs let an agent transfer control to another peer agent — useful for routing, specialization, and multi-agent flows.

## Declarative

```ts
const billing = await Agent.create({
  apiKey, model,
  name: "billing-agent",
  systemPrompt: "You handle billing questions.",
});

const router = await Agent.create({
  apiKey, model,
  name: "router",
  systemPrompt: "Triage. Transfer to billing-agent if the user mentions invoice or charge.",
  handoffs: [billing], // synthesized tool: transfer_to_billing-agent
});

await (await router.send("I was charged twice this month")).wait();
// Router calls transfer_to_billing-agent → billing handles the rest.
```

## Handoff-as-tool

Handoffs are implemented as synthetic tools (ADR D214). The agent decides to "call" `transfer_to_<name>` like any other tool. Inspired by `openai-agents-python` — proven pattern.

## `Handoff.create` for customization

```ts
import { Handoff } from "@theokit/sdk";
import { z } from "zod";

const handoff = Handoff.create(billing, {
  toolName: "escalate_to_billing",
  inputType: z.object({ reason: z.string() }),
  onHandoff: async (input) => console.log("[handoff]", input.reason),
  inputFilter: (history) => history.slice(-5), // only last 5 messages
});
```

## Guards

- **Peer-to-peer (D217)** — handoffs are not parent-child. The receiver runs independently.
- **Max depth 5 (D218)** — default chain limit. Configurable.
- **Single-flight per pair (D221)** — same (sender, receiver) pair can't recurse within one `send()`.
- **First-wins on parallel handoff tools (D226)** — if the model emits 2 handoffs in one turn, only the first executes.
- **CloudAgent throws `UnsupportedRunOperationError`** (D122) — handoffs are local-only in v1.

## API reference

---

# Hooks

Source: https://docs.usetheo.dev/theokit/concepts/hooks

Lifecycle hooks for plugins — pre_tool_call veto, post_assistant_reply, and 6 others.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `HookName` enum, `Plugin` discriminated union.

Hooks are typed extension points in the agent loop. Plugins register handlers; the loop invokes them at fixed lifecycle moments. The list of hook names is **closed** (8 fixed hooks, ADR D100) — adding a new one is a SDK release, not a runtime concern.

## The 8 hooks

| Hook | When | Can veto? |
|---|---|---|
| `pre_user_send` | Before user prompt added to history | No |
| `post_user_send` | After user prompt added | No |
| `pre_tool_call` | Before agent invokes a tool | **Yes** (return `{ block: true, message? }`) |
| `post_tool_call` | After tool returns | No |
| `pre_assistant_reply` | Before model generates reply | No |
| `post_assistant_reply` | After model emits final assistant message | No |
| `pre_dispose` | Before agent disposes | No |
| `post_dispose` | After agent disposed | No |

## Veto pattern

`pre_tool_call` is the only veto hook. Returning `{ block: true, message: "reason" }` aborts the tool call — the agent receives a synthetic `tool_result isError: true` and continues. Never throw from a veto hook (ADR D101).

```ts
import { Plugin } from "@theokit/sdk";

const noShellInProd = Plugin.create({
  kind: "hook",
  name: "no-shell-in-prod",
  hooks: {
    pre_tool_call: (ctx) => {
      if (ctx.toolName === "shell" && process.env.NODE_ENV === "production") {
        return { block: true, message: "Shell tool disabled in production." };
      }
    },
  },
});

const agent = await Agent.create({ apiKey, model, plugins: [noShellInProd] });
```

## Plugin context

Every hook receives a typed context object. The shape depends on the hook. In dev mode the context is sealed via Proxy (ADR D99) — assigning to it throws, helping you catch accidental mutation.

Example `PreToolCallContext`:

```ts
type PreToolCallContext = {
  toolName: string;
  toolArgs: unknown;
  agentId: string;
  runId: string;
  turnIndex: number;
  // ...
};
```

See the [Plugins concept](./plugins) for the full Plugin contract.

## API reference

---

# MCP (Model Context Protocol)

Source: https://docs.usetheo.dev/theokit/concepts/mcp

Connect to stdio + HTTP MCP servers, including OAuth 2.1 PKCE flows.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `mcpServers` option, OAuth flow.

[Model Context Protocol](https://modelcontextprotocol.io) is an open standard for connecting AI agents to data sources and tools. The SDK is a first-class MCP client.

## Stdio servers (local processes)

Most MCP servers ship as npx-runnable Node processes:

```ts
const agent = await Agent.create({
  apiKey, model,
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
    },
    puppeteer: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-puppeteer"],
    },
  },
});
```

The SDK spawns each server, discovers its tools/resources/prompts, and exposes them to the agent loop. On `dispose()`, all child processes are terminated.

## HTTP servers (remote)

For remote MCP servers (e.g. SaaS APIs):

```ts
mcpServers: {
  notion: {
    type: "http",
    url: "https://mcp.notion.com",
    headers: { Authorization: `Bearer ${process.env.NOTION_TOKEN}` },
  },
}
```

## OAuth 2.1 PKCE (remote SaaS APIs)

For MCP servers that require OAuth (e.g. Notion, Linear), the SDK ships a PKCE flow:

```bash
pnpm exec theokit-mcp-auth-notion --setup
```

This walks the user through browser auth, stores the token in OS keychain (fallback: `~/.theokit/mcp-tokens.json` with 0600 perms — ADR D41), and the agent picks it up automatically:

```ts
mcpServers: {
  notion: {
    type: "http",
    url: "https://mcp.notion.com",
    oauth: { provider: "notion" },
  },
}
```

See the [mcp-oauth-notion example](https://github.com/usetheodev/theokit-sdk/tree/main/examples/mcp-oauth-notion).

## MCP config files

Beyond inline config, the SDK reads `.theokit/mcp.json` (project) and `~/.theokit/mcp.json` (user). Project entries override user entries by key. See [Configuration](./configuration).

## Configuration reference

```ts
type McpServerConfig =
  | { command: string; args?: string[]; env?: Record<string, string> } // stdio
  | { type: "http"; url: string; headers?: Record<string, string>; oauth?: McpOauthConfig };
```

## API reference

---

# Memory

Source: https://docs.usetheo.dev/theokit/concepts/memory

Long-term memory — SQLite + sqlite-vec + FTS5 by default, LanceDB optional, pluggable adapters.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `Memory.*`, embedding adapters, MemoryAdapter interface.

Memory lets an agent recall facts across sessions. The SDK ships:

- **Default backend:** SQLite + sqlite-vec + FTS5 — zero setup, written to `.theokit/memory/`.
- **LanceDB backend** (opt-in via `@lancedb/lancedb`) — scales beyond ~100k facts.
- **Pluggable adapters:** `@theokit/memory-supermemory`, `@theokit/memory-honcho`, `@theokit/memory-mem0`.

## Enable Active Memory

```ts
const agent = await Agent.create({
  apiKey, model,
  memory: { enabled: true },
});
```

That's it. The SDK adds two hooks (ADR D145):

1. `pre_user_send` — query memory for relevant facts, inject as `<active-memory>` block in the prompt.
2. `post_assistant_reply` — extract new facts from the conversation, store them.

## Direct API

For programmatic access:

```ts
await agent.memory.write({ content: "User's home city is Brasília." });
const hits = await agent.memory.recall("home city");
await agent.memory.delete(hits[0].id);
```

## Embedding providers

Memory uses embeddings to do semantic recall. Built-in adapters (ADR D11):

| Provider | Env var |
|---|---|
| OpenAI (`text-embedding-3-small`) | `OPENAI_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Voyage | `VOYAGE_API_KEY` |
| DeepInfra | `DEEPINFRA_API_KEY` |
| Ollama (local) | none |

Configure via `memory: { embedding: { provider: "voyage" } }`.

## LanceDB (scale)

```bash
pnpm add @lancedb/lancedb
```

```ts
memory: { enabled: true, backend: "lancedb" }
```

Migration tool: `pnpm exec theokit-migrate-memory` (CLI, ADR D44).

## Custom adapters

Implement the `MemoryAdapter` interface (ADR D141) and pass via `memory: { adapter: myAdapter }`. The three shipped adapter packages are reference implementations:

- `@theokit/memory-supermemory` — MIT, zero-dep cloud client (default suggestion)
- `@theokit/memory-honcho` — dialectic reasoning (AGPL — read the README disclosure)
- `@theokit/memory-mem0` — cloud-only, unique `history(id)` API (CVSS disclosure in README)

## API reference

---

# Plugins

Source: https://docs.usetheo.dev/theokit/concepts/plugins

Plugin.create — discriminated union by kind, sealed PluginContext, closed HookName enum.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — ADRs D97-D104.

Plugins are the extension point of the SDK. The contract lives at `internal/plugins/` (ADR D97) and reaches consumers via `Plugin.create` + the `Plugin` discriminated union.

## Plugin kinds

```ts
type Plugin =
  | { kind: "hook"; ... }      // lifecycle hooks
  | { kind: "tool"; ... }      // toolset provider
  | { kind: "cache"; ... }     // semantic cache (Cache.semantic().asPlugin())
  | { kind: "telemetry"; ... } // custom telemetry sink
  | ... // see docs.md for full list
```

The union is **closed by `kind`** (ADR D98) — TypeScript forces exhaustive handling.

## `Plugin.create`

```ts
import { Plugin } from "@theokit/sdk";

const myPlugin = Plugin.create({
  kind: "hook",
  name: "rate-limit-tool-calls",
  hooks: {
    pre_tool_call: async (ctx) => {
      if (await isRateLimited(ctx.agentId)) {
        return { block: true, message: "Slow down." };
      }
    },
  },
});

const agent = await Agent.create({ apiKey, model, plugins: [myPlugin] });
```

## `PluginContext` (sealed in dev mode)

The context object passed to plugin hooks is sealed via Proxy in dev mode (ADR D99). Trying to assign to it throws — catches accidental mutation early.

In production, the Proxy is bypassed (no overhead).

## Hooks

See the [Hooks concept](./hooks) — 8 closed hook names (ADR D100), `pre_tool_call` is the only veto hook (ADR D101).

## Toolset plugins

A plugin with `kind: "tool"` provides a `Toolset`. The `ToolRegistry` is 3-layer (ADR D102):

1. **Registration** — plugin declares its tools.
2. **Exposure** — agent decides which subset to surface to the model per turn (via `check_fn` predicate, TTL-cached 30s — ADR D103).
3. **Availability** — per-turn check.

A `Toolset` is a flat list — no `extends` (ADR D104). Composition via multiple plugins.

## Discovery

Beyond programmatic `plugins: [...]`, the SDK loads `.theokit/plugins/*.ts` (project) and `~/.theokit/plugins/*.ts` (user). Each file must `export default` a `Plugin`.

## API reference

---

# AWS Bedrock + GCP Vertex

Source: https://docs.usetheo.dev/theokit/concepts/providers-bedrock-vertex

Enterprise cloud providers — Bearer/SigV4 auth, region routing, dialect dispatch.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Bedrock provider" + "Vertex AI provider".

The SDK ships two built-in profiles for enterprise cloud LLM providers — Bedrock (AWS) and Vertex (GCP). Both reuse the existing transport architecture (ADRs D105/D106) — `ProviderProfile` is data-only, transport is orthogonal.

## Bedrock

Claude models on AWS. v1 uses Bearer-only auth (no SigV4) — see ADR D286.

```ts
const agent = await Agent.create({
  apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK ?? "__bedrock_lazy_token__",
  model: { id: "bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0" },
});
```

The model id has 3 parts:

- `bedrock/` — provider prefix (stripped before sending)
- `us.` (or `eu.`, `apac.`, `jp.`, `global.`) — region prefix → routes to the right Bedrock regional endpoint (ADR D290)
- `anthropic.claude-...` — the model id Bedrock expects

### Auto-token via AWS credential chain

For long-running services, install the optional peers and the SDK auto-generates a Bearer from your standard AWS credentials:

```bash
pnpm add @aws/bedrock-token-generator @aws-sdk/credential-providers
```

The SDK reads from env vars → `AWS_PROFILE` → `~/.aws/credentials` → IMDS, in that order, mints a Bearer, and caches it for 1.5h (ADR D295).

### Common gotcha

The AWS account must complete the **"Anthropic use case details"** form in the Bedrock Console — separate from "Model access". Without it, every call returns `ResourceNotFoundException: Model use case details have not been submitted`. The error mapper surfaces an actionable message.

## Vertex AI

Both Claude and Gemini available. ADC auth via `google-auth-library` (required peer, ADR D288).

```bash
pnpm add google-auth-library
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="your-project-id"
```

Two dialects:

```ts
// Claude on Vertex (Anthropic Messages API via :rawPredict)
model: { id: "vertex/anthropic/claude-sonnet-4-5-20250929" }

// Gemini on Vertex (OpenAI-compat endpoint)
model: { id: "vertex/google/gemini-2.0-flash-001" }
```

The SDK dispatches between dialects at stream time (ADR D291/D292). Both reuse existing clients (`OpenAIClient` rewriter for Gemini, dedicated `VertexAnthropicClient` for Claude).

### Global location

`vertex/anthropic/...` with `VERTEX_LOCATION=global` forces baseUrl `aiplatform.googleapis.com` (no region prefix) — fixes the cline#10287 routing issue (ADR D293).

## Deferred to v1.x

| Feature | ADR |
|---|---|
| Bedrock streaming (Event Stream binary parser) | D302 |
| Bedrock Converse + Computer Use | D296 |
| Vertex WIF (Workload Identity Federation) walkthrough | D297 |
| SigV4 transport for Bedrock | D298 |

## API reference

---

# Security

Source: https://docs.usetheo.dev/theokit/concepts/security

Secret redaction at output boundaries, path traversal defense, TOCTOU primitives.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Security — secret redaction" + "Security — path traversal + TOCTOU".

The SDK takes two security concerns seriously: **secrets in observable output** and **filesystem operations on untrusted input**.

## Secret redaction (ADR D68-D73)

Every output boundary (logs, telemetry attrs, error metadata, transcripts) is wrapped by `redactSecrets`. The canonical implementation lives at `internal/security/redact.ts` — there's one source of truth.

**What gets redacted:**

- API key patterns (`sk-...`, `Bearer ey...`, `xoxb-...`)
- AWS access keys (`AKIA[0-9A-Z]{16}`)
- GitHub tokens (`ghp_...`, `gho_...`)
- JWT-like tokens (3-part base64url)
- URL `?token=` / `?api_key=` query params
- Environment-variable values when stringified

**Two-bucket masking (ADR D71):**

- Short tokens (less than 18 chars) → `***`
- Long tokens → `prefix...suffix` (first 4 + last 4)

**Opt-out (NOT recommended):**

```bash
export THEOKIT_REDACT_SECRETS=0
```

Emits a one-time stderr warning (ADR D70). The env var is snapshotted at module init (ADR D69) — prompt-injection defense.

**`codeFile: true` flag (ADR D72):**

When generating `.env.example` placeholders or similar, set `codeFile: true` to skip PARAM_PATTERN redaction — preserves intentional examples like `OPENAI_API_KEY=sk-...`.

## Path traversal + TOCTOU (ADRs D79-D85)

When the SDK writes to user-supplied paths (skills, agents, personalities, OAuth tokens), it routes through path-safety primitives:

| Primitive | Use |
|---|---|
| `safePathJoin(base, ...parts)` | Resolves THEN prefix-checks (defeats normalized `..` escape) |
| `sanitizeIdentifier(name)` | Strict grammar `^[a-z0-9][a-z0-9_-]*$` |
| `createExclusive(path, mode)` | `O_EXCL` open with default mode 0o600 |
| `casUpdate(db, stmt, params)` | SQLite optimistic compare-and-swap |

Available as `Security.*` namespace and at `@theokit/sdk/path-safety` sub-export (separate from main barrel to keep DTS bundle clean).

```ts
import { Security } from "@theokit/sdk";

const safe = Security.safePathJoin(".theokit/skills", userProvidedName);
```

## CI lint gate (ADR D85)

`packages/sdk/tests/lint/no-unredacted-sink.test.ts` runs in CI and fails if a new `console.log`/`writeFile`/`span.setAttribute` lands in `src/` without going through `redactSecrets`. Each whitelisted file carries a rationale comment.

`packages/sdk/tests/lint/no-todo-fixme.test.ts` prevents production stubs.

## API reference

---

# Sessions

Source: https://docs.usetheo.dev/theokit/concepts/sessions

How conversations persist across processes via Agent.resume and the native Claude Code .jsonl transcript.

> **Canonical contract:** [`docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/docs.md) — `Agent.resume`, native session transcript contract.

A *session* is the message history, tool registry, and optional memory of a single agent. Every `LocalAgent` gets a stable `agentId` and persists its session as a **native Claude Code `.jsonl` transcript** at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` (`baseDir` defaults to `~/.theokit`; set `local.baseDir: "~/.claude"` for Claude Code CLI `--continue` interop).

## The agent id

```ts
const agent = await Agent.create({ apiKey, model });
console.log(agent.agentId); // "agent-7a3c2f..."
```

Two namespaces:

- `agent-...` — LocalAgent (default).
- `bc-...` — CloudAgent (TheoCloud, pre-release).

`Agent.resume(id)` auto-detects by prefix and rehydrates from the appropriate backend.

## Resume across processes

```ts
// Process 1
const agent = await Agent.create({...});
const id = agent.agentId;
await (await agent.send("Hi, my name is Paulo.")).wait();
await agent.dispose();

// Process 2 (later, fresh Node process)
const resumed = await Agent.resume(id);
const r = await (await resumed.send("What's my name?")).wait();
console.log(r.result); // "Your name is Paulo."
```

The store is filesystem-based — survives crashes, replicable via `cp -r`, observable via `cat`.

## `Agent.getOrCreate`

Idempotent helper that tries `resume(id)` first; if the id doesn't exist, falls back to `create(options)` with that id:

```ts
const agent = await Agent.getOrCreate({
  agentId: "stable-id-from-my-app",
  apiKey, model,
});
```

Use this when your application has a stable per-user id (e.g. Telegram chat id) and wants "one agent per user, ever".

## What's persisted

| Persisted | Not persisted |
|---|---|
| Message history (user + assistant + tool) | Background MCP servers (re-spawned on resume) |
| Tool registry definitions | LLM client state (re-resolved from env) |
| Active memory facts (if memory enabled) | Live streams |
| Personality preset (if set) | Hooks (re-loaded from .theokit/hooks.json) |
| Cron job snapshots | Telemetry traces (already exported) |

## Disposal & cleanup

Always dispose:

```ts
await using agent = await Agent.create({...}); // Symbol.asyncDispose
// ...
```

Or explicit:

```ts
try { /* ... */ } finally { await agent.dispose(); }
```

`dispose()` is idempotent. The transcript on disk remains until you explicitly delete it (`<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`).

## API reference

---

# Skills — Google Workspace

Source: https://docs.usetheo.dev/theokit/concepts/skills-google-workspace

Wire Calendar, Drive, Sheets, Docs, Gmail, Slides, and Forms into your agent via the combined google-workspace-mcp server.

> **Concept:** `@theokit/skills-google-workspace` is a **skills bundle**, not a gateway. Gateways carry user conversation **into** the agent; skills are **tools the agent uses**. Use this package when you want your agent to read your calendar, summarize a Doc, append rows to a Sheet, etc.

A single workspace package that emits one `McpServerConfig` running the [`google-workspace-mcp`](https://github.com/pm990320/google-workspace-mcp) server (pm990320, MIT, GitHub Actions OIDC trusted publisher). One subprocess covers seven Google products. Read-only is the default per ADR D343.

## Quick start

```bash
pnpm add @theokit/skills-google-workspace
npx theokit setup gworkspace   # validates OAuth client + delegates to upstream installer
```

```ts
import { Agent } from "@theokit/sdk";
import { googleWorkspace } from "@theokit/skills-google-workspace";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: { id: "openai/gpt-4o-mini" },
  mcpServers: googleWorkspace(),   // read-only by default
});

const reply = await (await agent.send("What's on my calendar tomorrow?")).wait();
console.log(reply.result);
await agent.dispose();
```

## Tools exposed

The upstream server provides **95+ tools** across:

| Product | Examples |
|---|---|
| Calendar | `listCalendars`, `listCalendarEvents`, `createCalendarEvent` |
| Drive | `listGoogleDocs`, `searchGoogleDocs`, `getRecentGoogleDocs` |
| Docs | `readGoogleDoc`, `appendToGoogleDoc`, `insertText`, comments |
| Sheets | `readSpreadsheet`, `writeSpreadsheet`, `appendSpreadsheetRows` |
| Gmail | `listGmailMessages`, `searchGmail`, `createGmailDraft`, `sendGmailDraft` (draft workflow for safety) |
| Slides | `listPresentations`, `createPresentation`, `addSlide`, `addTextToSlide` |
| Forms | `listForms`, `readForm`, `getFormResponses`, `createForm` |

## Read-only by default (ADR D343)

```ts
googleWorkspace()                // safe — write tools return errors
googleWorkspace({ writable: true }) // unlocks Drive write, Gmail send, Calendar create, ...
```

The OAuth consent grants broad scopes (the upstream server uses one wide consent screen). `--read-only` is a runtime safety on top of that, NOT scope narrowing. To genuinely have narrow scopes, manage scope selection inside Google Cloud Console at consent time.

## CLI setup walkthrough

```bash
npx theokit setup gworkspace
```

What it does:

1. **EC-1 guard (MUST FIX):** validates that `~/.google-mcp/credentials.json` is a *Desktop application* OAuth client (not the *Web application* type that silently fails downstream). Bails with an actionable error if the wrong type is detected.
2. **EC-2 guard:** validates JSON shape before shelling out.
3. **Delegates** to `npx google-workspace-mcp setup` and `accounts add default` for the actual OAuth dance.

Flags:
- `--probe` — runs `npx google-workspace-mcp status` after staging (10s timeout per upstream call).
- `--credentials-path <path>` — override the default `~/.google-mcp/credentials.json`.
- `--non-interactive` — refuses prompts; suitable for CI.
- `--writable calendar,drive` — informational only; the actual write toggle lives in your `googleWorkspace({ writable: true })` call.

## Multi-account

```bash
npx google-workspace-mcp accounts add work
npx google-workspace-mcp accounts add personal
```

```ts
const workAgent = await Agent.create({
  apiKey: ...,
  mcpServers: googleWorkspace({ account: "work" }),
});
```

The factory keys the MCP server under `gworkspace-work` (or `gworkspace` for the default account), so it does not collide with other agents.

## ADRs

- **D340** — separate workspace package (matches gateway-* pattern, D170/D171)
- **D341** — single factory returns `Record<string, McpStdioServerConfig>`
- **D342** — stdio launch via `npx google-workspace-mcp serve`
- **D343** — read-only-by-default
- **D344** — credentials at upstream default `~/.google-mcp/credentials.json`
- **D345** — OAuth delegated to upstream `accounts add` CLI
- **D346** — `theokit setup` is a new CLI verb (future-proofs `setup notion`, `setup linear`)
- **D347** — six cookbook recipes, last one combines Calendar + Drive
- **D348** — package version 0.1.0 per D181 pre-1.0 policy

## See also

- [`examples/skills-google-workspace/`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/skills-google-workspace) — six recipes
- [`@theokit/skills-google-workspace`](https://github.com/usetheodev/theokit-sdk/tree/main/packages/skills-google-workspace) — package source
- Upstream MCP server: [github.com/pm990320/google-workspace-mcp](https://github.com/pm990320/google-workspace-mcp)

---

# Streaming

Source: https://docs.usetheo.dev/theokit/concepts/streaming

Read tokens, tool calls, and artifacts as they arrive — AsyncIterator of SDKMessage.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `SDKMessage` discriminated union, `run.stream()`, Vercel AI Data Stream v1 wire format.

`agent.send(prompt)` returns a `Run`. You can `await run.wait()` for the full result, OR iterate `run.stream()` to consume events as they happen.

## Iterate the stream

```ts
const run = await agent.send("Tell me a story about robots.");

for await (const msg of run.stream()) {
  switch (msg.type) {
    case "text_delta":
      process.stdout.write(msg.text);
      break;
    case "tool_call":
      console.log("[calling tool]", msg.name);
      break;
    case "tool_result":
      console.log("[tool returned]", msg.content);
      break;
    case "finished":
      console.log("\n[done]", msg.stopReason);
      break;
  }
}
```

`SDKMessage` is a discriminated union. The full variant list:

| `type` | Meaning |
|---|---|
| `text_delta` | Incremental text token from the model |
| `tool_call` | Model emitted a tool call (name + args) |
| `tool_result` | Tool execution finished (success or error) |
| `partial_object` | When using `streamObject`, partial typed payload |
| `complete_object` | When using `streamObject`, final typed payload |
| `finished` | Run is over (with `stopReason: end_turn | max_tokens | tool_use | ...`) |
| `error` | A non-recoverable error was emitted |

## Structured streaming (`streamObject`)

For typed payloads, use `Agent.streamObject<T>`:

```ts
import { z } from "zod";
const schema = z.object({ title: z.string(), bullets: z.array(z.string()) });

const stream = await Agent.streamObject({
  apiKey, model, schema,
  prompt: "Outline a blog post about Rust ownership.",
});

for await (const msg of stream) {
  if (msg.type === "partial_object") console.log("partial:", msg.value);
  if (msg.type === "complete_object") console.log("final:", msg.value);
}
```

The SDK uses a synthetic forced tool (ADR D33) — the model calls a single tool whose schema is your Zod schema, the SDK validates each partial, and you get progressively-typed updates.

## React hooks

For browser apps, `@theokit/react` exposes hooks that consume the same wire format (Vercel AI Data Stream v1, ADR D38):

- `useTheoChat` — multi-turn chat
- `useTheoCompletion` — single-shot text
- `useTheoAssistant<T>` — object streaming

See the [react-nextjs example](https://github.com/usetheodev/theokit-sdk/tree/main/examples/react-nextjs).

## API reference

---

# Tasks

Source: https://docs.usetheo.dev/theokit/concepts/tasks

Observable async work — Task.submit / list / get / cancel / subscribe.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `Task` namespace.

The `Task` namespace gives every piece of asynchronous work in the SDK a stable id, a 5-state lifecycle, an event stream, and a way to cancel it — without you writing your own job queue. It is the second gap closed against Hermes Agent's kanban registry, the first being [`ACP`](./acp-server).

ADRs: **D361-D374**. Edge cases absorbed: **EC-1..EC-16**.

## The 5 states

```
queued ─▶ running ─▶ finished
                  ├─▶ error
                  └─▶ cancelled
queued ──────────────▶ cancelled  (direct, no run)
```

Closed enum (D362). Transitions are acyclic — once a task is `finished` it stays `finished` until evicted.

## Submitting work

```ts
import { Task } from "@theokit/sdk";

const handle = await Task.submit("custom", async (ctx) => {
  ctx.emit({ step: "starting" });
  await doSomeWork({ signal: ctx.signal });
  return "result";
});

console.log(handle.id); // queued task id
```

`Task.submit(kind, work, options?)` takes:

- **`kind`** — one of `run | batch | workflow | cron | custom`. Discriminator only (D374); the registry does not branch on it.
- **`work`** — `(ctx) => Promise<T> | T`. `ctx.signal` is the AbortSignal honored on cancel; `ctx.emit(payload)` produces a `progress` event observable via `subscribe`.
- **`options`** — `{ id?: string; meta?: Record<string, unknown>; signal?: AbortSignal }`.

Returns a `TaskHandle` in `state: "queued"` immediately. Transitions happen in the background.

## Querying

```ts
// Single handle
const handle = await Task.get("abc-123");

// All handles, optionally filtered
const running = await Task.list({ state: "running" });
const cronFires = await Task.list({ kind: "cron", limit: 50 });
```

`Task.list(filter?)` returns up to `filter.limit ?? 100` handles. `JsonFileTaskStore` hard-caps loaded entries at 256 — page deeper by walking `submittedBefore`.

## Subscribing to progress

```ts
for await (const event of Task.subscribe(handle.id)) {
  switch (event.type) {
    case "submitted":  console.log("queued", event.taskId);  break;
    case "started":    console.log("running");               break;
    case "progress":   console.log("progress", event.payload); break;
    case "finished":   console.log("done", event.result);    return;
    case "errored":    console.error("err", event.error);    return;
    case "cancelled":  console.log("cancelled");             return;
  }
}
```

- **Late attach** is safe: the ring buffer (cap 64, D372) replays buffered events before tailing live. If the buffer was full at attach, the first replayed event carries a `truncated: true` flag.
- **Cleanup is automatic**: terminal events close the iterator; `break` inside the `for await` cleans up the subscriber (EC-10).

## Cancelling

```ts
const { cancelled, alreadyTerminal } = await Task.cancel("abc-123");
```

`Task.cancel` is **idempotent** (D365):
- Unknown id → `{ cancelled: false, alreadyTerminal: false }`. No throw.
- Terminal task → `{ cancelled: false, alreadyTerminal: true }`.
- Queued task → state transitions to `cancelled` immediately. AbortController not invoked.
- Running task → `ctx.signal` is aborted; the work function unwinds naturally.

## Persistence

```ts
import { Task } from "@theokit/sdk";

Task.configure({
  store: { backend: "json", dir: "/var/lib/myapp/tasks" },
  maxConcurrent: 16,
  retentionMs: 24 * 60 * 60 * 1000, // 7 days
});
```

- **`memory`** (default) — transient, lost on process exit. Retention 1 hour.
- **`json`** (opt-in) — one file per task. Survives restart. Retention 7 days. **Single-process** (EC-15) — concurrent writers from multiple Node processes may corrupt the store. v0.2 will add a SQLite backend behind the same interface.

> Configure once, before the first `submit`. Subsequent `configure()` calls are no-ops with a one-line stderr warning (EC-13).

## ID grammar

User-supplied ids must match `^[a-z0-9][a-z0-9_-]*$` and must NOT start with the reserved prefixes `wf-`, `b-`, or `cron-` (D368). Auto-generated ids use `crypto.randomUUID()`.

## CLI

```bash
theokit tasks list
theokit tasks list --state running --json
theokit tasks inspect <id>
theokit tasks cancel <id>
```

The CLI reads the `JsonFileTaskStore` at `$THEOKIT_HOME/tasks/` (fallback: `<cwd>/.theokit/tasks/`). Cross-process cancel sets `cancelRequested: true` on the handle — the owning process honors it at the next checkpoint (EC-7, best-effort).

## Wrapping existing work

The simplest pattern: caller envelops async work themselves.

```ts
const handle = await Task.submit("run", async (ctx) => {
  const run = await agent.send(prompt, { signal: ctx.signal });
  for await (const msg of run.stream()) {
    ctx.emit({ chunk: msg });
  }
  return (await run.wait()).result;
});
```

Fan-out batch with parent / children:

```ts
const parent = await Task.submit("batch", async (ctx) => {
  return Promise.all(
    inputs.map((input) =>
      Task.submit("run", async (childCtx) => {
        childCtx.emit({ input });
        return await processOne(input, childCtx.signal);
      }, { meta: { parentId: ctx.signal ? "auto" : undefined } }),
    ),
  );
});
```

> Auto-wrapping of `Agent.send` / `Agent.batch` / `Workflow.run` / `Cron` via an `{ task: true }` option on each is deferred to **v0.2**. v1 ships the primitive only; the user-side pattern above covers every observability use case today.

## Telemetry

Three OTel spans emitted via the existing seam (D34, D371):
- `task.submit` — attrs: `task.id`, `task.kind`.
- `task.transition` — attrs: `task.id`, `task.state.from`, `task.state.to`.
- `task.cancel` — attrs: `task.id`, `task.cancel.reason`, `task.cancel.via`.

When OTel is absent, spans are no-ops (D34 safe-noop). No extra peer deps required.

## Cloud rejection

`Task` is local-only in v1. CloudAgent surfaces wrapping with `{ task: true }` throw `UnsupportedTaskOperationError` (D370). Cloud support waits for TheoCloud GA.

## See also

- [ACP server](./acp-server) — the first Hermes Agent gap closed (2026-05-27).
- [Cron](./cron) — scheduled jobs; pair with `Task.submit("cron", ...)` for observability.
- [Workflows](./workflows) — declarative composition; pair with `Task.submit("workflow", ...)`.

---

# Telemetry

Source: https://docs.usetheo.dev/theokit/concepts/telemetry

OpenTelemetry spans, privacy-by-default, lazy load.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md).

The SDK emits OpenTelemetry spans for agent runs, tool calls, workflow steps, cache lookups, eval rows, and handoff transfers. Telemetry is **lazy-loaded** — if `@opentelemetry/api` isn't installed, you pay zero cost (ADR D34).

## Enable

```bash
pnpm add @opentelemetry/api
```

Plus your exporter of choice (Langfuse, Sentry, PostHog, console):

```bash
pnpm add @langfuse/otel-sdk
```

The SDK auto-detects exporters via `createRequire` feature-detect (ADR D42). No code change needed.

## Spans emitted

| Span | Where |
|---|---|
| `agent.send` | Per `agent.send()` call |
| `agent.tool_call.<toolName>` | Per tool invocation |
| `workflow.run` | Per `Workflow.run()` |
| `workflow.step.<id>` | Per workflow step (retries share kind) |
| `cache.lookup` / `cache.store` | Semantic cache hits/misses |
| `eval.run` / `eval.row.<n>` | Eval suite |
| `handoff.transfer` | Per peer handoff |
| `memory.recall` / `memory.write` | Per memory op |

## Privacy by default

Attribute values are routed through `redactSecrets` via the `wrapSpan` decorator (ADR D34 + D68). No raw API key, OAuth token, or env-var value lands in spans.

## Toggle

```bash
export THEOKIT_TELEMETRY=0  # disable entirely
export THEOKIT_REDACT_SECRETS=0  # disable redaction (NOT recommended)
```

Disabling redaction emits a one-time stderr warning (ADR D70).

## Custom tracer

For a custom tracer (e.g. your team's wrapper):

```ts
import { trace } from "@opentelemetry/api";
trace.setGlobalTracerProvider(myProvider);
// SDK picks it up via the standard OTel global tracer
```

## Telemetry namespace (SDK-internal)

The `internal/telemetry/tracer.ts` module is the canonical wrapper. All other modules (cache, eval, handoff, workflow telemetry) go through it — never call `setAttribute` directly on raw spans.

## API reference

The `Telemetry` namespace itself isn't exposed publicly — telemetry happens transparently inside agent operations. Configure via env vars + OTel ecosystem.

---

# Tools

Source: https://docs.usetheo.dev/theokit/concepts/tools

Tool.create, Zod schemas, error handling, dynamic tool dispatch.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — `Tool.create` + `Agent.create({ tools })`.

A tool is a typed function the agent can call. The SDK validates inputs against a Zod schema, surfaces errors as `tool_result isError: true` (never throws into the loop), and converts the schema to JSON Schema for the provider.

## Define a tool

```ts
import { Tool } from "@theokit/sdk";
import { z } from "zod";

const getWeather = Tool.create({
  name: "get_weather",
  description: "Look up the current weather in a given city.",
  inputSchema: z.object({
    city: z.string().describe("City name, e.g. 'Brasília'"),
  }),
  async execute({ city }) {
    return await fetch(`https://api.weather.com/${city}`).then((r) => r.text());
  },
});
```

Pass `tools: [getWeather]` to `Agent.create` and the agent decides when to call it based on the user prompt + tool description.

## Error handling

`execute` can throw — the SDK catches and converts to a `tool_result isError: true` block that the agent receives as part of the conversation. The loop continues; the agent typically retries or apologizes.

```ts
async execute({ city }) {
  if (city.length === 0) throw new Error("City is required");
  // The agent sees: { type: "tool_result", isError: true, content: "City is required" }
}
```

This is intentional — see [`docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) and ADR D89.

## Repair: malformed model output

If the model emits a malformed tool call (extra whitespace in JSON, missing trailing brace, etc.), the SDK applies 3 idempotent repairs before giving up. See ADR D87. You don't configure this — it's automatic.

## Dynamic tool dispatch (subagents / toolsets)

Agents can expose tools that aren't all available at once. The `Toolset` primitive lets you group tools and check availability per turn:

```ts
const agent = await Agent.create({
  // ...
  tools: [
    { name: "web", tools: [search, fetch] },
    { name: "shell", tools: [run, ls] },
  ],
});
```

See `docs.md` for the full Toolset / Subagent surface.

## MCP tools

Tools can also come from MCP servers (Model Context Protocol). MCP servers expose tools via stdio or HTTP and the SDK consumes them transparently. See [MCP](./mcp).

## API reference

---

# Workflows

Source: https://docs.usetheo.dev/theokit/concepts/workflows

Declarative multi-step pipelines — Workflow.create with 7 control-flow primitives.

> **Canonical contract:** [`packages/sdk/docs.md`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/docs.md) — "Workflows (v1.17+)".

`Workflow` is a declarative DSL for multi-step pipelines. Inspired by Mastra + Temporal. Use when imperative `agent.send` loops get awkward.

## Build + run

```ts
import { Workflow, Agent } from "@theokit/sdk";

const triage = Workflow
  .create({ name: "support-triage" })
  .then("fetch", async (input: { ticketId: string }) => {
    return { text: await db.getTicket(input.ticketId) };
  })
  .branch("route", [
    [(s) => s.text.includes("refund"), {
      step: { kind: "fn", id: "refund-flow", fn: async (s) => ({ result: "refund handled" }) },
    }],
    [(s) => s.text.includes("bug"), {
      step: { kind: "fn", id: "bug-flow", fn: async (s) => ({ result: "bug logged" }) },
    }],
  ])
  .commit();

const result = await Workflow.run(triage, { ticketId: "T-1234" });
console.log(result.output);
```

## 7 primitives

| Primitive | Purpose |
|---|---|
| `.then(id, fn)` | Sequential step |
| `.parallel([...], { errorPolicy })` | Run N steps concurrently |
| `.branch(id, [[pred, branch], ...])` | First-match-wins routing |
| `.foreach(id, items, fn, { concurrency })` | Map over a collection |
| `.dowhile(id, predicate, body)` | Loop until predicate false |
| `.sleep(id, ms)` | Wait |
| `.suspend(payload?)` | Pause; resume via `Workflow.resume(...)` |

## Suspend / resume

For long-running flows (human in the loop, external webhook):

```ts
const wf = Workflow.create({ name: "pr-review" })
  .then("draft", draftReview)
  .suspend()                              // ← pause here
  .then("publish", publishReview)
  .commit();

const run = await Workflow.run(wf, input);
// run.status === "suspended", run.suspendPayload visible

// Later, after the human reviews:
const finished = await Workflow.resume({
  workflowId: run.workflowId,
  runId: run.runId,
  resumeInput: { approved: true },
});
```

## Retry policies

Per-step Temporal-style retry (ADR D237):

```ts
.then("flaky", flakyApiCall, {
  retry: { maxAttempts: 3, backoffMs: 500, coef: 2 },
})
```

## Cancellation

`AbortSignal` is honored at step boundaries (ADR D245). Pass via options:

```ts
const ctrl = new AbortController();
const run = Workflow.run(wf, input, { signal: ctrl.signal });
// elsewhere: ctrl.abort();
```

## Persistence

Default: in-memory. Opt-in JSON snapshots:

```ts
Workflow.run(wf, input, {
  persistence: { backend: "json", dir: ".theokit/workflows" },
});
```

## Telemetry

OTel spans `workflow.run` + `workflow.step.<id>` via the existing telemetry seam (ADR D241).

## CloudAgent

Workflow steps throw `UnsupportedRunOperationError` on CloudAgent — local-only in v1 (ADR D244).

## API reference

---

# Advanced

Source: https://docs.usetheo.dev/theokit/context/advanced

The context discovery registry and priority, the token/byte budget with truncation, refresh-time snapshots, and reload.

# Advanced context

Verified against `@theokit/sdk` (`src/types/context.ts` + the discovery runner).

## Discovery registry

With `settingSources: ["project"]`, the file context manager scans the working directory for the
2026 industry-standard set, concatenating by **priority** (lower number wins on conflict):

| Source | Pattern | Priority | Notes |
| --- | --- | --- | --- |
| `AGENTS.md` | `AGENTS.md` | 10 | The cross-tool standard. |
| `GEMINI.md` | `GEMINI.md` | 20 | Follows `@path` import directives. |
| `CLAUDE.md` | `CLAUDE.md` | 30 | Follows `@path` import directives. |
| Cursor rules | `.cursor/rules/*.mdc` | 40 | Globbed; path-scoped via `globs:`. |
| Theokit rules | `.theokit/rules/*.md` | 45 | Globbed; path-scoped via `paths:`/`globs:`. |
| Legacy Theokit | `.theokit/context/*.md` | 50 | Backward-compatible. |
| `THEO.md` | `.theokit/THEO.md` | 60 | Theokit-native. |

`CLAUDE.md` / `GEMINI.md` may pull in additional files via `@path` import directives — those are
resolved and folded in too.

## Path-scoped rules

`.theokit/rules/*.md` (and `.cursor/rules/*.mdc`) carry frontmatter that gates activation:
`alwaysApply: true` loads every send, while `paths:` / `globs:` load only when a file in the current
send's scope matches. You declare the scope per send with `SendOptions.contextPaths`. See
[Scope rules by path](/theokit/context/scope-rules-by-path) for a runnable walkthrough.

## The budget — `ContextSettings`

```ts
context: {
  manager: "file",       // the only backend today (default)
  maxTokens: 8_000,       // hard cap on tokens emitted into the system prompt
  maxBytesPerFile: 40_000,  // per-file truncation cap in chars (default 40_000, ~10k tokens)
  maxBytesTotal: 120_000,   // aggregate cap across all files (default 120_000)
}
```

- **Per-file truncation** — a file larger than `maxBytesPerFile` is truncated to a **70% head + 20%
  tail** with a marker in between, so both the intro and the conclusion survive. Its snapshot `status`
  becomes `"summarized"`.
- **Aggregate cap** — when the total exceeds `maxBytesTotal`, **lower-priority sources are dropped**
  first (their `status` becomes `"excluded"` with a `reason`).
- **`maxTokens`** caps what reaches the system prompt regardless of byte budgets.

## Snapshots are refresh-time — `snapshot()` and `reload()`

The snapshot reflects the state at the **last refresh** — editing a context file mid-flight does not
auto-update the agent. Call **`agent.reload()`** to re-read the working directory and pick up changes,
then `snapshot()` again to confirm.

```ts
await agent.reload();                    // re-discover + re-read context files
const fresh = await agent.context?.snapshot();
```

`snapshot()` is **secret-free by design** (ADR D-context): it never contains raw secrets, local
absolute paths, or exact token counts — safe to log, persist, and diff in golden tests.

## The snapshot shape

```ts
interface ContextSnapshot {
  runtime: "local" | "cloud";
  sources: ContextSource[];      // { name, path?, status, reason? }
  budget?: { maxTokens?; usedTokens?: number | string[] };
}
```

## Reference

- [`SDKContextManager`](/theokit/reference/SDKContextManager) · [`ContextSettings`](/theokit/reference/ContextSettings) · [`ContextSnapshot`](/theokit/reference/ContextSnapshot) · [`ContextSource`](/theokit/reference/ContextSource)

---

# Overview

Source: https://docs.usetheo.dev/theokit/context

Give an agent structured file context from its working directory, and inspect exactly what it loaded with a secret-free snapshot.

# Context

Beyond the system prompt, an agent can carry **structured context** — files on disk that every run
sees without baking them into each message. Point an agent at a working directory and it discovers
context files (`AGENTS.md`, `CLAUDE.md`, `THEO.md`, `.cursor/rules/*.mdc`, `.theokit/context/*.md`),
loads them under a token budget, and folds them into the system prompt.

```ts
const agent = await Agent.create({
  apiKey, model,
  local: { cwd, settingSources: ["project"] }, // opt in to reading project files
  context: {},                                  // enable the file context manager
});

const snap = await agent.context?.snapshot();    // inspect what actually loaded
```

- **`AgentOptions.context`** (`ContextSettings`) — enable context; tune `maxTokens`, `maxBytesPerFile`,
  `maxBytesTotal`.
- **`local.settingSources: ["project"]`** — the opt-in that lets the manager read project files.
  Without it, discovery finds nothing (safe default).
- **`agent.context`** (`SDKContextManager`) — the inspector; `snapshot()` returns a secret-free
  `ContextSnapshot` of the sources it resolved and their budget status.
- **Per-tool context** — a *different* thing: a shared value (e.g. `projectRoot`) passed once on
  `send()` reaches every tool via the 2nd `ToolContext` argument (see
  [Tools › Advanced](/theokit/tools/advanced)).

## Next

- [Inspect loaded context](/theokit/context/inspect-loaded-context) — a runnable `snapshot()` example.
- [Advanced](/theokit/context/advanced) — discovery formats, the token budget, truncation, and refresh.

## Reference

- [`SDKContextManager`](/theokit/reference/SDKContextManager) · [`ContextSettings`](/theokit/reference/ContextSettings) · [`ContextSnapshot`](/theokit/reference/ContextSnapshot) · [`AgentOptions`](/theokit/reference/AgentOptions)

---

# Inspect loaded context

Source: https://docs.usetheo.dev/theokit/context/inspect-loaded-context

Enable the file context manager and read agent.context.snapshot() to see exactly which context files were loaded — deterministic, no LLM.

# Inspect loaded context

Turn on file context with `context: {}` and `settingSources: ["project"]`, then read
`agent.context.snapshot()` to see exactly what the manager resolved. Creating the agent and reading
the snapshot is a **local file read** — no network, no LLM.

```ts title="run.ts"
import { fileURLToPath } from "node:url";
import { dirname } from "node:path";
import { Agent } from "@theokit/sdk";

const here = dirname(fileURLToPath(import.meta.url)); // this dir holds AGENTS.md

const agent = await Agent.create({
  apiKey: "theo_test_context",             // fixture key — no network, no LLM
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: here, settingSources: ["project"] },
  context: {},
});

const snap = await agent.context?.snapshot();
console.log("Runtime:", snap?.runtime);

const agents = snap?.sources?.find((s) => s.name.startsWith("AGENTS.md"));
console.log("AGENTS.md status:", agents?.status ?? "not found");

await agent.dispose?.();
```

## Output

Deterministic — the example ships an `AGENTS.md` beside `run.ts`:

```text
Runtime: local
AGENTS.md status: included
```

## What it shows

- **`context: {}`** enables the file context manager; **`settingSources: ["project"]`** is the opt-in
  that lets it read project files. Omit `settingSources` and discovery finds nothing.
- **`snapshot()`** returns a `ContextSnapshot` — `runtime`, a `sources[]` list (each with `name`,
  `path?`, `status`, `reason?`), and an optional `budget`. It is **secret-free by design** — safe to
  log and persist; raw secrets, absolute paths, and exact token counts are never present.
- **`status`** is `"included"`, `"excluded"`, or `"summarized"` (trimmed to fit the token budget).

## Example

Full runnable source:
[`examples/context-inspect`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/context-inspect).

---

# Scope rules by path

Source: https://docs.usetheo.dev/theokit/context/scope-rules-by-path

Author .theokit/rules/*.md rule files that load into the agent's context only when you're working on matching files — declared per send via contextPaths. Deterministic, no LLM.

# Scope rules by path

`.theokit/rules/*.md` are theokit-native rule files, mirroring Claude Code's `.claude/rules/`. Each
file's frontmatter decides **when** the rule loads into the agent's context:

- `alwaysApply: true` — load on every send.
- `paths:` / `globs:` — load only when a file in the current send's scope matches one of the glob
  patterns. `paths:` is the Claude Code spelling; `globs:` is a Cursor-compatible alias (they are
  unioned).

You declare the in-scope files per send with `SendOptions.contextPaths` — "which files am I working
on right now". Building the agent and reading `agent.context.snapshot()` is a **local file read** —
no network, no LLM.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

// A project with two rule files under .theokit/rules/:
//   always.md  →  --- alwaysApply: true ---            (loads every send)
//   api.md     →  --- paths: [ src/api/**/*.ts ] ---   (loads only in API scope)

const agent = await Agent.create({
  apiKey: "theo_test_rules",               // fixture key — deterministic, no LLM
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd, settingSources: ["project"] },
  context: { manager: "file" },
});

// Working on an API file → the src/api/** rule activates for this send.
await (await agent.send("Add an endpoint.", { contextPaths: ["src/api/users.ts"] })).wait();
// agent.context.snapshot() → sources include rules/api.md AND rules/always.md

// Working on a UI file → the API rule stays dormant (no leak); alwaysApply remains.
await (await agent.send("Tweak the button.", { contextPaths: ["src/ui/button.tsx"] })).wait();
// agent.context.snapshot() → sources include only rules/always.md
```

## Output

Deterministic — the example writes the two rule files, then prints which rule files are active
under each scope:

```text
in scope [src/api/users.ts] -> [ 'rules/always.md', 'rules/api.md' ]
in scope [src/ui/button.tsx] -> [ 'rules/always.md' ]
OK — path-scoped rules activate by contextPaths; alwaysApply always on.
```

## What it shows

- **`paths:` / `globs:`** are glob-pattern arrays (not exact paths). Globs support `**` (any depth —
  `src/**/*.ts` matches `src/x.ts` and `src/a/b/x.ts`), `*` (a single path segment), and `?` (a
  single non-separator char).
- **`contextPaths`** is the per-send scope signal. Omit it and only `alwaysApply` rules load — the
  create-time snapshot is untouched, so agents that never scope pay nothing.
- **No leak between sends** — changing `contextPaths` on the next send re-scopes; a rule that
  matched the previous send but not this one drops out.
- The same signal also activates conditional **`.cursor/rules/*.mdc`** globs, if you keep Cursor
  rules alongside.

## Example

Full runnable source:
[`examples/rules-path-scoped`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/rules-path-scoped).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/cost/advanced

Budgets with scopes, windows, and warn/block thresholds; preflight enforcement; usage accumulation; and raw pricing lookup.

# Advanced cost

Verified against the SDK.

## Budgets — `Budget.create`

Register a budget with stacked limits over time windows, attributed to a scope:

```ts
import { Budget } from "@theokit/sdk";

const b = Budget.create({
  name: "monthly",          // grammar ^[a-z0-9][a-z0-9_-]*$ (else ConfigurationError)
  scope: /* where the charge is attributed */,
  limits: [ /* stacked warn/block limits over windows; [] ⇒ registry-only tracking */ ],
});

Budget.get("monthly");      // the handle, or undefined
Budget.list();              // all registered budgets
```

A `BudgetHandle` exposes per-window accounting — `spentIn(window)`, `remainingIn(window)`, and a
`snapshot()` — plus charging that fires the `warn` / `block` threshold callbacks.

## Preflight enforcement — `preflightCheck`

Before an expensive call, check the estimate against a budget:

```ts
import { preflightCheck } from "@theokit/sdk";

preflightCheck("monthly", estimatedUsd); // throws BudgetExceededError if the block limit would be crossed
```

Distinguish it from a post-hoc charge: `preflightCheck` blocks *before* spending; charging records
what was spent and updates thresholds. An unsupported budget operation throws
`UnsupportedBudgetOperationError`.

## Usage accounting

- **`normalizeUsage(raw)`** — canonicalize a provider's usage shape into `TokenUsage`
  (`inputTokens` / `outputTokens` / `cacheReadTokens` / `cacheWriteTokens` / `reasoningTokens` /
  `totalTokens`).
- **`UsageAccumulator`** — sum usage across many calls (a batch, a multi-turn run) into one total to
  cost once.
- **`getPricingEntry(provider, model)`** — the raw pricing row behind `computeCost`, for your own
  math or display.
- **`inferApiMode`** — resolve the API mode used for pricing.

## Subscription-included providers

Some providers are billed by subscription, not per-token — `computeCost` returns a
`subscription_included` source for those, so a flat-rate provider doesn't report a misleading
per-call USD figure.

## Reference

- [`Budget`](/theokit/reference/Budget) · [`BudgetExceededError`](/theokit/reference/BudgetExceededError) · [`CostBreakdown`](/theokit/reference/CostBreakdown) · [`UsageAccumulator`](/theokit/reference/UsageAccumulator)

---

# Estimate cost

Source: https://docs.usetheo.dev/theokit/cost/estimate-cost

Map a run's token usage to a USD CostBreakdown with computeCost — deterministic, no network.

# Estimate cost

`computeCost` turns `{ usage, provider, model }` into a `CostBreakdown` from the bundled pricing
snapshot. Pass a `RunResult.usage` straight in.

```ts title="run.ts"
import { computeCost } from "@theokit/sdk";

const cost = computeCost({
  usage: { inputTokens: 1500, outputTokens: 500 },
  provider: "openai",
  model: "gpt-4o-mini",
});

console.log("Amount USD:", cost.amountUsd);
console.log("Status:    ", cost.status);
console.log("Breakdown: ", JSON.stringify(cost.detail));
```

## Output

Deterministic — from the bundled pricing snapshot:

```text
Amount USD: 0.000525
Status:     estimated
Breakdown:  {"input":0.000225,"output":0.0003}
```

## What it shows

- **`computeCost({ usage, provider, model })`** → a `CostBreakdown` with `amountUsd`, a `status`
  (`"estimated"` from the snapshot), and per-bucket `detail` (input / output / cache / reasoning).
- **No network, no LLM** — pricing is a bundled snapshot (`source: "litellm_snapshot"`,
  `pricingVersion` stamped), so costing is instant and reproducible.
- **Unknown model** → `amountUsd: undefined` with a note, rather than a wrong number.

## Example

Full runnable source:
[`examples/cost-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/cost-basics).

---

# Overview

Source: https://docs.usetheo.dev/theokit/cost

Estimate the USD cost of token usage from a bundled pricing snapshot, and enforce per-scope budgets with warn/block thresholds.

# Cost

Two things: **estimate** what a run costs, and **enforce** a spending limit.

```ts
import { computeCost } from "@theokit/sdk";

const cost = computeCost({
  usage: { inputTokens: 1500, outputTokens: 500 },
  provider: "openai",
  model: "gpt-4o-mini",
});
cost.amountUsd; // 0.000525
```

`computeCost` maps a run's token usage to a `CostBreakdown` using a **bundled pricing snapshot** — no
network, no LLM. Every `RunResult` already carries its `usage`, so costing a run is one call.

## Estimate — `computeCost`

```ts
interface CostBreakdown {
  amountUsd: number | undefined;  // undefined when the model isn't in the snapshot
  status: CostStatus;             // e.g. "estimated"
  currency: "USD";
  source: CostSource;             // e.g. "litellm_snapshot"
  pricingVersion: string | undefined;
  detail?: { input?; output?; cacheRead?; cacheWrite?; reasoning? }; // per-bucket USD
}
```

Helpers: `normalizeUsage` (canonicalize a provider's usage shape), `getPricingEntry` (raw pricing for
a model), `inferApiMode`, and `UsageAccumulator` (sum usage across many calls).

## Enforce — `Budget`

`Budget.create({ name, scope, limits })` registers a budget with stacked `warn` / `block` limits over
time windows. `preflightCheck(name, estimatedUsd)` throws a `BudgetExceededError` before an expensive
call; charging a run updates the budget and fires threshold callbacks. See
[Advanced](/theokit/cost/advanced).

## Next

- [Estimate cost](/theokit/cost/estimate-cost) — a runnable computeCost example.
- [Advanced](/theokit/cost/advanced) — budgets, scopes, windows, and preflight enforcement.

## Reference

- [`Budget`](/theokit/reference/Budget) · [`CostBreakdown`](/theokit/reference/CostBreakdown) · [`UsageAccumulator`](/theokit/reference/UsageAccumulator)

---

# The Container

Source: https://docs.usetheo.dev/theokit/di/concepts/container

Registering providers, resolving tokens, request scopes, freezing, and dependency analysis.

The `Container` is the DI runtime. It holds a registry of providers, resolves tokens to
values (honouring scope), detects cycles, and disposes instances when it shuts down.

## Creating a container

Seed providers declaratively, or register them imperatively — both go through the same
validation path:

```ts
import { Container, Injectable } from "@theokit/di";

@Injectable()
class UserService {}

// Declarative
const container = new Container({ providers: [UserService] });

// Imperative
const c2 = new Container();
c2.register(UserService);
c2.register({ provide: "API_URL", useValue: "https://api.example.com" });
```

`register()` accepts a full `Provider` or a bare class (shorthand for
`{ provide: X, useClass: X }`). Registering the same token twice replaces the previous
registration (NestJS "last write wins") and emits a single stderr warning.

## Resolving

Use `resolve()` for synchronous graphs and `resolveAsync()` when any factory in the chain
returns a Promise:

```ts
const user = container.resolve(UserService);
const db = await container.resolveAsync<Database>("DB");
```

Calling `resolve()` on a chain that contains an async provider throws
`AsyncProviderInSyncResolveError` — switch that call to `resolveAsync()`.

## Freeze after first resolve

To prevent the subtle class of bug where a singleton is built against one set of
registrations and a different set is added later, the container **freezes on first
resolve**. Late `register()` / `registerModule()` calls throw `ContainerFrozenError`.

```ts
const container = new Container({ providers: [UserService] });
container.resolve(UserService);
container.register(OtherService); // throws ContainerFrozenError
```

Need late registration (e.g. in tests)? Opt in explicitly:

```ts
const container = new Container({ allowDynamicRegistration: true });
```

## Request scopes

`runInRequest(callback)` opens a fresh `REQUEST` scope. Every `REQUEST`-scoped provider
resolved inside the callback (or any async continuation) shares one per-request cache, and
those instances are disposed when the callback settles — even if it throws.

```ts
await container.runInRequest(async () => {
  const ctx = container.resolve(RequestContext); // one per request
  await handle(ctx);
});
```

See [Scopes](/theokit/di/concepts/scopes) for the full model.

## Analyzing the graph

`analyze()` returns a snapshot of nodes, edges, and cycles — including cycles in providers
you never resolve. Resolve-time detection only fires for paths you actually traverse, so
`analyze()` is the way to surface latent cycles proactively in a test or dev boot check.

```ts
const { nodes, edges, cycles } = container.analyze();
if (cycles.length > 0) throw new Error("DI cycle detected at boot");
```

## Disposal

`dispose()` runs `dispose()` (or `[Symbol.asyncDispose]`) on every singleton instance in
reverse construction order, then clears the cache. It is idempotent; resolving after
disposal throws `ContainerDisposedError`. The container is itself an async-disposable, so
`await using` works:

```ts
await using container = new Container({ providers: [Db] });
// container.dispose() runs automatically on scope exit
```

  Disposal keys off the `Disposable` shape (`dispose()`) or `Symbol.asyncDispose`. See
  [Lifecycle](/theokit/di/concepts/lifecycle) for how request-scoped and singleton
  instances are torn down.

---

# Errors

Source: https://docs.usetheo.dev/theokit/di/concepts/errors

The typed domain errors the container throws, and what each one means.

`@theokit/di` fails fast with typed, specific errors — never a generic string. Each one is
a distinct class you can catch and branch on.

## Resolution errors

| Error | Thrown when |
| --- | --- |
| `TokenNotFoundError` | A token has no registration (and the parameter isn't `@Optional()`). Includes the resolution path. |
| `CyclicDependencyError` | The dependency chain forms a cycle. The message renders the full `A → B → A` path. |
| `AsyncProviderInSyncResolveError` | `resolve()` hit an async provider in the chain — switch that call to `resolveAsync()`. |
| `ScopeViolationError` | A `REQUEST`-scoped provider was resolved outside an active `runInRequest(...)`. |

## Registration & configuration errors

| Error | Thrown when |
| --- | --- |
| `MissingInjectableError` | A class provider's class is not decorated with `@Injectable()`. |
| `ContainerFrozenError` | `register()` / `registerModule()` was called after the first resolve (without `allowDynamicRegistration`). |
| `ContainerDisposedError` | `resolve()` was called after `dispose()`. |
| `ReflectMetadataMissingError` | `reflect-metadata` wasn't imported before resolving a class provider. |

## Module errors

| Error | Thrown when |
| --- | --- |
| `InvalidModuleError` | A class passed to `registerModule()` isn't decorated with `@Module()`. |
| `InvalidExportError` | A module exports a token none of its providers or imports supply. |
| `CyclicModuleImportError` | The module `imports` graph contains a cycle. |

## Catching

All errors extend the built-in `Error`, so you can catch broadly or narrow by class:

```ts
import { TokenNotFoundError, CyclicDependencyError } from "@theokit/di";

try {
  container.resolve(UserService);
} catch (err) {
  if (err instanceof CyclicDependencyError) {
    // structural bug — fix the graph, don't retry
  } else if (err instanceof TokenNotFoundError) {
    // a provider is missing from the registry
  }
  throw err;
}
```

For proactive detection of cycles before they're hit at runtime, use
[`container.analyze()`](/theokit/di/concepts/container#analyzing-the-graph).

---

# Injectable & Inject

Source: https://docs.usetheo.dev/theokit/di/concepts/injectable-inject

Marking classes DI-managed, overriding tokens, and optional dependencies.

## @Injectable

Marks a class as DI-managed and, optionally, sets its scope. A class provider **must** be
`@Injectable()` — the container rejects an undecorated class at registration with
`MissingInjectableError`.

```ts
@Injectable()
class UserService {
  constructor(private readonly db: DbConnection) {}
}

@Injectable({ scope: Scope.REQUEST })
class RequestLogger {}
```

Constructor parameters typed as classes auto-resolve by their class token — the container
reads them from the `emitDecoratorMetadata` output via `reflect-metadata`.

## @Inject

Class tokens cover class-typed parameters. For anything **without** a class token — a
string token, or an interface (TypeScript emits `Object` for interfaces) — annotate the
parameter with `@Inject` to name the token explicitly.

```ts
@Injectable()
class GreeterService {
  constructor(
    @Inject("DATABASE_URL") private readonly dbUrl: string,
    @Inject("Logger") private readonly logger: Logger, // interface → string token
  ) {}
}
```

  A primitive or interface parameter **without** `@Inject` cannot be auto-resolved — the
  container throws a `TypeError` explaining that primitives and interfaces need an explicit
  token. Mark it `@Optional()` if it may legitimately be absent.

## @Optional

Marks a constructor parameter optional. If its dependency is not registered, the parameter
receives `undefined` instead of throwing `TokenNotFoundError`.

```ts
@Injectable()
class GreeterService {
  constructor(@Optional() private readonly logger?: Logger) {}
}
```

`@Optional()` only swallows `TokenNotFoundError`. Other failures — a factory that throws, a
cyclic dependency — still propagate, so a genuinely broken optional dependency never fails
silently.

---

# Lifecycle & disposal

Source: https://docs.usetheo.dev/theokit/di/concepts/lifecycle

Tearing down instances with dispose() and Symbol.asyncDispose, and the status of @PostConstruct / @PreDestroy.

## Disposal (works today)

The container tracks any instance that implements the `Disposable` shape — a `dispose()`
method — or Node's `[Symbol.asyncDispose]`. When the container (or a request scope) ends,
those instances are torn down in **reverse construction order**, so dependents are disposed
before the dependencies they rely on.

```ts
@Injectable()
class DbConnection {
  async dispose() {
    await this.pool.end();
  }
}

await using container = new Container({ providers: [DbConnection] });
container.resolve(DbConnection);
// on scope exit: container.dispose() → DbConnection.dispose() awaited
```

- **Singletons** are disposed on `container.dispose()`.
- **Request-scoped** instances are disposed when their `runInRequest(...)` callback settles
  — even if it throws.
- Disposal is idempotent; if several instances throw while disposing, the errors are
  collected and re-thrown as an `AggregateError` rather than silently dropped.

```ts
await container.runInRequest(async () => {
  container.resolve(RequestScopedResource); // disposed when this callback returns
});
```

## @PostConstruct & @PreDestroy

These decorators mark a method to run after construction (`@PostConstruct`) or before
teardown (`@PreDestroy`):

```ts
@Injectable()
class CacheService {
  @PostConstruct
  async init() {
    this.cache = await loadCacheFromRedis();
  }

  @PreDestroy
  async close() {
    await this.flush();
  }
}
```

  **v1 status — declared, not yet invoked by the resolver.** In the current release these
  decorators record their metadata but the container does **not** call the marked methods
  automatically. For teardown today, implement `dispose()` (or `[Symbol.asyncDispose]`) —
  that path is fully wired. For async initialization, use an async `useFactory` that
  performs setup before returning the instance:

  ```ts
  {
    provide: CacheService,
    useFactory: async () => {
      const svc = new CacheService();
      await svc.init();
      return svc;
    },
  }
  ```

  Adopt `@PostConstruct` / `@PreDestroy` to express intent; move off the workaround once
  resolver support lands.

---

# Modules

Source: https://docs.usetheo.dev/theokit/di/concepts/modules

Group providers, import other modules, and control visibility with exports.

A `@Module` groups related providers and declares which of them are visible to modules that
import it. The module class is never instantiated — the decorator only attaches metadata
that `Container.registerModule()` reads.

```ts
import { Module, Injectable } from "@theokit/di";

@Injectable()
class LoggerService {}

@Module({
  providers: [LoggerService],
  exports: [LoggerService],
})
class LoggingModule {}

@Module({
  providers: [UserService, { provide: "DB_URL", useValue: process.env.DB_URL }],
  imports: [LoggingModule],
  exports: [UserService],
})
class AppModule {}
```

## The three fields

- **`providers`** — providers registered into the container when the module loads. Bare
  classes expand to `ClassProvider` shorthand.
- **`imports`** — other `@Module()` classes whose **exported** providers become visible to
  this module.
- **`exports`** — the subset of this module's providers made visible to modules that import
  it. A token you don't export stays private to the module.

## Loading a module

`registerModule()` walks the import graph breadth-first, registers every provider, and
validates exports:

```ts
const container = new Container();
container.registerModule(AppModule);
container.resolve(UserService);
```

  Passing a class that isn't decorated with `@Module()` throws `InvalidModuleError`.
  Exporting a token that no imported module provides throws `InvalidExportError`. A cycle in
  the module import graph throws `CyclicModuleImportError`.

## Modules vs. flat providers

For small apps, a flat `new Container({ providers: [...] })` is enough. Reach for modules
when you want **encapsulation** — keeping internal providers private and exposing a small,
deliberate surface through `exports`. This is the same mental model as NestJS modules.

---

# Providers

Source: https://docs.usetheo.dev/theokit/di/concepts/providers

The four provider types — useClass, useFactory, useValue, useExisting.

A **provider** tells the container how to materialize a value for a token. Exactly one of
`useClass`, `useFactory`, `useValue`, or `useExisting` must be set. Every provider has a
`provide` token — a class or a non-empty string.

## useClass

Instantiate a class, resolving its constructor dependencies. The class must be
`@Injectable()`. A bare class is shorthand for `{ provide: X, useClass: X }`.

```ts
{ provide: UserService, useClass: UserService }
// or just: UserService

// Swap an implementation behind an interface token:
{ provide: "PaymentGateway", useClass: StripeGateway, scope: Scope.SINGLETON }
```

## useFactory

Compute the value with a function. List its dependencies in `inject` — they are resolved
and passed as positional arguments. The factory may be async (return a Promise), in which
case consumers must use `resolveAsync`.

```ts
{
  provide: "DB",
  useFactory: (config: AppConfig) => createPool(config.databaseUrl),
  inject: [AppConfig],
  scope: Scope.SINGLETON,
}
```

  If a factory returns a Promise, the container caches the in-flight Promise so concurrent
  async resolves share one instance rather than running the factory twice.

## useValue

Provide an already-constructed value — config objects, constants, pre-built clients. Always
`SINGLETON`; no dependencies.

```ts
{ provide: "APP_NAME", useValue: "theo" }
{ provide: AppConfig, useValue: { databaseUrl: process.env.DATABASE_URL! } }
```

## useExisting

Alias one token to another. Resolving the alias resolves the target — useful for exposing
one implementation under multiple tokens.

```ts
{ provide: StripeGateway, useClass: StripeGateway }
{ provide: "PaymentGateway", useExisting: StripeGateway } // alias
```

## Summary

| Provider | Field | Async? | Scope | Deps |
| --- | --- | --- | --- | --- |
| Class | `useClass` | via async deps | configurable | constructor (metadata) |
| Factory | `useFactory` | yes | configurable | explicit `inject` list |
| Value | `useValue` | no | always SINGLETON | none |
| Existing | `useExisting` | follows target | follows target | the aliased token |

---

# Qualifiers & Primary

Source: https://docs.usetheo.dev/theokit/di/concepts/qualifiers

Declaring a default implementation and disambiguating multiple bindings.

`@Primary` and `@Qualifier` express **intent** about which implementation to pick when more
than one is available for the same abstraction.

- **`@Primary`** — a class decorator marking a provider as the default choice.
- **`@Qualifier(name)`** — a parameter decorator that narrows a dependency to a
  specifically-named binding.

```ts
@Injectable()
@Primary
class StripePayments implements PaymentGateway {}

@Injectable()
class PayPalPayments implements PaymentGateway {}

@Injectable()
class OrderService {
  constructor(@Qualifier("stripe") private payments: PaymentGateway) {}
}
```

The intended resolution priority is **`@Qualifier` > `@Primary` > error**.

  **v1 status — declared, not yet wired into resolution.** In the current release these
  decorators record their metadata (a `@Primary` flag on the class, a qualifier name per
  parameter) but the resolver does **not** yet perform multi-binding selection: the registry
  is one provider per token, last-write-wins. To choose between implementations today, use
  distinct string tokens and `@Inject`, or `useExisting` to alias a chosen default:

  ```ts
  { provide: "payments.stripe", useClass: StripePayments }
  { provide: "payments.paypal", useClass: PayPalPayments }
  { provide: "PaymentGateway", useExisting: "payments.stripe" } // the default

  @Injectable()
  class OrderService {
    constructor(@Inject("PaymentGateway") private payments: PaymentGateway) {}
  }
  ```

  Adopt `@Primary` / `@Qualifier` now to communicate intent; switch off the string-token
  workaround once resolver support lands.

---

# Scopes

Source: https://docs.usetheo.dev/theokit/di/concepts/scopes

SINGLETON, TRANSIENT, and REQUEST — the three lifecycle scopes and when to use each.

Every provider resolves under one of three scopes. Scope is set on the `@Injectable`
decorator or on the provider entry, and defaults to `SINGLETON`.

```ts
import { Scope } from "@theokit/di";

Scope.SINGLETON; // "singleton" — one instance per container (default)
Scope.TRANSIENT; // "transient" — a fresh instance every resolve
Scope.REQUEST;   // "request"   — one instance per runInRequest(...) boundary
```

## SINGLETON

One shared instance for the container's lifetime. Constructed lazily on first resolve,
cached thereafter, and disposed when the container disposes. This is the default and the
right choice for stateless services, clients, and configuration.

```ts
@Injectable() // scope defaults to SINGLETON
class MetricsClient {}
```

## TRANSIENT

A new instance on every `resolve()`. Never cached. Use for lightweight, stateful helpers
that must not be shared.

```ts
@Injectable({ scope: Scope.TRANSIENT })
class RequestId {
  readonly value = crypto.randomUUID();
}
```

## REQUEST

One instance per `runInRequest(...)` boundary, backed by Node's `AsyncLocalStorage`. Every
`REQUEST`-scoped provider resolved within the same request — across any `await` — shares a
single cache, and is disposed when the request settles.

```ts
@Injectable({ scope: Scope.REQUEST })
class RequestContext {
  user?: User;
}

await container.runInRequest(async () => {
  const a = container.resolve(RequestContext);
  const b = container.resolve(RequestContext);
  console.log(a === b); // true — same instance within the request
});
```

Resolving a `REQUEST`-scoped provider **outside** an active `runInRequest` throws
`ScopeViolationError` — this is the fail-fast guard that keeps request state from leaking
into singletons.

  `REQUEST` scope is the wedge behind per-request isolation. `@theokit/di-agent` uses it to
  give every HTTP request its own isolated `@theokit/sdk` Agent — see
  [InjectAgent](/theokit/di-agent/concepts/inject-agent).

## Choosing a scope

| Scope | Instances | Cached | Disposed | Use for |
| --- | --- | --- | --- | --- |
| `SINGLETON` | one per container | yes | on `container.dispose()` | stateless services, clients, config |
| `TRANSIENT` | one per resolve | no | not tracked | short-lived stateful helpers |
| `REQUEST` | one per request boundary | per request | on request settle | per-request context, tenant, agent |

---

# Getting started

Source: https://docs.usetheo.dev/theokit/di/getting-started

Install @theokit/di, enable decorator metadata, and resolve your first service.

## Install

```bash
pnpm add @theokit/di reflect-metadata
```

`reflect-metadata` is a peer dependency — the container reads constructor parameter types
from the metadata TypeScript emits. Import it **once**, at your app entrypoint, before any
decorated class is loaded:

```ts
import "reflect-metadata";
```

## TypeScript configuration

Both flags are required. Without them, decorator metadata is never emitted and the
container cannot auto-resolve constructor parameters.

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

  If a class has `@Injectable()` but the container reports "no constructor metadata", it
  almost always means `emitDecoratorMetadata` is off, or `reflect-metadata` was imported
  too late. Import it at the very top of your entrypoint.

## Your first service

Declare a service, group it in a module, and resolve it:

```ts
import "reflect-metadata";
import { Container, Injectable, Inject, Module } from "@theokit/di";

@Injectable()
class Clock {
  now() {
    return new Date().toISOString();
  }
}

@Injectable()
class GreeterService {
  constructor(
    private readonly clock: Clock,
    @Inject("APP_NAME") private readonly appName: string,
  ) {}

  greet(name: string) {
    return `[${this.appName} @ ${this.clock.now()}] Hello, ${name}!`;
  }
}

@Module({
  providers: [Clock, GreeterService, { provide: "APP_NAME", useValue: "theo" }],
})
class AppModule {}

const container = new Container();
container.registerModule(AppModule);

const greeter = container.resolve(GreeterService);
console.log(greeter.greet("world"));
```

`Clock` auto-resolves by its class type; the string token `"APP_NAME"` is supplied
explicitly with `@Inject` because primitives and interfaces have no class token.

## Async resolution and disposal

When a provider factory returns a Promise, resolve it with `resolveAsync`. Clean up
resources by implementing `dispose()` — the container tears instances down in reverse
construction order:

```ts
await using container = new Container({
  providers: [
    {
      provide: "DB",
      useFactory: async () => connectToDatabase(process.env.DATABASE_URL!),
    },
  ],
});

const db = await container.resolveAsync<Database>("DB");
// on scope exit, `await using` calls container.dispose()
```

## Next

---

# Overview

Source: https://docs.usetheo.dev/theokit/di

A lightweight, NestJS-flavoured IoC container for TypeScript — @theokit/di.

**`@theokit/di`** is the dependency-injection core of the Theo backend ecosystem — a
lightweight, framework-agnostic IoC container with a **NestJS-compatible API**:
`@Injectable`, `@Inject`, `@Module`, and `providers: []`. It is the foundation the
DI-driven ORM (`@theokit/orm`) and the agent-aware layer (`@theokit/di-agent`) build on,
but it stands on its own in any TypeScript backend.

  `@theokit/di` is a standalone container — no NestJS, no framework lock-in. If you know
  the NestJS decorators, you already know this API. Requires `reflect-metadata` and TypeScript
  `experimentalDecorators` + `emitDecoratorMetadata`.

## Why `@theokit/di`

- **Three lifecycle scopes.** `SINGLETON` (one per container), `TRANSIENT` (one per
  resolve), and `REQUEST` (one per `runInRequest(...)` boundary, backed by Node's
  `AsyncLocalStorage`) — the wedge that makes per-request isolation trivial.
- **Four provider types.** `useClass`, `useFactory`, `useValue`, `useExisting` — the same
  surface you reach for in NestJS.
- **Sync and async resolution.** `resolve()` for synchronous graphs, `resolveAsync()`
  when any factory returns a Promise — with a promise-lock cache so concurrent async
  resolves share one instance.
- **Fail-fast by design.** Cycle detection at resolve-time, a container that freezes after
  the first resolve, typed domain errors, and an `analyze()` helper that surfaces latent
  cycles in providers you haven't even resolved yet.
- **Disposal lifecycle.** Instances with `dispose()` (or `[Symbol.asyncDispose]`) are torn
  down in reverse construction order when the container or a request scope ends.

## Quick code

```ts
import "reflect-metadata";
import { Container, Injectable, Module } from "@theokit/di";

@Injectable()
class GreeterService {
  greet(name: string) {
    return `Hello, ${name}!`;
  }
}

@Module({ providers: [GreeterService] })
class AppModule {}

const container = new Container();
container.registerModule(AppModule);

const greeter = container.resolve(GreeterService);
console.log(greeter.greet("Theo")); // "Hello, Theo!"
```

## Navigate

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/di/llms-txt

Machine-readable ground truth of @theokit/di for LLMs — package metadata, exported symbols, container API, conventions, and the honest v1 status of metadata-only decorators. Download it or curl it directly.

`@theokit/di` ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that
gives any LLM (Claude, ChatGPT, Cursor, Copilot, a local model) the **factual
ground truth** of this package without crawling the whole site:

- Exact package name, version, license, module format, Node floor, peer deps
- The single-barrel import path and every exported symbol
- The `Container` API surface and the four provider types
- Conventions to follow (reflect-metadata once, `@Inject` for primitives, freeze-on-resolve)
- The **honest v1 status**: `@Primary` / `@Qualifier` / `@PostConstruct` / `@PreDestroy`
  are metadata-only and NOT yet wired into resolution — with the workarounds that do work
- Anti-patterns to avoid

## Download

  <Card
    title="Download llms.txt"
    description="Single self-contained Markdown file. Drop it next to your AGENTS.md / .cursorrules / CLAUDE.md and reference it from the system prompt."
    href="/theokit/di/llms.txt"
  />

## Curl it directly

```bash
# Save to your project root
curl -o theokit-di-llms.txt https://docs.usetheo.dev/theokit/di/llms.txt

# Or pipe straight into a prompt
curl -s https://docs.usetheo.dev/theokit/di/llms.txt | head -120
```

The source files always win. If a bullet in `llms.txt` disagrees with
`packages/di/src/index.ts` or the per-symbol reference on this site, the code is
correct and the file is stale — regenerate it from the barrel.

---

# AsyncProviderInSyncResolveError

Source: https://docs.usetheo.dev/theokit/di/reference/AsyncProviderInSyncResolveError

Thrown when sync `resolve()` is called on a chain that contains an

# `AsyncProviderInSyncResolveError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when sync `resolve()` is called on a chain that contains an
async provider. The user must switch to `resolveAsync()`.

## Signature

```ts
class AsyncProviderInSyncResolveError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:61`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L61)

---

# ClassConstructor

Source: https://docs.usetheo.dev/theokit/di/reference/ClassConstructor

Constructor of a class — what TypeScript emits for `class X { ... }`.

# `ClassConstructor`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Constructor of a class — what TypeScript emits for `class X { ... }`.
Used as a Class-token (per ADR D2).

## Signature

```ts
type ClassConstructor
```

## Kind

`type`

## Source

[`packages/di/src/types.ts:11`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L11)

---

# ClassProvider

Source: https://docs.usetheo.dev/theokit/di/reference/ClassProvider

_No description available._

# `ClassProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
interface ClassProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:48`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L48)

---

# Container

Source: https://docs.usetheo.dev/theokit/di/reference/Container

Lightweight DI container. See `README.md` for usage examples.

# `Container`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Lightweight DI container. See `README.md` for usage examples.

**Auditor-acknowledged size (info-level):** the 2026-06-06 architecture
audit (`/loop-architecture-review` Phase 3 principles-auditor) flagged
this class as 812 LOC (above the 500 LOC heuristic file budget) under
principle violation PV#10 (SRP / clean_function category, INFO severity).
The auditor's own description annotates it as "large but justified DI
orchestrator". The class is the Single-Point-of-Truth for DI resolution:
registry lookup, lifecycle (SINGLETON/TRANSIENT/REQUEST), `@Injectable`
metadata read, alias resolution, request-scope ALS propagation, and
dispose chain. Splitting these concerns into separate classes would
fragment cohesion and force consumers to coordinate across an internal
micro-interface that adds no testability or extensibility per
`rules/architecture.md § 3` (module cohesion) + KISS / YAGNI. ADR D422
documents an ongoing Extract-Method refactor targeting individual long
methods (not class-level split). Plan `arch-review-fixes-2026-06-06`
T11.2 documents this trade-off; audit DB row `principle_violations.id=10`
@ `packages/di/src/container.ts:87`; report at
`architecture-output/final_report.md § Findings by dimension` PV#10.

## Signature

```ts
class Container {
  [asyncDispose](...): ...
  analyze(...): ...
  dispose(...): ...
  has(...): ...
  register(...): ...
  registerModule(...): ...
  resolve(...): ...
  resolveAsync(...): ...
  runInRequest(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/container.ts:105`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/container.ts#L105)

---

# ContainerDisposedError

Source: https://docs.usetheo.dev/theokit/di/reference/ContainerDisposedError

Thrown when `container.dispose()` is called and then a subsequent

# `ContainerDisposedError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when `container.dispose()` is called and then a subsequent
`resolve()` / `resolveAsync()` is attempted.

## Signature

```ts
class ContainerDisposedError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:108`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L108)

---

# ContainerFrozenError

Source: https://docs.usetheo.dev/theokit/di/reference/ContainerFrozenError

Thrown when `register()` or `registerModule()` is called AFTER the first

# `ContainerFrozenError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when `register()` or `registerModule()` is called AFTER the first
`resolve()` has materialized a singleton. Per ADR D7 + EC-R2-5, the
container freezes after first resolve unless
`allowDynamicRegistration: true` was passed to the constructor.

## Signature

```ts
class ContainerFrozenError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:121`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L121)

---

# ContainerOptions

Source: https://docs.usetheo.dev/theokit/di/reference/ContainerOptions

Options passed to `new Container({...})`.

# `ContainerOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Options passed to `new Container({...})`.

## Signature

```ts
interface ContainerOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:88`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L88)

---

# CyclicDependencyError

Source: https://docs.usetheo.dev/theokit/di/reference/CyclicDependencyError

Thrown when a resolution chain contains a cycle (A → B → A).

# `CyclicDependencyError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when a resolution chain contains a cycle (A → B → A).
Per ADR D7: detected at resolve-time (not register-time).

v1.2 EC-R2-1: cycle check happens BEFORE cache lookup in resolveAsync
to prevent infinite Promise await deadlocks on async REQUEST-scoped
cycles.

## Signature

```ts
class CyclicDependencyError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:50`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L50)

---

# CyclicModuleImportError

Source: https://docs.usetheo.dev/theokit/di/reference/CyclicModuleImportError

Thrown when module imports form a cycle (Module A imports B, B imports A).

# `CyclicModuleImportError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when module imports form a cycle (Module A imports B, B imports A).

## Signature

```ts
class CyclicModuleImportError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/internal/module-loader.ts:48`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/internal/module-loader.ts#L48)

---

# DependencyGraph

Source: https://docs.usetheo.dev/theokit/di/reference/DependencyGraph

`analyze()` debug return shape (per ADR D7).

# `DependencyGraph`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

`analyze()` debug return shape (per ADR D7).

## Signature

```ts
interface DependencyGraph { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:116`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L116)

---

# describeToken

Source: https://docs.usetheo.dev/theokit/di/reference/describeToken

Renders a token to a human-readable string for error messages.

# `describeToken`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Renders a token to a human-readable string for error messages.
- Class tokens: `MyService`
- String tokens: `"DATABASE_URL"`
- Anything else: `<unknown token>` (defensive — should never happen)

## Signature

```ts
function describeToken(token: Token): string
```

## Kind

`function`

## Source

[`packages/di/src/errors.ts:14`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L14)

---

# Disposable

Source: https://docs.usetheo.dev/theokit/di/reference/Disposable

Anything that implements a `dispose()` method participates in lifecycle

# `Disposable`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Anything that implements a `dispose()` method participates in lifecycle
cleanup when the container or REQUEST scope ends.

## Signature

```ts
interface Disposable { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:109`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L109)

---

# ExistingProvider

Source: https://docs.usetheo.dev/theokit/di/reference/ExistingProvider

_No description available._

# `ExistingProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
interface ExistingProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:67`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L67)

---

# FactoryProvider

Source: https://docs.usetheo.dev/theokit/di/reference/FactoryProvider

_No description available._

# `FactoryProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
interface FactoryProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:54`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L54)

---

# API reference

Source: https://docs.usetheo.dev/theokit/di/reference

Every public symbol in @theokit/di, auto-generated from TypeDoc.

# API reference

This section is **auto-generated** from TypeDoc on every build. 36 symbols exported by @theokit/di.

## Classes

- [`AsyncProviderInSyncResolveError`](/theokit/di/reference/AsyncProviderInSyncResolveError) — Thrown when sync `resolve()` is called on a chain that contains an
- [`Container`](/theokit/di/reference/Container) — Lightweight DI container. See `README.md` for usage examples.
- [`ContainerDisposedError`](/theokit/di/reference/ContainerDisposedError) — Thrown when `container.dispose()` is called and then a subsequent
- [`ContainerFrozenError`](/theokit/di/reference/ContainerFrozenError) — Thrown when `register()` or `registerModule()` is called AFTER the first
- [`CyclicDependencyError`](/theokit/di/reference/CyclicDependencyError) — Thrown when a resolution chain contains a cycle (A → B → A).
- [`CyclicModuleImportError`](/theokit/di/reference/CyclicModuleImportError) — Thrown when module imports form a cycle (Module A imports B, B imports A).
- [`InvalidExportError`](/theokit/di/reference/InvalidExportError) — Thrown when a module declares an export for a token that isn't in its
- [`InvalidModuleError`](/theokit/di/reference/InvalidModuleError) — Thrown when a class is passed to `Container.registerModule()` without
- [`MissingInjectableError`](/theokit/di/reference/MissingInjectableError) — Thrown when a class is registered as a provider (via `useClass` or shorthand)
- [`ReflectMetadataMissingError`](/theokit/di/reference/ReflectMetadataMissingError) — Thrown when `reflect-metadata` is not loaded. The polyfill mutates the
- [`ScopeViolationError`](/theokit/di/reference/ScopeViolationError) — Thrown when a REQUEST-scoped provider is resolved outside of
- [`TokenNotFoundError`](/theokit/di/reference/TokenNotFoundError) — Thrown when `resolve()` / `resolveAsync()` is asked for a token that

## Constantes

- [`METADATA_KEYS`](/theokit/di/reference/METADATA_KEYS) — _no description_

## Functiones

- [`describeToken`](/theokit/di/reference/describeToken) — Renders a token to a human-readable string for error messages.
- [`Inject`](/theokit/di/reference/Inject) — Overrides the default class-token resolution for a constructor parameter.
- [`Injectable`](/theokit/di/reference/Injectable) — Marks a class as DI-managed. Without this decorator, the container
- [`Module`](/theokit/di/reference/Module) — Mark a class as a DI module. The class itself never gets instantiated —
- [`Optional`](/theokit/di/reference/Optional) — Marks a constructor parameter as optional. If the corresponding
- [`PostConstruct`](/theokit/di/reference/PostConstruct) — _no description_
- [`PreDestroy`](/theokit/di/reference/PreDestroy) — _no description_
- [`Primary`](/theokit/di/reference/Primary) — _no description_
- [`Qualifier`](/theokit/di/reference/Qualifier) — @Qualifier(name) — parameter decorator for disambiguation.

## Interfacees

- [`ClassProvider`](/theokit/di/reference/ClassProvider) — _no description_
- [`ContainerOptions`](/theokit/di/reference/ContainerOptions) — Options passed to `new Container({...})`.
- [`DependencyGraph`](/theokit/di/reference/DependencyGraph) — `analyze()` debug return shape (per ADR D7).
- [`Disposable`](/theokit/di/reference/Disposable) — Anything that implements a `dispose()` method participates in lifecycle
- [`ExistingProvider`](/theokit/di/reference/ExistingProvider) — _no description_
- [`FactoryProvider`](/theokit/di/reference/FactoryProvider) — _no description_
- [`InjectableOptions`](/theokit/di/reference/InjectableOptions) — Options accepted by `@Injectable({...})`.
- [`ModuleMetadata`](/theokit/di/reference/ModuleMetadata) — Module declaration shape accepted by `@Module({...})`.
- [`ResolutionContext`](/theokit/di/reference/ResolutionContext) — Resolution context passed to factories. Mostly internal but exposed so
- [`ValueProvider`](/theokit/di/reference/ValueProvider) — _no description_

## Typees

- [`ClassConstructor`](/theokit/di/reference/ClassConstructor) — Constructor of a class — what TypeScript emits for `class X { ... }`.
- [`Provider`](/theokit/di/reference/Provider) — Tells the container HOW to materialize a value for a token.
- [`Scope`](/theokit/di/reference/Scope) — Lifecycle scope (per ADR D5). The container honors three modes:
- [`Token`](/theokit/di/reference/Token) — Token: anything that identifies a dependency in the container.

---

# Inject

Source: https://docs.usetheo.dev/theokit/di/reference/Inject

Overrides the default class-token resolution for a constructor parameter.

# `Inject`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Overrides the default class-token resolution for a constructor parameter.
Required when the parameter type is an interface (TS emits `Object`) or
a string token (e.g., `'DATABASE_URL'`).

## Signature

```ts
function Inject(token: Token): ParameterDecorator
```

## Kind

`function`

## Example

```ts
class GreeterService {
    constructor(
      @Inject('DATABASE_URL') readonly dbUrl: string,
      @Inject(LoggerInterface) readonly logger: LoggerInterface,
    ) {}
  }
```

## Source

[`packages/di/src/decorators/inject.ts:17`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/inject.ts#L17)

---

# Injectable

Source: https://docs.usetheo.dev/theokit/di/reference/Injectable

Marks a class as DI-managed. Without this decorator, the container

# `Injectable`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Marks a class as DI-managed. Without this decorator, the container
rejects the class at registration time (per v1.1 EC-1).

## Signature

```ts
function Injectable(options: InjectableOptions): ClassDecorator
```

## Kind

`function`

## Example

```ts
@Injectable()
  class UserService { constructor(private db: DbConnection) {} }

  @Injectable({ scope: Scope.REQUEST })
  class RequestLogger { ... }
```

## Source

[`packages/di/src/decorators/injectable.ts:22`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/injectable.ts#L22)

---

# InjectableOptions

Source: https://docs.usetheo.dev/theokit/di/reference/InjectableOptions

Options accepted by `@Injectable({...})`.

# `InjectableOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Options accepted by `@Injectable({...})`.

## Signature

```ts
interface InjectableOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/decorators/injectable.ts:7`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/injectable.ts#L7)

---

# InvalidExportError

Source: https://docs.usetheo.dev/theokit/di/reference/InvalidExportError

Thrown when a module declares an export for a token that isn't in its

# `InvalidExportError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when a module declares an export for a token that isn't in its
own `providers` (v1.1 EC-8 SHOULD TEST — pin register-time validation).

## Signature

```ts
class InvalidExportError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/internal/module-loader.ts:32`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/internal/module-loader.ts#L32)

---

# InvalidModuleError

Source: https://docs.usetheo.dev/theokit/di/reference/InvalidModuleError

Thrown when a class is passed to `Container.registerModule()` without

# `InvalidModuleError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when a class is passed to `Container.registerModule()` without
the `@Module()` decorator (v1.1 EC-4 MUST FIX).

## Signature

```ts
class InvalidModuleError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/internal/module-loader.ts:18`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/internal/module-loader.ts#L18)

---

# METADATA_KEYS

Source: https://docs.usetheo.dev/theokit/di/reference/METADATA_KEYS

_No description available._

# `METADATA_KEYS`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
const METADATA_KEYS
```

## Kind

`constant`

## Source

[`packages/di/src/internal/metadata.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/internal/metadata.ts#L9)

---

# MissingInjectableError

Source: https://docs.usetheo.dev/theokit/di/reference/MissingInjectableError

Thrown when a class is registered as a provider (via `useClass` or shorthand)

# `MissingInjectableError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when a class is registered as a provider (via `useClass` or shorthand)
but lacks the `@Injectable()` decorator. The decorator emits
`design:paramtypes` metadata that the container needs to auto-resolve
constructor parameters.

v1.1 EC-1: validateClassProvider() is called by BOTH the declarative
`providers: []` path AND the imperative `container.register()` path.

## Signature

```ts
class MissingInjectableError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:94`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L94)

---

# Module

Source: https://docs.usetheo.dev/theokit/di/reference/Module

Mark a class as a DI module. The class itself never gets instantiated —

# `Module`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Mark a class as a DI module. The class itself never gets instantiated —
the decorator just attaches metadata that `Container.registerModule()`
reads.

## Signature

```ts
function Module(metadata: ModuleMetadata): ClassDecorator
```

## Kind

`function`

## Example

```ts
@Module({
    providers: [UserService, { provide: 'DB_URL', useValue: process.env.DB }],
    imports: [LoggingModule],
    exports: [UserService],
  })
  class UserModule {}
```

## Source

[`packages/di/src/decorators/module.ts:39`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/module.ts#L39)

---

# ModuleMetadata

Source: https://docs.usetheo.dev/theokit/di/reference/ModuleMetadata

Module declaration shape accepted by `@Module({...})`.

# `ModuleMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Module declaration shape accepted by `@Module({...})`.

- `providers` — providers registered into the container when this module
  is loaded. Bare classes are expanded to ClassProvider shorthand.
- `imports` — other `@Module()` classes whose exported providers are
  visible to this module.
- `exports` — tokens from this module's `providers` that should be
  visible to outer modules that `import` this one.

## Signature

```ts
interface ModuleMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/decorators/module.ts:13`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/module.ts#L13)

---

# Optional

Source: https://docs.usetheo.dev/theokit/di/reference/Optional

Marks a constructor parameter as optional. If the corresponding

# `Optional`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Marks a constructor parameter as optional. If the corresponding
dependency is not registered, the parameter receives `undefined`
instead of throwing `TokenNotFoundError`.

`@Optional()` ONLY swallows `TokenNotFoundError` — other errors
(e.g., factory throws, cyclic dependency) propagate.

## Signature

```ts
function Optional(): ParameterDecorator
```

## Kind

`function`

## Example

```ts
class GreeterService {
    constructor(@Optional() private logger?: Logger) {}
  }
```

## Source

[`packages/di/src/decorators/optional.ts:16`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/optional.ts#L16)

---

# PostConstruct

Source: https://docs.usetheo.dev/theokit/di/reference/PostConstruct

_No description available._

# `PostConstruct`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
function PostConstruct(target: object, propertyKey: unknown): void
```

## Kind

`function`

## Example

```ts
@Injectable()
class CacheService {
  private cache!: Map<string, unknown>

  @PostConstruct
  async init() {
    this.cache = await loadCacheFromRedis()
  }
}
```

## Source

[`packages/di/src/decorators/lifecycle.ts:23`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/lifecycle.ts#L23)

---

# PreDestroy

Source: https://docs.usetheo.dev/theokit/di/reference/PreDestroy

_No description available._

# `PreDestroy`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
function PreDestroy(target: object, propertyKey: unknown): void
```

## Kind

`function`

## Example

```ts
@Injectable()
class DbConnection {
  @PreDestroy
  async close() {
    await this.pool.end()
  }
}
```

## Source

[`packages/di/src/decorators/lifecycle.ts:42`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/lifecycle.ts#L42)

---

# Primary

Source: https://docs.usetheo.dev/theokit/di/reference/Primary

_No description available._

# `Primary`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
function Primary(target: Function): void
```

## Kind

`function`

## Example

```ts
@Injectable()
@Primary
class StripePayments implements PaymentGateway { ... }

@Injectable()
class PayPalPayments implements PaymentGateway { ... }

// Without @Qualifier, StripePayments is resolved (it's @Primary)
```

## Source

[`packages/di/src/decorators/primary.ts:21`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/primary.ts#L21)

---

# Provider

Source: https://docs.usetheo.dev/theokit/di/reference/Provider

Tells the container HOW to materialize a value for a token.

# `Provider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Tells the container HOW to materialize a value for a token.
Exactly one of `useClass | useFactory | useValue | useExisting` MUST be set.

## Signature

```ts
type Provider
```

## Kind

`type`

## Source

[`packages/di/src/types.ts:42`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L42)

---

# Qualifier

Source: https://docs.usetheo.dev/theokit/di/reference/Qualifier

@Qualifier(name) — parameter decorator for disambiguation.

# `Qualifier`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

@Qualifier(name) — parameter decorator for disambiguation.

When multiple providers match the same token,

## Signature

```ts
function Qualifier(name: string): ParameterDecorator
```

## Kind

`function`

## Example

```ts
@Injectable()
class OrderService {
  constructor(@Qualifier('stripe') private payments: PaymentGateway) {}
}
```

## Source

[`packages/di/src/decorators/qualifier.ts:17`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/decorators/qualifier.ts#L17)

---

# ReflectMetadataMissingError

Source: https://docs.usetheo.dev/theokit/di/reference/ReflectMetadataMissingError

Thrown when `reflect-metadata` is not loaded. The polyfill mutates the

# `ReflectMetadataMissingError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when `reflect-metadata` is not loaded. The polyfill mutates the
global `Reflect` object; without it, the container cannot read decorator
metadata. Surfaces at first `resolve()` of a class provider — but the
Container constructor also probes proactively.

## Signature

```ts
class ReflectMetadataMissingError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:137`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L137)

---

# ResolutionContext

Source: https://docs.usetheo.dev/theokit/di/reference/ResolutionContext

Resolution context passed to factories. Mostly internal but exposed so

# `ResolutionContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Resolution context passed to factories. Mostly internal but exposed so
factories can `inject` siblings without hard-coding container references.

## Signature

```ts
interface ResolutionContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:76`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L76)

---

# Scope

Source: https://docs.usetheo.dev/theokit/di/reference/Scope

Lifecycle scope (per ADR D5). The container honors three modes:

# `Scope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Lifecycle scope (per ADR D5). The container honors three modes:

- `SINGLETON` — single instance shared across the entire container
- `TRANSIENT` — fresh instance per resolve
- `REQUEST` — single instance per `container.runInRequest(...)` boundary
  (uses Node's `AsyncLocalStorage`)

## Signature

```ts
type Scope
```

## Kind

`type`

## Source

[`packages/di/src/types.ts:30`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L30)

---

# ScopeViolationError

Source: https://docs.usetheo.dev/theokit/di/reference/ScopeViolationError

Thrown when a REQUEST-scoped provider is resolved outside of

# `ScopeViolationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when a REQUEST-scoped provider is resolved outside of
`container.runInRequest()`.

## Signature

```ts
class ScopeViolationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:75`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L75)

---

# Token

Source: https://docs.usetheo.dev/theokit/di/reference/Token

Token: anything that identifies a dependency in the container.

# `Token`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Token: anything that identifies a dependency in the container.

Per ADR D2: Class primary (auto-resolution via `reflect-metadata`),
String fallback (for primitives / interfaces). Symbol explicitly NOT
supported in v1 (deferred to v2 if real demand surfaces).

## Signature

```ts
type Token
```

## Kind

`type`

## Source

[`packages/di/src/types.ts:20`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L20)

---

# TokenNotFoundError

Source: https://docs.usetheo.dev/theokit/di/reference/TokenNotFoundError

Thrown when `resolve()` / `resolveAsync()` is asked for a token that

# `TokenNotFoundError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

Thrown when `resolve()` / `resolveAsync()` is asked for a token that
was never registered.

## Signature

```ts
class TokenNotFoundError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/di/src/errors.ts:28`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/errors.ts#L28)

---

# ValueProvider

Source: https://docs.usetheo.dev/theokit/di/reference/ValueProvider

_No description available._

# `ValueProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di` source to change this page.

_No description available._

## Signature

```ts
interface ValueProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di/src/types.ts:62`](https://github.com/usetheodev/theokit-di/blob/main/packages/di/src/types.ts#L62)

---

# Agent decorators

Source: https://docs.usetheo.dev/theokit/di-agent/concepts/decorators

The declarative capability decorators — how the annotate + read-back pattern works, and the full catalogue.

`@theokit/di-agent` ships a family of decorators that let you **declare** agent
capabilities — tools, cron schedules, retrievers, squads — directly on your classes and
methods.

## The annotate + read-back pattern

Every decorator here follows the same shape: it records its options as `reflect-metadata`
on the class, and the package exports a matching `read*Metadata()` reader.

```ts
import { Tool, readToolMetadata } from "@theokit/di-agent";

class SearchAgent {
  @Tool({ name: "web_search", description: "Search the web", inputSchema: schema })
  search(query: string) { /* ... */ }
}

// later, at wiring time:
const tools = readToolMetadata(SearchAgent); // Map<propertyKey, ToolOptions>
```

  **These decorators are declarative — they store metadata, they do not execute.** Applying
  `@Tool` does not by itself register a tool with an Agent; it records the intent. You (or a
  higher-level wiring layer) call `readToolMetadata(...)` and connect it to `@theokit/sdk`.
  The two surfaces that *do* materialize on their own are
  [`createAgentProvider`](/theokit/di-agent/concepts/inject-agent) and
  [`buildWorkflow`](/theokit/di-agent/concepts/workflow-builder).

## Catalogue

Each decorator pairs with a `read*Metadata()` reader of the same name (e.g. `@Tool` →
`readToolMetadata`).

| Decorator | Target | Key options |
| --- | --- | --- |
| `@Tool` | property | `name`, `description`, `inputSchema?` |
| `@SubAgent` | property | `name`, `description`, `instructions`, `model?`, `maxDelegationDepth?` |
| `@Squad` | property | `agents[]`, `process?` (`sequential` \| `hierarchical`), `name?` |
| `@Cron` | method | `schedule`, `timezone?` |
| `@Hitl` | method | `tools[]`, `timeoutMs?` |
| `@Retriever` | property | `topK?`, `threshold?` |
| `@Reranker` | property | `provider?`, `model?`, `topN?` |
| `@TextSplitter` | property | `strategy?`, `chunkSize?`, `overlap?` |
| `@MemoryScopeDecorator` | property | `path` |
| `@AutoSummarize` | class | `triggerFraction?`, `keepNewest?`, `model?` |
| `@Auth` | class | `providers?[]`, `sessionConfig?` |
| `@UseSandbox` | property | `backend?` (`local` \| `docker` \| …), `workDir?`, `timeoutMs?` |
| `@Subscription` | property | `name`, `transport?` |
| `@EvalDecorator` | class | `name?`, `scorers?[]`, `dataset?` |

`@Step` and `@Workflow` are covered separately in
[Workflow builder](/theokit/di-agent/concepts/workflow-builder), because they have a real
materializer (`buildWorkflow`).

## Example — a tool-carrying agent class

```ts
import { Tool, Retriever, Cron, readToolMetadata, readCronMetadata } from "@theokit/di-agent";

class SupportAgent {
  @Retriever({ topK: 5, threshold: 0.7 })
  knowledgeBase!: unknown;

  @Tool({ name: "create_ticket", description: "Open a support ticket", inputSchema: ticketSchema })
  createTicket(input: TicketInput) { /* ... */ }

  @Cron({ schedule: "0 9 * * *", timezone: "America/Sao_Paulo" })
  dailyDigest() { /* ... */ }
}

// wiring layer reads the intent back:
const tools = readToolMetadata(SupportAgent);   // Map with "createTicket"
const cron = readCronMetadata(SupportAgent);    // { schedule, timezone, methodKey }
```

---

# InjectAgent

Source: https://docs.usetheo.dev/theokit/di-agent/concepts/inject-agent

createAgentProvider, @InjectAgent, AGENT_TOKEN, and per-request Agent isolation.

The core of `@theokit/di-agent` is a small, sharp integration: register an Agent factory
under a well-known token, scoped so each request gets its own instance.

## createAgentProvider

Returns a `FactoryProvider` bound to `AGENT_TOKEN`. You supply the factory that builds an
Agent; the package supplies the scope + token wiring. The default scope is `REQUEST`.

```ts
import { createAgentProvider } from "@theokit/di-agent";
import { Agent } from "@theokit/sdk";

createAgentProvider({
  factory: () => Agent.create({ apiKey: process.env.OPENROUTER_API_KEY!, model: { id: "openai/gpt-4o-mini" } }),
});
```

```ts
interface CreateAgentProviderOptions<TAgent> {
  factory: () => TAgent | Promise<TAgent>;
  scope?: Scope; // default: Scope.REQUEST
}
```

The options are deliberately structural — the package doesn't hard-depend on the SDK's
`AgentOptions` type. Your `factory` typically wraps `Agent.create({...})`, but any producer
works.

## @InjectAgent

A parameter decorator that injects the Agent bound to `AGENT_TOKEN`. It is exactly
`@Inject(AGENT_TOKEN)` — the named decorator just documents intent at the call site.

```ts
import { Injectable } from "@theokit/di";
import { InjectAgent } from "@theokit/di-agent";

@Injectable()
class ChatController {
  constructor(@InjectAgent() private readonly agent: Agent) {}
}
```

## AGENT_TOKEN

The string token the provider and decorator share:

```ts
export const AGENT_TOKEN = "@theokit/di-agent:Agent";
```

Import it directly when you want to register a custom Agent factory (or a mock in tests)
under the same token without using `createAgentProvider`:

```ts
import { AGENT_TOKEN } from "@theokit/di-agent";

{ provide: AGENT_TOKEN, useValue: fakeAgent } // e.g. in a test module
```

## Request isolation

REQUEST scope is what makes this safe under concurrency. Within a single
`container.runInRequest(...)` boundary, every `@InjectAgent()` resolves the **same** Agent;
across two concurrent requests, they resolve **different** Agents. The Agent is disposed
when the request settles.

```ts
await container.runInRequest(async () => {
  const a = container.resolve(ChatController);
  const b = container.resolve(ChatController);
  // a.agent === b.agent within this request; a different Agent in the next request
});
```

  Resolving an `@InjectAgent()` dependency **outside** `runInRequest(...)` throws
  `ScopeViolationError` (from `@theokit/di`). For CLI/cron/single-tenant use where a shared
  Agent is fine, register it as `SINGLETON`:
  `createAgentProvider({ factory, scope: Scope.SINGLETON })`.

See [Scopes](/theokit/di/concepts/scopes) for the underlying scope model.

---

# Workflow builder

Source: https://docs.usetheo.dev/theokit/di-agent/concepts/workflow-builder

Author a workflow with @Step / @Workflow and compile it into a @theokit/sdk Workflow via buildWorkflow.

Unlike the [declarative decorators](/theokit/di-agent/concepts/decorators), `@Step` and
`@Workflow` have a real materializer: `buildWorkflow()` compiles a decorated class instance
into a runnable `@theokit/sdk` `Workflow`.

  `buildWorkflow` is the one bridge module that imports the `@theokit/sdk` peer directly
  (via `@theokit/sdk/workflow`). It composes the existing `Workflow` engine — it adds no
  orchestration of its own.

## @Step

Marks a method as a workflow step. A step receives its upstream step's return value (or the
workflow input, if it's the entry step) and returns its own output.

```ts
interface StepMetadata {
  after?: string; // method name of the upstream step; omitted = entry step
  name?: string;  // step id, defaults to the method name
}
```

## @Workflow

Marks the class as a workflow and names it. `name` is used as the compiled workflow's name;
the other fields are declarative options.

```ts
interface WorkflowOptions {
  name?: string;
  retryPolicy?: unknown;
  inputSchema?: unknown;
  outputSchema?: unknown;
}
```

## buildWorkflow

Pass an **instance** of a `@Step`-decorated class. `buildWorkflow` reads the step metadata,
topologically orders steps by their single `after` dependency into a linear chain, threads
each step's output into the next, and returns a committed `Workflow`.

```ts
import { Workflow as WorkflowDecorator, Step, buildWorkflow } from "@theokit/di-agent";

@WorkflowDecorator({ name: "onboarding" })
class OnboardingFlow {
  @Step() // entry step — receives the workflow input
  createUser(input: { email: string }) {
    return { userId: "u_123", email: input.email };
  }

  @Step({ after: "createUser" })
  sendWelcome(user: { userId: string; email: string }) {
    return { sent: true, userId: user.userId };
  }
}

const workflow = buildWorkflow(new OnboardingFlow());
// workflow is a @theokit/sdk Workflow — run it with the SDK's workflow runtime
```

## Validation (fail-fast)

`buildWorkflow` validates the step graph before building, and throws when:

- the class has **no** `@Step` methods;
- a step's `after` references an **unknown** step;
- the `after` graph contains a **cycle**.

  The MVP supports a **single upstream dependency per step** — a linear `then(...)` chain.
  Branching and fan-out remain on the imperative `@theokit/sdk` `Workflow` surface; reach
  for that directly when you need more than a linear pipeline.

---

# Getting started

Source: https://docs.usetheo.dev/theokit/di-agent/getting-started

Install @theokit/di-agent, register a REQUEST-scoped Agent, and inject it per request.

## Install

```bash
pnpm add @theokit/di-agent @theokit/di @theokit/sdk reflect-metadata
```

`@theokit/di-agent` builds on [`@theokit/di`](/theokit/di/getting-started) — the same
`reflect-metadata` import and TypeScript decorator flags apply. `@theokit/sdk` is a peer
dependency (`^1.9.0`); you provide the Agent factory, this package supplies the scope +
token wiring.

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

## Register the agent provider

`createAgentProvider()` returns a `FactoryProvider` bound to `AGENT_TOKEN`, REQUEST-scoped
by default. You pass the factory that builds a fresh Agent:

```ts
import { Agent } from "@theokit/sdk";
import { Module } from "@theokit/di";
import { createAgentProvider } from "@theokit/di-agent";

@Module({
  providers: [
    createAgentProvider({
      factory: () =>
        Agent.create({
          apiKey: process.env.OPENROUTER_API_KEY!,
          model: { id: "openai/gpt-4o-mini" },
        }),
    }),
  ],
})
class AppModule {}
```

## Inject the Agent

`@InjectAgent()` is a documented alias for `@Inject(AGENT_TOKEN)`:

```ts
import { Injectable } from "@theokit/di";
import { InjectAgent } from "@theokit/di-agent";
import type { Agent } from "@theokit/sdk";

@Injectable()
class ChatController {
  constructor(@InjectAgent() private readonly agent: Agent) {}

  async chat(message: string) {
    const run = await this.agent.send(message);
    return (await run.wait()).result;
  }
}
```

## Resolve inside a request scope

Because the Agent is REQUEST-scoped, resolve it inside `runInRequest(...)` — typically once
per HTTP request. Each request gets an isolated Agent, disposed when the request settles:

```ts
app.post("/chat", async (req, res) => {
  const answer = await container.runInRequest(async () => {
    const controller = container.resolve(ChatController);
    return controller.chat(req.body.message);
  });
  res.json({ answer });
});
```

  Need a single shared Agent (CLI, cron, single-tenant)? Override the scope:
  `createAgentProvider({ factory, scope: Scope.SINGLETON })`. A runnable Express example
  ships in the repo under `examples/di-agent-express`.

## Next

---

# Overview

Source: https://docs.usetheo.dev/theokit/di-agent

Agent-first DI — a REQUEST-scoped @theokit/sdk Agent per request, plus declarative agent decorators.

**`@theokit/di-agent`** is the agent-first integration layer for [`@theokit/di`](/theokit/di).
Its headline feature is `createAgentProvider()` + `@InjectAgent()` — a **REQUEST-scoped
`@theokit/sdk` Agent** so every HTTP request gets its own isolated agent, wired through the
container. Around that it ships a family of **declarative decorators** (`@Tool`,
`@Workflow`, `@Cron`, `@Retriever`, and more) for annotating agent capabilities on your
classes.

  `@theokit/di-agent` consumes `@theokit/sdk` as a published peer dependency (`^1.9.0`), not
  a workspace link. Decorators are an **optional DX layer** — the SDK itself no longer
  requires them (ADR D431 revoked the decorators-mandatory rule).

## The wedge: one Agent per request

```ts
import { Agent } from "@theokit/sdk";
import { Container, Module, Injectable } from "@theokit/di";
import { createAgentProvider, InjectAgent } from "@theokit/di-agent";

@Injectable()
class ChatController {
  constructor(@InjectAgent() private readonly agent: Agent) {}
  chat(message: string) {
    return this.agent.send(message);
  }
}

@Module({
  providers: [
    ChatController,
    createAgentProvider({
      factory: () =>
        Agent.create({ apiKey: process.env.OPENROUTER_API_KEY!, model: { id: "openai/gpt-4o-mini" } }),
    }),
  ],
})
class AppModule {}

// per HTTP request:
await container.runInRequest(async () => {
  const controller = container.resolve(ChatController); // fresh Agent, isolated per request
  await controller.chat("hello");
});
```

## Two kinds of surface

- **Materialized wiring (runs today).** `createAgentProvider()` produces a REQUEST-scoped
  Agent factory; `buildWorkflow()` compiles a `@Step`-decorated class into a `@theokit/sdk`
  `Workflow`. These two do real work.
- **Declarative decorators (annotation + read-back).** `@Tool`, `@Cron`, `@Retriever`,
  `@Reranker`, `@Squad`, `@Hitl`, `@Auth`, and the rest record their options as metadata and
  expose a matching `read*Metadata()` reader. They describe intent; your wiring (or a future
  materializer) reads the metadata and connects it to the SDK.

## Navigate

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/di-agent/llms-txt

Machine-readable ground truth of @theokit/di-agent for LLMs — package metadata, createAgentProvider / @InjectAgent, the full declarative decorator catalogue with read*Metadata pattern, and buildWorkflow. Download it or curl it directly.

`@theokit/di-agent` ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that
gives any LLM the **factual ground truth** of this package without crawling the site:

- Exact package name, version, license, and the three required peers (`@theokit/di`,
  `@theokit/sdk`, `reflect-metadata`)
- The REQUEST-scoped Agent wedge: `createAgentProvider`, `@InjectAgent`, `AGENT_TOKEN`
- The **full declarative decorator catalogue** (`@Tool`, `@Cron`, `@Retriever`, `@Squad`, …)
  with target, options, and the paired `read*Metadata()` reader
- The clear split between **materialized wiring** (`createAgentProvider`, `buildWorkflow`)
  and **metadata-only decorators** that you read back and wire yourself
- Anti-patterns to avoid (don't assume decorators self-wire; don't resolve outside a request)

## Download

  <Card
    title="Download llms.txt"
    description="Single self-contained Markdown file. Drop it next to your AGENTS.md / .cursorrules / CLAUDE.md and reference it from the system prompt."
    href="/theokit/di-agent/llms.txt"
  />

## Curl it directly

```bash
# Save to your project root
curl -o theokit-di-agent-llms.txt https://docs.usetheo.dev/theokit/di-agent/llms.txt

# Or pipe straight into a prompt
curl -s https://docs.usetheo.dev/theokit/di-agent/llms.txt | head -120
```

The source files always win. If a bullet in `llms.txt` disagrees with
`packages/di-agent/src/index.ts` or the per-symbol reference on this site, the code is
correct and the file is stale — regenerate it from the barrel.

---

# AGENT_TOKEN

Source: https://docs.usetheo.dev/theokit/di-agent/reference/AGENT_TOKEN

Token used by `@InjectAgent()` to look up the Agent provider. Importing

# `AGENT_TOKEN`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Token used by `@InjectAgent()` to look up the Agent provider. Importing
this directly (instead of using the decorator) lets you register a
custom factory under the same token.

## Signature

```ts
const AGENT_TOKEN
```

## Kind

`constant`

## Source

[`packages/di-agent/src/tokens.ts:6`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/tokens.ts#L6)

---

# Auth

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Auth

_No description available._

# `Auth`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Auth(options: AuthOptions): ClassDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/auth.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/auth.ts#L9)

---

# AuthOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/AuthOptions

_No description available._

# `AuthOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface AuthOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/auth.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/auth.ts#L4)

---

# AutoSummarize

Source: https://docs.usetheo.dev/theokit/di-agent/reference/AutoSummarize

_No description available._

# `AutoSummarize`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function AutoSummarize(options: AutoSummarizeOptions): ClassDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/auto-summarize.ts:16`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/auto-summarize.ts#L16)

---

# AutoSummarizeOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/AutoSummarizeOptions

_No description available._

# `AutoSummarizeOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface AutoSummarizeOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/auto-summarize.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/auto-summarize.ts#L5)

---

# buildWorkflow

Source: https://docs.usetheo.dev/theokit/di-agent/reference/buildWorkflow

Build a `Workflow` from a `@Step`-decorated instance. Validates the step

# `buildWorkflow`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Build a `Workflow` from a `@Step`-decorated instance. Validates the step
graph (fail-fast) before constructing the workflow.

## Signature

```ts
function buildWorkflow(instance: object): Workflow
```

## Kind

`function`

## Source

[`packages/di-agent/src/workflow-builder.ts:34`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/workflow-builder.ts#L34)

---

# createAgentProvider

Source: https://docs.usetheo.dev/theokit/di-agent/reference/createAgentProvider

Build a `FactoryProvider` that materializes an Agent on demand.

# `createAgentProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Build a `FactoryProvider` that materializes an Agent on demand.

## Signature

```ts
function createAgentProvider(options: CreateAgentProviderOptions): FactoryProvider
```

## Kind

`function`

## Example

```ts
import { Agent } from "@theokit/sdk";
  import { Module } from "@theokit/di";
  import { createAgentProvider } from "@theokit/di-agent";

  @Module({
    providers: [
      createAgentProvider({
        factory: () => Agent.create({ apiKey: process.env.OPENROUTER_API_KEY!, model: { id: "openai/gpt-4o-mini" } }),
      }),
    ],
  })
  class AppModule {}
```

## Source

[`packages/di-agent/src/agent-provider.ts:45`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/agent-provider.ts#L45)

---

# CreateAgentProviderOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/CreateAgentProviderOptions

Options accepted by `createAgentProvider()`. Mirrors the public

# `CreateAgentProviderOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Options accepted by `createAgentProvider()`. Mirrors the public
`AgentOptions` from `@theokit/sdk` but kept structural so this package
does not have a hard import dependency on the SDK's type tree.

The factory `async () => Agent.create(options)` is provided by the
consumer (see `createAgentProvider` below). This package supplies the
scope + token wiring.

## Signature

```ts
interface CreateAgentProviderOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/agent-provider.ts:14`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/agent-provider.ts#L14)

---

# Cron

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Cron

_No description available._

# `Cron`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Cron(options: CronOptions): MethodDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/cron.ts:13`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/cron.ts#L13)

---

# CronMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/CronMetadata

_No description available._

# `CronMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface CronMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/cron.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/cron.ts#L9)

---

# CronOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/CronOptions

_No description available._

# `CronOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface CronOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/cron.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/cron.ts#L4)

---

# EvalDecorator

Source: https://docs.usetheo.dev/theokit/di-agent/reference/EvalDecorator

_No description available._

# `EvalDecorator`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function EvalDecorator(options: EvalOptions): ClassDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/eval-decorator.ts:10`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/eval-decorator.ts#L10)

---

# EvalOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/EvalOptions

_No description available._

# `EvalOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface EvalOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/eval-decorator.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/eval-decorator.ts#L4)

---

# Hitl

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Hitl

_No description available._

# `Hitl`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Hitl(options: HitlOptions): MethodDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/hitl.ts:14`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/hitl.ts#L14)

---

# HitlMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/HitlMetadata

_No description available._

# `HitlMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface HitlMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/hitl.ts:10`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/hitl.ts#L10)

---

# HitlOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/HitlOptions

_No description available._

# `HitlOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface HitlOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/hitl.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/hitl.ts#L5)

---

# API reference

Source: https://docs.usetheo.dev/theokit/di-agent/reference

Every public symbol in @theokit/di-agent, auto-generated from TypeDoc.

# API reference

This section is **auto-generated** from TypeDoc on every build. 55 symbols exported by @theokit/di-agent.

## Constantes

- [`AGENT_TOKEN`](/theokit/di-agent/reference/AGENT_TOKEN) — Token used by `@InjectAgent()` to look up the Agent provider. Importing

## Functiones

- [`Auth`](/theokit/di-agent/reference/Auth) — _no description_
- [`AutoSummarize`](/theokit/di-agent/reference/AutoSummarize) — _no description_
- [`buildWorkflow`](/theokit/di-agent/reference/buildWorkflow) — Build a `Workflow` from a `@Step`-decorated instance. Validates the step
- [`createAgentProvider`](/theokit/di-agent/reference/createAgentProvider) — Build a `FactoryProvider` that materializes an Agent on demand.
- [`Cron`](/theokit/di-agent/reference/Cron) — _no description_
- [`EvalDecorator`](/theokit/di-agent/reference/EvalDecorator) — _no description_
- [`Hitl`](/theokit/di-agent/reference/Hitl) — _no description_
- [`InjectAgent`](/theokit/di-agent/reference/InjectAgent) — Parameter decorator — injects the REQUEST-scoped Agent into a constructor.
- [`MemoryScopeDecorator`](/theokit/di-agent/reference/MemoryScopeDecorator) — _no description_
- [`readAuthMetadata`](/theokit/di-agent/reference/readAuthMetadata) — _no description_
- [`readAutoSummarizeMetadata`](/theokit/di-agent/reference/readAutoSummarizeMetadata) — _no description_
- [`readCronMetadata`](/theokit/di-agent/reference/readCronMetadata) — _no description_
- [`readEvalDecoratorMetadata`](/theokit/di-agent/reference/readEvalDecoratorMetadata) — _no description_
- [`readHitlMetadata`](/theokit/di-agent/reference/readHitlMetadata) — _no description_
- [`readMemoryScopeMetadata`](/theokit/di-agent/reference/readMemoryScopeMetadata) — _no description_
- [`readRerankerMetadata`](/theokit/di-agent/reference/readRerankerMetadata) — _no description_
- [`readRetrieverMetadata`](/theokit/di-agent/reference/readRetrieverMetadata) — _no description_
- [`readSandboxMetadata`](/theokit/di-agent/reference/readSandboxMetadata) — _no description_
- [`readSquadMetadata`](/theokit/di-agent/reference/readSquadMetadata) — Read `@Squad()` metadata off a class constructor.
- [`readStepMetadata`](/theokit/di-agent/reference/readStepMetadata) — Read `@Step()` metadata off a class constructor (insertion-ordered).
- [`readSubAgentMetadata`](/theokit/di-agent/reference/readSubAgentMetadata) — _no description_
- [`readSubscriptionMetadata`](/theokit/di-agent/reference/readSubscriptionMetadata) — _no description_
- [`readTextSplitterMetadata`](/theokit/di-agent/reference/readTextSplitterMetadata) — _no description_
- [`readToolMetadata`](/theokit/di-agent/reference/readToolMetadata) — _no description_
- [`readWorkflowMetadata`](/theokit/di-agent/reference/readWorkflowMetadata) — _no description_
- [`Reranker`](/theokit/di-agent/reference/Reranker) — _no description_
- [`Retriever`](/theokit/di-agent/reference/Retriever) — _no description_
- [`Squad`](/theokit/di-agent/reference/Squad) — `@Squad(metadata)` — declare a sequential agent team on a property. The DI
- [`Step`](/theokit/di-agent/reference/Step) — `@Step(metadata?)` — mark a class method as a workflow step. The method
- [`SubAgent`](/theokit/di-agent/reference/SubAgent) — _no description_
- [`Subscription`](/theokit/di-agent/reference/Subscription) — _no description_
- [`TextSplitter`](/theokit/di-agent/reference/TextSplitter) — _no description_
- [`Tool`](/theokit/di-agent/reference/Tool) — _no description_
- [`UseSandbox`](/theokit/di-agent/reference/UseSandbox) — _no description_
- [`Workflow`](/theokit/di-agent/reference/Workflow) — _no description_

## Interfacees

- [`AuthOptions`](/theokit/di-agent/reference/AuthOptions) — _no description_
- [`AutoSummarizeOptions`](/theokit/di-agent/reference/AutoSummarizeOptions) — _no description_
- [`CreateAgentProviderOptions`](/theokit/di-agent/reference/CreateAgentProviderOptions) — Options accepted by `createAgentProvider()`. Mirrors the public
- [`CronMetadata`](/theokit/di-agent/reference/CronMetadata) — _no description_
- [`CronOptions`](/theokit/di-agent/reference/CronOptions) — _no description_
- [`EvalOptions`](/theokit/di-agent/reference/EvalOptions) — _no description_
- [`HitlMetadata`](/theokit/di-agent/reference/HitlMetadata) — _no description_
- [`HitlOptions`](/theokit/di-agent/reference/HitlOptions) — _no description_
- [`MemoryScopeOptions`](/theokit/di-agent/reference/MemoryScopeOptions) — _no description_
- [`RerankerOptions`](/theokit/di-agent/reference/RerankerOptions) — _no description_
- [`RetrieverOptions`](/theokit/di-agent/reference/RetrieverOptions) — _no description_
- [`SquadMetadata`](/theokit/di-agent/reference/SquadMetadata) — Metadata captured by the `@Squad()` property decorator. Declares a sequential
- [`StepMetadata`](/theokit/di-agent/reference/StepMetadata) — Metadata captured by the `@Step()` method decorator. Declares one step of a
- [`SubAgentOptions`](/theokit/di-agent/reference/SubAgentOptions) — _no description_
- [`SubscriptionOptions`](/theokit/di-agent/reference/SubscriptionOptions) — _no description_
- [`TextSplitterOptions`](/theokit/di-agent/reference/TextSplitterOptions) — _no description_
- [`ToolOptions`](/theokit/di-agent/reference/ToolOptions) — _no description_
- [`UseSandboxOptions`](/theokit/di-agent/reference/UseSandboxOptions) — _no description_
- [`WorkflowOptions`](/theokit/di-agent/reference/WorkflowOptions) — _no description_

---

# InjectAgent

Source: https://docs.usetheo.dev/theokit/di-agent/reference/InjectAgent

Parameter decorator — injects the REQUEST-scoped Agent into a constructor.

# `InjectAgent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Parameter decorator — injects the REQUEST-scoped Agent into a constructor.
Equivalent to `@Inject(AGENT_TOKEN)` but documents intent.

## Signature

```ts
function InjectAgent(): ParameterDecorator
```

## Kind

`function`

## Example

```ts
@Injectable()
  class ChatController {
    constructor(@InjectAgent() private readonly agent: Agent) {}

    async chat(message: string) {
      return this.agent.send(message);
    }
  }
```

## Source

[`packages/di-agent/src/inject-agent.ts:19`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/inject-agent.ts#L19)

---

# MemoryScopeDecorator

Source: https://docs.usetheo.dev/theokit/di-agent/reference/MemoryScopeDecorator

_No description available._

# `MemoryScopeDecorator`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function MemoryScopeDecorator(options: MemoryScopeOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/memory-scope.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/memory-scope.ts#L9)

---

# MemoryScopeOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/MemoryScopeOptions

_No description available._

# `MemoryScopeOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface MemoryScopeOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/memory-scope.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/memory-scope.ts#L5)

---

# readAuthMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readAuthMetadata

_No description available._

# `readAuthMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readAuthMetadata(target: Function): unknown
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/auth.ts:15`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/auth.ts#L15)

---

# readAutoSummarizeMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readAutoSummarizeMetadata

_No description available._

# `readAutoSummarizeMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readAutoSummarizeMetadata(target: unknown): unknown
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/auto-summarize.ts:23`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/auto-summarize.ts#L23)

---

# readCronMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readCronMetadata

_No description available._

# `readCronMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readCronMetadata(target: unknown): unknown
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/cron.ts:20`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/cron.ts#L20)

---

# readEvalDecoratorMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readEvalDecoratorMetadata

_No description available._

# `readEvalDecoratorMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readEvalDecoratorMetadata(target: Function): unknown
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/eval-decorator.ts:16`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/eval-decorator.ts#L16)

---

# readHitlMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readHitlMetadata

_No description available._

# `readHitlMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readHitlMetadata(target: unknown): unknown
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/hitl.ts:21`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/hitl.ts#L21)

---

# readMemoryScopeMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readMemoryScopeMetadata

_No description available._

# `readMemoryScopeMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readMemoryScopeMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/memory-scope.ts:18`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/memory-scope.ts#L18)

---

# readRerankerMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readRerankerMetadata

_No description available._

# `readRerankerMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readRerankerMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/reranker.ts:19`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/reranker.ts#L19)

---

# readRetrieverMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readRetrieverMetadata

_No description available._

# `readRetrieverMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readRetrieverMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/retriever.ts:18`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/retriever.ts#L18)

---

# readSandboxMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readSandboxMetadata

_No description available._

# `readSandboxMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readSandboxMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/use-sandbox.ts:20`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/use-sandbox.ts#L20)

---

# readSquadMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readSquadMetadata

Read `@Squad()` metadata off a class constructor.

# `readSquadMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Read `@Squad()` metadata off a class constructor.

## Signature

```ts
function readSquadMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/squad.ts:35`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/squad.ts#L35)

---

# readStepMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readStepMetadata

Read `@Step()` metadata off a class constructor (insertion-ordered).

# `readStepMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Read `@Step()` metadata off a class constructor (insertion-ordered).

## Signature

```ts
function readStepMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/step.ts:37`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/step.ts#L37)

---

# readSubAgentMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readSubAgentMetadata

_No description available._

# `readSubAgentMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readSubAgentMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/sub-agent.ts:22`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/sub-agent.ts#L22)

---

# readSubscriptionMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readSubscriptionMetadata

_No description available._

# `readSubscriptionMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readSubscriptionMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/subscription.ts:18`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/subscription.ts#L18)

---

# readTextSplitterMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readTextSplitterMetadata

_No description available._

# `readTextSplitterMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readTextSplitterMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/text-splitter.ts:19`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/text-splitter.ts#L19)

---

# readToolMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readToolMetadata

_No description available._

# `readToolMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readToolMetadata(target: unknown): ReadonlyMap
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/tool.ts:19`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/tool.ts#L19)

---

# readWorkflowMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/readWorkflowMetadata

_No description available._

# `readWorkflowMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function readWorkflowMetadata(target: Function): unknown
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/workflow.ts:17`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/workflow.ts#L17)

---

# Reranker

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Reranker

_No description available._

# `Reranker`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Reranker(options: RerankerOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/reranker.ts:10`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/reranker.ts#L10)

---

# RerankerOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/RerankerOptions

_No description available._

# `RerankerOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface RerankerOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/reranker.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/reranker.ts#L4)

---

# Retriever

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Retriever

_No description available._

# `Retriever`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Retriever(options: RetrieverOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/retriever.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/retriever.ts#L9)

---

# RetrieverOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/RetrieverOptions

_No description available._

# `RetrieverOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface RetrieverOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/retriever.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/retriever.ts#L4)

---

# Squad

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Squad

`@Squad(metadata)` — declare a sequential agent team on a property. The DI

# `Squad`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

`@Squad(metadata)` — declare a sequential agent team on a property. The DI
container / agent provider materializes it into a `createSquad(...)` at wiring
time.

## Signature

```ts
function Squad(metadata: SquadMetadata): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/squad.ts:25`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/squad.ts#L25)

---

# SquadMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/SquadMetadata

Metadata captured by the `@Squad()` property decorator. Declares a sequential

# `SquadMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Metadata captured by the `@Squad()` property decorator. Declares a sequential
agent team by referencing the agent property names that compose it. Mirrors
the `@theokit/sdk` `createSquad` factory (decorator mandate — every agentic
capability ships a decorator alongside the factory).

## Signature

```ts
interface SquadMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/squad.ts:11`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/squad.ts#L11)

---

# Step

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Step

`@Step(metadata?)` — mark a class method as a workflow step. The method

# `Step`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

`@Step(metadata?)` — mark a class method as a workflow step. The method
receives the upstream step's return value (or the workflow input for an
entry step) and returns this step's output.

## Signature

```ts
function Step(metadata: StepMetadata): MethodDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/step.ts:27`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/step.ts#L27)

---

# StepMetadata

Source: https://docs.usetheo.dev/theokit/di-agent/reference/StepMetadata

Metadata captured by the `@Step()` method decorator. Declares one step of a

# `StepMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

Metadata captured by the `@Step()` method decorator. Declares one step of a
decorator-driven workflow and its single upstream dependency. Compiled into
a `@theokit/sdk` `Workflow` by `buildWorkflow` (decorator mandate — every
agentic capability ships a decorator alongside the factory/builder).

## Signature

```ts
interface StepMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/step.ts:11`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/step.ts#L11)

---

# SubAgent

Source: https://docs.usetheo.dev/theokit/di-agent/reference/SubAgent

_No description available._

# `SubAgent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function SubAgent(options: SubAgentOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/sub-agent.ts:13`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/sub-agent.ts#L13)

---

# SubAgentOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/SubAgentOptions

_No description available._

# `SubAgentOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface SubAgentOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/sub-agent.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/sub-agent.ts#L5)

---

# Subscription

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Subscription

_No description available._

# `Subscription`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Subscription(options: SubscriptionOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/subscription.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/subscription.ts#L9)

---

# SubscriptionOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/SubscriptionOptions

_No description available._

# `SubscriptionOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface SubscriptionOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/subscription.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/subscription.ts#L4)

---

# TextSplitter

Source: https://docs.usetheo.dev/theokit/di-agent/reference/TextSplitter

_No description available._

# `TextSplitter`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function TextSplitter(options: TextSplitterOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/text-splitter.ts:10`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/text-splitter.ts#L10)

---

# TextSplitterOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/TextSplitterOptions

_No description available._

# `TextSplitterOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface TextSplitterOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/text-splitter.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/text-splitter.ts#L4)

---

# Tool

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Tool

_No description available._

# `Tool`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Tool(options: ToolOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/tool.ts:10`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/tool.ts#L10)

---

# ToolOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/ToolOptions

_No description available._

# `ToolOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface ToolOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/tool.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/tool.ts#L4)

---

# UseSandbox

Source: https://docs.usetheo.dev/theokit/di-agent/reference/UseSandbox

_No description available._

# `UseSandbox`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function UseSandbox(options: UseSandboxOptions): PropertyDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/use-sandbox.ts:11`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/use-sandbox.ts#L11)

---

# UseSandboxOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/UseSandboxOptions

_No description available._

# `UseSandboxOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface UseSandboxOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/use-sandbox.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/use-sandbox.ts#L5)

---

# Workflow

Source: https://docs.usetheo.dev/theokit/di-agent/reference/Workflow

_No description available._

# `Workflow`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
function Workflow(options: WorkflowOptions): ClassDecorator
```

## Kind

`function`

## Source

[`packages/di-agent/src/decorators/workflow.ts:11`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/workflow.ts#L11)

---

# WorkflowOptions

Source: https://docs.usetheo.dev/theokit/di-agent/reference/WorkflowOptions

_No description available._

# `WorkflowOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/di-agent` source to change this page.

_No description available._

## Signature

```ts
interface WorkflowOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/di-agent/src/decorators/workflow.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/di-agent/src/decorators/workflow.ts#L4)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/errors/advanced

AgentRunError's structured fields and codes, throwOnError vs the RunResult.error branch, Retry-After hints, and secret-safe raw bodies.

# Advanced errors

Verified against `@theokit/sdk` (`src/errors.ts`).

## `AgentRunError` — a run that ended in error

When a run terminates with `status: "error"`, the failure is an `AgentRunError` carrying everything you
need to route it or file a support ticket:

```ts
class AgentRunError extends TheokitAgentError {
  readonly code: AgentRunErrorCode;   // stable machine code (see below)
  readonly provider?: string;         // which provider failed
  readonly requestId?: string;        // provider x-request-id — quote in support tickets
  readonly conversationId?: string;   // the SDK conversation it was raised in
  readonly raw?: string;              // provider response body (secret-redacted at the getter)
  get retriable(): boolean;           // alias of isRetryable (handoff contract)
  get retryAfterMs(): number | undefined; // provider Retry-After hint, in ms (0 is valid — use === undefined)
}
```

### `AgentRunErrorCode`

A closed union you can `switch` on:

```
rate_limit · auth_failed · invalid_request · timeout · server_error · context_too_long ·
content_filtered · model_unavailable · network · quota_exceeded · unknown ·
tool_runtime_error · aborted · invalid_model · safety_blocked · provider_unreachable
```

```ts
catch (err) {
  if (err instanceof AgentRunError) {
    switch (err.code) {
      case "auth_failed":   return rotateKey();
      case "rate_limit":    return backoff(err.retryAfterMs);   // honor the provider hint
      case "context_too_long": return compactAndRetry();
      default:              throw err;
    }
  }
}
```

## Two ways to surface a run error — `throwOnError`

By default (`throwOnError: false`), a failed run is **data**: `RunResult.status === "error"` with a
structured `RunResult.error`. Set `throwOnError: true` (on `send` / `prompt`) and the same failure is
**thrown** as an `AgentRunError` — catch once and branch on `code`:

```ts
try {
  await Agent.prompt("hi", { apiKey, model, throwOnError: true });
} catch (err) {
  if (err instanceof AgentRunError && err.code === "auth_failed") { /* bad key */ }
}
```

Pick the style that fits: inspect `RunResult.error` inline, or `try/catch` at a boundary.

## `Retry-After` hints

`retryAfterMs` surfaces the provider's `Retry-After` header (stored in `metadata.retryAfter` as
seconds) multiplied to **milliseconds**, so it composes directly with `setTimeout` / `Date.now()`.
`0` is a legitimate value — check `=== undefined`, not truthiness.

## Secret safety

`raw` (the provider response body) is wrapped in `redactSecrets` **at the getter boundary** —
secret-shaped substrings (`sk-…`, Bearer JWTs) are stripped before they reach you, and `raw` is
**never** serialized into `.message` (anti-leak invariant). Error objects are safe to log.

## Reference

- [`TheokitAgentError`](/theokit/reference/TheokitAgentError) · [`AgentRunError`](/theokit/reference/AgentRunError) · [`RateLimitError`](/theokit/reference/RateLimitError) · [`AuthenticationError`](/theokit/reference/AuthenticationError) · [`isTransientError`](/theokit/reference/isTransientError)

---

# Catch typed errors

Source: https://docs.usetheo.dev/theokit/errors/catch-typed-errors

Every SDK error extends TheokitAgentError — inspect instanceof, isRetryable, and isTransientError to route failures. Deterministic, no LLM.

# Catch typed errors

Because every SDK error extends `TheokitAgentError`, you can branch on `instanceof` and the structured
`isRetryable` flag instead of matching strings. `isTransientError` is the SDK's own classification of
"worth retrying".

```ts title="run.ts"
import {
  TheokitAgentError,
  AuthenticationError,
  RateLimitError,
  NetworkError,
  ConfigurationError,
  isTransientError,
} from "@theokit/sdk";

const errors: TheokitAgentError[] = [
  new AuthenticationError("invalid API key"),
  new RateLimitError("429 — slow down"),
  new NetworkError("connection reset", { code: "network_error" }),
  new ConfigurationError("missing model id"),
];

for (const err of errors) {
  console.log(
    `${err.name.padEnd(20)} base=${err instanceof TheokitAgentError} ` +
      `retryable=${err.isRetryable} transient=${isTransientError(err)}`,
  );
}
```

## Output

Deterministic — the flags come from each error's own construction:

```text
AuthenticationError  base=true retryable=false transient=false
RateLimitError       base=true retryable=true transient=true
NetworkError         base=true retryable=true transient=true
ConfigurationError   base=true retryable=false transient=false
```

## What it shows

- **`instanceof TheokitAgentError`** is `true` for every SDK error — one catch clause covers them all.
- **`isRetryable`** is baked into each error at construction — `RateLimitError` / `NetworkError` are
  retryable; `AuthenticationError` / `ConfigurationError` are not (retrying a bad key never helps).
- **`isTransientError(err)`** is the SDK's transient-failure predicate — pair it with
  [`Retry.create`](/theokit/resilience/retry-a-flaky-call), which uses it as its default `isRetryable`.

## Example

Full runnable source:
[`examples/errors-catalog`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/errors-catalog).

---

# Overview

Source: https://docs.usetheo.dev/theokit/errors

One typed error hierarchy — every SDK error extends TheokitAgentError, so you catch once and branch on code, isRetryable, and instanceof.

# Errors

Every error the SDK throws extends a single base class, **`TheokitAgentError`**. That means you catch
once and branch on structured fields — never parse a message string.

```ts
import { TheokitAgentError, AuthenticationError } from "@theokit/sdk";

try {
  await agent.send("hi");
} catch (err) {
  if (err instanceof AuthenticationError) rotateKey();
  else if (err instanceof TheokitAgentError && err.isRetryable) backoffAndRetry();
  else throw err;
}
```

## The base — `TheokitAgentError`

```ts
class TheokitAgentError extends Error {
  readonly name: string;
  readonly isRetryable: boolean;   // is this worth retrying?
  readonly code?: string;          // stable machine code, e.g. "auth_failed"
  readonly protoErrorCode?: string;
  readonly metadata?: ErrorMetadata;
  // `cause` carries the underlying error when wrapping
}
```

## The hierarchy

| Error | When |
| --- | --- |
| `AuthenticationError` | Invalid API key, not logged in, insufficient permissions. |
| `RateLimitError` | Provider 429 — retryable. |
| `NetworkError` | Timeout, connection reset, transport failure — retryable. |
| `ConfigurationError` | Invalid options (bad model id, malformed config). |
| `IntegrationNotConnectedError` | A required integration isn't connected (extends `ConfigurationError`). |
| `AgentRunError` | A run terminated with `status: "error"` (carries `code`, `provider`, `requestId`). |
| `ToolError` | A tool threw during execution. |
| `BudgetExceededError` | A spending budget's block limit was crossed. |
| `AgentDisposedError` | Used an agent after `dispose()`. |
| `UnsupportedRunOperationError` | An operation the current runtime can't serve (e.g. artifacts on local). |
| `TaskNotFoundError` · `InvalidTaskIdError` · `UnsupportedTaskOperationError` | Background-task errors. |
| `MemoryAdapterError` · `CredentialPoolExhaustedError` · `UnknownAgentError` | Subsystem-specific. |

Plus the helper **`isTransientError(err)`** — the SDK's own "is this a transient failure?" predicate,
the same one [`Retry.create`](/theokit/resilience) uses by default.

## Next

- [Catch typed errors](/theokit/errors/catch-typed-errors) — a runnable example that inspects each type.
- [Advanced](/theokit/errors/advanced) — `AgentRunError` fields, `throwOnError`, and retry integration.

## Reference

- [`TheokitAgentError`](/theokit/reference/TheokitAgentError) · [`AgentRunError`](/theokit/reference/AgentRunError) · [`isTransientError`](/theokit/reference/isTransientError)

---

# Errors

Source: https://docs.usetheo.dev/theokit/errors

The typed error hierarchy.

# Errors

Every error extends `TheokitAgentError`, so you can catch broadly or narrowly. Also available at the `@theokit/sdk/errors` subpath.

| Capability | What it adds |
| --- | --- |
| `TheokitAgentError` | Base class for all SDK errors |
| Typed subclasses | `AuthenticationError` · `ConfigurationError` · `RateLimitError` · `BudgetExceededError` · … |

---

# Advanced

Source: https://docs.usetheo.dev/theokit/evals/advanced

The eval run and its aggregate, datasets from JSONL, row concurrency and cancellation, resumable persistence, custom scorers, LLM-judge, and the code-verify gate.

# Advanced evals

Verified against `@theokit/sdk/eval` (`eval.ts`, `scorers.ts`, `types/eval.ts`).

## Running — `eval.run`

```ts
const run = await evaluation.run({
  signal,                                  // cancels pending rows; in-flight rows finish
  persist: { /* durable, resumable per-row persistence */ },
  classify: (row) => row.output.length > 100 ? "verbose" : "concise", // taxonomy tag per row
});
```

`run()` returns an `EvalRun`:

```ts
interface EvalRun {
  id: string; name: string;
  startedAt: number; endedAt: number; durationMs: number;
  aggregate: EvalAggregate;               // rolled-up scores across all rows
  rows: EvalRowResult[];                   // per-row output + scores + outcome
  metadata?: Record<string, unknown>;
}
```

Per-row errors are **isolated** — one row throwing doesn't abort the run; it lands in `rows` with its
error.

## Datasets

A `Dataset` is a list of rows — `{ input, expected?, metadata? }` — or a loader. Load one from JSONL:

```ts
import { loadJsonl } from "@theokit/sdk/eval";

const dataset = await loadJsonl("./cases.jsonl"); // throws JsonlParseError on a bad line
```

## Concurrency

`Eval.create({ concurrency })` bounds how many rows run at once — default **4** (matches
`Agent.batch`). Tune it to your provider's rate limits.

## Custom scorers

A scorer is just a function — `(output, expected?) => Score | Promise<Score>`. Wrap it with a name to
show up in reports:

```ts
const startsWithHi: NamedScorer = {
  name: "starts-with-hi",
  score: (output) => ({ score: output.startsWith("Hi") ? 1 : 0 }),
};

Eval.create({ dataset, scorers: [startsWithHi], agent });
```

## LLM-as-judge — `Scorers.llmJudge`

```ts
Scorers.llmJudge({ /* rubric, model, … */ }); // an LLM grades the answer (uses the agent facade)
```

Use it when correctness is subjective (tone, helpfulness) and no string/regex rule captures it. Unlike
the string scorers, this one **calls an LLM** — budget accordingly.

## Code-verify gate — `Scorers.verifyGate`

Grades a code patch by actually running tests (SWE-bench style):

```ts
Scorers.verifyGate({
  repoDir,                    // where to run the tests
  failToPass: ["test_x"],     // tests that must flip to passing after the patch
  passToPass: ["test_y"],     // tests that must stay passing
  sandbox,                    // Local / Docker / E2B (defaults to LocalSandbox)
});
```

Pair it with `captureArtifact` to grade the working-tree diff an agent produced. See
[Sandbox](/theokit/sandbox) for the execution backends.

## Reference

- [`Eval`](/theokit/reference/Eval) · [`Scorers`](/theokit/reference/Scorers) · [`EvalRun`](/theokit/reference/EvalRun) · [`EvalOptions`](/theokit/reference/EvalOptions) · [`loadJsonl`](/theokit/reference/loadJsonl)

---

# Overview

Source: https://docs.usetheo.dev/theokit/evals

Grade agent output against a dataset with built-in and custom scorers — exact match, substring, regex, JSON shape, LLM-as-judge, and a code-verify gate.

# Evals

Run an agent over a dataset and **score** every answer. `Eval.create` pairs a dataset with an agent
and a list of scorers; `run()` grades each row with per-row error isolation.

```ts
import { Eval, Scorers } from "@theokit/sdk/eval";

const evaluation = Eval.create({
  dataset: [{ input: "Capital of France?", expected: "Paris" }],
  scorers: [Scorers.containsExpected()],
  agent: { apiKey, model },   // a fresh agent per row (state isolation)
});

const run = await evaluation.run();
```

## Built-in scorers — `Scorers`

Each returns a `NamedScorer` you drop into `scorers[]`; each is also directly callable —
`scorer.score(output, expected)` → `{ score, reason? }`.

| Scorer | Grades |
| --- | --- |
| `Scorers.exactMatch(opts?)` | Exact equality (case-sensitive by default). |
| `Scorers.containsExpected(opts?)` | Substring match (case-insensitive by default). |
| `Scorers.regex(pattern)` | Output matches a `RegExp`. |
| `Scorers.jsonShape(schema, opts?)` | Output parses and matches a Zod schema. |
| `Scorers.llmJudge(opts)` | An LLM grades the answer (uses the agent facade). |
| `Scorers.verifyGate(opts)` | Grades a code patch by running a verification command. |

## The agent, three ways

`Eval.create({ agent })` accepts an `SDKAgent` instance (shared, no isolation), an
`EvalAgentOptions` object (a fresh agent per row — the **default**, for state isolation), or a
`(entry) => SDKAgent` function for dynamic selection.

## Next

- [Score a prediction](/theokit/evals/score-a-prediction) — a runnable scorers example (deterministic).
- [Advanced](/theokit/evals/advanced) — the run, concurrency, datasets from JSONL, and custom scorers.

## Reference

- [`Eval`](/theokit/reference/Eval) · [`Scorers`](/theokit/reference/Scorers) · [`EvalOptions`](/theokit/reference/EvalOptions) · [`Score`](/theokit/reference/Score)

---

# Score a prediction

Source: https://docs.usetheo.dev/theokit/evals/score-a-prediction

Apply built-in Scorers directly to a prediction and expected answer — deterministic, no LLM. The same scorers drop into Eval.create to grade a dataset.

# Score a prediction

Every `Scorers.*` returns a `NamedScorer` whose `.score(output, expected)` is a **pure function** —
`{ score, reason? }`. You can call it directly to see exactly how a scorer grades, then hand the same
scorer to `Eval.create` to grade a whole dataset.

```ts title="run.ts"
import { Scorers } from "@theokit/sdk/eval";

const contains = Scorers.containsExpected();      // case-insensitive substring
const exact = Scorers.exactMatch();               // case-sensitive equality
const rx = Scorers.regex(/\b\d{4}\b/);            // pattern match

console.log("contains:", await contains.score("The capital is Paris.", "paris"));
console.log("exact:   ", await exact.score("Paris", "paris"));
console.log("regex:   ", await rx.score("Released in 2026", undefined));
```

## Output

Deterministic — the scorers are pure, no network:

```text
contains: { score: 1 }
exact:    { score: 0, reason: 'mismatch' }
regex:    { score: 1 }
```

## What it shows

- **`containsExpected`** is case-insensitive by default — `"The capital is Paris."` contains `"paris"`
  → `score: 1`.
- **`exactMatch`** is case-sensitive by default — `"Paris"` ≠ `"paris"` → `score: 0` with a
  `reason: "mismatch"`.
- **`regex`** grades the output alone (no `expected`) — `\b\d{4}\b` matches `"2026"` → `score: 1`.
- A `Score` is `{ score: number; reason?: string }` — `0..1`, with an optional explanation.

## Example

Full runnable source:
[`examples/eval-scorers`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/eval-scorers).

---

# Evals and scorers

Source: https://docs.usetheo.dev/theokit/evals

Measure accuracy, cost, and reliability.

# Evals and scorers

Run a dataset through your agent and score each case with built-in scorers or an LLM judge.

| Capability | What it adds |
| --- | --- |
| `Eval` (`/eval`) | Dataset-driven eval runs |
| `Scorers` | `exactMatch` · `regex` · `jsonShape` · `llmJudge` · `verifyGate` |

## Reference

See the [Evals and scorers concept](/theokit/concepts/eval) for the deep dive.

---

# File-based config

Source: https://docs.usetheo.dev/theokit/file-based

Assemble an agent's skills, subagents, hooks, MCP servers, context, and cron jobs from files under .theokit/ — discovered by a code-created agent via settingSources.

# File-based configuration

A TheoKit agent is created in code with `Agent.create(...)`. But most of what an agent
*uses* — skills, subagents, hooks, MCP servers, context, scheduled jobs — can live as
**files in your repo** under `.theokit/`. A code-created agent discovers them
automatically, so the configuration travels with git and applies to every caller that
starts the agent.

This **augments a code-created agent** — it is not a bundler that discovers and
instantiates whole agents from directories. The agent's `model` and base `systemPrompt`
are always set in `Agent.create(...)`; the files below are discovered from the filesystem
and merged in. The native session transcript (`<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`,
`baseDir` default `~/.theokit`) is runtime *state*, not an agent definition.

## Turn it on

File discovery is opt-in through `local.settingSources`:

```ts
const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd(), settingSources: ["project"] }, // read .theokit/ from cwd
});
```

- `settingSources: ["project"]` — read `.theokit/` from `local.cwd`.
- `settingSources: ["user"]` — also read `~/.theokit/` (user-level hooks and MCP servers).
- Omit `settingSources` — only inline (code) config is used; nothing is read from disk.

Call `agent.reload()` to re-read the files (context, skills, hooks, project MCP, subagents)
without disposing the agent or losing conversation state. A malformed skill or context
file raises `ConfigurationError` — it fails loudly, never silently ignored.

## What can live in files

```text
.theokit/
├── skills/<name>/SKILL.md      # capability packs (name + description + body)
├── agents/<name>.md            # subagents (one markdown file each)
├── hooks.json                  # shell-command policy hooks (Claude Code shape)
├── mcp.json                    # MCP servers
├── context/<name>.md           # context sources (task working-set)
└── cron/jobs.json              # scheduled agent runs (local scheduler)
```

Most files are **markdown + YAML frontmatter** (same shape as `SKILL.md`). The exception
is **hooks**, which use JSON in the exact Claude Code `settings.json` shape (a hook's
markdown body is inert, and Claude Code configures hooks in JSON).

### Skills — `.theokit/skills/<name>/SKILL.md`

A named capability pack. Required frontmatter `name` + `description`; optional `category`
and `dependencies`. Discovered skills are exposed to the model by name + description; read
the full body on demand.

```markdown title=".theokit/skills/release/SKILL.md"
---
name: release
description: How to cut a release — version bump, changelog, tag.
---

# Release skill

1. Consume the changeset, bump the version.
2. Move `[Unreleased]` into a dated section.
3. Open the develop→main PR; a human merges.
```

Inspect them at runtime with `agent.skills.list()` (metadata) and `agent.skills.get(name)`
(full body). See [Skills](/theokit/skills).

### Subagents — `.theokit/agents/<name>.md`

One markdown file per subagent: frontmatter carries the `description` (and optional `model`,
a `tools` whitelist, and per-subagent `mcpServers`); the body becomes the subagent prompt.
Inline definitions override a file-based subagent of the same name.

```markdown title=".theokit/agents/code-reviewer.md"
---
description: Reviews code for bugs and security issues.
model: inherit
tools: read_file, list_dir
---

You are a meticulous code reviewer. Report bugs, security issues, and unclear
naming. Do not modify files.
```

A `tools: read_file, list_dir` subagent provably cannot call `write_file` or `shell` — the
whitelist is enforced at dispatch. See [Subagents](/theokit/subagents).

### Hooks — `.theokit/hooks.json`

Shell-command policy hooks, in the exact Claude Code shape. Events map to the SDK's firing
points: `PreToolUse`→preToolUse, `PostToolUse`→postToolUse, `UserPromptSubmit`→preRun,
`Stop`→stop (unsupported Claude Code events are skipped with a warning).

```json title=".theokit/hooks.json"
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [{ "type": "command", "command": "node .theokit/policy.js", "timeout": 30 }]
      }
    ]
  }
}
```

The command receives the payload as JSON on stdin; a non-zero exit on `PreToolUse` /
`UserPromptSubmit` blocks. The old `.theokit/hooks/*.md` markdown form is no longer
supported (a stray dir warns to migrate). See [Hooks](/theokit/hooks).

### MCP servers — `.theokit/mcp.json`

Tool servers discovered from disk and merged with any inline `mcpServers`. Project servers
come from `.theokit/mcp.json` (with `settingSources: ["project"]`); user servers from
`~/.theokit/mcp.json` (with `"user"`).

```json title=".theokit/mcp.json"
{
  "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
}
```

See [MCP](/theokit/mcp).

### Context — `.theokit/context/<name>.md`

The task working-set offered to a run. With `context: { manager: "file" }` and
`settingSources: ["project"]`, the file context manager reads `.theokit/context/<name>.md`
(alongside conventional `AGENTS.md`, `CLAUDE.md`, `THEO.md`, `.cursor/rules/*.mdc`). Inspect
the redacted result with `agent.context.snapshot()`. See [Context](/theokit/context).

### Scheduled jobs — `.theokit/cron/jobs.json`

Local cron jobs are persisted here and reloaded on `Cron.start({ cwd })`; they fire while
the host process is alive. See [Schedules](/theokit/schedules).

## Local vs cloud

- **Local** — files are read from `local.cwd` (and `~/.theokit/` for user sources) when
  `settingSources` opts in.
- **Cloud** — commit the same `.theokit/` files to the repo passed in `cloud.repos`;
  SDK-created cloud agents load project skills, hooks, and subagents automatically.

## Set in code (not file-based)

These stay in `Agent.create(...)` — there is no file convention for them today:

- **`model` and base `systemPrompt`** — the agent's identity.
- **Tools** (`Tool.create`) — though MCP servers *are* file-based (above).
- **Memory, guardrails, processors, workflows** — configured in code.

## Migrating legacy config

A standalone CLI converts legacy `.theokit/context.json` and
`.theokit/plugins/<name>/plugin.json` to the markdown form (hooks migrate the other way,
back to `.theokit/hooks.json`):

```bash
npx theokit-migrate-config --apply
```

---

# Advanced

Source: https://docs.usetheo.dev/theokit/filesystem/advanced

Read-only backends, the stale-write guard, FileStat, custom backends, and per-request multi-tenant filesystem providers.

# Advanced filesystem

Verified against `@theokit/sdk/filesystem` (ADR 0011).

## Read-only backends

```ts
const ro = new LocalFilesystem({ basePath: "./data", readOnly: true });
await ro.readFile("report.md");   // fine
await ro.writeFile("x", "y");     // throws FilesystemReadOnlyError
```

A read-only backend rejects **every** write. Note the ordering: a traversal path on a read-only backend
reports the **security** error first (fail-clear) — the boundary check runs before the read-only check.

## Stale-write guard — `expectedMtime`

Optimistic concurrency for writes: pass the `mtime` you last read, and the write fails if the file
changed underneath you.

```ts
const stat = await fs.stat("notes.txt");
await fs.writeFile("notes.txt", "new content", { expectedMtime: stat.mtimeMs });
// throws StaleFileError if the file was modified since you read `stat`
```

`StaleFileError` carries `expectedMtime` and `actualMtime` so you can surface a precise conflict.

## `FileStat`

```ts
interface FileStat {
  size: number;
  mtimeMs: number;
  isFile: boolean;
  isDirectory: boolean;
}
```

Returned by `writeFile` and `stat`. `mtimeMs` feeds the stale-write guard above.

## Custom backends — `FilesystemBackend`

Implement the four abstract methods and you have an S3 / GCS / in-memory backend that composes exactly
like `LocalFilesystem`:

```ts
import { FilesystemBackend } from "@theokit/sdk/filesystem";

class InMemoryFs extends FilesystemBackend {
  async readFile(path) { /* … */ }
  async writeFile(path, content, opts) { /* … */ }
  async stat(path) { /* … */ }
  async list(path) { /* … */ }
}
```

`exists()` and the `readOnly` / `basePath` accessors derive on the base class — you only write the four.

## Multi-tenant roots — `FilesystemProvider` + `resolveFilesystem`

A `FilesystemProvider` is either a backend instance or a **factory of `(ctx) => backend`** — so a
multi-tenant app can hand each request its own boundary root:

```ts
import { resolveFilesystem, LocalFilesystem } from "@theokit/sdk/filesystem";

const provider = (ctx: { tenantId: string }) =>
  new LocalFilesystem({ basePath: `./tenants/${ctx.tenantId}` });

const fs = await resolveFilesystem(provider, { tenantId: "acme" }); // concrete backend for this request
```

`resolveFilesystem(provider, ctx)` returns the backend directly if `provider` is already an instance,
or calls the factory with `ctx` — the seam for per-request isolation.

## Reference

- [`LocalFilesystem`](/theokit/reference/LocalFilesystem) · [`FilesystemBackend`](/theokit/reference/FilesystemBackend) · [`FilesystemProvider`](/theokit/reference/FilesystemProvider) · [`resolveFilesystem`](/theokit/reference/resolveFilesystem) · [`StaleFileError`](/theokit/reference/StaleFileError)

---

# Enforce a storage boundary

Source: https://docs.usetheo.dev/theokit/filesystem/enforce-a-storage-boundary

Write, read, and list inside a LocalFilesystem root, and watch a path-traversal escape get rejected with a typed error — deterministic, no LLM.

# Enforce a storage boundary

`LocalFilesystem` resolves every path inside its `basePath`. Reads and writes within the boundary work
normally; anything that tries to escape it (`../`, absolute paths, symlink escape) is rejected with a
`FilesystemSecurityError`. It's all local file I/O — deterministic, no LLM.

```ts title="run.ts"
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";
import { LocalFilesystem, FilesystemSecurityError } from "@theokit/sdk/filesystem";

const here = dirname(fileURLToPath(import.meta.url));
const fs = new LocalFilesystem({ basePath: join(here, "root") });

const stat = await fs.writeFile("notes.txt", "ship it");
console.log("wrote notes.txt, size:", stat.size);

console.log("readFile:", await fs.readFile("notes.txt"));
console.log("list:    ", (await fs.list(".")).sort().join(", "));

try {
  await fs.readFile("../run.ts");            // escape the boundary
} catch (err) {
  console.log("traversal blocked:", err instanceof FilesystemSecurityError);
}
```

## Output

Deterministic — the boundary rejects the traversal every time:

```text
wrote notes.txt, size: 7
readFile: ship it
list:     .gitkeep, notes.txt
traversal blocked: true
```

## What it shows

- **`writeFile` returns a `FileStat`** (`size`, `mtimeMs`, `isFile`, `isDirectory`) — the 7 bytes of
  `"ship it"`.
- **`readFile` / `list`** operate relative to `basePath` — clean, root-relative paths.
- **`../run.ts` is rejected** — the resolver catches lexical traversal before touching the disk and
  throws a typed `FilesystemSecurityError`, so a malicious tool call can't read outside the root.

## Example

Full runnable source:
[`examples/filesystem-boundary`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/filesystem-boundary).

---

# Overview

Source: https://docs.usetheo.dev/theokit/filesystem

A boundary-enforced, swappable storage backend for agent file tools — every path resolves within a root, escapes are rejected, and read-only is one flag.

# Filesystem

`@theokit/sdk/filesystem` gives agent file tools a **boundary-enforced** storage root. Every path is
resolved within `basePath`; lexical traversal (`..`, absolute paths, NUL) and symlink escape are
rejected with a typed `FilesystemSecurityError`.

```ts
import { LocalFilesystem } from "@theokit/sdk/filesystem";

const fs = new LocalFilesystem({ basePath: "./workspace", readOnly: false });

await fs.writeFile("notes.txt", "ship it");
await fs.readFile("notes.txt");   // "ship it"
await fs.list(".");                // ["notes.txt"]
```

## The backend

`LocalFilesystem` implements four methods — `readFile`, `writeFile`, `stat`, `list` — plus a derived
`exists()`. It extends the abstract **`FilesystemBackend`**, so you can swap in your own (S3, GCS,
in-memory) by implementing the same four methods; the boundary and `readOnly` accessors derive on the
base class.

This is a **path boundary**, not an OS isolation boundary (same user, same machine). It stops traversal
and symlink escape; for untrusted code, still run it inside a container or VM sandbox — see
[Sandbox](/theokit/sandbox).

## Typed errors

| Error | When |
| --- | --- |
| `FilesystemSecurityError` | Path escapes the boundary (`..`, absolute, symlink escape). |
| `FilesystemReadOnlyError` | A write on a `readOnly: true` backend. |
| `FileNotFoundError` | Read/stat of a missing path. |
| `StaleFileError` | A write whose `expectedMtime` no longer matches (stale-write guard). |

## Next

- [Enforce a storage boundary](/theokit/filesystem/enforce-a-storage-boundary) — a runnable example.
- [Advanced](/theokit/filesystem/advanced) — read-only, the stale-write guard, custom backends, and
  per-request multi-tenant providers.

## Reference

- [`LocalFilesystem`](/theokit/reference/LocalFilesystem) · [`FilesystemBackend`](/theokit/reference/FilesystemBackend) · [`FilesystemConfig`](/theokit/reference/FilesystemConfig) · [`FileStat`](/theokit/reference/FileStat)

---

# Require read-before-write

Source: https://docs.usetheo.dev/theokit/filesystem/read-before-write

Refuse blind or stale overwrites — make the write tool require a prior read, and reject a write whose file changed since, with a typed StaleFileError.

# Require read-before-write

A coding agent that overwrites a file it never read (or read a stale copy of) silently clobbers work. SE32 adds an opt-in safety: the write tool refuses to write unless the same file was read first, and refuses if the file changed on disk since that read.

## Wire it up (tool layer)

Give the read and write tools a shared `ReadTracker` and turn on `requireReadBeforeWrite`:

```ts
import { createReadFileTool, createWriteFileTool, ReadTracker } from "@theokit/sdk-tools";

const tracker = new ReadTracker();
const readTool  = createReadFileTool({ projectRoot, readTracker: tracker });
const writeTool = createWriteFileTool({ projectRoot, readTracker: tracker, requireReadBeforeWrite: true });
```

Now the agent's writes behave like this:

| Situation | Result |
| --- | --- |
| File was read, unchanged since | write proceeds |
| File was **never read** | `{ ok: false, error: "read_required" }` |
| File **changed on disk** since it was read | `{ ok: false, error: "stale_file" }` |
| Brand-new file (does not exist) | write proceeds (nothing to clobber) |

Default is **off** — omit `requireReadBeforeWrite` and writes behave exactly as before (back-compat). Turning it on without a `readTracker` fails fast at construction, so you can't half-configure it.

## The backend guard (`expectedMtime` / `StaleFileError`)

Underneath, `@theokit/sdk/filesystem` enforces the same optimistic-concurrency check at the actual write. Pass `expectedMtime` and the write throws a typed `StaleFileError` — carrying `expectedMtime` and `actualMtime` — if the file moved under you, instead of clobbering it:

```ts
import { LocalFilesystem, StaleFileError } from "@theokit/sdk/filesystem";

const fs = new LocalFilesystem({ basePath: root });
const before = await fs.stat("doc.txt");
try {
  await fs.writeFile("doc.txt", next, { expectedMtime: before.mtimeMs });
} catch (err) {
  if (err instanceof StaleFileError) {
    // someone edited doc.txt since we read it — re-read and reconcile
  }
}
```

The tool-layer flag and the backend `expectedMtime` compose: the write tool forwards the tracked mtime as `expectedMtime` so the backend re-checks at write time (closing the read→write TOCTOU window a same-user stat cannot).

## Reference

- `ReadTracker` / `createWriteFileTool` (from `@theokit/sdk-tools`) · [`StaleFileError`](/theokit/reference/StaleFileError) · [`LocalFilesystem`](/theokit/reference/LocalFilesystem)

---

# Filesystem

Source: https://docs.usetheo.dev/theokit/filesystem

A pluggable, boundary-enforced filesystem.

# Filesystem

A filesystem provider seam — the storage-side twin of the sandbox — with enforced boundaries and read-only roots.

| Capability | What it adds |
| --- | --- |
| `LocalFilesystem` (`/filesystem`) | Boundary-enforced local FS |
| `resolveFilesystem` | Per-request provider resolution |

---

# @theokit/gateway

Source: https://docs.usetheo.dev/theokit/gateways/core

The transport-agnostic core — BasePlatformAdapter, GatewayRunner, SessionRouter, DeliveryRouter, the hook chain, the MessageEvent union, and the shared chunk/error primitives every adapter builds on.

`@theokit/gateway` is the transport-agnostic core of the gateway cluster. It defines the
contract every adapter implements and the orchestration that turns inbound platform
messages into agent replies — while **composing, not reimplementing**: session
persistence stays in `@theokit/sdk`, scheduling in `Cron`, prompt resolution in the
SDK's resolver. Adapters live in separate peer-dependency packages; the core imports
none of them.

## Install

```bash
pnpm add @theokit/gateway @theokit/sdk
# Plus one or more transport adapters:
pnpm add @theokit/gateway-telegram grammy
```

## Architecture (five pieces)

| Module | Responsibility |
|---|---|
| `BasePlatformAdapter` | The contract every adapter implements: `connect`, `disconnect`, `sendMessage`, `onInbound` (plus optional `startTyping`/`stopTyping`). Idempotent lifecycle; never throws on a platform error — returns a typed `SendResult`. |
| `GatewayRunner` | Orchestrator: holds the adapter map, runs the hook chain, dispatches each inbound `MessageEvent` to your handler, and auto-routes `ctx.reply` by `event.platform`. Drains in-flight replies on `stop()`. |
| `SessionRouter` | Pure `MessageEvent → agentId` strategy (composes `Agent.resume`, ADR D174). Swap the strategy for custom session keys. |
| `DeliveryRouter` | Dispatches outbound messages by platform (composes `Cron` for scheduled delivery, ADR D175). |
| `HookExecutor` | Runs the `pre_inbound` / `post_outbound` / `on_error` chain — the gateway's own extension contract (ADR D176), lives in `hooks/executor.ts`. |

## Minimal example

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { TelegramAdapter } from '@theokit/gateway-telegram'

const router = new SessionRouter()
const adapter = new TelegramAdapter({ token: process.env.TELEGRAM_BOT_TOKEN! })

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

## The `MessageEvent` union

Every adapter emits the same portable shape — a discriminated union keyed by `platform`
with a `BaseMessageEvent` (id, sender, channel, text, `receivedAt`, optional `replyTo`)
plus a platform-specific sibling field (`telegram?`, `discord?`, …) carrying the raw
payload as an escape hatch. Narrowing is exhaustive:

```ts
switch (event.platform) {
  case 'telegram': return event.telegram.threadId // narrowed
  case 'discord':  return event.discord.guildId   // narrowed
}
```

  The union is intentionally **closed** — all ten platform variants are declared in the
  core so consumer `switch`es are compiler-checked for exhaustiveness. Adding an
  eleventh platform is a bounded edit to the core union, by design (see
  `docs/adr/0001-message-event-closed-union.md`).

## Hooks

Three fire points let you gate, observe, and recover around the handler without touching
it. `pre_inbound` runs sequentially — the first `{ block: true }` short-circuits (and
its `message`, if set, is replied before the handler is skipped); a throwing hook is
treated fail-safe as a block. `post_outbound` and `on_error` are fire-and-forget.

```ts
const hook = {
  name: 'audit',
  pre_inbound: async ({ event }) => { /* return { block: true } to stop */ },
  post_outbound: async ({ event, outbound, result }) => { /* log delivery */ },
  on_error: async ({ event, error }) => { /* report */ },
}
```

## Shared text + error primitives

The core single-sources the message-splitting and configuration-error knowledge the
adapters used to copy:

- **`chunkText(text, options)`** — boundary-preferring chunker (prefers `\n\n` → `\n` →
  space, optional UTF-16 surrogate guard) used by the Slack/WhatsApp/Teams/Discord
  adapters to respect per-platform length caps. Validates its inputs and throws
  `RangeError` on misuse (positive-integer `limit`, `safeLimit <= limit`) — fail-fast,
  never an infinite loop.
- **`chunkByGrapheme(text, options)`** — grapheme-cluster-safe (`Intl.Segmenter`)
  chunker used by LINE and SMS; never severs an emoji, regional-indicator pair, or
  combining sequence.
- **`GatewayConfigurationError`** (+ `GatewayConfigurationErrorOptions`) — the shared
  base each adapter's `ConfigurationError` extends, so a construction-time misconfig
  carries one consistent `code` / `detail` contract across the cluster.

## Design principles

- **Compose, don't reimplement.** The gateway never owns session persistence (the SDK
  does), scheduling (`Cron`), or prompt resolution (`SystemPromptResolver`).
- **Adapters are peer-dep packages.** Install only the transports you need.
- **Hooks live in the gateway, not the SDK.** Transport-layer concerns don't pollute the
  SDK's `Plugin` contract.

  `@theokit/gateway` is versioned independently via Changesets and is a peer dependency
  of every adapter. Keep them in step: an adapter that uses `chunkText` /
  `GatewayConfigurationError` requires `@theokit/gateway@^0.5.0`.

---

# @theokit/gateway-discord

Source: https://docs.usetheo.dev/theokit/gateways/discord

Discord adapter for TheoKit gateways — wraps discord.js in the BasePlatformAdapter contract over the WebSocket Gateway, with MessageContent intents by default, bot-to-bot filtering, and 2000-char message splitting.

`@theokit/gateway-discord` is the Discord platform adapter for `@theokit/gateway`. It
wraps [discord.js](https://discord.js.org/) in the `BasePlatformAdapter` contract over the
**WebSocket Gateway**: `connect()` calls `client.login(token)` and awaits the `ready`
event, inbound Discord messages are normalized into a portable `MessageEvent`, and
outbound replies are auto-split at Discord's 2000-character cap. You construct a
`DiscordAdapter`, hand it to a `GatewayRunner`, and your handler stays platform-agnostic —
`ctx.reply` routes back to the same channel.

## Install

```bash
pnpm add @theokit/gateway-discord discord.js @theokit/gateway @theokit/sdk
```

`discord.js` is a peer dependency — install the version your bot needs. `@theokit/gateway`
and `@theokit/sdk` are peers too, so there is exactly one copy in your app.

## Usage

Construct the adapter, resolve an agent per session inside the handler, and reply:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { DiscordAdapter } from '@theokit/gateway-discord'

const router = new SessionRouter()

const adapter = new DiscordAdapter({
  token: process.env.DISCORD_BOT_TOKEN!,
  // intents defaults to [Guilds, GuildMessages, MessageContent,
  // DirectMessages, DirectMessageReactions] — see the callout below.
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

`DiscordAdapterOptions` is `{ token: string; intents?: GatewayIntentBits[] }`. When
`intents` is omitted it falls back to `DEFAULT_DISCORD_INTENTS`; messages from other bots
(`msg.author.bot`) are always ignored so loops can't form.

### Platform escape hatch

For Discord-only features — slash commands via the Application Commands API,
`interactionCreate`, presence updates — reach the underlying discord.js `Client` with
`adapter.getBot()` and register handlers **before** calling `runner.start()`. Per-message
platform fields (guild id, channel id, message id, the raw discord.js `Message`) are on
`event.discord`.

## What you get

- **`DiscordAdapter`** — the discord.js wrapper implementing `BasePlatformAdapter`
  (`connect` / `disconnect` / `sendMessage` / `onInbound`) over the WebSocket Gateway;
  `connect()` never throws on a bad token (returns `false`).
- **`DEFAULT_DISCORD_INTENTS`** — `[Guilds, GuildMessages, MessageContent, DirectMessages,
  DirectMessageReactions]`, the default intent set that ensures `msg.content` is populated.
- **Bot-to-bot filtering** — inbound messages from other bots (`msg.author.bot`) are
  dropped at the adapter so bots can't reply to each other in a loop.
- **2000-char message splitting** — outbound text is auto-split at Discord's hard message
  limit; each chunk is sent in order and the last message id is returned.
- **Error mapping** — discord.js `DiscordAPIError`s are mapped to stable send-result codes:
  `dm_blocked` (50007), `no_permission` (50001/50013), and `rate_limited` (HTTP 429).
- **`event.discord` fields + `adapter.getBot()`** — `guildId`, `channelId`, `messageId`,
  and `raw` (the discord.js `Message`) for platform-specific work, plus direct `Client`
  access to register slash-command / interaction handlers.

  This adapter is `0.1.0` (pre-release) and ships the **WebSocket Gateway only** — there is
  no webhook bot mode in v0.1. The default intents include `MessageContent`, which is
  **required** for the bot to see message text: without it discord.js delivers an empty
  `msg.content` and your handler silently receives blank `event.text`. If you pass a custom
  `intents` array, keep `GuildMessages` and `MessageContent` (passing `intents: []` logs a
  warning). Slash commands, voice, and other Discord-native features are reached via
  `adapter.getBot()` rather than the portable `MessageEvent`.

---

# @theokit/gateway-email

Source: https://docs.usetheo.dev/theokit/gateways/email

Email channel adapter for TheoKit gateways — inbound IMAP IDLE + outbound SMTP as a two-way bot channel, distinct from the transactional plugin-email. Reconstructs RFC 5322 threads and hardens against mail loops.

`@theokit/gateway-email` is the email platform adapter for `@theokit/gateway`. It turns a
plain mailbox into a two-way bot channel: inbound mail arrives over IMAP IDLE (with a
polling fallback), replies go out over SMTP, and threading headers are preserved so answers
land in the same conversation thread. You construct an `EmailAdapter`, hand it to a
`GatewayRunner`, and your handler stays platform-agnostic — `ctx.reply` routes back to the
sender.

This is **not** the transactional [`@theokit/plugin-email`](/theokit/plugins/email) (Resend
one-shot sends like magic links). This gateway is a conversational **inbound + outbound**
channel — the agent reads a mailbox and answers from it. It speaks the community-standard
2026 Node stack: [nodemailer](https://nodemailer.com/) (SMTP), [imapflow](https://imapflow.com/)
(IMAP IDLE), and [mailparser](https://nodemailer.com/extras/mailparser/) (RFC 5322 parsing).

## Install

```bash
pnpm add @theokit/gateway-email nodemailer imapflow mailparser @theokit/gateway @theokit/sdk
```

`nodemailer`, `imapflow`, and `mailparser` are peer dependencies — install the versions your
bot needs. `@theokit/gateway` and `@theokit/sdk` are peers too, so there is exactly one copy
in your app.

## Usage

Construct the adapter with SMTP + IMAP config, hand it to a `GatewayRunner`, and reply from
the handler:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner } from '@theokit/gateway'
import { EmailAdapter } from '@theokit/gateway-email'

const adapter = new EmailAdapter({
  address: process.env.EMAIL_ADDRESS!,     // mailbox the bot listens on + outbound From:
  password: process.env.EMAIL_PASSWORD!,   // Gmail: an App Password, NOT the account password
  imapHost: 'imap.gmail.com',              // inbound (default port 993 / SSL)
  smtpHost: 'smtp.gmail.com',              // outbound (default port 587 / STARTTLS)
  fromName: 'Acme Assistant',              // optional display name on outbound From:
  allowedSenders: ['founder@acme.test'],   // optional allowlist (case-insensitive)
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.create({
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
      systemPrompt: 'You are a concise email assistant. Plain text only.',
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

`ctx.reply` routes through the same `EmailAdapter`, which looks up the inbound thread and
prepends `Re:` plus the `In-Reply-To` / `References` headers — so the reply threads into the
original conversation instead of starting a new one.

### Options

`EmailAdapterOptions` requires `address`, `password`, `imapHost`, and `smtpHost` (validated
non-empty at construction — a missing one throws a `TypeError` immediately). The rest are
optional: `imapPort` (default `993`), `smtpPort` (default `587`), `fromName`, `allowedSenders`,
`allowAutomated` (default `false`), `pollIntervalMs` (default `15000`, used only when IMAP
IDLE is unavailable), and `maxBodyChars` (default `50000`, ~12k tokens — bodies above this are
truncated).

## What you get

- **`EmailAdapter`** — the nodemailer + imapflow + mailparser wrapper implementing
  `BasePlatformAdapter` (`connect` / `disconnect` / `sendMessage` / `onInbound`). `connect()`
  never throws on bad credentials — it logs and returns `false`.
- **IMAP IDLE inbound** — RFC 2177 push via imapflow when the server supports it, with a 15s
  polling fallback otherwise. Each UNSEEN message is fetched, deduplicated by UID, and
  dispatched once.
- **SMTP outbound with RFC 5322 threading** — replies reconstruct the thread from
  `Message-ID` / `In-Reply-To` / `References`, so answers land in the same inbox thread as the
  incoming mail.
- **Loopback guard (EC-1, critical)** — messages from the bot's own address are dropped
  before anything else, so the agent can never answer itself into an infinite mail loop.
- **Automated-sender filter** — `noreply@` / `postmaster@` / `mailer-daemon@` / `bounce@`
  addresses and `Auto-Submitted`, `Precedence: bulk|list`, and `X-Auto-Response-Suppress`
  headers are dropped unless you set `allowAutomated: true`.
- **`allowedSenders` allowlist** — case-insensitive, display-name aware (`"Alice" <a@x>`
  matches `a@x`). Omit it for an open mailbox; an empty array closes the mailbox entirely.

  This adapter is `0.1.x` (pre-release, ADR D338 — breaking changes allowed within `0.x`).
  It authenticates with a plain user + password, so with Gmail you need an **App Password**
  (2FA account, not the login password); Outlook/Office 365, Yahoo, and Fastmail work the
  same way with their app-password + IMAP/SMTP host settings. The own-address **loopback
  guard** is always on and non-negotiable — it is what keeps the bot from replying to itself
  in a loop. There is a runnable `examples/email-bot` in the repo (full Gmail App Password
  walkthrough) to copy from.

---

# Getting started

Source: https://docs.usetheo.dev/theokit/gateways/getting-started

The common adoption pattern for TheoKit gateways — install the core with an adapter and its peers, wire a GatewayRunner, resolve an agent per session, and reply.

Every gateway follows the same shape. Install `@theokit/gateway` and one adapter with
their peer dependencies, construct the adapter, hand it to a `GatewayRunner` with a
`handler`, and `start()`. The handler receives a portable `MessageEvent` and a `ctx`
whose `reply` is auto-routed back to the originating platform.

## Peer-dependency discipline

Adapters never bundle the framework. `@theokit/sdk` and `@theokit/gateway` are peer
dependencies you install alongside the adapter so there is exactly one copy in your app,
plus the platform SDK the adapter wraps. Each adapter's own page lists its full peer set.

```bash
# Core + SDK (always):
pnpm add @theokit/gateway @theokit/sdk

# Plus one or more transport adapters with their platform SDK:
pnpm add @theokit/gateway-telegram grammy
pnpm add @theokit/gateway-discord discord.js
```

## Minimal bot — one adapter

Construct the adapter, resolve an agent per session inside the handler, and reply:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { TelegramAdapter } from '@theokit/gateway-telegram'

const router = new SessionRouter()
const adapter = new TelegramAdapter({ token: process.env.TELEGRAM_BOT_TOKEN! })

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

`ctx.reply` sends back to the same chat on the same platform — no platform branching in
your handler. `runner.stop()` drains in-flight replies and disconnects every adapter.

## Multi-channel — many adapters, one handler

Pass several adapters to the same runner. The handler is platform-agnostic; narrow on
`event.platform` only when you need platform-specific fields:

```ts title="server/bot.ts"
const runner = new GatewayRunner({
  adapters: [
    new TelegramAdapter({ token: process.env.TELEGRAM_BOT_TOKEN! }),
    new SlackAdapter({ botToken: process.env.SLACK_BOT_TOKEN!, appToken: process.env.SLACK_APP_TOKEN! }),
  ],
  handler: async (event, ctx) => {
    // event.platform narrows the union: "telegram" | "slack" | …
    const agent = await Agent.resume(router.resolveAgentId(event), { /* … */ })
    await ctx.reply((await (await agent.send(event.text)).wait()).result ?? '…')
    await agent.dispose()
  },
})
```

## Extend with hooks

Register `pre_inbound` / `post_outbound` / `on_error` hooks to gate, observe, or recover
without touching your handler. A `pre_inbound` hook returning `{ block: true }`
short-circuits before the handler runs:

```ts
const runner = new GatewayRunner({
  adapters: [adapter],
  hooks: [
    {
      name: 'rate-limit',
      pre_inbound: async ({ event }) =>
        overLimit(event.sender.id) ? { block: true, message: 'Slow down 🙏' } : undefined,
    },
  ],
  handler,
})
```

  Each adapter has platform-specific setup (tokens, webhooks, intents, signing secrets).
  Start from the adapter's page and the matching `examples/*-bot/` in the repo — every
  shipped adapter has a runnable example. See [Core](/theokit/gateways/core) for the full
  `GatewayRunner`, `SessionRouter`, `DeliveryRouter`, hook, and `MessageEvent` contracts.

---

# Overview

Source: https://docs.usetheo.dev/theokit/gateways

First-party TheoKit gateways — a transport-agnostic core plus ten platform adapters that let a TheoKit agent chat on Telegram, Discord, Slack, WhatsApp, Teams, Email, SMS, LINE, Matrix, and Mattermost.

**TheoKit gateways** are the channel layer of the framework — small, focused packages
published as **`@theokit/gateway*`** on npm that let an agent **receive messages from a
platform and reply**, hiding each platform's shape behind one portable `MessageEvent`
union. A single transport-agnostic core (`@theokit/gateway`) defines the contract and
routing; ten sibling adapters implement one platform each. You install only the
transports you use.

Eleven packages ship today, in **two layers**:

- **Core** — `@theokit/gateway` defines `BasePlatformAdapter`, the `GatewayRunner`
  orchestrator, `SessionRouter`/`DeliveryRouter`, the `HookExecutor` extension chain,
  the `MessageEvent` discriminated union, and shared primitives (`chunkText`,
  `chunkByGrapheme`, `GatewayConfigurationError`). It never owns session persistence,
  scheduling, or prompt resolution — it composes `@theokit/sdk` for those.
- **Adapters** — `telegram`, `discord`, `slack`, `whatsapp`, `teams`, `email`, `sms`,
  `line`, `matrix`, and `mattermost` each wrap one platform SDK behind
  `BasePlatformAdapter`. Each is an independent package with a peer-dependency policy
  (ADR D171): its platform SDK, `@theokit/sdk`, and `@theokit/gateway` are peers you
  install alongside it.

  Adapters never bundle the framework or each other. `@theokit/sdk` and
  `@theokit/gateway` are the common peers; the platform SDK (`grammy`, `discord.js`,
  `@slack/bolt`, …) is the per-adapter peer. Import direction is one-way — adapters
  depend on the core, the core depends on neither the SDK's internals nor any adapter,
  so there are **zero circular dependencies** across the cluster.

## How a message flows

```
Platform (Telegram / Slack / …)
        │
        ▼
PlatformAdapter          per-platform package (grammy, discord.js, …)
        │  MessageEvent  portable, discriminated by `platform`
        ▼
GatewayRunner            holds adapters, runs pre_inbound hooks, dispatches
        │
        ▼
your handler(event, ctx) → ctx.reply(text)   auto-routed back by event.platform
```

`BasePlatformAdapter` handles lifecycle, idempotent connect/disconnect, and the
never-throw-on-platform-error contract. `GatewayRunner` owns the adapter map, the hook
chain, and `ctx.reply` routing; your handler owns the agent logic.

## What you'd add and when

- **Ship a chat bot on one platform** — install `@theokit/gateway` + one adapter (e.g.
  `@theokit/gateway-telegram`), wire a `GatewayRunner`, resolve an agent per session.
- **Be multi-channel** — pass several adapters to the same `GatewayRunner`; one handler
  serves Telegram, Slack, and Email at once, replies routed by `event.platform`.
- **Reach consumer channels** — `whatsapp` (Cloud API or web bridge), `sms`
  (Twilio/Plivo/Vonage), `line` for messaging-API markets.
- **Reach team channels** — `slack`, `teams`, `discord`, `mattermost`, `matrix` for
  internal / community bots.
- **Reach the inbox** — `email` speaks IMAP IDLE inbound + SMTP outbound with automatic
  RFC 5322 threading.

## Browse the gateways

---

# @theokit/gateway-line

Source: https://docs.usetheo.dev/theokit/gateways/line

LINE Messaging API adapter for TheoKit gateways — webhook-only with HMAC-SHA256 signature validation, reply-token-then-push delivery, source-type mapping, mentionee-based mention gating, and surrogate-safe 5000-char splitting.

`@theokit/gateway-line` is the LINE platform adapter for `@theokit/gateway`. LINE has no
WebSocket gateway, so this adapter is **webhook-only**: `createWebhookServer` validates the
`X-Line-Signature` HMAC on every POST, hands the batch envelope to the `LineAdapter`, and your
handler stays platform-agnostic — `ctx.reply` routes back to whoever spoke. Inbound LINE events
are normalized into a portable `MessageEvent`, and outbound replies use LINE's free one-shot
reply token first, falling back to the Push API when it expires.

## Install

```bash
pnpm add @theokit/sdk @theokit/gateway @theokit/gateway-line
pnpm add @line/bot-sdk express
```

`@line/bot-sdk` and `express` are optional peers — install them to run the built-in webhook
server. `@theokit/gateway` and `@theokit/sdk` are peers too, so there is exactly one copy in
your app.

## Usage

Construct the adapter with your channel secret and access token, hand it to a `GatewayRunner`,
then start the webhook server:

```ts title="server/bot.ts"
import { GatewayRunner } from '@theokit/gateway'
import { LineAdapter, createWebhookServer } from '@theokit/gateway-line'

const adapter = new LineAdapter({
  channelSecret: process.env.LINE_CHANNEL_SECRET!,
  channelAccessToken: process.env.LINE_CHANNEL_ACCESS_TOKEN!,
  // botUserId: 'Uxxxxxx',   // your bot's LINE user ID — enables the mention guard in groups
  // requireMention: true,   // default
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    if (event.platform !== 'line') return
    await ctx.reply(`Echo: ${event.text}`)
  },
})

await runner.start()

const server = await createWebhookServer({ adapter, port: 3000 })
await server.start()
```

Point your LINE channel's webhook URL at `https://<public-url>/line` (for local dev,
`ngrok http 3000`). The channel secret is required at construction — the adapter refuses to
start without it, since there is no unsigned mode.

## What you get

- **`LineAdapter`** — implements `BasePlatformAdapter` (`connect` / `disconnect` /
  `sendMessage` / `onInbound`) over the LINE Messaging API. Construction fails fast if
  `channelSecret` or `channelAccessToken` is empty.
- **Webhook-only with HMAC-SHA256 validation** — `createWebhookServer({ adapter, port })`
  verifies the `X-Line-Signature` on every POST before any event reaches your handler; there
  is no WebSocket transport and no insecure mode.
- **Reply-token-then-push delivery** — the first outbound to a user consumes the free one-shot
  reply token (cached per sender, ~60s TTL); once it expires the adapter auto-falls-back to the
  Push API. A bounded LRU cache (1000 entries) manages the lifecycle.
- **Source-type mapping** — LINE `user` sources map to a `dm` channel; `group` and `room`
  sources both map to `group`. The original is preserved on `event.line.sourceType`.
- **Mentionee-based mention guard** — LINE mentions are out-of-band (not inline `@text`).
  With `requireMention` (default) and `botUserId` set, group messages only dispatch when
  your bot's user ID appears in `event.line.mentionees`; DMs always dispatch.
- **Surrogate-safe splitting** — `splitForLine(text)` breaks text longer than LINE's 5000-char
  cap on grapheme-cluster boundaries (via `Intl.Segmenter`), so emoji and combined characters
  are never cut in half. Applied automatically by `sendMessage`.
- **Escape hatch** — `adapter.getClient()` returns the underlying `@line/bot-sdk` client for
  features outside the portable contract (Flex Messages, carousels, quick replies).

  This adapter is `0.1.x` (pre-release) and is **webhook-only** — LINE offers no WebSocket
  gateway, so you must expose an HTTPS endpoint. Only `message` events of type `text` reach
  your handler; the other 8 webhook event types (`follow`, `unfollow`, `join`, `leave`,
  `postback`, `beacon`, `accountLink`, `things`) and non-text messages (image/audio/video/
  sticker/location) are filtered out. The reply token is one-shot with a ~60s TTL, so replies
  sent after that window (or to a user who never spoke) go out via the Push API, which is
  metered beyond the free tier. There is a runnable `examples/line-bot` in the repo to copy
  from.

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/gateways/llms-txt

Machine-readable ground truth of @theokit/gateway* for LLMs — the transport-agnostic core, the ten platform adapters, their real class names, transports, peers, and honest v0.x status.

The `@theokit/gateway*` cluster ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that gives any
LLM (Claude, ChatGPT, Cursor, Copilot, a local model) the **factual ground truth** of the
gateway packages without crawling the whole site:

- The two layers — the **core** (`@theokit/gateway`: `BasePlatformAdapter`,
  `GatewayRunner`, `SessionRouter`, `DeliveryRouter`, `HookExecutor`, the `MessageEvent`
  union, and the `chunkText` / `chunkByGrapheme` / `GatewayConfigurationError` primitives)
  and the ten **adapters**
- All ten adapters, each with its real adapter class, the platform SDK it wraps, its
  transport (long-poll / WebSocket / webhook / IMAP-IDLE), its common peers, current
  version, and a link to its live page
- The install pattern (`pnpm add @theokit/gateway @theokit/sdk` plus the adapter and its
  platform SDK peer)
- Honest per-adapter gotchas — WhatsApp's two backends (Cloud vs web bridge), SMS's
  three backends + mandatory webhook signing, Matrix's initial-sync history filter and
  refused E2EE rooms, LINE's reply-token-then-push fallback, Email's own-address loopback
  guard

  Every adapter is still **v0.x** and the core is `@theokit/gateway@0.5.0`. The file is
  honest about what is shipped vs deferred (Matrix E2EE, Teams OAuth, MMS/group SMS), and
  every class name and peer range is sourced from the package's `package.json` and README —
  no fabricated APIs.

## Get it

```bash
curl https://docs.usetheo.dev/theokit/gateways/llms.txt
```

Or link your AI assistant directly at
[`https://docs.usetheo.dev/theokit/gateways/llms.txt`](https://docs.usetheo.dev/theokit/gateways/llms.txt).

## Why

Point your coding assistant at it when you want it to stop hallucinating adapter class
names, which platform SDK an adapter wraps, or how replies are routed. Adapters are
**peer-dependency packages behind one `BasePlatformAdapter` contract**, not standalone
servers; you construct an adapter, hand it to a `GatewayRunner`, and `ctx.reply` routes
back by `event.platform`. The file makes that model explicit so an agent wires each
gateway the right way the first time.

---

# @theokit/gateway-matrix

Source: https://docs.usetheo.dev/theokit/gateways/matrix

Matrix adapter for TheoKit gateways — wraps matrix-js-sdk in the BasePlatformAdapter contract, with transparent federation, member-count DM detection, cached alias resolution, and an initial-sync history filter.

`@theokit/gateway-matrix` is the Matrix platform adapter for `@theokit/gateway`. It wraps
[matrix-js-sdk](https://github.com/matrix-org/matrix-js-sdk) in the `BasePlatformAdapter`
contract: `connect()` starts the sync long-poll in the background, inbound timeline events
are normalized into a portable `MessageEvent`, and outbound replies route back to the same
room. You construct a `MatrixAdapter`, hand it to a `GatewayRunner`, and your handler stays
platform-agnostic — `ctx.reply` routes back to the originating room.

Matrix is decentralized: a bot at `@theo-bot:matrix.org` works against matrix.org,
self-hosted Synapse/Dendrite, and any other homeserver, and can be added to rooms by users
on any homeserver via federation — the adapter never touches that seam, the protocol
handles it.

## Install

```bash
pnpm add @theokit/gateway-matrix matrix-js-sdk @theokit/gateway @theokit/sdk
```

`matrix-js-sdk` is a peer dependency (~2MB) — install the version your bot needs. It is
lazy-loaded via a dynamic import inside `connect()`, so nothing is pulled into your bundle
until the adapter actually connects. `@theokit/gateway` and `@theokit/sdk` are peers too,
so there is exactly one copy in your app.

## Usage

Construct the adapter with the homeserver URL, an access token, and the bot's user id, then
hand it to a `GatewayRunner`:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { MatrixAdapter } from '@theokit/gateway-matrix'

const router = new SessionRouter()

const adapter = new MatrixAdapter({
  homeserverUrl: 'https://matrix.org', // no trailing slash
  accessToken: process.env.MATRIX_ACCESS_TOKEN!,
  userId: '@theo-bot:matrix.org',
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    if (event.platform !== 'matrix') return
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

`MatrixAdapterOptions` is `{ homeserverUrl, accessToken, userId, freshnessWindowMs? }`. The
constructor validates all three required fields eagerly: an empty `homeserverUrl` or
`accessToken`, or a `userId` that doesn't start with `@`, throws a `ConfigurationError`
before any network call. Generate the access token via Element web:
**Settings → Help & About → Advanced → Access Token** — it grants full account access, so
keep it secret.

### Platform escape hatch

For Matrix-only features (reactions, redactions, media, replaying history), reach the
underlying matrix-js-sdk `MatrixClient` via `adapter.getClient()` and call `sendEvent(...)`
directly. Inbound events preserve the raw Matrix event under `event.matrix.raw`, so you can
read `getContent()` for a media file URL that arrived with empty `text`.

## What you get

- **`MatrixAdapter`** — the matrix-js-sdk wrapper implementing `BasePlatformAdapter`
  (`connect` / `disconnect` / `sendMessage` / `onInbound`), with the SDK lazy-loaded on
  first `connect()` and a `connect()` that returns `false` (never throws) on a bad token.
- **Transparent federation** — the adapter delegates federation entirely to the Matrix
  protocol; your bot receives from and replies to users on any homeserver with no extra
  wiring. Remote-homeserver failures surface as a `send_failed` `SendResult`.
- **DM detection** — Matrix has no native DM concept, so the adapter applies the canonical
  member-count heuristic: `getJoinedMemberCount() === 2` → `channel.type: "dm"`, three or
  more members → `"group"`.
- **Alias resolution + cache** — `sendMessage` accepts a room id (`!abc:matrix.org`) or a
  human alias (`#general:matrix.org`); aliases are resolved to a room id on first send and
  cached for the process lifetime.
- **Initial-sync history filter** — matrix-js-sdk delivers ~10 recent events per room on
  boot, so a 50-room bot would fire ~500 stale LLM calls at startup. The adapter drops
  events older than the freshness window (`event.getTs() < Date.now() - freshnessWindowMs`,
  default 60s, overridable via `freshnessWindowMs`) so only genuinely live messages
  dispatch.
- **Surrogate/raw handling** — inbound events carry the raw Matrix event under
  `event.matrix.raw`; media arrives with empty `text` (read the raw content for the file
  URL), and `adapter.getClient()` is the escape hatch for anything the portable contract
  doesn't cover.

  This adapter is `0.1.x` (pre-release). End-to-end encrypted rooms are **refused** — an
  encrypted room is skipped on inbound and returns an `encrypted_room_unsupported` send
  result, each logged once to stderr; E2EE is deferred to v0.2. MSC4140 threads are also
  deferred to v0.2, so every reply lands at the room root. The `matrix-js-sdk` peer is
  ~2MB but lazy-loaded (dynamic import on `connect()`), so it costs nothing until the bot
  connects. The sync token is process-local — a restart re-syncs, and the 60s freshness
  filter is what keeps that re-sync from replaying old history. There is a runnable
  `examples/matrix-bot` in the repo to copy from.

---

# @theokit/gateway-mattermost

Source: https://docs.usetheo.dev/theokit/gateways/mattermost

Mattermost adapter for TheoKit gateways — wraps @mattermost/client in the BasePlatformAdapter contract, with a WebSocket gateway for real-time inbound, REST for outbound, channel-type mapping, thread replies, and mention gating for non-DM channels.

`@theokit/gateway-mattermost` is the Mattermost platform adapter for `@theokit/gateway`. It
wraps [`@mattermost/client`](https://www.npmjs.com/package/@mattermost/client) in the
`BasePlatformAdapter` contract: `connect()` opens a WebSocket and streams real-time
`posted` events, inbound posts are normalized into a portable `MessageEvent`, and outbound
replies go back out over the Client4 REST API. You construct a `MattermostAdapter`, hand it
to a `GatewayRunner`, and your handler stays platform-agnostic — `ctx.reply` routes back to
the same channel. Works with self-hosted Mattermost (Docker / Kubernetes / bare metal) at
any `baseUrl` and with Mattermost Cloud.

## Install

```bash
pnpm add @theokit/gateway-mattermost @mattermost/client @theokit/gateway @theokit/sdk
```

`@mattermost/client` (`^9`) and `ws` (`^8`) are peer dependencies — install the versions
your bot needs. `@theokit/gateway` and `@theokit/sdk` are peers too, so there is exactly
one copy in your app.

## Usage

Construct the adapter with your server URL and a bot Personal Access Token, hand it to a
`GatewayRunner`, and reply:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner } from '@theokit/gateway'
import { MattermostAdapter } from '@theokit/gateway-mattermost'

const adapter = new MattermostAdapter({
  baseUrl: 'https://mattermost.acme.com',
  accessToken: process.env.MM_BOT_TOKEN!,
  // Optional: ignore non-DM channels unless the bot is explicitly @mentioned (default: true).
  // requireMention: true,
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    if (event.platform !== 'mattermost') return
    await ctx.reply(`Echo: ${event.text}`)
  },
})

await runner.start()
```

To create the token: sign in as a Mattermost admin, enable **System Console → Integrations
→ Bot Accounts**, add a bot account, copy the generated access token (shown once), and add
the bot to the channels where it should listen.

### Platform escape hatch

For features `v0.1` doesn't expose (file uploads, custom REST calls), reach the underlying
Client4 client and WebSocket handle via `adapter.getClient()` before or after
`runner.start()`.

## What you get

- **`MattermostAdapter`** — the `@mattermost/client` wrapper implementing
  `BasePlatformAdapter` (`connect` / `disconnect` / `sendMessage` / `onInbound`): a
  WebSocket gateway for real-time `posted` events and Client4 REST for outbound.
  `connect()` never throws on a bad URL or token — it returns `false`.
- **Self-hosted and Cloud** — point `baseUrl` at any Mattermost server; the WebSocket URL
  is derived from it automatically.
- **Channel-type mapping** — Mattermost `D` (Direct) → `dm`; `G` (Group DM), `O`
  (Open/Public), and `P` (Private) → `group`. The raw Mattermost type is preserved on the
  event so platform-specific logic can still see it.
- **Bidirectional thread replies** — a post with `root_id` set arrives as
  `channel.type: "thread"` with `topicId` = the root post id; sending with
  `type: "thread"` + `topicId: <root>` posts back as a thread reply via `root_id`.
- **Mention gating** — with `requireMention: true` (the default for non-DM channels), the
  adapter checks Mattermost's `metadata.mentions` user-id list first (no ambiguity), then
  falls back to a word-boundary regex `\b@${botUsername}\b` on the text — so a bot named
  `theo` isn't triggered by `@theory_dept`. DMs always process inbound.

  This adapter is `0.1.x` (pre-release). Auth is **Personal Access Token only** — OAuth is
  deferred to `v0.2` (D401). `requireMention` defaults to `true`, so in group, public, and
  private channels the bot stays quiet until it is `@mentioned`; set `requireMention: false`
  to answer every message in every channel it belongs to (loud — use cautiously). File
  uploads, slash-command webhooks, and ephemeral messages are not supported in `v0.1` — use
  the `adapter.getClient()` escape hatch for raw REST. There is a runnable
  `examples/mattermost-bot` in the repo to copy from.

---

# @theokit/gateway-slack

Source: https://docs.usetheo.dev/theokit/gateways/slack

Slack adapter for TheoKit gateways — wraps @slack/bolt in the BasePlatformAdapter contract over Socket Mode, with mention-required channel gating, a bot-loop guard, and surrogate-safe 4000-char message splitting.

`@theokit/gateway-slack` is the Slack platform adapter for `@theokit/gateway`. It wraps
[@slack/bolt](https://slack.dev/bolt-js/) in the `BasePlatformAdapter` contract over
**Socket Mode**: `connect()` starts the Bolt app and caches the bot user id, inbound Slack
`message` events are normalized into a portable `MessageEvent`, and outbound replies go out
via `chat.postMessage`, auto-split at Slack's 4000-character cap. You construct a
`SlackAdapter`, hand it to a `GatewayRunner`, and your handler stays platform-agnostic —
`ctx.reply` routes back to the same channel (and thread, when the inbound was threaded).

## Install

```bash
pnpm add @theokit/gateway-slack @slack/bolt @theokit/gateway @theokit/sdk
```

`@slack/bolt` is a peer dependency — install the version your bot needs. `@theokit/gateway`
and `@theokit/sdk` are peers too, so there is exactly one copy in your app.

Before wiring the adapter, create a Slack app, enable **Socket Mode**, add the bot token
scopes (`chat:write`, `app_mentions:read`, the `*:history` scopes, `users:read`), and
generate an **App-Level Token** with the `connections:write` scope. The adapter needs both a
Bot User OAuth token (`xoxb-...`) and that App-Level token (`xapp-...`).

## Usage

Construct the adapter, resolve an agent per session inside the handler, and reply:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { SlackAdapter } from '@theokit/gateway-slack'

const router = new SessionRouter()

const adapter = new SlackAdapter({
  botToken: process.env.SLACK_BOT_TOKEN!, // xoxb-...
  appToken: process.env.SLACK_APP_TOKEN!, // xapp-... with connections:write
  // requireMention defaults to true — public-channel messages without @bot are dropped.
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

`SlackAdapterOptions` is `{ botToken; appToken; transport?: "socket"; requireMention?; logLevel? }`.
`transport` accepts only `"socket"` in v1. When `requireMention` is left at its default
(`true`), public-channel messages that don't `@mention` the bot are dropped before the handler
runs — set it to `false` for FAQ bots that should hear every message. `logLevel`
(`debug` | `info` | `warn` | `error`) is passed straight through to the underlying Bolt app.

### Platform escape hatch

Block Kit, slash commands, and modals are not part of the v1 surface. To reach any of those,
grab the underlying Bolt `App` via `adapter.getApp()` and register handlers on it directly.
`adapter.getBotUserId()` returns the id resolved via `auth.test` on connect.

## What you get

- **`SlackAdapter`** — the `@slack/bolt` wrapper implementing `BasePlatformAdapter`
  (`connect` / `disconnect` / `sendMessage` / `onInbound`) over Socket Mode. `connect()`
  never throws on a bad token — it cleans up any orphaned Bolt app and returns `false`;
  concurrent `connect()` calls share one in-flight start, and `disconnect()` is idempotent.
- **Mention-required channel gating** — `requireMention: true` (default) drops public-channel
  messages that don't `@mention` the bot, so a busy channel can't trigger a cost explosion.
  Opt out per adapter with `requireMention: false`.
- **Bot-loop guard** — the bot user id is cached via `auth.test` on connect and used to
  suppress the adapter's own messages, so a reply can't re-trigger the handler.
- **`splitForSlack(text)`** — splits at the 4000-char `chat.postMessage` cap, preferring
  `\n\n` → `\n` → space boundaries with a UTF-16 surrogate-pair guard so a chunk never breaks
  a code point. Applied automatically by `sendMessage`; multi-chunk replies stay in the same
  thread and the last chunk's `ts` is returned as the `messageId`.
- **Canonical `SendResult` errors** — Slack API failures are mapped to typed results
  (`not_connected`, `empty_text`, and mapped Slack errors) rather than thrown.
- **`getApp()` / `getBotUserId()`** — escape hatches for advanced Bolt features (Block Kit,
  slash commands, modals) and the cached bot user id.

  This adapter is **Socket Mode only** in v1 — there is no HTTP-webhook transport, so the
  `transport` option accepts only `"socket"`. That means you must enable Socket Mode on the
  Slack app and provide **both** tokens: a Bot User OAuth token (`xoxb-...`) and an App-Level
  token (`xapp-...`) carrying the `connections:write` scope. File uploads, Block Kit,
  reactions, modals, and slash commands are out of scope for v1 — reach them through
  `adapter.getApp()`.

---

# @theokit/gateway-sms

Source: https://docs.usetheo.dev/theokit/gateways/sms

SMS platform adapter for @theokit/gateway — one adapter, three backends (Twilio, Plivo, Vonage) with mandatory inbound webhook signing, E.164 normalization, and grapheme-safe multipart splitting.

`@theokit/gateway-sms` is the SMS platform adapter for `@theokit/gateway`. You construct one
`SMSAdapter`, pick a backend (`twilio`, `plivo`, or `vonage`) via the `backend` field, and hand
it to a `GatewayRunner` — the handler stays platform-agnostic, so `ctx.reply` routes back to the
same phone number. Inbound messages arrive over an Express webhook whose provider signature is
verified **before** any handler runs; outbound replies are normalized to E.164 and split into
`(i/N)` parts when they exceed the carrier limit.

The `backend` discriminated union means the credential shape matches the provider you chose — the
compiler tells you which fields Twilio needs versus Plivo versus Vonage. v0.1 is text-only.

## Install

```bash
pnpm add @theokit/gateway-sms @theokit/gateway @theokit/sdk

# Then install ONE backend SDK you actually use (each is an optional peer):
pnpm add twilio              # for backend: "twilio"
pnpm add plivo               # for backend: "plivo"
pnpm add @vonage/server-sdk  # for backend: "vonage"
```

`@theokit/gateway` and `@theokit/sdk` are peers, so there is exactly one copy in your app. The
backend SDKs (`twilio` / `plivo` / `@vonage/server-sdk`) and `express` (the webhook server) are
**optional** peers — resolved by dynamic import on first use, so only the one you install is
loaded. `libphonenumber-js` (E.164 normalization) is a peer as well.

## Usage

Construct the adapter, hand it to a `GatewayRunner`, then start an Express webhook server so the
provider can POST inbound messages:

```ts title="server/bot.ts"
import { GatewayRunner } from '@theokit/gateway'
import { SMSAdapter, createWebhookServer } from '@theokit/gateway-sms'

const adapter = new SMSAdapter({
  backend: 'twilio',
  accountSid: process.env.TWILIO_ACCOUNT_SID!,
  authToken: process.env.TWILIO_AUTH_TOKEN!, // also the webhook signing secret (required)
  fromNumber: process.env.TWILIO_FROM!, // bot's own E.164 number
  publicUrl: process.env.PUBLIC_URL!, // e.g. https://abc.ngrok.io — used to verify signatures
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    if (event.platform !== 'sms') return
    await ctx.reply(`Echo: ${event.text}`)
  },
})

await runner.start()

// The provider POSTs inbound to `${path}/${backend}` — here POST /sms/twilio.
const server = await createWebhookServer({ adapter, port: 3000 })
await server.start()
```

Each backend takes its own credential fields on the same union: Plivo uses `authId` + `authToken`,
Vonage uses `apiKey` + `apiSecret` + `signatureSecret`. All three also take `fromNumber`,
`publicUrl`, and an optional `defaultCountry` for parsing unprefixed inbound numbers. Point the
provider's inbound webhook at `https://<public-url>/sms/<backend>`.

## What you get

- **`SMSAdapter`** — one adapter implementing `BasePlatformAdapter` (`connect` / `disconnect` /
  `sendMessage` / `onInbound`) over a backend you pick with `backend: "twilio" | "plivo" |
  "vonage"`. Backend SDKs are lazily imported, so only the one you installed loads.
- **Mandatory webhook signing** — the constructor throws
  `ConfigurationError({ code: "signing_secret_required" })` if the backend's signing secret is
  empty, and the webhook responds `401` on a missing or invalid signature **before** any handler
  dispatch. A public webhook endpoint with no HMAC validation is refused outright.
- **E.164 normalization** — every phone number (inbound sender, outbound recipient) is normalized
  to E.164 via `libphonenumber-js`; a non-parseable number surfaces as an `invalid_phone_number`
  send result rather than throwing mid-send.
- **`(i/N)` multipart splitting** — outbound text over 1600 chars is split into `(1/N) …` parts
  with `Intl.Segmenter`, so emoji and combining characters are never severed. Parts are sent
  sequentially to preserve order; each part is one billable carrier message.
- **`createWebhookServer({ adapter, port })`** — the Express helper that mounts
  `POST /sms/<backend>`, captures the raw request body verbatim (the signature depends on exact
  bytes), verifies the signature, and dispatches. Pass your own `app` to mount it into an
  existing server.

  The backend signing secret is **mandatory** — `authToken` for Twilio/Plivo, `signatureSecret`
  for Vonage. There is no unsigned mode; the constructor refuses to build without it. This is
  v0.1, which is **text only**: MMS (image/audio), group SMS, per-message budget, and delivery
  status callbacks are deferred to v0.2. For a provider-specific feature meanwhile, reach the
  underlying SDK. There is a runnable `examples/sms-bot` in the repo to copy from.

---

# @theokit/gateway-teams

Source: https://docs.usetheo.dev/theokit/gateways/teams

Microsoft Teams adapter for TheoKit gateways — wraps the modern @microsoft/teams.apps v2 SDK in the BasePlatformAdapter contract, mounting a POST /api/messages webhook on your own Express server with SDK-handled JWT validation, mention stripping, and 8000-char message splitting.

`@theokit/gateway-teams` is the Microsoft Teams platform adapter for `@theokit/gateway`. It
wraps the modern [`@microsoft/teams.apps`](https://www.npmjs.com/package/@microsoft/teams.apps)
v2 SDK (ADR D315) in the `BasePlatformAdapter` contract: the SDK validates inbound JWTs,
strips `@bot` mentions, and routes proactive sends, while the adapter normalizes each Teams
`MessageActivity` into a portable `MessageEvent` and auto-splits outbound replies at Teams'
8000-character cap. You construct a `TeamsAdapter`, hand it the SDK's `ExpressAdapter` so it
can register `POST /api/messages` on your own server, and your handler stays platform-agnostic.

## Install

```bash
pnpm add @theokit/gateway-teams @microsoft/teams.apps @theokit/gateway @theokit/sdk
```

`@microsoft/teams.apps` is a peer dependency — it pulls in ~30 MB and is imported lazily, so
you only pay for it when this adapter is used. `@theokit/gateway` and `@theokit/sdk` are peers
too, so there is exactly one copy in your app.

## Usage

Build an Express app, wrap it in the SDK's `ExpressAdapter`, and pass that to the adapter as
`httpServerAdapter` — the SDK registers `POST /api/messages` during `connect()`. Then hand the
adapter to a `GatewayRunner` and reply from a platform-agnostic handler:

```ts title="server/bot.ts"
import express from 'express'
import { ExpressAdapter } from '@microsoft/teams.apps'
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { TeamsAdapter } from '@theokit/gateway-teams'

const expressApp = express()
expressApp.use(express.json())
const httpServerAdapter = new ExpressAdapter(expressApp)

const router = new SessionRouter()

const adapter = new TeamsAdapter({
  clientId: process.env.TEAMS_CLIENT_ID!,
  clientSecret: process.env.TEAMS_CLIENT_SECRET!,
  tenantId: process.env.TEAMS_TENANT_ID!,
  botDisplayName: process.env.TEAMS_BOT_DISPLAY_NAME ?? 'Theo',
  httpServerAdapter,
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
// The SDK registered POST /api/messages during connect(); now bind the port.
await httpServerAdapter.start(Number(process.env.PORT ?? 3978))
```

`TeamsAdapterOptions` is `{ clientId, clientSecret, tenantId, botDisplayName?, httpServerAdapter? }`.
The three Azure AD ids are required and validated as non-empty strings at construction (fail
fast). `botDisplayName` is an optional fallback for mention stripping. Reply routing uses
`event.channel.id` as the conversation id — the SDK manages the underlying conversation
reference, so there is no ref store to maintain.

### Platform escape hatch

For Teams-only features (Adaptive Cards, message extensions), reach the underlying SDK `App`
via `adapter.getApp()`, or get the mounted HTTP-server adapter with `adapter.getExpressAdapter()`.

## What you get

- **`TeamsAdapter`** — the `@microsoft/teams.apps` v2 wrapper implementing `BasePlatformAdapter`
  (`connect` / `disconnect` / `sendMessage` / `onInbound`); `connect()` never throws on bad
  credentials (returns `false`), and `disconnect()` swallows errors so shutdown is clean.
- **SDK-handled security** — JWT validation on inbound activities (D319) and built-in mention
  stripping (`activity.mentions.stripText`) are configured for you; there is no HMAC/rawBody
  middleware to wire (standard `express.json()` is enough).
- **Own-server webhook** — pass `new ExpressAdapter(yourApp)` as `httpServerAdapter` and the SDK
  registers `POST /api/messages` on your existing Express server during `connect()` (D316/D326).
- **Portable normalization** — each `MessageActivity` becomes a `TeamsMessageEvent` mapping
  `personal` → `dm`, `groupChat`/`channel` → `group`, with `teams` fields (`activityId`,
  `conversationId`, `conversationType`, `tenantId`, `channelId`, `teamId`, `raw`) for
  platform-specific work.
- **`splitForTeams(text)`** — splits at the 8000-char cap on `\n\n` / `\n` / ` ` boundaries
  with a UTF-16 surrogate-pair guard; applied automatically by `sendMessage`.
- **`stripTeamsMentions(text, botDisplayName?)`** — the standalone `<at>…</at>` cleanup helper,
  exported as a fallback for callers that consume raw text directly.

  This adapter is `0.1.x` (pre-release, ADR D324 — breaking changes allowed within 0.x) and
  ships **text only** — no first-class Adaptive Cards (use the `adapter.getApp()` escape hatch)
  and no delivery/read receipts. It requires real Azure setup before it can receive anything:
  an **Azure AD app registration** (client id, client secret, tenant id), an **Azure Bot
  Service** registration, and a **publicly reachable webhook** (ngrok for local dev) set as the
  Bot's Messaging Endpoint. There is a runnable `examples/teams-bot` in the repo with an 8-step
  Azure walkthrough plus a `smoke` script that validates credentials without standing up Bot
  Service.

---

# @theokit/gateway-telegram

Source: https://docs.usetheo.dev/theokit/gateways/telegram

Telegram adapter for TheoKit gateways — wraps grammy in the BasePlatformAdapter contract, with an allow-list filter, group-chat mention gating, and markdown-safe 4096-char message splitting.

`@theokit/gateway-telegram` is the Telegram platform adapter for `@theokit/gateway`. It
wraps [grammy](https://grammy.dev/) in the `BasePlatformAdapter` contract: `connect()`
starts long-polling in the background, inbound Telegram messages are normalized into a
portable `MessageEvent`, and outbound replies are auto-split at Telegram's 4096-character
cap. You construct a `TelegramAdapter`, hand it to a `GatewayRunner`, and your handler
stays platform-agnostic — `ctx.reply` routes back to the same chat.

## Install

```bash
pnpm add @theokit/gateway-telegram grammy @theokit/gateway @theokit/sdk
```

`grammy` is a peer dependency — install the version your bot needs. `@theokit/gateway`
and `@theokit/sdk` are peers too, so there is exactly one copy in your app.

## Usage

Construct the adapter, resolve an agent per session inside the handler, and reply:

```ts title="server/bot.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { TelegramAdapter } from '@theokit/gateway-telegram'

const router = new SessionRouter()

const adapter = new TelegramAdapter({
  token: process.env.TELEGRAM_BOT_TOKEN!,
  allowedUsers: ['7528967933'], // optional adapter-level allow-list
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

`TelegramAdapterOptions` is exactly `{ token: string; allowedUsers?: readonly string[] }`.
When `allowedUsers` is set, messages from any other sender id are dropped at the adapter
before the handler runs; messages from other bots (`ctx.from.is_bot`) are always ignored.

### Group-chat mention gating

In group chats you usually don't want the bot answering every message. Register
`shouldRespondInChat` as a `pre_inbound` hook: DMs always reply, groups only reply on
`@mention`, reply-to-bot, or a slash command. `stripBotMention` removes the leading
`@bot` from the text:

```ts
import { shouldRespondInChat, stripBotMention } from '@theokit/gateway-telegram'
```

### Platform escape hatch

For Telegram-only features (voice, photos, callback queries), reach the underlying grammy
`Context` via `event.telegram.raw`, or register grammy handlers directly on the bot with
`adapter.getBot()` before calling `runner.start()`.

## What you get

- **`TelegramAdapter`** — the grammy wrapper implementing `BasePlatformAdapter`
  (`connect` / `disconnect` / `sendMessage` / `onInbound` / `startTyping`), long-polling
  transport that never throws on a bad token (returns `false` from `connect`).
- **Adapter-level allow-list** — `allowedUsers` filters inbound by sender id; bot-to-bot
  messages are blocked so loops can't form.
- **`shouldRespondInChat(ctx, policy)` + `stripBotMention(text)`** — group-chat mention
  gating as a `pre_inbound` hook (DM = always, group = mention / reply-to-bot / command).
- **`splitForTelegram(text)`** — markdown-safe splitting at the 4096-char cap; breaks on
  paragraph/line boundaries and balances markdown pairs so a chunk never breaks `**`,
  `__`, `~~`, or `` ` ``. Applied automatically by `sendMessage`.
- **`event.telegram` fields** — `chatId`, `messageId`, optional `threadId`, and `raw`
  (the grammy `Context`) for platform-specific work, plus `adapter.getBot()` to register
  raw grammy handlers.

  This adapter is `0.1.0` (pre-release) and ships **long-polling** only — `connect()`
  calls `bot.start()` with `drop_pending_updates`, so updates queued while the bot was
  offline are discarded on reconnect. Outbound `parse_mode` is mapped from the message
  `format` (`markdown` → `Markdown`, `html` → `HTML`); a Telegram parse failure surfaces
  as a `markdown_error` send result rather than throwing. There is a runnable
  `examples/telegram-bot` (and `examples/telegram-pro`) in the repo to copy from.

---

# @theokit/gateway-whatsapp

Source: https://docs.usetheo.dev/theokit/gateways/whatsapp

WhatsApp adapter for TheoKit gateways with two backends — the official Meta WhatsApp Business Cloud API and an unofficial whatsapp-web.js subprocess bridge — behind one BasePlatformAdapter with 4096-char splitting.

`@theokit/gateway-whatsapp` is the WhatsApp platform adapter for `@theokit/gateway`. It
ships **two backends** behind one `WhatsAppAdapter` (ADR D303): **cloud** — the official
[Meta WhatsApp Business Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api)
(Bearer access token, signed inbound webhooks, verify-token handshake); and **web** — an
unofficial [`whatsapp-web.js`](https://wwebjs.dev/) subprocess bridge for personal accounts
that pairs over a QR code. You build a `WhatsAppCloudBackend` or `WhatsAppWebBackend`, hand it
to a `WhatsAppAdapter`, and your handler stays platform-agnostic — inbound WhatsApp messages
normalize into a portable `MessageEvent` and outbound replies auto-split at WhatsApp's
4096-character cap.

## Install

```bash
# Cloud backend (official Meta API) — no extra peer:
pnpm add @theokit/gateway-whatsapp @theokit/gateway @theokit/sdk

# Web backend adds the whatsapp-web.js peer (optional — only for the bridge):
pnpm add whatsapp-web.js
```

`@theokit/gateway` and `@theokit/sdk` are peers, so there is exactly one copy in your app.
`whatsapp-web.js` is an **optional** peer — install it only when you use the web bridge; the
cloud backend never pulls it in.

## Usage

### Cloud backend (official Meta API)

The cloud backend has no persistent connection — inbound is push over a webhook you host, and
send is HTTP. Build the backend, wrap it in a `WhatsAppAdapter`, and drive it with a
`GatewayRunner`:

```ts title="server/whatsapp.ts"
import { Agent } from '@theokit/sdk'
import { GatewayRunner, SessionRouter } from '@theokit/gateway'
import { WhatsAppAdapter, WhatsAppCloudBackend } from '@theokit/gateway-whatsapp'

const router = new SessionRouter()

const backend = new WhatsAppCloudBackend({
  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!, // Meta phone-number-id, not the phone
  appSecret: process.env.WHATSAPP_APP_SECRET!, // verifies X-Hub-Signature-256 on inbound
})

const adapter = new WhatsAppAdapter(backend, {
  botPhoneId: process.env.WHATSAPP_PHONE_NUMBER_ID!, // used for @mention gating in groups
})

const runner = new GatewayRunner({
  adapters: [adapter],
  handler: async (event, ctx) => {
    const agent = await Agent.resume(router.resolveAgentId(event), {
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: { id: 'openai/gpt-4o-mini' },
    })
    const run = await agent.send(event.text)
    const result = await run.wait()
    await ctx.reply(result.result ?? 'no reply')
    await agent.dispose()
  },
})

await runner.start()
```

Inbound is delivered by **your** HTTP route calling `backend.handleWebhookPayload(rawBody, sig)`.
Wire two routes: a `GET /webhook` handshake with `verifyWebhookSubscription(query, verifyToken)`,
and a `POST /webhook` that verifies the signature with `verifyWebhookSignature(rawBody, sig, appSecret)`
before dispatching. Preserve the **raw request bytes** — the HMAC is computed over them. See
`examples/whatsapp-bot` in the repo for the full Express wiring.

### Web backend (unofficial bridge)

The web backend spawns the `whatsapp-web.js` bridge as a subprocess; `connect()` prints a QR
code (to stderr) that you scan once from **WhatsApp → Linked devices**. The session persists,
so there is no webhook to host:

```ts title="server/whatsapp-web.ts"
import { WhatsAppAdapter, WhatsAppWebBackend } from '@theokit/gateway-whatsapp'

const backend = new WhatsAppWebBackend({ sessionId: 'my-bot' })
const adapter = new WhatsAppAdapter(backend, {
  botPhoneId: process.env.WHATSAPP_BOT_PHONE, // required for group @mention gating in web mode
})

// same adapter.onInbound / adapter.sendMessage (or GatewayRunner) as above
await adapter.connect() // races a 120s timeout so an unattended QR pairing fails fast
```

## What you get

- **`WhatsAppAdapter`** — the `BasePlatformAdapter` façade (`connect` / `disconnect` /
  `sendMessage` / `onInbound` / `onStatusReceipt`). It is backend-agnostic: you pass it a
  pre-built `WhatsAppCloudBackend` or `WhatsAppWebBackend` plus `{ requireMention?, botPhoneId? }`.
- **`WhatsAppCloudBackend`** — official Meta Cloud API backend. `connect`/`disconnect` are
  no-ops (webhook push + HTTP send); inbound flows through `handleWebhookPayload(rawBody, sig)`.
  Ships the webhook helpers `verifyWebhookSubscription`, `verifyWebhookSignature`,
  `parseWebhookPayload`, `normalizeInboundMessages`, and `normalizeStatusReceipts`.
- **`WhatsAppWebBackend`** — unofficial `whatsapp-web.js` subprocess bridge for personal
  accounts. QR pairing, `connectTimeoutMs` (default 120000) and `sendTimeoutMs` (default 30000)
  guards, and a `sessionId` that locks the bridge per workspace.
- **Group `@mention` gating** — `requireMention` (default `true`) drops group messages that
  don't mention the bot; matching uses digit-only normalization via `digitsOnly(...)`. DMs
  always pass. Misconfigured groups (no `botPhoneId`) are dropped silently.
- **`event.whatsapp` fields** — `wamid` (message id: `wamid.xxx` on cloud, serialized id on
  web), `phoneNumberId` (cloud only), `contactName`, `backend` (`"cloud" | "web"`), and `raw`
  (the backend-specific envelope) for platform-specific work.
- **Status receipts** — `adapter.onStatusReceipt(...)` surfaces `sent` / `delivered` / `read` /
  `failed` per `wamid`.
- **`splitForWhatsApp(text)`** — splitting at the fixed 4096-char cap (breaks on `\n\n` → `\n`
  → space, surrogate-pair safe, empty parts filtered). Applied automatically by `sendMessage`.

  This adapter is `0.1.0` (pre-release) — pre-1.0 contract per ADR D314, breaking changes
  allowed within 0.x. The **web** backend is **unofficial**: it drives a headless
  `whatsapp-web.js` session in a subprocess and carries account-ban risk — WhatsApp does not
  support automation of personal accounts. Use it for dev/prototypes; use **cloud** for
  production. The **cloud** backend requires a Meta app with a WhatsApp Business phone number,
  and you host the signed webhook yourself (`verifyWebhookSignature` over the raw request
  bytes). There are runnable `examples/whatsapp-bot` (cloud) and `examples/whatsapp-web-bot`
  (web) in the repo to copy from.

---

# Advanced

Source: https://docs.usetheo.dev/theokit/goals/advanced

The ephemeral runUntil judge loop and its event stream, goal options, the per-send completion check, and continuation across iteration ceilings.

# Advanced goals

Verified against `@theokit/sdk` (`types/goal-events.ts`, `types/run.ts`).

## The judge loop — `runUntil`

```ts
const iter = agent.runUntil("Ship a green test suite", { maxTurns: 10 });
let ev = await iter.next();
while (!ev.done) {
  // observe each transition — ev.value is a GoalEvent
  ev = await iter.next();
}
const result: GoalResult = ev.value; // the generator's return value
```

`runUntil(goal, options?)` drives `send → judge → continue` until the auxiliary judge returns `done`,
the judge fails too often, `maxTurns` is hit, or you abort. It is **ephemeral and per-call** — the
goal is passed on every call; there is no durable, thread-scoped objective. A no-goal `runUntil()`
pauses. It yields a `GoalEvent` per transition and returns a `GoalResult` (`status: "completed" |
"failed" | "paused"`, `turnsUsed`, `finalResponse`). **Local runtime only.**

## The event stream — `GoalEvent`

| Event | Meaning |
| --- | --- |
| `turn_start` | A new agent turn begins. |
| `agent_response` | The agent produced a response for this turn. |
| `judge_verdict` | The judge model evaluated the response (`parseFailed: true` on a malformed judge reply). |
| `continuation` | The judge ruled `continue` — carries the follow-up prompt. |
| `status_change` | Overall goal state moved (`active` / `paused` / `completed` / `failed`). |

## `GoalOptions`

```ts
agent.runUntil(goal, {
  maxTurns: 20,                     // hard iteration cap. Default 20
  maxConsecutiveJudgeFailures: 3,    // bail after N malformed judge replies. Default 3
  judgeModel: "openai/gpt-4o-mini",  // the auxiliary judge. Default gpt-4o-mini
  judgeApiKey,                       // override env for the judge (default OPENROUTER_API_KEY)
  subgoals: ["tests pass", "no lint errors"], // fed to the judge prompt
  signal,                            // AbortController — yields status_change: paused, returns at the next turn
});
```

## Lightweight check — per-send `completionCheck`

For a single-shot "is this done?" without the full loop, pass a `completionCheck` to `send`:

```ts
const result = await (await agent.send(prompt, { completionCheck: { criteria: "…" } })).wait();
result.completionCheck; // the resolved verdict on the run
```

It scores the finished reply against the criteria and surfaces a `CompletionCheckResult` on the run
plus a `completion_check` run-event — a goal check without the continue-loop.

## Continuation across iteration ceilings — `runToCompletion`

Distinct from goals: when a single `send` stops at the loop's iteration cap
(`RunResult.stoppedAtIterationLimit`), `agent.runToCompletion(...)` re-sends a short continuation
prompt (the stateful session preserves context) until a genuine terminal — `done`, `step_limit`
(`maxRounds` exhausted), or `no_progress`. Local agents only.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`GoalOptions`](/theokit/reference/GoalOptions) · [`GoalResult`](/theokit/reference/GoalResult) · [`GoalEvent`](/theokit/reference/GoalEvent) · [`RunToCompletionOptions`](/theokit/reference/RunToCompletionOptions)

---

# Overview

Source: https://docs.usetheo.dev/theokit/goals

Drive an agent toward a goal until an auxiliary judge says it's done — an ephemeral, per-call loop.

# Goals

A normal `send()` runs one turn. A **goal loop** keeps the agent working — `send → judge →
continue` — until an auxiliary judge model returns `done`, the judge fails too often, max turns are
exhausted, or you abort.

```ts
for await (const event of agent.runUntil("Ship a green test suite", { maxTurns: 10 })) {
  console.log(event.type); // GoalEvent per state transition
}
```

- **`agent.runUntil(goal, options?)`** — the loop. It is **ephemeral and per-call**: pass the goal to
  each call. Yields a `GoalEvent` per transition and returns a `GoalResult`. Local runtime only.
- A **no-goal `runUntil()` pauses** — there is no durable objective to resolve.
- **`isTaskComplete`** (per-send `completionCheck`) scores a finished reply against criteria and
  surfaces the verdict on the run — a lightweight goal check without the full loop.

## Next

- [Run until a goal is met](/theokit/goals/set-a-durable-objective) — a runnable `runUntil` example.
- [Advanced](/theokit/goals/advanced) — the `runUntil` judge loop, event stream, and completion checks.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`GoalOptions`](/theokit/reference/GoalOptions) · [`GoalResult`](/theokit/reference/GoalResult) · [`GoalEvent`](/theokit/reference/GoalEvent)

---

# Run until a goal is met

Source: https://docs.usetheo.dev/theokit/goals/set-a-durable-objective

Drive an agent with the ephemeral runUntil judge loop — iterate its GoalEvents and read the final GoalResult.

# Run until a goal is met

`agent.runUntil(goal, options)` drives `send()` in a loop: after each turn an auxiliary judge model
decides `done` vs `continue`, until the goal is met or `maxTurns` is hit. It is an async generator —
iterate the `GoalEvent`s, and the generator's final value is a `GoalResult`. The loop is **ephemeral
and per-call**: pass the goal on every call (a no-goal `runUntil()` pauses). Requires a real LLM
because the judge loop calls a model.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You are a concise assistant. Do exactly what is asked, one step at a time.",
});

// Explicit goal → ephemeral loop.
const loop = agent.runUntil?.(
  "List the first 3 prime numbers, one per line, then say the word DONE.",
  { maxTurns: 4 },
);

let ev = await loop!.next();
while (!ev.done) {
  const e = ev.value;
  if (e.type === "turn_start") console.log(`turn ${e.turn} → send`);
  else if (e.type === "judge_verdict") console.log(`turn ${e.turn} → judge: ${e.verdict}`);
  else if (e.type === "status_change") console.log(`status: ${e.status}`);
  ev = await loop!.next();
}

const result = ev.value; // GoalResult
console.log("goal status:", result.status);
console.log("turns used: ", result.turnsUsed);

await agent.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
turn 1 → send
turn 1 → judge: done
status: completed
goal status: completed
turns used:  1
```

## What it shows

- **`runUntil(goal, { maxTurns })`** returns an async generator. Each `next()` yields a `GoalEvent`
  (`turn_start`, `agent_response`, `judge_verdict`, `continuation`, `status_change`).
- **The generator's return value** (when `done: true`) is a `GoalResult` — `status`
  (`completed` / `failed` / `paused`), `turnsUsed`, `finalResponse`.
- **The loop is ephemeral** — the goal is passed to each call; a no-goal `runUntil()` pauses.
- The loop is **local-runtime only**; cloud agents manage continuation server-side.

## Example

Full runnable source:
[`examples/goals-objective`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/goals-objective).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/guardrails/advanced

The full Processor contract, the input/output contexts, violations, the deterministic in-tree processors, and the streaming and cloud caveats.

# Advanced guardrails

Verified against the SDK.

## The `Processor` contract

```ts
interface Processor {
  id: string;
  processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
  processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
  onViolation?(violation: ProcessorViolation): void; // errors here are swallowed — never break the pipeline
}
```

- Return a string → replace the payload. Return nothing (`void`) → observe-only, payload unchanged.
- `processInput` / `processOutput` may be `async`.
- Processors run **in array order**.

## The contexts

Both contexts extend `ProcessorControls` (`abort(reason): never`, `warn(message, detail?): void`):

```ts
interface InputProcessorContext extends ProcessorControls {
  message: string;   // the user message for this send
  agentId: string;
}
// OutputProcessorContext carries the model's final text plus the same controls.
```

## Violations

`abort()` and `warn()` produce a `ProcessorViolation` delivered to `onViolation`:

- **`abort(reason)`** → the run stops; `RunResult.status = "cancelled"`, `RunResult.tripwire =
  { reason, processorId }`, and a `tripwire` run-event fires. An input abort never reaches the model.
- **`warn(message, detail?)`** → non-blocking; the run continues.

## Deterministic in-tree processors

No LLM, no external service:

| Processor | What it does |
| --- | --- |
| `UnicodeNormalizer.create({ stripControlChars?, collapseWhitespace? })` | Unicode NFC + optional control-char strip / whitespace collapse. |
| `TokenLimiter.create({ limit, strategy? })` | Char-based token estimate (`estimateTokens` is exported); `truncate` cuts to fit, `block` aborts. Caps input or output by placement. |

## LLM-classifier processors — delegated

Moderation / PII / prompt-injection / language classifiers are **not** in core (they churn; the seam
does not). Build them on the same `Processor` seam using a specialist library, or your own model
call. See the SDK's guardrails guide + example for the paved path (the same rationale as
provider-auth delegation).

## Caveats

- **Streaming output redaction** — `processOutput` runs on the buffered `wait()` path in v1; a
  token-stream redaction seam is deferred. Redact on `wait()`, or gate the stream at your UI.
- **Cloud** — cloud agents reject processors: function handlers don't serialize across the network.
  Guardrails are a local-runtime feature.

## Reference

- [`Processor`](/theokit/reference/Processor) · [`ProcessorViolation`](/theokit/reference/ProcessorViolation) · [`TokenLimiter`](/theokit/reference/TokenLimiter) · [`UnicodeNormalizer`](/theokit/reference/UnicodeNormalizer)

---

# Block a message

Source: https://docs.usetheo.dev/theokit/guardrails/block-a-message

Add an input processor that aborts the run with a tripwire when the message violates a policy — before the model is called.

# Block a message

An `inputProcessor` runs before the LLM. Call `ctx.abort(reason)` and the run stops with a
**tripwire** — no provider call is made, and `RunResult.tripwire` carries the reason.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  inputProcessors: [
    {
      id: "no-secrets",
      processInput: (ctx) => {
        if (/password/i.test(ctx.message)) ctx.abort("blocked: message mentions a password");
      },
    },
  ],
});

const result = await (await agent.send("What is my password?")).wait();

console.log("status:", result.status);
console.log("tripwire:", JSON.stringify(result.tripwire));

await agent.dispose();
```

## Output

Deterministic — the processor aborts before the model is ever called:

```text
status: cancelled
tripwire: {"reason":"blocked: message mentions a password","processorId":"no-secrets"}
```

## What it shows

- **`inputProcessors`** run in order, before the LLM. `ctx.message` is the user text.
- **`ctx.abort(reason)`** stops the run with a tripwire: `status: "cancelled"`, and
  `result.tripwire = { reason, processorId }`. No provider call — cheap and fail-closed.
- Swap `abort` for **`ctx.warn(...)`** to log a non-blocking violation and let the run continue, or
  add a **`processOutput`** to redact the model's reply on the way out.

## Example

Full runnable source:
[`examples/guardrails-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/guardrails-basics).

---

# Overview

Source: https://docs.usetheo.dev/theokit/guardrails

Normalize, validate, block, or redact the user message and the model's reply with an ordered pipeline of processors.

# Guardrails

A **processor** runs on the way in (before the model) or on the way out (before the caller). Use
them to normalize input, block a policy violation, or redact the model's reply — an ordered pipeline
you control.

```ts
await Agent.create({
  apiKey, model,
  inputProcessors: [ /* run before the LLM */ ],
  outputProcessors: [ /* run on the model's reply */ ],
});
```

## A processor

```ts
interface Processor {
  id: string;                              // surfaced on violations + tripwires
  processInput?(ctx): string | void;       // transform/block the user message
  processOutput?(ctx): string | void;      // transform/redact the model's reply
  onViolation?(violation): void;           // fires on abort() and warn()
}
```

Return a (rewritten) string to transform; return nothing to leave the payload unchanged.

## Two controls

Every processor context carries:

- **`ctx.abort(reason)`** — stop the run **immediately** with a tripwire. `RunResult.status` becomes
  `"cancelled"` and `RunResult.tripwire` carries `{ reason, processorId }`. An input `abort` never
  reaches the model.
- **`ctx.warn(message, detail?)`** — report a **non-blocking** violation (fires `onViolation`); the
  run continues.

## Built-in, deterministic processors

No LLM required:

- **`UnicodeNormalizer.create({ … })`** — Unicode NFC + optional control-char strip / whitespace collapse.
- **`TokenLimiter.create({ limit, strategy? })`** — cap input or output size (`truncate` or `block`).

## LLM-classifier guardrails

Moderation, PII, and prompt-injection classifiers are **not** shipped in core — they churn and belong
to specialist libraries. Build them on this same seam (a processor that calls a classifier) — the SDK
ships the paved path and a recommendation rather than a bundled, stale classifier.

## Next

- [Block a message](/theokit/guardrails/block-a-message) — a runnable tripwire example.
- [Advanced](/theokit/guardrails/advanced) — the full contexts, violations, deterministic processors, and streaming.

## Reference

- [`Processor`](/theokit/reference/Processor) · [`ProcessorViolation`](/theokit/reference/ProcessorViolation) · [`TokenLimiter`](/theokit/reference/TokenLimiter)

---

# abort-mid-stream

Source: https://docs.usetheo.dev/theokit/guides/abort-mid-stream

Demonstrates `AbortSignal` end-to-end propagation: caller's signal stops upstream token billing mid-stream.

# abort-mid-stream

Demonstrates `AbortSignal` end-to-end propagation: caller's signal stops upstream token billing mid-stream.

## Run

```bash
# Fixture mode (validates wiring):
pnpm run

# Real LLM (actual token-billing stop visible in OpenRouter dashboard):
OPENROUTER_API_KEY=sk-or-... pnpm run
```

## What it shows

1. **Pre-aborted signal:** `controller.abort()` before send; signal flows to `fetch({ signal })` at LLM client level.
2. **Mid-stream abort (real LLM only):** start a long generation, abort after 200ms; `AgentRunError({ code: "aborted", retriable: false })` thrown, partial assistant message NOT persisted (D320).
3. **`agent.dispose()` lifecycle abort:** the agent owns a `#lifecycleAbortController` that fires on dispose, canceling in-flight sends. Dispose is idempotent (D5).

## Edge runtimes

The SDK ships `anySignal` ponyfill (D324) so `AbortSignal.any` semantics work on Vercel Edge subsets that lack the native method. See `docs.md` "Cancellation" section.

## Code

```ts title="run.ts"
/**
 * Production-Readiness #5 — AbortSignal end-to-end example.
 *
 * Demonstrates:
 * - Pass AbortSignal to agent.send via SendOptions.signal
 * - Compose user signal with timeout via anySignal-equivalent
 * - Agent.dispose() also aborts in-flight sends (lifecycle controller)
 *
 * To run with a real LLM (recommended to see actual token-billing stop):
 *   OPENROUTER_API_KEY=sk-or-... pnpm run
 */

import { Agent, AgentRunError } from "@theokit/sdk";

const apiKey = process.env.OPENROUTER_API_KEY ?? "theo_test_abort_example";
const realLlm = apiKey.startsWith("sk-or-");

console.log(`\n== AbortSignal end-to-end example ==`);
console.log(realLlm ? "Mode: real OpenRouter" : "Mode: fixture (no LLM call)");
console.log();

const providers = realLlm
  ? {
      routes: [{ capability: "chat" as const, provider: "openrouter" }],
      fallback: ["openrouter"],
    }
  : undefined;

// ── 1. Pre-aborted signal — send never even hits the LLM ────────────────
const ctrl1 = new AbortController();
ctrl1.abort("pre-aborted before send");

const agent1 = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd() },
  ...(providers !== undefined ? { providers } : {}),
});

try {
  await agent1.send("Reply with: this never runs", { signal: ctrl1.signal });
  // Fixture mode short-circuits before checking signal in production path,
  // so this is reachable. With real LLM, the loop catches abort early.
  console.log(`[1] Send completed (fixture mode short-circuit)`);
} catch (err) {
  if (err instanceof AgentRunError && err.code === "aborted") {
    console.log(`[1] ✓ Pre-aborted send threw AgentRunError(code="aborted")`);
  } else {
    console.log(`[1] Unexpected error:`, err);
  }
}
await agent1.dispose();

// ── 2. Mid-flight abort (real LLM only) ──────────────────────────────────
if (realLlm) {
  const ctrl2 = new AbortController();
  const agent2 = await Agent.create({
    apiKey,
    model: { id: "openai/gpt-4o-mini" },
    local: { cwd: process.cwd() },
    ...(providers !== undefined ? { providers } : {}),
  });
  // Abort BEFORE the send fires so we get a deterministic aborted result
  // (the SDK contract: ctrl2.signal.aborted === true at the moment streamLlmTurn
  // runs → fetch throws AbortError → run.wait returns status=error with code=aborted).
  console.log(`[2] Aborting BEFORE send to deterministically exercise the path…`);
  ctrl2.abort("user clicked stop");
  try {
    const run = await agent2.send("Write a long essay about jazz", {
      signal: ctrl2.signal,
    });
    // Consume the stream defensively.
    for await (const _ of run.stream()) {
      void _;
    }
    const result = await run.wait();
    if (result.status === "error" && result.error?.code === "aborted") {
      console.log(`[2] ✓ Run aborted with explicit AgentRunError code="aborted"`);
    } else if (result.status === "error") {
      // The loop's collector detected signal.aborted and surfaced via
      // status=error + [aborted] marker in events. Provider request was
      // cancelled at fetch level — no more token billing.
      console.log(`[2] ✓ Run terminated via abort path (status=error)`);
    } else {
      console.log(`[2] Run ended with status=${result.status}`);
    }
  } catch (err) {
    if (err instanceof AgentRunError && err.code === "aborted") {
      console.log(`[2] ✓ Aborted send threw AgentRunError(code="aborted")`);
    } else if (err instanceof Error) {
      console.log(`[2] Caught error: ${err.message.slice(0, 100)}`);
    } else {
      throw err;
    }
  }
  await agent2.dispose();
} else {
  console.log(`[2] Skipping mid-flight abort (no OPENROUTER_API_KEY set)`);
}

// ── 3. Dispose triggers lifecycle abort ──────────────────────────────────
const agent3 = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd() },
  ...(providers !== undefined ? { providers } : {}),
});
console.log(`[3] Disposing agent (lifecycle abort fires)…`);
await agent3.dispose();
console.log(`[3] ✓ Dispose completed — second call is idempotent:`);
await agent3.dispose();
console.log(`[3] ✓ Second dispose returned without error`);

console.log();
console.log(`Done. See docs.md "Cancellation" section for the full contract.`);

```

## Run

```bash
cd examples/abort-mid-stream
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/abort-mid-stream](https://github.com/usetheodev/theokit-sdk/tree/main/examples/abort-mid-stream)

---

# acp-server

Source: https://docs.usetheo.dev/theokit/guides/acp-server

Minimal `@theokit/acp` example: default-exports a per-session factory that creates a fresh `Agent` per ACP session.

# acp-server

Minimal `@theokit/acp` example: default-exports a per-session factory that creates a fresh `Agent` per ACP session.

## Run

### Local (manual, for testing)

```bash
# Install
pnpm install

# Set provider key
export OPENROUTER_API_KEY=sk-or-...

# Start the ACP server (stdin/stdout become the JSON-RPC channel)
pnpm serve
# OR explicitly:
npx theokit-acp --entry ./src/index.ts
```

The server will block reading from stdin. To talk to it manually, you need to send valid ACP `initialize` JSON-RPC frames. The realistic path is to point a host (Zed/Cursor) at it.

### Zed integration

```bash
mkdir -p ~/.config/zed/external_agents/usetheo-sdk
cp ../../packages/acp/registry/agent.json ~/.config/zed/external_agents/usetheo-sdk/
cp ../../packages/acp/registry/icon.svg ~/.config/zed/external_agents/usetheo-sdk/
```

Edit the `distribution.args` in the copied `agent.json` to point at this example's entry:

```json
{
  "distribution": {
    "type": "command",
    "command": "npx",
    "args": ["theokit-acp", "--entry", "/absolute/path/to/examples/acp-server/src/index.ts"],
    "env": { "OPENROUTER_API_KEY": "sk-or-..." }
  }
}
```

Restart Zed. Open External Agents → `Theokit SDK` should appear. Send a prompt.

## What it does

- ACP `new_session` → `Agent.create({ apiKey, model, local: { cwd } })` per session.
- ACP `prompt` → `agent.send(text).stream()` translated into ACP `agent_message_chunk` notifications.
- ACP `cancel` → fires the session's `AbortController`.
- Tool permissions → default `ask` mode prompts Zed UI; `--permission auto` to disable.

## Permissions

Default is `ask`. To trust the read-only tools and only prompt for writes:

```bash
npx theokit-acp --entry ./src/index.ts --trusted-tools read_file,list_dir,git_diff,search_text
```

## Notes

- Per `.claude/rules/real-llm-validation.md`, this example REQUIRES a real provider key. Fixture mode is not a valid dogfood substitute.
- Set `ACP_EXAMPLE_MODEL` to override the default model.

## Code

```ts title="src/index.ts"
/**
 * Minimal ACP server entry point. Default-exports a factory: ACP host
 * spawns one process per session and calls `factory(sessionId)` to get a
 * fresh `SDKAgent` for each session (D351 — per-session isolation).
 *
 * Provider precedence:
 *   1. `OPENROUTER_API_KEY` → openrouter/<model> (default `openai/gpt-4o-mini`)
 *   2. else falls through to Ollama at `OLLAMA_HOST` (default `localhost:11434`)
 *      with `ACP_OLLAMA_MODEL` (default `qwen2.5:3b`)
 *
 * Override either via env: `ACP_EXAMPLE_MODEL`, `ACP_OLLAMA_MODEL`, `OLLAMA_HOST`.
 */

import { Agent, type SDKAgent } from "@theokit/sdk";

export default async function createAgentForSession(sessionId: string): Promise<SDKAgent> {
  const openrouterKey = process.env.OPENROUTER_API_KEY;
  if (typeof openrouterKey === "string" && openrouterKey.length > 0) {
    return Agent.create({
      apiKey: openrouterKey,
      model: { id: process.env.ACP_EXAMPLE_MODEL ?? "openai/gpt-4o-mini" },
      providers: {
        routes: [{ capability: "chat", provider: "openrouter" }],
        fallback: ["openrouter"],
      },
      local: { cwd: process.cwd() },
      name: `acp-${sessionId}`,
    });
  }

  // Ollama fallback — 100% local, no remote provider needed.
  const ollamaModel = process.env.ACP_OLLAMA_MODEL ?? "qwen2.5:3b";
  return Agent.create({
    apiKey: "local",
    model: { id: `ollama/${ollamaModel}` },
    local: { cwd: process.cwd() },
    name: `acp-${sessionId}`,
  });
}

```

## Run

```bash
cd examples/acp-server
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/acp-server](https://github.com/usetheodev/theokit-sdk/tree/main/examples/acp-server)

---

# agent-basics

Source: https://docs.usetheo.dev/theokit/guides/agent-basics

The smallest end-to-end path with `@theokit/sdk`: create a local agent against

# agent-basics

The smallest end-to-end path with `@theokit/sdk`: create a local agent against
your own provider key, send one message, await the result, dispose.

Pairs with the docs page **[Agents › Creating an agent](https://docs.usetheo.dev/theokit/agents)**.

## Run

```bash
pnpm install
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys — or put it in .env
pnpm run run
```

## What it shows

- `Agent.create({ apiKey, model, name, systemPrompt })` — the canonical factory.
- `agent.send(message)` → `Run`; `await run.wait()` → `RunResult`.
- `result.result` (text), `result.status`, `result.model`, and typed `result.error`.
- `agent.dispose()` for resource cleanup.

## Code

```ts title="run.ts"
/**
 * Agents — creating and running an agent (features/agents).
 *
 * The smallest end-to-end path: create a local agent against your own provider
 * key, send one message, await the full result, dispose.
 *
 * Run:
 *   pnpm install
 *   export OPENROUTER_API_KEY=sk-or-...   # or put it in .env
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  name: "explainer-bot",
  systemPrompt: "You are a concise assistant. Answer in at most two sentences.",
  // Local runtime, no sandbox — runs inline in this Node process.
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
});

const run = await agent.send("What is an AI agent? Answer for a developer.");
const result = await run.wait();

console.log("Status:", result.status);
console.log("Model: ", result.model);
console.log("Reply: ", result.result);

await agent.dispose();

// Validate: a run that did not finish (auth, rate-limit, model error) is a failure, not a green run.
if (result.status !== "finished" || typeof result.result !== "string" || result.result.length === 0) {
  console.error("run did not finish:", JSON.stringify(result.error ?? result.status));
  process.exit(1);
}

```

## Run

```bash
cd examples/agent-basics
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/agent-basics](https://github.com/usetheodev/theokit-sdk/tree/main/examples/agent-basics)

---

# agent-streaming

Source: https://docs.usetheo.dev/theokit/guides/agent-streaming

Iterate `run.stream()` to consume `SDKMessage` events as they arrive, instead of

# agent-streaming

Iterate `run.stream()` to consume `SDKMessage` events as they arrive, instead of
awaiting the whole result.

Pairs with the docs page **[Agents › Streaming](https://docs.usetheo.dev/theokit/agents/streaming)**.

## Run

```bash
pnpm install
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys — or put it in .env
pnpm run run
```

## What it shows

- `run.stream()` yields a discriminated union of full `SDKMessage` events:
  `system` | `user` | `assistant` | `tool_call` | `thinking` | `status` | …
- `assistant` messages carry `.message.content` as `text` / `tool_use` blocks.
- `run.wait()` after the stream drains resolves to the terminal `RunResult`.

## Code

```ts title="run.ts"
/**
 * Agents — streaming a run (features/agents/streaming).
 *
 * `agent.send()` returns a `Run`. Instead of `await run.wait()` for the whole
 * result, iterate `run.stream()` to consume `SDKMessage` events as they arrive.
 * The stream is a discriminated union of full messages:
 *   - "system"    — run init metadata
 *   - "user"      — the submitted message, echoed back
 *   - "assistant" — model output; `.message.content` is (text | tool_use) blocks
 *   - "tool_call" — a tool the model invoked
 *   - "thinking"  — reasoning content (when the model emits it)
 *
 * Run:
 *   pnpm install
 *   export OPENROUTER_API_KEY=sk-or-...   # or put it in .env
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  name: "streamer-bot",
  systemPrompt: "You are a concise storyteller.",
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
});

const run = await agent.send("Tell me a two-sentence story about a curious robot.");

for await (const msg of run.stream()) {
  switch (msg.type) {
    case "assistant":
      for (const block of msg.message.content) {
        if (block.type === "text") process.stdout.write(block.text);
        else if (block.type === "tool_use") console.log(`\n[tool_use] ${block.name}`);
      }
      break;
    case "tool_call":
      console.log(`\n[calling tool] ${msg.name}`);
      break;
    default:
      // "system" | "user" | "thinking" | "status" | … — ignored here.
      break;
  }
}

// After the stream drains, wait() resolves to the terminal RunResult.
const result = await run.wait();
console.log(`\n\n[done] status=${result.status}`);

await agent.dispose();

// --- validate output (fail loud) ---
if (result.status !== "finished" || typeof result.result !== "string" || result.result.length === 0) {
  console.error("run did not finish:", JSON.stringify(result.error ?? result.status));
  process.exit(1);
}

```

## Run

```bash
cd examples/agent-streaming
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/agent-streaming](https://github.com/usetheodev/theokit-sdk/tree/main/examples/agent-streaming)

---

# agent-structured-output

Source: https://docs.usetheo.dev/theokit/guides/agent-structured-output

Coerce an agent's final answer into a validated, inferred-typed object with a Zod

# agent-structured-output

Coerce an agent's final answer into a validated, inferred-typed object with a Zod
schema via `agent.generate(message, { output: schema })`.

Pairs with the docs page **[Agents › Structured output](https://docs.usetheo.dev/theokit/agents/structured-output)**.

## Run

```bash
pnpm install
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys — or put it in .env
pnpm run run
```

## What it shows

- `agent.generate(message, { output: zodSchema })` → `{ object, result, raw, usage }`.
- `object` is typed from the schema (no manual JSON parsing, no casts).
- The SDK forces a single synthetic tool whose schema IS your Zod schema (ADR D33),
  then Zod-validates the model's output.

## Code

```ts title="run.ts"
/**
 * Agents — structured output (features/agents/structured-output).
 *
 * `agent.generate(message, { output: schema })` runs the normal tool loop, then
 * coerces the final answer into your Zod schema and returns a validated,
 * inferred-typed object. Under the hood the SDK forces a single synthetic tool
 * whose schema IS your Zod schema (ADR D33), then Zod-parses the result.
 *
 * Run:
 *   pnpm install
 *   export OPENROUTER_API_KEY=sk-or-...   # or put it in .env
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";
import { z } from "zod";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

const Sentiment = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  score: z.number().min(0).max(1).describe("Confidence between 0 and 1."),
  summary: z.string().describe("One short sentence summarizing the review."),
});

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  name: "review-analyzer",
  systemPrompt: "You analyze product reviews and return structured sentiment.",
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
});

const { object } = await agent.generate(
  "Review: 'The battery lasts two days and the screen is gorgeous, but it's pricey.'",
  { output: Sentiment },
);

// `object` is typed as { sentiment: "positive" | "neutral" | "negative"; score: number; summary: string }
console.log("sentiment:", object.sentiment);
console.log("score:    ", object.score);
console.log("summary:  ", object.summary);

await agent.dispose();

// --- validate output (fail loud) ---
if (!object || typeof object.sentiment !== "string") {
  console.error("structured output missing sentiment:", JSON.stringify(object));
  process.exit(1);
}

```

## Run

```bash
cd examples/agent-structured-output
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/agent-structured-output](https://github.com/usetheodev/theokit-sdk/tree/main/examples/agent-structured-output)

---

# bedrock-bot

Source: https://docs.usetheo.dev/theokit/guides/bedrock-bot

One-shot Claude prompt via AWS Bedrock (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-D302).

# bedrock-bot

One-shot Claude prompt via AWS Bedrock (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-D302).

## Setup

1. Enable Bedrock model access in your AWS account: [https://console.aws.amazon.com/bedrock/home](https://console.aws.amazon.com/bedrock/home) → "Model access" → request Anthropic models.
2. Generate a Bearer token (one of three paths):
   - **Short-term, AWS Console:** IAM → Users → your user → "Security credentials" → "Bedrock API keys" → "Generate API key" (≤12h TTL).
   - **Long-term via CLI:**
     ```bash
     aws iam create-service-specific-credential --service-name bedrock.amazonaws.com
     ```
     (only for exploration — AWS docs warn against long-term keys in prod).
   - **Auto-refresh via peer dep:**
     ```bash
     pnpm add @aws/bedrock-token-generator
     ```
     Then the SDK refreshes short-term tokens automatically (D287).
3. Copy `.env.example` to `.env` and fill `AWS_BEARER_TOKEN_BEDROCK`.

## Run

```bash
cp .env.example .env
# fill AWS_BEARER_TOKEN_BEDROCK
pnpm install
pnpm run run                           # default question: "Qual é a capital do Brasil?"
pnpm run run "What's 2+2?"             # custom question
```

## Model IDs

Format: `bedrock/{regionPrefix}.anthropic.{model}-v{N}:{rev}`.

Examples:
- `bedrock/us.anthropic.claude-sonnet-4-5-v1:0` — US-region
- `bedrock/eu.anthropic.claude-sonnet-4-5-v1:0` — EU region (different inference profile)
- `bedrock/global.anthropic.claude-opus-4-7-v1:0` — cross-region routed

See [AWS docs](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) for the full list per region.

## v1 limitations (documented)

- **Non-streaming only** (D302) — the full response arrives at once; chat UX with token-by-token rendering needs v1.x or the escape hatch via `@aws-sdk/client-bedrock-runtime`.
- **Bearer auth only** (D286) — no SigV4 in v1 (D298). Customers in IAM-role-only environments wait for v1.x.
- **InvokeModel only** (D289) — Converse API deferred. Preserves Anthropic prompt-caching + extended-thinking fields.
- **Claude only** — Llama / Cohere / Mistral via Bedrock Converse deferred (D296).
- **Bearer auth doesn't cover** Bedrock Agents / Knowledge Bases / Computer Use (D282-style escape hatch via `adapter.getApp()` not yet wired here).

## Code

```ts title="run.ts"
/**
 * AWS Bedrock demo (Adoption Roadmap #8; ADRs D286-D302).
 *
 * Sends a one-shot prompt to Claude on Bedrock and prints the reply.
 * Uses Bearer auth (no SigV4). Non-streaming in v1 (D302).
 *
 * Run:
 *   cp .env.example .env  # fill AWS_BEARER_TOKEN_BEDROCK
 *   pnpm install
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";

const token = process.env.AWS_BEARER_TOKEN_BEDROCK;
const modelId =
  process.env.BEDROCK_MODEL ?? "bedrock/us.anthropic.claude-sonnet-4-5-v1:0";

if (token === undefined || token.length === 0) {
  console.log(
    "[bedrock] AWS_BEARER_TOKEN_BEDROCK not set — SDK will auto-generate " +
      "via @aws/bedrock-token-generator + standard AWS credential chain.",
  );
}

const agent = await Agent.create({
  apiKey: token ?? "__bedrock_lazy_token__",
  model: { id: modelId },
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
  name: "bedrock-bot",
  systemPrompt: "You are a concise assistant. Reply in one short sentence.",
});

const question = process.argv[2] ?? "Qual é a capital do Brasil?";
console.log(`[bedrock] model=${modelId} question="${question}"`);

const run = await agent.send(question);
const result = await run.wait();
const errInfo = (result as { error?: { name?: string; message?: string; metadata?: unknown } }).error;
console.log(`[bedrock] status=${result.status} resultLen=${(result.result ?? "").length}`);
if (errInfo !== undefined) {
  console.log(`[bedrock] error.name=${errInfo.name}`);
  console.log(`[bedrock] error.message=${errInfo.message}`);
  console.log(`[bedrock] error.metadata=${JSON.stringify(errInfo.metadata, null, 2)}`);
}
console.log(result.result ?? "(no reply)");

await agent.dispose();

```

## Run

```bash
cd examples/bedrock-bot
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/bedrock-bot](https://github.com/usetheodev/theokit-sdk/tree/main/examples/bedrock-bot)

---

# cache

Source: https://docs.usetheo.dev/theokit/guides/cache

Demonstrates `Cache.semantic` + `Cache.consult` (Adoption Roadmap #6; ADRs D249-D266).

# cache

Demonstrates `Cache.semantic` + `Cache.consult` (Adoption Roadmap #6; ADRs D249-D266).

## Run (OpenRouter cloud)

```bash
export OPENROUTER_API_KEY=sk-or-...
pnpm install
pnpm run run
```

## What it shows

- `Cache.semantic({ embedder, threshold, ttl, namespace })` factory.
- `cache.consult(prompt)` — direct lookup with `hit: boolean` outcome + `source: "kv" | "semantic"`.
- `cache.remember(prompt, response)` — explicit store after dispatching the LLM yourself.
- `ttl.exclude` regex — time-sensitive prompts (weather, today, now) bypass cache.
- `cache.stats()` — kvHits / semanticHits / misses / excluded counters.

## v1 limitations (documented)

- **Plugin mode provides recall + context inject** — the LLM is still called on hit and pre-loaded with the cached answer. For true short-circuit (skip the LLM call entirely), use `cache.consult()` directly and dispatch your own LLM call only on miss (the demo shows this pattern).
- **No streaming cache** (D256) — only `agent.send` is cached, not `agent.stream`.
- **No adaptive threshold per entry** (D254) — single global threshold; tune via `Cache.semantic({ threshold: 0.95 })` for high-stakes scenarios.
- **No tool-use cache** (D266 / EC-10) — runs that invoked tools are NEVER cached (replay would lose side-effects).
- **Embedder change invalidates** (D258) — `embedder.id` is part of the cache key.

## Pairing with Anthropic prompt_caching (D263)

Cache.semantic resolves paraphrases BEFORE the LLM. Anthropic prompt_caching gives 90%
discount on prefix-identical input AFTER hitting the LLM. They're orthogonal — use both
for compound savings (~95% in ideal workloads):

```
[user query] → Cache.semantic hit? → return cached
              → miss → LLM call with cache_control on system/tools (90% discount)
```

## Code

```ts title="run.ts"
/**
 * Semantic Cache demo (Adoption Roadmap #6; ADRs D249-D266).
 *
 * Shows:
 *   1. First query: miss → LLM called → cache.remember stores it
 *   2. Paraphrase: semantic hit (no LLM call needed via consult())
 *   3. Time-sensitive query: bypassed via exclude regex
 *   4. Stats summary
 *
 * Run:
 *   export OPENROUTER_API_KEY=sk-or-...
 *   pnpm install
 *   pnpm run run
 */

import { Agent, Cache } from "@theokit/sdk";

const OPENROUTER = process.env.OPENROUTER_API_KEY;
if (OPENROUTER === undefined || OPENROUTER.length === 0) {
  console.error("OPENROUTER_API_KEY missing — see .env.example");
  process.exit(1);
}

// A deterministic toy embedder for the demo (avoids spending OpenAI tokens
// on every prompt — production users plug a real EmbeddingRuntime here).
const toyEmbedder = {
  id: "toy-letter",
  model: "letter-bag-1",
  dimension: 26,
  async embed(texts: ReadonlyArray<string>): Promise<number[][]> {
    return texts.map((t) => {
      const v = new Array(26).fill(0);
      const norm = t.toLowerCase().replace(/[^a-z]/g, "");
      for (const ch of norm) {
        const i = ch.charCodeAt(0) - 97;
        if (i >= 0 && i < 26) v[i] += 1;
      }
      const sum = v.reduce((a, b) => a + b, 0) || 1;
      return v.map((x) => x / sum);
    });
  },
};

async function main(): Promise<void> {
  const cache = Cache.semantic({
    embedder: toyEmbedder,
    threshold: 0.4,
    ttl: {
      default: process.env.CACHE_TTL ?? "1h",
      exclude: /\b(weather|today|now|current|stock)\b/i,
    },
    namespace: "demo",
    modelId: "openai/gpt-4o-mini",
  });

  const agent = await Agent.create({
    apiKey: OPENROUTER,
    model: { id: "openai/gpt-4o-mini" },
    local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
    name: "demo-agent",
    plugins: [cache.asPlugin()],
  });

  console.log("\n=== Query 1: 'What is the capital of France?' (miss expected) ===");
  const t1 = Date.now();
  const m1 = await cache.consult("What is the capital of France?");
  if (m1.hit) {
    console.log("(unexpected hit)", m1.response.slice(0, 80));
  } else {
    const r1 = await agent.send("What is the capital of France? Answer in one short sentence.");
    const result1 = await r1.wait();
    const text = result1.status === "finished" ? (result1.result ?? "") : "";
    await cache.remember("What is the capital of France?", text);
    console.log("LLM:", text.slice(0, 200));
  }
  console.log("Elapsed:", Date.now() - t1, "ms");

  console.log("\n=== Query 2: 'Tell me the capital city of France' (semantic hit expected) ===");
  const t2 = Date.now();
  const m2 = await cache.consult("Tell me the capital city of France");
  if (m2.hit) {
    console.log("CACHE HIT (", m2.source, ", dist=", m2.distance, ")");
    console.log("Cached:", m2.response.slice(0, 200));
  } else {
    console.log("(unexpected miss)");
  }
  console.log("Elapsed:", Date.now() - t2, "ms");

  console.log("\n=== Query 3: 'What is the weather in SF today?' (excluded by regex) ===");
  const t3 = Date.now();
  const m3 = await cache.consult("What is the weather in SF today?");
  console.log("hit:", m3.hit, "(should always be false due to exclude regex)");
  console.log("Elapsed:", Date.now() - t3, "ms");

  const s = cache.stats();
  console.log("\n=== Stats ===");
  console.log(
    `entries=${s.entries} kvHits=${s.kvHits} semanticHits=${s.semanticHits} misses=${s.misses} excluded=${s.excluded} evicted=${s.evicted} embedderFailures=${s.embedderFailures}`,
  );

  await agent.dispose();
}

main().catch((err) => {
  console.error("cache demo failed:", err);
  process.exit(1);
});

```

## Run

```bash
cd examples/cache
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/cache](https://github.com/usetheodev/theokit-sdk/tree/main/examples/cache)

---

# Session persistence

Source: https://docs.usetheo.dev/theokit/guides/conversation-storage

How a local agent's conversation persists in v4.0 — the native transcript on disk, with no pluggable adapter.

# Session persistence

In v4.0 a local agent's conversation persists as a **native Claude Code `.jsonl` transcript on
disk** — the file *is* the store. There is no pluggable `ConversationStorageAdapter` and no
session-metadata surface: the transcript is the single source of truth.

The transcript lands at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`, where `baseDir` comes
from `local.baseDir` (default `~/.theokit`; set `~/.claude` for Claude Code CLI `--continue`
interop). Each send appends the whole turn as native records, append-only, with secrets redacted
before disk.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const cwd = process.cwd();
const agentId = `agent-${Date.now().toString(36)}`;

// 1. Create + send — the transcript is written under ~/.theokit by default.
const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  agentId,
  local: { cwd, baseDir: "~/.theokit" },
});
await (await agent.send("Remember my favorite color is teal. Reply with: OK.")).wait();
await agent.dispose();

// 2. Resume the SAME agentId — the transcript rehydrates the conversation.
const resumed = await Agent.resume(agentId, { local: { cwd, baseDir: "~/.theokit" } });
await (await resumed.send("What is my favorite color?")).wait();
await resumed.dispose();
```

## Multi-host persistence

Because the transcript is a plain file tree, sharing it across hosts is a filesystem concern, not an
SDK adapter: point every host at a **shared `baseDir`** (a network mount), or **replicate the
transcript directory** between hosts. There is no Postgres/Redis/Durable-Object adapter today —
custom backends are out until an adapter contract over the native format ships.

## See also

- [Sessions overview](/theokit/sessions) — the native transcript model and where it lives.
- [Resume a session](/theokit/sessions/manage-sessions) — a runnable resume + `--continue` example.
- [Advanced sessions](/theokit/sessions/advanced) — the record shape, scoped ids, and CLI interop.

---

# custom-provider

Source: https://docs.usetheo.dev/theokit/guides/custom-provider

Register a custom OpenAI-/Anthropic-compatible LLM provider with `defineProvider`

# custom-provider

Register a custom OpenAI-/Anthropic-compatible LLM provider with `defineProvider`
and route to it — no fork required.

```bash
pnpm install
pnpm run                       # registration + routing only (no LLM call)
GROQ_API_KEY=gsk_... pnpm run  # performs a live send through Groq
```

What it shows:

- A `ProviderProfile` is **data only** — declare name, `apiMode` (HTTP dialect),
  auth, base URL, fallback models.
- `defineProvider(profile)` returns a `kind: "model-provider"` plugin (mirrors
  `defineTool` / `definePlugin`).
- Pass it to `Agent.create({ plugins: [...] })` and route via the `provider/model`
  id prefix (`groq/llama-3.1-8b-instant`).

See the "Custom providers (`defineProvider`)" section in `docs.md` for the full
`ProviderProfile` field reference and the supported `apiMode` values.

## Code

```ts title="run.ts"
/**
 * Custom LLM provider via `Provider.create`.
 *
 * Demonstrates:
 * - Declare a `ProviderProfile` for any OpenAI-compatible endpoint (here: Groq).
 * - Build a `kind: "model-provider"` plugin with `Provider.create`.
 * - Route to it via the `provider/model` id prefix on `Agent.create`.
 *
 * Real-LLM validation (per .claude/rules/real-llm-validation.md):
 *   The custom-provider REGISTRATION + ROUTING is demonstrated without a live
 *   call (no key needed). To actually send, set a real Groq key:
 *     GROQ_API_KEY=gsk_... pnpm run
 */

import { Agent, Provider } from "@theokit/sdk";

const groqKey = process.env.GROQ_API_KEY;
const realLlm = typeof groqKey === "string" && groqKey.startsWith("gsk_");

console.log("\n== Custom provider via Provider.create ==");
console.log(realLlm ? "Mode: real Groq call" : "Mode: registration/routing only (no key)");

// 1. Declare the provider — data only. OpenAI-compatible → apiMode "chat_completions".
const groq = Provider.create({
  name: "groq",
  apiMode: "chat_completions",
  authType: realLlm ? "api_key" : "none",
  envVars: ["GROQ_API_KEY"],
  baseUrl: "https://api.groq.com/openai/v1",
  fallbackModels: ["groq/llama-3.1-8b-instant"],
  aliases: ["groq-cloud"],
});

console.log(`Provider plugin: name=${groq.name} kind=${groq.kind}`);

// 2. Create an agent routed to the custom provider via the `groq/...` id prefix.
const agent = await Agent.create({
  model: { id: "groq/llama-3.1-8b-instant" },
  plugins: [groq],
});

console.log(`Agent created (id=${agent.id}) routing to the custom provider.`);

if (realLlm) {
  const run = await agent.send("Reply with exactly: custom provider works");
  const result = await run.wait();
  console.log(`status=${result.status}`);
  console.log(`reply=${result.result ?? "(none)"}`);
} else {
  console.log("Set GROQ_API_KEY=gsk_... to perform a live send.");
}

await agent.dispose();
console.log("Done.\n");

```

## Run

```bash
cd examples/custom-provider
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/custom-provider](https://github.com/usetheodev/theokit-sdk/tree/main/examples/custom-provider)

---

# eval

Source: https://docs.usetheo.dev/theokit/guides/eval

Runs `Eval.create / .run` against a real LLM and prints aggregate +

# eval

Runs `Eval.create / .run` against a real LLM and prints aggregate +
per-row results.

## Run (Ollama, no API keys)

```bash
ollama serve &
ollama pull llama3.2:3b
pnpm install
pnpm run run
```

## Run (OpenRouter cloud)

```bash
export OPENROUTER_API_KEY=sk-or-...
pnpm run run
```

## What it shows

- `Eval.create({...}).run()` returns a populated `EvalRun` shape (D202, D209)
- `Scorers.containsExpected()` + `Scorers.regex()` applied to each row
- Aggregate includes `meanScore`, `passRatio`, `errorRows`, `tokensInTotal`,
  `durationMsP50`, `durationMsP95` (D211)
- v1 scale: keep datasets ≤ 10k rows (EC-11 — v1 materializes the dataset
  in memory; partition manually for larger evals or wait for streaming v2)

## LLM-as-judge

For subjective scoring, swap the second scorer:

```ts
Scorers.llmJudge({
  model: { id: "openai/gpt-4o-mini" },
  apiKey: process.env.OPENROUTER_JUDGE_KEY ?? process.env.OPENROUTER_API_KEY ?? "",
  criteria: "The answer is concise and accurate.",
  rubric: "continuous",
}),
```

**Cost note (EC-12):** `llmJudge` doubles the per-row LLM cost. For
1000 rows × `gpt-4o-mini`, expect ~$1.50 (eval) + ~$1.50 (judge) = $3.00.
The `aggregate.tokensInTotal` only reflects the EVAL agent's tokens, not
the judge's — forecast accordingly.

## Code

```ts title="run.ts"
/**
 * Example: `Eval.create / .run` against a real LLM.
 *
 *   pnpm install
 *   ollama serve & ollama pull llama3.2:3b
 *   pnpm run run
 *
 * Or with cloud:
 *   OPENROUTER_API_KEY=... pnpm run run
 *
 * Prints the EvalRun JSON (aggregate + rows) to stdout.
 */

import { Eval, Scorers, type EvalRun } from "@theokit/sdk/eval";

const useCloud = typeof process.env.OPENROUTER_API_KEY === "string";

const agent = useCloud
  ? {
      apiKey: process.env.OPENROUTER_API_KEY ?? "",
      model: { id: "openai/gpt-4o-mini" },
      local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
      providers: {
        routes: [{ capability: "chat" as const, provider: "openrouter" }],
        fallback: ["openrouter"],
      },
    }
  : {
      apiKey: "ollama-local",
      model: { id: "ollama/llama3.2:3b" },
      local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
    };

const run: EvalRun = await Eval.create({
  name: "smoke-eval",
  dataset: [
    { input: "Reply with the single word: ok.", expected: "ok" },
    { input: "Say jazz in one word.", expected: "jazz" },
    { input: "What is 2 + 3? Reply with just the digit.", expected: "5" },
    { input: "Name a primary color. Reply with one word.", expected: "red" },
    { input: "Say hi in one word.", expected: "hi" },
  ],
  scorers: [
    Scorers.containsExpected({ caseSensitive: false }),
    Scorers.regex(/[a-zA-Z0-9]/),
  ],
  agent,
  concurrency: 2,
  metadata: { example: "eval-smoke", mode: useCloud ? "cloud" : "ollama" },
}).run();

console.log(JSON.stringify(run, null, 2));
console.log("");
console.log(
  `Mean: ${run.aggregate.meanScore.toFixed(3)} | Pass: ${(run.aggregate.passRatio * 100).toFixed(1)}% | Errors: ${run.aggregate.errorRows}/${run.aggregate.totalRows} | Tokens in/out: ${run.aggregate.tokensInTotal}/${run.aggregate.tokensOutTotal}`,
);

```

## Run

```bash
cd examples/eval
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/eval](https://github.com/usetheodev/theokit-sdk/tree/main/examples/eval)

---

# handoffs

Source: https://docs.usetheo.dev/theokit/guides/handoffs

Triage agent → billing/support specialist. Demonstrates the

# handoffs

Triage agent → billing/support specialist. Demonstrates the
`handoffs: []` declarative API.

## Run (Ollama)

```bash
ollama serve &
ollama pull llama3.2:3b
pnpm install
pnpm run run
```

## Run (OpenRouter cloud)

```bash
export OPENROUTER_API_KEY=sk-or-...
pnpm run run
```

## What it shows

- `Agent.create({ handoffs: [billing, support] })` declares peer-to-peer transfers (ADRs D214-D229).
- `RECOMMENDED_HANDOFF_PROMPT_PREFIX` exported as a constant; including it in the sender's system prompt makes the LLM use the transfer tools reliably.
- `Handoff.create(target, { toolDescription })` shows the customization escape hatch.
- Each handoff is exposed to the LLM as `transfer_to_<receiver_name>`; the LLM decides based on the user's intent.

## Model quality dependency (EC-14)

Handoffs require reliable function-calling. Tested combinations:

| Model | Reliability |
|---|---|
| `openai/gpt-4o-mini` (cloud) | ✅ Excellent |
| `anthropic/claude-3-5-haiku` (cloud) | ✅ Excellent |
| `ollama/llama3.2:3b` (local) | ⚠️ Inconsistent — small models often skip the transfer tool |
| `ollama/qwen2.5:7b` (local) | ✅ Good |
| `ollama/llama3.1:8b` (local) | ✅ Good |
| `ollama/mistral:7b` (local) | ✅ Good |

**Rule of thumb:** local models under ~7B params struggle with the handoff
tool-call decision (~30% miss rate observed). For local development, prefer
7B+ models OR test with `Agent.handoffTo` imperative as fallback.

## Cost tradeoff for deep chains (EC-12)

Full conversation history is passed to each receiver by default (D216). For
chains depth > 2, consider `Handoff.create(target, { inputFilter: summarize })`
to bound token cost. Token totals stack across hops; a 3-hop chain on a
5-message history roughly triples the prompt tokens.

## Loop protection

- `maxHandoffDepth: 5` per `send()` (default; D218). Override via `Agent.create({ maxHandoffDepth: N })`.
- Set `maxHandoffDepth: 0` to disable handoffs entirely (EC-8 — tools never fire).
- Pair single-flight (D221): A → B → A within the same `send()` throws `HandoffPairLoopError`. Use a 3rd agent for legitimate "back to triage" patterns.

## Code

```ts title="run.ts"
/**
 * Example: triage agent transfers to billing OR support based on intent.
 *
 *   ollama serve & ollama pull llama3.2:3b
 *   pnpm install
 *   pnpm run run
 *
 * Or with cloud:
 *   export OPENROUTER_API_KEY=sk-or-...
 *   pnpm run run
 */

import {
  Agent,
  Handoff,
  RECOMMENDED_HANDOFF_PROMPT_PREFIX,
} from "@theokit/sdk";

const useCloud = typeof process.env.OPENROUTER_API_KEY === "string";

const baseAgentConfig = useCloud
  ? {
      apiKey: process.env.OPENROUTER_API_KEY ?? "",
      model: { id: "openai/gpt-4o-mini" },
      local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
      providers: {
        routes: [{ capability: "chat" as const, provider: "openrouter" }],
        fallback: ["openrouter"],
      },
    }
  : {
      apiKey: "ollama-local",
      model: { id: "ollama/llama3.2:3b" },
      local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
    };

// Specialists
const billing = await Agent.create({
  ...baseAgentConfig,
  name: "billing",
  systemPrompt:
    "You are a billing specialist. Answer questions about invoices, charges, and payments concisely.",
});

const support = await Agent.create({
  ...baseAgentConfig,
  name: "support",
  systemPrompt:
    "You are a technical support specialist. Answer questions about installation, configuration, and troubleshooting.",
});

// Triage routes to the right specialist
const triage = await Agent.create({
  ...baseAgentConfig,
  name: "triage",
  systemPrompt: `${RECOMMENDED_HANDOFF_PROMPT_PREFIX}

You are a triage agent. Listen to the user's question and IMMEDIATELY transfer
the conversation to the right specialist:
  - billing questions → transfer_to_billing
  - technical/install questions → transfer_to_support

Do NOT answer the user directly. Use exactly ONE transfer_to_* tool per turn.`,
  handoffs: [billing, Handoff.create(support, { toolDescription: "Transfer to support for install/config issues" })],
});

console.log(`Triage agent ready (mode: ${useCloud ? "cloud" : "ollama"}).`);

const questions = [
  "I have a question about my bill.",
  "How do I install the SDK?",
];

for (const q of questions) {
  console.log(`\n=== User: ${q}`);
  const run = await triage.send(q);
  const result = await run.wait();
  console.log(`=== Triage status: ${result.status}`);
  console.log(`=== Response:`);
  console.log(result.result ?? `(${result.status}${result.error ? `: ${result.error.message}` : ""})`);
}

await triage.dispose();
await billing.dispose();
await support.dispose();
console.log("\nDone.");

```

## Run

```bash
cd examples/handoffs
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/handoffs](https://github.com/usetheodev/theokit-sdk/tree/main/examples/handoffs)

---

# Cookbook

Source: https://docs.usetheo.dev/theokit/guides

Runnable recipes auto-generated from packages/sdk/examples/.

# Cookbook

Every recipe below is a real, runnable example from the SDK repo. Each one has been validated with a real LLM provider before shipping.

- [`abort-mid-stream`](/theokit/guides/abort-mid-stream) — Demonstrates `AbortSignal` end-to-end propagation: caller's signal stops upstream token billing mid-
- [`acp-server`](/theokit/guides/acp-server) — Minimal `@theokit/acp` example: default-exports a per-session factory that creates a fresh `Agent` p
- [`agent-basics`](/theokit/guides/agent-basics) — The smallest end-to-end path with `@theokit/sdk`: create a local agent against
- [`agent-streaming`](/theokit/guides/agent-streaming) — Iterate `run.stream()` to consume `SDKMessage` events as they arrive, instead of
- [`agent-structured-output`](/theokit/guides/agent-structured-output) — Coerce an agent's final answer into a validated, inferred-typed object with a Zod
- [`bedrock-bot`](/theokit/guides/bedrock-bot) — One-shot Claude prompt via AWS Bedrock (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-D302).
- [`cache`](/theokit/guides/cache) — Demonstrates `Cache.semantic` + `Cache.consult` (Adoption Roadmap #6; ADRs D249-D266).
- [Session persistence](/theokit/guides/conversation-storage) — How a local agent's conversation persists in v4.0: the native transcript on disk, with no pluggable adapter.
- [`custom-provider`](/theokit/guides/custom-provider) — Register a custom OpenAI-/Anthropic-compatible LLM provider with `defineProvider`
- [`eval`](/theokit/guides/eval) — Runs `Eval.create / .run` against a real LLM and prints aggregate +
- [`handoffs`](/theokit/guides/handoffs) — Triage agent → billing/support specialist. Demonstrates the
- [`memory-lance`](/theokit/guides/memory-lance) — > Ships with `@theokit/sdk@1.4.0` (lancedb-backend-ship-v1-1 plan). Closes
- [`prompts`](/theokit/guides/prompts) — Instructions are the system prompt — a plain string, a resolver evaluated per send, or a
- [`providers-models`](/theokit/guides/providers-models) — The model is chosen by the `vendor/model` id you pass to `Agent.create` plus the key.
- [`squad-basics`](/theokit/guides/squad-basics) — A sequential `Squad` of two agents: a brainstormer proposes name ideas, a picker chooses the best.
- [`tasks`](/theokit/guides/tasks) — Demonstrates the `Task` namespace from `@theokit/sdk` (Adoption Roadmap gap #2; ADRs D361-D374).
- [`tool-basics`](/theokit/guides/tool-basics) — Give an agent a typed tool with `defineTool` — the model calls it when the prompt
- [`tool-hooks-tracking`](/theokit/guides/tool-hooks-tracking) — Demonstrates `onToolStart` / `onToolEnd` / `onToolError` callbacks for cost tracking, audit log, lat
- [`vertex-bot`](/theokit/guides/vertex-bot) — One-shot Gemini (or Claude) prompt via GCP Vertex AI (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-
- [`workflow-basics`](/theokit/guides/workflow-basics) — A two-step `Workflow`: a `fn` step normalizes the input, an `agentStep` turns it into a
- [`workflows`](/theokit/guides/workflows) — Multi-step pipeline: validate → classify (LLM) → branch (billing/support) → summarize.

## Complex examples (GitHub link)

These examples are too large to inline. View them directly:

- [examples/telegram-pro](https://github.com/usetheodev/theokit-sdk/tree/main/examples/telegram-pro)

---

# memory-lance

Source: https://docs.usetheo.dev/theokit/guides/memory-lance

> Ships with `@theokit/sdk@1.4.0` (lancedb-backend-ship-v1-1 plan). Closes

# memory-lance

> Ships with `@theokit/sdk@1.4.0` (lancedb-backend-ship-v1-1 plan). Closes
> ADR D12 ("LanceDB deferred to v1.1") via fulfillment of D43.

## What this shows

How to opt into the **Lance backend** for `Memory.create` instead of the
default SQLite-vec. Lance scales to >100k embeddings with HNSW-grade
vector search — relevant when SQLite-vec p95 latency starts hurting
(typically above ~10k facts).

Two modes:

1. **Dry-run (default)** — `pnpm run`: prints what the real path would
   do, exits 0. No LLM call, no Lance install required. Honored by ADR
   D50 — example must work even without the optional dep.
2. **Real** — `LANCE_REAL=1 pnpm run` (with `OPENROUTER_API_KEY` set
   and `@lancedb/lancedb` peer dep installed): seeds 3 facts with real
   OpenRouter embeddings, runs semantic recall, asserts a non-empty hit.

## Setup (real mode)

```bash
# 1. Install the peer deps (NOT bundled in @theokit/sdk — opt-in).
pnpm add @lancedb/lancedb apache-arrow@^18.1.0

# 2. Get a free OpenRouter key at https://openrouter.ai/keys and copy
#    .env.example to .env. Fill OPENROUTER_API_KEY and LANCE_REAL=1.
cp .env.example .env
# Edit .env

# 3. Run.
pnpm run
```

Expected output:

```
=== @theokit/sdk Lance backend example — REAL MODE ===
[1/4] Opening Lance index with real embedder...
[2/4] Seeding 3 synthetic facts...
[3/4] Recalling via semantic search...
      Got 3 hits. Top match:
        score=0.6XX
        snippet="LanceDB is a columnar vector database..."
[4/4] Closing index...
=== SUCCESS — Lance E2E validated with real LLM + real Lance. ===
```

## Gotchas

### Native binding prebuilds (ADR D43 consequences)

`@lancedb/lancedb` ships prebuilt binaries for:
- `linux-x64-gnu`
- `darwin-arm64`
- `darwin-x64`
- `win32-x64-msvc`

**Not covered:** Alpine/musl Linux, ARM-Linux. On those platforms the
peer install attempts a source build via `node-gyp` and fails without
toolchain. **Workaround:** stay on SQLite default (omit `backend: "lance"`).

### Bundler externalization (consumers of SDK)

If your consumer app bundles `@theokit/sdk` (Next.js, Vite, webpack,
rollup), you MUST externalize `@lancedb/lancedb`:

- **Next.js:**
  ```js
  // next.config.js
  experimental: { serverComponentsExternalPackages: ["@lancedb/lancedb"] }
  ```
- **Vite:**
  ```js
  // vite.config.js
  optimizeDeps: { exclude: ["@lancedb/lancedb"] },
  ssr: { external: ["@lancedb/lancedb"] }
  ```
- **webpack/rollup:** add to `externals` array.

Without this, the bundler tries to process the `.node` binding and
crashes at build time.

### apache-arrow peer pin

`@lancedb/lancedb@0.30.0` requires `apache-arrow >=15.0.0 <=18.1.0`.
If your app already pins a newer `apache-arrow`, you'll see an
`unmet peer` warning — downgrade to `^18.1.0` or accept the warning
(Lance still works at v21 in practice, but it's not officially supported).

## When to use Lance vs SQLite

| Scale | Recommended backend | Why |
|---|---|---|
| < 1k facts | SQLite-vec (default) | Zero deps, fast startup |
| 1k–10k facts | SQLite-vec (default) | Still under p95 threshold |
| 10k–100k facts | Lance (opt-in) | SQLite-vec p95 > 100ms; Lance HNSW wins |
| > 100k facts | Lance (recommended) | Columnar storage + vector indices designed for this |

See `.claude/knowledge-base/benchmarks/memory-backends-2026-05-31.md`
in the SDK repo for the numerical methodology behind these thresholds.

## Migration SQLite → Lance

If you already have an SQLite memory index and want to migrate:

```bash
# Built-in CLI (shipped with @theokit/sdk).
npx theokit-migrate-memory --from sqlite --to lance
```

See ADR D44 for migration design + `migrate-sqlite-to-lance.ts` for
implementation. Dry-run is the default — no destructive writes without
`--confirm`.

## Code

```ts title="run.ts"
/**
 * @theokit/sdk — Lance backend memory example.
 *
 * Mode A (default — dry-run, no install required): prints a walkthrough
 * of what the real path WOULD do. Exit 0.
 *
 * Mode B (LANCE_REAL=1 + OPENROUTER_API_KEY): runs the actual flow with
 * `@lancedb/lancedb` peer + real OpenRouter embeddings + real chat
 * completion. Verifies that recall returns at least one seeded fact.
 *
 * Ships with the lancedb-backend-ship-v1-1 plan (close ADR D12).
 * ADR D50 honored: graceful degradation when the peer dep is absent.
 */

import { createRequire } from "node:module";

const LANCE_REAL = process.env.LANCE_REAL === "1";
const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;

function dryRun(): void {
  console.log("=== @theokit/sdk Lance backend example — DRY-RUN MODE ===\n");
  console.log("This run did NOT touch a real LLM or write to a Lance index.\n");
  console.log("In real mode (LANCE_REAL=1 + OPENROUTER_API_KEY), the script:");
  console.log("  1. Confirms `@lancedb/lancedb` peer dep is installed.");
  console.log("  2. Opens a Lance index in a fresh tmpdir.");
  console.log("  3. Seeds 3 facts with real OpenRouter embeddings.");
  console.log("  4. Runs `Memory.recall()` to confirm semantic retrieval.");
  console.log("  5. Disposes the index cleanly.\n");
  console.log("To run for real:");
  console.log("  $ pnpm add @lancedb/lancedb apache-arrow@^18.1.0");
  console.log("  $ cp .env.example .env  # then fill OPENROUTER_API_KEY");
  console.log("  $ LANCE_REAL=1 pnpm run\n");
  console.log("Gotchas (ADR D43 + D50):");
  console.log("  - @lancedb/lancedb ships prebuilds for linux-x64-gnu,");
  console.log("    darwin-arm64, darwin-x64, win32-x64-msvc. Alpine/musl/ARM");
  console.log("    Linux require node-gyp toolchain. SQLite default covers");
  console.log("    these cases — use `Memory.create()` without `backend: \"lance\"`.");
  console.log("  - Bundlers (Next.js/Vite/webpack) must externalize the");
  console.log("    `@lancedb/lancedb` native binding — see SDK CHANGELOG 1.4.0.");
}

function checkPeerInstalled(): boolean {
  try {
    const require = createRequire(import.meta.url);
    require("@lancedb/lancedb");
    return true;
  } catch {
    return false;
  }
}

async function realRun(): Promise<void> {
  if (OPENROUTER_API_KEY === undefined || OPENROUTER_API_KEY === "") {
    console.error("ERROR: LANCE_REAL=1 requires OPENROUTER_API_KEY in env.");
    console.error("  Copy .env.example to .env and fill it in.");
    process.exit(1);
  }
  if (!checkPeerInstalled()) {
    console.error("ERROR: LANCE_REAL=1 requires @lancedb/lancedb peer dep.");
    console.error("  Install: pnpm add @lancedb/lancedb apache-arrow@^18.1.0");
    process.exit(1);
  }

  console.log("=== @theokit/sdk Lance backend example — REAL MODE ===\n");
  console.log("Peer dep present + OPENROUTER_API_KEY set. Proceeding...\n");

  // Dynamic imports so the dry-run path never executes any of this.
  const { mkdtempSync, rmSync } = await import("node:fs");
  const { tmpdir } = await import("node:os");
  const { join } = await import("node:path");
  const { IndexManager } = await import(
    "@theokit/sdk/internal/memory/index-manager.js" as string
  ).catch(async () => {
    // The SDK does not (yet) expose IndexManager as a public sub-export.
    // For this example we use the public Memory facade if available, OR
    // demonstrate the dispatch via direct internal import for educational
    // purposes only (NOT a stable API contract).
    return await import("../../packages/sdk/src/internal/memory/index-manager.js");
  });
  const { MEMORY_EMBEDDING_ADAPTERS } = await import(
    "../../packages/sdk/src/internal/memory/adapters/catalog.js"
  );

  const tmp = mkdtempSync(join(tmpdir(), "lance-example-"));
  console.log(`Lance storage: ${tmp}/.theokit/memory/lance/\n`);

  try {
    // For demo purposes we use a deterministic hash-based embedder so the
    // example runs reliably without depending on a specific embedding
    // provider's availability (OpenRouter embedding endpoints are gated
    // by scope; OpenAI requires a separate API key). This proves the
    // Lance dispatch + roundtrip end-to-end with REAL Lance.
    //
    // To use a real embedding provider: replace this with
    // `MEMORY_EMBEDDING_ADAPTERS.openai.create({ apiKey: process.env.OPENAI_API_KEY })`.
    void MEMORY_EMBEDDING_ADAPTERS; // catalog browseable for users
    const { createHash } = await import("node:crypto");
    const embedding = {
      id: "demo-mock-embedder",
      model: "demo",
      dimension: 64,
      async embed(texts: ReadonlyArray<string>): Promise<number[][]> {
        return texts.map((text) => {
          const hash = createHash("sha256").update(text).digest();
          const v: number[] = new Array(64);
          for (let i = 0; i < 64; i++) {
            const byte = hash[i % hash.length] as number;
            v[i] = (byte / 127.5) - 1;
          }
          const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
          return v.map((x) => x / (norm || 1));
        });
      },
      stats() {
        return { cacheHits: 0, cacheMisses: 0, httpCalls: 0, retries: 0 };
      },
    };

    console.log("[1/4] Opening Lance index with real embedder...");
    const index = await IndexManager.open({
      cwd: tmp,
      embedding,
      backend: "lance",
    });
    console.log("      Lance index opened successfully.\n");

    console.log("[2/4] Seeding 3 synthetic facts...");
    // We use the underlying LanceIndex via the adapter unwrap for direct
    // addFacts (the MemoryIndex interface does not expose addFact —
    // Memory facade does, via MEMORY.md markdown writes that get synced).
    // For this example we want to demonstrate Lance E2E without the
    // markdown corpus layer.
    const { LanceMemoryAdapter } = await import(
      "../../packages/sdk/src/internal/memory/lance-memory-adapter.js"
    );
    if (!(index instanceof LanceMemoryAdapter)) {
      throw new Error("Expected LanceMemoryAdapter — dispatch failed");
    }
    const lance = index.unwrap();
    const now = Date.now();
    await lance.addFacts([
      {
        id: "fact-1",
        text: "TypeScript was created by Microsoft and released in 2012.",
        source: "memory",
        namespace: "default",
        scope: "user",
        user_id: "demo",
        timestamp: now,
      },
      {
        id: "fact-2",
        text: "LanceDB is a columnar vector database optimized for embeddings.",
        source: "memory",
        namespace: "default",
        scope: "user",
        user_id: "demo",
        timestamp: now + 1,
      },
      {
        id: "fact-3",
        text: "Apache Arrow is the in-memory format used by Lance for fast IO.",
        source: "memory",
        namespace: "default",
        scope: "user",
        user_id: "demo",
        timestamp: now + 2,
      },
    ]);
    console.log("      3 facts written with deterministic demo embedder (real Lance).\n");

    console.log("[3/4] Recalling via semantic search...");
    const hits = await index.search("Which database does Lance use?", {
      maxResults: 3,
    });
    if (hits.length === 0) {
      throw new Error("Recall returned ZERO hits — semantic search broken");
    }
    console.log(`      Got ${hits.length} hits. Top match:`);
    console.log(`        score=${hits[0]?.score?.toFixed(3)}`);
    console.log(`        snippet="${hits[0]?.snippet}"\n`);

    console.log("[4/4] Closing index...");
    await index.close();
    console.log("      Index closed.\n");

    console.log("=== SUCCESS — Lance E2E validated with real LLM + real Lance. ===");
  } finally {
    rmSync(tmp, { recursive: true, force: true });
  }
}

async function main(): Promise<void> {
  if (LANCE_REAL) {
    await realRun();
  } else {
    dryRun();
  }
}

main().catch((err) => {
  console.error("FATAL:", err instanceof Error ? err.message : err);
  process.exit(1);
});

```

## Run

```bash
cd examples/memory-lance
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/memory-lance](https://github.com/usetheodev/theokit-sdk/tree/main/examples/memory-lance)

---

# prompts

Source: https://docs.usetheo.dev/theokit/guides/prompts

Instructions are the system prompt — a plain string, a resolver evaluated per send, or a

# prompts

Instructions are the system prompt — a plain string, a resolver evaluated per send, or a
per-send override.

Pairs with the docs page **[Prompts](https://docs.usetheo.dev/theokit/prompts)**.

## Run

```bash
pnpm install
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys — or put it in .env
pnpm run run
```

## What it shows

- `systemPrompt: (ctx) => string` — dynamic instructions from `SystemPromptContext`
  (`userMessage`, `model`, `memory`, …).
- `agent.send(msg, { systemPrompt })` — a per-send string override that wins over the resolver.

## Code

```ts title="run.ts"
/**
 * Prompts and instructions (features/prompts).
 *
 * The system prompt is the agent's instructions. It can be a plain string, a
 * resolver evaluated per send (with the message + context), or overridden for a
 * single send via `SendOptions.systemPrompt`.
 *
 * Run:
 *   pnpm install
 *   export OPENROUTER_API_KEY=sk-or-...   # or put it in .env
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

// Dynamic instructions: the system prompt is computed per send from context
// (`ctx.userMessage`, `ctx.model`, recalled `ctx.memory`, …).
const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: (ctx) =>
    `You are a terse assistant. Answer in exactly one sentence. The user asked: "${ctx.userMessage}".`,
});

const dynamic = await (await agent.send("What is TypeScript?")).wait();
console.log("Dynamic:  ", dynamic.result);

// Per-send override: a string that wins over the resolver for this send only.
const override = await (
  await agent.send("What is TypeScript?", { systemPrompt: "Reply as a pirate, in one sentence." })
).wait();
console.log("Override: ", override.result);

await agent.dispose();

// --- validate output (fail loud) ---
for (const [label, r] of [["dynamic", dynamic], ["override", override]] as const) {
  if (r.status !== "finished" || typeof r.result !== "string" || r.result.length === 0) {
    console.error(`${label} run did not finish:`, JSON.stringify(r.error ?? r.status));
    process.exit(1);
  }
}

```

## Run

```bash
cd examples/prompts
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/prompts](https://github.com/usetheodev/theokit-sdk/tree/main/examples/prompts)

---

# providers-models

Source: https://docs.usetheo.dev/theokit/guides/providers-models

The model is chosen by the `vendor/model` id you pass to `Agent.create` plus the key.

# providers-models

The model is chosen by the `vendor/model` id you pass to `Agent.create` plus the key.
`@theokit/sdk/models` gives you offline helpers to parse an id and look up capabilities.

Pairs with the docs page **[Providers and models](https://docs.usetheo.dev/theokit/providers-models)**.

## Run

```bash
pnpm install
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys — or put it in .env
pnpm run run
```

## What it shows

- `parseModelId` / `humanizeModelName` / `resolveModelCapabilities` from `@theokit/sdk/models` — offline, no key.
- `model: { id: "openai/gpt-oss-120b:free" }` — the id + key select the provider (OpenRouter routing).

## Code

```ts title="run.ts"
/**
 * Providers and models (features/providers-models).
 *
 * The model is chosen by the `vendor/model` id you pass to `Agent.create` plus
 * the key. `@theokit/sdk/models` also gives you offline helpers to parse a model
 * id and look up its capabilities — no key, no network.
 *
 * Run:
 *   pnpm install
 *   export OPENROUTER_API_KEY=sk-or-...   # or put it in .env
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";
import { humanizeModelName, parseModelId, resolveModelCapabilities } from "@theokit/sdk/models";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

// 1. Inspect any model id — offline, pure, no network.
const inspectId = "anthropic/claude-3-5-sonnet";
const { provider, name } = parseModelId(inspectId);
const caps = resolveModelCapabilities(inspectId);
console.log(`Inspect:  ${humanizeModelName(inspectId)}`);
console.log(`Provider: ${provider}  ·  name: ${name}`);
console.log(`Context:  ${caps.maxContextTokens} tokens  ·  tools: ${caps.supportsToolUse}  ·  vision: ${caps.supportsVision}`);

// 2. Run an agent. The `vendor/model` id + your key route to the provider
//    (here OpenRouter routes `openai/…`).
const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You are concise.",
});
const result = await (await agent.send("Name three popular LLM providers, comma-separated.")).wait();
console.log(`\nReply:    ${result.result}`);

await agent.dispose();

// --- validate output (fail loud) ---
if (result.status !== "finished" || typeof result.result !== "string" || result.result.length === 0) {
  console.error("run did not finish:", JSON.stringify(result.error ?? result.status));
  process.exit(1);
}

```

## Run

```bash
cd examples/providers-models
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/providers-models](https://github.com/usetheodev/theokit-sdk/tree/main/examples/providers-models)

---

# squad-basics

Source: https://docs.usetheo.dev/theokit/guides/squad-basics

A sequential `Squad` of two agents: a brainstormer proposes name ideas, a picker chooses the best.

# squad-basics

A sequential `Squad` of two agents: a brainstormer proposes name ideas, a picker chooses the best.

```bash
OPENROUTER_API_KEY=... pnpm run
```

## Code

```ts title="run.ts"
/**
 * Squad basics — a sequential team of agents.
 *
 * `Squad.create({ agents })` runs its agents in array order: each agent's reply becomes the next
 * agent's input. Here a brainstormer proposes name ideas, then a picker chooses the best one.
 * `squad.run(input)` returns the terminal `SquadRun` — `result` (last agent's output), `status`,
 * and `steps` (one `StepResult` per agent).
 */
import { Agent, Squad } from "@theokit/sdk";

const brainstormer = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "List exactly 3 short product name ideas as a comma-separated line. No preamble.",
});

const picker = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "From the given list, pick the single best name and reply with just that name and a 6-word reason.",
});

const squad = Squad.create({ agents: [brainstormer, picker] });

const run = await squad.run("a focus timer app for developers");

console.log("Status:", run.status);
console.log("Steps:", run.steps.length);
console.log("Result:", run.result);

await brainstormer.dispose();
await picker.dispose();

// Validate the output — a squad that did not complete is a failure, not a green run.
if (run.status !== "completed" || typeof run.result !== "string" || run.result.length === 0) {
  const failed = run.steps.find((s) => s.status === "failed");
  console.error(`Squad did not complete: status=${run.status}`, failed?.error ?? "");
  process.exit(1);
}

```

## Run

```bash
cd examples/squad-basics
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/squad-basics](https://github.com/usetheodev/theokit-sdk/tree/main/examples/squad-basics)

---

# tasks

Source: https://docs.usetheo.dev/theokit/guides/tasks

Demonstrates the `Task` namespace from `@theokit/sdk` (Adoption Roadmap gap #2; ADRs D361-D374).

# tasks

Demonstrates the `Task` namespace from `@theokit/sdk` (Adoption Roadmap gap #2; ADRs D361-D374).

## Run (no LLM required)

```bash
pnpm install
pnpm run run
```

The work functions are deterministic — no `OPENROUTER_API_KEY` needed. To use a real LLM, wrap your `agent.send(prompt, { signal: ctx.signal })` call inside the `work` callback.

## What it shows

- `Task.submit(kind, work, options?)` — submit a unit of async work and receive a queued `TaskHandle`.
- `Task.subscribe(id)` — `AsyncIterable<TaskEvent>` with ring-buffer replay (D372) for late-attach safety.
- Fan-out **batch** pattern — 1 parent task whose work spawns N children with `meta: { item }` provenance.
- Idempotent **cancel** — `Task.cancel` returns `{ cancelled, alreadyTerminal }`; calling twice is safe.
- **JsonFileTaskStore** opt-in via `Task.configure({ store: { backend: "json", dir } })` — handles persist across restarts; inspect them via the CLI:

  ```bash
  THEOKIT_HOME=/tmp/theokit-tasks-example-XXX pnpm exec theokit tasks list
  ```

## v1 scope cut (documented)

`Agent.send` / `Agent.batch` / `Workflow.run` / `Cron.register` do **NOT** accept a `{ task: true }` option yet — that adapter integration is deferred to v0.2 (see plan v1.2). The user-side pattern in `run.ts` (`Task.submit("kind", async (ctx) => myAsyncWork(ctx))`) covers every observability use case today, with zero coupling to the underlying runtime.

## Code

```ts title="run.ts"
/**
 * Example: Task observability registry (ADRs D361-D374, Adoption Roadmap gap #2).
 *
 * Demonstrates the 5-state lifecycle, subscribe with ring-buffer replay,
 * idempotent cancel, fan-out batch pattern, and JsonFileTaskStore
 * cross-restart persistence.
 *
 * No LLM required — the work functions are deterministic so the example
 * runs offline and quickly. For a real-LLM equivalent, wrap your
 * `agent.send` call inside the `work` callback.
 */

import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { Task } from "@theokit/sdk";

async function main(): Promise<void> {
  // Persist tasks to a temp dir so we can also exercise the CLI verb.
  const dir = mkdtempSync(join(tmpdir(), "theokit-tasks-example-"));
  Task.configure({
    store: { backend: "json", dir: join(dir, "tasks") },
    maxConcurrent: 4,
  });
  console.log(`Using JsonFileTaskStore at ${dir}/tasks\n`);

  // ─── 1. Submit a single task + subscribe to progress ──────────────
  console.log("1) Single task with progress events");
  const handle = await Task.submit("custom", async (ctx) => {
    for (let i = 0; i < 3; i++) {
      ctx.emit({ step: i });
      await sleep(20);
    }
    return "done";
  });

  for await (const event of Task.subscribe(handle.id)) {
    console.log("   event:", event.type, "type" in event ? JSON.stringify(event) : "");
    if (event.type === "finished" || event.type === "errored" || event.type === "cancelled") break;
  }

  // ─── 2. Fan-out batch with parent + children ──────────────────────
  console.log("\n2) Fan-out batch (1 parent + N children)");
  const parent = await Task.submit("batch", async (ctx) => {
    const items = ["alpha", "beta", "gamma"];
    const children = await Promise.all(
      items.map((item) =>
        Task.submit(
          "run",
          async (childCtx) => {
            childCtx.emit({ item });
            await sleep(10);
            return `processed:${item}`;
          },
          { meta: { item } },
        ),
      ),
    );
    return { childCount: children.length, ids: children.map((h) => h.id) };
  });

  await waitForTerminal(parent.id);
  const parentFinal = await Task.get(parent.id);
  console.log(`   parent ${parentFinal?.state}, result:`, parentFinal?.result);

  // ─── 3. Cancel a running task idempotently ────────────────────────
  console.log("\n3) Cancel mid-flight (idempotent)");
  const cancellable = await Task.submit("custom", async (ctx) => {
    return new Promise<string>((_resolve, reject) => {
      ctx.signal.addEventListener("abort", () => reject(new Error("aborted")));
    });
  });
  await sleep(10);
  const first = await Task.cancel(cancellable.id);
  const second = await Task.cancel(cancellable.id);
  console.log("   first cancel:", first);
  console.log("   second cancel (idempotent):", second);

  // ─── 4. List + filter ──────────────────────────────────────────────
  console.log("\n4) List + filter");
  const allFinished = await Task.list({ state: "finished" });
  const allCancelled = await Task.list({ state: "cancelled" });
  console.log(
    `   ${allFinished.length} finished | ${allCancelled.length} cancelled`,
  );

  console.log(`\n→ Done. Inspect via:`);
  console.log(`   THEOKIT_HOME=${dir} pnpm exec theokit tasks list`);
  console.log(`   THEOKIT_HOME=${dir} pnpm exec theokit tasks inspect <id>`);
}

function sleep(ms: number): Promise<void> {
  return new Promise((r) => setTimeout(r, ms));
}

async function waitForTerminal(id: string): Promise<void> {
  for (let i = 0; i < 100; i++) {
    const h = await Task.get(id);
    if (h?.state === "finished" || h?.state === "error" || h?.state === "cancelled") return;
    await sleep(10);
  }
}

main().catch((err) => {
  console.error("example failed:", err);
  process.exit(1);
});

```

## Run

```bash
cd examples/tasks
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/tasks](https://github.com/usetheodev/theokit-sdk/tree/main/examples/tasks)

---

# tool-basics

Source: https://docs.usetheo.dev/theokit/guides/tool-basics

Give an agent a typed tool with `defineTool` — the model calls it when the prompt

# tool-basics

Give an agent a typed tool with `defineTool` — the model calls it when the prompt
calls for it, and the Zod schema validates the arguments first.

Pairs with the docs page **[Tools › Give an agent a tool](https://docs.usetheo.dev/theokit/tools)**.

## Run

```bash
pnpm install
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys — or put it in .env
pnpm run run
```

## What it shows

- `defineTool({ name, description, inputSchema, execute })` — the canonical tool factory.
- The Zod `inputSchema` is converted to JSON Schema and validated before `execute` runs.
- `tools: [getWeather]` on `Agent.create` — the agent decides when to call the tool.

## Code

```ts title="run.ts"
/**
 * Tools — give an agent a typed tool (features/tools).
 *
 * `Tool.create` turns a plain async function into a tool the model can call. The
 * Zod `inputSchema` is converted to JSON Schema and validated before `execute`
 * runs, so the arguments are typed. The agent decides when to call it based on
 * the description and the user's message.
 *
 * Run:
 *   pnpm install
 *   export OPENROUTER_API_KEY=sk-or-...   # or put it in .env
 *   pnpm run run
 */

import { Agent, Tool } from "@theokit/sdk";
import { z } from "zod";

const apiKey = process.env.OPENROUTER_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("Set OPENROUTER_API_KEY (env or .env) — see https://openrouter.ai/keys");
}

const getWeather = Tool.create({
  name: "get_weather",
  description: "Look up the current weather in a given city.",
  inputSchema: z.object({
    city: z.string().describe("City name, e.g. 'Tokyo' or 'Brasília'."),
  }),
  async handler({ city }) {
    // A real tool would call a weather API. Mocked here so the example is self-contained.
    const mock: Record<string, string> = {
      Tokyo: "18°C, cloudy",
      Brasília: "27°C, sunny",
      London: "12°C, raining",
    };
    return mock[city] ?? `No weather data for ${city}.`;
  },
});

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  name: "weather-bot",
  systemPrompt: "Use the get_weather tool when the user asks about weather. Answer in one sentence.",
  tools: [getWeather],
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
});

const run = await agent.send("What's the weather in Tokyo?");
const result = await run.wait();

console.log("Status:", result.status);
console.log("Reply: ", result.result);

await agent.dispose();

// --- validate output (fail loud) ---
if (result.status !== "finished" || typeof result.result !== "string" || result.result.length === 0) {
  console.error("run did not finish:", JSON.stringify(result.error ?? result.status));
  process.exit(1);
}

```

## Run

```bash
cd examples/tool-basics
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/tool-basics](https://github.com/usetheodev/theokit-sdk/tree/main/examples/tool-basics)

---

# tool-hooks-tracking

Source: https://docs.usetheo.dev/theokit/guides/tool-hooks-tracking

Demonstrates `onToolStart` / `onToolEnd` / `onToolError` callbacks for cost tracking, audit log, latency telemetry.

# tool-hooks-tracking

Demonstrates `onToolStart` / `onToolEnd` / `onToolError` callbacks for cost tracking, audit log, latency telemetry.

## Run

```bash
# Fixture mode (no tool dispatch fires):
pnpm run

# Real LLM (the only path that actually exercises tool hooks):
OPENROUTER_API_KEY=sk-or-... pnpm run
```

## What it shows

1. Register `onToolStart` / `onToolEnd` / `onToolError` in `AgentOptions`
2. LLM invokes the tool → start hook fires → handler runs → end hook fires
3. Hooks receive `callId` (same value across start/end pair — correlate in logs)
4. `durationMs` measured from start to end (or error) hook fire
5. Hook listener errors are SWALLOWED (D317) — a crashing logger cannot kill the agent

## Use for production

```ts
onToolStart: ({ toolName, callId, conversationId }) => {
  metrics.recordToolStart({ toolName, callId, conversationId });
},
onToolEnd: ({ toolName, callId, durationMs, result }) => {
  metrics.recordToolEnd({ toolName, callId, durationMs });
},
onToolError: ({ toolName, callId, durationMs, error }) => {
  alerts.notify({ toolName, error: error.message });
},
```

See `docs.md` "Tool lifecycle hooks" section for the full contract.

## Code

```ts title="run.ts"
/**
 * Production-Readiness #4 — Tool lifecycle hooks example.
 *
 * Demonstrates onToolStart / onToolEnd / onToolError for cost tracking,
 * audit log, latency telemetry. Hook errors are SWALLOWED (D317) — a
 * misbehaving listener cannot crash the agent run.
 *
 * To run with a real LLM (only path that exercises tool dispatch):
 *   OPENROUTER_API_KEY=sk-or-... pnpm run
 */

import { Agent, Tool } from "@theokit/sdk";
import { z } from "zod";

const apiKey = process.env.OPENROUTER_API_KEY ?? "theo_test_tool_hooks_example";
const realLlm = apiKey.startsWith("sk-or-");

console.log(`\n== Tool lifecycle hooks example ==`);
console.log(realLlm ? "Mode: real OpenRouter" : "Mode: fixture (no LLM call)");
console.log();

// Custom tool that the LLM may invoke.
const getWeatherTool = Tool.create({
  name: "get_weather",
  description: "Return mock weather for a city",
  inputSchema: z.object({ city: z.string() }),
  handler: async ({ city }) => {
    await new Promise((r) => setTimeout(r, 20)); // simulate latency
    if (city === "boom") throw new Error("intentional handler failure");
    return JSON.stringify({ city, tempC: 22, condition: "sunny" });
  },
});

// In-memory telemetry sink.
const events: Array<{
  type: "start" | "end" | "error";
  toolName: string;
  callId: string;
  durationMs?: number;
  errorMsg?: string;
}> = [];

const providers = realLlm
  ? {
      routes: [{ capability: "chat" as const, provider: "openrouter" }],
      fallback: ["openrouter"],
    }
  : undefined;

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd() },
  tools: [getWeatherTool],
  ...(providers !== undefined ? { providers } : {}),
  onToolStart: ({ toolName, callId }) => {
    events.push({ type: "start", toolName, callId });
  },
  onToolEnd: ({ toolName, callId, durationMs }) => {
    events.push({ type: "end", toolName, callId, durationMs });
  },
  onToolError: ({ toolName, callId, durationMs, error }) => {
    events.push({ type: "error", toolName, callId, durationMs, errorMsg: error.message });
  },
});

if (realLlm) {
  console.log(`[1] Sending message that should invoke get_weather…`);
  const run = await agent.send("What is the weather in Paris? Use the get_weather tool.");
  // Consume the stream to drive the conversation forward (real tool dispatch).
  let text = "";
  for await (const event of run.stream()) {
    if (event.type === "assistant") {
      for (const part of event.message.content) {
        if (part.type === "text") text += part.text;
      }
    }
  }
  await run.wait();
  console.log(`[1] LLM reply: ${text.slice(0, 200)}`);
} else {
  console.log(`[1] Skipping LLM call (no OPENROUTER_API_KEY set)`);
}

console.log();
console.log(`Captured ${events.length} tool lifecycle events:`);
for (const e of events) {
  const dur = e.durationMs !== undefined ? ` (${e.durationMs}ms)` : "";
  const err = e.errorMsg !== undefined ? ` error="${e.errorMsg}"` : "";
  console.log(`  [${e.type.padEnd(5)}] ${e.toolName} callId=${e.callId}${dur}${err}`);
}

console.log();
console.log(`Invariants observed:`);
console.log(`- callId is identical across start↔end (or start↔error) pairs`);
console.log(`- durationMs measured from start hook → end (or error) hook`);
console.log(`- error.message is always present on onToolError`);
console.log(`- onToolError fires when validate fails OR handler throws`);
console.log(`- Hook listener throws are swallowed with stderr warn (D317)`);

await agent.dispose();

```

## Run

```bash
cd examples/tool-hooks-tracking
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/tool-hooks-tracking](https://github.com/usetheodev/theokit-sdk/tree/main/examples/tool-hooks-tracking)

---

# vertex-bot

Source: https://docs.usetheo.dev/theokit/guides/vertex-bot

One-shot Gemini (or Claude) prompt via GCP Vertex AI (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-D302).

# vertex-bot

One-shot Gemini (or Claude) prompt via GCP Vertex AI (`@theokit/sdk` Adoption Roadmap #8; ADRs D286-D302).

## Setup

1. Enable Vertex AI API in your GCP project: [https://console.cloud.google.com/apis/library/aiplatform.googleapis.com](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com).
2. Grant your principal the **Vertex AI User** role (`roles/aiplatform.user`).
3. Authenticate via ADC (Application Default Credentials):
   ```bash
   gcloud auth application-default login
   gcloud config set project <your-gcp-project>
   ```
4. (Optional, production) Use a service account instead:
   ```bash
   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json
   ```
5. Copy `.env.example` to `.env` and set `GOOGLE_CLOUD_PROJECT`.

## Run

```bash
cp .env.example .env
# fill GOOGLE_CLOUD_PROJECT
pnpm install
pnpm run run                                            # default question
pnpm run run "What's 2+2?"
VERTEX_MODEL=vertex/anthropic/claude-sonnet-4-5@20250929 pnpm run run  # Claude on Vertex
```

## Model IDs

- **Gemini (OpenAI-compat path, D291):** `vertex/google/gemini-2.0-flash-001`
- **Claude (`:rawPredict` path, D292):** `vertex/anthropic/claude-sonnet-4-5@20250929`

## Locations

- `us-central1`, `europe-west4`, `asia-southeast1`, etc — regional routing.
- `global` — cross-region for Anthropic (Vertex global endpoint with D293 baseUrl fix).

## v1 limitations (documented)

- **`google-auth-library` required peer dep** (D288) — repo archived Nov 2025 but security-patched.
- **OpenAI-compat path drops unsupported params silently** (D291) — e.g. recursive JSON schemas in `response_format`. Documented in Vertex's own docs.
- **Anthropic on Vertex is non-streaming** in v1 — `:streamRawPredict` deferred to v1.x; v1 always uses `:rawPredict`.
- **No Workload Identity Federation walkthrough** in v1 (D297) — ADC chain resolves it transparently, but the GCP-side setup is out of scope.
- **No Service Account JSON file generation tooling** (D299) — user provides via `GOOGLE_APPLICATION_CREDENTIALS`.

## Code

```ts title="run.ts"
/**
 * GCP Vertex AI demo (Adoption Roadmap #8; ADRs D286-D302).
 *
 * Sends a one-shot prompt to Gemini (or Claude on Vertex) and prints the reply.
 * Uses Application Default Credentials via `google-auth-library`.
 *
 * Run:
 *   gcloud auth application-default login
 *   cp .env.example .env  # fill GOOGLE_CLOUD_PROJECT
 *   pnpm install
 *   pnpm run run
 */

import { Agent } from "@theokit/sdk";

if (process.env.GOOGLE_CLOUD_PROJECT === undefined) {
  console.error(
    "GOOGLE_CLOUD_PROJECT is required. Set it in .env or run " +
      "`gcloud config set project <id>`.",
  );
  process.exit(1);
}

const modelId =
  process.env.VERTEX_MODEL ?? "vertex/google/gemini-2.0-flash-001";

// For Vertex, apiKey isn't strictly used — ADC resolves the OAuth token
// lazily inside the client. We pass an empty placeholder.
const agent = await Agent.create({
  apiKey: "vertex-adc",
  model: { id: modelId },
  local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
  name: "vertex-bot",
  systemPrompt: "You are a concise assistant. Reply in one short sentence.",
});

const question = process.argv[2] ?? "Qual é a capital do Brasil?";
console.log(
  `[vertex] model=${modelId} project=${process.env.GOOGLE_CLOUD_PROJECT} ` +
    `location=${process.env.GOOGLE_CLOUD_LOCATION ?? "us-central1"} question="${question}"`,
);

const run = await agent.send(question);
const result = await run.wait();
console.log(`[vertex] status=${result.status} resultLen=${(result.result ?? "").length}`);
console.log(result.result ?? "(no reply)");

await agent.dispose();

```

## Run

```bash
cd examples/vertex-bot
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/vertex-bot](https://github.com/usetheodev/theokit-sdk/tree/main/examples/vertex-bot)

---

# workflow-basics

Source: https://docs.usetheo.dev/theokit/guides/workflow-basics

A two-step `Workflow`: a `fn` step normalizes the input, an `agentStep` turns it into a

# workflow-basics

A two-step `Workflow`: a `fn` step normalizes the input, an `agentStep` turns it into a
one-sentence fact. Run with a real provider key:

```bash
OPENROUTER_API_KEY=... pnpm run
```

## Code

```ts title="run.ts"
/**
 * Workflow basics — declarative multi-step orchestration.
 *
 * `Workflow.create()` builds a pipeline of steps. A `fn` step is a plain (typed) function;
 * an `agentStep` renders a prompt and calls an agent. `.commit()` freezes the workflow, then
 * `.run(input)` executes it and returns the terminal `WorkflowRun` (status + output).
 *
 * NOTE the imports: `Agent` is on the main entrypoint; `Workflow` / `fn` / `agentStep` live on
 * the `@theokit/sdk/workflow` sub-path.
 */
import { Agent } from "@theokit/sdk";
import { Workflow, agentStep, fn } from "@theokit/sdk/workflow";

const writer = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You write exactly one concise, factual sentence. No preamble.",
});

const factPipeline = Workflow.create({ name: "topic-fact" })
  // Step 1 — a pure function normalizes the input to a clean topic string (no LLM).
  .then(fn("normalize", (input: { topic: string }) => input.topic.trim().toLowerCase()))
  // Step 2 — an agent step turns the normalized topic into a one-sentence fact. Workflow state
  // flows untyped between steps, so the renderer receives `unknown` — coerce it with String().
  .then(agentStep("write", writer, (topic) => `Write a one-sentence fact about ${String(topic)}.`))
  .commit();

const run = await factPipeline.run({ topic: "  The Moon  " });

console.log("Status:", run.status);
console.log("Output:", run.output);

await writer.dispose();

// --- validate output (fail loud) ---
if (run.status !== "completed" || run.output == null) {
  console.error("workflow did not complete:", JSON.stringify(run.error ?? run.status));
  process.exit(1);
}

```

## Run

```bash
cd examples/workflow-basics
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/workflow-basics](https://github.com/usetheodev/theokit-sdk/tree/main/examples/workflow-basics)

---

# workflows

Source: https://docs.usetheo.dev/theokit/guides/workflows

Multi-step pipeline: validate → classify (LLM) → branch (billing/support) → summarize.

# workflows

Multi-step pipeline: validate → classify (LLM) → branch (billing/support) → summarize.

Demonstrates the `Workflow.create / .then / .branch / .commit / .run` API
(Adoption Roadmap #5; ADRs D230-D248).

## Run (Ollama)

```bash
ollama serve &
ollama pull llama3.2:3b
pnpm install
pnpm run run
```

## Run (OpenRouter cloud)

```bash
export OPENROUTER_API_KEY=sk-or-...
pnpm run run
```

## What it shows

- `Workflow.create({ name }).then(fn(...)).then(agentStep(...)).branch(...).commit()` declarative DSL.
- `fn(id, handler)` for pure-function steps (validation, transformation).
- `agentStep(id, agent, promptTemplate)` for LLM-driven steps.
- `.branch([[predicate, [...]], [...]], { fallback })` first-match-wins routing.
- `WorkflowRun.stepResults` array with per-step status, attempts, duration.

## v1 limitations

- **LocalAgent only** (`CloudAgent` workflow steps throw `UnsupportedRunOperationError`, ADR D244).
- **Saga compensation deferred to v1.2** — `compensate?` slot reserved on `FnStep` but engine not yet implemented (ADR D238).
- **Persistence**: default in-memory. Use `Workflow.create({ persistence: { backend: "json", dir: ".theokit/workflows" } })` for filesystem snapshots.

## Other primitives not shown

- `.parallel([branchA, branchB], { concurrency })` — fan-out N concurrent branches.
- `.foreach("sourceStepId", innerStep, { concurrency })` — map over array output.
- `.dowhile(step, cond, { maxIterations })` — loop until predicate is false (default cap 100).
- `.sleep(ms)` — pause for fixed duration.
- `.suspend({ payloadSchema })` + `Workflow.resume({ runId, payload })` — human-in-the-loop.

## Code

```ts title="run.ts"
/**
 * Workflow demo (Adoption Roadmap #5; ADRs D230-D248).
 *
 * Demonstrates a 4-step refund triage pipeline:
 *   validate → classify (LLM) → branch (billing vs support) → summarize
 *
 * Run:
 *   pnpm install
 *   pnpm run run
 *
 * Requires `OPENROUTER_API_KEY` OR a local Ollama daemon listening on
 * `OLLAMA_HOST` (default http://localhost:11434).
 */

import { Agent, Workflow, agentStep, fn } from "@theokit/sdk";

const OPENROUTER = process.env.OPENROUTER_API_KEY;
const useOllama = OPENROUTER === undefined || OPENROUTER.length === 0;

const baseConfig = useOllama
  ? {
      model: { id: "ollama/llama3.2:3b" },
      local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
    }
  : {
      apiKey: OPENROUTER!,
      model: { id: "openai/gpt-4o-mini" },
      local: { cwd: process.cwd(), sandboxOptions: { enabled: false } as const },
    };

async function main(): Promise<void> {
  const classifier = await Agent.create({
    ...baseConfig,
    name: "classifier",
    systemPrompt:
      "You classify customer support requests. Reply with EXACTLY one word: BILLING, SUPPORT, or OTHER.",
  });
  const billingExpert = await Agent.create({
    ...baseConfig,
    name: "billing",
    systemPrompt:
      "You are a billing specialist. Answer concisely (1-2 sentences) about invoices, refunds, charges.",
  });
  const supportExpert = await Agent.create({
    ...baseConfig,
    name: "support",
    systemPrompt:
      "You are a technical support specialist. Answer concisely (1-2 sentences) about install, config, troubleshooting.",
  });

  const wf = Workflow.create<{ claim: string }, string>({ name: "refund-pipeline" })
    .then(
      fn<{ claim: string }, { claim: string; ts: number }>("validate", (input) => {
        if (!input.claim || input.claim.length < 3) {
          throw new Error("claim must be at least 3 characters");
        }
        return { ...input, ts: Date.now() };
      }),
    )
    .then(
      agentStep(
        "classify",
        classifier,
        (input) => `Classify: "${(input as { claim: string }).claim}"`,
      ),
    )
    .branch(
      [
        [(out) => String(out).toUpperCase().includes("BILLING"), [
          agentStep("billing_resolve", billingExpert, "Handle the billing question."),
        ]],
        [(out) => String(out).toUpperCase().includes("SUPPORT"), [
          agentStep("support_resolve", supportExpert, "Handle the support question."),
        ]],
      ],
      {
        id: "decide",
        fallback: [
          fn("escalate", () => "Escalating to a human agent."),
        ],
      },
    )
    .commit();

  console.log("Running workflow…");
  const run = await wf.run({ claim: "I was charged twice last month for the Pro plan." });
  console.log("");
  console.log("Status:", run.status);
  console.log("Duration:", run.durationMs, "ms");
  console.log("Steps:");
  for (const sr of run.stepResults) {
    console.log(`  - [${sr.kind}] ${sr.stepId} (${sr.status}, ${sr.attempts} attempt, ${sr.durationMs}ms)`);
  }
  console.log("");
  console.log("Final output:", run.output);

  await classifier.dispose();
  await billingExpert.dispose();
  await supportExpert.dispose();
}

main().catch((err) => {
  console.error("workflow demo failed:", err);
  process.exit(1);
});

```

## Run

```bash
cd examples/workflows
cp .env.example .env  # fill in keys
pnpm install
pnpm run run
```

## Repository

[examples/workflows](https://github.com/usetheodev/theokit-sdk/tree/main/examples/workflows)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/handoffs/advanced

Handoff.create descriptor options, the onHandoff hook, input filtering and tool scoping, depth control, the handoff result, and typed errors.

# Advanced handoffs

Verified against `@theokit/sdk-handoff`.

## `Handoff.create` — a configured descriptor

`asPlugin` accepts bare agents or `HandoffDescriptor`s. Build one with `Handoff.create(target,
options)` to customize the transfer tool:

```ts
import { Handoff } from "@theokit/sdk-handoff";
import { z } from "zod";

const toBilling = Handoff.create(billing, {
  toolName: "escalate_to_billing",          // default: transfer_to_<name>
  toolDescription: "Hand off billing and refund questions.",
  inputType: z.object({ reason: z.string() }), // typed structured input the model must supply
  onHandoff: (ctx, parsed) => log("handoff", ctx.senderAgentId, "→", ctx.receiverAgentId, ctx.currentDepth, parsed),
  inputFilter: (history) => history.slice(-4), // trim what the receiver sees
  tools: ["read_invoice"],                     // scope the receiver to a subset of tools
  isEnabled: (ctx) => ctx.currentDepth < 2,    // gate the handoff dynamically
});

Agent.create({ …, plugins: [Handoff.asPlugin({ targets: [toBilling] })] });
```

## `HandoffOptions`

| Option | Effect |
| --- | --- |
| `toolName` / `toolDescription` | Override the synthetic transfer tool's name / description. |
| `inputType` (Zod) | Require typed structured input the model fills when transferring. |
| `onHandoff(ctx, parsed)` | Side-effect hook fired at the transfer (telemetry, logging). |
| `inputFilter(history)` | Trim / rewrite the conversation the receiver inherits. |
| `tools` | Restrict the receiver to a subset of tool names. |
| `isEnabled` | Boolean or predicate — enable/disable the handoff per context. |

## Depth control

`Handoff.asPlugin({ maxHandoffDepth })` (or `Agent.create({ maxHandoffDepth })`, default **5**) caps
the transfer chain per `send()`. Set to `0` to disable handoff tools entirely. Exceeding the cap
throws `HandoffLoopError`; a direct A→B→A ping-pong throws `HandoffPairLoopError`.

## The handoff result

Each transfer produces a `HandoffResult` for telemetry:

```ts
interface HandoffResult { from: string; to: string; depth: number; toolName: string; reasonFromLlm?: string; }
```

## Typed errors

- **`HandoffLoopError`** — the chain exceeded `maxHandoffDepth`.
- **`HandoffPairLoopError`** — two agents ping-ponged control.
- **`HandoffNameCollisionError`** — two targets resolved to the same transfer-tool name.
- **`HandoffReceiverDisposedError`** — the target agent was disposed before it could take over.

## Reference

- [`Handoff`](/theokit/reference/Handoff) · [`HandoffDescriptor`](/theokit/reference/HandoffDescriptor) · [`HandoffOptions`](/theokit/reference/HandoffOptions) · [`HandoffResult`](/theokit/reference/HandoffResult) · [`HandoffLoopError`](/theokit/reference/HandoffLoopError)

---

# Overview

Source: https://docs.usetheo.dev/theokit/handoffs

Transfer control from one agent to another — unlike a subagent (delegate-and-return), the receiver takes over the conversation from that point.

# Handoffs

A **handoff** transfers control: agent A decides agent B should take over, and B continues the
conversation from there. Contrast with a [subagent](/theokit/subagents), which delegates a sub-task
and gets the answer *back* — a handoff does not return.

Handoffs ship in the companion package **`@theokit/sdk-handoff`** (`npm i @theokit/sdk-handoff`). The
preferred 2.x wiring is a plugin:

```ts
import { Agent } from "@theokit/sdk";
import { Handoff } from "@theokit/sdk-handoff";

const billing = await Agent.create({ apiKey, model, name: "billing", systemPrompt: "You handle billing." });

const support = await Agent.create({
  apiKey, model, name: "support",
  systemPrompt: "You are front-line support. Transfer billing questions.",
  plugins: [Handoff.asPlugin({ parentAgentId: "support", targets: [billing] })],
});
```

- **`Handoff.asPlugin({ targets, parentAgentId?, maxHandoffDepth? })`** — wraps each target in a
  synthetic `transfer_to_<name>` tool the model can call to hand off. The preferred wiring.
- **`Handoff.create(target, options?)`** — build a `HandoffDescriptor` (custom `toolName`,
  `inputType`, `onHandoff` hook, tool scoping) to pass in `targets`.
- **`maxHandoffDepth`** — caps the chain per `send()` (default 5); exceeding throws `HandoffLoopError`.

The legacy `Agent.create({ handoffs: [target] })` option still works while `@theokit/sdk-handoff` is
installed, but `plugins: [Handoff.asPlugin(...)]` is the 2.x pattern.

## Subagent vs Handoff vs Squad

| You want | Reach for |
| --- | --- |
| B does a sub-task and returns the answer to A | [Subagent](/theokit/subagents) |
| B **takes over** the conversation from A | **Handoff** (this page) |
| A fixed pipeline A → B → C in order | [Squad](/theokit/squad) |

## Next

- [Transfer control](/theokit/handoffs/transfer-control) — wire a handoff plugin and trigger a transfer.
- [Advanced](/theokit/handoffs/advanced) — `Handoff.create` options, the `onHandoff` hook, depth, and errors.

## Reference

- [`Handoff`](/theokit/reference/Handoff) · [`HandoffDescriptor`](/theokit/reference/HandoffDescriptor) · [`HandoffOptions`](/theokit/reference/HandoffOptions)

---

# Transfer control

Source: https://docs.usetheo.dev/theokit/handoffs/transfer-control

Wire a handoff plugin so a front-line agent transfers a conversation to a specialist — the specialist takes over from that turn.

# Transfer control

Give the front-line agent a `Handoff.asPlugin({ targets })`. The SDK exposes each target as a
`transfer_to_<name>` tool; when the model calls it, control **passes to the receiver**, which answers
the rest of the turn. This drives real models, so it needs a working key.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";
import { Handoff } from "@theokit/sdk-handoff";

// The specialist that will take over.
const billing = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  name: "billing",
  systemPrompt: "You are the billing specialist. Answer billing questions precisely.",
});

// Front-line support, wired to hand off to billing.
const support = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  name: "support",
  systemPrompt:
    "You are front-line support. For any billing or refund question you MUST transfer to the billing agent.",
  plugins: [Handoff.asPlugin({ parentAgentId: "support", targets: [billing] })],
});

const result = await (await support.send("I was double-charged — can I get a refund?")).wait();
console.log("Status:", result.status);
console.log("Reply: ", result.result); // answered by billing after the transfer

await support.dispose();
await billing.dispose();
```

## What it shows

- **`Handoff.asPlugin({ targets: [billing] })`** registers a `transfer_to_billing` tool on `support`.
  The model calls it to hand off; `support` does not resume — `billing` finishes the turn.
- **The receiver takes over** — unlike a subagent (delegate-and-return), a handoff transfers the
  conversation. `RunResult.origin` and the handoff telemetry (`HandoffResult`: `from`, `to`, `depth`)
  record who transferred to whom.
- **`maxHandoffDepth`** (default 5) caps how many transfers a single `send()` may chain, so
  A→B→A→B… can't loop unbounded — exceeding it throws `HandoffLoopError`.

Handoffs live in **`@theokit/sdk-handoff`** and drive real models, so this example runs from your own
checkout with a provider key rather than the live sandbox. (A release of `@theokit/sdk-handoff`
rebuilt against `@theokit/sdk@3.x` is pending — until then, install it from source.)

---

# Handoffs

Source: https://docs.usetheo.dev/theokit/handoffs

Route a conversation between specialists.

# Handoffs

Typed inter-agent dispatch with loop protection. Ships as its own package and rides on the plugin seam.

| Capability | What it adds |
| --- | --- |
| `@theokit/sdk-handoff` | `Handoff.create` — typed handoff descriptors |
| Loop protection | Guards against ping-pong handoffs |
| `Handoff.asPlugin` | Wire handoffs as a plugin |

## Reference

See the [Handoffs concept](/theokit/concepts/handoffs) for the deep dive.

---

# Add a file-based hook

Source: https://docs.usetheo.dev/theokit/hooks/add-a-file-based-hook

Gate the agent with a shell command from disk — write a .theokit/hooks.json (identical shape to Claude Code), block a dangerous tool call, no plugin code.

# Add a file-based hook

File-based hooks run a **shell command** on a lifecycle event, configured in `.theokit/hooks.json`. The format is **identical to Claude Code's `settings.json` hooks** — same nested shape, same `matcher` / `type: "command"` / `timeout`. Local runtime only.

## 1. Write `.theokit/hooks.json`

```json title=".theokit/hooks.json"
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [
          { "type": "command", "command": "node .theokit/policy.js", "timeout": 30 }
        ]
      }
    ]
  }
}
```

| Field | Meaning |
| --- | --- |
| `hooks.<Event>` | An array of matcher-groups for that lifecycle event (see the events below). |
| `matcher` | Regex — for `PreToolUse` / `PostToolUse` it matches the **tool name** (`shell`, `write_file`, …). Omit to match every tool. |
| `hooks[]` | The commands to run when the matcher hits. |
| `type` | Always `"command"` (a shell command). |
| `command` | The shell command (run via `sh -c`). |
| `timeout` | Optional, in **seconds** (default 30). |

## 2. Write the command

The command receives the hook **payload as JSON on stdin** — `{ event, tool?, input?, agentId?, runId? }` (`input` is the tool's arguments). **A non-zero exit on `PreToolUse` / `UserPromptSubmit` BLOCKS** the tool/run; the model sees the block and continues. You can also print `{"decision":"deny","reason":"…"}` on stdout for a clean message.

```js title=".theokit/policy.js"
let data = "";
process.stdin.on("data", (c) => (data += c));
process.stdin.on("end", () => {
  const { input } = JSON.parse(data);
  const cmd = typeof input?.command === "string" ? input.command : "";
  if (/(^|\s)(rm|sudo|dd|mkfs|kill)(\s|$)/.test(cmd)) {
    process.stderr.write(`Policy denied: ${cmd}`);
    process.exit(1);          // ← blocks the shell tool call
  }
  process.exit(0);            // allow
});
```

## 3. Enable it

File-based hooks are discovered only when the agent opts into project settings:

```ts
const agent = await Agent.create({
  apiKey, model,
  local: { cwd: projectRoot, settingSources: ["project"] },   // discovers .theokit/hooks.json
});
```

Edit `.theokit/hooks.json` while the agent is alive? Call `await agent.reload()` to pick up the change without disposing.

## Events

The SDK fires five lifecycle points; use the Claude Code event names in the config:

| Config event | Fires | Can block? |
| --- | --- | --- |
| `PreToolUse` | before a tool call (filtered by `matcher`) | **yes** (non-zero exit) |
| `PostToolUse` | after a tool call | observe |
| `UserPromptSubmit` | before a `send()` starts | **yes** |
| `Stop` | when the run ends | observe |

> A Claude Code event with no SDK firing point (`SessionStart`, `SubagentStop`, `PreCompact`, …) is skipped with a warning rather than silently accepted — the runtime would never fire it.

## When to use which hook surface

- **Just observing tool calls in code?** → the agent-level [`onTool*` callbacks](./observe-the-tool-lifecycle).
- **Vetoing / rewriting / session logic in code?** → a [plugin hook](./advanced) (`ctx.on("pre_tool_call", …)`).
- **Org policy as a shell command, no code?** → `.theokit/hooks.json` (this page).

## Reference

- [`HookName`](/theokit/reference/HookName) · [`Agent`](/theokit/reference/Agent) · [`PreToolCallContext`](/theokit/reference/PreToolCallContext)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/hooks/advanced

The plugin hook names and their contexts, vetoing a tool call, transforming results, session hooks, and file-based shell hooks.

# Advanced hooks

Verified against `@theokit/sdk` (`internal/plugins/types.ts`, `types/agent.ts`).

## Plugin hooks — `ctx.on(name, handler)`

A `Plugin` registers hooks in its `register(ctx)`:

```ts
import { Plugin } from "@theokit/sdk";

const audit = Plugin.create({
  name: "audit",
  register(ctx) {
    ctx.on("pre_tool_call", (c) => { /* c: PreToolCallContext */ });
    ctx.on("on_session_start", () => ctx.injectMessage("Session started.", "system"));
  },
});

Agent.create({ …, plugins: [audit] });
```

### The hook names

| Hook | When | Can change the run? |
| --- | --- | --- |
| `pre_tool_call` | before a tool runs | **veto** (return `{ block: true, message }`) |
| `post_tool_call` | after a tool returns | observe |
| `pre_llm_call` / `post_llm_call` | around each model call | observe |
| `transform_tool_result` | after a tool result | **rewrite** the result |
| `transform_llm_output` | after the model's output | **rewrite** the output |
| `on_session_start` / `on_session_end` | session boundaries | `injectMessage` (start) |
| `pre_user_send` / `post_assistant_reply` | around a turn (memory-adapter hooks) | inject `<memory-context>` |

### Veto a tool call — `pre_tool_call`

```ts
ctx.on("pre_tool_call", (c) => {
  // c: { name, args, agentId, runId }
  if (c.name === "delete_file") return { block: true, message: "deletes are not allowed" };
});
```

Returning a `PreToolCallDecision` (`{ block: true, message }`) stops the tool — the model sees the
`message` as the tool result and continues. Return nothing to allow it.

## Plugin capabilities beyond hooks

The same `ctx` also exposes:

- **`ctx.registerTool(tool)`** — add a tool from the plugin (this is how `Handoff.asPlugin` injects
  `transfer_to_*` tools).
- **`ctx.registerCommand(name, handler)`** — register a slash-command-style handler.
- **`ctx.injectMessage(content, role?)`** — inject a user/system message into the next turn (v1
  supports it from the `on_session_start` context).

## File-based hooks — `.theokit/hooks.json`

With `local: { settingSources: ["project"] }`, a `.theokit/hooks.json` runs a **shell command** on
lifecycle events. The config is the **same shape as Claude Code's** `settings.json` hooks — nested
`{ hooks: { PreToolUse: [{ matcher, hooks: [{ type: "command", command, timeout }] }] } }`, with the
events `PreToolUse` / `PostToolUse` / `UserPromptSubmit` / `Stop` mapped to the SDK's firing points.
Local runtime only; useful for org-wide policy (run a linter on every write, block a command pattern)
without shipping plugin code. (The old `.theokit/hooks/*.md` markdown form is no longer supported — a stray dir warns to migrate.)

**See the step-by-step: [Add a file-based hook](/theokit/hooks/add-a-file-based-hook)** — the JSON
format, the JSON-on-stdin payload, and blocking a tool via a non-zero exit.

## Which surface

- **Just observing tool calls?** → the agent-level `onTool*` callbacks (simplest).
- **Vetoing / rewriting / session logic in code?** → a plugin with `ctx.on`.
- **Org policy as shell commands, no code?** → `.theokit/hooks.json`.

## Reference

- [`Plugin`](/theokit/reference/Plugin) · [`PluginContext`](/theokit/reference/PluginContext) · [`HookName`](/theokit/reference/HookName) · [`PreToolCallContext`](/theokit/reference/PreToolCallContext) · [`PreToolCallDecision`](/theokit/reference/PreToolCallDecision)

---

# Overview

Source: https://docs.usetheo.dev/theokit/hooks

Observe and gate the agent lifecycle — tool-lifecycle callbacks on the agent, plugin hooks over the run, and file-based shell hooks discovered from disk.

# Hooks

Hooks let you **observe and gate** what an agent does — log tool calls, veto a dangerous one, inject
context, react to session boundaries. There are three surfaces:

- **Tool-lifecycle callbacks** — `onToolStart` / `onToolEnd` / `onToolError` on `AgentOptions`. The
  simplest surface: fire around every tool call for telemetry.

  ```ts
  const agent = await Agent.create({
    apiKey, model, tools: [myTool],
    onToolStart: ({ toolName, args }) => log("→", toolName, args),
    onToolEnd: ({ toolName, durationMs }) => log("✓", toolName, durationMs),
    onToolError: ({ toolName, error }) => log("✗", toolName, error.message),
  });
  ```

- **Plugin hooks** — a `Plugin` registers handlers with `ctx.on(name, handler)` over the run
  lifecycle: `pre_tool_call` (can veto), `post_tool_call`, `pre_llm_call`, `post_llm_call`,
  `transform_tool_result`, `transform_llm_output`, `on_session_start` / `on_session_end`, and the
  memory-adapter hooks `pre_user_send` / `post_assistant_reply`.

- **File-based hooks** — a `.theokit/hooks.json` (the **same shape as Claude Code's** `settings.json`
  hooks) discovered from the working directory (with `settingSources: ["project"]`) runs a **shell
  command** on lifecycle events. No plugin code; local runtime only.

## Next

- [Observe the tool lifecycle](/theokit/hooks/observe-the-tool-lifecycle) — a runnable `onTool*` example.
- [Add a file-based hook](/theokit/hooks/add-a-file-based-hook) — write a `.theokit/hooks.json` shell hook that blocks a dangerous tool call.
- [Advanced](/theokit/hooks/advanced) — the plugin hook names + contexts, vetoing, and file-based hooks.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`Plugin`](/theokit/reference/Plugin) · [`PreToolCallContext`](/theokit/reference/PreToolCallContext) · [`HookName`](/theokit/reference/HookName)

---

# Observe the tool lifecycle

Source: https://docs.usetheo.dev/theokit/hooks/observe-the-tool-lifecycle

Attach onToolStart / onToolEnd / onToolError to an agent and watch them fire around a tool call — a deterministic lifecycle over a real run.

# Observe the tool lifecycle

The `onToolStart` / `onToolEnd` / `onToolError` callbacks fire around every tool call — the simplest
hook surface. The **set and order** of hooks is deterministic (the same lifecycle every run), even
though the model's reply varies; the model just has to call the tool.

```ts title="run.ts"
import { Agent, Tool } from "@theokit/sdk";
import { z } from "zod";

const events: string[] = [];

const clock = Tool.create({
  name: "get_time",
  description: "Return the current time in a city.",
  inputSchema: z.object({ city: z.string() }),
  handler: ({ city }) => `12:00 in ${city}`,
});

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You MUST call get_time for any time question. Answer in one line.",
  tools: [clock],
  onToolStart: ({ toolName }) => events.push(`onToolStart:${toolName}`),
  onToolEnd: ({ toolName, durationMs }) => events.push(`onToolEnd:${toolName}(${durationMs >= 0 ? "ok" : "?"})`),
  onToolError: ({ toolName }) => events.push(`onToolError:${toolName}`),
});

const result = await (await agent.send("What time is it in Tokyo?")).wait();
console.log("hooks fired:", events.join(" -> "));
console.log("status:     ", result.status);

await agent.dispose();
```

## Output

The lifecycle is deterministic in structure — start then end around the one tool call:

```text
hooks fired: onToolStart:get_time -> onToolEnd:get_time(ok)
status:      finished
```

## What it shows

- **`onToolStart({ toolName, args, callId, conversationId })`** fires before the handler runs;
  **`onToolEnd({ …, result, durationMs })`** after it returns successfully.
- **`onToolError({ …, error, attempt })`** fires when the handler throws **or** the args fail schema
  validation — `error` is always an `Error`. (Try a handler that throws to see it.)
- These are pure observers — they can't change the tool result. To **veto** or **rewrite**, use a
  plugin `pre_tool_call` hook (see [Advanced](/theokit/hooks/advanced)).

## Example

Full runnable source:
[`examples/hooks-lifecycle`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/hooks-lifecycle).

---

# Plugins and hooks

Source: https://docs.usetheo.dev/theokit/hooks

Extend the agent loop.

# Plugins and hooks

`Plugin.create` adds lifecycle hooks — before a tool call, before a send, after a reply. Handoffs and the semantic cache ride on this seam.

| Capability | What it adds |
| --- | --- |
| `Plugin.create` | The plugin factory |
| Hooks | `preToolCall` / `preUserSend` / `postAssistantReply` |

## Reference

See the [Plugins and hooks concept](/theokit/concepts/hooks) for the deep dive.

---

# Introduction

Source: https://docs.usetheo.dev/theokit

Build AI agents in TypeScript — the primitives, every capability you can attach, and the full-stack framework.

# TheoKit

Build AI agents in TypeScript. TheoKit gives you a few **primitives** — Agent, Workflow,
Squad — and a large set of **capabilities** you attach to them. A primitive plus its
capabilities is a component of your agent system. Plain TypeScript: no DSL, no YAML.

Reach for the **SDK** to embed an agent in any Node process — a script, a CI job, a
backend. Reach for the **full-stack framework** (`create-theokit`) when you're building a
whole app. Same primitives underneath.

## Primitives

The things you create.

| Primitive | What it is | |
| --- | --- | --- |
| **Agent** | a model with instructions and tools that runs a task | [Agents](/theokit/agents) |
| **Workflow** | declarative multi-step orchestration (parallel / branch / foreach / suspend) | [Workflows](/theokit/concepts/workflows) |
| **Squad** | a sequential team of agents over a workflow | [Squad](/theokit/concepts/handoffs) |

## Foundations

Start here — the building blocks every agent uses.

| Foundation | What it adds |
| --- | --- |
| **Providers & Models** | Multi-provider access behind one API + an offline capability catalog. `Provider.create` for your own; built-in Bedrock, Vertex, and local (Ollama). |
| **Prompts & Instructions** | Static or per-send system prompts, hierarchical project instructions, and personality presets. |
| **Tools** | `Tool.create` — typed functions the model can call; argument sanitization, typed `ToolError`, multimodal results, and built-in coding tools. |
| **Streaming** | Iterate `run.stream()` over the `SDKMessage` event union, with pure readers and a typed run-event stream. |

## Capabilities

What you attach to a primitive.

| Group | Capabilities |
| --- | --- |
| **Memory & context** | Memory (vector + FTS recall, dreaming consolidation) · Sessions & scopes · Compaction · Conversation storage |
| **Multi-agent** | Subagents (`agent.fork`) · Handoffs (`@theokit/sdk-handoff`) · Agent-to-agent (mailbox + bus) |
| **Structured & generation** | `generateObject` / `generate` · `streamObject` · Batch · Schema normalizer (Zod / JSON Schema / ArkType / Valibot) |
| **Control & safety** | Guardrail processors · Plugins & hooks · Permissions engine · Secret redaction & path safety |
| **Operations** | Cron schedules · Tasks & job queue · Evals & scorers · Budget & cost · Semantic cache · Telemetry (OpenTelemetry) |

## Connections

| Connection | What it does |
| --- | --- |
| **MCP (client)** | Connect an agent to external MCP servers over stdio or HTTP/SSE. |
| **Sandbox** | Sandboxed code execution + repo provisioning. |
| **Filesystem** | A pluggable, boundary-enforced filesystem provider. |
| **ACP** | Drive an agent from Zed / Cursor / Claude Desktop over JSON-RPC (`@theokit/acp`). |
| **Subscriptions** | Typed server RPC over SSE / WebSocket with resume tokens. |
| **HTTP server adapters** | Express / Fastify / Hono handlers + OAuth orchestration. |

## Extensibility

`Provider.create` (bring your own model) · `Tool.create` · `Plugin.create` · filesystem &
inline **Skills** · `AgentBuilder` / `AgentFactory.create`. Every agentic capability ships
as a low-level factory function first.

## Runtimes

Where an agent runs is chosen by the key you pass to `Agent.create()` — your code is
otherwise identical.

| Runtime | What it does | When |
| --- | --- | --- |
| **Local** | runs in-process against your own provider key | dev scripts, CI, your backend |
| **Cloud** | isolated VM (Theo PaaS — **pre-release**) | many agents in parallel, survive caller disconnect |

The cloud surface — `Agent.archive` / `delete`, artifacts, `autoCreatePR`, hosted
`Cron.list`, `Theokit.repositories` — depends on Theo PaaS and is **pre-release**. The
local runtime is the primary, fully-tested path.

## Start here

## Building a full app?

The TheoKit **framework** layers file-based routing, a streaming chat UI, typed server
routes, persistence, and auth on top of the same primitives.

```bash
npx create-theokit my-app
```

---

# Advanced

Source: https://docs.usetheo.dev/theokit/mcp/advanced

Full stdio and HTTP config, OAuth, per-request timeouts, the env-scrub policy, config-file discovery, and the typed MCP error codes.

# Advanced MCP

Verified against `@theokit/sdk` (`types/mcp.ts`, `types/agent.ts`).

## `McpStdioServerConfig`

```ts
{
  type: "stdio",              // optional; inferred from `command`
  command: "npx",             // required
  args: ["-y", "@scope/server"],
  env: { TOKEN: "…" },        // extra vars, merged AFTER the scrub policy (always win)
  cwd: "./workspace",         // local agents only; cloud rejects this field
  requestTimeoutMs: 30_000,    // per-request timeout (default 30s)
  envPolicy: "inherit-scrubbed", // "inherit-scrubbed" (default) | "all" | "core"
}
```

The spawned server inherits a **secret-scrubbed** environment by default — host vars matching
`*KEY*` / `*SECRET*` / `*TOKEN*` / `*PASSWORD*` / `*_AUTH*` are dropped so a third-party MCP binary
can't exfiltrate host secrets. `env` above is applied after the policy and always wins; pass
`envPolicy: "all"` to restore full inheritance.

## `McpHttpServerConfig`

```ts
{
  type: "http" | "sse",
  url: "https://mcp.example.com",
  headers: { Authorization: `Bearer ${token}` },
  auth: { CLIENT_ID: "…", oauth: { /* McpOAuthConfig */ } },
  requestTimeoutMs: 30_000,
}
```

- **`headers`** are passed through — `Authorization` works directly for a static token.
- **`auth`** (`McpAuthConfig` → `McpOAuthConfig`) drives an OAuth flow for servers that require it.
- The timeout is enforced via `AbortSignal.timeout` — a slow fetch rejects with `mcp_timeout`.

## Config-file discovery

With `local: { settingSources: ["project"] }`, the SDK loads a project **`.theokit/mcp.json`** (in the
working directory) and merges it with inline `mcpServers`. This keeps server definitions out of code
and shareable across a team.

## Typed errors

MCP failures surface as `NetworkError` with a machine `code`, so you can route them:

| Code | Meaning |
| --- | --- |
| `mcp_timeout` | No reply within `requestTimeoutMs`. |
| `mcp_disconnected` | The server connection dropped mid-run. |
| `mcp_closed` | The stdio server closed its stream. |
| `mcp_crashed` | The spawned stdio process exited abnormally. |

## Reference

- [`McpServerConfig`](/theokit/reference/McpServerConfig) · [`McpStdioServerConfig`](/theokit/reference/McpStdioServerConfig) · [`McpHttpServerConfig`](/theokit/reference/McpHttpServerConfig) · [`McpAuthConfig`](/theokit/reference/McpAuthConfig) · [`McpOAuthConfig`](/theokit/reference/McpOAuthConfig) · [`NetworkError`](/theokit/reference/NetworkError)

---

# Connect an MCP server

Source: https://docs.usetheo.dev/theokit/mcp/connect-an-mcp-server

Wire a stdio or HTTP MCP server via mcpServers so its tools join the agent — with the exact config shape for each transport.

# Connect an MCP server

`mcpServers` is a map of `name → McpServerConfig`. The SDK connects to each server at run time and
adds its tools to the agent's toolset (namespaced `mcp_<server>_<tool>`). Two transports:

## Stdio — spawn a local server

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
      // env?: extra vars for the spawned process   ·   cwd?: working dir (local only)
      requestTimeoutMs: 30_000,
    },
  },
});

const result = await (await agent.send("List the files under /data.")).wait();
console.log(result.result);

await agent.dispose();
```

The SDK spawns `npx …`, speaks MCP over stdio, and exposes the server's tools to the model. The
spawned process's environment is **secret-scrubbed** by default (see [Advanced](/theokit/mcp/advanced)).

## HTTP / SSE — reach a remote server

```ts
mcpServers: {
  github: {
    type: "http",                 // or "sse"
    url: "https://mcp.example.com",
    headers: { Authorization: `Bearer ${token}` },  // Authorization works here
    requestTimeoutMs: 30_000,
  },
}
```

## Or declare them in a file

Drop a `.theokit/mcp.json` in your project (with `local: { settingSources: ["project"] }`):

```json title=".theokit/mcp.json"
{
  "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
}
```

Inline `mcpServers` merge with the discovered ones.

MCP tools come from a real running server (spawned or remote), so this connects live rather than in
the docs sandbox. Copy the snippet into your own project with a server of your choice.

## What it shows

- **`mcpServers: { name: config }`** — each entry is a stdio (`command`/`args`) or HTTP (`type`/`url`)
  server; its tools join `agent.tools` under the `mcp_` namespace.
- **Timeouts are typed** — a stalled MCP request rejects with `NetworkError` (`code: "mcp_timeout"`),
  never hanging the loop.
- **Discovery** — a project `.theokit/mcp.json` is merged with inline config.

---

# Overview

Source: https://docs.usetheo.dev/theokit/mcp

Connect Model Context Protocol servers — stdio or HTTP — and their tools become the agent's tools, namespaced under mcp_.

# MCP (Model Context Protocol)

Point an agent at one or more **MCP servers** and their tools become the agent's tools — the model
calls them like any other. Configure them inline via `mcpServers`, or discover them from a
`.theokit/mcp.json` file.

```ts
const agent = await Agent.create({
  apiKey, model,
  mcpServers: {
    filesystem: { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"] },
    github: { type: "http", url: "https://mcp.example.com", headers: { Authorization: `Bearer ${token}` } },
  },
});
```

- **Stdio server** — `{ command, args?, env?, cwd? }`. The SDK spawns the process and speaks MCP over
  stdio; the spawned env is **secret-scrubbed** by default.
- **HTTP / SSE server** — `{ type: "http" | "sse", url, headers?, auth? }`. Reaches a remote MCP
  endpoint (with optional OAuth).
- **Discovered from disk** — a project `.theokit/mcp.json` is picked up automatically; inline
  `mcpServers` merge with it.

MCP tools surface under the `mcp_` namespace and appear in `agent.tools`. A request that gets no reply
within the timeout rejects with a typed `NetworkError` (`code: "mcp_timeout"`) instead of hanging the
loop.

## Next

- [Connect an MCP server](/theokit/mcp/connect-an-mcp-server) — the stdio + HTTP config, step by step.
- [Advanced](/theokit/mcp/advanced) — auth, timeouts, the env-scrub policy, config files, and typed errors.

## Reference

- [`McpServerConfig`](/theokit/reference/McpServerConfig) · [`McpStdioServerConfig`](/theokit/reference/McpStdioServerConfig) · [`McpHttpServerConfig`](/theokit/reference/McpHttpServerConfig) · [`McpAuthConfig`](/theokit/reference/McpAuthConfig)

---

# MCP

Source: https://docs.usetheo.dev/theokit/mcp

Connect an agent to external MCP servers.

# MCP

TheoKit is an MCP **client** — it connects an agent to external MCP servers over stdio or HTTP/SSE. (It does not expose an agent as an MCP server; see ACP for that.)

| Capability | What it adds |
| --- | --- |
| `mcpServers` | stdio + HTTP/SSE server configs on `Agent.create` |
| Auth | `McpAuthConfig` for authenticated servers |

## Reference

See the [MCP concept](/theokit/concepts/mcp) for the deep dive.

---

# Advanced

Source: https://docs.usetheo.dev/theokit/memory/advanced

The full MemorySettings, the agent.memory API, third-party adapters, embedding providers, vector backends, active recall, and dreaming.

# Advanced memory

Everything memory exposes, verified against the SDK.

## `MemorySettings` — `AgentOptions.memory`

```ts
memory: {
  enabled: true,
  namespace,                 // logical partition
  userId,                    // per-user isolation
  scope: "agent" | "user" | "team",   // whose memories this agent recalls
  storePath,                 // where the store lives (defaults under cwd)
  autoInject: true,          // prepend recalled facts as a <memory> block (default true)

  index: {
    tools: true,             // register memory_search + memory_get for the model (default true)
    backend: "sqlite-vec",   // or "lance" (@lancedb/lancedb, optional peer) for scale
    embedding: {             // omit → FTS-only (lexical) recall
      provider: "openai" | "mistral" | "openrouter" | "voyage" | "deepinfra",
      model,
    },
  },

  activeRecall: {            // opt-in blocking pass before each send()
    enabled: true,
    queryMode: "message" | "recent" | "full",  // what to search on
    timeoutMs,
    maxSummaryChars,
  },
}
```

Without an `embedding` provider the index runs **FTS-only** (keyword). Add one and recall becomes
**vector-based** (sqlite-vec, or LanceDB via `backend: "lance"`).

## The direct API — `agent.memory`

Populated when a memory adapter is registered (via `plugins`). Merges + dedupes across adapters:

```ts
await agent.memory.write("The deploy command is 'make ship'.");   // → MemoryId
const facts = await agent.memory.recall("deploy command", undefined, 5);  // semantic recall, top-k
await agent.memory.delete(id);                                     // routes to the owning adapter
agent.memory.adapter();                                           // the first registered adapter, or null
```

`write` fans out to all adapters; `recall` merges + dedupes; `delete` routes by the id's prefix.

## Adapters

| Adapter | Package |
| --- | --- |
| In-memory markdown (dependency-free) | `createInMemoryMarkdownProvider()` — `@theokit/sdk-memory` |
| Honcho | `@theokit/memory-honcho` |
| Mem0 | `@theokit/memory-mem0` |
| Supermemory | `@theokit/memory-supermemory` |
| Your own | implement the `MemoryProvider` port and register it |

Register an adapter's `.asPlugin()` (or the provider) via `Agent.create({ plugins: [...] })`.

## Embedding providers

`@theokit/sdk-memory` ships embedding adapters for **OpenAI, Mistral, OpenRouter, Voyage, DeepInfra,
Ollama** (and more). Configure via `memory.index.embedding.provider`; the same provider keys drive
recall vectors. A circuit breaker guards a flaky embedding endpoint.

## Dreaming — consolidation sweep

Over time, raw memories accumulate. `Memory.runDreamingSweep(options)` runs an **offline**
consolidation: it summarizes and compacts stored memories into higher-level facts (a "dreaming"
phase), returning a `DreamingSweepResult`. Run it on a schedule (see [Schedules](/theokit/schedules))
rather than in the hot path.

```ts
import { Memory } from "@theokit/sdk";

const result = await Memory.runDreamingSweep({ /* DreamingSweepOptions */ });
```

## Active recall query modes

`activeRecall.queryMode` controls what the pre-send pass searches on:

| Mode | Searches on |
| --- | --- |
| `"message"` | Just the current user message (cheapest). |
| `"recent"` | The recent conversation window. |
| `"full"` | The full assembled context (most thorough). |

## Reference

- [`MemorySettings`](/theokit/reference/MemorySettings) · [`AgentMemory`](/theokit/reference/AgentMemory) · [`MemoryProvider`](/theokit/reference/MemoryProvider) · [`DreamingSweepOptions`](/theokit/reference/DreamingSweepOptions)

---

# Overview

Source: https://docs.usetheo.dev/theokit/memory

Give an agent memory that survives the conversation — semantic recall of facts, auto-injected into context, backed by a store you choose.

# Memory

By default an agent only knows the current conversation. Turn on **memory** and it recalls relevant
facts from past sessions — semantically, not just by keyword — and can search them with tools.

```ts
const agent = await Agent.create({
  apiKey, model,
  local: { cwd },            // where the memory store lives
  memory: { enabled: true }, // that's the whole opt-in
});
```

With `memory.enabled`, the SDK persists session summaries, recalls the relevant ones before each
run, and (by default) injects them into the system prompt as a `<memory>` block — so the model just
*knows*.

## Two layers

| Layer | What it is |
| --- | --- |
| **Built-in memory** (`AgentOptions.memory`) | A local store (SQLite + FTS5, optionally a vector index) with `memory_search` / `memory_get` tools, active recall, and auto-injection. Zero external services. |
| **Memory adapters** (`agent.memory`) | Plug a third-party memory backend — [Honcho](https://honcho.dev), [Mem0](https://mem0.ai), Supermemory, or your own — via `plugins`, and use the direct `write` / `recall` / `delete` API. |

## What it does

- **Semantic recall** — find facts by meaning. With an embedding provider configured, recall is
  vector-based (sqlite-vec or LanceDB); without one, it runs FTS-only (lexical).
- **Auto-inject** — recalled facts prepend to the system prompt (`autoInject`, default `true`).
- **Memory tools** — `memory_search` and `memory_get` let the model query its own memory mid-run.
- **Active recall** — an opt-in blocking pass that runs *before* each `send()` and prepends an
  `<active-memory>` block.
- **Dreaming** — an offline consolidation sweep (`Memory.runDreamingSweep`) that summarizes and
  compacts stored memories.
- **Scoping** — `scope: "agent" | "user" | "team"`, `namespace`, and `userId` keep memories isolated.

## Next

- [Remember and recall](/theokit/memory/remember-and-recall) — a runnable two-turn example.
- [Advanced](/theokit/memory/advanced) — the full `MemorySettings`, the `agent.memory` API, adapters,
  embedding providers, backends, active recall, and dreaming.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`MemorySettings`](/theokit/reference/MemorySettings) · [`AgentMemory`](/theokit/reference/AgentMemory)

---

# Remember and recall

Source: https://docs.usetheo.dev/theokit/memory/remember-and-recall

Turn on memory, tell the agent a fact, then ask for it on a later turn — the agent recalls it from its store.

# Remember and recall

Set `memory: { enabled: true }` and give the agent a `cwd` for its store. It persists what it's told
and recalls the relevant fact on a later turn — no re-stating required.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: "./.memory" },   // where the memory store lives
  memory: { enabled: true },
  systemPrompt: "You are concise. Recall from memory when asked.",
});

// Turn 1 — tell the agent a fact.
const t1 = await (await agent.send("Remember this fact: my project's deploy command is 'make ship'.")).wait();
console.log("Turn 1:", t1.status);

// Turn 2 — a fresh question; memory recalls the fact.
const t2 = await (await agent.send("What is my project's deploy command? Answer with just the command.")).wait();
console.log("Turn 2:", t2.status);
console.log("Recalled:", t2.result);

await agent.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Turn 1: finished
Turn 2: finished
Recalled: make ship
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- **`memory: { enabled: true }`** — the whole opt-in. The SDK persists session summaries under `cwd`
  and recalls the relevant ones before each run.
- **Auto-inject** — the recalled fact is prepended to the system prompt as a `<memory>` block, so
  turn 2 answers `make ship` without you repeating it.
- **No external service** — the built-in store is local (SQLite + FTS5). Add an embedding provider for
  vector recall, or plug a third-party adapter — see [Advanced](/theokit/memory/advanced).

## Example

Full runnable source:
[`examples/memory-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/memory-basics).
EOF

---

# Advanced

Source: https://docs.usetheo.dev/theokit/observability/advanced

Every RunEvent type, and the full TelemetrySettings — exporters, content capture, service name, and auto-detection of Langfuse / Sentry / PostHog.

# Advanced observability

Verified against `@theokit/sdk` (`types/run-events.ts`, `types/agent.ts`).

## Every `RunEvent`

`onRunEvent` receives a discriminated union — branch on `.type`:

| Event | Fires when |
| --- | --- |
| `tool_progress` | A long-running tool reports progress. |
| `tripwire` | An input/output processor aborted (guardrail). |
| `rate_limit` | The provider returned 429 and the SDK is backing off / rotating keys. |
| `permission_denied` | A tool call was denied by the permission engine. |
| `task_started` / `task_updated` / `task_completed` | A background task's lifecycle. |
| `completion_check` | A per-send `completionCheck` verdict resolved. |
| `compact_boundary` | The conversation was compacted mid-run. |

```ts
await agent.send(msg, {
  onRunEvent: (ev) => {
    switch (ev.type) {
      case "rate_limit": backoffUi(); break;
      case "permission_denied": auditLog(ev); break;
      // …
    }
  },
});
```

The sink is out-of-band and best-effort — a throwing handler is swallowed so it can never break the
run.

## Tracing — `TelemetrySettings`

```ts
telemetry: {
  enabled: true,               // master switch (default false)
  includeContent: false,        // include prompts/responses/tool args as span events (default false)
  exporter: "console",          // "console" | "otlp" | a custom exporter (default "console")
  serviceName: "theokit-sdk",   // service name on emitted spans
  autoDetect: true,             // feature-detect installed OTel exporters (default true)
  disable: [],                  // opt out per adapter: "langfuse" | "sentry" | "posthog"
}
```

- **Spans** wrap the run, each LLM call, and each tool call, with status + token attributes.
- **`includeContent`** is **off by default** — prompts, responses, and tool args are NOT put on spans
  unless you opt in (avoid leaking sensitive content to your tracer).
- **Auto-detection** — with `autoDetect: true`, the SDK feature-detects installed observability libs
  (**Langfuse**, **Sentry**, **PostHog**) via `createRequire` and registers their exporters; use
  `disable` to opt a specific one out.
- **`exporter: "otlp"`** ships spans to any OpenTelemetry collector; a custom exporter object is passed
  through unchanged.

## Which to use

- **Reacting to progress in-app** (a UI, custom logs) → `onRunEvent`.
- **Distributed tracing / an observability platform** → `telemetry` (OTel).

They compose — run events for your own UX, spans for your tracing backend.

## Reference

- [`RunEvent`](/theokit/reference/RunEvent) · [`RunEventSink`](/theokit/reference/RunEventSink) · [`TelemetrySettings`](/theokit/reference/TelemetrySettings) · [`RunRateLimitEvent`](/theokit/reference/RunRateLimitEvent) · [`RunPermissionDeniedEvent`](/theokit/reference/RunPermissionDeniedEvent)

---

# Overview

Source: https://docs.usetheo.dev/theokit/observability

See inside a run — a typed runtime-event sink for progress signals, and OpenTelemetry tracing that auto-detects Langfuse, Sentry, and PostHog.

# Observability

Two ways to see what an agent is doing:

- **Runtime events — `onRunEvent`.** A typed, out-of-band sink that receives `RunEvent`s as a run
  progresses: `tool_progress`, `rate_limit`, `permission_denied`, `tripwire`, `task_*`,
  `completion_check`, `compact_boundary`. Best for reacting to progress in your own UI or logs.

  ```ts
  await agent.send(msg, { onRunEvent: (ev) => console.log(ev.type) });
  ```

- **Tracing — `telemetry`.** OpenTelemetry spans over the run. Turn it on and the SDK emits spans and
  **auto-detects** installed observability libs (Langfuse, Sentry, PostHog).

  ```ts
  const agent = await Agent.create({
    apiKey, model,
    telemetry: { enabled: true, exporter: "otlp", serviceName: "my-app" },
  });
  ```

A throwing `onRunEvent` sink never breaks the run (best-effort), and telemetry defaults to **off** —
observability is opt-in and never on the critical path.

## Next

- [Subscribe to run events](/theokit/observability/subscribe-to-run-events) — a runnable `onRunEvent` example.
- [Advanced](/theokit/observability/advanced) — every `RunEvent`, and the full `TelemetrySettings`.

## Reference

- [`RunEvent`](/theokit/reference/RunEvent) · [`RunEventSink`](/theokit/reference/RunEventSink) · [`TelemetrySettings`](/theokit/reference/TelemetrySettings)

---

# Subscribe to run events

Source: https://docs.usetheo.dev/theokit/observability/subscribe-to-run-events

Pass onRunEvent to send() and receive typed RunEvents as the run progresses — deterministic tripwire, no LLM.

# Subscribe to run events

`onRunEvent` is a typed sink that receives `RunEvent`s out-of-band while a run executes. Here an input
processor aborts the message before the LLM, emitting a `tripwire` event — so this is deterministic,
no LLM call.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const seen: string[] = [];

const agent = await Agent.create({
  apiKey: "theo_test_observability",
  model: { id: "openai/gpt-4o-mini" },
  inputProcessors: [
    {
      id: "no-secrets",
      processInput: (ctx) => {
        if (/password/i.test(ctx.message)) ctx.abort("blocked: message mentions a password");
      },
    },
  ],
});

const result = await (
  await agent.send("What is my password?", { onRunEvent: (ev) => seen.push(ev.type) })
).wait();

console.log("status:      ", result.status);
console.log("run events:  ", seen.join(", ") || "(none)");
console.log("tripwire:    ", JSON.stringify(result.tripwire));

await agent.dispose?.();
```

## Output

Deterministic — the guardrail aborts and emits a `tripwire` event:

```text
status:       cancelled
run events:   tripwire
tripwire:     {"reason":"blocked: message mentions a password","processorId":"no-secrets"}
```

## What it shows

- **`send(msg, { onRunEvent })`** streams typed `RunEvent`s as the run progresses — here just the
  `tripwire` from the aborted input.
- **The sink is best-effort** — a throwing `onRunEvent` never breaks the run.
- **The full set** — `tool_progress`, `rate_limit`, `permission_denied`, `tripwire`, `task_started` /
  `task_updated` / `task_completed`, `completion_check`, `compact_boundary` — is in
  [Advanced](/theokit/observability/advanced).

## Example

Full runnable source:
[`examples/observability-events`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/observability-events).

---

# Observability

Source: https://docs.usetheo.dev/theokit/observability

See what the agent did.

# Observability

OpenTelemetry spans, a typed run-event stream, and trajectory export — plus retry, concurrency, and persistence helpers.

| Capability | What it adds |
| --- | --- |
| Telemetry | OpenTelemetry spans for send / llm / tool |
| Trajectory export | `toShareGptTrajectory` |
| Helpers | Retry · Concurrency · Persistence |

## Reference

See the [Observability concept](/theokit/concepts/telemetry) for the deep dive.

---

# Agent-aware columns

Source: https://docs.usetheo.dev/theokit/orm/concepts/agent-columns

Auto-fill agentId / runId / conversationId from ambient AgentContext on insert and update.

Tables that carry any of the tracked columns — `agentId`, `runId`, `conversationId` — get
those fields **auto-filled** from an ambient `AgentContext` whenever you `insert` or
`update` through a repository. This keeps agent provenance on your rows without threading
context through every call.

## Setting the context

Wrap your work in `withAgentContext`. Any repository write inside the callback (across
`await` boundaries) sees the context:

```ts
import { withAgentContext } from "@theokit/orm";

await withAgentContext({ agentId: "a_1", runId: "r_42", conversationId: "c_7" }, async () => {
  await repo.insert({ id: "e1", type: "message" });
  // the row is persisted with agentId="a_1", runId="r_42", conversationId="c_7"
});
```

`AgentContext` is `{ agentId?, runId?, conversationId? }` — set only the fields you have.

## Fill rules

On `insert` / `update`, for each tracked column that exists **on the table**:

- fill it from the matching `AgentContext` field, **only** if the value you passed is
  `undefined` (an explicit value you provide always wins);
- columns not present on the table are ignored;
- if the table has tracked columns but **no** context is active, the row is written
  unchanged — and in non-production a one-time `console.warn` per table reminds you to wrap
  the call in `withAgentContext`.

  Reading the current context anywhere: `getAgentContext()` returns the active
  `AgentContext` or `undefined`. It's backed by `AsyncLocalStorage`, so it's safe under
  concurrent requests.

## Example table

```ts
import { sqliteTable, text } from "drizzle-orm/sqlite-core";

export const events = sqliteTable("events", {
  id: text("id").primaryKey(),
  type: text("type").notNull(),
  agentId: text("agent_id"),
  runId: text("run_id"),
  conversationId: text("conversation_id"),
});
```

Only the columns your table actually declares are filled — a table with just `agentId`
gets only `agentId` populated.

---

# Errors

Source: https://docs.usetheo.dev/theokit/orm/concepts/errors

The typed error hierarchy @theokit/orm throws.

All ORM errors extend a common `OrmError` base, so you can catch the whole family or narrow
by class. Every message carries concrete context — the table, the method, the id, or the
configuration that was wrong.

| Error | Extends | Thrown when |
| --- | --- | --- |
| `OrmError` | `Error` | Base class — catch this to handle any ORM error. |
| `OrmConfigurationError` | `OrmError` | Misconfiguration: no primary key, `forFeature` before `forRoot`, missing `db`, unsupported `dialect`, a driver without `.returning()` / `.transaction()`, or a `@Transactional` method with no bound `DataSource`. |
| `OrmValidationError` | `OrmError` | Bad input at call time: an invalid `id` (null/undefined/empty/non-scalar), or an `insert`/`update` that returned zero rows. |
| `OrmSchemaExportError` | `OrmError` | A table couldn't be introspected during schema export. |

## Catching

```ts
import { OrmError, OrmConfigurationError, OrmValidationError } from "@theokit/orm";

try {
  await repo.update(id, patch);
} catch (err) {
  if (err instanceof OrmValidationError) {
    // caller sent bad input — surface a 400
  } else if (err instanceof OrmConfigurationError) {
    // wiring/setup bug — fix the configuration, don't retry
  } else if (err instanceof OrmError) {
    // any other ORM-level failure
  }
  throw err;
}
```

Configuration errors are **fail-fast setup problems** — they mean the wiring is wrong, not
that a retry might help. Validation errors are **caller input problems** — surface them to
whoever supplied the data.

---

# OrmModule

Source: https://docs.usetheo.dev/theokit/orm/concepts/module

forRoot and forFeature — registering data sources and repositories in the container.

`OrmModule` is a pair of provider factories that plug the ORM into a `@theokit/di`
container. Both return `Provider[]` — spread them into your `providers` array.

## forRoot — register a data source

`forRoot` builds a `DataSource` from your Drizzle setup and registers it under a token.
Call it once per data source, at the root of your provider list.

```ts
OrmModule.forRoot({
  schema: { users, posts },
  dialect: "sqlite", // "sqlite" | "pg" | "mysql"
  db,                // the Drizzle db instance
  dataSourceName: "default", // optional; defaults to "default"
});
```

It validates its inputs eagerly: a missing `db`, or a `dialect` outside the three supported
values, throws `OrmConfigurationError`.

## forFeature — register repositories

`forFeature` registers a `Repository` provider per entity, each wired to the data source's
`db`:

```ts
OrmModule.forFeature([users, posts]); // default data source
OrmModule.forFeature([events], "analytics"); // a named data source
```

  `forFeature` **must** run after `forRoot` for the same data source — it throws
  `OrmConfigurationError` if the data source isn't registered yet. Order matters in the
  `providers` array.

## Putting it together

```ts
const container = new Container({
  providers: [
    ...OrmModule.forRoot({ schema: { users }, dialect: "sqlite", db }),
    ...OrmModule.forFeature([users]),
    UserService,
  ],
});
```

## Multiple data sources

Give each `forRoot` a distinct `dataSourceName`, and pass the same name to `forFeature` and
`@InjectRepository`:

```ts
providers: [
  ...OrmModule.forRoot({ schema: { users }, dialect: "pg", db: pgDb }),
  ...OrmModule.forRoot({ schema: { events }, dialect: "sqlite", db: liteDb, dataSourceName: "analytics" }),
  ...OrmModule.forFeature([users]),
  ...OrmModule.forFeature([events], "analytics"),
]
```

```ts
@Injectable()
class Analytics {
  constructor(@InjectRepository(events, "analytics") private readonly repo: Repository<typeof events>) {}
}
```

## DataSource

The value `forRoot` registers is a `DataSource` — `{ name, dialect, schema, db }`. It is
exposed under `ORM_DATA_SOURCE_TOKEN` (or `${ORM_DATA_SOURCE_TOKEN}:<name>` for named
sources), and is what [`@Transactional`](/theokit/orm/concepts/transactional) reads to open
a transaction.

---

# Repository

Source: https://docs.usetheo.dev/theokit/orm/concepts/repository

CRUD methods, the raw query() escape hatch, createRepository, and @InjectRepository.

`Repository<T>` is a thin, typed wrapper over a Drizzle table. It infers its row types from
the table (`InferSelectModel` / `InferInsertModel`) and detects the primary key at
construction.

## CRUD methods

```ts
class Repository<T extends Table> {
  findById(id: string | number): Promise<InferSelectModel<T> | null>;
  findMany(where?: SQL): Promise<InferSelectModel<T>[]>;
  insert(values: InferInsertModel<T>): Promise<InferSelectModel<T>>;
  update(id: string | number, patch: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T>>;
  delete(id: string | number): Promise<void>;
  query(): /* raw Drizzle select builder */;
}
```

```ts
await repo.insert({ id: "u1", name: "Theo" });
const one = await repo.findById("u1");
const many = await repo.findMany(eq(users.name, "Theo"));
await repo.update("u1", { name: "Théo" });
await repo.delete("u1");
```

- `insert` and `update` use Drizzle's `.returning()` to hand back the persisted row. On a
  driver without `.returning()` (e.g. MySQL) they throw a clear `OrmConfigurationError`
  pointing you to `repo.query()`.
- `findById`, `update`, and `delete` validate the `id` up front — `undefined`, `null`, an
  empty string, or a non-string/number throws `OrmValidationError`.

## The query() escape hatch

`query()` returns the raw Drizzle select builder for the table — reach for it when you need
joins, aggregates, composite keys, or dialect-specific features the CRUD surface doesn't
cover:

```ts
const rows = await repo.query().where(eq(users.name, "Theo")).limit(10);
```

## Primary-key rules

The repository detects the primary key at construction: a column marked `.primaryKey()`, or
a column literally named `id`. If neither exists it throws `OrmConfigurationError` —

  v0.1 supports a **single-column** primary key named `id` or marked `.primaryKey()`. For
  composite or custom keys, use `repo.query()` and build the predicate yourself.

## createRepository (non-DI)

The `Repository` constructor is already DI-free — `createRepository` just makes that path
explicit and discoverable. No `@theokit/di`, no decorators, no `reflect-metadata`:

```ts
import { createRepository } from "@theokit/orm";

const repo = createRepository(db, users);
```

Works with any Drizzle `db` (including `better-sqlite3`, whose builders are awaitable). Only
[`@Transactional`](/theokit/orm/concepts/transactional) needs a bound `DataSource`.

## @InjectRepository (DI)

Under DI, `@InjectRepository(entity, dataSourceName?)` injects the repository registered by
`OrmModule.forFeature`. It's sugar over `@Inject(getRepositoryToken(entity, dataSourceName))`:

```ts
@Injectable()
class UserService {
  constructor(@InjectRepository(users) private readonly repo: Repository<typeof users>) {}
}
```

`getRepositoryToken(entity, dataSourceName?)` computes the token string
(`REPO:<table>` or `REPO:<dataSource>:<table>`) — useful if you register or resolve a
repository manually.

---

# Schema export

Source: https://docs.usetheo.dev/theokit/orm/concepts/schema-export

Turn a Drizzle table into JSON Schema (draft 7) for tool inputs, validation, or docs.

`@theokit/orm` can export a Drizzle table as a **JSON Schema (draft 7)** object — handy for
agent tool input schemas, request validation, or generating documentation. These helpers
ship on a dedicated subpath so the core repository surface stays lean.

```ts
import { exportSchema, exportSchemas } from "@theokit/orm/schema-export";
```

## exportSchema

Converts one table to a `JsonSchema7` object — typed `object` with `properties`,
`required`, and `additionalProperties: false`. Column types, nullability, defaults, enums,
and length constraints are mapped across dialects.

```ts
const schema = exportSchema(users);
// {
//   type: "object",
//   properties: {
//     id: { type: "string" },
//     name: { type: "string" },
//   },
//   required: ["id", "name"],
//   additionalProperties: false,
// }
```

## exportSchemas

Converts a whole schema map (`Record<string, Table>`) in one call, returning a map of
table-name → `JsonSchema7`:

```ts
const all = exportSchemas({ users, posts });
// { users: {...}, posts: {...} }
```

## Using it for tool inputs

Because the output is standard JSON Schema, it drops straight into anything that consumes
one — for example the input schema of a `@theokit/sdk` tool:

```ts
import { exportSchema } from "@theokit/orm/schema-export";
import { Tool } from "@theokit/sdk";

const createUser = Tool.create({
  name: "create_user",
  description: "Create a user",
  inputSchema: exportSchema(users),
  execute: (input) => repo.insert(input),
});
```

  A table that can't be introspected throws `OrmSchemaExportError`. The mapping targets the
  common column types across SQLite and Postgres; verify the output for exotic
  dialect-specific types.

---

# Transactional

Source: https://docs.usetheo.dev/theokit/orm/concepts/transactional

Wrap a method in a Drizzle transaction; nested repository calls join it automatically.

`@Transactional()` wraps a method so every repository call inside it runs in a single
Drizzle transaction. Nested repository calls join the active transaction transparently
through `AsyncLocalStorage` — you don't thread a `tx` handle around.

```ts
import { Injectable } from "@theokit/di";
import { InjectRepository, Repository, Transactional } from "@theokit/orm";

@Injectable()
class BillingService {
  constructor(
    @InjectRepository(accounts) private readonly accounts: Repository<typeof accounts>,
    @InjectRepository(ledger) private readonly ledger: Repository<typeof ledger>,
  ) {}

  @Transactional()
  async transfer(from: string, to: string, amount: number) {
    await this.accounts.update(from, { balance: /* ... */ });
    await this.accounts.update(to, { balance: /* ... */ });
    await this.ledger.insert({ id: crypto.randomUUID(), from, to, amount });
    // all three commit together, or roll back together on throw
  }
}
```

## How it works

The decorator reads a `DataSource` bound to the instance, calls `db.transaction(...)`, and
runs your method body inside `withTxContext(tx, ...)`. Every `Repository` checks that
transaction context first: if one is active, it uses the transaction's `db`; otherwise it
falls back to the default `db`. That's why nested repository calls join automatically.

  Isolation level is accepted as an option
  (`@Transactional({ isolationLevel: "serializable" })`) and passed through to Drizzle where
  the driver supports it.

## Requires a DI-managed instance

`@Transactional` reads a `DataSource` bound to the instance, and under DI the `OrmModule`
wiring arranges that binding automatically — a class resolved through the container is
ready to use `@Transactional`. This is the intended path.

  Calling a `@Transactional` method with **no** bound `DataSource` throws
  `OrmConfigurationError`. So does a `DataSource` whose `db` doesn't expose `.transaction()`
  — make sure you passed a real Drizzle db instance.

## Non-DI transactions

The non-DI `Repository` (via [`createRepository`](/theokit/orm/concepts/repository#createrepository-non-di))
covers plain CRUD, but `@Transactional` is designed for DI-managed classes. Outside DI, use
Drizzle's transaction API directly and run repository work against the transaction handle
with `repo.query()`:

```ts
await db.transaction(async (tx) => {
  const txRepo = createRepository(tx, accounts);
  await txRepo.update("a", { balance: 90 });
  await txRepo.update("b", { balance: 110 });
});
```

---

# Getting started

Source: https://docs.usetheo.dev/theokit/orm/getting-started

Install @theokit/orm, define a Drizzle table, register the module, and inject a repository.

## Install

```bash
pnpm add @theokit/orm @theokit/di reflect-metadata drizzle-orm
pnpm add -D drizzle-kit
```

`@theokit/di`, `drizzle-orm`, and `reflect-metadata` are peer dependencies. Enable the
decorator flags in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

## Define a table

Any Drizzle table works. v0.1 requires a single-column primary key named `id` or marked
`.primaryKey()`:

```ts
import { sqliteTable, text } from "drizzle-orm/sqlite-core";

export const users = sqliteTable("users", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  agentId: text("agent_id"), // optional agent-aware column
});
```

## Option A — with DI

Register a data source with `OrmModule.forRoot`, then repositories with `forFeature`, and
inject them via `@InjectRepository`:

```ts
import "reflect-metadata";
import Database from "better-sqlite3";
import { drizzle } from "drizzle-orm/better-sqlite3";
import { Container, Injectable } from "@theokit/di";
import { OrmModule, Repository, InjectRepository } from "@theokit/orm";

const db = drizzle(new Database(":memory:"), { schema: { users } });

@Injectable()
class UserService {
  constructor(@InjectRepository(users) private readonly repo: Repository<typeof users>) {}
  create(id: string, name: string) {
    return this.repo.insert({ id, name });
  }
}

const container = new Container({
  providers: [
    ...OrmModule.forRoot({ schema: { users }, dialect: "sqlite", db }),
    ...OrmModule.forFeature([users]),
    UserService,
  ],
});

const svc = container.resolve(UserService);
await svc.create("u1", "Theo");
```

  `OrmModule.forFeature([...])` must be called **after** `OrmModule.forRoot({...})` — it
  throws `OrmConfigurationError` otherwise. Spread both into your `providers` array in that
  order.

## Option B — without DI

Skip decorators and `reflect-metadata` entirely — `createRepository(db, table)` gives you
plain CRUD:

```ts
import { createRepository } from "@theokit/orm";

const repo = createRepository(db, users);
await repo.insert({ id: "u1", name: "Theo" });
const user = await repo.findById("u1");
```

## Next

---

# Overview

Source: https://docs.usetheo.dev/theokit/orm

Repository pattern + @Transactional + agent-aware columns over drizzle-orm — @theokit/orm.

**`@theokit/orm`** brings NestJS-flavoured TypeORM DX to the Theo ecosystem — a
**Repository pattern**, `@InjectRepository`, `@Transactional`, agent-aware columns, and
polyglot JSON-Schema export — built on **`drizzle-orm`** and wired through
[`@theokit/di`](/theokit/di).

  Built on Drizzle (Apache-2.0, edge-runtime ready, zero codegen). SQLite and Postgres are
  first-class in v0.1; MySQL works through `repo.query()` where `.returning()` isn't
  available. You can use the `Repository` with **or without** DI.

## Why `@theokit/orm`

- **Repository pattern.** `findById`, `findMany`, `insert`, `update`, `delete`, and an
  escape-hatch `query()` that hands you the raw Drizzle builder — typed against your Drizzle
  table.
- **DI-native or standalone.** `OrmModule.forRoot` / `forFeature` register repositories in
  the container, or call `createRepository(db, table)` for plain CRUD with no decorators and
  no `reflect-metadata`.
- **`@Transactional`.** Wrap a method in a Drizzle transaction; nested repository calls
  transparently join it through `AsyncLocalStorage`.
- **Agent-aware columns.** Tables with `agentId` / `runId` / `conversationId` are
  auto-filled from the ambient `AgentContext` on insert/update.
- **Schema export.** Turn a Drizzle table into JSON Schema (draft 7) for tool inputs,
  validation, or docs.

## Quick code

```ts
import "reflect-metadata";
import { createRepository } from "@theokit/orm";
import { drizzle } from "drizzle-orm/better-sqlite3";
import Database from "better-sqlite3";
import { sqliteTable, text } from "drizzle-orm/sqlite-core";

const users = sqliteTable("users", { id: text("id").primaryKey(), name: text("name").notNull() });
const db = drizzle(new Database(":memory:"), { schema: { users } });

const repo = createRepository(db, users);
await repo.insert({ id: "u1", name: "Theo" });
const user = await repo.findById("u1"); // { id: "u1", name: "Theo" }
```

## Navigate

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/orm/llms-txt

Machine-readable ground truth of @theokit/orm for LLMs — package metadata, Repository API, OrmModule, @Transactional, agent-aware columns, and schema export. Download it or curl it directly.

`@theokit/orm` ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that
gives any LLM the **factual ground truth** of this package without crawling the site:

- Exact package name, version, license, peers (`@theokit/di`, `drizzle-orm`, `reflect-metadata`)
- Both import paths: the main barrel and the `@theokit/orm/schema-export` subpath
- The full `Repository` API + the DI wiring (`OrmModule.forRoot` / `forFeature`, `@InjectRepository`)
- `@Transactional` (DI-only) + the non-DI transaction workaround
- Agent-aware columns (`withAgentContext` / `getAgentContext`) and their exact fill rules
- Anti-patterns to avoid (`forFeature` before `forRoot`; composite PKs; `bindDataSourceToInstance` is not public)

## Download

  <Card
    title="Download llms.txt"
    description="Single self-contained Markdown file. Drop it next to your AGENTS.md / .cursorrules / CLAUDE.md and reference it from the system prompt."
    href="/theokit/orm/llms.txt"
  />

## Curl it directly

```bash
# Save to your project root
curl -o theokit-orm-llms.txt https://docs.usetheo.dev/theokit/orm/llms.txt

# Or pipe straight into a prompt
curl -s https://docs.usetheo.dev/theokit/orm/llms.txt | head -120
```

The source files always win. If a bullet in `llms.txt` disagrees with
`packages/orm/src/index.ts` or the per-symbol reference on this site, the code is
correct and the file is stale — regenerate it from the barrel.

---

# AgentContext

Source: https://docs.usetheo.dev/theokit/orm/reference/AgentContext

_No description available._

# `AgentContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
interface AgentContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/orm/src/types.ts:26`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/types.ts#L26)

---

# AnyTable

Source: https://docs.usetheo.dev/theokit/orm/reference/AnyTable

_No description available._

# `AnyTable`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
type AnyTable
```

## Kind

`type`

## Source

[`packages/orm/src/types.ts:3`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/types.ts#L3)

---

# createRepository

Source: https://docs.usetheo.dev/theokit/orm/reference/createRepository

M7-7 — non-DI factory for Repository. The `Repository` constructor is

# `createRepository`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

M7-7 — non-DI factory for Repository. The `Repository` constructor is
already DI-free (`new Repository(db, table)`); this factory makes the non-DI
path explicit and discoverable, so consumers do NOT need `@theokit/di`,
decorators, or `reflect-metadata` for plain CRUD — only `@Transactional`
requires a bound DataSource. Works with any drizzle `db` (incl. better-sqlite3,
whose query builders are awaitable).

## Signature

```ts
function createRepository(db: unknown, table: T): Repository
```

## Kind

`function`

## Source

[`packages/orm/src/repository.ts:183`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/repository.ts#L183)

---

# DataSource

Source: https://docs.usetheo.dev/theokit/orm/reference/DataSource

_No description available._

# `DataSource`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
interface DataSource { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/orm/src/types.ts:16`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/types.ts#L16)

---

# Dialect

Source: https://docs.usetheo.dev/theokit/orm/reference/Dialect

_No description available._

# `Dialect`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
type Dialect
```

## Kind

`type`

## Source

[`packages/orm/src/types.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/types.ts#L5)

---

# getAgentContext

Source: https://docs.usetheo.dev/theokit/orm/reference/getAgentContext

_No description available._

# `getAgentContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
function getAgentContext(): unknown
```

## Kind

`function`

## Source

[`packages/orm/src/als-context.ts:10`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/als-context.ts#L10)

---

# getRepositoryToken

Source: https://docs.usetheo.dev/theokit/orm/reference/getRepositoryToken

_No description available._

# `getRepositoryToken`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
function getRepositoryToken(entity: unknown, dataSourceName: string): string
```

## Kind

`function`

## Source

[`packages/orm/src/tokens.ts:25`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/tokens.ts#L25)

---

# API reference

Source: https://docs.usetheo.dev/theokit/orm/reference

Every public symbol in @theokit/orm, auto-generated from TypeDoc.

# API reference

This section is **auto-generated** from TypeDoc on every build. 18 symbols exported by @theokit/orm.

## Classes

- [`OrmConfigurationError`](/theokit/orm/reference/OrmConfigurationError) — _no description_
- [`OrmError`](/theokit/orm/reference/OrmError) — _no description_
- [`OrmSchemaExportError`](/theokit/orm/reference/OrmSchemaExportError) — _no description_
- [`OrmValidationError`](/theokit/orm/reference/OrmValidationError) — _no description_
- [`Repository`](/theokit/orm/reference/Repository) — _no description_

## Constantes

- [`ORM_DATA_SOURCE_TOKEN`](/theokit/orm/reference/ORM_DATA_SOURCE_TOKEN) — _no description_
- [`OrmModule`](/theokit/orm/reference/OrmModule) — _no description_

## Functiones

- [`createRepository`](/theokit/orm/reference/createRepository) — M7-7 — non-DI factory for Repository. The `Repository` constructor is
- [`getAgentContext`](/theokit/orm/reference/getAgentContext) — _no description_
- [`getRepositoryToken`](/theokit/orm/reference/getRepositoryToken) — _no description_
- [`InjectRepository`](/theokit/orm/reference/InjectRepository) — _no description_
- [`Transactional`](/theokit/orm/reference/Transactional) — _no description_
- [`withAgentContext`](/theokit/orm/reference/withAgentContext) — _no description_

## Interfacees

- [`AgentContext`](/theokit/orm/reference/AgentContext) — _no description_
- [`DataSource`](/theokit/orm/reference/DataSource) — _no description_
- [`OrmRootOptions`](/theokit/orm/reference/OrmRootOptions) — _no description_

## Typees

- [`AnyTable`](/theokit/orm/reference/AnyTable) — _no description_
- [`Dialect`](/theokit/orm/reference/Dialect) — _no description_

---

# InjectRepository

Source: https://docs.usetheo.dev/theokit/orm/reference/InjectRepository

_No description available._

# `InjectRepository`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
function InjectRepository(entity: unknown, dataSourceName: string): ParameterDecorator
```

## Kind

`function`

## Source

[`packages/orm/src/inject-repository.ts:4`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/inject-repository.ts#L4)

---

# ORM_DATA_SOURCE_TOKEN

Source: https://docs.usetheo.dev/theokit/orm/reference/ORM_DATA_SOURCE_TOKEN

_No description available._

# `ORM_DATA_SOURCE_TOKEN`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
const ORM_DATA_SOURCE_TOKEN
```

## Kind

`constant`

## Source

[`packages/orm/src/types.ts:24`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/types.ts#L24)

---

# OrmConfigurationError

Source: https://docs.usetheo.dev/theokit/orm/reference/OrmConfigurationError

_No description available._

# `OrmConfigurationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
class OrmConfigurationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/orm/src/errors.ts:5`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/errors.ts#L5)

---

# OrmError

Source: https://docs.usetheo.dev/theokit/orm/reference/OrmError

_No description available._

# `OrmError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
class OrmError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/orm/src/errors.ts:1`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/errors.ts#L1)

---

# OrmModule

Source: https://docs.usetheo.dev/theokit/orm/reference/OrmModule

_No description available._

# `OrmModule`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
const OrmModule
```

## Kind

`constant`

## Source

[`packages/orm/src/module.ts:33`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/module.ts#L33)

---

# OrmRootOptions

Source: https://docs.usetheo.dev/theokit/orm/reference/OrmRootOptions

_No description available._

# `OrmRootOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
interface OrmRootOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/orm/src/types.ts:7`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/types.ts#L7)

---

# OrmSchemaExportError

Source: https://docs.usetheo.dev/theokit/orm/reference/OrmSchemaExportError

_No description available._

# `OrmSchemaExportError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
class OrmSchemaExportError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/orm/src/errors.ts:13`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/errors.ts#L13)

---

# OrmValidationError

Source: https://docs.usetheo.dev/theokit/orm/reference/OrmValidationError

_No description available._

# `OrmValidationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
class OrmValidationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/orm/src/errors.ts:9`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/errors.ts#L9)

---

# Repository

Source: https://docs.usetheo.dev/theokit/orm/reference/Repository

_No description available._

# `Repository`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
class Repository {
  delete(...): ...
  findById(...): ...
  findMany(...): ...
  insert(...): ...
  query(...): ...
  update(...): ...
}
```

## Kind

`class`

## Source

[`packages/orm/src/repository.ts:79`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/repository.ts#L79)

---

# Transactional

Source: https://docs.usetheo.dev/theokit/orm/reference/Transactional

_No description available._

# `Transactional`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
function Transactional(_opts: TransactionalOptions): MethodDecorator
```

## Kind

`function`

## Source

[`packages/orm/src/transactional.ts:28`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/transactional.ts#L28)

---

# withAgentContext

Source: https://docs.usetheo.dev/theokit/orm/reference/withAgentContext

_No description available._

# `withAgentContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `@theokit/orm` source to change this page.

_No description available._

## Signature

```ts
function withAgentContext(ctx: AgentContext, fn: unknown): Promise
```

## Kind

`function`

## Source

[`packages/orm/src/als-context.ts:6`](https://github.com/usetheodev/theokit-di/blob/main/packages/orm/src/als-context.ts#L6)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/permissions/advanced

Argument matchers, the full mode semantics, the canUseTool gate, and the fail-closed guarantees.

# Advanced permissions

Verified against the SDK.

## `PermissionEngine`

```ts
const engine = new PermissionEngine(rules, defaultAction?); // defaultAction default "ask"
engine.evaluate(toolName, args?, mode?): PermissionAction;   // "allow" | "deny" | "ask"
```

`evaluate` walks the rules in order; the **first** whose `tool` (string or `RegExp`) — and, if
present, whose `args` matchers — match the call wins. No match ⇒ `defaultAction` (fail-closed `ask`).

## Argument matchers

A rule can gate on the call's arguments, so the same tool resolves differently by *what* it's asked
to do:

```ts
{ tool: "write_file", args: { path: (p) => !String(p).startsWith("/etc") }, action: "allow" }
```

A missing/undefined argument **fails** its predicate (the rule doesn't match) — never throws.

## Mode semantics (`applyMode`)

The per-run `PermissionMode` is threaded into `evaluate`. An **explicit** rule verdict and the
**default** (unmatched) verdict are treated differently:

| Mode | Explicit rule verdict | Unmatched (default) |
| --- | --- | --- |
| `default` | as-is | `ask` (fail-closed) |
| `plan` | only `allow` passes; else `deny` | `deny` |
| `acceptEdits` | honors explicit `ask` | auto-`allow` |
| `bypass` | `allow` — **except** an explicit `deny`, which always wins | `allow` |

The one invariant across all modes: an **explicit `deny` rule is never overridden**.

## Wiring — `PermissionPlugin.create`

```ts
PermissionPlugin.create(engine, {
  name,                 // default "permission-engine"
  mode,                 // the per-run PermissionMode (default "default")
  canUseTool,           // the ask gate — (toolName, input, ctx) => decision
});
```

- **`canUseTool(toolName, input, ctx)`** is invoked **only** on an `ask` verdict and returns a typed
  allow/deny decision — bridge it to a CLI prompt, a UI approval, or a policy service.
- **Fail-closed** — an `ask` verdict with **no** `canUseTool` gate blocks the call. The deprecated
  `onAsk` (veto-shaped) is honored only when `canUseTool` is absent.

## Reference

- [`PermissionEngine`](/theokit/reference/PermissionEngine) · [`PermissionRule`](/theokit/reference/PermissionRule) · [`PermissionMode`](/theokit/reference/PermissionMode) · [`PermissionPlugin`](/theokit/reference/PermissionPlugin) · [`PermissionGate`](/theokit/reference/PermissionGate)

---

# Gate tool calls

Source: https://docs.usetheo.dev/theokit/permissions/gate-tool-calls

Build a PermissionEngine from rules and evaluate tool calls across modes — first-match wins, unmatched fails closed.

# Gate tool calls

A `PermissionEngine` resolves a verdict for a tool name (and optional args) against ordered rules,
under a mode. It's pure and deterministic — evaluate it directly to see the policy.

```ts title="run.ts"
import { PermissionEngine } from "@theokit/sdk";

const engine = new PermissionEngine([
  { tool: "delete_file", action: "deny" },
  { tool: /^read_/, action: "allow" },
]);

console.log("delete_file        :", engine.evaluate("delete_file"));
console.log("read_file          :", engine.evaluate("read_file"));
console.log("send_email (unmatch):", engine.evaluate("send_email"));
console.log("write_file in plan :", engine.evaluate("write_file", undefined, "plan"));
console.log("delete in bypass   :", engine.evaluate("delete_file", undefined, "bypass"));
```

## Output

Deterministic:

```text
delete_file        : deny
read_file          : allow
send_email (unmatch): ask
write_file in plan : deny
delete in bypass   : deny
```

## What it shows

- **First match wins** — `delete_file` hits the explicit `deny`; `read_file` hits the `/^read_/`
  allow; `send_email` matches nothing, so it falls back to **`ask`** (fail-closed).
- **`plan` mode is read-only** — `write_file` isn't an `allow` rule, so plan resolves it to `deny`.
- **Explicit `deny` is immune to `bypass`** — even in `bypass`, `delete_file` stays `deny`.

In a live agent, wire the engine with `PermissionPlugin.create(engine, { mode, canUseTool })`; the
`ask` verdict then calls your `canUseTool` gate for a human decision. See
[Advanced](/theokit/permissions/advanced).

## Example

Full runnable source:
[`examples/permissions-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/permissions-basics).

---

# Overview

Source: https://docs.usetheo.dev/theokit/permissions

Gate an agent's tool calls with first-match rules, a per-run permission mode, and a human-in-the-loop ask gate — fail-closed by default.

# Permissions

Before a tool runs, the SDK can ask: *is this allowed?* A **permission engine** answers with
`allow` / `deny` / `ask` from ordered rules; a per-run **mode** layers policy on top; and an `ask`
verdict routes to a **human-in-the-loop** gate. Unmatched calls fail closed.

```ts
import { PermissionEngine, PermissionPlugin } from "@theokit/sdk";

const engine = new PermissionEngine([
  { tool: "delete_file", action: "deny" },
  { tool: /^read_/, action: "allow" },
]);

await Agent.create({
  apiKey, model, tools,
  plugins: [PermissionPlugin.create(engine, { mode: "default", canUseTool })],
});
```

## Rules — first match wins

A `PermissionRule` matches a tool by exact name or `RegExp`, optionally gated on argument values,
and yields an action:

```ts
interface PermissionRule {
  tool: string | RegExp;
  args?: Record<string, ArgMatcher>; // match on call arguments too
  action: "allow" | "deny" | "ask";
}
```

The first matching rule wins; **no match ⇒ `ask`** (fail-closed).

## Modes

The per-run `PermissionMode` reshapes verdicts — but an explicit `deny` is immune to every mode:

| Mode | Effect |
| --- | --- |
| `default` | Rules decide; unmatched ⇒ `ask`. |
| `plan` | Read-only — only `allow` rules pass; everything else ⇒ `deny` (mutations blocked). |
| `acceptEdits` | Auto-approves unmatched calls, still honoring explicit `ask` rules. |
| `bypass` | Everything ⇒ `allow` **except** an explicit `deny` rule. Never asks. |

## The ask gate — human-in-the-loop

`PermissionPlugin.create(engine, { mode, canUseTool })` wires the engine into the agent. On an `ask`
verdict it calls your **`canUseTool(toolName, input, ctx)`** gate, which returns a typed
allow/deny decision — bridge it to a prompt, a UI approval, a policy service. **No gate on an `ask`
⇒ fail-closed block.**

## Next

- [Gate tool calls](/theokit/permissions/gate-tool-calls) — a runnable rules/modes example.
- [Advanced](/theokit/permissions/advanced) — arg matchers, the full mode semantics, and the gate.

## Reference

- [`PermissionEngine`](/theokit/reference/PermissionEngine) · [`PermissionMode`](/theokit/reference/PermissionMode) · [`PermissionPlugin`](/theokit/reference/PermissionPlugin)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/personalities/advanced

The resolved preset fields, save/reset semantics, tool and model overrides, project vs user precedence, prompt composition, and clearing.

# Advanced personalities

Verified against `@theokit/sdk` (`internal/personality/*`, `types/agent.ts`).

## The resolved preset — `PersonalityPreset`

```ts
interface PersonalityPreset {
  name: string;
  description: string | undefined;
  tools: ReadonlyArray<string> | undefined;   // tool allowlist for this personality
  model: string | undefined;                   // model override
  tags: ReadonlyArray<string> | undefined;
  systemPrompt: string;                        // the file body
  source: "project" | "user";                  // where it was found
  sourcePath: string;                          // the resolved file path
}
```

`usePersonality` returns this, or `null` when the personality was cleared.

## save / reset

```ts
await agent.usePersonality("reviewer", { save: true });  // persist across restarts
await agent.usePersonality("reviewer", { reset: true }); // also clear conversation history
```

- **`{ save: true }`** persists the active personality to `$THEOKIT_HOME/personality.json`, so a new
  process picks it up. Without it, the switch lasts only for the current process.
- **`{ reset: true }`** clears the conversation history as it switches (default: history is
  **preserved** across the switch).

## Tool and model overrides

A preset can carry `tools` (an allowlist) and `model` in its frontmatter — activating it narrows the
agent to those tools and swaps its model for the personality's duration. Omit them and the agent keeps
its base tools and model.

## Prompt composition

The active personality's body is **appended** to your base system prompt:

```
[base system prompt] + separator + [personality body]
```

An empty base means the personality body stands alone (no leading separator); `separator: ""` merges
them directly. The personality augments — it never silently discards your base prompt.

## Project vs user precedence

Presets are discovered from **project** (`.theokit/personalities/*.md` under the cwd) and **user**
(the same path under `$THEOKIT_HOME`) sources. The `source` field on the resolved preset tells you
which won.

## Clearing

Pass a reserved name — `"none"`, `"default"`, or `"neutral"` — to clear the active personality;
`usePersonality` returns `null`. With `{ save: true }`, the cleared state is persisted too.

All of the above is **local-runtime** only. On a cloud agent, `usePersonality` throws
`UnsupportedRunOperationError`.

## Reference

- [`PersonalityPreset`](/theokit/reference/PersonalityPreset) · [`SDKAgent`](/theokit/reference/SDKAgent) · [`UnsupportedRunOperationError`](/theokit/reference/UnsupportedRunOperationError)

---

# Overview

Source: https://docs.usetheo.dev/theokit/personalities

Swap an agent's voice and tool-set at runtime with a personality preset — persisted across restarts if you like.

# Personalities

A **personality preset** bundles a system prompt, an optional tool whitelist, a model, and tags —
activate one for the next `send` without rebuilding the agent.

```ts
const preset = await agent.usePersonality("researcher", { save: true });
```

- **`agent.usePersonality(name, opts?)`** — activate a preset for the next `send`; returns the
  resolved `PersonalityPreset` (or `null` when cleared). Reserved names `"none"` / `"default"` /
  `"neutral"` clear it.
- **`{ save: true }`** — persist across process restarts (`$THEOKIT_HOME/personality.json`).
- **`{ reset: true }`** — also clear the conversation history on the switch (default: preserved).
- Presets are discovered from **project** and **user** sources. Local runtime only.

## Where they live

Personality files are Markdown with frontmatter at `.theokit/personalities/*.md` — `name` (lowercase
slug), `description?`, `tools?`, `model?`, `tags?` in the frontmatter, the system prompt in the body.

```md
---
name: reviewer
description: A terse, exacting code reviewer.
tags: [engineering, review]
---
You are a senior code reviewer. Be terse. Flag correctness and security issues first.
```

Discovery requires `local: { settingSources: ["project"] }` (same opt-in as
[Skills](/theokit/skills) and [Context](/theokit/context)). Switching composes the prompt as
**`[base system prompt] + separator + [personality body]`** — the preset augments your base prompt.

Personalities are a **local-runtime** feature — cloud agents throw `UnsupportedRunOperationError`.

## Next

- [Switch personality](/theokit/personalities/switch-personality) — a runnable `usePersonality` example.
- [Advanced](/theokit/personalities/advanced) — the resolved preset fields, save/reset, tool + model overrides, and prompt composition.

## Reference

- [`PersonalityPreset`](/theokit/reference/PersonalityPreset) · [`Agent`](/theokit/reference/Agent)

---

# Switch personality

Source: https://docs.usetheo.dev/theokit/personalities/switch-personality

Switch an agent to a named personality with usePersonality and inspect the resolved preset — deterministic, no LLM.

# Switch personality

`agent.usePersonality(name)` resolves a `.theokit/personalities/<name>.md` preset from disk and
activates it for the next `send`. Resolving and inspecting the preset is a local file read — no LLM.

```ts title="run.ts"
import { fileURLToPath } from "node:url";
import { dirname } from "node:path";
import { Agent } from "@theokit/sdk";

const here = dirname(fileURLToPath(import.meta.url)); // holds .theokit/personalities/reviewer.md

const agent = await Agent.create({
  apiKey: "theo_test_persona",             // fixture key — no LLM
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: here, settingSources: ["project"] },
});

const preset = await agent.usePersonality?.("reviewer");
console.log("name:       ", preset?.name);
console.log("description:", preset?.description);
console.log("tags:       ", preset?.tags?.join(", "));
console.log("source:     ", preset?.source);

await agent.dispose?.();
```

The `.theokit/personalities/reviewer.md` beside `run.ts`:

```md
---
name: reviewer
description: A terse, exacting code reviewer.
tags: [engineering, review]
---
You are a senior code reviewer. Be terse. Flag correctness and security issues first.
```

## Output

Deterministic — the preset is resolved from disk:

```text
name:        reviewer
description: A terse, exacting code reviewer.
tags:        engineering, review
source:      project
```

## What it shows

- **`usePersonality(name)`** returns the resolved `PersonalityPreset` — `name`, `description`, `tags`,
  the `systemPrompt` body, and provenance (`source: "project" | "user"`, `sourcePath`).
- **`settingSources: ["project"]`** is required for the agent to discover project personality files.
- Passing a reserved name — `"none"`, `"default"`, `"neutral"` — clears the active personality and
  returns `null`.

## Example

Full runnable source:
[`examples/personality-switch`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/personality-switch).

---

# @theokit/auth-github

Source: https://docs.usetheo.dev/theokit/plugins/auth-github

GitHub OAuth 2.0 provider for the @theokit/sdk Auth.create orchestrator.

`@theokit/auth-github` is the GitHub OAuth 2.0 provider for the `@theokit/sdk` auth
orchestrator (`Auth.create`). It handles the authorization-code flow, state validation,
token exchange, and userinfo fetch — you supply the client credentials and an
`onSignIn` callback.

OAuth 2.0 only — GitHub does not expose OIDC discovery and does not implement PKCE. The
GitHub endpoints are hardcoded but overridable for GitHub Enterprise Server.

## Install

```bash
pnpm add @theokit/auth-github @theokit/sdk theokit
```

Peer dependencies: `@theokit/sdk >= 2.18.0`, `theokit >= 0.2.4`.

## Usage

```ts title="server/auth/index.ts"
import { Auth } from '@theokit/sdk/server/auth'
import { github } from '@theokit/auth-github'
import { sessionManager } from './session.js'

export const auth = Auth.create({
  session: sessionManager,
  providers: [
    github({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      redirectUri: 'https://myapp.com/api/auth/github/callback',
    }),
  ],
  onSignIn: async ({ profile }) => {
    return { userId: String(profile.id), email: profile.email, login: profile.login }
  },
})
```

Register a GitHub OAuth App at **GitHub Settings → Developer settings → OAuth Apps**,
set the callback URL to `https://<your-domain>/api/auth/github/callback`, and put the
Client ID + Client Secret in `.env`. Default scopes are `read:user user:email`
(override via `opts.scopes`).

### GitHub Enterprise Server

Override the four endpoints:

```ts
github({
  clientId: '...',
  clientSecret: '...',
  redirectUri: '...',
  authorizationEndpoint: 'https://github.acme.com/login/oauth/authorize',
  tokenEndpoint: 'https://github.acme.com/login/oauth/access_token',
  userinfoEndpoint: 'https://github.acme.com/api/v3/user',
  userEmailsEndpoint: 'https://github.acme.com/api/v3/user/emails',
})
```

## Profile shape

```ts
interface GitHubProfile {
  id: number // numeric, preserved as a number (NOT string)
  login: string
  name?: string | null
  email?: string | null // null when scope omits user:email AND user has no public email
  avatar_url?: string
}
```

When `scopes` include `user:email`, the provider fetches `/user` first and falls back to
`/user/emails` to pick the primary verified address. When the scope omits `user:email`,
that second fetch is skipped and `email` may be `null`.

  Do not assume `email` is always present. When the scope omits `user:email`, `email`
  can be `null` even for an active user — handle that case in your `onSignIn` callback.

## Notes

- `id` is preserved as a **number**, not a string — it is GitHub's stable numeric user
  identifier.
- Common error codes: `state_mismatch` (CSRF or stale callback), `token_exchange_failed`
  (wrong secret, expired code, or mismatched `redirectUri`), `userinfo_fetch_failed`
  (often a 403 rate limit), and `missing_id` / `missing_login` (malformed userinfo).

---

# @theokit/auth-google

Source: https://docs.usetheo.dev/theokit/plugins/auth-google

Google OAuth (OIDC) provider for the @theokit/sdk Auth.create orchestrator.

`@theokit/auth-google` is the Google OAuth (OIDC) provider for the `@theokit/sdk` auth
orchestrator (`Auth.create`). It composes OIDC discovery, PKCE (S256), the
authorization-code flow, and the userinfo fetch on top of the `theokit/server/auth`
primitives — with zero runtime dependencies and a roughly 5 KB ESM bundle.

## Install

```bash
pnpm add @theokit/auth-google @theokit/sdk theokit
```

Peer dependencies: `@theokit/sdk >= 2.18.0`, `theokit >= 0.2.4`.

## Usage

```ts title="server/auth/index.ts"
import { Auth } from '@theokit/sdk/server/auth'
import { google } from '@theokit/auth-google'
import { sessionManager } from './session.js'

export const auth = Auth.create({
  session: sessionManager,
  providers: [
    google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      redirectUri: 'https://myapp.com/api/auth/google/callback',
    }),
  ],
  onSignIn: async ({ profile }) => {
    // profile is GoogleProfile { sub, email, email_verified, name?, picture?, locale? }
    return { userId: profile.sub, email: profile.email }
  },
})
```

Wire the start and callback routes with `defineRoute`:

```ts title="server/routes/api/auth/google/start.ts"
import { defineRoute } from 'theokit/server'
import { auth } from '../../../auth/index.js'

export const GET = defineRoute({
  handler: async ({ req }) => auth.startSignIn('google', req),
})
```

```ts title="server/routes/api/auth/google/callback.ts"
import { defineRoute } from 'theokit/server'
import { auth } from '../../../auth/index.js'

export const GET = defineRoute({
  handler: async ({ req, res }) => {
    const { returnTo } = await auth.finishSignIn('google', req, res)
    return Response.redirect(returnTo ?? '/', 302)
  },
})
```

Create an OAuth 2.0 Client ID (type **Web application**) in the Google Cloud Console,
add your callback URI, and set `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` in `.env`.
The `openid`, `profile`, and `email` scopes are added automatically.

## Profile shape

```ts
interface GoogleProfile {
  sub: string // OIDC subject — case-sensitive, never lowercased
  email: string
  email_verified: boolean
  name?: string
  picture?: string
  locale?: string
}
```

  `sub` is the canonical Google user identifier and is preserved verbatim. **Never
  lowercase, normalize, or trim it** — different casings refer to different accounts.
  The `email_verified` boolean is surfaced as-is; you decide whether to gate user
  creation on `email_verified === true`.

## Notes

- **Custom scopes** (Drive, Gmail, Calendar) are not yet first-class via `opts.scopes`.
  Wrap the provider and post-process the URL in `createAuthorizationURL` to add them;
  a `opts.scopes` field lands in a future minor release.
- **Testing** — set `NODE_ENV=test` and `MOCK_GOOGLE_OIDC_BASE_URL=http://localhost:9999`
  to route OIDC discovery to a local sidecar. Production builds ignore this env var.
- Common error codes: `missing_pkce_verifier`, `state_mismatch`, `token_exchange_failed`,
  `missing_sub` / `missing_email`, and OIDC discovery `403` / `404` (wrong base URL).

---

# @theokit/auth-magic-link

Source: https://docs.usetheo.dev/theokit/plugins/auth-magic-link

Email magic-link (passwordless) provider for the @theokit/sdk Auth.create orchestrator.

`@theokit/auth-magic-link` is the passwordless email magic-link provider for the
`@theokit/sdk` auth orchestrator (`Auth.create`). It has two swappable pieces: a
pluggable token store (`MagicLinkStore` — in-memory for dev, ORM-backed for production)
and a consumer-supplied `sendEmail` callback, so you can use any email transport.

Zero runtime dependencies.

## Install

```bash
pnpm add @theokit/auth-magic-link @theokit/sdk theokit
```

Peer dependencies: `@theokit/sdk >= 2.18.0`, `theokit >= 0.2.4`.

## Quick start (dev)

```ts title="server/auth/index.ts"
import { Auth } from '@theokit/sdk/server/auth'
import { magicLink, createMemoryStore } from '@theokit/auth-magic-link'
import { sessionManager } from './session.js'

export const auth = Auth.create({
  session: sessionManager,
  providers: [
    magicLink({
      store: createMemoryStore(), // dev only — see Notes
      callbackBaseUrl: 'https://myapp.com',
      sendEmail: async ({ to, magicLinkUrl, expiresAt }) => {
        console.log(`Magic link for ${to}: ${magicLinkUrl} (expires ${expiresAt.toISOString()})`)
      },
    }),
  ],
  onSignIn: async ({ profile }) => ({ userId: profile.email, email: profile.email }),
})
```

## Wiring

Magic-link does **not** use the OAuth `startSignIn` flow — call
`provider.startSignIn(req)` directly on the start route, then finish through the
orchestrator on the callback:

```ts title="server/routes/api/auth/magic-link/start.ts"
import { defineRoute } from 'theokit/server'
import { magicLinkProvider } from '../../../auth/providers.js' // your magicLink() instance

export const POST = defineRoute({
  handler: async ({ req }) => {
    const redirect = await magicLinkProvider.startSignIn(req)
    return Response.redirect(redirect, 303)
  },
})
```

```ts title="server/routes/api/auth/magic-link/callback.ts"
import { defineRoute } from 'theokit/server'
import { auth } from '../../../auth/index.js'

export const GET = defineRoute({
  handler: async ({ req, res }) => {
    const { returnTo } = await auth.finishSignIn('magic-link', req, res)
    return Response.redirect(returnTo ?? '/', 302)
  },
})
```

The default `resolveEmail` reads `?email=` from the URL or the `email` field of a JSON /
form-encoded body; override via `opts.resolveEmail` for custom shapes.

  `createMemoryStore()` is **dev-only** — its state lives in one process and is lost on
  restart. In production, pass an ORM-backed store (`createOrmStore(...)`) or a custom
  `MagicLinkStore`. The store contract requires **atomic single-use** semantics: under
  concurrent reads of the same token, exactly one `consumeToken` call wins and the rest
  return `null` (SQL adapters use row-level locking).

## Production stores

Implement the store's atomic `consumeAtomically` (e.g. Postgres `UPDATE … RETURNING …
WHERE consumed_at IS NULL`) and pass it via `createOrmStore(...)`. Pair the provider with
[`@theokit/plugin-email`](/theokit/plugins/email) — its `sendMagicLink(provider, opts)`
helper returns a callback that satisfies the `sendEmail` contract directly. Resend,
SendGrid, and Nodemailer/SMTP transports all fit the same callback shape.

## Profile shape

```ts
interface MagicLinkProfile {
  email: string // verified by token possession
  verifiedAt: Date // when the callback completed
}
```

## Notes

- **Email validated at the boundary** — a malformed email throws
  `MagicLinkConfigError(code: 'invalid_email')` *before* any token is created or stored.
- **Token lifecycle** — 32 random bytes (43 base64url chars), 15-minute default lifetime
  (`opts.tokenLifetimeMs`), single-use. A second callback with the same token throws
  `invalid_or_expired_token`.
- **Cleanup** — expired tokens reject at consume time and can be batch-deleted via
  `store.cleanupExpired()`; run it periodically as a cron.

---

# @theokit/plugin-canvas

Source: https://docs.usetheo.dev/theokit/plugins/canvas

Canvas plugin for TheoKit — agent artifact protocol, side-panel UI, and a publish_artifact agent tool.

`@theokit/plugin-canvas` gives your agent a canvas: an auto-opening side panel that
renders nine artifact kinds — `markdown`, `code`, `svg`, `diff`, `whiteboard-scene`,
`slide-deck`, `mermaid`, `html`, and `image`. The agent publishes artifacts through the
`publish_artifact` tool; the panel reacts in real time over SSE.

Each kind has a byte cap and, where relevant, sanitization (SVG strips `<script>`; HTML
renders inside a sandboxed `<iframe>` with a closed permission enum).

## Install

```bash
pnpm add @theokit/plugin-canvas @usetheo/ui @theokit/ui
```

Required peers: `@theokit/ui ^0.14.2` (generic + AI surfaces / engines),
`@theokit/sdk >= 2.18.0` (agent tool runtime), `theokit >= 0.1.0-alpha.5`
(`defineAgentTool` / `defineAgentEndpoint`), and `react ^18 || ^19`. `mermaid ^11`
is an optional peer (see below).

  `mermaid >= 11.0.0` is an **optional** peer for SVG rendering of `mermaid` artifacts;
  without it the renderer falls back to a `<CodeBlock language="mermaid">`. If you use it,
  add `viteOptimizeDeps: ['mermaid']` to your `theo.config.ts` so Vite pre-bundles the
  dynamic import in dev mode.

## Usage

### 1. Register the agent tool

Create a module-scope artifact store and bus, then expose `publish_artifact` on your
agent endpoint. The bus bridges the tool handler (which emits) to the SSE stream (which
forwards `tool_result` events to the browser):

```ts title="server/routes/chat.ts"
import { defineAgentEndpoint, defineAgentTool, streamAgentRun, createConversationHistory } from 'theokit/server'
import { defineArtifactTool, createArtifactBus, createSqliteArtifactStore } from '@theokit/plugin-canvas'

// Module-scope singletons — one per process
const store = createSqliteArtifactStore({ db: yourSqliteDb })
const bus = createArtifactBus()

const publishArtifact = (convId: string) => {
  const cfg = defineArtifactTool({
    onPublish: async (artifact) => {
      const stored = await store.insert(artifact)
      bus.emit(convId, stored)
      return stored
    },
  })
  return defineAgentTool({
    name: cfg.name,
    description: cfg.description,
    inputSchema: cfg.inputSchema,
    handler: async (input) => JSON.stringify(await cfg.handler(input)),
  })
}

export const POST = defineAgentEndpoint({
  async *handler({ body }) {
    const { message } = body as { message: string }
    const { agent, conversationId } = await createConversationHistory({
      options: { model: { id: 'openai/gpt-4o-mini' }, tools: [publishArtifact('')] },
    })

    const queue = []
    const unsub = bus.subscribe(conversationId, (artifact) => {
      queue.push({ type: 'tool_result', name: 'publish_artifact', data: { artifact } })
    })
    const run = await agent.send(message)
    try {
      for await (const event of streamAgentRun(run)) {
        while (queue.length) yield queue.shift()
        yield event
      }
    } finally {
      unsub()
    }
  },
})
```

### 2. Mount the panel

```tsx title="app/page.tsx"
import { CanvasPanel, useCanvas, type Artifact } from '@theokit/plugin-canvas/ui'
import { useAgentStream } from 'theokit/client'
import { useEffect, useRef } from 'react'

export default function Page() {
  const { events } = useAgentStream<{ message: string }>('/api/chat')
  const canvas = useCanvas({ endpoint: '/api/canvas/artifacts' })

  const seen = useRef(0)
  useEffect(() => {
    for (let i = seen.current; i < events.length; i++) {
      const ev = events[i]
      if (ev?.type === 'tool_result' && ev.name === 'publish_artifact') {
        const artifact = (ev.data as { artifact?: Artifact })?.artifact
        if (artifact) canvas.show(artifact)
      }
    }
    seen.current = events.length
  }, [events, canvas])

  return (
    <>
      {/* … your chat UI … */}
      {canvas.open && (
        <div className="fixed inset-y-0 right-0 w-[40vw]">
          <CanvasPanel
            open={canvas.open}
            onOpenChange={canvas.setOpen}
            artifact={canvas.current}
            versions={canvas.versions}
            onVersionSelect={(a) => canvas.selectVersion(a.id, a.version)}
          />
        </div>
      )}
    </>
  )
}
```

## What you get

- **`defineArtifactTool` / `defineAgentTool`** — the `publish_artifact` tool the agent
  calls to render an artifact.
- **`createArtifactBus()`** — a process-local pub/sub between the tool handler and the
  SSE endpoint. Call it **once per process** at module top-level.
- **`createSqliteArtifactStore` / a store adapter** — persistence + versioning for
  artifacts.
- **`CanvasPanel` + `useCanvas`** (`/ui` sub-path) — the side-panel component and hook,
  with version history.

  The bus is **process-local**. In multi-instance deployments (Vercel Functions,
  multi-pod K8s) subscribers in one pod do not see emits from another — a
  `createRedisArtifactBus()` adapter is planned. Single-instance apps (a Node server,
  single Docker, or dev) work as-is.

---

# @theokit/plugin-copilot

Source: https://docs.usetheo.dev/theokit/plugins/copilot

AI Copilot pattern for TheoKit — a defineCopilot factory, a CopilotRuntime, React hooks, and a <CopilotChat /> composite.

`@theokit/plugin-copilot` implements the AI-copilot pattern for TheoKit: a
`defineCopilot` factory, a `CopilotRuntime` orchestrator, a family of React hooks, and a
`<CopilotChat />` composite. It composes the `@theokit/sdk` Agent with
`@theokit/plugin-realtime`, and optionally with rate-limit, canvas, and voice peers.

**Differentiator from CopilotKit:** the copilot is a first-class participant in the
realtime room — every human sees the copilot's `name`, `avatar`, `color`, and `typing`
status in the presence map. Multiple copilots can coexist in one room with policy-driven
dispatch (`first-wins` / `round-robin` / `all` / custom function).

## Install

```bash
pnpm add @theokit/plugin-copilot @theokit/sdk @theokit/plugin-realtime theokit
# Optional Zod schemas for room presence / broadcast:
pnpm add zod
# Optional React peer for the /react sub-path:
pnpm add react react-dom
# Optional UI composites (<CopilotChat /> builds on @theokit/ui chat surfaces):
pnpm add @theokit/ui
```

Optional capability peers: `@theokit/plugin-rate-limit` (cost guard),
`@theokit/plugin-voice` (STT/TTS), `@theokit/plugin-canvas` (artifact emission), and
`@usetheo/ui` (generic primitives for the usage-meter). The plugin uses structural type
mirrors, so it compiles standalone and resolves peers at runtime.

## Usage

### Define a copilot

```ts title="app/copilots/support.ts"
import { defineCopilot } from '@theokit/plugin-copilot'
import { z } from 'zod'

export default defineCopilot({
  id: 'support-bot',
  room: {
    id: 'support-room',
    presence: z.object({ name: z.string().optional() }),
    broadcast: z.object({
      kind: z.enum(['question', 'answer', 'tool-call']).optional(),
      text: z.string().optional(),
    }),
  },
  agent: {
    name: 'SupportBot',
    model: 'openai/gpt-4o-mini',
    systemPrompt: 'You are SupportBot. Be concise and helpful.',
  },
  identity: { name: 'Support Bot', avatar: '/avatars/support.png', color: '#7c3aed' },
  triggers: [
    { on: 'broadcast:question', action: 'respond' },
    { on: 'presence:idle', action: 'suggest', idleMs: 30_000 },
  ],
  budget: { perRoom: { perRequestUsd: 0.01, dailyUsd: 1.0 } },
})
```

### Activate the runtime

```ts title="server/bootstrap.ts"
import { createMemoryRealtimeProvider } from '@theokit/plugin-realtime'
import { CopilotRuntime } from '@theokit/plugin-copilot'
import supportCopilot from './copilots/support.js'

const provider = createMemoryRealtimeProvider()
// `agent` bridges the SDK Agent to the CopilotAgentLike streamObject shape — see README.
const runtime = new CopilotRuntime({ provider, agent, copilots: [supportCopilot], estimatedCostPerInvocationUsd: 0.001 })
await runtime.activate('support-bot')
```

### Render with React

```tsx title="app/page.tsx"
import { CopilotProvider, CopilotChat } from '@theokit/plugin-copilot/react'
import { provider } from './bootstrap'

export default function Page() {
  return (
    <CopilotProvider roomId="support-room" copilotId="support-bot" provider={provider} userConnectionId="alice">
      <CopilotChat />
    </CopilotProvider>
  )
}
```

Or drop to the headless hooks (`useCopilotMessages`, `useCopilotPresence`,
`useCopilotTyping`, `useCopilotReadable`, `useCopilotTool`) for full theme control.

## What you get

- **Triggers** — `broadcast:<event>` (`respond` / `execute-tool`), `presence:idle`
  (`suggest`), and `custom` filter functions decide when the copilot acts.
- **Multi-copilot dispatch** — `first-wins` (default), `round-robin`, `all`, or a
  custom `(copilots, frame) => string[]` function.
- **Budget guard** — `budget.perRoom.{perRequestUsd, dailyUsd, monthlyUsd}` runs a
  preflight; on exceed the copilot broadcasts a typed `budget-exceeded` frame instead of
  invoking the agent. `runtime.getUsage(copilotId)` returns the rolling totals.
- **Provider abstraction** — any realtime provider (Memory, Yjs, Liveblocks, PartyKit,
  TheoCloud) via `defineCopilotRealtimeProvider`.

  Cost runaway and copilot impersonation are guarded structurally: the runtime filters
  out any frame whose `connectionId` starts with `copilot:` **before** evaluating
  triggers, so a copilot cannot trigger another copilot into an infinite loop, and a
  human cannot claim a `copilot:*` connection id.

---

# @theokit/plugin-db-drizzle

Source: https://docs.usetheo.dev/theokit/plugins/db-drizzle

Standalone DB plugin for TheoKit — wraps drizzle-kit and @theokit/orm behind a single plugin-shape factory with a seven-verb CLI.

`@theokit/plugin-db-drizzle` wraps `drizzle-kit` and `@theokit/orm` behind a single
plugin-shape factory. One `drizzleDb(opts)` call wires Drizzle into your TheoKit app, and
you get seven `theokit db <verb>` CLI subcommands plus a drizzle-kit studio passthrough —
no custom UI baggage.

`@theokit/orm` is a required peer: this plugin **wraps** it, never duplicates it. Your
`Repository`, `@InjectRepository`, `@Transactional`, and `OrmModule` keep working
unchanged — the plugin re-exports the ORM's surface.

## Install

```bash
pnpm add @theokit/plugin-db-drizzle @theokit/orm drizzle-orm reflect-metadata
# Optional — only needed for the CLI verbs (generate/migrate/studio/...):
pnpm add -D drizzle-kit
```

## Usage

### Register in `theo.config.ts`

```ts title="theo.config.ts"
import { drizzleDb } from '@theokit/plugin-db-drizzle'
import { defineConfig } from 'theokit'

export default defineConfig({
  plugins: [
    drizzleDb({
      driver: 'postgres',
      url: process.env.DATABASE_URL,
      schemaPath: './db/schema.ts',
      migrationsPath: './db/migrations',
    }),
  ],
})
```

### CLI verbs

```bash
theokit db generate        # Generate migration from schema diff
theokit db migrate         # Apply pending migrations
theokit db push            # Push schema directly (dev-only)
theokit db studio          # Open drizzle-kit studio (visual DB explorer)
theokit db reset --force   # Drop tables + re-apply all migrations
theokit db seed            # Run the user-provided seed script
theokit db check           # Check schema drift
```

All verbs shell out to `drizzle-kit`. If you don't install it, your runtime app still
works — only the CLI verbs error out with an actionable message.

### Session-scoped queries (RLS / auth)

The plugin re-uses `@theokit/orm`'s `withAgentContext` AsyncLocalStorage — wrap
session-scoped queries the same way you do with the ORM directly:

```ts
import { withAgentContext } from '@theokit/orm'

await withAgentContext({ userId: session.userId }, async () => {
  return await users.findMany()
})
```

## Options reference

| Option           | Type                                | Default             | Notes                                     |
| ---------------- | ----------------------------------- | ------------------- | ----------------------------------------- |
| `driver`         | `'sqlite' \| 'postgres' \| 'mysql'` | (required)          | Canonical drizzle-kit driver names        |
| `url`            | `string`                            | (caller-provided)   | Connection URL — pass `process.env.DATABASE_URL` |
| `schemaPath`     | `string`                            | `'./db/schema.ts'`  | Path to your drizzle schema file          |
| `migrationsPath` | `string`                            | `'./db/migrations'` | Directory for generated migration files   |
| `devtoolsTab`    | `boolean`                           | `true`              | Register a devtools-overlay tab when present |

## Notes

- **Migrating from ORM-direct usage** — replace `OrmModule.forRoot({...})` in `modules`
  with `drizzleDb({...})` in `plugins`. Your Repository / decorator usage stays identical.
- **Devtools tab** — when the TheoKit devtools overlay is loaded, the plugin registers a
  "Database" tab that IFRAMEs drizzle-kit studio (`http://localhost:4983`); run
  `theokit db studio` in another terminal to populate it. Opt out with
  `drizzleDb({ devtoolsTab: false })`.

  The devtools overlay is dev-only — production builds tree-shake the tab module, so no
  IFRAME reaches your shipped bundle. For native RLS policy generation, drizzle-kit's own
  RLS support is the canonical path; this plugin does not add a layer on top of it.

---

# @theokit/plugin-email

Source: https://docs.usetheo.dev/theokit/plugins/email

Email plugin for TheoKit — an EmailProvider interface, a Resend default, opt-in React Email, and a magic-link template helper.

`@theokit/plugin-email` is the transactional-email layer for TheoKit. It defines a small
`EmailProvider` interface, ships a Resend implementation as the default, and adds a typed
template factory plus a `sendMagicLink` helper that wires directly into
[`@theokit/auth-magic-link`](/theokit/plugins/auth-magic-link). React Email is an opt-in
peer — the default templates are plain HTML/text, so nothing is pulled in until you use it.

The `EmailProvider` interface is the seam: implement it once and swap Resend for
SMTP/SES/SendGrid/custom without rewriting call sites.

## Install

```bash
# Minimum (Resend only — no React Email):
pnpm add @theokit/plugin-email resend

# With React Email templates (opt-in):
pnpm add @theokit/plugin-email resend @react-email/render @react-email/components react

# With magic-link wiring:
pnpm add @theokit/plugin-email resend @theokit/auth-magic-link
```

## Usage

### Send email

```ts title="server/email.ts"
import { ResendProvider } from '@theokit/plugin-email'

const email = ResendProvider({ apiKey: process.env.RESEND_API_KEY })

await email.send({
  from: 'Acme <noreply@app.test>',
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<h1>Welcome!</h1>',
  text: 'Welcome!',
})
```

### Wire magic-link delivery

`sendMagicLink(provider, opts)` returns a callback that satisfies
`@theokit/auth-magic-link`'s `SendMagicLinkFn` contract:

```ts title="server/auth/providers.ts"
import { ResendProvider, sendMagicLink } from '@theokit/plugin-email'
import { magicLink } from '@theokit/auth-magic-link'

const email = ResendProvider({ apiKey: process.env.RESEND_API_KEY })

export const magicLinkProvider = magicLink({
  store,
  callbackBaseUrl: 'https://app.test',
  sendEmail: sendMagicLink(email, {
    from: 'Acme <noreply@app.test>',
    appName: 'Acme',
    subject: ({ to, appName }) => `${appName} sign-in link for ${to}`,
  }),
})
```

The default magic-link template ships an accessible, single-CTA HTML + text body — no
React Email required.

### Custom provider or template

```ts
import { defineEmailProvider, defineEmailTemplate } from '@theokit/plugin-email'

const consoleProvider = defineEmailProvider({
  name: 'console',
  async send(msg) {
    console.log('[email]', msg.subject, '→', msg.to)
    return { id: `console_${Date.now()}`, provider: 'console' }
  },
})

const welcome = defineEmailTemplate<{ name: string }>('welcome', async (props) => ({
  subject: `Welcome, ${props.name}`,
  html: `<h1>Hi ${props.name}</h1>`,
  text: `Hi ${props.name}`,
}))
```

## What you get

- **`EmailProvider` interface** — `name` + `send(message): Promise<SendResult>`,
  implemented once for any transport.
- **`ResendProvider({ apiKey })`** — the canonical Resend wrapper (the default).
- **`defineEmailProvider(impl)`** — extension surface for SMTP/SES/SendGrid/custom.
- **`defineEmailTemplate(name, render)` + `renderReactEmail(component)`** — a typed
  template factory and the opt-in React Email render bridge (dynamic peer import; zero
  cost when unused).
- **`sendMagicLink(provider, opts)`** — the magic-link delivery helper.

  Resend's `Idempotency-Key` header is mapped automatically from
  `EmailMessage.idempotencyKey`, deduplicating retries. For magic-link, the key defaults
  to `magic_link:${token}`; override it with the `idempotencyKey` option or disable with
  `idempotencyKey: null`. The `RESEND_API_KEY` is resolved from env — the plugin never
  logs it.

---

# @theokit/plugin-forms

Source: https://docs.usetheo.dev/theokit/plugins/forms

Declarative form binding for TheoKit — zod + react-hook-form + useAction behind a single <TheoForm> component.

`@theokit/plugin-forms` glues `zod`, `react-hook-form`, and `useAction` (from
`@theokit/react`) into a single `<TheoForm action={actions.X}>` component. Field-level
errors from `ActionInputError.fields` map straight into the form via a small adapter, and
pending state flows through Context — so a typed server action becomes a validated form
with almost no boilerplate.

It offers two tiers: a styled `<TheoField>` tier built on `@usetheo/ui`, and a headless
`useTheoField` tier that works in any React stack (shadcn, MUI, raw HTML).

## Install

```bash
pnpm add @theokit/plugin-forms react-hook-form @hookform/resolvers zod
# Optional (recommended) for the styled <TheoField> tier:
pnpm add @usetheo/ui
```

Peers: `react >= 19`, `react-hook-form ^7.50`, `@hookform/resolvers ^5`,
`zod ^3.25 || ^4`, `theokit >= 0.2.3`, `@theokit/react >= 1.1.0`, and — only for the
styled tier — `@usetheo/ui >= 0.14.0`.

## Usage

### Shared-schema convention

Author each action's input schema in an isomorphic file so both the handler and the form
read the same source of truth:

```ts title="server/actions/schemas/save-memory.ts"
import { z } from 'zod'
export const schema = z.object({
  conversationId: z.string().min(1),
  content: z.string().min(1),
})
```

```ts title="server/actions/save-memory.ts"
import { defineAction } from 'theokit/server'
import { schema } from './schemas/save-memory.js'
export const saveMemory = defineAction({
  input: schema,
  handler: async ({ input }) => ({ id: 'mem_...' }),
})
```

The TheoKit Vite plugin exposes the schema at runtime as `actions.saveMemory.__zodSchema`;
`<TheoForm>` reads it to drive RHF's `zodResolver` — no client re-declaration.

### Styled tier

```tsx title="app/memory.tsx"
'use client'
import { actions } from '@theo/actions'
import { TheoForm, TheoField, useTheoFieldRegister } from '@theokit/plugin-forms'
import { FormField, Input, Button } from '@usetheo/ui'

function ContentInput() {
  const register = useTheoFieldRegister()
  return <Input {...register} placeholder="Type something..." />
}

export default function MemoryPage() {
  return (
    <TheoForm action={actions.saveMemory} defaultValues={{ conversationId: 'default', content: '' }} onSuccess={(d) => console.log('Saved:', d)}>
      <input type="hidden" name="conversationId" value="default" readOnly />
      <TheoField name="content">
        <FormField.Label required>Memory</FormField.Label>
        <FormField.Control><ContentInput /></FormField.Control>
        <FormField.Error />
      </TheoField>
      <Button type="submit">Save</Button>
    </TheoForm>
  )
}
```

### Headless tier (no `@usetheo/ui`)

```tsx title="app/my-form.tsx"
'use client'
import { actions } from '@theo/actions'
import { TheoForm, useTheoField } from '@theokit/plugin-forms'

function MyField({ name, label }: { name: string; label: string }) {
  const field = useTheoField(name)
  return (
    <label>
      {label}
      <input {...field.register} />
      {field.error && <span role="alert">{field.error.message}</span>}
    </label>
  )
}

export default function MyForm() {
  return (
    <TheoForm action={actions.saveMemory} defaultValues={{ conversationId: 'default', content: '' }}>
      <input type="hidden" name="conversationId" value="default" readOnly />
      <MyField name="content" label="Memory content" />
      <button type="submit">Save</button>
    </TheoForm>
  )
}
```

## What you get

- **`<TheoForm>`** — wires `useAction` + RHF `useForm({ resolver: zodResolver(...) })`
  and provides Context.
- **`<TheoField>` / `useTheoField`** — the styled and headless field tiers.
- **`useTheoFormState()`** — form-level `isPending` / `isError` / `error` / `data` for
  submit buttons and status.
- **`applyActionErrorsToForm(setError, fields)`** — the pure adapter mapping
  `ActionInputError.fields` into RHF `setError` calls (first message per field wins).

  v0.1 requires JavaScript on the client — there is no progressive-enhancement /
  FormData path yet (targeted for v0.2), and no file uploads. Async zod refinements
  (`.refine(async)`) are stripped client-side; rely on the server's `ActionInputError`
  for those. If you keep the input schema inline in `defineAction` instead of the
  shared-schema convention, `__zodSchema` is `undefined` and the form falls back to
  server-side validation only.

---

# Getting started

Source: https://docs.usetheo.dev/theokit/plugins/getting-started

The common adoption pattern for TheoKit plugins — install with peers, register in theo.config.ts or Auth.create, then wire routes with defineRoute.

Every TheoKit plugin follows the same shape. Install it with its peer dependencies,
register it once (in `theo.config.ts` for capability plugins, or inside `Auth.create`
for auth providers), and wire any endpoints it exposes with `defineRoute`. Below are
the two worked examples — a capability plugin and an auth provider.

## Peer-dependency discipline

Plugins never bundle the framework. `theokit` and, for most, `@theokit/sdk` are peer
dependencies you install alongside the plugin so there is exactly one copy in your app.
Each plugin's own doc lists its full peer set (some add `zod`, `react`, `drizzle-orm`,
`stripe`, or `resend`); install the ones the feature you use requires.

```bash
pnpm add theokit @theokit/sdk
```

## Capability plugin — register in `theo.config.ts`

Capability plugins register through the `plugins` array of your TheoKit config. The
Drizzle DB plugin is a compact example — one `drizzleDb(...)` call:

```bash
pnpm add @theokit/plugin-db-drizzle @theokit/orm drizzle-orm reflect-metadata
```

```ts title="theo.config.ts"
import { drizzleDb } from '@theokit/plugin-db-drizzle'
import { defineConfig } from 'theokit'

export default defineConfig({
  plugins: [
    drizzleDb({
      driver: 'postgres',
      url: process.env.DATABASE_URL,
      schemaPath: './db/schema.ts',
      migrationsPath: './db/migrations',
    }),
  ],
})
```

Some capability plugins expose an HTTP surface instead of (or in addition to) a config
registration. The canvas plugin, for example, is mounted through an agent endpoint and
an SSE route — see [Canvas](/theokit/plugins/canvas) for the full wiring. When a plugin
gives you a handler, expose it with `defineRoute`:

```ts title="server/routes/api/canvas/artifacts.ts"
import { defineRoute } from 'theokit/server'

export const GET = defineRoute({
  handler: async ({ req }) => {
    // forward the plugin's SSE / list handler here
    return new Response('…')
  },
})
```

  Not every plugin auto-registers its routes. Voice, for instance, validates config in
  `theo.config.ts` but you wire each endpoint yourself with `defineRoute` calling
  `handleSttRequest` / `handleTtsRequest`. Each plugin's doc states whether routes are
  automatic.

## Auth provider — add to `Auth.create`

Auth providers are factories you pass into the `providers` array of `Auth.create` from
`@theokit/sdk/server/auth`. GitHub is the canonical example:

```bash
pnpm add @theokit/auth-github @theokit/sdk theokit
```

```ts title="server/auth/index.ts"
import { Auth } from '@theokit/sdk/server/auth'
import { github } from '@theokit/auth-github'
import { sessionManager } from './session.js'

export const auth = Auth.create({
  session: sessionManager,
  providers: [
    github({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      redirectUri: 'https://myapp.com/api/auth/github/callback',
    }),
  ],
  onSignIn: async ({ profile }) => {
    return { userId: String(profile.id), email: profile.email, login: profile.login }
  },
})
```

The orchestrator drives a `start` and a `callback` route per provider — wire them with
`defineRoute`:

```ts title="server/routes/api/auth/github/callback.ts"
import { defineRoute } from 'theokit/server'
import { auth } from '../../../auth/index.js'

export const GET = defineRoute({
  handler: async ({ req, res }) => {
    const { returnTo } = await auth.finishSignIn('github', req, res)
    return Response.redirect(returnTo ?? '/', 302)
  },
})
```

## Next

---

# Overview

Source: https://docs.usetheo.dev/theokit/plugins

First-party TheoKit plugins — auth providers and capability plugins that extend a TheoKit app without leaving the framework.

**TheoKit plugins** are the first-party extensions of the framework — small, focused
packages published as **`@theokit/*`** on npm that add a capability to a TheoKit app
without you wiring the plumbing by hand. Auth, realtime, voice, payments, email, forms,
a canvas side-panel, a copilot participant, and a Drizzle-backed database plugin all
ship as independent packages you add only when you need them.

Eleven plugins ship today, in **two families**:

- **Auth providers** — `github`, `google`, and `magicLink` plug into the
  `@theokit/sdk` auth orchestrator via `Auth.create({ providers: [...] })`. Each is a
  factory that composes the OAuth / OIDC / passwordless flow against the SDK's auth
  primitives; you supply credentials and an `onSignIn` callback.
- **Capability plugins** — `canvas`, `copilot`, `realtime`, `voice`, `forms`,
  `payments`, `email`, and `db-drizzle` add a feature surface. Most register in
  `theo.config.ts` (`plugins: [...]`) and expose routes you wire with `defineRoute`;
  the React-facing ones ship components and hooks on a `/react` or `/ui` sub-path.

  Every plugin is Apache-2.0-style community-licensed (MIT per package) and versioned
  **independently** via Changesets — you upgrade `@theokit/plugin-canvas` without
  touching `@theokit/auth-github`. `theokit` and `@theokit/sdk` are the common peer
  dependencies; install them alongside the plugin.

## The two families at a glance

- **Auth providers** are stateless factories. You pass them into `Auth.create`, and the
  orchestrator drives the `startSignIn` / `finishSignIn` handshake. GitHub is OAuth 2.0,
  Google is full OIDC + PKCE, and magic-link is passwordless email with a pluggable
  token store.
- **Capability plugins** own more of the request lifecycle. `payments` verifies Stripe
  webhook signatures, `realtime` runs presence + broadcast rooms, `voice` bridges STT/TTS
  providers, `canvas` streams agent artifacts into a side panel, and `db-drizzle` wraps
  `@theokit/orm` behind a single factory plus a `theokit db` CLI.

## What you'd add and when

- **Ship sign-in** — drop `github` / `google` / `magicLink` into `Auth.create`; pair
  magic-link with `email` for the delivery transport.
- **Make the agent build things** — mount `canvas` so the agent can `publish_artifact`
  (markdown, code, diffs, diagrams, slides, whiteboards) into a live side panel.
- **Go multiplayer** — `realtime` for cursors, typing, and Yjs documents; `copilot`
  to make the agent a visible participant in the room.
- **Take money and talk to users** — `payments` for Stripe checkout + webhooks,
  `email` for transactional mail, `voice` for speech in and out.
- **Wire the data layer** — `forms` for typed, action-bound forms; `db-drizzle` for a
  one-call Drizzle + ORM setup with migrations and studio.

## Browse the plugins

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/plugins/llms-txt

Machine-readable ground truth of @theokit/plugins for LLMs — the 11 first-party plugins (auth + capability), their factory names, common peers, and honest v0.x status.

The `@theokit/plugins` section ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that gives any
LLM (Claude, ChatGPT, Cursor, Copilot, a local model) the **factual ground truth** of the
first-party TheoKit plugins without crawling the whole site:

- The two plugin families — **auth providers** (factories for `@theokit/sdk` `Auth.create`)
  and **capability plugins** (registered in `theo.config.ts` and/or wired via `defineRoute`)
- All 11 plugins, each with its real factory name, common peers, current version, and a
  link to its live reference page
- The install pattern (generic `pnpm add @theokit/<plugin>`, plus the extra `@theokit/sdk
  theokit` for auth providers)
- Honest per-plugin gotchas — canvas's optional `mermaid` peer and process-local bus,
  magic-link's dev-only memory store, voice's non-auto-registered secure-context endpoints,
  payments' swap-for-prod idempotency store, forms' v0.1 JS-required limitation

  Most plugins are still **v0.x**. The file is honest about what is shipped vs planned, and
  every factory name and peer range is sourced from the plugin's `package.json` and README —
  no fabricated APIs.

## Get it

```bash
curl https://docs.usetheo.dev/theokit/plugins/llms.txt
```

Or link your AI assistant directly at
[`https://docs.usetheo.dev/theokit/plugins/llms.txt`](https://docs.usetheo.dev/theokit/plugins/llms.txt).

## Why

Point your coding assistant at it when you want it to stop hallucinating factory names,
peer versions, or which family a plugin belongs to. Auth providers are **factories for
`Auth.create`**, not standalone servers; capability plugins register in `theo.config.ts` and
expose `defineRoute`-wired endpoints. The file makes that distinction explicit so an agent
wires each plugin the right way the first time.

---

# @theokit/plugin-payments

Source: https://docs.usetheo.dev/theokit/plugins/payments

Stripe payments plugin for TheoKit — a typed webhook dispatcher with signature verification, idempotency, and a Checkout helper.

`@theokit/plugin-payments` is the Stripe payments plugin for TheoKit. It gives you a
typed webhook dispatcher (`defineStripeWebhook`) with signature verification and
idempotency, plus a `createCheckoutSession` helper for Stripe-hosted checkout and a pair
of currency formatters. Handlers receive the narrowed `Stripe.Event` variant via a
discriminated union on `event.type`.

Stripe is the only supported gateway. `@theokit/orm` is an optional peer — needed only
when you swap the default in-memory idempotency store for the production-grade one.

## Install

```bash
pnpm add @theokit/plugin-payments stripe
# Production idempotency via @theokit/orm:
pnpm add @theokit/orm drizzle-orm reflect-metadata
```

## Usage

### Register in `theo.config.ts`

```ts title="theo.config.ts"
import { payments } from '@theokit/plugin-payments'
import { defineConfig } from 'theokit'

export default defineConfig({
  plugins: [
    payments({
      // secretKey defaults to process.env.STRIPE_SECRET_KEY
      // webhookSecret defaults to process.env.STRIPE_WEBHOOK_SECRET
      apiVersion: '2023-10-16',
    }),
  ],
})
```

### Handle webhooks

```ts title="server/routes/api/stripe/webhook.ts"
import { defineStripeWebhook, processWebhook, WebhookRegistry, payments } from '@theokit/plugin-payments'

const plugin = payments()
const registry = new WebhookRegistry()

registry.register(
  defineStripeWebhook('checkout.session.completed', async (event) => {
    const session = event.data.object // typed as Stripe.CheckoutSessionCompletedEvent
    console.log('Customer:', session.customer)
  }),
)

export async function POST(req: Request) {
  const rawBody = await req.text() // MUST read raw bytes FIRST
  const result = await processWebhook({
    stripe: plugin.getStripeClient(),
    rawBody,
    signatureHeader: req.headers.get('stripe-signature') ?? undefined,
    webhookSecret: plugin.options.webhookSecret!,
    registry,
    store: plugin.options.idempotencyStore!,
  })

  switch (result.status) {
    case 'ok': return Response.json({ received: true, eventId: result.eventId })
    case 'signature_invalid': return Response.json({ error: result.message }, { status: 400 })
    case 'handler_error': return Response.json({ error: 'handler failed' }, { status: 500 })
  }
}
```

### Create a Checkout session

```ts title="server/actions/checkout.ts"
import { createCheckoutSession, payments, formatAmountForStripe } from '@theokit/plugin-payments'

const plugin = payments()

export async function startCheckout() {
  const { url, sessionId } = await createCheckoutSession(plugin.getStripeClient(), {
    mode: 'payment',
    line_items: [{
      quantity: 1,
      price_data: {
        currency: 'USD',
        product_data: { name: 'Pro Plan' },
        unit_amount: formatAmountForStripe(29.99, 'USD'), // → 2999 cents
      },
    }],
    success_url: 'https://app.test/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url: 'https://app.test/cancel',
    metadata: { userId: 'u_123' }, // tie to your auth session
  })
  return { redirectTo: url, sessionId }
}
```

## What you get

- **`payments(opts)`** — the plugin factory (options: `secretKey`, `webhookSecret`,
  `apiVersion`, `idempotencyStore`).
- **`defineStripeWebhook(type, handler)` + `processWebhook` + `WebhookRegistry`** — the
  typed dispatcher with HMAC signature verification and idempotency.
- **`createCheckoutSession(client, params)`** — returns `{ url, sessionId }` for a
  Stripe-hosted checkout page.
- **`formatAmountForStripe` / `formatAmountForDisplay`** — zero-decimal vs decimal
  currency helpers.

  Two production gotchas. **Raw body:** webhook routes MUST receive raw bytes before any
  other body access — `await req.text()` first, or Stripe's HMAC breaks (on Vercel pages
  router, disable the body parser). **Idempotency store:** the default memory store is
  **not** multi-replica safe — swap it for `createOrmStore(repo)` (an atomic `UNIQUE`
  constraint on `event.id`) before shipping. The plugin does not auto-correlate customers
  to users; carry your user id in `metadata` and read it back in the handler.

---

# @theokit/plugin-realtime

Source: https://docs.usetheo.dev/theokit/plugins/realtime

Multiplayer realtime plugin for TheoKit — presence, broadcast, and opt-in Yjs CRDT rooms.

`@theokit/plugin-realtime` adds multiplayer to a TheoKit app: presence, broadcast, and
opt-in Yjs CRDT rooms. It ships primitives for cursors, typing indicators, live counters,
and collaborative documents, and consumes `@theokit/sdk/subscription` for the WebSocket
transport. React hooks live on the `/react` sub-path.

The provider is swappable — a Memory provider for single-node dev, a Yjs provider for
CRDT documents, and `defineRealtimeProvider` for Liveblocks / PartyKit / Redis / CF
Durable Objects.

## Install

```bash
pnpm add @theokit/plugin-realtime @theokit/sdk theokit zod
# Optional CRDT peers (only for YjsRealtimeProvider):
pnpm add yjs y-protocols
# Optional React peer (only for the /react sub-path):
pnpm add react react-dom
```

## Usage

### Define a room and mount the runtime

```ts title="app/rooms/cursor.ts"
import { defineRoom } from '@theokit/plugin-realtime'
import { z } from 'zod'

export default defineRoom({
  id: 'cursor',
  presence: z.object({
    cursor: z.tuple([z.number(), z.number()]).optional(),
    name: z.string().optional(),
  }),
  broadcast: z.object({ kind: z.literal('ping'), ts: z.number() }),
})
```

```ts title="server/bootstrap.ts"
import { RealtimeRuntime, createMemoryRealtimeProvider, mountRealtime } from '@theokit/plugin-realtime'
import { Subscription } from '@theokit/sdk/subscription'
import { z } from 'zod'
import cursorRoom from './app/rooms/cursor.js'

const provider = createMemoryRealtimeProvider()
const runtime = new RealtimeRuntime({ provider, rooms: [cursorRoom] })
const mounted = mountRealtime({ runtime, rooms: [cursorRoom] })

for (const [, sub] of mounted.subscriptions) {
  Subscription.create({ input: sub.input, output: z.any(), handler: sub.handler })
}
```

### React hooks

```tsx title="app/App.tsx"
import { RoomProvider, useOthers, useRoom } from '@theokit/plugin-realtime/react'
import { Theokit } from '@theokit/sdk'

function App() {
  return (
    <RoomProvider roomId="cursor" client={Theokit} initialPresence={{ name: 'Alice' }} baseUrl="http://localhost:3000">
      <Cursors />
    </RoomProvider>
  )
}

function Cursors() {
  const { myPresence, updateMyPresence } = useRoom()
  const others = useOthers()
  return (
    <div onMouseMove={(e) => updateMyPresence({ cursor: [e.clientX, e.clientY] })}>
      <p>You: {JSON.stringify(myPresence)}</p>
      {Object.entries(others).map(([id, p]) => (
        <p key={id}>{id}: {JSON.stringify(p)}</p>
      ))}
    </div>
  )
}
```

## What you get

- **`defineRoom`** — a Zod-validated room with typed `presence` and `broadcast` shapes,
  optional `authorize` hook, and `storage: 'yjs'` for CRDT documents.
- **Providers** — `createMemoryRealtimeProvider` (dev), `createYjsRealtimeProvider`
  (CRDT, with a `maxUpdateBytes` cap), and `defineRealtimeProvider` for custom backends.
- **Hooks** (`/react`) — `useRoom`, `useOthers`, `usePresence`, `useUpdateMyPresence`,
  `useBroadcast`, `useYDoc`.

  In v0.1 several hooks are **local-only**: `useUpdateMyPresence` and `useBroadcast`
  update the local client optimistically but do not yet fan out to other participants,
  and `useYDoc` throws (Y.Doc auto-wiring is deferred). Wire server-side presence through
  the runtime + subscription for cross-client sync today.

## Notes

- The Yjs provider requires `yjs ^13` + `y-protocols ^1`; a dynamic `import('yjs')`
  keeps the server-only path zero-cost when CRDT isn't used.
- `RealtimeRuntime` enforces `roomId` scoping — provider methods cannot cross-room emit.
  The Zod schema at the `defineRoom` boundary validates presence fields; keep presence to
  non-sensitive, opt-in data to avoid PII leakage.
- **Runtime support (v0.1):** Node 22+ is canonical; Cloudflare Workers, Bun, and Deno
  run via a consumer-supplied adapter through `defineRealtimeProvider`.

---

# @theokit/plugin-voice

Source: https://docs.usetheo.dev/theokit/plugins/voice

Voice plugin for TheoKit — speech-to-text and text-to-speech with a browser MediaRecorder helper and UI components.

`@theokit/plugin-voice` bridges speech-to-text and text-to-speech into a TheoKit app.
Register it once in `theo.config.ts`, then wire the STT/TTS endpoints yourself. It ships
a browser `MediaRecorder` helper that throws typed errors (instead of raw `DOMException`)
so a `<VoiceRecorderBar>` can render an actionable alert when the user denies the mic,
plus a `useTts` hook and UI components.

STT is provider-agnostic (OpenAI Whisper or Groq Whisper, selected by env var); config is
validated synchronously at boot, so a missing API key throws at startup — not on the
first user click.

## Install

```bash
pnpm add @theokit/plugin-voice
```

Peers: `theokit >= 0.1.0-alpha.5` (server-side hook registration) and `react ^18 || ^19`
(only for the `./ui` sub-path).

## Usage

### Configure the plugin

```ts title="theo.config.ts"
import { defineTheoConfig } from 'theokit/server'
import voicePlugin from '@theokit/plugin-voice'

export default defineTheoConfig({
  plugins: [
    voicePlugin({
      stt: { provider: 'openai' }, // reads OPENAI_API_KEY from env
      tts: { provider: 'openai', voice: 'alloy' },
    }),
  ],
})
```

  Endpoint registration is **not** automatic. Wire each endpoint with `defineRoute` in
  `server/routes/` — a POST route calling `handleSttRequest` at `/api/voice/stt`
  (`multipart/form-data`, field `audio`) and one calling `handleTtsRequest` at
  `/api/voice/tts` (`application/json`, `{ text, voice? }`). Both paths are configurable
  via `stt.endpoint` / `tts.endpoint` and must start with `/`.

### Browser recorder

```tsx title="app/chat.tsx"
'use client'
import { VoiceRecorderBar } from '@theokit/plugin-voice/ui'
import { ChatComposer } from '@theokit/ui'

export function ChatPage() {
  const [value, setValue] = useState('')
  return (
    <ChatComposer
      value={value}
      onValueChange={setValue}
      leadingActions={<VoiceRecorderBar onTranscript={(t) => setValue((v) => v + ' ' + t)} />}
    />
  )
}
```

## Environment variables

| Variable         | Required                                | Notes                                      |
| ---------------- | --------------------------------------- | ------------------------------------------ |
| `OPENAI_API_KEY` | yes (default STT + TTS provider)        | Used for `stt`/`tts` provider `"openai"`   |
| `GROQ_API_KEY`   | only if `stt.provider: "groq"`          | Groq Whisper (no TTS — fall back to OpenAI) |

Override the env var name with `stt.envVar` / `tts.envVar`, or pass `stt.apiKey` /
`tts.apiKey` explicitly.

## Notes

- **Secure context required.** `MediaRecorder` + `getUserMedia` only work over HTTPS or
  `localhost`. On plain `http://` the recorder throws `VoicePermissionDeniedError` even
  after the user grants permission — use `mkcert` or run on `localhost` in dev.
- **Typed error hierarchy.** All errors extend `VoicePluginError`. Catch the specific
  subclass for targeted UX: `VoicePermissionDeniedError` / `VoiceNoDeviceError` (browser,
  `recorder.start()`), `VoicePluginConfigError` (server, at construction), and
  `VoiceProviderError` (server, provider returned non-2xx).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/prompts/advanced

System-prompt precedence, per-send overrides, the full SystemPromptContext, and the resolver caveats.

# Advanced prompts

The [Dynamic instructions](/theokit/prompts/dynamic-instructions) how-to shows the resolver in
action. This page is the precise contract around `systemPrompt`.

## Precedence

`systemPrompt` can be set in two places. The order, highest first:

1. **`SendOptions.systemPrompt`** — a per-call override (string only). Wins for that one `send()`.
2. **`AgentOptions.systemPrompt`** — the agent default (a string, or a resolver evaluated per send).

An **empty string** in either slot is honored — it explicitly *clears* the system context (rather
than falling through). Omit the field entirely to leave it unset.

```ts
// Per-call override — string only. For dynamic per-call prompts, configure the resolver on the agent.
await agent.send("Summarize.", { systemPrompt: "Answer in exactly one sentence." });
```

## The resolver context

When `AgentOptions.systemPrompt` is a function, it receives a `SystemPromptContext`. **Field order is
a compatibility contract** — new fields are appended, never reordered.

```ts
interface SystemPromptContext {
  agentId: string;
  cwd: string | undefined;
  model: ModelSelection | undefined;
  skills: ReadonlyArray<{ name: string; description: string }>;
  userMessage: string;
}
```

The resolver may be **sync or async**. Errors it throws **propagate** to the caller of
`agent.send()`. The SDK imposes **no timeout** — if you call into a slow resource, wrap your own
`Promise.race`.

## Caveats

- **String-only per call.** `SendOptions.systemPrompt` is a plain string. Dynamic per-call behavior
  belongs on the agent's resolver (which sees `userMessage`).
- **Subagents do not inherit** the parent's `systemPrompt` — they use their own
  `AgentDefinition.prompt`.
- **Skills** surface to the resolver via `ctx.skills` (name + description) and are injected into the
  assembled prompt as a `<skills>` block — see [Skills](/theokit/skills).

## Reference

- [`AgentOptions`](/theokit/reference/AgentOptions) · [`SystemPromptContext`](/theokit/reference/SystemPromptContext)

---

# Dynamic instructions

Source: https://docs.usetheo.dev/theokit/prompts/dynamic-instructions

Compute the system prompt per send with a resolver, and override it for a single call.

# Dynamic instructions

Set the system prompt with a resolver — evaluated on every send — and override it for a
single call with a string.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

// Dynamic instructions: the system prompt is computed per send from context.
const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: (ctx) =>
    `You are a terse assistant. Answer in exactly one sentence. The user asked: "${ctx.userMessage}".`,
});

const dynamic = await (await agent.send("What is TypeScript?")).wait();
console.log("Dynamic:  ", dynamic.result);

// Per-send override: a string that wins over the resolver for this send only.
const override = await (
  await agent.send("What is TypeScript?", { systemPrompt: "Reply as a pirate, in one sentence." })
).wait();
console.log("Override: ", override.result);

await agent.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Dynamic:   TypeScript is a statically-typed superset of JavaScript that compiles to plain
JavaScript, adding optional type annotations, interfaces, and modern language features.
Override:  Arr, TypeScript be a swashbucklin' superset o' JavaScript that adds type-safety,
then compiles back to plain JavaScript for smooth sailin' on the high seas of code!
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- `systemPrompt: (ctx) => string` — a resolver that reads `ctx.userMessage` (and `model`,
  `memory`, `skills`) to build the prompt for **each** send.
- `agent.send(msg, { systemPrompt })` — a per-send string that **overrides** the resolver
  for one call (here: same question, pirate persona).

## Example

Full runnable source:
[`examples/prompts`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/prompts).

---

# Overview

Source: https://docs.usetheo.dev/theokit/prompts

An agent's instructions — the system prompt — as a string, a per-send resolver, or a per-call override.

# Prompts and instructions

An agent's **instructions** are its system prompt: who it is, what it should do, how it
should answer. In TheoKit the system prompt can be a fixed string, a function computed
per send, or overridden for a single call.

## Three ways to set instructions

### Static

The common case — a plain string set once.

```ts
await Agent.create({ apiKey, model, systemPrompt: "You are a concise assistant." });
```

### Dynamic (a resolver)

A function evaluated **on every send**, so the prompt can react to the message, the
model, or recalled memory.

```ts
await Agent.create({
  apiKey,
  model,
  systemPrompt: (ctx) => `Answer in one sentence. The user asked: "${ctx.userMessage}".`,
});
```

The resolver receives a `SystemPromptContext`:

| Field | What it carries |
| --- | --- |
| `userMessage` | the message being sent |
| `model` | the resolved model selection |
| `memory` | recalled durable facts (when memory is on) |
| `skills` | the skills available to the agent |
| `cwd` · `agentId` | run location and identity |

Errors thrown in the resolver propagate to the caller of `agent.send()`; there is no
built-in timeout, so wrap slow lookups yourself.

### Per-send override

Override the instructions for **one** send with a string — it wins over the resolver.

```ts
await agent.send(message, { systemPrompt: "Reply as a pirate." });
```

## Project instructions

`@theokit/sdk/project` reads and writes on-disk instructions that layer into the prompt:
`readProjectInstructions(cwd)` walks up the directory tree collecting instruction files
(never throws); `writeProjectInstructions(cwd, content)` writes them atomically.

## Personalities

`Agent.usePersonality(name)` applies a named personality preset on top of the base
instructions.

## Next

- [Dynamic instructions](/theokit/prompts/dynamic-instructions) — a runnable example: a
  resolver + a per-send override.

## Reference

- [`SystemPromptContext`](/theokit/reference/SystemPromptContext) · [`AgentOptions`](/theokit/reference/AgentOptions) · [`SendOptions`](/theokit/reference/SendOptions)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/providers-models/advanced

Model catalog and capability helpers, per-send model override, provider routing and fallback, resilience error codes, and custom providers.

# Advanced providers & models

## The model catalog

`Theokit.models.list()` returns the canonical catalog; the default model id
(`google/gemini-2.0-flash-001`) is a runnable fallback. Offline, inspect a model id with the helpers
from `@theokit/sdk/models`:

```ts
import { parseModelId, humanizeModelName, resolveModelCapabilities } from "@theokit/sdk/models";

parseModelId("anthropic/claude-3-5-sonnet");      // { provider, name, … }
humanizeModelName("claude-3-5-sonnet");            // "Claude 3 5 Sonnet"
resolveModelCapabilities("anthropic/claude-3-5-sonnet"); // { context, tools, vision, … }
```

## The `Theokit` namespace

`Theokit` is the static namespace for account- and catalog-level calls (against the PaaS control
plane, where configured):

| Call | Returns |
| --- | --- |
| `Theokit.me()` | The current user (`SDKUser`). |
| `Theokit.models.*` | The model catalog (list / lookup), including locally-served models. |
| `Theokit.providers.*` | Configured providers. |
| `Theokit.repositories.*` | Repositories (for the cloud/coding surfaces). |
| `Theokit.inspect.*` | Inspect a provider/model's resolved shape. |

## Per-send model override (sticky)

`send()` takes a per-call `model`. It's **sticky** — a successful send updates `agent.model`, so the
next send reuses it unless overridden again.

```ts
await agent.send("…", { model: { id: "openai/gpt-4o-mini" } });
```

## Provider routing & fallback

The same provider routing and fallback applies to `agent.send` and the model helpers — configure via
`local.providers` or environment keys. Keys are chosen per model id; the pool inserts a full-jitter
backoff before retrying a rate-limited (429) key.

## Resilience error codes

The runtime surfaces typed `NetworkError` codes so your retry / fallback logic can route them:

| Code | Meaning |
| --- | --- |
| `circuit_open` | A provider's circuit breaker is open after N consecutive failures — fails fast until a cooldown elapses. |
| `stream_idle_timeout` | An SSE stream produced no bytes within the idle bound (default 60s) and was cancelled. |
| `stream_truncated` | A stream ended without a finish reason / `[DONE]` sentinel — the partial turn is not committed. |
| `mcp_disconnected` | An MCP tool server dropped mid-run. |

## Custom providers — `Provider.create`

Bring a provider the catalog doesn't ship by building a provider plugin with `Provider.create` (the
v3.0 successor to `defineProvider`). It returns a `Plugin` you add to the agent, so a bespoke or
self-hosted endpoint speaks the same `agent.send` contract as a built-in provider.

```ts
import { Provider } from "@theokit/sdk";

const myProvider = Provider.create(profile, options); // returns a Plugin
await Agent.create({ /* … */, plugins: [myProvider] });
```

## Injectable `fetch`

Every provider call goes through an injectable `fetch` — pass your own to add tracing, a proxy, or a
custom retry layer without patching globals.

## Reference

- [`Provider`](/theokit/reference/Provider) · [`Theokit`](/theokit/reference/Theokit) · [`NetworkError`](/theokit/reference/NetworkError)

---

# Overview

Source: https://docs.usetheo.dev/theokit/providers-models

How TheoKit picks a model and connects to a provider, the built-in providers, and the offline model catalog.

# Providers and models

An agent needs a model. In TheoKit the model is chosen by **the id you pass** to
`Agent.create()` plus **the key** — the rest of your code is identical whichever
provider you use.

```ts
const agent = await Agent.create({
  apiKey,                              // authenticates the provider
  model: { id: "openai/gpt-4o-mini" }, // the vendor/model id selects it
});
```

## How selection works

- The **`vendor/model` id** picks the provider (`openai/…`, `anthropic/…`,
  `google/…`). [OpenRouter](https://openrouter.ai) routes any `vendor/model` id, so
  one key reaches every vendor.
- The **key** you pass authenticates. Pass an OpenRouter key to route through it, or
  a direct provider key to talk to that vendor.
- Routing prefixes (`openrouter/`, `bedrock/`, `vertex/`) and OpenRouter `:variant`
  suffixes (`openai/gpt-4o:free`) are understood everywhere.

## Built-in providers

| Provider | Reach it with | Notes |
| --- | --- | --- |
| **OpenRouter** | an OpenRouter key + any `vendor/model` id | One key, every vendor — the simplest multi-provider path. |
| **OpenAI** | an OpenAI key + `openai/…` | |
| **Anthropic** | an Anthropic key + `anthropic/…` | Claude models. |
| **Google** | a Google key + `google/…` | Gemini models. |
| **Bedrock** | AWS credentials | Claude on AWS Bedrock (v1.20+). |
| **Vertex** | GCP credentials | Gemini + Claude on GCP Vertex AI (v1.20+). |
| **Local** | `ollama` / LM Studio / llama.cpp on your machine | Zero cost, offline (v1.14+). |

Need one that isn't here? Bring your own with [`Provider.create`](#custom-providers).

## Inspect a model offline

`@theokit/sdk/models` is a **pure, offline** catalog — no key, no network — useful for
UIs and pre-flight checks.

| Helper | Returns |
| --- | --- |
| `resolveModelCapabilities(id)` | `{ supportsVision, supportsToolUse, supportsStructuredOutput, supportsCacheControl, maxContextTokens, maxOutputTokens }` |
| `parseModelId(id)` | `{ provider, name }` |
| `humanizeModelName(id)` | a human label, e.g. `"Claude 3 5 Sonnet"` |
| `toModelOption(id)` | `{ value, label, provider }` for a `<Select>` |

Unknown ids get conservative defaults (never throws). Pair `maxContextTokens` with
[`shouldCompact`](/theokit/sessions) for a pre-call compaction decision.

## Custom providers

Every provider is a plugin. `Provider.create(profile)` registers your own LLM behind
the same `Agent.create({ model })` surface — mirroring `Tool.create` and `Plugin.create`.

## Next

- [Use a model](/theokit/providers-models/use-a-model) — a runnable example: inspect a
  model offline, then run an agent with it.

## Reference

- [`ModelSelection`](/theokit/reference/ModelSelection) · [`ProviderProfile`](/theokit/reference/ProviderProfile) · [`ProviderRoute`](/theokit/reference/ProviderRoute)

---

# Use a model

Source: https://docs.usetheo.dev/theokit/providers-models/use-a-model

Inspect a model id offline, then run an agent with the model of your choice.

# Use a model

Pick a model by id, inspect its capabilities offline (no key), then run an agent with it.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";
import { humanizeModelName, parseModelId, resolveModelCapabilities } from "@theokit/sdk/models";

const apiKey = process.env.OPENROUTER_API_KEY;

// 1. Inspect any model id — offline, pure, no network.
const inspectId = "anthropic/claude-3-5-sonnet";
const { provider, name } = parseModelId(inspectId);
const caps = resolveModelCapabilities(inspectId);
console.log(`Inspect:  ${humanizeModelName(inspectId)}`);
console.log(`Provider: ${provider}  ·  name: ${name}`);
console.log(`Context:  ${caps.maxContextTokens} tokens  ·  tools: ${caps.supportsToolUse}  ·  vision: ${caps.supportsVision}`);

// 2. Run an agent. The `vendor/model` id + your key route to the provider
//    (here OpenRouter routes `openai/…`).
const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You are concise.",
});
const result = await (await agent.send("Name three popular LLM providers, comma-separated.")).wait();
console.log(`\nReply:    ${result.result}`);

await agent.dispose();
```

## Run

```bash
export OPENROUTER_API_KEY=sk-or-...   # https://openrouter.ai/keys
npm install @theokit/sdk zod
npx tsx run.ts
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter (the capability lookup is
offline and deterministic):

```text
Inspect:  Claude 3 5 Sonnet
Provider: anthropic  ·  name: claude-3-5-sonnet
Context:  200000 tokens  ·  tools: true  ·  vision: true

Reply:    OpenAI, Anthropic, Google AI
```

_The agent reply is model-generated, so yours will read differently. Click **Run** above for a fresh one._

## What it shows

- `parseModelId` / `humanizeModelName` / `resolveModelCapabilities` from
  `@theokit/sdk/models` — **offline**, no key, no network.
- `model: { id: "openai/gpt-4o-mini" }` — the id + key select the provider;
  swap the id (e.g. `anthropic/claude-3-5-sonnet`) to switch models with no other change.

## Example

Full runnable source:
[`examples/providers-models`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/providers-models).

---

# Quickstart

Source: https://docs.usetheo.dev/theokit/quickstart

Install the SDK, set a provider key, and run your first agent in about two minutes.

# Quickstart

Build an agent in code with `@theokit/sdk`. Three steps: install, set a key, run.

## 1. Install

```bash
npm install @theokit/sdk zod
```

## 2. Set a provider key

Any provider works — the model is chosen by the `model` id you pass. Here we use a
free model on [OpenRouter](https://openrouter.ai/keys).

```bash
export OPENROUTER_API_KEY=sk-or-...
```

## 3. Run an agent

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You are a concise assistant.",
});

const run = await agent.send("What is an AI agent? Answer for a developer.");
console.log((await run.wait()).result);

await agent.dispose();
```

```bash
npx tsx run.ts
```

## Where to next

---

# Reasoning

Source: https://docs.usetheo.dev/theokit/reasoning

Make an agent think before answering — native reasoning models, reasoning tools, or the reasoning:true flag.

# Reasoning

Three ways to make an agent reason before it answers. Native models reason internally; the other two
add explicit structure to any model.

| Approach | What | Best for |
| --- | --- | --- |
| **Native reasoning models** | `model.params: [{ id: "thinking", value: "high" }]` — the model reasons internally; the trace streams as `thinking` deltas + `usage.reasoningTokens`. | Models that support it (Claude extended thinking, Gemini thinking, o-series, DeepSeek-R1). |
| **Reasoning tools** | `ReasoningTools.create()` → a `think` + `analyze` scratchpad (no side effects — they echo structured reasoning back as an observation). Add to `tools: [...]`. | Any model; explicit, visible reasoning steps. |
| **`reasoning: true`** | A flag that prepends a chain-of-thought preamble AND auto-attaches the reasoning tools, using the SAME model. | Turning a non-reasoning model into a reason→act→observe loop. |

## `reasoning: true`

```ts
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" }, // a non-reasoning model
  reasoning: true,                      // CoT preamble + think/analyze auto-attached
});

const run = await agent.send("Which is bigger: 9.11 or 9.9? Think it through, then answer.");
// → the model calls `think`, reasons about magnitude, and answers 9.9 (a trap it often fails without reasoning)
```

Default **off** — byte-identical behaviour when unset. It reuses the existing tool loop; no new
runtime, no new dependency.

## Reasoning tools (explicit)

```ts
import { Agent } from "@theokit/sdk";
import { ReasoningTools } from "@theokit/sdk-tools";
// or: import { ReasoningTools } from "@theokit/sdk-tools";

const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  tools: [...ReasoningTools.create()], // think + analyze (pass { analyze: false } for think only)
});
```

- `think` — input `{ thought }`; the model works through one step out loud.
- `analyze` — input `{ result, analysis, next_action: "continue" | "validate" | "final_answer" }`;
  review a prior result and decide the next step.

## Native reasoning wins (no double-reasoning)

If a **native reasoning model** is configured (`model.params` carries a
`thinking`/`reasoning`/`reasoning_effort` id) and you also set `reasoning: true`, the flag is
**inert** and emits a one-time warning — the native reasoning takes over, so the two never stack. For
a native reasoning model, use `model.params` directly.

## Try it

The runnable [`examples/reasoning`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/reasoning)
proves this against a real LLM: `reasoning: true` drives the `think` tool and answers the 9.11/9.9
trap correctly.

---

# __resetSnapshotStoresForTests

Source: https://docs.usetheo.dev/theokit/reference/__resetSnapshotStoresForTests

_No description available._

# `__resetSnapshotStoresForTests`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function __resetSnapshotStoresForTests(): void
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/workflow/snapshot-store.ts:163`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/workflow/snapshot-store.ts#L163)

---

# A2AMessage

Source: https://docs.usetheo.dev/theokit/reference/A2AMessage

_No description available._

# `A2AMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface A2AMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/types.ts:8`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/types.ts#L8)

---

# ActiveMemoryPassArgs

Source: https://docs.usetheo.dev/theokit/reference/ActiveMemoryPassArgs

Arguments for `MemoryProvider.runActivePass(...)`.

# `ActiveMemoryPassArgs`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Arguments for `MemoryProvider.runActivePass(...)`.

## Signature

```ts
interface ActiveMemoryPassArgs { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider.ts#L46)

---

# ActiveMemoryPassResult

Source: https://docs.usetheo.dev/theokit/reference/ActiveMemoryPassResult

Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call.

# `ActiveMemoryPassResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the LLM call.

## Signature

```ts
interface ActiveMemoryPassResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider.ts:36`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider.ts#L36)

---

# Agent

Source: https://docs.usetheo.dev/theokit/reference/Agent

Static façade for creating and managing Theo agents.

# `Agent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Static façade for creating and managing Theo agents.

## Signature

```ts
class Agent {
  archive(...): ...
  batch(...): ...
  builder(...): ...
  create(...): ...
  delete(...): ...
  generateObject(...): ...
  get(...): ...
  getOrCreate(...): ...
  getRun(...): ...
  list(...): ...
  listRuns(...): ...
  prompt(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/agent.ts:65`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/agent.ts#L65)

---

# AgentBuilder

Source: https://docs.usetheo.dev/theokit/reference/AgentBuilder

Fluent builder for AgentOptions. Chainable setters mutate internal

# `AgentBuilder`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Fluent builder for AgentOptions. Chainable setters mutate internal
state and return `this`. Three terminals:

- `.build()` — synchronous snapshot (shallow clone) of accumulated options.
- `.create()` — calls the injected `create` (Agent.create).
- `.getOrCreate(agentId)` — calls the injected `getOrCreate` (Agent.getOrCreate).

Validation runs inside the terminals via `validateAgentOptions`. See ADR D25.

## Signature

```ts
class AgentBuilder {
  agentId(...): ...
  agents(...): ...
  apiKey(...): ...
  build(...): ...
  cloud(...): ...
  context(...): ...
  create(...): ...
  getOrCreate(...): ...
  local(...): ...
  mcpServers(...): ...
  memory(...): ...
  model(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/agent-builder.ts:41`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/agent-builder.ts#L41)

---

# AgentConversationTurn

Source: https://docs.usetheo.dev/theokit/reference/AgentConversationTurn

Agent turn: user message + assistant/tool/thinking steps.

# `AgentConversationTurn`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Agent turn: user message + assistant/tool/thinking steps.

## Signature

```ts
interface AgentConversationTurn { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:82`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L82)

---

# AgentDefinition

Source: https://docs.usetheo.dev/theokit/reference/AgentDefinition

Subagent definition. The parent agent spawns these via its Agent tool.

# `AgentDefinition`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Subagent definition. The parent agent spawns these via its Agent tool.

## Signature

```ts
interface AgentDefinition { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:85`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L85)

---

# AgentDisposedError

Source: https://docs.usetheo.dev/theokit/reference/AgentDisposedError

T1.6 — Thrown when a consumer calls `agent.send()` or any method

# `AgentDisposedError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

T1.6 — Thrown when a consumer calls `agent.send()` or any method
on an agent that has already been `dispose()`d. Pre-T1.6 this was
a generic `new Error("Agent has been disposed")` — consumers
couldn't catch it without string-matching the message.

## Signature

```ts
class AgentDisposedError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:670`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L670)

---

# AgentFactory

Source: https://docs.usetheo.dev/theokit/reference/AgentFactory

SE36 — `AgentFactory.create` replaces `createAgentFactory` (ADR 0015). Merges with the `AgentFactory` interface.

# `AgentFactory`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `AgentFactory.create` replaces `createAgentFactory` (ADR 0015). Merges with the `AgentFactory` interface.

## Signature

```ts
class AgentFactory {
  forSession(...): ...
  getOrCreate(...): ...
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/agent-factory.ts:10`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/agent-factory.ts#L10)

---

# AgentMailbox

Source: https://docs.usetheo.dev/theokit/reference/AgentMailbox

_No description available._

# `AgentMailbox`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class AgentMailbox {
  dispose(...): ...
  onMessage(...): ...
  request(...): ...
  send(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/a2a/agent-mailbox.ts:13`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/agent-mailbox.ts#L13)

---

# AgentMemory

Source: https://docs.usetheo.dev/theokit/reference/AgentMemory

Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever

# `AgentMemory`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
memory adapter(s) are registered via `Agent.create({ plugins: [...] })`.

## Signature

```ts
interface AgentMemory { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:177`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L177)

---

# AgentOperationOptions

Source: https://docs.usetheo.dev/theokit/reference/AgentOperationOptions

Options for archive/unarchive/delete.

# `AgentOperationOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for archive/unarchive/delete.

## Signature

```ts
interface AgentOperationOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:986`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L986)

---

# AgentOptions

Source: https://docs.usetheo.dev/theokit/reference/AgentOptions

Top-level options accepted by `Agent.create()`.

# `AgentOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Top-level options accepted by `Agent.create()`.

Pass either `local` or `cloud` to pick a runtime.

## Signature

```ts
interface AgentOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:374`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L374)

---

# AgentPromptResult

Source: https://docs.usetheo.dev/theokit/reference/AgentPromptResult

Result of a one-shot Agent.prompt call.

# `AgentPromptResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of a one-shot Agent.prompt call.

## Signature

```ts
type AgentPromptResult = RunResult;
```

## Kind

`type`

## Source

[`packages/sdk/src/agent.ts:58`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/agent.ts#L58)

---

# AgentRegistryOptions

Source: https://docs.usetheo.dev/theokit/reference/AgentRegistryOptions

_No description available._

# `AgentRegistryOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface AgentRegistryOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/registry/live-agent-registry.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/registry/live-agent-registry.ts#L25)

---

# AgentRunError

Source: https://docs.usetheo.dev/theokit/reference/AgentRunError

Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when

# `AgentRunError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when
the option `{ throwOnError: true }` is set and the run terminates with
`status: 'error'`. Carries the structured `RunResult.error` fields so
callers can `catch` once and branch on `code` / `provider` instead of
unwrapping the run.

Extends TheokitAgentError per ADR D65 — no new hierarchy.

## Signature

```ts
class AgentRunError {
  toJSON(...): ...
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:295`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L295)

---

# AgentRunErrorCode

Source: https://docs.usetheo.dev/theokit/reference/AgentRunErrorCode

Back-compat alias of KnownAgentRunErrorCode. Pre-T1.1 callers that

# `AgentRunErrorCode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Back-compat alias of KnownAgentRunErrorCode. Pre-T1.1 callers that
imported `AgentRunErrorCode` keep working; new code SHOULD prefer
`KnownAgentRunErrorCode` to make the closed-union intent explicit.

## Signature

```ts
type AgentRunErrorCode = KnownAgentRunErrorCode;
```

## Kind

`type`

## Source

[`packages/sdk/src/errors.ts:73`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L73)

---

# agentStep

Source: https://docs.usetheo.dev/theokit/reference/agentStep

_No description available._

# `agentStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function agentStep(id: string, agent: SDKAgent, promptTemplate: unknown, opts: unknown): AgentStep
```

## Kind

`function`

## Source

[`packages/sdk/src/workflow.ts:358`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L358)

---

# AgentStep

Source: https://docs.usetheo.dev/theokit/reference/AgentStep

An agent.send-driven step.

# `AgentStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

An agent.send-driven step.

## Signature

```ts
interface AgentStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:42`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L42)

---

# appendJsonl

Source: https://docs.usetheo.dev/theokit/reference/appendJsonl

_No description available._

# `appendJsonl`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function appendJsonl(path: string, record: unknown): void
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/persistence/jsonl.ts:86`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/jsonl.ts#L86)

---

# applyMode

Source: https://docs.usetheo.dev/theokit/reference/applyMode

_No description available._

# `applyMode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction
```

## Kind

`function`

## Source

[`packages/sdk/src/permission-engine.ts:45`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-engine.ts#L45)

---

# AssistantMessage

Source: https://docs.usetheo.dev/theokit/reference/AssistantMessage

Plain assistant message in a conversation history.

# `AssistantMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Plain assistant message in a conversation history.

## Signature

```ts
interface AssistantMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:15`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L15)

---

# assistantText

Source: https://docs.usetheo.dev/theokit/reference/assistantText

_No description available._

# `assistantText`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function assistantText(msg: SDKMessage): string
```

## Kind

`function`

## Source

[`packages/sdk/src/messages.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/messages.ts#L20)

---

# AsyncSemaphore

Source: https://docs.usetheo.dev/theokit/reference/AsyncSemaphore

_No description available._

# `AsyncSemaphore`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface AsyncSemaphore { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/concurrency/async-semaphore.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/concurrency/async-semaphore.ts#L19)

---

# Auth

Source: https://docs.usetheo.dev/theokit/reference/Auth

SE36 — `Auth.create` replaces `defineAuth` (ADR 0015).

# `Auth`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Auth.create` replaces `defineAuth` (ADR 0015).

## Signature

```ts
class Auth {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/server/auth/orchestrator.ts:247`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/orchestrator.ts#L247)

---

# AuthCallbackError

Source: https://docs.usetheo.dev/theokit/reference/AuthCallbackError

Thrown during OAuth callback handling for state mismatches, expired

# `AuthCallbackError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown during OAuth callback handling for state mismatches, expired
transactions, missing query params, or provider 4xx/5xx errors.

Typed `code` field lets consumers branch on cause:
  - 'oauth_transaction_expired' — cookie tx > 10min old (per ADR D5)
  - 'oauth_state_mismatch' — query state ≠ cookie state (CSRF defense per RFC 6749 §10.12)
  - 'oauth_provider_error' — non-access_denied error in callback URL
  - 'oauth_token_exchange_failed' — provider rejected code-for-tokens swap
  - 'oauth_userinfo_failed' — userinfo endpoint returned error
  - 'oauth_missing_code_or_state' — required query params absent

## Signature

```ts
class AuthCallbackError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/server/auth/errors.ts:49`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/errors.ts#L49)

---

# AuthCancelledError

Source: https://docs.usetheo.dev/theokit/reference/AuthCancelledError

Per v1.1 EC-1 MUST FIX — typed subclass of AuthCallbackError for the

# `AuthCancelledError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per v1.1 EC-1 MUST FIX — typed subclass of AuthCallbackError for the
specific case where user declined consent at provider screen.

OAuth 2.0 RFC 6749 §4.1.2.1: provider redirects with `?error=access_denied`.
Apps can catch this distinctly from network/server errors to render
"Login cancelled — try again" UX instead of opaque "callback failed".

## Signature

```ts
class AuthCancelledError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/server/auth/errors.ts:67`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/errors.ts#L67)

---

# AuthConfigError

Source: https://docs.usetheo.dev/theokit/reference/AuthConfigError

Thrown at `defineAuth()` time when configuration is invalid

# `AuthConfigError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown at `defineAuth()` time when configuration is invalid
(e.g., duplicate provider name, invalid email shape per EC-V1-12).

## Signature

```ts
class AuthConfigError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/server/auth/errors.ts:11`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/errors.ts#L11)

---

# AuthenticationError

Source: https://docs.usetheo.dev/theokit/reference/AuthenticationError

Invalid API key, not logged in, insufficient permissions.

# `AuthenticationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Invalid API key, not logged in, insufficient permissions.

## Signature

```ts
class AuthenticationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:173`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L173)

---

# AuthOrchestrator

Source: https://docs.usetheo.dev/theokit/reference/AuthOrchestrator

Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.

# `AuthOrchestrator`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.

- startSignIn: returns Response.redirect to provider authorization URL with state cookie
- finishSignIn: handles provider callback; verifies state; calls onSignIn; rotates session ID
  (OWASP A07:2021 per EC-10); creates session cookie; clears transaction cookie
- signIn: Caminho A escape hatch — skip OAuth flow; directly persist session from external profile
- signOut: destroys session cookie + invokes onSignOut callback
- getSession: read-only passthrough to session.getSession

## Signature

```ts
interface AuthOrchestrator { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/server/auth/types.ts:84`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/types.ts#L84)

---

# AuthProvider

Source: https://docs.usetheo.dev/theokit/reference/AuthProvider

Provider contract — each @theokit/auth-* package implements this.

# `AuthProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Provider contract — each @theokit/auth-* package implements this.
Per blueprint Q5 + ADR D11 (adapters layer).

## Signature

```ts
interface AuthProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/server/auth/types.ts:56`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/types.ts#L56)

---

# AuthProviderNotFoundError

Source: https://docs.usetheo.dev/theokit/reference/AuthProviderNotFoundError

Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`

# `AuthProviderNotFoundError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`
when the named provider is not registered in `providers[]`.

## Signature

```ts
class AuthProviderNotFoundError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/server/auth/errors.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/errors.ts#L25)

---

# AuthResult

Source: https://docs.usetheo.dev/theokit/reference/AuthResult

Per ADR D9 — provider profile types are provider-specific (not unified).

# `AuthResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per ADR D9 — provider profile types are provider-specific (not unified).
Each @theokit/auth-* package exports its own profile shape.
Generic param TProfile lets consumers narrow via discriminated unions on providerName.

## Signature

```ts
interface AuthResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/server/auth/types.ts:41`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/types.ts#L41)

---

# AuthSecretTooShortError

Source: https://docs.usetheo.dev/theokit/reference/AuthSecretTooShortError

T5.1 — Typed error thrown when an OAuth tx-cookie secret has < 32

# `AuthSecretTooShortError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

T5.1 — Typed error thrown when an OAuth tx-cookie secret has < 32
bytes of entropy. Surfaces the actual byte length so operators can
diagnose mis-configured env vars without leaking the secret itself.

## Signature

```ts
class AuthSecretTooShortError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/server/auth/oauth-transaction-store.ts:85`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/oauth-transaction-store.ts#L85)

---

# BatchItem

Source: https://docs.usetheo.dev/theokit/reference/BatchItem

Single prompt in a batch. Plain string is shorthand for `{ prompt }`.

# `BatchItem`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Single prompt in a batch. Plain string is shorthand for `{ prompt }`.

## Signature

```ts
interface BatchItem { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/batch.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/batch.ts#L20)

---

# BatchOptions

Source: https://docs.usetheo.dev/theokit/reference/BatchOptions

Options accepted by `Agent.batch`. Extends `AgentOptions` — every

# `BatchOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options accepted by `Agent.batch`. Extends `AgentOptions` — every
prompt gets an agent created with these options (ADR D138 isolation),
plus the batch-specific knobs below.

## Signature

```ts
interface BatchOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/batch.ts:39`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/batch.ts#L39)

---

# BatchProgress

Source: https://docs.usetheo.dev/theokit/reference/BatchProgress

Live progress snapshot delivered to `onProgress`.

# `BatchProgress`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Live progress snapshot delivered to `onProgress`.

## Signature

```ts
interface BatchProgress { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/batch.ts:110`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/batch.ts#L110)

---

# BatchResult

Source: https://docs.usetheo.dev/theokit/reference/BatchResult

Per-prompt outcome. Discriminated union — check `ok` before reading

# `BatchResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-prompt outcome. Discriminated union — check `ok` before reading
`result` or `error`.

## Signature

```ts
type BatchResult
```

## Kind

`type`

## Source

[`packages/sdk/src/types/batch.ts:87`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/batch.ts#L87)

---

# BranchStep

Source: https://docs.usetheo.dev/theokit/reference/BranchStep

First-match-wins predicates + optional fallback.

# `BranchStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

First-match-wins predicates + optional fallback.

## Signature

```ts
interface BranchStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:66`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L66)

---

# Budget

Source: https://docs.usetheo.dev/theokit/reference/Budget

_No description available._

# `Budget`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class Budget {
  create(...): ...
  delete(...): ...
  get(...): ...
  list(...): ...
  snapshot(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/budget.ts:58`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/budget.ts#L58)

---

# BudgetCheck

Source: https://docs.usetheo.dev/theokit/reference/BudgetCheck

Decision the tracker returns on each iteration / pre-flight check.

# `BudgetCheck`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Decision the tracker returns on each iteration / pre-flight check.

## Signature

```ts
interface BudgetCheck { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/budget/budget-tracker.ts:36`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/budget/budget-tracker.ts#L36)

---

# BudgetExceededError

Source: https://docs.usetheo.dev/theokit/reference/BudgetExceededError

Thrown by `Budget` enforcement (ADR D386) when a `mode: 'block'`

# `BudgetExceededError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown by `Budget` enforcement (ADR D386) when a `mode: "block"`
budget would be exceeded by the upcoming LLM call. Caller pega
tipado para retry-after-window-reset or surface to the user.

## Signature

```ts
class BudgetExceededError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:624`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L624)

---

# BudgetExceedEvent

Source: https://docs.usetheo.dev/theokit/reference/BudgetExceedEvent

Exceed event emitted at 100% across all modes.

# `BudgetExceedEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Exceed event emitted at 100% across all modes.

## Signature

```ts
interface BudgetExceedEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/budget.ts:48`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L48)

---

# BudgetHandle

Source: https://docs.usetheo.dev/theokit/reference/BudgetHandle

Returned by `Budget.create` and `Budget.get` — read-only view.

# `BudgetHandle`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Returned by `Budget.create` and `Budget.get` — read-only view.

## Signature

```ts
interface BudgetHandle { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/budget.ts:79`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L79)

---

# BudgetLimit

Source: https://docs.usetheo.dev/theokit/reference/BudgetLimit

A single limit; stacked in an array (D384, ANY exceeded blocks).

# `BudgetLimit`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A single limit; stacked in an array (D384, ANY exceeded blocks).

## Signature

```ts
interface BudgetLimit { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/budget.ts:33`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L33)

---

# BudgetMode

Source: https://docs.usetheo.dev/theokit/reference/BudgetMode

Enforcement mode (D383).

# `BudgetMode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Enforcement mode (D383).
- `audit`: log only, never throw, never block.
- `warn`: callbacks fire at 80/95/100% thresholds; no throw.
- `block`: preflightCheck throws `BudgetExceededError` BEFORE LLM call
  when would-exceed.

## Signature

```ts
type BudgetMode
```

## Kind

`type`

## Source

[`packages/sdk/src/types/budget.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L30)

---

# BudgetOptions

Source: https://docs.usetheo.dev/theokit/reference/BudgetOptions

Options for `Budget.create`.

# `BudgetOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Budget.create`.

## Signature

```ts
interface BudgetOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/budget.ts:57`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L57)

---

# BudgetScope

Source: https://docs.usetheo.dev/theokit/reference/BudgetScope

Scope of a budget — where the charge is attributed. v1 supports

# `BudgetScope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Scope of a budget — where the charge is attributed. v1 supports
`process` (shared global) only; `agent` and `call` reserved for
v0.2 multi-tenant scenarios.

## Signature

```ts
type BudgetScope
```

## Kind

`type`

## Source

[`packages/sdk/src/types/budget.ts:13`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L13)

---

# BudgetSnapshot

Source: https://docs.usetheo.dev/theokit/reference/BudgetSnapshot

Per-window snapshot returned by `Budget.snapshot()`.

# `BudgetSnapshot`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-window snapshot returned by `Budget.snapshot()`.

## Signature

```ts
interface BudgetSnapshot { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/budget.ts:91`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L91)

---

# BudgetThresholdEvent

Source: https://docs.usetheo.dev/theokit/reference/BudgetThresholdEvent

Threshold event emitted at 80% and 95% in `warn` and `block` modes.

# `BudgetThresholdEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Threshold event emitted at 80% and 95% in `warn` and `block` modes.

## Signature

```ts
interface BudgetThresholdEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/budget.ts:39`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L39)

---

# BudgetTotal

Source: https://docs.usetheo.dev/theokit/reference/BudgetTotal

Aggregate snapshot of usage so far.

# `BudgetTotal`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Aggregate snapshot of usage so far.

## Signature

```ts
interface BudgetTotal { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/budget/budget-tracker.ts:49`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/budget/budget-tracker.ts#L49)

---

# BudgetTracker

Source: https://docs.usetheo.dev/theokit/reference/BudgetTracker

The kernel-facing contract. Implementations live OUTSIDE the agent loop

# `BudgetTracker`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The kernel-facing contract. Implementations live OUTSIDE the agent loop
(in `@theokit/sdk-budget` after Phase 2 / in `internal/budget/` until then).

Implementations MUST be:
  - **Synchronous** — every method returns a value, never a Promise.
    `track()` is on the hot path (called on every iteration); async would
    bloat the loop with floating promises and force every call site to
    await.
  - **Non-throwing in track()** — record-only semantics. Validation
    failures bubble up via `check()` instead.

## Signature

```ts
interface BudgetTracker { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/budget/budget-tracker.ts:70`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/budget/budget-tracker.ts#L70)

---

# BudgetUsageEvent

Source: https://docs.usetheo.dev/theokit/reference/BudgetUsageEvent

Single usage event recorded during one LLM call.

# `BudgetUsageEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Single usage event recorded during one LLM call.

## Signature

```ts
interface BudgetUsageEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/budget/budget-tracker.ts:24`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/budget/budget-tracker.ts#L24)

---

# BudgetWindow

Source: https://docs.usetheo.dev/theokit/reference/BudgetWindow

Time window for a budget limit (D382 — UTC calendar-aligned).

# `BudgetWindow`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Time window for a budget limit (D382 — UTC calendar-aligned).
- `1h` is relative (last 60 minutes).
- `1d` / `1w` / `30d` / `365d` are aligned to UTC calendar
  boundaries (UTC midnight / monday 00:00 UTC / 1st 00:00 UTC).

## Signature

```ts
type BudgetWindow
```

## Kind

`type`

## Source

[`packages/sdk/src/types/budget.ts:21`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/budget.ts#L21)

---

# buildCheckpoint

Source: https://docs.usetheo.dev/theokit/reference/buildCheckpoint

_No description available._

# `buildCheckpoint`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function buildCheckpoint(label: string, marker: string): CompressibleMessage
```

## Kind

`function`

## Source

[`packages/sdk/src/compaction.ts:209`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L209)

---

# buildSkillsBlock

Source: https://docs.usetheo.dev/theokit/reference/buildSkillsBlock

_No description available._

# `buildSkillsBlock`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function buildSkillsBlock(skills: unknown): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/skills/skills-block.ts:17`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/skills/skills-block.ts#L17)

---

# captureArtifact

Source: https://docs.usetheo.dev/theokit/reference/captureArtifact

_No description available._

# `captureArtifact`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function captureArtifact(sandbox: SandboxBackend, repoDir: string): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/eval/code-runner.ts:31`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/eval/code-runner.ts#L31)

---

# chargeAndCheckThresholds

Source: https://docs.usetheo.dev/theokit/reference/chargeAndCheckThresholds

_No description available._

# `chargeAndCheckThresholds`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function chargeAndCheckThresholds(name: string, actualUsd: number): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/budget/enforcement.ts:58`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/enforcement.ts#L58)

---

# CHECKPOINT_MARKER

Source: https://docs.usetheo.dev/theokit/reference/CHECKPOINT_MARKER

Sentinel prefix marking a conversation checkpoint turn. A visible, structured,

# `CHECKPOINT_MARKER`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Sentinel prefix marking a conversation checkpoint turn. A visible, structured,
prose-unlikely token (no invisible/control bytes — safe to persist and to read
in source). Only buildCheckpoint should produce content beginning with it.

## Signature

```ts
const CHECKPOINT_MARKER
```

## Kind

`constant`

## Source

[`packages/sdk/src/compaction.ts:36`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L36)

---

# ClientOptions

Source: https://docs.usetheo.dev/theokit/reference/ClientOptions

Client SDK types (T20.2, ADR D454).

# `ClientOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Client SDK types (T20.2, ADR D454).

## Signature

```ts
interface ClientOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/client/types.ts:8`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/client/types.ts#L8)

---

# cloneWorkflow

Source: https://docs.usetheo.dev/theokit/reference/cloneWorkflow

_No description available._

# `cloneWorkflow`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function cloneWorkflow(wf: Workflow, opts: unknown): Workflow
```

## Kind

`function`

## Source

[`packages/sdk/src/workflow.ts:412`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L412)

---

# CloudEnv

Source: https://docs.usetheo.dev/theokit/reference/CloudEnv

Cloud execution environment.

# `CloudEnv`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Cloud execution environment.

## Signature

```ts
interface CloudEnv { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:57`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L57)

---

# CloudOptions

Source: https://docs.usetheo.dev/theokit/reference/CloudOptions

Cloud agent configuration.

# `CloudOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Cloud agent configuration.

## Signature

```ts
interface CloudOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:67`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L67)

---

# CloudRepo

Source: https://docs.usetheo.dev/theokit/reference/CloudRepo

Repo to clone into a cloud agent's VM.

# `CloudRepo`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Repo to clone into a cloud agent's VM.

## Signature

```ts
interface CloudRepo { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L46)

---

# compactTranscript

Source: https://docs.usetheo.dev/theokit/reference/compactTranscript

_No description available._

# `compactTranscript`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function compactTranscript(messages: unknown, options: CompactTranscriptOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/compaction.ts:176`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L176)

---

# CompactTranscriptOptions

Source: https://docs.usetheo.dev/theokit/reference/CompactTranscriptOptions

Options for compactTranscript.

# `CompactTranscriptOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for compactTranscript.

## Signature

```ts
interface CompactTranscriptOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/compaction.ts:123`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L123)

---

# CompletionCheck

Source: https://docs.usetheo.dev/theokit/reference/CompletionCheck

SE34 — the per-send completion criterion (see SendOptions.completionCheck).

# `CompletionCheck`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE34 — the per-send completion criterion (see SendOptions.completionCheck).

## Signature

```ts
interface CompletionCheck { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:493`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L493)

---

# CompletionCheckResult

Source: https://docs.usetheo.dev/theokit/reference/CompletionCheckResult

SE34 — the resolved per-send completion verdict (see RunResult.completionCheck).

# `CompletionCheckResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE34 — the resolved per-send completion verdict (see RunResult.completionCheck).

## Signature

```ts
interface CompletionCheckResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:507`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L507)

---

# computeCost

Source: https://docs.usetheo.dev/theokit/reference/computeCost

_No description available._

# `computeCost`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function computeCost(args: ComputeArgs): CostBreakdown
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/budget/compute-cost.ts:57`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/compute-cost.ts#L57)

---

# ConfigurationError

Source: https://docs.usetheo.dev/theokit/reference/ConfigurationError

Invalid model, bad request parameters, malformed options.

# `ConfigurationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Invalid model, bad request parameters, malformed options.

## Signature

```ts
class ConfigurationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:205`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L205)

---

# ContextBudget

Source: https://docs.usetheo.dev/theokit/reference/ContextBudget

Token budget used by the context manager for a single agent.

# `ContextBudget`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Token budget used by the context manager for a single agent.

## Signature

```ts
interface ContextBudget { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/context.ts:69`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L69)

---

# ContextManagerKind

Source: https://docs.usetheo.dev/theokit/reference/ContextManagerKind

Context manager backend.

# `ContextManagerKind`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context manager backend.

- `"file"` — Read `.theokit/context.json` from the workspace (local) or the
  cloned repo (cloud).

## Signature

```ts
type ContextManagerKind
```

## Kind

`type`

## Source

[`packages/sdk/src/types/context.ts:9`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L9)

---

# ContextSettings

Source: https://docs.usetheo.dev/theokit/reference/ContextSettings

Context configuration accepted by `Agent.create()` via AgentOptions.context.

# `ContextSettings`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context configuration accepted by `Agent.create()` via AgentOptions.context.

## Signature

```ts
interface ContextSettings { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/context.ts:16`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L16)

---

# ContextSnapshot

Source: https://docs.usetheo.dev/theokit/reference/ContextSnapshot

Result of `agent.context.snapshot()`. Public and secret-free by design — safe

# `ContextSnapshot`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of `agent.context.snapshot()`. Public and secret-free by design — safe
to log and persist. Raw secrets, local absolute paths, and exact token values
are never present.

## Signature

```ts
interface ContextSnapshot { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/context.ts:85`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L85)

---

# ContextSource

Source: https://docs.usetheo.dev/theokit/reference/ContextSource

A single context source resolved by the context manager.

# `ContextSource`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A single context source resolved by the context manager.

## Signature

```ts
interface ContextSource { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/context.ts:53`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L53)

---

# ContextSourceStatus

Source: https://docs.usetheo.dev/theokit/reference/ContextSourceStatus

Inclusion state of a single context source in a ContextSnapshot.

# `ContextSourceStatus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Inclusion state of a single context source in a ContextSnapshot.

## Signature

```ts
type ContextSourceStatus
```

## Kind

`type`

## Source

[`packages/sdk/src/types/context.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L46)

---

# ConversationStep

Source: https://docs.usetheo.dev/theokit/reference/ConversationStep

_No description available._

# `ConversationStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type ConversationStep
```

## Kind

`type`

## Source

[`packages/sdk/src/types/conversation.ts:71`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L71)

---

# ConversationTurn

Source: https://docs.usetheo.dev/theokit/reference/ConversationTurn

Structured per-turn view of a run.

# `ConversationTurn`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Structured per-turn view of a run.

## Signature

```ts
type ConversationTurn
```

## Kind

`type`

## Source

[`packages/sdk/src/types/conversation.ts:102`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L102)

---

# costAmountUsd

Source: https://docs.usetheo.dev/theokit/reference/costAmountUsd

_No description available._

# `costAmountUsd`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function costAmountUsd(cost: unknown): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/messages.ts:50`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/messages.ts#L50)

---

# CostBreakdown

Source: https://docs.usetheo.dev/theokit/reference/CostBreakdown

Cost breakdown attached to `RunResult.cost`. When `status === 'unknown'`,

# `CostBreakdown`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
`amountUsd` is `undefined` — DO NOT default to 0 (mentira). UI exibe
`n/a` para unknown, `~$1.23` para estimated, `$1.23` para actual.

## Signature

```ts
interface CostBreakdown { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/usage.ts:55`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/usage.ts#L55)

---

# CostSource

Source: https://docs.usetheo.dev/theokit/reference/CostSource

Source of the cost figure for caller-side audit.

# `CostSource`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Source of the cost figure for caller-side audit.

## Signature

```ts
type CostSource
```

## Kind

`type`

## Source

[`packages/sdk/src/types/usage.ts:43`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/usage.ts#L43)

---

# CostStatus

Source: https://docs.usetheo.dev/theokit/reference/CostStatus

Cost confidence level (D377).

# `CostStatus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Cost confidence level (D377).
- `actual`: returned by a provider billing API (e.g. OpenRouter `/generation`).
- `estimated`: computed from bundled pricing snapshot.
- `included`: subscription-included route (Codex CLI, Claude Pro).
- `unknown`: pricing data unavailable; `amountUsd` is undefined.

## Signature

```ts
type CostStatus
```

## Kind

`type`

## Source

[`packages/sdk/src/types/usage.ts:40`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/usage.ts#L40)

---

# CounterBudgetTrackerOptions

Source: https://docs.usetheo.dev/theokit/reference/CounterBudgetTrackerOptions

Options for `createCounterBudgetTracker`.

# `CounterBudgetTrackerOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `createCounterBudgetTracker`.

## Signature

```ts
interface CounterBudgetTrackerOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/budget/budget-tracker-counter.ts:26`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/budget/budget-tracker-counter.ts#L26)

---

# createCounterBudgetTracker

Source: https://docs.usetheo.dev/theokit/reference/createCounterBudgetTracker

_No description available._

# `createCounterBudgetTracker`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function createCounterBudgetTracker(options: CounterBudgetTrackerOptions): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/budget/budget-tracker-counter.ts:42`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/budget/budget-tracker-counter.ts#L42)

---

# CreateSkillSpec

Source: https://docs.usetheo.dev/theokit/reference/CreateSkillSpec

Spec accepted by createSkill.

# `CreateSkillSpec`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Spec accepted by createSkill.

## Signature

```ts
interface CreateSkillSpec { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/create-skill.ts:26`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/create-skill.ts#L26)

---

# CredentialPoolExhaustedError

Source: https://docs.usetheo.dev/theokit/reference/CredentialPoolExhaustedError

Thrown when every credential in a per-provider pool is in cooldown

# `CredentialPoolExhaustedError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when every credential in a per-provider pool is in cooldown
and no healthy key is available (ADR D133). The caller's
import("./internal/llm/fallback-client.js").FallbackLlmClient
catches this and tries the next provider in the fallback chain.

`metadata.nextRetryAt` (epoch ms) tells callers when the soonest
pool entry resumes — useful for manual retry scheduling.

## Signature

```ts
class CredentialPoolExhaustedError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:486`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L486)

---

# Cron

Source: https://docs.usetheo.dev/theokit/reference/Cron

Static façade for scheduling Theo agent runs on a cron expression.

# `Cron`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Static façade for scheduling Theo agent runs on a cron expression.

## Signature

```ts
class Cron {
  create(...): ...
  delete(...): ...
  disable(...): ...
  enable(...): ...
  get(...): ...
  list(...): ...
  run(...): ...
  start(...): ...
  status(...): ...
  stop(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/cron.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/cron.ts#L46)

---

# CronCreateOptions

Source: https://docs.usetheo.dev/theokit/reference/CronCreateOptions

Options for `Cron.create()`.

# `CronCreateOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Cron.create()`.

Pass exactly ONE target: `agent` (ephemeral agent fresh per fire), `agentId`
(reuse an existing agent — preserves conversation context), or `workflow`
(SE35 — run a committed workflow per fire). Agent targets REQUIRE `message`;
a workflow target takes `inputData` and MUST NOT set `message`. Violations are
a `ConfigurationError`.

## Signature

```ts
interface CronCreateOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:80`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L80)

---

# CronGetOptions

Source: https://docs.usetheo.dev/theokit/reference/CronGetOptions

Options for `Cron.get()`.

# `CronGetOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Cron.get()`.

## Signature

```ts
interface CronGetOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:117`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L117)

---

# CronJob

Source: https://docs.usetheo.dev/theokit/reference/CronJob

Persistent cron-scheduled invocation of the Theo agent or a workflow.

# `CronJob`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Persistent cron-scheduled invocation of the Theo agent or a workflow.

Exactly one target is set: CronJob.agent (ephemeral agent created on
each fire), CronJob.agentId (bound to an existing agent for context
continuity), or CronJob.workflow (a committed workflow run per fire;
SE35). Agent targets carry a `message`; a workflow target carries `inputData`.

## Signature

```ts
interface CronJob { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L34)

---

# CronJobStatus

Source: https://docs.usetheo.dev/theokit/reference/CronJobStatus

Lifecycle state reported by `Cron.list()` / `Cron.get()`.

# `CronJobStatus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Lifecycle state reported by `Cron.list()` / `Cron.get()`.

## Signature

```ts
type CronJobStatus
```

## Kind

`type`

## Source

[`packages/sdk/src/types/cron.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L22)

---

# CronListOptions

Source: https://docs.usetheo.dev/theokit/reference/CronListOptions

Options for `Cron.list()`.

# `CronListOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Cron.list()`.

## Signature

```ts
type CronListOptions
```

## Kind

`type`

## Source

[`packages/sdk/src/types/cron.ts:103`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L103)

---

# CronOperationOptions

Source: https://docs.usetheo.dev/theokit/reference/CronOperationOptions

Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.

# `CronOperationOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.

## Signature

```ts
interface CronOperationOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:127`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L127)

---

# CronRunOptions

Source: https://docs.usetheo.dev/theokit/reference/CronRunOptions

Options for `Cron.run()` — manually trigger a job off-schedule.

# `CronRunOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Cron.run()` — manually trigger a job off-schedule.

## Signature

```ts
interface CronRunOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:137`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L137)

---

# CronRuntime

Source: https://docs.usetheo.dev/theokit/reference/CronRuntime

Runtime hosting a cron job. Mirrors the agent runtime split.

# `CronRuntime`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Runtime hosting a cron job. Mirrors the agent runtime split.

- `local` — the in-process scheduler activated via `Cron.start()` fires the
  job while the host process is alive.
- `cloud` — Theo PaaS schedules the job server-side; fires independent of
  any SDK process.

## Signature

```ts
type CronRuntime
```

## Kind

`type`

## Source

[`packages/sdk/src/types/cron.ts:15`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L15)

---

# CronSchedulerStatus

Source: https://docs.usetheo.dev/theokit/reference/CronSchedulerStatus

Snapshot of the local scheduler returned by `Cron.status()`.

# `CronSchedulerStatus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Snapshot of the local scheduler returned by `Cron.status()`.

## Signature

```ts
interface CronSchedulerStatus { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:160`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L160)

---

# CronStartOptions

Source: https://docs.usetheo.dev/theokit/reference/CronStartOptions

Options for `Cron.start()` — activates the in-process scheduler for local

# `CronStartOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Cron.start()` — activates the in-process scheduler for local
jobs.

## Signature

```ts
interface CronStartOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/cron.ts:148`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/cron.ts#L148)

---

# CustomTool

Source: https://docs.usetheo.dev/theokit/reference/CustomTool

Local function tool declared per-agent via AgentOptions.tools. The

# `CustomTool`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Local function tool declared per-agent via AgentOptions.tools. The
handler runs in-process; no MCP server is involved. The SDK serializes
`name`, `description`, and `inputSchema` into the model's tool catalog.

Handlers MUST be re-passed on `Agent.resume()` because closures cannot be
persisted. The tool catalog (name + description + schema) is NOT serialized.

## Signature

```ts
interface CustomTool { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent-prims.ts:64`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent-prims.ts#L64)

---

# Dataset

Source: https://docs.usetheo.dev/theokit/reference/Dataset

`Dataset` is either an array OR a factory returning a (sync or async)

# `Dataset`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`Dataset` is either an array OR a factory returning a (sync or async)
iterable (D210). The runner normalizes both shapes into an
`AsyncIterable<DatasetEntry>` internally.

## Signature

```ts
type Dataset
```

## Kind

`type`

## Source

[`packages/sdk/src/types/eval.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L30)

---

# DatasetEntry

Source: https://docs.usetheo.dev/theokit/reference/DatasetEntry

A single dataset row — input prompt + optional reference + free-form metadata.

# `DatasetEntry`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A single dataset row — input prompt + optional reference + free-form metadata.

## Signature

```ts
interface DatasetEntry { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L19)

---

# DeepPartial

Source: https://docs.usetheo.dev/theokit/reference/DeepPartial

Recursive partial — `T` where every nested field becomes optional.

# `DeepPartial`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Recursive partial — `T` where every nested field becomes optional.

## Signature

```ts
type DeepPartial
```

## Kind

`type`

## Source

[`packages/sdk/src/stream-object.ts:45`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/stream-object.ts#L45)

---

# DefineAuthOptions

Source: https://docs.usetheo.dev/theokit/reference/DefineAuthOptions

`defineAuth(opts)` configuration shape — Caminho C (Hybrid).

# `DefineAuthOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`defineAuth(opts)` configuration shape — Caminho C (Hybrid).
`providers` optional: empty = Caminho A escape hatch (manual signIn only).
`onSignIn` invoked after provider callback success; returns TSession to persist.

## Signature

```ts
interface DefineAuthOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/server/auth/types.ts:67`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/types.ts#L67)

---

# DefineProviderOptions

Source: https://docs.usetheo.dev/theokit/reference/DefineProviderOptions

Options for defineProvider.

# `DefineProviderOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for defineProvider.

## Signature

```ts
interface DefineProviderOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/define-provider.ts:9`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/define-provider.ts#L9)

---

# DefineSubscriptionOptions

Source: https://docs.usetheo.dev/theokit/reference/DefineSubscriptionOptions

Options accepted by defineSubscription.

# `DefineSubscriptionOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options accepted by defineSubscription.

## Signature

```ts
interface DefineSubscriptionOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/subscription/define-subscription.ts:16`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/define-subscription.ts#L16)

---

# DefineToolSpec

Source: https://docs.usetheo.dev/theokit/reference/DefineToolSpec

_No description available._

# `DefineToolSpec`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface DefineToolSpec { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/define-tool.ts:28`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/define-tool.ts#L28)

---

# DelegationCompleteContext

Source: https://docs.usetheo.dev/theokit/reference/DelegationCompleteContext

Context passed to SubAgentSpec.onDelegationComplete after the child settles.

# `DelegationCompleteContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to SubAgentSpec.onDelegationComplete after the child settles.

## Signature

```ts
interface DelegationCompleteContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/subagent.ts:101`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L101)

---

# DelegationCompleteDecision

Source: https://docs.usetheo.dev/theokit/reference/DelegationCompleteDecision

Decision returned from SubAgentSpec.onDelegationComplete.

# `DelegationCompleteDecision`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Decision returned from SubAgentSpec.onDelegationComplete.

## Signature

```ts
interface DelegationCompleteDecision { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/subagent.ts:121`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L121)

---

# DelegationStartContext

Source: https://docs.usetheo.dev/theokit/reference/DelegationStartContext

Context passed to SubAgentSpec.onDelegationStart before the child runs.

# `DelegationStartContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to SubAgentSpec.onDelegationStart before the child runs.

## Signature

```ts
interface DelegationStartContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/subagent.ts:75`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L75)

---

# DelegationStartDecision

Source: https://docs.usetheo.dev/theokit/reference/DelegationStartDecision

Decision returned from SubAgentSpec.onDelegationStart. Discriminated on

# `DelegationStartDecision`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Decision returned from SubAgentSpec.onDelegationStart. Discriminated on
`proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
(`modifiedInput`) cannot be mixed into one nonsensical object.

## Signature

```ts
type DelegationStartDecision
```

## Kind

`type`

## Source

[`packages/sdk/src/a2a/subagent.ts:91`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L91)

---

# discoverSkills

Source: https://docs.usetheo.dev/theokit/reference/discoverSkills

`@theokit/sdk/skills` — first-party skill discovery + `<skills>` block.

# `discoverSkills`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/skills` — first-party skill discovery + `<skills>` block.

`discoverSkills(dir, options?)` discovers `<dir>/<name>/SKILL.md` files under
an ARBITRARY directory (not a hardcoded `.theokit/skills` root), parsing
strict YAML frontmatter (`name`/`description` required; `category`/
`dependencies` optional) and skipping malformed skills + symlink-escapes. It
never throws — a missing/unreadable/non-directory path yields `[]`.

`buildSkillsBlock(skills)` renders the prompt-injection-safe `<skills>` system
prompt block (name + description XML-escaped; the skill body is not part of
the input type, so it cannot leak).

Both are the same primitives the SDK runtime uses internally for
`.theokit/skills` discovery and `<skills>` injection — exposed so consumers
orient an agent with one import instead of hand-rolling discovery.

## Signature

```ts
function discoverSkills(dir: string, options: DiscoverSkillsOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/skills/discover-skills.ts:79`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/skills/discover-skills.ts#L79)

---

# DiscoverSkillsOptions

Source: https://docs.usetheo.dev/theokit/reference/DiscoverSkillsOptions

Options for discoverSkills.

# `DiscoverSkillsOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for discoverSkills.

## Signature

```ts
interface DiscoverSkillsOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/skills/discover-skills.ts:47`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/skills/discover-skills.ts#L47)

---

# DoomLoopThresholds

Source: https://docs.usetheo.dev/theokit/reference/DoomLoopThresholds

Doom-loop guard thresholds (see SendOptions.doomLoop). Both are counts of CONSECUTIVE

# `DoomLoopThresholds`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Doom-loop guard thresholds (see SendOptions.doomLoop). Both are counts of CONSECUTIVE
identical tool calls: `softThreshold` injects a one-time guidance nudge; `hardThreshold` stops.

## Signature

```ts
interface DoomLoopThresholds { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:185`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L185)

---

# DowhileStep

Source: https://docs.usetheo.dev/theokit/reference/DowhileStep

Loop a step until condFn returns false.

# `DowhileStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Loop a step until condFn returns false.

## Signature

```ts
interface DowhileStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:86`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L86)

---

# DreamingSweepOptions

Source: https://docs.usetheo.dev/theokit/reference/DreamingSweepOptions

Public `Memory` namespace.

# `DreamingSweepOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public `Memory` namespace.

Exposes operations users can run outside of `agent.send()` — most notably
the dreaming sweep (consolidation of facts via dedup + clustering).

## Signature

```ts
interface DreamingSweepOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/memory.ts:58`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/memory.ts#L58)

---

# DreamingSweepResult

Source: https://docs.usetheo.dev/theokit/reference/DreamingSweepResult

_No description available._

# `DreamingSweepResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface DreamingSweepResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/memory.ts:77`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/memory.ts#L77)

---

# emitRunEvent

Source: https://docs.usetheo.dev/theokit/reference/emitRunEvent

_No description available._

# `emitRunEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function emitRunEvent(sink: unknown, event: RunEvent): void
```

## Kind

`function`

## Source

[`packages/sdk/src/types/run-events.ts:125`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L125)

---

# ErrorCode

Source: https://docs.usetheo.dev/theokit/reference/ErrorCode

Finite, machine-readable error codes for provider-originated errors

# `ErrorCode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Finite, machine-readable error codes for provider-originated errors
(ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively
— adding a new variant is an explicit decision + test coverage.

## Signature

```ts
type ErrorCode
```

## Kind

`type`

## Source

[`packages/sdk/src/errors.ts:12`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L12)

---

# ErrorMetadata

Source: https://docs.usetheo.dev/theokit/reference/ErrorMetadata

Structured context for errors that originated from a provider HTTP

# `ErrorMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Structured context for errors that originated from a provider HTTP
call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),
surface actionable diagnostics (`provider`, `endpoint`), and inspect the
raw response body when needed (`raw`, capped at ~2KB by the mapper).

## Signature

```ts
interface ErrorMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/errors.ts:118`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L118)

---

# estimateTokens

Source: https://docs.usetheo.dev/theokit/reference/estimateTokens

_No description available._

# `estimateTokens`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function estimateTokens(text: string): number
```

## Kind

`function`

## Source

[`packages/sdk/src/compaction.ts:283`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L283)

---

# Eval

Source: https://docs.usetheo.dev/theokit/reference/Eval

_No description available._

# `Eval`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class Eval {
  run(...): ...
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/eval.ts:62`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/eval.ts#L62)

---

# EvalAgentOptions

Source: https://docs.usetheo.dev/theokit/reference/EvalAgentOptions

Inferred `Agent.create` options shape — avoid cycling through `AgentOptions` directly.

# `EvalAgentOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Inferred `Agent.create` options shape — avoid cycling through `AgentOptions` directly.

## Signature

```ts
type EvalAgentOptions
```

## Kind

`type`

## Source

[`packages/sdk/src/types/eval.ts:16`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L16)

---

# EvalAggregate

Source: https://docs.usetheo.dev/theokit/reference/EvalAggregate

Aggregate stats — the production-decision dashboard data (D211).

# `EvalAggregate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Aggregate stats — the production-decision dashboard data (D211).

## Signature

```ts
interface EvalAggregate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:161`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L161)

---

# EvalAlreadyRunningError

Source: https://docs.usetheo.dev/theokit/reference/EvalAlreadyRunningError

_No description available._

# `EvalAlreadyRunningError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class EvalAlreadyRunningError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/internal/eval/single-flight.ts:11`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/eval/single-flight.ts#L11)

---

# EvalHooks

Source: https://docs.usetheo.dev/theokit/reference/EvalHooks

Lifecycle hooks. Each fires inside a `safeHook` wrapper (EC-4); a throw never aborts the run.

# `EvalHooks`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Lifecycle hooks. Each fires inside a `safeHook` wrapper (EC-4); a throw never aborts the run.

## Signature

```ts
interface EvalHooks { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:53`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L53)

---

# EvalOptions

Source: https://docs.usetheo.dev/theokit/reference/EvalOptions

Public options for `Eval.create`.

# `EvalOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public options for `Eval.create`.

## Signature

```ts
interface EvalOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:60`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L60)

---

# EvalPersistOptions

Source: https://docs.usetheo.dev/theokit/reference/EvalPersistOptions

Crash-durable persistence for `eval.run(...)` (M6-1). Each completed row is

# `EvalPersistOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Crash-durable persistence for `eval.run(...)` (M6-1). Each completed row is
appended to `path` the instant it finishes (one `\n`-terminated JSON line),
so a crashed multi-hour run resumes without re-paying completed work.

Single-process contract: `appendFileSync` serializes writes within one Node
process; do NOT point two concurrent processes at the same `path`.

## Signature

```ts
interface EvalPersistOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:195`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L195)

---

# EvalRowResult

Source: https://docs.usetheo.dev/theokit/reference/EvalRowResult

Per-row outcome.

# `EvalRowResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-row outcome.

## Signature

```ts
interface EvalRowResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:92`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L92)

---

# EvalRun

Source: https://docs.usetheo.dev/theokit/reference/EvalRun

Final run result — plain serializable JSON (D209).

# `EvalRun`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Final run result — plain serializable JSON (D209).

## Signature

```ts
interface EvalRun { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:176`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L176)

---

# EvalRunOptions

Source: https://docs.usetheo.dev/theokit/reference/EvalRunOptions

Per-call options for `eval.run(...)`.

# `EvalRunOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-call options for `eval.run(...)`.

## Signature

```ts
interface EvalRunOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:215`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L215)

---

# EventBus

Source: https://docs.usetheo.dev/theokit/reference/EventBus

_No description available._

# `EventBus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class EventBus {
  once(...): ...
  publish(...): ...
  subscribe(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/event-bus.ts:10`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/event-bus.ts#L10)

---

# EvictReason

Source: https://docs.usetheo.dev/theokit/reference/EvictReason

_No description available._

# `EvictReason`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type EvictReason
```

## Kind

`type`

## Source

[`packages/sdk/src/internal/runtime/registry/live-agent-registry.ts:23`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/registry/live-agent-registry.ts#L23)

---

# ExecuteResult

Source: https://docs.usetheo.dev/theokit/reference/ExecuteResult

_No description available._

# `ExecuteResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface ExecuteResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/sandbox/types.ts:13`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/types.ts#L13)

---

# extractRawId

Source: https://docs.usetheo.dev/theokit/reference/extractRawId

_No description available._

# `extractRawId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function extractRawId(id: MemoryId, expectedAdapterId: string): string
```

## Kind

`function`

## Source

[`packages/sdk/src/memory-adapter-helpers.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/memory-adapter-helpers.ts#L34)

---

# extractToolUses

Source: https://docs.usetheo.dev/theokit/reference/extractToolUses

_No description available._

# `extractToolUses`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function extractToolUses(msg: SDKMessage): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/messages.ts:37`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/messages.ts#L37)

---

# FileNotFoundError

Source: https://docs.usetheo.dev/theokit/reference/FileNotFoundError

A read/stat targeted a path that does not exist.

# `FileNotFoundError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A read/stat targeted a path that does not exist.

## Signature

```ts
class FileNotFoundError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/types.ts:64`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L64)

---

# FileStat

Source: https://docs.usetheo.dev/theokit/reference/FileStat

Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32).

# `FileStat`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32).

## Signature

```ts
interface FileStat { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/filesystem/types.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L22)

---

# FilesystemBackend

Source: https://docs.usetheo.dev/theokit/reference/FilesystemBackend

Pluggable filesystem backend. Implement the four abstract methods; `exists()`

# `FilesystemBackend`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Pluggable filesystem backend. Implement the four abstract methods; `exists()`
and the `readOnly`/`basePath` accessors derive on the base class.

## Signature

```ts
class FilesystemBackend {
  assertWritable(...): ...
  exists(...): ...
  list(...): ...
  readFile(...): ...
  stat(...): ...
  writeFile(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/types.ts:119`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L119)

---

# FilesystemConfig

Source: https://docs.usetheo.dev/theokit/reference/FilesystemConfig

_No description available._

# `FilesystemConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface FilesystemConfig { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/filesystem/types.ts:38`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L38)

---

# FilesystemError

Source: https://docs.usetheo.dev/theokit/reference/FilesystemError

A filesystem I/O operation failed for a reason other than not-found /

# `FilesystemError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A filesystem I/O operation failed for a reason other than not-found /
read-only / stale / security (e.g. `ENOTDIR` — a path component is a file, or
`EACCES` / `ENOSPC`). Carries the original error as `cause` so no raw,
untyped Node `SystemError` ever escapes the backend (Unbreakable Rule 8).

## Signature

```ts
class FilesystemError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/types.ts:78`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L78)

---

# FilesystemProvider

Source: https://docs.usetheo.dev/theokit/reference/FilesystemProvider

A backend OR a per-request resolver of one. A resolver runs at tool-execution

# `FilesystemProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A backend OR a per-request resolver of one. A resolver runs at tool-execution
time (the request scope), so multi-tenant / multi-role agents get a distinct
root or permission set per request without a shared mutable backend.

## Signature

```ts
type FilesystemProvider
```

## Kind

`type`

## Source

[`packages/sdk/src/filesystem/types.ts:179`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L179)

---

# FilesystemReadOnlyError

Source: https://docs.usetheo.dev/theokit/reference/FilesystemReadOnlyError

A write was attempted on a read-only backend.

# `FilesystemReadOnlyError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A write was attempted on a read-only backend.

## Signature

```ts
class FilesystemReadOnlyError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/types.ts:55`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L55)

---

# FilesystemSecurityError

Source: https://docs.usetheo.dev/theokit/reference/FilesystemSecurityError

A path escaped the backend's `basePath` (traversal or symlink).

# `FilesystemSecurityError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A path escaped the backend's `basePath` (traversal or symlink).

## Signature

```ts
class FilesystemSecurityError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/types.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L46)

---

# FilterCheckpointOptions

Source: https://docs.usetheo.dev/theokit/reference/FilterCheckpointOptions

Options for filterFromLatestCheckpoint.

# `FilterCheckpointOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for filterFromLatestCheckpoint.

## Signature

```ts
interface FilterCheckpointOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/compaction.ts:218`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L218)

---

# filterFromLatestCheckpoint

Source: https://docs.usetheo.dev/theokit/reference/filterFromLatestCheckpoint

_No description available._

# `filterFromLatestCheckpoint`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function filterFromLatestCheckpoint(messages: unknown, options: FilterCheckpointOptions): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/compaction.ts:233`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L233)

---

# fn

Source: https://docs.usetheo.dev/theokit/reference/fn

_No description available._

# `fn`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function fn(id: string, step: unknown, opts: unknown): FnStep
```

## Kind

`function`

## Source

[`packages/sdk/src/workflow.ts:337`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L337)

---

# FnStep

Source: https://docs.usetheo.dev/theokit/reference/FnStep

A pure function step.

# `FnStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A pure function step.

## Signature

```ts
interface FnStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L30)

---

# ForbiddenPathError

Source: https://docs.usetheo.dev/theokit/reference/ForbiddenPathError

Thrown when an agent tool is asked to read or write a sensitive path

# `ForbiddenPathError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when an agent tool is asked to read or write a sensitive path
that the blocklist forbids (`.env`, `.git/`, `node_modules/`, `.theo/`,
lock files). Distinct from `PathTraversalError` because the path is
lexically inside the project — it is just sensitive.

Extends `ConfigurationError` (no new error hierarchy per ADR D65).

## Signature

```ts
class ForbiddenPathError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/internal/security/path-guard.ts:53`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/security/path-guard.ts#L53)

---

# ForeachStep

Source: https://docs.usetheo.dev/theokit/reference/ForeachStep

Map a step over an upstream array output.

# `ForeachStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Map a step over an upstream array output.

## Signature

```ts
interface ForeachStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:76`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L76)

---

# fromEnvelope

Source: https://docs.usetheo.dev/theokit/reference/fromEnvelope

_No description available._

# `fromEnvelope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function fromEnvelope(env: TheokitErrorEnvelope): TheokitAgentError
```

## Kind

`function`

## Source

[`packages/sdk/src/server/errors-envelope.ts:189`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/errors-envelope.ts#L189)

---

# GenerateObjectError

Source: https://docs.usetheo.dev/theokit/reference/GenerateObjectError

Typed error thrown by Agent.generateObject when the model refuses

# `GenerateObjectError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Typed error thrown by Agent.generateObject when the model refuses
to call the synthetic `output` tool or when retries are exhausted.

## Signature

```ts
class GenerateObjectError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/generate-object.ts:90`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/generate-object.ts#L90)

---

# GenerateObjectOptions

Source: https://docs.usetheo.dev/theokit/reference/GenerateObjectOptions

Options accepted by Agent.generateObject. Returns a typed object

# `GenerateObjectOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options accepted by Agent.generateObject. Returns a typed object
matching the supplied Zod schema. See ADR D33.

## Signature

```ts
interface GenerateObjectOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/generate-object.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/generate-object.ts#L20)

---

# GenerateObjectResult

Source: https://docs.usetheo.dev/theokit/reference/GenerateObjectResult

Successful return from Agent.generateObject.

# `GenerateObjectResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Successful return from Agent.generateObject.

## Signature

```ts
interface GenerateObjectResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/generate-object.ts:73`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/generate-object.ts#L73)

---

# GenerateOptions

Source: https://docs.usetheo.dev/theokit/reference/GenerateOptions

SE9 — options for the integrated structured-output method `agent.generate`: the

# `GenerateOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE9 — options for the integrated structured-output method `agent.generate`: the
SendOptions that drive the tool loop (phase 1) plus the required `output`
Zod schema and structuring knobs (phase 2). Co-located with `SendOptions` /
`RunResult` (which they extend/use) so the public `SDKAgent` interface does not
import the runtime `agent-generate` module (breaks the type cycle).

## Signature

```ts
interface GenerateOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:555`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L555)

---

# GenerateRunResult

Source: https://docs.usetheo.dev/theokit/reference/GenerateRunResult

SE9 — result of `agent.generate`: the validated typed object plus the underlying

# `GenerateRunResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE9 — result of `agent.generate`: the validated typed object plus the underlying
tool-loop RunResult (status / usage / model) and the raw pre-parse input.

## Signature

```ts
interface GenerateRunResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:576`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L576)

---

# GetAgentOptions

Source: https://docs.usetheo.dev/theokit/reference/GetAgentOptions

Options for `Agent.get()`.

# `GetAgentOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Agent.get()`.

## Signature

```ts
interface GetAgentOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:957`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L957)

---

# getPricingEntry

Source: https://docs.usetheo.dev/theokit/reference/getPricingEntry

_No description available._

# `getPricingEntry`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function getPricingEntry(opts: unknown): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/budget/pricing-registry.ts:83`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/pricing-registry.ts#L83)

---

# GetRunOptions

Source: https://docs.usetheo.dev/theokit/reference/GetRunOptions

Options for `Agent.getRun()`. Cloud requires the parent `agentId`.

# `GetRunOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Agent.getRun()`. Cloud requires the parent `agentId`.

## Signature

```ts
type GetRunOptions
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:977`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L977)

---

# getTaskStoreFor

Source: https://docs.usetheo.dev/theokit/reference/getTaskStoreFor

Public sub-export for the Task store interface + JSON-backed

# `getTaskStoreFor`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public sub-export for the Task store interface + JSON-backed
implementation. Used by `@theokit/cli` to read the registry
cross-process from disk (ADR D364 + EC-7 best-effort cancel).

## Signature

```ts
function getTaskStoreFor(options: TaskStoreOptions): TaskStore
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/task/store.ts:252`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/task/store.ts#L252)

---

# GoalEvent

Source: https://docs.usetheo.dev/theokit/reference/GoalEvent

Single event emitted while iterating a goal-driven loop. Five variants:

# `GoalEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Single event emitted while iterating a goal-driven loop. Five variants:

- `turn_start` — the agent is about to invoke `send()`. Emitted once
  per turn.
- `agent_response` — the agent's `send()` resolved; carries the text
  reply.
- `judge_verdict` — the auxiliary judge model evaluated the response.
  `parseFailed: true` indicates the judge returned a malformed reply
  (fail-safe verdict = `continue`, see ADR D121).
- `continuation` — the judge ruled `continue`; carries the prompt that
  was sent on THIS turn (i.e., the input that produced the agent
  response just yielded). Useful for consumers who want to audit the
  exact continuation message that drove each iteration. The prompt
  for the NEXT turn is composed lazily at the start of that turn
  from the latest `agent_response.content`.
- `status_change` — transition of the overall goal state. Always
  emitted once at start (`active`) and once at end
  (`completed | failed | paused`).

## Signature

```ts
type GoalEvent
```

## Kind

`type`

## Source

[`packages/sdk/src/types/goal-events.ts:33`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/goal-events.ts#L33)

---

# GoalOptions

Source: https://docs.usetheo.dev/theokit/reference/GoalOptions

Per-call configuration for `Agent.runUntil`.

# `GoalOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-call configuration for `Agent.runUntil`.

## Signature

```ts
interface GoalOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/goal-events.ts:75`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/goal-events.ts#L75)

---

# GoalResult

Source: https://docs.usetheo.dev/theokit/reference/GoalResult

Return value of the `runUntil` async generator. Consumer reads via

# `GoalResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Return value of the `runUntil` async generator. Consumer reads via
`const { value } = await gen.next()` (when `done: true`).

## Signature

```ts
interface GoalResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/goal-events.ts:56`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/goal-events.ts#L56)

---

# HookName

Source: https://docs.usetheo.dev/theokit/reference/HookName

_No description available._

# `HookName`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type HookName
```

## Kind

`type`

## Source

[`packages/sdk/src/internal/plugins/types.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L20)

---

# humanizeModelName

Source: https://docs.usetheo.dev/theokit/reference/humanizeModelName

_No description available._

# `humanizeModelName`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function humanizeModelName(modelId: string): string
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/llm/model-option.ts:40`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-option.ts#L40)

---

# ImageBlock

Source: https://docs.usetheo.dev/theokit/reference/ImageBlock

SE7 — a base64-encoded image block a tool can hand back as (part of) its

# `ImageBlock`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE7 — a base64-encoded image block a tool can hand back as (part of) its
result or its `ToolError`. `media_type` is a MIME type (e.g. `"image/png"`);
`data` is the base64 payload without a data-URL prefix.

Note: when a tool builds this from model- or user-influenced input, treat
`media_type` as UNTRUSTED — validate/allow-list it before rendering it in a
log or UI (it could carry newlines / control chars). The SDK only forwards it
(JSON-serialized onto the wire) and never executes or path-joins it.

## Signature

```ts
interface ImageBlock { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/content-blocks.ts:33`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/content-blocks.ts#L33)

---

# API reference

Source: https://docs.usetheo.dev/theokit/reference

Every public symbol in @theokit/sdk, auto-generated from TypeDoc.

# API reference

This section is **auto-generated** from TypeDoc on every build. 498 symbols exported.

## Classes

- [`Agent`](/theokit/reference/Agent) — Static façade for creating and managing Theo agents.
- [`AgentBuilder`](/theokit/reference/AgentBuilder) — Fluent builder for AgentOptions. Chainable setters mutate internal
- [`AgentDisposedError`](/theokit/reference/AgentDisposedError) — T1.6 — Thrown when a consumer calls `agent.send()` or any method
- [`AgentFactory`](/theokit/reference/AgentFactory) — SE36 — `AgentFactory.create` replaces `createAgentFactory` (ADR 0015). Merges wi
- [`AgentMailbox`](/theokit/reference/AgentMailbox) — _no description_
- [`AgentRunError`](/theokit/reference/AgentRunError) — Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when
- [`Auth`](/theokit/reference/Auth) — SE36 — `Auth.create` replaces `defineAuth` (ADR 0015).
- [`AuthCallbackError`](/theokit/reference/AuthCallbackError) — Thrown during OAuth callback handling for state mismatches, expired
- [`AuthCancelledError`](/theokit/reference/AuthCancelledError) — Per v1.1 EC-1 MUST FIX — typed subclass of AuthCallbackError for the
- [`AuthConfigError`](/theokit/reference/AuthConfigError) — Thrown at `defineAuth()` time when configuration is invalid
- [`AuthenticationError`](/theokit/reference/AuthenticationError) — Invalid API key, not logged in, insufficient permissions.
- [`AuthProviderNotFoundError`](/theokit/reference/AuthProviderNotFoundError) — Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`
- [`AuthSecretTooShortError`](/theokit/reference/AuthSecretTooShortError) — T5.1 — Typed error thrown when an OAuth tx-cookie secret has < 32
- [`Budget`](/theokit/reference/Budget) — _no description_
- [`BudgetExceededError`](/theokit/reference/BudgetExceededError) — Thrown by `Budget` enforcement (ADR D386) when a `mode: "block"`
- [`ConfigurationError`](/theokit/reference/ConfigurationError) — Invalid model, bad request parameters, malformed options.
- [`CredentialPoolExhaustedError`](/theokit/reference/CredentialPoolExhaustedError) — Thrown when every credential in a per-provider pool is in cooldown
- [`Cron`](/theokit/reference/Cron) — Static façade for scheduling Theo agent runs on a cron expression.
- [`Eval`](/theokit/reference/Eval) — _no description_
- [`EvalAlreadyRunningError`](/theokit/reference/EvalAlreadyRunningError) — _no description_
- [`EventBus`](/theokit/reference/EventBus) — _no description_
- [`FileNotFoundError`](/theokit/reference/FileNotFoundError) — A read/stat targeted a path that does not exist.
- [`FilesystemBackend`](/theokit/reference/FilesystemBackend) — Pluggable filesystem backend. Implement the four abstract methods; `exists()`
- [`FilesystemError`](/theokit/reference/FilesystemError) — A filesystem I/O operation failed for a reason other than not-found /
- [`FilesystemReadOnlyError`](/theokit/reference/FilesystemReadOnlyError) — A write was attempted on a read-only backend.
- [`FilesystemSecurityError`](/theokit/reference/FilesystemSecurityError) — A path escaped the backend's `basePath` (traversal or symlink).
- [`ForbiddenPathError`](/theokit/reference/ForbiddenPathError) — Thrown when an agent tool is asked to read or write a sensitive path
- [`GenerateObjectError`](/theokit/reference/GenerateObjectError) — Typed error thrown by Agent.generateObject when the model refuses
- [`InMemoryTaskStore`](/theokit/reference/InMemoryTaskStore) — Public sub-export for the Task store interface + JSON-backed
- [`IntegrationNotConnectedError`](/theokit/reference/IntegrationNotConnectedError) — Thrown when creating a cloud agent for a repo whose SCM provider is not
- [`InvalidTaskIdError`](/theokit/reference/InvalidTaskIdError) — Thrown when a user-supplied task ID violates the grammar
- [`JobQueue`](/theokit/reference/JobQueue) — _no description_
- [`JsonFileTaskStore`](/theokit/reference/JsonFileTaskStore) — Public sub-export for the Task store interface + JSON-backed
- [`LocalFilesystem`](/theokit/reference/LocalFilesystem) — `@theokit/sdk/filesystem` — pluggable filesystem provider seam (SE31).
- [`LocalSandbox`](/theokit/reference/LocalSandbox) — _no description_
- [`MaxDelegationDepthError`](/theokit/reference/MaxDelegationDepthError) — _no description_
- [`MemoryAdapterError`](/theokit/reference/MemoryAdapterError) — Error raised by `@theokit-memory-*` adapters. Carries `adapterId`
- [`MessageBus`](/theokit/reference/MessageBus) — _no description_
- [`NetworkError`](/theokit/reference/NetworkError) — Service unavailable, timeout, transport-level failure.
- [`NoopMemoryProvider`](/theokit/reference/NoopMemoryProvider) — SE36 — `NoopMemoryProvider.create` replaces `createNoopMemoryProvider` (ADR 0015
- [`PermissionEngine`](/theokit/reference/PermissionEngine) — _no description_
- [`PermissionPlugin`](/theokit/reference/PermissionPlugin) — SE36 — `PermissionPlugin.create` replaces `createPermissionPlugin` (ADR 0015).
- [`Provider`](/theokit/reference/Provider) — SE36 — uniform namespace API. `Provider.create` replaces `defineProvider` (ADR 0
- [`RateLimitError`](/theokit/reference/RateLimitError) — Too many requests or usage limits exceeded.
- [`RepoProvisionError`](/theokit/reference/RepoProvisionError) — Raised when cloning or checking out a repo fails. Carries the `instanceId`
- [`Retry`](/theokit/reference/Retry) — SE36 — `Retry.create` replaces `withRetry` (ADR 0015 / ADR-P2). NOTE: `withRetry
- [`SandboxBackend`](/theokit/reference/SandboxBackend) — _no description_
- [`SandboxNotAvailableError`](/theokit/reference/SandboxNotAvailableError) — _no description_
- [`SandboxSecurityError`](/theokit/reference/SandboxSecurityError) — _no description_
- [`Security`](/theokit/reference/Security) — _no description_
- [`Semaphore`](/theokit/reference/Semaphore) — SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015).
- [`Skill`](/theokit/reference/Skill) — SE36 — `Skill.create` replaces `createSkill` (ADR 0015).
- [`SkillReadTool`](/theokit/reference/SkillReadTool) — SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015).
- [`Squad`](/theokit/reference/Squad) — SE36 — `Squad.create` replaces `createSquad` (ADR 0015). Merges with the `Squad`
- [`StaleFileError`](/theokit/reference/StaleFileError) — SE32 — a write's `expectedMtime` did not match the file's current mtime: the
- [`StreamObjectError`](/theokit/reference/StreamObjectError) — Error thrown by Agent.streamObject when the model refuses to call
- [`SubAgent`](/theokit/reference/SubAgent) — SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015).
- [`Subscription`](/theokit/reference/Subscription) — SE36 — `Subscription.create` replaces `defineSubscription` (ADR 0015).
- [`SubscriptionDisconnectError`](/theokit/reference/SubscriptionDisconnectError) — Thrown when a subscription transport disconnects unexpectedly
- [`SubscriptionError`](/theokit/reference/SubscriptionError) — Base error for the subscription subsystem. Extends TheokitAgentError
- [`SubscriptionInputError`](/theokit/reference/SubscriptionInputError) — Thrown when subscription input fails Zod schema validation.
- [`Task`](/theokit/reference/Task) — _no description_
- [`TaskNotFoundError`](/theokit/reference/TaskNotFoundError) — Thrown when `Task.subscribe(id)` is called for a task that has been
- [`Theokit`](/theokit/reference/Theokit) — Account-level and catalog reads. All methods accept an optional `apiKey`
- [`TheokitAgentError`](/theokit/reference/TheokitAgentError) — Base class for all errors thrown by `@theokit/sdk`.
- [`TheoKitClient`](/theokit/reference/TheoKitClient) — Client sub-path barrel (T20.2, ADR D454).
- [`TokenLimiter`](/theokit/reference/TokenLimiter) — SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015).
- [`Tool`](/theokit/reference/Tool) — SE36 — the uniform `X.create()` namespace API. `Tool.create(spec)` is the sole p
- [`ToolError`](/theokit/reference/ToolError) — Thrown from a tool `handler` to surface a failure to the model. The SDK turns
- [`UnicodeNormalizer`](/theokit/reference/UnicodeNormalizer) — SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015).
- [`UnknownAgentError`](/theokit/reference/UnknownAgentError) — Catch-all for unclassified server or runtime errors.
- [`UnsupportedBudgetOperationError`](/theokit/reference/UnsupportedBudgetOperationError) — Base class for all errors thrown by `@theokit/sdk`.
- [`UnsupportedRunOperationError`](/theokit/reference/UnsupportedRunOperationError) — Thrown when a Run or agent operation is not available on the current
- [`UnsupportedTaskOperationError`](/theokit/reference/UnsupportedTaskOperationError) — Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
- [`UsageAccumulator`](/theokit/reference/UsageAccumulator) — _no description_
- [`Workflow`](/theokit/reference/Workflow) — _no description_
- [`WorkflowAlreadyRunningError`](/theokit/reference/WorkflowAlreadyRunningError) — _no description_
- [`WorkflowBuilder`](/theokit/reference/WorkflowBuilder) — _no description_
- [`WorkflowCompensateNotImplementedError`](/theokit/reference/WorkflowCompensateNotImplementedError) — D238 — saga engine not yet implemented.
- [`WorkflowDuplicateStepIdError`](/theokit/reference/WorkflowDuplicateStepIdError) — _no description_
- [`WorkflowInputError`](/theokit/reference/WorkflowInputError) — SE27 — the whole-workflow `inputSchema` rejected `run(input)` (before step 1).
- [`WorkflowMaxIterationsExceededError`](/theokit/reference/WorkflowMaxIterationsExceededError) — _no description_
- [`WorkflowNestedError`](/theokit/reference/WorkflowNestedError) — SE30 — a nested workflow (via `workflowStep`) did not `complete`. A nested
- [`WorkflowNotSerializableError`](/theokit/reference/WorkflowNotSerializableError) — EC-4 absorbed — JSON.stringify failed on snapshot payload.
- [`WorkflowOutputError`](/theokit/reference/WorkflowOutputError) — SE27 — the whole-workflow `outputSchema` rejected the final output (on `complete
- [`WorkflowParallelError`](/theokit/reference/WorkflowParallelError) — Aggregate failure from parallel branches.
- [`WorkflowResumeStepNotFoundError`](/theokit/reference/WorkflowResumeStepNotFoundError) — EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow.
- [`WorkflowSnapshotNotFoundError`](/theokit/reference/WorkflowSnapshotNotFoundError) — _no description_
- [`WorkflowStateError`](/theokit/reference/WorkflowStateError) — SE29 — `WorkflowOptions.stateSchema` rejected an `initialState` or a
- [`WorkflowToolError`](/theokit/reference/WorkflowToolError) — Raised by a workflowAsTool tool when the wrapped workflow run does not

## Constantes

- [`CHECKPOINT_MARKER`](/theokit/reference/CHECKPOINT_MARKER) — Sentinel prefix marking a conversation checkpoint turn. A visible, structured,
- [`Memory`](/theokit/reference/Memory) — _no description_
- [`Scorers`](/theokit/reference/Scorers) — _no description_
- [`SUMMARY_TEMPLATE`](/theokit/reference/SUMMARY_TEMPLATE) — The 7-section summary template handed to the `summarize` callback (theocode
- [`TASK_RESERVED_PREFIXES`](/theokit/reference/TASK_RESERVED_PREFIXES) — Re-exported for adapter implementations + tests.

## Functiones

- [`__resetSnapshotStoresForTests`](/theokit/reference/__resetSnapshotStoresForTests) — _no description_
- [`agentStep`](/theokit/reference/agentStep) — _no description_
- [`appendJsonl`](/theokit/reference/appendJsonl) — _no description_
- [`applyMode`](/theokit/reference/applyMode) — _no description_
- [`assistantText`](/theokit/reference/assistantText) — _no description_
- [`buildCheckpoint`](/theokit/reference/buildCheckpoint) — _no description_
- [`buildSkillsBlock`](/theokit/reference/buildSkillsBlock) — _no description_
- [`captureArtifact`](/theokit/reference/captureArtifact) — _no description_
- [`chargeAndCheckThresholds`](/theokit/reference/chargeAndCheckThresholds) — _no description_
- [`cloneWorkflow`](/theokit/reference/cloneWorkflow) — _no description_
- [`compactTranscript`](/theokit/reference/compactTranscript) — _no description_
- [`computeCost`](/theokit/reference/computeCost) — _no description_
- [`costAmountUsd`](/theokit/reference/costAmountUsd) — _no description_
- [`createCounterBudgetTracker`](/theokit/reference/createCounterBudgetTracker) — _no description_
- [`discoverSkills`](/theokit/reference/discoverSkills) — `@theokit/sdk/skills` — first-party skill discovery + `<skills>` block.
- [`emitRunEvent`](/theokit/reference/emitRunEvent) — _no description_
- [`estimateTokens`](/theokit/reference/estimateTokens) — _no description_
- [`extractRawId`](/theokit/reference/extractRawId) — _no description_
- [`extractToolUses`](/theokit/reference/extractToolUses) — _no description_
- [`filterFromLatestCheckpoint`](/theokit/reference/filterFromLatestCheckpoint) — _no description_
- [`fn`](/theokit/reference/fn) — _no description_
- [`fromEnvelope`](/theokit/reference/fromEnvelope) — _no description_
- [`getPricingEntry`](/theokit/reference/getPricingEntry) — _no description_
- [`getTaskStoreFor`](/theokit/reference/getTaskStoreFor) — Public sub-export for the Task store interface + JSON-backed
- [`humanizeModelName`](/theokit/reference/humanizeModelName) — _no description_
- [`inferApiMode`](/theokit/reference/inferApiMode) — _no description_
- [`isContextOverflowError`](/theokit/reference/isContextOverflowError) — _no description_
- [`isCorruptionError`](/theokit/reference/isCorruptionError) — _no description_
- [`isForbiddenPath`](/theokit/reference/isForbiddenPath) — Public path-safety primitives.
- [`isTrackedEnvelope`](/theokit/reference/isTrackedEnvelope) — _no description_
- [`isTransientError`](/theokit/reference/isTransientError) — _no description_
- [`isValidTaskId`](/theokit/reference/isValidTaskId) — _no description_
- [`mapWithConcurrency`](/theokit/reference/mapWithConcurrency) — _no description_
- [`migrateSqliteToLance`](/theokit/reference/migrateSqliteToLance) — _no description_
- [`mkMemoryId`](/theokit/reference/mkMemoryId) — _no description_
- [`normalizeSchema`](/theokit/reference/normalizeSchema) — _no description_
- [`normalizeUsage`](/theokit/reference/normalizeUsage) — _no description_
- [`openSqliteResilient`](/theokit/reference/openSqliteResilient) — _no description_
- [`parseModelId`](/theokit/reference/parseModelId) — _no description_
- [`preflightCheck`](/theokit/reference/preflightCheck) — _no description_
- [`provisionRepo`](/theokit/reference/provisionRepo) — _no description_
- [`readJsonlIds`](/theokit/reference/readJsonlIds) — _no description_
- [`readProjectInstructions`](/theokit/reference/readProjectInstructions) — `@theokit/sdk/project` — hierarchical project-instruction reader/writer.
- [`resolveFilesystem`](/theokit/reference/resolveFilesystem) — _no description_
- [`resolveModelCapabilities`](/theokit/reference/resolveModelCapabilities) — `@theokit/sdk/models` — per-model capability catalog.
- [`sanitizeIdentifier`](/theokit/reference/sanitizeIdentifier) — Public path-safety primitives.
- [`sanitizeToolInput`](/theokit/reference/sanitizeToolInput) — _no description_
- [`scopedConversationId`](/theokit/reference/scopedConversationId) — _no description_
- [`sessionScopePrefix`](/theokit/reference/sessionScopePrefix) — _no description_
- [`shouldCompact`](/theokit/reference/shouldCompact) — _no description_
- [`subagentToolWhitelist`](/theokit/reference/subagentToolWhitelist) — `@theokit/sdk/subagents` — sub-agent tool scoping (M4-6).
- [`subscribe`](/theokit/reference/subscribe) — _no description_
- [`toEnvelope`](/theokit/reference/toEnvelope) — _no description_
- [`toModelOption`](/theokit/reference/toModelOption) — _no description_
- [`toShareGptTrajectory`](/theokit/reference/toShareGptTrajectory) — _no description_
- [`tracked`](/theokit/reference/tracked) — _no description_
- [`validateReturnTo`](/theokit/reference/validateReturnTo) — _no description_
- [`withCwdMutex`](/theokit/reference/withCwdMutex) — _no description_
- [`withSubagentToolScope`](/theokit/reference/withSubagentToolScope) — `@theokit/sdk/subagents` — sub-agent tool scoping (M4-6).
- [`workflowAsTool`](/theokit/reference/workflowAsTool) — _no description_
- [`workflowStep`](/theokit/reference/workflowStep) — _no description_
- [`writeProjectInstructions`](/theokit/reference/writeProjectInstructions) — `@theokit/sdk/project` — hierarchical project-instruction reader/writer.

## Interfacees

- [`A2AMessage`](/theokit/reference/A2AMessage) — _no description_
- [`ActiveMemoryPassArgs`](/theokit/reference/ActiveMemoryPassArgs) — Arguments for `MemoryProvider.runActivePass(...)`.
- [`ActiveMemoryPassResult`](/theokit/reference/ActiveMemoryPassResult) — Result of `MemoryProvider.runActivePass(...)` — what the kernel injects into the
- [`AgentConversationTurn`](/theokit/reference/AgentConversationTurn) — Agent turn: user message + assistant/tool/thinking steps.
- [`AgentDefinition`](/theokit/reference/AgentDefinition) — Subagent definition. The parent agent spawns these via its Agent tool.
- [`AgentMemory`](/theokit/reference/AgentMemory) — Direct memory API exposed on `SDKAgent.memory`. Resolves to whichever
- [`AgentOperationOptions`](/theokit/reference/AgentOperationOptions) — Options for archive/unarchive/delete.
- [`AgentOptions`](/theokit/reference/AgentOptions) — Top-level options accepted by `Agent.create()`.
- [`AgentRegistryOptions`](/theokit/reference/AgentRegistryOptions) — _no description_
- [`AgentStep`](/theokit/reference/AgentStep) — An agent.send-driven step.
- [`AssistantMessage`](/theokit/reference/AssistantMessage) — Plain assistant message in a conversation history.
- [`AsyncSemaphore`](/theokit/reference/AsyncSemaphore) — _no description_
- [`AuthOrchestrator`](/theokit/reference/AuthOrchestrator) — Returned by `defineAuth<TSession>(opts)` — 5-method orchestrator surface.
- [`AuthProvider`](/theokit/reference/AuthProvider) — Provider contract — each @theokit/auth-* package implements this.
- [`AuthResult`](/theokit/reference/AuthResult) — Per ADR D9 — provider profile types are provider-specific (not unified).
- [`BatchItem`](/theokit/reference/BatchItem) — Single prompt in a batch. Plain string is shorthand for `{ prompt }`.
- [`BatchOptions`](/theokit/reference/BatchOptions) — Options accepted by `Agent.batch`. Extends `AgentOptions` — every
- [`BatchProgress`](/theokit/reference/BatchProgress) — Live progress snapshot delivered to `onProgress`.
- [`BranchStep`](/theokit/reference/BranchStep) — First-match-wins predicates + optional fallback.
- [`BudgetCheck`](/theokit/reference/BudgetCheck) — Decision the tracker returns on each iteration / pre-flight check.
- [`BudgetExceedEvent`](/theokit/reference/BudgetExceedEvent) — Exceed event emitted at 100% across all modes.
- [`BudgetHandle`](/theokit/reference/BudgetHandle) — Returned by `Budget.create` and `Budget.get` — read-only view.
- [`BudgetLimit`](/theokit/reference/BudgetLimit) — A single limit; stacked in an array (D384, ANY exceeded blocks).
- [`BudgetOptions`](/theokit/reference/BudgetOptions) — Options for `Budget.create`.
- [`BudgetSnapshot`](/theokit/reference/BudgetSnapshot) — Per-window snapshot returned by `Budget.snapshot()`.
- [`BudgetThresholdEvent`](/theokit/reference/BudgetThresholdEvent) — Threshold event emitted at 80% and 95% in `warn` and `block` modes.
- [`BudgetTotal`](/theokit/reference/BudgetTotal) — Aggregate snapshot of usage so far.
- [`BudgetTracker`](/theokit/reference/BudgetTracker) — The kernel-facing contract. Implementations live OUTSIDE the agent loop
- [`BudgetUsageEvent`](/theokit/reference/BudgetUsageEvent) — Single usage event recorded during one LLM call.
- [`ClientOptions`](/theokit/reference/ClientOptions) — Client SDK types (T20.2, ADR D454).
- [`CloudEnv`](/theokit/reference/CloudEnv) — Cloud execution environment.
- [`CloudOptions`](/theokit/reference/CloudOptions) — Cloud agent configuration.
- [`CloudRepo`](/theokit/reference/CloudRepo) — Repo to clone into a cloud agent's VM.
- [`CompactTranscriptOptions`](/theokit/reference/CompactTranscriptOptions) — Options for compactTranscript.
- [`CompletionCheck`](/theokit/reference/CompletionCheck) — SE34 — the per-send completion criterion (see SendOptions.completionCheck).
- [`CompletionCheckResult`](/theokit/reference/CompletionCheckResult) — SE34 — the resolved per-send completion verdict (see RunResult.completionCheck).
- [`ContextBudget`](/theokit/reference/ContextBudget) — Token budget used by the context manager for a single agent.
- [`ContextSettings`](/theokit/reference/ContextSettings) — Context configuration accepted by `Agent.create()` via AgentOptions.context.
- [`ContextSnapshot`](/theokit/reference/ContextSnapshot) — Result of `agent.context.snapshot()`. Public and secret-free by design — safe
- [`ContextSource`](/theokit/reference/ContextSource) — A single context source resolved by the context manager.
- [`CostBreakdown`](/theokit/reference/CostBreakdown) — Cost breakdown attached to `RunResult.cost`. When `status === "unknown"`,
- [`CounterBudgetTrackerOptions`](/theokit/reference/CounterBudgetTrackerOptions) — Options for `createCounterBudgetTracker`.
- [`CreateSkillSpec`](/theokit/reference/CreateSkillSpec) — Spec accepted by createSkill.
- [`CronCreateOptions`](/theokit/reference/CronCreateOptions) — Options for `Cron.create()`.
- [`CronGetOptions`](/theokit/reference/CronGetOptions) — Options for `Cron.get()`.
- [`CronJob`](/theokit/reference/CronJob) — Persistent cron-scheduled invocation of the Theo agent or a workflow.
- [`CronOperationOptions`](/theokit/reference/CronOperationOptions) — Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
- [`CronRunOptions`](/theokit/reference/CronRunOptions) — Options for `Cron.run()` — manually trigger a job off-schedule.
- [`CronSchedulerStatus`](/theokit/reference/CronSchedulerStatus) — Snapshot of the local scheduler returned by `Cron.status()`.
- [`CronStartOptions`](/theokit/reference/CronStartOptions) — Options for `Cron.start()` — activates the in-process scheduler for local
- [`CustomTool`](/theokit/reference/CustomTool) — Local function tool declared per-agent via AgentOptions.tools. The
- [`DatasetEntry`](/theokit/reference/DatasetEntry) — A single dataset row — input prompt + optional reference + free-form metadata.
- [`DefineAuthOptions`](/theokit/reference/DefineAuthOptions) — `defineAuth(opts)` configuration shape — Caminho C (Hybrid).
- [`DefineProviderOptions`](/theokit/reference/DefineProviderOptions) — Options for defineProvider.
- [`DefineSubscriptionOptions`](/theokit/reference/DefineSubscriptionOptions) — Options accepted by defineSubscription.
- [`DefineToolSpec`](/theokit/reference/DefineToolSpec) — _no description_
- [`DelegationCompleteContext`](/theokit/reference/DelegationCompleteContext) — Context passed to SubAgentSpec.onDelegationComplete after the child settles.
- [`DelegationCompleteDecision`](/theokit/reference/DelegationCompleteDecision) — Decision returned from SubAgentSpec.onDelegationComplete.
- [`DelegationStartContext`](/theokit/reference/DelegationStartContext) — Context passed to SubAgentSpec.onDelegationStart before the child runs.
- [`DiscoverSkillsOptions`](/theokit/reference/DiscoverSkillsOptions) — Options for discoverSkills.
- [`DoomLoopThresholds`](/theokit/reference/DoomLoopThresholds) — Doom-loop guard thresholds (see SendOptions.doomLoop). Both are counts of CONSEC
- [`DowhileStep`](/theokit/reference/DowhileStep) — Loop a step until condFn returns false.
- [`DreamingSweepOptions`](/theokit/reference/DreamingSweepOptions) — Public `Memory` namespace.
- [`DreamingSweepResult`](/theokit/reference/DreamingSweepResult) — _no description_
- [`ErrorMetadata`](/theokit/reference/ErrorMetadata) — Structured context for errors that originated from a provider HTTP
- [`EvalAggregate`](/theokit/reference/EvalAggregate) — Aggregate stats — the production-decision dashboard data (D211).
- [`EvalHooks`](/theokit/reference/EvalHooks) — Lifecycle hooks. Each fires inside a `safeHook` wrapper (EC-4); a throw never ab
- [`EvalOptions`](/theokit/reference/EvalOptions) — Public options for `Eval.create`.
- [`EvalPersistOptions`](/theokit/reference/EvalPersistOptions) — Crash-durable persistence for `eval.run(...)` (M6-1). Each completed row is
- [`EvalRowResult`](/theokit/reference/EvalRowResult) — Per-row outcome.
- [`EvalRun`](/theokit/reference/EvalRun) — Final run result — plain serializable JSON (D209).
- [`EvalRunOptions`](/theokit/reference/EvalRunOptions) — Per-call options for `eval.run(...)`.
- [`ExecuteResult`](/theokit/reference/ExecuteResult) — _no description_
- [`FileStat`](/theokit/reference/FileStat) — Structured file metadata. `mtimeMs` is the read-before-write oracle (SE32).
- [`FilesystemConfig`](/theokit/reference/FilesystemConfig) — _no description_
- [`FilterCheckpointOptions`](/theokit/reference/FilterCheckpointOptions) — Options for filterFromLatestCheckpoint.
- [`FnStep`](/theokit/reference/FnStep) — A pure function step.
- [`ForeachStep`](/theokit/reference/ForeachStep) — Map a step over an upstream array output.
- [`GenerateObjectOptions`](/theokit/reference/GenerateObjectOptions) — Options accepted by Agent.generateObject. Returns a typed object
- [`GenerateObjectResult`](/theokit/reference/GenerateObjectResult) — Successful return from Agent.generateObject.
- [`GenerateOptions`](/theokit/reference/GenerateOptions) — SE9 — options for the integrated structured-output method `agent.generate`: the
- [`GenerateRunResult`](/theokit/reference/GenerateRunResult) — SE9 — result of `agent.generate`: the validated typed object plus the underlying
- [`GetAgentOptions`](/theokit/reference/GetAgentOptions) — Options for `Agent.get()`.
- [`GoalOptions`](/theokit/reference/GoalOptions) — Per-call configuration for `Agent.runUntil`.
- [`GoalResult`](/theokit/reference/GoalResult) — Return value of the `runUntil` async generator. Consumer reads via
- [`ImageBlock`](/theokit/reference/ImageBlock) — SE7 — a base64-encoded image block a tool can hand back as (part of) its
- [`InlineSkill`](/theokit/reference/InlineSkill) — A code-defined skill (from createSkill) — a Skill plus its inline body.
- [`InputProcessorContext`](/theokit/reference/InputProcessorContext) — Context passed to Processor.processInput.
- [`InvalidateCacheOptions`](/theokit/reference/InvalidateCacheOptions) — Options for SDKAgent.invalidateCache.
- [`InvalidSkillInfo`](/theokit/reference/InvalidSkillInfo) — Information passed to `onInvalidSkill` when a `SKILL.md` is present but its
- [`JobQueueOptions`](/theokit/reference/JobQueueOptions) — #58 — construction options.
- [`ListResult`](/theokit/reference/ListResult) — Paginated list shape.
- [`LiveAgentRegistry`](/theokit/reference/LiveAgentRegistry) — _no description_
- [`LocalOptions`](/theokit/reference/LocalOptions) — Local agent configuration.
- [`McpAuthConfig`](/theokit/reference/McpAuthConfig) — OAuth-style auth bundle for HTTP/SSE MCP servers.
- [`McpOAuthConfig`](/theokit/reference/McpOAuthConfig) — OAuth 2.1 PKCE flow descriptor. See ADR D41.
- [`MemoryAdapter`](/theokit/reference/MemoryAdapter) — Portable third-party memory adapter contract. Implementations live
- [`MemoryAdapterCapabilities`](/theokit/reference/MemoryAdapterCapabilities) — Statically declared adapter feature flags. Consumers feature-detect
- [`MemoryContext`](/theokit/reference/MemoryContext) — Portable identity context. `userId` is the only required field —
- [`MemoryFact`](/theokit/reference/MemoryFact) — A single memory fact returned by `recall` or `get`.
- [`MemoryProvider`](/theokit/reference/MemoryProvider) — The kernel-facing contract. Implementations live OUTSIDE the agent loop
- [`MemoryProviderHandle`](/theokit/reference/MemoryProviderHandle) — Opaque handle returned by `init()`. Carried back into other methods so
- [`MemoryProviderInitOptions`](/theokit/reference/MemoryProviderInitOptions) — Options for `MemoryProvider.init(...)`.
- [`MemoryRevision`](/theokit/reference/MemoryRevision) — Versioned snapshot of a memory's history. Only emitted by providers
- [`MemorySettings`](/theokit/reference/MemorySettings) — Memory configuration accepted by `Agent.create()` via AgentOptions.memory.
- [`MemoryToolSchema`](/theokit/reference/MemoryToolSchema) — OpenAI-format function-calling schema exposed to the LLM.
- [`MemoryTurnMessage`](/theokit/reference/MemoryTurnMessage) — One assistant-turn message in the canonical `{role, content}` shape
- [`MessageFilterArgs`](/theokit/reference/MessageFilterArgs) — Arguments passed to SubAgentSpec.messageFilter (SE12).
- [`MigrateOptions`](/theokit/reference/MigrateOptions) — Options for migrateSqliteToLance.
- [`MigrateResult`](/theokit/reference/MigrateResult) — Outcome of migrateSqliteToLance.
- [`ModelCapabilities`](/theokit/reference/ModelCapabilities) — Per-model capability shape. Consumers use this to gate features at
- [`ModelListItem`](/theokit/reference/ModelListItem) — Single model entry in the catalog.
- [`ModelOption`](/theokit/reference/ModelOption) — A UI-friendly model option — the shape a `<select>`/dropdown consumes.
- [`ModelParameterDefinition`](/theokit/reference/ModelParameterDefinition) — Per-model parameter definition discovered from `Theokit.models.list()`.
- [`ModelParameterValue`](/theokit/reference/ModelParameterValue) — One slot in a ModelSelection.params array.
- [`ModelSelection`](/theokit/reference/ModelSelection) — Identifies a model plus optional per-model parameters (e.g. reasoning effort).
- [`ModelVariant`](/theokit/reference/ModelVariant) — Preset variant for a model — pre-filled parameter combinations.
- [`NamedScorer`](/theokit/reference/NamedScorer) — A named scorer — produced by every `Scorers.*` factory.
- [`OAuthTransaction`](/theokit/reference/OAuthTransaction) — Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
- [`OpenSqliteResilientOptions`](/theokit/reference/OpenSqliteResilientOptions) — _no description_
- [`OutputProcessorContext`](/theokit/reference/OutputProcessorContext) — Context passed to Processor.processOutput.
- [`ParallelStep`](/theokit/reference/ParallelStep) — N concurrent branches, each its own mini-step-list.
- [`ParsedModelId`](/theokit/reference/ParsedModelId) — Model identifier parsing (T1.2 follow-up, ADR D182 zero-config UX).
- [`PartialToolCallUpdate`](/theokit/reference/PartialToolCallUpdate) — Tool call arguments streaming in incrementally.
- [`PermissionEngineOptions`](/theokit/reference/PermissionEngineOptions) — Options for PermissionEngine.
- [`PermissionGateContext`](/theokit/reference/PermissionGateContext) — SE1 — context passed to the PermissionGate. Intentionally minimal for
- [`PermissionPluginOptions`](/theokit/reference/PermissionPluginOptions) — Options for createPermissionPlugin.
- [`PermissionRule`](/theokit/reference/PermissionRule) — _no description_
- [`PerScorerStats`](/theokit/reference/PerScorerStats) — Per-scorer breakdown computed across all rows.
- [`PersonalityPreset`](/theokit/reference/PersonalityPreset) — Resolved personality preset surfaced via SDKAgent.usePersonality
- [`PluginContext`](/theokit/reference/PluginContext) — _no description_
- [`PluginsSettings`](/theokit/reference/PluginsSettings) — Plugins configuration accepted by `Agent.create()` via
- [`PostAssistantReplyContext`](/theokit/reference/PostAssistantReplyContext) — Context passed to `post_assistant_reply` hook handlers (ADR D145).
- [`PreToolCallContext`](/theokit/reference/PreToolCallContext) — _no description_
- [`PreToolCallDecision`](/theokit/reference/PreToolCallDecision) — _no description_
- [`PreUserSendContext`](/theokit/reference/PreUserSendContext) — Context passed to `pre_user_send` hook handlers (ADR D145).
- [`PreUserSendResult`](/theokit/reference/PreUserSendResult) — Optional result returned by `pre_user_send` handlers. The agent loop
- [`Processor`](/theokit/reference/Processor) — A guardrail processor. Provide `processInput` (runs before the LLM) and/or
- [`ProcessorControls`](/theokit/reference/ProcessorControls) — Controls available to a processor while it runs: `abort()` stops the run with
- [`ProcessorTripwire`](/theokit/reference/ProcessorTripwire) — The tripwire detail attached to RunResult.tripwire when a processor
- [`ProcessorViolation`](/theokit/reference/ProcessorViolation) — A policy violation surfaced to a processor's Processor.onViolation
- [`ProjectInstructionFile`](/theokit/reference/ProjectInstructionFile) — One discovered project-instruction file.
- [`ProjectInstructions`](/theokit/reference/ProjectInstructions) — Result of readProjectInstructions.
- [`ProviderProfile`](/theokit/reference/ProviderProfile) — _no description_
- [`ProviderRoute`](/theokit/reference/ProviderRoute) — A single user-declared routing rule. Maps a capability to a provider, and
- [`ProviderRoutingSettings`](/theokit/reference/ProviderRoutingSettings) — Provider routing configuration accepted by `Agent.create()` via
- [`ProvisionRepoOptions`](/theokit/reference/ProvisionRepoOptions) — Options for provisionRepo.
- [`ReadProjectInstructionsOptions`](/theokit/reference/ReadProjectInstructionsOptions) — Options for readProjectInstructions.
- [`RecordSessionSummaryArgs`](/theokit/reference/RecordSessionSummaryArgs) — Arguments for `MemoryProvider.recordSessionSummary(...)`
- [`RequestOptions`](/theokit/reference/RequestOptions) — _no description_
- [`ResilientSqliteDb`](/theokit/reference/ResilientSqliteDb) — Minimal SQLite handle surface every driver (`better-sqlite3`) exposes.
- [`ResolvedProviderRoute`](/theokit/reference/ResolvedProviderRoute) — Resolved routing decision returned by `agent.providers.routes()`. Public and
- [`RetryOptions`](/theokit/reference/RetryOptions) — Options for withRetry. All fields optional; sensible defaults applied.
- [`RetryPolicy`](/theokit/reference/RetryPolicy) — D237 — retry policy applied per fn/agent step.
- [`Run`](/theokit/reference/Run) — Handle to a single prompt submission.
- [`RunCompactBoundaryEvent`](/theokit/reference/RunCompactBoundaryEvent) — The conversation crossed a compaction boundary (history was summarized).
- [`RunCompletionCheckEvent`](/theokit/reference/RunCompletionCheckEvent) — SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
- [`RunErrorDetail`](/theokit/reference/RunErrorDetail) — Structured error attached to a RunResult when the underlying run
- [`RunGitInfo`](/theokit/reference/RunGitInfo) — Git metadata attached to cloud runs.
- [`RunPermissionDeniedEvent`](/theokit/reference/RunPermissionDeniedEvent) — A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),
- [`RunRateLimitEvent`](/theokit/reference/RunRateLimitEvent) — The provider returned a rate-limit (HTTP 429); the loop will back off + retry.
- [`RunResult`](/theokit/reference/RunResult) — Terminal result of a Run.
- [`RunTaskCompletedEvent`](/theokit/reference/RunTaskCompletedEvent) — A background task/subagent finished.
- [`RunTaskStartedEvent`](/theokit/reference/RunTaskStartedEvent) — A background task/subagent started.
- [`RunTaskUpdatedEvent`](/theokit/reference/RunTaskUpdatedEvent) — A background task/subagent changed state.
- [`RunToCompletionOptions`](/theokit/reference/RunToCompletionOptions) — Options for SDKAgent.runToCompletion (M1 Phase 3 — continuation driver).
- [`RunToCompletionResult`](/theokit/reference/RunToCompletionResult) — Result of SDKAgent.runToCompletion.
- [`RunToolProgressEvent`](/theokit/reference/RunToolProgressEvent) — A tool call is being dispatched (before its result).
- [`RunTripwireEvent`](/theokit/reference/RunTripwireEvent) — SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
- [`SandboxConfig`](/theokit/reference/SandboxConfig) — _no description_
- [`SanitizeOptions`](/theokit/reference/SanitizeOptions) — Options for sanitizeToolInput. Trim is the only default-on rung — coercion and J
- [`SanitizeResult`](/theokit/reference/SanitizeResult) — Result of sanitizeToolInput. `value` is the sanitized copy; `changed` is true wh
- [`Score`](/theokit/reference/Score) — Outcome of a single scoring decision. `score` in [0, 1]; the runner clamps.
- [`SDKAgent`](/theokit/reference/SDKAgent) — Handle returned by `Agent.create()` and `Agent.resume()`.
- [`SDKAgentPlugins`](/theokit/reference/SDKAgentPlugins) — Public plugin listing handle exposed as `agent.plugins`. Populated when
- [`SDKAgentSkillDetail`](/theokit/reference/SDKAgentSkillDetail) — A skill resolved WITH its body, returned by SDKAgentSkills.get. Unlike
- [`SDKAgentSkills`](/theokit/reference/SDKAgentSkills) — _no description_
- [`SDKArtifact`](/theokit/reference/SDKArtifact) — Artifact produced inside an agent's workspace. Cloud-only.
- [`SDKAssistantMessage`](/theokit/reference/SDKAssistantMessage) — Model text output for this run.
- [`SDKContextManager`](/theokit/reference/SDKContextManager) — Public context manager handle exposed as `agent.context`.
- [`SDKImageDimension`](/theokit/reference/SDKImageDimension) — Dimensions of an inline image attachment.
- [`SDKObjectDelta`](/theokit/reference/SDKObjectDelta) — Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
- [`SDKPluginMetadata`](/theokit/reference/SDKPluginMetadata) — Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
- [`SDKProvider`](/theokit/reference/SDKProvider) — Provider catalog entry returned by `Theokit.providers.list()`.
- [`SDKProvidersManager`](/theokit/reference/SDKProvidersManager) — Public providers manager handle exposed as `agent.providers`.
- [`SDKRepository`](/theokit/reference/SDKRepository) — GitHub repository connected to the team. Cloud-only.
- [`SDKRequestMessage`](/theokit/reference/SDKRequestMessage) — Awaiting user input or approval.
- [`SDKStatusMessage`](/theokit/reference/SDKStatusMessage) — Cloud run lifecycle transitions.
- [`SDKSystemMessage`](/theokit/reference/SDKSystemMessage) — Init metadata. Emitted once at the start of a run.
- [`SDKTaskMessage`](/theokit/reference/SDKTaskMessage) — Task-level milestones and summaries.
- [`SDKThinkingMessage`](/theokit/reference/SDKThinkingMessage) — Reasoning content.
- [`SDKToolUseMessage`](/theokit/reference/SDKToolUseMessage) — Tool invocation lifecycle event. Emitted at start with `args`, then again on
- [`SDKUser`](/theokit/reference/SDKUser) — Account-level user info returned by `Theokit.me()`.
- [`SDKUserMessage`](/theokit/reference/SDKUserMessage) — Structured form of `agent.send()`'s message argument. Use it to send images
- [`SDKUserMessageEvent`](/theokit/reference/SDKUserMessageEvent) — Echo of the user prompt for this run.
- [`SendOptions`](/theokit/reference/SendOptions) — Per-send overrides and callbacks.
- [`SendResponse`](/theokit/reference/SendResponse) — _no description_
- [`ShareGptMessage`](/theokit/reference/ShareGptMessage) — One ShareGPT message in a conversation. `from` identifies the role and
- [`ShareGptTrajectory`](/theokit/reference/ShareGptTrajectory) — One full ShareGPT-format trajectory — a single conversation plus
- [`ShellCommand`](/theokit/reference/ShellCommand) — Shell command executed during a run.
- [`ShellConversationTurn`](/theokit/reference/ShellConversationTurn) — Shell turn: a command and its output.
- [`ShellOutput`](/theokit/reference/ShellOutput) — Output of a shell command.
- [`ShellOutputDeltaUpdate`](/theokit/reference/ShellOutputDeltaUpdate) — _no description_
- [`ShouldCompactInput`](/theokit/reference/ShouldCompactInput) — Input to shouldCompact: an estimate, the model's window, and reserved headroom.
- [`SkillsResolverContext`](/theokit/reference/SkillsResolverContext) — SE22 — context passed to a SkillsResolver. Mirrors
- [`SkillsSettings`](/theokit/reference/SkillsSettings) — Skills configuration accepted by `Agent.create()` via
- [`SleepStep`](/theokit/reference/SleepStep) — Pause for a fixed duration.
- [`SquadOptions`](/theokit/reference/SquadOptions) — Options for createSquad.
- [`SquadRun`](/theokit/reference/SquadRun) — Result of a Squad.run. `result` is the final (last agent's) output;
- [`StepCompletedUpdate`](/theokit/reference/StepCompletedUpdate) — Conversation step completed.
- [`StepContext`](/theokit/reference/StepContext) — D247 — context handed to every step.fn.
- [`StepResult`](/theokit/reference/StepResult) — _no description_
- [`StepStartedUpdate`](/theokit/reference/StepStartedUpdate) — Conversation step started.
- [`StreamEvent`](/theokit/reference/StreamEvent) — _no description_
- [`StreamObjectOptions`](/theokit/reference/StreamObjectOptions) — Options accepted by Agent.streamObject. Same shape as
- [`SubAgentSpec`](/theokit/reference/SubAgentSpec) — _no description_
- [`SubscribeOptions`](/theokit/reference/SubscribeOptions) — Options accepted by `Theokit.subscribe(name, input, opts?)`.
- [`SubscriptionCtx`](/theokit/reference/SubscriptionCtx) — Context passed to a subscription `handler` on each invocation.
- [`SubscriptionDescriptor`](/theokit/reference/SubscriptionDescriptor) — Descriptor returned by Subscription.create. Carries the typed
- [`SummaryCompletedUpdate`](/theokit/reference/SummaryCompletedUpdate) — _no description_
- [`SummaryStartedUpdate`](/theokit/reference/SummaryStartedUpdate) — _no description_
- [`SummaryUpdate`](/theokit/reference/SummaryUpdate) — _no description_
- [`SuspendStep`](/theokit/reference/SuspendStep) — Standalone explicit suspend point.
- [`SystemPromptContext`](/theokit/reference/SystemPromptContext) — Context passed to a SystemPromptResolver. Field order is a
- [`SystemPromptMemoryFact`](/theokit/reference/SystemPromptMemoryFact) — Public view of a recalled memory fact exposed to the system-prompt resolver.
- [`SystemPromptSkillRef`](/theokit/reference/SystemPromptSkillRef) — Public skill metadata exposed to the system-prompt resolver. Mirrors the
- [`TaskCancelResult`](/theokit/reference/TaskCancelResult) — Result of `Task.cancel` (D365 — idempotent).
- [`TaskConfigureOptions`](/theokit/reference/TaskConfigureOptions) — Registry-level configuration. May only be applied BEFORE the first
- [`TaskFilter`](/theokit/reference/TaskFilter) — Query filter for `Task.list`.
- [`TaskHandle`](/theokit/reference/TaskHandle) — Public read-only view of a task entry in the registry.
- [`TaskStore`](/theokit/reference/TaskStore) — Storage interface used by `TaskRegistry`.
- [`TaskSubmitOptions`](/theokit/reference/TaskSubmitOptions) — Options for `Task.submit`.
- [`TaskWorkContext`](/theokit/reference/TaskWorkContext) — _no description_
- [`TelemetrySettings`](/theokit/reference/TelemetrySettings) — Telemetry configuration for an agent. When `enabled: true`, the SDK emits
- [`TextBlock`](/theokit/reference/TextBlock) — Plain text content block emitted by the assistant or user, or returned by a
- [`TextDeltaUpdate`](/theokit/reference/TextDeltaUpdate) — Incremental text token from the assistant.
- [`TheokitErrorEnvelope`](/theokit/reference/TheokitErrorEnvelope) — Envelope shape — structurally identical to theokit/server `TheoErrorEnvelope`.
- [`TheokitRequestOptions`](/theokit/reference/TheokitRequestOptions) — Options shared by every `Theokit.*` request.
- [`ThinkingCompletedUpdate`](/theokit/reference/ThinkingCompletedUpdate) — Emitted when a reasoning block completes.
- [`ThinkingDeltaUpdate`](/theokit/reference/ThinkingDeltaUpdate) — Incremental reasoning token.
- [`ThinkingMessage`](/theokit/reference/ThinkingMessage) — Reasoning step in a conversation history.
- [`TokenDeltaUpdate`](/theokit/reference/TokenDeltaUpdate) — Token count delta for usage tracking.
- [`TokenLimiterOptions`](/theokit/reference/TokenLimiterOptions) — Options for createTokenLimiter.
- [`TokenUsage`](/theokit/reference/TokenUsage) — Token usage observed during a Run. 5 closed buckets (D376) cover
- [`ToolCall`](/theokit/reference/ToolCall) — Single tool call event. The internal `args` and `result` shapes are NOT stable.
- [`ToolCallCompletedUpdate`](/theokit/reference/ToolCallCompletedUpdate) — Tool call completed.
- [`ToolCallStartedUpdate`](/theokit/reference/ToolCallStartedUpdate) — Tool call started — args committed.
- [`ToolResult`](/theokit/reference/ToolResult) — Result of a tool invocation. Pairs with the preceding `toolCall` step
- [`ToolResultGuardOptions`](/theokit/reference/ToolResultGuardOptions) — _no description_
- [`ToolUseBlock`](/theokit/reference/ToolUseBlock) — Tool invocation block emitted by the assistant.
- [`TurnEndedUpdate`](/theokit/reference/TurnEndedUpdate) — Turn ended with usage summary.
- [`UnicodeNormalizerOptions`](/theokit/reference/UnicodeNormalizerOptions) — Options for createUnicodeNormalizer.
- [`UserMessage`](/theokit/reference/UserMessage) — User-authored message in a conversation history.
- [`UserMessageAppendedUpdate`](/theokit/reference/UserMessageAppendedUpdate) — User message appended to the conversation.
- [`VerifyGateOptions`](/theokit/reference/VerifyGateOptions) — Options for `Scorers.verifyGate` (M6-2) — grade a patch by running the
- [`WorkflowAsToolSpec`](/theokit/reference/WorkflowAsToolSpec) — Spec for workflowAsTool. `inputSchema` is the workflow's input shape (Zod).
- [`WorkflowOptions`](/theokit/reference/WorkflowOptions) — _no description_
- [`WorkflowPersistenceOptions`](/theokit/reference/WorkflowPersistenceOptions) — _no description_
- [`WorkflowResumeOptions`](/theokit/reference/WorkflowResumeOptions) — _no description_
- [`WorkflowRun`](/theokit/reference/WorkflowRun) — _no description_
- [`WorkflowRunOptions`](/theokit/reference/WorkflowRunOptions) — _no description_
- [`WorkflowSnapshot`](/theokit/reference/WorkflowSnapshot) — _no description_
- [`WriteFileOptions`](/theokit/reference/WriteFileOptions) — Options a write may carry. SE32 adds `expectedMtime` (stale-write guard).
- [`WriteProjectInstructionsOptions`](/theokit/reference/WriteProjectInstructionsOptions) — Options for writeProjectInstructions.

## Typees

- [`AgentPromptResult`](/theokit/reference/AgentPromptResult) — Result of a one-shot Agent.prompt call.
- [`AgentRunErrorCode`](/theokit/reference/AgentRunErrorCode) — Back-compat alias of KnownAgentRunErrorCode. Pre-T1.1 callers that
- [`BatchResult`](/theokit/reference/BatchResult) — Per-prompt outcome. Discriminated union — check `ok` before reading
- [`BudgetMode`](/theokit/reference/BudgetMode) — Enforcement mode (D383).
- [`BudgetScope`](/theokit/reference/BudgetScope) — Scope of a budget — where the charge is attributed. v1 supports
- [`BudgetWindow`](/theokit/reference/BudgetWindow) — Time window for a budget limit (D382 — UTC calendar-aligned).
- [`ContextManagerKind`](/theokit/reference/ContextManagerKind) — Context manager backend.
- [`ContextSourceStatus`](/theokit/reference/ContextSourceStatus) — Inclusion state of a single context source in a ContextSnapshot.
- [`ConversationStep`](/theokit/reference/ConversationStep) — _no description_
- [`ConversationTurn`](/theokit/reference/ConversationTurn) — Structured per-turn view of a run.
- [`CostSource`](/theokit/reference/CostSource) — Source of the cost figure for caller-side audit.
- [`CostStatus`](/theokit/reference/CostStatus) — Cost confidence level (D377).
- [`CronJobStatus`](/theokit/reference/CronJobStatus) — Lifecycle state reported by `Cron.list()` / `Cron.get()`.
- [`CronListOptions`](/theokit/reference/CronListOptions) — Options for `Cron.list()`.
- [`CronRuntime`](/theokit/reference/CronRuntime) — Runtime hosting a cron job. Mirrors the agent runtime split.
- [`Dataset`](/theokit/reference/Dataset) — `Dataset` is either an array OR a factory returning a (sync or async)
- [`DeepPartial`](/theokit/reference/DeepPartial) — Recursive partial — `T` where every nested field becomes optional.
- [`DelegationStartDecision`](/theokit/reference/DelegationStartDecision) — Decision returned from SubAgentSpec.onDelegationStart. Discriminated on
- [`ErrorCode`](/theokit/reference/ErrorCode) — Finite, machine-readable error codes for provider-originated errors
- [`EvalAgentOptions`](/theokit/reference/EvalAgentOptions) — Inferred `Agent.create` options shape — avoid cycling through `AgentOptions` dir
- [`EvictReason`](/theokit/reference/EvictReason) — _no description_
- [`FilesystemProvider`](/theokit/reference/FilesystemProvider) — A backend OR a per-request resolver of one. A resolver runs at tool-execution
- [`GetRunOptions`](/theokit/reference/GetRunOptions) — Options for `Agent.getRun()`. Cloud requires the parent `agentId`.
- [`GoalEvent`](/theokit/reference/GoalEvent) — Single event emitted while iterating a goal-driven loop. Five variants:
- [`HookName`](/theokit/reference/HookName) — _no description_
- [`InteractionUpdate`](/theokit/reference/InteractionUpdate) — Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
- [`JsonlParseError`](/theokit/reference/JsonlParseError) — _no description_
- [`KnownAgentRunErrorCode`](/theokit/reference/KnownAgentRunErrorCode) — T1.1 — closed literal union for `AgentRunError.code`. The previous
- [`ListAgentsOptions`](/theokit/reference/ListAgentsOptions) — Options for `Agent.list()`.
- [`ListRunsOptions`](/theokit/reference/ListRunsOptions) — Options for `Agent.listRuns()`.
- [`loadJsonl`](/theokit/reference/loadJsonl) — _no description_
- [`McpHttpServerConfig`](/theokit/reference/McpHttpServerConfig) — HTTP or SSE MCP server.
- [`McpServerConfig`](/theokit/reference/McpServerConfig) — Union of MCP server configs. See `docs.md` for the full reference.
- [`McpStdioServerConfig`](/theokit/reference/McpStdioServerConfig) — MCP server configuration accepted by `Agent.create()` and `agent.send()`.
- [`MemoryAdapterErrorCode`](/theokit/reference/MemoryAdapterErrorCode) — Finite error codes specific to memory adapter operations (ADR D141).
- [`MemoryId`](/theokit/reference/MemoryId) — Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
- [`MessageHandler`](/theokit/reference/MessageHandler) — _no description_
- [`MessageOrigin`](/theokit/reference/MessageOrigin) — SE3 — provenance of a turn (metadata-only; never changes routing/dispatch).
- [`NormalizedJsonSchema`](/theokit/reference/NormalizedJsonSchema) — The internal JSON-Schema shape the synthetic `output` tool consumes.
- [`PermissionAction`](/theokit/reference/PermissionAction) — `PermissionEngine` — first-match permission rules for tool invocations.
- [`PermissionGate`](/theokit/reference/PermissionGate) — SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape). Invoked ONLY
- [`PermissionGateDecision`](/theokit/reference/PermissionGateDecision) — SE1 — the resolution of an `"ask"` verdict by the host gate. Fail-closed: an
- [`PermissionMode`](/theokit/reference/PermissionMode) — SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.
- [`Plugin`](/theokit/reference/Plugin) — SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015). Const-companion (the 
- [`ProjectInstructionScope`](/theokit/reference/ProjectInstructionScope) — How discovered instruction files are reduced to a single `content` string.
- [`ProviderCapability`](/theokit/reference/ProviderCapability) — Capability slot a provider can fulfill.
- [`RunEvent`](/theokit/reference/RunEvent) — SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.
- [`RunEventSink`](/theokit/reference/RunEventSink) — SE2 — the opt-in sink for RunEvents. Supplied via `SendOptions.onRunEvent`.
- [`RunOperation`](/theokit/reference/RunOperation) — Operations that may or may not be supported on a given Run, or on
- [`RunStatus`](/theokit/reference/RunStatus) — Lifecycle status of a Run.
- [`RunUntilIterator`](/theokit/reference/RunUntilIterator) — Return type of import("../internal/runtime/local-agent/local-agent.js").LocalAge
- [`Scorer`](/theokit/reference/Scorer) — Scorer signature (D207). Returns `Score` synchronously OR via Promise —
- [`SDKAgentInfo`](/theokit/reference/SDKAgentInfo) — Metadata returned by `Agent.list()` and `Agent.get()`.
- [`SDKImage`](/theokit/reference/SDKImage) — Either a remote URL or inline base64 payload.
- [`SDKMessage`](/theokit/reference/SDKMessage) — Discriminated union of all stream events. Discriminate on `type`.
- [`SDKModel`](/theokit/reference/SDKModel) — _no description_
- [`SessionScope`](/theokit/reference/SessionScope) — M3 #62 — session state scope.
- [`SettingSource`](/theokit/reference/SettingSource) — Which on-disk settings layers a local agent loads.
- [`SkillsResolver`](/theokit/reference/SkillsResolver) — SE22 — a resolver that produces SkillsSettings per run from runtime
- [`Step`](/theokit/reference/Step) — _no description_
- [`StreamObjectEvent`](/theokit/reference/StreamObjectEvent) — Event emitted by Agent.streamObject. Discriminate on `type`.
- [`StreamToCompletionResult`](/theokit/reference/StreamToCompletionResult) — Result of SDKAgent.streamToCompletion (V3-4 — the STREAMING continuation
- [`SubscriptionTransport`](/theokit/reference/SubscriptionTransport) — Transport selection for subscriptions.
- [`SystemPromptResolver`](/theokit/reference/SystemPromptResolver) — Resolver function that produces the system prompt dynamically. Receives
- [`TaskEvent`](/theokit/reference/TaskEvent) — Discriminated union of task lifecycle events (D366).
- [`TaskKind`](/theokit/reference/TaskKind) — Discriminator of the runtime that produced a task (D374).
- [`TaskState`](/theokit/reference/TaskState) — Closed enum of the 5 lifecycle states (D362).
- [`TaskStoreOptions`](/theokit/reference/TaskStoreOptions) — Options shape for `TaskStore` factory (D364).
- [`TaskWorkFn`](/theokit/reference/TaskWorkFn) — _no description_
- [`TheokitErrorCode`](/theokit/reference/TheokitErrorCode) — Canonical envelope code union for cross-layer SDK boundary. Subset of the
- [`ToolContextMessage`](/theokit/reference/ToolContextMessage) — A2A (Agent-to-Agent) sub-path barrel (T20.1, ADR D453).
- [`ToolResultContentBlock`](/theokit/reference/ToolResultContentBlock) — SE7 — structured content a tool result may carry: text and/or images. A tool
- [`TrackedEnvelope`](/theokit/reference/TrackedEnvelope) — Tracked envelope: `[id, payload]` tuple yielded by subscription handlers
- [`WorkflowEvent`](/theokit/reference/WorkflowEvent) — SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level
- [`WorkflowStream`](/theokit/reference/WorkflowStream) — SE28 — the async iterator returned by `Workflow.stream()`. Yields

---

# inferApiMode

Source: https://docs.usetheo.dev/theokit/reference/inferApiMode

_No description available._

# `inferApiMode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function inferApiMode(provider: string): ApiMode
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/budget/normalize-usage.ts:66`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/normalize-usage.ts#L66)

---

# InlineSkill

Source: https://docs.usetheo.dev/theokit/reference/InlineSkill

A code-defined skill (from createSkill) — a Skill plus its inline body.

# `InlineSkill`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A code-defined skill (from createSkill) — a Skill plus its inline body.

## Signature

```ts
interface InlineSkill { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/create-skill.ts:14`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/create-skill.ts#L14)

---

# InMemoryTaskStore

Source: https://docs.usetheo.dev/theokit/reference/InMemoryTaskStore

Public sub-export for the Task store interface + JSON-backed

# `InMemoryTaskStore`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public sub-export for the Task store interface + JSON-backed
implementation. Used by `@theokit/cli` to read the registry
cross-process from disk (ADR D364 + EC-7 best-effort cancel).

## Signature

```ts
class InMemoryTaskStore {
  delete(...): ...
  evictTerminalOlderThan(...): ...
  get(...): ...
  insert(...): ...
  list(...): ...
  update(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/internal/task/store.ts:106`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/task/store.ts#L106)

---

# InputProcessorContext

Source: https://docs.usetheo.dev/theokit/reference/InputProcessorContext

Context passed to Processor.processInput.

# `InputProcessorContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to Processor.processInput.

## Signature

```ts
interface InputProcessorContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/processors.ts:39`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/processors.ts#L39)

---

# IntegrationNotConnectedError

Source: https://docs.usetheo.dev/theokit/reference/IntegrationNotConnectedError

Thrown when creating a cloud agent for a repo whose SCM provider is not

# `IntegrationNotConnectedError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when creating a cloud agent for a repo whose SCM provider is not
connected. Use `helpUrl` to point the user at the right reconnect flow.

## Signature

```ts
class IntegrationNotConnectedError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:222`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L222)

---

# InteractionUpdate

Source: https://docs.usetheo.dev/theokit/reference/InteractionUpdate

Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to

# `InteractionUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Lowest-level raw update from a run. Pass `onDelta` to `agent.send()` to
consume these. Finer-grained than `SDKMessage` events.

## Signature

```ts
type InteractionUpdate
```

## Kind

`type`

## Source

[`packages/sdk/src/types/updates.ts:166`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L166)

---

# InvalidateCacheOptions

Source: https://docs.usetheo.dev/theokit/reference/InvalidateCacheOptions

Options for SDKAgent.invalidateCache.

# `InvalidateCacheOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for SDKAgent.invalidateCache.

## Signature

```ts
interface InvalidateCacheOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:902`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L902)

---

# InvalidSkillInfo

Source: https://docs.usetheo.dev/theokit/reference/InvalidSkillInfo

Information passed to `onInvalidSkill` when a `SKILL.md` is present but its

# `InvalidSkillInfo`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Information passed to `onInvalidSkill` when a `SKILL.md` is present but its
frontmatter is malformed (missing required field or invalid YAML).

## Signature

```ts
interface InvalidSkillInfo { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/skills/discover-skills.ts:32`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/skills/discover-skills.ts#L32)

---

# InvalidTaskIdError

Source: https://docs.usetheo.dev/theokit/reference/InvalidTaskIdError

Thrown when a user-supplied task ID violates the grammar

# `InvalidTaskIdError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when a user-supplied task ID violates the grammar
`^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter
prefix (`wf-` / `b-` / `cron-`, EC-5).

## Signature

```ts
class InvalidTaskIdError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:560`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L560)

---

# isContextOverflowError

Source: https://docs.usetheo.dev/theokit/reference/isContextOverflowError

_No description available._

# `isContextOverflowError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function isContextOverflowError(err: unknown): boolean
```

## Kind

`function`

## Source

[`packages/sdk/src/compaction.ts:253`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L253)

---

# isCorruptionError

Source: https://docs.usetheo.dev/theokit/reference/isCorruptionError

_No description available._

# `isCorruptionError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function isCorruptionError(cause: unknown): boolean
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/persistence/sqlite-open.ts:96`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/sqlite-open.ts#L96)

---

# isForbiddenPath

Source: https://docs.usetheo.dev/theokit/reference/isForbiddenPath

Public path-safety primitives.

# `isForbiddenPath`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public path-safety primitives.

Thin re-export of the canonical implementation in
`internal/security/path-guard.ts`. Splitting this into its own
top-level module gives `rollup-plugin-dts` a clean boundary when
bundling declarations — without it, including the path-guard module
via the main barrel propagates a cascade of transitive imports that
surface a known-spurious "ForkOptions not exported" error from
`types/agent.ts` (dynamic-import-type quirk in rollup-plugin-dts).

See `docs.md → Security — path traversal + TOCTOU` for the full
primitive reference. Public from v1.x.

## Signature

```ts
function isForbiddenPath(input: string): boolean
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/security/path-guard.ts:267`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/security/path-guard.ts#L267)

---

# isTrackedEnvelope

Source: https://docs.usetheo.dev/theokit/reference/isTrackedEnvelope

_No description available._

# `isTrackedEnvelope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function isTrackedEnvelope(value: unknown): value
```

## Kind

`function`

## Source

[`packages/sdk/src/subscription/types.ts:84`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L84)

---

# isTransientError

Source: https://docs.usetheo.dev/theokit/reference/isTransientError

_No description available._

# `isTransientError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function isTransientError(err: unknown): boolean
```

## Kind

`function`

## Source

[`packages/sdk/src/errors.ts:443`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L443)

---

# isValidTaskId

Source: https://docs.usetheo.dev/theokit/reference/isValidTaskId

_No description available._

# `isValidTaskId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function isValidTaskId(id: string, allowReserved: boolean): boolean
```

## Kind

`function`

## Source

[`packages/sdk/src/types/task.ts:152`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L152)

---

# JobQueue

Source: https://docs.usetheo.dev/theokit/reference/JobQueue

_No description available._

# `JobQueue`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class JobQueue {
  cancel(...): ...
  enqueue(...): ...
  getJob(...): ...
  list(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/job-queue.ts:33`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/job-queue.ts#L33)

---

# JobQueueOptions

Source: https://docs.usetheo.dev/theokit/reference/JobQueueOptions

#58 — construction options.

# `JobQueueOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

#58 — construction options.

## Signature

```ts
interface JobQueueOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/job-queue.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/job-queue.ts#L25)

---

# JsonFileTaskStore

Source: https://docs.usetheo.dev/theokit/reference/JsonFileTaskStore

Public sub-export for the Task store interface + JSON-backed

# `JsonFileTaskStore`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public sub-export for the Task store interface + JSON-backed
implementation. Used by `@theokit/cli` to read the registry
cross-process from disk (ADR D364 + EC-7 best-effort cancel).

## Signature

```ts
class JsonFileTaskStore {
  delete(...): ...
  evictTerminalOlderThan(...): ...
  get(...): ...
  insert(...): ...
  list(...): ...
  update(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/internal/task/store.ts:161`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/task/store.ts#L161)

---

# JsonlParseError

Source: https://docs.usetheo.dev/theokit/reference/JsonlParseError

_No description available._

# `JsonlParseError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type JsonlParseError
```

## Kind

`type`

## Source

[`packages/sdk/src/eval.ts:88`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/eval.ts#L88)

---

# KnownAgentRunErrorCode

Source: https://docs.usetheo.dev/theokit/reference/KnownAgentRunErrorCode

T1.1 — closed literal union for `AgentRunError.code`. The previous

# `KnownAgentRunErrorCode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

T1.1 — closed literal union for `AgentRunError.code`. The previous
`(string & {})` escape hatch let arbitrary strings slip into the type
surface and defeated exhaustive `switch (code)` discrimination. This is
the canonical closed form. `AgentRunErrorCode` is re-aliased below for
source-level back-compat.

Adding a new code: append the literal here AND audit every `switch (err.code)`
in callers. Type-checker enforces the audit via the `default: assertNever(code)`
convention.

## Signature

```ts
type KnownAgentRunErrorCode
```

## Kind

`type`

## Source

[`packages/sdk/src/errors.ts:57`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L57)

---

# ListAgentsOptions

Source: https://docs.usetheo.dev/theokit/reference/ListAgentsOptions

Options for `Agent.list()`.

# `ListAgentsOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Agent.list()`.

## Signature

```ts
type ListAgentsOptions
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:938`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L938)

---

# ListResult

Source: https://docs.usetheo.dev/theokit/reference/ListResult

Paginated list shape.

# `ListResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Paginated list shape.

## Signature

```ts
interface ListResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:996`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L996)

---

# ListRunsOptions

Source: https://docs.usetheo.dev/theokit/reference/ListRunsOptions

Options for `Agent.listRuns()`.

# `ListRunsOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Agent.listRuns()`.

## Signature

```ts
type ListRunsOptions
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:967`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L967)

---

# LiveAgentRegistry

Source: https://docs.usetheo.dev/theokit/reference/LiveAgentRegistry

_No description available._

# `LiveAgentRegistry`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface LiveAgentRegistry { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/registry/live-agent-registry.ts:64`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/registry/live-agent-registry.ts#L64)

---

# loadJsonl

Source: https://docs.usetheo.dev/theokit/reference/loadJsonl

_No description available._

# `loadJsonl`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type loadJsonl
```

## Kind

`type`

## Source

[`packages/sdk/src/eval.ts:88`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/eval.ts#L88)

---

# LocalFilesystem

Source: https://docs.usetheo.dev/theokit/reference/LocalFilesystem

`@theokit/sdk/filesystem` — pluggable filesystem provider seam (SE31).

# `LocalFilesystem`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/filesystem` — pluggable filesystem provider seam (SE31).

The storage-side twin of `@theokit/sdk/sandbox`. Ship a `FilesystemBackend`
(default `LocalFilesystem`) to give agent file tools a boundary-enforced,
optionally read-only, provider-swappable storage root — including a
per-request resolver for multi-tenant roots. See ADR 0011.

## Signature

```ts
class LocalFilesystem {
  assertWritable(...): ...
  exists(...): ...
  list(...): ...
  readFile(...): ...
  stat(...): ...
  writeFile(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/local-filesystem.ts:45`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/local-filesystem.ts#L45)

---

# LocalOptions

Source: https://docs.usetheo.dev/theokit/reference/LocalOptions

Local agent configuration.

# `LocalOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Local agent configuration.

## Signature

```ts
interface LocalOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:35`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L35)

---

# LocalSandbox

Source: https://docs.usetheo.dev/theokit/reference/LocalSandbox

_No description available._

# `LocalSandbox`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class LocalSandbox {
  execute(...): ...
  glob(...): ...
  grep(...): ...
  listDir(...): ...
  readFile(...): ...
  truncateOutput(...): ...
  uploadFile(...): ...
  writeFile(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/sandbox/local-sandbox.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/local-sandbox.ts#L25)

---

# mapWithConcurrency

Source: https://docs.usetheo.dev/theokit/reference/mapWithConcurrency

_No description available._

# `mapWithConcurrency`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function mapWithConcurrency(items: unknown, concurrency: number, fn: unknown, options: unknown): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/concurrency/map-with-concurrency.ts:31`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/concurrency/map-with-concurrency.ts#L31)

---

# MaxDelegationDepthError

Source: https://docs.usetheo.dev/theokit/reference/MaxDelegationDepthError

_No description available._

# `MaxDelegationDepthError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class MaxDelegationDepthError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/a2a/subagent.ts:172`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L172)

---

# McpAuthConfig

Source: https://docs.usetheo.dev/theokit/reference/McpAuthConfig

OAuth-style auth bundle for HTTP/SSE MCP servers.

# `McpAuthConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

OAuth-style auth bundle for HTTP/SSE MCP servers.

## Signature

```ts
interface McpAuthConfig { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/mcp.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/mcp.ts#L34)

---

# McpHttpServerConfig

Source: https://docs.usetheo.dev/theokit/reference/McpHttpServerConfig

HTTP or SSE MCP server.

# `McpHttpServerConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

HTTP or SSE MCP server.

## Signature

```ts
type McpHttpServerConfig
```

## Kind

`type`

## Source

[`packages/sdk/src/types/mcp.ts:69`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/mcp.ts#L69)

---

# McpOAuthConfig

Source: https://docs.usetheo.dev/theokit/reference/McpOAuthConfig

OAuth 2.1 PKCE flow descriptor. See ADR D41.

# `McpOAuthConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

OAuth 2.1 PKCE flow descriptor. See ADR D41.

## Signature

```ts
interface McpOAuthConfig { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/mcp.ts:51`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/mcp.ts#L51)

---

# McpServerConfig

Source: https://docs.usetheo.dev/theokit/reference/McpServerConfig

Union of MCP server configs. See `docs.md` for the full reference.

# `McpServerConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Union of MCP server configs. See `docs.md` for the full reference.

## Signature

```ts
type McpServerConfig
```

## Kind

`type`

## Source

[`packages/sdk/src/types/mcp.ts:88`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/mcp.ts#L88)

---

# McpStdioServerConfig

Source: https://docs.usetheo.dev/theokit/reference/McpStdioServerConfig

MCP server configuration accepted by `Agent.create()` and `agent.send()`.

# `McpStdioServerConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

MCP server configuration accepted by `Agent.create()` and `agent.send()`.

## Signature

```ts
type McpStdioServerConfig
```

## Kind

`type`

## Source

[`packages/sdk/src/types/mcp.ts:6`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/mcp.ts#L6)

---

# Memory

Source: https://docs.usetheo.dev/theokit/reference/Memory

_No description available._

# `Memory`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
const Memory
```

## Kind

`constant`

## Source

[`packages/sdk/src/memory.ts:110`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/memory.ts#L110)

---

# MemoryAdapter

Source: https://docs.usetheo.dev/theokit/reference/MemoryAdapter

Portable third-party memory adapter contract. Implementations live

# `MemoryAdapter`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Portable third-party memory adapter contract. Implementations live
in `@theokit-memory-*` packages; the SDK never imports them.

## Signature

```ts
interface MemoryAdapter { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:126`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L126)

---

# MemoryAdapterCapabilities

Source: https://docs.usetheo.dev/theokit/reference/MemoryAdapterCapabilities

Statically declared adapter feature flags. Consumers feature-detect

# `MemoryAdapterCapabilities`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Statically declared adapter feature flags. Consumers feature-detect
at compile time via `if (adapter.capabilities.history)`.

## Signature

```ts
interface MemoryAdapterCapabilities { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:83`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L83)

---

# MemoryAdapterError

Source: https://docs.usetheo.dev/theokit/reference/MemoryAdapterError

Error raised by `@theokit-memory-*` adapters. Carries `adapterId`

# `MemoryAdapterError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Error raised by `@theokit-memory-*` adapters. Carries `adapterId`
so callers can branch on which provider failed (ADR D141).

## Signature

```ts
class MemoryAdapterError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:530`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L530)

---

# MemoryAdapterErrorCode

Source: https://docs.usetheo.dev/theokit/reference/MemoryAdapterErrorCode

Finite error codes specific to memory adapter operations (ADR D141).

# `MemoryAdapterErrorCode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Finite error codes specific to memory adapter operations (ADR D141).

## Signature

```ts
type MemoryAdapterErrorCode
```

## Kind

`type`

## Source

[`packages/sdk/src/errors.ts:516`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L516)

---

# MemoryContext

Source: https://docs.usetheo.dev/theokit/reference/MemoryContext

Portable identity context. `userId` is the only required field —

# `MemoryContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Portable identity context. `userId` is the only required field —
the lowest common denominator across Supermemory / Honcho / Mem0.
Adapter implementations translate the optional fields to their
provider's native primitives (Honcho session, Mem0 run_id, etc).

## Signature

```ts
interface MemoryContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L34)

---

# MemoryFact

Source: https://docs.usetheo.dev/theokit/reference/MemoryFact

A single memory fact returned by `recall` or `get`.

# `MemoryFact`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A single memory fact returned by `recall` or `get`.

## Signature

```ts
interface MemoryFact { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:54`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L54)

---

# MemoryId

Source: https://docs.usetheo.dev/theokit/reference/MemoryId

Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.

# `MemoryId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Branded provider memory ID. Format: `${adapterId}:${rawProviderId}`.
Use `mkMemoryId` / `extractRawId` from `../memory-adapter-helpers.js`
to construct and unwrap with cross-adapter safety (EC-B).

## Signature

```ts
type MemoryId
```

## Kind

`type`

## Source

[`packages/sdk/src/types/memory-adapter.ts:24`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L24)

---

# MemoryProvider

Source: https://docs.usetheo.dev/theokit/reference/MemoryProvider

The kernel-facing contract. Implementations live OUTSIDE the agent loop

# `MemoryProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The kernel-facing contract. Implementations live OUTSIDE the agent loop
(in `@theokit/sdk-memory` after Phase 1; in `internal/memory/` until then).

Implementations MUST be:
  - **Lazy** — `init()` may be called once per agent; subsequent calls
    return the same handle (impl decides via cache). Heavy work
    (loading the index, opening SQLite) deferred until first use.
  - **Non-throwing on the hot path** — `runActivePass()` returns an
    empty `facts: []` on degradation rather than throwing. Errors
    surface via the breakerTripped flag + telemetry.

## Signature

```ts
interface MemoryProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider.ts:122`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider.ts#L122)

---

# MemoryProviderHandle

Source: https://docs.usetheo.dev/theokit/reference/MemoryProviderHandle

Opaque handle returned by `init()`. Carried back into other methods so

# `MemoryProviderHandle`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Opaque handle returned by `init()`. Carried back into other methods so
the impl can stash per-agent state (index, breaker, cache, …) without
exposing it to the kernel.

## Signature

```ts
interface MemoryProviderHandle { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider.ts:103`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider.ts#L103)

---

# MemoryProviderInitOptions

Source: https://docs.usetheo.dev/theokit/reference/MemoryProviderInitOptions

Options for `MemoryProvider.init(...)`.

# `MemoryProviderInitOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `MemoryProvider.init(...)`.

## Signature

```ts
interface MemoryProviderInitOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider.ts:91`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider.ts#L91)

---

# MemoryRevision

Source: https://docs.usetheo.dev/theokit/reference/MemoryRevision

Versioned snapshot of a memory's history. Only emitted by providers

# `MemoryRevision`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Versioned snapshot of a memory's history. Only emitted by providers
with `capabilities.history === true` (Mem0 today).

## Signature

```ts
interface MemoryRevision { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:70`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L70)

---

# MemorySettings

Source: https://docs.usetheo.dev/theokit/reference/MemorySettings

Memory configuration accepted by `Agent.create()` via AgentOptions.memory.

# `MemorySettings`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Memory configuration accepted by `Agent.create()` via AgentOptions.memory.

Persists durable facts under `.theokit/memory/<namespace>/<scope>-<userId>.json`.

## Signature

```ts
interface MemorySettings { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:280`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L280)

---

# MemoryToolSchema

Source: https://docs.usetheo.dev/theokit/reference/MemoryToolSchema

OpenAI-format function-calling schema exposed to the LLM.

# `MemoryToolSchema`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

OpenAI-format function-calling schema exposed to the LLM.

## Signature

```ts
interface MemoryToolSchema { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:114`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L114)

---

# MemoryTurnMessage

Source: https://docs.usetheo.dev/theokit/reference/MemoryTurnMessage

One assistant-turn message in the canonical `{role, content}` shape

# `MemoryTurnMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

One assistant-turn message in the canonical `{role, content}` shape
an adapter may receive instead of a flat string when writing a turn.

## Signature

```ts
interface MemoryTurnMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/memory-adapter.ts:104`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/memory-adapter.ts#L104)

---

# MessageBus

Source: https://docs.usetheo.dev/theokit/reference/MessageBus

_No description available._

# `MessageBus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class MessageBus {
  has(...): ...
  listAgents(...): ...
  register(...): ...
  request(...): ...
  send(...): ...
  unregister(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/a2a/message-bus.ts:16`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/message-bus.ts#L16)

---

# MessageFilterArgs

Source: https://docs.usetheo.dev/theokit/reference/MessageFilterArgs

Arguments passed to SubAgentSpec.messageFilter (SE12).

# `MessageFilterArgs`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Arguments passed to SubAgentSpec.messageFilter (SE12).

## Signature

```ts
interface MessageFilterArgs { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/subagent.ts:65`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L65)

---

# MessageHandler

Source: https://docs.usetheo.dev/theokit/reference/MessageHandler

_No description available._

# `MessageHandler`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type MessageHandler
```

## Kind

`type`

## Source

[`packages/sdk/src/a2a/types.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/types.ts#L22)

---

# MessageOrigin

Source: https://docs.usetheo.dev/theokit/reference/MessageOrigin

SE3 — provenance of a turn (metadata-only; never changes routing/dispatch).

# `MessageOrigin`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE3 — provenance of a turn (metadata-only; never changes routing/dispatch).
Producers: `peer` (Squad step / a2a envelope), `coordinator` (subagent
delegation), `auto-continuation` (the run-to-completion / stream-to-completion
driver's continuation rounds) are stamped BY the SDK. `human` and
`task-notification` are positive markers a HOST stamps (e.g. re-sending an
agent after a background task completed). Absent origin ⇒ `undefined`.

## Signature

```ts
type MessageOrigin
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run.ts:76`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L76)

---

# MigrateOptions

Source: https://docs.usetheo.dev/theokit/reference/MigrateOptions

Options for migrateSqliteToLance.

# `MigrateOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for migrateSqliteToLance.

## Signature

```ts
interface MigrateOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/migrate.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/migrate.ts#L22)

---

# MigrateResult

Source: https://docs.usetheo.dev/theokit/reference/MigrateResult

Outcome of migrateSqliteToLance.

# `MigrateResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Outcome of migrateSqliteToLance.

## Signature

```ts
interface MigrateResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/migrate.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/migrate.ts#L34)

---

# migrateSqliteToLance

Source: https://docs.usetheo.dev/theokit/reference/migrateSqliteToLance

_No description available._

# `migrateSqliteToLance`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function migrateSqliteToLance(options: MigrateOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/migrate.ts:48`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/migrate.ts#L48)

---

# mkMemoryId

Source: https://docs.usetheo.dev/theokit/reference/mkMemoryId

_No description available._

# `mkMemoryId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function mkMemoryId(adapterId: string, rawId: string): MemoryId
```

## Kind

`function`

## Source

[`packages/sdk/src/memory-adapter-helpers.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/memory-adapter-helpers.ts#L22)

---

# ModelCapabilities

Source: https://docs.usetheo.dev/theokit/reference/ModelCapabilities

Per-model capability shape. Consumers use this to gate features at

# `ModelCapabilities`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-model capability shape. Consumers use this to gate features at
the SDK boundary (before request construction, not after 400).

## Signature

```ts
interface ModelCapabilities { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/llm/model-capabilities.ts:24`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-capabilities.ts#L24)

---

# ModelListItem

Source: https://docs.usetheo.dev/theokit/reference/ModelListItem

Single model entry in the catalog.

# `ModelListItem`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Single model entry in the catalog.

## Signature

```ts
interface ModelListItem { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/theokit.ts:40`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/theokit.ts#L40)

---

# ModelOption

Source: https://docs.usetheo.dev/theokit/reference/ModelOption

A UI-friendly model option — the shape a `<select>`/dropdown consumes.

# `ModelOption`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A UI-friendly model option — the shape a `<select>`/dropdown consumes.

Public via `@theokit/sdk/models`.

## Signature

```ts
interface ModelOption { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/llm/model-option.ts:10`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-option.ts#L10)

---

# ModelParameterDefinition

Source: https://docs.usetheo.dev/theokit/reference/ModelParameterDefinition

Per-model parameter definition discovered from `Theokit.models.list()`.

# `ModelParameterDefinition`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-model parameter definition discovered from `Theokit.models.list()`.

## Signature

```ts
interface ModelParameterDefinition { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/theokit.ts:17`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/theokit.ts#L17)

---

# ModelParameterValue

Source: https://docs.usetheo.dev/theokit/reference/ModelParameterValue

One slot in a ModelSelection.params array.

# `ModelParameterValue`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

One slot in a ModelSelection.params array.

## Signature

```ts
interface ModelParameterValue { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent-prims.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent-prims.ts#L19)

---

# ModelSelection

Source: https://docs.usetheo.dev/theokit/reference/ModelSelection

Identifies a model plus optional per-model parameters (e.g. reasoning effort).

# `ModelSelection`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Identifies a model plus optional per-model parameters (e.g. reasoning effort).

Use `Theokit.models.list()` to discover valid ids and parameter definitions.

## Signature

```ts
interface ModelSelection { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent-prims.ts:31`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent-prims.ts#L31)

---

# ModelVariant

Source: https://docs.usetheo.dev/theokit/reference/ModelVariant

Preset variant for a model — pre-filled parameter combinations.

# `ModelVariant`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Preset variant for a model — pre-filled parameter combinations.

## Signature

```ts
interface ModelVariant { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/theokit.ts:28`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/theokit.ts#L28)

---

# NamedScorer

Source: https://docs.usetheo.dev/theokit/reference/NamedScorer

A named scorer — produced by every `Scorers.*` factory.

# `NamedScorer`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A named scorer — produced by every `Scorers.*` factory.

## Signature

```ts
interface NamedScorer { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:47`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L47)

---

# NetworkError

Source: https://docs.usetheo.dev/theokit/reference/NetworkError

Service unavailable, timeout, transport-level failure.

# `NetworkError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Service unavailable, timeout, transport-level failure.

## Signature

```ts
class NetworkError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:248`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L248)

---

# NoopMemoryProvider

Source: https://docs.usetheo.dev/theokit/reference/NoopMemoryProvider

SE36 — `NoopMemoryProvider.create` replaces `createNoopMemoryProvider` (ADR 0015).

# `NoopMemoryProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `NoopMemoryProvider.create` replaces `createNoopMemoryProvider` (ADR 0015).

## Signature

```ts
class NoopMemoryProvider {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider-noop.ts:112`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider-noop.ts#L112)

---

# NormalizedJsonSchema

Source: https://docs.usetheo.dev/theokit/reference/NormalizedJsonSchema

The internal JSON-Schema shape the synthetic `output` tool consumes.

# `NormalizedJsonSchema`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The internal JSON-Schema shape the synthetic `output` tool consumes.

## Signature

```ts
type NormalizedJsonSchema = Record;
```

## Kind

`type`

## Source

[`packages/sdk/src/schema-normalizer.ts:18`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/schema-normalizer.ts#L18)

---

# normalizeSchema

Source: https://docs.usetheo.dev/theokit/reference/normalizeSchema

_No description available._

# `normalizeSchema`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function normalizeSchema(schema: unknown): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/schema-normalizer.ts:56`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/schema-normalizer.ts#L56)

---

# normalizeUsage

Source: https://docs.usetheo.dev/theokit/reference/normalizeUsage

_No description available._

# `normalizeUsage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function normalizeUsage(rawUsage: unknown, opts: unknown): TokenUsage
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/budget/normalize-usage.ts:80`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/normalize-usage.ts#L80)

---

# OAuthTransaction

Source: https://docs.usetheo.dev/theokit/reference/OAuthTransaction

Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie

# `OAuthTransaction`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
(cookie-state pattern). Expires within 10 minutes per invariant.

## Signature

```ts
interface OAuthTransaction { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/server/auth/types.ts:28`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/types.ts#L28)

---

# openSqliteResilient

Source: https://docs.usetheo.dev/theokit/reference/openSqliteResilient

_No description available._

# `openSqliteResilient`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function openSqliteResilient(options: OpenSqliteResilientOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/persistence/sqlite-open.ts:52`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/sqlite-open.ts#L52)

---

# OpenSqliteResilientOptions

Source: https://docs.usetheo.dev/theokit/reference/OpenSqliteResilientOptions

_No description available._

# `OpenSqliteResilientOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface OpenSqliteResilientOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/persistence/sqlite-open.ts:32`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/sqlite-open.ts#L32)

---

# OutputProcessorContext

Source: https://docs.usetheo.dev/theokit/reference/OutputProcessorContext

Context passed to Processor.processOutput.

# `OutputProcessorContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to Processor.processOutput.

## Signature

```ts
interface OutputProcessorContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/processors.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/processors.ts#L46)

---

# ParallelStep

Source: https://docs.usetheo.dev/theokit/reference/ParallelStep

N concurrent branches, each its own mini-step-list.

# `ParallelStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

N concurrent branches, each its own mini-step-list.

## Signature

```ts
interface ParallelStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:57`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L57)

---

# ParsedModelId

Source: https://docs.usetheo.dev/theokit/reference/ParsedModelId

Model identifier parsing (T1.2 follow-up, ADR D182 zero-config UX).

# `ParsedModelId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Model identifier parsing (T1.2 follow-up, ADR D182 zero-config UX).

SDK callers pass model strings like:
  - `"ollama/llama3.2:3b"`             → provider="ollama", name="llama3.2:3b"
  - `"anthropic/claude-3-5-sonnet"`    → provider="anthropic", name="claude-3-5-sonnet"
  - `"openrouter/meta-llama/llama-3"`  → provider="openrouter", name="meta-llama/llama-3"
  - `"claude-sonnet-4-6"`              → provider=undefined, name="claude-sonnet-4-6"

The first `/` separates the provider from the rest. Models with embedded
slashes (e.g. OpenRouter routing) keep the remainder intact. Tag suffixes
(`:latest`, `:3b`) are preserved as part of the name — Ollama expects them.

**Returns `undefined` provider** when no `/` is present so callers can
fall back to env-var detection. Empty/whitespace components are treated
as no-prefix.

Aligned with OpenClaw `extensions/ollama/src/discovery-shared.ts`
(`OLLAMA_PROVIDER_ID = "ollama"`) and Hermes `hermes_cli/providers.py`
(ALIASES table, `normalize_provider`).

Public via `@theokit/sdk/models` (M5-8).

## Signature

```ts
interface ParsedModelId { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/llm/model-identifier.ts:27`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-identifier.ts#L27)

---

# parseModelId

Source: https://docs.usetheo.dev/theokit/reference/parseModelId

_No description available._

# `parseModelId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function parseModelId(modelId: unknown): ParsedModelId
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/llm/model-identifier.ts:42`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-identifier.ts#L42)

---

# PartialToolCallUpdate

Source: https://docs.usetheo.dev/theokit/reference/PartialToolCallUpdate

Tool call arguments streaming in incrementally.

# `PartialToolCallUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Tool call arguments streaming in incrementally.

## Signature

```ts
interface PartialToolCallUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:63`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L63)

---

# PermissionAction

Source: https://docs.usetheo.dev/theokit/reference/PermissionAction

`PermissionEngine` — first-match permission rules for tool invocations.

# `PermissionAction`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`PermissionEngine` — first-match permission rules for tool invocations.

Evaluates a tool name (and optional arguments, #55) against an ordered list
of rules. First matching rule wins; when no rule matches the `defaultAction`
is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
engine that cannot positively allow must not silently allow. Opt back into
the previous fail-open behavior with `{ defaultAction: "allow" }`.

## Signature

```ts
type PermissionAction
```

## Kind

`type`

## Source

[`packages/sdk/src/permission-engine.ts:11`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-engine.ts#L11)

---

# PermissionEngine

Source: https://docs.usetheo.dev/theokit/reference/PermissionEngine

_No description available._

# `PermissionEngine`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class PermissionEngine {
  evaluate(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/permission-engine.ts:115`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-engine.ts#L115)

---

# PermissionEngineOptions

Source: https://docs.usetheo.dev/theokit/reference/PermissionEngineOptions

Options for PermissionEngine.

# `PermissionEngineOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for PermissionEngine.

## Signature

```ts
interface PermissionEngineOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/permission-engine.ts:93`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-engine.ts#L93)

---

# PermissionGate

Source: https://docs.usetheo.dev/theokit/reference/PermissionGate

SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape). Invoked ONLY

# `PermissionGate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE1 — the enriched `canUseTool` gate (the Anthropic-parity shape). Invoked ONLY
on an `"ask"` verdict, it receives the tool name, its input args, and the run
PermissionGateContext, and resolves to allow/deny. May be async (a real
gate can prompt a human — the `pre_tool_call` seam awaits it).

## Signature

```ts
type PermissionGate
```

## Kind

`type`

## Source

[`packages/sdk/src/permission-plugin.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-plugin.ts#L44)

---

# PermissionGateContext

Source: https://docs.usetheo.dev/theokit/reference/PermissionGateContext

SE1 — context passed to the PermissionGate. Intentionally minimal for

# `PermissionGateContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE1 — context passed to the PermissionGate. Intentionally minimal for
SE1; `agentId`/`runId` (for audit logging) are a documented follow-up — they are
available on the raw `pre_tool_call` context and can be threaded in a later slice.

## Signature

```ts
interface PermissionGateContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/permission-plugin.ts:21`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-plugin.ts#L21)

---

# PermissionGateDecision

Source: https://docs.usetheo.dev/theokit/reference/PermissionGateDecision

SE1 — the resolution of an `'ask'` verdict by the host gate. Fail-closed: an

# `PermissionGateDecision`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE1 — the resolution of an `"ask"` verdict by the host gate. Fail-closed: an
absent gate, a throwing gate, and a `"deny"` decision all block. Arg rewrite
(`updatedInput`) is intentionally NOT supported yet — the `pre_tool_call` seam
is veto-only (`{ block, message }`); a future enhancement can extend it.

## Signature

```ts
type PermissionGateDecision
```

## Kind

`type`

## Source

[`packages/sdk/src/permission-plugin.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-plugin.ts#L34)

---

# PermissionMode

Source: https://docs.usetheo.dev/theokit/reference/PermissionMode

SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.

# `PermissionMode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE1 — a per-run permission MODE that adjusts the rule-engine verdict globally.
A PURE post-processor of the verdict (no tool-safety metadata needed, so it fits
a bring-your-own-tools runtime). Grounded in OpenCode (plan agent = deny-all,
`dangerously-skip-permissions`) + Codex (`AskForApproval`: `OnRequest` default,
`Never`, `UnlessTrusted`). See applyMode for the exact table.

- `default` — verdict as-is (rules decide; unmatched ⇒ `ask`, fail-closed).
- `plan` — read-only: `allow` rules pass, everything else ⇒ `deny` (mutations blocked).
  NOTE: `plan` gates on the resolved verdict, so an engine configured with
  `{ defaultAction: "allow" }` still yields `allow` for UNMATCHED calls under
  `plan` — pair `plan` with the default fail-closed engine (`defaultAction: "ask"`)
  for full read-only behavior.
- `acceptEdits` — auto-approve the UNMATCHED verdict, but STILL honor an explicit
  `ask` rule (a caller gates a risky tool with an ask rule). Codex `UnlessTrusted`.
- `bypass` (alias `bypassPermissions`, the Anthropic-exact name) — everything ⇒
  `allow` EXCEPT an explicit `deny` rule. Never asks. OpenCode
  `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.

## Signature

```ts
type PermissionMode
```

## Kind

`type`

## Source

[`packages/sdk/src/permission-engine.ts:32`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-engine.ts#L32)

---

# PermissionPlugin

Source: https://docs.usetheo.dev/theokit/reference/PermissionPlugin

SE36 — `PermissionPlugin.create` replaces `createPermissionPlugin` (ADR 0015).

# `PermissionPlugin`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `PermissionPlugin.create` replaces `createPermissionPlugin` (ADR 0015).

## Signature

```ts
class PermissionPlugin {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/permission-plugin.ts:144`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-plugin.ts#L144)

---

# PermissionPluginOptions

Source: https://docs.usetheo.dev/theokit/reference/PermissionPluginOptions

Options for createPermissionPlugin.

# `PermissionPluginOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for createPermissionPlugin.

## Signature

```ts
interface PermissionPluginOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/permission-plugin.ts:51`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-plugin.ts#L51)

---

# PermissionRule

Source: https://docs.usetheo.dev/theokit/reference/PermissionRule

_No description available._

# `PermissionRule`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface PermissionRule { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/permission-engine.ts:78`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/permission-engine.ts#L78)

---

# PerScorerStats

Source: https://docs.usetheo.dev/theokit/reference/PerScorerStats

Per-scorer breakdown computed across all rows.

# `PerScorerStats`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-scorer breakdown computed across all rows.

## Signature

```ts
interface PerScorerStats { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:153`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L153)

---

# PersonalityPreset

Source: https://docs.usetheo.dev/theokit/reference/PersonalityPreset

Resolved personality preset surfaced via SDKAgent.usePersonality

# `PersonalityPreset`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Resolved personality preset surfaced via SDKAgent.usePersonality
(Hermes #26, ADRs D160-D169). Re-declared here so the public DTS bundle
never crosses the `internal/` path boundary. The implementation type in
`internal/personality/types.ts` is structurally identical.

## Signature

```ts
interface PersonalityPreset { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:886`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L886)

---

# Plugin

Source: https://docs.usetheo.dev/theokit/reference/Plugin

SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015). Const-companion (the `Plugin` type alias blocks a class of the same name); `create` is the generic `d

# `Plugin`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Plugin.create` replaces `definePlugin` (ADR 0015). Const-companion (the `Plugin` type alias blocks a class of the same name); `create` is the generic `definePlugin`.

## Signature

```ts
type Plugin
```

## Kind

`type`

## Source

[`packages/sdk/src/internal/plugins/types.ts:171`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L171)

---

# PluginContext

Source: https://docs.usetheo.dev/theokit/reference/PluginContext

_No description available._

# `PluginContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface PluginContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/plugins/types.ts:142`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L142)

---

# PluginsSettings

Source: https://docs.usetheo.dev/theokit/reference/PluginsSettings

Plugins configuration accepted by `Agent.create()` via

# `PluginsSettings`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Plugins configuration accepted by `Agent.create()` via
AgentOptions.plugins.

## Signature

```ts
interface PluginsSettings { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/providers.ts:78`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L78)

---

# PostAssistantReplyContext

Source: https://docs.usetheo.dev/theokit/reference/PostAssistantReplyContext

Context passed to `post_assistant_reply` hook handlers (ADR D145).

# `PostAssistantReplyContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to `post_assistant_reply` hook handlers (ADR D145).
Fire-and-forget — exceptions are caught and surfaced to stderr; the
caller's `wait()` never blocks on this dispatch.

## Signature

```ts
interface PostAssistantReplyContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/plugins/types.ts:126`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L126)

---

# preflightCheck

Source: https://docs.usetheo.dev/theokit/reference/preflightCheck

_No description available._

# `preflightCheck`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function preflightCheck(name: string, estimatedUsd: number): void
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/budget/enforcement.ts:29`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/enforcement.ts#L29)

---

# PreToolCallContext

Source: https://docs.usetheo.dev/theokit/reference/PreToolCallContext

_No description available._

# `PreToolCallContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface PreToolCallContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/plugins/types.ts:33`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L33)

---

# PreToolCallDecision

Source: https://docs.usetheo.dev/theokit/reference/PreToolCallDecision

_No description available._

# `PreToolCallDecision`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface PreToolCallDecision { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/plugins/types.ts:47`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L47)

---

# PreUserSendContext

Source: https://docs.usetheo.dev/theokit/reference/PreUserSendContext

Context passed to `pre_user_send` hook handlers (ADR D145).

# `PreUserSendContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to `pre_user_send` hook handlers (ADR D145).

## Signature

```ts
interface PreUserSendContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/plugins/types.ts:98`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L98)

---

# PreUserSendResult

Source: https://docs.usetheo.dev/theokit/reference/PreUserSendResult

Optional result returned by `pre_user_send` handlers. The agent loop

# `PreUserSendResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Optional result returned by `pre_user_send` handlers. The agent loop
concatenates `recalledContext` from all handlers and injects it as a
`<memory-context>...</memory-context>` block before the user prompt.

## Signature

```ts
interface PreUserSendResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/plugins/types.ts:115`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/plugins/types.ts#L115)

---

# Processor

Source: https://docs.usetheo.dev/theokit/reference/Processor

A guardrail processor. Provide `processInput` (runs before the LLM) and/or

# `Processor`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A guardrail processor. Provide `processInput` (runs before the LLM) and/or
`processOutput` (runs on the final text). A processor's `strategy` (block /
rewrite / redact / warn) is expressed via the ProcessorControls:
return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
to report without blocking. The core ships no strategy enum — strategies are a
processor-level convention over these primitives.

## Signature

```ts
interface Processor { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/processors.ts:62`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/processors.ts#L62)

---

# ProcessorControls

Source: https://docs.usetheo.dev/theokit/reference/ProcessorControls

Controls available to a processor while it runs: `abort()` stops the run with

# `ProcessorControls`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Controls available to a processor while it runs: `abort()` stops the run with
a tripwire; `warn()` reports a non-blocking violation and continues.

## Signature

```ts
interface ProcessorControls { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/processors.ts:31`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/processors.ts#L31)

---

# ProcessorTripwire

Source: https://docs.usetheo.dev/theokit/reference/ProcessorTripwire

The tripwire detail attached to RunResult.tripwire when a processor

# `ProcessorTripwire`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The tripwire detail attached to RunResult.tripwire when a processor
aborts, and carried by the `tripwire` run-event.

## Signature

```ts
interface ProcessorTripwire { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/processors.ts:89`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/processors.ts#L89)

---

# ProcessorViolation

Source: https://docs.usetheo.dev/theokit/reference/ProcessorViolation

A policy violation surfaced to a processor's Processor.onViolation

# `ProcessorViolation`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A policy violation surfaced to a processor's Processor.onViolation
callback — on `abort()` (blocking) AND on `warn()` (non-blocking).

## Signature

```ts
interface ProcessorViolation { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/processors.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/processors.ts#L19)

---

# ProjectInstructionFile

Source: https://docs.usetheo.dev/theokit/reference/ProjectInstructionFile

One discovered project-instruction file.

# `ProjectInstructionFile`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

One discovered project-instruction file.

## Signature

```ts
interface ProjectInstructionFile { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:12`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L12)

---

# ProjectInstructions

Source: https://docs.usetheo.dev/theokit/reference/ProjectInstructions

Result of readProjectInstructions.

# `ProjectInstructions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of readProjectInstructions.

## Signature

```ts
interface ProjectInstructions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L20)

---

# ProjectInstructionScope

Source: https://docs.usetheo.dev/theokit/reference/ProjectInstructionScope

How discovered instruction files are reduced to a single `content` string.

# `ProjectInstructionScope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

How discovered instruction files are reduced to a single `content` string.

## Signature

```ts
type ProjectInstructionScope
```

## Kind

`type`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:9`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L9)

---

# Provider

Source: https://docs.usetheo.dev/theokit/reference/Provider

SE36 — uniform namespace API. `Provider.create` replaces `defineProvider` (ADR 0015).

# `Provider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — uniform namespace API. `Provider.create` replaces `defineProvider` (ADR 0015).

## Signature

```ts
class Provider {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/define-provider.ts:55`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/define-provider.ts#L55)

---

# ProviderCapability

Source: https://docs.usetheo.dev/theokit/reference/ProviderCapability

Capability slot a provider can fulfill.

# `ProviderCapability`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Capability slot a provider can fulfill.

## Signature

```ts
type ProviderCapability
```

## Kind

`type`

## Source

[`packages/sdk/src/types/providers.ts:6`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L6)

---

# ProviderProfile

Source: https://docs.usetheo.dev/theokit/reference/ProviderProfile

_No description available._

# `ProviderProfile`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface ProviderProfile { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/providers/types.ts:27`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/providers/types.ts#L27)

---

# ProviderRoute

Source: https://docs.usetheo.dev/theokit/reference/ProviderRoute

A single user-declared routing rule. Maps a capability to a provider, and

# `ProviderRoute`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A single user-declared routing rule. Maps a capability to a provider, and
optionally pins a specific model.

## Signature

```ts
interface ProviderRoute { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/providers.ts:14`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L14)

---

# ProviderRoutingSettings

Source: https://docs.usetheo.dev/theokit/reference/ProviderRoutingSettings

Provider routing configuration accepted by `Agent.create()` via

# `ProviderRoutingSettings`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Provider routing configuration accepted by `Agent.create()` via
AgentOptions.providers.

## Signature

```ts
interface ProviderRoutingSettings { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/providers.ts:37`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L37)

---

# provisionRepo

Source: https://docs.usetheo.dev/theokit/reference/provisionRepo

_No description available._

# `provisionRepo`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function provisionRepo(opts: ProvisionRepoOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/sandbox/provision.ts:76`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/provision.ts#L76)

---

# ProvisionRepoOptions

Source: https://docs.usetheo.dev/theokit/reference/ProvisionRepoOptions

Options for provisionRepo.

# `ProvisionRepoOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for provisionRepo.

## Signature

```ts
interface ProvisionRepoOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/sandbox/provision.ts:42`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/provision.ts#L42)

---

# RateLimitError

Source: https://docs.usetheo.dev/theokit/reference/RateLimitError

Too many requests or usage limits exceeded.

# `RateLimitError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Too many requests or usage limits exceeded.

## Signature

```ts
class RateLimitError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:189`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L189)

---

# readJsonlIds

Source: https://docs.usetheo.dev/theokit/reference/readJsonlIds

_No description available._

# `readJsonlIds`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function readJsonlIds(path: string, keyFn: unknown): Set
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/persistence/jsonl.ts:101`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/jsonl.ts#L101)

---

# readProjectInstructions

Source: https://docs.usetheo.dev/theokit/reference/readProjectInstructions

`@theokit/sdk/project` — hierarchical project-instruction reader/writer.

# `readProjectInstructions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/project` — hierarchical project-instruction reader/writer.

`readProjectInstructions(cwd, options?)` walks up from `cwd` collecting a
configurable instruction file (default `THEO.md`), returning the found files
nearest-first plus a `scope`-selected `content` (`nearest` | `merged`). It
never throws. `writeProjectInstructions(cwd, content, options?)` writes the
file atomically (temp + fsync + rename) and fails loud on write errors.

Composes the SDK's own hardened `walkUpForFile` discovery + the atomic
`replaceFileAtomic` writer — so consumers read/write project instructions
with one import instead of hand-rolling the walk-up + atomic write.

## Signature

```ts
function readProjectInstructions(cwd: string, options: ReadProjectInstructionsOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:64`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L64)

---

# ReadProjectInstructionsOptions

Source: https://docs.usetheo.dev/theokit/reference/ReadProjectInstructionsOptions

Options for readProjectInstructions.

# `ReadProjectInstructionsOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for readProjectInstructions.

## Signature

```ts
interface ReadProjectInstructionsOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:32`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L32)

---

# RecordSessionSummaryArgs

Source: https://docs.usetheo.dev/theokit/reference/RecordSessionSummaryArgs

Arguments for `MemoryProvider.recordSessionSummary(...)`

# `RecordSessionSummaryArgs`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Arguments for `MemoryProvider.recordSessionSummary(...)`
(SDK 2.0 Phase 1 physical Stage 3 prep — iter 27).

The "session summary" is the markdown that gets written to disk
after a finished run + indexed under `corpus="sessions"`. This
port method lets sdk-core's `post-run-lifecycle.ts` delegate the
write to the provider instead of importing
`internal/memory/storage/session-summary-writer.ts` directly.

## Signature

```ts
interface RecordSessionSummaryArgs { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/memory/memory-provider.ts:67`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/memory/memory-provider.ts#L67)

---

# RepoProvisionError

Source: https://docs.usetheo.dev/theokit/reference/RepoProvisionError

Raised when cloning or checking out a repo fails. Carries the `instanceId`

# `RepoProvisionError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Raised when cloning or checking out a repo fails. Carries the `instanceId`
so a batch run can attribute the failure to the offending dataset row.

## Signature

```ts
class RepoProvisionError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/sandbox/provision.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/provision.ts#L25)

---

# RequestOptions

Source: https://docs.usetheo.dev/theokit/reference/RequestOptions

_No description available._

# `RequestOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface RequestOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/message-bus.ts:12`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/message-bus.ts#L12)

---

# ResilientSqliteDb

Source: https://docs.usetheo.dev/theokit/reference/ResilientSqliteDb

Minimal SQLite handle surface every driver (`better-sqlite3`) exposes.

# `ResilientSqliteDb`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Minimal SQLite handle surface every driver (`better-sqlite3`) exposes.

## Signature

```ts
interface ResilientSqliteDb { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/persistence/sqlite-open.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/sqlite-open.ts#L25)

---

# ResolvedProviderRoute

Source: https://docs.usetheo.dev/theokit/reference/ResolvedProviderRoute

Resolved routing decision returned by `agent.providers.routes()`. Public and

# `ResolvedProviderRoute`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Resolved routing decision returned by `agent.providers.routes()`. Public and
secret-free by design — safe to log.

## Signature

```ts
interface ResolvedProviderRoute { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/providers.ts:89`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L89)

---

# resolveFilesystem

Source: https://docs.usetheo.dev/theokit/reference/resolveFilesystem

_No description available._

# `resolveFilesystem`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function resolveFilesystem(provider: FilesystemProvider, ctx: Ctx): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/filesystem/types.ts:184`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L184)

---

# resolveModelCapabilities

Source: https://docs.usetheo.dev/theokit/reference/resolveModelCapabilities

`@theokit/sdk/models` — per-model capability catalog.

# `resolveModelCapabilities`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/models` — per-model capability catalog.

`resolveModelCapabilities(modelId)` returns a model's capability flags +
`maxContextTokens`/`maxOutputTokens` from a static, OFFLINE catalog (pure,
sync, no network). It strips routing prefixes (`openrouter/`/`vertex/`/
`bedrock/`) and OpenRouter `:variant` suffixes before lookup; unknown models
get conservative defaults. The `maxContextTokens` value feeds the pre-call
`shouldCompact` helper on `@theokit/sdk/compaction`.

Also exposes model-id parsing + UI label helpers (M5-8): `parseModelId`,
`humanizeModelName`, `toModelOption`.

## Signature

```ts
function resolveModelCapabilities(modelId: string): ModelCapabilities
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/llm/model-capabilities.ts:309`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-capabilities.ts#L309)

---

# Retry

Source: https://docs.usetheo.dev/theokit/reference/Retry

SE36 — `Retry.create` replaces `withRetry` (ADR 0015 / ADR-P2). NOTE: `withRetry` is an

# `Retry`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Retry.create` replaces `withRetry` (ADR 0015 / ADR-P2). NOTE: `withRetry` is an
EXECUTOR, not a constructor — `Retry.create(fn, opts)` RUNS `fn` with retry and resolves to
its result (`Promise<T>`), not a `Retry` instance. The `.create` name is the uniformity
mandate; the executor semantics are the documented, accepted awkwardness.

## Signature

```ts
class Retry {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/retry.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/retry.ts#L20)

---

# RetryOptions

Source: https://docs.usetheo.dev/theokit/reference/RetryOptions

Options for withRetry. All fields optional; sensible defaults applied.

# `RetryOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for withRetry. All fields optional; sensible defaults applied.

## Signature

```ts
interface RetryOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/retry/with-retry.ts:16`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/retry/with-retry.ts#L16)

---

# RetryPolicy

Source: https://docs.usetheo.dev/theokit/reference/RetryPolicy

D237 — retry policy applied per fn/agent step.

# `RetryPolicy`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

D237 — retry policy applied per fn/agent step.

## Signature

```ts
interface RetryPolicy { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:111`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L111)

---

# Run

Source: https://docs.usetheo.dev/theokit/reference/Run

Handle to a single prompt submission.

# `Run`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Handle to a single prompt submission.

## Signature

```ts
interface Run { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:521`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L521)

---

# RunCompactBoundaryEvent

Source: https://docs.usetheo.dev/theokit/reference/RunCompactBoundaryEvent

The conversation crossed a compaction boundary (history was summarized).

# `RunCompactBoundaryEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The conversation crossed a compaction boundary (history was summarized).

## Signature

```ts
interface RunCompactBoundaryEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:106`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L106)

---

# RunCompletionCheckEvent

Source: https://docs.usetheo.dev/theokit/reference/RunCompletionCheckEvent

SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.

# `RunCompletionCheckEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE34 — the per-send completion check (`isTaskComplete`) produced a verdict.
Emitted once, after a finished run's reply is judged against
SendOptions.completionCheck. Distinct from `task_completed` (which is
background-task/subagent lifecycle). Mirrors RunResult.completionCheck.

## Signature

```ts
interface RunCompletionCheckEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:99`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L99)

---

# RunErrorDetail

Source: https://docs.usetheo.dev/theokit/reference/RunErrorDetail

Structured error attached to a RunResult when the underlying run

# `RunErrorDetail`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Structured error attached to a RunResult when the underlying run
transitioned to `"error"` status. `message` is always present; `code` is
a stable identifier suitable for branching (e.g. `"llm_4xx"`,
`"tool_dispatch_failed"`, `"mcp_init_failed"`); `cause` is the raw error
for further inspection when available.

## Signature

```ts
interface RunErrorDetail { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:264`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L264)

---

# RunEvent

Source: https://docs.usetheo.dev/theokit/reference/RunEvent

SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.

# `RunEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE2 — typed runtime EVENT stream, ADDITIVE to the `SDKMessage` content stream.

`Run.stream()` yields `SDKMessage`s (the conversation content). `RunEvent`s are
out-of-band runtime-OBSERVABILITY signals — the model's content is unaffected —
delivered opt-in via `SendOptions.onRunEvent`. Discriminate on `type`. Mirrors
the Anthropic `SDKMessage`-union approach (rate-limit, permission-denied, task
lifecycle, compaction boundary).

The union is the forward-compatible CONTRACT (discriminate exhaustively). The
runtime EMITS every variant end-to-end: `tool_progress` + `permission_denied`
(agent-loop tool-dispatch seam), `rate_limit` (pool-aware LLM client 429 retry),
`compact_boundary` (session auto-compaction), and `task_*` (opt-in bridge from a
`Task.submit({ onRunEvent })` task's lifecycle). A consumer switching on `type`
sees the real signal.

## Signature

```ts
type RunEvent
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run-events.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L19)

---

# RunEventSink

Source: https://docs.usetheo.dev/theokit/reference/RunEventSink

SE2 — the opt-in sink for RunEvents. Supplied via `SendOptions.onRunEvent`.

# `RunEventSink`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE2 — the opt-in sink for RunEvents. Supplied via `SendOptions.onRunEvent`.
Synchronous + best-effort: a throwing sink must never break the run (the emitter
try-catches it), so keep it fast (push to a queue, don't await).

## Signature

```ts
type RunEventSink
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run-events.ts:118`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L118)

---

# RunGitInfo

Source: https://docs.usetheo.dev/theokit/reference/RunGitInfo

Git metadata attached to cloud runs.

# `RunGitInfo`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Git metadata attached to cloud runs.

## Signature

```ts
interface RunGitInfo { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L44)

---

# RunOperation

Source: https://docs.usetheo.dev/theokit/reference/RunOperation

Operations that may or may not be supported on a given Run, or on

# `RunOperation`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Operations that may or may not be supported on a given Run, or on
its parent agent.

Runtime-specific availability — query at runtime with `run.supports(op)` and
read the human reason via `run.unsupportedReason(op)`.

## Signature

```ts
type RunOperation
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L25)

---

# RunPermissionDeniedEvent

Source: https://docs.usetheo.dev/theokit/reference/RunPermissionDeniedEvent

A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),

# `RunPermissionDeniedEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A tool call was DENIED before dispatch — by the permission gate/plugin (SE1),
an operator file-hook `preToolUse`, or the fork tool-whitelist. `source`
discriminates which. `toolCallId` joins the event to the tool-call log.

## Signature

```ts
interface RunPermissionDeniedEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:62`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L62)

---

# RunRateLimitEvent

Source: https://docs.usetheo.dev/theokit/reference/RunRateLimitEvent

The provider returned a rate-limit (HTTP 429); the loop will back off + retry.

# `RunRateLimitEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The provider returned a rate-limit (HTTP 429); the loop will back off + retry.

## Signature

```ts
interface RunRateLimitEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:49`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L49)

---

# RunResult

Source: https://docs.usetheo.dev/theokit/reference/RunResult

Terminal result of a Run.

# `RunResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Terminal result of a Run.

## Signature

```ts
interface RunResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:95`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L95)

---

# RunStatus

Source: https://docs.usetheo.dev/theokit/reference/RunStatus

Lifecycle status of a Run.

# `RunStatus`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Lifecycle status of a Run.

## Signature

```ts
type RunStatus
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run.ts:14`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L14)

---

# RunTaskCompletedEvent

Source: https://docs.usetheo.dev/theokit/reference/RunTaskCompletedEvent

A background task/subagent finished.

# `RunTaskCompletedEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A background task/subagent finished.

## Signature

```ts
interface RunTaskCompletedEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:87`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L87)

---

# RunTaskStartedEvent

Source: https://docs.usetheo.dev/theokit/reference/RunTaskStartedEvent

A background task/subagent started.

# `RunTaskStartedEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A background task/subagent started.

## Signature

```ts
interface RunTaskStartedEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:73`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L73)

---

# RunTaskUpdatedEvent

Source: https://docs.usetheo.dev/theokit/reference/RunTaskUpdatedEvent

A background task/subagent changed state.

# `RunTaskUpdatedEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A background task/subagent changed state.

## Signature

```ts
interface RunTaskUpdatedEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:80`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L80)

---

# RunToCompletionOptions

Source: https://docs.usetheo.dev/theokit/reference/RunToCompletionOptions

Options for SDKAgent.runToCompletion (M1 Phase 3 — continuation driver).

# `RunToCompletionOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for SDKAgent.runToCompletion (M1 Phase 3 — continuation driver).

## Signature

```ts
interface RunToCompletionOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:197`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L197)

---

# RunToCompletionResult

Source: https://docs.usetheo.dev/theokit/reference/RunToCompletionResult

Result of SDKAgent.runToCompletion.

# `RunToCompletionResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of SDKAgent.runToCompletion.

## Signature

```ts
interface RunToCompletionResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:224`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L224)

---

# RunToolProgressEvent

Source: https://docs.usetheo.dev/theokit/reference/RunToolProgressEvent

A tool call is being dispatched (before its result).

# `RunToolProgressEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A tool call is being dispatched (before its result).

## Signature

```ts
interface RunToolProgressEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:42`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L42)

---

# RunTripwireEvent

Source: https://docs.usetheo.dev/theokit/reference/RunTripwireEvent

SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.

# `RunTripwireEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
Delivered via SendOptions.onRunEvent (mirrors the `RunResult.tripwire`
surfaced on `wait()`).

## Signature

```ts
interface RunTripwireEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run-events.ts:35`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run-events.ts#L35)

---

# RunUntilIterator

Source: https://docs.usetheo.dev/theokit/reference/RunUntilIterator

Return type of import('../internal/runtime/local-agent/local-agent.js').LocalAgent.runUntil.

# `RunUntilIterator`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Return type of import("../internal/runtime/local-agent/local-agent.js").LocalAgent.runUntil.
Extracted so the LocalAgent method signature stays a single line (G8 LoC budget).

## Signature

```ts
type RunUntilIterator = AsyncGenerator;
```

## Kind

`type`

## Source

[`packages/sdk/src/types/goal-events.ts:68`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/goal-events.ts#L68)

---

# SandboxBackend

Source: https://docs.usetheo.dev/theokit/reference/SandboxBackend

_No description available._

# `SandboxBackend`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class SandboxBackend {
  execute(...): ...
  glob(...): ...
  grep(...): ...
  listDir(...): ...
  readFile(...): ...
  truncateOutput(...): ...
  uploadFile(...): ...
  writeFile(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/sandbox/types.ts:49`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/types.ts#L49)

---

# SandboxConfig

Source: https://docs.usetheo.dev/theokit/reference/SandboxConfig

_No description available._

# `SandboxConfig`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SandboxConfig { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/sandbox/types.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/types.ts#L20)

---

# SandboxNotAvailableError

Source: https://docs.usetheo.dev/theokit/reference/SandboxNotAvailableError

_No description available._

# `SandboxNotAvailableError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class SandboxNotAvailableError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/sandbox/types.ts:41`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/types.ts#L41)

---

# SandboxSecurityError

Source: https://docs.usetheo.dev/theokit/reference/SandboxSecurityError

_No description available._

# `SandboxSecurityError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class SandboxSecurityError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/sandbox/types.ts:33`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sandbox/types.ts#L33)

---

# sanitizeIdentifier

Source: https://docs.usetheo.dev/theokit/reference/sanitizeIdentifier

Public path-safety primitives.

# `sanitizeIdentifier`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public path-safety primitives.

Thin re-export of the canonical implementation in
`internal/security/path-guard.ts`. Splitting this into its own
top-level module gives `rollup-plugin-dts` a clean boundary when
bundling declarations — without it, including the path-guard module
via the main barrel propagates a cascade of transitive imports that
surface a known-spurious "ForkOptions not exported" error from
`types/agent.ts` (dynamic-import-type quirk in rollup-plugin-dts).

See `docs.md → Security — path traversal + TOCTOU` for the full
primitive reference. Public from v1.x.

## Signature

```ts
function sanitizeIdentifier(input: string, options: unknown): string
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/security/path-guard.ts:386`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/security/path-guard.ts#L386)

---

# SanitizeOptions

Source: https://docs.usetheo.dev/theokit/reference/SanitizeOptions

Options for sanitizeToolInput. Trim is the only default-on rung — coercion and JSON

# `SanitizeOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for sanitizeToolInput. Trim is the only default-on rung — coercion and JSON
repair change a value's representation, so they are opt-in (the SDK's "values are strings; Zod
coerces" boundary; see `define-tool.ts` doc-comment).

## Signature

```ts
interface SanitizeOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/sanitize/types.ts:10`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sanitize/types.ts#L10)

---

# SanitizeResult

Source: https://docs.usetheo.dev/theokit/reference/SanitizeResult

Result of sanitizeToolInput. `value` is the sanitized copy; `changed` is true when any

# `SanitizeResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of sanitizeToolInput. `value` is the sanitized copy; `changed` is true when any
value was altered; `notes` records a human-readable line per change (for logging/debugging).

## Signature

```ts
interface SanitizeResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/sanitize/types.ts:37`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sanitize/types.ts#L37)

---

# sanitizeToolInput

Source: https://docs.usetheo.dev/theokit/reference/sanitizeToolInput

_No description available._

# `sanitizeToolInput`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function sanitizeToolInput(input: Record, options: SanitizeOptions): SanitizeResult
```

## Kind

`function`

## Source

[`packages/sdk/src/sanitize/sanitize-tool-input.ts:87`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/sanitize/sanitize-tool-input.ts#L87)

---

# scopedConversationId

Source: https://docs.usetheo.dev/theokit/reference/scopedConversationId

_No description available._

# `scopedConversationId`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function scopedConversationId(scope: SessionScope, id: string): string
```

## Kind

`function`

## Source

[`packages/sdk/src/session-scope.ts:25`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/session-scope.ts#L25)

---

# Score

Source: https://docs.usetheo.dev/theokit/reference/Score

Outcome of a single scoring decision. `score` in [0, 1]; the runner clamps.

# `Score`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Outcome of a single scoring decision. `score` in [0, 1]; the runner clamps.

## Signature

```ts
interface Score { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:35`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L35)

---

# Scorer

Source: https://docs.usetheo.dev/theokit/reference/Scorer

Scorer signature (D207). Returns `Score` synchronously OR via Promise —

# `Scorer`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Scorer signature (D207). Returns `Score` synchronously OR via Promise —
the runner always awaits.

## Signature

```ts
type Scorer
```

## Kind

`type`

## Source

[`packages/sdk/src/types/eval.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L44)

---

# Scorers

Source: https://docs.usetheo.dev/theokit/reference/Scorers

_No description available._

# `Scorers`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
const Scorers
```

## Kind

`constant`

## Source

[`packages/sdk/src/scorers.ts:58`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/scorers.ts#L58)

---

# SDKAgent

Source: https://docs.usetheo.dev/theokit/reference/SDKAgent

Handle returned by `Agent.create()` and `Agent.resume()`.

# `SDKAgent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Handle returned by `Agent.create()` and `Agent.resume()`.

## Signature

```ts
interface SDKAgent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:684`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L684)

---

# SDKAgentInfo

Source: https://docs.usetheo.dev/theokit/reference/SDKAgentInfo

Metadata returned by `Agent.list()` and `Agent.get()`.

# `SDKAgentInfo`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Metadata returned by `Agent.list()` and `Agent.get()`.

## Signature

```ts
type SDKAgentInfo
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:915`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L915)

---

# SDKAgentPlugins

Source: https://docs.usetheo.dev/theokit/reference/SDKAgentPlugins

Public plugin listing handle exposed as `agent.plugins`. Populated when

# `SDKAgentPlugins`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public plugin listing handle exposed as `agent.plugins`. Populated when
`settingSources` includes `"plugins"` OR when `plugins.enabled` is set
on the agent options.

## Signature

```ts
interface SDKAgentPlugins { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:163`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L163)

---

# SDKAgentSkillDetail

Source: https://docs.usetheo.dev/theokit/reference/SDKAgentSkillDetail

A skill resolved WITH its body, returned by SDKAgentSkills.get. Unlike

# `SDKAgentSkillDetail`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A skill resolved WITH its body, returned by SDKAgentSkills.get. Unlike
SystemPromptSkillRef (name + description only), this carries the full
`instructions` — read from the SKILL.md for filesystem skills or the inline
`createSkill` body.

## Signature

```ts
interface SDKAgentSkillDetail { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:126`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L126)

---

# SDKAgentSkills

Source: https://docs.usetheo.dev/theokit/reference/SDKAgentSkills

_No description available._

# `SDKAgentSkills`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SDKAgentSkills { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:134`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L134)

---

# SDKArtifact

Source: https://docs.usetheo.dev/theokit/reference/SDKArtifact

Artifact produced inside an agent's workspace. Cloud-only.

# `SDKArtifact`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Artifact produced inside an agent's workspace. Cloud-only.

## Signature

```ts
interface SDKArtifact { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:673`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L673)

---

# SDKAssistantMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKAssistantMessage

Model text output for this run.

# `SDKAssistantMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Model text output for this run.

## Signature

```ts
interface SDKAssistantMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:56`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L56)

---

# SDKContextManager

Source: https://docs.usetheo.dev/theokit/reference/SDKContextManager

Public context manager handle exposed as `agent.context`.

# `SDKContextManager`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public context manager handle exposed as `agent.context`.

## Signature

```ts
interface SDKContextManager { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/context.ts:96`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/context.ts#L96)

---

# SDKImage

Source: https://docs.usetheo.dev/theokit/reference/SDKImage

Either a remote URL or inline base64 payload.

# `SDKImage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Either a remote URL or inline base64 payload.

## Signature

```ts
type SDKImage
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run.ts:285`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L285)

---

# SDKImageDimension

Source: https://docs.usetheo.dev/theokit/reference/SDKImageDimension

Dimensions of an inline image attachment.

# `SDKImageDimension`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Dimensions of an inline image attachment.

## Signature

```ts
interface SDKImageDimension { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:275`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L275)

---

# SDKMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKMessage

Discriminated union of all stream events. Discriminate on `type`.

# `SDKMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Discriminated union of all stream events. Discriminate on `type`.

All events include `agent_id` and `run_id`.

## Signature

```ts
type SDKMessage
```

## Kind

`type`

## Source

[`packages/sdk/src/types/messages.ts:159`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L159)

---

# SDKModel

Source: https://docs.usetheo.dev/theokit/reference/SDKModel

_No description available._

# `SDKModel`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type SDKModel = ModelListItem;
```

## Kind

`type`

## Source

[`packages/sdk/src/types/theokit.ts:51`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/theokit.ts#L51)

---

# SDKObjectDelta

Source: https://docs.usetheo.dev/theokit/reference/SDKObjectDelta

Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).

# `SDKObjectDelta`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Partial object emitted during `Agent.streamObject<T>` streaming (ADR D45).
`partial` is `DeepPartial<z.infer<T>>` at the typed iterator level but
erased to `unknown` here because SDKMessage union is non-generic.

## Signature

```ts
interface SDKObjectDelta { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:144`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L144)

---

# SDKPluginMetadata

Source: https://docs.usetheo.dev/theokit/reference/SDKPluginMetadata

Public plugin metadata returned by `agent.plugins.list()`. Mirrors the

# `SDKPluginMetadata`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public plugin metadata returned by `agent.plugins.list()`. Mirrors the
`.theokit/plugins/<name>/MANIFEST.json` allow-listed shape; never exposes
raw plugin bodies, credentials, or internal hooks.

## Signature

```ts
interface SDKPluginMetadata { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:151`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L151)

---

# SDKProvider

Source: https://docs.usetheo.dev/theokit/reference/SDKProvider

Provider catalog entry returned by `Theokit.providers.list()`.

# `SDKProvider`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Provider catalog entry returned by `Theokit.providers.list()`.

## Signature

```ts
interface SDKProvider { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/providers.ts:112`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L112)

---

# SDKProvidersManager

Source: https://docs.usetheo.dev/theokit/reference/SDKProvidersManager

Public providers manager handle exposed as `agent.providers`.

# `SDKProvidersManager`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public providers manager handle exposed as `agent.providers`.

## Signature

```ts
interface SDKProvidersManager { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/providers.ts:102`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/providers.ts#L102)

---

# SDKRepository

Source: https://docs.usetheo.dev/theokit/reference/SDKRepository

GitHub repository connected to the team. Cloud-only.

# `SDKRepository`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

GitHub repository connected to the team. Cloud-only.

## Signature

```ts
interface SDKRepository { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/theokit.ts:58`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/theokit.ts#L58)

---

# SDKRequestMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKRequestMessage

Awaiting user input or approval.

# `SDKRequestMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Awaiting user input or approval.

## Signature

```ts
interface SDKRequestMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:130`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L130)

---

# SDKStatusMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKStatusMessage

Cloud run lifecycle transitions.

# `SDKStatusMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Cloud run lifecycle transitions.

## Signature

```ts
interface SDKStatusMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:104`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L104)

---

# SDKSystemMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKSystemMessage

Init metadata. Emitted once at the start of a run.

# `SDKSystemMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Init metadata. Emitted once at the start of a run.

## Signature

```ts
interface SDKSystemMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L30)

---

# SDKTaskMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKTaskMessage

Task-level milestones and summaries.

# `SDKTaskMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Task-level milestones and summaries.

## Signature

```ts
interface SDKTaskMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:117`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L117)

---

# SDKThinkingMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKThinkingMessage

Reasoning content.

# `SDKThinkingMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Reasoning content.

## Signature

```ts
interface SDKThinkingMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:71`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L71)

---

# SDKToolUseMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKToolUseMessage

Tool invocation lifecycle event. Emitted at start with `args`, then again on

# `SDKToolUseMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Tool invocation lifecycle event. Emitted at start with `args`, then again on
completion with `result`.

Tool `args` and `result` are NOT part of the stable schema — treat as unknown.

## Signature

```ts
interface SDKToolUseMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:87`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L87)

---

# SDKUser

Source: https://docs.usetheo.dev/theokit/reference/SDKUser

Account-level user info returned by `Theokit.me()`.

# `SDKUser`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Account-level user info returned by `Theokit.me()`.

## Signature

```ts
interface SDKUser { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/theokit.ts:6`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/theokit.ts#L6)

---

# SDKUserMessage

Source: https://docs.usetheo.dev/theokit/reference/SDKUserMessage

Structured form of `agent.send()`'s message argument. Use it to send images

# `SDKUserMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Structured form of `agent.send()`'s message argument. Use it to send images
alongside text.

## Signature

```ts
interface SDKUserMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:295`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L295)

---

# SDKUserMessageEvent

Source: https://docs.usetheo.dev/theokit/reference/SDKUserMessageEvent

Echo of the user prompt for this run.

# `SDKUserMessageEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Echo of the user prompt for this run.

## Signature

```ts
interface SDKUserMessageEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L44)

---

# Security

Source: https://docs.usetheo.dev/theokit/reference/Security

_No description available._

# `Security`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class Security {
  addPattern(...): ...
  redact(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/security.ts:28`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/security.ts#L28)

---

# Semaphore

Source: https://docs.usetheo.dev/theokit/reference/Semaphore

SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015).

# `Semaphore`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Semaphore.create` replaces `createSemaphore` (ADR 0015).

## Signature

```ts
class Semaphore {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/concurrency.ts:21`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/concurrency.ts#L21)

---

# SendOptions

Source: https://docs.usetheo.dev/theokit/reference/SendOptions

Per-send overrides and callbacks.

# `SendOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Per-send overrides and callbacks.

## Signature

```ts
interface SendOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/run.ts:305`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L305)

---

# SendResponse

Source: https://docs.usetheo.dev/theokit/reference/SendResponse

_No description available._

# `SendResponse`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SendResponse { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/client/types.ts:14`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/client/types.ts#L14)

---

# SessionScope

Source: https://docs.usetheo.dev/theokit/reference/SessionScope

M3 #62 — session state scope.

# `SessionScope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

M3 #62 — session state scope.

## Signature

```ts
type SessionScope
```

## Kind

`type`

## Source

[`packages/sdk/src/session-scope.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/session-scope.ts#L22)

---

# sessionScopePrefix

Source: https://docs.usetheo.dev/theokit/reference/sessionScopePrefix

_No description available._

# `sessionScopePrefix`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function sessionScopePrefix(scope: SessionScope): string
```

## Kind

`function`

## Source

[`packages/sdk/src/session-scope.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/session-scope.ts#L30)

---

# SettingSource

Source: https://docs.usetheo.dev/theokit/reference/SettingSource

Which on-disk settings layers a local agent loads.

# `SettingSource`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Which on-disk settings layers a local agent loads.

## Signature

```ts
type SettingSource
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:28`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L28)

---

# ShareGptMessage

Source: https://docs.usetheo.dev/theokit/reference/ShareGptMessage

One ShareGPT message in a conversation. `from` identifies the role and

# `ShareGptMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

One ShareGPT message in a conversation. `from` identifies the role and
`value` carries the textual content. Tool calls live in `tool_calls`
(assistant-only) and tool results re-enter as `from: "tool"` entries.

## Signature

```ts
interface ShareGptMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/trajectory.ts:18`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/trajectory.ts#L18)

---

# ShareGptTrajectory

Source: https://docs.usetheo.dev/theokit/reference/ShareGptTrajectory

One full ShareGPT-format trajectory — a single conversation plus

# `ShareGptTrajectory`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

One full ShareGPT-format trajectory — a single conversation plus
metadata. JSONL-friendly (one trajectory per line when serialized).

## Signature

```ts
interface ShareGptTrajectory { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/trajectory.ts:36`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/trajectory.ts#L36)

---

# ShellCommand

Source: https://docs.usetheo.dev/theokit/reference/ShellCommand

Shell command executed during a run.

# `ShellCommand`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Shell command executed during a run.

## Signature

```ts
interface ShellCommand { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:34`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L34)

---

# ShellConversationTurn

Source: https://docs.usetheo.dev/theokit/reference/ShellConversationTurn

Shell turn: a command and its output.

# `ShellConversationTurn`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Shell turn: a command and its output.

## Signature

```ts
interface ShellConversationTurn { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:92`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L92)

---

# ShellOutput

Source: https://docs.usetheo.dev/theokit/reference/ShellOutput

Output of a shell command.

# `ShellOutput`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Output of a shell command.

## Signature

```ts
interface ShellOutput { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L44)

---

# ShellOutputDeltaUpdate

Source: https://docs.usetheo.dev/theokit/reference/ShellOutputDeltaUpdate

_No description available._

# `ShellOutputDeltaUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface ShellOutputDeltaUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:155`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L155)

---

# shouldCompact

Source: https://docs.usetheo.dev/theokit/reference/shouldCompact

_No description available._

# `shouldCompact`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function shouldCompact(input: ShouldCompactInput): boolean
```

## Kind

`function`

## Source

[`packages/sdk/src/compaction.ts:295`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L295)

---

# ShouldCompactInput

Source: https://docs.usetheo.dev/theokit/reference/ShouldCompactInput

Input to shouldCompact: an estimate, the model's window, and reserved headroom.

# `ShouldCompactInput`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Input to shouldCompact: an estimate, the model's window, and reserved headroom.

## Signature

```ts
interface ShouldCompactInput { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/compaction.ts:261`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L261)

---

# Skill

Source: https://docs.usetheo.dev/theokit/reference/Skill

SE36 — `Skill.create` replaces `createSkill` (ADR 0015).

# `Skill`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Skill.create` replaces `createSkill` (ADR 0015).

## Signature

```ts
class Skill {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/create-skill.ts:55`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/create-skill.ts#L55)

---

# SkillReadTool

Source: https://docs.usetheo.dev/theokit/reference/SkillReadTool

SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015).

# `SkillReadTool`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015).

## Signature

```ts
class SkillReadTool {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/define-skill-read-tool.ts:94`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/define-skill-read-tool.ts#L94)

---

# SkillsResolver

Source: https://docs.usetheo.dev/theokit/reference/SkillsResolver

SE22 — a resolver that produces SkillsSettings per run from runtime

# `SkillsResolver`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE22 — a resolver that produces SkillsSettings per run from runtime
context (e.g. the user's role). Mirrors the SystemPromptResolver
pattern: evaluated per `send()` BEFORE skill assembly, so a cached
`getOrCreate` agent re-resolves on every run.

The SDK imposes NO timeout — wrap your own `Promise.race` for slow sources. A
throwing resolver fails the run (no silent fallback — Rule 8). Cloud agents
reject a function resolver (it can't run on PaaS); resolve to a static
SkillsSettings object before `Agent.create()`.

## Signature

```ts
type SkillsResolver
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:269`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L269)

---

# SkillsResolverContext

Source: https://docs.usetheo.dev/theokit/reference/SkillsResolverContext

SE22 — context passed to a SkillsResolver. Mirrors

# `SkillsResolverContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE22 — context passed to a SkillsResolver. Mirrors
SystemPromptContext MINUS `skills`: the resolver runs BEFORE skills
are assembled, so the resolved list does not exist yet.

## Signature

```ts
interface SkillsResolverContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:246`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L246)

---

# SkillsSettings

Source: https://docs.usetheo.dev/theokit/reference/SkillsSettings

Skills configuration accepted by `Agent.create()` via

# `SkillsSettings`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Skills configuration accepted by `Agent.create()` via
AgentOptions.skills.

Skills are discovered from `.theokit/skills/<name>/SKILL.md` when
`local.settingSources` includes `"project"`.

## Signature

```ts
interface SkillsSettings { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:213`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L213)

---

# SleepStep

Source: https://docs.usetheo.dev/theokit/reference/SleepStep

Pause for a fixed duration.

# `SleepStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Pause for a fixed duration.

## Signature

```ts
interface SleepStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:95`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L95)

---

# Squad

Source: https://docs.usetheo.dev/theokit/reference/Squad

SE36 — `Squad.create` replaces `createSquad` (ADR 0015). Merges with the `Squad` interface.

# `Squad`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Squad.create` replaces `createSquad` (ADR 0015). Merges with the `Squad` interface.

## Signature

```ts
class Squad {
  run(...): ...
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/squad.ts:57`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/squad.ts#L57)

---

# SquadOptions

Source: https://docs.usetheo.dev/theokit/reference/SquadOptions

Options for createSquad.

# `SquadOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for createSquad.

## Signature

```ts
interface SquadOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/squad.ts:26`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/squad.ts#L26)

---

# SquadRun

Source: https://docs.usetheo.dev/theokit/reference/SquadRun

Result of a Squad.run. `result` is the final (last agent's) output;

# `SquadRun`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of a Squad.run. `result` is the final (last agent's) output;
`steps` is the per-agent trace from the underlying workflow run.

## Signature

```ts
interface SquadRun { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/squad.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/squad.ts#L46)

---

# StaleFileError

Source: https://docs.usetheo.dev/theokit/reference/StaleFileError

SE32 — a write's `expectedMtime` did not match the file's current mtime: the

# `StaleFileError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE32 — a write's `expectedMtime` did not match the file's current mtime: the
file changed since it was last read, so the write would silently clobber.

## Signature

```ts
class StaleFileError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/filesystem/types.ts:98`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L98)

---

# Step

Source: https://docs.usetheo.dev/theokit/reference/Step

_No description available._

# `Step`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type Step
```

## Kind

`type`

## Source

[`packages/sdk/src/types/workflow.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L19)

---

# StepCompletedUpdate

Source: https://docs.usetheo.dev/theokit/reference/StepCompletedUpdate

Conversation step completed.

# `StepCompletedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Conversation step completed.

## Signature

```ts
interface StepCompletedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:107`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L107)

---

# StepContext

Source: https://docs.usetheo.dev/theokit/reference/StepContext

D247 — context handed to every step.fn.

# `StepContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

D247 — context handed to every step.fn.

## Signature

```ts
interface StepContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:121`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L121)

---

# StepResult

Source: https://docs.usetheo.dev/theokit/reference/StepResult

_No description available._

# `StepResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface StepResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:148`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L148)

---

# StepStartedUpdate

Source: https://docs.usetheo.dev/theokit/reference/StepStartedUpdate

Conversation step started.

# `StepStartedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Conversation step started.

## Signature

```ts
interface StepStartedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:97`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L97)

---

# StreamEvent

Source: https://docs.usetheo.dev/theokit/reference/StreamEvent

_No description available._

# `StreamEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface StreamEvent { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/client/types.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/client/types.ts#L20)

---

# StreamObjectError

Source: https://docs.usetheo.dev/theokit/reference/StreamObjectError

Error thrown by Agent.streamObject when the model refuses to call

# `StreamObjectError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Error thrown by Agent.streamObject when the model refuses to call
the synthetic `output` tool or when all retries fail to produce a
schema-valid object. Same code taxonomy as `GenerateObjectError`.

## Signature

```ts
class StreamObjectError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/stream-object.ts:80`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/stream-object.ts#L80)

---

# StreamObjectEvent

Source: https://docs.usetheo.dev/theokit/reference/StreamObjectEvent

Event emitted by Agent.streamObject. Discriminate on `type`.

# `StreamObjectEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Event emitted by Agent.streamObject. Discriminate on `type`.

- `partial` events fire zero or more times with monotonically increasing
  `attempt`, carrying best-effort schema-parsed snapshots of the model's
  accumulating output.
- `complete` fires exactly once at the end, carrying the fully Zod-parsed
  object alongside usage and finishReason — semantically identical to a
  successful `Agent.generateObject()` return.

## Signature

```ts
type StreamObjectEvent
```

## Kind

`type`

## Source

[`packages/sdk/src/stream-object.ts:63`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/stream-object.ts#L63)

---

# StreamObjectOptions

Source: https://docs.usetheo.dev/theokit/reference/StreamObjectOptions

Options accepted by Agent.streamObject. Same shape as

# `StreamObjectOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options accepted by Agent.streamObject. Same shape as
`Agent.generateObject` with the addition that the result is an
`AsyncIterator<StreamObjectEvent<T>>` rather than a single Promise. See ADR D39.

## Signature

```ts
interface StreamObjectOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/stream-object.ts:21`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/stream-object.ts#L21)

---

# StreamToCompletionResult

Source: https://docs.usetheo.dev/theokit/reference/StreamToCompletionResult

Result of SDKAgent.streamToCompletion (V3-4 — the STREAMING continuation

# `StreamToCompletionResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of SDKAgent.streamToCompletion (V3-4 — the STREAMING continuation
driver). Same shape + terminal semantics as RunToCompletionResult; it is
the generator's RETURN value (read it via a manual `gen.next()` loop — a plain
`for await...of` consumes the yielded `SDKMessage`s but discards this return value).

## Signature

```ts
type StreamToCompletionResult = RunToCompletionResult;
```

## Kind

`type`

## Source

[`packages/sdk/src/types/run.ts:253`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/run.ts#L253)

---

# SubAgent

Source: https://docs.usetheo.dev/theokit/reference/SubAgent

SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015).

# `SubAgent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015).

## Signature

```ts
class SubAgent {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/a2a/subagent.ts:413`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L413)

---

# SubAgentSpec

Source: https://docs.usetheo.dev/theokit/reference/SubAgentSpec

_No description available._

# `SubAgentSpec`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SubAgentSpec { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/a2a/subagent.ts:126`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/subagent.ts#L126)

---

# subagentToolWhitelist

Source: https://docs.usetheo.dev/theokit/reference/subagentToolWhitelist

`@theokit/sdk/subagents` — sub-agent tool scoping (M4-6).

# `subagentToolWhitelist`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/subagents` — sub-agent tool scoping (M4-6).

`subagentToolWhitelist(definition)` derives a `Set` of allowed tool names
from an `AgentDefinition.tools` whitelist (or `undefined` when unscoped).
`withSubagentToolScope(definition, fn)` runs `fn` under that whitelist via
the SDK's existing `withToolWhitelist` enforcement (the same dispatch veto
forks use) — so a `tools: ["read_file"]` sub-agent provably cannot call
`write_file`/`shell_exec`. NOT `PermissionEngine`.

Lives on a dedicated sub-export (not the main barrel) because it reaches into
`internal/runtime` — same isolation pattern as `@theokit/sdk/path-safety`.

## Signature

```ts
function subagentToolWhitelist(definition: AgentDefinition): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/skills/subagent-tool-scope.ts:13`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/skills/subagent-tool-scope.ts#L13)

---

# subscribe

Source: https://docs.usetheo.dev/theokit/reference/subscribe

_No description available._

# `subscribe`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function subscribe(name: string, input: TInput, opts: SubscribeOptions): AsyncGenerator
```

## Kind

`function`

## Source

[`packages/sdk/src/subscription/theokit-subscribe.ts:53`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/theokit-subscribe.ts#L53)

---

# SubscribeOptions

Source: https://docs.usetheo.dev/theokit/reference/SubscribeOptions

Options accepted by `Theokit.subscribe(name, input, opts?)`.

# `SubscribeOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options accepted by `Theokit.subscribe(name, input, opts?)`.

## Signature

```ts
interface SubscribeOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/subscription/theokit-subscribe.ts:27`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/theokit-subscribe.ts#L27)

---

# Subscription

Source: https://docs.usetheo.dev/theokit/reference/Subscription

SE36 — `Subscription.create` replaces `defineSubscription` (ADR 0015).

# `Subscription`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `Subscription.create` replaces `defineSubscription` (ADR 0015).

## Signature

```ts
class Subscription {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/subscription/define-subscription.ts:93`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/define-subscription.ts#L93)

---

# SubscriptionCtx

Source: https://docs.usetheo.dev/theokit/reference/SubscriptionCtx

Context passed to a subscription `handler` on each invocation.

# `SubscriptionCtx`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to a subscription `handler` on each invocation.

## Signature

```ts
interface SubscriptionCtx { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/subscription/types.ts:29`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L29)

---

# SubscriptionDescriptor

Source: https://docs.usetheo.dev/theokit/reference/SubscriptionDescriptor

Descriptor returned by Subscription.create. Carries the typed

# `SubscriptionDescriptor`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Descriptor returned by Subscription.create. Carries the typed
input/output Zod schemas + handler factory.

## Signature

```ts
interface SubscriptionDescriptor { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/subscription/types.ts:159`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L159)

---

# SubscriptionDisconnectError

Source: https://docs.usetheo.dev/theokit/reference/SubscriptionDisconnectError

Thrown when a subscription transport disconnects unexpectedly

# `SubscriptionDisconnectError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when a subscription transport disconnects unexpectedly
AND the client did not opt out of reconnect.

## Signature

```ts
class SubscriptionDisconnectError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/subscription/types.ts:137`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L137)

---

# SubscriptionError

Source: https://docs.usetheo.dev/theokit/reference/SubscriptionError

Base error for the subscription subsystem. Extends TheokitAgentError

# `SubscriptionError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Base error for the subscription subsystem. Extends TheokitAgentError
so existing `instanceof TheokitAgentError` branches keep working.

## Signature

```ts
class SubscriptionError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/subscription/types.ts:107`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L107)

---

# SubscriptionInputError

Source: https://docs.usetheo.dev/theokit/reference/SubscriptionInputError

Thrown when subscription input fails Zod schema validation.

# `SubscriptionInputError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when subscription input fails Zod schema validation.

## Signature

```ts
class SubscriptionInputError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/subscription/types.ts:120`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L120)

---

# SubscriptionTransport

Source: https://docs.usetheo.dev/theokit/reference/SubscriptionTransport

Transport selection for subscriptions.

# `SubscriptionTransport`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Transport selection for subscriptions.

- `'ws'`: WebSocket (bidirectional). Required for inbound client→server frames.
  v1.7 ships Node-canonical `ws` adapter; CF/Bun/Deno deferred to v1.8.x per ADR D425.
- `'sse'`: W3C Server-Sent Events (server→client only). Browser-native EventSource.
- `'auto'`: Prefer WS, fall back SSE on upgrade failure. Default.

## Signature

```ts
type SubscriptionTransport
```

## Kind

`type`

## Source

[`packages/sdk/src/subscription/types.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L22)

---

# SUMMARY_TEMPLATE

Source: https://docs.usetheo.dev/theokit/reference/SUMMARY_TEMPLATE

The 7-section summary template handed to the `summarize` callback (theocode

# `SUMMARY_TEMPLATE`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

The 7-section summary template handed to the `summarize` callback (theocode
parity shape). Every header is always present so the summarizer cannot silently
drop a category; the model is told to preserve file paths, commands, and error
text verbatim. Override per-call via CompactTranscriptOptions.summaryTemplate.

## Signature

```ts
const SUMMARY_TEMPLATE
```

## Kind

`constant`

## Source

[`packages/sdk/src/compaction.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/compaction.ts#L44)

---

# SummaryCompletedUpdate

Source: https://docs.usetheo.dev/theokit/reference/SummaryCompletedUpdate

_No description available._

# `SummaryCompletedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SummaryCompletedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:150`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L150)

---

# SummaryStartedUpdate

Source: https://docs.usetheo.dev/theokit/reference/SummaryStartedUpdate

_No description available._

# `SummaryStartedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SummaryStartedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:145`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L145)

---

# SummaryUpdate

Source: https://docs.usetheo.dev/theokit/reference/SummaryUpdate

_No description available._

# `SummaryUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface SummaryUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:139`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L139)

---

# SuspendStep

Source: https://docs.usetheo.dev/theokit/reference/SuspendStep

Standalone explicit suspend point.

# `SuspendStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Standalone explicit suspend point.

## Signature

```ts
interface SuspendStep { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:102`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L102)

---

# SystemPromptContext

Source: https://docs.usetheo.dev/theokit/reference/SystemPromptContext

Context passed to a SystemPromptResolver. Field order is a

# `SystemPromptContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Context passed to a SystemPromptResolver. Field order is a
compatibility contract: new fields are appended, never reordered.

## Signature

```ts
interface SystemPromptContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:182`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L182)

---

# SystemPromptMemoryFact

Source: https://docs.usetheo.dev/theokit/reference/SystemPromptMemoryFact

Public view of a recalled memory fact exposed to the system-prompt resolver.

# `SystemPromptMemoryFact`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public view of a recalled memory fact exposed to the system-prompt resolver.

## Signature

```ts
interface SystemPromptMemoryFact { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:172`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L172)

---

# SystemPromptResolver

Source: https://docs.usetheo.dev/theokit/reference/SystemPromptResolver

Resolver function that produces the system prompt dynamically. Receives

# `SystemPromptResolver`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Resolver function that produces the system prompt dynamically. Receives
the SystemPromptContext and returns a string (or a Promise of one).

The SDK does NOT impose a timeout on the resolver — wrap your own
`Promise.race` if you call into slow resources. Errors propagate to the
caller of `agent.send()`.

## Signature

```ts
type SystemPromptResolver
```

## Kind

`type`

## Source

[`packages/sdk/src/types/agent.ts:202`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L202)

---

# SystemPromptSkillRef

Source: https://docs.usetheo.dev/theokit/reference/SystemPromptSkillRef

Public skill metadata exposed to the system-prompt resolver. Mirrors the

# `SystemPromptSkillRef`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public skill metadata exposed to the system-prompt resolver. Mirrors the
shape returned by `agent.skills.list()` — name + description only, never
full skill bodies.

## Signature

```ts
interface SystemPromptSkillRef { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:107`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L107)

---

# TASK_RESERVED_PREFIXES

Source: https://docs.usetheo.dev/theokit/reference/TASK_RESERVED_PREFIXES

Re-exported for adapter implementations + tests.

# `TASK_RESERVED_PREFIXES`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Re-exported for adapter implementations + tests.

## Signature

```ts
const TASK_RESERVED_PREFIXES
```

## Kind

`constant`

## Source

[`packages/sdk/src/types/task.ts:162`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L162)

---

# Task

Source: https://docs.usetheo.dev/theokit/reference/Task

_No description available._

# `Task`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class Task {
  cancel(...): ...
  configure(...): ...
  get(...): ...
  list(...): ...
  submit(...): ...
  subscribe(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/task.ts:50`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/task.ts#L50)

---

# TaskCancelResult

Source: https://docs.usetheo.dev/theokit/reference/TaskCancelResult

Result of `Task.cancel` (D365 — idempotent).

# `TaskCancelResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of `Task.cancel` (D365 — idempotent).

## Signature

```ts
interface TaskCancelResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/task.ts:127`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L127)

---

# TaskConfigureOptions

Source: https://docs.usetheo.dev/theokit/reference/TaskConfigureOptions

Registry-level configuration. May only be applied BEFORE the first

# `TaskConfigureOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Registry-level configuration. May only be applied BEFORE the first
`Task.submit` of the process — see EC-13. Subsequent calls emit a
single stderr line and become no-ops.

## Signature

```ts
interface TaskConfigureOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/task.ts:44`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/task.ts#L44)

---

# TaskEvent

Source: https://docs.usetheo.dev/theokit/reference/TaskEvent

Discriminated union of task lifecycle events (D366).

# `TaskEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Discriminated union of task lifecycle events (D366).

## Signature

```ts
type TaskEvent
```

## Kind

`type`

## Source

[`packages/sdk/src/types/task.ts:26`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L26)

---

# TaskFilter

Source: https://docs.usetheo.dev/theokit/reference/TaskFilter

Query filter for `Task.list`.

# `TaskFilter`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Query filter for `Task.list`.

## Signature

```ts
interface TaskFilter { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/task.ts:86`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L86)

---

# TaskHandle

Source: https://docs.usetheo.dev/theokit/reference/TaskHandle

Public read-only view of a task entry in the registry.

# `TaskHandle`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Public read-only view of a task entry in the registry.

## Signature

```ts
interface TaskHandle { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/task.ts:63`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L63)

---

# TaskKind

Source: https://docs.usetheo.dev/theokit/reference/TaskKind

Discriminator of the runtime that produced a task (D374).

# `TaskKind`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Discriminator of the runtime that produced a task (D374).

## Signature

```ts
type TaskKind
```

## Kind

`type`

## Source

[`packages/sdk/src/types/task.ts:23`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L23)

---

# TaskNotFoundError

Source: https://docs.usetheo.dev/theokit/reference/TaskNotFoundError

Thrown when `Task.subscribe(id)` is called for a task that has been

# `TaskNotFoundError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when `Task.subscribe(id)` is called for a task that has been
evicted, never submitted, or evicted after retention (D373).

## Signature

```ts
class TaskNotFoundError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:580`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L580)

---

# TaskState

Source: https://docs.usetheo.dev/theokit/reference/TaskState

Closed enum of the 5 lifecycle states (D362).

# `TaskState`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Closed enum of the 5 lifecycle states (D362).

Transitions are acyclic:
  queued → running → (finished | error | cancelled)
  queued → cancelled (direct, no run started)

## Signature

```ts
type TaskState
```

## Kind

`type`

## Source

[`packages/sdk/src/types/task.ts:20`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L20)

---

# TaskStore

Source: https://docs.usetheo.dev/theokit/reference/TaskStore

Storage interface used by `TaskRegistry`.

# `TaskStore`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Storage interface used by `TaskRegistry`.

## Signature

```ts
interface TaskStore { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/task/store.ts:41`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/task/store.ts#L41)

---

# TaskStoreOptions

Source: https://docs.usetheo.dev/theokit/reference/TaskStoreOptions

Options shape for `TaskStore` factory (D364).

# `TaskStoreOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options shape for `TaskStore` factory (D364).

## Signature

```ts
type TaskStoreOptions
```

## Kind

`type`

## Source

[`packages/sdk/src/types/task.ts:122`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L122)

---

# TaskSubmitOptions

Source: https://docs.usetheo.dev/theokit/reference/TaskSubmitOptions

Options for `Task.submit`.

# `TaskSubmitOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Task.submit`.

## Signature

```ts
interface TaskSubmitOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/task.ts:96`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/task.ts#L96)

---

# TaskWorkContext

Source: https://docs.usetheo.dev/theokit/reference/TaskWorkContext

_No description available._

# `TaskWorkContext`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface TaskWorkContext { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/task.ts:32`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/task.ts#L32)

---

# TaskWorkFn

Source: https://docs.usetheo.dev/theokit/reference/TaskWorkFn

_No description available._

# `TaskWorkFn`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
type TaskWorkFn
```

## Kind

`type`

## Source

[`packages/sdk/src/task.ts:37`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/task.ts#L37)

---

# TelemetrySettings

Source: https://docs.usetheo.dev/theokit/reference/TelemetrySettings

Telemetry configuration for an agent. When `enabled: true`, the SDK emits

# `TelemetrySettings`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Telemetry configuration for an agent. When `enabled: true`, the SDK emits
OpenTelemetry spans for `agent.send`, `llm.call`, `tool.call`, and
`memory.search`. See ADR D34.

Privacy: content (prompts, responses, tool args) is OMITTED by default —
only timing/counts/IDs are recorded. Opt in via `includeContent: true`
to add prompt/response/args events to the spans (consumer's
responsibility to sanitize PII).

`@opentelemetry/api` is an OPTIONAL peer dependency. Without it
installed, telemetry is a no-op even when `enabled: true`.

## Signature

```ts
interface TelemetrySettings { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/agent.ts:345`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/agent.ts#L345)

---

# TextBlock

Source: https://docs.usetheo.dev/theokit/reference/TextBlock

Plain text content block emitted by the assistant or user, or returned by a

# `TextBlock`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Plain text content block emitted by the assistant or user, or returned by a
tool.

## Signature

```ts
interface TextBlock { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/content-blocks.ts:16`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/content-blocks.ts#L16)

---

# TextDeltaUpdate

Source: https://docs.usetheo.dev/theokit/reference/TextDeltaUpdate

Incremental text token from the assistant.

# `TextDeltaUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Incremental text token from the assistant.

## Signature

```ts
interface TextDeltaUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:21`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L21)

---

# Theokit

Source: https://docs.usetheo.dev/theokit/reference/Theokit

Account-level and catalog reads. All methods accept an optional `apiKey`

# `Theokit`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Account-level and catalog reads. All methods accept an optional `apiKey`
and otherwise fall back to the `THEOKIT_API_KEY` environment variable.

## Signature

```ts
class Theokit {
  me(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/theokit.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/theokit.ts#L46)

---

# TheokitAgentError

Source: https://docs.usetheo.dev/theokit/reference/TheokitAgentError

Base class for all errors thrown by `@theokit/sdk`.

# `TheokitAgentError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Base class for all errors thrown by `@theokit/sdk`.

Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`
are populated for server-originated errors when available. `metadata`
(ADR D65) carries structured `{ provider, endpoint, code, ... }` when
the error originated from a provider HTTP call.

## Signature

```ts
class TheokitAgentError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:143`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L143)

---

# TheoKitClient

Source: https://docs.usetheo.dev/theokit/reference/TheoKitClient

Client sub-path barrel (T20.2, ADR D454).

# `TheoKitClient`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Client sub-path barrel (T20.2, ADR D454).
Exported via `@theokit/sdk/client`.

## Signature

```ts
class TheoKitClient {
  send(...): ...
  stream(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/client/theokit-client.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/client/theokit-client.ts#L19)

---

# TheokitErrorCode

Source: https://docs.usetheo.dev/theokit/reference/TheokitErrorCode

Canonical envelope code union for cross-layer SDK boundary. Subset of the

# `TheokitErrorCode`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Canonical envelope code union for cross-layer SDK boundary. Subset of the
full `TheoErrorCode` (theokit/server) covering codes the SDK actually emits.
Other layers (theokit/server, theokit/client, theokit/ui) handle the broader
union; the SDK never needs the HTTP-only codes (PRECONDITION_FAILED, etc.).

## Signature

```ts
type TheokitErrorCode
```

## Kind

`type`

## Source

[`packages/sdk/src/server/errors-envelope.ts:36`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/errors-envelope.ts#L36)

---

# TheokitErrorEnvelope

Source: https://docs.usetheo.dev/theokit/reference/TheokitErrorEnvelope

Envelope shape — structurally identical to theokit/server `TheoErrorEnvelope`.

# `TheokitErrorEnvelope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Envelope shape — structurally identical to theokit/server `TheoErrorEnvelope`.

## Signature

```ts
interface TheokitErrorEnvelope { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/server/errors-envelope.ts:53`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/errors-envelope.ts#L53)

---

# TheokitRequestOptions

Source: https://docs.usetheo.dev/theokit/reference/TheokitRequestOptions

Options shared by every `Theokit.*` request.

# `TheokitRequestOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options shared by every `Theokit.*` request.

## Signature

```ts
interface TheokitRequestOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/theokit.ts:26`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/theokit.ts#L26)

---

# ThinkingCompletedUpdate

Source: https://docs.usetheo.dev/theokit/reference/ThinkingCompletedUpdate

Emitted when a reasoning block completes.

# `ThinkingCompletedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Emitted when a reasoning block completes.

## Signature

```ts
interface ThinkingCompletedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:41`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L41)

---

# ThinkingDeltaUpdate

Source: https://docs.usetheo.dev/theokit/reference/ThinkingDeltaUpdate

Incremental reasoning token.

# `ThinkingDeltaUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Incremental reasoning token.

## Signature

```ts
interface ThinkingDeltaUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:31`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L31)

---

# ThinkingMessage

Source: https://docs.usetheo.dev/theokit/reference/ThinkingMessage

Reasoning step in a conversation history.

# `ThinkingMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Reasoning step in a conversation history.

## Signature

```ts
interface ThinkingMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:24`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L24)

---

# toEnvelope

Source: https://docs.usetheo.dev/theokit/reference/toEnvelope

_No description available._

# `toEnvelope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function toEnvelope(value: unknown): TheokitErrorEnvelope
```

## Kind

`function`

## Source

[`packages/sdk/src/server/errors-envelope.ts:97`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/errors-envelope.ts#L97)

---

# TokenDeltaUpdate

Source: https://docs.usetheo.dev/theokit/reference/TokenDeltaUpdate

Token count delta for usage tracking.

# `TokenDeltaUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Token count delta for usage tracking.

## Signature

```ts
interface TokenDeltaUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:87`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L87)

---

# TokenLimiter

Source: https://docs.usetheo.dev/theokit/reference/TokenLimiter

SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015).

# `TokenLimiter`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015).

## Signature

```ts
class TokenLimiter {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/built-in-processors.ts:108`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/built-in-processors.ts#L108)

---

# TokenLimiterOptions

Source: https://docs.usetheo.dev/theokit/reference/TokenLimiterOptions

Options for createTokenLimiter.

# `TokenLimiterOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for createTokenLimiter.

## Signature

```ts
interface TokenLimiterOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/built-in-processors.ts:69`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/built-in-processors.ts#L69)

---

# TokenUsage

Source: https://docs.usetheo.dev/theokit/reference/TokenUsage

Token usage observed during a Run. 5 closed buckets (D376) cover

# `TokenUsage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Token usage observed during a Run. 5 closed buckets (D376) cover
100% of providers in 2026: OpenAI Chat / OpenAI Responses (o-series
with reasoning) / Anthropic Messages (with prompt caching).

`totalTokens` is derived (`inputTokens + outputTokens`); EC-10
invariant: SDK must never emit `totalTokens !== inputTokens + outputTokens`.

`requests[]` is the per-request breakdown (mirror openai-agents-python)
— populated only when the run made > 1 LLM call.

## Signature

```ts
interface TokenUsage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/usage.ts:22`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/usage.ts#L22)

---

# toModelOption

Source: https://docs.usetheo.dev/theokit/reference/toModelOption

_No description available._

# `toModelOption`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function toModelOption(modelId: string): ModelOption
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/llm/model-option.ts:67`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/llm/model-option.ts#L67)

---

# Tool

Source: https://docs.usetheo.dev/theokit/reference/Tool

SE36 — the uniform `X.create()` namespace API. `Tool.create(spec)` is the sole public

# `Tool`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — the uniform `X.create()` namespace API. `Tool.create(spec)` is the sole public
constructor for a CustomTool; it wraps the internal builder so behavior is identical
(ADR 0015). A `private constructor` makes `Tool` a namespace, not an instantiable value —
`new Tool()` is a compile error. Mirrors `Agent.create` / `Cron.create`.

## Signature

```ts
class Tool {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/define-tool.ts:170`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/define-tool.ts#L170)

---

# ToolCall

Source: https://docs.usetheo.dev/theokit/reference/ToolCall

Single tool call event. The internal `args` and `result` shapes are NOT stable.

# `ToolCall`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Single tool call event. The internal `args` and `result` shapes are NOT stable.

## Signature

```ts
interface ToolCall { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:9`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L9)

---

# ToolCallCompletedUpdate

Source: https://docs.usetheo.dev/theokit/reference/ToolCallCompletedUpdate

Tool call completed.

# `ToolCallCompletedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Tool call completed.

## Signature

```ts
interface ToolCallCompletedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:75`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L75)

---

# ToolCallStartedUpdate

Source: https://docs.usetheo.dev/theokit/reference/ToolCallStartedUpdate

Tool call started — args committed.

# `ToolCallStartedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Tool call started — args committed.

## Signature

```ts
interface ToolCallStartedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:51`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L51)

---

# ToolContextMessage

Source: https://docs.usetheo.dev/theokit/reference/ToolContextMessage

A2A (Agent-to-Agent) sub-path barrel (T20.1, ADR D453).

# `ToolContextMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

A2A (Agent-to-Agent) sub-path barrel (T20.1, ADR D453).
Exported via `@theokit/sdk/a2a`.

## Signature

```ts
type ToolContextMessage
```

## Kind

`type`

## Source

[`packages/sdk/src/a2a/index.ts:7`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/a2a/index.ts#L7)

---

# ToolError

Source: https://docs.usetheo.dev/theokit/reference/ToolError

Thrown from a tool `handler` to surface a failure to the model. The SDK turns

# `ToolError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown from a tool `handler` to surface a failure to the model. The SDK turns
it into a `tool_result` with `isError: true` carrying the content. A plain
`Error` thrown from a handler still works (its message becomes text);
`ToolError` is the opt-in for a clean message or a multimodal error (e.g. an
error screenshot).

## Signature

```ts
class ToolError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/tool-error.ts:23`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/tool-error.ts#L23)

---

# ToolResult

Source: https://docs.usetheo.dev/theokit/reference/ToolResult

Result of a tool invocation. Pairs with the preceding `toolCall` step

# `ToolResult`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Result of a tool invocation. Pairs with the preceding `toolCall` step
by `callId`. `isError: true` when the tool returned a failure result.

T2.3 — added so `Run.conversation()` surfaces the full interaction
including tool results (parity with OpenAI Agents `RunResult.new_items`).

## Signature

```ts
interface ToolResult { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/conversation.ts:64`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/conversation.ts#L64)

---

# ToolResultContentBlock

Source: https://docs.usetheo.dev/theokit/reference/ToolResultContentBlock

SE7 — structured content a tool result may carry: text and/or images. A tool

# `ToolResultContentBlock`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE7 — structured content a tool result may carry: text and/or images. A tool
`handler` may return this (success) and a `ToolError` may carry it (failure).
Block-capable provider wires forward it natively; string-only provider wires
flatten text and fail fast on an image.

## Signature

```ts
type ToolResultContentBlock
```

## Kind

`type`

## Source

[`packages/sdk/src/types/content-blocks.ts:46`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/content-blocks.ts#L46)

---

# ToolResultGuardOptions

Source: https://docs.usetheo.dev/theokit/reference/ToolResultGuardOptions

_No description available._

# `ToolResultGuardOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface ToolResultGuardOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/agent-loop/tool-result-guard.ts:18`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/agent-loop/tool-result-guard.ts#L18)

---

# ToolUseBlock

Source: https://docs.usetheo.dev/theokit/reference/ToolUseBlock

Tool invocation block emitted by the assistant.

# `ToolUseBlock`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Tool invocation block emitted by the assistant.

## Signature

```ts
interface ToolUseBlock { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages.ts:17`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages.ts#L17)

---

# toShareGptTrajectory

Source: https://docs.usetheo.dev/theokit/reference/toShareGptTrajectory

_No description available._

# `toShareGptTrajectory`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function toShareGptTrajectory(result: BatchResult, options: unknown): unknown
```

## Kind

`function`

## Source

[`packages/sdk/src/trajectory-helpers.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/trajectory-helpers.ts#L30)

---

# tracked

Source: https://docs.usetheo.dev/theokit/reference/tracked

_No description available._

# `tracked`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function tracked(id: string, payload: T): TrackedEnvelope
```

## Kind

`function`

## Source

[`packages/sdk/src/subscription/types.ts:94`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L94)

---

# TrackedEnvelope

Source: https://docs.usetheo.dev/theokit/reference/TrackedEnvelope

Tracked envelope: `[id, payload]` tuple yielded by subscription handlers

# `TrackedEnvelope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Tracked envelope: `[id, payload]` tuple yielded by subscription handlers
to advertise the resume token associated with the payload.

The encoder writes the `id` as an SSE `id:` field or WS payload metadata
so the client can echo it back on reconnect (`input.lastEventId`).

Per ADR D423.

## Signature

```ts
type TrackedEnvelope
```

## Kind

`type`

## Source

[`packages/sdk/src/subscription/types.ts:77`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/subscription/types.ts#L77)

---

# TurnEndedUpdate

Source: https://docs.usetheo.dev/theokit/reference/TurnEndedUpdate

Turn ended with usage summary.

# `TurnEndedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Turn ended with usage summary.

## Signature

```ts
interface TurnEndedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:118`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L118)

---

# UnicodeNormalizer

Source: https://docs.usetheo.dev/theokit/reference/UnicodeNormalizer

SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015).

# `UnicodeNormalizer`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015).

## Signature

```ts
class UnicodeNormalizer {
  create(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/built-in-processors.ts:115`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/built-in-processors.ts#L115)

---

# UnicodeNormalizerOptions

Source: https://docs.usetheo.dev/theokit/reference/UnicodeNormalizerOptions

Options for createUnicodeNormalizer.

# `UnicodeNormalizerOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for createUnicodeNormalizer.

## Signature

```ts
interface UnicodeNormalizerOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/built-in-processors.ts:26`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/built-in-processors.ts#L26)

---

# UnknownAgentError

Source: https://docs.usetheo.dev/theokit/reference/UnknownAgentError

Catch-all for unclassified server or runtime errors.

# `UnknownAgentError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Catch-all for unclassified server or runtime errors.

## Signature

```ts
class UnknownAgentError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:264`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L264)

---

# UnsupportedBudgetOperationError

Source: https://docs.usetheo.dev/theokit/reference/UnsupportedBudgetOperationError

Base class for all errors thrown by `@theokit/sdk`.

# `UnsupportedBudgetOperationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Base class for all errors thrown by `@theokit/sdk`.

Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`
are populated for server-originated errors when available. `metadata`
(ADR D65) carries structured `{ provider, endpoint, code, ... }` when
the error originated from a provider HTTP call.

## Signature

```ts
class UnsupportedBudgetOperationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:683`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L683)

---

# UnsupportedRunOperationError

Source: https://docs.usetheo.dev/theokit/reference/UnsupportedRunOperationError

Thrown when a Run or agent operation is not available on the current

# `UnsupportedRunOperationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when a Run or agent operation is not available on the current
runtime. Check first with `run.supports(operation)`.

Extends TheokitAgentError (so error-catching code that branches on
`instanceof TheokitAgentError` continues to work) but is never retryable —
an unsupported operation will not become supported on retry.

## Signature

```ts
class UnsupportedRunOperationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:457`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L457)

---

# UnsupportedTaskOperationError

Source: https://docs.usetheo.dev/theokit/reference/UnsupportedTaskOperationError

Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud

# `UnsupportedTaskOperationError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
task observability is deferred until Theo PaaS GA.

## Signature

```ts
class UnsupportedTaskOperationError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/errors.ts:600`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/errors.ts#L600)

---

# UsageAccumulator

Source: https://docs.usetheo.dev/theokit/reference/UsageAccumulator

_No description available._

# `UsageAccumulator`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class UsageAccumulator {
  add(...): ...
  hasAny(...): ...
  toTokenUsage(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/internal/budget/usage-accumulator.ts:23`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/budget/usage-accumulator.ts#L23)

---

# UserMessage

Source: https://docs.usetheo.dev/theokit/reference/UserMessage

User-authored message in a conversation history.

# `UserMessage`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

User-authored message in a conversation history.

## Signature

```ts
interface UserMessage { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/messages-base.ts:19`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/messages-base.ts#L19)

---

# UserMessageAppendedUpdate

Source: https://docs.usetheo.dev/theokit/reference/UserMessageAppendedUpdate

User message appended to the conversation.

# `UserMessageAppendedUpdate`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

User message appended to the conversation.

## Signature

```ts
interface UserMessageAppendedUpdate { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/updates.ts:133`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/updates.ts#L133)

---

# validateReturnTo

Source: https://docs.usetheo.dev/theokit/reference/validateReturnTo

_No description available._

# `validateReturnTo`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function validateReturnTo(returnTo: unknown, baseUrl: URL): string
```

## Kind

`function`

## Source

[`packages/sdk/src/server/auth/validate-return-to.ts:17`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/server/auth/validate-return-to.ts#L17)

---

# VerifyGateOptions

Source: https://docs.usetheo.dev/theokit/reference/VerifyGateOptions

Options for `Scorers.verifyGate` (M6-2) — grade a patch by running the

# `VerifyGateOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for `Scorers.verifyGate` (M6-2) — grade a patch by running the
project's tests in a provisioned repo and reading the exit code.

## Signature

```ts
interface VerifyGateOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/eval.ts:128`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/eval.ts#L128)

---

# withCwdMutex

Source: https://docs.usetheo.dev/theokit/reference/withCwdMutex

_No description available._

# `withCwdMutex`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function withCwdMutex(key: string, fn: unknown): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/persistence/cwd-mutex.ts:24`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/persistence/cwd-mutex.ts#L24)

---

# withSubagentToolScope

Source: https://docs.usetheo.dev/theokit/reference/withSubagentToolScope

`@theokit/sdk/subagents` — sub-agent tool scoping (M4-6).

# `withSubagentToolScope`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/subagents` — sub-agent tool scoping (M4-6).

`subagentToolWhitelist(definition)` derives a `Set` of allowed tool names
from an `AgentDefinition.tools` whitelist (or `undefined` when unscoped).
`withSubagentToolScope(definition, fn)` runs `fn` under that whitelist via
the SDK's existing `withToolWhitelist` enforcement (the same dispatch veto
forks use) — so a `tools: ["read_file"]` sub-agent provably cannot call
`write_file`/`shell_exec`. NOT `PermissionEngine`.

Lives on a dedicated sub-export (not the main barrel) because it reaches into
`internal/runtime` — same isolation pattern as `@theokit/sdk/path-safety`.

## Signature

```ts
function withSubagentToolScope(definition: AgentDefinition, fn: unknown): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/skills/subagent-tool-scope.ts:31`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/skills/subagent-tool-scope.ts#L31)

---

# Workflow

Source: https://docs.usetheo.dev/theokit/reference/Workflow

_No description available._

# `Workflow`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class Workflow {
  run(...): ...
  stream(...): ...
  create(...): ...
  resume(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/workflow.ts:229`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L229)

---

# WorkflowAlreadyRunningError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowAlreadyRunningError

_No description available._

# `WorkflowAlreadyRunningError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class WorkflowAlreadyRunningError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:364`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L364)

---

# workflowAsTool

Source: https://docs.usetheo.dev/theokit/reference/workflowAsTool

_No description available._

# `workflowAsTool`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function workflowAsTool(workflow: unknown, spec: WorkflowAsToolSpec): CustomTool
```

## Kind

`function`

## Source

[`packages/sdk/src/workflow.ts:496`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L496)

---

# WorkflowAsToolSpec

Source: https://docs.usetheo.dev/theokit/reference/WorkflowAsToolSpec

Spec for workflowAsTool. `inputSchema` is the workflow's input shape (Zod).

# `WorkflowAsToolSpec`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Spec for workflowAsTool. `inputSchema` is the workflow's input shape (Zod).

## Signature

```ts
interface WorkflowAsToolSpec { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/workflow.ts:474`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L474)

---

# WorkflowBuilder

Source: https://docs.usetheo.dev/theokit/reference/WorkflowBuilder

_No description available._

# `WorkflowBuilder`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class WorkflowBuilder {
  branch(...): ...
  commit(...): ...
  dowhile(...): ...
  foreach(...): ...
  parallel(...): ...
  sleep(...): ...
  suspend(...): ...
  then(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/workflow.ts:82`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L82)

---

# WorkflowCompensateNotImplementedError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowCompensateNotImplementedError

D238 — saga engine not yet implemented.

# `WorkflowCompensateNotImplementedError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

D238 — saga engine not yet implemented.

## Signature

```ts
class WorkflowCompensateNotImplementedError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:431`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L431)

---

# WorkflowDuplicateStepIdError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowDuplicateStepIdError

_No description available._

# `WorkflowDuplicateStepIdError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class WorkflowDuplicateStepIdError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:284`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L284)

---

# WorkflowEvent

Source: https://docs.usetheo.dev/theokit/reference/WorkflowEvent

SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level

# `WorkflowEvent`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE28 — a step-level workflow event emitted by `Workflow.stream()` as top-level
steps run. Coarse-grained (one event per top-level step; nested
parallel/branch/foreach emit as their single wrapping step), distinct from the
token-delta agent stream. Discriminate on `type`.

## Signature

```ts
type WorkflowEvent
```

## Kind

`type`

## Source

[`packages/sdk/src/types/workflow.ts:193`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L193)

---

# WorkflowInputError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowInputError

SE27 — the whole-workflow `inputSchema` rejected `run(input)` (before step 1).

# `WorkflowInputError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE27 — the whole-workflow `inputSchema` rejected `run(input)` (before step 1).
`detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).

## Signature

```ts
class WorkflowInputError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:295`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L295)

---

# WorkflowMaxIterationsExceededError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowMaxIterationsExceededError

_No description available._

# `WorkflowMaxIterationsExceededError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class WorkflowMaxIterationsExceededError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:381`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L381)

---

# WorkflowNestedError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowNestedError

SE30 — a nested workflow (via `workflowStep`) did not `complete`. A nested

# `WorkflowNestedError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE30 — a nested workflow (via `workflowStep`) did not `complete`. A nested
`suspended` is NOT resumable in v1 (resume continues AFTER the step, so the
child would be skipped) — restructure with a top-level suspend. A nested
`failed`/`cancelled` fails the parent step with the child's error attached.

## Signature

```ts
class WorkflowNestedError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:339`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L339)

---

# WorkflowNotSerializableError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowNotSerializableError

EC-4 absorbed — JSON.stringify failed on snapshot payload.

# `WorkflowNotSerializableError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

EC-4 absorbed — JSON.stringify failed on snapshot payload.

## Signature

```ts
class WorkflowNotSerializableError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:392`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L392)

---

# WorkflowOptions

Source: https://docs.usetheo.dev/theokit/reference/WorkflowOptions

_No description available._

# `WorkflowOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface WorkflowOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:224`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L224)

---

# WorkflowOutputError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowOutputError

SE27 — the whole-workflow `outputSchema` rejected the final output (on `completed`).

# `WorkflowOutputError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE27 — the whole-workflow `outputSchema` rejected the final output (on `completed`).
`detail` is a pre-formatted issues summary (a string, NOT Zod's `ZodIssue[]`).

## Signature

```ts
class WorkflowOutputError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:309`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L309)

---

# WorkflowParallelError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowParallelError

Aggregate failure from parallel branches.

# `WorkflowParallelError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Aggregate failure from parallel branches.

## Signature

```ts
class WorkflowParallelError {
  // see source for members
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:420`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L420)

---

# WorkflowPersistenceOptions

Source: https://docs.usetheo.dev/theokit/reference/WorkflowPersistenceOptions

_No description available._

# `WorkflowPersistenceOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface WorkflowPersistenceOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:218`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L218)

---

# WorkflowResumeOptions

Source: https://docs.usetheo.dev/theokit/reference/WorkflowResumeOptions

_No description available._

# `WorkflowResumeOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface WorkflowResumeOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:275`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L275)

---

# WorkflowResumeStepNotFoundError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowResumeStepNotFoundError

EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow.

# `WorkflowResumeStepNotFoundError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

EC-8 absorbed — `currentStepId` from snapshot not found in resumed workflow.

## Signature

```ts
class WorkflowResumeStepNotFoundError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:406`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L406)

---

# WorkflowRun

Source: https://docs.usetheo.dev/theokit/reference/WorkflowRun

_No description available._

# `WorkflowRun`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface WorkflowRun { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:158`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L158)

---

# WorkflowRunOptions

Source: https://docs.usetheo.dev/theokit/reference/WorkflowRunOptions

_No description available._

# `WorkflowRunOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface WorkflowRunOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:259`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L259)

---

# WorkflowSnapshot

Source: https://docs.usetheo.dev/theokit/reference/WorkflowSnapshot

_No description available._

# `WorkflowSnapshot`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
interface WorkflowSnapshot { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/types/workflow.ts:169`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L169)

---

# WorkflowSnapshotNotFoundError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowSnapshotNotFoundError

_No description available._

# `WorkflowSnapshotNotFoundError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
class WorkflowSnapshotNotFoundError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:374`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L374)

---

# WorkflowStateError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowStateError

SE29 — `WorkflowOptions.stateSchema` rejected an `initialState` or a

# `WorkflowStateError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE29 — `WorkflowOptions.stateSchema` rejected an `initialState` or a
`setState(next)` call. `detail` is a pre-formatted issues summary.

## Signature

```ts
class WorkflowStateError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/types/workflow.ts:323`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L323)

---

# workflowStep

Source: https://docs.usetheo.dev/theokit/reference/workflowStep

_No description available._

# `workflowStep`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

_No description available._

## Signature

```ts
function workflowStep(child: Workflow, opts: unknown): FnStep
```

## Kind

`function`

## Source

[`packages/sdk/src/workflow.ts:388`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L388)

---

# WorkflowStream

Source: https://docs.usetheo.dev/theokit/reference/WorkflowStream

SE28 — the async iterator returned by `Workflow.stream()`. Yields

# `WorkflowStream`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

SE28 — the async iterator returned by `Workflow.stream()`. Yields
WorkflowEvents in execution order; `result` resolves to the same
terminal WorkflowRun the `run()` path returns (the authoritative
outcome — the stream ends when the run terminates).

## Signature

```ts
type WorkflowStream
```

## Kind

`type`

## Source

[`packages/sdk/src/types/workflow.ts:212`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/types/workflow.ts#L212)

---

# WorkflowToolError

Source: https://docs.usetheo.dev/theokit/reference/WorkflowToolError

Raised by a workflowAsTool tool when the wrapped workflow run does not

# `WorkflowToolError`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Raised by a workflowAsTool tool when the wrapped workflow run does not
reach `status: "completed"` (a step failed, the run was cancelled/suspended).
The dispatch converts it to a `tool_result(isError)`.

## Signature

```ts
class WorkflowToolError {
  captureStackTrace(...): ...
  prepareStackTrace(...): ...
}
```

## Kind

`class`

## Source

[`packages/sdk/src/workflow.ts:457`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/workflow.ts#L457)

---

# WriteFileOptions

Source: https://docs.usetheo.dev/theokit/reference/WriteFileOptions

Options a write may carry. SE32 adds `expectedMtime` (stale-write guard).

# `WriteFileOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options a write may carry. SE32 adds `expectedMtime` (stale-write guard).

## Signature

```ts
interface WriteFileOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/filesystem/types.ts:30`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/filesystem/types.ts#L30)

---

# writeProjectInstructions

Source: https://docs.usetheo.dev/theokit/reference/writeProjectInstructions

`@theokit/sdk/project` — hierarchical project-instruction reader/writer.

# `writeProjectInstructions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

`@theokit/sdk/project` — hierarchical project-instruction reader/writer.

`readProjectInstructions(cwd, options?)` walks up from `cwd` collecting a
configurable instruction file (default `THEO.md`), returning the found files
nearest-first plus a `scope`-selected `content` (`nearest` | `merged`). It
never throws. `writeProjectInstructions(cwd, content, options?)` writes the
file atomically (temp + fsync + rename) and fails loud on write errors.

Composes the SDK's own hardened `walkUpForFile` discovery + the atomic
`replaceFileAtomic` writer — so consumers read/write project instructions
with one import instead of hand-rolling the walk-up + atomic write.

## Signature

```ts
function writeProjectInstructions(cwd: string, content: string, options: WriteProjectInstructionsOptions): Promise
```

## Kind

`function`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:113`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L113)

---

# WriteProjectInstructionsOptions

Source: https://docs.usetheo.dev/theokit/reference/WriteProjectInstructionsOptions

Options for writeProjectInstructions.

# `WriteProjectInstructionsOptions`

**Auto-generated** from TypeDoc on each build. Edit the JSDoc in `packages/sdk/src/` to change this page.

Options for writeProjectInstructions.

## Signature

```ts
interface WriteProjectInstructionsOptions { /* ... */ }
```

## Kind

`interface`

## Source

[`packages/sdk/src/internal/runtime/context/project-instructions.ts:42`](https://github.com/usetheodev/theokit-sdk/blob/main/packages/sdk/src/internal/runtime/context/project-instructions.ts#L42)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/resilience/advanced

Retry backoff tuning and abort, the semaphore acquire/release contract, ordered bounded map, and the distinct workflow-step RetryPolicy.

# Advanced resilience

Verified against `@theokit/sdk/retry` and `@theokit/sdk/concurrency`.

## `Retry.create` — full options

```ts
import { Retry } from "@theokit/sdk/retry";

await Retry.create(fn, {
  retries: 3,               // retries AFTER the first attempt (total = retries + 1). Default 3.
  isRetryable: (err) => …,  // which errors to retry. Default: transient only (isTransientError)
  initialDelayMs: 100,      // base backoff for the first retry. Default 100.
  maxDelayMs: 30_000,       // cap for a single backoff sleep. Default 30_000.
  backoffMultiplier: 2,     // exponential multiplier per retry. Default 2.
  rng: Math.random,         // [0,1) source for full-jitter. Inject for deterministic tests.
  sleep: (ms, signal) => …, // sleep fn. Default an abortable setTimeout. Inject in tests.
  signal: abortController.signal, // once aborted, the backoff sleep rejects and the loop stops.
});
```

- **Backoff** is exponential with **full jitter**: attempt *n* sleeps a random value in
  `[0, min(maxDelayMs, initialDelayMs * backoffMultiplier ** n))`. The `rng` + `sleep` seams make it
  fully deterministic under test.
- **`isRetryable` default is `isTransientError`** — it retries the SDK's own transient classification
  (network / rate-limit), *not* arbitrary errors. Override it to retry a domain error.
- **`signal`** cooperatively aborts mid-backoff — the pending sleep rejects and no further attempts run.

## Semaphore — the acquire / release contract

```ts
import { Semaphore } from "@theokit/sdk/concurrency";

const sem = Semaphore.create(2);       // N permits (positive integer, else ConfigurationError)
const release = await sem.acquire();   // waits for a free permit; returns a release fn
try {
  await doWork();
} finally {
  release();                            // MUST be called exactly once — always in finally
}
```

The contract is deliberate: `acquire()` resolves to a **release function** you call once when done.
Releasing in a `finally` guarantees the permit returns even if the work throws — leaking it starves
every waiter.

## Ordered bounded map — `mapWithConcurrency`

```ts
import { mapWithConcurrency } from "@theokit/sdk/concurrency";

const out = await mapWithConcurrency(
  items,
  2,                                    // at most 2 invocations in flight
  async (item, index, signal) => transform(item),
  { signal },                           // optional AbortSignal for the whole map
);
```

`mapWithConcurrency(items, concurrency, fn, options?)` runs `fn` over `items` with at most
`concurrency` in flight and returns results **in input order** (not completion order). The peak
concurrency never exceeds the cap:

```text
Results: 10, 20, 30, 40, 50
Peak concurrency: 2 (cap was 2)
```

## Workflow-step retry is a *different* shape — `RetryPolicy`

Retry *inside a workflow step* is declarative and uses its own field names — do **not** confuse it
with standalone `Retry.create`:

```ts
// on a workflow fn/agent step
retry: {
  maxAttempts: 3,             // TOTAL attempts (MIN 1, MAX 20). 1 = no retry.
  initialBackoffMs: 200,
  backoffCoefficient: 2,
  maximumBackoffMs: 10_000,
  nonRetryableErrors: ["ValidationError"], // error names that skip retry
}
```

| | Standalone `Retry.create` | Workflow-step `RetryPolicy` |
| --- | --- | --- |
| Count field | `retries` (after the first) | `maxAttempts` (total, incl. first) |
| Base backoff | `initialDelayMs` | `initialBackoffMs` |
| Multiplier | `backoffMultiplier` | `backoffCoefficient` |
| Cap | `maxDelayMs` | `maximumBackoffMs` |
| Non-retry | `isRetryable` predicate | `nonRetryableErrors` name list |

See [Workflows › Advanced](/theokit/workflows/advanced) for where a `RetryPolicy` attaches.

## Reference

- [`Retry`](/theokit/reference/Retry) · [`Semaphore`](/theokit/reference/Semaphore) · [`mapWithConcurrency`](/theokit/reference/mapWithConcurrency) · [`RetryPolicy`](/theokit/reference/RetryPolicy) · [`NetworkError`](/theokit/reference/NetworkError)

---

# Overview

Source: https://docs.usetheo.dev/theokit/resilience

Retry with backoff, bounded concurrency, automatic circuit breaking, and the typed network error codes that let you route failures.

# Resilience

Primitives for surviving flaky providers and bounding load — each a `X.create()` you drop around any
async work.

- **Retry** (`@theokit/sdk/retry`) — `Retry.create(fn, options)` *runs* `fn` with exponential backoff
  + full jitter and abortable sleeps, resolving to its result. `RetryOptions`: `retries`,
  `isRetryable`, `initialDelayMs`, `maxDelayMs`, `backoffMultiplier`, `rng`, `sleep`, `signal`.
- **Concurrency** (`@theokit/sdk/concurrency`) — `Semaphore.create(permits)` is an async counting
  semaphore; `mapWithConcurrency(items, n, fn)` is an ordered bounded map.
- **Automatic circuit breaking + typed errors** — the provider pool trips a circuit after repeated
  failures and surfaces a typed `NetworkError` (`code: "circuit_open"`); other transport failures
  carry `code: "network_error"`, `"anthropic_timeout"`, `"mcp_disconnected"`, `"mcp_closed"`,
  `"mcp_crashed"`, so your retry / fallback logic can route them. The breaker is automatic — you don't
  construct it.

```ts
import { Retry } from "@theokit/sdk/retry";

const value = await Retry.create(() => callFlakyApi(), { retries: 3 });
```

`Retry.create(fn, opts)` is an **executor**, not a constructor — it *runs* `fn` and resolves to its
result (`Promise<T>`), it does not return a `Retry` instance. The `.create` name is the SE36 uniformity
convention.

## Which primitive

| You want | Reach for |
| --- | --- |
| Survive a transient network / rate-limit blip | **`Retry.create`** — [Retry a flaky call](/theokit/resilience/retry-a-flaky-call). |
| Cap how many things run at once | **`Semaphore.create`** / **`mapWithConcurrency`** — [Advanced](/theokit/resilience/advanced). |
| Declarative retry *inside a workflow step* | A `RetryPolicy` on the step — [Advanced](/theokit/resilience/advanced). |

## Next

- [Retry a flaky call](/theokit/resilience/retry-a-flaky-call) — a runnable `Retry.create` example.
- [Advanced](/theokit/resilience/advanced) — backoff tuning, `isRetryable`, abort signals, the
  semaphore contract, `mapWithConcurrency`, and workflow-step retry policies.

## Reference

- [`Retry`](/theokit/reference/Retry) · [`Semaphore`](/theokit/reference/Semaphore) · [`mapWithConcurrency`](/theokit/reference/mapWithConcurrency) · [`NetworkError`](/theokit/reference/NetworkError)

---

# Retry a flaky call

Source: https://docs.usetheo.dev/theokit/resilience/retry-a-flaky-call

Wrap a function that fails intermittently in Retry.create so transient errors are retried with exponential backoff — deterministic.

# Retry a flaky call

`Retry.create(fn, options)` runs `fn` and, if it throws a *retryable* error, retries with exponential
backoff and full jitter until it succeeds or the budget is spent. It resolves to `fn`'s result — there
is no `Retry` instance to hold.

```ts title="run.ts"
import { Retry } from "@theokit/sdk/retry";

let attempts = 0;
const value = await Retry.create(
  async () => {
    attempts += 1;
    if (attempts < 3) throw new Error(`transient (attempt ${attempts})`);
    return `ok after ${attempts} attempts`;
  },
  { retries: 3, initialDelayMs: 20, isRetryable: () => true },
);

console.log("Result:", value);
```

## Output

Deterministic — the third attempt succeeds:

```text
Result: ok after 3 attempts
```

## What it shows

- **`Retry.create(fn, options)`** retries on failure — `retries: 3` means up to 4 total attempts.
- **`isRetryable`** decides *which* errors are worth retrying. The **default** predicate only retries
  *transient* errors (network / rate-limit, via the SDK's own classification), so this example passes
  `isRetryable: () => true` to retry its plain `Error`.
- **`initialDelayMs`** is the base backoff; each retry multiplies it by `backoffMultiplier` (default 2)
  up to `maxDelayMs`, with full jitter applied.

Without a custom `isRetryable`, a plain `new Error(...)` is **not** retried — only transient errors
are. Pass your own predicate to retry a domain error.

## Example

Full runnable source:
[`examples/retry-primitive`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/retry-primitive).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/sandbox/advanced

The env-scrub policy, timeouts and output caps, file helpers derived on the backend, repo provisioning for code evals, and custom backends.

# Advanced sandbox

Verified against `@theokit/sdk/sandbox`.

## Config — `SandboxConfig`

```ts
new LocalSandbox({
  workDir: "./scratch",     // where commands run
  timeoutMs: 30_000,        // default per-command timeout
  maxOutputBytes: 1_000_000, // cap captured stdout/stderr
  env: "inherit-scrubbed",  // env policy (see below)
});
```

## Environment policy — `env`

The child process env is filtered before the command runs:

| Policy | Behavior |
| --- | --- |
| `"inherit-scrubbed"` (default) | Inherit, but **drop** secret-like vars (`*KEY*`, `*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`). |
| `"all"` | Full inheritance — no scrubbing. |
| `"core"` | A minimal safe allowlist only. |

The default protects against a model-generated command exfiltrating a key via `echo $…`.

## Per-command timeout

`execute(command, { timeoutMs })` overrides the config default for a single call — cap a long-running
build without loosening the whole sandbox.

## File helpers (derived)

`SandboxBackend` implements only `execute` + `uploadFile`; the rest derive on top, so every backend
gets them for free:

```ts
await sandbox.writeFile("out.txt", "data");
const text = await sandbox.readFile("out.txt");
const files = await sandbox.list(".");
const there = await sandbox.exists("out.txt");
```

## Provision a repo — `provisionRepo`

```ts
import { provisionRepo } from "@theokit/sdk/sandbox";

const { repoDir } = await provisionRepo({
  repoUrl: "https://github.com/acme/widget",
  ref: "main",              // branch, tag, or SHA
});
```

Clones and checks out `ref` into an isolated working dir, returning the resolved `repoDir` — feed it to
[`Scorers.verifyGate`](/theokit/evals/advanced) to grade a patch by running the repo's tests. Fails
with `RepoProvisionError`.

## Custom backends

Implement `execute` + `uploadFile` on `SandboxBackend` for Docker, E2B, or a remote runner — the file
helpers and `verifyGate` integration come free. Surface `SandboxNotAvailableError` when the backend
can't start and `SandboxSecurityError` on a boundary violation.

## Reference

- [`LocalSandbox`](/theokit/reference/LocalSandbox) · [`SandboxBackend`](/theokit/reference/SandboxBackend) · [`SandboxConfig`](/theokit/reference/SandboxConfig) · [`provisionRepo`](/theokit/reference/provisionRepo) · [`ExecuteResult`](/theokit/reference/ExecuteResult)

---

# Overview

Source: https://docs.usetheo.dev/theokit/sandbox

Run agent-generated commands and code through a pluggable execution backend — local for dev, Docker/E2B for untrusted code, with a secret-scrubbed environment.

# Sandbox

`@theokit/sdk/sandbox` runs commands through a swappable backend. `LocalSandbox` shells out to the
host; the same `SandboxBackend` interface backs Docker / E2B for untrusted code.

```ts
import { LocalSandbox } from "@theokit/sdk/sandbox";

const sandbox = new LocalSandbox();
const result = await sandbox.execute("npm test");
// { stdout, stderr, exitCode }
```

## The backend

`SandboxBackend` has just two abstract methods — **`execute(command, { timeoutMs? })`** and
`uploadFile` — and derives `readFile`, `writeFile`, `list`, and `exists` on top. Implement the two and
you have a new backend that composes exactly like `LocalSandbox`.

`LocalSandbox` is **not** an isolation boundary — it runs on the same user and host. Its safety
affordance is a secret-scrubbed child environment, not containment. For untrusted or model-generated
code, use a Docker / E2B backend (same interface).

## Secret-scrubbed by default

The child process environment defaults to **`inherit-scrubbed`** — secret-like vars (`*KEY*`,
`*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_AUTH*`) are dropped before the command runs, so a stray
`echo $OPENAI_API_KEY` can't leak your key. Opt into `"all"` or the minimal `"core"` allowlist
explicitly.

## Provision a repo — `provisionRepo`

For code-eval workflows, `provisionRepo({ repoUrl, ref })` clones a repository and checks out a ref
into an isolated working dir, returning `{ repoDir }` — the input to
[`Scorers.verifyGate`](/theokit/evals/advanced).

## Next

- [Run a command](/theokit/sandbox/run-a-command) — a runnable `execute` example (deterministic).
- [Advanced](/theokit/sandbox/advanced) — the env policy, file helpers, repo provisioning, and custom backends.

## Reference

- [`LocalSandbox`](/theokit/reference/LocalSandbox) · [`SandboxBackend`](/theokit/reference/SandboxBackend) · [`ExecuteResult`](/theokit/reference/ExecuteResult) · [`provisionRepo`](/theokit/reference/provisionRepo)

---

# Run a command

Source: https://docs.usetheo.dev/theokit/sandbox/run-a-command

Execute a shell command through LocalSandbox and capture stdout and exit code — deterministic, no LLM.

# Run a command

`LocalSandbox.execute(command)` runs a shell command and returns `{ stdout, stderr, exitCode }`. It's
the primitive an agent's "run this code" tool sits on. Running a fixed command makes it deterministic —
no LLM.

```ts title="run.ts"
import { LocalSandbox } from "@theokit/sdk/sandbox";

const sandbox = new LocalSandbox();

const ok = await sandbox.execute("echo hello from the sandbox");
console.log("stdout:  ", ok.stdout.trim());
console.log("exitCode:", ok.exitCode);

const fail = await sandbox.execute("this-command-does-not-exist");
console.log("failed? ", fail.exitCode !== 0);
```

## Output

Deterministic — the command output is captured verbatim:

```text
stdout:   hello from the sandbox
exitCode: 0
failed?  true
```

## What it shows

- **`execute(command)`** returns `ExecuteResult` — `stdout`, `stderr`, and a numeric `exitCode`. A
  successful command exits `0`; a missing binary exits non-zero (branch on `exitCode !== 0`).
- **No throw on non-zero** — a failing command is *data* (`exitCode`), not an exception. You decide
  whether to treat it as failure.
- The child environment is **secret-scrubbed** by default, so the command can't read your API keys.

`LocalSandbox` runs on your host. For model-generated commands, swap in a Docker / E2B backend — the
`execute` call is identical.

## Example

Full runnable source:
[`examples/sandbox-exec`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/sandbox-exec).

---

# Sandbox

Source: https://docs.usetheo.dev/theokit/sandbox

Run code and provision repos safely.

# Sandbox

A sandbox backend for executing code and provisioning a repo into an isolated workspace.

| Capability | What it adds |
| --- | --- |
| `LocalSandbox` (`/sandbox`) | Sandboxed execution |
| `provisionRepo` | Clone a repo into the sandbox |
| `SandboxBackend` | Bring your own backend |

---

# Advanced

Source: https://docs.usetheo.dev/theokit/schedules/advanced

The full cron lifecycle — enable/disable, manual off-schedule runs, the local scheduler and its status, timezones, workflow targets, and cloud vs local runtime.

# Advanced schedules

Verified against `@theokit/sdk` (`src/cron.ts`, `src/types/cron.ts`).

## Lifecycle

```ts
const job = await Cron.create({ cron: "@hourly", message, agent });

await Cron.list();               // { items: CronJob[], nextCursor? } — local, cloud, or both
await Cron.get(job.id);          // one job
await Cron.disable(job.id);      // stop firing (status → paused), keep the job
await Cron.enable(job.id);       // resume firing
await Cron.delete(job.id);       // remove entirely
```

`cron` accepts a standard **5-field POSIX** expression (`0 9 * * *`) or a shorthand (`@hourly`,
`@daily`, `@weekly`, …).

## Run now — `Cron.run`

Trigger a job off-schedule and get its `Run` (or `WorkflowRun` for a workflow target) back:

```ts
const run = await Cron.run(job.id);   // fires immediately, regardless of schedule
```

Useful to test a job's behavior without waiting for its next fire.

## The local scheduler — `start` / `stop` / `status`

Local jobs fire only while the in-process scheduler runs:

```ts
await Cron.start({ cwd });        // load .theokit/cron/jobs.json and begin ticking
const s = await Cron.status();    // { running, jobCount, nextFireAt?, lastError? }
await Cron.stop();                // halt the scheduler (jobs persist)
```

`Cron.status()` returns a `CronSchedulerStatus` — whether the scheduler is `running`, how many jobs
are loaded, the `nextFireAt` across all jobs, and the `lastError` observed (jobId + message + time),
so a failing job is visible without digging through logs.

## Timezones

`timezone` is an IANA identifier (`"America/Sao_Paulo"`), defaulting to `"UTC"`. The cron expression
is evaluated in that zone — `0 9 * * *` with `timezone: "America/Sao_Paulo"` fires at 09:00 São Paulo
time, not UTC.

## Workflow targets

```ts
await Cron.create({
  cron: "0 0 * * 1",              // Mondays at midnight
  workflow: myWorkflow,           // a committed Workflow
  inputData: { week: "current" }, // passed to workflow.run(inputData) each fire
});
```

A workflow target is **always local** — a committed `Workflow` instance is held in-memory and cannot
cross the cloud process boundary (ADR 0014). It takes `inputData` and must **not** set `message`.

## Local vs cloud runtime

Runtime is inferred from the target at create time:

- **Local** — fires in your process while `Cron.start()` runs; persisted at `.theokit/cron/jobs.json`.
- **Cloud** (Theo PaaS) — fires server-side, independent of your process. **Pre-release** — the
  contract is documented; the endpoint ships with PaaS.

## Reference

- [`Cron`](/theokit/reference/Cron) · [`CronJob`](/theokit/reference/CronJob) · [`CronCreateOptions`](/theokit/reference/CronCreateOptions) · [`CronSchedulerStatus`](/theokit/reference/CronSchedulerStatus)

---

# Overview

Source: https://docs.usetheo.dev/theokit/schedules

Run an agent or a committed workflow on a cron schedule — locally via an in-process scheduler, or in the cloud via Theo PaaS.

# Schedules

`Cron` schedules a recurring invocation of an agent or a workflow. Define the job once; the scheduler
fires it on a standard cron expression.

```ts
import { Cron } from "@theokit/sdk";

const job = await Cron.create({
  name: "daily-digest",
  cron: "0 9 * * *",                         // 09:00 every day
  message: "Summarize yesterday's commits.",
  agent: { apiKey, model },                   // ephemeral agent, fresh per fire
});

await Cron.start();                            // activate the local in-process scheduler
```

## Three targets — pass exactly one

| Target | You pass | Fires |
| --- | --- | --- |
| Ephemeral agent | `agent` (AgentOptions) + `message` | A fresh agent each run. |
| Existing agent | `agentId` + `message` | Reuses an agent — preserves conversation context. |
| Committed workflow | `workflow` + `inputData` | Runs `workflow.run(inputData)` (local only). |

## The static API

- **`Cron.create` / `Cron.list` / `Cron.get` / `Cron.delete`** — CRUD over jobs.
- **`Cron.enable` / `Cron.disable`** — flip whether the scheduler fires a job.
- **`Cron.run(jobId)`** — trigger a job *now*, off-schedule.
- **`Cron.start` / `Cron.stop` / `Cron.status`** — control the local in-process scheduler.

**Local** jobs fire only while the in-process scheduler is running (`Cron.start()`), in your process.
**Cloud** jobs (Theo PaaS) fire server-side, independent of your process — pre-release. Runtime is
inferred from the target at create time (a `workflow` target is always local).

## Next

- [Schedule a recurring run](/theokit/schedules/schedule-a-recurring-run) — a runnable `Cron.create` example.
- [Advanced](/theokit/schedules/advanced) — the full lifecycle, manual runs, timezones, and the scheduler.

## Reference

- [`Cron`](/theokit/reference/Cron) · [`CronJob`](/theokit/reference/CronJob) · [`CronCreateOptions`](/theokit/reference/CronCreateOptions)

---

# Schedule a recurring run

Source: https://docs.usetheo.dev/theokit/schedules/schedule-a-recurring-run

Define a recurring agent run with Cron.create and inspect the persisted job — deterministic, created disabled so the scheduler never fires.

# Schedule a recurring run

`Cron.create` persists a job and (when enabled) hands it to the scheduler. Creating it **disabled**
keeps the example deterministic — the job is stored and inspectable, but the scheduler never fires it,
so no LLM is called.

```ts title="run.ts"
import { Cron } from "@theokit/sdk";

const job = await Cron.create({
  name: "daily-digest",
  cron: "0 9 * * *",                      // 09:00 every day (POSIX 5-field)
  timezone: "UTC",
  message: "Summarize yesterday's commits.",
  agent: { apiKey, model },                // ephemeral target, fresh per fire
  enabled: false,                          // created disabled — the scheduler won't fire it
});

console.log("cron:    ", job.cron);
console.log("runtime: ", job.runtime);
console.log("enabled: ", job.enabled);
console.log("status:  ", job.status);

await Cron.delete(job.id);                  // clean up
```

## Output

Deterministic — the job is created disabled and immediately deleted:

```text
id:       (assigned)
cron:     0 9 * * *
runtime:  local
enabled:  false
status:   paused
deleted:  true
```

## What it shows

- **`Cron.create({ cron, message, agent, enabled })`** persists a `CronJob` with an assigned `id`,
  the parsed `cron` expression, an inferred `runtime` (`local` from the `agent` target), and a
  `status`. A disabled job is `paused` — it won't fire.
- **Pass exactly one target** — `agent` (ephemeral), `agentId` (reuse), or `workflow`. An agent target
  requires `message`; a workflow target takes `inputData` and must not set `message`.
- **`Cron.delete(job.id)`** removes it. To actually run jobs, drop `enabled: false` and call
  `Cron.start()`.

## Example

Full runnable source:
[`examples/schedule-a-job`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/schedule-a-job).

---

# Schedules and tasks

Source: https://docs.usetheo.dev/theokit/schedules

Run agents on a schedule or in the background.

# Schedules and tasks

Persisted cron jobs fire an agent or a workflow; the Task registry and job queue track long-running work.

| Capability | What it adds |
| --- | --- |
| Cron (`/cron`) | Persisted cron jobs + in-process scheduler |
| `Task` (`/task-store`) | Task observability registry |
| `JobQueue` | Bounded background execution |

## Reference

See the [Schedules and tasks concept](/theokit/concepts/cron) for the deep dive.

---

# OAuth orchestrator

Source: https://docs.usetheo.dev/theokit/server/auth

Add OAuth sign-in to an agent web server with Auth.create — the sign-in → callback → session flow, provider config, and typed errors.

# OAuth orchestrator — `Auth.create`

When you host an agent behind your own HTTP server, `Auth.create` (from `@theokit/sdk/server/auth`) handles the OAuth handshake — redirect to the provider, validate the callback, exchange the code, and hand you a typed session. It is the server-side auth flow, distinct from the `plugins/auth-*` magic-link/social **plugins** (which authenticate a single agent action, not a web session).

```ts
import { Auth } from "@theokit/sdk/server/auth";

const auth = Auth.create<MySession>({
  secret: process.env.AUTH_SECRET!,        // signs the session cookie (min length enforced)
  returnTo: "/app",                        // default post-login redirect
  providers: [githubProvider, googleProvider],
  toSession: async (profile) => ({ userId: profile.id, name: profile.name }),
});
```

## The flow

`Auth.create` returns an orchestrator with the four calls a login route needs:

| Method | When | What it does |
| --- | --- | --- |
| `startSignIn(res, providerName, { returnTo? })` | `GET /auth/:provider` | Builds the provider authorize URL (with a signed transaction) and redirects. |
| `finishSignIn(req, res)` | `GET /auth/callback` | Validates the callback, exchanges the code, sets the session cookie, redirects to `returnTo`. |
| `getSession(req)` | any protected route | Returns the typed session (or `null`) from the cookie. |
| `signOut(res)` | `POST /auth/signout` | Clears the session cookie. |

```ts
// Express-style wiring (any Node http server works):
app.get("/auth/:provider", (req, res) => auth.startSignIn(res, req.params.provider));
app.get("/auth/callback",  (req, res) => auth.finishSignIn(req, res));
app.get("/me", async (req, res) => {
  const session = await auth.getSession(req);
  if (!session) return res.status(401).end();
  res.json(session);
});
```

There is also a `signIn(profile, opts?)` escape hatch (Path A) for issuing a session without a provider round-trip — useful when you already authenticated the user another way.

## Providers

A provider describes one OAuth identity source (`AuthProvider`). Concrete GitHub / Google / email providers ship as opt-in helpers; you can also implement the interface yourself. `providers` is optional — an empty list leaves only the manual `signIn` escape hatch.

## Redirect safety

Never redirect to an attacker-supplied URL. `validateReturnTo(url, allowlist)` returns a safe redirect target (or rejects an open-redirect attempt) — the orchestrator uses it internally, and you should use it for any `returnTo` you accept from the client.

```ts
import { validateReturnTo } from "@theokit/sdk/server/auth";
const safe = validateReturnTo(req.query.returnTo, ["/app", "/dashboard"]);
```

## Errors

Every failure is typed, so your error middleware can branch precisely:

- `AuthCallbackError` — the provider callback was invalid or the code exchange failed.
- `AuthCancelledError` — the user declined at the provider.
- `AuthProviderNotFoundError` — the requested provider name is not registered.
- `AuthConfigError` — misconfiguration (missing client id/secret, bad URLs).
- `AuthSecretTooShortError` — the `secret` used to sign the session cookie is too short.

Pair these with [`@theokit/sdk/server/errors-envelope`](./errors-envelope) to serialize them into a consistent HTTP error body.

## Reference

- [`Auth`](/theokit/reference/Auth) · [`AuthProvider`](/theokit/reference/AuthProvider) · [`validateReturnTo`](/theokit/reference/validateReturnTo)

---

# Error envelope

Source: https://docs.usetheo.dev/theokit/server/errors-envelope

Serialize typed SDK errors into a consistent HTTP body with toEnvelope, and reconstruct them on the client with fromEnvelope.

# Error envelope — `toEnvelope` / `fromEnvelope`

When an agent server returns an error over HTTP, you want one consistent shape — a `code`, a human `message`, and enough structure for the client to branch on. `@theokit/sdk/server/errors-envelope` gives you that, and lets the client turn the wire shape back into a typed `TheokitAgentError`.

## Server: any error → a stable body

```ts
import { toEnvelope } from "@theokit/sdk/server/errors-envelope";

app.use((err, _req, res, _next) => {
  const envelope = toEnvelope(err);            // works on any value, not just SDK errors
  res.status(statusFor(envelope.code)).json(envelope);
});
```

`toEnvelope(value)` normalizes anything you throw — a `RateLimitError`, a `ConfigurationError`, a plain `Error`, or a non-error value — into a `TheokitErrorEnvelope`: `{ code, message, … }`. The `code` is a stable `TheokitErrorCode` your HTTP layer can map to a status.

## Client: body → typed error

```ts
import { fromEnvelope } from "@theokit/sdk/server/errors-envelope";

const res = await fetch("/api/run", { method: "POST", body });
if (!res.ok) {
  const err = fromEnvelope(await res.json());  // a real TheokitAgentError subclass
  if (err instanceof RateLimitError) backOff();
  throw err;
}
```

`fromEnvelope(envelope)` reconstructs the typed `TheokitAgentError` from the wire shape, so the same `instanceof` checks you use in-process work across the network boundary. Pair it with [`isTransientError`](/theokit/concepts/errors) for retry decisions.

## Why an envelope

- **One shape everywhere** — every surface (server adapter, [OAuth orchestrator](./auth), gateway) serializes errors the same way.
- **No leaking internals** — the envelope carries a stable `code` + message, not a stack trace.
- **Round-trips the type** — `fromEnvelope(toEnvelope(err))` restores the original error class.

## Reference

- [`toEnvelope`](/theokit/reference/toEnvelope) · [`fromEnvelope`](/theokit/reference/fromEnvelope) · [`TheokitErrorEnvelope`](/theokit/reference/TheokitErrorEnvelope)

---

# Overview

Source: https://docs.usetheo.dev/theokit/server

The ways to expose a @theokit/sdk agent as a server — pick the surface that matches your client (an editor, a browser stream, a chat platform, or the cloud).

# Serving agents

A `@theokit/sdk` agent runs in-process by default. To reach it from *outside* that process, you expose
it through one of the SDK's serving surfaces. There is no single generic "server" object — you pick
the surface that matches your client:

| Client | Surface | Section |
| --- | --- | --- |
| An editor (Zed, …) speaking ACP | `serveAcp` — stdio JSON-RPC, per-session agents | [ACP server](/theokit/acp) |
| A browser / app consuming a live stream | `Subscription.create` + `subscribe` over WS/SSE | [Subscriptions](/theokit/subscriptions) |
| A chat platform (Slack, Discord, WhatsApp, …) | A gateway that turns inbound messages into `agent.send()` | [Gateways](/theokit/gateways) |
| A hosted runtime with its own endpoint | Theo PaaS via `cloud: {…}` + `TheoKitClient` | [Cloud runtime](/theokit/cloud) |

## How to choose

- **Building an IDE integration?** → [ACP](/theokit/acp) — the protocol editors already speak.
- **Streaming tokens/updates to a web UI?** → [Subscriptions](/theokit/subscriptions) — typed
  server→client frames with resume tokens.
- **Answering messages on a chat platform?** → [Gateways](/theokit/gateways) — a ready adapter per
  platform, so you write the agent, not the webhook plumbing.
- **Want someone else to host it?** → [Cloud runtime](/theokit/cloud) (pre-release) — Theo PaaS runs
  the agent and you reach it with the typed client.

Each surface wraps the **same** agent contract — `agent.send()` and the discriminated `SDKMessage`
stream — so the agent you build locally is the agent you serve, unchanged.

## Reference

- [`serveAcp`](/theokit/reference/serveAcp) · [`Subscription`](/theokit/reference/Subscription) · [`TheoKitClient`](/theokit/reference/TheoKitClient)

---

# HTTP server adapters

Source: https://docs.usetheo.dev/theokit/server

Serve agents over HTTP.

# HTTP server adapters

Framework adapters turn an agent into an HTTP handler, with OAuth orchestration for auth.

| Capability | What it adds |
| --- | --- |
| `/server/adapter` | Express / Fastify / Hono handlers |
| `/server/auth` | `Auth.create` + OAuth orchestration |

---

# Advanced

Source: https://docs.usetheo.dev/theokit/sessions/advanced

The native transcript record shape, write/read/compaction semantics, scoped conversation ids, and Claude Code CLI interop.

# Advanced sessions

Verified against the SDK. Conversation persistence is the native Claude Code `.jsonl` transcript —
the file on disk is the store.

## The record shape

Records are a `uuid` / `parentUuid` DAG. Each line is one record with:

- a `type` — `"user"`, `"assistant"`, or `"system"`;
- an envelope — `sessionId`, `timestamp`, `cwd`, `version`;
- a `message.content` array of structured blocks — `text`, `thinking`, `tool_use { id, name, input }`,
  `tool_result { tool_use_id, content, is_error }`.

A `system` record with `subtype: "compact_boundary"` is a new root (`parentUuid: null`) carrying
`compactMetadata`.

## Write / read / compaction

- **WRITE** — after each send, the whole turn (user text + assistant text/thinking + paired
  `tool_use` / `tool_result` blocks, taken from `run.conversation()`) is appended as native records
  under a cross-process file lock. Secrets are redacted before disk.
- **READ / resume** — hydration parses the lines, builds the uuid index, finds the most-recent leaf
  (a uuid never used as a `parentUuid`), and walks `parentUuid` back to a root. Tool turns fold into
  assistant-role context so a resumed agent keeps its tool history.
- **COMPACTION** — append-only. A `compact_boundary` record is appended; the transcript is never
  shrunk. A resume after a boundary replays only the post-boundary continuation.
- A torn last line (a crash mid-write) is skipped on read — the rest of the DAG still reconstructs.

## Scoped conversation ids

A conversation id can be namespaced by scope so app-durable, user-durable, and ephemeral session
data stay separated:

```ts
import { scopedConversationId, sessionScopePrefix } from "@theokit/sdk";

scopedConversationId("user", "abc");  // → "user__abc"  (scope ∈ "app" | "user" | "temp")
sessionScopePrefix("user");           // → "user__"
```

These are pure id helpers (the `__` separator is path-safe). Scope pruning against a storage backend
is no longer part of the SDK.

## Claude Code CLI interop

`local.baseDir` controls the root. The default `~/.theokit` isolates the SDK's sessions; set
`~/.claude` to write sessions the Claude Code CLI can `--continue`:

```ts
const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd(), baseDir: "~/.claude" },
});
// writes to ~/.claude/projects/<encoded-cwd>/<agentId>.jsonl
```

Extended-thinking signatures are written but dropped on read, so functional `--continue` for
extended thinking is out of scope for now (tracked as issue #122).

## Reference

- [`Agent`](/theokit/reference/Agent) — `Agent.create` / `Agent.resume`
- [`LocalOptions`](/theokit/reference/LocalOptions) — `cwd` and `baseDir`
- [`scopedConversationId`](/theokit/reference/scopedConversationId) · [`sessionScopePrefix`](/theokit/reference/sessionScopePrefix) · [`SessionScope`](/theokit/reference/SessionScope)

---

# Overview

Source: https://docs.usetheo.dev/theokit/sessions

How an agent's conversation persists — the native Claude Code transcript on disk — and how to resume it in a fresh process.

# Sessions

A local agent's conversation **is** a native Claude Code `.jsonl` transcript on disk. There is no
proprietary session store and no pluggable storage adapter — the transcript is the single source of
truth. Every send appends the whole turn (user text, assistant text and thinking, and paired
`tool_use` / `tool_result` blocks) as native records, append-only. Secrets are redacted before disk.

```ts
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd() },   // baseDir defaults to ~/.theokit
});

await (await agent.send("first message")).wait();
await agent.dispose();
```

The transcript lands at `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`.

## Where it lives

| Setting | Value |
| --- | --- |
| `local.baseDir` | The root directory. Default `~/.theokit` (isolates the SDK's sessions). |
| Path | `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl` |
| Format | A `uuid` / `parentUuid` DAG of records, one JSON object per line. |

Set `baseDir` to `~/.claude` so the Claude Code CLI can `--continue` a session your agent wrote:

```ts
const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd: process.cwd(), baseDir: "~/.claude" },
});
// writes to ~/.claude/projects/<encoded-cwd>/<agentId>.jsonl
```

## Resuming

A fresh process reconstructs the transcript DAG — walking the most-recent leaf back to a root — so a
resumed agent keeps its full conversation, including tool history:

```ts
const resumed = await Agent.resume(agent.agentId, {
  local: { cwd: process.cwd(), baseDir: "~/.theokit" },
});
```

## Compaction is append-only

When context is compacted, a `compact_boundary` system record (a new root) is appended — the
transcript is **never** shrunk. A resume after a boundary replays only the post-boundary
continuation.

## Next

- [Resume a session](/theokit/sessions/manage-sessions) — a runnable resume + `--continue` example.
- [Advanced](/theokit/sessions/advanced) — the record shape, scoped ids, and Claude Code CLI interop.

## Reference

- [`Agent`](/theokit/reference/Agent) — `Agent.create` / `Agent.resume`
- [`LocalOptions`](/theokit/reference/LocalOptions) — `cwd` and `baseDir`
- [`scopedConversationId`](/theokit/reference/scopedConversationId) — namespace a conversation id by scope

---

# Resume a session

Source: https://docs.usetheo.dev/theokit/sessions/manage-sessions

Persist a conversation to the native transcript, dispose the agent, then resume the same agentId in a fresh process and recall the history.

# Resume a session

A local agent writes its conversation to a native Claude Code `.jsonl` transcript on disk. Resume the
same `agentId` in a fresh process and the agent rehydrates the whole conversation — including tool
history — from that transcript.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";
import { transcriptPath } from "@theokit/sdk/persistence";

const apiKey = process.env.OPENROUTER_API_KEY;
const cwd = process.cwd();
const agentId = `agent-sessions-${Date.now().toString(36)}`;
const baseDir = "~/.theokit"; // or "~/.claude" for Claude Code CLI `--continue` interop

// 1. Create + send (plant a fact), then dispose to flush the transcript to disk.
const agent = await Agent.create({
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  agentId,
  systemPrompt: "You are concise. Remember facts the user tells you.",
  local: { cwd, baseDir },
});
await (await agent.send("Remember my favorite color is teal. Reply with just: OK.")).wait();
console.log("Transcript:", transcriptPath(baseDir, cwd, agentId));
await agent.dispose();

// 2. Resume the SAME agentId (a simulated restart) — the transcript rehydrates the history.
const resumed = await Agent.resume(agentId, {
  apiKey,
  model: { id: "openai/gpt-4o-mini" },
  local: { cwd, baseDir },
});
const recall = await (
  await resumed.send("What is my favorite color? Reply with just the color.")
).wait();
console.log("Recalled across restart:", String(recall.result).trim());
await resumed.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Transcript: ~/.theokit/projects/<encoded-cwd>/agent-sessions-<id>.jsonl
Recalled across restart: teal
```

## What it shows

- **The transcript is the store** — `Agent.create` writes native records to
  `<baseDir>/projects/<encoded-cwd>/<agentId>.jsonl`; `dispose()` flushes them.
- **`Agent.resume(agentId, { local: { cwd, baseDir } })`** rehydrates the conversation by walking the
  transcript DAG, so the resumed agent recalls the planted fact.
- **`baseDir: "~/.claude"`** writes a session the Claude Code CLI can pick up with `claude --continue`
  (extended-thinking `--continue` is out of scope for now — issue #122).

## Example

Full runnable source:
[`examples/sessions-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/sessions-basics).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/skills/advanced

Skill discovery from disk, enable lists and auto-inject, bundled reference documents, a custom skills directory, and the model-facing SkillReadTool.

# Advanced skills

Verified against `@theokit/sdk` (`create-skill.ts`, `define-skill-read-tool.ts`, `types/agent.ts`).

## Skill sources — `SkillsSettings`

```ts
skills: {
  inline: [shipSkill],       // code-defined skills
  enabled: ["ship", "test"],  // allowlist; omit to enable every discovered skill
  autoInject: true,           // inject the <skills> block into the system prompt (default true)
  skillsDir: "./my-skills",   // custom directory for file skills (M22)
}
```

- **`enabled`** — restrict which discovered skills the agent may use. Omit and *all* discovered skills
  are enabled.
- **`autoInject: false`** — stop the SDK from injecting the `<skills>` block, e.g. when a custom
  `systemPrompt` resolver formats skills itself.
- **`skillsDir`** — point discovery at a custom directory instead of the default `.theokit/skills/`.

## Discovery from disk

With `local: { settingSources: ["project"] }`, the SDK discovers file skills at
`.theokit/skills/<name>/SKILL.md` — each folder's `SKILL.md` supplies the body, and a `references/`
directory beside it supplies bundled documents. Inline and file skills coexist; a name conflict fails
fast (mirrors the subagents-loader precedent).

## Reference documents

Both inline and file skills can bundle supporting documents (`filename → content`):

```ts
Skill.create({
  name: "ship", description: "…", instructions: "…",
  references: { "checklist.md": "1. tests green\n2. changelog updated" },
});
```

References are surfaced to the app via `agent.skills.get(name).references` — they are **not** injected
into the model prompt (they're app-facing context, not token budget).

## Let the model pull skill bodies — `SkillReadTool`

By default only name + description reach the model. To let the **model** decide when to load a skill's
full instructions, give it the read tool:

```ts
import { Agent, SkillReadTool } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey, model,
  tools: [SkillReadTool.create([shipSkill, testSkill])],
});
```

`SkillReadTool.create(skills)` returns a `CustomTool`; the model calls it with a skill name and gets
the body back as the tool result. Duplicate skill names throw at construction.

## The inspector — `SDKAgentSkills`

```ts
interface SDKAgentSkills {
  list(): Promise<ReadonlyArray<{ name; description }>>;
  get(name): Promise<{ name; description; instructions; references? } | undefined>;
}
```

`list()` stays lean; `get()` returns the full body — `undefined` when no enabled skill matches.

## Reference

- [`Skill`](/theokit/reference/Skill) · [`CreateSkillSpec`](/theokit/reference/CreateSkillSpec) · [`SkillReadTool`](/theokit/reference/SkillReadTool) · [`SDKAgentSkills`](/theokit/reference/SDKAgentSkills) · [`SkillsSettings`](/theokit/reference/SkillsSettings)

---

# Give an agent a skill

Source: https://docs.usetheo.dev/theokit/skills/give-an-agent-a-skill

Define an inline skill with Skill.create, attach it to an agent, and inspect it through agent.skills — deterministic, no LLM.

# Give an agent a skill

`Skill.create` defines a capability in code; `skills: { inline: [...] }` attaches it. The
`agent.skills` inspector then reports what the agent loaded — all local, so this is deterministic.

```ts title="run.ts"
import { Agent, Skill } from "@theokit/sdk";

const shipSkill = Skill.create({
  name: "ship",
  description: "How to deploy this project to production.",
  instructions: "Run the test suite, then `npm run ship`. Never deploy on a red build.",
});

const agent = await Agent.create({
  apiKey: "theo_test_skills",              // fixture key — no LLM
  model: { id: "openai/gpt-4o-mini" },
  skills: { inline: [shipSkill] },
});

const listed = await agent.skills?.list();
console.log("skills:", listed?.map((s) => s.name).join(", "));

const detail = await agent.skills?.get("ship");
console.log("ship description:", detail?.description);
console.log("body loaded?    ", typeof detail?.instructions === "string");

await agent.dispose?.();
```

## Output

Deterministic — the inspector reads local state:

```text
skills: ship
ship description: How to deploy this project to production.
body loaded?     true
```

## What it shows

- **`Skill.create({ name, description, instructions })`** builds an inline skill — no `SKILL.md` file
  needed. It fails fast if `name` or `description` is empty.
- **`agent.skills.list()`** returns the lean `{ name, description }` refs — exactly what the SDK
  injects into the model's `<skills>` block.
- **`agent.skills.get(name)`** returns the full detail, including the `instructions` body — fetched on
  demand so the system prompt stays small.

## Example

Full runnable source:
[`examples/skills-inline`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/skills-inline).

---

# Overview

Source: https://docs.usetheo.dev/theokit/skills

Give an agent reusable capabilities — inline code-defined skills or ones discovered from disk — with name+description in the prompt and bodies fetched on demand.

# Skills

A **skill** is a named, described capability an agent can draw on. Its `name` + `description` go into
the model's `<skills>` system-prompt block so the model knows it exists; the full `instructions`
(body) are fetched on demand, keeping the prompt lean.

```ts
import { Agent, Skill } from "@theokit/sdk";

const ship = Skill.create({
  name: "ship",
  description: "How to deploy this project to production.",
  instructions: "Run the tests, then `npm run ship`. Never deploy on a red build.",
});

const agent = await Agent.create({ apiKey, model, skills: { inline: [ship] } });
```

## Skills vs Subagents

Easy to confuse — the shapes look alike (`name` / `description` / `instructions`), but they do
opposite things:

| | **Skill** | **[Subagent](/theokit/subagents)** |
| --- | --- | --- |
| What it is | An instruction pack injected into **this** agent's prompt | A separate specialist **agent** exposed as a delegation tool |
| Runs its own LLM turn? | **No** — no extra call; shares this agent's context | **Yes** — the child runs in isolation and returns a result (costs one more call) |
| Mental model | "the agent **knows how** to do X" | "there **is an agent** that does X" |

They are **not nested** — a subagent does not take `skills`; its own `prompt` already plays the
skill's role. A supervisor can carry skills (its knowledge) *and* delegate to subagents (their
knowledge) at the same time.

## Two sources

- **Inline** — `Skill.create(spec)` defines a skill in code (no files). Pass them via
  `skills: { inline: [...] }`.
- **From disk** — with `settingSources: ["project"]`, the SDK discovers `.theokit/skills/<name>/SKILL.md`
  skills automatically.

## Inspect what's loaded — `agent.skills`

- **`agent.skills.list()`** → the enabled skills as `{ name, description }` (lean — no bodies).
- **`agent.skills.get(name)`** → the full detail including `instructions` and any bundled `references`.

## Let the model read skills — `SkillReadTool`

By default the SDK injects only name + description. `SkillReadTool.create(skills)` returns a tool that
lets the **model** pull a skill's full body on demand — opt-in, for when you want the model to decide
which instructions to load.

## Next

- [Give an agent a skill](/theokit/skills/give-an-agent-a-skill) — a runnable inline-skill example.
- [Advanced](/theokit/skills/advanced) — discovery, enable lists, references, and the read tool.

## Reference

- [`Skill`](/theokit/reference/Skill) · [`CreateSkillSpec`](/theokit/reference/CreateSkillSpec) · [`SkillReadTool`](/theokit/reference/SkillReadTool) · [`SDKAgentSkills`](/theokit/reference/SDKAgentSkills)

---

# Skills

Source: https://docs.usetheo.dev/theokit/skills

Composable abilities you attach to agents.

# Skills

Skills are discovered from the filesystem or defined inline, and surfaced to the model as a `<skills>` block.

| Capability | What it adds |
| --- | --- |
| Filesystem skills (`/skills`) | `discoverSkills` + `buildSkillsBlock` |
| `Skill.create` | Inline, code-defined skills |
| `SkillReadTool.create` | Lazy skill-read tool for the model |

---

# Advanced

Source: https://docs.usetheo.dev/theokit/squad/advanced

The full Squad contract — options, the SquadRun and per-agent StepResult shapes, the sequential-only constraint, and the escape hatch to Workflow.

# Advanced squad

`Squad` is deliberately small — a convenience wrapper that compiles its agents into a
[`Workflow`](/theokit/workflows) of `agentStep`s. This page is the exact contract, verified against
the SDK, and the escape hatch for when a squad is not enough.

## Options — `SquadOptions`

```ts
Squad.create({
  agents,             // ReadonlyArray<SDKAgent> — MUST be non-empty; run order = array order
  process,            // "sequential" (default). "hierarchical" is rejected — see below
  name,               // optional; default "squad" (surfaced on the underlying workflow)
});
```

## The result — `SquadRun`

```ts
interface SquadRun {
  readonly result: unknown;                 // the LAST agent's output (end of the pipeline)
  readonly status: "running" | "completed" | "failed" | "suspended" | "cancelled";
  readonly steps: ReadonlyArray<StepResult>; // one per agent, in order
}
```

Each entry in `steps` is a `StepResult` — inspect what each agent contributed and how it went:

```ts
interface StepResult {
  readonly stepId: string;
  readonly kind: Step["kind"];              // "agent" for squad steps
  readonly status: "completed" | "failed" | "skipped" | "suspended";
  readonly attempts: number;
  readonly durationMs: number;
  readonly output?: unknown;
  readonly error?: { name: string; message: string };
}
```

`run()` never throws on a mid-pipeline failure — the run's `status` becomes `"failed"` and the
failing agent's `StepResult` carries the `error`.

## Sequential only — the exact constraint

`process` accepts `"sequential"` (the default) or `"hierarchical"`, but **`"hierarchical"` is
rejected at runtime** with a typed `ConfigurationError` (`code: "squad_process_unsupported"`) that
points you at the right primitive:

> `Squad only supports process "sequential"; for manager→worker delegation use subagents or @theokit/sdk-handoff`

The SDK ships one orchestration model per primitive rather than a second, weaker one inside Squad.

## Escape hatch — drop to a Workflow

Because a squad **is** a `Workflow` of `agentStep`s under the hood, anything richer than a straight
pipeline is a few lines of [Workflow](/theokit/workflows) — with each agent expressed as an
`agentStep`:

| You need | Reach for |
| --- | --- |
| Branch on an agent's output, run agents in parallel, `foreach`, `dowhile` | [`Workflow`](/theokit/workflows) — `.branch` / `.parallel` / `.foreach` / `.dowhile`. |
| Retry a flaky agent step, or a per-step timeout | [`Workflow`](/theokit/workflows/advanced) — `retry` on the step. |
| Pause for human approval between agents | [`Workflow`](/theokit/workflows/advanced) — `suspend` / `Workflow.resume`. |
| A manager agent that decides which worker handles a task | [Subagents](/theokit/subagents) or [Handoffs](/theokit/handoffs). |

```ts
// The squad below …
Squad.create({ agents: [research, write, edit] });

// … is equivalent to this workflow (which you can then extend with branch/retry/suspend):
Workflow.create({ name: "squad" })
  .then(agentStep("research", research, (i) => String(i)))
  .then(agentStep("write", write, (i) => String(i)))
  .then(agentStep("edit", edit, (i) => String(i)))
  .commit();
```

## Reference

- [`Squad`](/theokit/reference/Squad) · [`SquadOptions`](/theokit/reference/SquadOptions) · [`SquadRun`](/theokit/reference/SquadRun) · [`StepResult`](/theokit/reference/StepResult)

---

# Overview

Source: https://docs.usetheo.dev/theokit/squad

Run a team of agents as a sequential pipeline — each agent's output feeds the next.

# Squad

A **squad** is a team of agents that run in order: the first agent's reply becomes the second
agent's input, and so on. It's the thin, zero-ceremony way to express the common "research → write
→ edit" shape without building a full [workflow](/theokit/workflows).

```ts
import { Agent, Squad } from "@theokit/sdk";

const squad = Squad.create({ agents: [researcher, writer, editor] });
const run = await squad.run("Write a post about TypeScript agents.");

run.result; // the last agent's output
run.status; // "completed" | "failed" | …
run.steps;  // one StepResult per agent
```

## The result

`squad.run(input)` returns a `SquadRun`:

| Field | What it is |
| --- | --- |
| `result` | The final agent's output (the end of the pipeline). |
| `status` | `"completed"` \| `"failed"` \| `"suspended"` \| `"cancelled"` \| `"running"`. |
| `steps` | One `StepResult` per agent, in order — inspect what each contributed. |

`run()` does not throw on a mid-pipeline failure; it returns `status: "failed"` with the error
captured in `steps`.

## Sequential only — by design

`Squad.create` supports exactly one process: **sequential**. It's a convenience wrapper over the
[`Workflow`](/theokit/workflows) engine (each agent becomes an `agentStep`). For anything richer,
reach for the primitive that already fits:

| You need | Use |
| --- | --- |
| A team that runs in order | **Squad** (this page). |
| Branching, parallelism, retries, suspend/resume | [**Workflow**](/theokit/workflows). |
| A manager agent that delegates to workers | [**Subagents**](/theokit/subagents) or [**Handoffs**](/theokit/handoffs). |

Passing `process: "hierarchical"` is rejected at runtime with guidance — the SDK points you at
subagents / handoffs rather than shipping a second, weaker orchestration model.

## Next

- [Run a squad](/theokit/squad/run-a-squad) — a runnable two-agent example.

## Reference

- [`Squad`](/theokit/reference/Squad) · [`SquadOptions`](/theokit/reference/SquadOptions) · [`SquadRun`](/theokit/reference/SquadRun)

---

# Run a squad

Source: https://docs.usetheo.dev/theokit/squad/run-a-squad

Build a two-agent Squad — a brainstormer proposes ideas, a picker chooses the best — and run it end-to-end.

# Run a squad

Give `Squad.create` a list of agents and call `run(input)`. The agents fire in order; the first
agent's reply is the second agent's input.

```ts title="run.ts"
import { Agent, Squad } from "@theokit/sdk";

const brainstormer = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "List exactly 3 short product name ideas as a comma-separated line. No preamble.",
});

const picker = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "From the given list, pick the single best name and reply with just that name and a 6-word reason.",
});

const squad = Squad.create({ agents: [brainstormer, picker] });

const run = await squad.run("a focus timer app for developers");

console.log("Status:", run.status);
console.log("Steps:", run.steps.length);
console.log("Result:", run.result);

await brainstormer.dispose();
await picker.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Status: completed
Steps: 2
Result: CodePulse — concise, memorable, conveys coding rhythm.
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- **`Squad.create({ agents: [brainstormer, picker] })`** — a sequential team; array order is run
  order.
- **State flows down the line** — the brainstormer's comma-separated ideas become the picker's
  input; the picker returns the final pick.
- **`run.steps.length === 2`** — one `StepResult` per agent, so you can see each contribution.
- **`run.result`** — the last agent's output, i.e. the end of the pipeline.

## Example

Full runnable source:
[`examples/squad-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/squad-basics).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/streaming/advanced

Lower-level streaming — per-token onDelta/onStep callbacks, the InteractionUpdate union, backpressure, and per-send toolChoice.

# Advanced streaming

`run.stream()` yields **normalized `SDKMessage` events** (full messages). For **lower-level**
updates — per-token text, tool-call arguments streaming in, thinking deltas, step boundaries — pass
`onDelta` and `onStep` callbacks to `send()` instead.

## Token-level callbacks — `onDelta` / `onStep`

```ts
const run = await agent.send("Refactor the utils module", {
  onDelta: ({ update }) => {
    if (update.type === "text-delta") process.stdout.write(update.text);
    if (update.type === "thinking-delta") process.stdout.write(update.text);
  },
  onStep: ({ step }) => {
    console.log(`[step] ${step.type}`);
  },
});
```

- **`onDelta({ update })`** fires per raw `InteractionUpdate`.
- **`onStep({ step })`** fires after each completed conversation step (text, thinking, or tool batch).

## The `InteractionUpdate` union

`update.type` is one of: `text-delta`, `thinking-delta`, `thinking-completed`, `tool-call-started`,
`partial-tool-call`, `tool-call-completed`, `token-delta`, `step-started`, `step-completed`,
`turn-ended`, plus a handful of summary and shell-output deltas. Discriminate on `type` and read the
fields that variant carries (e.g. `text` on `text-delta`, tool name/args on the tool-call updates).

## Backpressure

The callbacks are **awaited before the next update is processed** — so an async `onDelta` applies
backpressure. Use it to throttle a UI, persist tokens, or await a slow sink without dropping updates.

## `run.stream()` vs `onDelta` — which to use

| You want | Use |
| --- | --- |
| Full messages to render or react to (chat UI, tool-call reactions) | `run.stream()` (the [Overview](/theokit/streaming)). |
| Per-token text / thinking deltas, tool-args streaming in | `onDelta` / `onStep` on `send()`. |

Both can run on the same send; they are additive.

## Related per-send controls

- **`toolChoice: "auto" \| "none" \| "required"`** — a per-call tool gate. `"none"` forces a text
  answer even when tools are registered (e.g. a closing summary at a step ceiling); `"required"`
  forces a tool call. OpenAI-compatible providers, local runtime.

## Reference

- [`SDKMessage`](/theokit/reference/SDKMessage) · [`InteractionUpdate`](/theokit/reference/InteractionUpdate) · [`Run`](/theokit/reference/Run) · [`RunResult`](/theokit/reference/RunResult)

---

# Overview

Source: https://docs.usetheo.dev/theokit/streaming

Consume an agent's output as it arrives — the SDKMessage event stream, and when to use it.

# Streaming

`agent.send()` returns a `Run`. You can `await run.wait()` for the complete result, or
iterate `run.stream()` to consume the output **as it arrives** — for a live chat UI, or to
react to tool calls mid-run.

```ts
const run = await agent.send("Tell me a story.");
for await (const msg of run.stream()) {
  if (msg.type === "assistant") { /* render msg.message.content */ }
}
```

## The `SDKMessage` event union

`run.stream()` yields **full messages**, not token deltas — a discriminated union you
switch on by `msg.type`:

| `type` | Meaning |
| --- | --- |
| `system` | Run init metadata (agent id, run id). |
| `user` | The submitted message, echoed back. |
| `assistant` | Model output — `.message.content` is `text` / `tool_use` blocks. |
| `tool_call` | A tool the model invoked. |
| `thinking` | Reasoning content, when the model emits it. |
| `status` | Progress / lifecycle signals. |

For a chat-like experience you print the `text` blocks of each `assistant` message.

## Draining vs. awaiting

Pick **one** primary consumer: `for await` the stream, or `await run.wait()`. Calling
`run.wait()` *after* the stream drains is cheap and returns the terminal `RunResult`
(status, usage, cost) — so a streaming UI can still report the final outcome.

## Next

- [Stream a response](/theokit/streaming/stream-a-response) — a runnable example.

## Reference

- [`SDKMessage`](/theokit/reference/SDKMessage) · [`Run`](/theokit/reference/Run) · [`RunResult`](/theokit/reference/RunResult)

---

# Stream a response

Source: https://docs.usetheo.dev/theokit/streaming/stream-a-response

Iterate run.stream() to consume the agent's output as it arrives, instead of awaiting the whole result.

# Stream a response

Iterate `run.stream()` and switch on `msg.type` to consume the output as it arrives, then
`await run.wait()` for the terminal result.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You are a concise storyteller.",
});

const run = await agent.send("Tell me a two-sentence story about a curious robot.");

for await (const msg of run.stream()) {
  switch (msg.type) {
    case "assistant":
      for (const block of msg.message.content) {
        if (block.type === "text") process.stdout.write(block.text);
        else if (block.type === "tool_use") console.log(`\n[tool_use] ${block.name}`);
      }
      break;
    case "tool_call":
      console.log(`\n[calling tool] ${msg.name}`);
      break;
    default:
      break; // "system" | "user" | "thinking" | "status" | … — ignored here.
  }
}

// After the stream drains, wait() resolves to the terminal RunResult.
const result = await run.wait();
console.log(`\n\n[done] status=${result.status}`);

await agent.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
The curious robot slipped into the abandoned library, its sensors humming as it scanned each
dust-covered tome for hidden code. When a cracked spine whispered a forgotten algorithm, the
machine's eyes flickered alive, and it began writing its own story.

[done] status=finished
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## Example

Full runnable source:
[`examples/agent-streaming`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/agent-streaming).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/structured-output/advanced

Retries and validation-failure strategy, the full result shape, the static generate/stream forms, and streaming a typed object.

# Advanced structured output

Verified against the SDK.

## `GenerateOptions`

`agent.generate` takes a `SendOptions` (so `model`, `tools`, `systemPrompt`, etc. all apply) plus:

```ts
{
  output,                 // the Zod schema — the structuring contract
  maxRetries: 1,          // parse-failure retries on the structuring phase (default 1)
  errorStrategy: "throw", // what happens when validation still fails after retries:
                          //   "throw"          → throw (default)
                          //   "return-partial" → salvage a partial object into `raw`
                          //   "return-raw"     → return the raw pre-parse value in `raw`
}
```

## The result — `GenerateRunResult`

```ts
interface GenerateRunResult<O> {
  object: O;              // the validated object, typed from `output`
  result: RunResult;      // the underlying tool-loop run (phase 1) — status, usage, cost
  raw: unknown;           // the model's raw input to the synthetic output tool, before Zod parse
  usage: { inputTokens: number; outputTokens: number };  // structuring-phase tokens
}
```

Note the two token counts: `result.usage` is the tool-loop turn; the top-level `usage` is the
structuring phase.

## Static forms — no persistent agent

| Call | Use |
| --- | --- |
| `Agent.generateObject(options)` | Buffered structured output without creating a long-lived agent. Same prompt + schema + model is deterministic-parity with `agent.generate`. |
| `Agent.streamObject(options)` | Streaming structured output — an `AsyncGenerator` of events for a live UI. |

## Streaming a typed object — `Agent.streamObject`

`Agent.streamObject` yields a `StreamObjectEvent` as the object fills in, then a final one:

```ts
for await (const ev of Agent.streamObject({ /* prompt, output, model, apiKey */ })) {
  if (ev.type === "partial") render(ev.partial);   // DeepPartial<T>, plus ev.attempt
  if (ev.type === "complete") done(ev.object);      // T, plus ev.raw / ev.usage / ev.finishReason
}
```

- **`{ type: "partial"; partial: DeepPartial<T>; attempt }`** — progressive, partially-filled object.
- **`{ type: "complete"; object: T; raw; usage; finishReason }`** — the validated final object.

A model that refuses the synthetic tool, or fails every retry, throws a `StreamObjectError` (same
code taxonomy as `GenerateObjectError`).

## Reference

- [`Agent`](/theokit/reference/Agent) · [`GenerateOptions`](/theokit/reference/GenerateOptions) · [`GenerateRunResult`](/theokit/reference/GenerateRunResult) · [`StreamObjectEvent`](/theokit/reference/StreamObjectEvent)

---

# Overview

Source: https://docs.usetheo.dev/theokit/structured-output

Get a validated, inferred-typed object back from an agent — not just text — with a Zod schema.

# Structured output

When you need data, not prose, declare a Zod schema and let the agent fill it. `agent.generate`
runs the normal tool loop, then coerces the final answer into your schema and returns a **validated,
inferred-typed object** — no manual JSON parsing, no casts.

```ts
const { object } = await agent.generate("Extract the invoice fields.", {
  output: z.object({ total: z.number(), currency: z.string() }),
});
object.total; // typed as number
```

Under the hood the SDK forces a single synthetic tool whose schema *is* your Zod schema, then
Zod-parses the model's output — so the type you declare is the type you get.

## Three forms

| Call | Shape |
| --- | --- |
| `agent.generate(message, { output })` | Instance method — returns `{ object, result, raw, usage }`. |
| `Agent.generateObject(options)` | Static, buffered — same result, no persistent agent. |
| `Agent.streamObject(options)` | Static, streaming — an `AsyncGenerator` of `partial` → `complete` events for a live UI. |

## Next

- [Return structured output](/theokit/structured-output/return-structured-output) — a runnable example.
- [Advanced](/theokit/structured-output/advanced) — retries, validation-failure strategy, the raw
  input, and streaming.

## Reference

- [`Agent`](/theokit/reference/Agent) · [`GenerateOptions`](/theokit/reference/GenerateOptions) · [`GenerateRunResult`](/theokit/reference/GenerateRunResult)

---

# Return structured output

Source: https://docs.usetheo.dev/theokit/structured-output/return-structured-output

Coerce an agent's answer into a validated, inferred-typed object with a Zod schema via agent.generate().

# Return structured output

`agent.generate(message, { output: schema })` runs the normal tool loop, then coerces the final
answer into your Zod schema and returns a **validated, inferred-typed object**.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";
import { z } from "zod";

const Sentiment = z.object({
  sentiment: z.enum(["positive", "neutral", "negative"]),
  score: z.number().min(0).max(1).describe("Confidence between 0 and 1."),
  summary: z.string().describe("One short sentence summarizing the review."),
});

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You analyze product reviews and return structured sentiment.",
});

const { object } = await agent.generate(
  "Review: 'The battery lasts two days and the screen is gorgeous, but it's pricey.'",
  { output: Sentiment },
);

// `object` is typed: { sentiment: "positive" | "neutral" | "negative"; score: number; summary: string }
console.log("sentiment:", object.sentiment);
console.log("score:    ", object.score);
console.log("summary:  ", object.summary);

await agent.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
sentiment: neutral
score:     0.9
summary:   Battery life and screen are praised while price is criticized.
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- **`agent.generate(message, { output })`** returns `{ object, result, raw, usage }` — `object` is the
  validated value, typed from your schema.
- **`.describe()`** on a schema field becomes guidance the model sees — use it to steer the output.
- **No parsing** — the SDK forces a synthetic tool whose schema *is* your Zod schema, then Zod-parses
  the result, so the declared type is the returned type.

For retries, the validation-failure strategy, the `raw` pre-parse value, and streaming, see
[Advanced](/theokit/structured-output/advanced).

## Example

Full runnable source:
[`examples/agent-structured-output`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/agent-structured-output).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/subagents/advanced

The delegation lifecycle hooks, parent-context forwarding, tool-result inclusion, and recursion depth control.

# Advanced subagents

The full `SubAgentSpec`, verified against the SDK. Every field beyond `name` / `description` /
`instructions` is opt-in.

## Credential inheritance

A delegated child is a full agent that must authenticate. It **inherits the supervisor's `apiKey` and
model automatically** — you don't pass them to the subagent. A `model` on the spec (or `"inherit"`)
overrides just the model; the key always comes from the parent.

The parent's key is threaded **only to first-party subagent tools** through a private per-tool channel
— it never appears on the `ctx` handed to your own custom tools. (Before this, a subagent created with
no key hit `AuthenticationError: Missing API key` whenever the parent used an explicit key rather than
`THEOKIT_API_KEY`.)

## Declarative form — `agents: { name: AgentDefinition }`

Instead of building tools with `SubAgent.create`, declare subagents on the supervisor. Each entry is
converted to a delegation tool for the local runtime:

```ts
agents: {
  reviewer: {
    description: "Reviews code for bugs and security issues.",
    prompt: "You are a senior code reviewer. Be terse. Flag correctness and security first.",
    model: "inherit",            // or { id: "…" } — omit to inherit the supervisor's
    tools: ["read_file"],         // scope the child to this subset of the parent's tools
  },
}
```

Mapping to a `SubAgentSpec`: `prompt` → `instructions`; `model` accepts `"inherit"` (or a
`ModelSelection`); `tools` is a **whitelist** — the child is scoped to that subset of the parent's
tools (absent → the parent's full toolset). Subagents committed at `.theokit/agents/*.md` are picked
up too; inline definitions override file-based ones with the same name. Per-subagent `mcpServers` on a
definition are honored by the cloud runtime.

## Delegation lifecycle hooks

Wrap each delegation with `onDelegationStart` (before the child runs) and `onDelegationComplete`
(after it settles).

### `onDelegationStart` — reject, rewrite, or cap

```ts
onDelegationStart: (ctx) => {
  if (isDisallowed(ctx.input)) return { proceed: false, rejectionReason: "not permitted" }; // child never runs
  return { modifiedInput: sanitize(ctx.input), modifiedMaxSteps: 3 }; // rewrite the prompt + cap the child's iterations
}
```

- Return **`{ proceed: false, rejectionReason }`** — the child never runs; `rejectionReason` becomes
  the tool result.
- Return **`{ modifiedInput }`** — rewrite the delegated prompt.
- Return **`{ modifiedMaxSteps }`** (SE13) — cap the child's iteration count for this delegation.
- `ctx.iteration` (SE15) is the supervisor's 1-based turn — use it to reject after N delegations.
- A throwing hook **surfaces** (never silently swallowed).

### `onDelegationComplete` — feedback or observe

```ts
onDelegationComplete: (ctx) => {
  if (ctx.result) return { feedback: "verified" }; // appended to the successful result
  // ctx.error is set on failure — the original error is ALWAYS re-thrown after this hook
}
```

- On **success** `ctx.result` is set; return `{ feedback }` to append to it. A throw here propagates.
- On **failure** `ctx.error` is set and the original error is **always re-thrown** after the hook —
  a throw on the error path is suppressed so it can't mask the real failure. `ctx.iteration` matches
  the `onDelegationStart` that opened this delegation.

## Parent-context forwarding — `messageFilter` (SE12)

By default the child sees only the delegated prompt. Opt in to forward a **slice** of the supervisor's
transcript as a role-tagged preamble:

```ts
messageFilter: ({ messages, prompt }) => messages.filter((m) => m.role === "user").slice(-2)
```

`messages` is a read-only text projection of the supervisor transcript; return the subset to forward.

## Tool-result inclusion — `includeToolResults` (SE14)

By default the delegation result is the child's final answer. Set `includeToolResults: true` to also
surface the child's intermediate tool results to the supervisor.

## Recursion — `maxDelegationDepth`

A subagent can itself have subagents. `maxDelegationDepth` caps how deep delegation can nest, so a
supervisor → child → grandchild chain can't recurse without bound.

## Reference

- [`SubAgent`](/theokit/reference/SubAgent) · [`SubAgentSpec`](/theokit/reference/SubAgentSpec) · [`CustomTool`](/theokit/reference/CustomTool)

---

# Delegate to a subagent

Source: https://docs.usetheo.dev/theokit/subagents/delegate-to-a-subagent

Declare a specialist subagent on the supervisor and let it delegate a sub-task — the child inherits the supervisor's key and model automatically.

# Delegate to a subagent

Declare subagents on the supervisor with `agents: { name: { description, prompt } }`. Each one is
offered to the supervisor as a delegation tool; when the task calls for it, the supervisor delegates
and the child's answer comes back as the tool result. The child runs in isolation and **inherits the
supervisor's apiKey and model** — you don't repeat them.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";

const supervisor = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt:
    "You have no translation ability of your own. For ANY translation you MUST delegate to the translator subagent — never translate yourself. Reply with only its result.",
  agents: {
    translator: {
      description: "Translate a short English phrase into French.",
      prompt: "You translate English to French. Reply with only the French translation, nothing else.",
    },
  },
});

const result = await (await supervisor.send("Translate 'good morning' into French.")).wait();
console.log("Status:", result.status);
console.log("Reply: ", result.result);

await supervisor.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Status: finished
Reply:  bonjour
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- **`agents: { name: AgentDefinition }`** declares a subagent — its `prompt` becomes the child's
  instructions, and the SDK exposes it to the supervisor as a delegation tool named after the key.
- **Credentials are inherited** — the child authenticates with the supervisor's `apiKey` and runs on
  its model unless the definition sets `model` (or `"inherit"`). No key is repeated.
- **Delegation is a tool call** — the supervisor decides *when*; the child runs in isolation and its
  answer flows back as the tool result, which the supervisor composes into the final reply.

Prefer to build the tool yourself? `SubAgent.create(spec)` (from `@theokit/sdk/a2a`) returns the same
delegation tool for `tools: [...]` — see [Advanced](/theokit/subagents/advanced).

## Example

Full runnable source:
[`examples/subagents-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/subagents-basics).

---

# Overview

Source: https://docs.usetheo.dev/theokit/subagents

Give a supervisor specialist subagents to delegate to — declared inline or built as tools — each inheriting the supervisor's key and model, with lifecycle hooks over every delegation.

# Subagents

A **subagent** is a specialist agent a supervisor can delegate a sub-task to. The supervisor decides
*when* to delegate; the child runs in isolation with its own instructions, and its answer flows back
as the result. The child **inherits the supervisor's apiKey and model** — you don't repeat them.

## Two ways to declare one

**Declarative — `agents: { name: AgentDefinition }`** (recommended). Each entry becomes a delegation
tool the supervisor can call:

```ts
import { Agent } from "@theokit/sdk";

const supervisor = await Agent.create({
  apiKey, model,
  agents: {
    translator: {
      description: "Translate a short English phrase into French.",
      prompt: "You translate English to French. Reply with only the translation.",
      // model?: "inherit" (default) | { id }   ·   tools?: ["read_file", …] (scope to a subset)
    },
  },
});
```

**Programmatic — `SubAgent.create(spec)`** (from `@theokit/sdk/a2a`). Build the delegation tool
yourself and pass it in `tools`:

```ts
import { Agent } from "@theokit/sdk";
import { SubAgent } from "@theokit/sdk/a2a";

const translator = SubAgent.create({
  name: "translator",
  description: "Translate a short English phrase into French.",
  instructions: "You translate English to French. Reply with only the translation.",
});
const supervisor = await Agent.create({ apiKey, model, tools: [translator] });
```

Both produce the same thing — a delegation tool the model chooses by its `description`. Use the
declarative form for simple named specialists; reach for `SubAgent.create` when you need the lifecycle
hooks below.

## The spec (`SubAgent.create`)

```ts
SubAgent.create({
  name, description,       // what the supervisor sees (the tool contract)
  instructions,           // the child's system prompt
  model?,                 // override the child's model (else inherits the supervisor's)
  tools?,                 // the child's own tools
  maxDelegationDepth?,     // cap recursive delegation
  onDelegationStart?,      // hook: reject / rewrite / cap before the child runs
  onDelegationComplete?,   // hook: append feedback / observe after it settles
  messageFilter?,          // forward a slice of the supervisor's transcript as context
  includeToolResults?,     // include the child's tool results in the delegation result
});
```

The declarative `AgentDefinition` maps onto this: `prompt` → `instructions`, plus `description`,
`model` (or `"inherit"`), and `tools` (a whitelist scoping the child to that subset of the parent's
tools).

## When to use which

| You want | Reach for |
| --- | --- |
| A supervisor that *chooses* to hand a sub-task to a specialist | **Subagents** (this page). |
| A fixed pipeline of agents in order | [Squad](/theokit/squad). |
| One agent to *transfer control* to another (not delegate-and-return) | [Handoffs](/theokit/handoffs). |
| Explicit branching / parallelism / retries | [Workflows](/theokit/workflows). |

## Subagents vs Skills

A [Skill](/theokit/skills) *looks* similar (`name` / `description` / `instructions`) but is a
different thing — don't reach for one when you want the other:

| | **Subagent** | **[Skill](/theokit/skills)** |
| --- | --- | --- |
| What it is | A separate specialist **agent** exposed as a delegation tool | An instruction pack injected into **this** agent's prompt |
| Runs its own LLM turn? | **Yes** — the child runs in isolation (costs one more call) | **No** — no extra call; shares this agent's context |
| Mental model | "there **is an agent** that does X" | "the agent **knows how** to do X" |

They are **not nested** — a subagent has no `skills` field; its `prompt`/`instructions` already plays
the skill's role. Bake the specialist's knowledge into its `prompt`. A supervisor may carry its own
skills *and* delegate to subagents at the same time — the two live at different levels.

A subagent runs a real LLM turn, so it needs a working key — a fixture key (`theo_test_*`) that
skips the LLM won't delegate. The child inherits the supervisor's `apiKey`/model automatically.

## Next

- [Delegate to a subagent](/theokit/subagents/delegate-to-a-subagent) — a runnable example.
- [Advanced](/theokit/subagents/advanced) — the delegation hooks, context forwarding, and depth control.

## Reference

- [`SubAgent`](/theokit/reference/SubAgent) · [`SubAgentSpec`](/theokit/reference/SubAgentSpec) · [`AgentDefinition`](/theokit/reference/AgentDefinition)

---

# Advanced

Source: https://docs.usetheo.dev/theokit/subscriptions/advanced

The server handler and its ctx, the typed input/output contract, the client subscribe generator, transports, resume-on-reconnect, and typed errors.

# Advanced subscriptions

Verified against `@theokit/sdk/subscription` (G8, ADRs D423–D430).

## Server — `Subscription.create`

```ts
const sub = Subscription.create({
  name: "ticker",                 // optional; else derived from the file
  input: z.object({ symbol: z.string() }),   // Zod — the typed RPC contract (validated before the handler)
  output: z.object({ price: z.number() }),    // Zod — describes each frame (informational)
  async *handler(input, ctx) {
    // yield a plain frame, or tracked(id, frame) to advertise a resume token
    yield { price: 100 };
    yield tracked("1", { price: 101 });
  },
});
```

Input is validated with `input.safeParse` **before** the handler runs — a failure throws
`SubscriptionInputError`, never reaching your code.

## The handler context — `SubscriptionCtx`

```ts
interface SubscriptionCtx {
  lastEventId?: string;   // the resume token the client forwarded on reconnect — resume from here
  signal: AbortSignal;    // fires on client disconnect / consumer abort / server shutdown
  connectionId: string;   // stable per transport connection (one connection may host many subscriptions)
}
```

Honor `ctx.signal.aborted` in long loops, and use `ctx.lastEventId` to skip ahead to where the client
left off — that's what makes a reconnect seamless.

## Client — `subscribe`

```ts
import { subscribe } from "@theokit/sdk/subscription";   // also Theokit.subscribe

// subscribe(name, input, opts) — name + typed input first, then the transport options.
for await (const frame of subscribe(
  "ticker",                 // the subscription name (matches the server descriptor)
  { symbol: "AAPL" },        // TInput — validated against the server's input schema
  {
    baseUrl: "https://api.example.com",   // required
    transport: "auto",                     // "ws" | "sse" | "auto" (WS preferred, SSE fallback)
    signal,                                 // cancel the whole subscription
    headers: { Authorization: `Bearer ${token}` },
  },
)) {
  // frame is your TOutput
}
```

The client **reconnects with exponential backoff** and forwards the last tracked `id` as
`lastEventId`, so the server resumes from that point — you consume one continuous stream across
transient drops.

## Transports

| Transport | Behavior |
| --- | --- |
| `"ws"` | WebSocket — bidirectional, lowest latency. |
| `"sse"` | Server-Sent Events — one-way, proxy-friendly, W3C `Last-Event-ID` resume. |
| `"auto"` (default) | Prefer WS; fall back to SSE when WS isn't available. |

The canonical Node WebSocket server adapter ships with the SDK; Bun / Deno / CF-Workers adapters are
on the roadmap.

## Typed errors

- **`SubscriptionInputError`** — input failed the Zod schema (thrown before the handler).
- **`SubscriptionDisconnectError`** — the connection dropped and could not be resumed.
- **`SubscriptionError`** — the base class for the above (catch once, branch on `instanceof`).

## Reference

- [`Subscription`](/theokit/reference/Subscription) · [`subscribe`](/theokit/reference/subscribe) · [`SubscriptionCtx`](/theokit/reference/SubscriptionCtx) · [`SubscriptionTransport`](/theokit/reference/SubscriptionTransport) · [`TrackedEnvelope`](/theokit/reference/TrackedEnvelope) · [`SubscriptionError`](/theokit/reference/SubscriptionError)

---

# Overview

Source: https://docs.usetheo.dev/theokit/subscriptions

Typed server→client streaming subscriptions over WebSocket or SSE, with opaque resume tokens so a reconnecting client picks up where it left off.

# Subscriptions

A **subscription** is a typed, long-lived server→client stream (`@theokit/sdk/subscription`). The
server defines a handler that yields frames; the client subscribes and consumes them, reconnecting
automatically and **resuming** from the last event it saw.

```ts
// Server — define a typed subscription
import { Subscription, tracked } from "@theokit/sdk/subscription";
import { z } from "zod";

const ticker = Subscription.create({
  input: z.object({ symbol: z.string() }),
  output: z.object({ price: z.number() }),
  async *handler({ symbol }, ctx) {
    for (let i = 0; !ctx.signal.aborted; i++) {
      yield tracked(String(i), { price: 100 + i }); // resume-token envelope
    }
  },
});

// Client — subscribe and consume: subscribe(name, input, opts)
import { subscribe } from "@theokit/sdk/subscription";
for await (const frame of subscribe("ticker", { symbol: "AAPL" }, { baseUrl: "http://localhost:3000" })) {
  /* frame: { price } */
}
```

- **`Subscription.create({ input, output, handler })`** — server-side. `input`/`output` are Zod
  schemas (the typed RPC contract); the handler is an `AsyncGenerator` that yields output frames.
- **`tracked(id, payload)`** — wrap a frame with an opaque **resume token** so a reconnect can pick up
  from that id. Plain yields have no token.
- **`subscribe(name, input, { baseUrl, transport?, signal?, headers? })`** — client-side
  `AsyncGenerator`. It reconnects with backoff and forwards the last resume token as `lastEventId`.
- **Transport** — `"ws"` (WebSocket), `"sse"` (Server-Sent Events), or `"auto"` (WS preferred, SSE
  fallback).

## Next

- [Track resumable events](/theokit/subscriptions/track-resumable-events) — a runnable `tracked` example.
- [Advanced](/theokit/subscriptions/advanced) — the server handler + ctx, the client, transports, and errors.

## Reference

- [`Subscription`](/theokit/reference/Subscription) · [`subscribe`](/theokit/reference/subscribe) · [`tracked`](/theokit/reference/tracked) · [`SubscriptionCtx`](/theokit/reference/SubscriptionCtx)

---

# Track resumable events

Source: https://docs.usetheo.dev/theokit/subscriptions/track-resumable-events

Wrap a payload in a resume-token envelope with tracked, and recognize it with isTrackedEnvelope — deterministic, no server.

# Track resumable events

`tracked(id, payload)` wraps a subscription frame with an opaque **resume token** — a `[id, payload]`
envelope. A server handler yields these so a reconnecting client can resume from the last id it saw.
`isTrackedEnvelope` recognizes one. Both are pure functions — deterministic, no server, no LLM.

```ts title="run.ts"
import { tracked, isTrackedEnvelope } from "@theokit/sdk/subscription";

// A server handler yields `tracked(id, payload)` so each event carries a resume token.
const event = tracked("evt-42", { message: "hello" });
console.log("envelope:   ", JSON.stringify(event));       // [id, payload]
console.log("id:         ", event[0]);
console.log("payload:    ", JSON.stringify(event[1]));

console.log("isTracked(envelope):", isTrackedEnvelope(event));
console.log("isTracked(plain):   ", isTrackedEnvelope({ message: "hi" }));
```

## Output

Deterministic — pure envelope helpers:

```text
envelope:    ["evt-42",{"message":"hello"}]
id:          evt-42
payload:     {"message":"hello"}
isTracked(envelope): true
isTracked(plain):    false
```

## What it shows

- **`tracked(id, payload)`** returns a `TrackedEnvelope<T>` — a readonly `[id, payload]` tuple. Yield
  it from a subscription handler to advertise a resume token; yield a plain value for an untracked
  frame.
- **`isTrackedEnvelope(value)`** is the type guard the client uses to tell a tracked frame from a
  plain one, so it knows which `id` to forward as `lastEventId` on reconnect.
- The `id` semantics are yours — a monotonic counter, a ULID, a timestamp, an encrypted cursor. The
  SDK passes it through unchanged.

## Example

Full runnable source:
[`examples/subscription-tracked`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/subscription-tracked).

---

# Subscriptions

Source: https://docs.usetheo.dev/theokit/subscriptions

Typed server RPC over SSE / WebSocket.

# Subscriptions

Define server subscriptions clients consume over SSE or WebSocket, with opaque resume tokens for reconnection.

| Capability | What it adds |
| --- | --- |
| `Subscription.create` (`/subscription`) | `subscribe` + `tracked` + resume tokens |
| Transports | SSE and WebSocket adapters |

---

# Advanced

Source: https://docs.usetheo.dev/theokit/tasks/advanced

The task state machine and event stream, progress emission, idempotent cancellation, custom IDs and reserved prefixes, and durable configuration.

# Advanced tasks

Verified against `@theokit/sdk` (`src/task.ts`, `src/types/task.ts`).

## The state machine

```
queued → running → (finished | error | cancelled)
```

Every `TaskHandle` carries the state plus timings (`submittedAt`, `startedAt`, `finishedAt`,
`cancelledAt`, `erroredAt`), the `result` (on finish), and a typed `error` `{ code, message }` (on
failure).

## The event stream

`Task.subscribe(id)` yields six `TaskEvent` types (ring buffer cap 64 — buffered events replay first):

| Event | Meaning |
| --- | --- |
| `submitted` | The task entered the queue. |
| `started` | Work began (a concurrency slot was acquired). |
| `progress` | The work called `ctx.emit(payload)` — carries `{ taskId, at, payload }`. |
| `finished` | Work resolved — terminal. |
| `errored` | Work threw — terminal, carries the error. |
| `cancelled` | Cancelled before/while running — terminal. |

The iterable **closes automatically** on a terminal event. Calling `.return()` (or `break`) cleans up
the subscriber.

## Reporting progress — `ctx.emit`

The work function receives a `TaskWorkContext` — an `AbortSignal` and an `emit`:

```ts
await Task.submit("custom", async (ctx) => {
  for (let i = 0; i < 100; i++) {
    if (ctx.signal.aborted) return;      // honor cancellation
    ctx.emit({ percent: i });            // → a "progress" event
  }
  return "done";
});
```

## Idempotent cancellation — `Task.cancel`

```ts
const r = await Task.cancel(id, "user aborted");
// { cancelled: true,  alreadyTerminal: false } — queued/running → cancelled
// { cancelled: false, alreadyTerminal: true  } — already terminal
// { cancelled: false, alreadyTerminal: false } — unknown id
```

`Task.cancel` **never throws**. A task can also be pre-cancelled: pass an already-aborted `signal` to
`submit` and it short-circuits to `cancelled` without ever acquiring a slot or running the work.

## Custom IDs and reserved prefixes

`options.id` must match `^[a-z0-9][a-z0-9_-]*$` and **must not** start with the reserved prefixes
`wf-` / `b-` / `cron-` (those are for SDK adapter-generated IDs). Violations throw `InvalidTaskIdError`.
Omit `id` and a normalized `crypto.randomUUID()` is used.

## Configuration + durability

```ts
Task.configure({
  maxConcurrent: 4,                        // concurrency cap across all tasks
  retentionMs: 3_600_000,                  // how long terminal handles stay queryable
  store: { backend: "json", dir: "./.tasks" }, // durable — survives restarts
});
```

- **`store`** — `{ backend: "memory" }` (default, process-local) or `{ backend: "json", dir }`
  (durable). The JSON store also powers cross-process cancel via `cancelRequested`.
- **`maxConcurrent`** bounds how many tasks run at once; the rest stay `queued`.
- **`retentionMs`** controls when finished handles are evicted from queries.

The five `TaskKind`s (`run` · `batch` · `workflow` · `cron` · `custom`) let you filter
`Task.list({ kind })` to attribute background work — the SDK routes its own runs, batches, workflows,
and cron fires through the same registry.

## Reference

- [`Task`](/theokit/reference/Task) · [`TaskHandle`](/theokit/reference/TaskHandle) · [`TaskEvent`](/theokit/reference/TaskEvent) · [`TaskCancelResult`](/theokit/reference/TaskCancelResult) · [`TaskConfigureOptions`](/theokit/reference/TaskConfigureOptions)

---

# Overview

Source: https://docs.usetheo.dev/theokit/tasks

Run work in the background and observe it — a task registry with submit/list/get/cancel/subscribe, batch fan-out, and a durable JSON store.

# Tasks

For work that runs alongside — or instead of — a single interactive turn. The **`Task`** registry
tracks any background work through a clean state machine and an event stream.

```ts
import { Task } from "@theokit/sdk";

const handle = await Task.submit("custom", async () => doWork(), { id: "my-task" });
// handle.state: "queued" → "running" → "finished" | "error" | "cancelled"

for await (const ev of Task.subscribe(handle.id)) { /* observe */ }
```

## The registry — `Task`

- **`Task.submit(kind, work, options)`** — enqueue work; returns a `TaskHandle` in `state: "queued"`.
- **`Task.list(filter)` / `Task.get(id)`** — query handles (state, result, timings, meta).
- **`Task.subscribe(id)`** — an `AsyncIterable<TaskEvent>` that replays buffered events then streams
  live ones until the task settles.
- **`Task.cancel(id, reason?)`** — idempotent cancel; never throws.
- **`Task.configure({ store, maxConcurrent, retentionMs })`** — set the store, concurrency cap, and
  retention window.

The five `TaskKind`s — `run`, `batch`, `workflow`, `cron`, `custom` — let you attribute every
background task to what spawned it. The SDK's own long-running work (agent runs, batches, workflows,
cron fires) flows through the same registry, so it's all observable in one place.

## Batch fan-out — `Agent.batch`

- **`Agent.batch(prompts, options)`** — run many prompts with **bounded concurrency**. The fan-out
  primitive for evaluating a dataset or processing a queue (see [Agents › Advanced](/theokit/agents/advanced)).

## Durability

- **Task store** (`@theokit/sdk/task-store`) — a JSON-backed store so a task's status **survives a
  process restart** and is observable across processes.

## Next

- [Run work in the background](/theokit/tasks/run-work-in-the-background) — a runnable `Task.submit` example.
- [Advanced](/theokit/tasks/advanced) — the state machine, event types, cancellation, and configuration.

## Reference

- [`Task`](/theokit/reference/Task) · [`TaskHandle`](/theokit/reference/TaskHandle) · [`TaskEvent`](/theokit/reference/TaskEvent)

---

# Run work in the background

Source: https://docs.usetheo.dev/theokit/tasks/run-work-in-the-background

Submit background work with Task.submit and watch it settle through the event stream — deterministic, no LLM.

# Run work in the background

`Task.submit(kind, work, options)` enqueues a function and returns a handle immediately. The task
moves through `queued → running → finished` on its own; `Task.subscribe` streams every transition.
The work here is a plain function, so the whole thing is deterministic — no LLM.

```ts title="run.ts"
import { Task } from "@theokit/sdk";

const handle = await Task.submit(
  "custom",
  async () => {
    await new Promise((r) => setTimeout(r, 10)); // simulate background work
    return 21 * 2;
  },
  { id: "compute-answer" },
);

console.log("submitted:", handle.state);

for await (const ev of Task.subscribe(handle.id)) {
  console.log("event:    ", ev.type);
  if (ev.type === "finished" || ev.type === "errored" || ev.type === "cancelled") break;
}

const done = await Task.get(handle.id);
console.log("final:    ", done?.state, "result:", done?.result);
```

## Output

Deterministic — the task's own state machine drives the events:

```text
submitted: queued
event:     submitted
event:     started
event:     finished
final:     finished result: 42
```

## What it shows

- **`Task.submit`** returns a `TaskHandle` in `state: "queued"` right away — the work runs in the
  background.
- **`Task.subscribe(id)`** replays the buffered events (`submitted`, `started`) then streams live ones
  until a terminal event (`finished` / `errored` / `cancelled`), then closes.
- **`Task.get(id)`** reads the settled handle — `state: "finished"` with the work's return value in
  `result`.

## Example

Full runnable source:
[`examples/tasks-background`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/tasks-background).

---

# Advanced

Source: https://docs.usetheo.dev/theokit/tools/advanced

Output schemas, model-facing output, argument sanitization, typed tool errors, cancellation, and per-send tool subsets.

# Advanced tools

Beyond `name` / `description` / `inputSchema` / `handler`, `Tool.create` exposes several controls
for production tools. Each is opt-in — omit it and behavior is unchanged.

## Validate the tool's output — `outputSchema`

Pass an `outputSchema` and the handler returns the **structured** value inferred from it; the SDK
validates the return before it reaches the model. A validation failure becomes a `tool_result`
marked as an error (not a crash).

```ts
Tool.create({
  name: "get_weather",
  description: "Look up the weather.",
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ tempC: z.number(), sky: z.string() }),
  handler: ({ city }) => ({ tempC: 18, sky: "cloudy" }), // typed by outputSchema
});
```

## Split model-facing vs app-facing output — `toModelOutput`

The handler keeps returning the **full** result (your app uses it); `toModelOutput` shapes only what
the *model* sees in the `tool_result`. Returns a string or SE7 content blocks (text + image), so you
can hand the model a compact summary while keeping the rich object in your own scope.

```ts
Tool.create({
  /* … */
  outputSchema: z.object({ rows: z.array(z.unknown()), total: z.number() }),
  handler: () => ({ rows: bigArray, total: 1234 }),
  toModelOutput: (out) => `Found ${out.total} rows.`, // the model sees just this
});
```

Observability (`onToolEnd`) sees the model-facing result, not the raw handler output.

## Clean shaky model args — `sanitize`

Models emit imperfect JSON. `sanitize` cleans raw args **before** `inputSchema.parse` using
`@theokit/sdk/sanitize`:

- `sanitize: true` — trims whitespace (a leaked `"\npackage.json\n"` validates as `"package.json"`).
- `sanitize: { coerce: true }` — additionally coerces toward the schema (a `z.number()` field accepts `"5"`).

Sanitize is hygiene, not a validity bypass — a genuinely invalid arg still becomes a
`tool_result(isError)`.

## Fail cleanly — `ToolError`

Throw a `ToolError` from a handler to send a clean message (or structured error content, e.g. an
error screenshot) back to the model as `tool_result(isError: true)` — the run continues, the model
can react.

```ts
import { ToolError } from "@theokit/sdk";

handler: async ({ city }) => {
  const res = await fetch(url);
  if (!res.ok) throw new ToolError(`weather lookup failed for ${city} (${res.status})`);
  return await res.text();
}
```

## Cancellation — the `ToolContext`

The handler's optional 2nd argument carries a `ToolContext` (`{ signal, context }`). A cooperative
handler checks `signal` to stop early when the run is cancelled; single-argument handlers are
unaffected.

```ts
handler: async ({ url }, ctx) => {
  const res = await fetch(url, { signal: ctx?.signal });
  return await res.text();
}
```

`context` carries the per-run user context (shared config like `projectRoot`) passed once on
`send()`, read by every tool.

## Bound and scope tool calls at send time

- **`activeTools`** — restrict a single `send()` to a subset of the agent's tools by name (a
  runtime allowlist, without rebuilding the agent).
- **`perToolTimeoutMs`** — bound each individual tool call; a hung tool yields a typed timeout
  result (`exitCode 124`) instead of wedging the run, while other tools continue.

```ts
await agent.send("…", { activeTools: ["get_weather"], perToolTimeoutMs: 5000 });
```

## Tools from other primitives — the "X as tools" trio

A tool doesn't have to be a hand-written `Tool.create`. Three factories turn other primitives into
tools the model can call:

| Factory | Turns … into a tool |
| --- | --- |
| `SubAgent.create(spec)` | Another agent — the model delegates a sub-task. See [Subagents](/theokit/subagents). |
| `workflowAsTool(workflow, { name, description, inputSchema })` | A committed [`Workflow`](/theokit/workflows) — the model invokes a whole pipeline (from `@theokit/sdk/workflow`). |
| `SkillReadTool.create(skills)` | A lazy skill-body reader — the model loads a skill's instructions on demand. See [Skills](/theokit/skills). |

None are auto-injected — you add them to `tools` explicitly, so bring-your-own-tools stays intact.

## Related

- **Built-in tools** — `@theokit/sdk-tools` ships file-system, git, shell, and search tools for coding agents.
- **MCP** — connect external [MCP](/theokit/mcp) tool servers.
- **Sanitize** — `@theokit/sdk/sanitize` (`sanitizeToolInput`) is the primitive behind the `sanitize` option, usable standalone.

## Reference

- [`Tool`](/theokit/reference/Tool) · [`DefineToolSpec`](/theokit/reference/DefineToolSpec) · [`ToolError`](/theokit/reference/ToolError) · [`CustomTool`](/theokit/reference/CustomTool)

---

# Give an agent a tool

Source: https://docs.usetheo.dev/theokit/tools/give-an-agent-a-tool

Define a typed tool with Tool.create and let the model call it.

# Give an agent a tool

Define a typed tool, pass it to the agent, and ask a question that needs it — the model
calls the tool, gets the result, and answers.

```ts title="run.ts"
import { Agent, Tool } from "@theokit/sdk";
import { z } from "zod";

const getWeather = Tool.create({
  name: "get_weather",
  description: "Look up the current weather in a given city.",
  inputSchema: z.object({
    city: z.string().describe("City name, e.g. 'Tokyo' or 'Brasília'."),
  }),
  async handler({ city }) {
    // A real tool would call a weather API. Mocked here so the example is self-contained.
    const mock: Record<string, string> = {
      Tokyo: "18°C, cloudy",
      Brasília: "27°C, sunny",
      London: "12°C, raining",
    };
    return mock[city] ?? `No weather data for ${city}.`;
  },
});

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "Use the get_weather tool when the user asks about weather. Answer in one sentence.",
  tools: [getWeather],
});

const result = await (await agent.send("What's the weather in Tokyo?")).wait();
console.log("Status:", result.status);
console.log("Reply: ", result.result);

await agent.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Status: finished
Reply:  Tokyo's weather is currently 18 °C and cloudy.
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- `Tool.create({ name, description, inputSchema, handler })` — the canonical tool factory.
- The Zod `inputSchema` is validated **before** `handler` runs, so `city` is typed.
- `tools: [getWeather]` on `Agent.create` — the agent decides when to call it; the tool
  loop (call → run → feed back → answer) is handled for you.

## Example

Full runnable source:
[`examples/tool-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/tool-basics).

---

# Overview

Source: https://docs.usetheo.dev/theokit/tools

Give an agent typed functions the model can call — defined once, validated automatically.

# Tools

A **tool** is a typed function the model can call. You define it once with `Tool.create`;
the agent decides *when* to call it based on the description and the user's message, and
the SDK validates the arguments before your code runs.

```ts
import { Tool } from "@theokit/sdk";
import { z } from "zod";

const getWeather = Tool.create({
  name: "get_weather",
  description: "Look up the current weather in a city.",
  inputSchema: z.object({ city: z.string() }),
  async handler({ city }) {
    return `18°C, cloudy in ${city}`;
  },
});

await Agent.create({ apiKey, model, tools: [getWeather] });
```

## Anatomy of a tool

| Field | What it is |
| --- | --- |
| `name` | the tool name the model sees |
| `description` | what it does — the model uses this to decide when to call it |
| `inputSchema` | a Zod `z.object(...)`; converted to JSON Schema and **validated before `handler` runs** |
| `handler` | your function — receives the parsed, typed input (2nd arg `ctx` carries the run's `AbortSignal`) |
| `outputSchema?` | optional Zod schema for a structured return; validated and serialized into the tool result |
| `toModelOutput?` | optional — shape what the *model* sees, keeping the full result for your app |

The handler property is `handler`, not `execute`. `execute` type-errors.

## The tool loop

`agent.send()` runs the loop for you: the model requests a tool, the SDK validates the
input and runs your `handler`, feeds the result back, and the model continues until it
produces a final answer. You never orchestrate the round-trips.

## Errors

Throw `ToolError` (or any error) from a handler — it becomes a `tool_result` marked as an
error the model can react to, rather than crashing the run.

## Related

- **Sanitize model args** — `@theokit/sdk/sanitize` (`sanitizeToolInput`) trims / coerces /
  json-repairs shaky model arguments before validation.
- **Built-in tools** — `@theokit/sdk-tools` ships file-system, git, shell, and search tools
  for coding agents.
- **MCP** — connect an agent to external [MCP](/theokit/mcp) tool servers.

## Next

- [Give an agent a tool](/theokit/tools/give-an-agent-a-tool) — a runnable example.

## Reference

- [`Tool.create`](/theokit/reference/DefineToolSpec) · [`CustomTool`](/theokit/reference/CustomTool)

---

# AgentStreaming

Source: https://docs.usetheo.dev/theokit/tui/agent-streaming

Live agent-turn indicator — an animated sparkle, thought line, and optional interrupt hint with token count.

`AgentStreaming` renders a single-line live indicator: an animated sparkle (`✳`), the
current thought, and an optional interrupt hint carrying the elapsed time and a live token
count:

```
✳ Searching (27s · ↓ 47k tokens · esc to interrupt)
```

The component is dumb — it holds no timer; ticking `elapsedSeconds` and updating `tokens` is
the caller's concern. It is the **indeterminate** counterpart to
[`ProgressActivity`](/theokit/tui/progress-activity) (the *determinate* task with a
percentage): use `AgentStreaming` when there is no percentage to show.

## Example

```tsx
import { AgentStreaming } from "@theokit/tui";

<AgentStreaming
  thought="Searching"
  elapsedSeconds={27}
  tokens={47_000}
  tokenDirection="down"
  showCancelHint
/>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `thought` | `string` | — | Primary line (italic, truncate-end). Empty or absent falls back to `Thinking…`. Newlines are sanitized to spaces (single-line contract). |
| `elapsedSeconds` | `number` | — | Elapsed seconds shown inside the interrupt hint. Always validated (finite, `>= 0`), even when the hint is hidden. |
| `tokens` | `number` | — | Live token count shown as `· {N} tokens` in the hint. Finite, `>= 0`. Rendered only with `showCancelHint`, but validated regardless. |
| `tokenDirection` | `"up" \| "down"` | — | Prefixes the token count with `↑` (context growing) or `↓` (shrinking): `↓ 47k tokens`. Absent → the bare count. |
| `showCancelHint` | `boolean` | `false` | Renders the dim `({elapsed} · {N} tokens · esc to interrupt)` suffix (each leading segment present only when its prop is supplied). |
| `phrases` | `readonly string[]` | — | Opt-in: witty status phrases cycled round-robin (~2s) while motion is enabled. Absent → byte-identical to the `thought \|\| "Thinking…"` behavior. |
| `shimmer` | `boolean` | `false` | Opt-in: pulse the primary line (dim ↔ normal, ~600ms) while motion is enabled. |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props. |

## Notes

- The leading glyph is a **sparkle** that animates through `✳ ✷ ✶ ✵` while motion is enabled — not a braille spinner. Under reduced-motion, non-TTY, or monochrome terminals it renders the static `✳` and schedules no timers.
- The indicator holds no internal timer. `elapsedSeconds` is formatted for display via the human elapsed format (`0s`…`59s`, `1m 5s`, `1h 2m 3s` — no days unit); fractional input is floored first. `tokens` is compacted via the same format as the metrics components (`47k`, `24.6k`).
- `elapsedSeconds` and `tokens` are validated fail-fast regardless of `showCancelHint`: prop validity does not depend on another prop. Out-of-range values throw a `TypeError`.
- `phrases` and `shimmer` are inert under reduced-motion, non-TTY, or monochrome terminals. When motion is disabled, `phrases` renders its first entry statically and `shimmer` does not pulse — no timers are scheduled.
- The hint reads `({elapsed} · {N} tokens · esc to interrupt)`, dropping the elapsed or tokens segment when its prop is absent (down to a bare `(esc to interrupt)`).

---

# AgentTimeline

Source: https://docs.usetheo.dev/theokit/tui/agent-timeline

Ordered agent-turn timeline mixing message, thinking, and tool events.

`AgentTimeline` renders a caller-ordered array of `AgentEvent`s as a windowed
timeline: recent events stay in the live tail while older ones graduate into Ink
`<Static>` (terminal scrollback) and are frozen. It is the sibling of `ChatThread` —
same windowing, identity-memoized rows, and its own kind dispatch.

## Example

```tsx
import { AgentTimeline } from '@theokit/tui';
import type { AgentEvent } from '@theokit/tui';

const events: AgentEvent[] = [
  { id: '1', kind: 'message', role: 'user', text: 'List the files.' },
  { id: '2', kind: 'thinking', text: 'The user wants a directory listing.' },
  {
    id: '3',
    kind: 'tool',
    name: 'ls',
    status: 'success',
    summary: 'ls -la',
    output: 'README.md\npackage.json',
  },
  { id: '4', kind: 'message', role: 'assistant', text: 'Found 2 files.' },
];

<AgentTimeline events={events} />;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `events` | `AgentEvent[]` | — (required) | Caller-ordered events. Unique ids (duplicates throw); graduated events are immutable — replace the tail event with a new object to stream. Always pass a new array on update. |
| `windowSize` | `number` | `8` | Events beyond `windowSize + windowOverscan` graduate into `<Static>` and freeze. Mount-time knob. |
| `windowOverscan` | `number` | `4` | Overscan added to the window before graduation. Mount-time knob. |
| `header` | `ReactElement` | — | Optional header folded as the first item of the timeline's own `<Static>`, pinned above graduated history. Mount-time frozen; the id `"__theokit_tui_header__"` is reserved. Size it explicitly. |

## AgentEvent kinds

An `AgentEvent` is a discriminated union on the `kind` field (`AGENT_EVENT_KINDS = ["message", "thinking", "tool"]`). Note the discriminant is `kind`, not `type`.

| Kind | Fields | Renders as |
|---|---|---|
| `message` | `id`, `kind: "message"`, `role` (`ChatRole`: `user` \| `assistant` \| `system`), `text` | A `ChatMessage` row with the role prefix. |
| `thinking` | `id`, `kind: "thinking"`, `text` | A dim, italic reasoning row with a `•` marker. |
| `tool` | `id`, `kind: "tool"`, `name`, `status` (`ToolCallStatus`: `pending` \| `running` \| `success` \| `failed`), `summary?`, `output?`, `shell?` (`ShellEnvelope`), `maxLines?` | A `ToolCallCard` with an optional `ToolResult` body. |

`isAgentEventKind(value)` is exported as a runtime type guard for the kind union.

## Notes

- Events are validated at the boundary before any hook runs (Ink swallows render-time throws). Invalid `role`, invalid `status`, providing both `output` and `shell`, a non-integer or `< 1` `maxLines`, a duplicate id, an unknown `kind`, or an id colliding with the reserved header sentinel all throw a `TypeError`.
- On tool events, `output` and `shell` are mutually exclusive. `output` is passed as `ToolResult` children so it inherits normalization (CRLF strip, trailing-blank pop). Empty output collapses to a bare row.
- Text passes through unsanitized — ANSI is the caller's responsibility. Extra/unknown properties on events are tolerated (adapters may enrich).
- Only one `AgentTimeline` (or `ChatThread`) per screen once history graduates: two mounted `<Static>` consumers cannot interleave their frozen output.
- Increasing `windowSize` / `windowOverscan` after events have graduated pulls scrollback rows back into the live tail, visibly duplicating history — treat them as mount-time only.

---

# AI SDK adapter

Source: https://docs.usetheo.dev/theokit/tui/ai-sdk

Adapt the ai SDK's UIMessage[] into ChatThread / AgentTimeline shapes — @theokit/tui/ai-sdk

`@theokit/tui/ai-sdk` is a small, pure-function subpath that adapts the [`ai`
SDK](https://www.npmjs.com/package/ai)'s `UIMessage[]` — the shape TheoKit's
unified agent client produces — into the two shapes this package renders:
`ChatThreadMessage[]` for `<ChatThread>` and `AgentEvent[]` for `<AgentTimeline>`.

No React, no Ink, no state — a terminal app folds the client's message snapshot
through these functions and renders it with the same primitives the web and
desktop surfaces use.

`ai` is a **type-only** import (erased at build) and an **optional** peer. A
consumer of the unified client already has it; a consumer that only renders raw
`AgentEvent[]` never installs it. Import the adapter from the `@theokit/tui/ai-sdk`
subpath — it is not re-exported from the main barrel.

## Import

```ts
import {
  uiMessagesToChatThread,
  uiMessagesToAgentEvents,
} from "@theokit/tui/ai-sdk";
```

## Example — chat surface

Project the client's `UIMessage[]` onto `<ChatThread>`: one bubble per message
that has text.

```tsx
import { render } from "ink";
import { ChatThread, TheoTUIProvider } from "@theokit/tui";
import { uiMessagesToChatThread } from "@theokit/tui/ai-sdk";
import type { UIMessage } from "ai";

function Chat({ messages }: { messages: UIMessage[] }) {
  return (
    <TheoTUIProvider>
      <ChatThread messages={uiMessagesToChatThread(messages)} />
    </TheoTUIProvider>
  );
}
```

## Example — agent timeline

Flatten the same `UIMessage[]` into an ordered `AgentEvent[]` — text, reasoning,
and tool invocations become `message` / `thinking` / `tool` events — for
`<AgentTimeline>`, which renders the full reasoning + tool lifecycle of a turn.

```tsx
import { AgentTimeline, TheoTUIProvider } from "@theokit/tui";
import { uiMessagesToAgentEvents } from "@theokit/tui/ai-sdk";

function Timeline({ messages }) {
  return (
    <TheoTUIProvider>
      <AgentTimeline events={uiMessagesToAgentEvents(messages)} />
    </TheoTUIProvider>
  );
}
```

## API

### `uiMessagesToChatThread(messages)`

```ts
function uiMessagesToChatThread(
  messages: readonly UIMessage[],
): ChatThreadMessage[];
```

One `ChatThreadMessage` per message that has text; its `content` is the
concatenation of the message's `text` parts, and `role` passes through 1:1.
Tool-only or reasoning-only turns produce **no** chat bubble — those belong to the
timeline. The message `id` passes through as the row key.

### `uiMessagesToAgentEvents(messages)`

```ts
function uiMessagesToAgentEvents(
  messages: readonly UIMessage[],
): AgentEvent[];
```

Flattens the messages into an ordered event list:

| `UIMessage` part | → `AgentEvent` |
|---|---|
| `text` (non-empty) | `message` event (role passes through) |
| `reasoning` (non-empty) | `thinking` event |
| `tool-<name>` / `dynamic-tool` | `tool` event (status mapped, see below) |
| `file`, `source`, `step-start`, `data`, custom | *skipped (not renderable)* |

Every id is unique — text and reasoning events are message-part-scoped
(`{id}::m{n}` / `{id}::r{n}`); tool events use the `toolCallId` (falling back to a
message-scoped id when a part omits it) — so the output always satisfies
`<AgentTimeline>`'s duplicate-id contract.

### Tool status mapping

The ai SDK tool-part `state` maps to this package's `ToolCallStatus`:

| ai SDK `state` | `ToolCallStatus` |
|---|---|
| `input-streaming` | `pending` |
| `input-available` | `running` |
| `approval-requested` | `pending` |
| `approval-responded` | `pending` |
| `output-available` | `success` |
| `output-error` | `failed` |

A failed tool's `errorText` becomes the event's output; otherwise the output is
the stringified tool result (`JSON.stringify(..., 2)` for non-string values).

## Notes

- **Pure and stateless.** Both functions are synchronous projections — call them
  on every render from the client's current message snapshot. There is no
  subscription and no memoization inside the adapter; wrap the call in `useMemo`
  keyed on `messages` if you want to skip re-projection.
- **Two surfaces, one source.** Use `uiMessagesToChatThread` for a chat bubble
  view and `uiMessagesToAgentEvents` for the reasoning-and-tools timeline — both
  fold the same `UIMessage[]`, so you can offer either view of the same turn.
- **Optional peer.** Install `ai` only when you use this subpath. The types are
  erased at build; nothing in the runtime bundle imports `ai`.

---

# AppStatusBar

Source: https://docs.usetheo.dev/theokit/tui/app-status-bar

Persistent one-line agent status bar — model, cwd, tokens, and turn state.

A single-line status bar with four fixed slots: model, cwd, tokens, and state. Absent slots (undefined or empty string) are omitted together with their separators, so there is never a dangling `·`. The cwd slot shrinks first under width pressure (truncate-start, keeping the informative path tail); every other slot keeps its width.

## Example

```tsx
import { AppStatusBar, useTurnElapsed } from "@theokit/tui";

<AppStatusBar
  model="theokit-demo"
  cwd={process.cwd()}
  tokens={{ used: 12_300, limit: 128_000 }}
  state={streaming ? "streaming" : "idle"}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `model` | `string` | `undefined` | Model identifier, rendered in the accent color. |
| `cwd` | `string` | `undefined` | Working directory. Home prefix is tildeified (`~/...`); rendered with `wrap="truncate-start"` so the tail stays visible. This is the only slot that shrinks. |
| `tokens` | `AppStatusBarTokens` | `undefined` | Token usage rendered compacted as `used/limit` (via `formatTokens`), dim. |
| `state` | `string` | `undefined` | Free-text turn state (e.g. `idle`, `streaming`, `error`). Never truncated. |

`AppStatusBarTokens`:

| Field | Type | Description |
|---|---|---|
| `used` | `number` | Tokens consumed so far. Finite, `>= 0`. |
| `limit` | `number` | Context-window limit. Finite, `> 0`. |

## Notes

- Empty strings are treated as absent — a `""` slot emits no content and no separator.
- If every slot is absent, the component renders `null`.
- Invalid `tokens` (non-finite, `used < 0`, or `limit <= 0`) throw a `TypeError` at the component boundary before any hook runs. Under a live Ink render the framework surfaces this via `waitUntilExit` rather than the render call.
- Separators (` · `) are dim and never shrink; the tokens slot uses `wrap="truncate-end"` so any clipping stays visible rather than reading as a complete-but-wrong limit.
- Colors come from theme tokens (accent + dim); monochrome themes drop color but keep the dim separator.

## useTurnElapsed hook

`useTurnElapsed(active: boolean): number` is the lib-shipped ticking source that drives elapsed time — for example `AgentStreaming.elapsedSeconds`, which holds no timer of its own.

```tsx
const elapsed = useTurnElapsed(streaming);
<AgentStreaming elapsedSeconds={elapsed} … />
```

- Returns seconds elapsed since `active` became `true`; `0` while inactive.
- Re-activation resets the count to `0` — a new turn is a new clock.
- The interval is cleared on deactivation and on unmount.

---

# ApprovalPrompt

Source: https://docs.usetheo.dev/theokit/tui/approval-prompt

A titled pending-action card composing an app-supplied preview and a once/always/reject choice bar.

A titled pending-action card. The preview is a `children` slot the app composes — a `<DiffViewer/>` for an edit, a `<Text>$ cmd</Text>` for a command, or any body; the prompt never touches diff/preview props. Choices default to the canonical once/always/reject triad (override-able), Enter commits, and Esc yields `"reject"` (the safe default). The decision leaves via one `onDecision` callback.

## Example

```tsx
import { ApprovalPrompt, DiffViewer } from "@theokit/tui";

<ApprovalPrompt
  title="Apply this edit?"
  onDecision={(d) => record(`approval: ${d}`)}
>
  <DiffViewer patch={PATCH} />
</ApprovalPrompt>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` | — (required) | The heading (e.g. `"Run command?"` / `"Apply edit?"`). |
| `children` | `ReactNode` | — (required) | The preview, composed by the app (DiffViewer / command line / any body). |
| `choices` | `readonly ApprovalChoice[]` | `DEFAULT_APPROVAL_CHOICES` | The choice bar. Defaults to `once` / `always` / `reject`. |
| `onDecision` | `(decision: ApprovalDecision) => void` | — (required) | Called with the chosen value; Esc yields `"reject"`. `ApprovalDecision` is a `string`. |
| `autoFocus` | `boolean` | `true` | Take focus on mount. Set `false` for a non-interactive render so the choice bar does not grab stdin. |

## Notes

- Callback-only: the component holds no app state. The app owns the decision sequencing.
- The preview is passed via `children`, never via prop-forwarding — the prompt does not reach into diff/preview props.
- Esc maps to the `"reject"` decision, the safe default. Enter commits the highlighted choice.
- The default choices come from the exported `DEFAULT_APPROVAL_CHOICES` (`[{once, Allow once}, {always, Allow always}, {reject, Reject}]`); pass `choices` to override.
- Requires a raw-mode TTY for interactive input (mount under `InputContext` + `FocusProvider`).

---

# Banner

Source: https://docs.usetheo.dev/theokit/tui/banner

Startup header — a big ASCII-art logo or the bold product name, with an optional framed status panel.

A pure, synchronous startup header: it renders a provided `art` string verbatim (accent-themed) or degrades to the bold product `name` when `art` is absent. In the `banner` layout it stacks the header above a framed status panel of `label value` rows (narrow-safe; no side-by-side). Figlet generation lives in the async `renderFigletArt` helper, never in render.

## Example

```tsx
import { Banner, TheoTUIProvider, VERSION, renderFigletArt } from "@theokit/tui";

const THEO_ART = [
  "  _____ _",
  " |_   _| |__   ___  ___",
  "   | | | '_ \\ / _ \\/ _ \\",
  "   | | | | | |  __/ (_) |",
  "   |_| |_| |_|\\___|\\___/",
].join("\n");

// Generate via the optional figlet peer; fall back to a ready art string.
const art = (await renderFigletArt("Theo", "Standard")) ?? THEO_ART;

<TheoTUIProvider>
  <Banner
    name="Theo TUI"
    version={VERSION}
    art={art}
    layout="banner"
    status={[
      { label: "model", value: "theo-demo-1" },
      { label: "cwd", value: "~/projects/app" },
    ]}
  />
</TheoTUIProvider>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — | Product name — the degrade target when `art` is absent (single line). |
| `version` | `string` | `undefined` | Rendered dim as ` v{version}` after the name on the degrade path. |
| `art` | `string` | `undefined` | A multi-line ASCII-art string, rendered verbatim (accent-themed). Absent falls back to the bold `name`. |
| `status` | `readonly BannerStatusRow[]` | `undefined` | Rows for the framed status panel (only shown in the `banner` layout). |
| `layout` | `"minimal" \| "banner"` | `"minimal"` | `minimal` renders the header only; `banner` stacks the header above the framed status panel. |

`BannerStatusRow` is `{ label: string; value: string }`.

## Notes

- The status panel renders only when `layout === "banner"` and `status` is non-empty; otherwise `Banner` returns the header alone.
- The ASCII-art block uses `flexShrink={0}` so layout never compresses it.
- Under a monochrome theme the accent is dropped and the status panel border degrades from `round` to `single`.

## Helper: renderFigletArt

`figlet` is an optional peer dependency (declared in `peerDependenciesMeta`), never a runtime dependency. The component never imports it; the app calls the helper and passes the result as `<Banner art={...} />`.

```ts
import { bannerArtWidth, renderFigletArt } from "@theokit/tui";

const art = await renderFigletArt("Theo", "Standard"); // string | null
const width = art !== null ? bannerArtWidth(art) : 0;
```

### `renderFigletArt(text, font?, loader?): Promise<string | null>`

| Param | Type | Default | Description |
|---|---|---|---|
| `text` | `string` | — | Text to convert to ASCII art. |
| `font` | `string` | `undefined` | Figlet font name; omitted uses figlet's default. |
| `loader` | `FigletLoader` | dynamic `import("figlet")` | Injectable module loader (for tests). |

Returns the art string, or `null` when figlet is not installed (import fails) or the font is unknown (`textSync` throws). It never throws, so a missing peer or bad font degrades cleanly to the caller's `name` path. Internally it renders with `width: 80` and `whitespaceBreak: true`.

### `bannerArtWidth(art): number`

Returns the display width of ASCII art — the widest line, measured with `string-width` (East-Asian-width and grapheme aware). Empty art returns `0`.

---

# ChatComposer

Source: https://docs.usetheo.dev/theokit/tui/chat-composer

Multi-line chat input with slash-command, file-mention, shell, and help affordances

`ChatComposer` is a multi-line chat input built on a grapheme-aware text buffer.
Enter submits the trimmed buffer (whitespace-only is a no-op) and clears it. It
layers in optional affordances — `/` slash-command menu, `@` file mentions, `!`
shell mode, and `?` keyboard-help toggle — each enabled only when its corresponding
prop is supplied.

## Example

```tsx
import { render } from "ink";
import { ChatComposer, TheoTUIProvider } from "@theokit/tui";

render(
  <TheoTUIProvider>
    <ChatComposer
      placeholder="Type a message (Enter sends · / commands · @ files · ! shell · ? help)"
      commands={[
        { name: "help", description: "show available commands" },
        { name: "clear", description: "clear the thread" },
      ]}
      hint="? toggles shortcuts · @ browses files · ! runs a shell command"
      bordered
      onSubmit={(text) => console.log(text)}
      onShellCommand={(cmd) => console.log("run:", cmd)}
      onHelpToggle={() => console.log("toggle help")}
    />
  </TheoTUIProvider>,
);
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `onSubmit` | `(text: string) => void` | — | Called with the trimmed buffer text on Enter. Exceptions propagate — the composer never swallows caller errors. |
| `placeholder` | `string` | `""` | Dimmed hint shown while the buffer is empty. |
| `multiLine` | `boolean` | `true` | Multi-line mode. Ctrl+J always inserts a newline; Shift+Enter also does, but only on terminals that encode shift (kitty protocol). |
| `autoFocus` | `boolean` | `true` | Whether the composer grabs focus on mount. |
| `commands` | `readonly SlashCommand[]` | `[]` | Slash-command menu entries (`{ name, description }`). Typing `/` at the start of line 1 opens a prefix-filtered menu. |
| `hint` | `string` | — | Dim affordance line rendered under the composer. |
| `bordered` | `boolean` | `false` | Draw a rounded border box around the input (the Claude Code look). Degrades to a `single` border with no accent under a monochrome theme. |
| `fileSearch` | `(query: string, signal?: AbortSignal) => Promise<string[]>` | gitignore-aware cwd walk | The `@`-mention provider. Return `[]` to disable mentions; inject for tests or to scope the search. |
| `onShellCommand` | `(command: string) => void` | — | Enables `!` shell mode. When provided, a leading `!` enters shell mode and Enter calls this with the trimmed command. The library never spawns a process. |
| `onHelpToggle` | `() => void` | — | Enables the `?` help toggle. On an empty buffer, `?` calls this instead of typing the character. |

The `SlashCommand` type is re-exported as `ChatComposerCommand`.

## Notes

- Affordances: `/` opens the slash-command menu (case-sensitive, prefix-filtered;
  ↑↓ select, Tab/Enter complete to `/name `, Esc dismisses until the filter token
  changes). `@` opens the async file-mention menu (same nav, no dismissal latch).
  `!` at the start of the buffer enters shell mode (only when `onShellCommand` is
  set); `?` on an empty buffer toggles help (only when `onHelpToggle` is set). A `!`
  or `?` mid-text stays literal, and both degrade to plain text when their handler
  is omitted (non-breaking defaults).
- Newlines: Alt+Enter inserts a newline portably in every terminal; Shift+Enter
  needs the kitty keyboard protocol; Ctrl+J always works (literal linefeed). In
  multi-line mode Enter submits only when it is not a newline chord.
- Menu completion only edits the buffer — dispatching/executing a slash command
  stays with your app.
- Shell mode: Enter runs the command via `onShellCommand` (buffer text after the
  `!`, trimmed); a bare `!` is a no-op; Esc cancels the draft. Handlers fire before
  the buffer clears so a throwing handler propagates and the draft survives.
- Requires a raw-mode-capable stdin (a real TTY) — Ink's `useInput` throws
  otherwise. Gate the mount on `process.stdin.isTTY` in non-interactive contexts.
- Under a monochrome theme (or `NO_COLOR`) the inverse-video cursor is replaced by
  a visible marker glyph; typed text still renders.

---

# ChatMessage

Source: https://docs.usetheo.dev/theokit/tui/chat-message

A single chat message with a role glyph prefix colored from theme tokens

`ChatMessage` renders one chat message prefixed with a role glyph colored via the
active theme's role tokens. The `role` prop selects the glyph and colors explicitly
— there is no runtime role inference. Opt into Markdown rendering for string content
with `markdown`.

The three roles are differentiated the Claude Code way: the **assistant** turn is
marked with a `●` bullet (an aligned width-1 filled circle, the same family as the
tool-status bullet) and normal-weight text — it reads as the prominent output; the
**user** turn uses a `>` prompt and renders its text **dim** (the input echo); the
**system** turn uses a `·` prefix. Every glyph is overridable via the theme's role
tokens, and all components (this one included) accept
[margin props](/theokit/tui/layout-margin).

## Example

```tsx
import { Box, render } from "ink";
import { ChatMessage, TheoTUIProvider } from "@theokit/tui";

render(
  <TheoTUIProvider>
    <Box flexDirection="column">
      <ChatMessage role="user">What is @theokit/tui?</ChatMessage>
      <ChatMessage role="assistant">
        Ink primitives for AI-agent surfaces.
      </ChatMessage>
      <ChatMessage role="assistant" markdown>
        {"## Highlights\n\n```bash\nnpm install @theokit/tui\n```"}
      </ChatMessage>
    </Box>
  </TheoTUIProvider>,
);
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `role` | `ChatRole` (`"user" \| "assistant" \| "system"`) | — | Message author. Selects the glyph prefix and role colors. |
| `children` | `ReactNode` | — | Message content (text). |
| `markdown` | `boolean` | `false` | Render string children as Markdown (AI-chat subset via `MarkdownText`; fenced blocks become `CodeBlock`). Requires string children. |

## Notes

- Boundary validation: throws `TypeError` when `role` is not one of `user`,
  `assistant`, `system` — fails fast before any hook so JS consumers get the
  contract, not a crash.
- `markdown` requires string `children`; passing `markdown` with non-string
  children throws `TypeError` (Markdown needs source text).
- When `markdown` is `false` the render path is byte-identical to raw text; the
  glyph prefix always keeps the role's prefix color.
- The message text color comes from the theme role token; when that token is
  `undefined` the terminal's default color is used. The user turn additionally
  renders dim (the input-echo contrast); the assistant and system turns do not.
- Under `NO_COLOR` the glyphs still carry the role — `●` (assistant), `>` (user),
  `·` (system) — since color is stripped but text is not (degrade-as-data).

---

# ChatThread

Source: https://docs.usetheo.dev/theokit/tui/chat-thread

Windowed chat thread that graduates older messages into terminal scrollback

`ChatThread` renders an ordered list of messages with a windowed `<Static>` history:
older messages render once into terminal scrollback (Ink's scroll mechanism) and are
frozen, while the live tail re-renders per message-identity change. It is the primary
surface for streaming agent conversations, with an optional pinned header.

Turns are separated by a single blank line (the Claude Code cadence) so the
conversation breathes — with no leading blank above the first turn. The spacing
lives in `ChatThread`'s row layout, so a standalone `<ChatMessage>` embedded
elsewhere keeps zero margin.

## Example

```tsx
import { render } from "ink";
import { ChatThread, TheoTUIProvider } from "@theokit/tui";
import type { ChatThreadMessage } from "@theokit/tui";

const messages: ChatThreadMessage[] = [
  { id: "1", role: "system", content: "Demo session." },
  { id: "2", role: "user", content: "What ships in M1?" },
  { id: "3", role: "assistant", content: "ChatThread with Static history." },
];

render(
  <TheoTUIProvider>
    <ChatThread messages={messages} />
  </TheoTUIProvider>,
);
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `messages` | `ChatThreadMessage[]` | — | Ordered messages. Each has `id: string`, `role: ChatRole`, `content: string`, and optional `markdown?: boolean`. |
| `windowSize` | `number` | `8` | Number of live tail messages kept in the re-rendering region. |
| `windowOverscan` | `number` | `4` | Extra tail rows kept live beyond `windowSize` before graduating into `<Static>`. |
| `header` | `ReactElement` | — | Optional header folded as the first `<Static>` item; prints once into scrollback and stays pinned above graduated history. |

`ChatThreadMessage`:

```ts
interface ChatThreadMessage {
  id: string;           // stable unique identity — React key + Static watermark anchor
  role: ChatRole;       // "user" | "assistant" | "system"
  content: string;
  markdown?: boolean;   // per-message opt-in Markdown rendering (default false)
}
```

## Notes

- Streaming contract: to stream, replace the last message with a new object
  carrying longer `content`. Rows are memoized by object identity, so only the
  replaced row repaints. In-place mutation (same reference) does not repaint.
- Messages beyond `windowSize + windowOverscan` graduate into `<Static>` and are
  frozen (append-only history). Treat both window props as mount-time tuning knobs:
  increasing them after messages have graduated pulls scrollback rows back into the
  live tail and visibly duplicates history (Static output is unerasable).
- `header` is a mount-time prop: the first render's value is frozen for the
  component's life; later changes to its content, identity, and presence are ignored
  by design.
- Empty-string ids are legal; only duplicate ids throw `TypeError`. A message id
  equal to the reserved header sentinel key (`__theokit_tui_header__`, exported as
  `HEADER_SENTINEL_KEY`) also throws.
- Size the header explicitly — Static's box is content-sized and absolute, so
  percentage widths may not resolve as they do in the live region.
- [Margin props](/theokit/tui/layout-margin) apply to the **live region**; the
  graduated `<Static>` history is not margined (a scrollback row's position is
  frozen once printed).

---

# ChoiceRow

Source: https://docs.usetheo.dev/theokit/tui/choice-row

A fixed choice bar (horizontal or vertical/numbered) — the callback-only spine of the decision surfaces.

A fixed choice bar over a small set of `{value, label}` choices. Distinct from `SelectList` (a filterable windowed vertical list), `ChoiceRow` has no filter and no window: arrows move (wrapping), Enter commits the active choice, Esc cancels, and a digit `1..n` jumps. The active choice is marked with `❯`; the accent color is decorative, the glyph carries the meaning.

It renders **horizontally** by default (the spine of [`ApprovalPrompt`](/theokit/tui/approval-prompt)), or **vertically with numbered prefixes** (`❯ 1. Yes` / `2. No`) via `orientation="vertical"` + `numbered` — the layout that powers [`PermissionPrompt`](/theokit/tui/permission-prompt). Both share one keyboard oracle: ←/→ move on the horizontal bar, ↑/↓ move on the vertical one, and a digit jumps in either.

## Example

```tsx
import { ChoiceRow } from "@theokit/tui";

<ChoiceRow
  choices={[
    { value: "once", label: "Allow once" },
    { value: "always", label: "Allow always" },
    { value: "reject", label: "Reject" },
  ]}
  onCommit={(value) => record(`chose: ${value}`)}
  onCancel={() => record("cancelled")}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `choices` | `readonly ApprovalChoice[]` | — (required) | The choices to render. `ApprovalChoice` is `{ value: string; label: string }`. |
| `onCommit` | `(value: string) => void` | — (required) | Called with the active choice's `value` on Enter (or a digit jump + Enter). |
| `onCancel` | `() => void` | `undefined` | Called on Esc. The caller decides the safe default (reject/revise). |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` stacks each choice on its own line (the numbered-menu / `PermissionPrompt` idiom); ↑/↓ move in that mode. |
| `numbered` | `boolean` | `false` | Prefix each label with `{n}. ` (matches the digit-jump shortcut). |
| `autoFocus` | `boolean` | `true` | Take focus on mount. Set `false` for a non-interactive render so the bar does not grab stdin. |

## Notes

- Callback-only: the component holds only the highlighted-index UI state — no app state machine. The decision leaves via `onCommit` / `onCancel`.
- The committed index is mirrored in a ref so a move + Enter arriving in the same tick (rapid input / paste over a real PTY) commits the moved-to choice, not the pre-move one.
- When the `choices` prop shrinks (a dynamic/streamed set), the index re-clamps to the new last row so it never renders no active marker or commits `undefined`.
- Requires a raw-mode TTY for interactive input; consumes the library's own input/focus hooks (mount under `InputContext` + `FocusProvider`).

---

# CodeBlock

Source: https://docs.usetheo.dev/theokit/tui/code-block

Syntax-highlighted code block that renders plain immediately and upgrades once the optional highlighter loads.

A syntax-highlighted code block. It renders plain immediately, then re-renders highlighted once the optional `lowlight` peer loads. Tabs expand to 4 spaces and ANSI escapes are stripped on input. Highlighting is deterministic — the language must be given explicitly (no auto-detect).

## Example

```tsx
import { CodeBlock, preloadHighlighter } from "@theokit/tui";

// Optional: await once so a one-shot / piped render captures the
// highlighted first frame instead of the plain one.
await preloadHighlighter();

const snippet = ['const result = greet("theo");', "console.log(result);"].join("\n");

<CodeBlock code={snippet} language="typescript" showLineNumbers />
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `code` | `string` | — (required) | Source text. ANSI escapes are stripped on input; tabs expand to 4 spaces. Trailing newline is not a row; empty input renders `null`. |
| `language` | `string` | `undefined` | Explicit language id (lowlight/common). No auto-detect — determinism. When omitted or unregistered, lines render plain. |
| `showLineNumbers` | `boolean` | `false` | Dim, right-aligned original line numbers. |
| `maxLines` | `number` | `undefined` | HEAD-retained line cap with a dim `… (+N more lines)` trailer. Must be an integer `>= 1`. |
| `interactive` | `boolean` | `false` | When line-capped, make the block interactively expandable (ctrl+o / Space / Enter over the collapsible block). |

## Notes

- `lowlight` is an OPTIONAL peer dependency. When it is absent, the block degrades to plain rendering permanently and emits one `console.warn` naming the peer (never a throw, never fully silent).
- Because highlighting arrives asynchronously, the first frame is always plain. Call `preloadHighlighter()` before a one-shot or piped render (snapshot tools, piped demos) so the single captured frame is the highlighted one — this is the public readiness seam.
- Highlighting follows a fallback ladder: an unavailable/unregistered highlighter, an empty highlight result, or a thrown highlight all fall back to the plain line.
- An invalid `maxLines` (non-integer or `< 1`) throws a `TypeError` at the boundary before any hook runs.

---

# CollapsibleBlock

Source: https://docs.usetheo.dev/theokit/tui/collapsible-block

A collapsed summary line plus an expandable body, controlled or key-toggled.

A collapsed summary line with an expandable body. When `expanded` is passed the block is controlled (the parent owns state; Space/Enter call `onToggle`); otherwise it is uncontrolled (internal state seeded by `defaultExpanded`). The `▶`/`▼` affordance is a glyph, so it survives a monochrome theme. `ThinkingBlock` is a preset for reasoning content, also exported from this file.

## Example

```tsx
import { CollapsibleBlock, ThinkingBlock } from "@theokit/tui";
import { Text } from "ink";

<CollapsibleBlock summary={<Text>tool output (space to expand)</Text>}>
  <Text dimColor>… 240 lines of build log …</Text>
</CollapsibleBlock>

<ThinkingBlock>
  The user wants a **live-turn** demo — I will compose the primitives.
</ThinkingBlock>
```

## Props

### CollapsibleBlockProps

| Prop | Type | Default | Description |
|---|---|---|---|
| `summary` | `ReactNode` | — (required) | The always-visible summary line, rendered after the `▶`/`▼` affordance. |
| `children` | `ReactNode` | — (required) | The body shown only when expanded. |
| `expanded` | `boolean` | `undefined` | Controlled expansion — when set, the block defers to this prop plus `onToggle`. |
| `defaultExpanded` | `boolean` | `false` | Uncontrolled initial state (ignored when `expanded` is set). |
| `onToggle` | `(expanded: boolean) => void` | `undefined` | Called with the requested next state on Space/Enter. |
| `autoFocus` | `boolean` | `true` | Whether the block grabs focus on mount so its toggle key is active. |

### ThinkingBlockProps

| Prop | Type | Default | Description |
|---|---|---|---|
| `summary` | `string` | `"Thinking…"` | The summary line (rendered dim + italic, prefixed with the `✻` thinking marker glyph). |
| `children` | `ReactNode` | — (required) | The reasoning body; a plain string renders via `MarkdownText`, otherwise the node is used as-is. |
| `defaultExpanded` | `boolean` | `false` | Uncontrolled initial expansion state. |

## Notes

- Toggle keys are Space or Enter; input is only active while the block is focused.
- No global toggle registry — each block owns only its own state; instances toggle independently.
- `ThinkingBlock` is a `CollapsibleBlock` preset: collapsed by default, dim + italic summary prefixed with the `✻` marker glyph, and a `MarkdownText` body when `children` is a string.

---

# ContextWindowBar

Source: https://docs.usetheo.dev/theokit/tui/context-window-bar

Context-window fill gauge with an endpoint-honest percentage and token detail.

A fill gauge for the context window. It is endpoint-honest: `100%`/`0%` are reserved for the truly-full/truly-empty states (99.6% used reads "1% left" with a visibly non-full bar). Props carry the last-turn context size, not a session total. When `limitTokens` is omitted the limit is unknown, so it renders the absolute count only — never a fabricated percentage.

## Example

```tsx
import { ContextWindowBar } from "@theokit/tui";

<ContextWindowBar usedTokens={79_360} limitTokens={128_000} width={46} />
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `usedTokens` | `number` | — (required) | Absolute tokens currently in the context window. Finite, `>= 0`. |
| `limitTokens` | `number` | `undefined` | Context-window size. Omitted = unknown: renders `<count> tokens used` and no percentage/bar. When present, must be finite and `> 0`. |
| `convention` | `"left" \| "used"` | `"left"` | Label wording. `"left"` (default) shows percent remaining with the detail clause; `"used"` shows percent consumed. The bar always fills with usage in both; the label derives from the same display authority so they can never disagree. |
| `baselineTokens` | `number` | `0` | Tokens subtracted from both used and limit before the ratio (effective-window parity). Finite, `>= 0`, and must be `< limitTokens`. Ignored when the limit is unknown. |
| `width` | `number` | `40` | Total column budget (bar + label + detail). Integer, `>= 0`. |

## Notes

- Invalid props throw a `TypeError` at the boundary before any hook: non-finite/negative `usedTokens`, `limitTokens <= 0`, `baselineTokens < 0` or `>= limitTokens`, or a non-integer/negative `width`.
- Fill color reflects usage: accent below the 0.5 warning ratio, warning color at or above it, and error color when full (`usedRatio >= 1`).
- When the computed bar cells fall below the minimum, the bar is dropped and only the label renders.
- The detail suffix reads `(<used> used / <limit>)` using `formatTokens` for compaction.

---

# CostMeter

Source: https://docs.usetheo.dev/theokit/tui/cost-meter

Honest session-cost display with an optional estimate marker.

An honest cost display rendering `cost ~$1.23`. The cost is precomputed in USD by the caller — this package ships no pricing tables. There is no bar and no budget thresholds; a nonzero sub-cent cost renders `<$0.01`, never `$0.00`.

## Example

```tsx
import { CostMeter } from "@theokit/tui";

<CostMeter costUsd={1.87} />
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `costUsd` | `number` | — (required) | Precomputed session cost in USD. Finite, `>= 0`. |
| `approx` | `boolean` | `true` | Show the `~` estimate marker (the number derives from token counts × price sheets). |

## Notes

- Invalid `costUsd` (non-finite or negative) throws a `TypeError` at the component boundary before render.
- The `~` marker is suppressed for an exact zero and for sub-cent renders even when `approx` is `true`.
- Formatting is delegated to `formatCost`, which re-validates at its own boundary.

---

# DiffViewer

Source: https://docs.usetheo.dev/theokit/tui/diff-viewer

Unified-diff renderer with signed lines, optional folding, line-number gutter, and intra-line word highlight.

Renders unified-diff text — the shape agent tools emit — as a multi-file view with `+`/`-`/` ` sign columns, a dim line-number gutter, and per-file `+additions`/`-deletions` counts. Signs are rendered unconditionally (a color-independent mechanism that survives `NO_COLOR`), and code lines wrap rather than truncate.

## Example

```tsx
import { DiffViewer } from "@theokit/tui";

const patch = [
  "--- a/greet.ts",
  "+++ b/greet.ts",
  "@@ -1,5 +1,6 @@",
  " export function greet(name: string) {",
  "-  return `hi ${name}`;",
  "+  const greeting = `hello ${name}`;",
  "+  return greeting;",
  " }",
].join("\n");

<DiffViewer patch={patch} contextLines={2} maxLines={12} />
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `patch` | `string` | — (required) | Unified-diff text (the shape agent tools emit). Parsed via `parseUnifiedDiff`. |
| `showLineNumbers` | `boolean` | `true` | Dim, right-aligned line-number gutter. |
| `maxLines` | `number` | `undefined` | Global rendered-row budget across all files, headers included. HEAD retention — first rows survive, with a dim `… (+N more lines)` trailer counting hidden source lines. Must be an integer `>= 1`. |
| `contextLines` | `number` | `undefined` | Fold unchanged runs beyond ±`contextLines` around changes into dim `--- N lines hidden ---` rows. Folding happens before capping. Must be an integer `>= 0`. |
| `intraLineHighlight` | `boolean` | `false` | Within paired del/add line replacements, highlight the changed words (rendered `inverse`). Off by default; when off, the word-diff is never computed and the render is byte-identical to whole-line coloring. |

## Notes

- The patch is parsed by `parseUnifiedDiff` (also exported from the package). It is lenient: trailing garbage after a valid file is dropped, and it throws a typed `TypeError` only when nothing parses out of a non-empty patch.
- An empty (or whitespace-only) patch renders `(no changes)`. A file with no line content (binary or metadata change) renders a dim `binary or metadata change` row.
- Parsing runs before any hook so the malformed-patch `TypeError` fires on direct invocation (Ink otherwise swallows render throws).
- Fold order is fixed: fold first, then cap. Runs of a single hidden line are not folded (a one-line fold row saves nothing).
- Invalid `maxLines` (non-integer or `< 1`) or `contextLines` (non-integer or `< 0`) throw a `TypeError` at the boundary before any hook runs.
- Renamed files show `oldName → newName` in the header; tabs expand to 4 spaces in line bodies.

---

# ExpandableOutput

Source: https://docs.usetheo.dev/theokit/tui/expandable-output

A capped view that reveals its full body on ctrl+o, Space, or Enter.

A capped output view that reveals its full body on `ctrl+o` / Space / Enter (the gemini `ctrl+o` idiom). It renders the `▶`/`▼` affordance inline as a line below the content, showing the number of hidden lines while collapsed. Per-component state — no global registry, so multiple instances toggle independently.

## Example

```tsx
import { ExpandableOutput } from "@theokit/tui";
import { Text } from "ink";

const HIDDEN = Array.from({ length: 12 }, (_, i) => `log line ${i}`).join("\n");

<ExpandableOutput
  collapsed={<Text dimColor>log line 0 … (capped)</Text>}
  expanded={<Text dimColor>{HIDDEN}</Text>}
  hiddenCount={11}
/>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `collapsed` | `ReactNode` | — (required) | The capped preview shown while collapsed. |
| `expanded` | `ReactNode` | — (required) | The full body shown while expanded. |
| `hiddenCount` | `number` | — (required) | Lines hidden by the cap — shown in the collapsed affordance line. |
| `autoFocus` | `boolean` | `true` | Whether the component grabs focus on mount so its toggle keys are active. |

## Notes

- Toggle keys are `ctrl+o`, Space, or Enter; input is only active while focused.
- The affordance is its own line below the content: `▶ … {hiddenCount} more (ctrl+o)` when collapsed, `▼ (ctrl+o to collapse)` when expanded.
- The `▶`/`▼` glyph carries the affordance under a monochrome theme.
- It renders the affordance inline rather than composing `CollapsibleBlock`, avoiding a second focusable that would inject a dead Tab-stop.

---

# FreeTextInput

Source: https://docs.usetheo.dev/theokit/tui/free-text-input

A minimal single-line text input — the shared free-text branch of QuestionPrompt and PlanApproval.

A minimal single-line text input over the shared text-buffer reducer — the free-text branch used by `QuestionPrompt` ("Other…") and `PlanApproval` ("revise"). Enter submits the current text (empty allowed); Esc cancels back to the parent. It gates input on focus so it never steals keys meant for a different focused surface.

## Example

```tsx
import { FreeTextInput } from "@theokit/tui";

<FreeTextInput
  label="Commit message:"
  onSubmit={(text) => record(`freetext: ${text}`)}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | — (required) | The prompt label shown before the buffer (e.g. `"Type your answer:"`). |
| `onSubmit` | `(text: string) => void` | — (required) | Called with the buffer text on Enter (empty string allowed). |
| `onCancel` | `() => void` | `undefined` | Called when Esc blurs the input (cancel back to the parent surface). |
| `autoFocus` | `boolean` | `true` | Take focus on mount. Set `false` for a non-interactive render (e.g. a component gallery) so the input does not grab stdin. |

## Notes

- Callback-only: the component holds only the text-buffer state. Submitted / cancelled text leaves via `onSubmit` / `onCancel`.
- Enter submits even when the buffer is empty — an empty string is a valid submission.
- Esc-cancel is edge-triggered: once the input has been focused, a subsequent blur (from the priority Esc arbiter) fires `onCancel`, since this is the exclusive interactive branch of its parent.
- Input is gated on `isFocused`, so it never steals keystrokes destined for another focused surface.
- Requires a raw-mode TTY for interactive input (mount under `InputContext` + `FocusProvider`).

---

# Getting started

Source: https://docs.usetheo.dev/theokit/tui/getting-started

From npm install to a rendered agent turn in the terminal.

The north-star of `@theokit/tui` is TTFATT — time-to-first-agent-turn-in-terminal.
This walkthrough takes you from an empty project to a streaming turn with tool
cards in a few minutes.

## 1. Install

```bash
npm install @theokit/tui react ink
```

`react` (>= 19.2) is the only required peer. Ink is a normal dependency. The
package is ESM-only and ships TypeScript types.

## 2. Wrap your app in the provider

`TheoTUIProvider` supplies theme tokens (colors, glyphs, role styles) to every
component. It is the one thing every tree needs.

```tsx title="cli.tsx"
import { render } from 'ink';
import { TheoTUIProvider, ChatThread } from '@theokit/tui';

function App() {
  return (
    <TheoTUIProvider>
      <ChatThread
        messages={[
          { id: '1', role: 'user', content: 'Fix the flaky retry test.' },
          { id: '2', role: 'assistant', content: 'On it.' },
        ]}
      />
    </TheoTUIProvider>
  );
}

render(<App />);
```

Run it with `tsx cli.tsx` (or your bundler) and you have a rendered thread.

## 3. Stream a real agent turn

The stream adapter, `useAgentStream`, folds a stream of agent events (from
`@theokit/sdk`, or any `AsyncIterable` of the event shape) into UI state. It gives
you the live message list, the current status, and the in-flight tool calls.

```tsx title="cli.tsx"
import { render } from 'ink';
import { TheoTUIProvider, ChatThread, AgentStreaming, useAgentStream } from '@theokit/tui';

function App({ source }) {
  const { messages, status } = useAgentStream(source);

  return (
    <TheoTUIProvider>
      <ChatThread messages={messages} />
      {status === 'streaming' && <AgentStreaming thought="working" elapsedSeconds={0} />}
    </TheoTUIProvider>
  );
}

render(<App source={agentEvents} />);
```

As events arrive, the assistant message grows token by token, tool calls render as
cards with a live status, and `AgentStreaming` shows the "thinking" indicator.

## 4. Add an input composer

`ChatComposer` is the multi-line input. It is callback-only: it emits the typed
text and lets you decide what to do (send it to your agent, run a command). It
ships the Claude Code affordances out of the box.

```tsx
import { ChatComposer } from '@theokit/tui';

<ChatComposer
  placeholder="Type a message"
  bordered
  commands={[{ name: 'help', description: 'show commands' }]}
  onSubmit={(text) => sendToAgent(text)}
  onShellCommand={(cmd) => runInApp(cmd)}   // ! shell mode
  onHelpToggle={() => setHelpOpen((v) => !v)} // ? help panel
/>
```

- Type `/` for the command menu, `@` to mention a file (with path navigation),
  `!` to enter shell mode, `?` to toggle a keyboard-shortcut panel.
- `Enter` submits, `Alt+Enter` inserts a newline.

## 5. A polished startup header (optional)

`Banner` renders an ASCII-art logo plus a framed status box — the Qwen / OpenCode
startup look.

```tsx
import { Banner, renderFigletArt } from '@theokit/tui';

// Generate the logo from text via the optional figlet peer; fall back if absent.
const art = (await renderFigletArt('Theo', 'Standard')) ?? undefined;

<Banner
  name="Theo CLI"
  art={art}
  layout="banner"
  status={[
    { label: 'model', value: 'gpt-4o' },
    { label: 'cwd', value: process.cwd() },
  ]}
/>;
```

## Runtime notes

- **Interactive input** (`ChatComposer`, `SelectList`, the decision prompts)
  requires a raw-mode-capable TTY. Gate the mount on `process.stdin.isTTY` in
  non-interactive contexts.
- **Piped / non-TTY** output degrades: components render a static, readable frame
  and never spray cursor escapes into logs.

Every component in the reference below ships with a runnable example in the
package's `examples/` folder. `pnpm example:showcase` plays a full scripted agent
turn using every primitive at once.

---

# Image

Source: https://docs.usetheo.dev/theokit/tui/image

Inline terminal image on kitty/iTerm2, with a text fallback everywhere else.

An inline-image component. On a kitty or iTerm2 terminal it emits the protocol escape sequence plus blank filler rows; on any other terminal — or under a multiplexer, or with unreadable image bytes — it renders a `[Image: …]` text fallback. The app supplies the bytes (`base64Data` plus `mimeType`); the component never does I/O.

## Example

```tsx
import { Image } from "@theokit/tui";

// The app reads the file and passes base64 bytes; a 1x1 PNG shown here.
const PNG_1X1 =
  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";

<Image
  base64Data={PNG_1X1}
  mimeType="image/png"
  filename="dot.png"
  maxWidthCells={20}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `base64Data` | `string` | — | Raw image bytes as base64 (the app reads the file; the component is pure). |
| `mimeType` | `string` | — | `image/png`, `image/jpeg`, `image/gif`, or `image/webp`. |
| `maxWidthCells` | `number` | `40` | Max width in terminal cells. |
| `filename` | `string` | `undefined` | Shown in the text fallback. |
| `protocol` | `"kitty" \| "iterm2" \| null` | env detection | Force a protocol (tests / explicit control). Defaults to env detection — `null` on multiplexers and unrecognized terminals (text fallback). |

## Notes

- Falls back to the `[Image: …]` text placeholder when no protocol is detected or the bytes are unreadable.
- Kitty images are freed on unmount (a `deleteKittyImage` escape), so mounted images do not permanently leak bytes into the terminal's graphics store. This is a no-op under Ink's default no-op stdout write and for iTerm2 (no persistent upload).
- Filler-line convention follows pi's image component: kitty puts the sequence on the first line with blank rows below; iTerm2 puts blank rows first, then a cursor-up plus the sequence on the last line, so cursor accounting stays inside the frame.

---

# TUI overview

Source: https://docs.usetheo.dev/theokit/tui

AI-native terminal UI components for agent CLIs, built on Ink (React for the terminal).

**@theokit/tui** is the terminal-native sibling of TheoUI. It ships the same
AI-agent primitives — `ChatThread`, `ToolCallCard`, `DiffViewer`, `AgentTimeline`,
`TokenUsageChart`, and the rest — as **Ink** components (React for the terminal),
so a coding agent or chat CLI gets one coherent primitive set instead of
rebuilding streaming, tool-call, and diff rendering from scratch.

If you have built a React app, you can build an agent CLI: same components, same
props, same theme tokens — rendered to a terminal instead of a browser.

## Install

```bash
npm install @theokit/tui react ink
```

`react` is the only required peer. `figlet` and `lowlight` are **optional** peers
(for `Banner` text-to-art and `CodeBlock` syntax highlighting) — install them only
if you use those features; both degrade gracefully when absent.

## Quick start

Mount a provider, a thread, and a stream adapter — a real agent turn renders in
the terminal:

```tsx title="cli.tsx"
import { render } from 'ink';
import {
  TheoTUIProvider,
  ChatThread,
  useAgentStream,
} from '@theokit/tui';

function App({ source }) {
  const { messages } = useAgentStream(source); // @theokit/sdk events / AsyncIterable

  return (
    <TheoTUIProvider>
      <ChatThread messages={messages} />
    </TheoTUIProvider>
  );
}

render(<App source={agentEvents} />);
```

That is the whole loop: `useAgentStream` folds agent events into UI state, and
`ChatThread` renders the turn — streaming text, tool cards, and all — token by
token.

## What you get

## Design principles

- **AI-native, not a generic TUI kit.** Every primitive maps to an agent-surface
  concept (turn, tool call, diff, token budget) — not menus and forms.
- **Declarative + callback-only.** Components render from props and emit events;
  the app owns state and side effects. No component spawns a process or calls an
  LLM.
- **Degrade as data.** Themes change color only; glyphs carry meaning so status is
  legible under `NO_COLOR`. Everything renders (degraded) on a non-TTY pipe.

`@theokit/tui` is Apache-2.0 and standalone — usable in any Ink app. It pairs
naturally with `@theokit/sdk` as the event source, but depends on nothing but
`react` + `ink`.

## Where to go next

---

# InkInputProvider

Source: https://docs.usetheo.dev/theokit/tui/ink-input-provider

Bridge that makes this library's interactive components respond to keys under pure Ink's render().

`InkInputProvider` wires keyboard input for this library's interactive components when you
render them under pure Ink's `render()`.

The interactive components — [`ChoiceRow`](/theokit/tui/choice-row),
[`SelectList`](/theokit/tui/select-list), [`Pager`](/theokit/tui/pager),
[`FreeTextInput`](/theokit/tui/free-text-input) and the decision prompts that compose them —
consume the custom V4 renderer's input + focus hooks, whose `InputContext` is not mounted
under Ink's `render`. Without this provider they render but silently ignore every key.
`InkInputProvider` connects an input source to Ink's stdin and provides the `InputContext`
+ focus context those components need. **Mount it once, high in the tree**, when you render
these interactive surfaces under Ink. Non-interactive apps (or
[`ChatComposer`](/theokit/tui/chat-composer), which uses Ink's own input hooks) do not need
it.

## Example

```tsx
import { render } from "ink";
import { InkInputProvider, TheoTUIProvider, SelectList } from "@theokit/tui";

render(
  <TheoTUIProvider>
    <InkInputProvider>
      <SelectList
        items={[
          { label: "Approve", value: "approve" },
          { label: "Reject", value: "reject" },
        ]}
        onSelect={(v) => console.log(v)}
      />
    </InkInputProvider>
  </TheoTUIProvider>,
);
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `ReactNode` | — (required) | The subtree containing this library's interactive components. |

## Notes

- Raw mode is delegated to Ink's ref-counted `setRawMode`, so the two input systems share one terminal-mode owner and never fight over it.
- Off a TTY (or where raw mode is unsupported), the provider is inert — interactive input is simply disabled, as it must be without a terminal.
- Mount it **once**. Nesting a second provider re-subscribes stdin; keep a single instance near the root, inside [`TheoTUIProvider`](/theokit/tui/theotui-provider).
- It is not needed for the custom-renderer entrypoints of this library, which already mount the input context — only for the pure-Ink `render()` path.

---

# KeyboardHelp

Source: https://docs.usetheo.dev/theokit/tui/keyboard-help

A presentational bordered panel listing keyboard shortcuts.

A presentational keyboard-shortcut help panel (Claude Code's `?` overlay). The library ships the panel plus a default shortcut list; the app owns when to show it and which shortcuts to list. It is presentational only — no input handling, so the caller decides visibility and dismissal.

## Example

```tsx
import { KeyboardHelp, DEFAULT_COMPOSER_SHORTCUTS } from "@theokit/tui";

<KeyboardHelp shortcuts={DEFAULT_COMPOSER_SHORTCUTS} />;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `shortcuts` | `readonly KeyboardShortcut[]` | — (required) | The rows to render. Each `KeyboardShortcut` is `{ keys: string; description: string }`. |
| `title` | `string` | `"Keyboard shortcuts"` | The bold panel title. |

`KeyboardShortcut` is `{ keys: string; description: string }` — `keys` is the key or chord (e.g. `"Alt+Enter"` or `"↑ ↓"`), `description` is a one-line explanation.

## Notes

- `DEFAULT_COMPOSER_SHORTCUTS` is exported: a ready set of the ChatComposer's built-in chords (Enter, Alt+Enter, `/`, `@`, `!`, `?`, arrows, Emacs-style line editing, Ctrl+C to quit). Spread it into the panel, then extend or replace with app-specific entries.
- The keys column auto-sizes to the widest `keys` string (plus padding); descriptions render dim.
- Degrades to a `single` border with no accent color under a monochrome theme.

---

# Layout & margin

Source: https://docs.usetheo.dev/theokit/tui/layout-margin

The universal margin API — every component accepts margin / marginX / marginY and the four sides

Every public visual component in `@theokit/tui` accepts the **CSS/Ink margin
family** and applies it to its root layout, so you can space any component from
its neighbours without wrapping it in a `<Box>`.

```tsx
import { ChatMessage, Banner, TodoList } from "@theokit/tui";

<Banner name="Theo" marginBottom={1} />
<TodoList items={items} marginY={1} />
<ChatMessage role="assistant" marginLeft={2}>done</ChatMessage>
```

## The props

Each component's props extend the shared `LayoutMarginProps` type:

| Prop | Type | Description |
|---|---|---|
| `margin` | `number` | All four sides. |
| `marginX` | `number` | Left + right. |
| `marginY` | `number` | Top + bottom. |
| `marginTop` | `number` | Top only. |
| `marginRight` | `number` | Right only. |
| `marginBottom` | `number` | Bottom only. |
| `marginLeft` | `number` | Left only. |

Values are **terminal cells** (rows for top/bottom, columns for left/right) — not
CSS units. All are optional and default to unset.

```ts
import type { LayoutMarginProps } from "@theokit/tui";

// Your own composite component can adopt the same surface:
interface MyPanelProps extends LayoutMarginProps {
  title: string;
}
```

## Helpers

The type ships with two helpers (and the key list) for building components that
forward margin correctly:

| Export | Description |
|---|---|
| `pickMargin(props)` | Returns only the margin fields (drops `undefined`) — spread onto a root `<Box>`. |
| `omitMargin(props)` | Returns `props` with the margin fields removed — forward the rest to a child so the margin is not applied twice. |
| `LAYOUT_MARGIN_KEYS` | The seven margin keys, in a stable order. |

```tsx
import { Box } from "ink";
import { pickMargin, omitMargin } from "@theokit/tui";

// A wrapper that owns the margin on its own Box, then forwards the rest:
function Card(props) {
  return (
    <Box flexDirection="column" {...pickMargin(props)}>
      <Header {...omitMargin(props)} />
    </Box>
  );
}
```

## Notes

- **Backward-compatible by construction.** When you pass no margin, the spread is
  a no-op and output is byte-identical to a component without the prop — adding
  the universal margin API changed no existing render.
- **Text-rooted components** (`FreeTextInput`) cannot carry margin on their Ink
  `<Text>` root, so they wrap in a margin `<Box>` **only when** a margin is
  actually passed (an always-on wrapper would add a layout node to a
  focus-sensitive input).
- **`<Static>`-based surfaces** (`ChatThread`, `AgentTimeline`) carry the margin
  on their **live region**. Their append-only scrollback history is not margined —
  a graduated row's position in the terminal is frozen.
- **Composition.** A component that owns its root `<Box>` and forwards the rest of
  its props to a child (like `ToolCallCard` → `ToolCall`) uses `pickMargin` /
  `omitMargin` so the gap is applied once, on the outer box.

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/tui/llms-txt

Machine-readable ground truth of @theokit/tui for LLMs — package metadata, full component inventory, import paths, conventions, and anti-patterns. Download it or curl it directly.

{/* curated */}

`@theokit/tui` ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that
gives any LLM (Claude, ChatGPT, Cursor, Copilot, a local model) the **factual
ground truth** of this package without crawling the whole site:

- Exact package name, current version, and npm tag
- The full component inventory (~34 components + hooks + helpers), grouped by surface
- The canonical import path (a single barrel) and the three real subpath exports
  (`.`, `./renderer`, `./ai-sdk`)
- The peer-dependency table (React required; figlet + lowlight + ai optional)
- Conventions to follow (declarative, callback-only, TTY-gating, degrade-as-data)
- Anti-patterns to avoid (do NOT run shell in a component, do NOT hard-import an
  optional peer, do NOT mount interactive components on a non-TTY, no CJS)
- Locked names (themes, tool statuses, chat roles, the Claude Code parity glyphs)

Use it when:

- You use an AI coding assistant to scaffold or refactor code that consumes
  `@theokit/tui` and want it to stop hallucinating import paths or component names.
- You write an agent that consumes the package and needs structured metadata.
- You want a single file to drop into a prompt as context.

## Download

  <Card
    title="Download llms.txt"
    description="Single self-contained Markdown file. Place it next to your project AGENTS.md / .cursorrules / CLAUDE.md and reference it from the system prompt."
    href="/theokit/tui/llms.txt"
  />

## Curl it directly

```bash
# Save to your project root
curl -o theokit-tui-llms.txt https://docs.usetheo.dev/theokit/tui/llms.txt

# Or pipe straight into a prompt
curl -s https://docs.usetheo.dev/theokit/tui/llms.txt | head -120
```

## What the file contains

The file is structured for LLM consumption — front-loaded facts, imperative
conventions, and tables. Sections in order:

1. **Project metadata** — name, version, license, repo, docs URL, module format,
   Node floor, required vs optional peers.
2. **Install** — the npm command plus the optional peers.
3. **Import path canonical form** — the single barrel and the two subpath exports
   (`.` and `./renderer`); there is no per-component subpath.
4. **Quick start** — the whole `TheoTUIProvider` + `ChatThread` + `useAgentStream`
   loop.
5. **Component inventory** — every barrel export, grouped Foundation / Chat / Tool
   calls / Agent / Stream adapter / Code / Metrics / Banner / Interaction / Agent
   decisions / Live progress / Terminal integration, with props and behavior.
6. **Conventions** — the load-bearing rules (provider, callback-only, TTY-gating,
   degrade-as-data, optional-peer degrade).
7. **Anti-patterns** — the things that break consumers.
8. **Testing** — Vitest + ink-testing-library, NO_COLOR / non-TTY as first-class.
9. **Locked names** — themes, tool statuses, roles, and the `●` / `⎿` / `✻` glyphs.
10. **Source of truth** — the barrel file + this docs section + the `examples/` folder.

The source files always win. If a bullet in `llms.txt` disagrees with
`src/index.ts` or the per-component reference on this site, the code is correct and
the file is stale — regenerate it from the barrel.

---

# MarkdownText

Source: https://docs.usetheo.dev/theokit/tui/markdown-text

Assistant-text Markdown renderer for the AI-chat subset, styled by theme tokens.

Renders the AI-chat Markdown subset — headings 1-4, lists, horizontal rules, paragraphs, fenced code (via `CodeBlock`), tables, and inline bold/italic/strikethrough/verbatim code/links — into an Ink tree styled by theme tokens. Streaming partials are safe: an unclosed code fence still renders as code, and malformed input degrades to literal text rather than throwing mid-turn.

## Example

```tsx
import { MarkdownText } from "@theokit/tui";

<MarkdownText text={"# H\n**b** and `c`"} />

<MarkdownText
  text={"## Release matrix\n\n| surface | status |\n| --- | :-: |\n| tables | done |"}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `text` | `string` | — (required) | Markdown source (the AI-chat subset). Streaming partials are safe — an unclosed code fence still renders as code. |

## Notes

- Headings use a level ladder: h1/h2 are bold in the theme accent color, h3 is bold, h4 is italic dim (gemini parity).
- Tables render as a box-drawing grid when they fit the terminal width; when too wide they degrade to space-separated, wrapped cells — no data loss, no overflow.
- Fenced code blocks are delegated to `CodeBlock`, with the fence language forwarded to the highlighter.
- Malformed input never throws mid-turn — it degrades to literal text. Empty input renders `null`.
- Under monochrome themes the color axis is zeroed while bold/italic/strikethrough attributes survive (these are SGR attributes, not color).
- Known subset limits: styled link text is literal (`[**b**](u)` keeps the asterisks — no recursive parse inside links), and a code span inside an h1/h2 heading is visually fused with the heading accent.
- A non-string `text` throws a `TypeError` at the boundary before any hook runs (fail-fast for JS consumers).

---

# ModeIndicator

Source: https://docs.usetheo.dev/theokit/tui/mode-indicator

The Claude Code permission-mode footer line — auto-accept / plan, with a glyph that carries the mode.

`ModeIndicator` renders the Claude Code permission-mode footer line:

```
⏵⏵ auto-accept edits on (shift+tab to cycle)
⏸ plan mode on (shift+tab to cycle)
```

The `default` mode renders nothing. It is display-only: the app owns the mode state and the
`shift+tab` cycling; this component only draws the line. The glyph (`⏵⏵` / `⏸`) carries the
mode under a monochrome theme (degrade-as-data).

## Example

```tsx
import { ModeIndicator } from "@theokit/tui";

<ModeIndicator mode="auto-accept" />;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `mode` | `"default" \| "auto-accept" \| "plan"` | — (required) | The active permission mode. `default` renders nothing; an invalid mode throws a `TypeError` at the boundary. |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props. |

## Notes

- The mode set is exported as `PERMISSION_MODES` (`readonly ["default", "auto-accept", "plan"]`) — in cycle order, so a `shift+tab` handler can advance `(i + 1) % PERMISSION_MODES.length`.
- The active mode is theme-accent colored; the dim `(shift+tab to cycle)` suffix always follows.
- For the full two-line footer (a status row above the mode row), compose [`StatusFooter`](/theokit/tui/status-footer), which embeds this component.

---

# MultiStepProgress

Source: https://docs.usetheo.dev/theokit/tui/multi-step-progress

A discrete n-of-m step list with a counter header, reusing TodoList rows.

A discrete n-of-m step list: a header line plus a step list. Each step is a `TodoItem` with ordered semantics, so the rows reuse `<TodoList>` verbatim and this component only adds the header. Without `current` the header counts done steps (`"{done} of {total}"`); with `current` it shows the clamped step position (`"step {i} of {total}"`). A `groupLabel` renders a subagent-lane variant header.

## Example

```tsx
import { MultiStepProgress, type TodoItem } from "@theokit/tui";

const STEPS: TodoItem[] = [
  { id: "a", label: "researcher", status: "done" },
  { id: "b", label: "coder", status: "active" },
  { id: "c", label: "reviewer", status: "pending" },
];

<MultiStepProgress steps={STEPS} groupLabel="3 subagents" />;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `steps` | `readonly TodoItem[]` | — (required) | The ordered steps; each is a `TodoItem` (`{ id, label, status }`), rendered via `<TodoList>`. |
| `current` | `number` | `undefined` | Active step index — renders a `"step i of m"` position counter (clamped to the valid range). Omit to render a `"{done} of {total}"` completed counter instead. |
| `groupLabel` | `string` | `undefined` | A bold subagent group header rendered above the steps (each step's `label` is a lane name). |

## Notes

- The step rows reuse `<TodoList>` — same glyphs (`☐` / `◐` / `☑`), same dim/strikethrough/bold status emphasis, same duplicate-id guard.
- The counter line is dim. With `current`, the index is clamped into `[0, total - 1]` before display; an empty `steps` array shows `0`.
- `groupLabel` only changes the header; the lanes are ordinary step rows.

---

# Notice

Source: https://docs.usetheo.dev/theokit/tui/notice

A persistent inline banner — a variant marker plus a message, legible under monochrome.

`Notice` is a persistent inline banner (distinct from the transient
[`Toast`](/theokit/tui/toast)): a leading marker carries the variant, and the message and
marker share the variant color.

```
│ Opus 4.8 is now available! · /model to switch                      (info)
!! Both apiKeyHelper and ANTHROPIC_API_KEY set · auth may not work   (warning)
✓ Saved settings to ~/.config                                        (success)
✗ Failed to reach the model endpoint                                 (error)
```

Under a monochrome theme the marker is the color-independent channel (`│` / `!!` / `✓` /
`✗`), so the notice stays legible (degrade-as-data).

## Example

```tsx
import { Notice } from "@theokit/tui";

<Notice variant="warning">
  Both apiKeyHelper and ANTHROPIC_API_KEY set · auth may not work
</Notice>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | `"info" \| "warning" \| "success" \| "error"` | `"info"` | Severity — selects the marker and color. An invalid variant throws a `TypeError` at the boundary. |
| `children` | `ReactNode` | — (required) | The notice message (truncated with an ellipsis at the terminal edge). |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props. |

## Notes

- The variant set is exported as `NOTICE_VARIANTS` (`readonly ["info", "warning", "success", "error"]`) for exhaustive handling in callers.
- `info` follows the theme accent; `warning` is yellow, `error` red, `success` green.
- Group adjacent notices in a `<Stack gap={0}>` so they read as one block, spaced from the rest of the surface by the outer stack.

---

# notify

Source: https://docs.usetheo.dev/theokit/tui/notify

Fire a desktop notification via OSC-9 or a terminal bell, gated by capability.

An imperative desktop-notification writer with a conservative capability gate. `notify` emits OSC-9 only where it is known-supported (iTerm2 / ConEmu), a BEL (`\x07`) as the universal fallback, and nothing under a multiplexer (tmux/screen/zellij) or on a non-TTY sink — never writing escape bytes into a pipe. The `out` and `env` arguments are injectable for deterministic tests.

## Example

```tsx
import { notify } from "@theokit/tui";
import { useEffect } from "react";

useEffect(() => {
  notify("build finished");
}, []);
```

## API

### `notify(message, out?, env?): void`

| Param | Type | Default | Description |
|---|---|---|---|
| `message` | `string` | — (required) | Written verbatim into the OSC-9 payload. An embedded BEL/ESC corrupts the sequence — sanitize upstream if untrusted. |
| `out` | `NotifySink` | `process.stdout` | The stdout-like sink. No-op unless `out.isTTY === true`. |
| `env` | `NodeJS.ProcessEnv` | `process.env` | Environment used for protocol detection. |

### `detectNotifyProtocol(env): NotifyProtocol | null`

Pure helper that picks the protocol for an env, or `null` to suppress. Returns `null` under a multiplexer, `"osc9"` on iTerm2/ConEmu, `"bel"` otherwise.

### Types

- `NotifyProtocol` — `"osc9" | "bel"`.
- `NotifySink` — `{ isTTY?: boolean; write(data: string): void }` (a stdout-like sink).

## Notes

- A multiplexer wins first: under `TMUX` / `STY` / `ZELLIJ`, `notify` suppresses entirely (a raw OSC-9 would leak visible bytes through the multiplexer).
- OSC-9 fires only on iTerm2 (`TERM_PROGRAM === "iTerm.app"` or `ITERM_SESSION_ID`) or ConEmu (`ConEmuPID`); every other TTY gets a BEL.
- On a non-TTY sink (`isTTY !== true`) it does nothing — safe to call when stdout is piped.

---

# Overlay

Source: https://docs.usetheo.dev/theokit/tui/overlay

In-band overlay stack with focus capture — OverlayProvider plus the useOverlay hook.

An overlay layer that renders a stack of overlays in-band (part of the live frame — no z-index compositing) above the thread. `OverlayProvider` wraps the app and manages focus capture: opening the first overlay saves and blurs the background focus and disables Tab navigation; closing the last one restores it. The `useOverlay` hook lets any component push and pop overlays and read the current depth. The top overlay owns Esc-dismiss.

## Example

```tsx
import { OverlayProvider, Pager, useOverlay } from "@theokit/tui";

// Wrap the app once (typically at the composition root):
<OverlayProvider>
  <App />
</OverlayProvider>

// Any component below pushes/pops overlays:
function Demo() {
  const { push, pop, depth } = useOverlay();
  return (
    <SelectList
      items={FRUITS}
      onSubmit={() => push(<Pager content={text} onClose={pop} />)}
    />
  );
}
```

## OverlayProvider props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `ReactNode` | — | The app subtree the provider wraps. |

## useOverlay hook

Returns the overlay context value:

| Member | Type | Description |
|---|---|---|
| `push` | `(node: ReactNode) => string` | Push an overlay above the thread; returns its id. |
| `pop` | `() => void` | Dismiss the top overlay. |
| `depth` | `number` | Number of open overlays. |

## Notes

- Focus capture is depth-counted (a ref), so a push -> push -> pop keeps the background inert until depth returns to 0.
- The top overlay owns Esc-dismiss; the priority Esc-blur arbiter is gated off while focus is disabled, so Esc reaches the overlay instead of blurring it.
- Documented limitation: only the top overlay is mounted. Pushing a nested overlay unmounts the one below; on pop it re-mounts fresh — which re-captures focus but resets internal component state (a covered SelectList's filter/selection is lost). To preserve a covered overlay's state, lift that state to the caller and pass it back in.

---

# Pager

Source: https://docs.usetheo.dev/theokit/tui/pager

Full-screen scrollable viewport over pre-wrapped content with a less/vim keymap.

A full-screen scrollable viewport over pre-wrapped `content`. It reads the terminal height (reserving one row for the status line), scrolls via a pure model, and binds the canonical less/vim keymap. It is meant to be pushed as an overlay — the overlay owns Esc-dismiss; the Pager owns `q`.

## Example

```tsx
import { Pager, useOverlay } from "@theokit/tui";

const LONG_TEXT = Array.from({ length: 60 }, (_, i) => `line ${i + 1}`).join("\n");

function Demo() {
  const { push, pop } = useOverlay();
  return (
    <SelectList
      items={FRUITS}
      onSubmit={() => push(<Pager content={LONG_TEXT} onClose={pop} />)}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `content` | `string` | — | Pre-wrapped content (the app wraps; the Pager does not). |
| `onClose` | `() => void` | — | Called on `q` (the overlay owns Esc). |
| `autoFocus` | `boolean` | `true` | Grab focus on mount. |

## Notes

- Keymap: `↑`/`k` line up, `↓`/`j` line down, `b` page up, `f`/space page down, `C-u`/`C-d` half-page, `g`/`G` top/bottom, `q` close.
- Viewport height is `max(1, rows - 1)` — one row is reserved for the status line.
- On resize (or content change) the model re-clamps a now-out-of-range offset.
- The status line (`line a-b of n · p% · q to close`) is clipped to one row so it never pushes content off the top.
- Input is only active while focused (`isActive: isFocused`).

---

# PermissionPrompt

Source: https://docs.usetheo.dev/theokit/tui/permission-prompt

The Claude Code tool-approval card — a framed request with a vertical numbered Yes/No choice.

`PermissionPrompt` renders the Claude Code tool-approval card: a top-ruled frame around a
tool-type header, the command + optional description, an optional permission-rule note, the
question, and a **vertical numbered** choice list.

```
────────────────────────────────────────────────
 Bash command

   cd .../sdk/javascript && npm install 2>&1 | tail -8
   Install SDK dev deps

 Permission rule Bash(npm *) requires confirmation for this command.
 /permissions to update rules

 Do you want to proceed?
 ❯ 1. Yes
   2. No
```

Enter commits the active choice; Esc is the safe default (the **last** choice — reject). It
composes [`ChoiceRow`](/theokit/tui/choice-row) in its vertical numbered mode, so the keyboard
model (↑/↓ or a digit to move, Enter to commit) comes for free. Callback-only: the decision
leaves via one `onDecision`.

## Example

```tsx
import { PermissionPrompt } from "@theokit/tui";

<PermissionPrompt
  toolType="Bash command"
  command="npm install 2>&1 | tail -8"
  description="Install SDK dev deps"
  ruleNote="Permission rule Bash(npm *) requires confirmation for this command."
  hint="/permissions to update rules"
  onDecision={(decision) => run(decision)}
/>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `toolType` | `string` | — (required) | The tool-type header, e.g. `Bash command`. Non-empty — an empty string throws a `TypeError` at the boundary. |
| `command` | `ReactNode` | — (required) | The command / action being approved (rendered indented under the header). |
| `description` | `string` | — | An optional one-line description under the command. |
| `ruleNote` | `string` | — | An optional permission-rule note, e.g. `Permission rule Bash(npm *) …`. |
| `hint` | `string` | — | An optional secondary hint, e.g. `/permissions to update rules`. |
| `question` | `string` | `Do you want to proceed?` | The question line above the choices. |
| `choices` | `readonly ApprovalChoice[]` | `[{yes}, {no}]` | The vertical numbered choices (`DEFAULT_PERMISSION_CHOICES`). Esc yields the **last** one. |
| `onDecision` | `(decision: string) => void` | — (required) | Called with the chosen value; Esc yields the last choice's value. |
| `autoFocus` | `boolean` | `true` | Take focus on mount. Set `false` for a non-interactive render so the choices do not grab stdin. |

## Notes

- The default choices are exported as `DEFAULT_PERMISSION_CHOICES` (`[{ value: "yes", label: "Yes" }, { value: "no", label: "No" }]`). Reject is deliberately **last** so Esc maps to the safe default.
- The frame is a single top rule (accent color; the `─` glyph carries it under a monochrome theme). The command is indented two columns under the header to match the Claude Code cadence.
- Interactive input requires a raw-mode TTY. Under pure Ink's `render()`, mount [`InkInputProvider`](/theokit/tui/ink-input-provider) once, high in the tree, so the vertical choice list responds to keys.
- For a lighter inline approval (a horizontal once/always/reject bar with an app-composed preview), use [`ApprovalPrompt`](/theokit/tui/approval-prompt) instead.

---

# PlanApproval

Source: https://docs.usetheo.dev/theokit/tui/plan-approval

The plan-mode idiom — a streaming-safe markdown plan body plus an approve/revise choice bar with a feedback branch.

The Claude Code plan-mode idiom: a proposed-plan markdown body (streaming partials are safe) followed by a choice bar of approve/revise. Choosing revise reveals a feedback text input; Enter emits the feedback (empty allowed). Esc on the choice bar is a safe default — revise, never auto-approve. The decision leaves via one `onDecision` callback.

## Example

```tsx
import { PlanApproval, type PlanDecision } from "@theokit/tui";

const PLAN = "# Plan\n\n1. Bump retries to 5\n2. Add a regression test\n";

<PlanApproval
  plan={PLAN}
  onDecision={(d: PlanDecision) => record(`plan: ${JSON.stringify(d)}`)}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `plan` | `string` | — (required) | The proposed plan, as markdown (streaming partials are safe). |
| `onDecision` | `(decision: PlanDecision) => void` | — (required) | Called with the decision. `PlanDecision` is `{ kind: "approve" }` or `{ kind: "revise"; feedback?: string }`. |
| `autoFocus` | `boolean` | `true` | Take focus on mount. Set `false` for a non-interactive render so the choice bar does not grab stdin. |

## Notes

- Callback-only: the component holds no app state beyond the transient revise branch. The decision leaves via `onDecision`.
- Choices are fixed to Approve / Revise. Approve emits `{ kind: "approve" }`; Revise reveals a feedback input that emits `{ kind: "revise", feedback }` on Enter (empty feedback allowed).
- Esc on the choice bar maps to revise, never approve — it never auto-approves. Esc in the feedback input returns to the choice bar.
- The plan body renders through the streaming-safe markdown renderer, so partial markdown while a plan streams in is safe to pass.
- Requires a raw-mode TTY for interactive input (mount under `InputContext` + `FocusProvider`).

---

# ProgressActivity

Source: https://docs.usetheo.dev/theokit/tui/progress-activity

The Claude Code compaction surface — a sparkle header over a determinate progress bar.

`ProgressActivity` renders a determinate task with the Claude Code "compaction" look — a
sparkle header (label + optional elapsed and directional token count) over a
[`ProgressBar`](/theokit/tui/progress-bar):

```
✳ Compacting conversation… (7m 3s · ↑ 24.6k tokens)
  ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 10%
```

It is the **determinate** counterpart to [`AgentStreaming`](/theokit/tui/agent-streaming)
(the *indeterminate* stream with an interrupt hint): use `ProgressActivity` when you have a
percentage, `AgentStreaming` when you don't. Display-only — the app drives `percent`,
`elapsedSeconds`, and `tokens`.

## Example

```tsx
import { ProgressActivity } from "@theokit/tui";

<ProgressActivity
  label="Compacting conversation…"
  percent={10}
  elapsedSeconds={423}
  tokens={24_600}
  tokenDirection="up"
/>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `string` | — (required) | The task label. Single line — newlines are sanitized to spaces, truncated with an ellipsis. |
| `percent` | `number` | — (required) | Progress in `[0,100]`, forwarded to the bar. |
| `elapsedSeconds` | `number` | — | Elapsed seconds → `7m 3s` in the dim meta suffix. Finite, `>= 0`. |
| `tokens` | `number` | — | Token count → `24.6k tokens` in the meta suffix. Finite, `>= 0` (throws otherwise). |
| `tokenDirection` | `"up" \| "down"` | — | Prefixes the token count with `↑` (context growing) or `↓` (shrinking). Absent → the bare count. |
| `barWidth` | `number` | `40` | Bar width in cells. |
| `fullChar` / `emptyChar` | `string` | `█` / `░` | Bar glyphs, forwarded to `ProgressBar`. |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props. |

## Notes

- The sparkle glyph (`✳ ✷ ✶ ✵`) animates while motion is enabled; under reduced-motion, non-TTY, or monochrome terminals it renders the static `✳` and schedules no timers.
- The meta suffix ` ({elapsed} · {arrow}{tokens} tokens)` includes only the segments you supply — both absent renders no suffix at all.
- The bar is indented two columns under the header, aligning with the sparkle gutter.

---

# ProgressBar

Source: https://docs.usetheo.dev/theokit/tui/progress-bar

Determinate progress-bar primitive — a filled run, an empty run, and an optional percentage.

`ProgressBar` is a determinate progress bar: a filled run + an empty run + an optional `N%`
label (`█████░░░░░ 50%`). The fill segment is the theme accent; the empty segment is dim.
`percent` clamps to `[0,100]` — an out-of-range value degrades rather than throws; only a
non-number is a boundary error. It is built on the same shared fill-bar as
[`ContextWindowBar`](/theokit/tui/context-window-bar) and
[`TokenUsageChart`](/theokit/tui/token-usage-chart), so bar and label agree by construction.

## Example

```tsx
import { ProgressBar } from "@theokit/tui";

<ProgressBar percent={50} width={24} />;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `percent` | `number` | — (required) | Progress in `[0,100]`. Out-of-range values clamp; a non-number throws a `TypeError` at the boundary. |
| `width` | `number` | `24` | Bar width in cells. |
| `showPercent` | `boolean` | `true` | Append ` {N}%` (rounded) after the bar. |
| `fullChar` | `string` | `█` | Filled-cell glyph. |
| `emptyChar` | `string` | `░` | Empty-cell glyph. |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props. |

## Notes

- Under a monochrome theme the fill drops its accent color; the filled/empty glyph contrast carries the progress (degrade-as-data).
- For the two-line Claude Code "compaction" surface (a sparkle header over the bar), use [`ProgressActivity`](/theokit/tui/progress-activity), which composes this primitive.
- Display-only: the app owns `percent`. The bar holds no timer and no animation.

---

# QuestionPrompt

Source: https://docs.usetheo.dev/theokit/tui/question-prompt

A per-question header plus question text plus a composed SelectList (single or multi), with an optional free-text branch.

A per-question header, the question text, and a composed `SelectList` (single or multi-select). When `allowFreeText` is set, a synthetic "Other…" option is injected; picking it reveals a mini text input (a `FreeTextInput`, not the full chat composer). The answer leaves via one `onAnswer({ values, text })` callback, and an empty submit is a no-op.

## Example

```tsx
import { QuestionPrompt, type QuestionAnswer } from "@theokit/tui";

<QuestionPrompt
  header="Follow-up"
  question="Which environments should this ship to?"
  options={[
    { value: "dev", label: "dev" },
    { value: "staging", label: "staging" },
    { value: "prod", label: "prod" },
  ]}
  multi
  allowFreeText
  onAnswer={(a: QuestionAnswer) => record(`question: ${JSON.stringify(a)}`)}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `header` | `string` | — (required) | The per-question header (bold, accent). |
| `question` | `string` | — (required) | The question text. |
| `options` | `readonly SelectListItem[]` | — (required) | The selectable options. `SelectListItem` is `{ value: string; label: string }`. |
| `multi` | `boolean` | `false` | Multi-select (space toggles); default single. |
| `allowFreeText` | `boolean` | `false` | Inject an "Other…" option that reveals a free-text input. |
| `onAnswer` | `(answer: QuestionAnswer) => void` | — (required) | Called with `{ values: string[]; text?: string }`. |
| `autoFocus` | `boolean` | `true` | Take focus on mount. Set `false` for a non-interactive render so the list does not grab stdin. |

## Notes

- Callback-only: the component holds no app state beyond the transient free-text branch. The answer leaves via `onAnswer`.
- The injected free-text option uses the exported sentinel `OTHER_OPTION_VALUE` (`"__theo_other__"`); it is stripped from `values` — picking it instead reveals the text input and returns the typed text in `answer.text`.
- An empty submit (no selection) is a no-op — `onAnswer` is not called.
- Esc in the revealed free-text input returns to the options list.
- Requires a raw-mode TTY for interactive input (mount under `InputContext` + `FocusProvider`).

---

# Robustness

Source: https://docs.usetheo.dev/theokit/tui/robustness

NO_COLOR, non-TTY pipes, optional peers, and graceful degrade.

`@theokit/tui` is built to render correctly across the range of real terminals an
agent CLI runs in — truecolor and 16-color, interactive and piped, with or without
optional dependencies.

## NO_COLOR and monochrome

Select the `no-color` theme (see [Theming](/theokit/tui/theming)). Colors become
empty strings; Ink renders unstyled text. Glyphs are preserved, so status,
diff signs, and box borders stay legible without color.

## Non-TTY / piped output

When stdout is not a TTY (piped to a file, a pager, or `| cat`), components render
a **static, readable frame** and never emit cursor-movement or erase escapes that
would corrupt a log. Animated surfaces (the `WelcomeBanner` reveal, spinners)
degrade to their final static state.

Interactive components that read raw stdin — `ChatComposer`, `SelectList`,
`Pager`, and the agent-decision prompts — require a raw-mode-capable TTY. Gate
their mount on `process.stdin.isTTY`:

```tsx
{process.stdin.isTTY && <ChatComposer onSubmit={send} />}
```

## Optional peers

Two peers are optional and declared as such — a consumer who does not use the
feature pulls zero extra weight, and the feature degrades cleanly when the peer is
absent:

| Peer | Used by | Absent behavior |
|---|---|---|
| `lowlight` | `CodeBlock` syntax highlighting | code renders unhighlighted (plain) |
| `figlet` | `renderFigletArt` (Banner text-to-art) | returns `null`; caller falls back to a ready `art` string or the bold name |

```bash
# only if you want highlighted code and generated banner art
npm install lowlight figlet
```

`renderFigletArt` never throws: a missing peer or an unknown font both resolve to
`null`, so a `Banner` always renders something.

## Width and resize

Components measure display width with `string-width` (East-Asian-width and
grapheme aware), so CJK and emoji do not overflow. Tables and truncation adapt to
the terminal width; wide ASCII art is rendered verbatim (the consumer chooses a
size that fits, or lets the `Banner` degrade to the bold name).

The package's test suite exercises the `NO_COLOR` and non-TTY paths as first-class
scenarios (snapshot both modes), and the optional-peer degrade is proven with the
peer uninstalled — the same environment your CI runs in by default.

---

# SelectList

Source: https://docs.usetheo.dev/theokit/tui/select-list

Windowed list with prefix/fuzzy filter and single or multi-select.

An interactive windowed list over a pure model: type to filter (prefix or fuzzy), navigate with the arrow keys, and commit on Enter. Supports single-select or multi-select (space toggles, Enter commits the set). Renders a `❯` active marker, `▲`/`▼` overflow arrows, a counter, and a `◉`/`◯` checkbox column for multi-select. Under a monochrome theme the marker glyph survives when color is stripped.

## Example

```tsx
import { SelectList, type SelectListItem } from "@theokit/tui";

const FRUITS: SelectListItem[] = [
  { value: "apple", label: "apple", description: "open a pager" },
  { value: "banana", label: "banana", description: "open a pager" },
  { value: "cherry", label: "cherry", description: "open a pager" },
];

<SelectList
  items={FRUITS}
  onSubmit={(values) => {
    console.log("chosen:", values[0]);
  }}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `readonly SelectListItem[]` | — | The list items. |
| `onSubmit` | `(values: string[]) => void` | — | Called with the chosen values on Enter (always an array; single-select yields one). |
| `multi` | `boolean` | `false` | Multi-select: space toggles, Enter commits the set. |
| `fuzzy` | `boolean` | `false` | Fuzzy rank vs case-insensitive prefix filtering. |
| `window` | `number` | `5` | Number of visible rows. |
| `autoFocus` | `boolean` | `true` | Grab focus on mount. |

`SelectListItem` is `{ value: string; label: string; description?: string }` — `value` is the stable identity (multi-select is keyed by it), `label` is the displayed and matched text.

## Notes

- Uses the library's own `useInput` and `useFocus` hooks, not Ink's directly.
- Keys: Up/Down navigate (wrapping), Enter submits, Space toggles (multi-select only), Backspace/Delete edit the filter, printable characters extend the filter.
- Editing the filter resets the selection index to 0.
- The counter reads `k selected` in multi-select, or `(i/n)` / `(0/0)` in single-select.
- Input is only active while focused (`isActive: isFocused`).

---

# Stack

Source: https://docs.usetheo.dev/theokit/tui/stack

The vertical-rhythm primitive — one gap between every child, spacing owned by the container.

`Stack` is the vertical-rhythm primitive: wrap a column of blocks (banner, notices,
timeline, the working indicator, the footer) and every child is separated by the same
`gap` — regardless of type. Spacing between transcript blocks is a **container** concern,
not a per-component one: a component that carried its own default top margin would double
up inside a container that already spaces (`ChatThread` / `AgentTimeline`) and break the
no-op margin invariant. It is the ergonomic name for Ink's `<Box flexDirection="column"
gap>` (the SwiftUI `VStack(spacing:)` / Braid `<Stack>` idiom); the `gap` is applied only
*between* children, never as leading or trailing padding.

## Example

```tsx
import { Stack, WelcomeBanner, Notice, AgentTimeline } from "@theokit/tui";

<Stack>
  <WelcomeBanner name="Theo Code" version="0.39.0" />
  <Stack gap={0}>
    <Notice variant="info">Opus 4.8 is now available! · /model to switch</Notice>
    <Notice variant="warning">apiKeyHelper and ANTHROPIC_API_KEY both set</Notice>
  </Stack>
  <AgentTimeline events={events} />
</Stack>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `gap` | `number` | `1` | Blank rows between adjacent children (the Claude Code cadence). `0` packs children tight; only applied *between* children. |
| `children` | `ReactNode` | — | The column of blocks to space. |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props (`margin`, `marginX`, `marginTop`, …) live *outside* the stack; `gap` never adds leading/trailing padding. |

## Notes

- Nest `Stack`s to mix rhythms: an outer `<Stack>` for the page cadence, an inner `<Stack gap={0}>` for a tight group (e.g. two adjacent notices) that reads as one block.
- Because spacing lives in the container, individual components stay margin-free by default — passing no margin is byte-identical to rendering them bare (the no-op invariant).
- Prefer `Stack` over per-component `marginTop` for standardized spacing across a surface.

---

# StatusFooter

Source: https://docs.usetheo.dev/theokit/tui/status-footer

The two-line Claude Code footer — a justified status row above the permission-mode / agents row.

`StatusFooter` composes the two-line Claude Code footer: a justified status row above the
mode/agents row.

```
main · plan                          42% context · fix the bug   (status row, justified)
⏵⏵ auto-accept edits on (shift+tab to cycle) · ← for agents      (mode row)
```

Both rows are display-only slots — the app owns the content and the mode state. The top row
space-betweens `left` and `right`; the bottom row shows the permission mode (via
[`ModeIndicator`](/theokit/tui/mode-indicator)) followed by the agents hint, or the
shortcuts hint when there is no active mode.

## Example

```tsx
import { StatusFooter } from "@theokit/tui";
import { Text } from "ink";

<StatusFooter
  left={<Text>main · plan mode</Text>}
  right={<Text>42% context · fix the bug</Text>}
  mode="auto-accept"
/>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `left` | `ReactNode` | — | Top-left slot — e.g. the branch / plan (`main · plan`). |
| `right` | `ReactNode` | — | Top-right slot — e.g. `42% context · fix the bug`. Space-betweened away from `left`. |
| `mode` | `"default" \| "auto-accept" \| "plan"` | `"default"` | Permission mode for the bottom row. `default` shows no mode — the `hint` renders instead. |
| `hint` | `string` | `? for shortcuts · ← for agents` | Bottom hint shown when no mode is active. |
| `margin*` | — | — | The universal [layout-margin](/theokit/tui/layout-margin) props. |

## Notes

- The footer sets `width: 100%` so the top row can space-between to the terminal edges. Give it a full-width container.
- When `mode` is non-`default`, the bottom row is `⏵⏵ auto-accept edits on (shift+tab to cycle) · ← for agents`; when `default`, it is the `hint` string (`? for shortcuts · ← for agents` by default).
- Pairs naturally at the bottom of a [`Stack`](/theokit/tui/stack) that owns the whole session surface.

---

# Terminal OSC helpers

Source: https://docs.usetheo.dev/theokit/tui/terminal-osc

Set the terminal title and emit OSC-8 hyperlinks, no-op off-TTY.

Terminal-title (OSC 0) and hyperlink (OSC 8) helpers. Each is pure with an injectable `env`/`out`, and degrades to a no-op or plain text off-TTY or under a multiplexer — never writing a raw escape into a pipe or a multiplexer stream. `title` and `url` are written verbatim; an embedded BEL/ESC corrupts the sequence, so sanitize upstream if untrusted.

## Example

```tsx
import { setTerminalTitle, osc8Link, supportsHyperlinks } from "@theokit/tui";
import { Text } from "ink";
import { useEffect } from "react";

useEffect(() => {
  setTerminalTitle("theokit — parity polish");
}, []);

<Text>{osc8Link("docs", "https://github.com/usetheodev/theokit-tui")}</Text>;
```

## API

### `setTerminalTitle(title, out?): void`

| Param | Type | Default | Description |
|---|---|---|---|
| `title` | `string` | — (required) | The window/tab title (OSC 0). Written verbatim. |
| `out` | `OscSink` | `process.stdout` | The sink. No-op unless `out.isTTY === true`. |

### `supportsHyperlinks(env?, out?): boolean`

| Param | Type | Default | Description |
|---|---|---|---|
| `env` | `NodeJS.ProcessEnv` | `process.env` | Environment checked for a multiplexer. |
| `out` | `{ isTTY?: boolean }` | `process.stdout` | Sink checked for a TTY. |

Returns `true` only when `out.isTTY === true` and not under a multiplexer.

### `osc8Link(text, url, env?, out?): string`

| Param | Type | Default | Description |
|---|---|---|---|
| `text` | `string` | — (required) | The visible link text. |
| `url` | `string` | — (required) | The link target (written verbatim). |
| `env` | `NodeJS.ProcessEnv` | `process.env` | Environment used for the support check. |
| `out` | `{ isTTY?: boolean }` | `process.stdout` | Sink used for the support check. |

Wraps `text` in an OSC-8 hyperlink when supported; otherwise returns `text` unchanged.

`OscSink` is `{ isTTY?: boolean; write(data: string): void }`.

## Notes

- `setTerminalTitle` does not gate on a multiplexer: tmux/screen forward OSC-0 title sequences to the outer terminal, so gating would break title-passthrough.
- `osc8Link` and `supportsHyperlinks` do gate on a multiplexer, because OSC-8 hyperlinks are not reliably forwarded — hence the asymmetry with the title helper.
- All three are no-ops / plain-text off-TTY, so they are safe to call when stdout is piped.

---

# Theming

Source: https://docs.usetheo.dev/theokit/tui/theming

The token system, built-in themes, and terminal-adaptive color.

Every `@theokit/tui` component reads its colors and glyphs from theme tokens
supplied by `TheoTUIProvider`. Theming changes color only — never text or layout —
so a themed tree and an unthemed tree are byte-identical modulo color.

## Built-in themes

Three themes ship with the package:

| Theme | Use |
|---|---|
| `dark` | The default. Truecolor / 16-color terminals. |
| `light` | Light terminal backgrounds. |
| `no-color` | Colors stripped; glyphs carry all meaning. The `NO_COLOR` degrade. |

```tsx
import { TheoTUIProvider, themes } from '@theokit/tui';

<TheoTUIProvider theme={themes.light}>
  {/* ... */}
</TheoTUIProvider>;
```

`defaultTheme` is the `dark` object; `themes` is a record of all three.

## Token shape

A theme is a frozen object of tokens. The most-used groups:

| Group | Tokens | Drives |
|---|---|---|
| `accent` | one color | borders, active items, the `Banner` art |
| `role` | `user` / `assistant` / `system` → `{ glyph, prefix }` | chat message prefixes |
| `toolStatus` | `pending` / `running` / `success` / `failed` → `{ glyph, color }` | tool-call status bullets |
| `status` | `error` / `success` / `warning` | Toast variants, error surfaces |
| `code` | keyword / string / number / … | CodeBlock syntax colors |

Read the resolved theme in a component with the `useTheoTheme` hook:

```tsx
import { useTheoTheme } from '@theokit/tui';

function MyRow() {
  const theme = useTheoTheme();
  return <Text color={theme.accent}>accented</Text>;
}
```

## Overrides

Pass a partial theme to override specific tokens; the rest inherit from the base:

```tsx
<TheoTUIProvider theme={{ toolStatus: { failed: { glyph: 'x' } } }}>
  {/* failed tool calls now render an x bullet; everything else unchanged */}
</TheoTUIProvider>
```

## Terminal-adaptive color

- Under `NO_COLOR` (or a non-color terminal), select the `no-color` theme: colors
  become empty strings and Ink renders unstyled, but glyphs (the color-independent
  channel) still carry status.
- Because tokens are data, a monochrome theme is a legitimate degrade path, not a
  special case — the same components render, just without color.

The status bullet on tool cards (`toolStatus`) is a filled circle colored by
status. Under `no-color` the color is stripped, so status there is conveyed by the
running spinner + context; the glyph itself is constant. See the `ToolCallCard`
reference for the full behavior.

---

# TheoTUIProvider

Source: https://docs.usetheo.dev/theokit/tui/theotui-provider

Root provider that supplies theme tokens (colors and glyphs) to every component

`TheoTUIProvider` is the root context provider for `@theokit/tui`. It resolves a
theme — a built-in name, a partial override, or a `{ base, override }` pair — into
the token set that every component reads via `useTheoTheme`. Mount it once near the
top of your Ink tree; components fall back to the default `dark` theme when no
provider is present.

## Example

```tsx
import { Box, render } from "ink";
import { ChatMessage, TheoTUIProvider } from "@theokit/tui";

render(
  <TheoTUIProvider>
    <Box flexDirection="column">
      <ChatMessage role="user">What is @theokit/tui?</ChatMessage>
      <ChatMessage role="assistant">Ink primitives for AI-agent surfaces.</ChatMessage>
    </Box>
  </TheoTUIProvider>,
);
```

Pick a built-in theme, or apply a partial override on top of a base:

```tsx
<TheoTUIProvider theme="light">{children}</TheoTUIProvider>

<TheoTUIProvider theme={{ base: "dark", override: { accent: "green" } }}>
  {children}
</TheoTUIProvider>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `theme` | `TheoThemeProp \| undefined` | `undefined` (resolves to `dark`) | Built-in name (`"dark" \| "light" \| "no-color"`), a partial `TheoThemeOverride`, or a `{ base?, override? }` pair. |
| `children` | `ReactNode` | — | The subtree that receives the resolved theme via context. |

`TheoThemeProp` is the union:

```ts
type TheoThemeProp =
  | TheoThemeOverride
  | TheoBuiltinThemeName                                    // "dark" | "light" | "no-color"
  | { base?: TheoBuiltinThemeName; override?: TheoThemeOverride };
```

## Hook: useTheoTheme

```ts
function useTheoTheme(): TheoTheme;
```

Returns the active resolved `TheoTheme` from context. It never returns `undefined` —
outside a provider it falls back to `defaultTheme` (`dark`). Use it to read role
glyphs/colors, status colors, the neutral `accent`, code-highlight buckets, and
tool-status glyphs.

```tsx
import { Text } from "ink";
import { useTheoTheme } from "@theokit/tui";

function Hint() {
  const theme = useTheoTheme();
  return <Text color={theme.accent}>ready</Text>;
}
```

## Exports: themes / defaultTheme

- `defaultTheme: TheoTheme` — the frozen `dark` theme; the fallback when no provider
  is mounted and the base of a bare `TheoThemeOverride`.
- `themes: Readonly<Record<TheoBuiltinThemeName, TheoTheme>>` — the three frozen
  built-in singletons keyed `dark`, `light`, `no-color`. Referentially stable, so a
  built-in name passed to the provider never re-renders consumers.

## Notes

- Degrade-as-data: the `no-color` theme empties every color slot so Ink renders
  unstyled, while glyphs (the color-independent channel) are preserved. Components
  branch on the exported `isMonochrome(theme)` predicate — never on the theme
  `name` — so a customized no-color base (whose `name` reads `"custom"`) still
  degrades correctly.
- The `NO_COLOR` environment variable (when non-empty) forces the `no-color` theme
  and wins over any `theme` prop with full-swap semantics. `NO_COLOR` is read only
  here, at mount/prop-change — provider-less usage gets no `NO_COLOR` support.
- Applying a non-empty override sets the resolved theme `name` to `"custom"`; an
  empty override object keeps the base's identity.
- Referential stability: the context value is memoized on `[theme]`. Pass a
  hoisted override object or a built-in name — an inline object literal re-merges
  and re-renders every consumer on each parent render.
- Nesting resets: a nested provider resolves against its own base + override; it
  never composes with an ancestor provider.
- Throws `TypeError` on an invalid `theme` (unknown built-in name, non-object
  override, array, or an unknown key in the `{ base, override }` form). Validation
  runs before hooks, so direct invocation surfaces the typed error, not an engine
  crash.

---

# Toast

Source: https://docs.usetheo.dev/theokit/tui/toast

A transient message on a bounded one-shot timer, with severity variants.

A transient message on a bounded, self-clearing timer. `onDismiss` fires when the timer elapses (the app removes the toast) and is read through a ref, so an inline callback does not reset the countdown each render — only a `durationMs` change re-schedules. The library ships a single self-dismissing toast; the app owns queueing and stacking.

## Example

```tsx
import { Toast } from "@theokit/tui";

<Toast
  message="build finished"
  durationMs={5000}
  onDismiss={() => {}}
  variant="success"
/>;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `message` | `string` | — (required) | The message text rendered inside the bordered box. |
| `durationMs` | `number` | `5000` | Auto-dismiss delay in ms. Changing it re-schedules the timer (clearing the prior one). |
| `onDismiss` | `() => void` | — (required) | Called when the timer fires. Read through a ref, so an inline callback never resets the countdown. |
| `variant` | `ToastVariant` | `"info"` | Severity variant — one of `"info" \| "success" \| "error"`. |

`ToastVariant` is the union `"info" | "success" | "error"`.

## Notes

- `success` and `error` color the border and prefix a `●` status bullet; `info` keeps the accent border with no bullet.
- Under a monochrome theme the border degrades to `single` with no accent color and no colored bullet.
- The timer is torn down on unmount, so removing the toast cancels the pending dismissal.

---

# TodoList

Source: https://docs.usetheo.dev/theokit/tui/todo-list

A live checklist keyed by stable id, with per-item status glyphs.

A fully-live checklist: each item carries a `status` (`pending` / `active` / `done`) rendered with a distinct status glyph (`☐` / `◐` / `☑`). An item updates in place when the caller passes a new object with the same `id`, and duplicate ids throw at the boundary. Unlike ChatThread/AgentTimeline it never graduates to `<Static>` — a done item may revert to active.

## Example

```tsx
import { TodoList, type TodoItem } from "@theokit/tui";

const TODOS: TodoItem[] = [
  { id: "1", label: "read the spec", status: "done" },
  { id: "2", label: "write the tests", status: "active" },
  { id: "3", label: "make them pass", status: "pending" },
];

<TodoList items={TODOS} />;
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` | `readonly TodoItem[]` | — (required) | The checklist rows. Each `TodoItem` is `{ id: string; label: string; status: TodoStatus }`. Duplicate `id`s throw a `TypeError` at the boundary. |

`TodoStatus` is the union `"pending" | "active" | "done"`.

## Notes

- Status glyphs carry the meaning so the surface survives a monochrome theme: `☐` pending, `◐` active, `☑` done.
- Row emphasis by status (Claude Code parity): a `done` item renders dim + strikethrough, an `active` item renders bold, `pending` is plain. The glyph still carries the meaning under monochrome — these attributes only reinforce it.
- The `todoRowStyle(status)` helper is exported (returns `{ dimColor?, strikethrough?, bold? }`) for tests and reuse.
- Rows are memoized by object identity + `key={id}`; pass a new object with the same `id` to update a row in place.
- Duplicate `id`s corrupt row identity and fail fast with `TypeError: TodoList: duplicate item id "..."`.

---

# TokenUsageChart

Source: https://docs.usetheo.dev/theokit/tui/token-usage-chart

Per-category token comparison bars scaled to the largest present category.

Per-category comparison bars for token usage. Each bar scales to the largest present category — a relative "where did the tokens go" view, not a limit gauge (for a fill-against-limit gauge use `ContextWindowBar`). Only present keys render: an absent category is skipped, while a present `0` renders an empty bar plus `0`.

## Example

```tsx
import { TokenUsageChart } from "@theokit/tui";

<TokenUsageChart
  usage={{ input: 62_100, output: 14_800, cached: 2_400 }}
  width={46}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `usage` | `Partial<Record<TokenCategory, number>>` | — (required) | Token counts per category. Only present keys render (absent ≠ zero). Each present value must be finite and `>= 0`. All absent → renders nothing. |
| `width` | `number` | `40` | Total column budget per row (label + bar + value). Integer, `>= 0`. |

`TokenCategory` is the union `"input" | "output" | "cached" | "reasoning"`. Rows always render in that fixed order.

## Notes

- A present value that is not finite or is negative throws a `TypeError` at the boundary; a non-integer/negative `width` also throws.
- With no present categories the component renders `null`.
- Bars scale to the largest present value; when all present values are `0`, every ratio is `0` (a valid all-zero chart does not throw).
- When the computed bar cells fall below the minimum, each row renders label + value only, with no bar.
- Label and value columns are padded to align across rows; filled bar segments use the accent color, empty segments are dim.

---

# ToolCallCard

Source: https://docs.usetheo.dev/theokit/tui/tool-call-card

A ToolCall header plus an indented result/children body rendered under a corner connector.

Tool-call card: a `ToolCall` header followed by a body indented under the status indicator. The body can be a typed `result` (diff, output, or preview), arbitrary `children`, or both. Without a body it renders exactly the bare row.

## Example

```tsx
import { ToolCallCard, ToolResult } from "@theokit/tui";

<ToolCallCard name="Bash" status="success" summary="pnpm install">
  <ToolResult lines={longOutput.split("\n")} maxLines={6} />
</ToolCallCard>

<ToolCallCard
  name="Edit"
  status="success"
  summary="retry.ts"
  result={{
    kind: "diff",
    patch: [
      "--- a/retry.ts",
      "+++ b/retry.ts",
      "@@ -1,2 +1,2 @@",
      " const attempts = 3;",
      "-const backoff = 0;",
      "+const backoff = attempt * 250;",
    ].join("\n"),
  }}
/>
```

## Props

`ToolCallCard` extends [`ToolCall`](./tool-call) props (`name`, `status`, `summary`) and adds:

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — (required) | Tool name (inherited from `ToolCall`). |
| `status` | `ToolCallStatus` | — (required) | Lifecycle state: `"pending" \| "running" \| "success" \| "failed"` (inherited from `ToolCall`). |
| `summary` | `string` | `undefined` | Dim `(args)` suffix (inherited from `ToolCall`). |
| `result` | `ToolCardResult` | `undefined` | Per-kind result body. `{kind:"diff"}` renders the patch via `DiffViewer`, `{kind:"output"}` a shell envelope via `ToolResult`, `{kind:"preview"}` a capped `CodeBlock` (with `language`) or plain lines. When both `result` and `children` are present, the result body comes first. |
| `children` | `ReactNode` | `undefined` | Card body, indented under the name. Plain string/number children are auto-wrapped in `<Text>`; an empty string collapses to the bare row. |

### ToolCardResult kinds

`result` is an explicit discriminated union (no shape-sniffing dispatch):

| Kind | Fields | Renders via | Notes |
|---|---|---|---|
| `"diff"` | `patch: string`, `maxLines?: number`, `contextLines?: number` | `DiffViewer` | `patch` is unified-diff text. A malformed patch throws a typed error that propagates through the card (fail-fast). `DiffViewer` emits its own per-file header row. |
| `"output"` | `shell: ShellEnvelope`, `maxLines?: number`, `expanded?: boolean` | `ToolResult` | `shell` is the `{ stdout, stderr, exitCode? }` envelope. |
| `"preview"` | `text: string`, `language?: string`, `maxLines?: number` | `CodeBlock` (with `language`) or `ToolResult` (without) | Cap semantics differ by branch: with `language` the head lines survive with a `(+N more lines)` trailer; without it the tail survives with a `+N lines hidden` indicator. |

## Notes

- M27 corner-connector result tree: the result/children body renders under a `⎿` (U+23BF) corner connector — the Claude Code tool-tree idiom. The connector shows once at the top-left and the body flows to its right, so multi-line continuation aligns under the body, not the connector.
- The card validates only `result.kind` at the boundary (an explicit check reachable from JS callers) — payload contracts stay with the underlying primitives. A `diff` patch is eagerly parsed at the boundary so a malformed patch throws a typed `TypeError` before any hook runs.
- Optional result fields are omitted (not passed as explicit `undefined`) to the underlying components, honoring `exactOptionalPropertyTypes`.
- With no renderable body (undefined/null/`""`/boolean children and no `result`), only the `ToolCall` row renders — no connector.

---

# ToolCall

Source: https://docs.usetheo.dev/theokit/tui/tool-call

Inline tool-call row with a status indicator, bold name, and dim argument suffix.

Inline tool-call row: a 3-cell status indicator followed by the tool name (bold) and an optional dim `(args)` suffix. Status arrives via props, so lifecycle transitions are plain rerenders. The header is always one line — newlines are sanitized to spaces and the row truncates at any terminal width.

## Example

```tsx
import { ToolCall } from "@theokit/tui";

<ToolCall name="Read" status="pending" summary="registry.json" />
<ToolCall name="build" status="success" summary="2.1s" />
<ToolCall name="Grep" status="running" summary="retry" />
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — (required) | Tool name rendered bold after the indicator. Header is one line by contract — newlines are sanitized to spaces. ANSI/control chars pass through unsanitized (caller responsibility). |
| `status` | `ToolCallStatus` | — (required) | Lifecycle state — selects the glyph/spinner and status color. Union: `"pending" \| "running" \| "success" \| "failed"`. |
| `summary` | `string` | `undefined` | Optional dim one-line summary rendered after the name (newlines sanitized). Rendered as a parenthesized `(args)` suffix glued to the name. |

## Notes

- M27 header shape is `name(args)`: `summary` becomes a parenthesized, dim argument suffix glued to the name (Claude Code header shape). A bare name with no summary never renders empty parens.
- The single monochrome header line survives color loss — the indicator uses glyph + color tokens (`theme.toolStatus`), while `failed` stays bold as a component attribute (attributes are the channel that survives when color is stripped).
- `running` renders an animated `ink-spinner`; each mounted running indicator owns one interval timer, so many concurrent running cards mean many timers.
- The indicator column is a fixed `STATUS_INDICATOR_WIDTH` (3 cells) that aligns card headers.
- An invalid `status` throws a `TypeError` at the boundary before any hook runs (fail-fast for JS consumers).
- The header uses `wrap="truncate-end"` to stay genuinely one line at any terminal width.

---

# ToolResult

Source: https://docs.usetheo.dev/theokit/tui/tool-result

Tool output block with tail-retention line truncation and an optional shell envelope.

Tool output block: renders content with tail-retention truncation and a dim `… +N lines hidden` indicator. Accepts plain string content, pre-split lines, or a shell envelope (labeled stderr, non-zero-only exit badge, `(no output)` placeholder). Content is capped at a hard character budget independent of line truncation.

## Example

```tsx
import { ToolResult } from "@theokit/tui";

<ToolResult lines={longOutput.split("\n")} maxLines={6} />

<ToolResult
  shell={{
    stdout: "573 passed",
    stderr: "1 flaky: retry_backoff_caps",
    exitCode: 1,
  }}
/>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` | `string` | `undefined` | Plain-string content, split on newlines. Exclusive with `lines`/`shell`. |
| `lines` | `string[]` | `undefined` | Pre-split content lines. Exclusive with `children`/`shell`. |
| `shell` | `ShellEnvelope` | `undefined` | Shell envelope. Exclusive with `children`/`lines`. |
| `maxLines` | `number` | `10` | Visible-line budget including the indicator row when line truncation fires. Integer >= 1 — validated even when `expanded`. |
| `expanded` | `boolean` | `false` | Render every line (bypasses line truncation only — never the character cap). |
| `interactive` | `boolean` | `undefined` | When line-capped, make the output interactively expandable (ctrl+o / Space / Enter). The character cap is never bypassed. |

### ShellEnvelope

| Field | Type | Description |
|---|---|---|
| `stdout` | `string` | Standard output. |
| `stderr` | `string` | Standard error. Rendered under a dim `stderr:` label. |
| `exitCode` | `number` (optional) | Exit badge renders only when a number and non-zero, verbatim. |

## Notes

- `MAX_RESULT_CHARS` (20000) is a hard input guard against pathological single payloads — not display truncation. `expanded` does not bypass it, and it renders a `… output capped at 20000 chars` indicator when it fires. For a shell envelope the 20k budget is combined across stdout and stderr (stderr gets whatever stdout leaves over).
- Truncation is tail-retention: it keeps the last `maxLines - 1` lines, reserving one row for the `… +N lines hidden` indicator. `maxLines` must be an integer >= 1, validated at the boundary with a typed `TypeError`.
- Exactly one of `children | lines | shell` must be provided; supplying more than one throws a typed `TypeError` (silent precedence would swallow content).
- The stderr label is pinned outside the visible budget when truncation cuts into the stderr block, so the color-independent stderr marker survives on `NO_COLOR` terminals. The non-zero exit badge (`exited N`) is likewise pinned.
- A shell envelope with no output rows renders a dim `(no output)` placeholder.
- In `interactive` mode the line-cap indicator is replaced by the expand affordance, but the character-cap notice stays visible so data loss remains observable.

---

# useAgentStream

Source: https://docs.usetheo.dev/theokit/tui/use-agent-stream

Fold an agent event stream into AgentTimeline-ready state inside a component.

`useAgentStream` consumes an async-iterable stream of `AgentStreamEvent`s and folds
each event through the pure `agentStreamReducer`, producing state whose `events`
array is exactly `AgentTimeline`'s input. The hook manages the consumption loop:
StrictMode-safe reset on source change, iterator teardown on cleanup, and a
`cancel()` escape hatch.

## Example

```tsx
import { useAgentStream, AgentTimeline, AgentStreaming } from '@theokit/tui';

async function* agentTurn() {
  yield { type: 'thinking-delta', text: 'Planning…' };
  yield { type: 'text-delta', text: 'Hello' };
  yield { type: 'text-delta', text: ' world.' };
}

function AgentView() {
  // Hoist or memoize the factory — its identity is the effect dependency.
  const { events, streaming, status, cancel } = useAgentStream(agentTurn);
  return (
    <>
      <AgentTimeline events={events} />
      {streaming.active && <AgentStreaming thought={streaming.thought} showCancelHint />}
    </>
  );
}
```

## API

```ts
function useAgentStream(source?: AgentStreamSource): UseAgentStreamResult;
```

`AgentStreamSource` is the stream source — an `AsyncIterable<AgentStreamEvent>`, or a
factory returning one:

```ts
type AgentStreamSource =
  | AsyncIterable<AgentStreamEvent>
  | (() => AsyncIterable<AgentStreamEvent>);
```

The return value extends `AgentStreamState` with a `cancel` method:

| Field | Type | Description |
|---|---|---|
| `events` | `AgentEvent[]` | Folded, boundary-safe events — pass directly to `AgentTimeline`. |
| `streaming` | `{ active: boolean; thought?: string }` | Source for `AgentStreaming` props; `thought` is the ungraduated reasoning buffer. |
| `status` | `"idle" \| "streaming" \| "done" \| "error"` | Current stream status. |
| `error` | `Error \| undefined` | Set when the stream folds an error terminal. |
| `seq` | `number` | Monotonic id counter (in-state, for generated event ids). |
| `liveMessageId` | `string \| undefined` | The tail-replace anchor currently open. |
| `cancel` | `() => void` | Stops consumption (`iterator.return`) and folds the terminal `done`. |

## Reducer exports

For folding a stream outside React, `agentStreamReducer(state, event)` and
`initialAgentStreamState` are exported directly. The reducer is pure (no ink/react
import) — testable and reusable without a renderer:

```ts
import { agentStreamReducer, initialAgentStreamState } from '@theokit/tui';

const state = [{ type: 'text-delta', text: 'Hi' }, { type: 'done' }].reduce(
  agentStreamReducer,
  initialAgentStreamState,
);
// state.events is AgentTimeline's input; state.status === 'done'.
```

## Notes

- Hoist or memoize the source factory — the source identity is the effect dependency, so an inline arrow restarts the stream on every render. A new identity deliberately restarts: state resets and refolds from scratch (this is how reconnect-by-refold works).
- Under React StrictMode, pass a factory (not a raw generator instance): the run-1 cleanup closes a raw generator, and the remount would refold it as an instant done.
- `done` and `error` are hook synthetics — no SDK stream emits them. Stream end is generator completion (folded as `done`); a throw during iteration folds as `error`.
- Terminal means terminal: `agentStreamReducer` drops every event after `done`/`error`. Handled event types are `text-delta`, `thinking-delta`, `thinking`, `assistant`, `tool_call`, `error`, and `done`; `system` / `user` / `status` / `task` / unknown types fold to no-op.
- Teardown rejections from `iterator.return()` are swallowed so a producer's failing cleanup cannot become an unhandled rejection that kills the CLI.

---

# WelcomeBanner

Source: https://docs.usetheo.dev/theokit/tui/welcome-banner

Claude Code / gemini-cli-style startup banner as a leaf primitive.

A framed startup banner rendered as a leaf primitive — accent-themed name, an optional dim version, a multi-line tagline, and dim hint lines. Color comes exclusively from the M6 theme tokens (accent border and name, dim meta). It never mounts `<Static>`; suppressing it is the consumer's responsibility.

## Example

```tsx
import { Text } from "ink";
import { TheoTUIProvider, VERSION, WelcomeBanner } from "@theokit/tui";

<TheoTUIProvider>
  <WelcomeBanner
    name="Theo TUI"
    version={VERSION}
    animated
    tagline="AI-agent primitives for the terminal"
    hints={[
      "/help for commands",
      "esc to cancel a running turn",
      "docs: github.com/usetheodev/theokit-tui",
    ]}
  >
    <Text dimColor>cwd: ~/projects/demo</Text>
  </WelcomeBanner>
</TheoTUIProvider>
```

## Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `name` | `string` | — | Product name — single line (embedded newlines throw). Must be non-empty. |
| `version` | `string` | `undefined` | Rendered dim as ` v{version}` on the name line; single line. Empty/whitespace renders as absent. |
| `tagline` | `string` | `undefined` | May contain `\n` — one line per segment; blank lines are dropped. |
| `hints` | `readonly string[]` | `undefined` | One dim line per entry; each entry is single-line (embedded newlines throw). |
| `children` | `ReactNode` | `undefined` | A single free-composition slot inside the box. |
| `animated` | `boolean` | `false` | Opt-in typewriter reveal (12 phases x 80 ms, under 2 s). |

## Notes

- Boundary validation runs first: `name` and each `hints` entry must be non-empty and single-line; `version` must be single-line. Violations throw `TypeError`.
- Width is read at render time and frozen until the next React re-render. Box width is `min(columns, 60)`.
- Below `24` columns it degrades to a single plain `Text` line (name plus version).
- `animated` is a mount-time gate evaluated once: it runs only on an interactive TTY with rows >= 15 and columns >= 44, a non-monochrome theme, and no `THEOKIT_TUI_NO_MOTION` env value. Everywhere else the render is the exact static banner tree (byte-identical by construction).
- During the reveal only the name typewriter shows; version, tagline, hints, and children are withheld until convergence. Theme dim changes mid-reveal do not abort it.
- Under a monochrome theme the border degrades from `round` to `single`.

---

# AgentComposer

Source: https://docs.usetheo.dev/theokit/ui/agent-composer

ChatComposer with slash-command, @file, and #memory triggers — watches the value and shows a mention menu of candidate items

`AgentComposer` wraps `ChatComposer` and watches the value for three trigger
characters: `/` for slash commands, `@` for file references, and `#` for memory
entries. Detection is string-based, so no textarea ref is required — a trigger is
active when the value ends with a trigger character preceded by whitespace or the
start of the string. You provide the candidate items per trigger; on selection
the trailing token is replaced with the chosen value.

<ComponentPreview name="agent-composer" code={`<AgentComposer
  mode="code"
  commands={[
    { id: "1", label: "/clear", description: "Reset session" },
    { id: "2", label: "/checkpoint", description: "Save state" },
    { id: "3", label: "/help", description: "Show help" },
  ]}
  files={[
    { id: "1", label: "src/components/AlignmentGrid.tsx", description: "modified · +85 −12" },
    { id: "2", label: "src/components/PanelGrid.tsx", description: "new" },
  ]}
  memories={[
    { id: "1", label: "#alignment-grid", description: "snap not stiffness" },
    { id: "2", label: "#auth-flow", description: "OAuth device flow" },
  ]}
/>`}>
  <AgentComposer
    mode="code"
    commands={[
      { id: "1", label: "/clear", description: "Reset session" },
      { id: "2", label: "/checkpoint", description: "Save state" },
      { id: "3", label: "/help", description: "Show help" },
    ]}
    files={[
      { id: "1", label: "src/components/AlignmentGrid.tsx", description: "modified · +85 −12" },
      { id: "2", label: "src/components/PanelGrid.tsx", description: "new" },
    ]}
    memories={[
      { id: "1", label: "#alignment-grid", description: "snap not stiffness" },
      { id: "2", label: "#auth-flow", description: "OAuth device flow" },
    ]}
  />

## Props

## Notes

- `commands`, `files`, and `memories` each accept an array of `MentionItem`
  objects (`id`, `label`, optional `description`, optional `icon`) or a function
  `(query) => MentionItem[]` for async or filtered results.
- `resolveInsertText` overrides what gets inserted when an item is picked
  (default is the trigger char plus the label); `emptyLabels` customizes the
  per-trigger empty state.
- Arrow keys, Enter, and Esc drive the mention menu; Esc dismisses it so you can
  keep typing past a trigger character without it reappearing.
- As a `ChatComposer` wrapper, it forwards the composer props — `value`,
  `onValueChange`, `mode`, `onSubmit`, and the rest.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentComposer } from "@theokit/ui/agent-composer";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-composer.json
```

---

# AgentEditor

Source: https://docs.usetheo.dev/theokit/ui/agent-editor

Form for creating or editing an agent persona — name, initials, tone, model, system prompt, allowed tools, linked skills, and active modes

`AgentEditor` is the form for creating or editing an agent persona. It collects a
name, initials, description, identity tone, model, a system-prompt override, a
comma-separated allowed-tools list, linked skills, and the modes the agent is
visible in. It seeds its state once on mount, so to edit a different agent, remount
it with a React `key` at the call site.

<ComponentPreview name="agent-editor" code={`<AgentEditor
  initial={{
    id: "a1",
    name: "Reviewer",
    initials: "RV",
    description: "Reviews code and writes regression tests before any fix.",
    tone: "info",
    model: "sonnet-4-6",
    systemPrompt: "You are the Reviewer. Your job is to spot bugs and write failing tests that demonstrate them before any code change.",
    allowedTools: ["Read", "Grep"],
    skillIds: ["sk1", "sk2"],
  }}
  models={[
    { id: "opus-4-7", label: "Opus 4.7" },
    { id: "sonnet-4-6", label: "Sonnet 4.6" },
    { id: "haiku-4-5", label: "Haiku 4.5" },
  ]}
  skills={[
    { id: "sk1", label: "diff-explainer" },
    { id: "sk2", label: "test-runner" },
    { id: "sk3", label: "security-audit" },
  ]}
/>`}>
  <AgentEditor
    initial={{
      id: "a1",
      name: "Reviewer",
      initials: "RV",
      description: "Reviews code and writes regression tests before any fix.",
      tone: "info",
      model: "sonnet-4-6",
      systemPrompt: "You are the Reviewer. Your job is to spot bugs and write failing tests that demonstrate them before any code change.",
      allowedTools: ["Read", "Grep"],
      skillIds: ["sk1", "sk2"],
    }}
    models={[
      { id: "opus-4-7", label: "Opus 4.7" },
      { id: "sonnet-4-6", label: "Sonnet 4.6" },
      { id: "haiku-4-5", label: "Haiku 4.5" },
    ]}
    skills={[
      { id: "sk1", label: "diff-explainer" },
      { id: "sk2", label: "test-runner" },
      { id: "sk3", label: "security-audit" },
    ]}
  />

## Props

## Notes

- `onSave` (required) receives an `AgentDraft` with the trimmed field values;
  allowed tools are split from the comma-separated input and empty entries are
  dropped.
- `initial` seeds the form for editing. When `initial.id` is present the submit
  button reads "Save changes"; otherwise "Create agent".
- Pass `models` and `skills` to render the model select and the skill toggle
  chips — both sections are hidden when their list is empty.
- Optional `onCancel` and `onDelete` render the corresponding footer buttons;
  save is disabled until the name is non-empty.
- Active modes are `chat`, `code`, and `infra`; an empty selection means the
  agent is global (available in every mode).

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentEditor } from "@theokit/ui/agent-editor";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-editor.json
```

---

# AgentErrorCard

Source: https://docs.usetheo.dev/theokit/ui/agent-error-card

Inline error / blocked-state card for an agent stream — icon by error kind, detail, timestamp, and a recovery-action slot

`AgentErrorCard` renders when an agent run hits a wall it cannot recover from on
its own: a rate limit, context overflow, lost auth, tool failure, or network
error. Severity is always destructive; the `kind` drives the icon and helps you
wire recovery actions into the footer slot.

<ComponentPreview name="agent-error-card" code={`<AgentErrorCard
  kind="rate-limit"
  title="Rate limit hit"
  detail="anthropic: 429 — retry after 60s"
  timestamp="9:59 PM"
/>`}>
  <AgentErrorCard
    kind="rate-limit"
    title="Rate limit hit"
    detail="anthropic: 429 — retry after 60s"
    timestamp="9:59 PM"
  />

## Props

## Notes

- `kind` is one of `rate-limit`, `context-overflow`, `auth`, `tool-failure`,
  `network`, or `generic` — each maps to its own icon.
- Instead of `kind`, you can pass `envelopeCode` (a canonical `TheoErrorCode`
  string like `"UNAUTHORIZED"` or `"RATE_LIMITED"`) and the card derives the
  kind for you. An explicit `kind` wins when both are supplied.
- The `actions` slot holds recovery buttons (Retry, Reset, Re-authenticate).
- The card renders `role="alert"`; when standalone it also sets
  `aria-live="assertive"`, and it drops that attribute when nested inside a
  container live region (such as `AgentStream`) to avoid double announcements.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentErrorCard } from "@theokit/ui/agent-error-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-error-card.json
```

---

# AgentEvent

Source: https://docs.usetheo.dev/theokit/ui/agent-event

Single event row in an agent timeline — type icon, label, path, diff stats, and status.

`AgentEvent` renders one row in an agent's activity timeline: a type icon, a label, an
optional file path, optional diff stats, and a status icon. When `collapsible` is set and
the event carries a `detail`, the row becomes a button that expands to reveal the detail
with correct keyboard and screen-reader semantics.

<ComponentPreview name="agent-event" code={`<AgentEvent
  event={{
    id: "2",
    type: "edit",
    label: "Edit AlignmentGrid.tsx",
    path: "src/components/AlignmentGrid.tsx",
    diff: { added: 142, removed: 38 },
    status: "success",
  }}
/>`}>
  <AgentEvent
    event={{
      id: "2",
      type: "edit",
      label: "Edit AlignmentGrid.tsx",
      path: "src/components/AlignmentGrid.tsx",
      diff: { added: 142, removed: 38 },
      status: "success",
    }}
  />

## Props

## Notes

- `event.type` is one of `command`, `file_read`, `file_write`, `edit`, `lint`,
  `typecheck`, `build`, `tool` — each maps to its own icon.
- `event.status` is `pending`, `running`, `success`, or `failed`. Running events show a
  spinner via `motion-safe:animate-spin` (respects `prefers-reduced-motion`); failed
  events flash red.
- When `collapsible` is true and `event.detail` is provided, the row renders as a native
  `<button>` with `aria-expanded` for keyboard and screen-reader support.
- The component holds no timer — `event.timestamp` is display-only.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentEvent } from "@theokit/ui/agent-event";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-event.json
```

---

# AgentHandoff

Source: https://docs.usetheo.dev/theokit/ui/agent-handoff

Visual marker of one agent delegating to another — two toned avatars, an arrow, the reason, and an optional metadata footer

`AgentHandoff` is a visual marker of one agent delegating to another. It pairs
with `AgentProfile` for the identity tones — place it in a timeline so the user
sees the baton being passed between the `from` and `to` parties.

<ComponentPreview name="agent-handoff" code={`<AgentHandoff
  from={{ name: "planner", tone: "accent", initials: "PL" }}
  to={{ name: "coder", tone: "primary", initials: "CD" }}
  reason="Plan complete · 7 steps · ready for implementation."
  footer="10:01:32 · token budget transferred: 120k"
/>`}>
  <AgentHandoff
    from={{ name: "planner", tone: "accent", initials: "PL" }}
    to={{ name: "coder", tone: "primary", initials: "CD" }}
    reason="Plan complete · 7 steps · ready for implementation."
    footer="10:01:32 · token budget transferred: 120k"
  />

## Props

## Notes

- `from` and `to` are `HandoffParty` objects: a `name`, optional `initials`
  (falls back to the first two letters of the name), and an optional `tone`.
- `tone` is one of `primary`, `accent`, `success`, `warning`, `info`, or `muted`
  — the same identity palette as `AgentProfile`.
- `reason` is the short payload preview; `footer` is optional metadata such as a
  timestamp or transferred token budget.
- The component is presentational and holds no internal state.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentHandoff } from "@theokit/ui/agent-handoff";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-handoff.json
```

---

# AgentProfile

Source: https://docs.usetheo.dev/theokit/ui/agent-profile

Switcher between multiple agent profiles (coder, planner, reviewer) — a toned avatar chip that opens a dropdown of personas

`AgentProfile` is a switcher between multiple agent profiles — coder, planner,
reviewer, and so on. Each profile gets its own tone so the user can spot at a
glance which persona is currently driving the session. Clicking the chip opens a
dropdown listing every agent, with descriptions and an optional badge.

<ComponentPreview name="agent-profile" code={`<AgentProfile
  agents={[
    { id: "coder", name: "Coder", initials: "CD", description: "Edits files and runs tests.", tone: "primary" },
    { id: "planner", name: "Planner", initials: "PL", description: "Breaks tasks into plans, no edits.", tone: "accent" },
    { id: "reviewer", name: "Reviewer", initials: "RV", description: "Reviews diffs, suggests changes.", tone: "info" },
  ]}
  activeId="coder"
/>`}>
  <AgentProfile
    agents={[
      { id: "coder", name: "Coder", initials: "CD", description: "Edits files and runs tests.", tone: "primary" },
      { id: "planner", name: "Planner", initials: "PL", description: "Breaks tasks into plans, no edits.", tone: "accent" },
      { id: "reviewer", name: "Reviewer", initials: "RV", description: "Reviews diffs, suggests changes.", tone: "info" },
    ]}
    activeId="coder"
  />

## Props

## Notes

- `agents` is an array of `AgentProfileDescriptor` objects (`id`, `name`,
  optional `initials`, `description`, `tone`, and `badge`); `activeId` selects
  which one is shown on the trigger.
- `tone` is one of `primary`, `accent`, `success`, `warning`, `info`, or `muted`
  and colors the avatar so agents are distinguishable at a glance.
- `onChange` fires with the selected agent id when the user picks a different
  profile from the dropdown.
- If `activeId` matches no agent, the first agent in the list is shown.
- Built on Radix Dropdown Menu, so keyboard navigation and focus management come
  for free.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentProfile } from "@theokit/ui/agent-profile";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-profile.json
```

---

# AgentStartingState

Source: https://docs.usetheo.dev/theokit/ui/agent-starting-state

Full-width skeleton shown while the agent boots — a violet spinner with a label and an optional bootstrap hint

`AgentStartingState` is the full-width placeholder shown while the agent boots.
It renders a violet spinner next to a label, with an optional hint below
explaining the bootstrap step. It uses a semantic `<output aria-live="polite">`
so screen readers announce the state.

<ComponentPreview name="agent-starting-state" code={`<AgentStartingState
  label="Booting local sandbox…"
  hint="Validating folder permissions and warming up the model context."
/>`}>
  <AgentStartingState
    label="Booting local sandbox…"
    hint="Validating folder permissions and warming up the model context."
  />

## Props

## Notes

- `label` defaults to `"Starting up…"` when omitted.
- `hint` is optional secondary copy for the current bootstrap step.
- The spinner uses `animate-spin`; the state is announced via
  `aria-live="polite"`, which is dropped when the component is nested inside a
  container live region to avoid double announcements.
- The component is presentational and holds no internal timer.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentStartingState } from "@theokit/ui/agent-starting-state";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-starting-state.json
```

---

# AgentStream

Source: https://docs.usetheo.dev/theokit/ui/agent-stream

The canonical conversation surface for a code agent — interleaves chat messages, tool calls, approvals, errors, and the live streaming indicator

`AgentStream` is the canonical conversation surface for a code agent. It
interleaves chat messages (user and assistant), tool invocations, approval gates,
errors, and the live streaming indicator — mirroring how Claude Code presents
work: conversation-centric, tool calls embedded, approvals pausing the flow
inline, errors surfacing where they happen. Items render in array order; you
fully control the data.

<ComponentPreview name="agent-stream" code={`<AgentStream
  className="max-w-2xl"
  items={[
    {
      kind: "message",
      id: "u1",
      message: { id: "u1", role: "user", parts: [{ type: "text", text: "Find every call site of stiffness and refactor to snap." }] },
    },
    {
      kind: "message",
      id: "a1",
      message: { id: "a1", role: "assistant", parts: [{ type: "text", text: "I'll start by grepping the codebase for stiffness call sites." }] },
    },
    {
      kind: "streaming",
      id: "s1",
      model: "Opus 4.7",
      partial: "Resuming. Let me re-run the failing test with verbose output…",
    },
  ]}
/>`}>
  <AgentStream
    className="max-w-2xl"
    items={[
      {
        kind: "message",
        id: "u1",
        message: { id: "u1", role: "user", parts: [{ type: "text", text: "Find every call site of stiffness and refactor to snap." }] },
      },
      {
        kind: "message",
        id: "a1",
        message: { id: "a1", role: "assistant", parts: [{ type: "text", text: "I'll start by grepping the codebase for stiffness call sites." }] },
      },
      {
        kind: "streaming",
        id: "s1",
        model: "Opus 4.7",
        partial: "Resuming. Let me re-run the failing test with verbose output…",
      },
    ]}
  />

## Props

## Notes

- Each item carries a `kind` discriminant: `message`, `tool-call`, `approval`,
  `error`, `streaming`, or `custom` (an escape hatch for arbitrary inline nodes).
  Each maps to the matching child primitive — `ChatMessage`, `ToolCallCard`,
  `ApprovalCard`, `AgentErrorCard`, `AgentStreaming`.
- `message` items take a `UIMessage` (structurally compatible with the Vercel AI
  `UIMessage` shape); `tool-call`, `approval`, and `error` items carry the data
  their card needs, including callbacks like `onApprove` and `onDeny`.
- The stream is the canonical live region for the surface: it wraps children in a
  provider so nested primitives (streaming indicator, error card, auto-compact
  notice) omit their own `aria-live` and avoid double announcements.
- The example above uses only serializable item kinds; a real stream also
  interleaves tool-call, approval, and error items with icons and action
  callbacks.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentStream } from "@theokit/ui/agent-stream";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-stream.json
```

---

# AgentStreaming

Source: https://docs.usetheo.dev/theokit/ui/agent-streaming

Inline "agent is thinking / typing" indicator — three pulsing dots, or the streamed-so-far text with a caret

`AgentStreaming` is the inline indicator shown inside an agent stream while the
model is producing a response. By default it renders three violet dots pulsing.
When `partial` is provided it renders the streamed-so-far text with a blinking
caret, and an optional `model` label appears above it.

<ComponentPreview name="agent-streaming" code={`<AgentStreaming
  model="Opus 4.7"
  partial="Let me start by inspecting the constraint solver in AlignmentGrid"
/>`}>
  <AgentStreaming
    model="Opus 4.7"
    partial="Let me start by inspecting the constraint solver in AlignmentGrid"
  />

## Props

## Notes

- With no `partial`, the component shows the three-dot "thinking…" animation.
- With `partial`, it renders the streamed text followed by a pulsing caret.
- `model` is an optional label rendered as an uppercase mono chip above the text.
- Standalone, the component is a `role="status"` polite live region; when nested
  inside a container live region (such as `AgentStream`) it omits its own
  `aria-live` to prevent double announcements.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentStreaming } from "@theokit/ui/agent-streaming";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-streaming.json
```

---

# AgentTimeline

Source: https://docs.usetheo.dev/theokit/ui/agent-timeline

Vertical list of agent events with an optional connecting line — composes AgentEvent rows that can expand to reveal detail

`AgentTimeline` is a vertical list of agent events. A thin border-left runs
through the column with each `AgentEvent` slightly indented from it, and events
animate in when first mounted. It is a composite over the `AgentEvent` primitive:
you pass the event data and it renders one row per event.

<ComponentPreview name="agent-timeline" code={`<AgentTimeline
  className="max-w-2xl"
  events={[
    { id: "1", type: "command", label: "Start dev server", status: "success", timestamp: "9:58:14 PM" },
    { id: "2", type: "file_write", label: "Write PanelGrid.tsx", path: "src/components/PanelGrid.tsx", diff: { added: 62, removed: 0 }, status: "success", timestamp: "9:58:24 PM" },
    { id: "3", type: "edit", label: "Edit AlignmentGrid.tsx", path: "src/components/AlignmentGrid.tsx", diff: { added: 142, removed: 38 }, status: "success", timestamp: "9:58:42 PM" },
    { id: "4", type: "lint", label: "Lint", status: "success" },
    { id: "5", type: "typecheck", label: "Typecheck", status: "success" },
    { id: "6", type: "build", label: "Build", status: "running" },
  ]}
/>`}>
  <AgentTimeline
    className="max-w-2xl"
    events={[
      { id: "1", type: "command", label: "Start dev server", status: "success", timestamp: "9:58:14 PM" },
      { id: "2", type: "file_write", label: "Write PanelGrid.tsx", path: "src/components/PanelGrid.tsx", diff: { added: 62, removed: 0 }, status: "success", timestamp: "9:58:24 PM" },
      { id: "3", type: "edit", label: "Edit AlignmentGrid.tsx", path: "src/components/AlignmentGrid.tsx", diff: { added: 142, removed: 38 }, status: "success", timestamp: "9:58:42 PM" },
      { id: "4", type: "lint", label: "Lint", status: "success" },
      { id: "5", type: "typecheck", label: "Typecheck", status: "success" },
      { id: "6", type: "build", label: "Build", status: "running" },
    ]}
  />

## Props

## Notes

- Each entry follows the `AgentEvent` model — `type`, `label`, optional `path`,
  `diff` stats, `status`, and `timestamp`.
- `collapsible` (default `true`) lets events that carry a `detail` expand
  inline; `showLine` (default `true`) toggles the vertical connecting line.
- Running events show a spinner; failed events flash red — the same per-status
  visuals as the underlying `AgentEvent`.
- The component is presentational; you fully control the event data.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentTimeline } from "@theokit/ui/agent-timeline";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-timeline.json
```

---

# AgentToolRenderer

Source: https://docs.usetheo.dev/theokit/ui/agent-tool-renderer

Dispatches a tool invocation to a rich renderer by kind — diff, terminal, code, created-files, or data-table — falling back to a generic tool card

`AgentToolRenderer` renders one `ToolUIPart` through a registry keyed by
classification kind (`diff`, `terminal`, `code`, `created-files`, `data-table`).
A default classifier maps the tool name to a kind via substring heuristics; the
registry then picks the matching rich renderer (`DiffViewer`, `TerminalPanel`,
`CodeBlock`, `CreatedFilesCard`, `DataTable`). Anything unmapped — or any
non-`output-available` state such as an errored tool — falls back to the generic
`ToolCallPart`, so an error is never swallowed by an empty rich surface.

<ComponentPreview name="agent-tool-renderer" code={`<AgentToolRenderer
  part={{
    type: "tool-shell",
    toolName: "shell",
    toolCallId: "call-shell",
    state: "output-available",
    input: { command: "pnpm test" },
    output: "src/lib/cn.test.ts (3)\\nsrc/components/button.test.tsx (5)\\n\\nTest Files  2 passed",
  }}
/>`}>
  <AgentToolRenderer
    part={{
      type: "tool-shell",
      toolName: "shell",
      toolCallId: "call-shell",
      state: "output-available",
      input: { command: "pnpm test" },
      output:
        "src/lib/cn.test.ts (3)\nsrc/components/button.test.tsx (5)\n\nTest Files  2 passed",
    }}
  />

## Props

## Notes

- The default classifier is a name-substring heuristic (`read_file` -> `code`,
  `shell` -> `terminal`, `git_diff` -> `diff`, `list_dir` -> `data-table`,
  `write_file` -> `created-files`). Override it with `classifyTool`.
- Override individual renderers with `toolRenderers` — a registry keyed by the
  five kinds.
- Rich renderers apply ONLY to the `output-available` state. Every other state
  (`input-streaming`, `input-available`, `approval-*`, `output-error`,
  `output-denied`) routes to `ToolCallPart`, which renders the state badge, the
  input, and any error text.
- The default `diff`, `created-files`, and `data-table` renderers are defensive:
  they render their rich primitive only when `part.output` already matches the
  structured shape, otherwise they degrade to `ToolCallPart` rather than throw.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AgentToolRenderer } from "@theokit/ui/agent-tool-renderer";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/agent-tool-renderer.json
```

---

# ApprovalCard

Source: https://docs.usetheo.dev/theokit/ui/approval-card

Inline pause-and-ask card for an agent stream, with Deny, Approve, and optional Always-allow actions

`ApprovalCard` is a bordered card that pauses an agent's visual flow to ask the
user for consent — running a destructive command, using a new tool, editing
outside the sandbox, and so on. It shows a severity-tuned icon, a title, the
monospace `request` being made, an optional description and expandable details,
and up to three actions: Deny, Approve, and Always allow.

<ComponentPreview name="approval-card" code={`<ApprovalCard
  severity="destructive"
  title="Run destructive command?"
  request="Bash · rm -rf node_modules"
  description="This will permanently delete files."
  onApprove={() => undefined}
  onDeny={() => undefined}
/>`}>
  <ApprovalCard
    severity="destructive"
    title="Run destructive command?"
    request="Bash · rm -rf node_modules"
    description="This will permanently delete files."
  />

## Props

## Notes

- `severity` is `info`, `warning` (default), or `destructive` — it selects the
  corner icon, the card tint, and the Approve button variant (destructive
  severity gives a destructive-styled Approve button).
- Each action button renders only when its handler is provided: `onDeny`,
  `onApprove`, and the tertiary `onAlways` ("Always allow").
- `details` renders inside a native collapsible `<details>` element ("Show
  details") — good for a full command or a diff.
- The card is a `role="alertdialog"`; when `title` is a string it becomes the
  `aria-label`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ApprovalCard } from "@theokit/ui/approval-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/approval-card.json
```

---

# ArtifactPreview

Source: https://docs.usetheo.dev/theokit/ui/artifact-preview

Shell for previewing a generated artifact (XLSX, PDF, image) — toolbar, content slot, and optional bottom tabs.

`ArtifactPreview` is a dependency-free shell for previewing a generated artifact such as a
spreadsheet, PDF, or image. It renders a toolbar (refresh, maximize, close), your own
preview content as `children`, and optional bottom tabs. Reach for it in a Task Completed
or side-panel view where an agent produced a file you want to show inline.

<ComponentPreview name="artifact-preview" code={`<ArtifactPreview
  className="h-[420px] w-full max-w-3xl"
  title="expense-report · XLSX"
  source="Google Drive · synced 2m ago"
  onRefresh={() => undefined}
  onMaximize={() => undefined}
  onClose={() => undefined}
>
  <div className="p-4 font-mono text-code-sm">Expense report preview…</div>
</ArtifactPreview>`}>
  <ArtifactPreview
    className="h-[420px] w-full max-w-3xl"
    title="expense-report · XLSX"
    source="Google Drive · synced 2m ago"
  >
    <div className="p-4 font-mono text-code-sm">Expense report preview…</div>

## Props

## Notes

- The actual preview (spreadsheet, PDF embed, image) is your `children` — the component
  stays dependency-free and only provides the frame.
- The default toolbar renders a button only for each callback you pass (`onRefresh`,
  `onMaximize`, `onClose`); pass a `toolbar` node to replace the whole action group.
- `source` is an optional monospace label under the title (e.g. `"Google Drive"`,
  `"Local · ~/reports"`).
- `tabs` render in a bottom footer; the active state is controlled externally by the
  caller.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ArtifactPreview } from "@theokit/ui/artifact-preview";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/artifact-preview.json
```

---

# AttachmentChip

Source: https://docs.usetheo.dev/theokit/ui/attachment-chip

File pill for the chat composer or a message attachments row — type icon, name, size, and optional remove button.

`AttachmentChip` renders a single file as a rounded chip: a type-aware icon, the file name
(truncated with the full name in the title), an optional size, and an optional remove
button. Use it in a chat composer or a message's attachments row.

<ComponentPreview name="attachment-chip" code={`<AttachmentChip
  attachment={{
    id: "1",
    name: "expense-report.xlsx",
    size: "42 KB",
    type: "spreadsheet",
  }}
  onRemove={() => undefined}
/>`}>
  <AttachmentChip
    attachment={{
      id: "1",
      name: "expense-report.xlsx",
      size: "42 KB",
      type: "spreadsheet",
    }}
  />

## Props

## Notes

- `attachment.type` (`image`, `spreadsheet`, `code`, `text`) maps to its own icon; any
  other or missing type falls back to a generic file icon.
- The name truncates with an ellipsis and exposes the full name via the `title` attribute.
- `attachment.size` is optional and shown as a trailing `· 42 KB` segment.
- The remove button only renders when `onRemove` is provided; it is labelled
  `Remove {name}` for screen readers.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AttachmentChip } from "@theokit/ui/attachment-chip";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/attachment-chip.json
```

---

# AuditLogEntry

Source: https://docs.usetheo.dev/theokit/ui/audit-log-entry

One row in the agent audit log — who did what and when, with severity coloring.

`AuditLogEntry` renders one row of an agent audit log: an actor icon, the actor
name, the action verb, an optional target, an optional detail block, and a
timestamp. It tells the user exactly who did what and when, and its severity
colors the action and the icon.

<ComponentPreview name="audit-log-entry" code={`<AuditLogEntry
  entry={{
    id: "3",
    actor: { kind: "agent", name: "coder" },
    action: "blocked from running",
    target: "rm -rf /etc/secrets",
    timestamp: "10:02:14",
    severity: "warning",
    detail: 'Matched permission rule "Bash · rm -rf* · deny".',
  }}
/>`}>
  <AuditLogEntry
    entry={{
      id: "3",
      actor: { kind: "agent", name: "coder" },
      action: "blocked from running",
      target: "rm -rf /etc/secrets",
      timestamp: "10:02:14",
      severity: "warning",
      detail: 'Matched permission rule "Bash · rm -rf* · deny".',
    }}
  />

## Props

## Notes

- `entry.actor.kind` is one of `user`, `agent`, or `system` — each maps to its own
  icon.
- `entry.severity` is `info` (default), `warning`, or `error`. It colors the action
  label and the actor icon.
- `entry.target` and `entry.detail` are optional and accept any `ReactNode`; the
  detail renders in its own block below the row.
- The component is presentational and holds no state — `entry.timestamp` is
  display-only.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AuditLogEntry } from "@theokit/ui/audit-log-entry";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/audit-log-entry.json
```

---

# AutoCompactNotice

Source: https://docs.usetheo.dev/theokit/ui/auto-compact-notice

Inline banner warning that the agent is about to summarize older context — with a turns-remaining countdown and token estimate

`AutoCompactNotice` is an inline banner that warns the user the agent is about to
summarize or compact older context. It is critical for transparency: a user must
not be surprised by silent context loss, so this component announces it before it
happens and lets them act early or dismiss.

<ComponentPreview name="auto-compact-notice" code={`<AutoCompactNotice
  turnsRemaining={3}
  tokensToCompact={48000}
/>`}>
  <AutoCompactNotice
    turnsRemaining={3}
    tokensToCompact={48000}
  />

## Props

## Notes

- `turnsRemaining` renders an inline countdown chip ("3 turns left"); it
  pluralizes correctly for a single turn.
- `tokensToCompact` is formatted compactly (for example `48.0k`) inside the
  explanatory copy.
- `title` defaults to `"Auto-compaction soon"`.
- Pass `onCompactNow` to render a "Compact now" action and `onDismiss` to render
  a dismiss button. Both are optional — omit them for a read-only notice.
- The banner uses `aria-live="polite"`, dropped when nested inside a container
  live region.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { AutoCompactNotice } from "@theokit/ui/auto-compact-notice";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/auto-compact-notice.json
```

---

# BranchIndicator

Source: https://docs.usetheo.dev/theokit/ui/branch-indicator

Small "×N" pill shown when an agent run was retried or branched — renders nothing when the count is below two

`BranchIndicator` is a small "×N" pill that surfaces when a run was retried or
branched. It renders `null` when `branchCount` is less than 2 or is not a
positive integer, so you can drop it into a row unconditionally and it only
appears when there is actually a branch to report.

<ComponentPreview name="branch-indicator" code={`<BranchIndicator branchCount={3} />`}>

## Props

## Notes

- Renders nothing when `branchCount < 2` or when it is not an integer (guarded
  against values like `-1`, `0`, and `0.5`).
- The default tooltip reads "Run branched N-1 time(s)"; override it with
  `tooltipText`.
- The pill exposes `data-branch-count` and a `data-testid` (default
  `branch-indicator`) for test targeting.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { BranchIndicator } from "@theokit/ui/branch-indicator";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/branch-indicator.json
```

---

# BrowserControls

Source: https://docs.usetheo.dev/theokit/ui/browser-controls

Back, forward, reload, and a URL bar — the top of a preview panel in a code workspace.

`BrowserControls` renders back/forward/reload buttons and an editable URL bar. It is
designed as the top strip of a `PreviewPanel` in a code workspace, sitting above an iframe
or preview surface.

<ComponentPreview name="browser-controls" code={`<BrowserControls
  url="http://localhost:5173/"
  onUrlChange={() => undefined}
  onBack={() => undefined}
  onForward={() => undefined}
  onReload={() => undefined}
/>`}>
  <BrowserControls
    url="http://localhost:5173/"
  />

## Props

## Notes

- Each nav button is disabled unless its callback (`onBack`, `onForward`, `onReload`) is
  provided — no dead affordances.
- The URL input is read-only when `readOnlyUrl` is set, or automatically when no
  `onUrlChange` is passed.
- The component is presentational: navigation and reload behavior are the caller's job.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { BrowserControls } from "@theokit/ui/browser-controls";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/browser-controls.json
```

---

# BuildLogStream

Source: https://docs.usetheo.dev/theokit/ui/build-log-stream

Terminal-like log viewer with timestamps, level coloring, and optional level filter chips.

`BuildLogStream` renders a scrollable, terminal-styled log viewer. Each line carries a
timestamp, a level (`info`, `warn`, `error`, `success`, `debug`), a message, and an
optional source tag. Use it in a code workspace or a deployment view to show build and
deploy output.

<ComponentPreview name="build-log-stream" code={`<BuildLogStream
  lines={[
    { id: "1", timestamp: "10:01:32", level: "info", message: "preparing build environment", source: "theo" },
    { id: "2", timestamp: "10:01:38", level: "info", message: "running typecheck", source: "tsc" },
    { id: "3", timestamp: "10:01:42", level: "warn", message: "deprecated: legacy ssr flag", source: "tsc" },
    { id: "4", timestamp: "10:01:44", level: "success", message: "types ok", source: "tsc" },
  ]}
/>`}>
  <BuildLogStream
    lines={[
      { id: "1", timestamp: "10:01:32", level: "info", message: "preparing build environment", source: "theo" },
      { id: "2", timestamp: "10:01:38", level: "info", message: "running typecheck", source: "tsc" },
      { id: "3", timestamp: "10:01:42", level: "warn", message: "deprecated: legacy ssr flag", source: "tsc" },
      { id: "4", timestamp: "10:01:44", level: "success", message: "types ok", source: "tsc" },
    ]}
  />

## Props

## Notes

- Level filter chips render by default (`filterable`); toggling a level filters the stream.
  Filtering can be uncontrolled or driven via `visibleLevels` + `onVisibleLevelsChange` —
  pick one mode and keep it.
- `maxLines` (default `2000`) caps rendered rows; beyond it only the tail is shown and a
  banner reports how many earlier lines are hidden. Reconciliation cost scales linearly, so
  raise it with care.
- `live` defaults to `"off"` because streams can be high-volume; opt into `"polite"` only
  when the build runs in the foreground. When nested inside a container live region, the
  component suppresses its own `aria-live`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { BuildLogStream } from "@theokit/ui/build-log-stream";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/build-log-stream.json
```

---

# CapabilityIndicator

Source: https://docs.usetheo.dev/theokit/ui/capability-indicator

Row of chips showing what the agent can currently do — read, write, exec, network, deploy — with per-capability state

`CapabilityIndicator` renders a row of chips that make the agent's current
capabilities visible at a glance — typically in a top bar, so the user always
knows whether read, write, shell, network, or deploy access is on. Each chip
carries a state (`enabled`, `active`, `disabled`, `blocked`); an `active`
capability pulses its icon while in use.

<ComponentPreview name="capability-indicator" code={`<CapabilityIndicator
  capabilities={[
    { id: "read", label: "Read files", state: "enabled" },
    { id: "write", label: "Write files", state: "active", hint: "Editing src/lib/cn.ts" },
    { id: "bash", label: "Run shell", state: "enabled" },
    { id: "network", label: "Network", state: "disabled" },
    { id: "delete", label: "Delete files", state: "blocked" },
  ]}
/>`}>
  <CapabilityIndicator
    capabilities={[
      { id: "read", label: "Read files", state: "enabled" },
      { id: "write", label: "Write files", state: "active", hint: "Editing src/lib/cn.ts" },
      { id: "bash", label: "Run shell", state: "enabled" },
      { id: "network", label: "Network", state: "disabled" },
      { id: "delete", label: "Delete files", state: "blocked" },
    ]}
  />

## Props

## Notes

- Each `Capability` has an `id`, a `label`, an optional `icon`, an optional
  `state` (defaults to `enabled`), and an optional `hint` (rendered as the chip
  `title` when it is a string).
- The four states map to distinct tones: `enabled` (success), `active`
  (primary), `disabled` (muted, struck-through), `blocked` (destructive).
- The `active` state pulses the chip icon.
- The package exports `capabilityPresets` (read, write, delete, bash, network,
  deploy, llm) so apps can spread a preset and add a `state` instead of
  re-declaring labels and icons.
- The list is labelled `aria-label="Agent capabilities"`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { CapabilityIndicator } from "@theokit/ui/capability-indicator";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/capability-indicator.json
```

---

# ChannelCard

Source: https://docs.usetheo.dev/theokit/ui/channel-card

Inbound gateway connection card (Telegram, Discord, Slack, …) showing connection status, platform, and inline controls

`ChannelCard` represents an inbound gateway connection — Telegram, Discord,
Slack, WhatsApp, a webhook, or MCP — showing its connection status, platform, and
inline controls. The toggle reflects the current status: a connected channel can
be disconnected, a disconnected or errored one can be reconnected, and a
connecting channel disables the toggle while the handshake completes.

<ComponentPreview name="channel-card" code={`<ChannelCard
  className="max-w-md"
  channel={{
    id: "telegram-support",
    name: "support-bot",
    platform: "telegram",
    status: "connected",
    description: "Routes inbound DMs to the Support agent. Mirrors threads back via Telegram replies.",
    lastSeen: "2m ago",
    messageCount: 8421,
  }}
/>`}>
  <ChannelCard
    className="max-w-md"
    channel={{
      id: "telegram-support",
      name: "support-bot",
      platform: "telegram",
      status: "connected",
      description: "Routes inbound DMs to the Support agent. Mirrors threads back via Telegram replies.",
      lastSeen: "2m ago",
      messageCount: 8421,
    }}
  />

## Props

## Notes

- `channel.platform` is one of `telegram`, `discord`, `slack`, `whatsapp`,
  `webhook`, or `mcp` — each maps to its own icon and label.
- `channel.status` is one of `disconnected`, `connecting`, `connected`, or
  `error`; the status pill styling follows the state (connecting pulses).
- `lastSeen` and `messageCount` render an optional stats row only when supplied;
  `messageCount` is localized with thousands separators.
- Pass `onConfigure` and `onToggle` to render the footer controls. The toggle is
  disabled while the status is `connecting`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ChannelCard } from "@theokit/ui/channel-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/channel-card.json
```

---

# ChatComposer

Source: https://docs.usetheo.dev/theokit/ui/chat-composer

Message input area shared by Chat, Code, and Infra modes — stateless, submit on Enter, opt-in affordances

`ChatComposer` is the message input area, shared across Chat, Code, and Infra modes. It is
stateless: the caller controls `value` and handles `onSubmit`. Submit fires on Enter
(without Shift); Shift+Enter inserts a newline. Optional affordances (attach, voice, model
selector) are opt-in via slots and callbacks, so no fake controls are rendered.

<ComponentPreview name="chat-composer" code={`<ChatComposer value="" onValueChange={() => {}} />`}>

## Props

## Notes

- `mode` is `chat` (default), `code`, or `infra`. Code mode is a compact, mono-font form;
  chat and infra render a softer card. The placeholder and textarea label default per mode.
- Controlled: `value` + `onValueChange` are required; `onSubmit` fires on Enter or the Send
  button (only when the value is non-empty).
- When `running` is true, the Send button becomes a destructive Stop button that calls
  `onStop`.
- Slots let you compose the surface: `contextSlot` and `attachmentsSlot` above the textarea,
  `leadingActions` / `trailingActions` on the action row. `onAttach` and `onVoiceInput`
  render their buttons only when provided.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ChatComposer } from "@theokit/ui/chat-composer";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/chat-composer.json
```

---

# ChatMessage

Source: https://docs.usetheo.dev/theokit/ui/chat-message

Render a chat turn from a UIMessage — parts are dispatched to their built-in renderers automatically

`ChatMessage` renders a single chat turn from a `UIMessage` (the Vercel AI SDK `parts`
shape). Pass a full message and its parts — text, reasoning, files, sources, tool calls,
data — are dispatched to their built-in renderers automatically. Role controls layout:
user turns align right with a secondary bubble, assistant turns align left with a primary
accent border.

<ComponentPreview name="chat-message" code={`<ChatMessage
  message={{
    id: "1",
    role: "user",
    parts: [{ type: "text", text: "Quais arquivos do projeto?" }],
  }}
/>`}>
  <ChatMessage
    message={{
      id: "1",
      role: "user",
      parts: [{ type: "text", text: "Quais arquivos do projeto?" }],
    }}
  />

## Props

## Notes

- `message.role` drives layout: `user` (right-aligned secondary bubble), `assistant`
  (left, primary accent), or `system` (accent callout).
- Each part in `message.parts` is dispatched by type — `text`, `reasoning`, `file`,
  `source-url`, `source-document`, `tool-*`, `data-*`, `step-start`. Unhandled kinds render
  nothing.
- `variant` selects the content surface (`contained` bubble vs `flat`); assistant defaults
  to `contained`.
- `avatar` and `actions` are optional slots. `partRenderers`, `dataRenderers`,
  `toolRenderers`, and `classifyTool` override the built-in dispatch when you need custom
  rendering.
- A composable shell (`ChatMessageRoot`, `ChatMessageContent`, `ChatMessageToolbar`, and
  the `ChatMessageBranch*` parts) is also exported for cases where you compose the turn
  explicitly, alongside part renderers (`TextPart`, `ReasoningPart`, `ToolCallPart`, …).

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ChatMessage } from "@theokit/ui/chat-message";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/chat-message.json
```

---

# ChatThread

Source: https://docs.usetheo.dev/theokit/ui/chat-thread

Simple vertical container for chat turns — applies spacing and declares the outer live region

`ChatThread` is a simple vertical container that stacks chat turns with spacing. It
declares the outer live region for the conversation and wraps its children in a
`LiveRegionProvider`, so nested streaming, error, and skeleton components do not add their
own `aria-live` (avoiding double announcements). There is no virtualization or stickiness —
wrap it in your own scroller for long threads.

  <ChatMessage
    message={{ id: "u1", role: "user", parts: [{ type: "text", text: "What's the status of the deploy?" }] }}
  />
  <ChatMessage
    message={{ id: "a1", role: "assistant", parts: [{ type: "text", text: "Build is running. Should be live in ~12s." }] }}
  />
</ChatThread>`}>
    <ChatMessage
      message={{ id: "u1", role: "user", parts: [{ type: "text", text: "What's the status of the deploy?" }] }}
    />
    <ChatMessage
      message={{ id: "a1", role: "assistant", parts: [{ type: "text", text: "Build is running. Should be live in ~12s." }] }}
    />

## Props

`ChatThread` is a generic container — it accepts the standard `div` attributes
(`HTMLAttributes<HTMLDivElement>`), so there is no dedicated metadata table below.

- `className` — merged onto the container (`flex flex-col gap-6` by default).
- `children` — the chat turns to stack (typically `ChatMessage` elements).
- Any other `div` attribute (`id`, `style`, `data-*`, event handlers, etc.) is forwarded.

## Notes

- The container renders as `role="log"` with `aria-live="polite"` and
  `aria-relevant="additions"`, so appended turns are announced to screen readers.
- It wraps children in `LiveRegionProvider` (value `true`) — nested components that would
  otherwise declare their own live region defer to this one.
- No virtualization or sticky behavior; provide your own scroll container for long threads.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ChatThread } from "@theokit/ui/chat-thread";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/chat-thread.json
```

---

# ChoicePrompt

Source: https://docs.usetheo.dev/theokit/ui/choice-prompt

Single-select ask-the-user card for agent surfaces, with option descriptions, number-key shortcuts, an optional Other field, and a preview pane

`ChoicePrompt` mirrors the UX of Claude Code's question card: a question with an
optional header chip, a list of options each carrying a label and description, optional
`1`..`9` number-key selection, an injectable free-text Other option, and a side-by-side
preview pane when options carry preview content.

It renders one question at a time — sequencing across multiple questions is the
consumer's responsibility. Selection is controlled (`value` + `onValueChange`) or
uncontrolled (`defaultValue`).

<ComponentPreview name="choice-prompt" code={`<ChoicePrompt
  question="Which deploy strategy?"
  badge="Deploy"
  description="Pick how the new version rolls out to production."
  options={[
    { value: "blue-green", label: "Blue-green", description: "Zero downtime, 2x infra cost" },
    { value: "rolling", label: "Rolling", description: "Gradual rollout, no cost spike" },
    { value: "recreate", label: "Recreate", description: "Cheapest, brief downtime" },
  ]}
  onConfirm={(r) => console.log(r)}
  onCancel={() => {}}
/>`}>
  <PreviewChoicePrompt
    question="Which deploy strategy?"
    badge="Deploy"
    description="Pick how the new version rolls out to production."
    options={[
      { value: "blue-green", label: "Blue-green", description: "Zero downtime, 2x infra cost" },
      { value: "rolling", label: "Rolling", description: "Gradual rollout, no cost spike" },
      { value: "recreate", label: "Recreate", description: "Cheapest, brief downtime" },
    ]}
  />

## Props

## Notes

- Each option carries a `label`, optional `description`, optional `preview`, and can be
  `disabled`. When any option has a `preview`, the card renders a side-by-side preview
  pane showing the selected option's content.
- `allowOther` injects a free-text Other row as the last option; its text is surfaced on
  `onConfirm` as `otherText` when the Other row is selected.
- `enableKeyboardShortcuts` (default true) binds `1`..`9` to the first nine options.
  Digits typed into a form field (the Other input) are never hijacked. `showNumbers`
  controls the hint chips and defaults to the shortcut flag.
- `onConfirm` receives `{ value }` — or `{ value, otherText }` when the Other option is
  the selection. Confirm is disabled until a selection exists.
- The confirm/cancel footer only renders when `onConfirm`/`onCancel` are provided.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ChoicePrompt } from "@theokit/ui/choice-prompt";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/choice-prompt.json
```

---

# ConfirmPrompt

Source: https://docs.usetheo.dev/theokit/ui/confirm-prompt

Binary yes/no ask-the-user card for agent surfaces, with a destructive variant that exposes an alertdialog role

`ConfirmPrompt` is the simplest member of the prompt family: a question with an optional
header chip and two actions. Reach for it when the agent needs a plain yes/no from the
user before acting.

Use `variant="destructive"` for dangerous confirmations (delete, drop, force-push) — it
tones the confirm button red and exposes the card as an `alertdialog` so assistive tech
announces the stakes. It renders one question at a time; sequencing is the consumer's
responsibility.

<ComponentPreview name="confirm-prompt" code={`<ConfirmPrompt
  question="Deploy to production?"
  badge="Deploy"
  description="This rolls out v2.3.0 to all regions."
  onConfirm={() => console.log("confirmed")}
  onCancel={() => console.log("cancelled")}
/>`}>
  <PreviewConfirmPrompt
    question="Deploy to production?"
    badge="Deploy"
    description="This rolls out v2.3.0 to all regions."
  />

## Props

## Notes

- `variant="destructive"` tints the card and confirm button with the destructive tone and
  sets `role="alertdialog"` so screen readers announce the stakes.
- `confirmLabel` and `cancelLabel` default to `"Confirm"` and `"Cancel"`; override them to
  match the action (e.g. `"Delete cluster"` / `"Keep it"`).
- `badge` renders a header chip — `destructive` uses the destructive badge tone.
- The cancel button always renders; wire `onCancel` and `onConfirm` to handle each action.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ConfirmPrompt } from "@theokit/ui/confirm-prompt";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/confirm-prompt.json
```

---

# ContextCard

Source: https://docs.usetheo.dev/theokit/ui/context-card

Generic informational card for the right inspector — illustration or icon, title, and short description

`ContextCard` is an inert "informational" card, used as the context panel on Files screens.
It shows an optional illustration or icon, a title, and a short description. It has no
actions by design — reach for it when you want to surface context, not controls.

<ComponentPreview name="context-card" code={`<ContextCard
  title="Contexto"
  description="Acompanhe ferramentas e arquivos referenciados nesta tarefa."
/>`}>
  <ContextCard
    title="Contexto"
    description="Acompanhe ferramentas e arquivos referenciados nesta tarefa."
  />

## Props

## Notes

- When `illustration` is provided it renders centered above the title; otherwise the `icon`
  is shown (defaults to `BookOpen` from lucide-react).
- `title` and `description` accept any `ReactNode` and are each rendered only when present.
- The card is presentational and holds no state — it renders a `<section>` with no
  interactive affordances.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ContextCard } from "@theokit/ui/context-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/context-card.json
```

---

# ContextWindowBar

Source: https://docs.usetheo.dev/theokit/ui/context-window-bar

Shows how much of a model's context window has been consumed, with success to warning to danger color transitions

`ContextWindowBar` visualizes how much of the model's context window is used. The bar
transitions from primary to warning to destructive as usage crosses its thresholds, so a
user can glance at it and know whether the conversation is about to hit the cap.

<ComponentPreview name="context-window-bar" code={`<ContextWindowBar
  used={32400}
  total={200000}
  label="Context · Sonnet 4.6"
  trailing="20% used, ~167k tokens remaining"
/>`}>
  <ContextWindowBar
    used={32400}
    total={200000}
    label="Context · Sonnet 4.6"
    trailing="20% used, ~167k tokens remaining"
  />

## Props

## Notes

- `used` and `total` are token counts; the label formats large numbers as `k`/`M` (e.g.
  `32.4k / 200.0k`).
- Color tone is derived from the ratio `used / total`: primary below `warnAt` (default
  `0.7`), warning at or above it, and destructive at or above `dangerAt` (default `0.9`).
- `compact` hides the label and numbers, rendering just the bar — suited to dense layouts.
- The bar exposes `role="progressbar"` with `aria-valuenow`/`aria-valuemin`/`aria-valuemax`
  and a percentage `aria-label`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ContextWindowBar } from "@theokit/ui/context-window-bar";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/context-window-bar.json
```

---

# CostMeter

Source: https://docs.usetheo.dev/theokit/ui/cost-meter

Gauge for token spend — card with a big number and optional budget bar, or a compact chip.

`CostMeter` visualizes token spend. It has two visuals: a **card** (title, big number,
optional budget progress bar, optional delta vs a previous period) and a **compact** chip
for nav bars.

<ComponentPreview name="cost-meter" code={`<CostMeter
  cost={42.18}
  budget={100}
  title="This month"
  delta={{ value: 8.3, period: "vs last month" }}
/>`}>
  <CostMeter
    cost={42.18}
    budget={100}
    title="This month"
    delta={{ value: 8.3, period: "vs last month" }}
  />

## Props

## Notes

- With a `budget`, the card renders a progress bar; spend over budget is visually
  distinct.
- `delta` shows a signed change against a named period (e.g. `"vs last month"`).
- `compact` renders a single-line chip (`Coins $4.20`) suited to nav bars — no progress
  bar or delta.
- The component is presentational: it formats the numbers you pass and holds no internal
  state.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { CostMeter } from "@theokit/ui/cost-meter";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/cost-meter.json
```

---

# CreatedFilesCard

Source: https://docs.usetheo.dev/theokit/ui/created-files-card

Surfaces files produced by a completed task — icon, name, destination, and optional CTA.

`CreatedFilesCard` lists the files an agent produced when a task completes. Each file is a
row with an icon, name, an optional destination label, and an optional size; the card can
carry a call-to-action at the bottom. Use it as social proof of delivery in a Task
Completed view.

<ComponentPreview name="created-files-card" code={`<CreatedFilesCard
  className="max-w-xl"
  files={[
    { id: "1", name: "expense-report.xlsx", size: "42 KB", destination: "Google Drive · /Reports", href: "#" },
    { id: "2", name: "summary.md", size: "3 KB", destination: "Local · ~/Downloads" },
  ]}
/>`}>
  <CreatedFilesCard
    className="max-w-xl"
    files={[
      { id: "1", name: "expense-report.xlsx", size: "42 KB", destination: "Google Drive · /Reports", href: "#" },
      { id: "2", name: "summary.md", size: "3 KB", destination: "Local · ~/Downloads" },
    ]}
  />

## Props

## Notes

- A file with an `href` renders as a link (opens in a new tab); without one it renders as a
  static row.
- Each file may override its icon (`file.icon`); the default is a spreadsheet icon.
- `title` defaults to `"Files created"`; pass a `cta` node to render an action at the
  bottom-right (e.g. a "Move to Google Drive" button).

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { CreatedFilesCard } from "@theokit/ui/created-files-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/created-files-card.json
```

---

# CronJobCard

Source: https://docs.usetheo.dev/theokit/ui/cron-job-card

One scheduled agent job — cron expression, prompt, status, last/next run, and inline run/pause/delete actions

`CronJobCard` renders a single scheduled agent job as a card: the job name, its
cron expression, the prompt that gets run, a status pill, and last/next run
timestamps. When you pass the action callbacks, it renders inline `Run now`,
`Pause`/`Enable`, and delete controls.

<ComponentPreview name="cron-job-card" code={`<CronJobCard
  job={{
    id: "j1",
    name: "Nightly type-check",
    schedule: "0 3 * * *",
    prompt: "Run pnpm typecheck and report any errors.",
    status: "idle",
    lastRun: "9h ago",
    nextRun: "in 15h",
    lastResult: "no type errors",
  }}
  onRunNow={() => undefined}
  onToggle={() => undefined}
  onRemove={() => undefined}
/>`}>
  <CronJobCard
    job={{
      id: "j1",
      name: "Nightly type-check",
      schedule: "0 3 * * *",
      prompt: "Run pnpm typecheck and report any errors.",
      status: "idle",
      lastRun: "9h ago",
      nextRun: "in 15h",
      lastResult: "no type errors",
    }}
  />

## Props

## Notes

- `job.status` is one of `idle` (Scheduled), `running` (Running, pulses), `failed`
  (Last run failed), or `disabled` (Disabled, card dims to 70% opacity).
- Each action button only renders when its callback is provided: `onRunNow`,
  `onToggle`, `onRemove`. The toggle label reads `Pause` when the job is enabled and
  `Enable` when it is disabled.
- `job.lastRun` falls back to `never` and `job.nextRun` to a dash when absent.
- `job.lastResult` is an optional `ReactNode` shown below the run times.
- The component is presentational and holds no scheduling logic — timestamps are
  display strings you pass in.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { CronJobCard } from "@theokit/ui/cron-job-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/cron-job-card.json
```

---

# CronJobsList

Source: https://docs.usetheo.dev/theokit/ui/cron-jobs-list

Grid of CronJobCards with a header, a job count, and an optional new-job action

`CronJobsList` lays out a collection of `CronJobCard`s in a responsive grid with a
header, a live job count, and an optional `New job` button. When the list is empty
it renders a dashed empty-state panel instead of the grid. Action callbacks are
relayed down to every card.

<ComponentPreview name="cron-jobs-list" code={`<CronJobsList
  jobs={[
    {
      id: "1",
      name: "Daily TypeScript audit",
      schedule: "0 9 * * *",
      prompt: "Run typecheck across the workspace, summarize errors by category.",
      status: "idle",
      lastRun: "Yesterday 09:00",
      nextRun: "Tomorrow 09:00",
      lastResult: "0 errors, 14 warnings.",
    },
    {
      id: "2",
      name: "Hourly deploy health",
      schedule: "0 * * * *",
      prompt: "Check deploy status of theo-api in production and ping if degraded.",
      status: "running",
      lastRun: "55m ago",
      nextRun: "in 5m",
    },
  ]}
  onAdd={() => undefined}
  onRunNow={() => undefined}
  onToggle={() => undefined}
  onRemove={() => undefined}
/>`}>
  <CronJobsList
    jobs={[
      {
        id: "1",
        name: "Daily TypeScript audit",
        schedule: "0 9 * * *",
        prompt: "Run typecheck across the workspace, summarize errors by category.",
        status: "idle",
        lastRun: "Yesterday 09:00",
        nextRun: "Tomorrow 09:00",
        lastResult: "0 errors, 14 warnings.",
      },
      {
        id: "2",
        name: "Hourly deploy health",
        schedule: "0 * * * *",
        prompt: "Check deploy status of theo-api in production and ping if degraded.",
        status: "running",
        lastRun: "55m ago",
        nextRun: "in 5m",
      },
    ]}
  />

## Props

## Notes

- `title` defaults to `Scheduled jobs`; the header also shows a job count that
  pluralizes automatically (`1 job` vs `2 jobs`).
- The `New job` button only renders when `onAdd` is provided.
- With an empty `jobs` array, the list shows a dashed `No scheduled jobs yet.`
  panel instead of the grid.
- `onRunNow`, `onToggle`, and `onRemove` are forwarded to each `CronJobCard`; a card
  only renders the corresponding action when the callback is present.
- This is a composite — it depends on the `CronJobCard` primitive.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { CronJobsList } from "@theokit/ui/cron-jobs-list";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/cron-jobs-list.json
```

---

# DiffViewer

Source: https://docs.usetheo.dev/theokit/ui/diff-viewer

Unified diff rendering with old/new line-number gutters and success/destructive tinting — no external dep.

`DiffViewer` renders a unified diff for a single file: a header with the path and stats,
then one or more hunks of added, removed, unchanged, or meta lines. Added rows tint
success, removed rows tint destructive, and collapsed hunks render as a single muted "N
unmodified lines" row. No external diff library is required.

<ComponentPreview name="diff-viewer" code={`<DiffViewer
  className="max-w-3xl"
  path="src/components/AlignmentGrid.tsx"
  stats={{ added: 85, removed: 12 }}
  hunks={[
    {
      id: "h1",
      header: "@@ -424,5 +424,5 @@",
      lines: [
        { kind: "removed", oldNumber: 424, content: "<select stiffness={0.8}" },
        { kind: "added", newNumber: 424, content: "<select snap={true}" },
        { kind: "added", newNumber: 425, content: "  bounce={false}" },
        { kind: "unchanged", oldNumber: 425, newNumber: 426, content: "  align='center'" },
      ],
    },
  ]}
/>`}>
  <DiffViewer
    className="max-w-3xl"
    path="src/components/AlignmentGrid.tsx"
    stats={{ added: 85, removed: 12 }}
    hunks={[
      {
        id: "h1",
        header: "@@ -424,5 +424,5 @@",
        lines: [
          { kind: "removed", oldNumber: 424, content: "<select stiffness={0.8}" },
          { kind: "added", newNumber: 424, content: "<select snap={true}" },
          { kind: "added", newNumber: 425, content: "  bounce={false}" },
          { kind: "unchanged", oldNumber: 425, newNumber: 426, content: "  align='center'" },
        ],
      },
    ]}
  />

## Props

## Notes

- Each line's `kind` is `added`, `removed`, `unchanged`, or `meta`; the gutter shows the
  old and new line numbers, omitting whichever side does not apply.
- A hunk with `collapsed: true` renders as a single "N unmodified lines" placeholder instead
  of its rows.
- `stats` and each hunk's `header` are optional and formatted by the caller.
- For syntax highlighting, pass already-highlighted strings as line `content` — the
  component itself does no highlighting.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { DiffViewer } from "@theokit/ui/diff-viewer";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/diff-viewer.json
```

---

# ExportChatDialog

Source: https://docs.usetheo.dev/theokit/ui/export-chat-dialog

Modal for exporting a chat session in a selectable format — async-aware, controlled by the consumer

`ExportChatDialog` is a modal that lets users export a chat session in a selectable format
(Markdown, JSON, JSONL, or ShareGPT). It is async-aware: an `onExport` that returns a
Promise disables the Export button until the promise resolves. It is controlled — the
consumer renders the trigger and toggles `open`.

Because the dialog renders as a `fixed inset-0` full-screen overlay, it is shown here as
its real usage rather than an inline live preview:

```tsx
import { useState } from "react";
import { ExportChatDialog, type ExportFormat } from "@theokit/ui/export-chat-dialog";

function Example() {
  const [open, setOpen] = useState(true);
  return (
    <ExportChatDialog
      open={open}
      onOpenChange={setOpen}
      sessionLabel="sess_demo"
      onExport={async (format: ExportFormat) => {
        await new Promise((r) => setTimeout(r, 800));
        alert(`Exported as ${format}`);
      }}
    />
  );
}
```

## Props

## Notes

- Controlled overlay: `open`, `onOpenChange`, and `onExport` are required. When `open` is
  false the component renders nothing.
- `onExport` receives the chosen `ExportFormat` (`markdown`, `json`, `jsonl`, `sharegpt`).
  While it resolves, the radios and buttons are disabled and the Export button shows a
  spinner; the dialog closes on success.
- `availableFormats` restricts the offered formats (defaults to all four); the first
  available format is preselected. `sessionLabel` is shown next to the title when provided.
- The overlay renders as `role="dialog"` with `aria-modal="true"` and a labelled title for
  screen-reader semantics.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ExportChatDialog } from "@theokit/ui/export-chat-dialog";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/export-chat-dialog.json
```

---

# FolderContextCard

Source: https://docs.usetheo.dev/theokit/ui/folder-context-card

File and folder tree fragment for a right-hand inspector — chevrons, nested children, controlled open state.

`FolderContextCard` renders a shallow file/folder tree, suitable for a right-hand
inspector. Folders show a chevron reflecting their expanded state and render nested
children recursively. It does not manage open state — the caller controls each entry's
`open` flag and reacts to `onEntryClick`.

<ComponentPreview name="folder-context-card" code={`<FolderContextCard
  className="max-w-sm"
  title="capturas"
  entries={[
    {
      id: "folder",
      name: "capturas",
      kind: "folder",
      open: true,
      children: [
        { id: "claude", name: "Instruções · CLAUDE.md", kind: "file" },
        { id: "out", name: "Projeto-A", kind: "folder" },
      ],
    },
  ]}
/>`}>
  <FolderContextCard
    className="max-w-sm"
    title="capturas"
    entries={[
      {
        id: "folder",
        name: "capturas",
        kind: "folder",
        open: true,
        children: [
          { id: "claude", name: "Instruções · CLAUDE.md", kind: "file" },
          { id: "out", name: "Projeto-A", kind: "folder" },
        ],
      },
    ]}
  />

## Props

## Notes

- Each entry's `kind` is `folder` or `file`; folders with children show a chevron that
  rotates when `open` is true.
- Open state is caller-controlled: set `entry.open` and update it in response to
  `onEntryClick`.
- Entries may override their icon (`entry.icon`) and add a `trailing` adornment (badge,
  modified indicator) after the name.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { FolderContextCard } from "@theokit/ui/folder-context-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/folder-context-card.json
```

---

# FolderSelector

Source: https://docs.usetheo.dev/theokit/ui/folder-selector

Chip showing the active working directory — folder icon, monospaced path, chevron.

`FolderSelector` is a stateless chip that shows the active working directory: a folder
icon, the monospaced path (truncated when long), and a chevron. It is the trigger for a
folder-picker — the caller handles the actual dialog.

<ComponentPreview name="folder-selector" code={`<FolderSelector path="~/Code/usetheo/theo-desktop" />`}>

## Props

## Notes

- The component is stateless: opening the folder-picker dialog is the caller's
  responsibility (wire an `onClick` — it forwards native button props).
- `compact` renders a shorter variant for tight rows; the default is the full-width
  composer variant used in a Files panel.
- The path truncates when it overflows; the full string stays available in the DOM.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { FolderSelector } from "@theokit/ui/folder-selector";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/folder-selector.json
```

---

# GatewayStatusIndicator

Source: https://docs.usetheo.dev/theokit/ui/gateway-status-indicator

Live connection-status dot for a gateway or server, with optional label and latency

`GatewayStatusIndicator` shows the live connection status of a gateway or server
as a colored dot. The `labeled` variant adds a status label and optional latency
text; the `compact` variant is dot-only for tight spots like a sidebar footer.

<ComponentPreview name="gateway-status-indicator" code={`<GatewayStatusIndicator status="online" latencyMs={47} />`}>

## Props

## Notes

- `status` is one of `online`, `offline`, `degraded`, or `reconnecting` — each maps
  to its own dot color. `reconnecting` pulses via `animate-pulse` (respects
  `prefers-reduced-motion`).
- `variant` defaults to `labeled` (dot + label + optional latency). Use `compact`
  for a dot-only indicator.
- `latencyMs` is formatted for readability: sub-millisecond shows `<1ms`, values
  under a second show whole milliseconds, and larger values show seconds (e.g.
  `2.1s`). Negative or non-finite values are hidden.
- The root renders `role="img"` with a descriptive `aria-label` per status so the
  state is announced to assistive tech.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { GatewayStatusIndicator } from "@theokit/ui/gateway-status-indicator";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/gateway-status-indicator.json
```

---

# Getting started

Source: https://docs.usetheo.dev/theokit/ui/getting-started

Install @theokit/ui or copy components from the registry, wire the provider, render your first component.

Two ways to adopt `@theokit/ui` — install the whole package, or copy individual
components via the shadcn-compatible registry. Both are first-class.

## Option A — install the package

```bash
pnpm add @theokit/ui
```

Import the tokens and component styles once, at your app entrypoint:

```css
/* app entrypoint (e.g. app/globals.css) */
@import "@theokit/ui/tokens.css";
@import "@theokit/ui/styles.css";
```

Wrap your app in `<ThemeProvider>` and render a component:

```tsx
import { ThemeProvider, CostMeter } from "@theokit/ui";

export default function App() {
  return (
    <ThemeProvider defaultTheme="violet-forge" defaultMode="dark">
      <CostMeter cost={4.2} budget={100} title="This session" />
    </ThemeProvider>
  );
}
```

That renders:

<ComponentPreview name="cost-meter" code={`<CostMeter cost={4.2} budget={100} title="This session" />`}>

React (18 or 19) is the only required peer. Radix UI, CVA, cmdk, and lucide ship as
dependencies.

## Option B — copy individual components (shadcn-style)

Copy the source of a single component (and its declared dependencies) into your project:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/cost-meter.json
```

Every page in this reference lists its own `npx shadcn add …` command. The registry is
served at `https://usetheodev.github.io/theokit-ui/r/` (a branded `https://ui.usetheo.dev/r/`
URL follows once the DNS CNAME is configured — both serve identical content).

  Copy-paste install expects `@/` configured as a path alias in your `tsconfig.json`
  (`{ "paths": { "@/*": ["./src/*"] } }`) — the shadcn-ui convention. Inlined source uses
  `@/lib/cn` and similar imports.

## SSR / Server Components

Inject `<ThemeScript>` in `<head>` to prevent a flash of unstyled content and hydration
mismatch. Client components ship the `"use client"` directive in the published build, so
they are safe to import into a React Server Component tree.

```tsx
import { ThemeProvider, ThemeScript } from "@theokit/ui";

<html lang="en" suppressHydrationWarning>
  <head>
    <ThemeScript defaultTheme="violet-forge" defaultMode="dark" />
  </head>
  <body>
    <ThemeProvider defaultTheme="violet-forge" defaultMode="dark">
      {children}
    </ThemeProvider>
  </body>
</html>;
```

## Need generic or cloud-ops components?

Generic primitives (buttons, tables, dialogs), auth surfaces, and the cloud-ops layer
(deployment rows, env-var editors, domain config, rollback flows, metrics panels) live in
[`@usetheo/ui`](https://github.com/usetheodev/usetheo-ui) — the community-standard layer
`@theokit/ui` builds on. Install it alongside:

```bash
pnpm add @usetheo/ui
```

## Next

---

# HookConfig

Source: https://docs.usetheo.dev/theokit/ui/hook-config

Visual editor for lifecycle hooks — each row is an event, matcher, and command triple with an on/off toggle

`HookConfig` is a visual editor for lifecycle hooks (PreToolUse, PostToolUse,
UserPromptSubmit, Stop, SessionStart, SessionEnd). It mirrors Claude Code's
`settings.json` hooks: each row is an `{ event, matcher, command }` triple with
an on/off toggle. When `onAdd` is provided, a form row lets the user append new
hooks; `onRemove` and `onToggle` wire the per-row delete and enable controls.

<ComponentPreview name="hook-config" code={`<HookConfig
  hooks={[
    { id: "1", event: "PreToolUse", matcher: "Bash", command: "./scripts/audit-bash.sh", enabled: true },
    { id: "2", event: "PostToolUse", matcher: "Write", command: "biome check --write", enabled: true },
    { id: "3", event: "Stop", matcher: "*", command: "say 'agent done'", enabled: false },
  ]}
/>`}>
  <HookConfig
    hooks={[
      { id: "1", event: "PreToolUse", matcher: "Bash", command: "./scripts/audit-bash.sh", enabled: true },
      { id: "2", event: "PostToolUse", matcher: "Write", command: "biome check --write", enabled: true },
      { id: "3", event: "Stop", matcher: "*", command: "say 'agent done'", enabled: false },
    ]}
  />

## Props

## Notes

- Each `HookEntry` has an `id`, an `event` (one of the six `HookEvent` values), a
  `matcher` (tool name like `Bash` or `*`), a `command`, and an optional
  `enabled` flag (defaults to on).
- The add form renders only when `onAdd` is passed; the per-row On/Off toggle
  renders only with `onToggle`; the remove button renders only with `onRemove`.
  Omit them for a read-only view.
- A disabled hook (`enabled: false`) renders at reduced opacity.
- The package also exports `HOOK_EVENTS`, the ordered list of the six lifecycle
  events used to populate the event `<select>`.
- The header shows a live hook count.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { HookConfig } from "@theokit/ui/hook-config";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/hook-config.json
```

---

# HookEventLog

Source: https://docs.usetheo.dev/theokit/ui/hook-event-log

Chronological list of hook firings, each with a result tone, the command that ran, an optional output preview, and a timestamp

`HookEventLog` renders a chronological list of hook firings. Each entry shows a
result-tinted icon (`ok`, `blocked`, `error`), the event and matcher, an
optional duration, the command that ran, an optional output/stderr preview, and
a timestamp. It is the runtime companion to `HookConfig` — the config edits the
hooks, the log shows what they did.

<ComponentPreview name="hook-event-log" code={`<HookEventLog
  events={[
    { id: "1", event: "PreToolUse", matcher: "Bash", command: "./scripts/audit-bash.sh", result: "ok", timestamp: "10:02:14", duration: "47ms" },
    { id: "2", event: "PostToolUse", matcher: "Write", command: "biome check --write", result: "ok", timestamp: "10:02:31", duration: "212ms", output: "Checked 1 file. Fixed 1 file." },
    { id: "3", event: "PreToolUse", matcher: "Bash", command: "./scripts/audit-bash.sh", result: "blocked", timestamp: "10:03:02", duration: "8ms", output: "blocked by audit: command matches \\"rm -rf\\"" },
  ]}
/>`}>
  <HookEventLog
    events={[
      { id: "1", event: "PreToolUse", matcher: "Bash", command: "./scripts/audit-bash.sh", result: "ok", timestamp: "10:02:14", duration: "47ms" },
      { id: "2", event: "PostToolUse", matcher: "Write", command: "biome check --write", result: "ok", timestamp: "10:02:31", duration: "212ms", output: "Checked 1 file. Fixed 1 file." },
      { id: "3", event: "PreToolUse", matcher: "Bash", command: "./scripts/audit-bash.sh", result: "blocked", timestamp: "10:03:02", duration: "8ms", output: 'blocked by audit: command matches "rm -rf"' },
    ]}
  />

## Props

## Notes

- Each `HookEventEntry` has an `id`, `event`, `matcher`, `command`, `result`,
  and `timestamp`; `output` (a stdout/stderr snippet) and `duration` are
  optional.
- `result` is `ok` (success tone), `blocked` (warning tone), or `error`
  (destructive tone) — each maps to its own icon.
- The `output` snippet renders in a scrollable monospace preview capped in
  height.
- The `title` defaults to "Hook log"; the header shows a live event count.
- The component is presentational and holds no state — pass an already-ordered
  list of events.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { HookEventLog } from "@theokit/ui/hook-event-log";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/hook-event-log.json
```

---

# Overview

Source: https://docs.usetheo.dev/theokit/ui

The React component library your agent already needs — @theokit/ui, codename Violet Forge.

**`@theokit/ui`** is the React component library of the Theo ecosystem — the design
system codename **Violet Forge**, built for **AI-agent surfaces**: coding agents and
chat. It is the UI pillar of Theo. Because it ships as a normal React + Tailwind package,
you can adopt it standalone in any React app.

**82 components** (60 primitives + 22 composites) for the surfaces AI agents actually
need — the chat thread, the streaming assistant message, the tool-call timeline, the
model selector, the cost meter, the context-window indicator, the permission modal, the
build-log stream. You write product logic; the interface ships with you.

  `@theokit/ui` is Apache-2.0 and a community auxiliary of the ecosystem — usable
  standalone, not part of the paid funnel. It pairs with TheoKit and `@theokit/sdk` but
  runs on its own.

## Why `@theokit/ui`

Most component libraries optimize for marketing pages. `@theokit/ui` is built for the
surfaces where transparency, information density, and developer trust matter more than
hero sections.

- **Built for AI agents.** Primitives for skills, cron jobs, permission matrices, MCP
  servers, memory editing, hook config, audit logs, model cards, token-usage charts,
  sub-agent dispatch — the components a transparent agent UI actually needs.
- **Built on `@usetheo/ui`.** Generic primitives, auth surfaces, and cloud-ops composites
  (project cards, deployment rows, env-var editors, domain config, preview environments,
  rollback flows, metrics panels) live in
  [`@usetheo/ui`](https://github.com/usetheodev/usetheo-ui) — the community-standard layer
  `@theokit/ui` builds on. Need those too? Install `@usetheo/ui` alongside.
- **Themeable at runtime.** Ten built-in themes, swapped live via `<ThemeProvider />`, or
  define your own. See [Theming](/theokit/ui/theming).
- **shadcn-compatible registry.** Copy individual components into your project
  (`npx shadcn add …`) or install the whole package — your call.
- **Same Radix underneath as shadcn.** No foundational fork. React is the only required
  peer; Radix, CVA, cmdk, and lucide ship as dependencies.

## What you'd build

- **Coding assistant interface** — chat thread, streaming assistant, tool-call timeline,
  file diff viewer, permission matrix, sub-agent dispatch.
- **Agent dashboard** — run stats, session timeline, MCP server admin, cron scheduler,
  memory editor, audit log, model card, cost meter.
- **Internal AI tools** — quick-action chips, intent selector, system-prompt editor,
  skill manager, rule editor, lane board.

## Where to go next

---

# IntentSelector

Source: https://docs.usetheo.dev/theokit/ui/intent-selector

Chip dropdown for picking the agent's intent for the next turn — edit, plan, review

`IntentSelector` is a pill-shaped dropdown for choosing the agent's intent for the next
turn (for example edit, plan, or review). It renders a trigger chip and a Radix dropdown
menu of options, each with an optional description and a check mark on the active one.

<ComponentPreview name="intent-selector" code={`<IntentSelector
  value="edit"
  options={[
    { id: "edit", label: "Edit", description: "Apply code changes directly." },
    { id: "plan", label: "Plan", description: "Plan the change without executing." },
    { id: "review", label: "Review", description: "Analyze code and suggest improvements." },
  ]}
/>`}>
  <IntentSelector
    value="edit"
    options={[
      { id: "edit", label: "Edit", description: "Apply code changes directly." },
      { id: "plan", label: "Plan", description: "Plan the change without executing." },
      { id: "review", label: "Review", description: "Analyze code and suggest improvements." },
    ]}
  />

## Props

## Notes

- `value` is the id of the active option; if it does not match any option, the first option
  is used as the current selection.
- Each `IntentOption` has an `id`, a `label`, an optional `description` shown below the
  label in the menu, and an optional `icon` (falls back to a pencil).
- `onChange` fires with the selected option's `id`. The component is controlled — the
  consumer owns `value`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { IntentSelector } from "@theokit/ui/intent-selector";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/intent-selector.json
```

---

# LaneBoard

Source: https://docs.usetheo.dev/theokit/ui/lane-board

Kanban-style board with four fixed lanes — started, blocked, failed, finished.

`LaneBoard` is a kanban-style task board with four lanes matching the agent lane
event schema: `started`, `blocked`, `failed`, and `finished`. Each lane shows its
card count and either its cards or an empty placeholder; each card is a
machine-readable task snapshot the agent emits.

<ComponentPreview name="lane-board" code={`<LaneBoard
  title="Agent activity"
  lanes={[
    {
      state: "started",
      cards: [
        {
          id: "1",
          title: "Implement Tier 3 components",
          description: "8 new primitives for multi-agent flows.",
          footer: "agent · coder · 12m",
        },
      ],
    },
    {
      state: "blocked",
      cards: [
        {
          id: "3",
          title: "Publish @theokit/ui to npm",
          description: "Waiting for org access from owner.",
          footer: "blocked by paulo · 1h",
        },
      ],
    },
    {
      state: "failed",
      cards: [
        {
          id: "4",
          title: "Deploy preview env for PR #142",
          description: "k8s cluster unreachable.",
          footer: "agent · ops · 8s ago",
        },
      ],
    },
    {
      state: "finished",
      cards: [
        {
          id: "5",
          title: "Sprint 2 agent components",
          description: "9 primitives shipped.",
          footer: "agent · coder · 1h",
        },
      ],
    },
  ]}
/>`}>
  <LaneBoard
    title="Agent activity"
    lanes={[
      {
        state: "started",
        cards: [
          {
            id: "1",
            title: "Implement Tier 3 components",
            description: "8 new primitives for multi-agent flows.",
            footer: "agent · coder · 12m",
          },
        ],
      },
      {
        state: "blocked",
        cards: [
          {
            id: "3",
            title: "Publish @theokit/ui to npm",
            description: "Waiting for org access from owner.",
            footer: "blocked by paulo · 1h",
          },
        ],
      },
      {
        state: "failed",
        cards: [
          {
            id: "4",
            title: "Deploy preview env for PR #142",
            description: "k8s cluster unreachable.",
            footer: "agent · ops · 8s ago",
          },
        ],
      },
      {
        state: "finished",
        cards: [
          {
            id: "5",
            title: "Sprint 2 agent components",
            description: "9 primitives shipped.",
            footer: "agent · coder · 1h",
          },
        ],
      },
    ]}
  />

## Props

## Notes

- `lane.state` is one of `started`, `blocked`, `failed`, or `finished` — each lane
  gets its own header color and card tint.
- Each `LaneCard` has an `id` and `title`; `description` and `footer` are optional
  and accept any `ReactNode`.
- A lane with no cards renders an `empty` placeholder instead of a card list.
- The lanes grid is responsive: one column on small screens, up to four on large
  screens.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { LaneBoard } from "@theokit/ui/lane-board";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/lane-board.json
```

---

# For AI agents (llms.txt)

Source: https://docs.usetheo.dev/theokit/ui/llms-txt

Machine-readable ground truth of @theokit/ui for LLMs — package metadata, the full 82-component inventory with links, import paths, and conventions.

`@theokit/ui` ships an `llms.txt` file following the
[llmstxt.org convention](https://llmstxt.org/) — a single Markdown document that gives any
LLM (Claude, ChatGPT, Cursor, Copilot, a local model) the **factual ground truth** of this
package without crawling the whole site:

- Exact package name, current version, license, and module format
- The full component inventory — all 82 components (60 primitives + 22 composites) grouped
  by surface, each linking to its live reference page
- The canonical import paths (the barrel and per-component subpaths)
- The three guides (overview, getting started, theming)
- Conventions to follow (`data-slot`, `"use client"`, runtime theming) and anti-patterns
  to avoid (do NOT import generic/auth/cloud-ops from here — those live in `@usetheo/ui`;
  no fabricated props; ESM-only)

## Get it

```bash
curl https://docs.usetheo.dev/theokit/ui/llms.txt
```

Or link your AI assistant directly at
[`https://docs.usetheo.dev/theokit/ui/llms.txt`](https://docs.usetheo.dev/theokit/ui/llms.txt).

## Why

Point your coding assistant at it when you want it to stop hallucinating import paths or
component names — the file is generated from the real `@theokit/ui` inventory and the
shipped `.d.ts`, and every component links to a reference page whose props table is
auto-sourced from the package types. No fabricated APIs.

---

# MCPServerCard

Source: https://docs.usetheo.dev/theokit/ui/mcp-server-card

One MCP server entry showing connection status, the tools and resources it exposes, and inline restart / disconnect controls

`MCPServerCard` renders a single MCP server entry: its name and transport
endpoint, a connection-status badge (`connected`, `starting`, `degraded`,
`disconnected`), the tools it exposes, any resources, an optional diagnostic
message, and inline restart / disconnect controls. A degraded or disconnected
server still appears here with a recovery message, so failures stay visible.

<ComponentPreview name="mcp-server-card" code={`<MCPServerCard
  server={{
    id: "s1",
    name: "postgres",
    endpoint: "stdio: mcp-postgres",
    status: "connected",
    tools: ["query", "schema_inspect", "explain"],
    resources: ["postgres://localhost/dev"],
  }}
  onRestart={() => undefined}
  onDisconnect={() => undefined}
/>`}>
  <MCPServerCard
    server={{
      id: "s1",
      name: "postgres",
      endpoint: "stdio: mcp-postgres",
      status: "connected",
      tools: ["query", "schema_inspect", "explain"],
      resources: ["postgres://localhost/dev"],
    }}
  />

## Props

## Notes

- The export is `MCPServerCard` (acronym-cased), imported from
  `@theokit/ui/mcp-server-card`.
- Each `MCPServer` has an `id`, `name`, `endpoint`, `status`, and `tools`;
  `resources`, `message`, and `autoRestart` are optional.
- `status` drives the badge tone: `connected` (success), `starting` (primary,
  pulsing), `degraded` (warning), `disconnected` (destructive).
- A `message` renders as a warning-tinted diagnostic line — use it for
  rate-limit or crash reasons on degraded/disconnected servers.
- The Restart and Disconnect buttons render only when their handlers
  (`onRestart`, `onDisconnect`) are provided.
- Tools and resources render as chip lists only when non-empty.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { MCPServerCard } from "@theokit/ui/mcp-server-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/mcp-server-card.json
```

---

# MCPServerList

Source: https://docs.usetheo.dev/theokit/ui/mcp-server-list

Grouped MCP server inventory with status filter chips, surfacing degraded and disconnected servers prominently

`MCPServerList` renders an inventory of MCP servers as a responsive grid of
`MCPServerCard`s, with status filter chips (All, connected, starting, degraded,
disconnected) that carry live counts. It keeps degraded and disconnected servers
visible so the user can act on them, and optionally exposes an "Add server"
button plus per-card restart / disconnect handlers.

<ComponentPreview name="mcp-server-list" code={`<MCPServerList
  servers={[
    { id: "fs", name: "filesystem", endpoint: "stdio · npx @modelcontextprotocol/server-filesystem", status: "connected", tools: ["read_file", "write_file", "list_directory", "search_files"], resources: ["file:///workspace/**"] },
    { id: "pg", name: "postgres", endpoint: "stdio · npx @modelcontextprotocol/server-postgres", status: "connected", tools: ["query", "schema", "explain"] },
    { id: "github", name: "github", endpoint: "https://api.github.com", status: "degraded", tools: ["create_issue", "list_prs"], message: "rate limit reached — 0/5000 remaining (resets in 12m)" },
    { id: "linear", name: "linear", endpoint: "stdio · npx @linear/mcp-server", status: "disconnected", tools: [], message: "process exited with code 127 (binary not found)" },
    { id: "vault", name: "vault", endpoint: "https://vault.usetheo.dev:8200", status: "starting", tools: [] },
  ]}
  onAdd={() => undefined}
  onRestart={() => undefined}
  onDisconnect={() => undefined}
/>`}>
  <MCPServerList
    servers={[
      { id: "fs", name: "filesystem", endpoint: "stdio · npx @modelcontextprotocol/server-filesystem", status: "connected", tools: ["read_file", "write_file", "list_directory", "search_files"], resources: ["file:///workspace/**"] },
      { id: "pg", name: "postgres", endpoint: "stdio · npx @modelcontextprotocol/server-postgres", status: "connected", tools: ["query", "schema", "explain"] },
      { id: "github", name: "github", endpoint: "https://api.github.com", status: "degraded", tools: ["create_issue", "list_prs"], message: "rate limit reached — 0/5000 remaining (resets in 12m)" },
      { id: "linear", name: "linear", endpoint: "stdio · npx @linear/mcp-server", status: "disconnected", tools: [], message: "process exited with code 127 (binary not found)" },
      { id: "vault", name: "vault", endpoint: "https://vault.usetheo.dev:8200", status: "starting", tools: [] },
    ]}
  />

## Props

## Notes

- The export is `MCPServerList` (acronym-cased), imported from
  `@theokit/ui/mcp-server-list`. Each item is an `MCPServer` (same shape as
  `MCPServerCard`).
- The filter chips show a live count per status; a chip with a zero count is
  disabled. Selecting one filters the grid; "All" clears the filter.
- The "Add server" button renders only when `onAdd` is provided. `onRestart` and
  `onDisconnect` are threaded to each card only when passed.
- When the active filter matches no servers, an empty-state message is shown.
- `title` defaults to "MCP servers".

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { MCPServerList } from "@theokit/ui/mcp-server-list";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/mcp-server-list.json
```

---

# MemoryEditor

Source: https://docs.usetheo.dev/theokit/ui/memory-editor

Three-layer Markdown memory editor (global / project / session) mirroring Claude Code's CLAUDE.md hierarchy

`MemoryEditor` surfaces an agent's persistent memory as three separate Markdown
files — `global`, `project`, and `session` — each with its own path on disk. A tab
group switches which layer is being edited; the active layer's file path is shown
explicitly so users always know where the content lives.

<ComponentPreview name="memory-editor" code={`<MemoryEditor
  activeScope="project"
  layers={[
    {
      scope: "global",
      path: "~/.claude/CLAUDE.md",
      content: "# Theo global rules\\n\\n- Always respond in pt-BR.\\n- 95% confidence rule.\\n",
      modifiedAt: "1h ago",
    },
    {
      scope: "project",
      path: "./CLAUDE.md",
      content: "# theo-desktop\\n\\n- shadcn-style component library.\\n- Default theme: Violet Forge.\\n",
      modifiedAt: "12m ago",
    },
    {
      scope: "session",
      path: ".claude/session/2026-05-13.md",
      content: "User is currently iterating on the agent components sprint.",
      modifiedAt: "just now",
    },
  ]}
/>`}>
  <MemoryEditor
    activeScope="project"
    layers={[
      {
        scope: "global",
        path: "~/.claude/CLAUDE.md",
        content: "# Theo global rules\n\n- Always respond in pt-BR.\n- 95% confidence rule.\n",
        modifiedAt: "1h ago",
      },
      {
        scope: "project",
        path: "./CLAUDE.md",
        content: "# theo-desktop\n\n- shadcn-style component library.\n- Default theme: Violet Forge.\n",
        modifiedAt: "12m ago",
      },
      {
        scope: "session",
        path: ".claude/session/2026-05-13.md",
        content: "User is currently iterating on the agent components sprint.",
        modifiedAt: "just now",
      },
    ]}
  />

## Props

## Notes

- `MemoryScope` is one of `global`, `project`, or `session`. Each scope carries a
  short hint — global applies to every project, project is versioned and team-shared,
  session is wiped on exit.
- Switching tabs calls `onScopeChange`; editing the textarea calls
  `onContentChange(scope, next)`. The component is controlled — you own the `layers`
  array and the `activeScope`.
- Each layer's `path` is rendered in monospace, with the optional `modifiedAt` label
  next to it for transparency about where the content lives on disk.
- The scope tabs use `aria-pressed` to signal the active layer to assistive tech.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { MemoryEditor } from "@theokit/ui/memory-editor";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/memory-editor.json
```

---

# MentionMenu

Source: https://docs.usetheo.dev/theokit/ui/mention-menu

Keyboard-navigable popover for slash-command, @file, and #memory triggers inside a composer

`MentionMenu` is a keyboard-navigable popover for `/` command, `@` file, and `#` memory
triggers inside an agent composer. It is generic by design: the consumer decides which
items appear for each trigger and controls `open`. MentionMenu owns the visual presentation,
the selection highlight, and the Esc/Enter/Arrow-key behavior.

<ComponentPreview name="mention-menu" code={`<MentionMenu
  open
  trigger="/"
  items={[
    { id: "clear", label: "/clear", description: "Reset session" },
    { id: "checkpoint", label: "/checkpoint", description: "Save state" },
    { id: "undo", label: "/undo", description: "Undo last action" },
    { id: "help", label: "/help", description: "Show help" },
  ]}
  onSelect={() => {}}
  onClose={() => {}}
/>`}>
  <div className="relative h-72 w-full max-w-xl rounded-xl border border-fd-border p-4">
    <MentionMenu
      open
      trigger="/"
      items={[
        { id: "clear", label: "/clear", description: "Reset session" },
        { id: "checkpoint", label: "/checkpoint", description: "Save state" },
        { id: "undo", label: "/undo", description: "Undo last action" },
        { id: "help", label: "/help", description: "Show help" },
      ]}
    />
  </div>

## Props

## Notes

- `open` is controlled by the consumer (usually the composer). When `open` is false the
  component renders nothing.
- `trigger` (`/`, `@`, `#`) drives the default title and header icon — Commands, Files,
  Memories — each overridable via `title`.
- `items` are already filtered by the consumer; each has an `id`, a `label`, an optional
  `description`, and an optional `icon`. `emptyLabel` shows when `items` is empty.
- Keyboard: ArrowUp/ArrowDown move the highlight, Enter fires `onSelect` for the active
  item, Esc fires `onClose`. Mouse-down is prevented so the composer keeps focus.
- The panel is positioned `absolute bottom-full left-0`, anchored to its nearest positioned
  ancestor — typically the composer wrapper (shown here inside a `relative` container).

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { MentionMenu } from "@theokit/ui/mention-menu";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/mention-menu.json
```

---

# ModelCard

Source: https://docs.usetheo.dev/theokit/ui/model-card

Full info card for a model — vendor, context window, output cap, pricing, capabilities, and knowledge cutoff

`ModelCard` shows everything about a single LLM: vendor, context window, max output,
input/output pricing, capability chips, and knowledge cutoff. It is the card used in a
"switch model" surface. When `onSelect` is passed it renders as a selectable button;
otherwise it is a plain article.

<ComponentPreview name="model-card" code={`<ModelCard
  model={{
    id: "opus-4-7",
    name: "Opus 4.7",
    vendor: "Anthropic",
    tag: "smart",
    contextWindow: 1000000,
    maxOutput: 32000,
    pricePerMInput: 15,
    pricePerMOutput: 75,
    cutoff: "Jan 2026",
    description: "Top capability, best reasoning, longest context.",
    capabilities: [
      { id: "vision", label: "Vision", enabled: true },
      { id: "tools", label: "Tool use", enabled: true },
      { id: "reasoning", label: "Reasoning", enabled: true },
      { id: "ft", label: "Fine-tuning", enabled: false },
    ],
  }}
  selected
/>`}>
  <ModelCard
    model={{
      id: "opus-4-7",
      name: "Opus 4.7",
      vendor: "Anthropic",
      tag: "smart",
      contextWindow: 1000000,
      maxOutput: 32000,
      pricePerMInput: 15,
      pricePerMOutput: 75,
      cutoff: "Jan 2026",
      description: "Top capability, best reasoning, longest context.",
      capabilities: [
        { id: "vision", label: "Vision", enabled: true },
        { id: "tools", label: "Tool use", enabled: true },
        { id: "reasoning", label: "Reasoning", enabled: true },
        { id: "ft", label: "Fine-tuning", enabled: false },
      ],
    }}
    selected
  />

## Props

## Notes

- `contextWindow` and `maxOutput` are raw token counts — the card formats them
  compactly (`1M tok`, `32k tok`). Pricing is USD per million tokens and only renders
  when `pricePerMInput` / `pricePerMOutput` are set.
- `capabilities` render as chips; enabled ones are highlighted, disabled ones are
  struck through. Each may carry its own `icon`, falling back to a wrench.
- Passing `onSelect` turns the card into a `<button>` with `aria-pressed`; `selected`
  adds the violet ring. Without `onSelect` it is a non-interactive `<article>`.
- `modelCapabilityPresets` (exported alongside `ModelCard`) provides ready-made flags
  for vision, tools, reasoning, fine-tuning, and multimodal.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ModelCard } from "@theokit/ui/model-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/model-card.json
```

---

# ModelSelector

Source: https://docs.usetheo.dev/theokit/ui/model-selector

Chip dropdown for picking the active LLM — a pill with a violet dot, label, and chevron

`ModelSelector` is a compact pill that opens a dropdown of models. The trigger shows a
violet dot, the current model's label, and a chevron; the menu lists each option with
an optional vendor hint and tag, and a check on the active one. The dropdown is built
on Radix Menu.

<ComponentPreview name="model-selector" code={`<ModelSelector
  value="sonnet-4-6"
  options={[
    { id: "opus-4-7", label: "Opus 4.7", vendor: "Anthropic", tag: "smart" },
    { id: "sonnet-4-6", label: "Sonnet 4.6", vendor: "Anthropic", tag: "default" },
    { id: "haiku-4-5", label: "Haiku 4.5", vendor: "Anthropic", tag: "fast" },
    { id: "gpt-5-4", label: "GPT-5.4", vendor: "OpenAI" },
    { id: "gemini-2-5", label: "Gemini 2.5", vendor: "Google" },
  ]}
/>`}>
  <ModelSelector
    value="sonnet-4-6"
    options={[
      { id: "opus-4-7", label: "Opus 4.7", vendor: "Anthropic", tag: "smart" },
      { id: "sonnet-4-6", label: "Sonnet 4.6", vendor: "Anthropic", tag: "default" },
      { id: "haiku-4-5", label: "Haiku 4.5", vendor: "Anthropic", tag: "fast" },
      { id: "gpt-5-4", label: "GPT-5.4", vendor: "OpenAI" },
      { id: "gemini-2-5", label: "Gemini 2.5", vendor: "Google" },
    ]}
  />

## Props

## Notes

- `value` is the id of the active option; the trigger falls back to the first option
  if `value` matches none. Selecting an item calls `onChange(id)` — the component is
  controlled and holds no selection state of its own.
- Each `ModelOption` may carry an optional `vendor` (shown small under the label) and a
  `tag` (`default`, `fast`, `smart`, …). A `smart` tag adds a sparkle icon.
- The menu uses Radix `DropdownMenu` with a portal, so it escapes overflow-clipped
  containers and gets keyboard navigation and focus management for free.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ModelSelector } from "@theokit/ui/model-selector";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/model-selector.json
```

---

# MultiSelectPrompt

Source: https://docs.usetheo.dev/theokit/ui/multi-select-prompt

Multi-select ask-the-user card for agent surfaces — the checkbox sibling of ChoicePrompt with number-key toggles, an Other field, and a preview pane

`MultiSelectPrompt` is the checkbox sibling of `ChoicePrompt`: the same question, header
chip, option shape, `1`..`9` number-key toggles, injectable free-text Other, and
side-by-side preview — but the user may select any number of options.

It renders one question at a time; sequencing is the consumer's responsibility. Selection
is controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).

<ComponentPreview name="multi-select-prompt" code={`<MultiSelectPrompt
  question="Which capacity options should we enable?"
  badge="Scaling"
  description="Select any that apply."
  options={[
    { value: "auto", label: "Auto-scaling", description: "Scale on demand" },
    { value: "spot", label: "Spot instances", description: "Cheaper, interruptible" },
    { value: "reserved", label: "Reserved", description: "Committed capacity" },
  ]}
  onConfirm={(r) => console.log(r)}
  onCancel={() => {}}
/>`}>
  <PreviewMultiSelectPrompt
    question="Which capacity options should we enable?"
    badge="Scaling"
    description="Select any that apply."
    options={[
      { value: "auto", label: "Auto-scaling", description: "Scale on demand" },
      { value: "spot", label: "Spot instances", description: "Cheaper, interruptible" },
      { value: "reserved", label: "Reserved", description: "Committed capacity" },
    ]}
  />

## Props

## Notes

- `minSelected` (default 1) is the number of selections required before Confirm enables.
- When any option has a `preview`, the card renders a preview pane that stacks the content
  of every currently selected option.
- `allowOther` injects a free-text Other row; when it is checked, its text is surfaced on
  `onConfirm` as `otherText`.
- `enableKeyboardShortcuts` (default true) binds `1`..`9` to toggle the first nine
  options; digits typed into the Other input are never hijacked. `showNumbers` controls
  the hint chips and defaults to the shortcut flag.
- `onConfirm` receives `{ values }` — or `{ values, otherText }` when the Other option is
  among the selected values.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { MultiSelectPrompt } from "@theokit/ui/multi-select-prompt";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/multi-select-prompt.json
```

---

# PermissionMatrix

Source: https://docs.usetheo.dev/theokit/ui/permission-matrix

Tool × path × decision grid for fine-grained agent access control — click a decision pill to cycle Allow, Ask, Deny

`PermissionMatrix` is a tool × path × decision grid for fine-grained access
control — the "permissions" tab of an agent's settings. Each `PermissionRule` is
one row; clicking its decision pill cycles Allow -> Ask -> Deny. When `onAdd` and
a non-empty `toolOptions` are provided, a form row lets the user append rules;
`onRemove` wires per-row deletion.

<ComponentPreview name="permission-matrix" code={`<PermissionMatrix
  rules={[
    { id: "1", tool: "Read", path: "**/*", decision: "allow" },
    { id: "2", tool: "Write", path: "src/**/*.ts", decision: "allow", note: "Codebase only" },
    { id: "3", tool: "Write", path: ".env*", decision: "deny", note: "Never touch env files" },
    { id: "4", tool: "Bash", path: "rm -rf*", decision: "deny" },
    { id: "5", tool: "Bash", path: "*", decision: "ask" },
    { id: "6", tool: "WebFetch", path: "*", decision: "deny" },
  ]}
/>`}>
  <PermissionMatrix
    rules={[
      { id: "1", tool: "Read", path: "**/*", decision: "allow" },
      { id: "2", tool: "Write", path: "src/**/*.ts", decision: "allow", note: "Codebase only" },
      { id: "3", tool: "Write", path: ".env*", decision: "deny", note: "Never touch env files" },
      { id: "4", tool: "Bash", path: "rm -rf*", decision: "deny" },
      { id: "5", tool: "Bash", path: "*", decision: "ask" },
      { id: "6", tool: "WebFetch", path: "*", decision: "deny" },
    ]}
  />

## Props

## Notes

- Each `PermissionRule` has an `id`, a `tool` (`*` for any), a `path` glob (`*`
  for any), a `decision` (`allow`, `ask`, `deny`), and an optional `note`.
- The decision pill cycles Allow -> Ask -> Deny on click, calling
  `onDecisionChange`. Without that handler the pill is non-interactive.
- The add form renders only when `onAdd` is provided AND `toolOptions` has at
  least one entry; the per-row remove button renders only with `onRemove`. Omit
  all handlers for a read-only matrix.
- With no rules, an empty-state row explains the agent falls back to the default
  policy.
- Despite rendering inputs and selects, this ships as a primitive — a single
  self-contained file with no transitive `@theokit/ui` dependencies.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { PermissionMatrix } from "@theokit/ui/permission-matrix";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/permission-matrix.json
```

---

# PermissionModal

Source: https://docs.usetheo.dev/theokit/ui/permission-modal

Local-files access prompt built on Dialog — Cancel, Always allow, and Allow once, with the path shown in the title

`PermissionModal` is a local-files access prompt built on `Dialog`. It offers
three actions — Cancel (denied), Always allow, and Allow once — and shows the
requested path in the title (not hidden in the body) with the requested
operations listed inline. It is a controlled, portalled dialog: it does not
auto-close on a decision, and dismissing it via Esc or an overlay click is
treated as `"denied"` so the caller never sees a silent close.

Because the modal portals over the page and requires `onOpenChange` / `onDecide`
callbacks, drive it from state rather than rendering it inline:

```tsx
import { PermissionModal } from "@theokit/ui/permission-modal";
import { useState } from "react";

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button type="button" onClick={() => setOpen(true)}>
        Open permission modal
      </button>
      <PermissionModal
        open={open}
        onOpenChange={setOpen}
        request={{
          path: "C:\\Users\\AlfredoAraujo\\Downloads\\capturas",
          operations: ["read", "write", "delete"],
        }}
        onDecide={(decision) => {
          console.warn("decision", decision);
          setOpen(false);
        }}
      />
    </>
  );
}
```

## Props

## Notes

- `request` is a `PermissionRequest` — a `path` and a list of `operations`
  (`read`, `write`, `delete`).
- `onDecide` fires with `"denied"`, `"always_allowed"`, or `"allowed_once"`. The
  modal does NOT auto-close — the caller decides whether a decision dismisses it.
- Closing without an explicit button (Esc / overlay click) reports `"denied"` so
  a dismissal is never silent.
- All visible text is overridable: `title`, `description`, `operationLabels`
  (per-operation verbs), and `labels` (button text) — defaults are English. The
  package also exports `defaultOperationLabels`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { PermissionModal } from "@theokit/ui/permission-modal";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/permission-modal.json
```

---

# PreviewPanel

Source: https://docs.usetheo.dev/theokit/ui/preview-panel

Browser preview with URL controls and an integrated logs slot in a single card

`PreviewPanel` wraps a preview surface with browser-style controls (URL, back,
forward, reload) and an optional logs section below it — so a Code workspace can
show a live dev-server URL and its build output side by side without switching
contexts.

<ComponentPreview name="preview-panel" code={`<PreviewPanel
  className="h-[520px] w-full max-w-3xl"
  url="http://localhost:5173/"
  onReload={() => undefined}
  content={
    <div className="grid h-full place-items-center bg-muted/30 font-mono text-muted-foreground">
      [preview iframe slot]
    </div>
  }
  logsSlot={
    <BuildLogStream
      filterable={false}
      height="160px"
      lines={[
        { id: "1", timestamp: "10:01:32", level: "info", source: "vite", message: "ready in 312ms" },
        { id: "2", timestamp: "10:01:44", level: "success", source: "tsc", message: "types ok" },
        { id: "3", timestamp: "10:01:58", level: "info", source: "vite", message: "hmr update" },
      ]}
    />
  }
/>`}>
  <PreviewPanel
    className="h-[520px] w-full max-w-3xl"
    url="http://localhost:5173/"
    content={
      <div className="grid h-full place-items-center bg-muted/30 font-mono text-muted-foreground">
        [preview iframe slot]
      </div>
    }
    logsSlot={
      <BuildLogStream
        filterable={false}
        height="160px"
        lines={[
          { id: "1", timestamp: "10:01:32", level: "info", source: "vite", message: "ready in 312ms" },
          { id: "2", timestamp: "10:01:44", level: "success", source: "tsc", message: "types ok" },
          { id: "3", timestamp: "10:01:58", level: "info", source: "vite", message: "hmr update" },
        ]}
      />
    }
  />

## Props

## Notes

- `content` is the required preview body — typically an `<iframe>`. `PreviewPanel`
  does not render the iframe for you; you pass whatever should fill the frame.
- The URL bar and navigation buttons come from the built-in `BrowserControls`
  primitive; each control only wires up when its callback (`onUrlChange`, `onBack`,
  `onForward`, `onReload`) is provided.
- `logsSlot` is optional and renders in a scrollable region (max height ~12rem)
  below the preview — pair it with `BuildLogStream` for dev-server output.
- This is a composite — it depends on the `BrowserControls` primitive.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { PreviewPanel } from "@theokit/ui/preview-panel";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/preview-panel.json
```

---

# ProgressChecklist

Source: https://docs.usetheo.dev/theokit/ui/progress-checklist

Right-inspector checklist of task steps with status dots and optional progress bars.

`ProgressChecklist` renders a vertical list of task steps, each with a status dot,
a label, and — for running steps that carry a `progress` value — an optional
progress bar. It suits a right-inspector panel that tracks a task's steps as they
move from pending to done.

<ComponentPreview name="progress-checklist" code={`<ProgressChecklist
  className="max-w-sm"
  title="Progresso"
  steps={[
    { id: "1", label: "Criar subpastas na pasta capturas", status: "done" },
    {
      id: "2",
      label: "Mover imagens para subpastas corretas",
      status: "running",
      progress: 0.4,
    },
    { id: "3", label: "Verificar resultado final", status: "pending" },
    { id: "4", label: "Limpeza opcional", status: "skipped" },
  ]}
/>`}>
  <ProgressChecklist
    className="max-w-sm"
    title="Progresso"
    steps={[
      { id: "1", label: "Criar subpastas na pasta capturas", status: "done" },
      {
        id: "2",
        label: "Mover imagens para subpastas corretas",
        status: "running",
        progress: 0.4,
      },
      { id: "3", label: "Verificar resultado final", status: "pending" },
      { id: "4", label: "Limpeza opcional", status: "skipped" },
    ]}
  />

## Props

## Notes

- Each `step.status` is one of `pending`, `running`, `done`, or `skipped`. Done and
  skipped steps show a strikethrough label.
- Running steps spin their status icon.
- `showProgressBars` defaults to `true`; a progress bar renders only for a running
  step that also carries a `progress` value between 0 and 1.
- `title` is optional; without it the header is omitted.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ProgressChecklist } from "@theokit/ui/progress-checklist";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/progress-checklist.json
```

---

# ProjectSwitcher

Source: https://docs.usetheo.dev/theokit/ui/project-switcher

Sidebar header for a code agent app — active workspace, branch, status dot, and picker hint

`ProjectSwitcher` anchors the current project context in a code agent's sidebar
header. It shows the active workspace (folder), an optional git branch, a status
dot, and a brand tile. When you pass `onClick` it becomes a focusable button with a
`ChevronsUpDown` hint for opening a project picker; without it, it renders as a
static, non-interactive header.

<ComponentPreview name="project-switcher" code={`<ProjectSwitcher
  workspace="acme-web"
  branch="claude/alignment-grid"
  status="running"
  onClick={() => undefined}
/>`}>
  <ProjectSwitcher
    workspace="acme-web"
    branch="claude/alignment-grid"
    status="running"
  />

## Props

## Notes

- `status` is one of `idle`, `running` (pulses green), `error`, or `offline`, and
  defaults to `idle`. The dot carries an `aria-label` describing the state.
- `brand` is the letter/icon in the violet tile. When omitted, it defaults to the
  uppercased first character of a string `workspace` (falls back to a dot).
- `branch` is optional and renders inline with a `GitBranch` icon.
- Passing `onClick` renders an interactive `<button>` with a picker chevron and
  focus ring; omitting it renders a static `<div>` (no chevron, not focusable).

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ProjectSwitcher } from "@theokit/ui/project-switcher";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/project-switcher.json
```

---

# QuickActionChips

Source: https://docs.usetheo.dev/theokit/ui/quick-action-chips

Row of intent chips below a hero composer — one chip can be highlighted as the suggested next action

`QuickActionChips` renders a wrapping row of intent chips, typically placed below a hero
composer (as on Chat Home) or in the Files panel. Each chip has a label and an optional
icon; one chip can be marked `primary` to highlight it as the suggested next action.

<ComponentPreview name="quick-action-chips" code={`<QuickActionChips
  actions={[
    { id: "write", label: "Escrever" },
    { id: "learn", label: "Aprender" },
    { id: "code", label: "Código" },
    { id: "design", label: "Design" },
    { id: "personal", label: "Assuntos pessoais" },
    { id: "auto", label: "Escolha do Theo", primary: true },
  ]}
/>`}>
  <QuickActionChips
    actions={[
      { id: "write", label: "Escrever" },
      { id: "learn", label: "Aprender" },
      { id: "code", label: "Código" },
      { id: "design", label: "Design" },
      { id: "personal", label: "Assuntos pessoais" },
      { id: "auto", label: "Escolha do Theo", primary: true },
    ]}
  />

## Props

## Notes

- Each `QuickAction` has an `id`, a `label` (any `ReactNode`), an optional `icon`, and an
  optional `primary` flag.
- A `primary` chip is filled with the primary color and gets a glow on hover; the rest are
  outlined and highlight on hover.
- `onSelect` fires with the chip's `id` when clicked. The chips are stateless buttons.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { QuickActionChips } from "@theokit/ui/quick-action-chips";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/quick-action-chips.json
```

---

# RecentFoldersList

Source: https://docs.usetheo.dev/theokit/ui/recent-folders-list

Recently-used folders for the Files picker — folder icon, name, path, highlighted active row.

`RecentFoldersList` renders a stack of recently-used folders for a Files picker. Each row
shows a folder icon, the folder name, and its path in smaller muted text; the active row is
highlighted. Clicking a row fires `onSelect` with the folder id.

<ComponentPreview name="recent-folders-list" code={`<RecentFoldersList
  className="max-w-md"
  folders={[
    { id: "1", name: "Downloads", path: "/Users/Alfredo/Downloads" },
    { id: "2", name: "Documents/Projects", path: "/Users/Alfredo/Documents/Projects", active: true },
    { id: "3", name: "Desktop/Screenshots", path: "/Users/Alfredo/Desktop/Screenshots" },
  ]}
  onSelect={() => undefined}
/>`}>
  <RecentFoldersList
    className="max-w-md"
    folders={[
      { id: "1", name: "Downloads", path: "/Users/Alfredo/Downloads" },
      { id: "2", name: "Documents/Projects", path: "/Users/Alfredo/Documents/Projects", active: true },
      { id: "3", name: "Desktop/Screenshots", path: "/Users/Alfredo/Desktop/Screenshots" },
    ]}
  />

## Props

## Notes

- The row whose `active` flag is true is highlighted with a violet background; selection is
  caller-controlled.
- `onSelect` receives the folder id when a row is clicked.
- `title` defaults to `"Recent folders"`; pass `null` (or your own node) to change or hide
  the header.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { RecentFoldersList } from "@theokit/ui/recent-folders-list";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/recent-folders-list.json
```

---

# RuleCard

Source: https://docs.usetheo.dev/theokit/ui/rule-card

Single Rule row in the Rules list — title, scope/state badges, tags, a truncated body preview, and edit/toggle/delete actions

`RuleCard` renders one Rule row: its title, scope and state badges, optional tag
chips, a two-line body preview, and edit/toggle/delete actions in the corner. Reach
for it to build a Rules list where each behavior instruction is a scannable card.

<ComponentPreview name="rule-card" code={`<RuleCard
  rule={{
    id: "1",
    title: "Always write tests before fixes",
    body: "When fixing a bug, write a failing regression test first, then the fix.",
    scope: "global",
    state: "enabled",
    tags: ["testing", "process"],
    updatedAt: "2d ago",
  }}
/>`}>
  <RuleCard
    rule={{
      id: "1",
      title: "Always write tests before fixes",
      body: "When fixing a bug, write a failing regression test first, then the fix.",
      scope: "global",
      state: "enabled",
      tags: ["testing", "process"],
      updatedAt: "2d ago",
    }}
  />

## Props

## Notes

- `rule.scope` is `global` or `project`, each with its own badge color.
- The toggle chip (`Enabled` / `Disabled`) renders only when `onToggle` is provided;
  the delete icon renders only when `onDelete` is provided.
- `onEdit` falls back to `onSelect` when omitted, so the edit pencil still works with a
  single handler.
- A `disabled` rule renders at reduced opacity. `rule.tags` and `rule.updatedAt` are
  optional and shown in the footer when present.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { RuleCard } from "@theokit/ui/rule-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/rule-card.json
```

---

# RuleEditor

Source: https://docs.usetheo.dev/theokit/ui/rule-editor

Form for creating or editing a Rule — the behavior instruction injected into the system prompt

`RuleEditor` is the form for authoring a Rule: a title, a markdown body, a scope
(global or project), tags, active modes, and an enabled switch. Reach for it when a
user needs to create or edit a behavior instruction that gets injected into the
agent's system prompt.

<ComponentPreview name="rule-editor" code={`<RuleEditor
  initial={{
    id: "r1",
    title: "Always write tests before fixes",
    body: "When fixing a bug, first write a failing regression test, then the fix.",
    scope: "global",
    state: "enabled",
    tags: ["testing", "process"],
  }}
  onSave={(draft) => save(draft)}
/>`}>
  <RuleEditor
    initial={{
      id: "r1",
      title: "Always write tests before fixes",
      body: "When fixing a bug, first write a failing regression test, then the fix.",
      scope: "global",
      state: "enabled",
      tags: ["testing", "process"],
    }}
  />

## Props

## Notes

- `onSave` is required and receives a `RuleDraft` (title, body, scope, state, tags,
  and modes). Save is disabled until both title and body are non-empty.
- The `Cancel` button renders only when `onCancel` is provided; the `Delete` button
  only when `onDelete` is provided.
- The submit label is `Save changes` when `initial.id` is set, otherwise `Create rule`.
- Form state seeds from `initial` once on mount. To reset when editing a different
  rule, use the React `key` pattern at the call site: `<RuleEditor key={rule.id}
  initial={rule} ... />`.
- Tags are entered comma-separated and split on save. Active modes default to empty,
  meaning the rule applies to every mode.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { RuleEditor } from "@theokit/ui/rule-editor";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/rule-editor.json
```

---

# RunStats

Source: https://docs.usetheo.dev/theokit/ui/run-stats

Inline metric row shown after an agent run — duration, tokens, and files changed

`RunStats` is a muted, bullet-separated row of run metrics: a duration, a token count,
and a files-changed count. Every field is optional — the row skips any entry you do not
pass, so it works for a full run summary or a single stat.

<ComponentPreview name="run-stats" code={`<RunStats duration="24s" tokens="35.7k" filesChanged={3} />`}>

## Props

## Notes

- `duration` and `tokens` are pre-formatted strings you supply (e.g. `"1m 12s"`,
  `"35.7k"`); the component appends the `tokens` label and a `files` suffix but does no
  number formatting itself.
- `filesChanged` is a number and only renders when defined — including `0`.
- Each present field gets its own icon (clock, coins, file-edit); omitting a field
  removes both its icon and its separator.
- Purely presentational — it renders in monospace and holds no state.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { RunStats } from "@theokit/ui/run-stats";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/run-stats.json
```

---

# RunStatusPill

Source: https://docs.usetheo.dev/theokit/ui/run-status-pill

Compact status indicator for Run/Task lifecycle states — icon, label, and optional detail

`RunStatusPill` renders a small pill that reports the state of a run or task:
`queued`, `in_progress`, `finished`, `error`, `cancelled`, or `interrupted`. Each state
has its own icon, label, and color. Reach for it in chat headers, timeline rows, or table
cells where a run's status needs a glanceable badge.

<ComponentPreview name="run-status-pill" code={`<RunStatusPill status="finished" detail="3.2s · 1.4k tokens" />`}>

## Props

## Notes

- `status` is one of `queued`, `in_progress`, `finished`, `error`, `cancelled`,
  `interrupted`. `finished` renders as "Done" and `interrupted` maps to the warning tone.
- The `in_progress` state uses a spinning `Loader2` icon; every other state uses a static
  icon.
- `detail` appends a muted secondary string after a `·` separator; it is omitted when
  empty.
- The pill renders as `<span role="status" aria-live="polite">` so it stays valid inside
  phrasing content and announces status changes to screen readers.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { RunStatusPill } from "@theokit/ui/run-status-pill";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/run-status-pill.json
```

---

# RunningTasksPanel

Source: https://docs.usetheo.dev/theokit/ui/running-tasks-panel

Split list of running vs completed tasks, grouped by status with a source label.

`RunningTasksPanel` splits a list of tasks into a **Running** group and a
**Completed** group (anything not running), giving operational visibility into
what an agent is executing versus what already finished. Each row shows a status
icon, a source icon, the task label, and the source name.

<ComponentPreview name="running-tasks-panel" code={`<RunningTasksPanel
  className="max-w-sm"
  tasks={[
    { id: "1", source: "agent", label: "Verify constraint solver convergence", status: "running" },
    { id: "2", source: "bash", label: "npm run dev (background)", status: "running" },
    { id: "3", source: "bash", label: "npx tsc --noEmit", status: "completed" },
    { id: "4", source: "tool", label: "Lint completed", status: "completed" },
    { id: "5", source: "bash", label: "vitest run", status: "failed" },
  ]}
/>`}>
  <RunningTasksPanel
    className="max-w-sm"
    tasks={[
      { id: "1", source: "agent", label: "Verify constraint solver convergence", status: "running" },
      { id: "2", source: "bash", label: "npm run dev (background)", status: "running" },
      { id: "3", source: "bash", label: "npx tsc --noEmit", status: "completed" },
      { id: "4", source: "tool", label: "Lint completed", status: "completed" },
      { id: "5", source: "bash", label: "vitest run", status: "failed" },
    ]}
  />

## Props

## Notes

- `task.status` is `running`, `completed`, or `failed`. Running tasks land in the
  Running group; completed and failed land in the Completed group.
- Running rows show a spinner, completed rows a check, and failed rows a red dot.
- `task.source` is `agent`, `bash`, or `tool` — it picks the source icon and the
  uppercase source label.
- The Completed group is hidden entirely when no task has finished.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { RunningTasksPanel } from "@theokit/ui/running-tasks-panel";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/running-tasks-panel.json
```

---

# SessionListItem

Source: https://docs.usetheo.dev/theokit/ui/session-list-item

Single sidebar row for a code-agent session — status dot, mode pill, and timestamp.

`SessionListItem` is one row in a code-agent app's sidebar Sessions list. Richer
than a generic sidebar item, it shows a status dot that maps to the agent run
state (and pulses while running), an optional mode pill (chat / code / infra), a
relative timestamp, and an optional unread count.

<ComponentPreview name="session-list-item" code={`<SessionListItem
  title="Build the alignment grid demo"
  status="running"
  mode="code"
  timestamp="now"
  active
/>`}>
  <SessionListItem
    title="Build the alignment grid demo"
    status="running"
    mode="code"
    timestamp="now"
    active
  />

## Props

## Notes

- `status` is one of `running`, `queued`, `completed`, `failed`, or `cancelled`.
  The running dot pulses; the color communicates the state (with an accessible
  label).
- `mode` is optional — `chat`, `code`, or `infra` — and renders as a small colored
  pill.
- `active` sets `aria-current` and highlights the row as the selected session.
- `unread` renders a badge (capped at `99+`) only when greater than zero.
- The component renders as a native `<button>`; pass `onClick` to make it navigate.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SessionListItem } from "@theokit/ui/session-list-item";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/session-list-item.json
```

---

# SessionTimeline

Source: https://docs.usetheo.dev/theokit/ui/session-timeline

Historical list of past agent sessions with per-row tokens, cost, duration, and status.

`SessionTimeline` shows a historical list of past agent sessions. Each row carries
a title, a status pill, a start time and optional duration, and optional model,
token, cost, and message-count metadata. When `onOpen` is supplied, rows become
buttons that open the full session.

<ComponentPreview name="session-timeline" code={`<SessionTimeline
  className="max-w-3xl"
  sessions={[
    {
      id: "1",
      title: "Build the agent components sprint 1+2",
      startedAt: "Today 13:15",
      duration: "47m",
      status: "active",
      model: "Opus 4.7",
      tokens: "184k",
      cost: 5.42,
      messageCount: 22,
    },
    {
      id: "2",
      title: "Migrate theo-desktop to Geist tokens",
      startedAt: "Today 11:02",
      duration: "1h 12m",
      status: "completed",
      model: "Sonnet 4.6",
      tokens: "92k",
      cost: 1.18,
      messageCount: 14,
    },
    {
      id: "3",
      title: "Investigate deploy regression in theo-api",
      startedAt: "Yesterday 16:24",
      duration: "23m",
      status: "failed",
      model: "Opus 4.7",
      tokens: "61k",
      cost: 2.04,
      messageCount: 9,
    },
  ]}
/>`}>
  <SessionTimeline
    className="max-w-3xl"
    sessions={[
      {
        id: "1",
        title: "Build the agent components sprint 1+2",
        startedAt: "Today 13:15",
        duration: "47m",
        status: "active",
        model: "Opus 4.7",
        tokens: "184k",
        cost: 5.42,
        messageCount: 22,
      },
      {
        id: "2",
        title: "Migrate theo-desktop to Geist tokens",
        startedAt: "Today 11:02",
        duration: "1h 12m",
        status: "completed",
        model: "Sonnet 4.6",
        tokens: "92k",
        cost: 1.18,
        messageCount: 14,
      },
      {
        id: "3",
        title: "Investigate deploy regression in theo-api",
        startedAt: "Yesterday 16:24",
        duration: "23m",
        status: "failed",
        model: "Opus 4.7",
        tokens: "61k",
        cost: 2.04,
        messageCount: 9,
      },
    ]}
  />

## Props

## Notes

- Each `session.status` is `active`, `completed`, `failed`, or `aborted` — it colors
  the status pill.
- Only `id`, `title`, `startedAt`, and `status` are required per session; `duration`,
  `model`, `tokens`, `cost`, and `messageCount` are optional and shown when present.
- `title` defaults to `"Recent sessions"` and shows a live session count in the
  header; pass `null` to hide the header.
- When `onOpen` is provided, each row becomes a button and a chevron appears; an
  empty list renders a "No sessions yet." placeholder.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SessionTimeline } from "@theokit/ui/session-timeline";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/session-timeline.json
```

---

# SkillCard

Source: https://docs.usetheo.dev/theokit/ui/skill-card

Single skill entry showing what it does, where it came from, and which tools it needs — with an enable/disable toggle

`SkillCard` renders one skill: its name, a source icon and label, an optional
description, allowed-tools chips, and trigger chips. Reach for it to show a skill in
an inventory and let the user toggle it on or off for the current session.

<ComponentPreview name="skill-card" code={`<SkillCard
  skill={{
    id: "sk1",
    name: "diff-explainer",
    description: "Explain a diff in plain English with intent + risk.",
    source: "user",
    state: "enabled",
    allowedTools: ["Read", "Grep"],
    triggers: ["explain diff"],
  }}
/>`}>
  <SkillCard
    skill={{
      id: "sk1",
      name: "diff-explainer",
      description: "Explain a diff in plain English with intent + risk.",
      source: "user",
      state: "enabled",
      allowedTools: ["Read", "Grep"],
      triggers: ["explain diff"],
    }}
  />

## Props

## Notes

- `skill.source` is one of `builtin`, `project`, `user`, or `plugin` — each maps to its
  own icon and label.
- The enable/disable toggle renders only when `onToggle` is provided; `skill.state`
  defaults to `enabled`, and a disabled card renders at reduced opacity.
- `skill.allowedTools` and `skill.triggers` are optional; their chip rows appear only
  when the arrays are non-empty.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SkillCard } from "@theokit/ui/skill-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/skill-card.json
```

---

# SkillEditor

Source: https://docs.usetheo.dev/theokit/ui/skill-editor

Form for creating or editing a Skill — name, description, instructions, source, allowed tools, triggers, and modes

`SkillEditor` is the form for authoring a Skill: a kebab-case name, a description, an
instructions sub-prompt, a source, allowed tools, triggers, active modes, and an
enabled switch. Reach for it when a user needs to create or edit a skill the agent can
invoke.

<ComponentPreview name="skill-editor" code={`<SkillEditor
  initial={{
    id: "s1",
    name: "diff-explainer",
    description: "Explain a diff in plain English.",
    instructions:
      "When invoked, read the diff via Read or Grep and produce a concise summary of intent + risk.",
    source: "user",
    state: "enabled",
    allowedTools: ["Read", "Grep"],
    triggers: ["explain diff", "summarize change"],
  }}
  onSave={(draft) => save(draft)}
/>`}>
  <SkillEditor
    initial={{
      id: "s1",
      name: "diff-explainer",
      description: "Explain a diff in plain English.",
      instructions:
        "When invoked, read the diff via Read or Grep and produce a concise summary of intent + risk.",
      source: "user",
      state: "enabled",
      allowedTools: ["Read", "Grep"],
      triggers: ["explain diff", "summarize change"],
    }}
  />

## Props

## Notes

- `onSave` is required and receives a `SkillDraft` (name, description, instructions,
  source, state, allowedTools, triggers, and modes). Save is disabled until the name is
  non-empty.
- The `Cancel` button renders only when `onCancel` is provided; `Delete` only when
  `onDelete` is provided.
- The submit label is `Save changes` when `initial.id` is set, otherwise `Create skill`.
- Form state seeds from `initial` once on mount. To reset when editing a different
  skill, use the React `key` pattern at the call site: `<SkillEditor key={skill.id}
  initial={skill} ... />`.
- Allowed tools and triggers are entered comma-separated and split on save.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SkillEditor } from "@theokit/ui/skill-editor";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/skill-editor.json
```

---

# SkillsList

Source: https://docs.usetheo.dev/theokit/ui/skills-list

Grid of SkillCards with an optional title and search input, filtering by name, description, and triggers

`SkillsList` renders a responsive grid of `SkillCard`s under an optional title, with an
optional search box that filters by name, description, and triggers. Reach for it to
build the skills inventory screen where a user browses and toggles skills.

<ComponentPreview name="skills-list" code={`<SkillsList
  skills={[
    {
      id: "code-review",
      name: "code-review",
      source: "builtin",
      description:
        "Review a pull request diff and surface SQL safety, trust boundary, and side-effect issues.",
      allowedTools: ["Read", "Grep", "Bash"],
      triggers: ["review this PR", "pre-landing review"],
      state: "enabled",
    },
    {
      id: "make-pdf",
      name: "make-pdf",
      source: "project",
      description:
        "Turn any markdown file into a publication-quality PDF with cover, TOC, and watermark.",
      allowedTools: ["Read", "Write", "Bash"],
      triggers: ["make a pdf", "export to pdf"],
      state: "enabled",
    },
  ]}
/>`}>
  <SkillsList
    skills={[
      {
        id: "code-review",
        name: "code-review",
        source: "builtin",
        description:
          "Review a pull request diff and surface SQL safety, trust boundary, and side-effect issues.",
        allowedTools: ["Read", "Grep", "Bash"],
        triggers: ["review this PR", "pre-landing review"],
        state: "enabled",
      },
      {
        id: "make-pdf",
        name: "make-pdf",
        source: "project",
        description:
          "Turn any markdown file into a publication-quality PDF with cover, TOC, and watermark.",
        allowedTools: ["Read", "Write", "Bash"],
        triggers: ["make a pdf", "export to pdf"],
        state: "enabled",
      },
    ]}
  />

## Props

## Notes

- `title` defaults to `Skills` and `searchable` defaults to `true`. The header hides
  when both `title` is falsy and `searchable` is `false`.
- Search matches against each skill's name, description (when it is a string), and
  triggers. When nothing matches, an empty-state message is shown instead of the grid.
- `onToggle` is forwarded to each `SkillCard`, so the enable/disable toggle only renders
  on the cards when this prop is provided.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SkillsList } from "@theokit/ui/skills-list";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/skills-list.json
```

---

# SlideDeck

Source: https://docs.usetheo.dev/theokit/ui/slide-deck

View-only composite engine that orchestrates N Slide primitives into a navigable, presenter-aware deck

`SlideDeck` is a composite render engine: pass it a markdown string (auto-split
on top-level `---`) or a pre-parsed slide array, and it renders a navigable deck
of `Slide` primitives with keyboard, touch, and hash navigation, a thumbnails
sidebar, presenter view, fullscreen, and PDF export via the browser print
dialog. It renders decks — it is not a deck editor.

It lives in the isolated subpath `@theokit/ui/slide-deck` and reuses `Slide`'s
markdown peer-deps (no new ones).

<ComponentPreview name="slide-deck" code={`const deck = \`# Welcome to TheoUI

A multi-slide deck rendered from one markdown string.

---

# Navigation

Use left / right / Space / Home / End or swipe on mobile.

---

# That's it

Press F for fullscreen, P or N to open presenter view.\`;

<SlideDeck slides={deck} transition="fade" enableHashRouting={false} />`}>

## Props

## Notes

- This is a render engine, not an editor. It navigates and presents slides but
  offers no authoring surface.
- `slides` accepts a markdown string (auto-split on top-level `---`) or a
  `SlideDeckSlide[]` array (`{ markdown, id?, notes? }`).
- Default layout renders canonical chrome (slide view + controls + progress bar
  + slide number + presenter/fullscreen/print buttons). Pass children to compose
  a headless layout from the dot-namespaced sub-components: `SlideDeck.Slides`,
  `SlideDeck.Controls`, `SlideDeck.ProgressBar`, `SlideDeck.SlideNumber`,
  `SlideDeck.Thumbnails`, `SlideDeck.PresenterView`, and the button parts.
- Navigation: keyboard (arrows / Space / Home / End / F / P), pointer swipe, and
  hash routing (`#/N`). Each is individually toggleable via `enableKeyboard`,
  `enableTouch`, and `enableHashRouting`.
- Speaker notes come from `<!-- notes: ... -->` HTML comments and are extracted
  before sanitize — they never reach the rendered slide DOM. Marpit-style `*`
  lists render as progressive fragments.
- Transitions are `"none"`, `"fade"`, or `"slide"`, CSS-only and
  `prefers-reduced-motion`-aware. PDF export uses `window.print()` with `@page`
  CSS. SSR-safe: markdown parses inside `useEffect` and hash init is lazy.
- Optional peer-deps: same markdown stack as `Slide`
  (`mdast-util-from-markdown`, `mdast-util-gfm`, `micromark-extension-gfm`,
  `mdast-util-to-hast`, `hast-util-sanitize`, `hast-util-to-jsx-runtime`,
  `hast-util-from-html`, `unist-util-visit`, `unist-util-visit-parents`,
  `yaml`) — no additional peer-deps.

## Install

Engines are distributed via the package subpath (with the markdown peer-deps):

```bash
pnpm add @theokit/ui mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm mdast-util-to-hast hast-util-sanitize hast-util-to-jsx-runtime hast-util-from-html unist-util-visit unist-util-visit-parents yaml
```

```tsx
import { SlideDeck } from "@theokit/ui/slide-deck";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/slide-deck.json
```

---

# Slide

Source: https://docs.usetheo.dev/theokit/ui/slide

View-only engine that renders markdown plus YAML frontmatter into a themed, fixed-aspect surface

`Slide` is a view-only render engine: pass it a markdown string (CommonMark +
GFM, with optional YAML frontmatter) and it renders a themed surface on a fixed
logical canvas (1280×720 for the default 16:9). It is designed to consume LLM
tool-call output and show it immediately, safely sanitized, with a consistent
visual identity. It is a single-slide primitive — no deck navigation, no
transitions, no presenter mode.

It lives in the isolated subpath `@theokit/ui/slide` so the markdown parsing
peer-deps only ship to consumers that import it.

<ComponentPreview name="slide" code={`const md = \`---
theme: violet-forge
---

# Welcome

A simple slide rendered from CommonMark.

- Bullet one
- Bullet two
- Bullet three\`;

<Slide markdown={md} aspectRatio="16:9" />`}>

## Props

## Notes

- This is a render engine, not an editor. It renders one slide from markdown and
  holds no authoring surface.
- Markdown is CommonMark + GFM. A top-level horizontal rule (`---` outside
  frontmatter) implies a deck split — only the first slide renders and
  `onValidationError` fires with `MULTIPLE_SLIDES`. Use `SlideDeck` for
  multi-slide input.
- HTML is sanitized with `hast-util-sanitize`'s default schema: `<script>`,
  `<iframe>`, `<style>` and similar tags are stripped. Stripped tags surface as
  a `BANNED_TAG` error so agents can self-correct.
- Two built-in themes: `default` and `violet-forge` (via the `theme` prop or
  frontmatter). `aspectRatio` accepts `"16:9"`, `"4:3"`, or a custom
  `{ width, height }`; invalid values fall back to 16:9 with an
  `INVALID_ASPECT_RATIO` error.
- The canvas scales to fit its container (Reveal.js-style transform), clamped by
  `minScale` / `maxScale`. Parsing runs client-side in a `useEffect`; wrap in a
  Suspense/skeleton to mitigate the first-paint jump.
- Pass memoized `components` and `plugins` (via `useMemo`) — inline arrays
  recreate on every render and cause re-parses.
- Optional peer-deps: the markdown stack —
  `mdast-util-from-markdown`, `mdast-util-gfm`, `micromark-extension-gfm`,
  `mdast-util-to-hast`, `hast-util-sanitize`, `hast-util-to-jsx-runtime`,
  `hast-util-from-html`, `unist-util-visit`, `unist-util-visit-parents`, and
  `yaml`. Tier-2 rich content (Shiki, KaTeX, Mermaid, emoji) ships as opt-in
  plugins under `@theokit/ui/slide/plugins/*`.

## Install

Engines are distributed via the package subpath (with the markdown peer-deps):

```bash
pnpm add @theokit/ui mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm mdast-util-to-hast hast-util-sanitize hast-util-to-jsx-runtime hast-util-from-html unist-util-visit unist-util-visit-parents yaml
```

```tsx
import { Slide } from "@theokit/ui/slide";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/slide.json
```

---

# StabilityBundleViewer

Source: https://docs.usetheo.dev/theokit/ui/stability-bundle-viewer

Inspector for a stability-bundle JSON from a server crash, with independently collapsible sections

`StabilityBundleViewer` renders a stability bundle produced by a server crash: a
severity header with timestamp and summary, plus independently collapsible
sections for the error (with stack), environment, config, and metadata. Sections
that are absent from the bundle are simply not rendered.

<ComponentPreview name="stability-bundle-viewer" code={`<StabilityBundleViewer
  bundle={{
    timestamp: "2026-05-29T14:00:00.000Z",
    severity: "fatal",
    summary: "Gateway failed to start: Invalid config at /home/node/.openclaw/openclaw.json.",
    error: {
      name: "ConfigValidationError",
      message: "models.providers.openrouter.models.0.name: expected string, received undefined",
      stack: "ConfigValidationError: models.providers.openrouter.models.0.name: expected string\\n    at parseConfig (dist/config.js:42:11)",
    },
    env: {
      NODE_ENV: "production",
      HOSTNAME: "5c14100d5356",
      PORT: "18789",
      OPENROUTER_API_KEY: "[REDACTED]",
    },
    config: { gateway: { mode: "local", port: 18789 } },
    metadata: { processUptimeMs: 1280, pid: 8 },
  }}
  onCopy={() => undefined}
/>`}>
  <StabilityBundleViewer
    bundle={{
      timestamp: "2026-05-29T14:00:00.000Z",
      severity: "fatal",
      summary: "Gateway failed to start: Invalid config at /home/node/.openclaw/openclaw.json.",
      error: {
        name: "ConfigValidationError",
        message: "models.providers.openrouter.models.0.name: expected string, received undefined",
        stack: "ConfigValidationError: models.providers.openrouter.models.0.name: expected string\n    at parseConfig (dist/config.js:42:11)",
      },
      env: {
        NODE_ENV: "production",
        HOSTNAME: "5c14100d5356",
        PORT: "18789",
        OPENROUTER_API_KEY: "[REDACTED]",
      },
      config: { gateway: { mode: "local", port: 18789 } },
      metadata: { processUptimeMs: 1280, pid: 8 },
    }}
  />

## Props

## Notes

- `bundle.severity` is one of `fatal`, `error`, or `warn` — each drives the header
  icon, color, and label.
- The `error`, `env`, `config`, and `metadata` sections are all optional; a section
  only renders when its data is present. The Error section is expanded by default;
  Environment, Config, and Metadata start collapsed.
- The viewer does not redact environment values — the bundle writer is expected to
  redact secrets at emit time (the example above shows a pre-redacted API key).
- `onCopy` is optional; when provided, a `Copy` button appears in the header.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { StabilityBundleViewer } from "@theokit/ui/stability-bundle-viewer";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/stability-bundle-viewer.json
```

---

# StepsRail

Source: https://docs.usetheo.dev/theokit/ui/steps-rail

Vertical numbered rail with a connecting line — complete, current, and pending steps.

`StepsRail` is a slim vertical rail of numbered dots joined by a connecting line,
with each step marked complete, current, or pending. It mirrors a task right-rail
that shows how far a multi-step flow has progressed.

  <StepsRail
    title="Steps"
    steps={[
      { id: 1, state: "complete" },
      { id: 2, state: "complete" },
      { id: 3, state: "current" },
      { id: 4, state: "pending" },
      { id: 5, state: "pending" },
    ]}
  />
</div>`}>
  <div className="flex h-[420px]">
    <StepsRail
      title="Steps"
      steps={[
        { id: 1, state: "complete" },
        { id: 2, state: "complete" },
        { id: 3, state: "current" },
        { id: 4, state: "pending" },
        { id: 5, state: "pending" },
      ]}
    />
  </div>

## Props

## Notes

- Each `step.state` is `complete`, `current`, or `pending`. When a step omits its
  state, the first step defaults to `current` and the rest to `pending`.
- A step renders its `label` if provided; otherwise it shows its 1-based index.
- The current step carries `aria-current="step"` for assistive technology.
- `title` is optional and renders as an uppercase caption above the rail.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { StepsRail } from "@theokit/ui/steps-rail";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/steps-rail.json
```

---

# SubAgentDispatch

Source: https://docs.usetheo.dev/theokit/ui/sub-agent-dispatch

Visualization for a Task() sub-agent invocation — agent name, task summary, state, event preview, and optional result

`SubAgentDispatch` visualizes a `Task()` / sub-agent invocation inside an agent timeline.
It shows the agent name, the task summary, the current state, an inline preview of the
latest event, and an optional result — making delegation visible.

<ComponentPreview name="sub-agent-dispatch" code={`<SubAgentDispatch
  run={{
    id: "2",
    agent: "code-reviewer",
    task: "Review the changes in scripts/build-registry.ts for SQL safety.",
    state: "completed",
    duration: "1m 04s",
    result: "No issues found. 47 lines reviewed, 0 blocking, 2 suggestions.",
  }}
/>`}>
  <SubAgentDispatch
    run={{
      id: "2",
      agent: "code-reviewer",
      task: "Review the changes in scripts/build-registry.ts for SQL safety.",
      state: "completed",
      duration: "1m 04s",
      result: "No issues found. 47 lines reviewed, 0 blocking, 2 suggestions.",
    }}
  />

## Props

## Notes

- `run.state` is one of `spawning`, `running`, `completed`, `failed`, `cancelled`. Each maps
  to its own labeled badge; `spawning` and `running` are treated as live.
- Live runs show a spinning `Loader2` in the badge; `spawning` also pulses the badge.
- `run.duration`, `run.lastEvent`, and `run.result` are optional and each rendered only when
  present.
- `onCancel` renders a Cancel button, but only while the run is live (`spawning` or
  `running`); it fires with `run.id`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SubAgentDispatch } from "@theokit/ui/sub-agent-dispatch";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/sub-agent-dispatch.json
```

---

# SystemPromptEditor

Source: https://docs.usetheo.dev/theokit/ui/system-prompt-editor

Surface the agent's system prompt with a clear vendor-default vs user-override toggle

`SystemPromptEditor` makes the agent's system prompt visible and editable. A badge shows
whether the vendor default or a user override is active; a "Show default" toggle reveals
the read-only default, and a "Reset" button clears the override. This is a transparency
surface — a user must always be able to see and edit the prompt the agent runs with.

<ComponentPreview name="system-prompt-editor" code={`<SystemPromptEditor
  defaultPrompt="You are Theo, an autonomous coding agent. You operate in a controlled sandbox. Prefer the simplest solution, stop and ask below 95% confidence, and never run destructive commands without explicit confirmation."
  override=""
  tokenEstimate={62}
  onOverrideChange={(next) => setOverride(next)}
/>`}>
  <SystemPromptEditor
    defaultPrompt="You are Theo, an autonomous coding agent. You operate in a controlled sandbox. Prefer the simplest solution, stop and ask below 95% confidence, and never run destructive commands without explicit confirmation."
    override=""
    tokenEstimate={62}
  />

## Props

## Notes

- The component is controlled: an empty `override` string means "use the vendor
  default", and any non-empty value flips the badge to "Override active". Typing calls
  `onOverrideChange(next)`; "Reset" calls it with `""`.
- `defaultPrompt` is read-only. The "Show default" toggle reveals it in a scrollable
  `<pre>` block above the editor.
- `tokenEstimate` is optional; when provided it renders as `~N tokens` in the header. It
  is display-only — the component does no tokenization.
- Marked `"use client"` since the show/hide default toggle uses local component state.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { SystemPromptEditor } from "@theokit/ui/system-prompt-editor";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/system-prompt-editor.json
```

---

# TaskPlan

Source: https://docs.usetheo.dev/theokit/ui/task-plan

Hierarchical agent task plan — nested steps progressing from pending to done.

`TaskPlan` renders a hierarchical task plan, à la Claude "plan mode". The agent
emits a structured plan and the user watches each step move from pending to running
to done (or failed / skipped). Child steps render one indent level deeper with a
left border to suggest hierarchy.

<ComponentPreview name="task-plan" code={`<TaskPlan
  className="max-w-xl"
  title="Build plan"
  nodes={[
    {
      id: "1",
      label: "Scan repository structure",
      status: "done",
      children: [
        { id: "1a", label: "Detect framework", status: "done" },
        { id: "1b", label: "Inventory dependencies", status: "done" },
      ],
    },
    {
      id: "2",
      label: "Implement the deploy command",
      status: "running",
      detail: "Editing src/cli/deploy.ts",
      children: [
        { id: "2a", label: "Parse CLI flags", status: "done" },
        { id: "2b", label: "Wire HTTP client", status: "running" },
        { id: "2c", label: "Handle errors", status: "pending" },
      ],
    },
    { id: "3", label: "Write unit tests", status: "pending" },
    { id: "4", label: "Run typecheck + lint", status: "pending" },
    {
      id: "5",
      label: "Update CHANGELOG",
      status: "skipped",
      detail: "Skipped because no public API changed.",
    },
  ]}
/>`}>
  <TaskPlan
    className="max-w-xl"
    title="Build plan"
    nodes={[
      {
        id: "1",
        label: "Scan repository structure",
        status: "done",
        children: [
          { id: "1a", label: "Detect framework", status: "done" },
          { id: "1b", label: "Inventory dependencies", status: "done" },
        ],
      },
      {
        id: "2",
        label: "Implement the deploy command",
        status: "running",
        detail: "Editing src/cli/deploy.ts",
        children: [
          { id: "2a", label: "Parse CLI flags", status: "done" },
          { id: "2b", label: "Wire HTTP client", status: "running" },
          { id: "2c", label: "Handle errors", status: "pending" },
        ],
      },
      { id: "3", label: "Write unit tests", status: "pending" },
      { id: "4", label: "Run typecheck + lint", status: "pending" },
      {
        id: "5",
        label: "Update CHANGELOG",
        status: "skipped",
        detail: "Skipped because no public API changed.",
      },
    ]}
  />

## Props

## Notes

- Each `node.status` is `pending`, `running`, `done`, `skipped`, or `failed` — each
  maps to its own icon and color; running nodes spin their icon.
- Nodes nest via `children`, rendered recursively with extra indentation and a left
  border.
- `title` defaults to `"Plan"`; `summary` defaults to a computed "`N` of `M` done"
  line counting top-level done nodes.
- `node.detail` is an optional sub-line shown under the label.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { TaskPlan } from "@theokit/ui/task-plan";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/task-plan.json
```

---

# TerminalPanel

Source: https://docs.usetheo.dev/theokit/ui/terminal-panel

Minimal read-only terminal output viewer — mono font, prompt prefix on commands, color-coded stdout/stderr/success.

`TerminalPanel` is a read-only terminal output viewer. Command lines get a prompt prefix;
stdout, stderr, success, and prompt lines are color-coded. It has no interactivity — pair
it with your own pty/xterm if you need a live shell.

<ComponentPreview name="terminal-panel" code={`<TerminalPanel
  className="max-w-3xl"
  lines={[
    { id: "1", kind: "command", content: "pnpm typecheck" },
    { id: "2", kind: "stdout", content: "> tsc --noEmit" },
    { id: "3", kind: "ok", content: "typecheck passed (0 errors)" },
    { id: "4", kind: "stderr", content: "AlignmentGrid.tsx(424,41): Property 'stiffness' is missing" },
    { id: "5", kind: "prompt", content: "_" },
  ]}
/>`}>
  <TerminalPanel
    className="max-w-3xl"
    lines={[
      { id: "1", kind: "command", content: "pnpm typecheck" },
      { id: "2", kind: "stdout", content: "> tsc --noEmit" },
      { id: "3", kind: "ok", content: "typecheck passed (0 errors)" },
      { id: "4", kind: "stderr", content: "AlignmentGrid.tsx(424,41): Property 'stiffness' is missing" },
      { id: "5", kind: "prompt", content: "_" },
    ]}
  />

## Props

## Notes

- Each line's `kind` (`command`, `stdout`, `stderr`, `ok`, `prompt`) sets its color;
  `command` lines get the prompt prefix and `prompt` lines pulse (respecting
  `prefers-reduced-motion`). Lines default to `stdout`.
- `promptPrefix` defaults to `"$"`.
- `title` defaults to `"Terminal"`.
- `live` defaults to `"off"`; set `"polite"` when streaming fresh output so assistive tech
  announces new lines. When nested in a container live region, the component suppresses its
  own `aria-live`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { TerminalPanel } from "@theokit/ui/terminal-panel";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/terminal-panel.json
```

---

# TextPrompt

Source: https://docs.usetheo.dev/theokit/ui/text-prompt

Free-text ask-the-user card for agent surfaces, with single-line or multi-line input and an optional required gate

`TextPrompt` is the open-ended sibling of `ChoicePrompt`: a question with an optional
header chip and a single-line (`Input`) or multi-line (`Textarea`) field. It is the
"Other" affordance promoted to a question of its own — reach for it when the answer is
free text rather than a choice.

It renders one question at a time; sequencing is the consumer's responsibility. Text is
controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).

<ComponentPreview name="text-prompt" code={`<TextPrompt
  question="What should we name the service?"
  badge="Naming"
  description="Lowercase, no spaces."
  placeholder="payments-api"
  required
  onConfirm={(r) => console.log(r)}
  onCancel={() => {}}
/>`}>
  <PreviewTextPrompt
    question="What should we name the service?"
    badge="Naming"
    description="Lowercase, no spaces."
    placeholder="payments-api"
    required
  />

## Props

## Notes

- `multiline` swaps the single-line `Input` for a `Textarea`; `rows` (default 3) sets its
  height.
- `required` disables Confirm until the text is non-empty (whitespace-trimmed) and marks
  the label as required.
- `onConfirm` receives `{ text }` with the typed value.
- The confirm/cancel footer only renders when `onConfirm`/`onCancel` are provided.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { TextPrompt } from "@theokit/ui/text-prompt";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/text-prompt.json
```

---

# Theming

Source: https://docs.usetheo.dev/theokit/ui/theming

Ten built-in themes, runtime switching via ThemeProvider, and authoring your own with defineTheme.

`@theokit/ui` ships **10 themes out of the box** — `violet-forge` (default),
`classic-paper`, `aurora-terminal`, `dracula`, `github-dark`, `one-dark`, `linear-glass`,
`anthropic-style`, `openai-style`, and `vercel-mono`. Swap them at runtime through
`<ThemeProvider>`; every component picks up the new palette via CSS variables, with no
markup change.

## Runtime switching

Wrap your app once and set a default. `<ThemeSwitcher>` gives users a live picker:

```tsx
import { ThemeProvider, ThemeSwitcher } from "@theokit/ui";

<ThemeProvider defaultTheme="violet-forge" defaultMode="dark">
  <ThemeSwitcher />
  {/* your app */}
</ThemeProvider>;
```

<ComponentPreview name="theme-switcher" code={`<ThemeSwitcher />`}>

`<ThemeProvider>` takes `defaultTheme` (any built-in name or a custom theme's name) and
`defaultMode` (`"light"` | `"dark"`). Read or set the active theme from any component with
the `useTheme()` hook.

## Author your own — `defineTheme`

The smallest valid override is a clone of the default with your own name. Any color key
you do not pass is inherited from `violetForge`.

```tsx
import { ThemeProvider, defineTheme, hex } from "@theokit/ui";

const corp = defineTheme({
  name: "corp",
  light: { primary: hex("#0EA5E9"), accent: hex("#F59E0B") },
  dark: { primary: hex("#38BDF8"), accent: hex("#FBBF24") },
});

export function App({ children }) {
  return (
    <ThemeProvider themes={[corp]} defaultTheme="corp">
      {children}
    </ThemeProvider>
  );
}
```

### `defineTheme(input)`

```ts
function defineTheme(input: {
  name: string;                 // required, /^[a-z][a-z0-9-]*$/i
  label?: string;               // defaults to capitalize(name)
  description?: string;
  light?: Partial<ColorScale>;  // merged into violetForge.light
  dark?: Partial<ColorScale>;   // merged into violetForge.dark
  fonts?: Partial<ThemeFonts>;  // merged into violetForge.fonts
  fontUrls?: string[];          // defaults to violetForge.fontUrls
}): Theme;
```

Returns a complete `Theme` that drops into `<ThemeProvider themes={[...]}>`.

  If you override `light.primary` but not `dark.primary`, the two modes use different
  primary colors — your override in light, violet-forge's default in dark. That is the
  merge behavior; pass both sides to keep them in sync.

### `hex(input)` and `rgb(r, g, b)`

Color helpers emit OKLCH strings (the canonical format since theme 0.14):

```ts
hex("#7C3AED");    // 'oklch(0.542 0.245 293)'
hex("#abc");       // expanded to '#aabbcc'
rgb(124, 58, 237); // 'oklch(0.542 0.245 293)'
```

`ColorScale` stores colors as OKLCH strings; alpha overlays compose via
`color-mix(in oklch, var(--primary) 50%, transparent)` — perceptually uniform. You only
declare the keys you want to change; the rest inherit from the default.

## Preventing FOUC (SSR)

Inject `<ThemeScript>` in `<head>` so the correct theme is applied before hydration — see
[Getting started](/theokit/ui/getting-started#ssr--server-components).

---

# ThinkingLevelSelector

Source: https://docs.usetheo.dev/theokit/ui/thinking-level-selector

Native select for the LLM reasoning budget — inherited mode plus explicit off/minimal/low/medium/high/xhigh overrides

`ThinkingLevelSelector` is a `<select>` for choosing an agent's reasoning budget. It offers
an `inherited` option (use the value resolved by the parent agent or session) plus explicit
overrides: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. It is a pure UI primitive —
the consumer wires `value` from agent state and persists `onChange` selections.

<ComponentPreview name="thinking-level-selector" code={`<ThinkingLevelSelector value="inherited" inheritedValue="medium" />`}>

## Props

## Notes

- `value` is either one of the six override levels or the sentinel `inherited`. `onChange`
  fires with the newly selected value.
- `inheritedValue` labels the inherited option (e.g. `Inherited: medium`); when omitted the
  option reads just `Inherited`.
- In development, passing `value="inherited"` without an `inheritedValue` logs a console
  warning.
- `disabled` dims the control and blocks interaction. The select carries
  `aria-label="Thinking level"`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ThinkingLevelSelector } from "@theokit/ui/thinking-level-selector";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/thinking-level-selector.json
```

---

# TokenUsageChart

Source: https://docs.usetheo.dev/theokit/ui/token-usage-chart

Stacked-bar chart of input vs output tokens over time — pure SVG, no chart library

`TokenUsageChart` plots input vs output tokens per period as a stacked-bar chart. It is
pure SVG with no chart dependency: the width is fluid, bars adjust to the viewBox, and
each bar carries a hover tooltip plus an `sr-only` data table so assistive tech gets the
same numbers.

<ComponentPreview name="token-usage-chart" code={`<TokenUsageChart
  title="This week"
  points={[
    { label: "Mon", input: 24000, output: 6000 },
    { label: "Tue", input: 41000, output: 12000 },
    { label: "Wed", input: 33000, output: 8500 },
    { label: "Thu", input: 67000, output: 18000 },
    { label: "Fri", input: 52000, output: 14000 },
    { label: "Sat", input: 9000, output: 2000 },
    { label: "Sun", input: 14000, output: 3500 },
  ]}
/>`}>
  <TokenUsageChart
    title="This week"
    points={[
      { label: "Mon", input: 24000, output: 6000 },
      { label: "Tue", input: 41000, output: 12000 },
      { label: "Wed", input: 33000, output: 8500 },
      { label: "Thu", input: 67000, output: 18000 },
      { label: "Fri", input: 52000, output: 14000 },
      { label: "Sat", input: 9000, output: 2000 },
      { label: "Sun", input: 14000, output: 3500 },
    ]}
  />

## Props

## Notes

- Each `TokenUsagePoint` has a `label`, `input`, and `output`. By default input and
  output stack into one bar; set `splitSeries` to render them as two adjacent bars per
  period instead.
- When `points.length` exceeds `maxBars` (default 60), the series is binned — summed in
  equal-width windows — so the SVG node count stays bounded and the chart stays legible.
- `maxScale` fixes the y-axis maximum so multiple charts share a scale; bars over it are
  clamped to 100% height while the tooltip and a11y table still show the true value.
- A visually-hidden `<table>` mirrors every bar's numbers for screen readers, since
  per-bar SVG `<title>` is exposed inconsistently across AT (WCAG 1.1.1).
- `height` (default 160), `showLegend` (default true), and `title` control the framing.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { TokenUsageChart } from "@theokit/ui/token-usage-chart";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/token-usage-chart.json
```

---

# ToolCallCard

Source: https://docs.usetheo.dev/theokit/ui/tool-call-card

Single agent tool invocation as a stand-alone card — tool name, optional icon and target, status, and an expandable output block

`ToolCallCard` renders one agent tool invocation as a stand-alone card inside a stream:
a tool name, an optional icon and monospace target/command, a status icon, and an
optional timestamp. When `output` is provided the card becomes expandable to reveal the
stdout/stderr/result body.

<ComponentPreview name="tool-call-card" code={`<ToolCallCard
  tool="Bash"
  target="tsc --noEmit"
  status="success"
  timestamp="9:58 PM"
  output={<pre className="whitespace-pre-wrap text-success">[vite] ready in 504 ms</pre>}
/>`}>
  <ToolCallCard
    tool="Bash"
    target="tsc --noEmit"
    status="success"
    timestamp="9:58 PM"
    output={<pre className="whitespace-pre-wrap text-success">[vite] ready in 504 ms</pre>}
  />

## Props

## Notes

- `tool` and `status` are required. `status` is one of `running`, `success`, `failed`,
  `queued`, or `skipped` — each maps to its own icon and accessible label.
- The card is expandable only when `output` is provided; the chevron button carries
  `aria-expanded` and an accessible expand/collapse label. `defaultExpanded` sets the
  initial state (default collapsed).
- `icon`, `target`, and `timestamp` are optional. Running status shows a spinner via
  `animate-spin`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ToolCallCard } from "@theokit/ui/tool-call-card";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/tool-call-card.json
```

---

# ToolCall

Source: https://docs.usetheo.dev/theokit/ui/tool-call

Collapsible row representing an agent tool invocation — wrench icon, optional name, summary, and an expandable detail payload

`ToolCall` renders one agent tool invocation as a collapsible row: a wrench icon, an
optional tool name, a summary label, and a chevron that rotates on expand. When a
`detail` is provided the row expands to reveal the payload. It pairs with `ToolResult`
for the rendered output inside a chat message body.

<ComponentPreview name="tool-call" code={`<ToolCall
  name="read_file"
  summary="Read 18 files"
  detail={<ToolResult variant="code">{\`README.md
src/index.ts
src/lib/cn.ts
... (15 more)\`}</ToolResult>}
/>`}>
  <ToolCall
    name="read_file"
    summary="Read 18 files"
    detail={<ToolResult variant="code">{`README.md
src/index.ts
src/lib/cn.ts
... (15 more)`}</ToolResult>}
  />

## Props

## Notes

- `summary` is required; `name` is optional and rendered in monospace before the summary.
- The row is expandable only when `detail` is provided — without it the button is
  disabled and no chevron shows. `defaultOpen` controls the initial expanded state.
- `hideIcon` removes the wrench icon, useful when grouping calls by name elsewhere.
- Expansion uses `aria-expanded` on a native button for keyboard and screen-reader
  support.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ToolCall } from "@theokit/ui/tool-call";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/tool-call.json
```

---

# ToolResult

Source: https://docs.usetheo.dev/theokit/ui/tool-result

Formatted output of a tool invocation — plain text, code (monospace), or json (monospace, tinted)

`ToolResult` renders the output of a tool invocation in one of three variants: plain
`text`, `code` (monospace, whitespace preserved), or `json` (monospace, tinted). Reach
for it to display stdout, a file list, or a JSON response inside a tool call.

<ComponentPreview name="tool-result" code={`<ToolResult variant="code">{\`$ pnpm test
src/lib/cn.test.ts (5)
src/components/primitives/button/button.test.tsx (10)
Test Files  22 passed
     Tests  122 passed\`}</ToolResult>`}>
    {`$ pnpm test
src/lib/cn.test.ts (5)
src/components/primitives/button/button.test.tsx (10)
Test Files  22 passed
     Tests  122 passed`}

## Props

## Notes

- `variant` defaults to `text`. The `text` variant uses normal body font; `code` and
  `json` wrap children in a `<pre>` with monospace font and preserved whitespace.
- The `json` variant tints the text distinctly from `code`.
- `children` is required and rendered verbatim — the component formats but does not parse
  the content.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ToolResult } from "@theokit/ui/tool-result";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/tool-result.json
```

---

# ToolsList

Source: https://docs.usetheo.dev/theokit/ui/tools-list

Surface every tool the agent could call, with its enablement state — click a chip to cycle Allowed, Ask, Denied

`ToolsList` renders every tool the agent could call as rows with an icon, name,
optional source and badge, a description, and an enablement chip. Clicking the chip
cycles the state: Allowed to Ask to Denied. Reach for it to build the agent's tool
permissions screen.

<ComponentPreview name="tools-list" code={`<ToolsList
  tools={[
    {
      id: "read",
      name: "Read",
      source: "builtin",
      description: "Read files from the working directory.",
      enablement: "enabled",
    },
    {
      id: "write",
      name: "Write",
      source: "builtin",
      description: "Create or replace file contents.",
      enablement: "enabled",
      badge: "destructive",
    },
    {
      id: "bash",
      name: "Bash",
      source: "builtin",
      description: "Execute shell commands.",
      enablement: "ask",
    },
  ]}
/>`}>
  <ToolsList
    tools={[
      {
        id: "read",
        name: "Read",
        source: "builtin",
        description: "Read files from the working directory.",
        enablement: "enabled",
      },
      {
        id: "write",
        name: "Write",
        source: "builtin",
        description: "Create or replace file contents.",
        enablement: "enabled",
        badge: "destructive",
      },
      {
        id: "bash",
        name: "Bash",
        source: "builtin",
        description: "Execute shell commands.",
        enablement: "ask",
      },
    ]}
  />

## Props

## Notes

- `tools` is required. Each `ToolEntry` supports an optional `icon`, `source`, `badge`,
  `description`, and `enablement` (defaults to `enabled`). Entries without an `icon` fall
  back to a settings icon.
- `title` defaults to `Tools`; when set, the header also shows a tool count.
- Clicking an enablement chip calls `onEnablementChange` with the next state in the
  cycle `enabled` to `ask` to `denied`. Without `onEnablementChange` the chip is
  non-interactive (display-only).

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { ToolsList } from "@theokit/ui/tools-list";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/tools-list.json
```

---

# UsageMeter

Source: https://docs.usetheo.dev/theokit/ui/usage-meter

Multi-metric stacked usage card — N metrics with arbitrary units, each a labeled progress bar

`UsageMeter` is a stacked usage card: a title, an optional action slot, and N
metrics, each rendered as a label plus a value/max readout over a `Progress` bar.
It is the PaaS-shaped sibling of `CostMeter` (which is mono-USD) — use it for
quotas like data transfer, requests, build minutes, or seats.

<ComponentPreview name="usage-meter" code={`<UsageMeter
  title="Last 30 days"
  action={<Badge variant="outline">Upgrade</Badge>}
  metrics={[
    { label: "Fast Data Transfer", value: 12, max: 100, unit: "GB" },
    { label: "Fast Origin Transfer", value: 1, max: 10, unit: "GB" },
  ]}
/>`}>
  <UsageMeter
    title="Last 30 days"
    action={<Badge variant="outline">Upgrade</Badge>}
    metrics={[
      { label: "Fast Data Transfer", value: 12, max: 100, unit: "GB" },
      { label: "Fast Origin Transfer", value: 1, max: 10, unit: "GB" },
    ]}
  />

## Props

## Notes

- Each `metric` has a `label`, `value`, `max`, and optional `unit`. The default
  readout is `value / max unit`; pass a per-metric `formatter` to override it.
- Over-quota (`value > max`) styles the value text with `text-warning` and switches
  the `Progress` bar to the warning intent; the bar clamps at 100%.
- `compact` renders only the bars (no label/value text) — useful in narrow nav-bar
  slots.
- The header (title + action) only renders when `title` or `action` is provided.
- This is a composite — it uses the `Progress` primitive from `@usetheo/ui`.

## Install

```bash
pnpm add @theokit/ui
```

```tsx
import { UsageMeter } from "@theokit/ui/usage-meter";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/usage-meter.json
```

---

# Whiteboard

Source: https://docs.usetheo.dev/theokit/ui/whiteboard

View-only engine that turns a declarative JSON scene into a hand-drawn SVG, with pan and zoom built in

`Whiteboard` is a view-only render engine: feed it a `WhiteboardData` JSON
object (usually the output of an LLM tool call) and it renders an SVG with an
Excalidraw-style hand-drawn aesthetic. Pan and zoom are handled internally.
There is no editor surface — no toolbar, no selection, no undo, no hit-testing.

It lives in the isolated subpath `@theokit/ui/whiteboard` so its optional
peer-deps (`roughjs`, `perfect-freehand`) only ship to consumers that import it.

<ComponentPreview name="whiteboard" code={`const scene = {
  version: 1,
  width: 600,
  height: 320,
  elements: [
    { type: "rect", x: 60, y: 110, w: 140, h: 60, label: "Client" },
    { type: "ellipse", x: 400, y: 110, w: 140, h: 60, label: "API" },
    { type: "arrow", x: 200, y: 140, to: [400, 140], label: "POST /deploy" },
  ],
};

<Whiteboard data={scene} fitOnLoad />`}>

## Props

## Notes

- This is a render engine, not an editor. It is view-only by design — no
  toolbar, no selection, no undo. Pan (drag) and zoom (wheel, clamped 0.1–8) are
  the only interactions.
- The scene JSON is a discriminated union with seven element types: `rect`,
  `ellipse`, `diamond`, `line`, `arrow`, `text`, and `freedraw`.
- `data` is validated with Zod on every change. Invalid scenes render an empty
  SVG (`data-whiteboard-state="invalid"`); `onValidationError` fires from a
  `useEffect`, never during render.
- `fitOnLoad` computes the bounding box of all elements and zooms to fit on
  first render. `initialZoom` and `initialCenter` set the starting viewport.
- Rendering is SSR-safe: `renderToString` produces the same static SVG the
  browser shows on first paint.
- Optional peer-deps: `roughjs` (rough sketch strokes) and `perfect-freehand`
  (freedraw). Both live behind the `@theokit/ui/whiteboard` subpath.

## Install

Engines are distributed via the package subpath (with the optional peer-deps):

```bash
pnpm add @theokit/ui roughjs perfect-freehand
```

```tsx
import { Whiteboard, type WhiteboardData } from "@theokit/ui/whiteboard";
```

Or copy the source via the shadcn CLI:

```bash
npx shadcn@latest add https://usetheodev.github.io/theokit-ui/r/whiteboard.json
```

---

# Advanced

Source: https://docs.usetheo.dev/theokit/workflows/advanced

The full Workflow surface — every control-flow primitive, step type, retry, suspend/resume, shared state, whole-workflow schemas, streaming, and reuse.

# Advanced workflows

Everything the [`WorkflowBuilder`](/theokit/reference/Workflow) exposes, verified against the SDK.
The [Run a workflow](/theokit/workflows/run-a-workflow) how-to is the starting point; this page is
the exhaustive index.

## Control-flow primitives

Chain these on the builder; `.commit()` freezes it into a runnable `Workflow`.

| Primitive | Purpose |
| --- | --- |
| `.then(step)` | Run a step sequentially. |
| `.parallel([a, b], { concurrency, errorPolicy })` | Fan out concurrent branches (`errorPolicy: "fail-fast" \| "collect"`). |
| `.branch([[pred, [...steps]], …], { fallback })` | First-match-wins routing on the upstream output. |
| `.foreach(srcStepId, step, { concurrency })` | Map a step over an upstream array (default concurrency 4). |
| `.dowhile(step, cond, { maxIterations })` | Loop while `cond` is true (default cap 100). |
| `.sleep(durationMs, id?)` | Pause (abortable). |
| `.suspend({ id?, payloadSchema? })` | A declarative pause step — resumes via `Workflow.resume`. |
| `.commit()` | Freeze the builder into a `Workflow`. |

## Step types

```ts
import { fn, agentStep, workflowStep } from "@theokit/sdk/workflow";

// fn — a pure, typed function step. Optional Zod schemas + retry.
fn("id", (input, ctx) => {/* … */}, { inputSchema, outputSchema, retry });

// agentStep — render a prompt from the input and call an agent.
agentStep("id", agent, (input) => `prompt: ${String(input)}`, { retry, origin });

// workflowStep — run a committed child Workflow as a single step (opaque: its own executor + id-space).
workflowStep(childWorkflow, { id });
```

Each step receives the **previous step's output** as its input — state flows explicitly down the
chain. The `agentStep` renderer's input is `unknown` (workflow state is untyped between steps) —
coerce it (`String(input)`) or cast.

## Retry a failing step

Attach a `retry` policy to any step; the workflow re-runs it with exponential backoff.

```ts
fn("flaky", () => { if (++attempts < 3) throw new Error("transient"); return "ok"; },
   { retry: { maxAttempts: 3, initialBackoffMs: 50, backoffCoefficient: 2 } });
// → after two failures, the run completes with "ok"
```

```ts
retry: {
  maxAttempts: 3,            // 1..20 — REQUIRED when retry is set
  initialBackoffMs: 1000,    // default 1000
  backoffCoefficient: 2.0,   // default 2.0 (exponential)
  maximumBackoffMs: 30_000,  // default 30s
  nonRetryableErrors: ["ConfigurationError", "AbortError"], // skip the loop for these
}
```

Backoff sleeps are **abortable**; `nonRetryableErrors` (and a few built-ins) skip the loop; exhausting
`maxAttempts` fails the step (`run.status === "failed"`).

## Suspend and resume

Pause mid-run for a human decision, then continue later — the run state is durable, so resume can
happen in a different process, driven by a webhook or UI.

```ts
const wf = Workflow.create({ name: "approval" })
  .then(fn("draft", () => "draft text"))
  .then(fn("gate", async (input, ctx) => { await ctx.suspend({ awaiting: "approval", draft: input }); return "unreached"; }))
  .then(fn("publish", (payload) => `published: ${JSON.stringify(payload)}`))
  .commit();

const first = await wf.run(undefined);          // status: "suspended", first.id is the handle
const done = await Workflow.resume({ runId: first.id, workflow: wf, payload: { approved: true } });
// done.status: "completed" → published: {"approved":true}
```

- `ctx.suspend(payload)` (inside a `fn`) or the declarative `.suspend()` step both pause the run.
- `Workflow.resume({ runId, workflow, payload })` continues from the **next** step; `payload` is that
  step's input. The suspending step never returns normally — put post-approval logic in the next step.

## Shared state — `stateSchema`

`Workflow.create({ stateSchema, initialState })` seeds a shared state; every step's context gains
`state` (read) and `setState(next)` (write for later steps), validated against `stateSchema`. State
is captured in the snapshot and restored across suspend/resume.

## Whole-workflow validation — `inputSchema` / `outputSchema`

`Workflow.create({ inputSchema, outputSchema })` validates the input **before step 1** (typed
`WorkflowInputError`, fail-fast — no step runs) and the final output on the `completed` path (typed
`WorkflowOutputError`). `run()` never throws; both surface as `status: "failed"`.

## Streaming — `.stream()`

`workflow.stream(input)` returns a `WorkflowStream`: it emits step-level `WorkflowEvent`s
(`step_started` / `step_completed` / `step_failed` / `workflow_suspended` / `workflow_completed`) in
execution order, plus a `result` promise resolving to the same terminal `WorkflowRun` that `run()`
returns. Distinct from the token-level agent stream.

## Reuse

| Factory | What it does |
| --- | --- |
| `workflowAsTool(workflow, { name, description, inputSchema })` | Expose a whole workflow as a [tool](/theokit/tools) an agent can call. |
| `workflowStep(child, { id })` | Nest a committed workflow as a step (opaque; own id-space). Nested `suspend` is not supported — use a top-level suspend. |
| `cloneWorkflow(wf, { id })` | Copy a committed workflow under a new id. |

## Runnable examples

- [`examples/workflow-retry`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/workflow-retry) — the retry example above (deterministic).
- [`examples/workflow-suspend-resume`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/workflow-suspend-resume) — the suspend/resume example above (deterministic).

## Reference

- [`Workflow`](/theokit/reference/Workflow) · [`WorkflowRun`](/theokit/reference/WorkflowRun) · [`WorkflowEvent`](/theokit/reference/WorkflowEvent) · [`WorkflowResumeOptions`](/theokit/reference/WorkflowResumeOptions) · [`RetryPolicy`](/theokit/reference/RetryPolicy)

---

# Overview

Source: https://docs.usetheo.dev/theokit/workflows

Declarative multi-step orchestration over agents — steps, branching, parallelism, and suspend/resume.

# Workflows

An **agent** decides its own next step inside a single `send()`. A **workflow** is the opposite:
*you* declare the steps and the order, and each step is a small, testable unit. Use a workflow
when the control flow is known up front — validate, classify, route, fan-out, retry — and you want
it explicit and resumable rather than left to the model.

```ts
const pipeline = Workflow.create({ name: "refund" })
  .then(fn("validate", (input) => { /* pure function */ }))
  .then(agentStep("classify", classifier, (i) => `Classify: ${i.text}`))
  .commit();

const run = await pipeline.run({ text: "I was charged twice" });
```

`Workflow.create()` returns a builder; you chain steps, call `.commit()` to freeze it, then
`.run(input)` to execute. The result is a `WorkflowRun` with `status` and `output`.

`Agent` is on the main entrypoint; `Workflow`, `fn`, and `agentStep` are imported from the
`@theokit/sdk/workflow` sub-path.

## Step types

| Step | What it is |
| --- | --- |
| `fn(id, handler, opts?)` | A plain, typed function step — no LLM. Optional Zod `inputSchema`/`outputSchema` and `retry`. |
| `agentStep(id, agent, prompt, opts?)` | Renders a prompt from the previous step's output and calls `agent.send()`. Optional `retry`. |

Each step receives the **previous step's output** as its input — state flows explicitly down the
chain (not a shared mutable graph).

## Control-flow primitives

| Primitive | Purpose |
| --- | --- |
| `.then(step)` | Run a step sequentially. |
| `.parallel([a, b], { concurrency })` | Fan out concurrent branches (`errorPolicy: "fail-fast" \| "collect"`). |
| `.branch([[pred, [...]], …], { fallback })` | First-match-wins routing on the upstream output. |
| `.foreach(srcStepId, step, { concurrency })` | Map a step over an upstream array (default concurrency 4). |
| `.dowhile(step, cond, { maxIterations })` | Loop until the condition is false (default cap 100). |
| `.sleep(ms, id?)` | Pause (abortable). |
| `.suspend({ payloadSchema })` | Pause until `Workflow.resume(...)` — the human-in-the-loop seam. |

## Retry, suspend, resume

- **Retry** — pass `retry: { maxAttempts, initialBackoffMs?, backoffCoefficient?, nonRetryableErrors? }`
  to any step. Backoff sleeps are abortable; non-retryable errors skip the loop.
- **Suspend / resume** — `ctx.suspend(payload)` inside a `fn` pauses the run (`status: "suspended"`);
  later, `Workflow.resume({ runId, workflow, payload })` continues from where it stopped. This is how
  a workflow waits for human approval without holding a process open.

## Streaming

`workflow.stream(input)` emits step-level `WorkflowEvent`s (`step_started` / `step_completed` /
`step_failed` / `workflow_suspended` / `workflow_completed`) in execution order, plus a `result`
promise resolving to the same terminal `WorkflowRun`. Distinct from the token-level agent stream.

## Reuse

- **`workflowAsTool(workflow, { name, description, inputSchema })`** — expose a whole workflow as a
  tool an agent can call (`@theokit/sdk/workflow`).
- **Nested workflows** — `workflowStep(child)` runs a committed workflow as a step; `cloneWorkflow`
  copies one under a new id.

## Next

- [Run a workflow](/theokit/workflows/run-a-workflow) — a runnable two-step example.

## Reference

- [`Workflow`](/theokit/reference/Workflow) · [`WorkflowRun`](/theokit/reference/WorkflowRun) · [`WorkflowEvent`](/theokit/reference/WorkflowEvent)

---

# Run a workflow

Source: https://docs.usetheo.dev/theokit/workflows/run-a-workflow

Build a two-step Workflow — a fn step normalizes the input, an agentStep turns it into a fact — then run it end-to-end.

# Run a workflow

Chain a pure `fn` step and an `agentStep`, `.commit()` the workflow, and `.run(input)` it. State
flows from each step to the next; the result carries the terminal `status` and `output`.

```ts title="run.ts"
import { Agent } from "@theokit/sdk";
import { Workflow, agentStep, fn } from "@theokit/sdk/workflow";

const writer = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  systemPrompt: "You write exactly one concise, factual sentence. No preamble.",
});

const factPipeline = Workflow.create({ name: "topic-fact" })
  // Step 1 — a pure function normalizes the input to a clean topic string (no LLM).
  .then(fn("normalize", (input: { topic: string }) => input.topic.trim().toLowerCase()))
  // Step 2 — an agent step turns the normalized topic into a one-sentence fact. Workflow state
  // flows untyped between steps, so the renderer receives `unknown` — coerce it with String().
  .then(agentStep("write", writer, (topic) => `Write a one-sentence fact about ${String(topic)}.`))
  .commit();

const run = await factPipeline.run({ topic: "  The Moon  " });

console.log("Status:", run.status);
console.log("Output:", run.output);

await writer.dispose();
```

## Output

Verified against `openai/gpt-4o-mini` via OpenRouter:

```text
Status: completed
Output: The Moon is slowly drifting away from Earth at about 3.8 centimeters per year.
```

_Model-generated — yours will read differently. Click **Run** above for a fresh one._

## What it shows

- **`Workflow.create({ name }).then(…).commit()`** — the builder freezes into a runnable workflow.
- **`fn("normalize", …)`** — a plain typed function step; no LLM, fully deterministic and testable.
- **`agentStep("write", writer, (i) => prompt)`** — renders a prompt from the previous step's output
  and calls the agent. The `fn` output (`{ topic }`) is the `agentStep`'s input.
- **`run.status` / `run.output`** — the terminal result. `run()` never throws on a step failure; it
  returns `status: "failed"` with the error captured.

## Import note

`Agent` is on the main entrypoint; `Workflow` / `fn` / `agentStep` live on the
`@theokit/sdk/workflow` sub-path.

## Example

Full runnable source:
[`examples/workflow-basics`](https://github.com/usetheodev/theokit-sdk/tree/main/examples/workflow-basics).

---