@vextlabs/theron-agent-sdk 0.3.0

package/dist/index.js

@@ -0,0 +1,1244 @@
+import { z } from 'zod';
+export { z as zod } from 'zod';
+
+// src/agent/index.ts
+var Agent = class {
+  name;
+  model;
+  instruction;
+  tools;
+  sub_agents;
+  verifiers;
+  max_turns;
+  constructor(config) {
+    if (!config.name) throw new Error("Agent requires a `name`.");
+    if (!config.instruction) throw new Error(`Agent "${config.name}" requires an \`instruction\`.`);
+    this.name = config.name;
+    this.model = config.model;
+    this.instruction = typeof config.instruction === "string" ? { system: config.instruction } : config.instruction;
+    this.tools = config.tools ?? [];
+    this.sub_agents = config.sub_agents ?? [];
+    this.verifiers = config.verifiers ?? [];
+    this.max_turns = config.max_turns ?? 10;
+  }
+  /** Render the tools as JSON schemas for the model. */
+  toolSchemas() {
+    return this.tools.map((t) => t.schema);
+  }
+  /** True if the agent has any sub-agents (i.e., this is a supervisor). */
+  isSupervisor() {
+    return this.sub_agents.length > 0;
+  }
+};
+
+// src/council/index.ts
+var Council = class {
+  name;
+  specialists;
+  verifiers;
+  reconciler;
+  specialist_timeout_ms;
+  constructor(config) {
+    if (!config.name) throw new Error("Council requires a `name`.");
+    if (!config.specialists || config.specialists.length === 0) {
+      throw new Error(`Council "${config.name}" requires at least one specialist.`);
+    }
+    this.name = config.name;
+    this.specialists = config.specialists;
+    this.verifiers = config.verifiers ?? [];
+    this.reconciler = config.reconciler ?? deterministicClaimMerge;
+    this.specialist_timeout_ms = config.specialist_timeout_ms ?? 3e4;
+  }
+  /**
+   * Convenience entry point — pointed at the Runner you've already constructed.
+   * Most users will call `runner.runCouncil(council, query)` directly; this
+   * exists for symmetry with `agent.run`-style ergonomics in user code.
+   */
+  async deliberate(_query) {
+    throw new Error(
+      "Council.deliberate() requires a Runner. Use:\n  const runner = new Runner({ ... });\n  const result = await runner.runCouncil(council, query);\nSee: https://github.com/Vext-Labs-Inc/theron-agent-sdk/blob/main/examples/03_council_of_three.ts"
+    );
+  }
+};
+var deterministicClaimMerge = async (specialists) => {
+  if (specialists.length === 0) {
+    return { answer: "(no specialists responded)", consensus: "refuted" };
+  }
+  if (specialists.length === 1) {
+    return { answer: specialists[0].output, consensus: "ratified" };
+  }
+  const claimMap = /* @__PURE__ */ new Map();
+  for (const s of specialists) {
+    for (const c of s.claims) {
+      const key = c.text.toLowerCase().trim();
+      if (!claimMap.has(key)) claimMap.set(key, []);
+      claimMap.get(key).push(s.specialist);
+    }
+  }
+  const ratified = [];
+  const disagreements = [];
+  const majorityThreshold = specialists.length / 2;
+  for (const [claim, voters] of claimMap.entries()) {
+    if (voters.length === specialists.length) {
+      ratified.push(claim);
+    } else if (voters.length > majorityThreshold) {
+      ratified.push(claim);
+    } else {
+      disagreements.push({
+        claim,
+        specialists_for: voters,
+        specialists_against: specialists.map((s) => s.specialist).filter((n) => !voters.includes(n))
+      });
+    }
+  }
+  const answer = ratified.join(" ") || specialists[0].output;
+  const consensus = disagreements.length > 0 ? "split" : ratified.length > 0 ? "ratified" : "refuted";
+  return { answer, consensus, disagreements: disagreements.length > 0 ? disagreements : void 0 };
+};
+
+// 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()}`;
+}
+
+// src/memory/index.ts
+var Memory = class {
+};
+var InMemoryStore = class extends Memory {
+  records = /* @__PURE__ */ new Map();
+  async set(record) {
+    const id = record.id ?? `mem_${Math.random().toString(36).slice(2)}_${Date.now()}`;
+    const full = {
+      ...record,
+      id,
+      created_at: record.created_at ?? Date.now(),
+      last_accessed_at: record.last_accessed_at ?? Date.now()
+    };
+    this.records.set(id, full);
+    return full;
+  }
+  async get(id) {
+    const r = this.records.get(id);
+    if (r) {
+      r.last_accessed_at = Date.now();
+    }
+    return r;
+  }
+  async query(q) {
+    let results = Array.from(this.records.values());
+    if (q.tenant_id !== void 0) {
+      results = results.filter((r) => r.tenant_id === q.tenant_id);
+    }
+    if (q.key !== void 0) {
+      results = results.filter((r) => r.key === q.key);
+    }
+    if (q.tags !== void 0 && q.tags.length > 0) {
+      results = results.filter((r) => r.tags?.some((t) => q.tags.includes(t)));
+    }
+    if (q.semantic_query !== void 0) {
+      const ql = q.semantic_query.toLowerCase();
+      results = results.filter((r) => r.value.toLowerCase().includes(ql));
+    }
+    results.sort((a, b) => b.last_accessed_at - a.last_accessed_at);
+    if (q.limit !== void 0) {
+      results = results.slice(0, q.limit);
+    }
+    return results;
+  }
+  async delete(id) {
+    this.records.delete(id);
+  }
+};
+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" };
+}
+
+// src/tools/local-contract.ts
+var LOCAL_TOOL_PARAMETERS = {
+  Read: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "Absolute or relative path to the file." },
+      offset: { type: "number", description: "Optional 1-indexed line to start reading from." },
+      limit: { type: "number", description: "Optional max lines to read." }
+    },
+    required: ["file_path"]
+  },
+  Write: {
+    type: "object",
+    properties: {
+      file_path: { type: "string" },
+      content: { type: "string", description: "Full file contents \u2014 overwrites whatever was there." }
+    },
+    required: ["file_path", "content"]
+  },
+  Edit: {
+    type: "object",
+    properties: {
+      file_path: { type: "string" },
+      old_string: { type: "string" },
+      new_string: { type: "string" },
+      replace_all: { type: "boolean", default: false }
+    },
+    required: ["file_path", "old_string", "new_string"]
+  },
+  Bash: {
+    type: "object",
+    properties: {
+      command: { type: "string" },
+      timeout: { type: "number", description: "Timeout in ms (default 120000, max 600000)." },
+      description: { type: "string", description: "Short label for what the command does, shown to the user." }
+    },
+    required: ["command"]
+  },
+  Glob: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Glob like 'src/**/*.ts'." },
+      path: { type: "string", description: "Root directory to search from. Defaults to the working directory." }
+    },
+    required: ["pattern"]
+  },
+  Grep: {
+    type: "object",
+    properties: {
+      pattern: { type: "string", description: "Regex pattern." },
+      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 }
+    },
+    required: ["pattern"]
+  },
+  LS: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Path to list. Defaults to the working directory." }
+    }
+  }
+};
+var LOCAL_TOOL_NAMES = [
+  "Read",
+  "Write",
+  "Edit",
+  "Bash",
+  "Glob",
+  "Grep",
+  "LS"
+];
+var MUTATING_LOCAL_TOOLS = /* @__PURE__ */ new Set([
+  "Write",
+  "Edit",
+  "Bash"
+]);
+function buildLocalToolSchemas(descriptions) {
+  return LOCAL_TOOL_NAMES.map((name) => ({
+    type: "function",
+    function: {
+      name,
+      description: descriptions[name] ?? "",
+      parameters: LOCAL_TOOL_PARAMETERS[name]
+    }
+  }));
+}
+
+// src/verifiers/index.ts
+function defineVerifier(opts) {
+  return {
+    name: opts.name,
+    description: opts.description,
+    async check(output, context) {
+      const t0 = Date.now();
+      const result = await opts.check(output, context);
+      return { kernel: opts.name, pass: result.pass, issues: result.issues, ms: Date.now() - t0 };
+    }
+  };
+}
+var VerifierKernels = {
+  /** Block em-dashes (common AI tell). */
+  emDash: defineVerifier({
+    name: "em_dash_check",
+    description: "Block em-dashes in output (common AI tell).",
+    check: async (output) => {
+      const matches = [...output.matchAll(/—/g)];
+      const issues = matches.map((m) => ({
+        kernel: "em_dash_check",
+        severity: "error",
+        message: "Em-dash detected",
+        span: { start: m.index, end: m.index + 1 }
+      }));
+      return { pass: issues.length === 0, issues };
+    }
+  }),
+  /** Block common AI-ism words. Word-boundary aware to avoid false positives
+   *  (e.g., "leverage" matches but not "delivered"). */
+  aiIsm: defineVerifier({
+    name: "ai_ism_check",
+    description: "Block common AI-ism words.",
+    check: async (output) => {
+      const aiisms = ["delve", "tapestry", "leverage", "robust", "seamless", "navigate", "embark"];
+      const issues = [];
+      for (const w of aiisms) {
+        const re = new RegExp(`\\b${w}\\b`, "gi");
+        if (re.test(output)) {
+          issues.push({
+            kernel: "ai_ism_check",
+            severity: "warning",
+            message: `AI-ism detected: "${w}"`
+          });
+        }
+      }
+      return { pass: issues.length === 0, issues };
+    }
+  }),
+  /** Re-evaluate arithmetic claims like "X op Y = Z". */
+  arithmetic: defineVerifier({
+    name: "arithmetic_recheck",
+    description: "Re-evaluate arithmetic in 'X op Y = Z' form.",
+    check: async (output) => {
+      const pattern = /(-?\d+(?:\.\d+)?)\s*([+\-*/])\s*(-?\d+(?:\.\d+)?)\s*=\s*(-?\d+(?:\.\d+)?)/g;
+      const issues = [];
+      for (const m of output.matchAll(pattern)) {
+        const a = parseFloat(m[1]);
+        const op = m[2];
+        const b = parseFloat(m[3]);
+        const claimed = parseFloat(m[4]);
+        const actual = op === "+" ? a + b : op === "-" ? a - b : op === "*" ? a * b : op === "/" ? b === 0 ? NaN : a / b : NaN;
+        if (!Number.isFinite(actual) || Math.abs(actual - claimed) > 1e-6) {
+          issues.push({
+            kernel: "arithmetic_recheck",
+            severity: "error",
+            message: `Claimed ${a} ${op} ${b} = ${claimed}; actual ${Number.isFinite(actual) ? actual : "undefined"}`
+          });
+        }
+      }
+      return { pass: issues.length === 0, issues };
+    }
+  }),
+  /** Require at least one citation pattern ([N], (Author Year), https://...). */
+  citationPresence: defineVerifier({
+    name: "citation_presence",
+    description: "Require at least one citation in output.",
+    check: async (output) => {
+      const patterns = [/\[\d+\]/, /\([A-Z][a-z]+(?: et al\.?)? \d{4}\)/, /https?:\/\//];
+      const found = patterns.some((p) => p.test(output));
+      const issues = found ? [] : [
+        {
+          kernel: "citation_presence",
+          severity: "error",
+          message: "No citation found. Expected one of: [N], (Author YEAR), or a URL."
+        }
+      ];
+      return { pass: found, issues };
+    }
+  })
+};
+
+// 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;
+  }
+};
+
+// src/mcp/index.ts
+var MCP_PROTOCOL_VERSION = "2024-11-05";
+var DEFAULT_TIMEOUT_MS = 12e3;
+var MCPClient = class {
+  config;
+  initialized = false;
+  toolCache = null;
+  constructor(config) {
+    if (!/^[a-z0-9_-]+$/.test(config.slug)) {
+      throw new Error(
+        `MCPClient slug "${config.slug}" must match /^[a-z0-9_-]+$/`
+      );
+    }
+    this.config = { timeout_ms: DEFAULT_TIMEOUT_MS, ...config };
+  }
+  /** Fetch the server's tool catalog. Cached for the lifetime of the client. */
+  async listTools(signal) {
+    if (this.toolCache) return this.toolCache;
+    await this.ensureInitialized(signal);
+    const result = await this.rpc("tools/list", {}, signal);
+    this.toolCache = Array.isArray(result?.tools) ? result.tools : [];
+    return this.toolCache;
+  }
+  /** Call a tool by its bare (non-namespaced) name. Returns the text payload. */
+  async callTool(name, args, signal) {
+    await this.ensureInitialized(signal);
+    const result = await this.rpc(
+      "tools/call",
+      { name, arguments: args },
+      signal
+    );
+    const blocks = Array.isArray(result?.content) ? result.content : [];
+    const text = blocks.map((b) => b.type === "text" && typeof b.text === "string" ? b.text : "").filter(Boolean).join("\n").trim();
+    return text || JSON.stringify(result ?? {}).slice(0, 4e3);
+  }
+  /**
+   * Return the server's tool catalog as SDK Tool[] objects, namespaced so they
+   * compose with tools from other sources without colliding.
+   *
+   * Pass these directly to a Runner. The Runner sees standard SDK tools; it
+   * never has to know MCP existed.
+   */
+  async asTools(signal) {
+    const raw = await this.listTools(signal);
+    return raw.map((t) => this.toSdkTool(t));
+  }
+  /** Health-check: returns toolCount on success, throws on failure. */
+  async probe(signal) {
+    const tools = await this.listTools(signal);
+    return { toolCount: tools.length };
+  }
+  // -------------------------------------------------------------- internals
+  toSdkTool(raw) {
+    const ns = `${this.config.slug}__${raw.name}`.slice(0, 64).replace(/[^a-zA-Z0-9_-]/g, "_");
+    const schema = {
+      name: ns,
+      description: `[${this.config.name}] ${raw.description || raw.name}`,
+      input_schema: raw.inputSchema ?? {
+        type: "object",
+        properties: {}
+      }
+    };
+    const client = this;
+    return {
+      schema,
+      async execute(input, _ctx) {
+        return client.callTool(raw.name, input);
+      }
+    };
+  }
+  async ensureInitialized(signal) {
+    if (this.initialized) return;
+    await this.rpc(
+      "initialize",
+      {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "theron-agent-sdk", version: "0.1" }
+      },
+      signal
+    );
+    this.rpc("notifications/initialized", {}, signal).catch(() => void 0);
+    this.initialized = true;
+  }
+  async rpc(method, params, externalSignal) {
+    const ac = new AbortController();
+    const timer = setTimeout(
+      () => ac.abort(),
+      this.config.timeout_ms ?? DEFAULT_TIMEOUT_MS
+    );
+    if (externalSignal) {
+      if (externalSignal.aborted) ac.abort();
+      else externalSignal.addEventListener("abort", () => ac.abort());
+    }
+    const body = {
+      jsonrpc: "2.0",
+      id: Date.now() + Math.floor(Math.random() * 1e3),
+      method,
+      params
+    };
+    try {
+      const r = await fetch(this.config.url, {
+        method: "POST",
+        signal: ac.signal,
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json, text/event-stream",
+          ...this.config.token ? { Authorization: `Bearer ${this.config.token}` } : {},
+          "MCP-Protocol-Version": MCP_PROTOCOL_VERSION
+        },
+        body: JSON.stringify(body)
+      });
+      if (!r.ok) {
+        const errText = await r.text().catch(() => "");
+        throw new Error(
+          `mcp http ${r.status} on ${method}: ${errText.slice(0, 200)}`
+        );
+      }
+      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;
+      }
+      const env = await r.json();
+      if (env.error) throw new Error(`mcp error: ${env.error.message}`);
+      return env.result;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+async function collectMcpTools(clients, signal) {
+  const lists = await Promise.all(
+    clients.map(async (c) => {
+      try {
+        return await c.asTools(signal);
+      } catch (err) {
+        console.warn(`[mcp] ${c.config.slug} listTools failed:`, err);
+        return [];
+      }
+    })
+  );
+  return lists.flat();
+}
+
+// src/adapters/theron.ts
+function theronAdapter(opts = {}) {
+  const base = (opts.base ?? "https://itstheron.com").replace(/\/$/, "");
+  const url = `${base}/api/v1/chat/completions`;
+  const councilMode = opts.councilMode ?? "fast";
+  return {
+    name: "theron",
+    async chat({ model, messages, tools, max_tokens, temperature, onDelta }) {
+      const body = {
+        model: model || "theron-council",
+        council_mode: councilMode,
+        messages,
+        max_tokens: max_tokens ?? 2048,
+        temperature: temperature ?? 0.2,
+        stream: !!onDelta
+      };
+      if (tools && tools.length > 0) {
+        body.tools = tools.map((t) => ({
+          type: "function",
+          function: { name: t.name, description: t.description, parameters: t.input_schema }
+        }));
+      }
+      const headers = { "Content-Type": "application/json" };
+      if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
+      const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+      if (!res.ok) {
+        throw new Error(`Theron ${res.status} (${url}): ${(await res.text().catch(() => "")).slice(0, 500)}`);
+      }
+      if (onDelta && res.body) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let content = "";
+        let inputTokens = 0;
+        let outputTokens = 0;
+        let buf = "";
+        for (; ; ) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split("\n");
+          buf = lines.pop() ?? "";
+          for (const line of lines) {
+            if (!line.startsWith("data:")) continue;
+            const data = line.slice(5).trim();
+            if (!data || data === "[DONE]") continue;
+            try {
+              const json2 = JSON.parse(data);
+              const delta = json2.choices?.[0]?.delta?.content;
+              if (delta) {
+                onDelta(delta);
+                content += delta;
+              }
+              if (json2.usage) {
+                inputTokens = json2.usage.prompt_tokens ?? inputTokens;
+                outputTokens = json2.usage.completion_tokens ?? outputTokens;
+              }
+            } catch {
+            }
+          }
+        }
+        return { content, tokens: { input: inputTokens, output: outputTokens } };
+      }
+      const json = await res.json();
+      const msg = json.choices?.[0]?.message ?? { content: "" };
+      const tool_calls = msg.tool_calls?.map((tc) => ({
+        name: tc.function.name,
+        input: safeJson(tc.function.arguments)
+      }));
+      return {
+        content: msg.content ?? "",
+        tool_calls,
+        tokens: {
+          input: json.usage?.prompt_tokens ?? 0,
+          output: json.usage?.completion_tokens ?? 0
+        }
+      };
+    }
+  };
+}
+var theron = theronAdapter;
+function safeJson(s) {
+  try {
+    return JSON.parse(s || "{}");
+  } catch {
+    return {};
+  }
+}
+
+// src/receipts/index.ts
+var ReceiptEmitter = class {
+  sinks;
+  signer;
+  issuer;
+  actor;
+  tenant_id;
+  constructor(config) {
+    if (!config.sinks || config.sinks.length === 0) {
+      throw new Error("ReceiptEmitter requires at least one sink.");
+    }
+    this.sinks = config.sinks;
+    this.signer = config.signer;
+    this.issuer = config.signer?.issuer ?? config.issuer ?? "did:web:local";
+    this.actor = config.actor;
+    this.tenant_id = config.tenant_id;
+  }
+  async emit(input) {
+    const ts = Date.now();
+    const payload = {
+      input: input.input,
+      output: input.output,
+      ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
+    };
+    const content_hash = await sha256Hex(canonicalize(payload));
+    let receipt = {
+      v: "stoa.receipt.v1",
+      id: ulid(),
+      cap: input.cap,
+      issuer: this.issuer,
+      actor: input.actor ?? this.actor,
+      ts,
+      session_id: input.session_id,
+      tenant_id: input.tenant_id ?? this.tenant_id,
+      content_hash,
+      payload
+    };
+    if (this.signer) {
+      const signature = await this.signer.sign(receipt);
+      receipt = { ...receipt, signature };
+    }
+    await Promise.all(
+      this.sinks.map(async (sink) => {
+        try {
+          await sink.emit(receipt);
+        } catch (err) {
+          console.warn(`[receipts] sink "${sink.name}" failed:`, err);
+        }
+      })
+    );
+    return receipt;
+  }
+};
+var InMemoryReceiptSink = class {
+  name = "in-memory";
+  records = [];
+  async emit(receipt) {
+    this.records.push(receipt);
+  }
+  list() {
+    return this.records;
+  }
+  clear() {
+    this.records.length = 0;
+  }
+};
+function fileReceiptSink(path) {
+  return {
+    name: `file:${path}`,
+    async emit(receipt) {
+      const fs = await import('fs/promises');
+      await fs.appendFile(path, JSON.stringify(receipt) + "\n", "utf8");
+    }
+  };
+}
+function httpReceiptSink(opts) {
+  const timeout_ms = opts.timeout_ms ?? 5e3;
+  return {
+    name: `http:${new URL(opts.url).host}`,
+    async emit(receipt) {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeout_ms);
+      try {
+        const res = await fetch(opts.url, {
+          method: "POST",
+          signal: ac.signal,
+          headers: {
+            "Content-Type": "application/json",
+            ...opts.token ? { Authorization: `Bearer ${opts.token}` } : {}
+          },
+          body: JSON.stringify(receipt)
+        });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          throw new Error(
+            `http sink ${opts.url} returned ${res.status}: ${text.slice(0, 200)}`
+          );
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => canonicalize(v)).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return "{" + keys.map(
+    (k) => JSON.stringify(k) + ":" + canonicalize(value[k])
+  ).join(",") + "}";
+}
+async function sha256Hex(input) {
+  const data = new TextEncoder().encode(input);
+  const buf = await globalThis.crypto.subtle.digest("SHA-256", data);
+  const bytes = new Uint8Array(buf);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function ulid() {
+  const ts = Date.now();
+  const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+  let tsPart = "";
+  let t = ts;
+  for (let i = 9; i >= 0; i--) {
+    tsPart = ALPHABET[t % 32] + tsPart;
+    t = Math.floor(t / 32);
+  }
+  let randPart = "";
+  if (globalThis.crypto?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    for (let i = 0; i < 16; i++) randPart += ALPHABET[bytes[i] % 32];
+  } else {
+    for (let i = 0; i < 16; i++)
+      randPart += ALPHABET[Math.floor(Math.random() * 32)];
+  }
+  return tsPart + randPart;
+}
+
+// src/loop/index.ts
+function stepCountIs(n) {
+  return (s) => s.step >= n;
+}
+function costUsdAtLeast(min) {
+  return (s) => s.cost_usd >= min;
+}
+function verifierSatisfied(kernelName) {
+  return (s) => {
+    if (!s.verifier_results) return false;
+    return s.verifier_results.some((r) => r.kernel === kernelName && r.pass === true);
+  };
+}
+function anyOf(...preds) {
+  return (s) => preds.some((p) => p(s));
+}
+function allOf(...preds) {
+  return (s) => preds.every((p) => p(s));
+}
+function verifiedRatchet(opts) {
+  const threshold = opts?.minConfidence ?? 0.6;
+  return (v) => {
+    if (v === void 0) {
+      return { advance: false, reason: "no verdict" };
+    }
+    if (v.verdict !== "sufficient") {
+      return {
+        advance: false,
+        reason: `verdict '${v.verdict}' is not 'sufficient'${v.source ? ` (source: ${v.source})` : ""}`
+      };
+    }
+    if (v.confidence < threshold) {
+      return {
+        advance: false,
+        reason: `verdict is 'sufficient' but confidence ${v.confidence.toFixed(3)} < threshold ${threshold.toFixed(3)}`
+      };
+    }
+    return {
+      advance: true,
+      reason: `verified sufficient at confidence ${v.confidence.toFixed(3)} >= ${threshold.toFixed(3)}${v.source ? ` (source: ${v.source})` : ""}`
+    };
+  };
+}
+async function runImprovementCycle(spec) {
+  const ratchet = spec.ratchet ?? verifiedRatchet();
+  const proposal = await spec.propose();
+  const trial = await spec.trial(proposal);
+  const verdict = await spec.verify(proposal, trial);
+  const decision = ratchet(verdict);
+  return { proposal, trial, verdict, decision };
+}
+var SUMMARY_PREFIX = "[Summary of earlier conversation]";
+async function compactHistory(opts) {
+  const keepRecent = Math.max(1, Math.floor(opts.keepRecent ?? 6));
+  const msgs = opts.messages ?? [];
+  const totalChars = msgs.reduce((n, m) => n + (m.content?.length ?? 0), 0);
+  const maxChars = opts.maxChars ?? 0;
+  if (msgs.length <= keepRecent || maxChars > 0 && totalChars <= maxChars) {
+    return { messages: msgs, compacted: false, droppedCount: 0 };
+  }
+  const older = msgs.slice(0, msgs.length - keepRecent);
+  const recent = msgs.slice(msgs.length - keepRecent);
+  const summary = String(await opts.summarize(older));
+  return {
+    messages: [{ role: "system", content: `${SUMMARY_PREFIX}
+${summary}` }, ...recent],
+    compacted: true,
+    summary,
+    droppedCount: older.length
+  };
+}
+async function runUntil(opts) {
+  const maxSteps = Math.max(1, Math.floor(opts.maxSteps ?? 100));
+  let state = opts.initial;
+  for (let i = 0; i < maxSteps; i++) {
+    state = await opts.step(state, i);
+    if (opts.onCheckpoint) await opts.onCheckpoint(state, i);
+    if (opts.stopWhen(state, i)) return { state, steps: i + 1, stopped: "predicate" };
+  }
+  return { state, steps: maxSteps, stopped: "maxSteps" };
+}
+function boundWorkingSet(items, max) {
+  const cap = Math.max(0, Math.floor(max));
+  if (items.length <= cap) return { kept: items, evicted: [] };
+  const pinned = items.filter((i) => i.pinned);
+  const rest = items.filter((i) => !i.pinned);
+  const slots = Math.max(0, cap - pinned.length);
+  const ranked = [...rest].sort((a, b) => (b.importance ?? 0) - (a.importance ?? 0) || b.seq - a.seq);
+  const keepRest = new Set(ranked.slice(0, slots));
+  const kept = items.filter((i) => i.pinned || keepRest.has(i));
+  const evicted = items.filter((i) => !i.pinned && !keepRest.has(i));
+  return { kept, evicted };
+}
+
+// src/patterns/index.ts
+async function selfConsistency(opts) {
+  const n = Math.max(1, Math.floor(opts.samples));
+  const keyOf = opts.key ?? ((v) => JSON.stringify(v));
+  const clusters = /* @__PURE__ */ new Map();
+  let total = 0;
+  for (let i = 0; i < n; i++) {
+    const v = await opts.generate(i);
+    if (v === void 0 || v === null) continue;
+    total += 1;
+    const k = keyOf(v);
+    const c = clusters.get(k) ?? { count: 0, sample: v };
+    c.count += 1;
+    clusters.set(k, c);
+  }
+  if (total === 0) throw new Error("selfConsistency: generate produced no values");
+  const ranked = [...clusters.entries()].map(([key, { count, sample }]) => ({ key, count, sample })).sort((a, b) => b.count - a.count);
+  const winner = ranked[0];
+  return {
+    answer: winner.sample,
+    consistency: Math.round(winner.count / total * 1e3) / 1e3,
+    votes: winner.count,
+    total,
+    clusters: ranked
+  };
+}
+async function bestOfN(opts) {
+  const n = Math.max(1, Math.floor(opts.n));
+  let best = null;
+  const scores = [];
+  for (let i = 0; i < n; i++) {
+    const v = await opts.generate(i);
+    const s = await opts.score(v, i);
+    scores.push(s);
+    if (!best || s > best.score) best = { value: v, score: s, index: i };
+  }
+  if (!best) throw new Error("bestOfN: generate produced no candidates");
+  return { best: best.value, score: best.score, index: best.index, scores };
+}
+var DEFAULT_CLEAN = /\b(no (issues|problems|flaws|changes)|looks good|lgtm|nothing to (fix|improve))\b/i;
+async function selfRefine(opts) {
+  const maxIters = Math.max(1, Math.floor(opts.maxIters ?? 2));
+  const isClean = opts.isClean ?? ((c) => DEFAULT_CLEAN.test(c));
+  let value = await opts.draft();
+  const trace = [];
+  let revised = 0;
+  for (let iter = 1; iter <= maxIters; iter++) {
+    const critique = String(await opts.critique(value, iter));
+    if (isClean(critique)) {
+      trace.push({ iter, critique, revised: false });
+      break;
+    }
+    value = await opts.revise(value, critique, iter);
+    revised += 1;
+    trace.push({ iter, critique, revised: true });
+  }
+  return { answer: value, iterations: trace.length, revised, trace };
+}
+async function treeOfThoughts(opts) {
+  const breadth = Math.max(1, Math.floor(opts.breadth));
+  const depth = Math.max(1, Math.floor(opts.depth));
+  const path = [];
+  const scored = [];
+  for (let d = 0; d < depth; d++) {
+    let best = null;
+    for (let b = 0; b < breadth; b++) {
+      const cand = await opts.expand(path, b);
+      const s = await opts.score(cand, path);
+      if (!best || s > best.score) best = { thought: cand, score: s };
+    }
+    if (!best) break;
+    path.push(best.thought);
+    scored.push(best);
+  }
+  const answer = opts.synthesize ? await opts.synthesize(path) : path[path.length - 1];
+  return { answer, path: scored };
+}
+async function chainOfVerification(opts) {
+  const draft = await opts.draft();
+  const questions = await opts.planChecks(draft) ?? [];
+  const checks = [];
+  for (const q of questions) {
+    checks.push({ q, a: String(await opts.answerCheck(q)) });
+  }
+  const answer = checks.length ? await opts.revise(draft, checks) : draft;
+  return { answer, checks };
+}
+async function reflexion(opts) {
+  const maxAttempts = Math.max(1, Math.floor(opts.maxAttempts));
+  const reflections = [];
+  let last;
+  for (let i = 0; i < maxAttempts; i++) {
+    last = await opts.attempt(reflections, i);
+    const { success, feedback } = await opts.evaluate(last, i);
+    if (success) return { answer: last, attempts: i + 1, succeeded: true, reflections };
+    if (i < maxAttempts - 1) reflections.push(String(await opts.reflect(last, feedback, i)));
+  }
+  return { answer: last, attempts: maxAttempts, succeeded: false, reflections };
+}
+async function mixtureOfAgents(opts) {
+  const agents = Math.max(1, Math.floor(opts.agents));
+  const layers = Math.max(1, Math.floor(opts.layers));
+  const layerOutputs = [];
+  let current = [];
+  for (let a = 0; a < agents; a++) current.push(String(await opts.propose(a)));
+  layerOutputs.push([...current]);
+  for (let layer = 2; layer <= layers; layer++) {
+    if (!opts.refine) break;
+    const next = [];
+    for (let a = 0; a < agents; a++) {
+      const others = current.filter((_, i) => i !== a);
+      next.push(String(await opts.refine(a, others, layer)));
+    }
+    current = next;
+    layerOutputs.push([...current]);
+  }
+  const answer = String(await opts.aggregate(current));
+  return { answer, layerOutputs };
+}
+var mean = (xs) => xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+var round = (x) => Math.round(x * 1e3) / 1e3;
+async function measureLift(opts) {
+  const perTask = [];
+  const baseScores = [];
+  const treatScores = [];
+  let wins = 0;
+  for (let i = 0; i < opts.tasks.length; i++) {
+    const task = opts.tasks[i];
+    const bOut = await opts.baseline(task, i);
+    const tOut = await opts.treatment(task, i);
+    const b = await opts.score(task, bOut, i);
+    const t = await opts.score(task, tOut, i);
+    baseScores.push(b);
+    treatScores.push(t);
+    if (t > b) wins += 1;
+    perTask.push({ task, baseline: round(b), treatment: round(t), delta: round(t - b) });
+  }
+  const baselineMean = round(mean(baseScores));
+  const treatmentMean = round(mean(treatScores));
+  return {
+    n: opts.tasks.length,
+    baselineMean,
+    treatmentMean,
+    lift: round(treatmentMean - baselineMean),
+    winRate: opts.tasks.length ? round(wins / opts.tasks.length) : 0,
+    perTask
+  };
+}
+
+// src/index.ts
+var VERSION = "0.3.0";
+
+export { Agent, Council, InMemoryReceiptSink, InMemoryStore, LOCAL_TOOL_NAMES, LOCAL_TOOL_PARAMETERS, MCPClient, MUTATING_LOCAL_TOOLS, Memory, ReceiptEmitter, Runner, Session, VERSION, VerifierKernels, allOf, anyOf, bestOfN, boundWorkingSet, buildLocalToolSchemas, chainOfVerification, collectMcpTools, compactHistory, costUsdAtLeast, defineTool, defineVerifier, fileReceiptSink, httpReceiptSink, measureLift, mixtureOfAgents, reflexion, runImprovementCycle, runUntil, selfConsistency, selfRefine, stepCountIs, theron, theronAdapter, treeOfThoughts, verifiedRatchet, verifierSatisfied };