@genesislcap/ai-assistant 15.85.1 → 15.86.0-GENC-0.4

package/dist/ai-assistant.d.ts

@@ -1229,6 +1229,20 @@ export declare interface AiDriver extends EventTarget {
      * @beta
      */
     addInteractionInterceptor?(interceptor: InteractionInterceptor): () => void;
+    /**
+     * Run one of a pending interaction's surface actions as the person: the programmatic equivalent
+     * of clicking the widget, for a host with no DOM to click (GENC-1660). The interaction is
+     * credited to the person (`answeredBy: 'user'`), never to a claimant, and an action that finishes
+     * it settles it.
+     *
+     * Refused as `not-held` when the interaction has ended, or when a claimant holds it — one is not
+     * pushed aside; the person takes it back first, for example by pausing the autopilot. Any other
+     * refusal is as for `hold.invoke`, and nothing runs. Optional, so a third-party
+     * driver need not implement it; every shipped driver does.
+     *
+     * @beta
+     */
+    invokeAsUser?(interactionId: string, action: string, args?: unknown): Promise<InvokeResult>;
     /**
      * Show a widget in the transcript OUTSIDE any tool loop, and resolve with its result
      * (GENC-1660): `requestInteraction` for something that is not a tool handler. How a decorator
@@ -1965,6 +1979,16 @@ export declare class AutopilotDriver extends BaseDriverDecorator implements Auto
     private turnHandBack?;
     /** A mode restored with the session, waiting for its flow to become the owner again. */
     private restored?;
+    /**
+     * The mode of a hand-off's target that has released, kept for its caller, which has not taken the
+     * lock back yet (GENC-1751): the flow has no owner in between. See `carriedTo`.
+     */
+    private handingBack?;
+    /**
+     * The mode of the flow that just ended, should a one-way hand-off with nobody waiting turn out to
+     * have ended it: that switch announces itself only after the owner has changed (GENC-1751).
+     */
+    private switchedFrom?;
     /**
      * Bumped on every pause and resume, and when its sessions end. A written answer is sent only if
      * none came between asking for it and its landing: one started before a pause is stale after it,
@@ -2005,7 +2029,10 @@ export declare class AutopilotDriver extends BaseDriverDecorator implements Auto
     pause(): void;
     resume(): void;
     stop(): void;
-    /** The mode to save with the session, while it is set for the current flow. */
+    /**
+     * The mode to save with the session, while it is set for the current flow — or kept for a
+     * hand-off's caller while its target releases, saved for that target, as the stack saves it.
+     */
     getPersistedMode(): PersistedAutopilotMode | undefined;
     /**
      * Bring back a saved mode. It applies once its flow is the owner again — at once if it already
@@ -2157,6 +2184,36 @@ export declare class AutopilotDriver extends BaseDriverDecorator implements Auto
     /** A claimed interaction settled, whoever settled it. */
     private onSettled;
     private onFlowOwnerChanged;
+    /**
+     * A one-way hand-off with nobody waiting is a plain switch, the caller deactivated, so nothing on
+     * the stack says the owner it changed to took over the same task: its event, raised once the
+     * target is active, does (GENC-1751).
+     */
+    private onHandOffStarted;
+    /** The mode set for the current flow, or kept for the caller of a hand-back under way. */
+    private current;
+    /**
+     * The mode that carries to `owner` because the owner changed for a hand-off or its hand-back, as
+     * the hand-off stack shows it at that moment (GENC-1751):
+     * - a hand-off: `owner` is the top frame's target, which has not finished. Its frame is on the
+     *   stack before the target is activated, and so is a waiting caller's passed on by a one-way
+     *   hand-off from a target;
+     * - a hand-back: the top frame's target, which the mode is set for, has finished, and `owner` is
+     *   its caller, or no one while the target releases. Its frame leaves the stack only after the
+     *   caller is active again.
+     *
+     * Clear and an agents change empty the stack before the flow ends, so the mode ends with it, as
+     * it ends with any flow. A turn routed away from the target ends the hand-offs the same way.
+     */
+    private carriedTo;
+    /** Whether `owner` is the caller the top hand-off hands back to from `target`. */
+    private handsBack;
+    /**
+     * Set `carried`'s mode for `owner`, which took the task over in a hand-off or its hand-back. A
+     * pause the person chose carries with it; the autopilot's own hand-back of an interaction does
+     * not, since that interaction settled before the hand-off could start.
+     */
+    private carry;
     private capabilityFor;
     private flowOwner;
     private bindingFor;
@@ -2283,6 +2340,13 @@ export declare interface AutopilotHostState {
     readonly working: boolean;
 }
 
+/**
+ * The part of an `AutopilotHost` a session uses.
+ *
+ * @beta
+ */
+export declare type AutopilotLike = Pick<AutopilotHost, 'state' | 'subscribe' | 'pause' | 'resume' | 'stop'>;
+
 /**
  * The autopilot's mode for the current flow (GENC-1660 §4.10). `'unavailable'`: no autopilot for
  * this flow, or not yet (e.g. no approved brief). `'paused'`: available but not answering.
@@ -2696,6 +2760,11 @@ export declare abstract class BaseDriverDecorator<TInner extends AiDriver = AiDr
      * interactions. A decorator that answers interactions installs its own on `this.inner`.
      */
     addInteractionInterceptor(interceptor: InteractionInterceptor): () => void;
+    /**
+     * Forwarded: the interaction belongs to the driver that opened it. An inner driver that cannot
+     * run actions answers as if the interaction had ended.
+     */
+    invokeAsUser(interactionId: string, action: string, args?: unknown): Promise<InvokeResult>;
     presentInteraction<T = InteractionResult>(componentName: string, data: unknown, options?: InteractionRequestOptions): Promise<T>;
     provideHandlerCapability(name: string, factory: HandlerCapabilityFactory): () => void;
     getContextReserve(): ContextReserveResolution | undefined;
@@ -2788,6 +2857,28 @@ declare type BudgetDetail = NonNullable<Extract<ChatDriverResult, {
  */
 export declare function budgetPercentOf(figures: VendorBudgetFigures): number;
 
+/**
+ * The current page's diagnostic entries (GENC-1351 §5.8): the debug-log timeline entries
+ * (`message`/`turn`/`event`), the driver's external diagnostics, and one `meta-snapshot` carrying
+ * the export-time `meta` block. The assistant element reassembles these into the live log, and the
+ * persister's forward-capture path diffs them against what has already been appended to the stored
+ * stream. Extracted from the element so a host with no element (the headless session) derives its
+ * log from the same code, not a second copy that could drift.
+ *
+ * DOM-free and framework-free.
+ *
+ * @beta
+ */
+export declare function buildDiagnosticEntries(input: {
+    driver: AiDriver | undefined;
+    /** The debug-log key the meta events are kept under; none, no events. */
+    stateKey: string | undefined;
+    /** The `meta-snapshot` entry for right now (see `buildMetaSnapshot`). */
+    metaSnapshot: () => DiagnosticEntry;
+    /** The transcript to use when the driver has no raw history: the host's own copy. */
+    messages?: readonly ChatMessage[];
+}): DiagnosticEntry[];
+
 export { CachePolicy }
 
 /**
@@ -3841,6 +3932,12 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * @beta
      */
     addInteractionInterceptor(interceptor: InteractionInterceptor): () => void;
+    /**
+     * {@inheritDoc AiDriver.invokeAsUser}
+     *
+     * @beta
+     */
+    invokeAsUser(interactionId: string, action: string, args?: unknown): Promise<InvokeResult>;
     /**
      * {@inheritDoc AiDriver.presentInteraction}
      *
@@ -4788,6 +4885,69 @@ export declare type DelegatedMessage = ChatMessage & {
     delegate: string;
 };
 
+/**
+ * One action of a pending interaction, as a model reads it: a SurfaceAction cut to what is
+ * useful to choose by, with the number {@link describeInteraction} gave it. Plain data.
+ *
+ * @beta
+ */
+export declare interface DescribedAction {
+    /**
+     * The number the action is chosen by, when it is a numbered option: the same number the
+     * autopilot's list gives it, so "1" means the same option to both. Absent on a platform-owned
+     * action (`select`, `reply`) or a named, full-form one, which are chosen by `name`.
+     */
+    readonly n?: number;
+    /** The action's name: what `act` runs when it is not chosen by number. */
+    readonly name: string;
+    /** What the person would read on the button, when it differs from the name. */
+    readonly label?: string;
+    /** What a full-form action does, as its widget wrote it. */
+    readonly description?: string;
+    /** Whether it can be taken now. */
+    readonly enabled: boolean;
+    /** Why it cannot be, when it is not enabled and the widget said. */
+    readonly unavailable?: string;
+    /**
+     * What it takes: `'options'` (`select`: several, by number or label), `'text'` (written words)
+     * or `'fields'` (a JSON object fitting `argsSchema`). Absent: nothing.
+     */
+    readonly args?: 'options' | 'text' | 'fields';
+    /** The shape `fields` must fit, for an action that takes them. */
+    readonly argsSchema?: Readonly<Record<string, unknown>>;
+    /** Whether running it settles the interaction. */
+    readonly finishes: boolean;
+    /** Whether it is a written refinement: one that counts against a step's limit. */
+    readonly refines?: boolean;
+}
+
+/**
+ * What the person is being asked, as a compact JSON-serialisable record a model can read and
+ * answer (GENC-1660): the same text the autopilot is sent for the decision (`renderDecision`,
+ * so there is one rendering of a decision, not two), and its actions as data, numbered as that text
+ * numbers them, so "1" means the same option here and there.
+ *
+ * With no surface — a widget with no controller, or one that has not exposed anything yet — there
+ * is nothing to act on: `controller` is `false` (or `true` and not `ready`, while a controller that
+ * will expose a surface has not yet), `actions` is empty, and `text` is the widget as text alone.
+ *
+ * Reads the surface fresh each time, so it describes the widget as it is now.
+ *
+ * @beta
+ */
+export declare function describeInteraction(input: DescribeInteractionInput): InteractionDescription;
+
+/**
+ * The input of {@link describeInteraction}: a pending interaction as the driver knows it.
+ *
+ * @beta
+ */
+export declare interface DescribeInteractionInput {
+    readonly ctx: InteractionContext;
+    readonly componentName: string;
+    readonly data: unknown;
+}
+
 /**
  * One entry in the diagnostics stream — the debug-log timeline-entry union
  * (`message` / `turn` / `event`, as `getDebugLog()` builds) plus a point-in-time
@@ -7276,6 +7436,573 @@ export declare interface HandOffOutcome {
  */
 export declare type HandOffOutcomeKind = 'completed' | 'released' | 'cleared' | 'agent-removed' | 'state-lost';
 
+/**
+ * What `act` is given besides the action: the arguments a person would fill in.
+ *
+ * @beta
+ */
+export declare interface HeadlessActArgs {
+    /** Written words, for an action that takes `text`, such as `reply`. */
+    readonly text?: string;
+    /** Options for `select`, by number or label. */
+    readonly options?: readonly string[];
+    /** A form's fields: an object, or JSON text of one. */
+    readonly fields?: unknown;
+}
+
+/**
+ * The result of `act`: the driver's, plus the interaction as it stands when it is still open.
+ *
+ * @beta
+ */
+export declare type HeadlessActResult = InvokeResult & {
+    /** The interaction after the action, when it is still pending. */
+    readonly description?: InteractionDescription;
+};
+
+/**
+ * The current page's debug log: what `HeadlessSession.debugLog()` returns when nothing is
+ * persisted, and the fallback when the stored stream cannot be read.
+ *
+ * @beta
+ */
+export declare function headlessCurrentDebugLog(driver: AiDriver, stateKey: string, options?: HeadlessDebugOptions): DebugLog;
+
+/**
+ * What a debug log reports of the host that built it: the `meta` block's agents, state and host.
+ *
+ * @beta
+ */
+export declare interface HeadlessDebugOptions {
+    /** The configured agents, as the element's `agents` are. */
+    readonly agents?: () => readonly AgentConfig[];
+    /** The host's own debug state, shown as `meta.debug`. */
+    readonly debugState?: () => unknown;
+    /** The host name `meta.host` carries. The element's is `window.location.host`. Default `'headless'`. */
+    readonly host?: string;
+    /**
+     * The active model and its context window, which the element learns from the provider registry's
+     * status; the session has no registry, so the host says. Read each time they are needed.
+     */
+    readonly context?: () => {
+        model?: string;
+        contextLimit?: number;
+    } | undefined;
+}
+
+/**
+ * The diagnostic entries for the session so far, from the same `buildDiagnosticEntries` the
+ * browser's element and its persister use.
+ *
+ * @beta
+ */
+export declare function headlessDiagnosticEntries(driver: AiDriver, stateKey: string, options?: HeadlessDebugOptions): DiagnosticEntry[];
+
+/**
+ * What a headless session logs, one entry per thing that happened. Every entry has a `seq` (from
+ * 1, rising by one) and an `at` (an ISO time); `wait` is cursored by `seq`.
+ *
+ * @beta
+ */
+export declare type HeadlessEvent = HeadlessEventBase & (({
+    readonly type: 'decision';
+} & InteractionDescription & {
+    /** The agents that asked for it, outermost first. */
+    readonly ownerPath?: readonly string[];
+}) | {
+    readonly type: 'working';
+    readonly interactionId: string;
+    readonly component: string;
+    /** Who holds it; `'user'` when it is the person's but not ready yet. */
+    readonly heldBy: string;
+} | {
+    readonly type: 'settled';
+    readonly interactionId: string;
+    readonly component: string;
+    /** Who answered it; absent for a timeout, a stop, or one that settled by itself. */
+    readonly answeredBy?: string;
+    /** Set when the widget settled by itself and nobody answered. */
+    readonly resolvedItself?: boolean;
+    /** Set when the session settled it for a widget that settles itself in a browser. */
+    readonly auto?: boolean;
+    /** Set when the host settled it raw, bypassing the widget's actions. */
+    readonly raw?: boolean;
+} | {
+    readonly type: 'message';
+    /** One line of what the person would see, as the autopilot reads it ("Assistant: ..."). */
+    readonly text: string;
+    /** The line's full length, in characters, when `text` was cut. */
+    readonly chars?: number;
+} | {
+    readonly type: 'turn';
+    /** The driver's reason, `'done'` for a finished turn; `'error'` when it threw. */
+    readonly reason: string;
+    /** Set when the turn ended in a typed failure rather than completing. */
+    readonly failureReason?: string;
+    /** The assistant's final text for the turn, when it said any. */
+    readonly text?: string;
+    /** The text's full length, in characters, when `text` was cut. */
+    readonly chars?: number;
+} | {
+    readonly type: 'autopilot';
+    readonly mode: string;
+    readonly status: string;
+    readonly needsUser: boolean;
+    readonly working: boolean;
+    /** Why it is paused, when it said. */
+    readonly reason?: string;
+} | {
+    readonly type: 'probe';
+    /** What the host's probe reads now. */
+    readonly probe: Readonly<Record<string, unknown>>;
+    /** The keys whose values changed since the last entry. */
+    readonly changed: readonly string[];
+} | {
+    readonly type: 'error';
+    /** What failed: `'turn'`, `'auto-settle'`, `'probe'`, … */
+    readonly where: string;
+    readonly message: string;
+});
+
+/**
+ * The fields every {@link HeadlessEvent} has.
+ *
+ * @beta
+ */
+export declare interface HeadlessEventBase {
+    readonly seq: number;
+    /** When it was logged, as an ISO time. */
+    readonly at: string;
+}
+
+/**
+ * The type of a {@link HeadlessEvent}.
+ *
+ * @beta
+ */
+export declare type HeadlessEventType = HeadlessEvent['type'];
+
+/**
+ * The `meta-snapshot` entry for right now, gathered the way the assistant element gathers it
+ * (`buildMetaSnapshot` does the assembly; this reads what it reports): the live agent comes from
+ * the DRIVER, the transcript from its raw history, and the figures from the transcript, so what a
+ * headless host logs is what the browser would. The context window and model, which the element
+ * learns from its provider registry, are the host's to say.
+ *
+ * @beta
+ */
+export declare function headlessMetaSnapshot(driver: AiDriver, options?: HeadlessDebugOptions): DiagnosticEntry;
+
+/**
+ * Persistence for a {@link HeadlessSession}, as `headlessPersistence(...)` builds it. Lives apart
+ * from the session so that the session itself, and the Node entry that exports it, never reach the
+ * store, the persister or the framework they use.
+ *
+ * @beta
+ */
+export declare interface HeadlessPersistence {
+    /** The session key: the file under `sessions/` and the stream under `diag/`. */
+    readonly stateKey: string;
+    attach(host: HeadlessPersistenceHost): HeadlessPersistenceBinding;
+}
+
+/**
+ * Persistence for a `HeadlessSession`: it writes exactly what the browser writes — the
+ * `sessions/<key>` snapshot and the `diag/<key>` stream — through the platform's
+ * `SessionPersister` and the host's `SessionPersistenceProvider`, and builds the lifetime debug log
+ * from the same code as the browser's Download.
+ *
+ * Exported from the package's main entry only, NOT from the Node entry (`./chat-driver`): it
+ * reaches the session store, and through it `@genesislcap/foundation-redux`, which are not
+ * Node-clean. The `persister` it makes is the registry's, so a host can restore through
+ * `getPersister(stateKey)`.
+ *
+ * @example
+ * ```ts
+ * const session = new HeadlessSession(driver, {
+ *   persistence: headlessPersistence({ provider, stateKey: 'project-1', agents: () => agents }),
+ * });
+ * ```
+ *
+ * @beta
+ */
+export declare function headlessPersistence(options: HeadlessPersistenceOptions): HeadlessPersistence;
+
+/**
+ * A session's saving, attached to a driver: it keeps what the persister reads current and asks it
+ * to save when the browser's element would. Built by `HeadlessPersistence.attach`.
+ *
+ * @beta
+ */
+export declare interface HeadlessPersistenceBinding {
+    /** Note the prompt a person is about to send, for the flow it may start (`flowActivationPrompt`). */
+    notePrompt(text: string): void;
+    /** Save the snapshot and append the diagnostics now, rather than at the next throttled flush. */
+    flush(): Promise<void>;
+    /** The debug log for the whole session, stitched from the stored stream (see `lifetimeDebugLog`). */
+    debugLog(): Promise<DebugLog>;
+    /** Stop watching the driver and cancel pending saves. The saved session is left as it is. */
+    dispose(): void;
+}
+
+/**
+ * What a persistence binding is built from: the session's driver, and its debug-log key.
+ *
+ * @beta
+ */
+export declare interface HeadlessPersistenceHost {
+    readonly driver: AiDriver;
+    readonly sessionKey: string;
+}
+
+/**
+ * Options for {@link headlessPersistence}: where to save, and what the debug log says of the host.
+ *
+ * @beta
+ */
+export declare interface HeadlessPersistenceOptions extends HeadlessDebugOptions {
+    /** The storage backend, as a browser host supplies it. */
+    readonly provider: SessionPersistenceProvider;
+    /** The session key: the file under `sessions/` and the stream under `diag/`. */
+    readonly stateKey: string;
+}
+
+/**
+ * What `read` asks for: a view of the widget, or one of the widget's tools (not both).
+ *
+ * @beta
+ */
+export declare interface HeadlessReadRequest {
+    /** A view's name, from the description's `views`. Absent (with no `tool`): the default read. */
+    readonly view?: string;
+    /** A widget tool's name, from `HeadlessSessionOptions.widgetTools`. */
+    readonly tool?: string;
+    /** The tool's arguments. */
+    readonly args?: Record<string, unknown>;
+}
+
+/**
+ * The result of `read`: what was read as text (capped), or why it was refused.
+ *
+ * @beta
+ */
+export declare type HeadlessReadResult = {
+    readonly ok: true;
+    readonly content: string;
+    readonly error?: never;
+} | {
+    readonly ok: false;
+    readonly content?: never;
+    readonly error: string;
+};
+
+/**
+ * The result of a call that may be refused: the reason, as words, in `error`.
+ *
+ * @beta
+ */
+export declare type HeadlessResult = {
+    readonly ok: true;
+    readonly error?: never;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+
+/**
+ * What `send` may carry besides the words.
+ *
+ * @beta
+ */
+export declare interface HeadlessSendOptions {
+    readonly attachments?: ChatAttachment[];
+    /** Route the turn to this agent, as `SendMessageOptions.agent` does. */
+    readonly agent?: string;
+}
+
+/**
+ * A driver with no screen: a way for a host with no browser (a coding agent behind a small HTTP
+ * server, a test) to run a whole assistant journey as the person (GENC-1660).
+ *
+ * It watches the driver for interactions and turns the conversation into an append-only log of
+ * plain-data events (see {@link HeadlessEvent}): `decision` when the person has something to
+ * answer, `working` when someone else has it, `settled`, the visible `message`s, the end of each
+ * `turn`, the autopilot's state, and the host's own `probe`. The caller reads the log with
+ * {@link HeadlessSession.wait}, a long poll cursored by `seq`, so nothing is lost between calls.
+ * It answers with {@link HeadlessSession.act}, which runs a widget's action as a click would, with
+ * the same numbered options the autopilot is shown.
+ *
+ * It only observes: its interceptor never claims an interaction, so an autopilot on the same
+ * driver works as it always does, and what the session reports as a `decision` is what the autopilot
+ * has handed to the person. Plain classes only: no DOM, no FAST.
+ *
+ * @beta
+ */
+export declare class HeadlessSession {
+    private readonly driver;
+    private readonly options;
+    private readonly sessionKey;
+    private readonly allowRaw;
+    private readonly clock;
+    private readonly autopilotHost;
+    private readonly events;
+    private seq;
+    private readonly tracked;
+    /** What the session did to an interaction itself, for `settled` to say when the driver reports it. */
+    private readonly origin;
+    private readonly waiters;
+    private readonly teardown;
+    /** How much of the driver's history has been reported as messages. */
+    private seen;
+    /** The `send` in flight, if any. */
+    private turn;
+    /**
+     * The turn that is running, whoever started it, until the driver has been idle for a beat:
+     * `start` is where its messages begin in the history. Its `reason` and `failureReason` are what
+     * ended it, when something said.
+     */
+    private open;
+    /** History length when the last turn closed: where a turn the session did not start begins. */
+    private base;
+    private quiesceTimer;
+    private poller;
+    private readonly persistence;
+    private lastProbe;
+    private lastAutopilot;
+    private disposed;
+    constructor(driver: AiDriver, options?: HeadlessSessionOptions);
+    /**
+     * Send the person's message, and start the turn. Returns as soon as the turn has started, not
+     * when it ends: a turn includes every interaction parked on the person, so it can run as long as
+     * the journey. Its end is the `turn` event.
+     *
+     * Refused, never thrown, when the message is empty, or a turn is already running.
+     */
+    send(text: string, options?: HeadlessSendOptions): HeadlessResult;
+    /**
+     * Run one of a pending interaction's actions as the person, as a click would (the answer is
+     * credited `answeredBy: 'user'`). `action` is a number from the description's actions, or an
+     * action's name; `args` carry the text, the options (numbers or labels) or the form's fields it
+     * takes. Refused, with the reason and what is enabled, when a claimant holds the interaction,
+     * the action is unknown or disabled, or its arguments do not fit: nothing runs then.
+     *
+     * The result is the driver's `InvokeResult`, plus `description` of the interaction when it is
+     * still open.
+     */
+    act(interactionId: string, action: string | number, args?: HeadlessActArgs): Promise<HeadlessActResult>;
+    /**
+     * Settle a pending interaction raw, with `result` as the widget would have resolved it,
+     * bypassing its actions and everything they check: an escape hatch for a widget with no
+     * controller, or one that cannot be acted on. Logs `settled` with `raw: true` and records
+     * `headless.raw-resolved`. Refused when `allowRaw` is `false` or the interaction is not pending.
+     */
+    resolve(interactionId: string, result: unknown): HeadlessResult;
+    /**
+     * Read from a pending interaction without changing it: one of its views, or (with `tool`) one of
+     * the widget tools given to the session. The text is capped. A view the surface does not list is
+     * refused, naming those it does, as the autopilot's `widget_read` does.
+     */
+    read(interactionId: string, request?: HeadlessReadRequest): Promise<HeadlessReadResult>;
+    /**
+     * Wait for the log to say something, then return what it said. Resolves as soon as an event in
+     * `until` is in the log after `since` (immediately, when one already is), or at `maxWaitMs` with
+     * status `'working'`. Either way it returns every event after `since`, and `nextSeq`, the cursor
+     * for the next call: poll with it and nothing is lost.
+     */
+    wait(request: HeadlessWaitRequest): Promise<HeadlessWaitResult>;
+    /** Every event logged after `since` (default: all the log keeps), without waiting. */
+    eventsSince(since?: number): readonly HeadlessEvent[];
+    /**
+     * What is going on now: whether a turn runs, the interaction the person should answer first (and
+     * the others open behind it), the autopilot, what it has cost, and the host's probe.
+     */
+    state(): HeadlessState;
+    /**
+     * Save the session now: the snapshot, and the diagnostics appended since the last flush, rather
+     * than at the next throttled save. A no-op without `persistence`.
+     */
+    flush(): Promise<void>;
+    /**
+     * The debug log, the document the browser's Download gives. With `persistence`, the log of the
+     * whole session stitched from the stored stream with a fresh `meta-snapshot` (`lifetimeDebugLog`,
+     * the same code); without, the current page's, from `buildDiagnosticEntries`. Never throws.
+     */
+    debugLog(): Promise<DebugLog>;
+    /** Stop the running turn, when the driver can. */
+    stop(): HeadlessResult;
+    /**
+     * Pause, resume or stop the autopilot, when there is one. Pausing hands what it holds to the
+     * person, which then appears as a `decision`.
+     */
+    autopilot(mode: 'pause' | 'resume' | 'stop'): HeadlessResult;
+    /** Detach: remove the interceptor and every subscription, and release anyone waiting. */
+    dispose(): void;
+    private listen;
+    private history;
+    /** An interaction opened: watch it. Who holds it is not decided yet, so it is reported later. */
+    private onOpened;
+    /** The driver says an interaction settled, by whatever route. */
+    private onSettled;
+    /** The interaction's context was disposed: if nothing said it settled, say it did. */
+    private onEnded;
+    private settle;
+    private release;
+    /** New messages in the driver's history: report what the person would see of them. */
+    private onHistory;
+    private reportMessages;
+    private onAutopilot;
+    private autopilotSignature;
+    private describe;
+    /**
+     * Report where an interaction stands, when that has changed. A `decision` when the person holds
+     * it and can act; `working` when a claimant holds it or it is not ready yet. A `decision` is
+     * logged again only when its description changed materially: who holds it, whether it is ready
+     * or has a controller, or which actions are enabled. The text and facts alone do not count.
+     */
+    private evaluate;
+    /**
+     * Settle a widget that settles itself in a browser, as it would on mounting. Once, and only when
+     * the person holds it. Returns whether it settled it.
+     */
+    private autoSettle;
+    private readTool;
+    /**
+     * Notice a turn begin or end, whoever started it. The driver being busy (or a `send` in flight)
+     * is a turn; once it has been idle for a beat the turn is over and is reported, once. The beat
+     * covers the gaps inside one turn, such as a hand-off continuing it, which are a microtask long.
+     * A turn that begins the instant another ends, with no idle between, is reported as one.
+     */
+    private observe;
+    /** Report the open turn as ended, unless the driver is busy again. */
+    private closeTurn;
+    /** Without a shared bus nothing says a turn ended, so while one is open the driver is asked. */
+    private startPolling;
+    private stopPolling;
+    private logTurn;
+    private log;
+    private append;
+    private readProbe;
+    /** Read the probe again; a change in any top-level value is a `probe` event. */
+    private checkProbe;
+    private waited;
+}
+
+/**
+ * Options for a {@link HeadlessSession}.
+ *
+ * @beta
+ */
+export declare interface HeadlessSessionOptions {
+    /** The debug-log key its meta events go under: the driver's own. Defaults to `''`. */
+    readonly sessionKey?: string;
+    /** What the host calls itself, recorded with `headless.attached`, e.g. `'cli'`. */
+    readonly label?: string;
+    /**
+     * Widgets that settle themselves in a browser when their element mounts, with no controller
+     * to act on, by widget type: each maps the widget's `data` to the result to settle it with.
+     * When one opens the session settles it with that result (once the open has completed), logs
+     * `settled` with `auto: true`, and never reports it as a `decision`.
+     */
+    readonly autoSettle?: Readonly<Record<string, (data: unknown) => unknown>>;
+    /** The widget tools `read({ tool })` may run, as for the autopilot. */
+    readonly widgetTools?: readonly WidgetTools[];
+    /**
+     * Host state shown in `state()` as `probe`, e.g. its app phase. Read again at every event; a
+     * change in any top-level value is logged as a `probe` event.
+     */
+    readonly probe?: () => Record<string, unknown>;
+    /** Whether `resolve` (settling an interaction raw) is allowed. Default `true`. */
+    readonly allowRaw?: boolean;
+    /**
+     * The autopilot, when the driver handed to the session is not itself one (a decorator wrapped
+     * over it hides it). Default: the driver, when it has the shape of an `AutopilotHost`.
+     */
+    readonly autopilot?: AutopilotLike;
+    /** The time source for `at`, in milliseconds. Default `Date.now`. */
+    readonly clock?: () => number;
+    /**
+     * Where the session is saved, as `headlessPersistence(...)` builds it: the same
+     * `sessions/<key>` snapshot and `diag/<key>` stream the browser writes. Absent: nothing is
+     * saved, and `debugLog()` is the current page's.
+     */
+    readonly persistence?: HeadlessPersistence;
+    /**
+     * What `debugLog()` reports of the host when nothing is persisted (with `persistence` its own
+     * options are used instead).
+     */
+    readonly debug?: HeadlessDebugOptions;
+    /**
+     * The bus the driver was built with (`ChatDriver`'s `activityBus` option), to hear turns end the
+     * moment they do, whoever started them. Without it a turn the session did not start is noticed
+     * by watching the driver's history and polling `isBusy()`, which is the slower route.
+     */
+    readonly activityBus?: Pick<AgenticActivityBus, 'subscribe'>;
+}
+
+/**
+ * What a headless session is doing now.
+ *
+ * @beta
+ */
+export declare interface HeadlessState {
+    /** Whether the driver is running a turn. */
+    readonly busy: boolean;
+    /** The oldest interaction the person holds and can act on, or `null`. */
+    readonly pending: InteractionDescription | null;
+    /** The other open interactions: a claimant's, or not ready yet, or behind the first. */
+    readonly others: readonly PendingSummary[];
+    /** The autopilot's state, when there is one. */
+    readonly autopilot?: {
+        readonly mode: string;
+        readonly status: string;
+        readonly needsUser: boolean;
+        readonly working: boolean;
+    };
+    /** What the conversation has cost so far, in `sumUsage`'s four buckets. */
+    readonly cost: AggregateUsage;
+    /** The host's probe, read now. */
+    readonly probe: Readonly<Record<string, unknown>>;
+    /** The `seq` of the last event logged: `wait`'s cursor. */
+    readonly lastSeq: number;
+}
+
+/**
+ * What `wait` takes.
+ *
+ * @beta
+ */
+export declare interface HeadlessWaitRequest {
+    /**
+     * The cursor: the `seq` of the last event already seen. Events after it are returned. Absent:
+     * from the start of the log.
+     */
+    readonly since?: number;
+    /**
+     * The event types that end the wait. Default: `decision`, `turn`, `error`, and an `autopilot`
+     * entry that `needsUser`. One naming `autopilot` ends it on any autopilot entry.
+     */
+    readonly until?: readonly HeadlessEventType[];
+    /** The longest to wait, in milliseconds. */
+    readonly maxWaitMs: number;
+}
+
+/**
+ * What `wait` returns.
+ *
+ * @beta
+ */
+export declare interface HeadlessWaitResult {
+    /** Every event after `since`, up to now. */
+    readonly events: readonly HeadlessEvent[];
+    /**
+     * `'ready'`: an event the caller was waiting for is among them. `'working'`: none came in
+     * time. `'closed'`: the session was disposed.
+     */
+    readonly status: 'ready' | 'working' | 'closed';
+    /** The cursor to pass as `since` next time: the `seq` of the last event logged. */
+    readonly nextSeq: number;
+}
+
 /**
  * A single in-flight per-call chat-input override pushed by a `requestSubAgent`
  * or `requestInteraction` call. Tracked as an array (not a counter) so the
@@ -7524,6 +8251,42 @@ export declare type InteractionControllerFactory<TController = unknown> = (data:
  */
 export declare type InteractionCostEventDetail = ChatInteractionEventsMap['interaction-cost'];
 
+/**
+ * What a pending interaction needs from the person, as a compact, JSON-serialisable view a model
+ * can read and answer.
+ *
+ * @beta
+ */
+export declare interface InteractionDescription {
+    readonly interactionId: string;
+    /** The widget type. */
+    readonly component: string;
+    /** Who holds it: `'user'`, or a claimant such as `'autopilot'`. */
+    readonly heldBy: string;
+    /**
+     * Whether the widget has a controller and so a surface to act on. `false`: nothing here can be
+     * run with `act`; `text` is all the widget says, and only a raw `resolve` can settle it.
+     */
+    readonly controller: boolean;
+    /**
+     * Whether the person can act now. A widget with no controller is ready; one with a surface is
+     * ready when it has an enabled finishing action and is not busy working.
+     */
+    readonly ready: boolean;
+    /**
+     * What the autopilot would be sent for it: the same `renderDecision` text (the widget as text,
+     * its views and facts, the numbered actions), or the widget as text alone where there is no
+     * surface.
+     */
+    readonly text: string;
+    /** Every action, in the order the list shows them. Empty with no surface. */
+    readonly actions: readonly DescribedAction[];
+    /** The views `read` takes, each with what it holds. */
+    readonly views?: Readonly<Record<string, string>>;
+    /** The surface's facts, as they stand now. */
+    readonly facts?: Readonly<Record<string, unknown>>;
+}
+
 export { InteractionEdit }
 
 /**
@@ -7898,6 +8661,30 @@ export declare function isAiAssistantDocked(): boolean;
  */
 export declare const isDelegated: (message: ChatMessage) => message is DelegatedMessage;
 
+/**
+ * The debug log for the WHOLE session (GENC-1351 §5.8 / §5.10), not just this page's activity:
+ * the persisted diagnostics stream with its stored `meta-snapshot`s replaced by a fresh one
+ * (`withFreshMetaSnapshot`), so its context and cost figures are current. When the provider
+ * stores no diagnostics, there is no key, the stream is empty or loading it fails, it is
+ * `fallback()` — the current-page log. Never throws.
+ *
+ * The one derivation of the lifetime log: the assistant element's `getLifetimeDebugLog` and the
+ * headless session both call it, because a second one drifts, and for this log that means silently
+ * understating spend.
+ *
+ * @beta
+ */
+export declare function lifetimeDebugLog(input: {
+    provider: SessionPersistenceProvider | undefined;
+    stateKey: string | undefined;
+    /** Land the current page's unflushed diagnostics delta, so the log includes it. */
+    flush: () => Promise<void> | void;
+    /** The `meta-snapshot` entry for right now. */
+    metaSnapshot: () => DiagnosticEntry;
+    /** The current-page log, for when there is no stored stream to stitch. */
+    fallback: () => DebugLog;
+}): Promise<DebugLog>;
+
 /**
  * The interchangeable "assistant is working" loading-indicator styles. At most
  * one of these may be enabled at a time — enabling one disables the other.
@@ -8289,6 +9076,18 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
     private appendInlineMessage;
 }
 
+/**
+ * Something else pending, besides the one `state().pending` describes.
+ *
+ * @beta
+ */
+export declare interface PendingSummary {
+    readonly interactionId: string;
+    readonly component: string;
+    readonly heldBy: string;
+    readonly ready: boolean;
+}
+
 /**
  * Schema version of the persisted session shape. Bump on an incompatible
  * change; a snapshot whose `version` doesn't match is discarded on load rather
@@ -8300,7 +9099,8 @@ export declare const PERSISTED_SESSION_VERSION = 1;
 
 /**
  * The autopilot's mode as saved with the session (GENC-1660 §4.8): which flow it was set for, and
- * whether it was running. Cleared when that flow ends, so a saved mode never outlives its flow.
+ * whether it was running. Cleared when that flow ends, so a saved mode never outlives its flow. A
+ * hand-off does not end it: the mode goes with the task to the target, and back (GENC-1751).
  *
  * @beta
  */