@vextlabs/theron-agent-sdk 0.3.0 → 0.3.1

package/dist/runtime/index.d.ts

@@ -6,6 +6,65 @@ import { ToolContext } from '../tools/index.js';
 import { VerifierResult } from '../verifiers/index.js';
 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 };

package/dist/runtime/index.js

@@ -1,3 +1,73 @@
+import { readFile, mkdir, writeFile, rm, mkdtemp } from 'fs/promises';
+import { tmpdir } from 'os';
+import { dirname, join, isAbsolute, resolve, relative, sep } from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { randomUUID } from 'crypto';
+
+// src/runtime/cloud-session.ts
+var pExecFile = promisify(execFile);
+function resolveInside(root, p) {
+  const abs = isAbsolute(p) ? p : resolve(root, p);
+  const rel = relative(root, abs);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || 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 readFile(resolveInside(this.root, path), "utf8");
+  }
+  async writeFile(path, content) {
+    if (this.disposed) throw new Error("session disposed");
+    const abs = resolveInside(this.root, path);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, content, "utf8");
+  }
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    await rm(this.root, { recursive: true, force: true });
+  }
+};
+var LocalCloudSessionProvider = class {
+  async provision() {
+    const id = randomUUID();
+    const root = await mkdtemp(join(tmpdir(), `theron-session-${id.slice(0, 8)}-`));
+    return new LocalCloudSession(id, root);
+  }
+};
+
 // src/runtime/index.ts
 var Runner = class {
   model;
@@ -35,8 +105,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 }
@@ -49,49 +120,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) {
@@ -114,8 +220,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
     };
   }
@@ -125,17 +231,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",
@@ -161,8 +268,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.
@@ -200,4 +310,4 @@ var Runner = class {
   }
 };
 
-export { Runner };
+export { LocalCloudSession, LocalCloudSessionProvider, Runner };

package/dist/tools/index.cjs

@@ -26,22 +26,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" });
 }
 
 Object.defineProperty(exports, "zod", {

package/dist/tools/index.js

@@ -25,22 +25,57 @@ function defineTool(opts) {
   };
 }
 function zodToJsonSchema(schema) {
+  const description = schema._def?.description;
+  const withDesc = (s) => description ? { ...s, description } : s;
+  if (schema instanceof z.ZodOptional) return zodToJsonSchema(schema.unwrap());
+  if (schema instanceof 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 z.ZodNullable) {
+    return withDesc({ ...zodToJsonSchema(schema.unwrap()), nullable: true });
+  }
   if (schema instanceof z.ZodObject) {
     const properties = {};
     const required = [];
     for (const [key, value] of Object.entries(schema.shape)) {
-      properties[key] = zodToJsonSchema(value);
-      if (!(value instanceof z.ZodOptional)) required.push(key);
+      const field = value;
+      properties[key] = zodToJsonSchema(field);
+      if (!(field instanceof z.ZodOptional) && !(field instanceof 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 z.ZodString) return { type: "string" };
-  if (schema instanceof z.ZodNumber) return { type: "number" };
-  if (schema instanceof z.ZodBoolean) return { type: "boolean" };
-  if (schema instanceof z.ZodArray) return { type: "array", items: zodToJsonSchema(schema.element) };
-  if (schema instanceof z.ZodOptional) return zodToJsonSchema(schema.unwrap());
-  if (schema instanceof z.ZodEnum) return { type: "string", enum: schema.options };
-  return { type: "string" };
+  if (schema instanceof z.ZodString) return withDesc({ type: "string" });
+  if (schema instanceof z.ZodNumber) return withDesc({ type: "number" });
+  if (schema instanceof z.ZodBoolean) return withDesc({ type: "boolean" });
+  if (schema instanceof z.ZodArray) return withDesc({ type: "array", items: zodToJsonSchema(schema.element) });
+  if (schema instanceof z.ZodEnum) return withDesc({ type: "string", enum: schema.options });
+  if (schema instanceof 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 z.ZodUnion) {
+    const options = schema._def.options;
+    return withDesc({ anyOf: options.map((o) => zodToJsonSchema(o)) });
+  }
+  if (schema instanceof z.ZodRecord) {
+    const valueType = schema._def.valueType;
+    return withDesc({
+      type: "object",
+      additionalProperties: valueType ? zodToJsonSchema(valueType) : true
+    });
+  }
+  return withDesc({ type: "string" });
 }
 
 export { defineTool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vextlabs/theron-agent-sdk",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Open-source agent SDK with a Council of specialists, deterministic verifier kernels, and Stoa-signed integrations. Build any agent against any model. From Vext Labs.",
   "license": "MIT",
   "homepage": "https://tryvext.com/adk",