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

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
@@ -51,6 +54,7 @@ export function listServicesTool(port, access = "owner") {
         },
     };
 }
+/** Takes any port that can search the catalogue — the customer set shares this tool. */
 export function findServiceTypeTool(port) {
     return {
         name: "find_service_type",
@@ -102,12 +106,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 +133,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 +161,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 +181,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 +213,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 +228,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 +262,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 +292,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,7 +1,7 @@
 {
     "name": "@jsm-mit/sultana-agent-tools-package",
-    "version": "0.2.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.",
+    "version": "0.4.0",
+    "description": "Agent tool layer for Sultana: framework-agnostic tools over the Sultana core canister wrapper — a salon owner's set (services, promos, schedule) and a customer's set (search, free times, booking), each with a read-only set that needs no identity.",
     "homepage": "https://github.com/JSM-Sultana/sultana-agent-tools-package#readme",
     "bugs": {
         "url": "https://github.com/JSM-Sultana/sultana-agent-tools-package/issues"
@@ -31,12 +31,13 @@
         "sandbox": "npx tsx --env-file-if-exists=.env sandbox/main.ts",
         "prepare": "npm run build",
         "test-tools": "npx tsx --env-file-if-exists=.env --test tests/integration/test-salon-tools.ts",
+        "test-customer-tools": "npx tsx --env-file-if-exists=.env --test tests/integration/test-customer-tools.ts",
         "whoami": "npx tsx --env-file-if-exists=.env sandbox/whoami.ts",
         "publish-public": "bash scripts/publish-public.sh"
     },
     "dependencies": {
         "@icp-sdk/core": "^6.1.0",
-        "@jsm-mit/sultana-core-motoko-package": "^0.16.0"
+        "@jsm-mit/sultana-core-motoko-package": "^0.21.1"
     },
     "devDependencies": {
         "@jsm-mit/utils-package": "^0.5.0",