@genesislcap/ai-assistant 15.84.3 → 15.85.0

package/dist/ai-assistant.d.ts

@@ -25,6 +25,9 @@ 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 type { HandOffCompletion } from '@genesislcap/foundation-ai';
+import type { HandOffRequest } from '@genesislcap/foundation-ai';
+import type { HandOffResult } from '@genesislcap/foundation-ai';
 import { InteractionEdit } from '@genesislcap/foundation-ai';
 import type { InteractionRequestOptions } from '@genesislcap/foundation-ai';
 import type { InteractionResult } from '@genesislcap/foundation-ai';
@@ -531,8 +534,8 @@ export { AgentPickerMode }
  * and the `onActivate` / `onDeactivate` lifecycle around a swap. Either driver can own one.
  *
  * Knows nothing about routing, tool surfaces or transcripts — whether an agent is terminal, the
- * continuation tool, the handoff marker in history all stay with the orchestrator, which is the
- * only thing with agents to route between.
+ * hand-off stack, the divider in history all stay with the orchestrator, which is the only thing
+ * with agents to route between.
  *
  * @beta
  */
@@ -564,6 +567,17 @@ export declare class AgentSession {
     private restoredStates;
     /** The tail of the activation queue — see {@link AgentSession.activate}. */
     private activation;
+    /**
+     * Callers waiting in a hand-off (GENC-1737), oldest first: still live, so never deactivated by
+     * the hand-off, and resumed without `onActivate`. Empty after a reload, when a caller has no live
+     * state and is activated again from its saved state instead.
+     */
+    private suspended;
+    /**
+     * The `data` of the hand-off that activated each agent (GENC-1737), for its tool handlers: kept
+     * while it is active or waits as a caller, and dropped when its activation ends.
+     */
+    private handOffData;
     constructor(deps: AgentSessionDeps);
     /** The active agent, or `undefined` before the first activation and after a release. */
     getActive(): AgentConfig | undefined;
@@ -589,6 +603,39 @@ export declare class AgentSession {
     primeRestoredStates(snapshots: Record<string, unknown>): void;
     /** Whether a restored snapshot is waiting for this agent's next activation. */
     hasRestoredState(agentName: string): boolean;
+    /** The `data` of the hand-off that activated `agentName`, if one did and carried any. */
+    getHandOffData(agentName: string): unknown;
+    /** Record the `data` a hand-off activated `agentName` with, or restore it; `undefined` drops it. */
+    setHandOffData(agentName: string, data: unknown): void;
+    /**
+     * Drop the flow lock and leave the active agent active (GENC-1737): a plain agent holding it with
+     * no hand-off behind it is done once its turn ends.
+     */
+    dropFlowLock(): void;
+    /** The callers waiting in a hand-off whose state is live, oldest first. */
+    getSuspended(): readonly AgentConfig[];
+    /**
+     * Make `target` active for a hand-off (GENC-1737), holding the flow lock whatever kind of agent
+     * it is, since a waiting caller depends on it. With `suspendCaller` the active agent waits:
+     * it is not deactivated and keeps its state. Without it the active agent is deactivated as on
+     * any swap: a one-way hand-off from a target, whose waiting caller then waits for the new
+     * target. Queued with {@link AgentSession.activate}.
+     */
+    handOff(target: AgentConfig, options: {
+        suspendCaller: boolean;
+    }): Promise<AgentTransition>;
+    /**
+     * Make a waiting caller active again when its hand-off ends (GENC-1737). One whose state is live
+     * resumes without `onActivate`, since it was never deactivated; after a reload it is activated
+     * from its saved state like any other agent. `lock` keeps the flow lock on it: it held it before,
+     * or another caller is still waiting further down.
+     */
+    resume(caller: AgentConfig, lock: boolean): Promise<AgentTransition>;
+    /**
+     * Deactivate the callers left waiting by hand-offs that ended without a hand-back, newest first,
+     * when no teardown follows to do it (GENC-1737).
+     */
+    endSuspended(): Promise<void>;
     /**
      * Make `agent` active, firing the lifecycle hooks around the swap: outgoing `onDeactivate`
      * first, then incoming `onActivate`. Both are awaited so heavy activation work (a machine
@@ -605,6 +652,10 @@ export declare class AgentSession {
      * the flow owner outside a turn, where a send can land mid-activation.
      */
     activate(agent: AgentConfig): Promise<AgentTransition>;
+    /**
+     * `lock` takes the flow lock whatever kind of agent it is, and `suspendPrevious` leaves the
+     * outgoing agent waiting instead of deactivating it, as a hand-off does (GENC-1737).
+     */
     private activateNow;
     /**
      * Release the active agent: fire `onDeactivate` and drop the flow lock.
@@ -742,6 +793,12 @@ export declare const AiAssistantEvent: {
     readonly SessionCleared: "session-cleared";
     /** Header pressed in `popout-mode="expand"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */
     readonly ChatHeaderMouseDown: "chat-header-mousedown";
+    /** An agent's hand-off started (GENC-1737). `detail`: `HandOffFrame`. */
+    readonly HandOffStarted: "handoff-started";
+    /** A hand-off ended and its caller is active again. `detail`: `HandOffFrame`, with `outcome`. */
+    readonly HandOffReturned: "handoff-returned";
+    /** A hand-off ended with no hand-back. `detail`: `HandOffFrame`, with `outcome`. */
+    readonly HandOffUnwound: "handoff-unwound";
 };
 
 /**
@@ -1033,6 +1090,58 @@ export declare interface AiDriver extends EventTarget {
         restored: number;
         awaitingReactivation: number;
     };
+    /**
+     * The hand-offs in progress, oldest first, to save with the session (GENC-1737). Copies: changing
+     * them changes nothing.
+     *
+     * @beta
+     */
+    getHandOffStack?(): HandOffFrame[];
+    /**
+     * Restore saved hand-offs, before the condense policies, against the agents configured now and
+     * the saved agent states. A frame whose caller has gone, or whose stateful caller has no saved
+     * state (`interrupted` drops them all), is unwound with `handoff-unwound`. When the top frame's
+     * target had finished, or has gone, its caller is due to resume: `resume` names it and the note
+     * its resumed turn needs, and {@link AiDriver.resumeRestoredFlow} hands back. `droppedLocks`
+     * names plain targets of unwound hand-offs, whose saved lock was only that hand-off's.
+     *
+     * @beta
+     */
+    restoreHandOffStack?(saved: unknown, savedStates: Record<string, unknown>, interrupted: boolean): {
+        resume?: {
+            agent: string;
+            note: string;
+        };
+        droppedLocks?: string[];
+    };
+    /**
+     * End every hand-off without a hand-back, newest first: the chat was cleared, or the agents
+     * changed. Each raises `handoff-unwound`; on Clear a waiting caller's `onHandOffReturn` is told.
+     *
+     * @beta
+     */
+    unwindHandOffs?(kind: Extract<HandOffOutcomeKind, 'cleared' | 'state-lost'>): Promise<void>;
+    /**
+     * The saved state of each caller waiting in a hand-off whose state is live, by name, from its
+     * `serialize`. Saved with the active agent's, so a reload can resume the caller.
+     *
+     * @beta
+     */
+    serializeWaitingCallers?(): Record<string, unknown>;
+    /**
+     * The `data` each hand-off target was activated with, by name, for the agents a reload resumes:
+     * the flow owner and the callers waiting in a hand-off. See the tool context's `handOffData`.
+     *
+     * @beta
+     */
+    getHandOffData?(): Record<string, unknown>;
+    /**
+     * Restore what {@link AiDriver.getHandOffData} saved, before the hand-off stack. Nothing comes
+     * back from a frozen (`interrupted`) session, whose flow does not resume.
+     *
+     * @beta
+     */
+    restoreHandOffData?(saved: unknown, interrupted: boolean): void;
     /**
      * The live `AgentConfig` currently active in the driver — the instance whose
      * `onActivate` ran, so its `serialize`/`getDebugSnapshot` closures hold live
@@ -1323,6 +1432,12 @@ export declare interface AiDriverEventMap {
     'agent-released': CustomEvent<AgentConfig>;
     /** The flow-owner lock changed. Detail: the new owner's name, or `null` when cleared. */
     'flow-owner-changed': CustomEvent<string | null>;
+    /** A hand-off started: its target is now active (GENC-1737). */
+    'handoff-started': CustomEvent<HandOffFrame>;
+    /** A hand-off ended and its caller is active again; `detail.outcome` says how. */
+    'handoff-returned': CustomEvent<HandOffFrame>;
+    /** A hand-off ended with no hand-back: cleared, or found unresumable. */
+    'handoff-unwound': CustomEvent<HandOffFrame>;
     /** Routing started (the classifier is about to run). Orchestrator only. */
     'orchestrating-start': CustomEvent<undefined>;
     /** Routing finished and an agent is installed. Orchestrator only. */
@@ -2372,6 +2487,28 @@ declare interface BaseAgentConfig {
      * @beta
      */
     onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+    /**
+     * Fires on the caller when its `handOff` takes effect, after its turn: it now waits, still active
+     * in spirit, for `frame.target` to finish. Awaited before the target runs. GENC-1737.
+     *
+     * @beta
+     */
+    onHandOffStart?: (frame: HandOffFrame) => void | Promise<void>;
+    /**
+     * Fires on the caller when a hand-off it made ends, before its next model call, so its own state
+     * can move on. `outcome.kind` says how it ended. Not fired for `state-lost`, whose caller cannot
+     * resume. GENC-1737.
+     *
+     * @beta
+     */
+    onHandOffReturn?: (outcome: HandOffOutcome, frame: HandOffFrame) => void | Promise<void>;
+    /**
+     * The agents this one may hand off to. Left out, any other agent. A `handOff` to one not listed
+     * is refused with `not-allowed`. GENC-1737.
+     *
+     * @beta
+     */
+    handOffTargets?: string[];
     /**
      * Returns an agent-supplied debug payload for the export log. Called once per
      * LLM call by the driver (alongside the resolved prompt and tool list) and
@@ -2534,6 +2671,18 @@ export declare abstract class BaseDriverDecorator<TInner extends AiDriver = AiDr
         restored: number;
         awaitingReactivation: number;
     };
+    getHandOffStack(): HandOffFrame[];
+    restoreHandOffStack(saved: unknown, savedStates: Record<string, unknown>, interrupted: boolean): {
+        resume?: {
+            agent: string;
+            note: string;
+        };
+        droppedLocks?: string[];
+    };
+    unwindHandOffs(kind: Extract<HandOffOutcomeKind, 'cleared' | 'state-lost'>): Promise<void>;
+    serializeWaitingCallers(): Record<string, unknown>;
+    getHandOffData(): Record<string, unknown>;
+    restoreHandOffData(saved: unknown, interrupted: boolean): void;
     getActiveAgent(): AgentConfig | undefined;
     setPinnedAgent(name: string | null): void;
     setFlowOwner(name: string | null): void;
@@ -2801,9 +2950,8 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     /** Sub-agents declared on the active agent config, keyed by name. */
     private subAgentsMap;
     /**
-     * Set by `completeSubAgent` inside a sub-agent tool handler. Checked at the
-     * same point in the loop as `REQUEST_CONTINUATION_TOOL` — after tool results
-     * are appended — so the exit path mirrors the system-call pattern.
+     * Set by `completeSubAgent` inside a sub-agent tool handler. Checked after tool
+     * results are appended, so the turn ends without another model call.
      * `undefined` means the loop has not been stopped early.
      */
     private subAgentCompletion;
@@ -2835,6 +2983,23 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * doesn't leak forward.
      */
     private agentReleaseRequested;
+    /** A `handOff` this call accepted, for the orchestrator to act on after it (GENC-1737). */
+    private handOffRequested?;
+    /** What `completeHandOff` handed back this call, beside the release it also requests. */
+    private handOffCompletion?;
+    /** See {@link ChatDriver.setHandOffCheck}. */
+    private checkHandOff?;
+    /**
+     * The `agentEnd` activation of each caller waiting in a hand-off, by agent name, with the phase
+     * epoch it was suspended at (GENC-1737). A waiting caller is suspended, not ended, so neither its
+     * `agentEnd` payloads nor its `phaseEnd` ones (to another agent's `endPhase()`) collapse while the
+     * target runs; when it is installed again its entries move to the new activation and, while
+     * their phase had not ended, to the current epoch. A caller restored from a saved session gets
+     * an activation placeholder below zero, which no live activation uses.
+     */
+    private readonly suspendedActivations;
+    /** The last placeholder handed out for a restored caller; see `suspendedActivations`. */
+    private restoredSuspensionSeq;
     /**
      * Per-turn snapshots, forwarded sub-agent snapshots, and harvested external diagnostics —
      * everything the exported debug log draws from this driver.
@@ -2980,8 +3145,8 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * The stateful-agent contract for this driver: active agent, user pin, flow lock, restored
      * state, and the `onActivate` / `onDeactivate` hooks (§7.1).
      *
-     * **Public because `OrchestratingDriver` reaches through to it.** The orchestrator decorates a
-     * config before installing it (the cross-agent continuation tool), so it cannot route through
+     * **Public because `OrchestratingDriver` reaches through to it.** The orchestrator builds a
+     * config before installing it (the fallback's prompt), so it cannot route through
      * {@link ChatDriver.activateAgent} and must drive the session itself — and one shared session is
      * the point: two would let `getActiveAgent()` disagree between the outer and inner driver.
      * `@internal` rather than private so that reach is legal without six delegating one-liners.
@@ -3223,17 +3388,13 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * does not show it twice. Marks it shown otherwise. Only the driver the user sees keeps count.
      */
     private aiServiceSentenceShown;
-    /**
-     * Whether a sub-agent hit a wall this turn that stops this driver too. A handoff goes on past an
-     * AI-service wall: the next agent may use another vendor, and if it uses this one its own call
-     * meets the wall and says so.
-     */
+    /** Whether a sub-agent hit a wall this turn that stops this driver too. */
     private subAgentWallThisTurn;
     /**
      * Ends the turn when a sub-agent hit a wall this turn that stops this driver too: the provider
      * refusing the account, the AI service (GENC-1611), or the budget. Checked before each model call,
-     * and again right after a tool batch, before a handoff or the iteration cap can report the turn as
-     * something else.
+     * and again right after a tool batch, before the iteration cap can report the turn as something
+     * else.
      */
     private endTurnOnSubAgentWall;
     /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
@@ -3406,6 +3567,53 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Consumed by the orchestrator to trigger the auto-pin release path.
      */
     getAgentReleaseRequested(): boolean;
+    /**
+     * Offer `handOff` and `completeHandOff` to tool handlers, checking each `handOff` with `check`
+     * (GENC-1737). Set by `OrchestratingDriver`, which knows the agents and the hand-off stack and acts
+     * on the request after the call; a bare `ChatDriver` has no other agent to hand to.
+     *
+     * @internal
+     */
+    setHandOffCheck(check: (request: HandOffRequest, caller: string | undefined) => HandOffResult): void;
+    /** The `handOff` the most recent call accepted, if any (GENC-1737). */
+    getHandOffRequest(): HandOffRequest | undefined;
+    /** What `completeHandOff` handed back in the most recent call, if it was called. */
+    getHandOffCompletion(): HandOffCompletion | undefined;
+    /**
+     * A handler's `handOff`: refused once this call has handed off or released, or when `data` is
+     * not JSON, and otherwise checked by the orchestrator. `data` is kept as a JSON copy, since it is
+     * saved with the session and the handler may change its own object afterwards.
+     */
+    private requestHandOff;
+    /**
+     * The note of the closing call a hand-off asks for (GENC-1737), or `undefined` when none: once a
+     * handler's `handOff` is accepted, or `completeHandOff` is called, the rest of that batch runs,
+     * then one model call with no tools, so the agent can say so but not carry on, which a model told
+     * so in a tool result does anyway. Then the turn ends.
+     */
+    private closingCallNote;
+    /**
+     * Suspend the active agent's activation for a hand-off it made (GENC-1737): installing the target
+     * advances the `agentEnd` clock as any swap does, but this caller's payloads stay live.
+     */
+    suspendActivation(agentName: string): void;
+    /**
+     * Suspend restored callers before their condense policies are restored, so entries still live
+     * at save time stay live instead of waiting for "the next activation", which is the target's.
+     */
+    suspendRestoredActivations(agentNames: readonly string[]): void;
+    /** End every suspension: the hand-offs were unwound, so their callers' activations are over. */
+    endSuspendedActivations(): void;
+    /**
+     * A caller installed again takes its suspended entries into the activation it resumes in, and
+     * the ones whose phase had not ended into the current phase epoch.
+     */
+    private resumeSuspendedActivation;
+    /**
+     * The suspended activations, each with the phase epoch it was suspended at, for the `agentEnd`
+     * and `phaseEnd` checks and for persistence.
+     */
+    private suspendedClocks;
     /**
      * Act on a `releaseAgent` call from a tool handler: fire `onDeactivate` and drop the flow lock,
      * so the next turn starts clean and the persister does not serialize a flow that is over.
@@ -3856,7 +4064,7 @@ export declare interface ChatDriverConfig {
      * Leave acting on `releaseAgent` to the owner of this driver.
      *
      * Set by `OrchestratingDriver` for its inner driver, which performs the release itself after the
-     * turn, because a release ends its handoff loop and it reads the flag to know. Both drivers share
+     * call, because a release may hand back to a waiting caller and it reads the flag to know. Both drivers share
      * one `AgentSession`, and releasing here first would clear the flag before the orchestrator saw
      * it. The host-facing `agent-released` / `agent-changed` / `flow-owner-changed` events fire from
      * the session's transition either way (GENC-1485).
@@ -4696,6 +4904,9 @@ export declare function formatBlockedReason(budget?: Partial<Extract<ChatDriverR
  *
  * @fires chat-header-mousedown - Fired when the user presses the chat header in `popout-mode="expand"` (for drag-to-popout hosts). Bubbles and composed. detail: `ChatHeaderMouseDownDetail`
  * @fires session-cleared - Fired after the session is wiped (the lifecycle menu's Clear). The payload is captured before teardown so the host can clean up any external state the active agent was working on. Bubbles and composed. detail: `SessionClearedDetail`
+ * @fires handoff-started - Fired when an agent's `handOff` takes effect and its target becomes active. Bubbles and composed. detail: `HandOffFrame`
+ * @fires handoff-returned - Fired when a hand-off ends and its caller is active again; `detail.outcome` says how it ended. Bubbles and composed. detail: `HandOffFrame`
+ * @fires handoff-unwound - Fired when a hand-off ends with no hand-back: the chat was cleared, the agents changed, or a restore found it could not resume. Bubbles and composed. detail: `HandOffFrame`
  *
  * @beta
  */
@@ -7018,6 +7229,53 @@ export declare interface HandlerCapabilityScope {
     readonly flowOwner: string | null;
 }
 
+/**
+ * One hand-off on the stack, saved with the session: who waits, for whom, and why. `outcome` is set
+ * when the target finishes, until the caller has resumed, so a reload in between still hands back.
+ * Also the `detail` of the `handoff-started`, `handoff-returned` and `handoff-unwound` events.
+ *
+ * @beta
+ */
+export declare interface HandOffFrame {
+    id: string;
+    /** The agent waiting for the hand-back. */
+    caller: string;
+    target: string;
+    returnTo: boolean;
+    /** The brief. */
+    message: string;
+    /** JSON only. */
+    data?: unknown;
+    /** ISO time the hand-off started. */
+    startedAt: string;
+    outcome?: HandOffOutcome;
+}
+
+/**
+ * What a hand-off's caller gets back. `message` is the target's `completeHandOff` summary, or for
+ * `released` its final reply since the brief; `data` is what `completeHandOff` passed.
+ *
+ * @beta
+ */
+export declare interface HandOffOutcome {
+    kind: HandOffOutcomeKind;
+    message?: string;
+    data?: unknown;
+}
+
+/**
+ * How a hand-off ended (GENC-1737):
+ * - `completed`: the target called `completeHandOff`;
+ * - `released`: the target called `releaseAgent`, or, a plain one, ended its turn;
+ * - `cleared`: the user cleared the chat;
+ * - `agent-removed`: the caller or the target is no longer in the agent list, found on restore;
+ * - `state-lost`: the caller's saved state is gone, so it cannot resume: a session saved while its
+ *   flow could not be resumed, or a change to the agents, which disposes them.
+ *
+ * @beta
+ */
+export declare type HandOffOutcomeKind = 'completed' | 'released' | 'cleared' | 'agent-removed' | 'state-lost';
+
 /**
  * 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
@@ -7772,22 +8030,37 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
      */
     private get agentSession();
     /**
-     * Set by `cancel()` for the duration of a `sendMessage` run. Breaks the
-     * handoff loop so we don't classify or start another agent turn after the
-     * user stops. Reset at the start of each `sendMessage`.
+     * Set by `cancel()` for the duration of a run. Stops it before the next agent
+     * runs — a hand-off's target or a hand-back's caller — so nothing more is asked
+     * of a provider after the user stops. Reset at the start of each run.
      */
     private cancelled;
     /**
      * Whether the CURRENT turn's user message has reached the inner driver's
      * history. False through the pre-first-turn classify (where the only echo of
      * the message is an optimistic `history-updated` dispatch), true from the
-     * moment `chatDriver.sendMessage` is entered — including through every later
-     * handoff classify. Read by the budget-wall catch in `sendMessage` to decide
+     * moment `chatDriver.sendMessage` is entered. Read by the budget-wall catch in
+     * `sendMessage` to decide
      * whether `reportBudgetExhausted` must append the message itself: appending
      * it when already appended duplicated it; not appending it when unappended
      * made it vanish. Reset at the top of each `runOrchestratedTurn`.
      */
     private userMessageAppended;
+    /** How many callers may wait in hand-offs at once (GENC-1737). */
+    private readonly maxHandOffDepth;
+    /**
+     * The hand-offs in progress, oldest first (GENC-1737). The top frame's target is the active agent
+     * and holds the flow lock; each caller waits, suspended, for the target above it. Saved with the
+     * session through {@link OrchestratingDriver.getHandOffStack}.
+     */
+    private handOffStack;
+    /** Hand-offs and hand-backs this user turn, against `maxHandoffs`. */
+    private handOffsThisTurn;
+    /**
+     * A hand-back a restore found due — the top frame's target had finished, or has gone — which
+     * {@link OrchestratingDriver.resumeRestoredFlow} carries out.
+     */
+    private pendingHandBack?;
     /**
      * The active agent, or `undefined` before the first activation and after a release.
      *
@@ -7798,6 +8071,8 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
     constructor(providerRegistry: AIProviderRegistry, agents: AgentConfig[], options?: {
         sessionKey?: string;
         maxHandoffs?: number;
+        /** How many callers may wait in hand-offs at once. Default 1. */
+        maxHandOffDepth?: number;
         classifierHistoryLength?: number;
         classifierRetries?: number;
         maxToolIterations?: number;
@@ -7818,6 +8093,33 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     sendMessage(input: string, attachments?: ChatAttachment[], options?: SendMessageOptions): Promise<ChatDriverResult>;
     private runOrchestratedTurn;
+    /**
+     * Act on what the agent call that just ended asked for, and run the next agent in the same user
+     * turn while there is one (GENC-1737): a `handOff` runs its target with the brief, and a target
+     * that releases hands back to its caller. Returns the last call's result.
+     *
+     * A failed call ends the turn there, as a Stop does: what it asked for still happens, and the
+     * next agent runs on the next message. Running it now would meet the same wall (a budget, a
+     * refused account, a full context window), or build on a reply that never came.
+     */
+    private carryOn;
+    /**
+     * After one agent call: start the hand-off it asked for, or release it and, when it was a
+     * hand-off's target, hand back. Returns the tail note for the agent to run next, or `undefined`
+     * when the turn ends here.
+     *
+     * A plain target hands back when its call ends, released or not, as a plain agent is done once
+     * it has answered. A stateful one holds the hand-off until it releases, as it holds its flow.
+     */
+    private afterAgentCall;
+    /** How the target of `frame` finished: with `completeHandOff`, or a release and its last reply. */
+    private outcomeOf;
+    /**
+     * A plain agent is done once it has answered (GENC-1737): the data a one-way hand-off gave it ends
+     * with its turn, and so does a flow lock no hand-off holds, such as one a restore left on a
+     * target whose hand-off it could not resume.
+     */
+    private endPlainTurn;
     /** {@inheritDoc AiDriver.canRestoreFlowOwner} */
     canRestoreFlowOwner(agentName: string): boolean;
     /** {@inheritDoc AiDriver.canResumeRestoredFlow} */
@@ -7835,25 +8137,31 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
      * undecorated.
      */
     resumeRestoredFlow(resumeNote?: string): Promise<ChatDriverResult | undefined>;
+    /**
+     * The hand-back a restore found due (GENC-1737). The first call, inside the host's restore gate,
+     * makes the caller active again and tells it the outcome; the call with the note runs its turn.
+     */
+    private resumeHandBack;
     /**
      * 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}
      *
      * Two cases, because routing has two modes and they need opposite answers.
      */
     getContextReserve(): ContextReserveResolution | undefined;
+    /** Make `agent` active through the session, firing its hooks, and install it. */
+    private installAgent;
     /**
-     * `pin` stands in for the user-pin when given, as for
-     * {@link OrchestratingDriver.resolvePinnedAgent}.
+     * Install an agent the session has already made active on the inner driver: the transcript's
+     * divider when another agent spoke before it, and its own view of the history. What is left here
+     * is this driver's own job, the transcript; the session owns the lifecycle.
      */
-    private installAgent;
+    private applyAgent;
     /**
      * Release the current stateful agent: fire `onDeactivate` and clear the flow-owner lock. The
      * inner driver raises the events from the session's transition, so the host (and Redux) reflect
@@ -7866,10 +8174,66 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
      * routing through the classifier.
      */
     private releaseActiveAgent;
+    /** The agent named `name` as this driver installs it: the fallback with its prompt built. */
+    private agentNamed;
+    /**
+     * End the hand-offs when a turn runs an agent other than the top target (GENC-1737): the lock
+     * that kept turns on the target was taken away, by a host clearing `flowOwnerAgentName` say,
+     * and its caller would otherwise wait for good.
+     */
+    private endOrphanedHandOffs;
+    /**
+     * Check a handler's `handOff` when it is made (GENC-1737), so a refusal reaches its model. Checked
+     * against the agents and the stack as they are now; the hand-off itself starts after the call.
+     */
+    private checkHandOff;
+    /**
+     * Start the hand-off the agent call just made, and return the target's tail note (GENC-1737).
+     *
+     * - `returnTo` (the default): push a frame. The caller waits without being deactivated, its
+     *   `agentEnd` payloads suspended, and the target takes the flow lock.
+     * - One-way from a hand-off's target: that frame's caller now waits for the new target instead.
+     * - One-way with nobody waiting: a plain switch, the caller deactivated as on any swap.
+     *
+     * Either way the brief is recorded as a message the caller sent on the user's behalf.
+     */
+    private startHandOff;
+    /**
+     * Hand back to `frame`'s caller with `outcome`, and return its tail note (GENC-1737). The outcome
+     * is kept on the frame until the caller is active again and its `onHandOffReturn` has run, so a
+     * reload in between still hands back; the frame then goes, before the caller's model call.
+     */
+    private handBack;
+    /** The top frame, when `agent` is its target. */
+    private topFrameFor;
+    /** The target's last reply since its brief, for a target that released without a summary. */
+    private lastReply;
+    /** The brief, in the transcript as a message the caller sent on the user's behalf. */
+    private recordDelegated;
+    /** End `frame` with `kind` and no hand-back, for the host. */
+    private unwound;
+    /** {@inheritDoc AiDriver.getHandOffStack} */
+    getHandOffStack(): HandOffFrame[];
+    /** {@inheritDoc AiDriver.restoreHandOffStack} */
+    restoreHandOffStack(saved: unknown, savedStates: Record<string, unknown>, interrupted: boolean): {
+        resume?: {
+            agent: string;
+            note: string;
+        };
+        droppedLocks?: string[];
+    };
+    /** {@inheritDoc AiDriver.unwindHandOffs} */
+    unwindHandOffs(kind: 'cleared' | 'state-lost'): Promise<void>;
+    /** {@inheritDoc AiDriver.getHandOffData} */
+    getHandOffData(): Record<string, unknown>;
+    /** {@inheritDoc AiDriver.restoreHandOffData} */
+    restoreHandOffData(saved: unknown, interrupted: boolean): void;
+    /** {@inheritDoc AiDriver.serializeWaitingCallers} */
+    serializeWaitingCallers(): Record<string, unknown>;
     /**
      * Stop the current turn (user "stop" button). Cancels the inner chat driver's
-     * in-flight request and breaks the handoff loop so no further agent turn or
-     * classify runs. The driver stays usable for the next message.
+     * in-flight request, and no further agent runs this turn, not even a hand-off's
+     * target or a hand-back. The driver stays usable for the next message.
      */
     cancel(): void;
     /**
@@ -7911,7 +8275,7 @@ export declare class OrchestratingDriver extends BaseDriverDecorator<ChatDriver>
      */
     private resolvePinnedAgent;
     /**
-     * Append prose the ORCHESTRATOR wrote — the handoff cap, the no-specialist apology. Flagged
+     * Append prose the ORCHESTRATOR wrote — the no-specialist apology. Flagged
      * `excludeFromProvider` for the same reason the driver's own notices are: it is not something a
      * model said, and feeding it back invites the model to echo it. See
      * `ChatMessage.excludeFromProvider`.
@@ -8076,6 +8440,33 @@ export declare interface PersistedSession {
         componentName: string;
         value: unknown;
     };
+    /**
+     * The hand-offs in progress, oldest first (GENC-1737): who waits for whom, and why. A frame with
+     * an `outcome` was finished by its target but its caller had not resumed yet, so a restore hands
+     * back. Each agent's own state is in `agentSnapshots`, the waiting callers' included. Optional
+     * and additive, like `condensePolicies`; omitted when there are none. The frame's shape, written
+     * out here as for `checkpoints`.
+     */
+    handoffStack?: Array<{
+        id: string;
+        caller: string;
+        target: string;
+        returnTo: boolean;
+        message: string;
+        data?: unknown;
+        startedAt: string;
+        outcome?: {
+            kind: string;
+            message?: string;
+            data?: unknown;
+        };
+    }>;
+    /**
+     * The `data` each hand-off target was activated with, by agent name (GENC-1737), for the agents
+     * a restore resumes: the flow owner and the waiting callers. Not written for a frozen session.
+     * Optional and additive, like `handoffStack`; omitted when there is none.
+     */
+    handOffData?: Record<string, 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`).
@@ -8163,13 +8554,6 @@ export declare function registerInteraction<TController = unknown>(name: string,
  */
 export declare function registerTieredAIProviders(container: Container, options: Omit<TieredAIProviderSwitcherOptions, 'container'>): TieredAIProviderSwitcher;
 
-/**
- * Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver.
- *
- * @beta
- */
-export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
-
 /**
  * Ask the person for permission to show notifications, and resolve to the result. Call it from a
  * click or key handler: browsers ignore or refuse a request that does not come from the person.
@@ -8336,13 +8720,6 @@ export declare type RoutingDecision =
 'classified'
 /** The classifier ran and answered -1: nothing listed covers the request. */
 | 'no-match'
-/**
-* Every classifier-eligible specialist had already handled part of this turn and handed on, so
-* the ballot was empty and no call was made. Distinct from `'no-match'`, which means a
-* classifier RAN and declined — conflating the two re-creates exactly the "did anything actually
-* get asked?" ambiguity this event exists to remove.
-*/
-| 'ballot-exhausted'
 /** One viable specialist and no fallback — no point asking. */
 | 'single-candidate'
 /** Nothing classifier-eligible was configured. */
@@ -9684,7 +10061,7 @@ export declare type UnresolvedToolInput = (ctx: UnresolvedToolContext) => string
  * A fallback prompt written by a consumer reliably covers two cases — small talk, and a request
  * that belongs to a specialist — because those are the ones you think of when you write it. The
  * case it exists FOR is the third: a substantive request that no specialist covers, and no way to
- * act on it, because a fallback holds no tools and is denied the continuation tool as a leaf.
+ * act on it, because a fallback holds no tools.
  *
  * Create's fallback prompt is the worked example (GENC-1573). It covered chit-chat and
  * "out of scope, here are the specialists", said nothing about a request nothing can serve, and