@genesislcap/ai-assistant 15.84.2 → 15.85.0

package/dist/esm/components/chat-driver/chat-driver.js

@@ -13,13 +13,13 @@ import { freshUserMessages } from '../../utils/preserved-user-messages';
 import { resolveTurnInput } from '../../utils/resolve-turn-input';
 import { messageUsage, sumUsage } from '../../utils/sum-usage';
 import { AgentSession } from '../agent-session/agent-session';
-import { DEFAULT_MAX_FOLD_OPERATIONS, DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_MAX_TURN_SNAPSHOTS, DEFAULT_MAX_UNKNOWN_TOOL_CALLS, EMPTY_RESPONSE_NUDGE, HANDOFF_TOOL_RESULT_PLACEHOLDER, HARVESTED_SUBAGENT_EVENTS, MALFORMED_CALL_NUDGE, MAX_EMPTY_RESPONSE_RETRIES, MAX_MALFORMED_RETRIES, MAX_SETUP_TRANSPORT_RETRIES, MAX_STALE_TOOL_CALLS, REQUEST_CONTINUATION_TOOL, } from './chat-driver.constants';
+import { DEFAULT_MAX_FOLD_OPERATIONS, DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_MAX_TURN_SNAPSHOTS, DEFAULT_MAX_UNKNOWN_TOOL_CALLS, EMPTY_RESPONSE_NUDGE, HARVESTED_SUBAGENT_EVENTS, MALFORMED_CALL_NUDGE, MAX_EMPTY_RESPONSE_RETRIES, MAX_MALFORMED_RETRIES, MAX_SETUP_TRANSPORT_RETRIES, MAX_STALE_TOOL_CALLS, } from './chat-driver.constants';
 import { FoldController } from './fold-controller';
 import { InteractionController, } from './interaction-controller';
 import { TURN_FAILURE_EXITS, turnDone } from './turn-failures';
 import { TurnRecorder } from './turn-recorder';
 /** Re-exported so `from './chat-driver'` keeps resolving these. */
-export { EMPTY_RESPONSE_NUDGE, MALFORMED_CALL_NUDGE, REQUEST_CONTINUATION_TOOL, } from './chat-driver.constants';
+export { EMPTY_RESPONSE_NUDGE, MALFORMED_CALL_NUDGE } from './chat-driver.constants';
 /**
  * Refusals about one request rather than the service: the parent may well succeed, so a sub-agent's
  * is not shown to the user.
@@ -43,6 +43,22 @@ const SERVICE_WIDE_REFUSALS = new Set([
     'ACCESS_DENIED',
     'VENDOR_UNREACHABLE',
 ]);
+/**
+ * The tail note of a caller's closing call, once a handler's `handOff` is accepted (GENC-1737).
+ */
+const handOffClosingNote = (to) => `[Hand-off]: You handed this request to ${to}, which takes it from here. Tell the user so in one short line. Call no tools, and do not answer the rest of the request.`;
+/** The tail note of an agent's closing call, once a handler calls `completeHandOff` (GENC-1737). */
+const HAND_BACK_CLOSING_NOTE = '[Hand-back]: You have finished this request and handed it back. Tell the user so in one short line. Call no tools, and start nothing new.';
+/** A JSON copy of `value`, or `undefined` when it cannot be stored as JSON (GENC-1737). */
+const jsonCopy = (value) => {
+    try {
+        const text = JSON.stringify(value);
+        return text === undefined ? undefined : JSON.parse(text);
+    }
+    catch (_a) {
+        return undefined;
+    }
+};
 /**
  * Lift the reportable facts off a {@link BudgetExhaustedError}, or `undefined`
  * when it carries none.
@@ -283,6 +299,17 @@ export class ChatDriver extends EventTarget {
          * doesn't leak forward.
          */
         this.agentReleaseRequested = false;
+        /**
+         * 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.
+         */
+        this.suspendedActivations = new Map();
+        /** The last placeholder handed out for a restored caller; see `suspendedActivations`. */
+        this.restoredSuspensionSeq = 0;
         /**
          * Aborted by `dispose()` on driver teardown (e.g. an agent-config swap).
          * Threaded into every provider call as `ChatRequestOptions.signal`, so a
@@ -331,8 +358,8 @@ export class ChatDriver extends EventTarget {
          * 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.
@@ -495,7 +522,7 @@ export class ChatDriver extends EventTarget {
     cancel() {
         // The message is over, running or not: a handler holding `turnSignal` — including one in a
         // sub-agent, which inherits it — sees the stop. Ended even when idle, because an orchestrator
-        // stops between this driver's turns too (its re-classify, an agent install): a continuation
+        // stops between this driver's turns too (its classify, an agent install, a hand-off): a continuation
         // afterwards would otherwise carry the stopped message's denials and change rounds.
         this.messageController.abort(new DOMException('Cancelled by user', 'AbortError'));
         if (!this.busy)
@@ -790,21 +817,15 @@ export class ChatDriver extends EventTarget {
         this.aiServiceNoticesShown.add(code);
         return false;
     }
-    /**
-     * 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.
-     */
-    subAgentWallThisTurn(handingOff = false) {
-        return (this.providerRefusedThisTurn ||
-            this.budgetExhaustedThisTurn ||
-            (this.aiServiceErrorThisTurn && !handingOff));
+    /** Whether a sub-agent hit a wall this turn that stops this driver too. */
+    subAgentWallThisTurn() {
+        return (this.providerRefusedThisTurn || this.budgetExhaustedThisTurn || this.aiServiceErrorThisTurn);
     }
     /**
      * 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.
      */
     endTurnOnSubAgentWall() {
         var _a, _b, _c, _d, _e;
@@ -1066,6 +1087,7 @@ export class ChatDriver extends EventTarget {
         // does not spuriously advance the clock and prematurely drop its payloads.
         if (config.name !== this.activeAgentName) {
             this.currentActivation += 1;
+            this.resumeSuspendedActivation(config.name);
             this.resumeRestoredCondensePolicies(config.name);
         }
         this.systemPrompt = config.systemPrompt;
@@ -1300,6 +1322,111 @@ export class ChatDriver extends EventTarget {
     getAgentReleaseRequested() {
         return this.agentReleaseRequested;
     }
+    /**
+     * 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) {
+        this.checkHandOff = check;
+    }
+    /** The `handOff` the most recent call accepted, if any (GENC-1737). */
+    getHandOffRequest() {
+        return this.handOffRequested;
+    }
+    /** What `completeHandOff` handed back in the most recent call, if it was called. */
+    getHandOffCompletion() {
+        return this.handOffCompletion;
+    }
+    /**
+     * 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.
+     */
+    requestHandOff(request) {
+        var _a;
+        if (this.handOffRequested)
+            return { ok: false, reason: 'already-requested' };
+        if (this.agentReleaseRequested)
+            return { ok: false, reason: 'released' };
+        let data;
+        if ((request === null || request === void 0 ? void 0 : request.data) !== undefined) {
+            data = jsonCopy(request.data);
+            if (data === undefined)
+                return { ok: false, reason: 'not-json' };
+        }
+        const accepted = Object.assign(Object.assign({ to: request.to, message: String((_a = request.message) !== null && _a !== void 0 ? _a : '') }, (data !== undefined && { data })), (request.returnTo === false && { returnTo: false }));
+        const result = this.checkHandOff(accepted, this.activeAgentName);
+        if (result.ok)
+            this.handOffRequested = accepted;
+        return result;
+    }
+    /**
+     * 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.
+     */
+    closingCallNote() {
+        if (this.handOffRequested)
+            return handOffClosingNote(this.handOffRequested.to);
+        return this.handOffCompletion ? HAND_BACK_CLOSING_NOTE : undefined;
+    }
+    /**
+     * 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) {
+        if (agentName === this.activeAgentName) {
+            this.suspendedActivations.set(agentName, {
+                activation: this.currentActivation,
+                phaseEpoch: this.currentPhaseEpoch,
+            });
+        }
+    }
+    /**
+     * 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) {
+        for (const name of agentNames) {
+            this.restoredSuspensionSeq -= 1;
+            this.suspendedActivations.set(name, {
+                activation: this.restoredSuspensionSeq,
+                phaseEpoch: this.currentPhaseEpoch,
+            });
+        }
+    }
+    /** End every suspension: the hand-offs were unwound, so their callers' activations are over. */
+    endSuspendedActivations() {
+        this.suspendedActivations.clear();
+    }
+    /**
+     * 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.
+     */
+    resumeSuspendedActivation(agentName) {
+        const suspended = this.suspendedActivations.get(agentName);
+        if (suspended === undefined)
+            return;
+        this.suspendedActivations.delete(agentName);
+        for (const entry of this.condensePolicies.values()) {
+            if (entry.activation !== suspended.activation)
+                continue;
+            entry.activation = this.currentActivation;
+            if (entry.phaseEpoch >= suspended.phaseEpoch)
+                entry.phaseEpoch = this.currentPhaseEpoch;
+        }
+    }
+    /**
+     * The suspended activations, each with the phase epoch it was suspended at, for the `agentEnd`
+     * and `phaseEnd` checks and for persistence.
+     */
+    suspendedClocks() {
+        return new Map([...this.suspendedActivations.values()].map((s) => [s.activation, s.phaseEpoch]));
+    }
     /**
      * 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.
@@ -1462,7 +1589,7 @@ export class ChatDriver extends EventTarget {
      * @beta
      */
     getCondensePoliciesForPersistence(messages) {
-        return snapshotCondensePolicies(this.condensePolicies, this.condenseClocks(), messages);
+        return snapshotCondensePolicies(this.condensePolicies, this.condenseClocks(), messages, this.suspendedClocks());
     }
     /**
      * Re-register policies saved by {@link ChatDriver.getCondensePoliciesForPersistence} against
@@ -1513,9 +1640,18 @@ export class ChatDriver extends EventTarget {
                 continue;
             if (this.condensePolicies.has(entry.toolCallId))
                 continue;
-            this.condensePolicies.set(entry.toolCallId, rebaseRestoredCondensePolicy(entry, clocks));
+            const registered = rebaseRestoredCondensePolicy(entry, clocks);
+            this.condensePolicies.set(entry.toolCallId, registered);
             restored += 1;
-            if (entry.elapsed.activations === 0 && entry.agent !== this.activeAgentName) {
+            // A caller waiting in a hand-off owns it: live, but suspended until its hand-back, not left
+            // for the next activation, which is the target's (GENC-1737).
+            const suspended = entry.elapsed.activations === 0 && entry.agent !== undefined
+                ? this.suspendedActivations.get(entry.agent)
+                : undefined;
+            if (suspended !== undefined) {
+                registered.activation = suspended.activation;
+            }
+            else if (entry.elapsed.activations === 0 && entry.agent !== this.activeAgentName) {
                 this.condenseAwaitingReactivation.add(entry.toolCallId);
                 awaitingReactivation += 1;
             }
@@ -1895,6 +2031,8 @@ export class ChatDriver extends EventTarget {
             this.subAgentCompletion = undefined;
             this.subAgentFailure = undefined;
             this.agentReleaseRequested = false;
+            this.handOffRequested = undefined;
+            this.handOffCompletion = undefined;
             this.budgetExhaustedThisTurn = false;
             this.budgetWallDetail = undefined;
             this.budgetWallViaSubAgent = false;
@@ -1978,7 +2116,7 @@ export class ChatDriver extends EventTarget {
         let opened;
         let recorded = false;
         const capabilities = this.buildCapabilities();
-        return Object.assign(Object.assign(Object.assign(Object.assign({}, (capabilities && { capabilities })), { requestInteraction: (componentName, data, options) => this.requestInteraction(componentName, data, options, (interactionId) => {
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (capabilities && { capabilities })), { requestInteraction: (componentName, data, options) => this.requestInteraction(componentName, data, options, (interactionId) => {
                 opened = interactionId;
             }, undefined, 
             // What an interceptor did to an interaction is reported in THIS call's result
@@ -2023,16 +2161,42 @@ export class ChatDriver extends EventTarget {
                 // `agentEnd` payloads collapse and a re-run starts a fresh activation.
                 this.currentActivation += 1;
             }, releaseAgent: () => {
-                var _a;
+                var _a, _b;
+                if (this.handOffRequested) {
+                    logger.warn(`ChatDriver(${(_a = this.activeAgentName) !== null && _a !== void 0 ? _a : 'unknown'}): releaseAgent called after handOff — ignoring; the hand-off ends this agent's turn`);
+                    return;
+                }
                 if (this.agentReleaseRequested) {
-                    logger.warn(`ChatDriver(${(_a = this.activeAgentName) !== null && _a !== void 0 ? _a : 'unknown'}): releaseAgent called more than once — ignoring`);
+                    logger.warn(`ChatDriver(${(_b = this.activeAgentName) !== null && _b !== void 0 ? _b : 'unknown'}): releaseAgent called more than once — ignoring`);
                     return;
                 }
                 this.agentReleaseRequested = true;
                 // The stateful flow has wrapped up — advance the clock so its `agentEnd`
                 // payloads collapse and a re-run starts a fresh activation.
                 this.currentActivation += 1;
-            }, endPhase: () => {
+            } }), (this.checkHandOff && {
+            handOff: (request) => this.requestHandOff(request),
+            // A copy, so a handler cannot change what is saved.
+            handOffData: () => { var _a; return jsonCopy(this.agentSession.getHandOffData((_a = this.activeAgentName) !== null && _a !== void 0 ? _a : '')); },
+            completeHandOff: (completion) => {
+                var _a, _b, _c;
+                if (this.agentReleaseRequested || this.handOffRequested) {
+                    logger.warn(`ChatDriver(${(_a = this.activeAgentName) !== null && _a !== void 0 ? _a : 'unknown'}): completeHandOff called after a release or a hand-off — ignoring`);
+                    return;
+                }
+                let data;
+                if ((completion === null || completion === void 0 ? void 0 : completion.data) !== undefined) {
+                    data = jsonCopy(completion.data);
+                    if (data === undefined) {
+                        logger.warn(`ChatDriver(${(_b = this.activeAgentName) !== null && _b !== void 0 ? _b : 'unknown'}): completeHandOff data cannot be saved as JSON — handing back without it`);
+                    }
+                }
+                this.handOffCompletion = Object.assign({ message: String((_c = completion === null || completion === void 0 ? void 0 : completion.message) !== null && _c !== void 0 ? _c : '') }, (data !== undefined && { data }));
+                // The same release as `releaseAgent`, with a payload for the caller.
+                this.agentReleaseRequested = true;
+                this.currentActivation += 1;
+            },
+        })), { endPhase: () => {
                 // Advance the phase epoch so payloads registered with `{ on: phaseEnd }`
                 // during the phase that just ended collapse on the next provider call.
                 // Repeatable (no once-only guard, unlike releaseAgent/completeSubAgent):
@@ -2360,6 +2524,11 @@ export class ChatDriver extends EventTarget {
             this.beginTurn();
             this.subAgentCompletion = undefined;
             this.subAgentFailure = undefined;
+            // A release or a hand-off is what this call asks for, as for a `sendMessage`: the orchestrator
+            // acts on one after each call, so an earlier one must not be read again (GENC-1737).
+            this.agentReleaseRequested = false;
+            this.handOffRequested = undefined;
+            this.handOffCompletion = undefined;
             this.budgetExhaustedThisTurn = false;
             this.budgetWallDetail = undefined;
             this.budgetWallViaSubAgent = false;
@@ -2419,7 +2588,7 @@ export class ChatDriver extends EventTarget {
     // oxlint-disable-next-line complexity, max-lines-per-function
     runToolLoop(userInput, attachments, transientPrimer, tailNote) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
             if (!this.systemPrompt) {
                 logger.warn('ChatDriver: no systemPrompt set. The assistant will have no instructions — provide a systemPrompt via agents config or the foundation-ai-assistant property.');
             }
@@ -2449,7 +2618,11 @@ export class ChatDriver extends EventTarget {
             // Resolved per USER turn instead, which is where the docs say to choose it.
             let pinnedThinkingPolicy;
             let thinkingPolicyPinned = false;
-            while (iterations < this.maxToolIterations) {
+            // A `handOff` accepted in a batch gets its closing call even past the iteration cap.
+            // A closing call (see `closingCallNote`) is one model call, made even past the iteration cap;
+            // whatever path brings the loop back after it, a retry included, the turn ends there.
+            let closingCallMade = false;
+            while (iterations < this.maxToolIterations || (this.closingCallNote() && !closingCallMade)) {
                 iterations += 1;
                 // Monotonic across the driver's life — the age clock. Unlike `iterations`,
                 // it is NOT reset per turn and NOT decremented for folds, so `age` keeps
@@ -2465,6 +2638,9 @@ export class ChatDriver extends EventTarget {
                 const wall = this.endTurnOnSubAgentWall();
                 if (wall)
                     return wall;
+                if (closingCallMade)
+                    return turnDone();
+                const closing = this.closingCallNote();
                 const promptCtx = {
                     agentName: (_a = this.activeAgentName) !== null && _a !== void 0 ? _a : '',
                     history: this.history,
@@ -2533,7 +2709,8 @@ export class ChatDriver extends EventTarget {
                 // A continuation's tail note (GENC-1662) holds for the first model call — retries included,
                 // since they rewind `iterations` — and goes before the retry nudge, which must stay last.
                 const firstCallNote = tailNote && iterations === 1 ? `\n\n${tailNote}` : '';
-                const frameworkSystemSuffix = `${foldSuffix}${firstCallNote}${retryNudge}`;
+                const closingNote = closing ? `\n\n${closing}` : '';
+                const frameworkSystemSuffix = `${foldSuffix}${firstCallNote}${closingNote}${retryNudge}`;
                 // Normalize the primer at the same chokepoint as the driver's own history
                 // (GENC-1351 §5.7): a parent's `compacted-summary` message rides into a
                 // sub-agent's primer (`requestSubAgent` snapshots the parent's raw history),
@@ -2552,15 +2729,17 @@ export class ChatDriver extends EventTarget {
                 // <conversation_summary> user message (GENC-1351 §5.7) before any per-agent
                 // masking, so the raw display-only role can never reach a transport. Each
                 // step runs on a copy — stored history is untouched.
+                const suspended = this.suspendedClocks();
                 const condensedHistory = applyCondensation([...baseHistory], this.condensePolicies, {
                     modelCall: this.modelCallSeq,
                     turn: this.turnSeq,
                     // A call's activation has ended once a later activation is current — a
                     // swap or release/complete both advance the counter.
-                    activationEnded: (activation) => activation < this.currentActivation,
+                    // A caller waiting in a hand-off is suspended, not ended (GENC-1737).
+                    activationEnded: (activation) => activation < this.currentActivation && !suspended.has(activation),
                     // A call's phase has ended once the app declared a later phase epoch
-                    // current via `endPhase()`.
-                    phaseEnded: (phaseEpoch) => phaseEpoch < this.currentPhaseEpoch,
+                    // current via `endPhase()`; a waiting caller's, only by one before it waited.
+                    phaseEnded: (phaseEpoch, activation) => { var _a; return phaseEpoch < ((_a = suspended.get(activation)) !== null && _a !== void 0 ? _a : this.currentPhaseEpoch); },
                     batchCalls: this.condenseBatchCalls,
                 }, (detail) => recordMetaEvent(this.sessionKey, 'context.condensed', detail));
                 const normalizedHistory = normalizeForProvider(condensedHistory);
@@ -2607,7 +2786,11 @@ export class ChatDriver extends EventTarget {
                 // finish by calling a tool (their completion tool) so the turn can't end
                 // on a free-text answer; top-level agents stay 'auto'. (Transports no-op a
                 // force when no tools are advertised.)
-                const effectiveToolChoice = resolvedToolChoice !== null && resolvedToolChoice !== void 0 ? resolvedToolChoice : (this.isSubAgent ? 'required' : undefined);
+                // The tools stay advertised on a closing call: a request whose history holds tool calls must
+                // define them (Anthropic refuses one that doesn't).
+                const effectiveToolChoice = closing
+                    ? 'none'
+                    : (resolvedToolChoice !== null && resolvedToolChoice !== void 0 ? resolvedToolChoice : (this.isSubAgent ? 'required' : undefined));
                 const turnSnapshot = this.turnRecorder.record({
                     agentName: this.activeAgentName,
                     agentLabel: this.activeAgentLabel,
@@ -2712,6 +2895,8 @@ export class ChatDriver extends EventTarget {
                     });
                     return this.endTurnWithFailure(TURN_FAILURE_EXITS.contextGuard);
                 }
+                if (closing)
+                    closingCallMade = true;
                 let response;
                 try {
                     // oxlint-disable-next-line no-await-in-loop
@@ -2945,15 +3130,23 @@ export class ChatDriver extends EventTarget {
                 // fallback chain answered on a different model than the one we asked for.
                 if (response.model !== undefined)
                     turnSnapshot.model = response.model;
-                const isThinkingStep = response.content && ((_g = response.toolCalls) === null || _g === void 0 ? void 0 : _g.length);
-                const isEmptyResponse = !((_h = response.content) === null || _h === void 0 ? void 0 : _h.trim()) && !((_j = response.toolCalls) === null || _j === void 0 ? void 0 : _j.length);
+                if (closing) {
+                    // What it tried to call is not run, on a transport that ignores `toolChoice` too. Saying
+                    // nothing is fine, a refusal included: no failure that would hold the hand-off up.
+                    if ((_g = response.toolCalls) === null || _g === void 0 ? void 0 : _g.length)
+                        response = Object.assign(Object.assign({}, response), { toolCalls: undefined });
+                    if (!((_h = response.content) === null || _h === void 0 ? void 0 : _h.trim()))
+                        return turnDone();
+                }
+                const isThinkingStep = response.content && ((_j = response.toolCalls) === null || _j === void 0 ? void 0 : _j.length);
+                const isEmptyResponse = !((_k = response.content) === null || _k === void 0 ? void 0 : _k.trim()) && !((_l = response.toolCalls) === null || _l === void 0 ? void 0 : _l.length);
                 // A pre-output refusal (safety-classifier decline, e.g. Fable 5 `stop_reason: 'refusal'`)
                 // comes back with empty content, so it looks like a blank response — but it is deterministic:
                 // retrying re-sends the identical request and refuses again, burning up to
                 // MAX_EMPTY_RESPONSE_RETRIES turns on the most expensive models for the same outcome, ending
                 // in the misleading "blank response" message. Treat it as a terminal, non-retried failure with
                 // its own reason and message. (GENC-1461)
-                const isRefusal = ((_k = response.responseMeta) === null || _k === void 0 ? void 0 : _k.finishReason) === 'refusal';
+                const isRefusal = ((_m = response.responseMeta) === null || _m === void 0 ? void 0 : _m.finishReason) === 'refusal';
                 if (isEmptyResponse) {
                     emptyResponseAttempts += 1;
                     if (!isRefusal && emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
@@ -3024,16 +3217,12 @@ export class ChatDriver extends EventTarget {
                 emptyResponseAttempts = 0;
                 malformedAttempts = 0;
                 setupTransportAttempts = 0;
-                if (!((_l = response.toolCalls) === null || _l === void 0 ? void 0 : _l.length)) {
+                if (closing)
+                    return turnDone();
+                if (!((_o = response.toolCalls) === null || _o === void 0 ? void 0 : _o.length)) {
                     break;
                 }
-                const [toolCalls, systemCalls] = response.toolCalls.reduce((acc, tc) => {
-                    if (tc.name === REQUEST_CONTINUATION_TOOL)
-                        acc[1].push(tc);
-                    else
-                        acc[0].push(tc);
-                    return acc;
-                }, [[], []]);
+                const toolCalls = response.toolCalls;
                 const executedById = new Map();
                 const unknownToolIds = new Set();
                 // Subset of unknownToolIds that were stale (previously available) rather
@@ -3229,34 +3418,25 @@ export class ChatDriver extends EventTarget {
                 // Tag tool calls with fold UI metadata before appending results
                 const foldPath = this.folds.activeNames();
                 for (const tc of response.toolCalls) {
-                    if (tc.name === REQUEST_CONTINUATION_TOOL) {
+                    const r = executedById.get(tc.id);
+                    if (r) {
+                        // Persist only `toolCallId`/`content` on the tool result — the sub-agent
+                        // trace lives on the tool *call* (back-patched below from `executedById`),
+                        // which is what the UI's trace panel and `sumCosts` read. Appending the
+                        // trace here too would duplicate the entire child conversation in history
+                        // (and the exported debug log) for no reader.
                         this.appendToHistory({
                             role: 'tool',
                             content: '',
-                            toolResult: { toolCallId: tc.id, content: HANDOFF_TOOL_RESULT_PLACEHOLDER },
+                            toolResult: Object.assign({ toolCallId: r.toolCallId, content: r.content }, (r.attachments ? { attachments: r.attachments } : {})),
                         });
                     }
-                    else {
-                        const r = executedById.get(tc.id);
-                        if (r) {
-                            // Persist only `toolCallId`/`content` on the tool result — the sub-agent
-                            // trace lives on the tool *call* (back-patched below from `executedById`),
-                            // which is what the UI's trace panel and `sumCosts` read. Appending the
-                            // trace here too would duplicate the entire child conversation in history
-                            // (and the exported debug log) for no reader.
-                            this.appendToHistory({
-                                role: 'tool',
-                                content: '',
-                                toolResult: Object.assign({ toolCallId: r.toolCallId, content: r.content }, (r.attachments ? { attachments: r.attachments } : {})),
-                            });
-                        }
-                    }
                 }
                 // Back-patch foldEvent and foldPath onto the tool call message we just appended.
                 // The response was appended before execution — find it and annotate.
                 let tcMsgIdx = -1;
                 for (let i = this.history.length - 1; i >= 0; i -= 1) {
-                    if (this.history[i].role === 'assistant' && ((_m = this.history[i].toolCalls) === null || _m === void 0 ? void 0 : _m.length)) {
+                    if (this.history[i].role === 'assistant' && ((_p = this.history[i].toolCalls) === null || _p === void 0 ? void 0 : _p.length)) {
                         tcMsgIdx = i;
                         break;
                     }
@@ -3294,7 +3474,7 @@ export class ChatDriver extends EventTarget {
                     const unknownTools = [
                         ...new Set([
                             ...this.recentUnknownToolNames,
-                            ...((_o = response.toolCalls) !== null && _o !== void 0 ? _o : [])
+                            ...((_q = response.toolCalls) !== null && _q !== void 0 ? _q : [])
                                 .filter((tc) => unknownToolIds.has(tc.id))
                                 .map((tc) => tc.name),
                         ]),
@@ -3306,7 +3486,7 @@ export class ChatDriver extends EventTarget {
                     const staleTools = [
                         ...new Set([
                             ...this.recentStaleToolNames,
-                            ...((_p = response.toolCalls) !== null && _p !== void 0 ? _p : [])
+                            ...((_r = response.toolCalls) !== null && _r !== void 0 ? _r : [])
                                 .filter((tc) => staleToolIds.has(tc.id))
                                 .map((tc) => tc.name),
                         ]),
@@ -3324,29 +3504,22 @@ export class ChatDriver extends EventTarget {
                     return this.endTurnWithFailure(TURN_FAILURE_EXITS.unknownToolLimit);
                 }
                 // A wall a sub-agent hit in this batch wins over the exits below, which would report the turn
-                // as a handoff or the iteration cap, or lose the wall altogether. Three things win over it: a
-                // completion, which needs no further model call; a handoff past an AI-service wall; and a stop
-                // the user pressed while the batch ran, which ends the turn as "Stopped." as it would at the
-                // next model call.
-                const firstContinuation = systemCalls[0];
-                if (!this.subAgentCompletion && this.subAgentWallThisTurn(!!firstContinuation)) {
+                // as the iteration cap, or lose the wall altogether. Two things win over it: a completion,
+                // which needs no further model call; and a stop the user pressed while the batch ran, which
+                // ends the turn as "Stopped." as it would at the next model call.
+                if (!this.subAgentCompletion && this.subAgentWallThisTurn()) {
                     if (this.turnController.signal.aborted)
                         return this.completeAbortedTurn();
                     const wallAfterBatch = this.endTurnOnSubAgentWall();
                     if (wallAfterBatch)
                         return wallAfterBatch;
                 }
-                // A completion or a handoff went on past a child's AI-service refusal: say it once.
+                // A completion went on past a child's AI-service refusal: say it once.
                 if (this.aiServiceErrorThisTurn && this.aiServiceWall) {
                     this.noticeAIServiceRefusal(this.aiServiceWall.code);
                     this.flushAIServiceNotices();
                 }
-                if (firstContinuation) {
-                    const { summary, remaining_task: remainingTask } = firstContinuation.args;
-                    return { reason: 'agent-handoff', summary, remainingTask };
-                }
-                // Sub-agent early exit — checked here so the exit point mirrors the
-                // system-call pattern above. Set by completeSubAgent() in a tool handler.
+                // Sub-agent early exit, set by completeSubAgent() in a tool handler.
                 if (this.subAgentCompletion) {
                     return turnDone();
                 }

package/dist/esm/components/orchestrating-driver/hand-off.js

@@ -0,0 +1,59 @@
+const OUTCOME_KINDS = [
+    'completed',
+    'released',
+    'cleared',
+    'agent-removed',
+    'state-lost',
+];
+/**
+ * The tail note a hand-off's target runs its first call with (GENC-1737). The brief itself is in
+ * the transcript, as a message delegated by the caller, so the request already closes on it.
+ */
+export function handOffNote(caller) {
+    return `[Hand-off]: ${caller} handed this request to you. Its brief is the message above. Work on it as you would on a request from the user.`;
+}
+/**
+ * The tail note a caller resumes with when its hand-off ends (GENC-1737). It quotes nothing: a
+ * completed target's summary is in the transcript as a message it handed back, and a released
+ * target's last reply already is.
+ */
+export function handBackNote(frame, outcome) {
+    const how = {
+        completed: `${frame.target} has finished the request you handed it.`,
+        released: `${frame.target} has finished the request you handed it, without a summary. Its last reply is above.`,
+        cleared: 'The hand-off was cleared.',
+        'agent-removed': `${frame.target} is no longer available, so the request you handed it was not finished.`,
+        'state-lost': `The hand-off to ${frame.target} could not be resumed.`,
+    };
+    const summary = outcome.kind === 'completed' && outcome.message ? ' Its summary is the message above.' : '';
+    return `[Hand-back]: ${how[outcome.kind]}${summary} Carry on with the user from here.`;
+}
+/**
+ * A copy of `frame` for a hook or an event, so a host that changes it changes neither the stack
+ * nor what is saved. Frames are JSON.
+ */
+export const frameCopy = (frame) => structuredClone(frame);
+const isOutcome = (value) => {
+    const o = value;
+    return (!!o &&
+        typeof o === 'object' &&
+        OUTCOME_KINDS.includes(o.kind) &&
+        (o.message === undefined || typeof o.message === 'string'));
+};
+/** The saved frames that are frames, oldest first. The snapshot is parsed data. */
+export function parseHandOffFrames(saved) {
+    if (!Array.isArray(saved))
+        return [];
+    return saved.filter((value) => {
+        const f = value;
+        return (!!f &&
+            typeof f === 'object' &&
+            typeof f.id === 'string' &&
+            typeof f.caller === 'string' &&
+            typeof f.target === 'string' &&
+            typeof f.returnTo === 'boolean' &&
+            typeof f.message === 'string' &&
+            typeof f.startedAt === 'string' &&
+            (f.outcome === undefined || isOutcome(f.outcome)));
+    });
+}