@vextlabs/theron-agent-sdk 0.3.0

package/dist/patterns/index.js

@@ -0,0 +1,150 @@
+// 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
+  };
+}
+
+export { bestOfN, chainOfVerification, measureLift, mixtureOfAgents, reflexion, selfConsistency, selfRefine, treeOfThoughts };

package/dist/receipts/index.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+// 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;
+}
+
+exports.InMemoryReceiptSink = InMemoryReceiptSink;
+exports.ReceiptEmitter = ReceiptEmitter;
+exports.fileReceiptSink = fileReceiptSink;
+exports.httpReceiptSink = httpReceiptSink;

package/dist/receipts/index.d.cts

@@ -0,0 +1,132 @@
+interface ReceiptInput {
+    /** Stable capability identifier. Examples: "agent.run", "council.deliberate",
+     *  "vext.calendar.list_events", "vext.github.create_pr". Free-form; pick a
+     *  reverse-DNS-ish scheme so receipts cluster by domain. */
+    cap: string;
+    /** Inputs the agent saw. Hashed into the content_hash. */
+    input: unknown;
+    /** Outputs the agent produced. Hashed into the content_hash. */
+    output: unknown;
+    /** Actor — who/what produced this. Free-form: agent name, council name,
+     *  user id, tenant. */
+    actor?: string;
+    /** Optional session id for correlation with a Session log. */
+    session_id?: string;
+    /** Optional tenant id for multi-tenant deployments. */
+    tenant_id?: string;
+    /** Optional metadata. Hashed into content_hash. */
+    metadata?: Record<string, unknown>;
+}
+interface Receipt {
+    /** Schema version. */
+    v: "stoa.receipt.v1";
+    /** ULID-shaped id. */
+    id: string;
+    /** Capability the receipt covers. */
+    cap: string;
+    /** Issuer DID or label. Defaults to "did:web:local". Production users set
+     *  this to their issuer DID (did:web:tryvext.com, did:web:acme.com, ...). */
+    issuer: string;
+    /** Actor — who/what produced this. */
+    actor?: string;
+    /** Unix ms timestamp. */
+    ts: number;
+    /** Session correlation id. */
+    session_id?: string;
+    /** Tenant id. */
+    tenant_id?: string;
+    /** SHA-256 hex of canonical(input + output + metadata). Lets downstream
+     *  systems verify the receipt without seeing the payload. */
+    content_hash: string;
+    /** Inline payload. Implementations MAY null this out before transmission
+     *  if the sink already has the data; the content_hash is the source of
+     *  truth. */
+    payload: {
+        input: unknown;
+        output: unknown;
+        metadata?: Record<string, unknown>;
+    };
+    /** Optional detached signature (base64). Populated by a signer. The SDK
+     *  ships an unsigned receipt by default; plug a signer into the emitter
+     *  to populate this. ES256 over canonical(receipt without `signature`)
+     *  is the canonical scheme. */
+    signature?: string;
+}
+/** A sink receives receipts and persists / forwards them. */
+interface ReceiptSink {
+    name: string;
+    emit(receipt: Receipt): Promise<void>;
+}
+/** A signer turns an unsigned receipt into a signed one. Implementations:
+ *  ES256 (default Stoa scheme), Ed25519, HMAC-SHA256 (for internal flows). */
+interface ReceiptSigner {
+    algorithm: "ES256" | "Ed25519" | "HMAC-SHA256" | string;
+    issuer: string;
+    sign(receipt: Receipt): Promise<string>;
+}
+interface ReceiptEmitterConfig {
+    /** Sinks the emitter writes to. Multiple sinks fan out in parallel. */
+    sinks: ReceiptSink[];
+    /** Optional signer. If provided, every receipt is signed before sink emit. */
+    signer?: ReceiptSigner;
+    /** Default issuer if no signer is configured. Defaults to "did:web:local". */
+    issuer?: string;
+    /** Default actor. Overridable per-emit. */
+    actor?: string;
+    /** Default tenant id. Overridable per-emit. */
+    tenant_id?: string;
+}
+/**
+ * ReceiptEmitter — the main primitive callers use.
+ *
+ * Minimal usage:
+ *   const receipts = new ReceiptEmitter({ sinks: [new InMemoryReceiptSink()] });
+ *   await receipts.emit({
+ *     cap: "agent.run",
+ *     actor: "code-reviewer",
+ *     input: { query: "review PR 42" },
+ *     output: { review: "LGTM with two nits" },
+ *   });
+ *
+ * Wire into a Runner via the runner.on() callback:
+ *   runner.on(async (event) => {
+ *     if (event.type === "agent_output") {
+ *       await receipts.emit({ cap: "agent.run", actor: event.agent,
+ *                             input: { agent: event.agent }, output: event.output });
+ *     }
+ *   });
+ */
+declare class ReceiptEmitter {
+    readonly sinks: ReceiptSink[];
+    readonly signer: ReceiptSigner | undefined;
+    readonly issuer: string;
+    readonly actor: string | undefined;
+    readonly tenant_id: string | undefined;
+    constructor(config: ReceiptEmitterConfig);
+    emit(input: ReceiptInput): Promise<Receipt>;
+}
+/** In-memory sink — for tests + ephemeral inspection. */
+declare class InMemoryReceiptSink implements ReceiptSink {
+    readonly name = "in-memory";
+    private readonly records;
+    emit(receipt: Receipt): Promise<void>;
+    list(): readonly Receipt[];
+    clear(): void;
+}
+/**
+ * JSONL file sink — appends each receipt as a single JSON line to `path`.
+ * Lazily imports `node:fs/promises` so the SDK stays bundleable for non-Node
+ * runtimes (Workers, Deno). Throws on use outside Node.
+ */
+declare function fileReceiptSink(path: string): ReceiptSink;
+/**
+ * HTTP sink — POSTs each receipt to a Stoa-conformant sink URL. The URL must
+ * accept `application/json` and return 2xx on accept.
+ */
+declare function httpReceiptSink(opts: {
+    url: string;
+    token?: string;
+    timeout_ms?: number;
+}): ReceiptSink;
+
+export { InMemoryReceiptSink, type Receipt, ReceiptEmitter, type ReceiptEmitterConfig, type ReceiptInput, type ReceiptSigner, type ReceiptSink, fileReceiptSink, httpReceiptSink };

package/dist/receipts/index.d.ts

@@ -0,0 +1,132 @@
+interface ReceiptInput {
+    /** Stable capability identifier. Examples: "agent.run", "council.deliberate",
+     *  "vext.calendar.list_events", "vext.github.create_pr". Free-form; pick a
+     *  reverse-DNS-ish scheme so receipts cluster by domain. */
+    cap: string;
+    /** Inputs the agent saw. Hashed into the content_hash. */
+    input: unknown;
+    /** Outputs the agent produced. Hashed into the content_hash. */
+    output: unknown;
+    /** Actor — who/what produced this. Free-form: agent name, council name,
+     *  user id, tenant. */
+    actor?: string;
+    /** Optional session id for correlation with a Session log. */
+    session_id?: string;
+    /** Optional tenant id for multi-tenant deployments. */
+    tenant_id?: string;
+    /** Optional metadata. Hashed into content_hash. */
+    metadata?: Record<string, unknown>;
+}
+interface Receipt {
+    /** Schema version. */
+    v: "stoa.receipt.v1";
+    /** ULID-shaped id. */
+    id: string;
+    /** Capability the receipt covers. */
+    cap: string;
+    /** Issuer DID or label. Defaults to "did:web:local". Production users set
+     *  this to their issuer DID (did:web:tryvext.com, did:web:acme.com, ...). */
+    issuer: string;
+    /** Actor — who/what produced this. */
+    actor?: string;
+    /** Unix ms timestamp. */
+    ts: number;
+    /** Session correlation id. */
+    session_id?: string;
+    /** Tenant id. */
+    tenant_id?: string;
+    /** SHA-256 hex of canonical(input + output + metadata). Lets downstream
+     *  systems verify the receipt without seeing the payload. */
+    content_hash: string;
+    /** Inline payload. Implementations MAY null this out before transmission
+     *  if the sink already has the data; the content_hash is the source of
+     *  truth. */
+    payload: {
+        input: unknown;
+        output: unknown;
+        metadata?: Record<string, unknown>;
+    };
+    /** Optional detached signature (base64). Populated by a signer. The SDK
+     *  ships an unsigned receipt by default; plug a signer into the emitter
+     *  to populate this. ES256 over canonical(receipt without `signature`)
+     *  is the canonical scheme. */
+    signature?: string;
+}
+/** A sink receives receipts and persists / forwards them. */
+interface ReceiptSink {
+    name: string;
+    emit(receipt: Receipt): Promise<void>;
+}
+/** A signer turns an unsigned receipt into a signed one. Implementations:
+ *  ES256 (default Stoa scheme), Ed25519, HMAC-SHA256 (for internal flows). */
+interface ReceiptSigner {
+    algorithm: "ES256" | "Ed25519" | "HMAC-SHA256" | string;
+    issuer: string;
+    sign(receipt: Receipt): Promise<string>;
+}
+interface ReceiptEmitterConfig {
+    /** Sinks the emitter writes to. Multiple sinks fan out in parallel. */
+    sinks: ReceiptSink[];
+    /** Optional signer. If provided, every receipt is signed before sink emit. */
+    signer?: ReceiptSigner;
+    /** Default issuer if no signer is configured. Defaults to "did:web:local". */
+    issuer?: string;
+    /** Default actor. Overridable per-emit. */
+    actor?: string;
+    /** Default tenant id. Overridable per-emit. */
+    tenant_id?: string;
+}
+/**
+ * ReceiptEmitter — the main primitive callers use.
+ *
+ * Minimal usage:
+ *   const receipts = new ReceiptEmitter({ sinks: [new InMemoryReceiptSink()] });
+ *   await receipts.emit({
+ *     cap: "agent.run",
+ *     actor: "code-reviewer",
+ *     input: { query: "review PR 42" },
+ *     output: { review: "LGTM with two nits" },
+ *   });
+ *
+ * Wire into a Runner via the runner.on() callback:
+ *   runner.on(async (event) => {
+ *     if (event.type === "agent_output") {
+ *       await receipts.emit({ cap: "agent.run", actor: event.agent,
+ *                             input: { agent: event.agent }, output: event.output });
+ *     }
+ *   });
+ */
+declare class ReceiptEmitter {
+    readonly sinks: ReceiptSink[];
+    readonly signer: ReceiptSigner | undefined;
+    readonly issuer: string;
+    readonly actor: string | undefined;
+    readonly tenant_id: string | undefined;
+    constructor(config: ReceiptEmitterConfig);
+    emit(input: ReceiptInput): Promise<Receipt>;
+}
+/** In-memory sink — for tests + ephemeral inspection. */
+declare class InMemoryReceiptSink implements ReceiptSink {
+    readonly name = "in-memory";
+    private readonly records;
+    emit(receipt: Receipt): Promise<void>;
+    list(): readonly Receipt[];
+    clear(): void;
+}
+/**
+ * JSONL file sink — appends each receipt as a single JSON line to `path`.
+ * Lazily imports `node:fs/promises` so the SDK stays bundleable for non-Node
+ * runtimes (Workers, Deno). Throws on use outside Node.
+ */
+declare function fileReceiptSink(path: string): ReceiptSink;
+/**
+ * HTTP sink — POSTs each receipt to a Stoa-conformant sink URL. The URL must
+ * accept `application/json` and return 2xx on accept.
+ */
+declare function httpReceiptSink(opts: {
+    url: string;
+    token?: string;
+    timeout_ms?: number;
+}): ReceiptSink;
+
+export { InMemoryReceiptSink, type Receipt, ReceiptEmitter, type ReceiptEmitterConfig, type ReceiptInput, type ReceiptSigner, type ReceiptSink, fileReceiptSink, httpReceiptSink };