@vinaverse/server 0.0.0-stage → 0.1.0-alpha.10

package/dist/provider-ytczljc-.d.cts

@@ -0,0 +1,2193 @@
+import { c as components$1, w as webhooks } from './vinaverse-v1.d-DT7a1T80.cjs';
+import { c as NonceStore, a as IdempotencyStore } from './nonces-scwljZwl.cjs';
+
+/**
+ * Why a delivery was refused, in the conformance vectors' words
+ * (vinaverse-contracts `conformance/webhooks.json`). Every one is answered with
+ * `400`, so Vinaverse retries it; none of them is ever a valid delivery.
+ *
+ * - `missing`: no `Vinaverse-Signature` header.
+ * - `malformed`: the header is not `t=<unix seconds>,v1=<hex>[,v1=<hex>]`
+ *   (no single timestamp, or no `v1` signature).
+ * - `stale`: signed more than the tolerance (300 seconds) before or after now:
+ *   a replay, or a clock far off.
+ * - `mismatch`: no `v1` signature matches the body with any secret: a wrong
+ *   secret (or the secret without its `vv_whsec_` prefix), a changed body, or a
+ *   body parsed and serialized again.
+ * - `invalid_body`: signed by Vinaverse, but not a webhook envelope this
+ *   package can read.
+ */
+type WebhookErrorCode = 'missing' | 'malformed' | 'stale' | 'mismatch' | 'invalid_body';
+interface WebhookError {
+    readonly code: WebhookErrorCode;
+    readonly message: string;
+}
+
+type Schemas = components$1['schemas'];
+/** The envelope every webhook body has. `data` depends on `type`. */
+type WebhookEnvelope = Schemas['WebhookEnvelope'];
+/** Every event type the targeted contract defines. */
+type WebhookEventType = WebhookEnvelope['type'] & keyof webhooks;
+type BodyOf<T extends WebhookEventType> = NonNullable<webhooks[T]['post']['requestBody']>['content']['application/json'];
+/** One event of type `T`: the envelope, with `data` as the contract says. */
+type WebhookEventOf<T extends WebhookEventType> = Omit<WebhookEnvelope, 'type' | 'data'> & {
+    type: T;
+    data: NonNullable<BodyOf<T>['data']>;
+};
+/** Any event this package version knows; narrow it on `type`. */
+type WebhookEvent = {
+    [T in WebhookEventType]: WebhookEventOf<T>;
+}[WebhookEventType];
+type ConversationEventType = 'conversation.updated' | 'conversation.completed' | 'conversation.failed' | 'conversation.expired';
+/** A guided-flow conversation's state changed: `data` is its `ConversationState`. */
+type ConversationEvent = {
+    [T in ConversationEventType]: WebhookEventOf<T>;
+}[ConversationEventType];
+type ConversationState = Schemas['ConversationState'];
+declare const WEBHOOK_EVENT_TYPES: readonly WebhookEventType[];
+declare function isConversationEvent(event: WebhookEvent): event is ConversationEvent;
+/** What a verified body is: a known event, a test delivery, or a type newer than this package. */
+type ReadBody = {
+    kind: 'event';
+    event: WebhookEvent;
+} | {
+    kind: 'test';
+    envelope: WebhookEnvelope;
+} | {
+    kind: 'unrecognized';
+    envelope: WebhookEnvelope;
+};
+
+interface WebhookHandlerOptions {
+    /** The endpoint's signing secret, or two while rolling a new one out. */
+    secret: string | readonly string[];
+    /**
+     * Called once per verified delivery of a known event. Answer quickly (the
+     * contract allows 5 seconds) and do the work afterwards; deliveries are at
+     * least once, so deduplicate on `event.id`.
+     */
+    onEvent(event: WebhookEvent): void | Promise<void>;
+    /** A test delivery from Studio; by default it is acknowledged and ignored. */
+    onTest?(envelope: WebhookEnvelope): void | Promise<void>;
+    /** A verified type newer than this package; by default acknowledged and ignored. */
+    onUnrecognized?(envelope: WebhookEnvelope): void | Promise<void>;
+    /** A refused delivery, for logging; it is answered 400 either way. */
+    onRejected?(error: WebhookError): void | Promise<void>;
+    /** How far from now a signature may be, in seconds; default 300. */
+    toleranceSeconds?: number;
+    /**
+     * The largest body accepted, in bytes; default 1 MiB (a conversation
+     * webhook is at most 64 KB). A larger one is answered 413 unread.
+     */
+    maxBodyBytes?: number;
+    /** The clock; default the system clock. */
+    now?: () => Date;
+}
+interface WebhookResponse {
+    readonly status: 200 | 400 | 413;
+    readonly body: string;
+}
+
+declare const TOOL_OPERATIONS: {
+    readonly create_handoff: {
+        readonly id: "create_handoff";
+        readonly method: "POST";
+        readonly path: "/handoffs";
+        readonly effect: "write";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 201;
+        readonly idempotencyKey: true;
+        readonly body: true;
+        readonly pathParams: {};
+        readonly queryParams: {};
+    };
+    readonly create_proposal: {
+        readonly id: "create_proposal";
+        readonly method: "POST";
+        readonly path: "/proposals";
+        readonly effect: "propose";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 201;
+        readonly idempotencyKey: true;
+        readonly body: true;
+        readonly pathParams: {};
+        readonly queryParams: {};
+    };
+    readonly get_availability: {
+        readonly id: "get_availability";
+        readonly method: "GET";
+        readonly path: "/availability";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly professional_id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly service_id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly from: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly to: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly get_flow_definition: {
+        readonly id: "get_flow_definition";
+        readonly method: "GET";
+        readonly path: "/flows/{flow}/definition";
+        readonly effect: "read";
+        readonly maxResultBytes: 131072;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly flow: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {
+            readonly version: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly get_my_booking: {
+        readonly id: "get_my_booking";
+        readonly method: "GET";
+        readonly path: "/me/bookings/{id}";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+    readonly get_my_kit: {
+        readonly id: "get_my_kit";
+        readonly method: "GET";
+        readonly path: "/me/kits/{id}";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+    readonly get_my_order: {
+        readonly id: "get_my_order";
+        readonly method: "GET";
+        readonly path: "/me/orders/{id}";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+    readonly get_policy: {
+        readonly id: "get_policy";
+        readonly method: "GET";
+        readonly path: "/policies/{topic}";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly topic: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+    readonly get_professional: {
+        readonly id: "get_professional";
+        readonly method: "GET";
+        readonly path: "/professionals/{id}";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+    readonly get_quote: {
+        readonly id: "get_quote";
+        readonly method: "POST";
+        readonly path: "/quotes";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: true;
+        readonly body: true;
+        readonly pathParams: {};
+        readonly queryParams: {};
+    };
+    readonly get_setup_state: {
+        readonly id: "get_setup_state";
+        readonly method: "GET";
+        readonly path: "/business/setup";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {};
+    };
+    readonly get_workspace: {
+        readonly id: "get_workspace";
+        readonly method: "GET";
+        readonly path: "/workspaces/{id}";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {
+            readonly id: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+    readonly list_my_bookings: {
+        readonly id: "list_my_bookings";
+        readonly method: "GET";
+        readonly path: "/me/bookings";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly scope: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly list_my_kits: {
+        readonly id: "list_my_kits";
+        readonly method: "GET";
+        readonly path: "/me/kits";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly scope: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly list_my_orders: {
+        readonly id: "list_my_orders";
+        readonly method: "GET";
+        readonly path: "/me/orders";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly kit_id: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly list_services: {
+        readonly id: "list_services";
+        readonly method: "GET";
+        readonly path: "/catalog/services";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly q: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly list_services_in_area: {
+        readonly id: "list_services_in_area";
+        readonly method: "GET";
+        readonly path: "/areas/services";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly lat: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly lng: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly radius_miles: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+        };
+    };
+    readonly resolve_place: {
+        readonly id: "resolve_place";
+        readonly method: "GET";
+        readonly path: "/places/resolve";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly text: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly near_lat: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly near_lng: {
+                readonly type: "number";
+                readonly required: false;
+            };
+        };
+    };
+    readonly search_professionals: {
+        readonly id: "search_professionals";
+        readonly method: "GET";
+        readonly path: "/search/professionals";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly q: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly category_id: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly service_type_id: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly lat: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly lng: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly radius_miles: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly date: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly time_from: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly time_to: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly max_price: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly min_rating_ppm: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly sort: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly cursor: {
+                readonly type: "string";
+                readonly required: false;
+            };
+        };
+    };
+    readonly search_workspaces: {
+        readonly id: "search_workspaces";
+        readonly method: "GET";
+        readonly path: "/search/workspaces";
+        readonly effect: "read";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: false;
+        readonly pathParams: {};
+        readonly queryParams: {
+            readonly q: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly space_category: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly lat: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly lng: {
+                readonly type: "number";
+                readonly required: false;
+            };
+            readonly radius_miles: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly max_price: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly min_rating_ppm: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly sort: {
+                readonly type: "string";
+                readonly required: false;
+            };
+            readonly limit: {
+                readonly type: "integer";
+                readonly required: false;
+            };
+            readonly cursor: {
+                readonly type: "string";
+                readonly required: false;
+            };
+        };
+    };
+    readonly submit_flow: {
+        readonly id: "submit_flow";
+        readonly method: "POST";
+        readonly path: "/flows/{flow}/submissions";
+        readonly effect: "write";
+        readonly maxResultBytes: 16384;
+        readonly successStatus: 200;
+        readonly idempotencyKey: false;
+        readonly body: true;
+        readonly pathParams: {
+            readonly flow: {
+                readonly type: "string";
+                readonly required: true;
+            };
+        };
+        readonly queryParams: {};
+    };
+};
+type ToolOperationId = keyof typeof TOOL_OPERATIONS;
+
+interface components {
+    schemas: {
+        Money: {
+            amount: number;
+            currency: string;
+        };
+        Rating: {
+            /** @description e.g. 4.8 stars = 4800000 */
+            value_ppm: number;
+            count: number;
+        };
+        /** @description Public location only. Never a street address for a home-based professional unless the tenant shows it publicly. */
+        Area: {
+            neighborhood?: string;
+            city?: string;
+            region?: string;
+            /** @description distance × 10 from the search point, e.g. 8 = 0.8 mi */
+            distance_miles_x10?: number;
+        };
+        Place: {
+            name: string;
+            lat: number;
+            lng: number;
+            /** @enum {string} */
+            kind?: "neighborhood" | "city" | "address" | "landmark" | "region";
+        };
+        CatalogService: {
+            /** @constant */
+            type: "service_type";
+            id: string;
+            name: string;
+            category?: string;
+            category_id?: string;
+            synonyms?: string[];
+        };
+        ServiceOffer: {
+            /** @constant */
+            type: "service";
+            id: string;
+            name: string;
+            price: components["schemas"]["Money"];
+            /** @description true when the price is a starting price */
+            price_is_from?: boolean;
+            duration_minutes: number;
+        };
+        /**
+         * @description `estimate`: the tenant did not count exactly (a cached or sampled figure); the agent says "about"
+         * @enum {string}
+         */
+        CountStatus: "exact" | "estimate";
+        InventoryService: {
+            id: string;
+            name: string;
+            count: number;
+            count_status: components["schemas"]["CountStatus"];
+        };
+        InventoryCategory: {
+            id: string;
+            name: string;
+            count: number;
+            count_status: components["schemas"]["CountStatus"];
+            services?: components["schemas"]["InventoryService"][];
+        };
+        NearbyArea: {
+            area: components["schemas"]["Area"];
+            lat?: number;
+            lng?: number;
+            count: number;
+            count_status: components["schemas"]["CountStatus"];
+        };
+        /** @description v1-draft.15, `list_services_in_area`'s result: what is represented around the place, and where else there is supply. Empty `categories` means nothing is offered within the radius; `nearest_areas` then says where there is. */
+        AreaInventory: {
+            /** @constant */
+            type: "area_inventory";
+            /**
+             * Format: date-time
+             * @description when the tenant counted
+             */
+            as_of: string;
+            categories: components["schemas"]["InventoryCategory"][];
+            /** @description the nearest areas outside the radius that have supply, nearest first */
+            nearest_areas: components["schemas"]["NearbyArea"][];
+        };
+        /** @description v1-draft.15: one approved photo. `id` and `version` name the asset as the tenant's media store does: a new version is a new photo, and approval binds to the version, never to a mutable URL. The URL is https and starts with a prefix the manifest registers (`image_url_prefixes`), compared after the runtime parses and normalizes it: a URL with user info, a backslash, a fragment, or a `.` or `..` path segment (also percent-encoded, as `%2e`) is dropped, never resolved, so no path can step outside the approved one. `expires_at` is set only when the URL expires (a signed URL), and then the runtime drops it from a card it records after that time. */
+        ImageAsset: {
+            id: string;
+            version: string;
+            /** Format: uri */
+            url: string;
+            width?: number;
+            height?: number;
+            /** Format: date-time */
+            expires_at?: string;
+        };
+        ProfessionalSummary: {
+            /** @constant */
+            type: "professional";
+            id: string;
+            display_name: string;
+            headline?: string;
+            /** Format: uri */
+            photo_url?: string;
+            /** @description v1-draft.15, approved photos, the first the hero (`photo_url` is its URL) */
+            images?: components["schemas"]["ImageAsset"][];
+            rating?: components["schemas"]["Rating"];
+            area?: components["schemas"]["Area"];
+            /** @description v1-draft.15: the lowest price the professional asks for a service, as the tenant knows it; left out when it does not */
+            price_from?: components["schemas"]["Money"];
+            top_services?: components["schemas"]["ServiceOffer"][];
+            /** Format: date-time */
+            next_available?: string | null;
+            deep_link: string;
+        };
+        ProfessionalDetail: components["schemas"]["ProfessionalSummary"] & {
+            about?: string;
+            services?: components["schemas"]["ServiceOffer"][];
+            languages?: string[];
+            accepts_new_clients?: boolean;
+            /** @description workspace id */
+            works_at?: string | null;
+        };
+        WorkspaceSummary: {
+            /** @constant */
+            type: "workspace";
+            id: string;
+            title: string;
+            category?: string;
+            /** Format: uri */
+            photo_url?: string;
+            /** @description v1-draft.15, approved photos, the first the hero (`photo_url` is its URL) */
+            images?: components["schemas"]["ImageAsset"][];
+            rating?: components["schemas"]["Rating"];
+            area?: components["schemas"]["Area"];
+            price_from?: components["schemas"]["Money"];
+            /** @enum {string} */
+            price_unit?: "hour" | "day" | "week" | "month";
+            deep_link: string;
+        };
+        WorkspaceDetail: components["schemas"]["WorkspaceSummary"] & {
+            description?: string;
+            amenities?: string[];
+            suites_available?: number;
+            rules?: string;
+        };
+        Quote: {
+            /** @constant */
+            type: "quote";
+            id: string;
+            professional_id: string;
+            service_id: string;
+            /** Format: date-time */
+            start: string;
+            /** Format: date-time */
+            end: string;
+            total: components["schemas"]["Money"];
+            lines: {
+                /**
+                 * @example Service
+                 * @example Booking fee
+                 * @example Tax
+                 */
+                label: string;
+                amount: components["schemas"]["Money"];
+            }[];
+            cancellation: {
+                /** Format: date-time */
+                free_until: string;
+                fee_after: components["schemas"]["Money"];
+                policy_id?: string;
+            };
+            /** Format: date-time */
+            expires_at: string;
+            /** @description opens the normal checkout for this quote */
+            deep_link?: string;
+        };
+        Booking: {
+            /** @constant */
+            type: "booking";
+            id: string;
+            /** @enum {string} */
+            status: "requested" | "confirmed" | "completed" | "cancelled_by_client" | "cancelled_by_professional" | "no_show";
+            /** Format: date-time */
+            start: string;
+            /** Format: date-time */
+            end?: string;
+            timezone?: string;
+            service_name: string;
+            professional?: {
+                id?: string;
+                display_name?: string;
+            };
+            location_summary?: string;
+            amount_paid?: components["schemas"]["Money"];
+            cancellation?: {
+                can_cancel?: boolean;
+                /** Format: date-time */
+                free_until?: string | null;
+                fee_now?: components["schemas"]["Money"];
+            };
+            deep_link: string;
+        };
+        /** @description A change the tenant holds after a `propose` call. Nothing has changed while it is `pending`. The person confirms or declines it in the tenant's app, and the runtime shows it as a `proposal` card (`confirm_mode: tenant_app`). */
+        Proposal: {
+            /** @constant */
+            type: "proposal";
+            id: string;
+            /**
+             * @description The tenant's current state of the proposal. Only `pending` can still be confirmed. The tenant is the source of truth, and `confirmed` means the change was applied.
+             * @enum {string}
+             */
+            status: "pending" | "confirmed" | "declined" | "expired" | "superseded";
+            /** @description the older pending proposals this one superseded (they now have `status: superseded`) */
+            supersedes?: string[];
+            /**
+             * @example business_address
+             * @example opening_hours
+             * @example services
+             * @example booking
+             * @example booking_reschedule
+             * @example booking_cancellation
+             */
+            topic: string;
+            title: string;
+            summary: string;
+            fields: components["schemas"]["ProposalField"][];
+            /**
+             * Format: date-time
+             * @description after it the tenant declines the proposal on its own
+             */
+            expires_at: string;
+            /** @description A link into the tenant's app, to edit the change there. It must start with a prefix registered for the environment and pass the link checks (`admin-v1.yaml`, `Connector.deep_link_prefixes`). The runtime removes one that fails, and the proposal is still shown. */
+            edit_deep_link?: string;
+        } & (unknown & unknown & unknown & unknown);
+        /** @description The fields of a booking proposal (topic `booking`, `booking_reschedule` or `booking_cancellation`), whose keys are fixed so every app draws a booking card the same way (`docs/agents-guardrails-suggestions-writes.md` §3.4): `service`, `professional`, `space`, `booking`, `location`, `note` and `reason` are `text`, `services` is a `list`, `time` is a `time_range`, `place` an `address`, and `price`, `deposit`, `fee`, `cancellation_fee` and `refund` are `money_cents`. */
+        BookingFields: (unknown & unknown & unknown & unknown & unknown)[];
+        /** @description `before` is the current value, absent or null when the proposal creates it, and equal to `after` when the field does not change but says what the change is about (the booking a reschedule moves); `before` and `after` take the shape `type` names. */
+        ProposalField: {
+            key: string;
+            label: string;
+            /**
+             * @description `money_cents` is an amount in the currency's minor units (ISO 4217: cents for USD, yen for JPY, fils for BHD), never negative. `time_range` is one dated range whose `end` is after its `start`. `weekly_hours` is recurring opening hours, by weekday, in the business's time zone.
+             * @enum {string}
+             */
+            type: "text" | "money_cents" | "time_range" | "address" | "list" | "weekly_hours";
+            before?: unknown;
+            after: unknown;
+        } & (unknown & unknown & unknown & unknown & unknown & unknown);
+        ProposalMoney: {
+            /** @description in the currency's minor units (ISO 4217) */
+            amount: number;
+            currency: string;
+        };
+        /** @description Recurring opening hours. A day absent from `entries` is closed; a day may have several entries (a lunch break), which never overlap. `end` may be `24:00` (closing at midnight), and `00:00`–`24:00` is open all day. An `end` earlier than `start` runs past midnight into the next day (a bar's `22:00`–`02:00`), and that spill counts against the next day's entries: `fri 22:00`–`02:00` and `sat 01:00`–`09:00` overlap. `end` never equals `start`. */
+        WeeklyHours: {
+            /**
+             * @description an IANA time zone name
+             * @example America/New_York
+             */
+            time_zone: string;
+            entries: {
+                /** @enum {string} */
+                day: "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+                start: string;
+                end: string;
+            }[];
+        };
+        TimeRange: {
+            /** Format: date-time */
+            start: string;
+            /** Format: date-time */
+            end: string;
+        };
+        PostalAddress: {
+            line1: string;
+            line2?: string;
+            city: string;
+            region?: string;
+            postal_code?: string;
+            /** @description ISO 3166-1 alpha-2 */
+            country: string;
+        };
+        TextList: string[];
+        /** @description A business's setup steps, in the order the business should do them. The steps and their state are the tenant's own record; a business with nothing left to set up has every step `done`. */
+        SetupState: {
+            steps: components["schemas"]["SetupStep"][];
+        };
+        /** @description One step of a business's setup. `title`, `body` and `label` are the tenant's own words for it, shown on the `next_step` card when the step has a `deep_link`. A `blocked` step says why in `reason`. */
+        SetupStep: {
+            /**
+             * @description the tenant's id for the step, stable across reads; the agent names a step by it
+             * @example business_name
+             * @example opening_hours
+             * @example payouts
+             */
+            id: string;
+            /** @description the step, as the person knows it */
+            title: string;
+            /**
+             * @description `not_started` and `in_progress` are still to do, `done` is finished, and `blocked` waits on something the person cannot do in this conversation (a review, another step), named in `reason`.
+             * @enum {string}
+             */
+            status: "not_started" | "in_progress" | "done" | "blocked";
+            /** @description what the step is for, in one or two sentences */
+            body?: string;
+            /** @description why a `blocked` step is blocked; only a `blocked` step has one */
+            reason?: string;
+            /** @description the action's words on its `next_step` card */
+            label?: string;
+            /** @description For a step finished on the tenant's own screen, a link into the tenant's app. It must start with a prefix registered for the environment and pass the link checks (`admin-v1.yaml`, `Connector.deep_link_prefixes`). The runtime removes one that fails, and the step is then shown without a card. */
+            deep_link?: string;
+        } & unknown;
+        /** @description One of the signed-in customer's kits: items a styling-kit retailer sends to try at home, each kept or returned, the kept ones charged. `status` is where the kit is in its life: `preparing` (being put together), `shipped` (on its way), `delivered` (arrived, deciding not open yet), `feedback_open` (the customer decides keep or return for each item, until `feedback_closes_at`), `feedback_closed` (the decisions are in; the items to return are due back by `return_by`), `returned` (the returned items arrived), `billed` (the kept items were charged: `order_id`), `cancelled`. A retailer whose kits skip a state (feedback opens on delivery) never sends it. "What do I still need to do" is answered by `undecided_count` and each item's `decision` before `feedback_closes_at`, and by the items to return and `return_by` after it. */
+        Kit: {
+            /** @constant */
+            type: "kit";
+            id: string;
+            /** @example October kit */
+            title?: string;
+            /** @enum {string} */
+            status: "preparing" | "shipped" | "delivered" | "feedback_open" | "feedback_closed" | "returned" | "billed" | "cancelled";
+            /** Format: date-time */
+            ordered_at?: string | null;
+            /** Format: date-time */
+            shipped_at?: string | null;
+            /** Format: date-time */
+            delivered_at?: string | null;
+            /**
+             * Format: date-time
+             * @description until when the customer decides keep or return
+             */
+            feedback_closes_at?: string | null;
+            /**
+             * Format: date-time
+             * @description when the items to return must be sent back
+             */
+            return_by?: string | null;
+            carrier?: string;
+            /** Format: uri */
+            tracking_url?: string;
+            delivery_area?: components["schemas"]["KitDeliveryArea"];
+            item_count?: number;
+            /** @description items the customer has not decided on yet */
+            undecided_count?: number;
+            /** @description a listed kit may leave them out; `get_my_kit` returns them */
+            items?: components["schemas"]["KitItem"][];
+            /** @description the order that charged the kept items, once billed */
+            order_id?: string;
+            /** @description the kit's screen in the tenant's app */
+            deep_link?: string;
+        };
+        KitItem: {
+            id: string;
+            name: string;
+            /** Format: uri */
+            image_url?: string;
+            price?: components["schemas"]["Money"];
+            /**
+             * @description the customer's, so far
+             * @enum {string}
+             */
+            decision: "keep" | "return" | "undecided";
+            /**
+             * @description for an item to return, where the return is
+             * @enum {string}
+             */
+            return_status?: "not_sent" | "in_transit" | "received";
+        };
+        /** @description Where a kit goes, as an area only. Never the street, the unit, the recipient's name or a phone number. */
+        KitDeliveryArea: {
+            suburb: string;
+            postcode: string;
+            /** @description state or province */
+            region?: string;
+            country?: string;
+        };
+        /** @description What the signed-in customer was charged or refunded, as amounts and dates: for a styling-kit retailer, the kept items of one kit. No payment instrument (card, account, wallet or token) appears in it. */
+        Order: {
+            /** @constant */
+            type: "order";
+            id: string;
+            kit_id?: string;
+            /** @enum {string} */
+            status: "pending" | "paid" | "partially_refunded" | "refunded" | "failed" | "cancelled";
+            /** Format: date-time */
+            placed_at?: string | null;
+            total: components["schemas"]["Money"];
+            charges?: components["schemas"]["OrderCharge"][];
+            /** @description the order's screen in the tenant's app */
+            deep_link?: string;
+        };
+        OrderCharge: {
+            /** @enum {string} */
+            kind: "charge" | "refund";
+            amount: components["schemas"]["Money"];
+            /** Format: date-time */
+            at: string;
+            /** @enum {string} */
+            status: "pending" | "succeeded" | "failed";
+            /** @example 2 items kept */
+            description?: string;
+        };
+        Policy: {
+            /** @constant */
+            type: "policy";
+            id: string;
+            topic: string;
+            version: string;
+            title: string;
+            /** @description plain text or simple markdown; the source of truth for answers */
+            body: string;
+            /** Format: date-time */
+            updated_at: string;
+            /** Format: uri */
+            url?: string;
+        };
+        /** @description The tenant's stable ref for a question (or a `rate_each` row), echoed in answers. */
+        QuestionId: string;
+        /** @enum {string} */
+        QuestionKind: "single_choice" | "multi_choice" | "image_choice" | "yes_no" | "list_choice" | "rate_each" | "short_text" | "long_text" | "date" | "number" | "scale" | "photo";
+        QuestionOption: {
+            /** @description The tenant's stable ref for this choice. Answers carry it, never the label. */
+            value: string;
+            label: string;
+            /**
+             * Format: uri
+             * @description on the tenant's CDN; required for `image_choice`
+             */
+            image_url?: string;
+            description?: string;
+        };
+        FlowDefinition: {
+            /** @description the published version; the submission echoes it */
+            version: number;
+            /** @description Facts the agent may use in the conversation. Nothing else about the person is sent. A field not listed here fails closed: the runtime rejects the whole definition and logs it, and the flow does not start. */
+            context: {
+                /** @description for the greeting */
+                first_name?: string;
+            };
+            /** @description In order. Every `question_id`, rows included, is unique within the definition. */
+            questions: components["schemas"]["FlowQuestion"][];
+        };
+        /** @description A question as the tenant defines it: the fields of the `question` card (`vinaverse-v1.yaml`), without the conversation's `progress`, `state` and `answer`, plus `logic` and `hints` for the agent. */
+        FlowQuestion: {
+            question_id: components["schemas"]["QuestionId"];
+            kind: components["schemas"]["QuestionKind"];
+            /** @description The question's wording. The agent phrases it conversationally unless `hints.may_rephrase` is false. */
+            prompt: string;
+            /** @description shown with the question */
+            help?: string;
+            /** @description when false the person may skip it (`answer.skipped`) */
+            required: boolean;
+            /** @description The choices, and for `rate_each` the columns. Choice kinds and `rate_each` need at least 2 and at most 12; `yes_no` needs exactly 2; `list_choice` allows up to 500. */
+            options?: components["schemas"]["QuestionOption"][];
+            /** @description fewest selections (`multi_choice`, `image_choice`) */
+            min?: number;
+            /** @description most selections (`multi_choice`, `image_choice`) */
+            max?: number;
+            /**
+             * @description offers a free-text "Other", answered with `other_text`
+             * @default false
+             */
+            allows_other: boolean;
+            /**
+             * @description With `allows_other` only: the longest "Other" text (`other_text`), in Unicode code points; 500 when absent. A longer `ui.answer` is rejected with `invalid_value`, and Other text the agent takes from a typed message is held to it too: the runtime asks for a shorter one and never submits a longer one. The app enforces it as the person types.
+             * @default 500
+             */
+            other_max_length: number;
+            /** @description an exclusive choice, answered as `values` with its `value` alone */
+            none_of_the_above?: {
+                value: string;
+                label: string;
+            };
+            /** @description `rate_each` only: each row is rated on the `options` scale and answered on its own `question_id` */
+            rows?: {
+                question_id: components["schemas"]["QuestionId"];
+                label: string;
+                /** Format: uri */
+                image_url?: string;
+            }[];
+            /** @description `short_text` (max_length at most 200) and `long_text` (at most 2000) */
+            text?: {
+                max_length: number;
+            };
+            number?: {
+                min: number;
+                max: number;
+                step: number;
+                /**
+                 * @example cm
+                 * @example kg
+                 * @example years
+                 */
+                unit?: string;
+            };
+            /** @description optional bounds, inclusive */
+            date?: {
+                /** Format: date */
+                min?: string;
+                /** Format: date */
+                max?: string;
+            };
+            scale?: {
+                min: number;
+                max: number;
+                step: number;
+                min_label: string;
+                max_label: string;
+            };
+            /** @description The app uploads the photo to the tenant (never through Vinaverse) and answers with the `upload_ref` the tenant issued. */
+            photo?: {
+                max_bytes: number;
+                mime_types: string[];
+            };
+            /** @description Forward-only jumps, tested in order once this question is answered. The first rule that matches moves the conversation to `jump_to`, or ends the flow on `end`. When none matches, the next question in order follows. Questions jumped over are not asked and not submitted. */
+            logic?: components["schemas"]["FlowJump"][];
+            hints?: components["schemas"]["FlowHints"];
+        } & (unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown & unknown);
+        /** @description A condition on option values and where it leads: exactly one of `jump_to` (a question later in the definition) or `end: true`. */
+        FlowJump: {
+            when: {
+                /** @description the question whose answer is tested; this one when absent, otherwise an earlier one */
+                question_id?: components["schemas"]["QuestionId"];
+                /**
+                 * @description `any`: at least one of `values` was selected; `all`: every one; `none`: none of them
+                 * @default any
+                 * @enum {string}
+                 */
+                match: "any" | "all" | "none";
+                values: string[];
+            };
+            jump_to?: components["schemas"]["QuestionId"];
+            /** @constant */
+            end?: true;
+        } & (unknown | unknown);
+        /** @description For the agent only. Never shown to the person as written. */
+        FlowHints: {
+            /** @description what the question is for; what to explain when asked why */
+            intent?: string;
+            /** @default true */
+            may_rephrase: boolean;
+            examples?: string[];
+            /** @description what to ask or say when an answer is vague */
+            follow_up?: string;
+            /** @description By option value, the words people use for it. Typed text maps to one of the card's values, to `other_text` when allowed, or to "unclear", and the agent then asks again with the options shown. */
+            synonyms?: {
+                [key: string]: string[];
+            };
+        };
+        /** @description Exactly one of: `values` (option values, validated against the card; one for single-choice kinds), `other_text` (the free-text "Other", when `allows_other`), `text`, `number`, `date` (YYYY-MM-DD), `upload_ref` (`photo`) or `skipped` (only when the question is not `required`). The one combination is `values` with `other_text`, for a `single_choice` or `multi_choice` question that `allows_other`: the person picked options and also typed an "Other". On any other question it is refused (`not_allowed`). */
+        QuestionAnswer: {
+            values: string[];
+        } | {
+            other_text: string;
+        } | {
+            values: string[];
+            other_text: string;
+        } | {
+            text: string;
+        } | {
+            number: number;
+        } | {
+            /** Format: date */
+            date: string;
+        } | {
+            upload_ref: string;
+        } | {
+            /** @constant */
+            skipped: true;
+        };
+        FlowSubmission: {
+            /** @description the definition version the answers follow */
+            version: number;
+            /** @description Chosen by Vinaverse, once per submission attempt with a new body, and reused only to repeat the same body. The same id with a different body is `409 SUBMISSION_ID_REUSED` (see `submit_flow`). */
+            submission_id: string;
+            /** @description One per question on the path the person took, a `rate_each` row counting as a question, so up to 100 questions of 50 rows each. A question that was not required and that the person skipped carries `skipped: true`. Questions the logic jumped over are left out. */
+            answers: {
+                question_id: components["schemas"]["QuestionId"];
+                answer: components["schemas"]["QuestionAnswer"];
+            }[];
+            /** @description By `question_id`, extra things the person volunteered while answering. The tenant stores them as remarks and never treats them as answers. May be empty. */
+            remarks: {
+                [key: string]: string;
+            };
+        };
+        /**
+         * @description A coded refusal. `question_id` names the question to ask again; it is absent only for `VERSION_NOT_ACCEPTED`. What the agent does with each code: - `REQUIRED_MISSING`: asks the question it left out; - `UNKNOWN_VALUE`: asks again with the options shown; - `TOO_LONG`: asks again, with the length limit; - `TOO_MANY`: asks again, with the most selections allowed (the question's `max`); selections only; - `TOO_FEW`: asks again, with the fewest selections allowed (the question's `min`); selections only; - `OUT_OF_RANGE`: a `number` or `scale` answer below `min`, above `max` or off `step`; asks again with
+         *       the range;
+         *     - `BAD_DATE`: asks again for a valid date, within the question's bounds; - `UPLOAD_NOT_FOUND`: asks for the photo again (the tenant has no upload under that `upload_ref`); - `VERSION_NOT_ACCEPTED`: fetches the definition again.
+         *     An unknown code is handled like `REQUIRED_MISSING` on the named question. An unknown code without a `question_id` is handled like `VERSION_NOT_ACCEPTED`: the agent fetches the definition again, walks it, and asks what is missing. If nothing is, it reports `flow.completed` with `refused` and that code.
+         *     The runtime forwards the code to the app in `flow.completed.code`, a free string. **Rollout:** send `TOO_MANY`, `TOO_FEW`, `BAD_DATE`, `UPLOAD_NOT_FOUND` and `OUT_OF_RANGE` only once the runtime release that handles them is live.
+         */
+        FlowSubmissionRefusal: {
+            /** @constant */
+            status: 422;
+            /** @enum {string} */
+            code: "REQUIRED_MISSING" | "UNKNOWN_VALUE" | "TOO_LONG" | "VERSION_NOT_ACCEPTED" | "TOO_MANY" | "TOO_FEW" | "BAD_DATE" | "UPLOAD_NOT_FOUND" | "OUT_OF_RANGE";
+            question_id?: components["schemas"]["QuestionId"];
+            detail?: string;
+        };
+        /** @description The `submission_id` was already used with a different body. The second body was not stored. `stored` is the result the tenant holds for that id, which the runtime takes as that id's outcome. It submits again under a new id only when `stored` is a refusal. */
+        FlowSubmissionConflict: {
+            /** @constant */
+            status: 409;
+            /** @constant */
+            code: "SUBMISSION_ID_REUSED";
+            stored: {
+                /** @enum {string} */
+                result: "accepted" | "refused";
+                /** @enum {string} */
+                code?: "REQUIRED_MISSING" | "UNKNOWN_VALUE" | "TOO_LONG" | "VERSION_NOT_ACCEPTED" | "TOO_MANY" | "TOO_FEW" | "BAD_DATE" | "UPLOAD_NOT_FOUND" | "OUT_OF_RANGE";
+                question_id?: components["schemas"]["QuestionId"];
+            } & (unknown & unknown & unknown);
+            detail?: string;
+        };
+    };
+    responses: {
+        /** @description Problem details. The status decides what the runtime does with the refusal, never `code`: only a `401` ends the session's tool access, a `403` fails that call only, and any other `4xx` or `5xx` fails it as the status says. `code` must agree with the status; the runtime reads it only for `IDEMPOTENCY_KEY_REUSED` (a `create_proposal` `409`), for `invalid_argument` with `field` and `example` (a `create_proposal` `422`), and, on the catalogue sweep, for `invalid_argument` with `field` (a `422` naming an input the sweep did not send skips that optional step). */
+        Problem: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/problem+json": {
+                    status: number;
+                    /** @enum {string} */
+                    code: "not_found" | "forbidden" | "invalid_argument" | "unavailable" | "token_expired";
+                    detail?: string;
+                    /** @description `invalid_argument` on `create_proposal`: the argument at fault, as a JSON Pointer into the body (`/changes/address/postal_code`) */
+                    field?: string;
+                    /** @description `invalid_argument` on `create_proposal`: a valid value the agent can offer when it asks again */
+                    example?: string;
+                };
+            };
+        };
+    };
+    parameters: {
+        /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+        VinaverseSession: string;
+        /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+        VinaverseConversation: string;
+        Q: string;
+        Lat: number;
+        Lng: number;
+        RadiusMiles: number;
+        /** @description minor units */
+        MaxPrice: number;
+        /** @description rating × 1,000,000 */
+        MinRatingPpm: number;
+        Limit: number;
+        Cursor: string;
+        /** @description the flow's name, as registered for the tenant in Studio */
+        Flow: string;
+    };
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    resolve_place: {
+        parameters: {
+            query: {
+                text: string;
+                near_lat?: number;
+                near_lng?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        places: components["schemas"]["Place"][];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    list_services: {
+        parameters: {
+            query: {
+                q: string;
+                limit?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        services: components["schemas"]["CatalogService"][];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    search_professionals: {
+        parameters: {
+            query?: {
+                q?: components["parameters"]["Q"];
+                category_id?: string;
+                service_type_id?: string;
+                lat?: components["parameters"]["Lat"];
+                lng?: components["parameters"]["Lng"];
+                radius_miles?: components["parameters"]["RadiusMiles"];
+                /** @description only professionals with an open slot that day (subject timezone) */
+                date?: string;
+                time_from?: string;
+                time_to?: string;
+                /** @description minor units */
+                max_price?: components["parameters"]["MaxPrice"];
+                /** @description rating × 1,000,000 */
+                min_rating_ppm?: components["parameters"]["MinRatingPpm"];
+                sort?: "relevance" | "nearest" | "top_rated" | "price_low";
+                limit?: components["parameters"]["Limit"];
+                cursor?: components["parameters"]["Cursor"];
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        results: components["schemas"]["ProfessionalSummary"][];
+                        next_cursor?: string | null;
+                        total_estimate?: number;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    list_services_in_area: {
+        parameters: {
+            query?: {
+                lat?: components["parameters"]["Lat"];
+                lng?: components["parameters"]["Lng"];
+                radius_miles?: components["parameters"]["RadiusMiles"];
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AreaInventory"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    search_workspaces: {
+        parameters: {
+            query?: {
+                q?: components["parameters"]["Q"];
+                space_category?: string;
+                lat?: components["parameters"]["Lat"];
+                lng?: components["parameters"]["Lng"];
+                radius_miles?: components["parameters"]["RadiusMiles"];
+                /** @description minor units */
+                max_price?: components["parameters"]["MaxPrice"];
+                /** @description rating × 1,000,000 */
+                min_rating_ppm?: components["parameters"]["MinRatingPpm"];
+                sort?: "relevance" | "nearest" | "top_rated" | "price_low";
+                limit?: components["parameters"]["Limit"];
+                cursor?: components["parameters"]["Cursor"];
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        results: components["schemas"]["WorkspaceSummary"][];
+                        next_cursor?: string | null;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_professional: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ProfessionalDetail"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_workspace: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["WorkspaceDetail"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_availability: {
+        parameters: {
+            query: {
+                professional_id: string;
+                service_id: string;
+                from: string;
+                /** @description at most 14 days after from */
+                to: string;
+                limit?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        type?: "slot_list";
+                        /** @description stable id for this answer, e.g. a hash of the query */
+                        id?: string;
+                        professional_id: string;
+                        service_id: string;
+                        timezone: string;
+                        slots: {
+                            /** Format: date-time */
+                            start: string;
+                            /** Format: date-time */
+                            end: string;
+                        }[];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_quote: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+                "Idempotency-Key": string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    professional_id: string;
+                    service_id: string;
+                    /** Format: date-time */
+                    start: string;
+                };
+            };
+        };
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Quote"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    list_my_bookings: {
+        parameters: {
+            query?: {
+                scope?: "upcoming" | "past";
+                limit?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        bookings: components["schemas"]["Booking"][];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_my_booking: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Booking"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    list_my_kits: {
+        parameters: {
+            query?: {
+                scope?: "current" | "past";
+                limit?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        kits: components["schemas"]["Kit"][];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_my_kit: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Kit"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    list_my_orders: {
+        parameters: {
+            query?: {
+                kit_id?: string;
+                limit?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        orders: components["schemas"]["Order"][];
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_my_order: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Order"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_policy: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                /** @description A marketplace's topics, and a retailer's: `shipping` (delivery times and costs), `returns`, `exchanges`, `billing` (when and how kept items are charged) and `kit_window` (how long a customer has to decide and to send items back). Answers about a rule come only from the tenant's published document. */
+                topic: "fees" | "cancellation" | "refunds" | "no_show" | "rentals" | "classes" | "rent_links" | "payments" | "account" | "safety" | "reviews" | "shipping" | "returns" | "exchanges" | "billing" | "kit_window";
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Policy"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_setup_state: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SetupState"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    create_handoff: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+                "Idempotency-Key": string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /**
+                     * @description A marketplace's categories, and a retailer's: `order_or_delivery` (a kit or order that is late, lost or wrong), `return_or_exchange`, `product_quality` (an item damaged or faulty) and `fit_or_sizing`.
+                     * @enum {string}
+                     */
+                    category: "booking_problem" | "payment_or_refund" | "account_access" | "safety_concern" | "listing_issue" | "complaint" | "asked_for_human" | "assistant_could_not_help" | "other" | "order_or_delivery" | "return_or_exchange" | "product_quality" | "fit_or_sizing";
+                    /** @description written by the agent for the support person who picks it up */
+                    summary: string;
+                    /** @enum {string} */
+                    urgency: "normal" | "high";
+                    related?: {
+                        /** @enum {string} */
+                        type: "booking" | "professional" | "workspace" | "quote" | "kit" | "kit_item" | "order";
+                        id: string;
+                    }[];
+                    vinaverse_session_id?: string;
+                    /**
+                     * Format: uri
+                     * @description a signed Vinaverse URL, valid 30 days, where staff can read the conversation
+                     */
+                    transcript_url?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        type: "ticket";
+                        id: string;
+                        /**
+                         * @description When and how a person will reply, as a phrase that completes the sentence the runtime says after a handoff, "I've passed this to the support team, and they'll reply {expected_response}.": `within one business day by email`, never a sentence of its own (no capital letter at the start, no full stop at the end).
+                         * @example within one business day by email
+                         * @example by email within 1 business day
+                         */
+                        expected_response: string;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    create_proposal: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+                "Idempotency-Key": string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /**
+                     * @example business_address
+                     * @example opening_hours
+                     */
+                    topic: string;
+                    /** @description by field key, the proposed value, in the shape of one of the `ProposalField` types */
+                    changes: {
+                        [key: string]: string | components["schemas"]["ProposalMoney"] | components["schemas"]["TimeRange"] | components["schemas"]["PostalAddress"] | components["schemas"]["TextList"] | components["schemas"]["WeeklyHours"];
+                    };
+                    /** @description what the person said that led to it */
+                    reason?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Created, pending */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Proposal"];
+                };
+            };
+            /** @description The `Idempotency-Key` was already used with a different `{topic, changes}`; nothing new was created */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": {
+                        /** @constant */
+                        status: 409;
+                        /** @constant */
+                        code: "IDEMPOTENCY_KEY_REUSED";
+                        proposal: components["schemas"]["Proposal"];
+                        detail?: string;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    get_flow_definition: {
+        parameters: {
+            query?: {
+                /** @description the version the conversation started on; absent, the version currently published */
+                version?: number;
+            };
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                /** @description the flow's name, as registered for the tenant in Studio */
+                flow: components["parameters"]["Flow"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FlowDefinition"];
+                };
+            };
+            /** @description The requested `version` is no longer accepted; fetch the current version (no `version`) */
+            410: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": {
+                        /** @constant */
+                        status: 410;
+                        /** @constant */
+                        code: "VERSION_GONE";
+                        detail?: string;
+                    };
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+    submit_flow: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description on every tool call in a session, a channel session's included (never on the catalogue sweep), the session's id; informational and not signed */
+                "Vinaverse-Session"?: components["parameters"]["VinaverseSession"];
+                /** @description on every tool call of a session that belongs to a conversation (never on the catalogue sweep), its id; informational and not signed */
+                "Vinaverse-Conversation"?: components["parameters"]["VinaverseConversation"];
+            };
+            path: {
+                /** @description the flow's name, as registered for the tenant in Studio */
+                flow: components["parameters"]["Flow"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FlowSubmission"];
+            };
+        };
+        responses: {
+            /** @description Accepted */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @constant */
+                        ok: true;
+                    };
+                };
+            };
+            /** @description The `submission_id` was already used with a different body; nothing new was stored */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["FlowSubmissionConflict"];
+                };
+            };
+            /** @description Refused; nothing was stored as accepted */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["FlowSubmissionRefusal"];
+                };
+            };
+            default: components["responses"]["Problem"];
+        };
+    };
+}
+
+/**
+ * Why a tool call's signature was refused, in the conformance vectors' words
+ * (vinaverse-contracts `conformance/tool-calls.json`), checked in their order:
+ * - `missing`: no `Vinaverse-Signature` header.
+ * - `malformed`: no valid `t`, or no valid nonce (16 to 64 of `A-Z a-z 0-9 - _`).
+ * - `stale`: signed more than 300 seconds from now, either way.
+ * - `v2_required`: no `v2` (a v1-only header binds neither the token nor a nonce).
+ * - `mismatch`: no `v2` matches with any secret: a wrong secret, or a method,
+ *   target, delegated token or body other than the ones signed.
+ * - `replayed`: a valid signature whose nonce was already taken.
+ */
+type ToolSignatureErrorCode = 'missing' | 'malformed' | 'stale' | 'v2_required' | 'mismatch' | 'replayed';
+interface ToolSignatureError {
+    readonly code: ToolSignatureErrorCode;
+    readonly message: string;
+}
+interface ToolCallToVerify {
+    /** The HTTP method. */
+    method: string;
+    /** The request target exactly as received: path and query, still percent-escaped. */
+    target: string;
+    /** The delegated token from the `Authorization: Bearer` header. */
+    token: string;
+    /** The body as received; `undefined`, `null` or empty for none. */
+    body?: Uint8Array | null | undefined;
+    /** The `Vinaverse-Signature` header. */
+    header: string | null | undefined;
+}
+interface VerifyToolCallOptions {
+    /** The tool signing secret, or two during a rotation. */
+    secrets: readonly string[];
+    nonces: NonceStore;
+    now: Date;
+    toleranceSeconds?: number;
+}
+/**
+ * Checks a tool call's v2 signature and takes its nonce. Returns null when the
+ * call is authentic and fresh. The nonce is claimed only after a signature
+ * matched, so a forged header cannot burn a real call's nonce.
+ */
+declare function verifyToolCall(call: ToolCallToVerify, options: VerifyToolCallOptions): Promise<ToolSignatureError | null>;
+
+type Op<K extends ToolOperationId> = operations[K];
+type ParamsOf<K extends ToolOperationId, Where extends string> = Op<K>['parameters'] extends Record<Where, infer P> ? [P] extends [never | undefined] ? Record<string, never> : NonNullable<P> : Record<string, never>;
+/** A tool's request body, as the contract types it. */
+type ToolBody<K extends ToolOperationId> = Op<K> extends {
+    requestBody: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : Op<K> extends {
+    requestBody?: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B | undefined : undefined;
+type SuccessOf<R> = R extends {
+    200: infer S;
+} ? S : R extends {
+    201: infer S;
+} ? S : never;
+/** A tool's success result, as the contract types it. */
+type ToolResult<K extends ToolOperationId> = SuccessOf<Op<K>['responses']> extends {
+    content: {
+        'application/json': infer B;
+    };
+} ? B : never;
+/** What a handler receives. */
+interface ToolCall<K extends ToolOperationId, P> {
+    readonly operation: K;
+    /** What `authenticate` returned for the delegated token. */
+    readonly principal: P;
+    /** The session's delegated token (verified as signed; its meaning is the tenant's). */
+    readonly token: string;
+    readonly params: ParamsOf<K, 'path'>;
+    readonly query: ParamsOf<K, 'query'>;
+    readonly body: ToolBody<K>;
+    /** The informational headers Vinaverse sends (not signed). */
+    readonly session: {
+        readonly id?: string;
+        readonly conversationId?: string;
+        readonly toolCallId?: string;
+        readonly requestId?: string;
+    };
+    readonly idempotencyKey?: string;
+}
+/**
+ * A handler per served operation; one the tenant does not serve answers 404.
+ * Handlers validate what they act on: the toolkit checks the call's origin and
+ * shape, not the meaning of its values. A `submit_flow` handler refuses only
+ * with `ToolRefusal.flowRefused` (the contract's `FlowSubmissionRefusal`); any
+ * other 422 from it is answered as a 500 and reported to `onError`.
+ */
+type ToolHandlers<P> = {
+    [K in ToolOperationId]?: (call: ToolCall<K, P>) => K extends 'submit_flow' ? Accepting : Promise<ToolResult<K>> | ToolResult<K>;
+};
+type Accepted = ToolResult<'submit_flow'>;
+type Accepting = Promise<void | Accepted> | void | Accepted;
+interface ToolProviderOptions<P> {
+    /** The tool signing secret, or two during a rotation. */
+    secret: string | readonly string[];
+    /** Where nonces are taken: shared by every instance (`@vinaverse/server/stores`). */
+    nonces: NonceStore;
+    /** Where idempotent answers are kept: shared by every instance. */
+    idempotency: IdempotencyStore;
+    /**
+     * The path of the tool base URL registered in Studio (`/api/v2/ai` for
+     * `https://tenant.example.com/api/v2/ai`); routes are matched below it.
+     */
+    basePath?: string;
+    /**
+     * Resolves the delegated token to the tenant's principal (the person and
+     * what the token lets them do). Throw `ToolRefusal.tokenExpired()` for a
+     * token that is not valid.
+     */
+    authenticate(token: string, operation: ToolOperationId): Promise<P> | P;
+    handlers: ToolHandlers<P>;
+    /**
+     * For `create_proposal`: the stored proposal's current state, read again on
+     * a replay (the contract returns its current `status`). Default: as stored.
+     */
+    currentProposal?(stored: ToolResult<'create_proposal'>, principal: P): Promise<ToolResult<'create_proposal'>> | ToolResult<'create_proposal'>;
+    /**
+     * An error the toolkit answered with a 500 (a handler's, a result over its
+     * limit, a refusal the contract does not allow), or one it worked around (an
+     * answer it could not store).
+     */
+    onError?(error: unknown, operation: ToolOperationId | undefined): void;
+    /**
+     * A call whose signature was refused, with the reason (`stale`, `mismatch`,
+     * `replayed`, …): the 403 itself says only that the signature was refused.
+     */
+    onRefused?(reason: ToolSignatureErrorCode, message: string): void;
+    /**
+     * Scopes idempotent answers, for example to the tenant or environment of the
+     * principal: a stored answer is replayed only to a call with the same scope.
+     */
+    scope?(principal: P, operation: ToolOperationId): string;
+    /**
+     * How long a running call holds its idempotency key, in seconds; default 60.
+     * Set it above the longest your handlers can run: a resend after it lapses
+     * runs the handler again.
+     */
+    leaseSeconds?: number;
+    /** The largest request body accepted, in bytes; default 1 MiB. */
+    maxRequestBytes?: number;
+    toleranceSeconds?: number;
+    now?: () => Date;
+}
+interface ToolRequest {
+    method: string;
+    /** The request target exactly as received: path and query, percent-escaped. */
+    target: string;
+    /** Header lookup by name, any case. */
+    header(name: string): string | undefined;
+    body: string | Uint8Array | ArrayBuffer | null | undefined;
+}
+interface ToolResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+/** How long idempotent answers are kept (seconds), and a pending call holds its key. */
+declare const KEEP_SECONDS: {
+    readonly submit_flow: number;
+    readonly create_proposal: number;
+    readonly default: 86400;
+    readonly pending: 60;
+};
+declare const MAX_REQUEST_BYTES: number;
+/** A run's idempotency lease lapsed and another run took the key: its answer was sent but not stored. */
+declare class LeaseLostError extends Error {
+    constructor(operation: ToolOperationId, leaseSeconds: number);
+}
+declare class ResultTooLargeError extends Error {
+    constructor(operation: ToolOperationId, bytes: number, limit: number);
+}
+interface ToolProvider {
+    handle(request: ToolRequest): Promise<ToolResponse>;
+}
+declare function createToolProvider<P>(options: ToolProviderOptions<P>): ToolProvider;
+
+export { verifyToolCall as A, type ConversationEvent as C, KEEP_SECONDS as K, LeaseLostError as L, MAX_REQUEST_BYTES as M, type ReadBody as R, type ToolProvider as T, type WebhookHandlerOptions as W, type WebhookError as a, type ConversationEventType as b, type ConversationState as c, ResultTooLargeError as d, TOOL_OPERATIONS as e, type ToolBody as f, type ToolCall as g, type components as h, type ToolHandlers as i, type ToolOperationId as j, type ToolProviderOptions as k, type ToolRequest as l, type ToolResponse as m, type ToolResult as n, type operations as o, type ToolSignatureError as p, type ToolSignatureErrorCode as q, WEBHOOK_EVENT_TYPES as r, type WebhookEnvelope as s, type WebhookErrorCode as t, type WebhookEvent as u, type WebhookEventOf as v, type WebhookEventType as w, type WebhookResponse as x, createToolProvider as y, isConversationEvent as z };