@happyvertical/smrt-chat 0.51.39 → 0.53.0

package/dist/svelte/components/assistant/assistant-choices.svelte.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Choices: the assistant offers 1–4 options, the person picks one.
+ *
+ * The proposal counterpart of `assistant_propose_action` for work that has
+ * several good answers — "crop this tighter", "find me a picture of the
+ * arena". The page registers a {@link AssistantChoiceSource} while it can
+ * serve one; the dock offers each source to the model as a browser tool
+ * (`assistant_offer_<source id>`, effect `read`). When the model calls it the
+ * dock asks the SOURCE for the options (the model never supplies them), shows
+ * them as cards in the chat, and returns only their ids and labels to the
+ * model. Nothing changes until the person clicks a card: only then does the
+ * dock call the source's `apply`, in the page, as the person. The model has
+ * no way to apply an option.
+ *
+ * Images on the cards are restricted to same-origin paths (`/…`), so a
+ * source cannot leak a signed provider URL and an injected prompt cannot make
+ * the dock load a remote address.
+ *
+ * Options that take a while (generated pictures) arrive later: the offer
+ * carries `pending`, the cards show "Making…" placeholders and the source's
+ * `fill` adds options as they finish. The person can pick any option that
+ * has arrived. Such an offer is not replaced by the person's next message
+ * (it cost real work); "None of these" stops it.
+ *
+ * Previewing: a source that implements `preview` shows a pick in place on
+ * the page WITHOUT applying it. A click on a card only previews (another
+ * click swaps the preview; the offer's `original` card shows the page as it
+ * was); nothing is committed until the person presses the offer's commit
+ * button (`commit`, which applies the previewed option and resolves the
+ * offer). Cancel (`cancel`), dismissing, clearing the conversation and
+ * disposing all restore the original. The model still only offers.
+ */
+import type { AssistantClientToolCall, AssistantClientToolResult } from '../../../assistant-turn-events.js';
+import type { AssistantClientTool } from './client-tools.js';
+/** Tool-name prefix for choice sources (add `assistant_offer_*` to a server allow-list). */
+export declare const ASSISTANT_CHOICE_TOOL_PREFIX = "assistant_offer_";
+/** At most this many options are shown for one offer. */
+export declare const ASSISTANT_CHOICE_MAX_OPTIONS = 4;
+/** One option the person can pick. */
+export interface AssistantChoiceOption {
+    /** Stable within the offer; what `apply` receives back. */
+    id: string;
+    /** Short plain label ("Square", "Arena at night"). */
+    label: string;
+    /** One optional plain sentence under the label. */
+    description?: string;
+    /** Same-origin preview path (`/…`); anything else is dropped. */
+    imageUrl?: string;
+    /** Alt text for the preview; defaults to the label. */
+    imageAlt?: string;
+    /** Source-owned data carried to `apply` (never shown, never sent to the model). */
+    value?: unknown;
+}
+/** How a pending offer reports progress (see {@link AssistantChoicePending}). */
+export interface AssistantChoicePendingUpdate {
+    /** Add finished options (normalized; at most 4 in the whole offer). */
+    add(options: AssistantChoiceOption[]): void;
+    /** Replace the plain progress line. */
+    status(message: string): void;
+}
+/** Options still being made, added to the cards as they finish. */
+export interface AssistantChoicePending {
+    /** A plain line while they are made ("Making versions… about a minute"). */
+    message: string;
+    /** How many options are coming, for placeholders (1–4; default 4 less the ready ones). */
+    expected?: number;
+    /**
+     * Called once, after the cards show. Call `update.add` as options finish,
+     * and resolve when there are no more. Throw an `Error` with a plain
+     * message when making them failed; it is shown on the cards. `signal`
+     * aborts when the person dismisses the offer (or picks an option, or the
+     * conversation is cleared): stop polling then.
+     */
+    fill(update: AssistantChoicePendingUpdate, signal: AbortSignal): Promise<void>;
+}
+/** What a source offers for one request. */
+export interface AssistantChoiceOffer {
+    /** A plain heading for the cards ("Pick a crop"). */
+    title: string;
+    /** The ready options (may be empty when `pending` is set). */
+    options: AssistantChoiceOption[];
+    /** More options are being made; they are added as they finish. */
+    pending?: AssistantChoicePending;
+    /**
+     * The page as it is now, shown as the first card ("Original") when the
+     * source can `preview`: previewing it restores the page. Needs an image.
+     */
+    original?: AssistantChoiceOption;
+    /** The commit button's label when previewing (default "Use this"). */
+    commitLabel?: string;
+    /** The cancel button's label when previewing (default "Cancel"). */
+    cancelLabel?: string;
+}
+/** A page feature that can offer choices while it is on screen. */
+export interface AssistantChoiceSource {
+    /** Lowercase id, `[a-z][a-z0-9_]*`, at most 40 characters. */
+    id: string;
+    /** What the options are and when to offer them, for the model. */
+    description: string;
+    /** JSON schema of the model's arguments (default: none). */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Build the options for the model's arguments. Throw an `Error` with a
+     * plain message when there is nothing to offer; the model sees it.
+     */
+    offer(args: Record<string, unknown>, options: {
+        signal?: AbortSignal;
+    }): Promise<AssistantChoiceOffer> | AssistantChoiceOffer;
+    /**
+     * Apply the option the person clicked. Runs in the page on their click.
+     * May return a short plain line saying what changed.
+     */
+    apply(option: AssistantChoiceOption): Promise<string | undefined | void> | string | undefined | void;
+    /**
+     * Show `option` in place on the page WITHOUT saving or applying it, so the
+     * person can see it before committing. `option` is the offer's `original`
+     * to put the page back (or null when the offer had none). Runs in the page
+     * on the person's click; must never persist anything. A source that
+     * implements this gets preview-then-commit cards; one that does not keeps
+     * "click applies".
+     */
+    preview?(option: AssistantChoiceOption | null): Promise<void> | void;
+}
+/** Where the dock finds the choice sources the page has registered. */
+export interface AssistantChoiceSourceRegistry {
+    /** Register a source; returns the function that removes it. */
+    register(source: AssistantChoiceSource): () => void;
+    list(): AssistantChoiceSource[];
+}
+/** A simple in-memory registry; the latest registration of an id wins. */
+export declare function createAssistantChoiceSourceRegistry(): AssistantChoiceSourceRegistry;
+/** The browser tool name for a source. */
+export declare function choiceToolName(sourceId: string): string;
+/** A same-origin path, or null. Rejects `//host`, `\\`, schemes, and controls. */
+export declare function safeChoiceImageUrl(value: unknown): string | null;
+/** Normalize a source's options: unique ids, plain labels, safe images, at most 4. */
+export declare function normalizeChoiceOptions(options: readonly AssistantChoiceOption[]): AssistantChoiceOption[];
+/** One offer shown in the chat. */
+export interface AssistantChoiceSet {
+    /** The model's call id. */
+    id: string;
+    sourceId: string;
+    title: string;
+    options: AssistantChoiceOption[];
+    /**
+     * `waiting` for the person (options may still be arriving, see `pending`);
+     * `applying` after a click; `applied` once the source applied it;
+     * `dismissed` when the person said none (or a newer request replaced it);
+     * `failed` when applying failed (they may pick again); `unavailable` when
+     * the pending options could not be made and none arrived.
+     */
+    status: 'waiting' | 'applying' | 'applied' | 'dismissed' | 'failed' | 'unavailable';
+    chosenOptionId?: string;
+    /** The source's line about what changed. */
+    outcome?: string;
+    error?: string;
+    /** Options still being made: the progress line and how many are coming. */
+    pending?: {
+        message: string;
+        expected: number;
+    };
+    /** A plain line when some pending options could not be made. */
+    note?: string;
+    /** Kept when the person sends another message (it had pending work). */
+    lasting?: boolean;
+    /** The source can preview: a click previews, the commit button applies. */
+    previewable?: boolean;
+    /** The page as it is now (previewable offers): the "Original" card. */
+    original?: AssistantChoiceOption;
+    /** The option (or the original) now previewed; nothing is applied yet. */
+    previewOptionId?: string;
+    /**
+     * The option whose preview is being shown right now (the source has not
+     * finished). Cards and the commit button wait for it, so what is committed
+     * is always what the page shows.
+     */
+    previewPendingId?: string;
+    commitLabel?: string;
+    cancelLabel?: string;
+}
+/** The dock's choice state: offers from tool calls, and the person's picks. */
+export declare class AssistantChoices {
+    private readonly getRegistry;
+    private readonly hold?;
+    sets: AssistantChoiceSet[];
+    /** Release functions of the holds for offers still open. */
+    private readonly releases;
+    /**
+     * Per-offer preview queue and request counter: previews run one at a time
+     * in click order, so the page ends on the last click, and only the latest
+     * request updates the offer.
+     */
+    private readonly previewQueues;
+    private readonly previewRequests;
+    /** Abort controllers of pending offers still being filled. */
+    private readonly fills;
+    /**
+     * @param hold Called for each offer while it waits for the person (and
+     *   after a failed apply); returns the release, called once they picked,
+     *   dismissed, or the offer was replaced. The dock uses its run holds.
+     */
+    constructor(getRegistry: () => AssistantChoiceSourceRegistry | undefined, hold?: ((set: AssistantChoiceSet) => () => void) | undefined);
+    /** Keep one hold per open offer (`waiting` or `failed`). */
+    private syncHolds;
+    private sources;
+    private source;
+    /** The browser tools for the registered sources. */
+    tools(): AssistantClientTool[];
+    isChoiceTool(name: string): boolean;
+    /** Number of offers waiting for the person. */
+    get waitingCount(): number;
+    /** The progress line of an offer still being made with nothing to pick yet. */
+    get pendingMessage(): string | null;
+    private update;
+    /** Run a model call to a choice tool: ask the source, show the cards. */
+    offerFromCall(call: AssistantClientToolCall, signal?: AbortSignal): Promise<AssistantClientToolResult>;
+    /** Run a pending offer's `fill`, adding its options as they finish. */
+    private fill;
+    /** Stop filling an offer (it was picked, dismissed or cleared). */
+    private stopFill;
+    /** The person picked `optionId`: apply it through its source. */
+    choose(setId: string, optionId: string): Promise<void>;
+    /** The person wants none of these. */
+    dismiss(setId: string): void;
+    /**
+     * Put the page back if this offer is previewing something (or is about
+     * to). Queued behind any preview still running, and it cancels queued
+     * ones, so a slow preview never lands after the page was restored.
+     */
+    private restorePreview;
+    /**
+     * The person clicked a card of a previewable offer (or its `original`):
+     * show it in place. Nothing is applied.
+     */
+    preview(setId: string, optionId: string): Promise<void>;
+    /**
+     * The person pressed the commit button: apply the previewed option (the
+     * one thing that changes the page). The original, or nothing, previewed
+     * means there is nothing to apply: that is a cancel.
+     */
+    commit(setId: string): Promise<void>;
+    /** The person wants to keep the original: restore it and close the offer. */
+    cancel(setId: string): void;
+    /**
+     * A new request replaces offers still waiting, except ones that had
+     * options made for them (`lasting`): only the person dismisses those.
+     */
+    supersedeWaiting(): void;
+    clear(): void;
+}
+//# sourceMappingURL=assistant-choices.svelte.d.ts.map

package/dist/svelte/components/assistant/assistant-choices.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-choices.svelte.d.ts","sourceRoot":"","sources":["../../../../src/svelte/components/assistant/assistant-choices.svelte.ts"],"names":[],"mappings":"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"}