@nxisai/agent-harness 0.5.0 → 0.7.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
 
@@ -221,6 +222,7 @@ Both flags go false at a specialist handoff, which swaps the system prompt and t
 | `mode` | `fullscreen` (default), `window`, `inline` | Cover the page; dock in the corner at `--window-w` × `--window-h` (400 × 620); or fill the box the host puts it in and stay open — for a copilot rail the host lays out. Below 520px a window covers the page anyway. |
 | `discover` | `"false"` | Skip remote MCP discovery. |
 | `site-actions` | `"false"` | Don't fetch the actions on other pages of the site. |
+| `prompt-style` | `"classic"` | Use the separate ask, "Ready to send" and "Submitted" cards of earlier versions instead of the action card. |
 | `cache` | `"false"` | Do not store model files in Cache Storage. |
 | `model-host` | URL | Fetch weights from another origin. |
 | `model-path-template` | string | Path template under `model-host`. |
@@ -283,9 +285,19 @@ Given the tool the model picked and everything already known, the harness asks w
 |---|---|---|
 | read (`readOnlyHint`) | none | runs, no UI |
 | read | some | asks only for those, then runs |
-| write | none | confirm card, one Submit |
-| write | one | asks for one field, then confirms |
-| write | several | stepper, then confirms |
+| write | none | action card: what will be sent, and Send |
+| write | some | action card: what it has, the fields still needed, then Send |
+
+### The action card
+
+A write, and a handoff to an agent or a person, is one message in the conversation rather than a series of cards. The card names who it goes to (the business the form belongs to, or the team or agent and whether they are available now), then moves through:
+
+1. **Fill in**: what the agent already has, editable, under "What I have", and anything still needed under "Still needed" (for a handoff to a team that is away, "Where should they reply?"). The button says what is missing until nothing is.
+2. **Review**: one sentence saying what will happen ("I'll send this quote form to Hatzel & Sons Plumbing. They'll reply to dana@example.com."), the details behind "What they'll get", and Send or Not now. A form on another page says it will be sent from there.
+3. **Sending**: the steps as they run, on this page or the one it opens.
+4. **Sent**, **Handed to …**, or **It didn't go through** with the form's reason and "Change and try again".
+
+The card is saved with the conversation and replaces the step-by-step journey card for that request. `prompt-style="classic"` brings back the earlier cards; a custom renderer opts in to the same behaviour with `inlinePrompts` and `left` (see [`HarnessRenderer`](#harnessrenderer)).
 
 Values merge in this order, last wins: schema default, page context, saved preferences, model arguments.
 
@@ -397,6 +409,8 @@ interface HarnessRenderer {
   step?(step: AgentStep, all: AgentStep[]): void;
   dismissPrompt?(): void;
   stoppable?(canStop: boolean): void;    // false once a tool call has gone out
+  inlinePrompts?: boolean;               // prompts speak for themselves: no "One more thing for …" line
+  left?(tool, destination): void;        // a confirmed call is leaving for its page, instead of "Opening …"
 }
 ```
 
@@ -435,7 +449,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>
@@ -574,6 +588,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":"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"}

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