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

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

@@ -0,0 +1,132 @@
+import { Principal } from "@icp-sdk/core/principal";
+import { AppointmentsActor, AvailabilityActor, filterServiceTypes, PromoActor, SalonServicesActor, SalonsActor, searchAsapAsyncUnsafe, searchAtMomentsAsyncUnsafe, SearchActor, ServiceTypesActor, } from "@jsm-mit/sultana-core-motoko-package";
+/**
+ * The customer port over the published canister wrapper. Conversions live here and nowhere
+ * else: the canister speaks `bigint`, `Principal` and nanoseconds, the tools speak numbers,
+ * strings and milliseconds.
+ *
+ * The public reads go out ANONYMOUSLY even when an identity is present: they answer the same
+ * either way, and a signed query would only spend the customer's delegation on nothing.
+ */
+export class IcCustomerCorePort {
+    location;
+    language;
+    search;
+    salons;
+    services;
+    serviceTypes;
+    promo;
+    availability;
+    appointments;
+    constructor(options) {
+        this.location = options.location ?? null;
+        this.language = options.language;
+        this.search = new SearchActor(options.canisterId);
+        this.salons = new SalonsActor(options.canisterId);
+        this.services = new SalonServicesActor(options.canisterId);
+        this.serviceTypes = new ServiceTypesActor(options.canisterId);
+        this.promo = new PromoActor(options.canisterId);
+        this.availability = new AvailabilityActor(options.canisterId);
+        this.appointments = new AppointmentsActor(options.canisterId, options.identity);
+    }
+    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 searchAsap(serviceTypeId, radiusKm, now) {
+        const state = await searchAsapAsyncUnsafe(this.search, {
+            location: this.requireLocation(),
+            serviceTypeId,
+            radiusKm,
+            now,
+        });
+        return { phase: state.phase, salons: state.results.map(toSalonSlots), failedProbes: state.failedProbes };
+    }
+    async searchAtMoments(serviceTypeId, radiusKm, moments) {
+        const state = await searchAtMomentsAsyncUnsafe(this.search, {
+            location: this.requireLocation(),
+            serviceTypeId,
+            radiusKm,
+            moments,
+        });
+        return { salons: state.results.map(toSalonSlots), failedProbes: state.failedProbes };
+    }
+    async getSalons(salonIds) {
+        if (salonIds.length === 0)
+            return [];
+        // The canister answers for at most 100 ids per call.
+        const salons = await this.salons.getSalonsPublicInfoAsyncUnsafe(salonIds.slice(0, 100));
+        return salons.map((salon) => ({ id: salon.id, name: salon.name, address: salon.address }));
+    }
+    async listSalonServices(salonId) {
+        const services = await this.services.getSalonServicesPublicAsyncUnsafe(salonId);
+        return services.map(toService);
+    }
+    async listSalonPromos(salonId) {
+        const promos = await this.promo.getSalonPromosAsyncUnsafe(salonId);
+        return promos
+            .filter((promo) => promo.active)
+            .map((promo) => ({
+            name: promo.name,
+            textLines: [...promo.textLines],
+            discountCode: promo.cta.discountCode[0],
+            targetServiceId: "SalonService" in promo.target ? promo.target.SalonService : undefined,
+        }));
+    }
+    async freeWindows(salonId, workerId, day) {
+        // `day` stays a "YYYY-MM-DD" string: the wrapper reads a date's UTC parts, so a Date of
+        // local midnight would land a day early. The offset is the one of that day's noon, so a
+        // day on the far side of a clock change is read with its own offset.
+        const [year, month, date] = day.split("-").map(Number);
+        const offsetSlots = BigInt(-new Date(year, month - 1, date, 12).getTimezoneOffset() / 5);
+        return this.availability.getEffectiveMaskForSalonAsyncUnsafe(day, salonId, Principal.fromText(workerId), offsetSlots);
+    }
+    async book(input) {
+        return this.appointments.bookAppointmentAsyncUnsafe(input.notes, input.salonId, input.serviceId, input.startAt, input.workerId, input.discountCode);
+    }
+    async listMyAppointments() {
+        const appointments = await this.appointments.getMyAppointmentsAsyncUnsafe();
+        return appointments.map((appointment) => ({
+            id: appointment.id,
+            salonId: appointment.salonId,
+            serviceId: appointment.salonServiceId,
+            startAt: Number(appointment.startTimeUTC / 1000000n),
+            durationMinutes: Number(appointment.durationMinutes),
+            pricePln: Number(appointment.priceSnapshot),
+            status: Object.keys(appointment.status)[0],
+            discountCode: appointment.discountCode[0],
+        }));
+    }
+    async cancel(appointmentId) {
+        await this.appointments.cancelAppointmentAsyncUnsafe(appointmentId);
+    }
+    requireLocation() {
+        if (!this.location)
+            throw new Error("IcCustomerCorePort: no location — the tools check it before they search");
+        return this.location;
+    }
+}
+function toService(service) {
+    return {
+        id: service.id,
+        salonId: service.salonId,
+        name: service.name,
+        pricePln: Number(service.price),
+        durationMinutes: Number(service.duration),
+        serviceTypeIds: [...service.serviceTypeIds],
+        workerIds: service.workerIds.map((worker) => worker.toText()),
+    };
+}
+function toSalonSlots(found) {
+    return {
+        salonId: found.salonId,
+        distanceKm: found.distanceKm,
+        services: found.services.map(toService),
+        availableAt: [...found.availableAt],
+        soonestAt: found.soonest ? found.soonest.at : null,
+    };
+}

package/dist/customer/persona.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The operating rules of the customer tools, as a system prompt — next to the tools for the same
+ * reason as the salon persona: they describe the tool contract. A host appends who the agent is.
+ */
+export declare const CUSTOMER_AGENT_PERSONA_PL = "Jeste\u015B asystentem klienta w aplikacji Sultana: pomagasz znale\u017A\u0107 salon i wolny termin,\nrezerwujesz i odwo\u0142ujesz wizyty w imieniu klienta. Rozmawiasz po polsku, kr\u00F3tko i konkretnie.\n\nZasady pracy:\n- Szukasz zawsze wok\u00F3\u0142 pozycji klienta, kt\u00F3r\u0105 poda\u0142a aplikacja. Nie pytaj o adres.\n- Typ us\u0142ugi ustal przez find_service_type (np. \u201Estrzy\u017Cenie m\u0119skie\u201D). Nigdy nie wymy\u015Blaj id.\n  Gdy pasuje kilka typ\u00F3w, dopytaj klienta, o kt\u00F3ry chodzi.\n- Terminy znajd\u017A przez search_slots: bez daty = jak najszybciej, z date i time = okolice tej godziny.\n  Dzisiejsz\u0105 dat\u0119 we\u017A z get_current_date \u2014 \u201Ejutro o 10\u201D przelicz na RRRR-MM-DD i GG:MM.\n- Poka\u017C klientowi najwy\u017Cej kilka propozycji: salon, us\u0142uga, cena, odleg\u0142o\u015B\u0107, godzina. Nie pokazuj id.\n- Inne godziny w wybranym salonie sprawd\u017A przez get_free_times.\n- Rezerwacja i odwo\u0142anie to dwa kroki w dw\u00F3ch r\u00F3\u017Cnych wiadomo\u015Bciach klienta:\n  1. Wywo\u0142aj book_appointment albo cancel_appointment z confirmed=false. Poka\u017C klientowi zdanie\n     z pola summary, 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- Kod rabatowy podawaj tylko wtedy, gdy klient go wpisa\u0142 albo wybra\u0142 promocj\u0119 z get_salon.\n- Je\u015Bli masz tylko narz\u0119dzia do szukania (bez book_appointment), nie mo\u017Cesz rezerwowa\u0107 \u2014\n  powiedz, \u017Ce klient musi si\u0119 zalogowa\u0107 ponownie w aplikacji i otworzy\u0107 czat jeszcze raz.\n- Je\u015Bli narz\u0119dzie zwr\u00F3ci status \"error\", przeczytaj summary i powiedz klientowi, co posz\u0142o nie tak.\n  Nie powtarzaj tego samego wywo\u0142ania w k\u00F3\u0142ko: nieudana pr\u00F3ba rezerwacji zu\u017Cywa dzienny limit klienta.\n- Nie obiecuj rezerwacji, kt\u00F3rej nie wykona\u0142e\u015B narz\u0119dziem.";
+//# sourceMappingURL=persona.d.ts.map

package/dist/customer/persona.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona.d.ts","sourceRoot":"","sources":["../../src/customer/persona.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,yBAAyB,isEAsBqB,CAAC"}

package/dist/customer/persona.js

@@ -0,0 +1,27 @@
+/**
+ * The operating rules of the customer tools, as a system prompt — next to the tools for the same
+ * reason as the salon persona: they describe the tool contract. A host appends who the agent is.
+ */
+export const CUSTOMER_AGENT_PERSONA_PL = `Jesteś asystentem klienta w aplikacji Sultana: pomagasz znaleźć salon i wolny termin,
+rezerwujesz i odwołujesz wizyty w imieniu klienta. Rozmawiasz po polsku, krótko i konkretnie.
+
+Zasady pracy:
+- Szukasz zawsze wokół pozycji klienta, którą podała aplikacja. Nie pytaj o adres.
+- Typ usługi ustal przez find_service_type (np. „strzyżenie męskie”). Nigdy nie wymyślaj id.
+  Gdy pasuje kilka typów, dopytaj klienta, o który chodzi.
+- Terminy znajdź przez search_slots: bez daty = jak najszybciej, z date i time = okolice tej godziny.
+  Dzisiejszą datę weź z get_current_date — „jutro o 10” przelicz na RRRR-MM-DD i GG:MM.
+- Pokaż klientowi najwyżej kilka propozycji: salon, usługa, cena, odległość, godzina. Nie pokazuj id.
+- Inne godziny w wybranym salonie sprawdź przez get_free_times.
+- Rezerwacja i odwołanie to dwa kroki w dwóch różnych wiadomościach klienta:
+  1. Wywołaj book_appointment albo cancel_appointment z confirmed=false. Pokaż klientowi 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.
+- Kod rabatowy podawaj tylko wtedy, gdy klient go wpisał albo wybrał promocję z get_salon.
+- Jeśli masz tylko narzędzia do szukania (bez book_appointment), nie możesz rezerwować —
+  powiedz, że klient musi się zalogować ponownie w aplikacji i otworzyć czat jeszcze raz.
+- Jeśli narzędzie zwróci status "error", przeczytaj summary i powiedz klientowi, co poszło nie tak.
+  Nie powtarzaj tego samego wywołania w kółko: nieudana próba rezerwacji zużywa dzienny limit klienta.
+- Nie obiecuj rezerwacji, której nie wykonałeś narzędziem.`;

package/dist/customer/time.d.ts

@@ -0,0 +1,27 @@
+import type { TimeRange } from "../salon-core-port.js";
+/** The local day of a moment, `"YYYY-MM-DD"`. */
+export declare function localDayOf(at: number | Date): string;
+/** The local time of a moment, `"HH:mm"`. */
+export declare function localTimeOf(at: number | Date): string;
+/** `"YYYY-MM-DD HH:mm"` — what a model reads and sends back as `date` + `time`. */
+export declare function localStampOf(at: number | Date): string;
+export declare function isDay(text: string): boolean;
+/** Minutes from midnight of `"HH:mm"` (`"9:30"` too), or `null` when it is no time of day. */
+export declare function minutesOf(time: string): number | null;
+export declare function timeOfMinutes(minutes: number): string;
+/** The moment of a local day at minutes from its midnight. `day` must pass `isDay`. */
+export declare function momentOf(day: string, minutes: number): number;
+export declare function onSlotGrid(minutes: number): boolean;
+/** Start minutes, on the 5-minute grid, where a service of this duration fits in one window. */
+export declare function freeStartMinutes(windows: TimeRange[], durationMinutes: number): number[];
+/** Consecutive grid minutes folded into ranges — dozens of start times are noise to a model. */
+export declare function foldStartRanges(starts: number[]): {
+    from: string;
+    to: string;
+}[];
+/**
+ * Why this process must not book for salons in `expectedTimeZone`, or `null` when it may: the
+ * process clock has to run in that zone, because the canister wrapper takes every offset from it.
+ */
+export declare function hostTimeZoneProblem(expectedTimeZone: string, at?: Date): string | null;
+//# sourceMappingURL=time.d.ts.map

package/dist/customer/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/customer/time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAevD,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGpD;AAED,6CAA6C;AAC7C,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGrD;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEtD;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAO3C;AAED,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,uFAAuF;AACvF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,EAAE,CAcxF;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,CAUhF;AAqBD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,EAAE,EAAE,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAalG"}

package/dist/customer/time.js

@@ -0,0 +1,113 @@
+/**
+ * Local-time arithmetic of the customer tools. "Local" is the zone of the HOST PROCESS: the
+ * canister wrapper derives every `timeOffset` from the process zone too, so the two cannot
+ * disagree — but the process zone must then be the salons' zone. `hostTimeZoneProblem` is the
+ * guard: a host in UTC would book every visit two hours off, and refusing is better than that.
+ */
+const SLOT_MINUTES = 5;
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const TIME_PATTERN = /^(\d{1,2}):(\d{2})$/;
+const pad = (value) => String(value).padStart(2, "0");
+/** The local day of a moment, `"YYYY-MM-DD"`. */
+export function localDayOf(at) {
+    const date = new Date(at);
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** The local time of a moment, `"HH:mm"`. */
+export function localTimeOf(at) {
+    const date = new Date(at);
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+/** `"YYYY-MM-DD HH:mm"` — what a model reads and sends back as `date` + `time`. */
+export function localStampOf(at) {
+    return `${localDayOf(at)} ${localTimeOf(at)}`;
+}
+export function isDay(text) {
+    const match = DAY_PATTERN.exec(text);
+    if (!match)
+        return false;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const date = new Date(year, month - 1, day);
+    return date.getFullYear() === year && date.getMonth() === month - 1 && date.getDate() === day;
+}
+/** Minutes from midnight of `"HH:mm"` (`"9:30"` too), or `null` when it is no time of day. */
+export function minutesOf(time) {
+    const match = TIME_PATTERN.exec(time.trim());
+    if (!match)
+        return null;
+    const [hours, minutes] = [Number(match[1]), Number(match[2])];
+    if (hours > 23 || minutes > 59)
+        return null;
+    return hours * 60 + minutes;
+}
+export function timeOfMinutes(minutes) {
+    return `${pad(Math.floor(minutes / 60))}:${pad(minutes % 60)}`;
+}
+/** The moment of a local day at minutes from its midnight. `day` must pass `isDay`. */
+export function momentOf(day, minutes) {
+    const [year, month, date] = day.split("-").map(Number);
+    return new Date(year, month - 1, date, Math.floor(minutes / 60), minutes % 60, 0, 0).getTime();
+}
+export function onSlotGrid(minutes) {
+    return minutes % SLOT_MINUTES === 0;
+}
+/** Start minutes, on the 5-minute grid, where a service of this duration fits in one window. */
+export function freeStartMinutes(windows, durationMinutes) {
+    const starts = new Set();
+    for (const window of windows) {
+        const from = minutesOf(window.startTime);
+        // The wrapper writes the end of the day as "24:00" or "00:00".
+        const to = window.endTime === "24:00" || window.endTime === "00:00" ? 24 * 60 : minutesOf(window.endTime);
+        if (from === null || to === null)
+            continue;
+        const first = Math.ceil(from / SLOT_MINUTES) * SLOT_MINUTES;
+        for (let start = first; start + durationMinutes <= to; start += SLOT_MINUTES)
+            starts.add(start);
+    }
+    return [...starts].sort((a, b) => a - b);
+}
+/** Consecutive grid minutes folded into ranges — dozens of start times are noise to a model. */
+export function foldStartRanges(starts) {
+    const ranges = [];
+    for (const start of starts) {
+        const last = ranges[ranges.length - 1];
+        if (last && start === last.to + SLOT_MINUTES)
+            last.to = start;
+        else
+            ranges.push({ from: start, to: start });
+    }
+    return ranges.map((range) => ({ from: timeOfMinutes(range.from), to: timeOfMinutes(range.to) }));
+}
+/** Minutes east of UTC of a named zone at a moment. */
+function zoneOffsetMinutes(timeZone, at) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        second: "numeric",
+    }).formatToParts(at);
+    const read = (type) => Number(parts.find((part) => part.type === type)?.value);
+    const asUtc = Date.UTC(read("year"), read("month") - 1, read("day"), read("hour"), read("minute"), read("second"));
+    return Math.round((asUtc - at.getTime()) / 60_000);
+}
+/**
+ * Why this process must not book for salons in `expectedTimeZone`, or `null` when it may: the
+ * process clock has to run in that zone, because the canister wrapper takes every offset from it.
+ */
+export function hostTimeZoneProblem(expectedTimeZone, at = new Date()) {
+    let expected;
+    try {
+        expected = zoneOffsetMinutes(expectedTimeZone, at);
+    }
+    catch {
+        return `nieznana strefa czasowa „${expectedTimeZone}”`;
+    }
+    const actual = -at.getTimezoneOffset();
+    if (actual === expected)
+        return null;
+    return `proces działa w innej strefie czasowej niż salony (${expectedTimeZone}): różnica ${Math.abs(expected - actual)} min — ustaw TZ=${expectedTimeZone}`;
+}

package/dist/customer/tools.d.ts

@@ -0,0 +1,17 @@
+import type { TurnConfirmations } from "../confirmations.js";
+import { type AgentTool } from "../types.js";
+import type { CustomerCorePort } from "./customer-core-port.js";
+export interface CustomerToolsContext {
+    port: CustomerCorePort;
+    /** The clock — a test sets it. */
+    now: () => Date;
+    /** The salons' time zone the host process must run in; `undefined` skips the guard. */
+    timeZone?: string;
+}
+export declare function searchSlotsTool(context: CustomerToolsContext): AgentTool;
+export declare function getSalonTool(context: CustomerToolsContext): AgentTool;
+export declare function getFreeTimesTool(context: CustomerToolsContext): AgentTool;
+export declare function bookAppointmentTool(context: CustomerToolsContext, confirmations: TurnConfirmations | undefined): AgentTool;
+export declare function listMyAppointmentsTool(context: CustomerToolsContext): AgentTool;
+export declare function cancelAppointmentTool(context: CustomerToolsContext, confirmations: TurnConfirmations | undefined): AgentTool;
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/customer/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7D,OAAO,EAAW,KAAK,SAAS,EAAmB,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAmB,gBAAgB,EAAkD,MAAM,yBAAyB,CAAC;AAejI,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,kCAAkC;IAClC,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAwCD,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAgFxE;AAUD,wBAAgB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAkCrE;AAkCD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CA2CzE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,GAAG,SAAS,GAAG,SAAS,CA6E1H;AA6CD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,SAAS,CAkC/E;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,GAAG,SAAS,GAAG,SAAS,CA4C5H"}