@nxisai/agent-harness 0.4.1 → 0.6.0

package/README.md

@@ -211,6 +211,7 @@ Both flags go false at a specialist handoff, which swaps the system prompt and t
 | `preload` | `'eager' \| 'idle' \| 'none'` | `'idle'` | When weights are fetched. Local provider only. Settable mid-session. |
 | `debug` | `boolean` | `false` | Shows tool receipts and route labels. |
 | `preferences` | `AgentPreferences` | session-scoped | See [Preferences](#preferences). |
+| `handoff` | `HandoffConfig \| null` | `null` | Hand conversations to other agents and people. See [Handoff](#handoff-to-an-agent-or-a-person). |
 
 ### Attributes
 
@@ -435,7 +436,7 @@ const card = viewJourney(steps);   // { title, steps, outcome, active, summary }
 ### `AgentCoordinator`
 
 ```ts
-new AgentCoordinator({ agents, rules, fallback, provider?, descriptions?, onRoute? })
+new AgentCoordinator({ agents, rules, fallback, provider?, descriptions?, onRoute?, handoff? })
 coordinator.turn(goal, messages): Promise<TurnResult>
 coordinator.stop(): void                 // the classifier and the agent that took the turn
 coordinator.turn(goal, messages): Promise<TurnResult>
@@ -558,10 +559,12 @@ Serving requirements:
 - Discovery failure is never fatal. The agent keeps running with whatever the page registered itself, and `connectTools` returns the reason in `warning`.
 - Once connected, the harness also asks the server for every Schema.org Action on the site (one public `nxis_query`, cached in the tab for ten minutes), and registers them as tools, so the agent can reach the whole site's forms from whichever page it was opened on. Actions whose page is on another origin are ignored. A failed query leaves everything else working, and `connectTools` reports it in `warning`. `site-actions="false"` skips the query.
 - **One tool per form, not per page.** Actions sharing a name and a field list become a single tool: the listings demo's 38 per-business quote forms register as one `quote_form_anywhere`. The field whose default value differs between them — the site's own name for the target, such as `business` — becomes a required choice, and defaults to this page's action when the agent is on one. Where no field tells them apart, a `target` field named after each page is added instead.
-- **Named for the reach they add** — `quote_form_anywhere` beside the page's own `quote_form`. These are couriers rather than second copies of a form: one captures an action's inputs wherever the agent is, carries them to the page that can submit them, and calls the tool there, never filling a field itself. The distinct name is also mechanical: a repeated name is a duplicate registration, so the polyfill would replace the very tool the courier delegates to, and a native registry rejects it. On the page an action belongs to, the courier calls the page's tool directly and that page tool is hidden from the model, so there is one route per action rather than two.
+- **Named for the reach they add** — `quote_form_anywhere` beside the page's own `quote_form`. These are couriers rather than second copies of a form: one captures an action's inputs wherever the agent is, carries them to the page that can submit them, and calls the tool there, never filling a field itself. The distinct name is also mechanical: a repeated name is a duplicate registration, which a WebMCP registry rejects — and the courier needs the page's tool to stay registered. On the page an action belongs to, the courier calls the page's tool directly and that page tool is hidden from the model, so there is one route per action rather than two.
 - **Only what a turn could need reaches the prompt.** Every registered tool's schema goes into every prompt, so a site with many distinct forms would fill the context with forms nobody asked about. Past `maxSiteTools` (default 8), the tools covering the current page are kept and the rest compete on how well they answer what was asked — a business named in the request matches the choice that names it. Only site-wide tools are ever dropped; the page's own tools and the retrieval tools stay.
 - **A form can only be submitted on its own page**, since running an action means filling that form. Calling one from elsewhere collects and confirms the values where the visitor is — the button reads "Open & submit" rather than "Submit", and the card says which page it will open — then stores the confirmed call, navigates, and submits once the page has loaded. The stored call holds what someone typed, so it lives in the tab's `sessionStorage`, expires after two minutes, and is read exactly once, which is what stops a reload from submitting twice.
 - **Results link to their pages, and the agent can open them.** A record's `url` is often the site root rather than its page, so the harness also fetches the site's page records (a second `nxis_query`, on `@type` containing `Page`, cached the same way) and adds the pages its actions live on. A result card gets an "Open page" link when its page can be told — from `mainEntityOfPage`, an `@id` formed from its page (`page.html#organization`), a `url` deeper than the root, a page whose `mainEntity` or `about` is the record, or a single page with the record's name — and an `open_page` tool lets "take me to that page" work in conversation — along with "take me home" (the page record at `/` or `/index.html`, else the site root) and "go back" (`history.back()`, only when the previous page was on this site). It needs no confirmation, only opens pages on this origin, and carries the conversation across, so the thread continues on the page it opened. `connectTools({ openPage: false })` leaves the tool out.
+- **The agent can walk the site, not only open a page by name.** Every page's `BreadcrumbList` is fetched in a third cached `nxis_query` and the trails are inverted into a graph: each page's sections above it, the pages beside and under it, and the pages it links to (`significantLink`, `relatedLink`). `open_page` then understands `up` — "up a level", "the section above" — and the name of anything near the page, and its list of destinations is the pages around this one rather than the whole site. A `page_links` tool reports where the visitor is and what leads where, so "what else is in this section" is answered without navigating. A site that publishes no trails behaves exactly as before.
+- **A rate-limited read is waited out, not reported as an empty site.** The MCP server answers a read over the site's limit with how long to wait ("Retry after 52s"), and the harness waits exactly that, twice at most, and never longer than a minute — then says so in words the agent can pass on. Connecting spends two reads (actions, pages); the breadcrumb trails are fetched the first time navigation needs them, so a small plan's budget is not gone before the visitor has asked anything.
 - `discover="false"` skips all of this.
 
 ### A2UI
@@ -572,6 +575,26 @@ import { emitAsk, emitStep, emitConfirm, toV09 } from '@nxisai/agent-harness/a2u
 
 Messages are authored against A2UI v1.0 and downgraded with `toV09` for the published `@a2ui/lit` renderer.
 
+## Handoff to an agent or a person
+
+The assistant can hand a conversation to another agent that can finish what it can't, or to a person on the site's team. Both are reached over [A2A 1.0](https://a2a-protocol.org/latest/specification/), through a relay the site hosts on its own origin, so the page holds no credential and never talks to a target directly.
+
+```ts
+agent.handoff = {
+  relay: '/api/handoff',
+  targets: {
+    booking: { kind: 'agent', label: 'Booking', description: 'books a service visit' },
+    team: { kind: 'person', label: 'Our team' },
+  },
+};
+```
+
+That offers two tools, `transfer_to_agent` and `talk_to_a_person`, listing only the targets both this config and the relay name. They are consequential: the visitor sees who the conversation goes to and the summary that goes with it, and presses **Send**. From then on what the visitor types goes to the target — its replies appear under its name, a bar above the input says who is listening, and **Back to the assistant** ends it. When the target finishes, the assistant carries on from its hand-back note ("Booked for Thursday, reference CL-4KDQ-7M2X"). A handoff survives page changes and reloads.
+
+Headless, `HandoffController` runs the same handoffs and reports them as `handoff` events; `registerHandoffTools` offers the tools; `AgentCoordinator`'s `handoff` option routes a handed-off conversation's turns to its target.
+
+[docs/handoff.md](docs/handoff.md) is the contract: the relay's endpoints, the handoff extension (`https://nxis.ai/a2a/handoff/v1`: the envelope, queue, operator and hand-back parts), the lifecycle, what makes a good target, and the adapter contract for putting a help desk behind A2A. [Copperline](https://github.com/nxisai/copperline-home-services) has a reference of each part on Netlify: the relay, an A2A booking agent built on `@a2a-js/sdk`, and a human desk with an operator console.
+
 ## Requirements
 
 - WebGPU: Chrome or Edge 113+, or Safari 18+.

package/dist/handoff/a2a.d.ts

@@ -0,0 +1,152 @@
+/**
+ * A small A2A 1.0 client, over JSON-RPC, for talking to a site's handoff relay.
+ *
+ * Only what a handoff needs: send a message (streamed or not), read a task,
+ * subscribe to one, cancel one. The official `@a2a-js/sdk` covers the whole
+ * protocol, but brings a JWT library and protobuf and gRPC peers with it, and
+ * this harness ships nothing it doesn't use.
+ *
+ * The wire format is A2A 1.0's JSON: parts and stream events are told apart by
+ * which member they carry (`text`, `data`, `statusUpdate`, …), and enums are
+ * their names (`TASK_STATE_WORKING`, `ROLE_USER`). Servers still on 0.3 send
+ * `kind` discriminators and lower-case states; those are read too.
+ *
+ * @see https://a2a-protocol.org/latest/specification/
+ * @module
+ */
+/** The A2A protocol version this client speaks, sent as `A2A-Version`. */
+export declare const A2A_VERSION = "1.0";
+/** A task's state, by its A2A 1.0 name. */
+export type A2ATaskState = 'TASK_STATE_UNSPECIFIED' | 'TASK_STATE_SUBMITTED' | 'TASK_STATE_WORKING' | 'TASK_STATE_COMPLETED' | 'TASK_STATE_FAILED' | 'TASK_STATE_CANCELED' | 'TASK_STATE_INPUT_REQUIRED' | 'TASK_STATE_REJECTED' | 'TASK_STATE_AUTH_REQUIRED';
+/** One piece of a message or artifact. Which member is present says what it is. */
+export interface A2APart {
+    text?: string;
+    data?: unknown;
+    url?: string;
+    raw?: string;
+    filename?: string;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A message, from the visitor (`ROLE_USER`) or the target (`ROLE_AGENT`). */
+export interface A2AMessage {
+    messageId: string;
+    role: 'ROLE_USER' | 'ROLE_AGENT';
+    parts: A2APart[];
+    contextId?: string;
+    taskId?: string;
+    metadata?: Record<string, unknown>;
+    extensions?: string[];
+}
+/** Where a task stands, and the message that goes with it, if any. */
+export interface A2ATaskStatus {
+    state: A2ATaskState;
+    message?: A2AMessage;
+    timestamp?: string;
+}
+/** Output a task produced. */
+export interface A2AArtifact {
+    artifactId?: string;
+    name?: string;
+    parts: A2APart[];
+    metadata?: Record<string, unknown>;
+}
+/** A unit of work at the target. */
+export interface A2ATask {
+    id: string;
+    contextId?: string;
+    status: A2ATaskStatus;
+    artifacts?: A2AArtifact[];
+    history?: A2AMessage[];
+    metadata?: Record<string, unknown>;
+}
+/** One event on a stream, or the result of a send: exactly one member is set. */
+export interface A2AStreamResponse {
+    task?: A2ATask;
+    message?: A2AMessage;
+    statusUpdate?: {
+        taskId: string;
+        contextId?: string;
+        status: A2ATaskStatus;
+        metadata?: Record<string, unknown>;
+    };
+    artifactUpdate?: {
+        taskId: string;
+        contextId?: string;
+        artifact: A2AArtifact;
+        append?: boolean;
+        lastChunk?: boolean;
+    };
+}
+/** An error the relay or the target answered with. */
+export declare class A2AError extends Error {
+    /** The JSON-RPC error code, or the HTTP status when the relay refused before A2A. */
+    readonly code: number;
+    /** The HTTP status of the response. */
+    readonly status?: number | undefined;
+    /** Seconds to wait, from `Retry-After`, when the relay is rate limiting. */
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, 
+    /** The JSON-RPC error code, or the HTTP status when the relay refused before A2A. */
+    code: number, 
+    /** The HTTP status of the response. */
+    status?: number | undefined, 
+    /** Seconds to wait, from `Retry-After`, when the relay is rate limiting. */
+    retryAfter?: number | undefined);
+}
+/** Options for {@link A2AClient}. */
+export interface A2AClientOptions {
+    /** Where requests go: the relay's URL for one target, `/api/handoff/booking`. */
+    endpoint: string;
+    /** Extensions to announce in `A2A-Extensions`. */
+    extensions?: string[];
+    /** `fetch` to use. Defaults to the global. */
+    fetchImpl?: typeof fetch;
+}
+/** What a call returned, with the response headers the relay may have set. */
+export interface A2AReply<T> {
+    result: T;
+    headers: Headers;
+}
+/** A stream of events, and the response headers it opened with. */
+export interface A2AStream {
+    events: AsyncGenerator<A2AStreamResponse, void, undefined>;
+    headers: Headers;
+}
+/** A2A over JSON-RPC to one endpoint. */
+export declare class A2AClient {
+    private readonly opts;
+    constructor(opts: A2AClientOptions);
+    /**
+     * Call a method that answers once: `SendMessage`, `GetTask`, `CancelTask`.
+     *
+     * @throws {@link A2AError} when the relay refuses or the target answers with an error.
+     */
+    call<T>(method: string, params: unknown, init?: {
+        signal?: AbortSignal;
+        headers?: Record<string, string>;
+    }): Promise<A2AReply<T>>;
+    /**
+     * Call a method that answers with a stream: `SendStreamingMessage`, `SubscribeToTask`.
+     *
+     * The generator ends when the server closes the stream, which it does at a
+     * terminal state, or earlier if the host cuts the response off.
+     *
+     * @throws {@link A2AError} when the relay refuses; an error event on the stream
+     * is thrown from the generator.
+     */
+    stream(method: string, params: unknown, init?: {
+        signal?: AbortSignal;
+        headers?: Record<string, string>;
+    }): Promise<A2AStream>;
+    private post;
+}
+/** A task state by its 1.0 name, whichever version sent it. */
+export declare function taskState(raw: unknown): A2ATaskState;
+/** A result in 1.0's shape, whether it came as 1.0 or 0.3 (`kind` discriminators). */
+export declare function normaliseResponse(raw: A2AStreamResponse | Record<string, unknown>): A2AStreamResponse;
+/** Whether a state ends the task. */
+export declare function isTerminal(state: A2ATaskState): boolean;
+/** A message id, unique enough for one conversation. */
+export declare function newMessageId(): string;
+//# sourceMappingURL=a2a.d.ts.map

package/dist/handoff/a2a.d.ts.map

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

package/dist/handoff/a2a.js

@@ -0,0 +1,227 @@
+/**
+ * A small A2A 1.0 client, over JSON-RPC, for talking to a site's handoff relay.
+ *
+ * Only what a handoff needs: send a message (streamed or not), read a task,
+ * subscribe to one, cancel one. The official `@a2a-js/sdk` covers the whole
+ * protocol, but brings a JWT library and protobuf and gRPC peers with it, and
+ * this harness ships nothing it doesn't use.
+ *
+ * The wire format is A2A 1.0's JSON: parts and stream events are told apart by
+ * which member they carry (`text`, `data`, `statusUpdate`, …), and enums are
+ * their names (`TASK_STATE_WORKING`, `ROLE_USER`). Servers still on 0.3 send
+ * `kind` discriminators and lower-case states; those are read too.
+ *
+ * @see https://a2a-protocol.org/latest/specification/
+ * @module
+ */
+/** The A2A protocol version this client speaks, sent as `A2A-Version`. */
+export const A2A_VERSION = '1.0';
+/** An error the relay or the target answered with. */
+export class A2AError extends Error {
+    constructor(message, 
+    /** The JSON-RPC error code, or the HTTP status when the relay refused before A2A. */
+    code, 
+    /** The HTTP status of the response. */
+    status, 
+    /** Seconds to wait, from `Retry-After`, when the relay is rate limiting. */
+    retryAfter) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.retryAfter = retryAfter;
+        this.name = 'A2AError';
+    }
+}
+let nextId = 1;
+/** A2A over JSON-RPC to one endpoint. */
+export class A2AClient {
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Call a method that answers once: `SendMessage`, `GetTask`, `CancelTask`.
+     *
+     * @throws {@link A2AError} when the relay refuses or the target answers with an error.
+     */
+    async call(method, params, init = {}) {
+        const res = await this.post(method, params, 'application/json', init);
+        const body = (await res.json().catch(() => null));
+        if (!body)
+            throw new A2AError(`Empty answer to ${method}`, -32603, res.status);
+        if (body.error)
+            throw new A2AError(body.error.message, body.error.code, res.status);
+        return { result: body.result, headers: res.headers };
+    }
+    /**
+     * Call a method that answers with a stream: `SendStreamingMessage`, `SubscribeToTask`.
+     *
+     * The generator ends when the server closes the stream, which it does at a
+     * terminal state, or earlier if the host cuts the response off.
+     *
+     * @throws {@link A2AError} when the relay refuses; an error event on the stream
+     * is thrown from the generator.
+     */
+    async stream(method, params, init = {}) {
+        const res = await this.post(method, params, 'text/event-stream', init);
+        const type = res.headers.get('content-type') ?? '';
+        // A server may answer a streaming request with a single JSON response: an
+        // error, or a target without streaming that replied at once.
+        if (!type.includes('text/event-stream')) {
+            const body = (await res.json().catch(() => null));
+            if (body?.error)
+                throw new A2AError(body.error.message, body.error.code, res.status);
+            const once = body?.result;
+            return {
+                headers: res.headers,
+                events: (async function* () {
+                    if (once)
+                        yield normaliseResponse(once);
+                })(),
+            };
+        }
+        return { headers: res.headers, events: readEvents(res, init.signal) };
+    }
+    async post(method, params, accept, init) {
+        const doFetch = this.opts.fetchImpl ?? fetch;
+        const res = await doFetch(this.opts.endpoint, {
+            method: 'POST',
+            credentials: 'same-origin',
+            signal: init.signal,
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: accept,
+                'A2A-Version': A2A_VERSION,
+                ...(this.opts.extensions?.length ? { 'A2A-Extensions': this.opts.extensions.join(',') } : {}),
+                ...init.headers,
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', id: nextId++, method, params }),
+        });
+        if (!res.ok) {
+            const retry = Number(res.headers.get('retry-after'));
+            let message = `${method} refused (${res.status})`;
+            try {
+                const body = (await res.json());
+                const text = typeof body.error === 'string' ? body.error : (body.error?.message ?? body.message);
+                if (text)
+                    message = text;
+            }
+            catch {
+                // Not JSON: keep the status line.
+            }
+            throw new A2AError(message, res.status, res.status, Number.isFinite(retry) && retry > 0 ? retry : undefined);
+        }
+        return res;
+    }
+}
+/** Server-sent events off a response body, as A2A stream responses. */
+async function* readEvents(res, signal) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            if (signal?.aborted)
+                return;
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let cut;
+            while ((cut = boundary(buffer)) >= 0) {
+                const block = buffer.slice(0, cut);
+                buffer = buffer.slice(cut).replace(/^(\r?\n){2}/, '');
+                const event = parseBlock(block);
+                if (event)
+                    yield event;
+            }
+        }
+        const tail = parseBlock(buffer);
+        if (tail)
+            yield tail;
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+}
+/** Where the first complete event block ends, or -1. */
+function boundary(buffer) {
+    const m = /\r?\n\r?\n/.exec(buffer);
+    return m ? m.index : -1;
+}
+/** One SSE block's `data:` lines, as a stream response; null for comments and keep-alives. */
+function parseBlock(block) {
+    const data = block
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice(5).replace(/^ /, ''))
+        .join('\n');
+    if (!data.trim())
+        return null;
+    const body = JSON.parse(data);
+    if (body.error)
+        throw new A2AError(body.error.message, body.error.code);
+    return body.result ? normaliseResponse(body.result) : null;
+}
+/** 0.3 event and state names, read as 1.0's. */
+const LEGACY_STATES = {
+    submitted: 'TASK_STATE_SUBMITTED',
+    working: 'TASK_STATE_WORKING',
+    completed: 'TASK_STATE_COMPLETED',
+    failed: 'TASK_STATE_FAILED',
+    canceled: 'TASK_STATE_CANCELED',
+    'input-required': 'TASK_STATE_INPUT_REQUIRED',
+    rejected: 'TASK_STATE_REJECTED',
+    'auth-required': 'TASK_STATE_AUTH_REQUIRED',
+};
+/** A task state by its 1.0 name, whichever version sent it. */
+export function taskState(raw) {
+    const s = String(raw ?? '');
+    if (s.startsWith('TASK_STATE_'))
+        return s;
+    return LEGACY_STATES[s] ?? 'TASK_STATE_UNSPECIFIED';
+}
+/** A result in 1.0's shape, whether it came as 1.0 or 0.3 (`kind` discriminators). */
+export function normaliseResponse(raw) {
+    const r = raw;
+    if (r.task || r.message || r.statusUpdate || r.artifactUpdate) {
+        const out = { ...r };
+        if (out.task)
+            out.task = { ...out.task, status: { ...out.task.status, state: taskState(out.task.status?.state) } };
+        if (out.statusUpdate) {
+            out.statusUpdate = { ...out.statusUpdate, status: { ...out.statusUpdate.status, state: taskState(out.statusUpdate.status?.state) } };
+        }
+        return out;
+    }
+    switch (r.kind) {
+        case 'task':
+            return normaliseResponse({ task: r });
+        case 'message':
+            return { message: r };
+        case 'status-update':
+            return normaliseResponse({ statusUpdate: r });
+        case 'artifact-update':
+            return { artifactUpdate: r };
+        default:
+            // A bare task, as `GetTask` returns one.
+            if (typeof r.id === 'string' && r.status)
+                return normaliseResponse({ task: r });
+            return {};
+    }
+}
+/** Whether a state ends the task. */
+export function isTerminal(state) {
+    return (state === 'TASK_STATE_COMPLETED' ||
+        state === 'TASK_STATE_FAILED' ||
+        state === 'TASK_STATE_CANCELED' ||
+        state === 'TASK_STATE_REJECTED');
+}
+/** A message id, unique enough for one conversation. */
+export function newMessageId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `m-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+//# sourceMappingURL=a2a.js.map

package/dist/handoff/a2a.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a.js","sourceRoot":"","sources":["../../src/handoff/a2a.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,CAAC;AAqEjC,sDAAsD;AACtD,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,YACE,OAAe;IACf,qFAAqF;IAC5E,IAAY;IACrB,uCAAuC;IAC9B,MAAe;IACxB,4EAA4E;IACnE,UAAmB;QAE5B,KAAK,CAAC,OAAO,CAAC,CAAC;QANN,SAAI,GAAJ,IAAI,CAAQ;QAEZ,WAAM,GAAN,MAAM,CAAS;QAEf,eAAU,GAAV,UAAU,CAAS;QAG5B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAwBD,IAAI,MAAM,GAAG,CAAC,CAAC;AAEf,yCAAyC;AACzC,MAAM,OAAO,SAAS;IACpB,YAA6B,IAAsB;QAAtB,SAAI,GAAJ,IAAI,CAAkB;IAAG,CAAC;IAEvD;;;;OAIG;IACH,KAAK,CAAC,IAAI,CACR,MAAc,EACd,MAAe,EACf,OAAmE,EAAE;QAErE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAqE,CAAC;QACtH,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,QAAQ,CAAC,mBAAmB,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/E,IAAI,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACpF,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IAC5D,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,CACV,MAAc,EACd,MAAe,EACf,OAAmE,EAAE;QAErE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,IAAI,CAAC,CAAC;QACvE,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QACnD,0EAA0E;QAC1E,6DAA6D;QAC7D,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAExC,CAAC;YACT,IAAI,IAAI,EAAE,KAAK;gBAAE,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YACrF,MAAM,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC;YAC1B,OAAO;gBACL,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,CAAC,KAAK,SAAS,CAAC;oBACtB,IAAI,IAAI;wBAAE,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;gBAC1C,CAAC,CAAC,EAAE;aACL,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IACxE,CAAC;IAEO,KAAK,CAAC,IAAI,CAChB,MAAc,EACd,MAAe,EACf,MAAc,EACd,IAAgE;QAEhE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;QAC7C,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC5C,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,aAAa;YAC1B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,MAAM;gBACd,aAAa,EAAE,WAAW;gBAC1B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7F,GAAG,IAAI,CAAC,OAAO;aAChB;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;SACvE,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;YACrD,IAAI,OAAO,GAAG,GAAG,MAAM,aAAa,GAAG,CAAC,MAAM,GAAG,CAAC;YAClD,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgE,CAAC;gBAC/F,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;gBACjG,IAAI,IAAI;oBAAE,OAAO,GAAG,IAAI,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACP,kCAAkC;YACpC,CAAC;YACD,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC/G,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAED,uEAAuE;AACvE,KAAK,SAAS,CAAC,CAAC,UAAU,CAAC,GAAa,EAAE,MAAoB;IAC5D,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO;IACtB,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;YACZ,IAAI,MAAM,EAAE,OAAO;gBAAE,OAAO;YAC5B,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,IAAI,GAAW,CAAC;YAChB,OAAO,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBACnC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;gBACtD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;gBAChC,IAAI,KAAK;oBAAE,MAAM,KAAK,CAAC;YACzB,CAAC;QACH,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,IAAI;YAAE,MAAM,IAAI,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,wDAAwD;AACxD,SAAS,QAAQ,CAAC,MAAc;IAC9B,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED,8FAA8F;AAC9F,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,IAAI,GAAG,KAAK;SACf,KAAK,CAAC,OAAO,CAAC;SACd,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;SAC1C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;SAC9C,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA8E,CAAC;IAC3G,IAAI,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,gDAAgD;AAChD,MAAM,aAAa,GAAiC;IAClD,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,oBAAoB;IAC7B,SAAS,EAAE,sBAAsB;IACjC,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,qBAAqB;IAC/B,gBAAgB,EAAE,2BAA2B;IAC7C,QAAQ,EAAE,qBAAqB;IAC/B,eAAe,EAAE,0BAA0B;CAC5C,CAAC;AAEF,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,GAAY;IACpC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,CAAiB,CAAC;IAC1D,OAAO,aAAa,CAAC,CAAC,CAAC,IAAI,wBAAwB,CAAC;AACtD,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,iBAAiB,CAAC,GAAgD;IAChF,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;QAC9D,MAAM,GAAG,GAAG,EAAE,GAAI,CAAuB,EAAE,CAAC;QAC5C,IAAI,GAAG,CAAC,IAAI;YAAE,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;QACnH,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;YACrB,GAAG,CAAC,YAAY,GAAG,EAAE,GAAG,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,GAAG,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;QACvI,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAuB,EAAE,CAAC,CAAC;QAC9D,KAAK,SAAS;YACZ,OAAO,EAAE,OAAO,EAAE,CAA0B,EAAE,CAAC;QACjD,KAAK,eAAe;YAClB,OAAO,iBAAiB,CAAC,EAAE,YAAY,EAAE,CAAiD,EAAE,CAAC,CAAC;QAChG,KAAK,iBAAiB;YACpB,OAAO,EAAE,cAAc,EAAE,CAAmD,EAAE,CAAC;QACjF;YACE,yCAAyC;YACzC,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM;gBAAE,OAAO,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAuB,EAAE,CAAC,CAAC;YACtG,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,UAAU,CAAC,KAAmB;IAC5C,OAAO,CACL,KAAK,KAAK,sBAAsB;QAChC,KAAK,KAAK,mBAAmB;QAC7B,KAAK,KAAK,qBAAqB;QAC/B,KAAK,KAAK,qBAAqB,CAChC,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY;IAC1B,MAAM,CAAC,GAAI,UAAkC,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC,EAAE,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IACzC,OAAO,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACnF,CAAC"}

package/dist/handoff/controller.d.ts

@@ -0,0 +1,181 @@
+import { type HandBack, type HandoffEnvelope } from './envelope.js';
+/** Who a target is: software, or a person behind a desk. */
+export type HandoffKind = 'agent' | 'person';
+/** A target as the page knows it: a name, and how to present it. */
+export interface HandoffTargetConfig {
+    kind: HandoffKind;
+    /** What the visitor reads: "You're talking with *Booking*". */
+    label: string;
+    /** What it handles, for the model choosing between targets. */
+    description?: string;
+}
+/** Where handoffs go. */
+export interface HandoffConfig {
+    /** The relay on the site's own origin, `/api/handoff`. */
+    relay: string;
+    /** The targets, by the name the relay knows them by. */
+    targets: Record<string, HandoffTargetConfig>;
+}
+/** A target as the relay reports it, merged with the page's config. */
+export interface HandoffTarget extends HandoffTargetConfig {
+    name: string;
+    /** Whether it can take a handoff now. A desk outside its hours cannot. */
+    available: boolean;
+    /** When a desk is staffed, as a person should read it. */
+    hours?: string;
+    /** How many are waiting at a desk. */
+    queueLength?: number;
+    /** Expected wait at a desk, in minutes. */
+    waitMinutes?: number | null;
+    /** Whether the relay allows the recent transcript to be shared with it. */
+    transcript: boolean;
+}
+/** Where a handoff stands. See the lifecycle table in `docs/handoff.md`. */
+export type HandoffState = 'connecting' | 'queued' | 'active' | 'awaiting-visitor' | 'handed-back' | 'ended' | 'failed';
+/** Whether a handoff in this state is over. */
+export declare const isHandoffOver: (state: HandoffState) => boolean;
+/** One conversation's handoff, as kept between pages. */
+export interface HandoffSession {
+    conversationId: string;
+    target: string;
+    label: string;
+    kind: HandoffKind;
+    state: HandoffState;
+    taskId?: string;
+    contextId?: string;
+    /** The relay's `Nxis-Handoff-Key`, proving this browser started the task. */
+    key?: string;
+    /** Who is speaking at the target, once a person or agent has said. */
+    operator?: string;
+    /** Place in a desk's queue, while queued. */
+    queue?: {
+        position?: number;
+        waitMinutes?: number;
+    };
+    handBack?: HandBack;
+    /** Why it failed, in words for the visitor. */
+    error?: string;
+    startedAt: number;
+    updatedAt: number;
+    /** Message ids already shown, so a resumed task's history is not shown twice. */
+    seen: string[];
+}
+/** What the controller reports, as the `detail` of a `handoff` event. */
+export type HandoffEvent = {
+    type: 'state';
+    conversationId: string;
+    session: HandoffSession;
+    state: HandoffState;
+} | {
+    type: 'message';
+    conversationId: string;
+    session: HandoffSession;
+    /** Who said it: the operator's name, or the target's label. */
+    from: string;
+    fromKind: HandoffKind;
+    text: string;
+} | {
+    type: 'handback';
+    conversationId: string;
+    session: HandoffSession;
+    handBack: HandBack;
+};
+/** Options for {@link HandoffController}. */
+export interface HandoffControllerOptions extends HandoffConfig {
+    /** `fetch` to use. Defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Where sessions are kept. Defaults to `localStorage`; null keeps them in memory only. */
+    storage?: Storage | null;
+    /** The clock. */
+    now?: () => number;
+    /** First wait before picking up a stream the host cut off. Doubles up to 15 s. */
+    resumeDelayMs?: number;
+}
+/** The response header a relay ties a task to this browser with. */
+export declare const HANDOFF_KEY_HEADER = "Nxis-Handoff-Key";
+/** Runs handoffs for every conversation on the page. Dispatches `handoff` events. */
+export declare class HandoffController extends EventTarget {
+    private readonly opts;
+    private readonly sessions;
+    /** The stream open for each conversation, so a new one can close it first. */
+    private readonly live;
+    /** Consecutive resumes that brought nothing, per conversation, for backoff. */
+    private readonly idle;
+    private readonly timers;
+    private targetsCache;
+    /** Events reported so far, so a stream can tell whether it brought anything new. */
+    private reported;
+    private readonly storage;
+    private loaded;
+    constructor(opts: HandoffControllerOptions);
+    /** The page's target config. */
+    get config(): HandoffConfig;
+    /**
+     * The targets that can be offered: those both in the page's config and on
+     * the relay's list, with the relay's availability.
+     *
+     * Cached for thirty seconds. A relay that can't be reached offers none.
+     */
+    targets(): Promise<HandoffTarget[]>;
+    private fetchTargets;
+    /** A conversation's handoff, open or finished, if it has one. */
+    session(conversationId: string): HandoffSession | null;
+    /** A conversation's handoff while it is open, else null. */
+    active(conversationId: string | undefined): HandoffSession | null;
+    /**
+     * Hand a conversation to a target.
+     *
+     * Resolves once the relay has accepted it; what the target says arrives as
+     * events. Call only after the visitor has confirmed what is being sent.
+     *
+     * @throws When the target is not configured, the conversation is already
+     * handed off, or the relay refuses. The session is marked failed first.
+     */
+    start(conversationId: string, target: string, envelope: HandoffEnvelope): Promise<HandoffSession>;
+    /**
+     * Send what the visitor typed to the target handling this conversation.
+     *
+     * @throws When nothing is handed off, or the target hasn't answered yet.
+     */
+    send(conversationId: string, text: string): Promise<void>;
+    /**
+     * End a handoff at the visitor's request: "Back to the assistant".
+     *
+     * Cancels the task at the target. A target that won't cancel still loses the
+     * visitor: the handoff is ended here either way.
+     */
+    end(conversationId: string): Promise<void>;
+    /**
+     * Pick up an open handoff after a page change or reload.
+     *
+     * Subscribes to the task while it runs, or reads it once when it is waiting
+     * on the visitor. Safe to call for any conversation, at any time: it does
+     * nothing when there is no open handoff or a stream is already open.
+     */
+    resume(conversationId: string): Promise<void>;
+    /** Stop every stream and pending resume. The sessions stay saved for the next page. */
+    dispose(): void;
+    private client;
+    private keyHeader;
+    /** A fresh abort signal for a conversation's stream, closing the one before it. */
+    private openLive;
+    private closeLive;
+    /** Read a stream to its end, then resume it if the task is still running. */
+    private pump;
+    /** Read a task once, for a handoff that can't or needn't be streamed. */
+    private readOnce;
+    private apply;
+    private adopt;
+    private status;
+    private stateFor;
+    /** One message from the target: who is speaking, a hand-back, and the words. */
+    private message;
+    private parts;
+    private remember;
+    private setState;
+    private emit;
+    private now;
+    private load;
+    private save;
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/handoff/controller.d.ts.map

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