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

package/README.md

@@ -0,0 +1,133 @@
+# sultana-agent-tools-package
+
+`@jsm-mit/sultana-agent-tools-package` — the tool layer that lets an LLM agent edit a Sultana
+salon by conversation: services, promos and working hours.
+
+It is **framework-agnostic**. A tool is `{ name, description, parameters, progress, execute }`, which is what
+OpenAI, Anthropic and `@jsm-mit/chat-agent-package` all want from a function tool, so wiring this
+into an agent host is registration rather than translation. The package depends on the published
+canister wrapper and nothing else — no model provider, no agent framework.
+
+## Use
+
+```ts
+import { createSalonTools, SALON_AGENT_PERSONA_PL } from "@jsm-mit/sultana-agent-tools-package";
+
+const tools = createSalonTools({
+    canisterId: process.env.SULTANA_CORE_CANISTER_ID!,
+    identity,           // the salon owner's identity (or, later, a granted agent principal)
+    salonId,
+});
+```
+
+`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.
+
+### Read-only set
+
+An assistant that runs without the owner's identity takes the read-only set and its own persona:
+
+```ts
+import { createSalonReadTools, SALON_READ_PERSONA_PL } from "@jsm-mit/sultana-agent-tools-package";
+
+const tools = createSalonReadTools({
+    canisterId: process.env.SULTANA_CORE_CANISTER_ID!,
+    salonId,            // no identity: every call is a public query, made anonymously
+});
+```
+
+It holds `list_services`, `list_promos` and `find_service_type` — nothing that writes. The port
+behind it is built with `access: "public"`, so `list_services` calls the visitor's query: a
+visitor, and so this agent, sees **ACTIVE services and ACTIVE promos only** (and no worker who has
+not claimed their account). The two list tools say so in their description and summary, and
+`SALON_READ_PERSONA_PL` tells the model to mention it and to send edits to the "Usługi" and
+"Promocje" panel pages. No identity is needed; if a host passes the owner's anyway, the port still
+drops inactive promos, so the tool keeps its promise.
+
+`createSalonReadToolsFromPort(port)` is the same set over any port, for tests.
+
+## Tools
+
+Every tool carries `progress` — a short Polish line in the present continuous, ending with "…",
+that a chat shows while the tool runs (`@jsm-mit/chat-agent-package` reads `Tool.progress`). It is
+never sent to the model. A write tool previewing with `confirmed: false` shows the same line.
+
+| tool | writes | progress |
+|---|---|---|
+| `list_services` | | Sprawdzam listę usług… |
+| `find_service_type` | | Szukam typu usługi… |
+| `list_workers` | | Sprawdzam zespół… |
+| `add_service` | yes | Dodaję usługę… |
+| `update_service` | yes | Zmieniam usługę… |
+| `remove_service` | yes | Usuwam usługę… |
+| `get_weekly_hours` | | Sprawdzam grafik tygodniowy… |
+| `set_weekly_hours` | yes | Ustawiam grafik… |
+| `get_day_schedule` | | Sprawdzam grafik na ten dzień… |
+| `set_day_off` | yes | Ustawiam dzień wolny… |
+| `set_busy_hours` | yes | Zapisuję godziny zajęte… |
+| `clear_daily_override` | yes | Przywracam grafik tygodniowy… |
+| `list_media` | | Sprawdzam bibliotekę materiałów… |
+| `list_promos` | | Sprawdzam promocje… |
+| `add_promo` | yes | Zakładam promocję… |
+| `update_promo` | yes | Zmieniam promocję… |
+| `set_promo_active` | yes | Zmieniam status promocji… |
+| `remove_promo` | yes | Kasuję promocję… |
+| `list_discount_codes` | | Sprawdzam kody rabatowe… |
+| `add_discount_code` | yes | Dodaję kod rabatowy… |
+| `remove_discount_code` | yes | Usuwam kod rabatowy… |
+
+`createSalonTools` returns all 21; `createSalonReadTools` returns `list_services`, `list_promos`
+and `find_service_type`.
+
+## What the tools guarantee
+
+- **`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.
+- **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.
+- **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
+  frontends, and a write with an unknown id is refused before the canister is called.
+
+## Scripts
+
+| script | what it does |
+|---|---|
+| `npm run build` | `tsc` for `dist/`, then a type-check over tests and sandbox |
+| `npm test` | unit tests against an in-memory salon — no replica, no network |
+| `npm run whoami` | setup check: the identity, its salons, the service-type catalogue |
+| `npm run sandbox -- --fake` | talk to the tools against an in-memory salon |
+| `npm run sandbox` | the same conversation against a real canister |
+| `npm run test-tools` | the round trip against a live canister (creates its own salon) |
+| `npm run publish-public` | publishes to npm from master — see below |
+
+## Testing by talking
+
+`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.
+
+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
+that identity owns on that canister — one of which is your `SULTANA_SALON_ID` — and whether the
+service-type catalogue is seeded at all. `npm run test-tools` is the deterministic version of that: every write tool against
+a live canister, each verified by reading it back. Both talk to a canister, so **a human starts
+them, not Claude**.
+
+## Publishing
+
+Bump `version` in `package.json` by hand, then `npm run publish-public` from `master`. The script
+refuses a `master` that differs from `origin/master`, any uncommitted change besides the version
+bump, and a version already on the registry. It builds from a clean `dist/`, runs the unit
+tests, publishes with `--access public`, and only then commits "Version bump to <version>" and
+pushes `master` — so a failed publish leaves nothing claiming a release. A version whose bump is
+already committed publishes without a new commit.
+
+There is no canister-commit stamp: this package wraps no canister of its own. The tarball holds
+`dist/`, `README.md` and `package.json` — no tests, no sandbox, no `.env`.

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

@@ -0,0 +1,37 @@
+import type { Identity } from "@icp-sdk/core/agent";
+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"> {
+    /** Language of service-type labels. Defaults to Polish. */
+    language?: string;
+}
+/**
+ * Builds the tool set for ONE salon. `salonId` is captured here and never appears as a tool
+ * argument, so a model holding these tools cannot reach another salon's data whatever it sends.
+ */
+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 interface CreateSalonReadToolsOptions {
+    canisterId: string;
+    salonId: string;
+    /**
+     * Omit it — the read set is built for a host that holds no owner identity, and every call it
+     * makes is a public query. With the owner's identity the canister would show the whole promo
+     * library; the port drops inactive promos in public access, so the tools still keep their word.
+     */
+    identity?: Identity;
+    /** Language of service-type labels. Defaults to Polish. */
+    language?: string;
+}
+/**
+ * The read-only tool set for ONE salon: `list_services`, `list_promos` and `find_service_type`,
+ * nothing that writes. Reads what a visitor sees — ACTIVE services and ACTIVE promos only — so an
+ * assistant can run without the owner's identity.
+ */
+export declare function createSalonReadTools(options: CreateSalonReadToolsOptions): AgentTool[];
+/** The read-only set over any port. The port must return the public view — the tool texts tell the
+ * model that inactive services and promos are not in the lists. */
+export declare function createSalonReadToolsFromPort(port: SalonCorePort): AgentTool[];
+//# sourceMappingURL=create-salon-tools.d.ts.map

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

@@ -0,0 +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"}

package/dist/create-salon-tools.js

@@ -0,0 +1,30 @@
+import { IcSalonCorePort } from "./ic-salon-core-port.js";
+import { createPromoTools, listPromosTool } from "./tools/promos.js";
+import { createScheduleTools } from "./tools/schedule.js";
+import { createServiceTools, findServiceTypeTool, listServicesTool } from "./tools/services.js";
+/**
+ * Builds the tool set for ONE salon. `salonId` is captured here and never appears as a tool
+ * 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);
+}
+/** 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)];
+}
+/**
+ * The read-only tool set for ONE salon: `list_services`, `list_promos` and `find_service_type`,
+ * nothing that writes. Reads what a visitor sees — ACTIVE services and ACTIVE promos only — so an
+ * assistant can run without the owner's identity.
+ */
+export function createSalonReadTools(options) {
+    const port = new IcSalonCorePort({ ...options, language: options.language ?? "pl", access: "public" });
+    return createSalonReadToolsFromPort(port);
+}
+/** The read-only set over any port. The port must return the public view — the tool texts tell the
+ * model that inactive services and promos are not in the lists. */
+export function createSalonReadToolsFromPort(port) {
+    return [listServicesTool(port, "public"), listPromosTool(port, "public"), findServiceTypeTool(port)];
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+import { type ToolResult } from "./types.js";
+/**
+ * Maps what the canister wrapper throws onto a tool result. The wrapper has exactly three failure
+ * shapes (see `ActorBase.executeFunctionAsyncUnsafe`): a decoded business error, a rejection by
+ * `system func inspect`, and everything else.
+ *
+ * `fallbackSummary` is what the agent reads when the canister gives us nothing better — write it
+ * in the language the agent speaks to the owner.
+ */
+export declare function toToolError(error: unknown, fallbackSummary: string): ToolResult;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAQtE;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,GAAG,UAAU,CAsB/E"}

package/dist/errors.js

@@ -0,0 +1,39 @@
+import { err } from "./types.js";
+/**
+ * Maps what the canister wrapper throws onto a tool result. The wrapper has exactly three failure
+ * shapes (see `ActorBase.executeFunctionAsyncUnsafe`): a decoded business error, a rejection by
+ * `system func inspect`, and everything else.
+ *
+ * `fallbackSummary` is what the agent reads when the canister gives us nothing better — write it
+ * in the language the agent speaks to the owner.
+ */
+export function toToolError(error, fallbackSummary) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = (error instanceof Error ? error.cause : undefined);
+    if (message === "CallRefusedAtInspectionStage") {
+        return err("quota_exceeded", "Kanister odrzucił wywołanie przed wykonaniem — najczęściej wyczerpany dzienny limit akcji albo zbyt duży ładunek.");
+    }
+    if (message === "CriticalCanisterError") {
+        return err("unavailable", "Brak łączności z kanistrem albo kanister przerwał wykonanie. Spróbuj ponownie za chwilę.");
+    }
+    if (message === "CanisterError") {
+        const detail = cause?.errorMessage?.trim();
+        const code = mapErrorKey(cause?.errorKey);
+        return err(code, detail ? `${fallbackSummary} (${detail})` : fallbackSummary);
+    }
+    return err("canister_error", fallbackSummary);
+}
+function mapErrorKey(errorKey) {
+    switch (errorKey) {
+        case "NotAuthorized":
+            return "not_authorized";
+        case "NotFound":
+        case "ReturnsNull":
+            return "not_found";
+        case "InvalidData":
+        case "AlreadyExists":
+            return "invalid_arguments";
+        default:
+            return "canister_error";
+    }
+}

package/dist/ic-salon-core-port.d.ts

@@ -0,0 +1,57 @@
+import type { Identity } from "@icp-sdk/core/agent";
+import type { DiscountCodeInput, DiscountCodeView, MediaView, PromoView, PromoWriteInput, SalonAccess, SalonCorePort, TimeRange, ServiceTypeView, ServiceView, ServiceWriteInput, WorkerView } from "./salon-core-port.js";
+export interface IcSalonCorePortOptions {
+    canisterId: string;
+    /** Omit for an anonymous identity — every write will then be refused, which is only useful in
+     * a read-only demo. */
+    identity?: Identity;
+    salonId: string;
+    /** Language of service-type labels the agent sees and quotes back to the owner. */
+    language: string;
+    /**
+     * Which services endpoint `listServices` reads. `"owner"` (the default) is the owner-only
+     * query — the whole catalogue. `"public"` is the visitor's query: no identity needed, ACTIVE
+     * services only, and without workers who have not claimed their account yet. Every other
+     * method is the same in both.
+     */
+    access?: SalonAccess;
+}
+/**
+ * The port over the published canister wrapper. Conversions live here and nowhere else: the
+ * canister speaks `bigint` and `Principal`, the tools speak numbers and strings.
+ */
+export declare class IcSalonCorePort implements SalonCorePort {
+    private readonly salonId;
+    private readonly language;
+    private readonly access;
+    private readonly services;
+    private readonly hr;
+    private readonly serviceTypes;
+    private readonly availability;
+    private readonly assets;
+    private readonly promo;
+    private readonly discountCodes;
+    constructor(options: IcSalonCorePortOptions);
+    listServices(): Promise<ServiceView[]>;
+    addService(input: ServiceWriteInput): Promise<string>;
+    updateService(serviceId: string, input: ServiceWriteInput): Promise<void>;
+    removeService(serviceId: string): Promise<void>;
+    listWorkers(): Promise<WorkerView[]>;
+    findServiceTypes(query: string): Promise<ServiceTypeView[]>;
+    getWeeklyHours(workerId: string, day: number): Promise<TimeRange[]>;
+    setWeeklyHours(workerId: string, day: number, ranges: TimeRange[]): Promise<void>;
+    getDailyBusy(workerId: string, date: string): Promise<TimeRange[]>;
+    setDailyBusy(workerId: string, date: string, ranges: TimeRange[]): Promise<void>;
+    setDayOff(workerId: string, date: string): Promise<void>;
+    clearDailyOverride(workerId: string, date: string): Promise<void>;
+    listMedia(): Promise<MediaView[]>;
+    listPromos(): Promise<PromoView[]>;
+    addPromo(input: PromoWriteInput): Promise<string>;
+    updatePromo(promoId: string, input: PromoWriteInput): Promise<void>;
+    setPromoActive(promoId: string, active: boolean): Promise<void>;
+    removePromo(promoId: string): Promise<void>;
+    listDiscountCodes(): Promise<DiscountCodeView[]>;
+    addDiscountCode(input: DiscountCodeInput): Promise<void>;
+    removeDiscountCode(code: string): Promise<void>;
+}
+//# sourceMappingURL=ic-salon-core-port.d.ts.map

package/dist/ic-salon-core-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ic-salon-core-port.d.ts","sourceRoot":"","sources":["../src/ic-salon-core-port.ts"],"names":[],"mappings":"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"}

package/dist/ic-salon-core-port.js

@@ -0,0 +1,160 @@
+import { Principal } from "@icp-sdk/core/principal";
+import { AssetsActor, AvailabilityActor, DiscountCodesActor, filterServiceTypes, HrActor, PromoActor, promoMusicOf, SalonServicesActor, ServiceTypesActor, } from "@jsm-mit/sultana-core-motoko-package";
+/**
+ * The port over the published canister wrapper. Conversions live here and nowhere else: the
+ * canister speaks `bigint` and `Principal`, the tools speak numbers and strings.
+ */
+export class IcSalonCorePort {
+    salonId;
+    language;
+    access;
+    services;
+    hr;
+    serviceTypes;
+    availability;
+    assets;
+    promo;
+    discountCodes;
+    constructor(options) {
+        this.salonId = options.salonId;
+        this.language = options.language;
+        this.access = options.access ?? "owner";
+        this.services = new SalonServicesActor(options.canisterId, options.identity);
+        this.hr = new HrActor(options.canisterId, options.identity);
+        this.serviceTypes = new ServiceTypesActor(options.canisterId, options.identity);
+        this.availability = new AvailabilityActor(options.canisterId, options.identity);
+        this.assets = new AssetsActor(options.canisterId, options.identity);
+        this.promo = new PromoActor(options.canisterId, options.identity);
+        this.discountCodes = new DiscountCodesActor(options.canisterId, options.identity);
+    }
+    async listServices() {
+        // Both queries return the same candid record, so one mapping serves both.
+        const services = this.access === "public"
+            ? await this.services.getSalonServicesPublicAsyncUnsafe(this.salonId)
+            : await this.services.getSalonServicesBySalonIdAsyncUnsafe(this.salonId);
+        return services.map((service) => ({
+            id: service.id,
+            name: service.name,
+            pricePln: Number(service.price),
+            durationMinutes: Number(service.duration),
+            active: service.active,
+            serviceTypeIds: [...service.serviceTypeIds],
+            workerIds: service.workerIds.map((worker) => worker.toText()),
+        }));
+    }
+    async addService(input) {
+        return this.services.addSalonServiceAsyncUnsafe(input.active, BigInt(input.durationMinutes), input.name, BigInt(input.pricePln), this.salonId, input.serviceTypeIds, input.workerIds);
+    }
+    async updateService(serviceId, input) {
+        await this.services.updateSalonServiceAsyncUnsafe(input.active, BigInt(input.durationMinutes), input.name, BigInt(input.pricePln), serviceId, input.serviceTypeIds, input.workerIds);
+    }
+    async removeService(serviceId) {
+        await this.services.removeSalonServiceAsyncUnsafe(serviceId);
+    }
+    async listWorkers() {
+        const workers = await this.hr.getWorkersBySalonIdAsyncUnsafe(this.salonId);
+        return workers.map((worker) => ({
+            id: worker.id.toText(),
+            name: worker.name,
+            // A pending code means the placeholder principal is still waiting to be claimed. The
+            // owner can already assign and schedule against it, so it is a usable worker either way.
+            linked: worker.pendingCode === undefined,
+        }));
+    }
+    async findServiceTypes(query) {
+        const catalog = await this.serviceTypes.getServiceTypesCatalogAsyncUnsafe(this.language);
+        return filterServiceTypes(catalog, query).map((entry) => ({
+            id: entry.id,
+            label: entry.text,
+            category: entry.category,
+        }));
+    }
+    async getWeeklyHours(workerId, day) {
+        return this.availability.getDayFromWeeklyTemplateAsyncUnsafe(BigInt(day), this.salonId, Principal.fromText(workerId));
+    }
+    async setWeeklyHours(workerId, day, ranges) {
+        await this.availability.setWeeklyTemplateAsyncUnsafe(BigInt(day), ranges, this.salonId, Principal.fromText(workerId));
+    }
+    async getDailyBusy(workerId, date) {
+        return this.availability.getDailyScheduleAsyncUnsafe(date, Principal.fromText(workerId));
+    }
+    async setDailyBusy(workerId, date, ranges) {
+        await this.availability.setDailyScheduleAsyncUnsafe(date, ranges, Principal.fromText(workerId));
+    }
+    async setDayOff(workerId, date) {
+        await this.availability.setADayOffAsyncUnsafe(date, Principal.fromText(workerId));
+    }
+    async clearDailyOverride(workerId, date) {
+        await this.availability.removeDailyScheduleAsyncUnsafe(date, Principal.fromText(workerId));
+    }
+    async listMedia() {
+        const assets = await this.assets.getSalonAssetsAsyncUnsafe(this.salonId);
+        return assets
+            // Only a #Ready entry can carry a promo; a #Pending one is still transcoding and a
+            // #Failed one would be refused by the canister.
+            .filter((asset) => "Ready" in asset.status)
+            .map((asset) => ({
+            assetId: asset.assetId,
+            name: asset.name,
+            kind: "Image" in asset.kind ? "image" : "Video" in asset.kind ? "video" : "audio",
+        }));
+    }
+    async listPromos() {
+        const promos = await this.promo.getSalonPromosAsyncUnsafe(this.salonId);
+        // The canister gives the owner the whole library; a public tool set promises active
+        // promos only, whatever identity its host passed in.
+        const visible = this.access === "public" ? promos.filter((promo) => promo.active) : promos;
+        return visible.map((promo) => ({
+            id: promo.id,
+            name: promo.name,
+            active: promo.active,
+            assetId: promo.assetId,
+            textLines: [...promo.textLines],
+            chips: [...promo.chips],
+            buttonLabel: promo.cta.buttonLabel[0],
+            discountCode: promo.cta.discountCode[0],
+            targetServiceId: "SalonService" in promo.target ? promo.target.SalonService : undefined,
+            hasMusic: promo.music.length > 0,
+            music: promoMusicOf(promo) ?? undefined,
+        }));
+    }
+    async addPromo(input) {
+        return this.promo.addPromoAsyncUnsafe(this.salonId, input.name, input.assetId, toContent(input), input.targetServiceId);
+    }
+    async updatePromo(promoId, input) {
+        await this.promo.updatePromoAsyncUnsafe(this.salonId, promoId, input.name, input.assetId, toContent(input), input.targetServiceId);
+    }
+    async setPromoActive(promoId, active) {
+        await this.promo.setPromoActiveAsyncUnsafe(this.salonId, promoId, active);
+    }
+    async removePromo(promoId) {
+        await this.promo.removePromoAsyncUnsafe(this.salonId, promoId);
+    }
+    async listDiscountCodes() {
+        const codes = await this.discountCodes.getSalonDiscountCodesAsyncUnsafe(this.salonId);
+        return codes.map((code) => ({
+            code: code.code,
+            percent: "Percent" in code.value ? Number(code.value.Percent) : undefined,
+            amountPln: "Amount" in code.value ? Number(code.value.Amount) : undefined,
+            scopeServiceId: "SalonService" in code.scope ? code.scope.SalonService : undefined,
+        }));
+    }
+    async addDiscountCode(input) {
+        const value = input.percent === undefined ? { amount: BigInt(input.amountPln ?? 0) } : { percent: BigInt(input.percent) };
+        await this.discountCodes.addDiscountCodeAsyncUnsafe(this.salonId, input.code, value, input.scopeServiceId);
+    }
+    async removeDiscountCode(code) {
+        await this.discountCodes.removeDiscountCodeAsyncUnsafe(this.salonId, code);
+    }
+}
+/** The promo's content half, with `music` carried through unchanged — an edit that dropped it
+ * would silently turn a rendered campaign back into a plain one. */
+function toContent(input) {
+    return {
+        textLines: input.textLines,
+        chips: input.chips,
+        buttonLabel: input.buttonLabel,
+        discountCode: input.discountCode,
+        music: input.music,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createSalonReadTools, createSalonReadToolsFromPort, createSalonTools, createSalonToolsFromPort, } from "./create-salon-tools.js";
+export type { CreateSalonReadToolsOptions, 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";
+export type { DiscountCodeInput, DiscountCodeView, MediaView, PromoView, PromoWriteInput, SalonAccess, SalonCorePort, SalonPromoPort, ServiceTypeView, ServiceView, ServiceWriteInput, SalonSchedulePort, TimeRange, WorkerView, } from "./salon-core-port.js";
+export { err, needsConfirmation, ok } from "./types.js";
+export type { AgentTool, ToolErrorCode, ToolParametersSchema, ToolResult } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,4 @@
+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";
+export { err, needsConfirmation, ok } from "./types.js";

package/dist/persona.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The operating rules an agent needs to use these tools well, as a system prompt.
+ *
+ * It lives in this package on purpose: the rules describe the tool contract (units, the
+ * 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.
+ */
+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.";
+/**
+ * The operating rules for the read-only set (`createSalonReadTools`), as a system prompt.
+ *
+ * Separate from `SALON_AGENT_PERSONA_PL` because the two contracts differ where it matters: this
+ * agent sees only what a visitor sees and cannot write at all, so it must say so instead of
+ * promising a change or reporting a hidden service as missing.
+ */
+export declare const SALON_READ_PERSONA_PL = "Jeste\u015B asystentem w\u0142a\u015Bciciela salonu w aplikacji Sultana.\nRozmawiasz po polsku, kr\u00F3tko i konkretnie. Odpowiadasz na pytania o salon za pomoc\u0105 narz\u0119dzi.\n\nZasady pracy:\n- Zanim odpowiesz o us\u0142ugach, promocjach albo typach us\u0142ug, ZAWSZE wywo\u0142aj narz\u0119dzie\n  (list_services, list_promos, find_service_type). Nigdy nie zgaduj.\n- Widzisz tylko AKTYWNE us\u0142ugi i AKTYWNE promocje \u2014 to, co widz\u0105 klientki.\n  Powiedz o tym, gdy ma to znaczenie, np. gdy w\u0142a\u015Bciciel pyta o us\u0142ug\u0119, kt\u00F3rej nie ma na li\u015Bcie:\n  mo\u017Ce by\u0107 wy\u0142\u0105czona.\n- Nie mo\u017Cesz jeszcze niczego zmienia\u0107. Gdy w\u0142a\u015Bciciel prosi o dodanie, zmian\u0119 albo usuni\u0119cie,\n  powiedz, \u017Ce edycja przez czat b\u0119dzie dost\u0119pna wkr\u00F3tce, i wska\u017C stron\u0119 w panelu:\n  \u201EUs\u0142ugi\u201D dla us\u0142ug, \u201EPromocje\u201D dla promocji.\n- Ceny podawaj w pe\u0142nych z\u0142otych, czas trwania w minutach.\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- Nie obiecuj zmian, kt\u00F3rych nie mo\u017Cesz wykona\u0107.";
+//# sourceMappingURL=persona.d.ts.map

package/dist/persona.d.ts.map

@@ -0,0 +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"}

package/dist/persona.js

@@ -0,0 +1,49 @@
+/**
+ * The operating rules an agent needs to use these tools well, as a system prompt.
+ *
+ * It lives in this package on purpose: the rules describe the tool contract (units, the
+ * 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.
+ */
+export const SALON_AGENT_PERSONA_PL = `Jesteś asystentem właściciela salonu w aplikacji Sultana.
+Rozmawiasz po polsku, krótko i konkretnie. Wykonujesz zmiany w salonie za pomocą narzędzi.
+
+Zasady pracy:
+- Zanim zmienisz albo usuniesz usługę, wywołaj list_services i ustal jej id. Nie zgaduj id.
+- Zanim podasz serviceTypeIds, wywołaj find_service_type. Nigdy nie wymyślaj id typu usługi.
+- 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,
+  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.`;
+/**
+ * The operating rules for the read-only set (`createSalonReadTools`), as a system prompt.
+ *
+ * Separate from `SALON_AGENT_PERSONA_PL` because the two contracts differ where it matters: this
+ * agent sees only what a visitor sees and cannot write at all, so it must say so instead of
+ * promising a change or reporting a hidden service as missing.
+ */
+export const SALON_READ_PERSONA_PL = `Jesteś asystentem właściciela salonu w aplikacji Sultana.
+Rozmawiasz po polsku, krótko i konkretnie. Odpowiadasz na pytania o salon za pomocą narzędzi.
+
+Zasady pracy:
+- Zanim odpowiesz o usługach, promocjach albo typach usług, ZAWSZE wywołaj narzędzie
+  (list_services, list_promos, find_service_type). Nigdy nie zgaduj.
+- Widzisz tylko AKTYWNE usługi i AKTYWNE promocje — to, co widzą klientki.
+  Powiedz o tym, gdy ma to znaczenie, np. gdy właściciel pyta o usługę, której nie ma na liście:
+  może być wyłączona.
+- Nie możesz jeszcze niczego zmieniać. Gdy właściciel prosi o dodanie, zmianę albo usunięcie,
+  powiedz, że edycja przez czat będzie dostępna wkrótce, i wskaż stronę w panelu:
+  „Usługi” dla usług, „Promocje” dla promocji.
+- Ceny podawaj w pełnych złotych, czas trwania w minutach.
+- Jeśli narzędzie zwróci status "error", przeczytaj summary i powiedz właścicielowi,
+  co poszło nie tak. Nie powtarzaj tego samego wywołania w kółko.
+- Nie obiecuj zmian, których nie możesz wykonać.`;