@vextlabs/theron-agent-sdk 0.3.0

package/examples/adapters/openrouter.ts

@@ -0,0 +1,144 @@
+/**
+ * OpenRouter ModelAdapter — works against 200+ models for free-tier users.
+ *
+ * Used by the sample agents in the SDK. Production users should write their
+ * own adapter for their preferred provider (OpenAI direct, Anthropic, Vext
+ * managed Theron, etc.).
+ */
+import type { ModelAdapter } from "../../src/runtime/index.js";
+
+type ToolCallChunk = {
+  index?: number;
+  function?: { name?: string; arguments?: string };
+};
+
+export function openrouterAdapter(opts: {
+  apiKey: string;
+  siteName?: string;
+  siteUrl?: string;
+}): ModelAdapter {
+  if (!opts.apiKey) {
+    throw new Error(
+      "openrouterAdapter: `apiKey` is required. Get a key at https://openrouter.ai/keys.",
+    );
+  }
+  return {
+    name: "openrouter",
+    async chat({ model, messages, tools, max_tokens, temperature, onDelta }) {
+      const body: Record<string, unknown> = {
+        model,
+        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 res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${opts.apiKey}`,
+          "Content-Type": "application/json",
+          ...(opts.siteUrl ? { "HTTP-Referer": opts.siteUrl } : {}),
+          ...(opts.siteName ? { "X-Title": opts.siteName } : {}),
+        },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        const bodyText = await res.text().catch(() => "");
+        throw new Error(
+          `OpenRouter request failed (HTTP ${res.status}). Check your API key and model name. Response: ${bodyText.slice(0, 500)}`,
+        );
+      }
+
+      if (onDelta && res.body) {
+        // Streaming path — parse SSE, accumulate tool-call fragments.
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let content = "";
+        let inputTokens = 0;
+        let outputTokens = 0;
+        const toolCallBuffer = new Map<number, { name: string; argsText: string }>();
+        let buf = "";
+        while (true) {
+          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(6).trim();
+            if (!data || data === "[DONE]") continue;
+            try {
+              const json = JSON.parse(data);
+              const delta = json.choices?.[0]?.delta;
+              if (delta?.content) {
+                onDelta(delta.content);
+                content += delta.content;
+              }
+              const toolCalls: ToolCallChunk[] | undefined = delta?.tool_calls;
+              if (toolCalls) {
+                for (const tc of toolCalls) {
+                  const idx = tc.index ?? 0;
+                  const cur = toolCallBuffer.get(idx) ?? { name: "", argsText: "" };
+                  if (tc.function?.name) cur.name = tc.function.name;
+                  if (tc.function?.arguments) cur.argsText += tc.function.arguments;
+                  toolCallBuffer.set(idx, cur);
+                }
+              }
+              if (json.usage) {
+                inputTokens = json.usage.prompt_tokens ?? inputTokens;
+                outputTokens = json.usage.completion_tokens ?? outputTokens;
+              }
+            } catch {
+              // skip malformed SSE line
+            }
+          }
+        }
+        const tool_calls = Array.from(toolCallBuffer.values())
+          .filter((c) => c.name)
+          .map((c) => ({ name: c.name, input: safeJsonParse(c.argsText) }));
+        return {
+          content,
+          ...(tool_calls.length > 0 ? { tool_calls } : {}),
+          tokens: { input: inputTokens, output: outputTokens },
+        };
+      }
+
+      // Non-streaming path.
+      const json = (await res.json()) as {
+        choices: Array<{
+          message: {
+            content: string | null;
+            tool_calls?: Array<{ function: { name: string; arguments: string } }>;
+          };
+        }>;
+        usage: { prompt_tokens: number; completion_tokens: number };
+      };
+      const msg = json.choices[0].message;
+      const tool_calls = msg.tool_calls?.map((tc) => ({
+        name: tc.function.name,
+        input: safeJsonParse(tc.function.arguments),
+      }));
+      return {
+        content: msg.content ?? "",
+        ...(tool_calls && tool_calls.length > 0 ? { tool_calls } : {}),
+        tokens: { input: json.usage.prompt_tokens, output: json.usage.completion_tokens },
+      };
+    },
+  };
+}
+
+function safeJsonParse(s: string | undefined): unknown {
+  if (!s) return {};
+  try {
+    return JSON.parse(s);
+  } catch {
+    return {};
+  }
+}

package/examples/adapters/theron.ts

@@ -0,0 +1,105 @@
+/**
+ * Theron ModelAdapter — talks to the Vext-hosted council at
+ * https://tryvext.com/api/theron-chat-phased.
+ *
+ * Same OpenAI-compatible adapter shape as openrouter.ts. Use this when you
+ * want the SDK to drive the Vext Council with its trained specialists and
+ * verifier kernels instead of a single foundation model.
+ *
+ * Tool-calling is NOT yet exposed by the hosted Theron endpoint, so this
+ * adapter ignores any `tools` argument and returns only `content` + a
+ * synthetic token count. The SDK's tool-call loop is still exercised when
+ * you swap in OpenRouter / OpenAI / Anthropic adapters for local dev.
+ */
+import type { ModelAdapter } from "../../src/runtime/index.js";
+
+type ToolDef = { name: string; description: string; input_schema: Record<string, unknown> };
+
+type ChatMessage = {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+};
+
+export function theronAdapter(opts: {
+  /** Endpoint base. Defaults to tryvext.com. */
+  base?: string;
+  /** Vext API key, if you have one. Owner key is fine. Optional for OSS demo. */
+  apiKey?: string;
+  /** Which surface to advertise. Affects the Theron system prompt. */
+  surface?: "marketing" | "theron" | "aeos-personal" | "aeos-company";
+}): ModelAdapter {
+  const base = (opts.base ?? "https://tryvext.com").replace(/\/$/, "");
+  return {
+    name: "theron",
+    async chat({ messages, onDelta }: {
+      messages: ChatMessage[];
+      tools?: ToolDef[];
+      onDelta?: (delta: string) => void;
+    }) {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+      };
+      if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
+
+      const res = await fetch(`${base}/api/theron-chat-phased`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          messages: messages.map((m) => ({ role: m.role, content: m.content })),
+          surface: opts.surface ?? "theron",
+          stream: true,
+        }),
+      });
+
+      if (!res.ok || !res.body) {
+        const text = await res.text().catch(() => "");
+        throw new Error(
+          `Theron request failed (HTTP ${res.status}). Endpoint: ${base}/api/theron-chat-phased. Response: ${text.slice(0, 500)}`,
+        );
+      }
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let content = "";
+      let buf = "";
+      let currentEvent: string | null = null;
+
+      while (true) {
+        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("event:")) {
+            currentEvent = line.slice(6).trim();
+            continue;
+          }
+          if (!line.startsWith("data:")) continue;
+          const data = line.slice(5).trim();
+          if (!data) continue;
+          try {
+            const json = JSON.parse(data);
+            if (currentEvent === "token" && typeof json.t === "string") {
+              content += json.t;
+              onDelta?.(json.t);
+            } else if (currentEvent === "final" && typeof json.text === "string") {
+              content = json.text;
+            }
+          } catch {
+            // skip malformed event
+          }
+        }
+      }
+
+      // The phased endpoint does not return real token counts. We synthesize
+      // a rough estimate from character length (4 chars ≈ 1 token).
+      const approxTokens = Math.ceil(content.length / 4);
+      return {
+        content,
+        tokens: { input: 0, output: approxTokens },
+      };
+    },
+  };
+}

package/examples/basic-agent.ts

@@ -0,0 +1,56 @@
+/**
+ * basic-agent — 1 tool, calls the hosted Theron endpoint, streams to stdout.
+ *
+ * Run:
+ *   THERON_API_KEY=... npx tsx examples/basic-agent.ts
+ *
+ * What this shows:
+ *   - Define a tool with Zod (defineTool)
+ *   - Build a one-line Agent
+ *   - Drive it with Runner + theronAdapter against tryvext.com
+ *   - Stream tokens to stdout via runner.on("agent_thinking")
+ *
+ * The hosted Theron endpoint does not return tool calls today, so the agent
+ * answers from the conversation; the tool is included to show the contract.
+ * Swap theronAdapter for openrouterAdapter to get real tool-call routing.
+ */
+import { Agent, Runner, defineTool, zod as z } from "../src/index.js";
+import { theronAdapter } from "./adapters/theron.js";
+
+const wordCount = defineTool({
+  name: "word_count",
+  description: "Count words in a passage. Returns { count }.",
+  input: z.object({ text: z.string() }),
+  async execute({ text }) {
+    return { count: text.trim().split(/\s+/).filter(Boolean).length };
+  },
+});
+
+const helper = new Agent({
+  name: "helper",
+  instruction:
+    "Answer briefly. If the user gives a passage to count, call word_count.",
+  tools: [wordCount],
+});
+
+async function main() {
+  const runner = new Runner({
+    model: theronAdapter({
+      apiKey: process.env.THERON_API_KEY,
+      surface: "marketing",
+    }),
+    default_model: "theron",
+  });
+
+  runner.on((event) => {
+    if (event.type === "agent_thinking") process.stdout.write(event.delta);
+    if (event.type === "agent_output") process.stdout.write("\n");
+  });
+
+  await runner.run(helper, "In one sentence, what is the Theron Council?");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/council-deliberation.ts

@@ -0,0 +1,90 @@
+/**
+ * council-deliberation — 3 specialists + reconciler on a hard problem.
+ *
+ * Three generic agents (Engineer, Security, Product) deliberate. Verifier
+ * kernels run across every output. The default deterministic reconciler
+ * collapses agreeing claims; disagreements surface as a split consensus.
+ *
+ * Run:
+ *   OPENROUTER_API_KEY=sk-or-... npx tsx examples/council-deliberation.ts
+ *
+ * Why OpenRouter and not the Theron adapter here? Council deliberation needs
+ * three independent specialist calls. Local dev against OpenRouter gives you
+ * that for ~$0.001/run. In production, point the Runner at theronAdapter and
+ * the Vext-hosted council answers all three roles with trained LoRAs.
+ */
+import { Agent, Council, Runner, VerifierKernels } from "../src/index.js";
+import { openrouterAdapter } from "./adapters/openrouter.js";
+
+const engineer = new Agent({
+  name: "engineer",
+  instruction:
+    "You are a senior backend engineer. Answer from a system-design and " +
+    "reliability perspective. Be specific about trade-offs. Cite RFCs and " +
+    "public benchmarks where applicable.",
+});
+
+const security = new Agent({
+  name: "security",
+  instruction:
+    "You are an application-security engineer. Answer from a threat-model " +
+    "and attack-surface perspective. Flag anything that could be exploited. " +
+    "Cite OWASP / CWE / CVE where applicable.",
+});
+
+const product = new Agent({
+  name: "product",
+  instruction:
+    "You are a product manager. Answer from a user-impact and adoption " +
+    "perspective. Be specific about who this helps, who it doesn't, and " +
+    "what could backfire.",
+});
+
+const council = new Council({
+  name: "engineering-review",
+  specialists: [engineer, security, product],
+  verifiers: [VerifierKernels.emDash, VerifierKernels.aiIsm],
+});
+
+async function main() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    console.error("Set OPENROUTER_API_KEY (https://openrouter.ai/keys) and rerun.");
+    process.exit(1);
+  }
+
+  const runner = new Runner({
+    model: openrouterAdapter({ apiKey }),
+    default_model: "openai/gpt-4o-mini",
+  });
+
+  runner.on((event) => {
+    if (event.type === "specialist_done") {
+      console.log(`\n--- ${event.specialist} ---`);
+      console.log(event.output.output.slice(0, 280) + "...");
+    }
+    if (event.type === "council_done") {
+      console.log(`\n=== Council answer (${event.output.consensus}) ===`);
+      console.log(event.output.answer);
+      const splits = event.output.disagreements ?? [];
+      if (splits.length > 0) {
+        console.log(`\n=== Disagreements (${splits.length}) ===`);
+        for (const d of splits) {
+          console.log(`Claim: "${d.claim}"`);
+          console.log(`  for:     ${d.specialists_for.join(", ")}`);
+          console.log(`  against: ${d.specialists_against.join(", ")}`);
+        }
+      }
+    }
+  });
+
+  await runner.runCouncil(
+    council,
+    "Should we let users store API keys in localStorage instead of a cookie?",
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/cyber-recon-bot.ts

@@ -0,0 +1,163 @@
+/**
+ * Sample agent: cyber-recon-bot
+ *
+ * Reconnaissance agent for authorized security testing. Given a target
+ * hostname, plans a passive-recon chain (subdomain enumeration → port
+ * surface → TLS posture → tech fingerprint) and produces a structured
+ * report.
+ *
+ * SCOPE: ships with mock tools so it runs without external credentials and
+ * cannot accidentally hit a real target. Wire your own subfinder / naabu /
+ * httpx / nuclei back-ends behind the same defineTool signatures for
+ * production use. Always confirm written authorization before pointing this
+ * at a real host.
+ *
+ * Run:
+ *   OPENROUTER_API_KEY=sk-or-... npx tsx examples/cyber-recon-bot.ts
+ *
+ * What this demonstrates:
+ *   - Multi-tool agent with a tool-call loop (Runner re-enters until end_turn)
+ *   - Verifier kernels gating output style (no em-dashes, no AI-isms)
+ *   - Receipts: every tool call + the final report is emitted to a sink so
+ *     a downstream auditor can replay what the agent did
+ */
+
+import {
+  Agent,
+  Runner,
+  defineTool,
+  zod as z,
+  VerifierKernels,
+  ReceiptEmitter,
+  InMemoryReceiptSink,
+} from "../src/index.js";
+import { openrouterAdapter } from "./adapters/openrouter.js";
+
+// --- Tools (mocked so the sample runs offline) ------------------------------
+
+const enumerateSubdomains = defineTool({
+  name: "enumerate_subdomains",
+  description: "Passive subdomain enumeration (CT logs / wordlist).",
+  input: z.object({ host: z.string() }),
+  async execute({ host }) {
+    return {
+      host,
+      subdomains: [`api.${host}`, `www.${host}`, `staging.${host}`],
+    };
+  },
+});
+
+const portScan = defineTool({
+  name: "port_scan",
+  description: "Top-100 TCP port surface for a host.",
+  input: z.object({ host: z.string() }),
+  async execute({ host }) {
+    return { host, open: [80, 443, 22] };
+  },
+});
+
+const tlsPosture = defineTool({
+  name: "tls_posture",
+  description: "TLS version + cert issuer + expiry + cipher suite.",
+  input: z.object({ host: z.string(), port: z.number().optional() }),
+  async execute({ host, port }) {
+    return {
+      host,
+      port: port ?? 443,
+      tls_version: "TLS 1.3",
+      issuer: "Let's Encrypt R3",
+      expires_in_days: 27,
+      ciphers_offered: ["TLS_AES_256_GCM_SHA384"],
+    };
+  },
+});
+
+const techFingerprint = defineTool({
+  name: "tech_fingerprint",
+  description: "Detect web server + framework + CDN from HTTP headers.",
+  input: z.object({ host: z.string() }),
+  async execute({ host }) {
+    return {
+      host,
+      server: "nginx/1.25.3",
+      framework: "Next.js 14",
+      cdn: "Cloudflare",
+    };
+  },
+});
+
+// --- Agent ------------------------------------------------------------------
+
+const reconBot = new Agent({
+  name: "cyber-recon-bot",
+  instruction: `You are a passive reconnaissance agent operating under written authorization.
+
+Workflow:
+  1. enumerate_subdomains on the target host
+  2. For each discovered subdomain, port_scan + tls_posture + tech_fingerprint
+  3. Produce a structured report:
+     ## Subdomains
+     ## Port surface
+     ## TLS posture (flag expiry < 30 days)
+     ## Tech stack
+     ## Findings worth a deeper look
+
+Rules:
+  - Passive only. Never call active exploitation tools.
+  - One bullet per finding. No filler. No em-dashes or AI-isms.`,
+  tools: [enumerateSubdomains, portScan, tlsPosture, techFingerprint],
+  verifiers: [VerifierKernels.emDash, VerifierKernels.aiIsm],
+});
+
+// --- Main -------------------------------------------------------------------
+
+async function main() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    console.error("Set OPENROUTER_API_KEY (https://openrouter.ai/keys) and rerun.");
+    process.exit(1);
+  }
+
+  const runner = new Runner({
+    model: openrouterAdapter({ apiKey }),
+    default_model: "openai/gpt-4o-mini",
+  });
+
+  const sink = new InMemoryReceiptSink();
+  const receipts = new ReceiptEmitter({
+    sinks: [sink],
+    issuer: "did:web:local",
+    actor: reconBot.name,
+  });
+
+  // Emit a receipt for every tool call + the final agent output. Downstream
+  // auditors can replay what the agent saw and said.
+  runner.on(async (event) => {
+    if (event.type === "tool_call_done") {
+      await receipts.emit({
+        cap: `recon.${event.tool}`,
+        input: { tool: event.tool },
+        output: event.output,
+      });
+    }
+    if (event.type === "agent_output") {
+      await receipts.emit({
+        cap: "agent.run",
+        input: { agent: event.agent },
+        output: event.output,
+      });
+    }
+  });
+
+  const result = await runner.run(reconBot, "Recon example.com");
+  console.log("\n=== Report ===\n" + result.output);
+  console.log(`\n=== Receipts emitted: ${sink.list().length} ===`);
+  for (const r of sink.list()) {
+    console.log(`  ${r.cap} (${r.content_hash.slice(0, 12)}…)`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/loop-primitives.ts

@@ -0,0 +1,50 @@
+/**
+ * Sample: Loop primitives
+ *
+ * Demonstrates the verified-ratchet + verifier-in-the-loop primitives — the
+ * governance layer for agent loops. A loop's state advances ONLY on a confident
+ * verifier pass; stop predicates terminate the loop on verifier/cost/step
+ * conditions. No public agent SDK ships a verified ratchet as a typed primitive.
+ *
+ * Offline + deterministic — no API key. Swap the mock judges for real verifiers.
+ *
+ * Run:
+ *   npx tsx examples/loop-primitives.ts
+ */
+
+import {
+  verifiedRatchet,
+  runImprovementCycle,
+  verifierSatisfied,
+  stepCountIs,
+  anyOf,
+  type LoopState,
+} from "../src/index.js";
+
+async function main() {
+  // 1) verifiedRatchet — advance ONLY on a confident "sufficient" verdict.
+  const ratchet = verifiedRatchet({ minConfidence: 0.6 });
+  console.log("ratchet (0.9 sufficient):", ratchet({ verdict: "sufficient", confidence: 0.9 }));
+  console.log("ratchet (0.5 sufficient):", ratchet({ verdict: "sufficient", confidence: 0.5 }));
+  console.log("ratchet (insufficient):", ratchet({ verdict: "insufficient", confidence: 0.9 }));
+
+  // 2) runImprovementCycle — propose → trial → verify → ratchet, in one call.
+  const cycle = await runImprovementCycle<string, { ok: boolean }>({
+    propose: () => "a candidate improvement",
+    trial: (proposal) => ({ ok: proposal.length > 0 }),
+    verify: (_p, trial) => ({ verdict: trial.ok ? "sufficient" : "insufficient", confidence: 0.8 }),
+  });
+  console.log("cycle decision:", cycle.decision, "| advanced:", cycle.decision.advance);
+
+  // 3) stop predicates — terminate a loop on verifier / step conditions.
+  const stop = anyOf(verifierSatisfied("citation"), stepCountIs(5));
+  const stateA: LoopState = { step: 2, cost_usd: 0.01, output: "draft", verifier_results: [{ kernel: "citation", pass: true, issues: [], ms: 1 }] };
+  const stateB: LoopState = { step: 2, cost_usd: 0.01, output: "draft", verifier_results: [{ kernel: "citation", pass: false, issues: [], ms: 1 }] };
+  console.log("stop when citation passes:", stop(stateA)); // true — verifier satisfied
+  console.log("stop when citation fails @ step 2:", stop(stateB)); // false — keep going
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});