@vextlabs/theron-agent-sdk 0.3.0 → 0.3.1

package/dist/index.cjs

@@ -1,6 +1,12 @@
 'use strict';
 
 var zod = require('zod');
+var promises = require('fs/promises');
+var os = require('os');
+var path = require('path');
+var child_process = require('child_process');
+var util = require('util');
+var crypto = require('crypto');
 
 // src/agent/index.ts
 var Agent = class {
@@ -22,23 +28,213 @@ var Agent = class {
     this.verifiers = config.verifiers ?? [];
     this.max_turns = config.max_turns ?? 10;
   }
-  /** Render the tools as JSON schemas for the model. */
+  /**
+   * Render the tools as JSON schemas for the model — the agent's own tools
+   * PLUS one `delegate_to_<sub-agent>` tool per declared sub-agent, so a
+   * supervisor can actually hand work to its specialists. The Runner routes
+   * those delegate calls back into `runner.run(subAgent, task)`.
+   */
   toolSchemas() {
-    return this.tools.map((t) => t.schema);
+    const own = this.tools.map((t) => t.schema);
+    const delegates = this.sub_agents.map((sa) => ({
+      name: subAgentToolName(sa.name),
+      description: `Delegate a self-contained subtask to the "${sa.name}" sub-agent and get back its result. ${sa.instruction.system.slice(0, 200)}`,
+      input_schema: {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: `The subtask for the "${sa.name}" sub-agent to perform, stated as a complete, standalone instruction.`
+          }
+        },
+        required: ["task"]
+      }
+    }));
+    return [...own, ...delegates];
+  }
+  /** Resolve a delegate tool-call name back to the sub-agent it targets. */
+  findSubAgent(toolName) {
+    return this.sub_agents.find((sa) => subAgentToolName(sa.name) === toolName);
   }
   /** True if the agent has any sub-agents (i.e., this is a supervisor). */
   isSupervisor() {
     return this.sub_agents.length > 0;
   }
 };
+function subAgentToolName(name) {
+  return `delegate_to_${name}`.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+}
+function parseMarkdownAgent(filename, content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!fmMatch) return null;
+  const frontmatter = fmMatch[1];
+  const body = fmMatch[2].trim();
+  if (!body) return null;
+  const fields = {};
+  let currentKey = "";
+  for (const line of frontmatter.split("\n")) {
+    const listMatch = line.match(/^\s+-\s+(.+)$/);
+    if (listMatch && currentKey) {
+      const existing = fields[currentKey];
+      if (Array.isArray(existing)) {
+        existing.push(listMatch[1].trim());
+      } else {
+        fields[currentKey] = [listMatch[1].trim()];
+      }
+      continue;
+    }
+    const kvMatch = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (kvMatch) {
+      const key = kvMatch[1].trim();
+      const value = kvMatch[2].trim();
+      currentKey = key;
+      fields[key] = value.replace(/^["']|["']$/g, "");
+    }
+  }
+  const name = String(fields.name || "").trim();
+  if (!name) return null;
+  const baseFilename = filename.replace(/\.md$/i, "").replace(/[^a-z0-9_-]/gi, "-").toLowerCase();
+  const id = name.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/-+/g, "-") || baseFilename;
+  return {
+    id,
+    name,
+    description: String(fields.description || ""),
+    model: fields.model ? String(fields.model) : void 0,
+    tools: Array.isArray(fields.tools) ? fields.tools.map(String) : void 0,
+    max_turns: fields.max_turns ? parseInt(String(fields.max_turns), 10) || void 0 : void 0,
+    system_prompt: body,
+    source: filename
+  };
+}
+async function loadMarkdownAgents(dir) {
+  const fs = await import('fs/promises');
+  const path = await import('path');
+  try {
+    const entries = await fs.readdir(dir);
+    const mdFiles = entries.filter((f) => f.endsWith(".md"));
+    const results = [];
+    for (const file of mdFiles) {
+      try {
+        const fullPath = path.join(dir, file);
+        const content = await fs.readFile(fullPath, "utf8");
+        const parsed = parseMarkdownAgent(file, content);
+        if (parsed) results.push(parsed);
+      } catch {
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+async function loadAllMarkdownAgents(projectDir) {
+  const os = await import('os');
+  const path = await import('path');
+  const home = os.homedir();
+  const globalDir = path.join(home, ".theron", "agents");
+  const localDir = projectDir ? path.join(projectDir, ".theron", "agents") : path.join(process.cwd(), ".theron", "agents");
+  const [globalAgents, localAgents] = await Promise.all([
+    loadMarkdownAgents(globalDir),
+    loadMarkdownAgents(localDir)
+  ]);
+  const byId = /* @__PURE__ */ new Map();
+  for (const a of globalAgents) byId.set(a.id, a);
+  for (const a of localAgents) byId.set(a.id, a);
+  return [...byId.values()];
+}
+
+// src/skills/index.ts
+function parseMarkdownSkill(filename, content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!fmMatch) return null;
+  const frontmatter = fmMatch[1];
+  const body = fmMatch[2].trim();
+  if (!body) return null;
+  const fields = {};
+  let currentKey = "";
+  for (const line of frontmatter.split("\n")) {
+    const listMatch = line.match(/^\s+-\s+(.+)$/);
+    if (listMatch && currentKey) {
+      const existing = fields[currentKey];
+      if (Array.isArray(existing)) existing.push(listMatch[1].trim());
+      else fields[currentKey] = [listMatch[1].trim()];
+      continue;
+    }
+    const kvMatch = line.match(/^([\w-]+)\s*:\s*(.*)$/);
+    if (kvMatch) {
+      currentKey = kvMatch[1].trim();
+      fields[currentKey] = kvMatch[2].trim().replace(/^["']|["']$/g, "");
+    }
+  }
+  const rawName = String(fields.name || filename.replace(/\.md$/i, "")).trim();
+  const name = rawName.toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/-+/g, "-");
+  if (!name) return null;
+  let allowedTools;
+  const at = fields["allowed-tools"] ?? fields.allowedTools ?? fields.tools;
+  if (Array.isArray(at)) allowedTools = at.map(String);
+  else if (typeof at === "string" && at.trim()) {
+    allowedTools = at.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return {
+    name,
+    description: String(fields.description || ""),
+    body,
+    allowedTools,
+    model: fields.model ? String(fields.model) : void 0,
+    source: filename
+  };
+}
+async function loadMarkdownSkills(dir) {
+  const fs = await import('fs/promises');
+  const path = await import('path');
+  const out = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const ent of entries) {
+      try {
+        if (ent.isFile() && ent.name.endsWith(".md")) {
+          const full = path.join(dir, ent.name);
+          const parsed = parseMarkdownSkill(ent.name, await fs.readFile(full, "utf8"));
+          if (parsed) out.push(parsed);
+        } else if (ent.isDirectory()) {
+          const full = path.join(dir, ent.name, "SKILL.md");
+          const buf = await fs.readFile(full, "utf8").catch(() => null);
+          if (buf) {
+            const parsed = parseMarkdownSkill(`${ent.name}/SKILL.md`, buf);
+            if (parsed) out.push({ ...parsed, name: parsed.name || ent.name.toLowerCase() });
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return out;
+}
+async function loadAllMarkdownSkills(projectDir) {
+  const os = await import('os');
+  const path = await import('path');
+  const globalDir = path.join(os.homedir(), ".theron", "skills");
+  const localDir = path.join(projectDir ?? process.cwd(), ".theron", "skills");
+  const [globalSkills, localSkills] = await Promise.all([
+    loadMarkdownSkills(globalDir),
+    loadMarkdownSkills(localDir)
+  ]);
+  const byName = /* @__PURE__ */ new Map();
+  for (const s of globalSkills) byName.set(s.name, s);
+  for (const s of localSkills) byName.set(s.name, s);
+  return [...byName.values()];
+}
 
 // src/council/index.ts
+var sentenceClaimExtractor = (output) => output.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter((s) => s.length > 0).map((text) => ({ text, confidence: 1, type: "assertion" }));
 var Council = class {
   name;
   specialists;
   verifiers;
   reconciler;
   specialist_timeout_ms;
+  claimExtractor;
   constructor(config) {
     if (!config.name) throw new Error("Council requires a `name`.");
     if (!config.specialists || config.specialists.length === 0) {
@@ -49,6 +245,7 @@ var Council = class {
     this.verifiers = config.verifiers ?? [];
     this.reconciler = config.reconciler ?? deterministicClaimMerge;
     this.specialist_timeout_ms = config.specialist_timeout_ms ?? 3e4;
+    this.claimExtractor = config.claimExtractor;
   }
   /**
    * Convenience entry point — pointed at the Runner you've already constructed.
@@ -214,22 +411,57 @@ function defineTool(opts) {
   };
 }
 function zodToJsonSchema(schema) {
+  const description = schema._def?.description;
+  const withDesc = (s) => description ? { ...s, description } : s;
+  if (schema instanceof zod.z.ZodOptional) return zodToJsonSchema(schema.unwrap());
+  if (schema instanceof zod.z.ZodDefault) {
+    const innerType = schema._def.innerType;
+    const inner = zodToJsonSchema(innerType);
+    let def;
+    try {
+      def = schema._def.defaultValue?.();
+    } catch {
+      def = void 0;
+    }
+    return withDesc(def === void 0 ? inner : { ...inner, default: def });
+  }
+  if (schema instanceof zod.z.ZodNullable) {
+    return withDesc({ ...zodToJsonSchema(schema.unwrap()), nullable: true });
+  }
   if (schema instanceof zod.z.ZodObject) {
     const properties = {};
     const required = [];
     for (const [key, value] of Object.entries(schema.shape)) {
-      properties[key] = zodToJsonSchema(value);
-      if (!(value instanceof zod.z.ZodOptional)) required.push(key);
+      const field = value;
+      properties[key] = zodToJsonSchema(field);
+      if (!(field instanceof zod.z.ZodOptional) && !(field instanceof zod.z.ZodDefault)) {
+        required.push(key);
+      }
     }
-    return { type: "object", properties, ...required.length > 0 ? { required } : {} };
+    return withDesc({ type: "object", properties, ...required.length > 0 ? { required } : {} });
   }
-  if (schema instanceof zod.z.ZodString) return { type: "string" };
-  if (schema instanceof zod.z.ZodNumber) return { type: "number" };
-  if (schema instanceof zod.z.ZodBoolean) return { type: "boolean" };
-  if (schema instanceof zod.z.ZodArray) return { type: "array", items: zodToJsonSchema(schema.element) };
-  if (schema instanceof zod.z.ZodOptional) return zodToJsonSchema(schema.unwrap());
-  if (schema instanceof zod.z.ZodEnum) return { type: "string", enum: schema.options };
-  return { type: "string" };
+  if (schema instanceof zod.z.ZodString) return withDesc({ type: "string" });
+  if (schema instanceof zod.z.ZodNumber) return withDesc({ type: "number" });
+  if (schema instanceof zod.z.ZodBoolean) return withDesc({ type: "boolean" });
+  if (schema instanceof zod.z.ZodArray) return withDesc({ type: "array", items: zodToJsonSchema(schema.element) });
+  if (schema instanceof zod.z.ZodEnum) return withDesc({ type: "string", enum: schema.options });
+  if (schema instanceof zod.z.ZodLiteral) {
+    const val = schema.value;
+    const t = typeof val === "number" ? "number" : typeof val === "boolean" ? "boolean" : "string";
+    return withDesc({ type: t, enum: [val] });
+  }
+  if (schema instanceof zod.z.ZodUnion) {
+    const options = schema._def.options;
+    return withDesc({ anyOf: options.map((o) => zodToJsonSchema(o)) });
+  }
+  if (schema instanceof zod.z.ZodRecord) {
+    const valueType = schema._def.valueType;
+    return withDesc({
+      type: "object",
+      additionalProperties: valueType ? zodToJsonSchema(valueType) : true
+    });
+  }
+  return withDesc({ type: "string" });
 }
 
 // src/tools/local-contract.ts
@@ -281,17 +513,30 @@ var LOCAL_TOOL_PARAMETERS = {
   Grep: {
     type: "object",
     properties: {
-      pattern: { type: "string", description: "Regex pattern." },
+      pattern: { type: "string", description: "Regex pattern (ripgrep syntax). Use fixed_strings for a literal search." },
       path: { type: "string", description: "Optional file or directory to limit the search." },
-      glob: { type: "string", description: "Optional glob filter, e.g. '*.ts'." },
-      case_insensitive: { type: "boolean", default: false }
+      glob: { type: "string", description: "Optional glob filter, e.g. '*.ts' or 'src/**/*.tsx'." },
+      type: { type: "string", description: "Optional file-type filter (ripgrep --type), e.g. 'ts', 'py', 'rust'. More efficient than glob for language filters." },
+      case_insensitive: { type: "boolean", default: false, description: "Case-insensitive match." },
+      output_mode: {
+        type: "string",
+        enum: ["content", "files_with_matches", "count"],
+        description: "What to return: 'content' = matching lines with file:line (default), 'files_with_matches' = just the file paths, 'count' = per-file match counts.",
+        default: "content"
+      },
+      context_lines: { type: "number", description: "Lines of context to show before AND after each match (ripgrep -C). Only applies to output_mode 'content'." },
+      multiline: { type: "boolean", default: false, description: "Allow the pattern to span line boundaries (ripgrep --multiline; '.' matches newlines)." },
+      fixed_strings: { type: "boolean", default: false, description: "Treat the pattern as a literal string, not a regex (ripgrep -F)." }
     },
     required: ["pattern"]
   },
   LS: {
     type: "object",
     properties: {
-      path: { type: "string", description: "Path to list. Defaults to the working directory." }
+      path: { type: "string", description: "Path to list. Defaults to the working directory." },
+      show_hidden: { type: "boolean", default: false, description: "Include dotfiles (.env, .gitignore, .github, etc.) in the listing." },
+      recursive: { type: "boolean", default: false, description: "List subdirectories recursively (up to `depth` levels)." },
+      depth: { type: "number", description: "Max recursion depth when recursive=true (default 3)." }
     }
   }
 };
@@ -412,6 +657,105 @@ var VerifierKernels = {
   })
 };
 
+// src/reasoning-cert/index.ts
+var ARITH = /(-?\d+(?:\.\d+)?)\s*([+\-*/])\s*(-?\d+(?:\.\d+)?)\s*=\s*(-?\d+(?:\.\d+)?)/g;
+async function sha256Hex(s) {
+  const buf = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(s));
+  return "sha256:" + [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function certifyArithmetic(text) {
+  const claim = String(text ?? "");
+  const matched = [...claim.matchAll(ARITH)].length;
+  const res = await VerifierKernels.arithmetic.check(claim);
+  const verdict = matched === 0 ? "ABSTAIN" : res.pass ? "PASS" : "FAIL";
+  return {
+    tier: "arithmetic",
+    oracle_id: "js_runtime",
+    oracle_version: typeof process !== "undefined" && process.version ? process.version : "webcrypto",
+    claim_input_hash: await sha256Hex(claim),
+    verdict,
+    verdict_detail: matched === 0 ? "no 'A op B = C' arithmetic claim found \u2014 nothing certified" : res.pass ? `${matched} arithmetic claim(s) re-computed and match` : res.issues.map((i) => i.message).join("; "),
+    certifies: verdict === "PASS" ? "arithmetic_correct" : verdict === "FAIL" ? "arithmetic_incorrect" : "nothing",
+    does_not_certify: "any reasoning, fact, or step beyond the literal 'A op B = C' arithmetic re-check",
+    oracle_ts: Math.floor(Date.now() / 1e3)
+  };
+}
+async function verifyReasoningCertificate(cert, claimText) {
+  const reasons = [];
+  if (cert.tier !== "arithmetic") {
+    reasons.push(`offline re-check for tier '${cert.tier}' is not implemented in Slice 0 (arithmetic only)`);
+    return { ok: false, reasons };
+  }
+  const claim = String(claimText ?? "");
+  const hashOk = await sha256Hex(claim) === cert.claim_input_hash;
+  if (!hashOk) reasons.push("claim_input_hash does not match the provided claim text");
+  const recomputed = await certifyArithmetic(claim);
+  const verdictOk = recomputed.verdict === cert.verdict;
+  if (!verdictOk) reasons.push(`re-computed verdict ${recomputed.verdict} != certificate ${cert.verdict}`);
+  return { ok: hashOk && verdictOk, reasons };
+}
+var pExecFile = util.promisify(child_process.execFile);
+function resolveInside(root, p) {
+  const abs = path.isAbsolute(p) ? p : path.resolve(root, p);
+  const rel = path.relative(root, abs);
+  if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    throw new Error(`path escapes session root: ${p}`);
+  }
+  return abs;
+}
+var LocalCloudSession = class {
+  id;
+  root;
+  disposed = false;
+  constructor(id, root) {
+    this.id = id;
+    this.root = root;
+  }
+  async exec(command, options = {}) {
+    if (this.disposed) throw new Error("session disposed");
+    const cwd = options.cwd ? resolveInside(this.root, options.cwd) : this.root;
+    try {
+      const { stdout, stderr } = await pExecFile("/bin/sh", ["-c", command], {
+        cwd,
+        timeout: options.timeoutMs ?? 12e4,
+        env: { ...process.env, ...options.env ?? {} },
+        maxBuffer: 64 * 1024 * 1024
+      });
+      return { stdout: stdout.toString(), stderr: stderr.toString(), exitCode: 0 };
+    } catch (e) {
+      const err = e;
+      const exitCode = typeof err.code === "number" ? err.code : err.killed ? 124 : 1;
+      return {
+        stdout: (err.stdout ?? "").toString(),
+        stderr: (err.stderr ?? err.message ?? String(e)).toString(),
+        exitCode
+      };
+    }
+  }
+  async readFile(path) {
+    if (this.disposed) throw new Error("session disposed");
+    return promises.readFile(resolveInside(this.root, path), "utf8");
+  }
+  async writeFile(path$1, content) {
+    if (this.disposed) throw new Error("session disposed");
+    const abs = resolveInside(this.root, path$1);
+    await promises.mkdir(path.dirname(abs), { recursive: true });
+    await promises.writeFile(abs, content, "utf8");
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    await promises.rm(this.root, { recursive: true, force: true });
+  }
+};
+var LocalCloudSessionProvider = class {
+  async provision() {
+    const id = crypto.randomUUID();
+    const root = await promises.mkdtemp(path.join(os.tmpdir(), `theron-session-${id.slice(0, 8)}-`));
+    return new LocalCloudSession(id, root);
+  }
+};
+
 // src/runtime/index.ts
 var Runner = class {
   model;
@@ -449,8 +793,9 @@ var Runner = class {
    *   4. Run any registered verifier kernels on the final output
    *   5. Return the AgentResult
    */
-  async run(agent, query) {
+  async run(agent, query, opts) {
     const startedAt = Date.now();
+    const signal = opts?.signal;
     this.emit({ type: "agent_start", agent: agent.name, query });
     const messages = [
       { role: "system", content: agent.instruction.system }
@@ -463,49 +808,84 @@ var Runner = class {
     const toolCalls = [];
     let tokensIn = 0;
     let tokensOut = 0;
+    let costUsd = 0;
     let finalOutput = "";
+    let completed = false;
+    let aborted = false;
     for (let turn = 0; turn < agent.max_turns; turn++) {
+      if (signal?.aborted) {
+        aborted = true;
+        this.emit({ type: "aborted", agent: agent.name });
+        break;
+      }
       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 })
+        onDelta: (delta) => this.emit({ type: "agent_thinking", agent: agent.name, delta }),
+        signal
       });
       tokensIn += response.tokens.input;
       tokensOut += response.tokens.output;
+      costUsd += response.cost_usd ?? 0;
       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}` });
-          }
+        const calls = response.tool_calls;
+        const results = await Promise.all(
+          calls.map(async (call) => {
+            const subAgent = agent.findSubAgent(call.name);
+            if (subAgent) {
+              this.emit({ type: "tool_call_start", agent: agent.name, tool: call.name, input: call.input });
+              const t02 = Date.now();
+              try {
+                const task = typeof call.input?.task === "string" ? call.input.task : JSON.stringify(call.input);
+                const sub = await this.run(subAgent, task, { signal });
+                const ms = Date.now() - t02;
+                this.emit({ type: "tool_call_done", agent: agent.name, tool: call.name, output: sub.output, ms });
+                return { call, output: sub.output, content: sub.output, ok: true };
+              } catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.emit({ type: "error", agent: agent.name, message: `Sub-agent ${subAgent.name} threw: ${msg}` });
+                return { call, content: `error: ${msg}`, ok: false };
+              }
+            }
+            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}`
+              });
+              return { call, content: `error: unknown tool ${call.name}`, ok: false };
+            }
+            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 });
+              return { call, output, content: JSON.stringify(output), ok: true };
+            } catch (err) {
+              const msg = err instanceof Error ? err.message : String(err);
+              this.emit({ type: "error", agent: agent.name, message: `Tool ${call.name} threw: ${msg}` });
+              return { call, content: `error: ${msg}`, ok: false };
+            }
+          })
+        );
+        for (const r of results) {
+          if (r.ok) toolCalls.push({ name: r.call.name, input: r.call.input, output: r.output });
+          messages.push({ role: "tool", content: r.content });
         }
         continue;
       }
       finalOutput = response.content;
       messages.push({ role: "assistant", content: finalOutput });
+      completed = true;
       break;
     }
+    if (!completed && !aborted) {
+      this.emit({ type: "max_turns_exhausted", agent: agent.name, turns: agent.max_turns });
+    }
     this.emit({ type: "agent_output", agent: agent.name, output: finalOutput });
     const verifier_results = [];
     for (const v of agent.verifiers) {
@@ -528,8 +908,8 @@ var Runner = class {
       tool_calls: toolCalls,
       verifier_results,
       tokens_used: { input: tokensIn, output: tokensOut },
-      cost_usd: 0,
-      // adapter-specific; populated by adapter
+      cost_usd: costUsd,
+      // summed from adapter-reported per-call cost (0 if the adapter doesn't report it)
       latency_ms
     };
   }
@@ -539,17 +919,18 @@ var Runner = class {
    * Fan out to all specialists in parallel (with timeout), gather outputs,
    * run council-level verifier kernels on each, and reconcile.
    */
-  async runCouncil(council, query) {
+  async runCouncil(council, query, opts) {
     const startedAt = Date.now();
+    const signal = opts?.signal;
     this.emit({ type: "council_start", council: council.name, query });
     const withTimeout = (p, ms) => Promise.race([
       p,
-      new Promise((resolve) => setTimeout(() => resolve(null), ms))
+      new Promise((resolve2) => setTimeout(() => resolve2(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);
+          const result = await withTimeout(this.run(spec, query, { signal }), council.specialist_timeout_ms);
           if (result === null) {
             this.emit({
               type: "error",
@@ -575,8 +956,11 @@ var Runner = class {
           const out = {
             specialist: spec.name,
             output: result.output,
-            claims: [],
-            // claim extraction is the reconciler's job
+            // Extract claims if the council supplies an extractor; otherwise the
+            // reconciler is responsible (the default deterministic reconciler
+            // votes over these claims, so a council that wants automatic
+            // ratification should set `claimExtractor`).
+            claims: council.claimExtractor ? council.claimExtractor(result.output) : [],
             // 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.
@@ -619,7 +1003,7 @@ var MCP_PROTOCOL_VERSION = "2024-11-05";
 var DEFAULT_TIMEOUT_MS = 12e3;
 var MCPClient = class {
   config;
-  initialized = false;
+  initPromise = null;
   toolCache = null;
   constructor(config) {
     if (!/^[a-z0-9_-]+$/.test(config.slug)) {
@@ -685,7 +1069,17 @@ var MCPClient = class {
     };
   }
   async ensureInitialized(signal) {
-    if (this.initialized) return;
+    if (!this.initPromise) {
+      this.initPromise = this.doInitialize(signal);
+    }
+    try {
+      await this.initPromise;
+    } catch (err) {
+      this.initPromise = null;
+      throw err;
+    }
+  }
+  async doInitialize(signal) {
     await this.rpc(
       "initialize",
       {
@@ -696,7 +1090,6 @@ var MCPClient = class {
       signal
     );
     this.rpc("notifications/initialized", {}, signal).catch(() => void 0);
-    this.initialized = true;
   }
   async rpc(method, params, externalSignal) {
     const ac = new AbortController();
@@ -710,9 +1103,9 @@ var MCPClient = class {
     }
     const body = {
       jsonrpc: "2.0",
-      id: Date.now() + Math.floor(Math.random() * 1e3),
       method,
-      params
+      params,
+      ...method.startsWith("notifications/") ? {} : { id: Date.now() + Math.floor(Math.random() * 1e3) }
     };
     try {
       const r = await fetch(this.config.url, {
@@ -735,11 +1128,19 @@ var MCPClient = class {
       const ct = r.headers.get("content-type") || "";
       if (ct.includes("text/event-stream")) {
         const text = await r.text();
-        const m = text.match(/data:\s*(\{[\s\S]*?\})\s*\n/);
-        if (!m) throw new Error("mcp sse stream had no data event");
-        const env2 = JSON.parse(m[1]);
-        if (env2.error) throw new Error(`mcp error: ${env2.error.message}`);
-        return env2.result;
+        for (const ev of text.split(/\n\n/)) {
+          const payload = ev.split(/\r?\n/).filter((l) => l.startsWith("data:")).map((l) => l.slice(5).replace(/^ /, "")).join("\n").trim();
+          if (!payload || payload === "[DONE]") continue;
+          let env2;
+          try {
+            env2 = JSON.parse(payload);
+          } catch {
+            continue;
+          }
+          if (env2.error) throw new Error(`mcp error: ${env2.error.message}`);
+          return env2.result;
+        }
+        throw new Error("mcp sse stream had no data event");
       }
       const env = await r.json();
       if (env.error) throw new Error(`mcp error: ${env.error.message}`);
@@ -798,6 +1199,7 @@ function theronAdapter(opts = {}) {
         let inputTokens = 0;
         let outputTokens = 0;
         let buf = "";
+        const toolAcc = {};
         for (; ; ) {
           const { value, done } = await reader.read();
           if (done) break;
@@ -810,11 +1212,20 @@ function theronAdapter(opts = {}) {
             if (!data || data === "[DONE]") continue;
             try {
               const json2 = JSON.parse(data);
-              const delta = json2.choices?.[0]?.delta?.content;
+              const d = json2.choices?.[0]?.delta;
+              const delta = d?.content;
               if (delta) {
                 onDelta(delta);
                 content += delta;
               }
+              if (Array.isArray(d?.tool_calls)) {
+                for (const tc of d.tool_calls) {
+                  const i = typeof tc.index === "number" ? tc.index : 0;
+                  toolAcc[i] ??= { name: "", args: "" };
+                  if (tc.function?.name) toolAcc[i].name = tc.function.name;
+                  if (tc.function?.arguments) toolAcc[i].args += tc.function.arguments;
+                }
+              }
               if (json2.usage) {
                 inputTokens = json2.usage.prompt_tokens ?? inputTokens;
                 outputTokens = json2.usage.completion_tokens ?? outputTokens;
@@ -823,7 +1234,8 @@ function theronAdapter(opts = {}) {
             }
           }
         }
-        return { content, tokens: { input: inputTokens, output: outputTokens } };
+        const tool_calls2 = Object.keys(toolAcc).length ? Object.values(toolAcc).map((t) => ({ name: t.name, input: safeJson(t.args) })) : void 0;
+        return { content, tool_calls: tool_calls2, tokens: { input: inputTokens, output: outputTokens } };
       }
       const json = await res.json();
       const msg = json.choices?.[0]?.message ?? { content: "" };
@@ -875,7 +1287,7 @@ var ReceiptEmitter = class {
       output: input.output,
       ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
     };
-    const content_hash = await sha256Hex(canonicalize(payload));
+    const content_hash = await sha256Hex2(canonicalize(payload));
     let receipt = {
       v: "stoa.receipt.v1",
       id: ulid(),
@@ -965,7 +1377,7 @@ function canonicalize(value) {
     (k) => JSON.stringify(k) + ":" + canonicalize(value[k])
   ).join(",") + "}";
 }
-async function sha256Hex(input) {
+async function sha256Hex2(input) {
   const data = new TextEncoder().encode(input);
   const buf = await globalThis.crypto.subtle.digest("SHA-256", data);
   const bytes = new Uint8Array(buf);
@@ -1059,8 +1471,9 @@ async function compactHistory(opts) {
   const older = msgs.slice(0, msgs.length - keepRecent);
   const recent = msgs.slice(msgs.length - keepRecent);
   const summary = String(await opts.summarize(older));
+  const summaryRole = opts.summaryRole ?? "system";
   return {
-    messages: [{ role: "system", content: `${SUMMARY_PREFIX}
+    messages: [{ role: summaryRole, content: `${SUMMARY_PREFIX}
 ${summary}` }, ...recent],
     compacted: true,
     summary,
@@ -1240,7 +1653,7 @@ async function measureLift(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.3.1";
 
 Object.defineProperty(exports, "zod", {
   enumerable: true,
@@ -1252,6 +1665,8 @@ exports.InMemoryReceiptSink = InMemoryReceiptSink;
 exports.InMemoryStore = InMemoryStore;
 exports.LOCAL_TOOL_NAMES = LOCAL_TOOL_NAMES;
 exports.LOCAL_TOOL_PARAMETERS = LOCAL_TOOL_PARAMETERS;
+exports.LocalCloudSession = LocalCloudSession;
+exports.LocalCloudSessionProvider = LocalCloudSessionProvider;
 exports.MCPClient = MCPClient;
 exports.MUTATING_LOCAL_TOOLS = MUTATING_LOCAL_TOOLS;
 exports.Memory = Memory;
@@ -1265,6 +1680,7 @@ exports.anyOf = anyOf;
 exports.bestOfN = bestOfN;
 exports.boundWorkingSet = boundWorkingSet;
 exports.buildLocalToolSchemas = buildLocalToolSchemas;
+exports.certifyArithmetic = certifyArithmetic;
 exports.chainOfVerification = chainOfVerification;
 exports.collectMcpTools = collectMcpTools;
 exports.compactHistory = compactHistory;
@@ -1273,16 +1689,25 @@ exports.defineTool = defineTool;
 exports.defineVerifier = defineVerifier;
 exports.fileReceiptSink = fileReceiptSink;
 exports.httpReceiptSink = httpReceiptSink;
+exports.loadAllMarkdownAgents = loadAllMarkdownAgents;
+exports.loadAllMarkdownSkills = loadAllMarkdownSkills;
+exports.loadMarkdownAgents = loadMarkdownAgents;
+exports.loadMarkdownSkills = loadMarkdownSkills;
 exports.measureLift = measureLift;
 exports.mixtureOfAgents = mixtureOfAgents;
+exports.parseMarkdownAgent = parseMarkdownAgent;
+exports.parseMarkdownSkill = parseMarkdownSkill;
 exports.reflexion = reflexion;
 exports.runImprovementCycle = runImprovementCycle;
 exports.runUntil = runUntil;
 exports.selfConsistency = selfConsistency;
 exports.selfRefine = selfRefine;
+exports.sentenceClaimExtractor = sentenceClaimExtractor;
 exports.stepCountIs = stepCountIs;
+exports.subAgentToolName = subAgentToolName;
 exports.theron = theron;
 exports.theronAdapter = theronAdapter;
 exports.treeOfThoughts = treeOfThoughts;
 exports.verifiedRatchet = verifiedRatchet;
 exports.verifierSatisfied = verifierSatisfied;
+exports.verifyReasoningCertificate = verifyReasoningCertificate;