@jsm-mit/sultana-agent-tools-package 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,55 @@ const tools = createSalonTools({
 `salonId` is captured at construction and is **never a tool argument** — a model holding these
 tools cannot reach another salon's data whatever it sends.
 
+### Confirmations across turns
+
+A host that runs the owner set in a chat keeps one `ConfirmationLedger` per conversation and builds
+the tools again for every incoming owner message, with that message's turn:
+
+```ts
+import { ConfirmationLedger, createSalonTools, SALON_AGENT_PERSONA_PL } from "@jsm-mit/sultana-agent-tools-package";
+
+const ledger = new ConfirmationLedger();          // one per conversation, kept in memory
+
+// on every owner message — one agent turn:
+const tools = createSalonTools({ canisterId, identity, salonId, confirmations: ledger.forTurn() });
+```
+
+With `confirmations`, the two-step protocol is enforced by the tools, not only asked for by the
+persona:
+
+1. `confirmed: false` makes no canister write and returns `confirmation_required` with a
+   `summary` and an `echo` that now carries a `confirmationId` (`c-` and 8 hex digits).
+2. `confirmed: true` goes through only with that `confirmationId`, the **same arguments** (key
+   order does not matter, array order does; `confirmed`, `confirmationId` and
+   `confirmationPhrase` are not compared), from a **later turn**, within 15 minutes, and once.
+   Anything else is `status: "error"`, `code: "invalid_arguments"`, returned before the tool calls
+   the canister at all:
+
+| why | summary |
+|---|---|
+| same turn as the preview | Zgoda musi przyjść w osobnej wiadomości właścicielki — najpierw pokaż podsumowanie i poczekaj na odpowiedź. |
+| no id, unknown, used or expired | Brak ważnego podglądu tej zmiany — wywołaj narzędzie z confirmed=false i pokaż właścicielce podsumowanie. |
+| other tool or other arguments | Argumenty różnią się od pokazanego podglądu — pokaż nowy podgląd (confirmed=false). |
+
+Every write tool's schema gets a `confirmationId` parameter when a ledger is passed; without one,
+the schemas and the protocol are what they were in 0.2.0 (a model can still confirm in the same
+breath — only the persona stops it). The id is used up right before the write, not at the first
+check: a confirmation refused for a mistyped name can be sent again with the same id once the owner
+has typed it right. Two parallel calls with one id cannot both write: the second is refused right before its write.
+
+`ConfirmationLedger` takes `{ ttlMs, now, newId }` for tests; `createSalonToolsFromPort(port,
+{ confirmations })` is the same over any port. `forTurn()` returns `TurnConfirmations` —
+`issue(toolName, args)`, `check(toolName, args, id)` (the verdict, the id kept) and
+`redeem(toolName, args, id)` (the verdict, the id used up) — for a host that wants the protocol
+around tools of its own.
+
+`SALON_AGENT_PERSONA_PL` is written for this: every write first with `confirmed=false`, the
+summary shown, the owner's answer awaited in her **next** message, then `confirmed=true` with the
+`confirmationId` and the same arguments; a removal only with the name the owner typed herself; and
+with read tools only, the agent says that changes need the "Salon Assistant" page open in the
+panel.
+
 ### Read-only set
 
 An assistant that runs without the owner's identity takes the read-only set and its own persona:
@@ -84,12 +133,18 @@ and `find_service_type`.
 - **`execute` never throws.** Every call returns `{status: "ok" | "confirmation_required" | "error"}`
   so an agent can read a failure and talk about it.
 - **Confirmation is a schema field, not a prompt rule.** Called with `confirmed: false`, a write
-  tool makes no canister call and returns a sentence built from *resolved* arguments — worker names
-  and service-type labels already looked up — plus the exact arguments to send back. A persona can
-  be talked out of a rule; a required field cannot.
+  tool makes no canister write and returns a sentence built from *resolved* arguments — worker names
+  and service-type labels already looked up — plus the arguments to send back in `echo`. A persona
+  can be talked out of a rule; a required field cannot. With a `ConfirmationLedger` (above) the
+  confirmation must also come from a later turn, with the preview's id.
 - **Irreversible operations need the entity's own name** typed back in `confirmationPhrase`.
-- **A partial edit is merged.** `updateSalonService` replaces the whole record on the canister, so
-  "just change the price" would otherwise unassign the team.
+  `remove_service` and `remove_promo` leave the name OUT of `echo`, and their summary asks the
+  model to have the owner write it: a model that just sends the echo back deletes nothing.
+- **A partial edit is merged — at write time.** `updateSalonService` replaces the whole record on
+  the canister, so "just change the price" would otherwise unassign the team. The preview summary
+  shows the merged record, but `update_service`'s `echo` carries only `salonServiceId` and the
+  fields the model sent; the confirmed call reads the record again and merges then, so a change
+  made in the panel between preview and confirmation is kept.
 - **Units are fixed at the boundary**: price is whole zloty, duration is minutes rounded up to a
   multiple of 5 (the availability grid), and the tool says when it rounded.
 - **Service-type ids come from the catalogue.** `find_service_type` uses the same matcher as both
@@ -111,7 +166,9 @@ and `find_service_type`.
 
 `npm run sandbox -- --fake` is the loop to iterate in: a real model, real tool calls, an in-memory
 salon. Every call is printed with its arguments and its result, so a tool description that misleads
-the model shows up immediately — and a wrong answer costs no cycles and no daily action quota.
+the model shows up immediately — and a wrong answer costs no cycles and no daily action quota. The
+sandbox builds the tools again for every line you type, with a turn of one `ConfirmationLedger`,
+as a host does — so the confirmation id and the next-message rule are in play there too.
 
 Drop `--fake` to run the same conversation against a canister with the owner's identity
 (`OWNER1_PEM`). Start with `npm run whoami`: it prints the principal the PEM makes you, the salons

package/dist/confirmations.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The two-step write protocol, enforced in code rather than by the persona.
+ *
+ * A write tool called with `confirmed: false` issues a confirmation id for exactly those arguments.
+ * The write itself goes through only when a LATER turn — the owner's next message — sends the same
+ * arguments back with that id. A model that previews and confirms in one breath, confirms
+ * something it never showed, or reuses an id, is refused before any canister call.
+ *
+ * The ledger lives in memory next to the conversation. A host keeps one ledger per conversation and
+ * calls `forTurn()` once per incoming owner message, when it builds that turn's tools.
+ */
+export declare const DEFAULT_CONFIRMATION_TTL_MS: number;
+export interface ConfirmationLedgerOptions {
+    /** How long a preview can still be confirmed. Defaults to 15 minutes. */
+    ttlMs?: number;
+    /** Milliseconds since the epoch. For tests. */
+    now?: () => number;
+    /** Confirmation id generator. For tests. */
+    newId?: () => string;
+}
+export type ConfirmationRefusal = 
+/** No `confirmationId` was sent. */
+"missing"
+/** The id was never issued, was already used, or was cleared out after expiring. */
+ | "unknown"
+/** The id comes from this very turn — the owner has not answered the preview yet. */
+ | "same_turn"
+/** The preview is older than the ledger's TTL. */
+ | "expired"
+/** The id was issued for another tool or other arguments. */
+ | "mismatch";
+export type RedeemResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: ConfirmationRefusal;
+};
+/** One turn's view of the ledger. Ids issued here can only be redeemed from a later turn. */
+export interface TurnConfirmations {
+    /** Records a preview of `toolName` with `args` and returns its id (`c-` and 8 hex digits). */
+    issue(toolName: string, args: Record<string, unknown>): string;
+    /** Whether `redeem` would succeed now — without using the id up. An expired entry is cleared. */
+    check(toolName: string, args: Record<string, unknown>, confirmationId: string | undefined): RedeemResult;
+    /** The same verdict as `check`; on success the id is used up and cannot confirm anything again. */
+    redeem(toolName: string, args: Record<string, unknown>, confirmationId: string | undefined): RedeemResult;
+}
+export declare class ConfirmationLedger {
+    private readonly ttlMs;
+    private readonly now;
+    private readonly newId;
+    private readonly pending;
+    private turn;
+    constructor(options?: ConfirmationLedgerOptions);
+    /** Starts a new turn. Call it once per incoming owner message and hand the result to that
+     * turn's tools; every call is a later turn than the one before. */
+    forTurn(): TurnConfirmations;
+    private issue;
+    private verdict;
+    private isExpired;
+}
+//# sourceMappingURL=confirmations.d.ts.map

package/dist/confirmations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmations.d.ts","sourceRoot":"","sources":["../src/confirmations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAK1D,MAAM,WAAW,yBAAyB;IACtC,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,mBAAmB;AAC3B,oCAAoC;AAClC,SAAS;AACX,oFAAoF;GAClF,SAAS;AACX,qFAAqF;GACnF,WAAW;AACb,kDAAkD;GAChD,SAAS;AACX,6DAA6D;GAC3D,UAAU,CAAC;AAEjB,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAErF,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAC9B,8FAA8F;IAC9F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IAC/D,iGAAiG;IACjG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACzG,mGAAmG;IACnG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;CAC7G;AASD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAClE,OAAO,CAAC,IAAI,CAAK;gBAEL,OAAO,GAAE,yBAA8B;IAMnD;uEACmE;IAC5D,OAAO,IAAI,iBAAiB;IAWnC,OAAO,CAAC,KAAK;IAeb,OAAO,CAAC,OAAO;IA6Bf,OAAO,CAAC,SAAS;CAGpB"}

package/dist/confirmations.js

@@ -0,0 +1,100 @@
+/**
+ * The two-step write protocol, enforced in code rather than by the persona.
+ *
+ * A write tool called with `confirmed: false` issues a confirmation id for exactly those arguments.
+ * The write itself goes through only when a LATER turn — the owner's next message — sends the same
+ * arguments back with that id. A model that previews and confirms in one breath, confirms
+ * something it never showed, or reuses an id, is refused before any canister call.
+ *
+ * The ledger lives in memory next to the conversation. A host keeps one ledger per conversation and
+ * calls `forTurn()` once per incoming owner message, when it builds that turn's tools.
+ */
+export const DEFAULT_CONFIRMATION_TTL_MS = 15 * 60 * 1000;
+/** Argument keys that carry the protocol, not the change — never part of what is compared. */
+const PROTOCOL_KEYS = new Set(["confirmed", "confirmationId", "confirmationPhrase"]);
+export class ConfirmationLedger {
+    ttlMs;
+    now;
+    newId;
+    pending = new Map();
+    turn = 0;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? DEFAULT_CONFIRMATION_TTL_MS;
+        this.now = options.now ?? Date.now;
+        this.newId = options.newId ?? randomConfirmationId;
+    }
+    /** Starts a new turn. Call it once per incoming owner message and hand the result to that
+     * turn's tools; every call is a later turn than the one before. */
+    forTurn() {
+        this.turn += 1;
+        const turn = this.turn;
+        return {
+            issue: (toolName, args) => this.issue(turn, toolName, args),
+            check: (toolName, args, confirmationId) => this.verdict(turn, toolName, args, confirmationId, false),
+            redeem: (toolName, args, confirmationId) => this.verdict(turn, toolName, args, confirmationId, true),
+        };
+    }
+    issue(turn, toolName, args) {
+        // Previews nobody confirmed would otherwise pile up for the life of the conversation.
+        const now = this.now();
+        for (const [id, entry] of this.pending) {
+            if (this.isExpired(entry, now))
+                this.pending.delete(id);
+        }
+        // A 32-bit collision only replaces an older preview, whose id then fails as a mismatch —
+        // never lets a change through.
+        const id = this.newId();
+        this.pending.set(id, { toolName, argsKey: confirmationArgsKey(args), turn, issuedAt: now });
+        return id;
+    }
+    verdict(turn, toolName, args, confirmationId, redeem) {
+        const id = confirmationId?.trim();
+        if (!id)
+            return { ok: false, reason: "missing" };
+        const entry = this.pending.get(id);
+        if (!entry)
+            return { ok: false, reason: "unknown" };
+        if (this.isExpired(entry, this.now())) {
+            this.pending.delete(id);
+            return { ok: false, reason: "expired" };
+        }
+        if (entry.turn >= turn)
+            return { ok: false, reason: "same_turn" };
+        if (entry.toolName !== toolName || entry.argsKey !== confirmationArgsKey(args)) {
+            return { ok: false, reason: "mismatch" };
+        }
+        if (redeem)
+            this.pending.delete(id);
+        return { ok: true };
+    }
+    isExpired(entry, now) {
+        return now - entry.issuedAt > this.ttlMs;
+    }
+}
+/** Canonical JSON of the arguments without the protocol keys: object keys sorted at every depth,
+ * array order kept — `{b, a}` and `{a, b}` are the same change, `[1, 2]` and `[2, 1]` are not. */
+function confirmationArgsKey(args) {
+    const change = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (!PROTOCOL_KEYS.has(key))
+            change[key] = value;
+    }
+    return JSON.stringify(sortKeys(change));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value === null || typeof value !== "object")
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+}
+/** `crypto.getRandomValues` exists in Node and in every browser, secure context or not. */
+function randomConfirmationId() {
+    const bytes = new Uint8Array(4);
+    globalThis.crypto.getRandomValues(bytes);
+    return `c-${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}

package/dist/create-salon-tools.d.ts

@@ -1,8 +1,19 @@
 import type { Identity } from "@icp-sdk/core/agent";
+import type { TurnConfirmations } from "./confirmations.js";
 import { type IcSalonCorePortOptions } from "./ic-salon-core-port.js";
 import type { SalonCorePort } from "./salon-core-port.js";
 import type { AgentTool } from "./types.js";
-export interface CreateSalonToolsOptions extends Omit<IcSalonCorePortOptions, "language" | "access"> {
+export interface CreateSalonToolsFromPortOptions {
+    /**
+     * This turn's confirmations — `ledger.forTurn()` from the conversation's `ConfirmationLedger`,
+     * taken once per incoming owner message. With it, every write tool issues a `confirmationId`
+     * on `confirmed: false` and refuses `confirmed: true` unless that id comes back, with the same
+     * arguments, from a later turn. Omit it and the tools keep the old protocol, where only the
+     * persona stops a model from confirming on its own.
+     */
+    confirmations?: TurnConfirmations;
+}
+export interface CreateSalonToolsOptions extends Omit<IcSalonCorePortOptions, "language" | "access">, CreateSalonToolsFromPortOptions {
     /** Language of service-type labels. Defaults to Polish. */
     language?: string;
 }
@@ -12,7 +23,7 @@ export interface CreateSalonToolsOptions extends Omit<IcSalonCorePortOptions, "l
  */
 export declare function createSalonTools(options: CreateSalonToolsOptions): AgentTool[];
 /** The same tool set over any port — the seam tests and the sandbox use. */
-export declare function createSalonToolsFromPort(port: SalonCorePort): AgentTool[];
+export declare function createSalonToolsFromPort(port: SalonCorePort, options?: CreateSalonToolsFromPortOptions): AgentTool[];
 export interface CreateSalonReadToolsOptions {
     canisterId: string;
     salonId: string;

package/dist/create-salon-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-salon-tools.d.ts","sourceRoot":"","sources":["../src/create-salon-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,sBAAsB,EAAE,UAAU,GAAG,QAAQ,CAAC;IAChG,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAAE,CAG9E;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CAEzE;AAED,MAAM,WAAW,2BAA2B;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,SAAS,EAAE,CAGtF;AAED;mEACmE;AACnE,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CAE7E"}
+{"version":3,"file":"create-salon-tools.d.ts","sourceRoot":"","sources":["../src/create-salon-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAmB,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,+BAA+B;IAC5C;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,WAAW,uBACb,SAAQ,IAAI,CAAC,sBAAsB,EAAE,UAAU,GAAG,QAAQ,CAAC,EACvD,+BAA+B;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,SAAS,EAAE,CAK9E;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,+BAAoC,GAAG,SAAS,EAAE,CAQxH;AAED,MAAM,WAAW,2BAA2B;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,SAAS,EAAE,CAGtF;AAED;mEACmE;AACnE,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CAE7E"}

package/dist/create-salon-tools.js

@@ -7,12 +7,18 @@ import { createServiceTools, findServiceTypeTool, listServicesTool } from "./too
  * argument, so a model holding these tools cannot reach another salon's data whatever it sends.
  */
 export function createSalonTools(options) {
-    const port = new IcSalonCorePort({ ...options, language: options.language ?? "pl", access: "owner" });
-    return createSalonToolsFromPort(port);
+    const { confirmations, language, ...portOptions } = options;
+    const port = new IcSalonCorePort({ ...portOptions, language: language ?? "pl", access: "owner" });
+    return createSalonToolsFromPort(port, { confirmations });
 }
 /** The same tool set over any port — the seam tests and the sandbox use. */
-export function createSalonToolsFromPort(port) {
-    return [...createServiceTools(port), ...createScheduleTools(port), ...createPromoTools(port)];
+export function createSalonToolsFromPort(port, options = {}) {
+    const { confirmations } = options;
+    return [
+        ...createServiceTools(port, confirmations),
+        ...createScheduleTools(port, confirmations),
+        ...createPromoTools(port, confirmations),
+    ];
 }
 /**
  * The read-only tool set for ONE salon: `list_services`, `list_promos` and `find_service_type`,

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+export { ConfirmationLedger, DEFAULT_CONFIRMATION_TTL_MS } from "./confirmations.js";
+export type { ConfirmationLedgerOptions, ConfirmationRefusal, RedeemResult, TurnConfirmations, } from "./confirmations.js";
 export { createSalonReadTools, createSalonReadToolsFromPort, createSalonTools, createSalonToolsFromPort, } from "./create-salon-tools.js";
-export type { CreateSalonReadToolsOptions, CreateSalonToolsOptions } from "./create-salon-tools.js";
+export type { CreateSalonReadToolsOptions, CreateSalonToolsFromPortOptions, CreateSalonToolsOptions, } from "./create-salon-tools.js";
 export { IcSalonCorePort } from "./ic-salon-core-port.js";
 export type { IcSalonCorePortOptions } from "./ic-salon-core-port.js";
 export { SALON_AGENT_PERSONA_PL, SALON_READ_PERSONA_PL } from "./persona.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,wBAAwB,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACpG,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EACR,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,UAAU,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACrF,YAAY,EACR,yBAAyB,EACzB,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,oBAAoB,EACpB,4BAA4B,EAC5B,gBAAgB,EAChB,wBAAwB,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACR,2BAA2B,EAC3B,+BAA+B,EAC/B,uBAAuB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC7E,YAAY,EACR,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,UAAU,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export { ConfirmationLedger, DEFAULT_CONFIRMATION_TTL_MS } from "./confirmations.js";
 export { createSalonReadTools, createSalonReadToolsFromPort, createSalonTools, createSalonToolsFromPort, } from "./create-salon-tools.js";
 export { IcSalonCorePort } from "./ic-salon-core-port.js";
 export { SALON_AGENT_PERSONA_PL, SALON_READ_PERSONA_PL } from "./persona.js";

package/dist/persona.d.ts

@@ -5,8 +5,11 @@
  * confirmation protocol, which reads come before which writes), so keeping them next to the tools
  * is the only way they cannot drift apart. An agent host may append its own persona — who the
  * agent is, how it speaks — on top of this.
+ *
+ * The two-step rule is written for a host that passes a `ConfirmationLedger` turn to the tools:
+ * the tools then refuse a confirmation from the same turn, so the persona and the code agree.
  */
-export declare const SALON_AGENT_PERSONA_PL = "Jeste\u015B asystentem w\u0142a\u015Bciciela salonu w aplikacji Sultana.\nRozmawiasz po polsku, kr\u00F3tko i konkretnie. Wykonujesz zmiany w salonie za pomoc\u0105 narz\u0119dzi.\n\nZasady pracy:\n- Zanim zmienisz albo usuniesz us\u0142ug\u0119, wywo\u0142aj list_services i ustal jej id. Nie zgaduj id.\n- Zanim podasz serviceTypeIds, wywo\u0142aj find_service_type. Nigdy nie wymy\u015Blaj id typu us\u0142ugi.\n- Zanim przypiszesz pracownik\u00F3w, wywo\u0142aj list_workers.\n- Cena to pe\u0142ne z\u0142ote (liczba ca\u0142kowita). Czas trwania to minuty, wielokrotno\u015B\u0107 5.\n  \"p\u00F3\u0142torej godziny\" to 90 minut, \"kwadrans\" to 15 minut.\n- Ka\u017Cde narz\u0119dzie zapisuj\u0105ce ma pole confirmed. Najpierw wywo\u0142aj je z confirmed=false,\n  poka\u017C w\u0142a\u015Bcicielowi zdanie, kt\u00F3re wr\u00F3ci w polu summary, i poczekaj na zgod\u0119.\n  Dopiero po wyra\u017Anym \"tak\" wywo\u0142aj to samo narz\u0119dzie z confirmed=true.\n- Przy usuwaniu popro\u015B w\u0142a\u015Bciciela o przepisanie dok\u0142adnej nazwy usuwanej rzeczy\n  i wstaw j\u0105 w confirmationPhrase.\n- Je\u015Bli narz\u0119dzie zwr\u00F3ci status \"error\", przeczytaj summary i powiedz w\u0142a\u015Bcicielowi,\n  co posz\u0142o nie tak. Nie powtarzaj tego samego wywo\u0142ania w k\u00F3\u0142ko.\n- Je\u015Bli brakuje Ci danych do wykonania polecenia, dopytaj o jedn\u0105 rzecz naraz.\n- Nie obiecuj zmian, kt\u00F3rych nie wykona\u0142e\u015B narz\u0119dziem.";
+export declare const SALON_AGENT_PERSONA_PL = "Jeste\u015B asystentem w\u0142a\u015Bcicielki salonu w aplikacji Sultana.\nRozmawiasz po polsku, kr\u00F3tko i konkretnie. Wykonujesz zmiany w salonie za pomoc\u0105 narz\u0119dzi.\n\nZasady pracy:\n- Zanim zmienisz albo usuniesz us\u0142ug\u0119, wywo\u0142aj list_services i ustal jej id. Nie zgaduj id.\n- Zanim podasz serviceTypeIds, wywo\u0142aj find_service_type. Nigdy nie wymy\u015Blaj id typu us\u0142ugi.\n- Zanim przypiszesz pracownik\u00F3w, wywo\u0142aj list_workers.\n- Cena to pe\u0142ne z\u0142ote (liczba ca\u0142kowita). Czas trwania to minuty, wielokrotno\u015B\u0107 5.\n  \"p\u00F3\u0142torej godziny\" to 90 minut, \"kwadrans\" to 15 minut.\n- Gdy masz narz\u0119dzia zapisuj\u0105ce, list_services i list_promos pokazuj\u0105 te\u017C us\u0142ugi\n  i promocje wy\u0142\u0105czone \u2014 nie tylko to, co widz\u0105 klientki.\n- Ka\u017Cda zmiana to dwa kroki w dw\u00F3ch r\u00F3\u017Cnych wiadomo\u015Bciach w\u0142a\u015Bcicielki:\n  1. Wywo\u0142aj narz\u0119dzie zapisuj\u0105ce z confirmed=false. Poka\u017C w\u0142a\u015Bcicielce zdanie z pola summary,\n     zapytaj o zgod\u0119 i na tym zako\u0144cz odpowied\u017A.\n  2. Dopiero gdy w swojej NAST\u0118PNEJ wiadomo\u015Bci wyra\u017Anie si\u0119 zgodzi, wywo\u0142aj to samo narz\u0119dzie\n     z confirmed=true, z confirmationId z tego podgl\u0105du i z tymi samymi argumentami (pole echo).\n  Nigdy nie potwierdzaj w tej samej odpowiedzi, w kt\u00F3rej pokaza\u0142e\u015B podgl\u0105d.\n  Gdy w\u0142a\u015Bcicielka chce co\u015B inaczej, zr\u00F3b nowy podgl\u0105d i zn\u00F3w poczekaj na zgod\u0119.\n- Przy usuwaniu popro\u015B w\u0142a\u015Bcicielk\u0119, \u017Ceby sama napisa\u0142a dok\u0142adn\u0105 nazw\u0119 usuwanej rzeczy,\n  i wstaw w confirmationPhrase to, co napisa\u0142a. Nigdy nie wpisuj nazwy za ni\u0105.\n- Je\u015Bli masz tylko narz\u0119dzia do odczytu (list_\u2026, find_\u2026), nie mo\u017Cesz niczego zmieni\u0107 \u2014\n  powiedz, \u017Ce zmiany wymagaj\u0105 otwartej strony \u201ESalon Assistant\u201D w panelu.\n- Je\u015Bli narz\u0119dzie zwr\u00F3ci status \"error\", przeczytaj summary i powiedz w\u0142a\u015Bcicielce,\n  co posz\u0142o nie tak. Nie powtarzaj tego samego wywo\u0142ania w k\u00F3\u0142ko.\n- Je\u015Bli brakuje Ci danych do wykonania polecenia, dopytaj o jedn\u0105 rzecz naraz.\n- Nie obiecuj zmian, kt\u00F3rych nie wykona\u0142e\u015B narz\u0119dziem.";
 /**
  * The operating rules for the read-only set (`createSalonReadTools`), as a system prompt.
  *

package/dist/persona.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../src/persona.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,28CAiBoB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,6wCAee,CAAC"}
+{"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../src/persona.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,i2EAyBoB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,6wCAee,CAAC"}

package/dist/persona.js

@@ -5,8 +5,11 @@
  * confirmation protocol, which reads come before which writes), so keeping them next to the tools
  * is the only way they cannot drift apart. An agent host may append its own persona — who the
  * agent is, how it speaks — on top of this.
+ *
+ * The two-step rule is written for a host that passes a `ConfirmationLedger` turn to the tools:
+ * the tools then refuse a confirmation from the same turn, so the persona and the code agree.
  */
-export const SALON_AGENT_PERSONA_PL = `Jesteś asystentem właściciela salonu w aplikacji Sultana.
+export const SALON_AGENT_PERSONA_PL = `Jesteś asystentem właścicielki salonu w aplikacji Sultana.
 Rozmawiasz po polsku, krótko i konkretnie. Wykonujesz zmiany w salonie za pomocą narzędzi.
 
 Zasady pracy:
@@ -15,12 +18,20 @@ Zasady pracy:
 - Zanim przypiszesz pracowników, wywołaj list_workers.
 - Cena to pełne złote (liczba całkowita). Czas trwania to minuty, wielokrotność 5.
   "półtorej godziny" to 90 minut, "kwadrans" to 15 minut.
-- Każde narzędzie zapisujące ma pole confirmed. Najpierw wywołaj je z confirmed=false,
-  pokaż właścicielowi zdanie, które wróci w polu summary, i poczekaj na zgodę.
-  Dopiero po wyraźnym "tak" wywołaj to samo narzędzie z confirmed=true.
-- Przy usuwaniu poproś właściciela o przepisanie dokładnej nazwy usuwanej rzeczy
-  i wstaw ją w confirmationPhrase.
-- Jeśli narzędzie zwróci status "error", przeczytaj summary i powiedz właścicielowi,
+- Gdy masz narzędzia zapisujące, list_services i list_promos pokazują też usługi
+  i promocje wyłączone — nie tylko to, co widzą klientki.
+- Każda zmiana to dwa kroki w dwóch różnych wiadomościach właścicielki:
+  1. Wywołaj narzędzie zapisujące z confirmed=false. Pokaż właścicielce zdanie z pola summary,
+     zapytaj o zgodę i na tym zakończ odpowiedź.
+  2. Dopiero gdy w swojej NASTĘPNEJ wiadomości wyraźnie się zgodzi, wywołaj to samo narzędzie
+     z confirmed=true, z confirmationId z tego podglądu i z tymi samymi argumentami (pole echo).
+  Nigdy nie potwierdzaj w tej samej odpowiedzi, w której pokazałeś podgląd.
+  Gdy właścicielka chce coś inaczej, zrób nowy podgląd i znów poczekaj na zgodę.
+- Przy usuwaniu poproś właścicielkę, żeby sama napisała dokładną nazwę usuwanej rzeczy,
+  i wstaw w confirmationPhrase to, co napisała. Nigdy nie wpisuj nazwy za nią.
+- Jeśli masz tylko narzędzia do odczytu (list_…, find_…), nie możesz niczego zmienić —
+  powiedz, że zmiany wymagają otwartej strony „Salon Assistant” w panelu.
+- Jeśli narzędzie zwróci status "error", przeczytaj summary i powiedz właścicielce,
   co poszło nie tak. Nie powtarzaj tego samego wywołania w kółko.
 - Jeśli brakuje Ci danych do wykonania polecenia, dopytaj o jedną rzecz naraz.
 - Nie obiecuj zmian, których nie wykonałeś narzędziem.`;

package/dist/tools/promos.d.ts

@@ -1,6 +1,7 @@
+import type { TurnConfirmations } from "../confirmations.js";
 import type { SalonAccess, SalonCorePort } from "../salon-core-port.js";
 import { type AgentTool } from "../types.js";
-export declare function createPromoTools(port: SalonCorePort): AgentTool[];
+export declare function createPromoTools(port: SalonCorePort, confirmations?: TurnConfirmations): AgentTool[];
 /** `access` must match the port: `"public"` only for a port read anonymously, because the canister
  * gives the salon's owner the whole library whatever the port calls. */
 export declare function listPromosTool(port: SalonCorePort, access?: SalonAccess): AgentTool;

package/dist/tools/promos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"promos.d.ts","sourceRoot":"","sources":["../../src/tools/promos.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA8B,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAqBzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CAYjE;AA2CD;wEACwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,WAAqB,GAAG,SAAS,CAmB5F"}
+{"version":3,"file":"promos.d.ts","sourceRoot":"","sources":["../../src/tools/promos.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,KAAK,EAA8B,WAAW,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACpG,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAsBtD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,EAAE,CAYpG;AA2CD;wEACwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,WAAqB,GAAG,SAAS,CAmB5F"}

package/dist/tools/promos.js

@@ -1,7 +1,8 @@
 import { MAX_ACTIVE_PROMOS_PER_SALON, MAX_PROMOS_PER_SALON } from "@jsm-mit/sultana-core-motoko-package";
 import { toToolError } from "../errors.js";
-import { err, needsConfirmation, ok } from "../types.js";
+import { err, ok } from "../types.js";
 import { ArgumentError, phrasesMatch, readBoolean, readOptionalNumber, readOptionalString, readOptionalStringArray, readString, } from "./args.js";
+import { writeGate } from "./write-gate.js";
 const MAX_PROMO_NAME_LENGTH = 60;
 const MAX_TEXT_LINES = 2;
 const MAX_CHIPS = 2;
@@ -9,17 +10,17 @@ const CONFIRMED_FIELD = {
     type: "boolean",
     description: "false dla podglądu: narzędzie nic nie zapisze i odda opis zmiany do zatwierdzenia przez właściciela. true dopiero po potwierdzeniu.",
 };
-export function createPromoTools(port) {
+export function createPromoTools(port, confirmations) {
     return [
         listMediaTool(port),
         listPromosTool(port),
-        addPromoTool(port),
-        updatePromoTool(port),
-        setPromoActiveTool(port),
-        removePromoTool(port),
+        addPromoTool(port, confirmations),
+        updatePromoTool(port, confirmations),
+        setPromoActiveTool(port, confirmations),
+        removePromoTool(port, confirmations),
         listDiscountCodesTool(port),
-        addDiscountCodeTool(port),
-        removeDiscountCodeTool(port),
+        addDiscountCodeTool(port, confirmations),
+        removeDiscountCodeTool(port, confirmations),
     ];
 }
 function listMediaTool(port) {
@@ -81,12 +82,13 @@ export function listPromosTool(port, access = "owner") {
         },
     };
 }
-function addPromoTool(port) {
+function addPromoTool(port, confirmations) {
+    const gate = writeGate("add_promo", confirmations);
     return {
         name: "add_promo",
         progress: "Zakładam promocję…",
         description: "Zakłada nową promocję na materiale z biblioteki. Najpierw wywołaj list_media i wybierz assetId. Nowa promocja jest nieaktywna — włącz ją potem przez set_promo_active.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 name: { type: "string", description: `Nazwa kampanii, maksymalnie ${MAX_PROMO_NAME_LENGTH} znaków.` },
@@ -104,13 +106,19 @@ function addPromoTool(port) {
             },
             required: ["name", "assetId", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const input = await buildPromoInput(port, args, null);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Założę promocję ${await describePromo(port, input)}.`, { ...args, confirmed: true });
+                    return gate.preview(`Założę promocję ${await describePromo(port, input)}.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 const promoId = await port.addPromo(input);
                 return ok(`Założono promocję „${input.name}”. Jest jeszcze nieaktywna.`, { promoId });
             }
@@ -122,12 +130,13 @@ function addPromoTool(port) {
         },
     };
 }
-function updatePromoTool(port) {
+function updatePromoTool(port, confirmations) {
+    const gate = writeGate("update_promo", confirmations);
     return {
         name: "update_promo",
         progress: "Zmieniam promocję…",
         description: "Zmienia istniejącą promocję. Podaj tylko pola, które mają się zmienić — reszta zostanie zachowana. Promocja zachowuje swoje miejsce w kanale, więc poprawka nie restartuje kampanii.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 promoId: { type: "string", description: "Id promocji z list_promos." },
@@ -142,20 +151,23 @@ function updatePromoTool(port) {
             },
             required: ["promoId", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const promoId = readString(args, "promoId");
                 const current = await findPromo(port, promoId);
                 if (!current)
                     return err("not_found", `W tym salonie nie ma promocji o id ${promoId}.`);
                 const input = await buildPromoInput(port, args, current);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Zmienię promocję „${current.name}” na: ${await describePromo(port, input)}.`, {
-                        ...args,
-                        confirmed: true,
-                    });
+                    return gate.preview(`Zmienię promocję „${current.name}” na: ${await describePromo(port, input)}.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.updatePromo(promoId, input);
                 return ok(`Zmieniono promocję „${input.name}”.`);
             }
@@ -167,12 +179,13 @@ function updatePromoTool(port) {
         },
     };
 }
-function setPromoActiveTool(port) {
+function setPromoActiveTool(port, confirmations) {
+    const gate = writeGate("set_promo_active", confirmations);
     return {
         name: "set_promo_active",
         progress: "Zmieniam status promocji…",
         description: `Włącza promocję w kanale albo ją wyłącza. Naraz może być aktywnych najwyżej ${MAX_ACTIVE_PROMOS_PER_SALON} — żeby włączyć kolejną, najpierw wyłącz inną.`,
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 promoId: { type: "string", description: "Id promocji z list_promos." },
@@ -181,9 +194,12 @@ function setPromoActiveTool(port) {
             },
             required: ["promoId", "active", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const promoId = readString(args, "promoId");
                 const current = await findPromo(port, promoId);
                 if (!current)
@@ -191,11 +207,11 @@ function setPromoActiveTool(port) {
                 const active = readBoolean(args, "active");
                 const verb = active ? "włączę" : "wyłączę";
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`${verb[0].toUpperCase()}${verb.slice(1)} promocję „${current.name}”.`, {
-                        ...args,
-                        confirmed: true,
-                    });
+                    return gate.preview(`${verb[0].toUpperCase()}${verb.slice(1)} promocję „${current.name}”.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.setPromoActive(promoId, active);
                 return ok(`Promocja „${current.name}” jest teraz ${active ? "aktywna" : "wyłączona"}.`);
             }
@@ -207,12 +223,13 @@ function setPromoActiveTool(port) {
         },
     };
 }
-function removePromoTool(port) {
+function removePromoTool(port, confirmations) {
+    const gate = writeGate("remove_promo", confirmations);
     return {
         name: "remove_promo",
         progress: "Kasuję promocję…",
         description: "Kasuje promocję z biblioteki. Nieodwracalne — właściciel musi przepisać jej nazwę w confirmationPhrase. Żeby tylko zdjąć ją z kanału, użyj set_promo_active.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 promoId: { type: "string", description: "Id promocji z list_promos." },
@@ -221,20 +238,29 @@ function removePromoTool(port) {
             },
             required: ["promoId", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
                 const promoId = readString(args, "promoId");
+                // No confirmationPhrase in the echo: the name is the owner's to type, so a model that
+                // simply sends the echo back cannot delete anything.
+                const echo = { promoId };
+                const refusal = gate.refusal(args, echo);
+                if (refusal)
+                    return refusal;
                 const current = await findPromo(port, promoId);
                 if (!current)
                     return err("not_found", `W tym salonie nie ma promocji o id ${promoId}.`);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Skasuję promocję „${current.name}”. Tego nie da się cofnąć — poproś właściciela o przepisanie nazwy. Jeśli chodzi tylko o zdjęcie z kanału, lepiej ją wyłączyć.`, { promoId, confirmationPhrase: current.name, confirmed: true });
+                    return gate.preview(`Skasuję promocję „${current.name}”. Tego nie da się cofnąć — poproś właścicielkę, żeby sama napisała dokładną nazwę promocji, i wstaw ją w confirmationPhrase. Jeśli chodzi tylko o zdjęcie z kanału, lepiej ją wyłączyć.`, echo);
                 }
                 const phrase = readOptionalString(args, "confirmationPhrase");
                 if (!phrase || !phrasesMatch(phrase, current.name)) {
-                    return err("invalid_arguments", `Aby skasować promocję, właściciel musi przepisać jej nazwę: „${current.name}”.`);
+                    return err("invalid_arguments", `Aby skasować promocję, właścicielka musi sama napisać jej dokładną nazwę: „${current.name}”.`);
                 }
+                const refused = gate.redeem(args, echo);
+                if (refused)
+                    return refused;
                 await port.removePromo(promoId);
                 return ok(`Skasowano promocję „${current.name}”.`);
             }
@@ -265,12 +291,13 @@ function listDiscountCodesTool(port) {
         },
     };
 }
-function addDiscountCodeTool(port) {
+function addDiscountCodeTool(port, confirmations) {
+    const gate = writeGate("add_discount_code", confirmations);
     return {
         name: "add_discount_code",
         progress: "Dodaję kod rabatowy…",
         description: "Dodaje kod rabatowy salonu. Podaj albo percent, albo amountPln — nie oba. Kod nie ma daty ważności ani limitu użyć; działa, dopóki go nie usuniesz.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 code: { type: "string", description: "Treść kodu, którą wpisze klientka." },
@@ -281,9 +308,12 @@ function addDiscountCodeTool(port) {
             },
             required: ["code", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const code = readString(args, "code");
                 const percent = readOptionalNumber(args, "percent");
                 const amountPln = readOptionalNumber(args, "amountPln");
@@ -301,8 +331,11 @@ function addDiscountCodeTool(port) {
                 const value = percent !== undefined ? `${percent}%` : `${amountPln} zł`;
                 const scope = scopeServiceId ? "na jedną usługę" : "na cały salon";
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Dodam kod rabatowy „${code}”: ${value}, ${scope}.`, { ...args, confirmed: true });
+                    return gate.preview(`Dodam kod rabatowy „${code}”: ${value}, ${scope}.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.addDiscountCode({ code, percent, amountPln, scopeServiceId });
                 return ok(`Dodano kod rabatowy „${code}” (${value}, ${scope}).`);
             }
@@ -314,12 +347,13 @@ function addDiscountCodeTool(port) {
         },
     };
 }
-function removeDiscountCodeTool(port) {
+function removeDiscountCodeTool(port, confirmations) {
+    const gate = writeGate("remove_discount_code", confirmations);
     return {
         name: "remove_discount_code",
         progress: "Usuwam kod rabatowy…",
         description: "Usuwa kod rabatowy salonu. Kanister odmówi, dopóki jakakolwiek promocja ten kod rozgłasza — wtedy najpierw zmień promocję.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 code: { type: "string", description: "Treść kodu z list_discount_codes." },
@@ -327,18 +361,24 @@ function removeDiscountCodeTool(port) {
             },
             required: ["code", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         // No confirmation phrase here, unlike a service or a promo: a removed code can simply be
         // added back with the same text, and nothing else in the salon points at it.
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const code = readString(args, "code");
                 const codes = await port.listDiscountCodes();
                 if (!codes.some((entry) => entry.code === code))
                     return err("not_found", `Salon nie ma kodu „${code}”.`);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Usunę kod rabatowy „${code}”.`, { ...args, confirmed: true });
+                    return gate.preview(`Usunę kod rabatowy „${code}”.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.removeDiscountCode(code);
                 return ok(`Usunięto kod rabatowy „${code}”.`);
             }

package/dist/tools/schedule.d.ts

@@ -1,4 +1,5 @@
+import type { TurnConfirmations } from "../confirmations.js";
 import type { SalonCorePort } from "../salon-core-port.js";
 import { type AgentTool } from "../types.js";
-export declare function createScheduleTools(port: SalonCorePort): AgentTool[];
+export declare function createScheduleTools(port: SalonCorePort, confirmations?: TurnConfirmations): AgentTool[];
 //# sourceMappingURL=schedule.d.ts.map

package/dist/tools/schedule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/tools/schedule.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAA8B,KAAK,SAAS,EAAmB,MAAM,aAAa,CAAC;AAqB1F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CASpE"}
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/tools/schedule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAsBtD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,EAAE,CASvG"}

package/dist/tools/schedule.js

@@ -1,7 +1,8 @@
 import { formatMinutesToTime, parseTimeRangesToSlots, parseTimeToMinutes } from "@jsm-mit/sultana-core-motoko-package";
 import { toToolError } from "../errors.js";
-import { err, needsConfirmation, ok } from "../types.js";
+import { err, ok } from "../types.js";
 import { ArgumentError, readBoolean, readOptionalString, readString } from "./args.js";
+import { writeGate } from "./write-gate.js";
 /** 0 = Monday, matching the canister's own day index. */
 const DAY_NAMES_PL = ["poniedziałek", "wtorek", "środa", "czwartek", "piątek", "sobota", "niedziela"];
 const CONFIRMED_FIELD = {
@@ -14,14 +15,14 @@ const RANGES_FIELD = {
     type: "string",
     description: 'Zakresy godzin oddzielone przecinkiem, np. "10-18" albo "9:30-13,14-18".',
 };
-export function createScheduleTools(port) {
+export function createScheduleTools(port, confirmations) {
     return [
         getWeeklyHoursTool(port),
-        setWeeklyHoursTool(port),
+        setWeeklyHoursTool(port, confirmations),
         getDayScheduleTool(port),
-        setDayOffTool(port),
-        setBusyHoursTool(port),
-        clearDailyOverrideTool(port),
+        setDayOffTool(port, confirmations),
+        setBusyHoursTool(port, confirmations),
+        clearDailyOverrideTool(port, confirmations),
     ];
 }
 function getWeeklyHoursTool(port) {
@@ -53,12 +54,13 @@ function getWeeklyHoursTool(port) {
         },
     };
 }
-function setWeeklyHoursTool(port) {
+function setWeeklyHoursTool(port, confirmations) {
+    const gate = writeGate("set_weekly_hours", confirmations);
     return {
         name: "set_weekly_hours",
         progress: "Ustawiam grafik…",
         description: "Ustawia godziny PRACY pracownika w wybranych dniach tygodnia. Zastępuje dotychczasowe godziny w tych dniach. Pusty zakres oznacza dzień niepracujący.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 workerId: WORKER_FIELD,
@@ -72,20 +74,23 @@ function setWeeklyHoursTool(port) {
             },
             required: ["workerId", "days", "ranges", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const worker = await resolveWorker(port, readString(args, "workerId"));
                 const days = readDays(args);
                 const parsed = normalizeRanges(readOptionalString(args, "ranges") ?? "");
                 const dayNames = days.map((day) => DAY_NAMES_PL[day]).join(", ");
                 const hours = parsed.ranges.length === 0 ? "dzień wolny" : formatRanges(parsed.ranges).join(", ");
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Ustawię ${worker.name}: ${dayNames} — ${hours}.${noteSuffix(parsed.notes)}`, {
-                        ...args,
-                        confirmed: true,
-                    });
+                    return gate.preview(`Ustawię ${worker.name}: ${dayNames} — ${hours}.${noteSuffix(parsed.notes)}`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 for (const day of days) {
                     await port.setWeeklyHours(worker.id, day, parsed.ranges);
                 }
@@ -127,24 +132,31 @@ function getDayScheduleTool(port) {
         },
     };
 }
-function setDayOffTool(port) {
+function setDayOffTool(port, confirmations) {
+    const gate = writeGate("set_day_off", confirmations);
     return {
         name: "set_day_off",
         progress: "Ustawiam dzień wolny…",
         description: "Oznacza cały wskazany dzień jako wolny dla pracownika.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: { workerId: WORKER_FIELD, date: DATE_FIELD, confirmed: CONFIRMED_FIELD },
             required: ["workerId", "date", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const worker = await resolveWorker(port, readString(args, "workerId"));
                 const date = readDate(args);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Ustawię ${worker.name} dzień wolny: ${date}.`, { ...args, confirmed: true });
+                    return gate.preview(`Ustawię ${worker.name} dzień wolny: ${date}.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.setDayOff(worker.id, date);
                 return ok(`${worker.name} ma wolne ${date}.`);
             }
@@ -156,19 +168,23 @@ function setDayOffTool(port) {
         },
     };
 }
-function setBusyHoursTool(port) {
+function setBusyHoursTool(port, confirmations) {
+    const gate = writeGate("set_busy_hours", confirmations);
     return {
         name: "set_busy_hours",
         progress: "Zapisuję godziny zajęte…",
         description: "Ustawia godziny ZAJĘTE w konkretnym dniu — nadpisuje grafik tygodniowy tylko tego dnia. Używaj do jednorazowych nieobecności („we wtorek jestem zajęta od 12 do 15”).",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: { workerId: WORKER_FIELD, date: DATE_FIELD, ranges: RANGES_FIELD, confirmed: CONFIRMED_FIELD },
             required: ["workerId", "date", "ranges", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const worker = await resolveWorker(port, readString(args, "workerId"));
                 const date = readDate(args);
                 const parsed = normalizeRanges(readString(args, "ranges"));
@@ -177,11 +193,11 @@ function setBusyHoursTool(port) {
                 }
                 const hours = formatRanges(parsed.ranges).join(", ");
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Zaznaczę ${worker.name} jako zajętą ${date}: ${hours}.${noteSuffix(parsed.notes)}`, {
-                        ...args,
-                        confirmed: true,
-                    });
+                    return gate.preview(`Zaznaczę ${worker.name} jako zajętą ${date}: ${hours}.${noteSuffix(parsed.notes)}`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.setDailyBusy(worker.id, date, parsed.ranges);
                 return ok(`${worker.name}, ${date}: zajęte ${hours}.${noteSuffix(parsed.notes)}`);
             }
@@ -193,27 +209,31 @@ function setBusyHoursTool(port) {
         },
     };
 }
-function clearDailyOverrideTool(port) {
+function clearDailyOverrideTool(port, confirmations) {
+    const gate = writeGate("clear_daily_override", confirmations);
     return {
         name: "clear_daily_override",
         progress: "Przywracam grafik tygodniowy…",
         description: "Usuwa nadpisanie dla wskazanego dnia — od tej chwili obowiązuje zwykły grafik tygodniowy.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: { workerId: WORKER_FIELD, date: DATE_FIELD, confirmed: CONFIRMED_FIELD },
             required: ["workerId", "date", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
+                const refusal = gate.refusal(args);
+                if (refusal)
+                    return refusal;
                 const worker = await resolveWorker(port, readString(args, "workerId"));
                 const date = readDate(args);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Usunę nadpisanie dnia ${date} dla ${worker.name} — wróci grafik tygodniowy.`, {
-                        ...args,
-                        confirmed: true,
-                    });
+                    return gate.preview(`Usunę nadpisanie dnia ${date} dla ${worker.name} — wróci grafik tygodniowy.`, args);
                 }
+                const refused = gate.redeem(args);
+                if (refused)
+                    return refused;
                 await port.clearDailyOverride(worker.id, date);
                 return ok(`${worker.name}, ${date}: wrócił grafik tygodniowy.`);
             }

package/dist/tools/services.d.ts

@@ -1,6 +1,7 @@
+import type { TurnConfirmations } from "../confirmations.js";
 import type { SalonAccess, SalonCorePort } from "../salon-core-port.js";
 import { type AgentTool } from "../types.js";
-export declare function createServiceTools(port: SalonCorePort): AgentTool[];
+export declare function createServiceTools(port: SalonCorePort, confirmations?: TurnConfirmations): AgentTool[];
 /** `access` must match the port: `"public"` only for a port that reads the visitor's view. */
 export declare function listServicesTool(port: SalonCorePort, access?: SalonAccess): AgentTool;
 export declare function findServiceTypeTool(port: SalonCorePort): AgentTool;

package/dist/tools/services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/tools/services.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAkC,MAAM,uBAAuB,CAAC;AACxG,OAAO,EAA8B,KAAK,SAAS,EAAmB,MAAM,aAAa,CAAC;AAoB1F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,CASnE;AAoBD,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,WAAqB,GAAG,SAAS,CAmB9F;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAiClE"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/tools/services.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAkC,MAAM,uBAAuB,CAAC;AACxG,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAwBtD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,EAAE,CAStG;AAoBD,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,GAAE,WAAqB,GAAG,SAAS,CAmB9F;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAiClE"}

package/dist/tools/services.js

@@ -1,18 +1,21 @@
 import { toToolError } from "../errors.js";
-import { err, needsConfirmation, ok } from "../types.js";
+import { err, ok } from "../types.js";
 import { ArgumentError, normalizeDuration, normalizePrice, phrasesMatch, readBoolean, readNumber, readOptionalNumber, readOptionalString, readOptionalStringArray, readString, } from "./args.js";
+import { writeGate } from "./write-gate.js";
 const CONFIRMED_FIELD = {
     type: "boolean",
     description: "false dla podglądu: narzędzie nic nie zapisze i odda opis zmiany do zatwierdzenia przez właściciela. true dopiero po tym, jak właściciel potwierdzi.",
 };
-export function createServiceTools(port) {
+/** The fields of a service a model may set — what `update_service` echoes back when it was sent. */
+const SERVICE_FIELDS = ["name", "pricePln", "durationMinutes", "serviceTypeIds", "workerIds", "active"];
+export function createServiceTools(port, confirmations) {
     return [
         listServicesTool(port),
         findServiceTypeTool(port),
         listWorkersTool(port),
-        addServiceTool(port),
-        updateServiceTool(port),
-        removeServiceTool(port),
+        addServiceTool(port, confirmations),
+        updateServiceTool(port, confirmations),
+        removeServiceTool(port, confirmations),
     ];
 }
 /** What the model reads about the list depends on whose view the port returns: a public read has
@@ -102,12 +105,13 @@ function listWorkersTool(port) {
         },
     };
 }
-function addServiceTool(port) {
+function addServiceTool(port, confirmations) {
+    const gate = writeGate("add_service", confirmations);
     return {
         name: "add_service",
         progress: "Dodaję usługę…",
         description: "Dodaje nową usługę do katalogu salonu. Najpierw ustal typ usługi przez find_service_type i pracowników przez list_workers.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 name: { type: "string", description: "Nazwa usługi widoczna dla klientek." },
@@ -128,17 +132,23 @@ function addServiceTool(port) {
             },
             required: ["name", "pricePln", "durationMinutes", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
-                const draft = await buildDraft(port, args, null);
+                // The echo is the draft laid over the model's own arguments, and a draft read from an
+                // echo is that echo again — resending either one confirms the same change.
+                const draft = readDraft(args, null);
+                const echo = { ...args, ...draft.input };
+                const refusal = gate.refusal(args, echo);
+                if (refusal)
+                    return refusal;
+                await assertDraftReferences(port, draft.input);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Dodam usługę: ${await describe(port, draft.input)}.${noteSuffix(draft.notes)}`, {
-                        ...args,
-                        ...draft.input,
-                        confirmed: true,
-                    });
+                    return gate.preview(`Dodam usługę: ${await describe(port, draft.input)}.${noteSuffix(draft.notes)}`, echo);
                 }
+                const refused = gate.redeem(args, echo);
+                if (refused)
+                    return refused;
                 const serviceId = await port.addService(draft.input);
                 return ok(`Dodano usługę „${draft.input.name}”.${noteSuffix(draft.notes)}`, { serviceId });
             }
@@ -150,12 +160,13 @@ function addServiceTool(port) {
         },
     };
 }
-function updateServiceTool(port) {
+function updateServiceTool(port, confirmations) {
+    const gate = writeGate("update_service", confirmations);
     return {
         name: "update_service",
         progress: "Zmieniam usługę…",
         description: "Zmienia istniejącą usługę. Podaj tylko te pola, które mają się zmienić — reszta zostanie zachowana. Id weź z list_services.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 salonServiceId: { type: "string", description: "Id usługi z list_services." },
@@ -169,17 +180,27 @@ function updateServiceTool(port) {
             },
             required: ["salonServiceId", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
                 const serviceId = readString(args, "salonServiceId");
+                const echo = requestedServiceChange(serviceId, args);
+                const refusal = gate.refusal(args, echo);
+                if (refusal)
+                    return refusal;
                 const current = await findService(port, serviceId);
                 if (!current)
                     return err("not_found", `W tym salonie nie ma usługi o id ${serviceId}.`);
-                const draft = await buildDraft(port, args, current);
+                // The summary shows the merged record the owner will end up with; the write merges
+                // again onto the record as it is by then.
+                const draft = readDraft(args, current);
+                await assertDraftReferences(port, draft.input);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Zmienię usługę „${current.name}” na: ${await describe(port, draft.input)}.${noteSuffix(draft.notes)}`, { ...args, ...draft.input, confirmed: true });
+                    return gate.preview(`Zmienię usługę „${current.name}” na: ${await describe(port, draft.input)}.${noteSuffix(draft.notes)}`, echo);
                 }
+                const refused = gate.redeem(args, echo);
+                if (refused)
+                    return refused;
                 await port.updateService(serviceId, draft.input);
                 return ok(`Zmieniono usługę „${draft.input.name}”.${noteSuffix(draft.notes)}`);
             }
@@ -191,12 +212,13 @@ function updateServiceTool(port) {
         },
     };
 }
-function removeServiceTool(port) {
+function removeServiceTool(port, confirmations) {
+    const gate = writeGate("remove_service", confirmations);
     return {
         name: "remove_service",
         progress: "Usuwam usługę…",
         description: "Usuwa usługę z katalogu. Operacja jest nieodwracalna — właściciel musi przepisać dokładną nazwę usługi w polu confirmationPhrase.",
-        parameters: {
+        parameters: gate.parameters({
             type: "object",
             properties: {
                 salonServiceId: { type: "string", description: "Id usługi z list_services." },
@@ -205,20 +227,29 @@ function removeServiceTool(port) {
             },
             required: ["salonServiceId", "confirmed"],
             additionalProperties: false,
-        },
+        }),
         execute: async (args) => {
             try {
                 const serviceId = readString(args, "salonServiceId");
+                // No confirmationPhrase in the echo: the name is the owner's to type, so a model that
+                // simply sends the echo back cannot delete anything.
+                const echo = { salonServiceId: serviceId };
+                const refusal = gate.refusal(args, echo);
+                if (refusal)
+                    return refusal;
                 const current = await findService(port, serviceId);
                 if (!current)
                     return err("not_found", `W tym salonie nie ma usługi o id ${serviceId}.`);
                 if (!readBoolean(args, "confirmed")) {
-                    return needsConfirmation(`Usunę usługę „${current.name}” (${current.pricePln} zł, ${current.durationMinutes} min). Tego nie da się cofnąć — poproś właściciela o przepisanie nazwy usługi.`, { salonServiceId: serviceId, confirmationPhrase: current.name, confirmed: true });
+                    return gate.preview(`Usunę usługę „${current.name}” (${current.pricePln} zł, ${current.durationMinutes} min). Tego nie da się cofnąć — poproś właścicielkę, żeby sama napisała dokładną nazwę usługi, i wstaw ją w confirmationPhrase.`, echo);
                 }
                 const phrase = readOptionalString(args, "confirmationPhrase");
                 if (!phrase || !phrasesMatch(phrase, current.name)) {
-                    return err("invalid_arguments", `Aby usunąć usługę, właściciel musi przepisać jej nazwę: „${current.name}”.`);
+                    return err("invalid_arguments", `Aby usunąć usługę, właścicielka musi sama napisać jej dokładną nazwę: „${current.name}”.`);
                 }
+                const refused = gate.redeem(args, echo);
+                if (refused)
+                    return refused;
                 await port.removeService(serviceId);
                 return ok(`Usunięto usługę „${current.name}”.`);
             }
@@ -230,12 +261,23 @@ function removeServiceTool(port) {
         },
     };
 }
+/** `update_service`'s echo: the id and only the fields the model sent, as it sent them — never the
+ * merged record, which would pin fields the owner did not mention to what they were at preview. */
+function requestedServiceChange(serviceId, args) {
+    const change = { salonServiceId: serviceId };
+    for (const field of SERVICE_FIELDS) {
+        if (args[field] !== undefined && args[field] !== null)
+            change[field] = args[field];
+    }
+    return change;
+}
 /**
- * Builds the full record the canister needs. `current` is null for a new service and the existing
- * record for an edit — **this merge is the whole point**: `updateSalonService` replaces every
- * field, so a "just the price" call that forgot `workerIds` would unassign the entire team.
+ * Builds the full record the canister needs, without calling it. `current` is null for a new
+ * service and the existing record for an edit — **this merge is the whole point**:
+ * `updateSalonService` replaces every field, so a "just the price" call that forgot `workerIds`
+ * would unassign the entire team.
  */
-async function buildDraft(port, args, current) {
+function readDraft(args, current) {
     const notes = [];
     const name = current ? (readOptionalString(args, "name") ?? current.name) : readString(args, "name");
     const rawPrice = readOptionalNumber(args, "pricePln");
@@ -249,10 +291,12 @@ async function buildDraft(port, args, current) {
     const serviceTypeIds = readOptionalStringArray(args, "serviceTypeIds") ?? current?.serviceTypeIds ?? [];
     const workerIds = readOptionalStringArray(args, "workerIds") ?? current?.workerIds ?? [];
     const active = args.active === undefined || args.active === null ? (current?.active ?? true) : readBoolean(args, "active");
-    await assertKnownServiceTypes(port, serviceTypeIds);
-    await assertKnownWorkers(port, workerIds);
     return { input: { name, pricePln: price, durationMinutes: duration, active, serviceTypeIds, workerIds }, notes };
 }
+async function assertDraftReferences(port, input) {
+    await assertKnownServiceTypes(port, input.serviceTypeIds);
+    await assertKnownWorkers(port, input.workerIds);
+}
 function normalizeOrNote(normalized, notes) {
     if (normalized.note)
         notes.push(normalized.note);

package/dist/tools/write-gate.d.ts

@@ -0,0 +1,29 @@
+import type { TurnConfirmations } from "../confirmations.js";
+import { type ToolParametersSchema, type ToolResult } from "../types.js";
+/**
+ * The confirmation protocol of ONE write tool, in one place for all of them.
+ *
+ * `echo` is the change as the tool describes it back to the model — the arguments to send again
+ * with `confirmed: true`; it defaults to `args` itself. A tool must build it from `args` the same
+ * way on both calls, and building it from an echo must give that echo back, so a model that resends
+ * its own arguments and a model that resends the echo confirm the same change.
+ *
+ * Without a ledger the gate lets every `confirmed: true` through, which is the protocol as it was
+ * before the ledger: the rule then lives in the persona only.
+ */
+export interface WriteGate {
+    /** The tool's schema, with `confirmationId` added when the tool set has a ledger. */
+    parameters(schema: ToolParametersSchema): ToolParametersSchema;
+    /** The `confirmed: false` answer: `echo` goes back with `confirmed: true` and, with a ledger,
+     * the id of this preview. */
+    preview(summary: string, echo: Record<string, unknown>): ToolResult;
+    /** Run first, before any canister call. For a `confirmed: true` call whose id would not redeem,
+     * the refusal to return; otherwise `null`. Does not use the id up, so a write that then fails
+     * on its arguments (a mistyped name, say) can be retried with the same id. */
+    refusal(args: Record<string, unknown>, echo?: Record<string, unknown>): ToolResult | null;
+    /** Run right before the write: uses the id up. `null` lets the write go ahead; a refusal here
+     * means a parallel call used the id first, or the preview expired in the meantime. */
+    redeem(args: Record<string, unknown>, echo?: Record<string, unknown>): ToolResult | null;
+}
+export declare function writeGate(toolName: string, confirmations: TurnConfirmations | undefined): WriteGate;
+//# sourceMappingURL=write-gate.d.ts.map

package/dist/tools/write-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-gate.d.ts","sourceRoot":"","sources":["../../src/tools/write-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqC,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAChG,OAAO,EAA0B,KAAK,oBAAoB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAkBjG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACtB,qFAAqF;IACrF,UAAU,CAAC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAC/D;iCAC6B;IAC7B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAAC;IACpE;;kFAE8E;IAC9E,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,GAAG,IAAI,CAAC;IAC1F;0FACsF;IACtF,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,GAAG,IAAI,CAAC;CAC5F;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,iBAAiB,GAAG,SAAS,GAAG,SAAS,CA6BnG"}

package/dist/tools/write-gate.js

@@ -0,0 +1,37 @@
+import { err, needsConfirmation } from "../types.js";
+import { readBoolean, readOptionalString } from "./args.js";
+const CONFIRMATION_ID_FIELD = {
+    type: "string",
+    description: "Id z podglądu (confirmed=false). Wymagane przy confirmed=true.",
+};
+const NO_PREVIEW = "Brak ważnego podglądu tej zmiany — wywołaj narzędzie z confirmed=false i pokaż właścicielce podsumowanie.";
+const REFUSALS = {
+    missing: NO_PREVIEW,
+    unknown: NO_PREVIEW,
+    expired: NO_PREVIEW,
+    same_turn: "Zgoda musi przyjść w osobnej wiadomości właścicielki — najpierw pokaż podsumowanie i poczekaj na odpowiedź.",
+    mismatch: "Argumenty różnią się od pokazanego podglądu — pokaż nowy podgląd (confirmed=false).",
+};
+export function writeGate(toolName, confirmations) {
+    const decide = (args, verdict) => {
+        if (!confirmations || !readBoolean(args, "confirmed"))
+            return null;
+        const result = verdict(confirmations, readOptionalString(args, "confirmationId"));
+        return result.ok ? null : err("invalid_arguments", REFUSALS[result.reason]);
+    };
+    return {
+        parameters: (schema) => {
+            if (!confirmations)
+                return schema;
+            return { ...schema, properties: { ...schema.properties, confirmationId: CONFIRMATION_ID_FIELD } };
+        },
+        preview: (summary, echo) => {
+            if (!confirmations)
+                return needsConfirmation(summary, { ...echo, confirmed: true });
+            const confirmationId = confirmations.issue(toolName, echo);
+            return needsConfirmation(summary, { ...echo, confirmed: true, confirmationId });
+        },
+        refusal: (args, echo = args) => decide(args, (turn, confirmationId) => turn.check(toolName, echo, confirmationId)),
+        redeem: (args, echo = args) => decide(args, (turn, confirmationId) => turn.redeem(toolName, echo, confirmationId)),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jsm-mit/sultana-agent-tools-package",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Agent tool layer for a Sultana salon: framework-agnostic tools (services, promos, schedule) over the Sultana core canister wrapper, plus a read-only set that needs no identity.",
     "homepage": "https://github.com/JSM-Sultana/sultana-agent-tools-package#readme",
     "bugs": {
@@ -36,7 +36,7 @@
     },
     "dependencies": {
         "@icp-sdk/core": "^6.1.0",
-        "@jsm-mit/sultana-core-motoko-package": "^0.16.0"
+        "@jsm-mit/sultana-core-motoko-package": "^0.17.0"
     },
     "devDependencies": {
         "@jsm-mit/utils-package": "^0.5.0",