@vextlabs/theron-agent-sdk 0.3.0

package/dist/receipts/index.js

@@ -0,0 +1,146 @@
+// src/receipts/index.ts
+var ReceiptEmitter = class {
+  sinks;
+  signer;
+  issuer;
+  actor;
+  tenant_id;
+  constructor(config) {
+    if (!config.sinks || config.sinks.length === 0) {
+      throw new Error("ReceiptEmitter requires at least one sink.");
+    }
+    this.sinks = config.sinks;
+    this.signer = config.signer;
+    this.issuer = config.signer?.issuer ?? config.issuer ?? "did:web:local";
+    this.actor = config.actor;
+    this.tenant_id = config.tenant_id;
+  }
+  async emit(input) {
+    const ts = Date.now();
+    const payload = {
+      input: input.input,
+      output: input.output,
+      ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
+    };
+    const content_hash = await sha256Hex(canonicalize(payload));
+    let receipt = {
+      v: "stoa.receipt.v1",
+      id: ulid(),
+      cap: input.cap,
+      issuer: this.issuer,
+      actor: input.actor ?? this.actor,
+      ts,
+      session_id: input.session_id,
+      tenant_id: input.tenant_id ?? this.tenant_id,
+      content_hash,
+      payload
+    };
+    if (this.signer) {
+      const signature = await this.signer.sign(receipt);
+      receipt = { ...receipt, signature };
+    }
+    await Promise.all(
+      this.sinks.map(async (sink) => {
+        try {
+          await sink.emit(receipt);
+        } catch (err) {
+          console.warn(`[receipts] sink "${sink.name}" failed:`, err);
+        }
+      })
+    );
+    return receipt;
+  }
+};
+var InMemoryReceiptSink = class {
+  name = "in-memory";
+  records = [];
+  async emit(receipt) {
+    this.records.push(receipt);
+  }
+  list() {
+    return this.records;
+  }
+  clear() {
+    this.records.length = 0;
+  }
+};
+function fileReceiptSink(path) {
+  return {
+    name: `file:${path}`,
+    async emit(receipt) {
+      const fs = await import('fs/promises');
+      await fs.appendFile(path, JSON.stringify(receipt) + "\n", "utf8");
+    }
+  };
+}
+function httpReceiptSink(opts) {
+  const timeout_ms = opts.timeout_ms ?? 5e3;
+  return {
+    name: `http:${new URL(opts.url).host}`,
+    async emit(receipt) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeout_ms);
+      try {
+        const res = await fetch(opts.url, {
+          method: "POST",
+          signal: ac.signal,
+          headers: {
+            "Content-Type": "application/json",
+            ...opts.token ? { Authorization: `Bearer ${opts.token}` } : {}
+          },
+          body: JSON.stringify(receipt)
+        });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          throw new Error(
+            `http sink ${opts.url} returned ${res.status}: ${text.slice(0, 200)}`
+          );
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => canonicalize(v)).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return "{" + keys.map(
+    (k) => JSON.stringify(k) + ":" + canonicalize(value[k])
+  ).join(",") + "}";
+}
+async function sha256Hex(input) {
+  const data = new TextEncoder().encode(input);
+  const buf = await globalThis.crypto.subtle.digest("SHA-256", data);
+  const bytes = new Uint8Array(buf);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function ulid() {
+  const ts = Date.now();
+  const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+  let tsPart = "";
+  let t = ts;
+  for (let i = 9; i >= 0; i--) {
+    tsPart = ALPHABET[t % 32] + tsPart;
+    t = Math.floor(t / 32);
+  }
+  let randPart = "";
+  if (globalThis.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    for (let i = 0; i < 16; i++) randPart += ALPHABET[bytes[i] % 32];
+  } else {
+    for (let i = 0; i < 16; i++)
+      randPart += ALPHABET[Math.floor(Math.random() * 32)];
+  }
+  return tsPart + randPart;
+}
+
+export { InMemoryReceiptSink, ReceiptEmitter, fileReceiptSink, httpReceiptSink };

package/dist/runtime/index.cjs

@@ -0,0 +1,205 @@
+'use strict';
+
+// src/runtime/index.ts
+var Runner = class {
+  model;
+  default_model;
+  memory;
+  session;
+  tool_context;
+  listeners = [];
+  constructor(config) {
+    if (!config.model) throw new Error("Runner requires a `model` adapter.");
+    if (!config.default_model) throw new Error("Runner requires a `default_model` identifier.");
+    this.model = config.model;
+    this.default_model = config.default_model;
+    this.memory = config.memory;
+    this.session = config.session;
+    this.tool_context = config.tool_context ?? { cwd: process.cwd(), yolo: false };
+  }
+  /** Subscribe to runner events for streaming UIs / observability. */
+  on(handler) {
+    this.listeners.push(handler);
+    return () => {
+      this.listeners = this.listeners.filter((h) => h !== handler);
+    };
+  }
+  emit(event) {
+    for (const h of this.listeners) h(event);
+  }
+  /**
+   * Run a single agent on a query.
+   *
+   * Loop:
+   *   1. Send messages + tool schemas to the model
+   *   2. If model returns a tool call → execute the tool → append result to messages → repeat
+   *   3. If model returns content + end_turn → finalize
+   *   4. Run any registered verifier kernels on the final output
+   *   5. Return the AgentResult
+   */
+  async run(agent, query) {
+    const startedAt = Date.now();
+    this.emit({ type: "agent_start", agent: agent.name, query });
+    const messages = [
+      { role: "system", content: agent.instruction.system }
+    ];
+    for (const ex of agent.instruction.examples ?? []) {
+      messages.push({ role: "user", content: ex.user });
+      messages.push({ role: "assistant", content: ex.assistant });
+    }
+    messages.push({ role: "user", content: query });
+    const toolCalls = [];
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let finalOutput = "";
+    for (let turn = 0; turn < agent.max_turns; turn++) {
+      const response = await this.model.chat({
+        model: agent.model ?? this.default_model,
+        messages,
+        tools: agent.toolSchemas(),
+        onDelta: (delta) => this.emit({ type: "agent_thinking", agent: agent.name, delta })
+      });
+      tokensIn += response.tokens.input;
+      tokensOut += response.tokens.output;
+      if (response.tool_calls && response.tool_calls.length > 0) {
+        messages.push({ role: "assistant", content: response.content });
+        for (const call of response.tool_calls) {
+          const tool = agent.tools.find((t) => t.schema.name === call.name);
+          if (!tool) {
+            this.emit({
+              type: "error",
+              agent: agent.name,
+              message: `Model called unknown tool: ${call.name}`
+            });
+            messages.push({ role: "tool", content: `error: unknown tool ${call.name}` });
+            continue;
+          }
+          this.emit({ type: "tool_call_start", agent: agent.name, tool: call.name, input: call.input });
+          const t0 = Date.now();
+          try {
+            const output = await tool.execute(call.input, this.tool_context);
+            const ms = Date.now() - t0;
+            this.emit({ type: "tool_call_done", agent: agent.name, tool: call.name, output, ms });
+            toolCalls.push({ name: call.name, input: call.input, output });
+            messages.push({ role: "tool", content: JSON.stringify(output) });
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.emit({ type: "error", agent: agent.name, message: `Tool ${call.name} threw: ${msg}` });
+            messages.push({ role: "tool", content: `error: ${msg}` });
+          }
+        }
+        continue;
+      }
+      finalOutput = response.content;
+      messages.push({ role: "assistant", content: finalOutput });
+      break;
+    }
+    this.emit({ type: "agent_output", agent: agent.name, output: finalOutput });
+    const verifier_results = [];
+    for (const v of agent.verifiers) {
+      try {
+        const result = await v.check(finalOutput);
+        verifier_results.push(result);
+        this.emit({ type: "verifier_run", agent: agent.name, kernel: v.name, result });
+      } catch (err) {
+        this.emit({
+          type: "error",
+          agent: agent.name,
+          message: `Verifier ${v.name} threw: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }
+    const latency_ms = Date.now() - startedAt;
+    return {
+      agent: agent.name,
+      output: finalOutput,
+      tool_calls: toolCalls,
+      verifier_results,
+      tokens_used: { input: tokensIn, output: tokensOut },
+      cost_usd: 0,
+      // adapter-specific; populated by adapter
+      latency_ms
+    };
+  }
+  /**
+   * Run a Council on a query.
+   *
+   * Fan out to all specialists in parallel (with timeout), gather outputs,
+   * run council-level verifier kernels on each, and reconcile.
+   */
+  async runCouncil(council, query) {
+    const startedAt = Date.now();
+    this.emit({ type: "council_start", council: council.name, query });
+    const withTimeout = (p, ms) => Promise.race([
+      p,
+      new Promise((resolve) => setTimeout(() => resolve(null), ms))
+    ]);
+    const specialistResults = await Promise.all(
+      council.specialists.map(async (spec) => {
+        try {
+          const result = await withTimeout(this.run(spec, query), council.specialist_timeout_ms);
+          if (result === null) {
+            this.emit({
+              type: "error",
+              agent: spec.name,
+              message: `Specialist timed out after ${council.specialist_timeout_ms}ms`
+            });
+            return null;
+          }
+          const councilVerifierResults = [];
+          for (const v of council.verifiers) {
+            try {
+              const r = await v.check(result.output);
+              councilVerifierResults.push(r);
+              this.emit({ type: "verifier_run", agent: spec.name, kernel: v.name, result: r });
+            } catch (err) {
+              this.emit({
+                type: "error",
+                agent: spec.name,
+                message: `Council verifier ${v.name} threw: ${err instanceof Error ? err.message : String(err)}`
+              });
+            }
+          }
+          const out = {
+            specialist: spec.name,
+            output: result.output,
+            claims: [],
+            // claim extraction is the reconciler's job
+            // AgentResult.verifier_results widens issues to unknown[]; at the
+            // runtime layer we know every entry came from a Verifier.check()
+            // call (which produces VerifierIssue[]), so the cast is sound.
+            verifier_results: [
+              ...result.verifier_results,
+              ...councilVerifierResults
+            ],
+            cost_usd: result.cost_usd,
+            latency_ms: result.latency_ms
+          };
+          this.emit({ type: "specialist_done", specialist: spec.name, output: out });
+          return out;
+        } catch (err) {
+          this.emit({
+            type: "error",
+            agent: spec.name,
+            message: err instanceof Error ? err.message : String(err)
+          });
+          return null;
+        }
+      })
+    );
+    const survivors = specialistResults.filter((s) => s !== null);
+    const reconciled = await council.reconciler(survivors);
+    const output = {
+      answer: reconciled.answer,
+      specialists: survivors,
+      consensus: reconciled.consensus,
+      disagreements: reconciled.disagreements,
+      total_cost_usd: survivors.reduce((s, x) => s + x.cost_usd, 0),
+      total_latency_ms: Date.now() - startedAt
+    };
+    this.emit({ type: "council_done", council: council.name, output });
+    return output;
+  }
+};
+
+exports.Runner = Runner;

package/dist/runtime/index.d.cts

@@ -0,0 +1,148 @@
+import { Agent, AgentResult } from '../agent/index.cjs';
+import { CouncilSpecialistOutput, CouncilOutput, Council } from '../council/index.cjs';
+import { Session } from '../session/index.cjs';
+import { Memory } from '../memory/index.cjs';
+import { ToolContext } from '../tools/index.cjs';
+import { VerifierResult } from '../verifiers/index.cjs';
+import 'zod';
+
+/** Events the Runner emits as it executes. Subscribe via runner.on(). */
+type RunnerEvent = {
+    type: "agent_start";
+    agent: string;
+    query: string;
+} | {
+    type: "agent_thinking";
+    agent: string;
+    delta: string;
+} | {
+    type: "tool_call_start";
+    agent: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: "tool_call_done";
+    agent: string;
+    tool: string;
+    output: unknown;
+    ms: number;
+} | {
+    type: "verifier_run";
+    agent: string;
+    kernel: string;
+    result: VerifierResult;
+} | {
+    type: "agent_output";
+    agent: string;
+    output: string;
+} | {
+    type: "council_start";
+    council: string;
+    query: string;
+} | {
+    type: "specialist_done";
+    specialist: string;
+    output: CouncilSpecialistOutput;
+} | {
+    type: "council_done";
+    council: string;
+    output: CouncilOutput;
+} | {
+    type: "error";
+    agent: string;
+    message: string;
+};
+/**
+ * Model adapter — the function the Runner calls to talk to an LLM.
+ *
+ * Implement once per provider. Three reference adapters ship in
+ * `examples/adapters/`: OpenRouter, OpenAI, Anthropic. Production users write
+ * their own adapter for their preferred endpoint (Vext-hosted Theron, AWS
+ * Bedrock, Cerebras, Groq, your own OSS endpoint).
+ */
+interface ModelAdapter {
+    name: string;
+    /** Chat completion. Streams deltas via the optional `onDelta` callback. */
+    chat(opts: {
+        model: string;
+        messages: Array<{
+            role: "system" | "user" | "assistant" | "tool";
+            content: string;
+        }>;
+        tools?: Array<{
+            name: string;
+            description: string;
+            input_schema: Record<string, unknown>;
+        }>;
+        max_tokens?: number;
+        temperature?: number;
+        onDelta?: (delta: string) => void;
+    }): Promise<{
+        content: string;
+        tool_calls?: Array<{
+            name: string;
+            input: unknown;
+        }>;
+        tokens: {
+            input: number;
+            output: number;
+        };
+    }>;
+}
+interface RunnerConfig {
+    /** The model adapter to use. */
+    model: ModelAdapter;
+    /** Default model identifier (e.g., "gpt-4o", "claude-3-5-sonnet"). */
+    default_model: string;
+    /** Optional Memory implementation. */
+    memory?: Memory;
+    /** Optional Session for event logging. */
+    session?: Session;
+    /** Optional tool execution context (cwd, yolo, tenant). */
+    tool_context?: ToolContext;
+}
+/**
+ * Runner — executes Agents and Councils.
+ *
+ * Minimal usage:
+ *   const runner = new Runner({
+ *     model: openrouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }),
+ *     default_model: "openai/gpt-4o-mini",
+ *   });
+ *   const result = await runner.run(myAgent, "What's 2+2?");
+ *
+ * With a council:
+ *   const result = await runner.runCouncil(myCouncil, "Review this PR");
+ */
+declare class Runner {
+    readonly model: ModelAdapter;
+    readonly default_model: string;
+    readonly memory: Memory | undefined;
+    readonly session: Session | undefined;
+    readonly tool_context: ToolContext;
+    private listeners;
+    constructor(config: RunnerConfig);
+    /** Subscribe to runner events for streaming UIs / observability. */
+    on(handler: (event: RunnerEvent) => void): () => void;
+    private emit;
+    /**
+     * Run a single agent on a query.
+     *
+     * Loop:
+     *   1. Send messages + tool schemas to the model
+     *   2. If model returns a tool call → execute the tool → append result to messages → repeat
+     *   3. If model returns content + end_turn → finalize
+     *   4. Run any registered verifier kernels on the final output
+     *   5. Return the AgentResult
+     */
+    run(agent: Agent, query: string): Promise<AgentResult>;
+    /**
+     * Run a Council on a query.
+     *
+     * Fan out to all specialists in parallel (with timeout), gather outputs,
+     * run council-level verifier kernels on each, and reconcile.
+     */
+    runCouncil(council: Council, query: string): Promise<CouncilOutput>;
+}
+
+export { type ModelAdapter, Runner, type RunnerConfig, type RunnerEvent };

package/dist/runtime/index.d.ts

@@ -0,0 +1,148 @@
+import { Agent, AgentResult } from '../agent/index.js';
+import { CouncilSpecialistOutput, CouncilOutput, Council } from '../council/index.js';
+import { Session } from '../session/index.js';
+import { Memory } from '../memory/index.js';
+import { ToolContext } from '../tools/index.js';
+import { VerifierResult } from '../verifiers/index.js';
+import 'zod';
+
+/** Events the Runner emits as it executes. Subscribe via runner.on(). */
+type RunnerEvent = {
+    type: "agent_start";
+    agent: string;
+    query: string;
+} | {
+    type: "agent_thinking";
+    agent: string;
+    delta: string;
+} | {
+    type: "tool_call_start";
+    agent: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: "tool_call_done";
+    agent: string;
+    tool: string;
+    output: unknown;
+    ms: number;
+} | {
+    type: "verifier_run";
+    agent: string;
+    kernel: string;
+    result: VerifierResult;
+} | {
+    type: "agent_output";
+    agent: string;
+    output: string;
+} | {
+    type: "council_start";
+    council: string;
+    query: string;
+} | {
+    type: "specialist_done";
+    specialist: string;
+    output: CouncilSpecialistOutput;
+} | {
+    type: "council_done";
+    council: string;
+    output: CouncilOutput;
+} | {
+    type: "error";
+    agent: string;
+    message: string;
+};
+/**
+ * Model adapter — the function the Runner calls to talk to an LLM.
+ *
+ * Implement once per provider. Three reference adapters ship in
+ * `examples/adapters/`: OpenRouter, OpenAI, Anthropic. Production users write
+ * their own adapter for their preferred endpoint (Vext-hosted Theron, AWS
+ * Bedrock, Cerebras, Groq, your own OSS endpoint).
+ */
+interface ModelAdapter {
+    name: string;
+    /** Chat completion. Streams deltas via the optional `onDelta` callback. */
+    chat(opts: {
+        model: string;
+        messages: Array<{
+            role: "system" | "user" | "assistant" | "tool";
+            content: string;
+        }>;
+        tools?: Array<{
+            name: string;
+            description: string;
+            input_schema: Record<string, unknown>;
+        }>;
+        max_tokens?: number;
+        temperature?: number;
+        onDelta?: (delta: string) => void;
+    }): Promise<{
+        content: string;
+        tool_calls?: Array<{
+            name: string;
+            input: unknown;
+        }>;
+        tokens: {
+            input: number;
+            output: number;
+        };
+    }>;
+}
+interface RunnerConfig {
+    /** The model adapter to use. */
+    model: ModelAdapter;
+    /** Default model identifier (e.g., "gpt-4o", "claude-3-5-sonnet"). */
+    default_model: string;
+    /** Optional Memory implementation. */
+    memory?: Memory;
+    /** Optional Session for event logging. */
+    session?: Session;
+    /** Optional tool execution context (cwd, yolo, tenant). */
+    tool_context?: ToolContext;
+}
+/**
+ * Runner — executes Agents and Councils.
+ *
+ * Minimal usage:
+ *   const runner = new Runner({
+ *     model: openrouterAdapter({ apiKey: process.env.OPENROUTER_API_KEY }),
+ *     default_model: "openai/gpt-4o-mini",
+ *   });
+ *   const result = await runner.run(myAgent, "What's 2+2?");
+ *
+ * With a council:
+ *   const result = await runner.runCouncil(myCouncil, "Review this PR");
+ */
+declare class Runner {
+    readonly model: ModelAdapter;
+    readonly default_model: string;
+    readonly memory: Memory | undefined;
+    readonly session: Session | undefined;
+    readonly tool_context: ToolContext;
+    private listeners;
+    constructor(config: RunnerConfig);
+    /** Subscribe to runner events for streaming UIs / observability. */
+    on(handler: (event: RunnerEvent) => void): () => void;
+    private emit;
+    /**
+     * Run a single agent on a query.
+     *
+     * Loop:
+     *   1. Send messages + tool schemas to the model
+     *   2. If model returns a tool call → execute the tool → append result to messages → repeat
+     *   3. If model returns content + end_turn → finalize
+     *   4. Run any registered verifier kernels on the final output
+     *   5. Return the AgentResult
+     */
+    run(agent: Agent, query: string): Promise<AgentResult>;
+    /**
+     * Run a Council on a query.
+     *
+     * Fan out to all specialists in parallel (with timeout), gather outputs,
+     * run council-level verifier kernels on each, and reconcile.
+     */
+    runCouncil(council: Council, query: string): Promise<CouncilOutput>;
+}
+
+export { type ModelAdapter, Runner, type RunnerConfig, type RunnerEvent };