@vextlabs/theron-agent-sdk 0.3.0 → 0.3.1

package/dist/loop/index.cjs

@@ -63,8 +63,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,

package/dist/loop/index.d.cts

@@ -231,6 +231,9 @@ interface CompactHistoryOptions {
     /** Only compact when total content chars exceed this (default 0 = compact
      *  whenever there is more history than keepRecent). */
     maxChars?: number;
+    /** Role to attach the summary message under. Default 'system'. Set to 'user'
+     *  for providers (e.g. Anthropic) that reject a second system message. */
+    summaryRole?: "system" | "user";
 }
 interface CompactHistoryResult {
     /** The compacted message list: [summary-as-system, ...recent] when compacted. */

package/dist/loop/index.d.ts

@@ -231,6 +231,9 @@ interface CompactHistoryOptions {
     /** Only compact when total content chars exceed this (default 0 = compact
      *  whenever there is more history than keepRecent). */
     maxChars?: number;
+    /** Role to attach the summary message under. Default 'system'. Set to 'user'
+     *  for providers (e.g. Anthropic) that reject a second system message. */
+    summaryRole?: "system" | "user";
 }
 interface CompactHistoryResult {
     /** The compacted message list: [summary-as-system, ...recent] when compacted. */

package/dist/loop/index.js

@@ -61,8 +61,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,

package/dist/mcp/index.cjs

@@ -5,7 +5,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)) {
@@ -71,7 +71,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",
       {
@@ -82,7 +92,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();
@@ -96,9 +105,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, {
@@ -121,11 +130,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}`);

package/dist/mcp/index.d.cts

@@ -34,7 +34,7 @@ interface McpTool {
  */
 declare class MCPClient {
     readonly config: McpServerConfig;
-    private initialized;
+    private initPromise;
     private toolCache;
     constructor(config: McpServerConfig);
     /** Fetch the server's tool catalog. Cached for the lifetime of the client. */
@@ -55,6 +55,7 @@ declare class MCPClient {
     }>;
     private toSdkTool;
     private ensureInitialized;
+    private doInitialize;
     private rpc;
 }
 /**

package/dist/mcp/index.d.ts

@@ -34,7 +34,7 @@ interface McpTool {
  */
 declare class MCPClient {
     readonly config: McpServerConfig;
-    private initialized;
+    private initPromise;
     private toolCache;
     constructor(config: McpServerConfig);
     /** Fetch the server's tool catalog. Cached for the lifetime of the client. */
@@ -55,6 +55,7 @@ declare class MCPClient {
     }>;
     private toSdkTool;
     private ensureInitialized;
+    private doInitialize;
     private rpc;
 }
 /**

package/dist/mcp/index.js

@@ -3,7 +3,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)) {
@@ -69,7 +69,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",
       {
@@ -80,7 +90,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();
@@ -94,9 +103,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, {
@@ -119,11 +128,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}`);

package/dist/runtime/index.cjs

@@ -1,5 +1,75 @@
 'use strict';
 
+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/runtime/cloud-session.ts
+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;
@@ -37,8 +107,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 }
@@ -51,49 +122,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) {
@@ -116,8 +222,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
     };
   }
@@ -127,17 +233,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",
@@ -163,8 +270,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.
@@ -202,4 +312,6 @@ var Runner = class {
   }
 };
 
+exports.LocalCloudSession = LocalCloudSession;
+exports.LocalCloudSessionProvider = LocalCloudSessionProvider;
 exports.Runner = Runner;

package/dist/runtime/index.d.cts

@@ -6,6 +6,65 @@ import { ToolContext } from '../tools/index.cjs';
 import { VerifierResult } from '../verifiers/index.cjs';
 import 'zod';
 
+interface CloudExecResult {
+    stdout: string;
+    stderr: string;
+    /** 0 on success. Non-zero exit is RETURNED, never thrown. 124 = timeout. */
+    exitCode: number;
+}
+interface CloudExecOptions {
+    /** Working directory, relative to (or inside) the session root. */
+    cwd?: string;
+    /** Hard timeout in ms (default 120000). */
+    timeoutMs?: number;
+    /** Extra environment variables for the command. */
+    env?: Record<string, string>;
+}
+/**
+ * An isolated, per-session execution environment with a filesystem.
+ *
+ * Lifecycle: a {@link CloudSessionProvider} hands back a live session from
+ * `provision()`; call `dispose()` to release it (tear down the VM / delete the
+ * workspace). All file paths are resolved INSIDE the session root; a path that
+ * escapes the root is rejected.
+ */
+interface CloudSession {
+    /** Stable id, for receipts and logs. */
+    readonly id: string;
+    /** Absolute path to the session filesystem root (backend-specific). */
+    readonly root: string;
+    /** Run a shell command in the session. Non-zero exit is returned, not thrown. */
+    exec(command: string, options?: CloudExecOptions): Promise<CloudExecResult>;
+    /** Read a session file as UTF-8 (path resolved inside the root). */
+    readFile(path: string): Promise<string>;
+    /** Write a session file, creating parent dirs (path resolved inside the root). */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Release the session. Idempotent. */
+    dispose(): Promise<void>;
+}
+interface CloudSessionProvider {
+    /** Provision a fresh, isolated session. */
+    provision(): Promise<CloudSession>;
+}
+/**
+ * In-process {@link CloudSession} backend: a temp workspace on the host, commands
+ * via `/bin/sh -c`. For tests/CI/local dev only — NOT a security boundary.
+ */
+declare class LocalCloudSession implements CloudSession {
+    readonly id: string;
+    readonly root: string;
+    private disposed;
+    constructor(id: string, root: string);
+    exec(command: string, options?: CloudExecOptions): Promise<CloudExecResult>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Provisions {@link LocalCloudSession}s in fresh OS temp dirs. */
+declare class LocalCloudSessionProvider implements CloudSessionProvider {
+    provision(): Promise<CloudSession>;
+}
+
 /** Events the Runner emits as it executes. Subscribe via runner.on(). */
 type RunnerEvent = {
     type: "agent_start";
@@ -47,6 +106,13 @@ type RunnerEvent = {
     type: "council_done";
     council: string;
     output: CouncilOutput;
+} | {
+    type: "max_turns_exhausted";
+    agent: string;
+    turns: number;
+} | {
+    type: "aborted";
+    agent: string;
 } | {
     type: "error";
     agent: string;
@@ -77,6 +143,8 @@ interface ModelAdapter {
         max_tokens?: number;
         temperature?: number;
         onDelta?: (delta: string) => void;
+        /** Cancellation signal — adapters should forward it to fetch(). */
+        signal?: AbortSignal;
     }): Promise<{
         content: string;
         tool_calls?: Array<{
@@ -87,8 +155,15 @@ interface ModelAdapter {
             input: number;
             output: number;
         };
+        /** Optional per-call cost in USD. Adapters that can compute it should set
+         *  it so AgentResult.cost_usd and the costUsdAtLeast stop-predicate work. */
+        cost_usd?: number;
     }>;
 }
+/** Per-run options. `signal` cancels the loop cooperatively. */
+interface RunOptions {
+    signal?: AbortSignal;
+}
 interface RunnerConfig {
     /** The model adapter to use. */
     model: ModelAdapter;
@@ -135,14 +210,14 @@ declare class Runner {
      *   4. Run any registered verifier kernels on the final output
      *   5. Return the AgentResult
      */
-    run(agent: Agent, query: string): Promise<AgentResult>;
+    run(agent: Agent, query: string, opts?: RunOptions): 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>;
+    runCouncil(council: Council, query: string, opts?: RunOptions): Promise<CouncilOutput>;
 }
 
-export { type ModelAdapter, Runner, type RunnerConfig, type RunnerEvent };
+export { type CloudExecOptions, type CloudExecResult, type CloudSession, type CloudSessionProvider, LocalCloudSession, LocalCloudSessionProvider, type ModelAdapter, type RunOptions, Runner, type RunnerConfig, type RunnerEvent };