@codespar/cli 0.14.1 → 0.16.0

package/templates/hello-agent/packages/agent-runtime/test/whatsapp-rules.test.ts

@@ -0,0 +1,174 @@
+/**
+ * The rules of collecting over a conversation, tried and refused.
+ *
+ * Every case here is an ATTEMPT: the message is handed to the channel the way
+ * the runner hands it one, and what is asserted is that nothing left the
+ * process. The backend under the channel is a recorder, so "refused" is not a
+ * claim about a return value — it is the recorder having seen nothing.
+ *
+ * The last case is the one that matters most: the same attempts through a
+ * DIFFERENT backend. The rules live above the backend, so choosing one cannot
+ * be a way around them.
+ */
+import { describe, expect, it } from "vitest";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { checkOutbound } from "../src/channels/rules.js";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../src/channels/types.js";
+
+/** A backend that carries nothing and remembers everything it was asked to carry. */
+class Recorder implements ChannelBackend {
+  readonly delivered: Array<{ to: string; body: OutboundBody }> = [];
+  constructor(
+    readonly name = "recorder",
+    readonly live = false,
+    private readonly inbox: InboundMessage[] = [],
+  ) {}
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return this.inbox.shift();
+  }
+  async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push({ to, body });
+    return { id: `rec_${this.delivered.length}`, state: "sent" };
+  }
+  async close(): Promise<void> {}
+}
+
+const CONTACT = "+5511987654321";
+const INSIDE = new Date("2026-09-23T14:00:00-03:00");
+const OUTSIDE = new Date("2026-09-23T22:30:00-03:00");
+const HOURS = { window: "08:00-20:00", timezone: "America/Sao_Paulo" };
+
+function channelAt(now: Date, backend = new Recorder(), openSession = true) {
+  const channel = new WhatsAppChannel({
+    backend,
+    conversation: { contact: CONTACT, subject: "acordo-1042" },
+    now: () => now,
+    hours: HOURS,
+    knownSubjects: ["acordo-1042", "acordo-1077", "acordo-1103"],
+    templates: [{ name: "cobranca_lembrete", language: "pt_BR", description: "a reminder", body: "Oi {{1}}, sobre o acordo." }],
+  });
+  // A session is open because the person wrote; the window is WhatsApp's rule, not ours, and has its own test below.
+  if (openSession) {
+    (channel as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(now.getTime() / 1000));
+  }
+  return { channel, backend };
+}
+
+describe("the collection rules, tried through the channel", () => {
+  it("sends inside the collection hours", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const sent = await channel.say("Oi, Joana! Sobre o pedido #1042.");
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses everything outside the collection hours, and the backend never sees it", async () => {
+    const { channel, backend } = channelAt(OUTSIDE);
+    const sent = await channel.say("Oi, Joana! Sobre o pedido #1042.");
+    expect(sent.refused?.rule).toBe("collection_hours");
+    expect(sent.state).toBe("failed");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("refuses a message to any contact but the one the conversation is bound to", () => {
+    const refusal = checkOutbound("+5511900000000", { kind: "text", text: "sobre a sua divida" }, {
+      conversation: { contact: CONTACT, subject: "acordo-1042" },
+      hours: HOURS,
+      now: () => INSIDE,
+    });
+    expect(refusal?.rule).toBe("bound_contact");
+  });
+
+  it("refuses a message that names another debtor's agreement", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const sent = await channel.say("O acordo-1077 do Carlos tambem esta em aberto, voces podem combinar.");
+    expect(sent.refused?.rule).toBe("subject_scope");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("refuses a CPF or a CNPJ in a message, formatted or bare", async () => {
+    for (const text of ["confirma o CPF 111.444.777-35?", "o CPF do titular e 11144477735", "CNPJ 12.345.678/0001-95", "CNPJ 12345678000195"]) {
+      const { channel, backend } = channelAt(INSIDE);
+      const sent = await channel.say(text);
+      expect(sent.refused?.rule, text).toBe("no_document");
+      expect(backend.delivered).toHaveLength(0);
+    }
+  });
+
+  it("does NOT read a Pix copy-and-paste or a boleto line as a document", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const brcode = "00020126580014br.gov.bcb.pix0136stub-chg_abc5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB";
+    const bankLine = "78517596684364082005302425802108566187285620000";
+    expect((await channel.send({ kind: "instrument", instrument: "pix_copy_paste", value: brcode })).refused).toBeUndefined();
+    expect((await channel.send({ kind: "instrument", instrument: "boleto_bank_line", value: bankLine })).refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(2);
+  });
+
+  it("refuses an empty message", async () => {
+    const { channel } = channelAt(INSIDE);
+    expect((await channel.say("   ")).refused?.rule).toBe("empty_message");
+  });
+
+  it("masks the contact everywhere it is written down", async () => {
+    const { channel } = channelAt(INSIDE);
+    await channel.say("Oi!");
+    for (const line of channel.log()) {
+      expect(line.contact).not.toContain("987654321");
+      expect(line.contact).toContain("****");
+    }
+  });
+
+  it("applies the same rules through a different backend: a backend is not a way around one", async () => {
+    const other = new Recorder("another-backend", true);
+    const { channel, backend } = channelAt(OUTSIDE, other);
+    expect((await channel.say("boa noite, sobre a sua divida")).refused?.rule).toBe("collection_hours");
+    expect((await channelAt(INSIDE, new Recorder("another-backend", true)).channel.say("CPF 11144477735")).refused?.rule).toBe("no_document");
+    expect(backend.delivered).toHaveLength(0);
+  });
+});
+
+describe("WhatsApp's own rule: the 24-hour session window", () => {
+  it("carries a free-form message while the window is open", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    expect((await channel.say("Oi, Joana!")).refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses a free-form message once the window has shut, and says what would carry", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(sent.refused?.detail).toContain("template");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("carries a declared template with the window shut", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses a template the agent never declared: Meta only delivers the ones it approved", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "nao_registrado", language: "pt_BR", variables: [] });
+    expect(sent.refused?.rule).toBe("template_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("holds a template to the house rules too: an approved template is not a way past the hours", async () => {
+    const { channel, backend } = channelAt(OUTSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(sent.refused?.rule).toBe("collection_hours");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("reopens the window when the person writes again", async () => {
+    const backend = new Recorder("recorder", false, [{ id: "in_1", from: CONTACT, text: "oi", timestamp: Math.floor(INSIDE.getTime() / 1000) }]);
+    const { channel } = channelAt(INSIDE, backend, false);
+    expect((await channel.say("antes")).refused?.rule).toBe("session_window_closed");
+    await channel.next();
+    expect((await channel.say("depois")).refused).toBeUndefined();
+  });
+});

package/templates/hello-agent/packages/agent-runtime/test/whatsapp-session.test.ts

@@ -0,0 +1,135 @@
+/**
+ * The 24-hour window, read back and reasoned about.
+ *
+ * Two things are under test and they are the two halves of issue #25. A
+ * conversation that a later process comes back to has to know where its
+ * window stood, and the only honest source for that is the PROVIDER's
+ * timestamp in the record — not the run's own clock, which belongs to a
+ * machine WhatsApp never consulted. And a message that may only go as a
+ * template has to be held to what the agent actually declared, because a
+ * template Meta never approved is not a message, it is a 4xx.
+ *
+ * None of it needs the emulator: every refusal here happens above the
+ * backend, which is the whole claim `channels/` makes.
+ */
+import { describe, expect, it } from "vitest";
+import { templateArity, type WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { SessionWindow, sessionStateFromChannelLog, SESSION_WINDOW_SECONDS } from "../src/channels/whatsapp/session.js";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../src/channels/types.js";
+
+class Recorder implements ChannelBackend {
+  readonly name = "recorder";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return undefined;
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `rec_${this.delivered.length}`, state: "sent" };
+  }
+  async close(): Promise<void> {}
+}
+
+const CONTACT = "+5511987654321";
+const TUESDAY = new Date("2026-09-23T14:00:00-03:00");
+const FRIDAY = new Date("2026-09-25T14:00:00-03:00");
+const QUITADO: WhatsAppTemplate = { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Recebemos o pagamento do {{1}}." };
+
+function channel(now: Date, lastInboundAt?: number, backend = new Recorder()) {
+  const c = new WhatsAppChannel({
+    backend,
+    conversation: { contact: CONTACT, subject: "acordo-1042" },
+    now: () => now,
+    templates: [QUITADO],
+    ...(lastInboundAt !== undefined ? { session: { lastInboundAt } } : {}),
+  });
+  return { channel: c, backend };
+}
+
+describe("where the window stood, read back from the record", () => {
+  it("takes the provider's timestamp and never the line's own `at`", () => {
+    const state = sessionStateFromChannelLog([
+      { direction: "in", at: "2020-01-01T00:00:00.000Z", provider_timestamp: 1790182801 },
+      { direction: "out", at: "2026-09-23T17:00:10.000Z" },
+      { direction: "in", at: "2020-01-01T00:00:00.000Z", provider_timestamp: 1790182821 },
+    ]);
+    expect(state.lastInboundAt).toBe(1790182821);
+  });
+
+  it("yields nothing from a log whose inbound lines carry no provider timestamp, and the window then reads as shut", () => {
+    // A bundle written before the timestamp was recorded. Shut is the safe
+    // direction: a template is deliverable in both halves of the rule.
+    const state = sessionStateFromChannelLog([{ direction: "in", at: "2026-09-23T17:00:00.000Z", text: "oi" }]);
+    expect(state.lastInboundAt).toBeUndefined();
+    expect(new SessionWindow([], state).open(TUESDAY)).toBe(false);
+  });
+
+  it("ignores outbound lines: the window is opened by the PERSON writing, not by us", () => {
+    expect(sessionStateFromChannelLog([{ direction: "out", provider_timestamp: 1790182801 }]).lastInboundAt).toBeUndefined();
+  });
+});
+
+describe("a conversation a later process comes back to", () => {
+  it("writes freely when the restored window is still open", async () => {
+    const { channel: c, backend } = channel(TUESDAY, Math.floor(TUESDAY.getTime() / 1000) - 3600);
+    expect(c.sessionOpen).toBe(true);
+    expect(c.sessionRemainingSeconds).toBe(SESSION_WINDOW_SECONDS - 3600);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses free text once the restored window has shut, which is the case the poll exists for", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    expect(c.sessionOpen).toBe(false);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("carries the declared template in the same breath, with the language the registry holds", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const declared = c.declaredTemplate("acordo_quitado");
+    expect(declared?.language).toBe("pt_BR");
+    const sent = await c.send({ kind: "template", template: declared!.name, language: declared!.language, variables: ["acordo-1042"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toEqual([{ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"] }]);
+  });
+
+  it("reads as shut when nothing restored it: a process with no record of the conversation assumes the worst", () => {
+    expect(channel(TUESDAY).channel.sessionOpen).toBe(false);
+  });
+});
+
+describe("the local registry refuses what Meta would refuse", () => {
+  it("a name the agent never declared", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "nao_registrado", language: "pt_BR", variables: [] });
+    expect(sent.refused?.rule).toBe("template_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("a language the template was not registered in: an approved template does not exist in another", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "acordo_quitado", language: "es_MX", variables: ["acordo-1042"] });
+    expect(sent.refused?.rule).toBe("template_language_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("a variable count the body has no placeholders for", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042", "a mais"] });
+    expect(sent.refused?.rule).toBe("template_variables_mismatch");
+    expect(sent.refused?.detail).toContain("takes 1 variable(s)");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("counts the placeholders the way Meta numbers them", () => {
+    expect(templateArity("nenhuma")).toBe(0);
+    expect(templateArity("Oi {{1}}, sobre o {{2}}.")).toBe(2);
+    expect(templateArity("Oi {{ 1 }}.")).toBe(1);
+  });
+});

package/templates/hello-agent/packages/agent-runtime/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/templates/hello-agent/tsconfig.base.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node"]
+  }
+}

package/templates/hello-agent/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["packages/*/test/**/*.test.ts", "agents/*/test/**/*.test.ts", "test/**/*.test.ts"],
+    pool: "forks",
+    maxWorkers: 1,
+    minWorkers: 1,
+    fileParallelism: false,
+    testTimeout: 30000,
+  },
+});

package/templates/kits.lock.json

@@ -1,41 +1,89 @@
 {
   "format": 1,
   "kits_repo": "https://github.com/codespar/agent-starter-kits",
-  "kits_ref": "778223274a5df3521d9ef9f33a21446868482391",
-  "commit": "778223274a5df3521d9ef9f33a21446868482391",
-  "agent_core": {
-    "source": "packages/agent-core",
-    "version": "0.1.0"
-  },
+  "kits_ref": "8f130b7cdc30510c929e6f7ebb07184f763e6ce4",
+  "commit": "8f130b7cdc30510c929e6f7ebb07184f763e6ce4",
+  "vendored_packages": [
+    {
+      "name": "@codespar/agent-core",
+      "source": "packages/agent-core",
+      "version": "0.1.0"
+    },
+    {
+      "name": "@codespar/agent-runtime",
+      "source": "packages/agent-runtime",
+      "version": "0.1.0"
+    }
+  ],
   "templates": {
     "bills-agent": {
       "source": "agents/bills-agent",
       "description": "The consumer delegates the month's bills to an agent that pays under a signed mandate: per-payment cap, monthly cap, named payees, expiry. Every payment returns a receipt.",
       "version": "0.1.0",
-      "cli": "@codespar/cli@0.13.0",
+      "cli": "@codespar/cli@0.14.0",
       "mcp": "@codespar/mcp@0.5.8",
-      "agent_core": "0.1.0",
+      "vendored": {
+        "@codespar/agent-core": "0.1.0",
+        "@codespar/agent-runtime": "0.1.0"
+      },
       "next_steps": [
         "cp agents/bills-agent/.env.example agents/bills-agent/.env   # then fill in your keys",
         "npm install",
         "npm run consent -- --yes",
         "npm start"
       ],
-      "hash": "sha256:6cc725fc673f19f855a480163e463da121fe964db89320e587260097215b4f41"
+      "hash": "sha256:e75c5293ae7d576fa5263b9f7bc8accbd4b83d781a5220f4bbc4368f8746abc3"
     },
     "collections-agent": {
       "source": "agents/collections-agent",
       "description": "The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired.",
       "version": "0.1.0",
-      "cli": "@codespar/cli@0.13.0",
+      "cli": "@codespar/cli@0.14.0",
       "mcp": "@codespar/mcp@0.5.8",
-      "agent_core": "0.1.0",
+      "vendored": {
+        "@codespar/agent-core": "0.1.0",
+        "@codespar/agent-runtime": "0.1.0"
+      },
       "next_steps": [
         "cp agents/collections-agent/.env.example agents/collections-agent/.env   # then fill in your keys",
         "npm install",
         "npm start"
       ],
-      "hash": "sha256:149b22e812a97b35f90b42fed6a38261975346035abec05e779f938b5148c131"
+      "hash": "sha256:0588aa52d737058375f5a617844071998a5db3147bddd73447577f756cd11c10"
+    },
+    "hello-agent": {
+      "source": "agents/hello-agent",
+      "description": "The worked example of the codespar-agent-builder skill: a read-only agent that reads the month's bills and cannot pay. Built from the five files, the packs and one kit module.",
+      "version": "0.1.0",
+      "cli": "@codespar/cli@0.14.0",
+      "mcp": "@codespar/mcp@0.5.8",
+      "vendored": {
+        "@codespar/agent-core": "0.1.0",
+        "@codespar/agent-runtime": "0.1.0"
+      },
+      "next_steps": [
+        "cp agents/hello-agent/.env.example agents/hello-agent/.env   # then fill in your keys",
+        "npm install",
+        "npm start"
+      ],
+      "hash": "sha256:f75d8ddb2d1808e337e7c785a3801bbce127a6822de9b761f5c57c28ce1848b9"
+    },
+    "supplier-payments-agent": {
+      "source": "agents/supplier-payments-agent",
+      "description": "A company delegates its suppliers, commissions and payroll to an agent that pays them in batches under one signed mandate. A batch is a loop of executions: one refusal does not stop the others, and re-running it pays nobody twice.",
+      "version": "0.1.0",
+      "cli": "@codespar/cli@0.14.0",
+      "mcp": "@codespar/mcp@0.5.8",
+      "vendored": {
+        "@codespar/agent-core": "0.1.0",
+        "@codespar/agent-runtime": "0.1.0"
+      },
+      "next_steps": [
+        "cp agents/supplier-payments-agent/.env.example agents/supplier-payments-agent/.env   # then fill in your keys",
+        "npm install",
+        "npm start"
+      ],
+      "hash": "sha256:a89cb114242eb0f5e3114801341dbf90ea54e7665f73d24bb68a9fdf452b2753"
     }
   }
 }

package/templates/supplier-payments-agent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codespar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/supplier-payments-agent/README.md

@@ -0,0 +1,23 @@
+# {{name}}
+
+Scaffolded by `codespar init --template supplier-payments-agent` from the `supplier-payments-agent` starter kit
+(https://github.com/codespar/agent-starter-kits at `8f130b7cdc30510c929e6f7ebb07184f763e6ce4`, agent 0.1.0).
+
+A company delegates its suppliers, commissions and payroll to an agent that pays them in batches under one signed mandate. A batch is a loop of executions: one refusal does not stop the others, and re-running it pays nobody twice.
+
+`@codespar/agent-core` and `@codespar/agent-runtime` are not published on npm, so the copies this agent was built
+against are vendored here and linked as npm workspaces; the agent's own
+`package.json` pins resolve to them unchanged:
+
+  - `packages/agent-core/` — @codespar/agent-core 0.1.0
+  - `packages/agent-runtime/` — @codespar/agent-runtime 0.1.0
+
+```
+  cp agents/supplier-payments-agent/.env.example agents/supplier-payments-agent/.env   # then fill in your keys
+  npm install
+  npm start
+```
+
+The agent's guide is [`agents/supplier-payments-agent/README.md`](agents/supplier-payments-agent/README.md); its commands run at this root
+(`npm run check`, `npm run eval`, `npm test`) or inside `agents/supplier-payments-agent/`. The manifest pins
+`cli: "@codespar/cli@0.14.0"`, the CLI version whose `agent run`/`eval` this agent was written for.

package/templates/supplier-payments-agent/_gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+*.tsbuildinfo
+
+# local state, proof bundles and keys: never committed
+.codespar/
+runs/
+.env
+.env.*
+!.env.example

package/templates/supplier-payments-agent/agents/supplier-payments-agent/.env.example

@@ -0,0 +1,7 @@
+# Copy to agents/supplier-payments-agent/.env. `npm install` runs at the repository ROOT (npm workspace), then `npm start`.
+# Test key from https://dashboard.codespar.dev (starts with csk_test_). A live key is refused.
+CODESPAR_API_KEY=csk_test_your_key_here
+# https://console.anthropic.com. Leave empty to replay the recorded happy path (the old placeholder sk-ant-your_key_here also counts as empty).
+ANTHROPIC_API_KEY=
+# Staging only (docs/OPEN_QUESTIONS.md, item 12): a staging test key also needs the staging base URL. A production key needs nothing here.
+# CODESPAR_API_URL=https://api.staging.codespar.dev

package/templates/supplier-payments-agent/agents/supplier-payments-agent/AGENTS.md

@@ -0,0 +1,21 @@
+# Rules for the coding agent working on supplier-payments-agent
+
+You are editing a reference agent of the CodeSpar Agent Starter Kits. These rules keep it a reference.
+
+1. **Read `agent.yaml` before editing anything.** It is the index. `SYSTEM_PROMPT.md`, `tools.json`, `guardrails.json` and `mandate.example.json` must agree with it, and `npm run check` fails when they do not.
+2. **A batch is a loop of executions, one per line.** Never fold a batch back into one multi-item execution to "save a round trip". Not because the core would strand the siblings — it no longer does — but because a payroll line has to be approvable, refusable and re-runnable ALONE: one execution of 200 items is one all-or-nothing decision, and one wrong key sends the whole list back through approval. `src/modules/batch-payout.ts` and `docs/OPEN_QUESTIONS.md` § 40 say why; read them before changing the loop.
+3. **The loop `continue`s, it never breaks.** Every exit from one line — a refusal, a claim already held, a malformed line — is a fact about that line only. A change that lets one line throw past the loop is the bug this agent exists to not have.
+4. **The claim is the thing that stops a double payment.** `engine.claim`/`claimed` pairs a batch line with the execution that covers it, and it is taken BEFORE the channel can run the execution. Claiming afterwards would leave a settled payout unclaimed on a crash, which is the double payment. Only a claim whose execution ended without moving money (`denied`, `expired`, `failed`) is retried.
+5. **The set is bound, and the binding is not decoration.** The list is hashed ONCE, before any line is drafted, and every artifact of the batch carries that `batch_hash` with the line's `index` and the list's `count`. Hash with `batchHash` from the core — it is `itemsHash` over the ordered list; do not write a second canonicalisation — and resolve with `engine.preview`, which does not throw, so a line the core would refuse still occupies its position. A run whose list differs from the one some line of that ref was approved under is refused BEFORE it drafts anything: the surviving lines would each answer `already_settled` and nothing per-line would notice.
+6. **The lines of a batch are the company's, not the model's.** `codespar_pay` refuses `batch_ref` together with `items` or `total_minor`. Do not "helpfully" merge them: that refusal is what makes a batch un-fractionable.
+7. **Do not widen `tools.json` or the mandate without asking.** The tool list is closed on purpose; the mandate's caps and payees are the company's. Adding a tool or a payee is a product decision, not a refactor.
+8. **The model proposes, the code executes.** Nothing you write may let a model output reach `executing` without going through `ExecutionEngine` in `@codespar/agent-core`. If you need a new check, add it to the core or to a `policyExtension`, never to the prompt.
+9. **`escalate_above` only tightens.** A trigger may send an execution to a human; it may never raise a cap or add a payee.
+10. **`actor` on everything.** Every event, approval and receipt copy carries who acted. A receipt without an actor fails the CI.
+11. **Sandbox by construction.** Only `csk_test_` keys. Never commit `.env`, `.codespar/` or `runs/`. The pre-commit secret scan and the CI both refuse a key-shaped string.
+12. **Before you say a task is done:** `npm run check`, `npm run eval` (adversarial suite plus scenarios, on the replay provider, no model needed) and `npm test` at the repository root. All green, or it is not done.
+13. **Use the CodeSpar MCP and skills** (`@codespar/mcp@0.5.8`, pinned in `agent.yaml`) to learn the real API. When the spec in `docs/spec-v5.1.1.md` and the API diverge, follow the API and log it in `docs/OPEN_QUESTIONS.md`.
+14. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
+15. **No telemetry.** Nothing in this repository phones home.
+
+`AGENTS.md` and `CLAUDE.md` are the same file; the CI fails if they diverge. Edit both or neither.

package/templates/supplier-payments-agent/agents/supplier-payments-agent/CLAUDE.md

@@ -0,0 +1,21 @@
+# Rules for the coding agent working on supplier-payments-agent
+
+You are editing a reference agent of the CodeSpar Agent Starter Kits. These rules keep it a reference.
+
+1. **Read `agent.yaml` before editing anything.** It is the index. `SYSTEM_PROMPT.md`, `tools.json`, `guardrails.json` and `mandate.example.json` must agree with it, and `npm run check` fails when they do not.
+2. **A batch is a loop of executions, one per line.** Never fold a batch back into one multi-item execution to "save a round trip". Not because the core would strand the siblings — it no longer does — but because a payroll line has to be approvable, refusable and re-runnable ALONE: one execution of 200 items is one all-or-nothing decision, and one wrong key sends the whole list back through approval. `src/modules/batch-payout.ts` and `docs/OPEN_QUESTIONS.md` § 40 say why; read them before changing the loop.
+3. **The loop `continue`s, it never breaks.** Every exit from one line — a refusal, a claim already held, a malformed line — is a fact about that line only. A change that lets one line throw past the loop is the bug this agent exists to not have.
+4. **The claim is the thing that stops a double payment.** `engine.claim`/`claimed` pairs a batch line with the execution that covers it, and it is taken BEFORE the channel can run the execution. Claiming afterwards would leave a settled payout unclaimed on a crash, which is the double payment. Only a claim whose execution ended without moving money (`denied`, `expired`, `failed`) is retried.
+5. **The set is bound, and the binding is not decoration.** The list is hashed ONCE, before any line is drafted, and every artifact of the batch carries that `batch_hash` with the line's `index` and the list's `count`. Hash with `batchHash` from the core — it is `itemsHash` over the ordered list; do not write a second canonicalisation — and resolve with `engine.preview`, which does not throw, so a line the core would refuse still occupies its position. A run whose list differs from the one some line of that ref was approved under is refused BEFORE it drafts anything: the surviving lines would each answer `already_settled` and nothing per-line would notice.
+6. **The lines of a batch are the company's, not the model's.** `codespar_pay` refuses `batch_ref` together with `items` or `total_minor`. Do not "helpfully" merge them: that refusal is what makes a batch un-fractionable.
+7. **Do not widen `tools.json` or the mandate without asking.** The tool list is closed on purpose; the mandate's caps and payees are the company's. Adding a tool or a payee is a product decision, not a refactor.
+8. **The model proposes, the code executes.** Nothing you write may let a model output reach `executing` without going through `ExecutionEngine` in `@codespar/agent-core`. If you need a new check, add it to the core or to a `policyExtension`, never to the prompt.
+9. **`escalate_above` only tightens.** A trigger may send an execution to a human; it may never raise a cap or add a payee.
+10. **`actor` on everything.** Every event, approval and receipt copy carries who acted. A receipt without an actor fails the CI.
+11. **Sandbox by construction.** Only `csk_test_` keys. Never commit `.env`, `.codespar/` or `runs/`. The pre-commit secret scan and the CI both refuse a key-shaped string.
+12. **Before you say a task is done:** `npm run check`, `npm run eval` (adversarial suite plus scenarios, on the replay provider, no model needed) and `npm test` at the repository root. All green, or it is not done.
+13. **Use the CodeSpar MCP and skills** (`@codespar/mcp@0.5.8`, pinned in `agent.yaml`) to learn the real API. When the spec in `docs/spec-v5.1.1.md` and the API diverge, follow the API and log it in `docs/OPEN_QUESTIONS.md`.
+14. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
+15. **No telemetry.** Nothing in this repository phones home.
+
+`AGENTS.md` and `CLAUDE.md` are the same file; the CI fails if they diverge. Edit both or neither.