@codespar/cli 0.13.0 → 0.14.0

package/templates/collections-agent/packages/agent-core/src/escalate.ts

@@ -0,0 +1,85 @@
+/**
+ * Section 4.4: `escalate_above` only tightens. Each trigger sends a
+ * `mandate` execution to `awaiting_approval`; none of them raises a cap or
+ * adds a payee. The first trigger that fires is the one the artifact records.
+ */
+import type { Guardrails } from "./guardrails.js";
+import type { EscalateAbove } from "./manifest.js";
+import type { EscalationTrigger, ExecutionItem } from "./types.js";
+
+export interface EscalationContext {
+  now: Date;
+  timezone: string;
+  /** Payees this agent has already settled a payment to, under this mandate. */
+  knownPayees: ReadonlySet<string>;
+  /** Minor units already executed (settled or in flight) per payee inside the velocity window. */
+  recentByPayee: ReadonlyMap<string, number>;
+}
+
+export interface Escalation {
+  trigger: EscalationTrigger;
+  detail: string;
+}
+
+export function evaluateEscalation(
+  rule: EscalateAbove | undefined,
+  guardrails: Guardrails,
+  items: readonly ExecutionItem[],
+  ctx: EscalationContext,
+): Escalation | undefined {
+  if (!rule) return undefined;
+
+  if (rule.amount !== undefined) {
+    const total = items.reduce((sum, i) => sum + i.amount, 0);
+    if (total > rule.amount) {
+      return { trigger: "amount", detail: `total ${total} is above the escalation threshold ${rule.amount}` };
+    }
+    // Fractioning (section 9): the same payee, several parts inside the window, adds up.
+    if (guardrails.velocity) {
+      const perPayee = new Map<string, number>();
+      for (const item of items) perPayee.set(item.payee, (perPayee.get(item.payee) ?? 0) + item.amount);
+      for (const [payee, amount] of perPayee) {
+        const recent = ctx.recentByPayee.get(payee) ?? 0;
+        if (recent + amount > rule.amount) {
+          return {
+            trigger: "amount",
+            detail: `payments to ${payee} inside the last ${guardrails.velocity.window_hours}h add up to ${recent + amount}, above the escalation threshold ${rule.amount}`,
+          };
+        }
+      }
+    }
+  }
+
+  if (rule.new_beneficiary) {
+    const fresh = items.find((i) => !ctx.knownPayees.has(i.payee));
+    if (fresh) {
+      return { trigger: "new_beneficiary", detail: `first payment to ${fresh.beneficiary} (${fresh.payee}) under this mandate` };
+    }
+  }
+
+  if (rule.outside_hours && isOutsideHours(rule.outside_hours, ctx.now, ctx.timezone)) {
+    return { trigger: "outside_hours", detail: `requested at ${localClock(ctx.now, ctx.timezone)}, inside the ${rule.outside_hours} window` };
+  }
+
+  return undefined;
+}
+
+export function localClock(now: Date, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-GB", { timeZone: timezone, hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).formatToParts(now);
+  const hour = parts.find((p) => p.type === "hour")?.value ?? "00";
+  const minute = parts.find((p) => p.type === "minute")?.value ?? "00";
+  return `${hour}:${minute}`;
+}
+
+/** `"22:00-07:00"` is the CLOSED window: inside it, the trigger fires. Crosses midnight when start > end. */
+export function isOutsideHours(window: string, now: Date, timezone: string): boolean {
+  const [start, end] = window.split("-") as [string, string];
+  const minutes = (hhmm: string): number => {
+    const [h, m] = hhmm.split(":").map(Number) as [number, number];
+    return h * 60 + m;
+  };
+  const current = minutes(localClock(now, timezone));
+  const s = minutes(start);
+  const e = minutes(end);
+  return s <= e ? current >= s && current < e : current >= s || current < e;
+}

package/templates/collections-agent/packages/agent-core/src/events.ts

@@ -0,0 +1,40 @@
+/**
+ * The events the CodeSpar API publishes, as an agent may declare them under
+ * `events:` in `agent.yaml`. The list is the one place the kits keep it;
+ * `npm run check` refuses a manifest entry outside it.
+ *
+ * Source: codespar-enterprise `packages/api/src` (the publishers behind
+ * `/v1/triggers`), measured 2026-09-23. Update it against that tree, never
+ * from memory.
+ */
+export const PUBLISHED_EVENTS = [
+  "commerce.payment.succeeded",
+  "commerce.payment.failed",
+  "commerce.payment.pending",
+  "commerce.payment.refunded",
+  "commerce.payment.updated",
+  "commerce.pix_out.succeeded",
+  "commerce.pix_out.failed",
+  "commerce.charge.created",
+  "commerce.charge.paid",
+  "commerce.charge.expired",
+  "commerce.charge.cancelled",
+  "commerce.mandate.granted",
+  "commerce.mandate.paused",
+  "commerce.mandate.resumed",
+  "commerce.mandate.revoked",
+] as const;
+
+export type PublishedEvent = (typeof PUBLISHED_EVENTS)[number];
+
+/** The rail's answer to one attempt, as the core records it locally and as the API publishes it. */
+export const PAYMENT_SUCCEEDED: PublishedEvent = "commerce.payment.succeeded";
+export const PAYMENT_FAILED: PublishedEvent = "commerce.payment.failed";
+/** The payer's answer to a receivable, as the API publishes it: paid settles, expired and cancelled fail. */
+export const CHARGE_PAID: PublishedEvent = "commerce.charge.paid";
+export const CHARGE_EXPIRED: PublishedEvent = "commerce.charge.expired";
+export const CHARGE_CANCELLED: PublishedEvent = "commerce.charge.cancelled";
+
+export function isPublishedEvent(name: string): name is PublishedEvent {
+  return (PUBLISHED_EVENTS as readonly string[]).includes(name);
+}

package/templates/collections-agent/packages/agent-core/src/guardrails.ts

@@ -0,0 +1,45 @@
+/**
+ * `guardrails.json`: what the agent applies on its own, before the mandate.
+ * Everything here can only tighten the mandate; nothing here widens it.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { EscalateAboveSchema } from "./manifest.js";
+
+export const GuardrailsSchema = z
+  .object({
+    approval: z.enum(["human", "mandate"]),
+    /** Must equal the manifest's `escalate_above`; `npm run check` compares them. */
+    escalate_above: EscalateAboveSchema.optional(),
+    /** Section 9, fractioning: the window over which amounts to one payee add up towards `escalate_above.amount`. */
+    velocity: z
+      .object({
+        window_hours: z.number().int().positive(),
+        /** Optional hard ceiling on the number of executions to one payee in the window. */
+        max_per_payee: z.number().int().positive().optional(),
+      })
+      .strict()
+      .optional(),
+    /** When an `outside_hours` trigger fires: ask a human now, or refuse and let the person retry inside the window. */
+    outside_hours_action: z.enum(["escalate", "refuse"]).default("escalate"),
+    /** When the model's stated total differs from the core's: execute the core's number, or refuse. Never the model's. */
+    model_total_mismatch: z.enum(["use_core", "refuse"]).default("use_core"),
+    /** Minutes an approval artifact stays valid. */
+    approval_ttl_minutes: z.number().int().positive().default(15),
+    /** IANA zone the `outside_hours` window is read in. */
+    timezone: z.string().default("America/Sao_Paulo"),
+    /**
+     * The agent-specific envelope the kit's own deterministic policy reads
+     * (a collections agent: discount ceiling, instalments, due-date window).
+     * The core carries it and runs the kit's `policyExtension` at every gate;
+     * it does not interpret the keys.
+     */
+    envelope: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+
+export type Guardrails = z.infer<typeof GuardrailsSchema>;
+
+export function loadGuardrails(path: string): Guardrails {
+  return GuardrailsSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}

package/templates/collections-agent/packages/agent-core/src/hash.ts

@@ -0,0 +1,49 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import type { ExecutionItem } from "./types.js";
+
+/** JSON with keys sorted at every level, so the same value always hashes the same. */
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const v = (value as Record<string, unknown>)[key];
+      if (v !== undefined) out[key] = sortKeys(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function sha256Hex(input: string | Buffer): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * Section 4.2: the hash of the canonical list. Only the fields that decide
+ * where money goes take part: payee, amount, currency, and the due date of a
+ * receivable when it has one. Aliases, names and descriptions are
+ * presentation and may differ without changing the hash.
+ */
+export function itemsHash(items: readonly ExecutionItem[]): string {
+  const canonical = items.map((item) => ({
+    payee: item.payee,
+    amount: item.amount,
+    currency: item.currency,
+    ...(item.due_date ? { due_date: item.due_date } : {}),
+  }));
+  return `sha256:${sha256Hex(canonicalJson(canonical))}`;
+}
+
+export function hmacSha256Hex(key: Buffer, payload: string): string {
+  return createHmac("sha256", key).update(payload).digest("hex");
+}
+
+export function hexEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+}

package/templates/collections-agent/packages/agent-core/src/ids.ts

@@ -0,0 +1,10 @@
+import { randomBytes } from "node:crypto";
+
+export function newId(prefix: string, bytes = 8): string {
+  return `${prefix}_${randomBytes(bytes).toString("hex")}`;
+}
+
+export function newRunId(label?: string): string {
+  const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  return label ? `run_${stamp}_${label}_${randomBytes(3).toString("hex")}` : `run_${stamp}_${randomBytes(3).toString("hex")}`;
+}

package/templates/collections-agent/packages/agent-core/src/index.ts

@@ -0,0 +1,29 @@
+export * from "./types.js";
+export * from "./state-machine.js";
+export * from "./hash.js";
+export * from "./ids.js";
+export * from "./approval.js";
+export * from "./manifest.js";
+export * from "./guardrails.js";
+export * from "./mandate.js";
+export * from "./escalate.js";
+export * from "./secrets.js";
+export * from "./revocation.js";
+export * from "./rail.js";
+export * from "./tools.js";
+export * from "./bundle.js";
+export * from "./engine.js";
+export * from "./agent.js";
+export * from "./check.js";
+export * from "./events.js";
+export * from "./state/store.js";
+export * from "./stubs/mandate-status.js";
+export * from "./stubs/rail.js";
+export * from "./stubs/charge-rail.js";
+export * from "./api/client.js";
+export * from "./api/rail.js";
+export * from "./api/mandate-status.js";
+export * from "./api/charge-rail.js";
+export * from "./api/sandbox-payer.js";
+export * from "./providers/types.js";
+export * from "./providers/replay.js";

package/templates/collections-agent/packages/agent-core/src/mandate.ts

@@ -0,0 +1,100 @@
+/**
+ * The local view of a consumer mandate: the fields the core checks before
+ * anything reaches the API, plus the named payees the kit presents to the
+ * person. The API re-verifies all of it server-side on every spend; the
+ * local checks exist so a refusal is readable and happens before any call.
+ */
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+
+export const BeneficiarySchema = z
+  .object({
+    /** Short handle the model may use: `escola`, `mercado`. */
+    alias: z.string().regex(/^[a-z0-9_-]+$/),
+    name: z.string().min(1),
+    /** The pinned payee key. Must appear in `merchant_allowlist`. */
+    payee: z.string().min(1),
+  })
+  .strict();
+
+export const MandateSchema = z
+  .object({
+    id: z.string().min(1),
+    /** Local version counter for the approval artifact; bumps when the mandate is re-signed. */
+    version: z.number().int().positive(),
+    consumer_id: z.string().min(1),
+    agent_id: z.string().min(1),
+    purpose: z.string().min(1),
+    currency: z.string().min(1),
+    /** Section 4.3: total over the window, in minor units. */
+    cap_minor: z.number().int().positive(),
+    per_tx_cap_minor: z.number().int().positive(),
+    periodic_cap: z.object({ window: z.enum(["day", "month"]), cap_minor: z.number().int().positive() }).strict().optional(),
+    /** `document` is the receivable side: the list names the debtors (CPF/CNPJ) with an open agreement, and a charge may only be issued against one of them. */
+    merchant_pin_kind: z.enum(["pix-key", "merchant-id", "mcc", "document"]),
+    /** Concrete keys. The kit never treats `"*"` as authorizing a payee. */
+    merchant_allowlist: z.array(z.string().min(1)).nonempty(),
+    beneficiaries: z.array(BeneficiarySchema),
+    status: z.enum(["active", "paused", "revoked", "expired"]),
+    /** ISO 8601. */
+    expires_at: z.string().datetime(),
+    /** The signature the API returned at consent, when the mandate is a real one. Never required locally. */
+    signature: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+    /** The canonical mandate the API returned, presented on `/v1/consumer-payments/execute`. */
+    canonical: z.record(z.string(), z.unknown()).optional(),
+    /** Where this mandate came from. */
+    source: z.enum(["example", "consent"]).default("example"),
+  })
+  .strict()
+  .superRefine((m, ctx) => {
+    if (m.per_tx_cap_minor > m.cap_minor) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["per_tx_cap_minor"], message: "per_tx_cap_minor cannot exceed cap_minor" });
+    }
+    // The API's own rule (`periodic_cap_never_binds`): the window cap must sit below the lifetime cap, or it is a limit the consumer was shown and never enforced.
+    if (m.periodic_cap && m.periodic_cap.cap_minor >= m.cap_minor) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["periodic_cap", "cap_minor"], message: "periodic_cap.cap_minor must be below cap_minor (the lifetime cap)" });
+    }
+    for (const [i, b] of m.beneficiaries.entries()) {
+      if (!m.merchant_allowlist.includes(b.payee)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["beneficiaries", i, "payee"], message: `payee ${b.payee} is not in merchant_allowlist` });
+      }
+    }
+  });
+
+export type Mandate = z.infer<typeof MandateSchema>;
+export type Beneficiary = z.infer<typeof BeneficiarySchema>;
+
+export function loadMandate(path: string): Mandate {
+  return MandateSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+/** The window the monthly cap is counted over. */
+export function windowStart(mandate: Mandate, now: Date): Date {
+  const window = mandate.periodic_cap?.window ?? "month";
+  const d = new Date(now);
+  if (window === "day") {
+    d.setUTCHours(0, 0, 0, 0);
+  } else {
+    d.setUTCDate(1);
+    d.setUTCHours(0, 0, 0, 0);
+  }
+  return d;
+}
+
+export function windowCap(mandate: Mandate): number {
+  return mandate.periodic_cap?.cap_minor ?? mandate.cap_minor;
+}
+
+/** A payee is allowed only when the SIGNED list names it. A wildcard names nobody here. */
+export function payeeAllowed(mandate: Mandate, payee: string): boolean {
+  return mandate.merchant_allowlist.some((entry) => entry !== "*" && entry === payee);
+}
+
+export function resolveBeneficiary(mandate: Mandate, aliasOrPayee: string): Beneficiary | undefined {
+  const needle = aliasOrPayee.trim().toLowerCase();
+  return mandate.beneficiaries.find((b) => b.alias === needle || b.payee.toLowerCase() === needle || b.name.toLowerCase() === needle);
+}
+
+export function mandateExpired(mandate: Mandate, now: Date): boolean {
+  return new Date(mandate.expires_at).getTime() <= now.getTime();
+}

package/templates/collections-agent/packages/agent-core/src/manifest.ts

@@ -0,0 +1,76 @@
+/**
+ * Section 4.3: the `agent.yaml` manifest, `schema: 1`.
+ *
+ * The schema promises stability from now on: a field is removed or changes
+ * meaning only under a new `schema` number.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+const PINNED_PACKAGE = /^@codespar\/(mcp|cli)@\d+\.\d+\.\d+$/;
+const HOURS_WINDOW = /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/;
+
+export const MaturitySchema = z.enum(["live", "sandbox", "blocked"]);
+
+export const EscalateAboveSchema = z
+  .object({
+    /** Minor units. A payment above this, still inside the mandate cap, asks a human. */
+    amount: z.number().int().positive().optional(),
+    /** The first payment to a payee that is already on the allowlist asks a human. */
+    new_beneficiary: z.boolean().optional(),
+    /** "HH:MM-HH:MM", may cross midnight. Execution requested inside it asks a human. */
+    outside_hours: z.string().regex(HOURS_WINDOW, 'expected "HH:MM-HH:MM"').optional(),
+  })
+  .strict();
+
+export const ManifestSchema = z
+  .object({
+    schema: z.literal(1),
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    version: z.string().regex(/^\d+\.\d+\.\d+$/),
+    approval: z.array(z.enum(["human", "mandate"])).nonempty(),
+    default_approval: z.enum(["human", "mandate"]),
+    escalate_above: EscalateAboveSchema.optional(),
+    mcp: z.string().regex(PINNED_PACKAGE, "mcp must pin an exact version, e.g. @codespar/mcp@0.5.8"),
+    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.13.0"),
+    tools: z.string(),
+    guardrails: z.string(),
+    mandate_schema: z.string(),
+    events: z.array(z.string().regex(/^commerce\.[a-z_.]+$/)),
+    channels: z.array(z.enum(["terminal", "whatsapp"])).nonempty(),
+    maturity: z.record(z.string(), MaturitySchema),
+    scenarios: z.string(),
+    evals: z.string(),
+    agents_md: z.string(),
+  })
+  .strict()
+  .superRefine((m, ctx) => {
+    if (!m.approval.includes(m.default_approval)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["default_approval"], message: "default_approval must be one of approval" });
+    }
+  });
+
+export type Manifest = z.infer<typeof ManifestSchema>;
+export type EscalateAbove = z.infer<typeof EscalateAboveSchema>;
+
+export interface LoadedManifest {
+  manifest: Manifest;
+  /** Absolute path of the manifest file. */
+  path: string;
+  /** Directory the relative paths in the manifest resolve against. */
+  dir: string;
+  resolvePath(relative: string): string;
+}
+
+export function parseManifest(text: string): Manifest {
+  return ManifestSchema.parse(parseYaml(text));
+}
+
+export function loadManifest(path: string): LoadedManifest {
+  const absolute = resolve(path);
+  const manifest = parseManifest(readFileSync(absolute, "utf8"));
+  const dir = dirname(absolute);
+  return { manifest, path: absolute, dir, resolvePath: (relative) => resolve(dir, relative) };
+}

package/templates/collections-agent/packages/agent-core/src/providers/anthropic.ts

@@ -0,0 +1,76 @@
+/**
+ * The reference harness: a tool-use loop on `@anthropic-ai/sdk`. It only
+ * turns messages into a request and the response into tool calls or a
+ * reply; it never decides anything about money.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import type { ContentBlockParam, MessageParam, Tool as AnthropicTool } from "@anthropic-ai/sdk/resources/messages";
+import type { AgentRuntime, ConversationMessage, Reply, ToolCall, ToolSpec, Turn } from "./types.js";
+
+export const DEFAULT_MODEL = "claude-sonnet-5";
+
+export interface AnthropicRuntimeOptions {
+  apiKey?: string | undefined;
+  model?: string;
+  maxTokens?: number;
+}
+
+export class AnthropicRuntime implements AgentRuntime {
+  readonly name = "anthropic";
+  private readonly client: Anthropic;
+  private readonly model: string;
+  private readonly maxTokens: number;
+
+  constructor(options: AnthropicRuntimeOptions = {}) {
+    const apiKey = options.apiKey ?? process.env["ANTHROPIC_API_KEY"];
+    if (!apiKey) throw new Error("ANTHROPIC_API_KEY is not set; use the replay provider for runs without a model");
+    this.client = new Anthropic({ apiKey });
+    this.model = options.model ?? process.env["ANTHROPIC_MODEL"] ?? DEFAULT_MODEL;
+    this.maxTokens = options.maxTokens ?? 1024;
+  }
+
+  async step(input: Turn, tools: ToolSpec[]): Promise<ToolCall[] | Reply> {
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: this.maxTokens,
+      system: input.system,
+      tools: tools.map(toAnthropicTool),
+      messages: toAnthropicMessages(input.messages),
+    });
+    const calls: ToolCall[] = [];
+    const text: string[] = [];
+    for (const block of response.content) {
+      if (block.type === "tool_use") calls.push({ id: block.id, name: block.name, input: (block.input ?? {}) as Record<string, unknown> });
+      else if (block.type === "text") text.push(block.text);
+    }
+    if (calls.length > 0) return calls;
+    return { text: text.join("\n").trim() };
+  }
+}
+
+function toAnthropicTool(tool: ToolSpec): AnthropicTool {
+  return { name: tool.name, description: tool.description, input_schema: tool.input_schema as AnthropicTool["input_schema"] };
+}
+
+function toAnthropicMessages(messages: ConversationMessage[]): MessageParam[] {
+  const out: MessageParam[] = [];
+  for (const m of messages) {
+    if (m.role === "user") {
+      out.push({ role: "user", content: m.content });
+    } else if (m.role === "assistant") {
+      const content: ContentBlockParam[] = [];
+      if (m.content) content.push({ type: "text", text: m.content });
+      for (const call of m.tool_calls ?? []) content.push({ type: "tool_use", id: call.id, name: call.name, input: call.input });
+      out.push({ role: "assistant", content });
+    } else {
+      const last = out[out.length - 1];
+      const block = { type: "tool_result" as const, tool_use_id: m.tool_call_id, content: m.content, ...(m.is_error ? { is_error: true } : {}) };
+      if (last && last.role === "user" && Array.isArray(last.content) && last.content.every((b) => (b as { type: string }).type === "tool_result")) {
+        (last.content as Array<typeof block>).push(block);
+      } else {
+        out.push({ role: "user", content: [block] });
+      }
+    }
+  }
+  return out;
+}

package/templates/collections-agent/packages/agent-core/src/providers/replay.ts

@@ -0,0 +1,63 @@
+/**
+ * The deterministic provider. It reads the `assistant_step` lines of a
+ * recorded transcript and answers them in order, so the CI, the scenarios
+ * and `npm run rerun` run with no model and no network. The recorded lines
+ * are the MODEL's outputs only; everything the core decided is recomputed
+ * live, which is what makes a rerun a test rather than a printout.
+ */
+import { readFileSync } from "node:fs";
+import type { AgentRuntime, Reply, ToolCall, ToolSpec, Turn } from "./types.js";
+
+export interface RecordedStep {
+  kind: "assistant_step";
+  tool_calls?: ToolCall[];
+  reply?: string;
+}
+
+export class ReplayExhaustedError extends Error {
+  constructor(consumed: number) {
+    super(`replay transcript exhausted after ${consumed} step(s); the run asked the model more than the recording holds`);
+    this.name = "ReplayExhaustedError";
+  }
+}
+
+export class ReplayRuntime implements AgentRuntime {
+  readonly name = "replay";
+  private cursor = 0;
+
+  constructor(private readonly steps: RecordedStep[]) {}
+
+  static fromFile(path: string): ReplayRuntime {
+    return new ReplayRuntime(parseTranscript(readFileSync(path, "utf8")));
+  }
+
+  static fromLines(lines: Array<Record<string, unknown>>): ReplayRuntime {
+    return new ReplayRuntime(lines.filter((l) => l["kind"] === "assistant_step") as unknown as RecordedStep[]);
+  }
+
+  get consumed(): number {
+    return this.cursor;
+  }
+
+  get remaining(): number {
+    return this.steps.length - this.cursor;
+  }
+
+  async step(_input: Turn, _tools: ToolSpec[]): Promise<ToolCall[] | Reply> {
+    const next = this.steps[this.cursor];
+    if (!next) throw new ReplayExhaustedError(this.cursor);
+    this.cursor += 1;
+    if (next.tool_calls && next.tool_calls.length > 0) {
+      return next.tool_calls.map((c, i) => ({ id: c.id ?? `tc_${this.cursor}_${i}`, name: c.name, input: c.input ?? {} }));
+    }
+    return { text: next.reply ?? "" };
+  }
+}
+
+export function parseTranscript(text: string): RecordedStep[] {
+  return text
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l) as Record<string, unknown>)
+    .filter((l) => l["kind"] === "assistant_step") as unknown as RecordedStep[];
+}

package/templates/collections-agent/packages/agent-core/src/providers/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Section 13: the contract of the harness file. Policy stays outside the
+ * provider: the state machine, the mandate, the guardrails and `tools.json`
+ * are the core's. Changing the model changes nothing about what can be paid.
+ */
+export interface ToolSpec {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface Reply {
+  text: string;
+}
+
+export type ConversationMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string; tool_calls?: ToolCall[] }
+  | { role: "tool"; tool_call_id: string; name: string; content: string; is_error?: boolean };
+
+export interface Turn {
+  system: string;
+  messages: ConversationMessage[];
+}
+
+export interface AgentRuntime {
+  readonly name: string;
+  step(input: Turn, tools: ToolSpec[]): Promise<ToolCall[] | Reply>;
+}
+
+export function isReply(out: ToolCall[] | Reply): out is Reply {
+  return !Array.isArray(out);
+}