@vextlabs/theron-agent-sdk 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to `@vextlabs/theron-agent-sdk` are documented here.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-06-13
+
+### Added
+- **`patterns`** primitives — framework-agnostic, verifier/score-gated reasoning patterns no public agent SDK ships as first-class composables: `selfConsistency` (sample N paths → majority answer + agreement ratio), `bestOfN` (verifier-guided best-of-N), `selfRefine` (draft → critique → revise, early-exit when clean), `treeOfThoughts` (best-first branch/score/expand search), `chainOfVerification` (draft → verify claims independently → revise; hallucination reduction), `mixtureOfAgents` (layered multi-agent propose → refine-seeing-peers → aggregate), `reflexion` (retry with accumulated verbal reflections; learns from outcome feedback, not just output quality). Provider-agnostic (take async `generate`/`score`/`verify`/`critique` fns); pure, deterministic, zero-network. The SDK-side counterparts of Theron's server Hive loops.
+- **`measureLift`** — measure a pattern/loop's score lift + win-rate over a single-shot baseline on a task set. The empirical backbone for proving the harness beats raw single-shot ("the system is the moat") rather than asserting it. Pure; no benchmark framework required.
+- **`loop`** primitives: `verifiedRatchet` (advance only on a confident verifier pass), verifier-in-the-loop `stopWhen` predicates (`stepCountIs`/`costUsdAtLeast`/`verifierSatisfied`/`anyOf`/`allOf`), `runImprovementCycle`.
+- **Long-horizon primitives** — `compactHistory` (summarize-and-continue: fold older messages into a summary, keep recent verbatim, so a conversation/loop runs far past the context window), `runUntil` (a bounded, checkpointable long-horizon driver: run `step` until a predicate holds or `maxSteps`, with an `onCheckpoint` hook for durable resume), and `boundWorkingSet` (keep a long agent's working memory bounded by importance + recency; pinned items never evicted). Provider-agnostic + pure. The "run soo long, hold soo much context" kit.
+
+## [0.1.0] - 2026-05-23
+
+First stable npm release. The five primitives and the runtime ship under the
+`@vextlabs/theron-agent-sdk` name with no API breaks expected through the 0.1
+line.
+
+### Added (v0.1.0 release polish)
+- **`Receipts`** primitive: `ReceiptEmitter` + `InMemoryReceiptSink` + `fileReceiptSink` + `httpReceiptSink` + `ReceiptSigner` interface. Stoa-shaped receipts (`stoa.receipt.v1`) with deterministic SHA-256 content hash, ULID ids, optional detached signature. Importable as `@vextlabs/theron-agent-sdk/receipts` for tree-shake.
+- **Three sample agents** that ship in `examples/`:
+  - `cyber-recon-bot.ts` — passive recon (subdomains → ports → TLS → tech), receipts per tool call.
+  - `meeting-prep-bot.ts` — one-page meeting brief from calendar + docs + memory.
+  - `support-triage-bot.ts` — three-specialist Council that classifies + retrieves + drafts a reply, with the routing decision emitted as a signable receipt.
+- New tests at `test/receipts.test.ts` cover canonicalization, signing, sink fan-out, ULID ordering, and sink-failure isolation.
+
+### Added
+- **`Agent`** primitive: model + instruction + tools + sub-agents + verifier kernels.
+- **`Council`** primitive: N specialists + verifier kernels + reconciler. Built-in deterministic claim-merge reconciler; bring your own for semantic merging.
+- **`Session`** primitive: append-only event log + scoped state, with `toJSON` / `fromJSON` for persistence.
+- **`Memory`** primitive with `InMemoryStore` reference implementation. Tenant-scoped; ready to swap in pgvector, R2, SQLite, etc.
+- **`defineTool`** factory backed by Zod schemas (auto-converts to JSON schema for OpenAI/Anthropic-style tool calls).
+- **`defineVerifier`** factory + `VerifierKernels.{emDash, aiIsm, arithmetic, citationPresence}` built-ins.
+- **`Runner`** with pluggable `ModelAdapter` interface. Streams events (`agent_thinking`, `tool_call_*`, `verifier_run`, `council_done`, etc.). Supports per-specialist timeouts in `runCouncil`.
+- **Reference adapters** in `examples/adapters/`:
+  - `openrouter.ts` — works against 200+ models with SSE streaming + tool-call buffering.
+  - `theron.ts` — points at the hosted Vext Theron endpoint at `tryvext.com/api/theron-chat-phased`.
+- **Three runnable examples**: `basic-agent.ts`, `council-deliberation.ts`, `verifier-kernel.ts`.
+- **MCP client** at `@vextlabs/theron-agent-sdk/mcp` — `MCPClient` speaks the Model Context Protocol over streamable HTTP / SSE. `collectMcpTools()` collapses multiple servers into one namespaced `Tool[]`. Tests land in v0.1.x.
+
+### Build & tooling
+- Switched build from `tsc` to **`tsup`**. Emits ESM + CJS + `.d.ts` for every entry point. Tree-shakeable.
+- Added **`vitest`** test suite with 58 tests covering the 5 primitives + runtime + built-in kernels.
+- Added **`@vitest/coverage-v8`** with thresholds at 80% lines / 80% functions / 70% branches; current coverage 95%+ lines.
+- Added **`typedoc`** for API reference generation (`npm run docs`); output lands in `docs/`.
+
+### Notes
+- Runner's `runCouncil` passes `claims: []` to the reconciler — claim extraction is the reconciler's job. The default deterministic reconciler therefore returns `refuted` for generic prose; swap in a semantic reconciler or a claim-extracting one for production deliberation.
+- The MCP subpath is excluded from the 80% coverage threshold pending dedicated tests.
+
+## [0.1.0-alpha] - 2026-05-12
+
+Pre-release. SDK surface defined under five primitives; `tsc` build; node `--test` harness; sample agents under numeric prefixes (`01_*`, `02_*`, `03_*`).
+
+[0.1.0]: https://github.com/Vext-Labs-Inc/theron-agent-sdk/releases/tag/v0.1.0
+[0.1.0-alpha]: https://github.com/Vext-Labs-Inc/theron-agent-sdk/releases/tag/v0.1.0-alpha

package/LICENSE

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

package/README.md

@@ -0,0 +1,270 @@
+# Theron Agent SDK
+
+> Build agents that work, with receipts you can verify. Any model. MIT.
+
+[![npm](https://img.shields.io/npm/v/@vextlabs/theron-agent-sdk.svg)](https://www.npmjs.com/package/@vextlabs/theron-agent-sdk)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](https://nodejs.org/)
+[![tests](https://img.shields.io/badge/tests-64%20passing-brightgreen.svg)](#tests)
+
+```sh
+npm install @vextlabs/theron-agent-sdk
+```
+
+```ts
+import { Agent, Runner } from "@vextlabs/theron-agent-sdk";
+import { openrouterAdapter } from "@vextlabs/theron-agent-sdk/examples/adapters/openrouter.js";
+
+const agent = new Agent({ name: "helper", instruction: "Answer helpfully." });
+const runner = new Runner({ model: openrouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY! }), default_model: "openai/gpt-4o-mini" });
+const result = await runner.run(agent, "What's 2+2?");
+console.log(result.output);
+```
+
+That is a runnable agent in five lines. Requires Node 20+. An `OPENROUTER_API_KEY` gets you 200+ models through one adapter; swap in Anthropic, OpenAI, or your own OSS endpoint by writing a 30-line `ModelAdapter`.
+
+---
+
+## 15-line Council
+
+```ts
+import { Agent, Council, Runner, VerifierKernels } from "@vextlabs/theron-agent-sdk";
+
+const engineer = new Agent({ name: "engineer", instruction: "Answer from a backend reliability perspective." });
+const security = new Agent({ name: "security", instruction: "Answer from a threat-model perspective." });
+const product  = new Agent({ name: "product",  instruction: "Answer from a user-impact perspective." });
+
+const council = new Council({
+  name: "engineering-review",
+  specialists: [engineer, security, product],
+  verifiers: [VerifierKernels.emDash, VerifierKernels.aiIsm, VerifierKernels.citationPresence],
+});
+
+const result = await runner.runCouncil(council, "Should we store API keys in localStorage?");
+console.log(result.answer);             // synthesized answer
+console.log(result.consensus);          // "ratified" | "split" | "refuted"
+console.log(result.disagreements);      // surfaced if specialists disagreed
+```
+
+## Why Theron
+
+| | Theron Agent SDK | Claude Agent SDK | OpenAI Assistants | Vercel AI SDK |
+|---|---|---|---|---|
+| Multi-specialist deliberation | First-class `Council` primitive with deterministic reconciliation | Sub-agents, you write the deliberation loop | Single assistant, you wire fan-out | Single model, you wire fan-out |
+| Output verification before return | Built-in `VerifierKernels` (em-dash, AI-ism, arithmetic, citation) plus `defineVerifier` | Hooks pattern, you implement the checkers | None built-in | None built-in |
+| Audit chain on every agent action | `Receipts` primitive: content-hashed, optionally ES256-signed, Merkle-anchorable via Stoa | None built-in | None built-in | None built-in |
+
+The receipt chain is the differentiator. Every tool call, every Council vote, every output emits a content-hashed receipt you can sign with your own key and anchor in a daily Merkle root. When someone asks "did an AI do this," you hand them a document, not a vibe.
+
+The SDK is model-agnostic. The verifier kernels and the receipt chain work the same whether you point at OpenRouter, Anthropic, OpenAI, a local Ollama, or the hosted Theron substrate.
+
+## The five primitives
+
+| Primitive | What it is | Why it matters |
+|---|---|---|
+| `Agent` (composer) | A model + instruction + tools + sub-agents + verifier slugs | The 5-line agent — every other framework starts here |
+| `Runner` | The execution loop — LLM call + tool dispatch + verifier sweep + event stream | Pluggable `ModelAdapter` (OpenRouter, Anthropic, OpenAI, your own endpoint) |
+| `Verifier` | Deterministic render-then-judge / regex / arithmetic / citation kernels | Fast, free, no second LLM call — built-ins in `VerifierKernels` |
+| `Receipts` | `ReceiptEmitter` + sinks — Stoa-shaped, content-hashed, optionally signed | Audit trail every external system can verify, no Vext lock-in |
+| `Council` | N specialists + verifier kernels + a reconciler | Multi-specialist deliberation as a first-class primitive |
+
+Plus:
+- `Session` — append-only event log + scoped state (checkpoint + time-travel debug)
+- `Memory` — cross-session, durable knowledge (`InMemoryStore` ships; plug in pgvector / R2 / SQLite for production)
+- `Tool` — typed function with auto-injected `ToolContext`; schema-from-Zod
+- `MCPClient` — Model Context Protocol over HTTP/SSE; surfaces any MCP server as `Tool[]`
+
+## Why a Council?
+
+Every other agent framework binds to a model name string (`gpt-4o`, `claude-3-5-sonnet`). Theron Agent SDK binds to a Council of N specialists who deliberate and produce a reconciled answer.
+
+```ts
+// Standard agent — one model decides
+const out = await runner.run(agent, "Review this PR for security risks");
+
+// Council — three specialists deliberate, verifier kernels check, reconciler synthesizes
+const out = await runner.runCouncil(council, "Review this PR for security risks");
+// out.consensus === "ratified"  — all three agreed
+// or out.consensus === "split"   — disagreements surfaced (don't hide them — show them to the user)
+```
+
+**The Council primitive doesn't require Vext's managed substrate.** You can run a Council of three generic OpenRouter agents and the SDK handles the deliberation + verifier dispatch + reconciliation locally.
+
+When you upgrade to Vext-managed Theron, the same Council code points at our 15 trained Layer-1 LoRA specialists — same SDK surface, dramatically better per-domain output.
+
+## Verifier kernels: fast, deterministic, free
+
+Verifier kernels are NOT another LLM call. They're small typed checkers that run after your agent produces output:
+
+```ts
+import { VerifierKernels, defineVerifier } from "@vextlabs/theron-agent-sdk";
+
+// Built-in kernels
+VerifierKernels.emDash         // block em-dashes (AI tell)
+VerifierKernels.aiIsm          // block "delve", "tapestry", "leverage", etc.
+VerifierKernels.arithmetic     // re-evaluate "X op Y = Z" claims
+VerifierKernels.citationPresence  // require at least one citation
+
+// Roll your own
+const noProfanity = defineVerifier({
+  name: "no_profanity",
+  description: "Block profanity in customer-facing output.",
+  check: async (output) => {
+    const bad = ["badword1", "badword2"];
+    const issues = bad
+      .filter((w) => output.toLowerCase().includes(w))
+      .map((w) => ({ kernel: "no_profanity", severity: "error" as const, message: `profanity: ${w}` }));
+    return { pass: issues.length === 0, issues };
+  },
+});
+```
+
+Every kernel runs in milliseconds. Pure regex / arithmetic / hash-equal. **No additional LLM cost.**
+
+## Reasoning patterns & loop primitives
+
+Framework- and provider-agnostic primitives for verifier/score-gated reasoning —
+the SDK-side counterparts of Theron's server Hive loops. Each takes plain async
+functions (`generate` / `score` / `verify` / `critique`), so they work on any
+model and compose anywhere. No other public agent SDK ships these as first-class
+typed primitives.
+
+```ts
+import {
+  selfConsistency,    // sample N paths → majority answer + agreement ratio
+  bestOfN,            // verifier-guided best-of-N
+  selfRefine,         // draft → critique → revise (early-exit when clean)
+  treeOfThoughts,     // best-first branch / score / expand search
+  chainOfVerification,// draft → verify claims independently → revise
+  mixtureOfAgents,    // layered multi-agent propose → refine → aggregate
+  reflexion,          // retry with accumulated verbal reflections (verbal RL)
+  measureLift,        // measure a pattern's score-lift vs single-shot baseline
+  verifiedRatchet,    // advance loop state ONLY on a confident verifier pass
+  stepCountIs, verifierSatisfied, anyOf, allOf, // verifier-in-the-loop stop predicates
+  runImprovementCycle,
+  compactHistory,     // summarize-and-continue: run far past the context window
+  runUntil,           // bounded, checkpointable long-horizon driver (run soo long)
+} from "@vextlabs/theron-agent-sdk";
+
+const { answer, consistency } = await selfConsistency({
+  samples: 5,
+  generate: (i) => model.complete(prompt, { seed: i }),
+});
+```
+
+See [`examples/reasoning-patterns.ts`](examples/reasoning-patterns.ts) for all
+five run end-to-end (offline, no API key).
+
+## How this compares
+
+| | Theron Agent SDK | Hermes-Agent | Claude Agent SDK | Google ADK | LangGraph |
+|---|---|---|---|---|---|
+| License | **MIT** | MIT | Apache 2.0 | Apache 2.0 | MIT |
+| Multi-agent / Council | **First-class primitive with reconciler** | Sub-agents | Sub-agents | Multi-agent patterns | Supervisor / swarm |
+| Verifier kernels | **First-class typed kernels** | Skill assertions | Hooks pattern | User-implemented | User-implemented |
+| Memory + Session | Session (event log) + Memory (cross-session, swappable backend) | Honcho dialectic | Hooks-based | ADK Memory | Checkpointer |
+| Tool typing | **Zod schemas, validated I/O** | Function decorators | Pydantic schemas | Pydantic | Pydantic |
+| Model-agnostic | **Yes — any OpenAI-compatible endpoint** | Yes — 200+ via OpenRouter | Claude-optimized | Gemini-optimized | Yes |
+| Signed integrations | **Stoa cap protocol (ES256 receipts + Merkle anchor)** | MCP (no integrity) | MCP | MCP | Custom |
+| Managed substrate path | [Vext Theron — 15-specialist Council + per-tenant LoRA tuning](https://theron.tryvext.com) | Nous Portal | Anthropic API | Vertex AI | LangGraph Cloud |
+
+We're not trying to beat Hermes-Agent on community size or Claude Agent SDK on Claude-specific polish. We're shipping the three primitives nobody else ships first-class: **Council + Verifier kernels + Signed integrations.** Plus the optional managed substrate where you get our trained specialists.
+
+## Receipts: every agent action, signable
+
+The `Receipts` primitive gives every agent action a portable, content-hashed,
+optionally signed record. Receipts are shaped to drop straight into a Stoa
+sink, but the SDK runs offline with an in-memory sink for tests.
+
+```ts
+import {
+  ReceiptEmitter, InMemoryReceiptSink, fileReceiptSink, httpReceiptSink,
+} from "@vextlabs/theron-agent-sdk";
+
+const receipts = new ReceiptEmitter({
+  sinks: [
+    new InMemoryReceiptSink(),
+    fileReceiptSink("./receipts.jsonl"),
+    httpReceiptSink({ url: "https://stoa.tryvext.com/sink", token: process.env.STOA }),
+  ],
+  issuer: "did:web:acme.com",
+  actor: "support-triage-bot",
+});
+
+runner.on(async (event) => {
+  if (event.type === "tool_call_done") {
+    await receipts.emit({
+      cap: `vext.${event.tool}`,
+      input: { tool: event.tool },
+      output: event.output,
+    });
+  }
+});
+```
+
+Every receipt has a deterministic `content_hash` (sorted-key SHA-256). Provide
+a `ReceiptSigner` to attach an ES256 / Ed25519 / HMAC detached signature.
+
+## Runnable examples
+
+The SDK ships with runnable examples in `examples/`. None require external
+network credentials — the agent examples mock every tool so they run offline
+against any OpenRouter-compatible model, and the pattern/loop examples are fully
+offline (no key at all).
+
+| Example | What it shows |
+|---|---|
+| `cyber-recon-bot.ts` | Multi-tool recon chain (subdomains → ports → TLS → tech). Every tool call emits a receipt. |
+| `meeting-prep-bot.ts` | Calendar + docs + memory composition; produces a one-page meeting brief. |
+| `support-triage-bot.ts` | Three-specialist Council (classifier + retriever + writer); routing decision emitted as a signable receipt. |
+| `reasoning-patterns.ts` | All five reasoning patterns end-to-end (self-consistency, best-of-N, self-refine, tree-of-thoughts, chain-of-verification). **No key — fully offline.** |
+| `loop-primitives.ts` | Verified ratchet, `runImprovementCycle`, and verifier-in-the-loop stop predicates. **No key — fully offline.** |
+
+```sh
+OPENROUTER_API_KEY=sk-or-... npm run example:cyber
+OPENROUTER_API_KEY=sk-or-... npm run example:meeting
+OPENROUTER_API_KEY=sk-or-... npm run example:support
+# offline, no key needed:
+npx tsx examples/reasoning-patterns.ts
+npx tsx examples/loop-primitives.ts
+```
+
+## What this SDK is NOT
+
+This package is the framework. It is intentionally NOT:
+
+- A pre-trained model — bring your own (OpenRouter / OpenAI / Anthropic / your own OSS base)
+- A pre-built agent fleet — there are 3 sample agents in `examples/` to show you how to build, then you build your own
+- A hosted runtime — run it on your own infra (Node, Bun, Deno, serverless, container)
+
+If you want the trained 15-specialist Council, the 450+ curated industry-pack worker agents, the auto-improving Meta agents, or per-tenant overnight LoRA tuning — that's [Vext's managed Theron](https://theron.tryvext.com). The SDK is free; the substrate is the product.
+
+## Documentation
+
+- [Docs site](https://tryvext.com/adk)
+- [Architecture](./docs/architecture.md)
+- [API reference](./docs/api.md)
+- [Migration guide (from LangChain / CrewAI / AutoGen)](./docs/migration.md)
+- [Stoa cap protocol](https://github.com/Vext-Labs-Inc/stoa)
+
+## More from Vext Labs
+
+The SDK is one corner of a larger surface. The full picture lives on the Vext Labs organization page: [github.com/Vext-Labs-Inc](https://github.com/Vext-Labs-Inc). Theron the product is at [theron.tryvext.com](https://theron.tryvext.com).
+
+## Contributing
+
+PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). We're particularly interested in:
+- Model adapters (Anthropic Claude direct, AWS Bedrock, etc.)
+- Verifier kernels for specific domains (SQL syntax check, K8s YAML lint, etc.)
+- Memory backends (pgvector, sqlite-vec, R2)
+- Persistence adapters for `Session` (Postgres, Redis, KV)
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Built by [Vext Labs, Inc.](https://tryvext.com) (Maryland). Founder: Annalea Layton.
+
+---
+
+*The framework is yours forever. The moat is the substrate underneath.*

package/dist/adapters/theron.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// src/adapters/theron.ts
+function theronAdapter(opts = {}) {
+  const base = (opts.base ?? "https://itstheron.com").replace(/\/$/, "");
+  const url = `${base}/api/v1/chat/completions`;
+  const councilMode = opts.councilMode ?? "fast";
+  return {
+    name: "theron",
+    async chat({ model, messages, tools, max_tokens, temperature, onDelta }) {
+      const body = {
+        model: model || "theron-council",
+        council_mode: councilMode,
+        messages,
+        max_tokens: max_tokens ?? 2048,
+        temperature: temperature ?? 0.2,
+        stream: !!onDelta
+      };
+      if (tools && tools.length > 0) {
+        body.tools = tools.map((t) => ({
+          type: "function",
+          function: { name: t.name, description: t.description, parameters: t.input_schema }
+        }));
+      }
+      const headers = { "Content-Type": "application/json" };
+      if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
+      const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+      if (!res.ok) {
+        throw new Error(`Theron ${res.status} (${url}): ${(await res.text().catch(() => "")).slice(0, 500)}`);
+      }
+      if (onDelta && res.body) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let content = "";
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let buf = "";
+        for (; ; ) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.startsWith("data:")) continue;
+            const data = line.slice(5).trim();
+            if (!data || data === "[DONE]") continue;
+            try {
+              const json2 = JSON.parse(data);
+              const delta = json2.choices?.[0]?.delta?.content;
+              if (delta) {
+                onDelta(delta);
+                content += delta;
+              }
+              if (json2.usage) {
+                inputTokens = json2.usage.prompt_tokens ?? inputTokens;
+                outputTokens = json2.usage.completion_tokens ?? outputTokens;
+              }
+            } catch {
+            }
+          }
+        }
+        return { content, tokens: { input: inputTokens, output: outputTokens } };
+      }
+      const json = await res.json();
+      const msg = json.choices?.[0]?.message ?? { content: "" };
+      const tool_calls = msg.tool_calls?.map((tc) => ({
+        name: tc.function.name,
+        input: safeJson(tc.function.arguments)
+      }));
+      return {
+        content: msg.content ?? "",
+        tool_calls,
+        tokens: {
+          input: json.usage?.prompt_tokens ?? 0,
+          output: json.usage?.completion_tokens ?? 0
+        }
+      };
+    }
+  };
+}
+var theron = theronAdapter;
+function safeJson(s) {
+  try {
+    return JSON.parse(s || "{}");
+  } catch {
+    return {};
+  }
+}
+
+exports.theron = theron;
+exports.theronAdapter = theronAdapter;

package/dist/adapters/theron.d.cts

@@ -0,0 +1,42 @@
+import { ModelAdapter } from '../runtime/index.cjs';
+import '../agent/index.cjs';
+import '../tools/index.cjs';
+import 'zod';
+import '../verifiers/index.cjs';
+import '../council/index.cjs';
+import '../session/index.cjs';
+import '../memory/index.cjs';
+
+/**
+ * Theron ModelAdapter — first-class, built-in. Drives the Vext-hosted Theron
+ * council so agents you build with this SDK run on Theron's substrate (the
+ * trained specialists + verifier kernels), not a single foundation model.
+ *
+ *   import { Agent, Runner, theronAdapter } from "@vextlabs/theron-agent-sdk";
+ *
+ *   const runner = new Runner({
+ *     model: theronAdapter({ apiKey: process.env.THERON_API_KEY }),
+ *     default_model: "theron-council",
+ *   });
+ *
+ * Talks to the OpenAI-compatible council endpoint
+ * (`<base>/api/v1/chat/completions`), so tool-calling and streaming work the
+ * same way they do for the OpenAI/OpenRouter reference adapters — unlike the
+ * older phased-SSE example, which could not call tools.
+ */
+
+interface TheronAdapterOptions {
+    /** Endpoint base. Defaults to the hosted council at itstheron.com. */
+    base?: string;
+    /** Vext / Theron bearer key. Optional for free-tier LLM caps; required for
+     *  anything privileged. */
+    apiKey?: string;
+    /** Council mode: "fast" (cheaper cascade) or "full" (deep). Default "fast". */
+    councilMode?: "fast" | "full";
+}
+/** Build a first-class Theron adapter. Alias: `theron`. */
+declare function theronAdapter(opts?: TheronAdapterOptions): ModelAdapter;
+/** Convenience alias matching the docs voice (`theron({...})`). */
+declare const theron: typeof theronAdapter;
+
+export { type TheronAdapterOptions, theron, theronAdapter };

package/dist/adapters/theron.d.ts

@@ -0,0 +1,42 @@
+import { ModelAdapter } from '../runtime/index.js';
+import '../agent/index.js';
+import '../tools/index.js';
+import 'zod';
+import '../verifiers/index.js';
+import '../council/index.js';
+import '../session/index.js';
+import '../memory/index.js';
+
+/**
+ * Theron ModelAdapter — first-class, built-in. Drives the Vext-hosted Theron
+ * council so agents you build with this SDK run on Theron's substrate (the
+ * trained specialists + verifier kernels), not a single foundation model.
+ *
+ *   import { Agent, Runner, theronAdapter } from "@vextlabs/theron-agent-sdk";
+ *
+ *   const runner = new Runner({
+ *     model: theronAdapter({ apiKey: process.env.THERON_API_KEY }),
+ *     default_model: "theron-council",
+ *   });
+ *
+ * Talks to the OpenAI-compatible council endpoint
+ * (`<base>/api/v1/chat/completions`), so tool-calling and streaming work the
+ * same way they do for the OpenAI/OpenRouter reference adapters — unlike the
+ * older phased-SSE example, which could not call tools.
+ */
+
+interface TheronAdapterOptions {
+    /** Endpoint base. Defaults to the hosted council at itstheron.com. */
+    base?: string;
+    /** Vext / Theron bearer key. Optional for free-tier LLM caps; required for
+     *  anything privileged. */
+    apiKey?: string;
+    /** Council mode: "fast" (cheaper cascade) or "full" (deep). Default "fast". */
+    councilMode?: "fast" | "full";
+}
+/** Build a first-class Theron adapter. Alias: `theron`. */
+declare function theronAdapter(opts?: TheronAdapterOptions): ModelAdapter;
+/** Convenience alias matching the docs voice (`theron({...})`). */
+declare const theron: typeof theronAdapter;
+
+export { type TheronAdapterOptions, theron, theronAdapter };

package/dist/adapters/theron.js

@@ -0,0 +1,89 @@
+// src/adapters/theron.ts
+function theronAdapter(opts = {}) {
+  const base = (opts.base ?? "https://itstheron.com").replace(/\/$/, "");
+  const url = `${base}/api/v1/chat/completions`;
+  const councilMode = opts.councilMode ?? "fast";
+  return {
+    name: "theron",
+    async chat({ model, messages, tools, max_tokens, temperature, onDelta }) {
+      const body = {
+        model: model || "theron-council",
+        council_mode: councilMode,
+        messages,
+        max_tokens: max_tokens ?? 2048,
+        temperature: temperature ?? 0.2,
+        stream: !!onDelta
+      };
+      if (tools && tools.length > 0) {
+        body.tools = tools.map((t) => ({
+          type: "function",
+          function: { name: t.name, description: t.description, parameters: t.input_schema }
+        }));
+      }
+      const headers = { "Content-Type": "application/json" };
+      if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
+      const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+      if (!res.ok) {
+        throw new Error(`Theron ${res.status} (${url}): ${(await res.text().catch(() => "")).slice(0, 500)}`);
+      }
+      if (onDelta && res.body) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let content = "";
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let buf = "";
+        for (; ; ) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.startsWith("data:")) continue;
+            const data = line.slice(5).trim();
+            if (!data || data === "[DONE]") continue;
+            try {
+              const json2 = JSON.parse(data);
+              const delta = json2.choices?.[0]?.delta?.content;
+              if (delta) {
+                onDelta(delta);
+                content += delta;
+              }
+              if (json2.usage) {
+                inputTokens = json2.usage.prompt_tokens ?? inputTokens;
+                outputTokens = json2.usage.completion_tokens ?? outputTokens;
+              }
+            } catch {
+            }
+          }
+        }
+        return { content, tokens: { input: inputTokens, output: outputTokens } };
+      }
+      const json = await res.json();
+      const msg = json.choices?.[0]?.message ?? { content: "" };
+      const tool_calls = msg.tool_calls?.map((tc) => ({
+        name: tc.function.name,
+        input: safeJson(tc.function.arguments)
+      }));
+      return {
+        content: msg.content ?? "",
+        tool_calls,
+        tokens: {
+          input: json.usage?.prompt_tokens ?? 0,
+          output: json.usage?.completion_tokens ?? 0
+        }
+      };
+    }
+  };
+}
+var theron = theronAdapter;
+function safeJson(s) {
+  try {
+    return JSON.parse(s || "{}");
+  } catch {
+    return {};
+  }
+}
+
+export { theron, theronAdapter };

package/dist/agent/index.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+// src/agent/index.ts
+var Agent = class {
+  name;
+  model;
+  instruction;
+  tools;
+  sub_agents;
+  verifiers;
+  max_turns;
+  constructor(config) {
+    if (!config.name) throw new Error("Agent requires a `name`.");
+    if (!config.instruction) throw new Error(`Agent "${config.name}" requires an \`instruction\`.`);
+    this.name = config.name;
+    this.model = config.model;
+    this.instruction = typeof config.instruction === "string" ? { system: config.instruction } : config.instruction;
+    this.tools = config.tools ?? [];
+    this.sub_agents = config.sub_agents ?? [];
+    this.verifiers = config.verifiers ?? [];
+    this.max_turns = config.max_turns ?? 10;
+  }
+  /** Render the tools as JSON schemas for the model. */
+  toolSchemas() {
+    return this.tools.map((t) => t.schema);
+  }
+  /** True if the agent has any sub-agents (i.e., this is a supervisor). */
+  isSupervisor() {
+    return this.sub_agents.length > 0;
+  }
+};
+
+exports.Agent = Agent;