@genesislcap/ai-assistant 15.60.0 → 15.62.0

package/dist/ai-assistant.d.ts

@@ -25,6 +25,7 @@ import type { CondensePolicy } from '@genesislcap/foundation-ai';
 import { Container } from '@genesislcap/web-core';
 import { ElementStyles } from '@genesislcap/web-core';
 import { GenesisElement } from '@genesislcap/web-core';
+import { InteractionEdit } from '@genesislcap/foundation-ai';
 import type { InteractionRequestOptions } from '@genesislcap/foundation-ai';
 import type { InteractionResult } from '@genesislcap/foundation-ai';
 import { InterfaceSymbol } from '@microsoft/fast-foundation';
@@ -186,6 +187,23 @@ export declare interface AgenticActivityEvents {
     'chat-popout': undefined;
     /** Fired when the user clicks the collapse button — moves assistant from layout back to bubble. State lives in the session store, not in this event. */
     'chat-popin': undefined;
+    /**
+     * Whether something waits on the person in a session while its autopilot is available
+     * (GENC-1660 §4.10): an interaction it handed back, or the turn-level hand-back. The collapsed
+     * assistant shows a badge while it is true, since under "Build it for me" the chat is likely out
+     * of view. Fired on change; read the current value with `autopilotNeedsUser`.
+     */
+    'autopilot-needs-user': {
+        sessionKey: string;
+        needsUser: boolean;
+    };
+    /**
+     * The person opened the collapsed assistant from its "needs you" badge: the assistant for
+     * `sessionKey` (any, when absent) brings what waits on them into view.
+     */
+    'autopilot-show-waiting': {
+        sessionKey?: string;
+    };
     /**
      * Fired immediately before the tool loop begins running for the current turn — after the busy
      * flag is set and the user message (if any) has been appended, but before the first
@@ -388,6 +406,10 @@ export declare class AgentPicker extends GenesisElement {
     pinnedAgentName: string | null;
     /** When true, rows show a neutral dot instead of the per-agent brand tint. */
     disablePinColours: boolean;
+    /** The orchestration row's name, from `chatConfig.picker.orchestrationMenuLabel` (resolved by the host). */
+    orchestrationLabel: string;
+    /** The orchestration row's hint, from `chatConfig.picker.orchestrationDescription` (resolved by the host). */
+    orchestrationDescription: string;
     /** Top-level agents that opted in to manual selection. */
     get selectableAgents(): AgentConfig[];
     /** Whether the picker should render at all. */
@@ -687,6 +709,12 @@ export declare type AiChatInteraction<TData = unknown, TResult = unknown> = {
      * Display-only: the widget shows it, and it is never sent to a model.
      */
     outcome?: unknown;
+    /**
+     * The edits a claimant (an autopilot, say) made to the widget before it was settled, in
+     * order, whoever settled it. Absent when there were none. Lets the resolved view mark what
+     * was changed for the person rather than by them; display-only.
+     */
+    edits?: readonly InteractionEdit[];
 };
 
 export declare class AiChatMarkdown extends GenesisElement {
@@ -956,6 +984,23 @@ export declare interface AiDriver extends EventTarget {
      * @beta
      */
     getFlowOwner?(): string | null;
+    /**
+     * The checkpoint of the long action in flight, or the one a reload cut and nothing has taken over
+     * yet (GENC-1660 §4.12), for the host to save with the session.
+     *
+     * Optional, so a third-party driver need not implement it; every shipped driver does.
+     *
+     * @beta
+     */
+    getInteractionCheckpoint?(): PersistedInteractionCheckpoint | undefined;
+    /**
+     * Bring back a checkpoint saved with the session. Its interaction was cut by the reload, so it
+     * waits for the first request of the same widget type, which takes it over if the registration's
+     * `sameWork` agrees; it is dropped when the flow ends.
+     *
+     * @beta
+     */
+    restoreInteractionCheckpoint?(saved: PersistedInteractionCheckpoint | undefined): void;
     /**
      * Install an {@link InteractionInterceptor}: told about every interaction this driver opens,
      * with its live context, and able to claim it and answer it instead of the person (GENC-1660).
@@ -1140,11 +1185,27 @@ export declare interface AiDriverEventMap {
     'provider-changed': CustomEvent<{
         name: string;
     }>;
+    /**
+     * An interaction settled, by whatever route — a widget, a controller's `ctx.resolve`, a claimant,
+     * a timeout (GENC-1660). Detail: its id, and `answeredBy` when someone answered it (absent for a
+     * timeout or a stop).
+     */
+    'interaction-settled': CustomEvent<{
+        interactionId: string;
+        answeredBy?: string;
+    }>;
     /** Spend was recorded against an already-resolved interaction. */
     'external-cost-recorded': CustomEvent<{
         interactionId: string;
         costUsd: number;
     }>;
+    /**
+     * A long action saved its checkpoint (GENC-1660 §4.12). No message changed, so the host saves the
+     * session on this rather than waiting for the transcript to move.
+     */
+    'checkpoint-saved': CustomEvent<{
+        interactionId: string;
+    }>;
     /** The active agent changed. Detail: the new agent, or `undefined` after a release. */
     'agent-changed': CustomEvent<AgentConfig | undefined>;
     /** A stateful agent released its flow. Detail: the released agent. */
@@ -1361,6 +1422,467 @@ export declare interface AssistantAppSettingsToggle {
  */
 export declare const assistantSettingsSectionTitleStyles: ElementStyles;
 
+/**
+ * The holder id the autopilot claims interactions as.
+ *
+ * @beta
+ */
+export declare const AUTOPILOT_CLAIMANT = "autopilot";
+
+/**
+ * The tag of the turn-level hand-back widget (GENC-1660 §4.10): what the autopilot shows when a
+ * working turn ends needing the person, and there is no widget to hand over.
+ *
+ * @beta
+ */
+export declare const AUTOPILOT_HAND_BACK = "ai-autopilot-hand-back";
+
+/**
+ * An {@link AutopilotConfig} bound to its agent's live state — what `AgentConfig.autopilot` holds
+ * (GENC-1660). `state()` is `undefined` while the agent is not active.
+ *
+ * @beta
+ */
+export declare interface AutopilotBinding {
+    readonly config: AutopilotConfig<unknown>;
+    state(): unknown;
+}
+
+/**
+ * What a working agent's tool handlers get as `context.capabilities.autopilot` (GENC-1660): the
+ * mode of their own flow, and a way to set it — e.g. after the user picks "Build it for me".
+ * Absent when the flow has no autopilot, so a handler feature-detects and does not offer the choice.
+ *
+ * @beta
+ */
+export declare interface AutopilotCapability {
+    readonly mode: AutopilotMode;
+    setMode(mode: 'paused' | 'running'): void;
+}
+
+/**
+ * An autopilot definition, generic over the state `S` of the agent it serves (GENC-1660). An
+ * ordinary agent definition run the other way round: it is sent each decision the agent asks of
+ * the user, and answers it, or hands it back.
+ *
+ * `S` appears only as a resolver parameter, so a definition whose resolvers take `unknown` (a
+ * shared const) is assignable to every agent's `AutopilotConfig<S>`. Keep no mutable state in a
+ * shared definition or its closures: one is used by every agent that references it.
+ *
+ * @beta
+ */
+export declare interface AutopilotConfig<S = unknown> {
+    /**
+     * Whether the autopilot can be switched on right now, given the agent's live state — e.g. "the
+     * brief is approved", for an autopilot grounded in a brief. Default: whenever the agent's flow is
+     * active.
+     */
+    availableWhen?: (ctx: {
+        state: S;
+    }) => boolean;
+    /** Per widget component name; unlisted widgets are `'human-first'`. */
+    widgetPolicy?: Readonly<Record<string, AutopilotWidgetPolicy>>;
+    /** The autopilot's grounding. Keep it byte-stable for the run, so its cache prefix holds. */
+    systemPrompt: string | ((ctx: SystemPromptContext & {
+        state: S;
+    }) => string | Promise<string>);
+    /** What is true now (step guidance, a project snapshot). Rebuilt every call, never stored. */
+    tailContext?: string | ((ctx: SystemPromptContext & {
+        state: S;
+    }) => string | Promise<string>);
+    /** Which registered provider it uses. Defaults to the registry default. */
+    provider?: string | ((ctx: SystemPromptContext & {
+        state: S;
+    }) => string | Promise<string>);
+    /** Read-only tools it may use to check a fact, beside the three the platform adds. */
+    tools?: {
+        definitions: ChatToolDefinition[];
+        handlers: ChatToolHandlers;
+    };
+    /**
+     * How the working agent is told a decision was made for the user, e.g. "Decided on the user's
+     * behalf, from their brief". Must not name the autopilot.
+     */
+    decisionFraming?: string;
+    /**
+     * How the working agent is told that the user finished a widget the autopilot had already
+     * changed, e.g. "Changed on the user's behalf from their brief, before the user answered; the user
+     * then finished it, confirming the changes". Must say the changes came first and that finishing
+     * confirmed them; must not name the autopilot. Defaults to the platform's wording.
+     */
+    editFraming?: string;
+    /** Overrides for the UI's words. */
+    copy?: Partial<AutopilotCopy>;
+    /** Model calls per decision before it is handed back; `> 0`, or the default is used. Default 6. */
+    maxIterationsPerDecision?: number;
+    /**
+     * Written answers (`reply`) allowed per step before `reply` is withdrawn, so refining a proposal
+     * cannot loop with the working agent re-proposing it. `>= 0` (0 never offers one), or the
+     * default is used. Default 2. Enforced by the platform, not asked of the model: past the limit it
+     * can only accept or hand back.
+     */
+    maxRefinements?: number;
+    /**
+     * What counts as one step for {@link AutopilotConfig.maxRefinements}, e.g. the machine's phase
+     * and substate. The count resets when it changes. Default: the widget's component name, which is
+     * coarser but never unsafe.
+     */
+    stepKey?: (ctx: {
+        state: S;
+    }) => string;
+    /**
+     * What one decision may cost, in USD, before it is handed back; `> 0`. Unset (or not `> 0`): no
+     * cap (the session's budget wall still stops everything). Set it from measured decision costs,
+     * e.g. 3x the p95.
+     */
+    maxDecisionCostUsd?: number;
+    /**
+     * How long the autopilot's work on a claimed interaction may go quiet before it is handed back,
+     * in ms; `> 0`, or the default is used. Quiet means either no ready surface and no heartbeat
+     * (`ctx.notify()`), or a decision of its own still running with no model call landing and no
+     * heartbeat — a stalled model call, which has no timeout of its own. A decision handed back this
+     * way is stopped. Must outlast the slowest honest wait, such as a compile. Default 10 minutes.
+     */
+    watchdogMs?: number;
+    /**
+     * How large the autopilot's own history may grow, in characters, before it is rebuilt from a
+     * short-form digest of what the person saw (recent entries verbatim, older answered widgets as
+     * one line, and only the newest entries that fit in half of this). `> 0`, or the default is used.
+     * A safety net, not expected to fire on an ordinary run. Default 120,000 (roughly 30k tokens).
+     */
+    historyBudgetChars?: number;
+}
+
+/**
+ * The words the autopilot UI shows (GENC-1660). Supplied by the autopilot's config, because the
+ * host is platform code and must not carry any one app's wording; every field has a default.
+ *
+ * @beta
+ */
+export declare interface AutopilotCopy {
+    /** The slim bar's status while running, e.g. "Building from your plan…". */
+    running: string;
+    /** While paused by the user. */
+    paused: string;
+    /** While the autopilot waits on one answer it handed back. */
+    selfPaused: string;
+    /** In front of a hand-back reason, in the widget's banner, e.g. "I need your input on this one:". */
+    handBackLead: string;
+    /** The toggle pill's label and its accessible name, e.g. "Autopilot". */
+    toggleLabel: string;
+    /**
+     * What the autopilot does, in a sentence: in the toggle's tooltip, after what clicking does.
+     * The place to name what it decides from, e.g. "…from your plan".
+     */
+    description: string;
+    /**
+     * What clicking the toggle does while it is on, at the head of its tooltip, e.g. "Pause
+     * autopilot"; also the turn-level hand-back's pause button. The toggle's accessible name is
+     * always `toggleLabel`: it is a pressed/not-pressed toggle, so its name does not change with it.
+     */
+    pauseLabel: string;
+    /** What clicking the toggle does while it is off, at the head of its tooltip, e.g. "Resume autopilot". */
+    resumeLabel: string;
+    /**
+     * What clicking the toggle does while the autopilot waits on a question it handed back, at the
+     * head of its tooltip, e.g. "Resume autopilot and force it to decide this one": resuming forces it
+     * to take the question back and decide it, with no way to hand it back again, so say so.
+     */
+    resumeDecideLabel: string;
+    /** The hand-back banner's button that keeps the autopilot paused after the answer. */
+    keepPausedLabel: string;
+    /** The tooltip on the autopilot mark, beside anything done in autopilot mode. */
+    markLabel: string;
+    /**
+     * The turn-level hand-back's message when the working agent stopped at its call limit, e.g. "I've
+     * done a lot in one go, so I've stopped to check in. Shall I carry on?".
+     */
+    checkInMessage: string;
+    /** The turn-level hand-back's button that carries the working agent on, e.g. "Carry on". */
+    carryOnLabel: string;
+    /** The turn-level hand-back's message when the conversation has grown too long to carry on. */
+    tooLongMessage: string;
+    /** The turn-level hand-back's button that compacts the conversation, then carries on. */
+    compactLabel: string;
+    /** The turn-level hand-back's message when the working agent's turn failed. */
+    failedMessage: string;
+    /** The turn-level hand-back's button that runs the failed step again, e.g. "Try again". */
+    tryAgainLabel: string;
+    /** The turn-level hand-back's button that sends the person's own written answer, e.g. "Send". */
+    sendLabel: string;
+    /** The hand-back reason when a decision passed its spend cap (`maxDecisionCostUsd`). */
+    budgetReason: string;
+    /** The hand-back reason when a decision failed with an error. */
+    errorReason: string;
+    /** The hand-back reason when a decision ended without acting or handing back. */
+    noDecisionReason: string;
+    /** The hand-back reason when the watchdog found the autopilot's work gone quiet (`watchdogMs`). */
+    watchdogReason: string;
+}
+
+/**
+ * Autopilot (GENC-1660): a driver decorator that answers the questions a working agent asks the
+ * user, on their behalf, grounded in the agent's autopilot config (for bootstrap, the brief).
+ *
+ * Neither side calls the other. The working agent asks as it always does; this driver claims the
+ * interactions its policy allows, while it is running for that flow, and answers each in one short
+ * turn on the flow's `AutopilotSession`. It plugs in only through the generic extension points
+ * — an interaction interceptor, a handler capability and the flow lifecycle — so the core knows
+ * nothing about it, and it wraps any `AiDriver`.
+ *
+ * @beta
+ */
+export declare class AutopilotDriver extends BaseDriverDecorator implements AutopilotHost {
+    private readonly agents;
+    private readonly providerRegistry;
+    private readonly sessionKey;
+    private readonly listeners;
+    private readonly sessions;
+    /** The flow the mode applies to: set when it is first switched, cleared when that flow ends. */
+    private onFor;
+    private mode;
+    private pauseState?;
+    private held?;
+    /** Written answers given on the current step, for the refinement limit. */
+    private refinements?;
+    /** The watchdog's next check, while a claimed interaction is pending. */
+    private watchdog?;
+    /** What sessions that have ended did, kept for the debug log. */
+    private readonly endedDiagnostics;
+    /** Written answers sent in a row; see `MAX_CONSECUTIVE_REPLIES`. */
+    private consecutiveReplies;
+    /** Set while the turn-level hand-back waits on the person. */
+    private turnHandBack?;
+    /** A mode restored with the session, waiting for its flow to become the owner again. */
+    private restored?;
+    /**
+     * 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,
+     * even once resumed.
+     */
+    private generation;
+    /** Working turns this driver has started that have not ended yet; see `working`. */
+    private turnsInFlight;
+    /** Written questions being answered right now; see `working`. */
+    private answersInFlight;
+    constructor(inner: AiDriver, options: AutopilotDriverOptions);
+    get state(): AutopilotHostState;
+    get copy(): AutopilotCopy;
+    subscribe(listener: () => void): () => void;
+    pause(): void;
+    resume(): void;
+    stop(): void;
+    /** The mode to save with the session, while it is set for the current flow. */
+    getPersistedMode(): PersistedAutopilotMode | undefined;
+    /**
+     * Bring back a saved mode. It applies once its flow is the owner again — at once if it already
+     * is, otherwise when the restored flow re-activates. Restoring starts nothing: the autopilot acts
+     * only on live events, such as the working agent's own resume asking a question (§4.10, S3).
+     */
+    restorePersistedMode(saved: PersistedAutopilotMode | undefined): void;
+    private adoptRestored;
+    keepPaused(interactionId: string): void;
+    sendMessage(input: string, attachments?: ChatAttachment[], options?: SendMessageOptions): Promise<ChatDriverResult>;
+    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
+    resumeRestoredFlow(resumeNote?: string, agent?: AgentConfig): Promise<ChatDriverResult | undefined>;
+    /**
+     * Run a working turn, counted for `working` from the moment it is asked for: the wrapped driver
+     * may not say it is busy until some way in. The caller notifies once it has acted on the end.
+     */
+    private whileWorking;
+    /**
+     * Act on how a working turn ended, without holding up whoever awaited it, then notify: idle
+     * unless that started something (an answer, a hand-back), which it does before this returns.
+     */
+    private afterTurn;
+    private onTurnEnded;
+    /** {@link AutopilotDriver.answer}, from a caller that does not wait for it. */
+    private answerInBackground;
+    /**
+     * Answer a written question the working agent ended its turn on, and send the answer on the
+     * user's behalf, with what writing it cost booked on that message (§4.2).
+     *
+     * Sent only if the question still stands when the answer lands: no pause or resume since it was
+     * asked (Pause stops it, and the question is the person's to answer by typing), the flow still
+     * running, the working agent idle, and the question still the last thing it said. Otherwise the
+     * answer goes nowhere — not sent, not counted, not recorded as acted — and its cost is recorded as
+     * dropped, as it is whenever no reply is sent to carry it.
+     */
+    private answer;
+    /**
+     * Spend on a written answer that no reply carries into the session total — it was handed back,
+     * stopped, or went stale — recorded so it is never lost silently.
+     */
+    private dropCost;
+    /** The working agent's last visible words, when its turn ended on them. */
+    private lastQuestion;
+    /**
+     * The turn-level hand-back (§4.10): a working turn ended needing the person and there is no
+     * widget to hand over, so the autopilot shows its own, `userOnly`, and acts on the choice.
+     */
+    private presentHandBack;
+    /**
+     * The inner driver's diagnostics, then everything the autopilot did (§4.8): diagnostics compose
+     * down the decorator stack, so they reach the downloaded and the persisted debug log through the
+     * host's existing external-diagnostics channel.
+     */
+    getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry>;
+    /**
+     * Close every session, keeping what it did for the debug log. An answer one was still writing is
+     * stale from here: it is never sent, and its cost is recorded as dropped when it lands.
+     */
+    private endSessions;
+    dispose(): Promise<void>;
+    private onInteractionOpened;
+    /** Run one decision on the flow's session, and act on how it ended. */
+    private decide;
+    /** The step a decision belongs to, for the refinement limit (§4.4). */
+    private stepKey;
+    /** Whether a written answer is still allowed on this step. The count resets when the step changes. */
+    private mayRefine;
+    private countRefinement;
+    /** Written answers allowed per step: the config's when it is a whole number `>= 0`. */
+    private refinementLimit;
+    /**
+     * The watchdog (§4.2, critique S5): a claimed interaction whose work has gone quiet for longer
+     * than `watchdogMs` is handed back rather than left to hang silently. Quiet is either no surface
+     * ready to act on and no heartbeat, or the autopilot's own decision still running with no model
+     * call landing and no heartbeat — a stalled model call, which nothing else times out. It checks a
+     * few times per window, and stops when the interaction settles.
+     */
+    private armWatchdog;
+    private disarmWatchdog;
+    private onDecided;
+    /**
+     * The autopilot's self-pause, for one interaction (§4.10): the person gets it, with the reason as
+     * the banner, and the autopilot carries on by itself once they answer. Only while it is still
+     * the autopilot's to hand back — not settled, not already with the person — and its decision
+     * stops with it, so a decision still running spends nothing more on an interaction it no longer
+     * holds. Every caller (a decision's own hand-back, a failed decision, the watchdog) gets both.
+     */
+    private handBack;
+    /**
+     * On detach: hand a claimed interaction the autopilot still holds to the person, stopping its
+     * decision, so the driver it wrapped lives on with nothing held by an autopilot that is gone.
+     */
+    private releaseHeld;
+    /** A claimed interaction settled, whoever settled it. */
+    private onSettled;
+    private onFlowOwnerChanged;
+    private capabilityFor;
+    private flowOwner;
+    private bindingFor;
+    private isAvailable;
+    private copyFor;
+    private sessionFor;
+    private record;
+    private notify;
+}
+
+/**
+ * Options for {@link AutopilotDriver}.
+ *
+ * @beta
+ */
+export declare interface AutopilotDriverOptions {
+    /** The agents the host configured; an agent's `autopilot` key is what this driver runs. */
+    readonly agents: readonly AgentConfig[];
+    /** The registry the autopilot's own driver resolves its provider from. */
+    readonly providerRegistry: AIProviderRegistry;
+    /** The working session's debug-log key. */
+    readonly sessionKey?: string;
+}
+
+/**
+ * The turn-level hand-back's view (GENC-1660 §4.10): the message, the working agent's question if
+ * there was one, and the choices. It only renders: choosing calls the controller, which resolves.
+ * Always the person's to answer (`userOnly`), so it never hides itself.
+ *
+ * @beta
+ */
+export declare class AutopilotHandBack extends GenesisElement {
+    interactionId: string;
+    interaction?: AiChatInteraction<HandBackData, HandBackResult['payload']>;
+    draft: string;
+    get data(): HandBackData | undefined;
+    /** What was chosen, once resolved. */
+    get answer(): string | undefined;
+    private get controller();
+    choose(option: string): void;
+    reply(): void;
+}
+
+/**
+ * The contract the autopilot UI is built against (GENC-1660 §4.10): the slim bar, its buttons, the
+ * banner's "Keep paused", and the badge. The host installs `AutopilotDriver` itself, so it reads it
+ * as this; nothing about it travels through `AiDriver`.
+ *
+ * @beta
+ */
+export declare interface AutopilotHost {
+    readonly state: AutopilotHostState;
+    subscribe(listener: () => void): () => void;
+    /** Pause until resumed. Hands a held interaction to the person on the spot. */
+    pause(): void;
+    /**
+     * Resume. Takes back an interaction that pausing handed over; during the autopilot's own
+     * hand-back it means "decide it yourself".
+     */
+    resume(): void;
+    /** The existing Stop, which also pauses, so what is shown stays honest. */
+    stop(): void;
+    /** The banner's "Keep paused": turn the autopilot's own hand-back into an ordinary pause. */
+    keepPaused(interactionId: string): void;
+    readonly copy: AutopilotCopy;
+}
+
+/**
+ * What the autopilot UI reads (GENC-1660 §4.10).
+ *
+ * @beta
+ */
+export declare interface AutopilotHostState {
+    readonly mode: AutopilotMode;
+    /**
+     * Set while paused. `'this-interaction'` is the autopilot's own hand-back: it resumes by itself
+     * once the person answers `interactionId`, and `reason` is the banner's text.
+     */
+    readonly pause?: {
+        readonly scope: 'until-resumed' | 'this-interaction';
+        readonly interactionId?: string;
+        readonly reason?: string;
+    };
+    /** The slim bar's one-line status. */
+    readonly status: string;
+    /** Whether something waits on the person: drives the "needs you" badge. */
+    readonly needsUser: boolean;
+    /**
+     * Whether something is happening: the working agent is busy, or the autopilot is deciding (a
+     * widget it holds, or a written question it is answering). The slim bar replaces the composer
+     * only while this is set; running but idle — stopped at a wall such as the budget, or at the end
+     * of a turn it had nothing to answer for — the host shows what the agent's own rules show. A host
+     * that hides the built-in composer keeps the slim bar regardless, as its only place for the pill.
+     */
+    readonly working: boolean;
+}
+
+/**
+ * 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.
+ * `'running'`: answering what its policy allows.
+ *
+ * @beta
+ */
+export declare type AutopilotMode = 'unavailable' | 'paused' | 'running';
+
+/**
+ * Whether an autopilot may answer a widget (GENC-1660). `'human-first'` hands it straight to the
+ * person; `'allowed'` lets the autopilot decide. Anything unlisted is `'human-first'`.
+ *
+ * @beta
+ */
+export declare type AutopilotWidgetPolicy = 'human-first' | 'allowed';
+
 declare interface BaseAgentConfig {
     /**
      * Stable identity for this agent. Used for classifier routing, manual
@@ -1649,6 +2171,14 @@ declare interface BaseAgentConfig {
      * @beta
      */
     contextReserve?: ContextReserveInput;
+    /**
+     * The autopilot that may answer this agent's interactions on the user's behalf (GENC-1660). Set by
+     * `defineStatefulAgent`'s `autopilot` option, which binds the config to the agent's live state;
+     * consumed by `AutopilotDriver`. Never routed to or pinned: it is not an agent in the array.
+     *
+     * @beta
+     */
+    autopilot?: AutopilotBinding;
 }
 
 /**
@@ -1706,6 +2236,8 @@ export declare abstract class BaseDriverDecorator<TInner extends AiDriver = AiDr
     setPinnedAgent(name: string | null): void;
     setFlowOwner(name: string | null): void;
     getFlowOwner(): string | null;
+    getInteractionCheckpoint(): PersistedInteractionCheckpoint | undefined;
+    restoreInteractionCheckpoint(saved: PersistedInteractionCheckpoint | undefined): void;
     /**
      * Forwarded, so an interceptor installed on any layer lands on the driver that opens the
      * interactions. A decorator that answers interactions installs its own on `this.inner`.
@@ -2863,6 +3395,10 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * host) to build the widget's pending `interaction` descriptor.
      */
     getInteractionContext(interactionId: string): InteractionContext | undefined;
+    /** {@inheritDoc AiDriver.getInteractionCheckpoint} */
+    getInteractionCheckpoint(): PersistedInteractionCheckpoint | undefined;
+    /** {@inheritDoc AiDriver.restoreInteractionCheckpoint} */
+    restoreInteractionCheckpoint(saved: PersistedInteractionCheckpoint | undefined): void;
     /**
      * Replace the history message owning `interactionId`. `false` when it is no longer in history.
      * Does not announce the change — the interaction paths differ on whether they should.
@@ -3393,6 +3929,79 @@ export declare interface DebugLog {
     meta: unknown;
 }
 
+/**
+ * What was decided, as handed to a short-form decision's `choose` (GENC-1660).
+ *
+ * @beta
+ */
+export declare type DecisionAnswer = 
+/** One option, by id. */
+    {
+    readonly kind: 'option';
+    readonly option: string;
+}
+/** Several options, by id (a multi-select). */
+| {
+    readonly kind: 'options';
+    readonly options: readonly string[];
+}
+/** A written answer (`freeText`). */
+| {
+    readonly kind: 'text';
+    readonly text: string;
+};
+
+/**
+ * One option of a short-form decision (GENC-1660). A bare string is an option whose id and label are
+ * the same text.
+ *
+ * @beta
+ */
+export declare type DecisionOption = string | {
+    /**
+     * The stable name of the option's action — what a view passes to `ctx.claimantOwns` to hide
+     * its button. Defaults to `label`.
+     */
+    readonly id?: string;
+    /** The option's text, as the person sees it. */
+    readonly label: string;
+    /**
+     * Whether it can be chosen right now — the button's own guard (e.g. `validated` for a
+     * Continue). Read fresh every time. A disabled option is listed as unavailable and refused.
+     */
+    readonly enabledWhen?: () => boolean;
+};
+
+/**
+ * A short-form decision: the surface most widgets need (GENC-1660). Its actions are its options,
+ * all finishing, plus `select` for a multi-select and `reply` for a written answer.
+ *
+ * @beta
+ */
+export declare interface DecisionSpec {
+    readonly options: readonly DecisionOption[];
+    /** Adds a `select({ options })` action that picks several. */
+    readonly multi?: boolean;
+    /** Adds a `reply({ text })` action: an answer in the chooser's own words. */
+    readonly freeText?: boolean;
+    /**
+     * What a decision needs that the person sees on screen in some other form — e.g.
+     * `{ validated: true }`. A getter, so it is read fresh whenever the decision is described.
+     */
+    readonly facts?: () => Readonly<Record<string, unknown>>;
+    /**
+     * Model-only guidance the person would not see. The decision's own text comes from the
+     * widget's `asText`, which is what the person saw.
+     */
+    readonly prompt?: string;
+    /**
+     * Act on the answer. The SAME method the view's buttons call, so a claimant's answer runs the
+     * code a click runs. Must resolve the interaction (through `ctx.resolve`), now or once its work
+     * is done.
+     */
+    choose(answer: DecisionAnswer): void | Promise<void>;
+}
+
 /**
  * Animations enabled by default when a consumer opts into the animations
  * feature without specifying an explicit `enabled` list. Keeps the dots loading
@@ -3427,6 +4036,28 @@ export declare const DEFAULT_DELEGATE_FRAMING = "Sent on the user's behalf.";
  */
 export declare function defineAgent<const T extends AgentConfig>(config: T): T;
 
+/**
+ * Define an autopilot for a stateful agent whose state is `S` (GENC-1660). An identity function
+ * that exists for its type: the resolvers get `S`, and the result goes on `defineStatefulAgent`'s
+ * `autopilot` option.
+ *
+ * @example
+ * ```ts
+ * defineStatefulAgent<BootstrapState>({
+ *   name: 'bootstrap',
+ *   …,
+ *   autopilot: defineAutopilot<BootstrapState>({
+ *     availableWhen: ({ state }) => briefApproved(state.machine),
+ *     widgetPolicy: { 'planning-question': 'allowed' },
+ *     systemPrompt: ({ state }) => `${AUTOPILOT_BASE}\n<brief>${frozenBrief(state)}</brief>`,
+ *   }),
+ * });
+ * ```
+ *
+ * @beta
+ */
+export declare function defineAutopilot<S = unknown>(config: AutopilotConfig<S>): AutopilotConfig<S>;
+
 /**
  * Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool
  * handlers all close over a long-lived state object created on activation.
@@ -3459,8 +4090,8 @@ export declare function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): Agen
  * to the result of the tool call that requested it, as `decidedOnUsersBehalf` on an object result
  * or as a line appended to a text one.
  *
- * Built only from what the platform already holds — the claimant's framing, and the choice and
- * narration it recorded — so the text the person saw and the text the agent is told about are the
+ * Built only from what the platform already holds — the claimant's framing, and the choice,
+ * narration and edits it recorded — so the text the person saw and the text the agent is told about are the
  * same string. It never names the claimant, so the agent has nothing to repeat about one.
  *
  * @beta
@@ -3472,6 +4103,34 @@ export declare interface DelegatedDecision {
     readonly choice?: string;
     /** What the person was shown about it, verbatim, as the assistant's own words. */
     readonly shownToUser?: string;
+    /**
+     * What the claimant changed in the widget before it decided, in order, each as the claimant
+     * reported it (`InteractionEdit.choice`): present only when it made edits. Lets the agent know
+     * the interaction was altered, not just answered.
+     */
+    readonly edits?: readonly string[];
+}
+
+/**
+ * What the working agent is told when the PERSON settled an interaction an interceptor had already
+ * changed (GENC-1660): added to the result of the tool call that requested it, as
+ * `editedOnUsersBehalf` on an object result or as a line appended to a text one. The edits were
+ * made on the user's behalf before they answered; the user then confirmed them by finishing it, so
+ * the answer itself is theirs and is not a {@link DelegatedDecision}.
+ *
+ * Built, like a decision, only from what the platform holds — the claimant's framing and the edits
+ * it reported — and never names the claimant.
+ *
+ * @beta
+ */
+export declare interface DelegatedEdits {
+    /**
+     * The claimant's {@link InteractionInterceptor.editFraming}, e.g. "Changed on the user's behalf
+     * before they answered; the user then finished it, confirming the changes".
+     */
+    readonly framing: string;
+    /** What the claimant changed, in order, each as it reported it (`InteractionEdit.choice`). */
+    readonly edits: readonly string[];
 }
 
 /**
@@ -4198,7 +4857,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private get transcriptBudgetExhaustedMessage();
     /**
      * Name of the agent the user has pinned via the agent picker. `null` means
-     * automatic routing (Auto). Persisted on the session store, so it survives
+     * orchestration: the assistant routes each message. Persisted on the session store, so it survives
      * pop-in/pop-out but resets on page refresh.
      *
      * Only changes on explicit user action (picker click or host's `setAgent`).
@@ -4595,6 +5254,110 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private syncShowHalo;
     /** True when there is a pending (unresolved) interaction. */
     get hasActivePendingInteraction(): boolean;
+    /**
+     * True when the turn is parked on the person: a pending interaction they hold. One a claimant
+     * holds (the autopilot deciding it) is the assistant still working, so the halo and the loading
+     * indicator stay on (GENC-1660 §4.10).
+     */
+    get waitingOnUser(): boolean;
+    /**
+     * An autopilot host supplied from outside, in place of the one this element installs — the
+     * sandbox's stub, or a test's. Without it, the element reads the `AutopilotDriver` it installed
+     * when some agent declares `autopilot`.
+     *
+     * @beta
+     */
+    autopilotHostOverride?: AutopilotHost;
+    /** The autopilot's state and copy, mirrored for the template. Absent with no autopilot. @internal */
+    autopilotState?: AutopilotHostState;
+    /** @internal */
+    autopilotCopy?: AutopilotCopy;
+    /**
+     * A pending interaction being pointed out, after the person opened the collapsed assistant from
+     * its "needs you" badge: its row pulses briefly. @internal
+     */
+    attentionInteractionId?: string;
+    private attentionTimer?;
+    /** Who holds the trailing pending interaction: `'user'` unless a claimant took it. @internal */
+    activeHeldBy: InteractionHolder;
+    private autopilotCleanup?;
+    private heldCleanup?;
+    private heldInteractionId?;
+    /** The autopilot behind the slim bar and the banner, if there is one. */
+    get autopilotHost(): AutopilotHost | undefined;
+    /** Whether the autopilot is available for the current flow, running or paused. @internal */
+    get autopilotAvailable(): boolean;
+    /** Running and not waiting on an answer, so its control pauses it; otherwise it resumes. @internal */
+    get autopilotCanPause(): boolean;
+    /**
+     * What clicking the toggle does, at the head of its tooltip. While it waits on a question it
+     * handed back, Resume is not a plain resume: it takes that question back and decides it, with no
+     * way to hand it back again. @internal
+     */
+    get autopilotToggleAction(): string | undefined;
+    /**
+     * The toggle's tooltip: what clicking does now, then what the autopilot does. The action is here
+     * and not in its accessible name: the toggle is a toggle (`aria-pressed`), so its name stays
+     * `toggleLabel` and its state is announced once, by the pressed state. @internal
+     */
+    get autopilotToggleTitle(): string | undefined;
+    /** Waiting on one answer it handed back. @internal */
+    get autopilotSelfPaused(): boolean;
+    /**
+     * The slim bar takes the composer's place while something is happening and the autopilot runs or
+     * waits on one answer, and otherwise wherever the agent's own rules would hide the composer. Running
+     * but idle — stopped at a wall such as the budget, or at the end of a turn it had nothing to
+     * answer for — shows what those rules show, normally the composer, with the Autopilot pill on among
+     * its pills. It never forces the composer open. A host that hides the built-in composer
+     * (`chatConfig.ui.hideComposer`) has no pills to put it among, so there the slim bar stays up
+     * whenever the autopilot is available, running or paused, idle or not: the person can always see
+     * that it is on, and pause or resume it. @internal
+     */
+    get slimBarVisible(): boolean;
+    /**
+     * What the autopilot's status region announces (GENC-1660 §4.10): the hand-back, with its reason,
+     * while the autopilot waits on an answer; otherwise the slim bar's status while that shows;
+     * otherwise nothing. The region stays mounted and only this text changes, so each change is
+     * announced. @internal
+     */
+    get autopilotAnnouncement(): string;
+    /**
+     * The Autopilot pill among the composer's pills: available, with the composer shown — paused, or
+     * running with nothing happening. Where the host hides the composer, it is in the slim bar
+     * instead (see `slimBarVisible`). @internal
+     */
+    get composerAutopilotVisible(): boolean;
+    autopilotHostOverrideChanged(): void;
+    /** Follow the autopilot host's state, publishing the "needs you" signal for the bubble. */
+    private wireAutopilot;
+    /**
+     * Scroll to the pending interaction that waits on the person, and pulse it, so opening the chat
+     * from the badge lands on it rather than wherever the transcript was left.
+     */
+    private showWaiting;
+    /** How long a pointed-out interaction pulses for. */
+    private static readonly ATTENTION_MS;
+    /**
+     * Follow who holds the trailing pending interaction. A claimant changes it on its context, which
+     * notifies, so the view re-reads it on every notification rather than once (GENC-1660 §4.3).
+     */
+    private syncActiveHold;
+    private readActiveHold;
+    /**
+     * Whether a pending interaction's bubble is drawn at all. A widget registered with
+     * `whileAutopilot: 'hidden'` asks for no chrome while a claimant holds it: the view renders
+     * nothing, so an empty bubble would be left behind. @internal
+     */
+    isHiddenWhileHeld(m: ChatMessage): boolean;
+    /** The hand-back banner's reason, when this interaction is the one the autopilot handed back. @internal */
+    handBackReasonFor(m: ChatMessage): string | undefined;
+    /** Whether to mark a message as done in autopilot mode. @internal */
+    showsDelegateMark(m: ChatMessage): boolean;
+    /** The autopilot mark's tooltip. @internal */
+    get delegateMarkLabel(): string;
+    handleAutopilotPause(): void;
+    handleAutopilotResume(): void;
+    handleKeepPaused(interactionId: string): void;
     showHaloChanged(): void;
     private getActiveToolNames;
     /**
@@ -4764,6 +5527,15 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private syncLoadingIndicator;
     /** Called when the user clicks the popout button. */
     handlePopout(): void;
+    /**
+     * The key this assistant's session is published under (on the activity bus, in the debug log,
+     * in storage): the wired session's once one is active, else the one its attributes imply. Not
+     * always the `session-key` attribute, which can run ahead of a deferred switch and is absent when
+     * the key is derived from `id` and the header title. `undefined` when it has no identity.
+     *
+     * @beta
+     */
+    get stateKey(): string | undefined;
     /** Returns a cache key for this instance, or undefined if the component has no identity. */
     private getStateKey;
     /**
@@ -5143,12 +5915,21 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get pinnedAgentColour(): string | undefined;
     /**
-     * Label beside the composer's agent glyph: `AUTO` while the orchestrator is
-     * routing, otherwise the pinned agent's name. The name is NOT shortened here —
+     * Label beside the composer's agent glyph: the orchestration label (`Orchestration` unless the
+     * host renames it) while the orchestrator is routing, otherwise the pinned agent's name. The name is NOT shortened here —
      * the button truncates with an ellipsis in CSS, so the full name stays
      * available to a screen reader and to the `title` tooltip.
      */
     get agentButtonLabel(): string;
+    /**
+     * The picker's name for orchestration, from `chatConfig.picker.orchestrationLabel`. Not "Auto":
+     * other tools use that for picking a model tier, and here it is the agent that is chosen.
+     */
+    get orchestrationLabel(): string;
+    /** The same choice's name in the picker menu, from `chatConfig.picker.orchestrationMenuLabel`. */
+    get orchestrationMenuLabel(): string;
+    /** What orchestration does, from `chatConfig.picker.orchestrationDescription`. */
+    get orchestrationDescription(): string;
     /**
      * Placeholder shown in the chat input. Substitutes the pinned agent's name
      * when one is selected so the user has a clearer signal of where their
@@ -5593,6 +6374,62 @@ export declare type GenesisWriteReviewCompletedEventDetail = InteractionResult<G
  */
 export declare function getAiPopoutManager(): FoundationAiPopoutManager | undefined;
 
+/**
+ * The registration for a component name, or `undefined` when it has none.
+ *
+ * @beta
+ */
+export declare function getInteractionRegistration(name: string): InteractionRegistration | undefined;
+
+/**
+ * What the person can choose. `reply` carries their written answer to the working agent's
+ * question; the rest tell the autopilot what to do next.
+ *
+ * @beta
+ */
+export declare type HandBackChoice = 'carry-on' | 'try-again' | 'compact' | 'pause' | 'reply';
+
+/**
+ * The hand-back's inputs. Every word it shows comes from here, so it follows the autopilot's
+ * `AutopilotCopy`.
+ *
+ * @beta
+ */
+export declare interface HandBackData {
+    /** Why the person is needed, in the assistant's voice. */
+    readonly message: string;
+    /** The working agent's question, when the turn ended on one. */
+    readonly question?: string;
+    readonly options: readonly HandBackOption[];
+    /** Whether a written answer is offered (a turn that ended on a question). */
+    readonly freeText?: boolean;
+    /** The label of the button that sends the written answer, with `freeText`. */
+    readonly sendLabel?: string;
+}
+
+/**
+ * One choice the hand-back offers.
+ *
+ * @beta
+ */
+export declare interface HandBackOption {
+    readonly id: HandBackChoice;
+    readonly label: string;
+}
+
+/**
+ * What the hand-back resolves with.
+ *
+ * @beta
+ */
+export declare interface HandBackResult {
+    readonly status: 'approved';
+    readonly payload: {
+        choice: HandBackChoice;
+        text?: string;
+    };
+}
+
 /**
  * Builds a capability's value for one tool-handler call (GENC-1660). Called per call, so it can
  * reflect the moment; it should be cheap and must not throw (a throw is logged and the capability
@@ -5673,7 +6510,7 @@ export declare type InteractionCompletedEventDetail = ChatInteractionEventsMap['
  *
  * @beta
  */
-export declare interface InteractionContext<TState extends object = Record<string, unknown>> {
+export declare interface InteractionContext<TState extends object = Record<string, unknown>, TCheckpoint = unknown> {
     /** Stable id of the interaction this context belongs to. */
     readonly interactionId: string;
     /**
@@ -5729,14 +6566,78 @@ export declare interface InteractionContext<TState extends object = Record<strin
      * has already been disposed runs `fn` immediately.
      */
     onDispose(fn: () => void): void;
+    /**
+     * The widget's controller, built by the platform from its registration when the interaction was
+     * requested, before anything rendered. `undefined` for an unregistered widget. One per
+     * interaction for its whole life, so a remounted view picks up the same one.
+     */
+    readonly controller: unknown;
+    /**
+     * Settle the interaction with `result` — the controller's way to resolve, in place of an element
+     * emitting `interaction-completed`, so resolving needs no mounted view. Goes through the same
+     * path, so cost and diagnostics fold in as before. Settles once: later calls do nothing.
+     */
+    resolve(result: unknown): void;
+    /**
+     * Expose what can be decided here (the short form). Called by the controller: in its constructor
+     * for a pure question, or when its gate opens for a widget that works first. Calling again
+     * replaces it.
+     */
+    exposeDecision(decision: DecisionSpec): void;
+    /**
+     * Expose the full form, for a rich widget: a description, views to read, and named actions —
+     * some only edit (and do not settle), some finish. Calling again replaces the surface, as
+     * `exposeDecision` does.
+     */
+    exposeSurface(surface: SurfaceSpec): void;
+    /** The surface the controller exposed, or `undefined` until it exposes one. */
+    readonly surface: InteractionSurface | undefined;
+    /**
+     * Run `fn` once the surface is ready (see `InteractionSurface.isReady`) — or now if
+     * it already is. Readiness is re-checked on every `notify()`, so a gate whose guard turns true
+     * later fires it then. Never runs after the interaction ends. Returns an unsubscribe.
+     */
+    onSurfaceReady(fn: () => void): () => void;
+    /**
+     * Whether a claimant holds the interaction AND `action` is one of its enabled actions right now.
+     * A view hides a button with this, never with `heldBy` alone: a button the controller did not
+     * expose — an error-state Retry, say — is then never hidden, so nothing can strand the journey.
+     */
+    claimantOwns(action: string): boolean;
+    /** When the controller last called `notify()` (or the interaction opened), in epoch ms. A heartbeat. */
+    readonly lastActivityAt: number;
+    /**
+     * What is already done, for long work that should survive a reload: the last checkpoint saved,
+     * or the one the platform handed over — after a restore, the first request for the same widget
+     * type takes over the checkpoint the reload cut, if the registration's `sameWork` agrees.
+     * `undefined` for fresh work. See `runSteps`, which reads and writes it for you.
+     */
+    readonly checkpoint: TCheckpoint | undefined;
+    /**
+     * Save a checkpoint into the session snapshot, so a reload does not lose it. Kept as JSON, so it
+     * must be storable as JSON; keep it small and hold anything large by reference (a job id, a store
+     * key). One per interaction: each save replaces the last. Cleared when the interaction settles,
+     * and when its flow ends.
+     */
+    saveCheckpoint(checkpoint: TCheckpoint): void;
 }
 
+/**
+ * Builds a widget's controller when its interaction is requested (GENC-1660). DOM-free: it owns the
+ * interaction's state, its surface and resolving it; the view only renders.
+ *
+ * @beta
+ */
+export declare type InteractionControllerFactory = (data: unknown, ctx: InteractionContext) => unknown;
+
 /**
  * Detail payload for the `interaction-cost` event — a POSITIVE DELTA in USD, not a running total.
  * @public
  */
 export declare type InteractionCostEventDetail = ChatInteractionEventsMap['interaction-cost'];
 
+export { InteractionEdit }
+
 /**
  * The handle an interceptor uses to move a pending interaction between the person and itself
  * (GENC-1660): to the person when it hands back or is paused, back to itself when resumed.
@@ -5775,6 +6676,28 @@ export declare interface InteractionHold {
      * `heldBy`. Returns `false`, settling nothing, unless this interceptor holds it right now.
      */
     resolve(result: unknown): boolean;
+    /**
+     * Run one of the surface's actions as the claimant (GENC-1660): an option by its id, `select`
+     * with `{ options }`, or `reply` with `{ text }`. It runs the same code the widget's own button
+     * runs, and records the decision for the asking tool — the choice as the person would read it,
+     * and `note`, verbatim, as what they were shown about it — so `recordDecision` is not needed.
+     *
+     * A finishing action settles the interaction AS the claimant, as {@link InteractionHold.resolve}
+     * does, so it is stamped `answeredBy` the claimant.
+     *
+     * Refused, with nothing run, unless this interceptor holds the interaction right now, the
+     * surface has that action, it is enabled and `args` fit it. One action runs at a time: a call
+     * made while an earlier one on the same interaction is still running is refused as `'busy'`, to
+     * be tried again once that one has returned. A refusal lists what is enabled, so the caller can
+     * correct itself. `finished` says whether the interaction settled.
+     *
+     * Handing the interaction to the person (`set('user')`) while a finishing action is still
+     * running does not take that action's credit away: if it settles the interaction, the answer is
+     * the claimant's. If it does not, the interaction is the person's like any other.
+     */
+    invoke(action: string, args?: unknown, options?: {
+        note?: string;
+    }): Promise<InvokeResult>;
 }
 
 /**
@@ -5805,6 +6728,14 @@ export declare interface InteractionInterceptor {
      * would say "Decided on the user's behalf, from their brief".
      */
     readonly decisionFraming?: string;
+    /**
+     * How {@link DelegatedEdits} open, as the working agent reads them: the person finished an
+     * interaction this interceptor had changed first. Must say the changes were made on the user's
+     * behalf before they answered, and that finishing it confirmed them; must not name the
+     * interceptor. Defaults to "Changed on the user's behalf before the user answered; the user then
+     * finished it, confirming the changes".
+     */
+    readonly editFraming?: string;
     /** Return `'claim'` to hold the interaction, or nothing to leave it with the person. */
     onInteractionOpened(opened: InteractionOpened): 'claim' | undefined | void;
 }
@@ -5836,6 +6767,39 @@ export declare interface InteractionOpened {
     readonly hold: InteractionHold;
 }
 
+/**
+ * How a widget is registered with the platform, once, at start-up (GENC-1660).
+ *
+ * @beta
+ */
+export declare interface InteractionRegistration {
+    /**
+     * Builds the controller when the interaction is requested, before anything renders. Without
+     * one the widget works exactly as today and is never handed to a claimant.
+     */
+    readonly controller?: InteractionControllerFactory;
+    /** The custom element that renders it. Defaults to the registered name. */
+    readonly view?: string;
+    /**
+     * What the widget shows while a claimant holds it: `'visible'` (the default; it hides only the
+     * buttons the claimant owns) or `'hidden'` (the wrapper drops the bubble chrome too).
+     */
+    readonly whileAutopilot?: 'visible' | 'hidden';
+    /**
+     * The widget as text: what the person saw. Without `result` the pending widget, with it what the
+     * resolved view shows. Used for the visible transcript a claimant reads.
+     */
+    readonly asText?: (data: unknown, result?: unknown) => string;
+    /**
+     * Whether a checkpoint a reload cut (`saved`) is the same work as this new request (`next`, its
+     * data), so the new interaction may take it over and skip what is already done (GENC-1660 §4.12).
+     * Without it, the same widget type is enough. Compare identity only — the fields the work's
+     * output depends on, kept in the checkpoint itself — never the model's prose, which a resumed call
+     * rewrites.
+     */
+    readonly sameWork?: (saved: unknown, next: unknown) => boolean;
+}
+
 /**
  * Opens an interaction somewhere else — the parent driver, for a sub-agent's — and tells
  * `onOpened` its id. `ownerPath` is the agents the request has already come up through, outermost
@@ -5845,22 +6809,74 @@ declare type InteractionRequester = <T>(componentName: string, data: any, option
 
 /**
  * Who answered an interaction, as its requester is told (GENC-1660). `answeredBy` is absent when it
- * closed unanswered (a timeout or a stop); `decision` is present when an interceptor answered.
+ * closed unanswered (a timeout or a stop); `decision` is present when an interceptor answered;
+ * `edited` is present when the person answered one an interceptor had changed first.
  */
 declare interface InteractionSettled {
     readonly answeredBy?: string;
     readonly decision?: DelegatedDecision;
+    readonly edited?: DelegatedEdits;
+}
+
+/**
+ * What can be read from an interaction's surface (GENC-1660): its actions as they stand now, and
+ * its facts. Present once the controller has exposed one.
+ *
+ * @beta
+ */
+export declare interface InteractionSurface {
+    /** Model-only guidance, from the decision's `prompt`. */
+    readonly prompt?: string;
+    /** Read fresh on every call. */
+    facts(): Readonly<Record<string, unknown>>;
+    /** A full-form surface's description. Absent on a short-form decision. */
+    describe?(): string;
+    /** A full-form surface's views. */
+    readonly views?: readonly string[];
+    /** Read one view of a full-form surface; absent on a short-form decision. */
+    read?(view?: string): unknown;
+    /** Read fresh on every call: `enabled` reflects each option's guard right now. */
+    actions(): readonly SurfaceAction[];
+    /**
+     * Whether a claimant could act on it now. A short-form decision is ready once one of its options
+     * is enabled; a full-form surface once any of its actions is, since editing comes before
+     * finishing (its Save may be disabled until something is edited).
+     */
+    isReady(): boolean;
 }
 
 /**
  * A message's interaction widget, in the wrapper that mounts it. Everything the widget is shown
- * comes from the history message through here, the outcome a tool recorded after the answer
- * included, so a remount, a pop-out and a reload all show the same thing.
+ * comes from the history message through here, the outcome a tool recorded after the answer and the
+ * edits a claimant made included, so a remount, a pop-out and a reload all show the same thing.
  *
  * @internal
  */
 export declare const interactionWrapperTemplate: ViewTemplate<ChatMessage, FoundationAiAssistant>;
 
+/**
+ * What came of an `InteractionHold.invoke` (GENC-1660). On success, `finished` says whether the
+ * interaction settled and `actions` is what is enabled now; on failure, `error` says why and nothing
+ * ran.
+ *
+ * @beta
+ */
+export declare type InvokeResult = {
+    readonly ok: true;
+    readonly finished: boolean;
+    readonly actions: readonly SurfaceAction[];
+    /** What an editing action returned (fresh errors, say), for the claimant. */
+    readonly output?: unknown;
+    readonly error?: never;
+    readonly message?: never;
+} | {
+    readonly ok: false;
+    readonly finished?: never;
+    readonly error: 'not-held' | 'no-surface' | 'unknown-action' | 'disabled' | 'invalid-args' | 'threw' | 'busy';
+    readonly message: string;
+    readonly actions?: readonly SurfaceAction[];
+};
+
 /** True when the assistant is active in the layout panel (docked) rather than the bubble. */
 export declare function isAiAssistantDocked(): boolean;
 
@@ -6047,6 +7063,14 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
      * undecorated.
      */
     resumeRestoredFlow(resumeNote?: string): Promise<ChatDriverResult | undefined>;
+    /**
+     * A continuation outside a routed turn — a decorator carrying the agent on, say — can finish the
+     * flow as surely as a turn can, so a release it requests is acted on here too. Before
+     * (GENC-1660), only `sendMessage` checked, and a flow finished by a continuation stayed locked.
+     */
+    continueFromHistory(transientPrimer?: ChatMessage[], options?: ContinueFromHistoryOptions): Promise<ChatDriverResult>;
+    /** Release the flow if the turn that just ended asked to, and an agent is still active to release. */
+    private releaseIfRequested;
     /**
      * {@inheritDoc AiDriver.getContextReserve}
      *
@@ -6126,6 +7150,17 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
  */
 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.
+ *
+ * @beta
+ */
+export declare interface PersistedAutopilotMode {
+    readonly onFor: string;
+    readonly mode: 'running' | 'paused';
+}
+
 /**
  * A `condenseWhen` policy that had NOT fired when the session was saved, in the shape it is
  * persisted in (GENC-1632).
@@ -6167,6 +7202,17 @@ export declare interface PersistedCondensePolicy {
     };
 }
 
+/**
+ * A long action's checkpoint as persisted with the session (GENC-1660 §4.12): the widget type it
+ * belongs to, and the value its controller saved.
+ *
+ * @beta
+ */
+export declare interface PersistedInteractionCheckpoint {
+    readonly componentName: string;
+    readonly value: unknown;
+}
+
 /**
  * A durable, restorable snapshot of one chat session — the *restorable core* of
  * the debug log (GENC-1351 §5.1/D1), captured losslessly and independently of
@@ -6222,6 +7268,25 @@ export declare interface PersistedSession {
      * predates it ignores it. Omitted rather than written empty when there is nothing to carry.
      */
     condensePolicies?: PersistedCondensePolicy[];
+    /**
+     * The autopilot's mode for the flow it was set for (GENC-1660 §4.8), restored with the session.
+     * Optional and additive like `condensePolicies`: absent when no autopilot was switched for the
+     * current flow, and a snapshot from before it existed restores with the autopilot paused.
+     */
+    autopilot?: {
+        onFor: string;
+        mode: 'running' | 'paused';
+    };
+    /**
+     * The checkpoint of a long action (GENC-1660 §4.12): what a widget's work had already done, so a
+     * reload skips it. Kept here rather than on the interaction message, which a restore trims. On
+     * restore it waits for the first request of the same widget type. Optional and additive, like
+     * `condensePolicies`.
+     */
+    checkpoint?: {
+        componentName: string;
+        value: unknown;
+    };
     /**
      * Interrupted-flow marker (GENC-1351 §5.9). Present when the session was saved
      * while an agent declared its current state non-resumable (`resumable === false`).
@@ -6267,6 +7332,17 @@ declare type ProviderRefusedDetail = NonNullable<Extract<ChatDriverResult, {
     reason: 'done';
 }>['providerRefused']>;
 
+/**
+ * Register a widget with the platform (GENC-1660): its controller, the element that renders it, how
+ * it behaves while a claimant holds it, and its text form. Once per name, at start-up; a second
+ * registration under the same name replaces the first, with a warning.
+ *
+ * Registering is optional and additive: an unregistered widget works exactly as before.
+ *
+ * @beta
+ */
+export declare function registerInteraction(name: string, registration: InteractionRegistration): void;
+
 /**
  * Build a {@link TieredAIProviderSwitcher} — which registers the tier-shaped provider
  * registry — and put it on the {@link (AIProviderSwitcher:variable)} token. Call once at app
@@ -6464,6 +7540,23 @@ export declare type RoutingDecision =
 /** A pin or an active flow owned the turn; the classifier was skipped. */
 | 'pinned';
 
+/**
+ * Run a long action as named steps, checkpointing after each one (GENC-1660 §4.12), so a reload
+ * skips what is already done instead of starting again.
+ *
+ * Starts from the checkpoint the platform handed over, if any — it has already decided, by widget
+ * type and the registration's `sameWork`, that the checkpoint is this work's — or from `initial`, the
+ * identity `sameWork` compares, kept in the checkpoint because the request that cut it is gone.
+ * Each step that is already done is skipped; the rest run in order. `ctx.state.stage` names the step
+ * running, and every step notifies, which is also the watchdog's heartbeat.
+ *
+ * Exported beside the context rather than added to it, so the context's own API stays small.
+ * Throws if `signal` aborts, before or between steps.
+ *
+ * @beta
+ */
+export declare function runSteps<C extends StepCheckpoint>(ctx: InteractionContext<object, C>, initial: Omit<C, 'done' | 'started'>, steps: readonly Step<C>[], signal?: AbortSignal): Promise<C>;
+
 /**
  * Options for `AiDriver.sendMessage` (GENC-1660).
  *
@@ -6481,6 +7574,12 @@ export declare interface SendMessageOptions {
      * {@link DEFAULT_DELEGATE_FRAMING}. Ignored unless `delegate` is set.
      */
     delegateFraming?: string;
+    /**
+     * What producing the message cost outside the working agent's own model calls — e.g. the model
+     * calls the decorator made to write it — booked on the stored message as `externalCostUsd`, so it
+     * reaches the session total. Ignored unless `delegate` is set and it is a positive, finite number.
+     */
+    externalCostUsd?: number;
 }
 
 /**
@@ -6853,6 +7952,15 @@ export declare interface StatefulAgentInit<S> {
      * reached.
      */
     toolHandlers?: (state: S) => ChatToolHandlers | Promise<ChatToolHandlers>;
+    /**
+     * The autopilot that may answer this agent's interactions on the user's behalf (GENC-1660). Its
+     * resolvers receive this agent's live state, typed. Build it with {@link defineAutopilot}; a
+     * shared definition (a const or a factory) works for any agent.
+     *
+     * Only stateful agents take one: an autopilot is scoped to a flow, and only a stateful agent
+     * owns one.
+     */
+    autopilot?: AutopilotConfig<S>;
     /**
      * Which registered AI provider this agent uses, by name. Either a static
      * string or a function resolved each tool-loop iteration with the current
@@ -6991,6 +8099,45 @@ export declare type StatefulAgentPersistenceContext<S> = Omit<AgentPersistenceCo
     state: S;
 };
 
+/**
+ * One named step of a long action. A step is either done-or-restart (its output is kept once it
+ * finishes, and a cut one simply runs again) or re-attachable (it saves a job id with `save` before
+ * waiting, and on a re-run finds that id in the checkpoint and reconnects to the job).
+ *
+ * @beta
+ */
+export declare interface Step<C extends StepCheckpoint> {
+    readonly name: string;
+    /**
+     * Do the step. Returns its outputs, merged into the checkpoint. `save` persists part of an
+     * unfinished step, such as a job id, before a long wait.
+     */
+    run(checkpoint: C, io: {
+        readonly signal?: AbortSignal;
+        save(partial: Partial<C>): void;
+    }): Promise<Partial<C>>;
+}
+
+/**
+ * A long action's checkpoint (GENC-1660 §4.12): the steps already done, the steps that started, and
+ * whatever the steps returned or saved. Keep it small, and storable as JSON.
+ *
+ * @beta
+ */
+export declare type StepCheckpoint = {
+    /** Steps that finished: skipped when the work resumes after a reload. */
+    readonly done: readonly string[];
+    /** Steps that started. One started but not done was cut mid-way, and runs again. */
+    readonly started?: readonly string[];
+} & Record<string, unknown>;
+
+/**
+ * How a step went, for the debug log.
+ *
+ * @beta
+ */
+export declare type StepOutcome = 'started' | 'resumed' | 'done' | 'skipped';
+
 /**
  * A brief, professional fallback agent. States what is available without
  * elaboration. The `{{agents}}` placeholder is replaced at runtime by
@@ -7038,6 +8185,85 @@ export declare type SuggestionsState = {
     message: string;
 };
 
+/**
+ * One action on a surface, as anyone may read it (GENC-1660).
+ *
+ * @beta
+ */
+export declare interface SurfaceAction {
+    /** The name to invoke it by: an option's id, or `select` / `reply`. */
+    readonly name: string;
+    /** The text the person sees for it, where it has one. */
+    readonly label?: string;
+    /** Whether running it settles the interaction. Every short-form action does. */
+    readonly finishes: boolean;
+    /** Whether it can be run right now. */
+    readonly enabled: boolean;
+    /**
+     * What its `args` must look like, where it takes any: `options` (a multi-select's picks), `text`
+     * (a written answer) or `fields` (an object, described by `argsSchema`).
+     */
+    readonly args?: 'options' | 'text' | 'fields';
+    /** A full-form action's own description, for the model. Short-form options have none. */
+    readonly description?: string;
+    /** For `fields`: the JSON schema its arguments are checked against. */
+    readonly argsSchema?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * One action of a full-form surface (GENC-1660 §4.2): a named thing a claimant can do, which may or
+ * may not settle the interaction.
+ *
+ * @beta
+ */
+export declare interface SurfaceActionSpec {
+    /** For the model: what it does, and when to use it. */
+    readonly description: string;
+    /** Whether it settles the interaction. An editing action (`edit_rows`) does not. */
+    readonly finishes?: boolean;
+    /** The button's own guard, read fresh: the claimant can never do what the view would refuse. */
+    readonly enabledWhen?: () => boolean;
+    /**
+     * The JSON schema of its arguments, an object. Its `properties` and `required` are checked before
+     * it runs; a mismatch is refused with the reason, so the model can correct itself.
+     */
+    readonly argsSchema?: Readonly<Record<string, unknown>>;
+    /**
+     * Do it — the SAME code the view's control runs. A finishing action resolves the interaction; an
+     * editing one returns what changed (fresh errors, say), which the claimant is shown.
+     *
+     * A finishing action should settle promptly. While one runs asynchronously, the claimant can run
+     * nothing else, and it keeps the claimant's credit even if the interaction is handed to the person
+     * meanwhile, so the view should block its own controls until it ends: a click that lands then
+     * would be credited to the claimant.
+     */
+    run(args: unknown): unknown | Promise<unknown>;
+}
+
+/**
+ * A full-form surface, for a rich widget (GENC-1660 §4.2): something to describe, views to read,
+ * and named actions, some of which only edit.
+ *
+ * Its actions run one at a time. An asynchronous finishing action should settle promptly, and the
+ * view should block its own controls while one runs (see {@link SurfaceActionSpec.run}).
+ *
+ * @beta
+ */
+export declare interface SurfaceSpec {
+    /** For the model: what this is, and what good looks like. Read fresh. */
+    describe(): string;
+    /** The names of the views `read` answers, e.g. `['summary', 'rows', 'errors']`. */
+    readonly views?: readonly string[];
+    /**
+     * The widget's state as JSON, by view, so a large widget is read a slice at a time. Called with
+     * no view for the default (shown with the decision, so pick something small).
+     */
+    read(view?: string): unknown;
+    readonly actions: Readonly<Record<string, SurfaceActionSpec>>;
+    /** Model-only guidance, beside `describe`. */
+    readonly prompt?: string;
+}
+
 /**
  * Context passed to the function form of `systemPrompt` / `toolDefinitions`.
  * Resolved each tool-loop iteration so the agent can vary what the LLM sees per turn.