@vextlabs/theron-agent-sdk 0.3.0

package/dist/runtime/index.js

@@ -0,0 +1,203 @@
+// 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;
+  }
+};
+
+export { Runner };

package/dist/session/index.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+// src/session/index.ts
+var Session = class _Session {
+  id;
+  tenant_id;
+  state;
+  events;
+  constructor(config = {}) {
+    this.id = config.id ?? cryptoRandomId();
+    this.tenant_id = config.tenant_id;
+    this.state = new Map(Object.entries(config.initial_state ?? {}));
+    this.events = [];
+  }
+  append(event) {
+    this.events.push(event);
+  }
+  /** Get a read-only snapshot of all events. */
+  getEvents() {
+    return this.events;
+  }
+  /** Get events of a specific type (typed). */
+  getEventsOfType(type) {
+    return this.events.filter((e) => e.type === type);
+  }
+  /** Serialize the session for persistence. */
+  toJSON() {
+    return {
+      id: this.id,
+      tenant_id: this.tenant_id,
+      state: Object.fromEntries(this.state.entries()),
+      events: this.events.slice()
+    };
+  }
+  /** Restore a session from its serialized form. */
+  static fromJSON(data) {
+    const sess = new _Session({ id: data.id, tenant_id: data.tenant_id, initial_state: data.state });
+    for (const e of data.events) sess.events.push(e);
+    return sess;
+  }
+};
+function cryptoRandomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `sess_${Math.random().toString(36).slice(2)}_${Date.now()}`;
+}
+
+exports.Session = Session;

package/dist/session/index.d.cts

@@ -0,0 +1,79 @@
+type SessionEvent = {
+    type: "user_input";
+    content: string;
+    ts: number;
+} | {
+    type: "agent_output";
+    agent: string;
+    content: string;
+    ts: number;
+} | {
+    type: "tool_call";
+    tool: string;
+    input: unknown;
+    output: unknown;
+    ts: number;
+    ms: number;
+} | {
+    type: "verifier_result";
+    kernel: string;
+    pass: boolean;
+    issues: unknown[];
+    ts: number;
+} | {
+    type: "state_change";
+    key: string;
+    before: unknown;
+    after: unknown;
+    ts: number;
+} | {
+    type: "error";
+    agent: string;
+    message: string;
+    ts: number;
+};
+interface SessionConfig {
+    /** Unique session identifier. Generated if not provided. */
+    id?: string;
+    /** Optional tenant scope. */
+    tenant_id?: string;
+    /** Optional initial state. */
+    initial_state?: Record<string, unknown>;
+}
+type SessionJSON = {
+    id: string;
+    tenant_id?: string;
+    state: Record<string, unknown>;
+    events: SessionEvent[];
+};
+/**
+ * Session — append-only event log + scoped state.
+ *
+ * Minimal usage:
+ *   const sess = new Session();
+ *   sess.append({ type: "user_input", content: "Hello", ts: Date.now() });
+ *   sess.state.set("user_name", "Annalea");
+ *
+ * Persistence: by default, sessions are in-memory. Plug in a persistence
+ * adapter (Postgres, R2, SQLite) via the toJSON / fromJSON pair.
+ */
+declare class Session {
+    readonly id: string;
+    readonly tenant_id: string | undefined;
+    readonly state: Map<string, unknown>;
+    private readonly events;
+    constructor(config?: SessionConfig);
+    append(event: SessionEvent): void;
+    /** Get a read-only snapshot of all events. */
+    getEvents(): readonly SessionEvent[];
+    /** Get events of a specific type (typed). */
+    getEventsOfType<T extends SessionEvent["type"]>(type: T): Extract<SessionEvent, {
+        type: T;
+    }>[];
+    /** Serialize the session for persistence. */
+    toJSON(): SessionJSON;
+    /** Restore a session from its serialized form. */
+    static fromJSON(data: SessionJSON): Session;
+}
+
+export { Session, type SessionConfig, type SessionEvent, type SessionJSON };

package/dist/session/index.d.ts

@@ -0,0 +1,79 @@
+type SessionEvent = {
+    type: "user_input";
+    content: string;
+    ts: number;
+} | {
+    type: "agent_output";
+    agent: string;
+    content: string;
+    ts: number;
+} | {
+    type: "tool_call";
+    tool: string;
+    input: unknown;
+    output: unknown;
+    ts: number;
+    ms: number;
+} | {
+    type: "verifier_result";
+    kernel: string;
+    pass: boolean;
+    issues: unknown[];
+    ts: number;
+} | {
+    type: "state_change";
+    key: string;
+    before: unknown;
+    after: unknown;
+    ts: number;
+} | {
+    type: "error";
+    agent: string;
+    message: string;
+    ts: number;
+};
+interface SessionConfig {
+    /** Unique session identifier. Generated if not provided. */
+    id?: string;
+    /** Optional tenant scope. */
+    tenant_id?: string;
+    /** Optional initial state. */
+    initial_state?: Record<string, unknown>;
+}
+type SessionJSON = {
+    id: string;
+    tenant_id?: string;
+    state: Record<string, unknown>;
+    events: SessionEvent[];
+};
+/**
+ * Session — append-only event log + scoped state.
+ *
+ * Minimal usage:
+ *   const sess = new Session();
+ *   sess.append({ type: "user_input", content: "Hello", ts: Date.now() });
+ *   sess.state.set("user_name", "Annalea");
+ *
+ * Persistence: by default, sessions are in-memory. Plug in a persistence
+ * adapter (Postgres, R2, SQLite) via the toJSON / fromJSON pair.
+ */
+declare class Session {
+    readonly id: string;
+    readonly tenant_id: string | undefined;
+    readonly state: Map<string, unknown>;
+    private readonly events;
+    constructor(config?: SessionConfig);
+    append(event: SessionEvent): void;
+    /** Get a read-only snapshot of all events. */
+    getEvents(): readonly SessionEvent[];
+    /** Get events of a specific type (typed). */
+    getEventsOfType<T extends SessionEvent["type"]>(type: T): Extract<SessionEvent, {
+        type: T;
+    }>[];
+    /** Serialize the session for persistence. */
+    toJSON(): SessionJSON;
+    /** Restore a session from its serialized form. */
+    static fromJSON(data: SessionJSON): Session;
+}
+
+export { Session, type SessionConfig, type SessionEvent, type SessionJSON };

package/dist/session/index.js

@@ -0,0 +1,47 @@
+// src/session/index.ts
+var Session = class _Session {
+  id;
+  tenant_id;
+  state;
+  events;
+  constructor(config = {}) {
+    this.id = config.id ?? cryptoRandomId();
+    this.tenant_id = config.tenant_id;
+    this.state = new Map(Object.entries(config.initial_state ?? {}));
+    this.events = [];
+  }
+  append(event) {
+    this.events.push(event);
+  }
+  /** Get a read-only snapshot of all events. */
+  getEvents() {
+    return this.events;
+  }
+  /** Get events of a specific type (typed). */
+  getEventsOfType(type) {
+    return this.events.filter((e) => e.type === type);
+  }
+  /** Serialize the session for persistence. */
+  toJSON() {
+    return {
+      id: this.id,
+      tenant_id: this.tenant_id,
+      state: Object.fromEntries(this.state.entries()),
+      events: this.events.slice()
+    };
+  }
+  /** Restore a session from its serialized form. */
+  static fromJSON(data) {
+    const sess = new _Session({ id: data.id, tenant_id: data.tenant_id, initial_state: data.state });
+    for (const e of data.events) sess.events.push(e);
+    return sess;
+  }
+};
+function cryptoRandomId() {
+  if (typeof globalThis.crypto?.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `sess_${Math.random().toString(36).slice(2)}_${Date.now()}`;
+}
+
+export { Session };

package/dist/tools/index.cjs

@@ -0,0 +1,51 @@
+'use strict';
+
+var zod = require('zod');
+
+// src/tools/index.ts
+function defineTool(opts) {
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(opts.name)) {
+    throw new Error(
+      `Tool name "${opts.name}" is invalid. Must match /^[a-zA-Z][a-zA-Z0-9_-]*$/ for OpenAI/Anthropic tool-call compatibility.`
+    );
+  }
+  return {
+    schema: {
+      name: opts.name,
+      description: opts.description,
+      input_schema: zodToJsonSchema(opts.input)
+    },
+    async execute(input, ctx) {
+      const parsed = opts.input.safeParse(input);
+      if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new Error(`Tool "${opts.name}" received invalid input: ${issues}`);
+      }
+      return opts.execute(parsed.data, ctx);
+    }
+  };
+}
+function zodToJsonSchema(schema) {
+  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);
+    }
+    return { 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" };
+}
+
+Object.defineProperty(exports, "zod", {
+  enumerable: true,
+  get: function () { return zod.z; }
+});
+exports.defineTool = defineTool;

package/dist/tools/index.d.cts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export { z as zod } from 'zod';
+
+interface ToolContext {
+    /** Current working directory (for file-system tools). */
+    cwd: string;
+    /** Whether to auto-approve potentially destructive operations.
+     *  Default `false`. The SDK does NOT enforce sandboxing — tool authors are
+     *  responsible for honoring this flag when their tool can mutate state. */
+    yolo: boolean;
+    /** Session identifier (for memory + audit logging). */
+    session_id?: string;
+    /** Tenant identifier (for multi-tenant deployments). */
+    tenant_id?: string;
+}
+interface ToolSchema {
+    name: string;
+    description: string;
+    /** JSON schema describing the input shape. */
+    input_schema: Record<string, unknown>;
+}
+interface Tool<TInput = unknown, TOutput = unknown> {
+    schema: ToolSchema;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+/**
+ * defineTool — ergonomic tool factory.
+ *
+ * Pass a Zod schema for input + an async execute fn. The schema is converted
+ * to JSON-schema automatically and used to validate tool-call args at runtime.
+ *
+ * Example:
+ *   const greet = defineTool({
+ *     name: "greet",
+ *     description: "Greet a person by name.",
+ *     input: z.object({ name: z.string() }),
+ *     async execute({ name }) {
+ *       return `Hello, ${name}!`;
+ *     },
+ *   });
+ *
+ * On invalid input, throws an Error with a structured message that includes
+ * the tool name + Zod's parse issues — surface this to your end user.
+ */
+declare function defineTool<TSchema extends z.ZodTypeAny, TOutput>(opts: {
+    name: string;
+    description: string;
+    input: TSchema;
+    execute: (input: z.infer<TSchema>, ctx: ToolContext) => Promise<TOutput>;
+}): Tool<z.infer<TSchema>, TOutput>;
+
+export { type Tool, type ToolContext, type ToolSchema, defineTool };

package/dist/tools/index.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export { z as zod } from 'zod';
+
+interface ToolContext {
+    /** Current working directory (for file-system tools). */
+    cwd: string;
+    /** Whether to auto-approve potentially destructive operations.
+     *  Default `false`. The SDK does NOT enforce sandboxing — tool authors are
+     *  responsible for honoring this flag when their tool can mutate state. */
+    yolo: boolean;
+    /** Session identifier (for memory + audit logging). */
+    session_id?: string;
+    /** Tenant identifier (for multi-tenant deployments). */
+    tenant_id?: string;
+}
+interface ToolSchema {
+    name: string;
+    description: string;
+    /** JSON schema describing the input shape. */
+    input_schema: Record<string, unknown>;
+}
+interface Tool<TInput = unknown, TOutput = unknown> {
+    schema: ToolSchema;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+/**
+ * defineTool — ergonomic tool factory.
+ *
+ * Pass a Zod schema for input + an async execute fn. The schema is converted
+ * to JSON-schema automatically and used to validate tool-call args at runtime.
+ *
+ * Example:
+ *   const greet = defineTool({
+ *     name: "greet",
+ *     description: "Greet a person by name.",
+ *     input: z.object({ name: z.string() }),
+ *     async execute({ name }) {
+ *       return `Hello, ${name}!`;
+ *     },
+ *   });
+ *
+ * On invalid input, throws an Error with a structured message that includes
+ * the tool name + Zod's parse issues — surface this to your end user.
+ */
+declare function defineTool<TSchema extends z.ZodTypeAny, TOutput>(opts: {
+    name: string;
+    description: string;
+    input: TSchema;
+    execute: (input: z.infer<TSchema>, ctx: ToolContext) => Promise<TOutput>;
+}): Tool<z.infer<TSchema>, TOutput>;
+
+export { type Tool, type ToolContext, type ToolSchema, defineTool };

package/dist/tools/index.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export { z as zod } from 'zod';
+
+// src/tools/index.ts
+function defineTool(opts) {
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(opts.name)) {
+    throw new Error(
+      `Tool name "${opts.name}" is invalid. Must match /^[a-zA-Z][a-zA-Z0-9_-]*$/ for OpenAI/Anthropic tool-call compatibility.`
+    );
+  }
+  return {
+    schema: {
+      name: opts.name,
+      description: opts.description,
+      input_schema: zodToJsonSchema(opts.input)
+    },
+    async execute(input, ctx) {
+      const parsed = opts.input.safeParse(input);
+      if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new Error(`Tool "${opts.name}" received invalid input: ${issues}`);
+      }
+      return opts.execute(parsed.data, ctx);
+    }
+  };
+}
+function zodToJsonSchema(schema) {
+  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);
+    }
+    return { 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" };
+}
+
+export { defineTool };