@genesislcap/ai-assistant 15.84.2 → 15.85.0

package/dist/esm/main/main.js

@@ -204,6 +204,9 @@ avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiWave
  *
  * @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
  */
@@ -2059,7 +2062,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         return trailingInteractionRow(this.messages);
     }
     agentsChanged() {
-        var _a, _b, _c;
+        var _a, _b, _c, _d, _e;
         // Guard: driver doesn't exist yet during connectedCallback — createDriver/wireDriver handle that.
         if (!this.driver)
             return;
@@ -2105,6 +2108,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         if (registryDriver && registryDriver !== this.driver && registryDriver.isBusy())
             return;
         const history = (_c = (_b = (_a = this.driver).getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [];
+        // A hand-off cannot outlive its callers' machines, which the teardown disposes (GENC-1737).
+        void ((_e = (_d = this.driver).unwindHandOffs) === null || _e === void 0 ? void 0 : _e.call(_d, 'state-lost'));
         // Fire the active agent's `onDeactivate` so machines / per-agent state get
         // torn down before the replacement driver instantiates them again.
         this.teardownDriver(key);
@@ -2178,6 +2183,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             const orchestrator = new OrchestratingDriver(this.providerRegistry, agents, {
                 sessionKey: (_b = this.getStateKey()) !== null && _b !== void 0 ? _b : '',
                 maxHandoffs: agent.maxHandoffs,
+                maxHandOffDepth: agent.maxHandOffDepth,
                 classifierHistoryLength: agent.classifierHistoryLength,
                 classifierRetries: agent.classifierRetries,
                 maxToolIterations: agent.maxToolIterations,
@@ -2426,6 +2432,24 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         driver.addEventListener('pinned-changed', onPinnedChanged);
         driver.addEventListener('flow-owner-changed', onFlowOwnerChanged);
         cleanups.push(() => driver.removeEventListener('orchestrating-start', onOrchStart), () => driver.removeEventListener('orchestrating-stop', onOrchStop), () => driver.removeEventListener('agent-changed', onAgentChanged), () => driver.removeEventListener('pinned-changed', onPinnedChanged), () => driver.removeEventListener('flow-owner-changed', onFlowOwnerChanged));
+        // Hand-offs (GENC-1737): told to the host, and saved, since the stack is part of the session.
+        // Not one ended as `cleared`: a Clear drops the session, and a save could land after it. (A
+        // turn that ends an orphaned hand-off as `cleared` saves anyway.)
+        const onHandOff = (e) => {
+            var _a, _b;
+            const detail = e.detail;
+            if (((_a = detail === null || detail === void 0 ? void 0 : detail.outcome) === null || _a === void 0 ? void 0 : _a.kind) !== 'cleared')
+                (_b = this.persister()) === null || _b === void 0 ? void 0 : _b.scheduleSave();
+            this.dispatchEvent(new CustomEvent(e.type, { bubbles: true, composed: true, detail }));
+        };
+        for (const type of [
+            AiAssistantEvent.HandOffStarted,
+            AiAssistantEvent.HandOffReturned,
+            AiAssistantEvent.HandOffUnwound,
+        ]) {
+            driver.addEventListener(type, onHandOff);
+            cleanups.push(() => driver.removeEventListener(type, onHandOff));
+        }
         this.driverCleanup = () => {
             for (const fn of cleanups)
                 fn();
@@ -3496,7 +3520,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      */
     clearSession() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
             if ((_a = this.driver) === null || _a === void 0 ? void 0 : _a.isBusy())
                 return; // the menu only opens when idle; defensive
             const key = this.getStateKey();
@@ -3516,9 +3540,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // proved, and nothing else records it. Banking it is what stops the next turn rewriting the
             // project's row down to itself and losing the spend up to the clear (GENC-1475).
             const discarded = this.sessionUsage;
+            // Each hand-off ends as `cleared`, telling its waiting caller while it is still live (GENC-1737).
+            yield ((_g = (_f = this.driver) === null || _f === void 0 ? void 0 : _f.unwindHandOffs) === null || _g === void 0 ? void 0 : _g.call(_f, 'cleared'));
             if (this.driver)
                 this.teardownDriver(key);
-            (_f = this._sessionRef) === null || _f === void 0 ? void 0 : _f.actions.aiAssistant.resetSession();
+            (_h = this._sessionRef) === null || _h === void 0 ? void 0 : _h.actions.aiAssistant.resetSession();
             // Same reason as in `switchSession`: the compose box and its note were about the
             // conversation just discarded.
             this.resetDebugLogSubmitState();
@@ -3533,7 +3559,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // Restore-core is owned by the shared per-session persister (GENC-1351 §5.10):
             // it drops the snapshot + resets the carry-forward cache. Diagnostics is
             // append-only and handled separately below.
-            yield ((_g = this.persister()) === null || _g === void 0 ? void 0 : _g.clearRestoreCore());
+            yield ((_j = this.persister()) === null || _j === void 0 ? void 0 : _j.clearRestoreCore());
             this.confirmingClear = false;
             this.composerMenus.closeImmediate();
             this.logMeta('session.cleared', { agentName });
@@ -3542,8 +3568,8 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // forward-capture cursors and flush, so the just-logged `session.cleared`
             // event becomes the stream's roll boundary: exactly like a page reload, the
             // new conversation begins a fresh section within the same lifetime log (§5.8).
-            resetDiagnosticsCursorsFor((_h = this.getStateKey()) !== null && _h !== void 0 ? _h : '');
-            (_j = this.persister()) === null || _j === void 0 ? void 0 : _j.scheduleDiagnostics();
+            resetDiagnosticsCursorsFor((_k = this.getStateKey()) !== null && _k !== void 0 ? _k : '');
+            (_l = this.persister()) === null || _l === void 0 ? void 0 : _l.scheduleDiagnostics();
             this.dispatchEvent(new CustomEvent(AiAssistantEvent.SessionCleared, {
                 bubbles: true,
                 composed: true,

package/dist/esm/main/main.types.js

@@ -24,6 +24,12 @@ export const AiAssistantEvent = {
     SessionCleared: 'session-cleared',
     /** Header pressed in `popout-mode="expand"` (drag-to-popout hosts). `detail`: `ChatHeaderMouseDownDetail`. */
     ChatHeaderMouseDown: 'chat-header-mousedown',
+    /** An agent's hand-off started (GENC-1737). `detail`: `HandOffFrame`. */
+    HandOffStarted: 'handoff-started',
+    /** A hand-off ended and its caller is active again. `detail`: `HandOffFrame`, with `outcome`. */
+    HandOffReturned: 'handoff-returned',
+    /** A hand-off ended with no hand-back. `detail`: `HandOffFrame`, with `outcome`. */
+    HandOffUnwound: 'handoff-unwound',
 };
 /**
  * Registry of all available animations with their display metadata.

package/dist/esm/state/debug-event-log.js

@@ -266,7 +266,7 @@ export const DEBUG_LOG_README = [
     'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
     "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
     'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',
-    "kind:'event' type 'routing.decided' — how ONE turn was routed, emitted by the orchestrating driver before the agent runs (and again after every handoff). `decision` is why that agent was chosen: 'classified' (the classifier ran and picked one), 'no-match' (it ran and answered -1 — nothing listed covers the request), 'ballot-exhausted' (every eligible specialist had already handed off this turn, so the ballot was empty and NO call was made — distinct from 'no-match', where one ran and declined), 'pinned' (a user pin, an agent named for that one message by the send's `agent` option, or an active stateful flow owned the turn, so no call was made), 'single-candidate'/'no-specialists' (configuration left nothing to decide), 'provider-unavailable' (the registry default exposes no chat()), 'classifier-failed' (every attempt threw — `error` carries the last one). `to` names the agent and `fallback` says whether that agent is the fallback. `candidates` is what was actually ON THE BALLOT, in ballot order, so `index` — the classifier's own answer — indexes it directly; `excluded` names the specialists left off because they already handed off this turn, so the full eligible set is `candidates` ∪ `excluded`. `candidates` is absent on the four decisions that put nothing to a vote — 'pinned', 'single-candidate', 'no-specialists', 'ballot-exhausted'. It IS present on 'provider-unavailable', which is not an exception worth removing: the ballot was built there, it simply never got sent. `attempts` covers the retry ladder. `durationMs` is on EVERY routing.decided, and is the field to read when a decision looks wrong: the four decisions that can reach the fallback are told apart by the clock as much as by their name, because a fallback routing that resolved in tens of milliseconds made no network call at all whatever its `decision` says.",
+    "kind:'event' type 'routing.decided' — how ONE user turn was routed, emitted by the orchestrating driver before the agent runs. Only a user turn is routed: a hand-off names its target, so the agents a hand-off runs show up as agent.handoff events, not as more routing.decided. `decision` is why that agent was chosen: 'classified' (the classifier ran and picked one), 'no-match' (it ran and answered -1 — nothing listed covers the request), 'pinned' (a user pin, an agent named for that one message by the send's `agent` option, or an active stateful flow owned the turn, so no call was made), 'single-candidate'/'no-specialists' (configuration left nothing to decide), 'provider-unavailable' (the registry default exposes no chat()), 'classifier-failed' (every attempt threw — `error` carries the last one). `to` names the agent and `fallback` says whether that agent is the fallback. `candidates` is what was ON THE BALLOT — every classifier-eligible specialist — in ballot order, so `index` — the classifier's own answer — indexes it directly. `candidates` is absent on the three decisions that put nothing to a vote — 'pinned', 'single-candidate', 'no-specialists'. It IS present on 'provider-unavailable', which is not an exception worth removing: the ballot was built there, it simply never got sent. `attempts` covers the retry ladder. `durationMs` is on EVERY routing.decided, and is the field to read when a decision looks wrong: the decisions that can reach the fallback ('no-match', 'no-specialists', 'provider-unavailable', 'classifier-failed') are told apart by the clock as much as by their name, because a fallback routing that resolved in tens of milliseconds made no network call at all whatever its `decision` says.",
     "kind:'event' type 'routing.decided'.`usage` — what that classifier call cost, in the same four-bucket + costUsd shape as `sessionUsage`, plus `model`. Absent on the decisions that make no call (see 'pinned' and the configuration ones). THIS SPEND IS NOT IN `sessionUsage`: a classifier call never enters the transcript and `sessionUsage` is derived from the transcript, so classifier cost is missing from the session total by construction, not by accident. Sum these events to close that gap — it is the one component of a session's real spend that the totals cannot see.",
     'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it. For a turn that went to the wrong agent, read its routing.decided first — `decision` says whether anything was actually asked.',
 ];

package/dist/esm/state/persistence/session-persister.js

@@ -28,6 +28,38 @@ function savedCheckpoints(snapshot) {
         return snapshot.checkpoints;
     return snapshot.checkpoint ? [snapshot.checkpoint] : [];
 }
+/** The hand-offs in progress and their waiting callers' states, to save (GENC-1737). */
+function handOffsOf(driver) {
+    var _a, _b, _c, _d, _e, _f;
+    return {
+        waitingCallers: (_b = (_a = driver === null || driver === void 0 ? void 0 : driver.serializeWaitingCallers) === null || _a === void 0 ? void 0 : _a.call(driver)) !== null && _b !== void 0 ? _b : {},
+        handoffStack: (_d = (_c = driver === null || driver === void 0 ? void 0 : driver.getHandOffStack) === null || _c === void 0 ? void 0 : _c.call(driver)) !== null && _d !== void 0 ? _d : [],
+        handOffData: (_f = (_e = driver === null || driver === void 0 ? void 0 : driver.getHandOffData) === null || _e === void 0 ? void 0 : _e.call(driver)) !== null && _f !== void 0 ? _f : {},
+    };
+}
+/**
+ * Restore the saved hand-offs (GENC-1737), and settle what the restore re-activates and locks:
+ * - the top frame's target had finished, or has gone: its caller resumes, and the target's lock
+ *   goes. The hand-back happens either way; the note, which runs the caller's turn, comes only
+ *   when its turn would run on any resume;
+ * - a plain target's hand-off could not be resumed: it held the lock only for that hand-off, so
+ *   the lock goes, and nothing is re-activated.
+ */
+function restoreHandOffs(driver, snapshot, restored) {
+    var _a, _b, _c, _d, _e, _f;
+    // The data first: the stack drops it for a caller that cannot resume.
+    (_a = driver === null || driver === void 0 ? void 0 : driver.restoreHandOffData) === null || _a === void 0 ? void 0 : _a.call(driver, snapshot.handOffData, !!snapshot.interrupted);
+    const { resume, droppedLocks } = (_d = (_b = driver === null || driver === void 0 ? void 0 : driver.restoreHandOffStack) === null || _b === void 0 ? void 0 : _b.call(driver, snapshot.handoffStack, (_c = snapshot.agentSnapshots) !== null && _c !== void 0 ? _c : {}, !!snapshot.interrupted)) !== null && _d !== void 0 ? _d : {};
+    if (resume) {
+        const note = ((_e = driver === null || driver === void 0 ? void 0 : driver.canResumeRestoredFlow) === null || _e === void 0 ? void 0 : _e.call(driver, resume.agent)) ? resume.note : undefined;
+        return { flowOwner: resume.agent, resumeNote: note, savedLock: null, handBack: true };
+    }
+    const savedLock = (_f = snapshot.flowOwnerAgentName) !== null && _f !== void 0 ? _f : null;
+    if (savedLock && (droppedLocks === null || droppedLocks === void 0 ? void 0 : droppedLocks.includes(savedLock))) {
+        return { flowOwner: null, savedLock: null, handBack: false };
+    }
+    return Object.assign(Object.assign({}, restored), { savedLock, handBack: false });
+}
 /** Hand restored checkpoints back to the driver: none clears what it holds. */
 function restoreCheckpoints(driver, saved) {
     var _a;
@@ -347,7 +379,9 @@ export class SessionPersister {
             // `onActivate` ran), not via the host's `agents` — a host whose `agents` getter
             // mints fresh configs (the showcase) would otherwise hand us a never-activated
             // closure whose `serialize()` returns undefined.
-            const liveSnapshots = {};
+            // Callers waiting in a hand-off are live too, and resume from their state (GENC-1737).
+            const { waitingCallers, handoffStack, handOffData } = handOffsOf(driver);
+            const liveSnapshots = Object.assign({}, waitingCallers);
             const liveActive = driver === null || driver === void 0 ? void 0 : driver.getActiveAgent();
             if (liveActive === null || liveActive === void 0 ? void 0 : liveActive.serialize) {
                 try {
@@ -364,7 +398,7 @@ export class SessionPersister {
             // even though a flow is mid-stream. Writing `{}` would wipe the machine and
             // reset the flow on the next reload — so carry the flow-owner's last-known-good
             // image forward (GENC-1351 §6). Pure + unit-tested.
-            const { snapshots: agentSnapshots, cache } = reconcileAgentSnapshots(liveSnapshots, s.flowOwnerAgentName, this._cache);
+            const { snapshots: agentSnapshots, cache } = reconcileAgentSnapshots(liveSnapshots, s.flowOwnerAgentName, this._cache, handoffStack.map((f) => f.caller));
             this._cache = cache;
             const resumable = yield this.resolveResumable(liveActive, key, agentSnapshots, messages, s);
             // Report a broken episode at the first SAFE moment, which is what `resumable` decides.
@@ -422,6 +456,9 @@ export class SessionPersister {
                     condensePolicies: this.condensePoliciesToPersist(driver, frozenMessages, {
                         flowDropped: true,
                     }),
+                    // Kept so a restore can say so: a frozen session drops every agent's state, and with it
+                    // any hand-off's chance to resume (GENC-1737).
+                    handoffStack,
                 });
                 // Skip the write when the frozen boundary has not moved — a flow autosaves on every
                 // transcript change, and while it runs the last user message (and therefore the
@@ -496,6 +533,8 @@ export class SessionPersister {
                 condensePolicies: this.condensePoliciesToPersist(driver, messages),
                 autopilot: (_h = autopilotOf(driver)) === null || _h === void 0 ? void 0 : _h.getPersistedMode(),
                 checkpoints: checkpointsOf(driver),
+                handoffStack,
+                handOffData,
             });
             // Observability (GENC-1351): record what each autosave captured for stateful
             // agents — `agents: []` here means no machine snapshot was taken (the bug to
@@ -567,7 +606,7 @@ export class SessionPersister {
      */
     restore() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
             const { provider } = this.deps.getPersistence();
             if (!provider)
                 return undefined;
@@ -607,8 +646,8 @@ export class SessionPersister {
                 // whose owner this driver knows; resume it as well when the reload interrupted a turn and the
                 // owner has not opted out. Otherwise the restore is exactly what it was.
                 const savedOwner = snapshot.interrupted ? null : ((_a = snapshot.flowOwnerAgentName) !== null && _a !== void 0 ? _a : null);
-                const flowOwner = savedOwner && ((_b = driver === null || driver === void 0 ? void 0 : driver.canRestoreFlowOwner) === null || _b === void 0 ? void 0 : _b.call(driver, savedOwner)) ? savedOwner : null;
-                const resumeNote = flowOwner && ((_c = driver === null || driver === void 0 ? void 0 : driver.canResumeRestoredFlow) === null || _c === void 0 ? void 0 : _c.call(driver, flowOwner))
+                let flowOwner = savedOwner && ((_b = driver === null || driver === void 0 ? void 0 : driver.canRestoreFlowOwner) === null || _b === void 0 ? void 0 : _b.call(driver, savedOwner)) ? savedOwner : null;
+                let resumeNote = flowOwner && ((_c = driver === null || driver === void 0 ? void 0 : driver.canResumeRestoredFlow) === null || _c === void 0 ? void 0 : _c.call(driver, flowOwner))
                     ? buildResumeNote(trimmed, snapshot.messages.slice(bounded.length))
                     : undefined;
                 const ref = this.deps.getStore();
@@ -625,13 +664,18 @@ export class SessionPersister {
                 // matter when the agent re-activates. The flow-owner lock self-heals on
                 // activation (OrchestratingDriver.installAgent re-sets it).
                 driver === null || driver === void 0 ? void 0 : driver.primeRestoredAgentState(snapshot.agentSnapshots);
+                // Hand-offs (GENC-1737), before the condense policies, which have to know who is waiting. They
+                // can change who is re-activated and resumed, and the lock the session saved: see the helper.
+                const handOffs = restoreHandOffs(driver, snapshot, { flowOwner, resumeNote });
+                const { savedLock, handBack } = handOffs;
+                ({ flowOwner, resumeNote } = handOffs);
                 // The autopilot's mode waits for its flow to re-activate; restoring it starts nothing.
                 (_d = autopilotOf(driver)) === null || _d === void 0 ? void 0 : _d.restorePersistedMode(snapshot.autopilot);
                 // Long actions the reload cut wait for requests of their widget types (§4.12) — but only when
                 // their flow is re-activated above. A flow left behind (interrupted, or an owner this driver
                 // does not know) never ends, so nothing would clear its checkpoints, and the next request of
                 // such a widget type would take over the abandoned run's work.
-                restoreCheckpoints(driver, flowOwner ? savedCheckpoints(snapshot) : []);
+                restoreCheckpoints(driver, flowOwner && !handBack ? savedCheckpoints(snapshot) : []);
                 // Seed the carry-forward cache so the immediate post-restore autosave (fired
                 // by the history change below, before any agent re-activates) preserves the
                 // machine snapshot instead of overwriting it with an empty one (GENC-1351).
@@ -703,7 +747,9 @@ export class SessionPersister {
                     ];
                 }
                 const messages = [...trimmed, ...trailers];
-                ref.actions.aiAssistant.loadSession(toLoadSessionPayload(Object.assign(Object.assign({}, snapshot), { messages })));
+                ref.actions.aiAssistant.loadSession(toLoadSessionPayload(Object.assign(Object.assign({}, snapshot), { messages, 
+                    // A hand-back takes the lock from the target that finished; it sets its own.
+                    flowOwnerAgentName: savedLock })));
                 (_e = driver === null || driver === void 0 ? void 0 : driver.loadHistory) === null || _e === void 0 ? void 0 : _e.call(driver, [...messages]);
                 // Re-arm the condense policies that had not fired at save time (GENC-1632) — AFTER
                 // `loadHistory`, because the driver keeps only entries whose tool call is in the history it
@@ -754,11 +800,12 @@ export class SessionPersister {
                 // On the driver itself, not a narrowed orchestrator (GENC-1660): both members are on
                 // `AiDriver` and every decorator forwards them, so this reaches the routing whatever wraps it.
                 driver === null || driver === void 0 ? void 0 : driver.setPinnedAgent((_h = snapshot.pinnedAgentName) !== null && _h !== void 0 ? _h : null);
-                driver === null || driver === void 0 ? void 0 : driver.setFlowOwner((_j = snapshot.flowOwnerAgentName) !== null && _j !== void 0 ? _j : null);
+                driver === null || driver === void 0 ? void 0 : driver.setFlowOwner(savedLock);
                 if (flowOwner) {
                     this.logMeta('persistence.resume-planned', {
                         flowOwner,
                         resume: !!resumeNote,
+                        handBack: !!handBack,
                         dropped: snapshot.messages.length - bounded.length,
                     });
                 }

package/dist/esm/state/persistence/session-snapshot.js

@@ -13,8 +13,10 @@ export const PERSISTED_SESSION_VERSION = 1;
  * @internal
  */
 export function createPersistedSession(input) {
-    var _a, _b, _c;
-    return Object.assign(Object.assign(Object.assign({ version: PERSISTED_SESSION_VERSION, savedAt: new Date().toISOString(), host: input.host, sessionKey: input.sessionKey, messages: input.messages, activeAgentName: input.activeAgentName, pinnedAgentName: input.pinnedAgentName, flowOwnerAgentName: input.flowOwnerAgentName, sessionCostUsd: input.sessionCostUsd, contextTokens: input.contextTokens, contextLimit: input.contextLimit, activeModel: input.activeModel, activeProviderName: input.activeProviderName, agentSnapshots: (_a = input.agentSnapshots) !== null && _a !== void 0 ? _a : {} }, (((_b = input.condensePolicies) === null || _b === void 0 ? void 0 : _b.length) ? { condensePolicies: input.condensePolicies } : {})), (input.autopilot ? { autopilot: input.autopilot } : {})), (((_c = input.checkpoints) === null || _c === void 0 ? void 0 : _c.length) ? { checkpoints: input.checkpoints } : {}));
+    var _a, _b, _c, _d;
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ version: PERSISTED_SESSION_VERSION, savedAt: new Date().toISOString(), host: input.host, sessionKey: input.sessionKey, messages: input.messages, activeAgentName: input.activeAgentName, pinnedAgentName: input.pinnedAgentName, flowOwnerAgentName: input.flowOwnerAgentName, sessionCostUsd: input.sessionCostUsd, contextTokens: input.contextTokens, contextLimit: input.contextLimit, activeModel: input.activeModel, activeProviderName: input.activeProviderName, agentSnapshots: (_a = input.agentSnapshots) !== null && _a !== void 0 ? _a : {} }, (((_b = input.condensePolicies) === null || _b === void 0 ? void 0 : _b.length) ? { condensePolicies: input.condensePolicies } : {})), (input.autopilot ? { autopilot: input.autopilot } : {})), (((_c = input.checkpoints) === null || _c === void 0 ? void 0 : _c.length) ? { checkpoints: input.checkpoints } : {})), (((_d = input.handoffStack) === null || _d === void 0 ? void 0 : _d.length) ? { handoffStack: input.handoffStack } : {})), (input.handOffData && Object.keys(input.handOffData).length
+        ? { handOffData: input.handOffData }
+        : {}));
 }
 /**
  * Resolve the notice text + pre-fill prompt for an interrupted (non-resumable) flow
@@ -280,12 +282,16 @@ export function unknownAgentSnapshots(snapshot, knownAgentNames) {
  *
  * @internal
  */
-export function reconcileAgentSnapshots(live, flowOwnerName, lastKnownGood) {
+export function reconcileAgentSnapshots(live, flowOwnerName, lastKnownGood, 
+/** Callers waiting in a hand-off (GENC-1737): after a restore they are not live until it ends. */
+waitingCallers = []) {
     const snapshots = Object.assign({}, live);
-    if (flowOwnerName && snapshots[flowOwnerName] === undefined) {
-        const carried = lastKnownGood[flowOwnerName];
+    for (const name of [flowOwnerName, ...waitingCallers]) {
+        if (!name || snapshots[name] !== undefined)
+            continue;
+        const carried = lastKnownGood[name];
         if (carried !== undefined)
-            snapshots[flowOwnerName] = carried;
+            snapshots[name] = carried;
     }
     const cache = Object.keys(snapshots).length ? snapshots : lastKnownGood;
     return { snapshots, cache };

package/dist/esm/utils/condense-history.js

@@ -63,7 +63,13 @@ export function toolCallIdsIn(history) {
  *
  * Pure, no writes to the registry — safe on a save path that runs on every autosave.
  */
-export function snapshotCondensePolicies(policies, clocks, history) {
+export function snapshotCondensePolicies(policies, clocks, history, 
+/**
+ * Activations suspended in a hand-off (GENC-1737), each with the phase epoch it was suspended
+ * at: still live, so written as unended, and their phases counted only up to the suspension.
+ */
+suspended = new Map()) {
+    var _a;
     if (policies.size === 0)
         return [];
     const present = toolCallIdsIn(history);
@@ -76,8 +82,10 @@ export function snapshotCondensePolicies(policies, clocks, history) {
                 // the clamp only stops a malformed entry from being written out as "the future".
                 modelCalls: Math.max(0, clocks.modelCall - entry.iteration),
                 turns: Math.max(0, clocks.turn - entry.turn),
-                activations: Math.max(0, clocks.activation - entry.activation),
-                phases: Math.max(0, clocks.phaseEpoch - entry.phaseEpoch),
+                activations: suspended.has(entry.activation)
+                    ? 0
+                    : Math.max(0, clocks.activation - entry.activation),
+                phases: Math.max(0, ((_a = suspended.get(entry.activation)) !== null && _a !== void 0 ? _a : clocks.phaseEpoch) - entry.phaseEpoch),
             } }));
     }
     return out;
@@ -337,7 +345,8 @@ export function applyCondensation(history, policies, ctx, onCondensed) {
             // backstop, when the whole activation has ended, so a phase boundary that
             // is never declared still collapses at `agentEnd` rather than never.
             case 'phaseEnd':
-                return ctx.phaseEnded(entry.phaseEpoch) || ctx.activationEnded(entry.activation);
+                return (ctx.phaseEnded(entry.phaseEpoch, entry.activation) ||
+                    ctx.activationEnded(entry.activation));
             default:
                 return latestByKey.get(trig.by) !== toolCallId; // superseded by a newer call
         }

package/dist/react.cjs

@@ -53,7 +53,7 @@ const AiWavesIndicator = React.forwardRef(function AiWavesIndicator(props, ref)
 });
 
 const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(props, ref) {
-  const { onBudgetRefreshRequested, onChatHeaderMousedown, onSessionCleared, children, ...rest } = props;
+  const { onBudgetRefreshRequested, onChatHeaderMousedown, onSessionCleared, onHandoffStarted, onHandoffReturned, onHandoffUnwound, children, ...rest } = props;
   const _innerRef = React.useRef(null);
   const _onBudgetRefreshRequestedRef = React.useRef(onBudgetRefreshRequested);
   _onBudgetRefreshRequestedRef.current = onBudgetRefreshRequested;
@@ -61,6 +61,12 @@ const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(pr
   _onChatHeaderMousedownRef.current = onChatHeaderMousedown;
   const _onSessionClearedRef = React.useRef(onSessionCleared);
   _onSessionClearedRef.current = onSessionCleared;
+  const _onHandoffStartedRef = React.useRef(onHandoffStarted);
+  _onHandoffStartedRef.current = onHandoffStarted;
+  const _onHandoffReturnedRef = React.useRef(onHandoffReturned);
+  _onHandoffReturnedRef.current = onHandoffReturned;
+  const _onHandoffUnwoundRef = React.useRef(onHandoffUnwound);
+  _onHandoffUnwoundRef.current = onHandoffUnwound;
   React.useLayoutEffect(() => {
     const el = _innerRef.current;
     if (!el) return;
@@ -70,10 +76,19 @@ const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(pr
     el.addEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
     const _onSessionClearedFn = (e) => _onSessionClearedRef.current?.(e);
     el.addEventListener('session-cleared', _onSessionClearedFn);
+    const _onHandoffStartedFn = (e) => _onHandoffStartedRef.current?.(e);
+    el.addEventListener('handoff-started', _onHandoffStartedFn);
+    const _onHandoffReturnedFn = (e) => _onHandoffReturnedRef.current?.(e);
+    el.addEventListener('handoff-returned', _onHandoffReturnedFn);
+    const _onHandoffUnwoundFn = (e) => _onHandoffUnwoundRef.current?.(e);
+    el.addEventListener('handoff-unwound', _onHandoffUnwoundFn);
     return () => {
       el.removeEventListener('budget-refresh-requested', _onBudgetRefreshRequestedFn);
       el.removeEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
       el.removeEventListener('session-cleared', _onSessionClearedFn);
+      el.removeEventListener('handoff-started', _onHandoffStartedFn);
+      el.removeEventListener('handoff-returned', _onHandoffReturnedFn);
+      el.removeEventListener('handoff-unwound', _onHandoffUnwoundFn);
     };
   }, []);
   return React.createElement(customElements.getName(FoundationAiAssistantWC) ?? 'foundation-ai-assistant', { ...rest, ref: _mergeRefs(_innerRef, ref) }, children);

package/dist/react.mjs

@@ -51,7 +51,7 @@ export const AiWavesIndicator = React.forwardRef(function AiWavesIndicator(props
 });
 
 export const FoundationAiAssistant = React.forwardRef(function FoundationAiAssistant(props, ref) {
-  const { onBudgetRefreshRequested, onChatHeaderMousedown, onSessionCleared, children, ...rest } = props;
+  const { onBudgetRefreshRequested, onChatHeaderMousedown, onSessionCleared, onHandoffStarted, onHandoffReturned, onHandoffUnwound, children, ...rest } = props;
   const _innerRef = React.useRef(null);
   const _onBudgetRefreshRequestedRef = React.useRef(onBudgetRefreshRequested);
   _onBudgetRefreshRequestedRef.current = onBudgetRefreshRequested;
@@ -59,6 +59,12 @@ export const FoundationAiAssistant = React.forwardRef(function FoundationAiAssis
   _onChatHeaderMousedownRef.current = onChatHeaderMousedown;
   const _onSessionClearedRef = React.useRef(onSessionCleared);
   _onSessionClearedRef.current = onSessionCleared;
+  const _onHandoffStartedRef = React.useRef(onHandoffStarted);
+  _onHandoffStartedRef.current = onHandoffStarted;
+  const _onHandoffReturnedRef = React.useRef(onHandoffReturned);
+  _onHandoffReturnedRef.current = onHandoffReturned;
+  const _onHandoffUnwoundRef = React.useRef(onHandoffUnwound);
+  _onHandoffUnwoundRef.current = onHandoffUnwound;
   React.useLayoutEffect(() => {
     const el = _innerRef.current;
     if (!el) return;
@@ -68,10 +74,19 @@ export const FoundationAiAssistant = React.forwardRef(function FoundationAiAssis
     el.addEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
     const _onSessionClearedFn = (e) => _onSessionClearedRef.current?.(e);
     el.addEventListener('session-cleared', _onSessionClearedFn);
+    const _onHandoffStartedFn = (e) => _onHandoffStartedRef.current?.(e);
+    el.addEventListener('handoff-started', _onHandoffStartedFn);
+    const _onHandoffReturnedFn = (e) => _onHandoffReturnedRef.current?.(e);
+    el.addEventListener('handoff-returned', _onHandoffReturnedFn);
+    const _onHandoffUnwoundFn = (e) => _onHandoffUnwoundRef.current?.(e);
+    el.addEventListener('handoff-unwound', _onHandoffUnwoundFn);
     return () => {
       el.removeEventListener('budget-refresh-requested', _onBudgetRefreshRequestedFn);
       el.removeEventListener('chat-header-mousedown', _onChatHeaderMousedownFn);
       el.removeEventListener('session-cleared', _onSessionClearedFn);
+      el.removeEventListener('handoff-started', _onHandoffStartedFn);
+      el.removeEventListener('handoff-returned', _onHandoffReturnedFn);
+      el.removeEventListener('handoff-unwound', _onHandoffUnwoundFn);
     };
   }, []);
   return React.createElement(customElements.getName(FoundationAiAssistantWC) ?? 'foundation-ai-assistant', { ...rest, ref: _mergeRefs(_innerRef, ref) }, children);

package/docs/sub_agent.md

@@ -165,7 +165,7 @@ reason you got**, and the two groups are opposites:
 | `budget_exhausted` | **Terminal, and already handled for you.** The AI-spend budget is gone and the proxy is refusing every request. Retrying is another `402`, and "ask the user" is asking someone who cannot fix it. Return a terse error and let the turn end — the parent driver ends the turn as soon as this outcome comes back, so your handler will not be called again this turn. |
 | `provider_refused` | **Terminal, and already handled for you.** The vendor refused the account (a revoked key, a suspended organisation). Retrying gets the same refusal. Return a terse error: the parent driver ends the turn before its next model call, as for `budget_exhausted`. |
 | `context_exhausted` | **Terminal.** The sub-agent stopped because going on would overrun the context window. Re-invoking it with the same conversation stops it the same way, and your own next model call is likely to stop on the same guard. Return a terse error; a new conversation, or a smaller task, is the way on. |
-| `ai_service_error` | **Check `terminal`.** The app's AI service refused the sub-agent, and `code` says why (`MODEL_NOT_ALLOWED`, `NO_API_KEY`, …). When `terminal` is true, re-invoking the sub-agent with the same request gets the same refusal: return a terse error and do not re-invoke it. Only `VENDOR_UNREACHABLE` is not terminal, but a refusal from your own vendor that is about the service (for example `VENDOR_UNREACHABLE`) still ends this turn; retry on the user's next message, not in the handler. When the refusal is about the service itself and the sub-agent used your vendor, the parent turn ends on it, as for `budget_exhausted`, unless a completion or a handoff from the same batch goes on past it. The user is shown the sentence for a key, access, model or reachability refusal once per message, so your reply need not repeat it; a refusal about the request itself (`REQUEST_TOO_LARGE`, `BAD_REQUEST`, `FALLBACKS_NOT_SUPPORTED`) is left to you and the console. |
+| `ai_service_error` | **Check `terminal`.** The app's AI service refused the sub-agent, and `code` says why (`MODEL_NOT_ALLOWED`, `NO_API_KEY`, …). When `terminal` is true, re-invoking the sub-agent with the same request gets the same refusal: return a terse error and do not re-invoke it. Only `VENDOR_UNREACHABLE` is not terminal, but a refusal from your own vendor that is about the service (for example `VENDOR_UNREACHABLE`) still ends this turn; retry on the user's next message, not in the handler. When the refusal is about the service itself and the sub-agent used your vendor, the parent turn ends on it, as for `budget_exhausted`, unless a completion from the same batch goes on past it. The user is shown the sentence for a key, access, model or reachability refusal once per message, so your reply need not repeat it; a refusal about the request itself (`REQUEST_TOO_LARGE`, `BAD_REQUEST`, `FALLBACKS_NOT_SUPPORTED`) is left to you and the console. |
 
 ```ts
 const outcome = await context.requestSubAgent<ExtractedTrades>('trade_file_extractor', {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "15.84.2",
+  "version": "15.85.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/dts/index.d.ts",
@@ -92,31 +92,31 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-comms": "15.84.2",
-    "@genesislcap/foundation-testing": "15.84.2",
-    "@genesislcap/genx": "15.84.2",
-    "@genesislcap/ts-builder": "15.84.2",
-    "@genesislcap/uvu-playwright-builder": "15.84.2",
-    "@genesislcap/vite-builder": "15.84.2",
-    "@genesislcap/webpack-builder": "15.84.2",
+    "@genesislcap/foundation-comms": "15.85.0",
+    "@genesislcap/foundation-testing": "15.85.0",
+    "@genesislcap/genx": "15.85.0",
+    "@genesislcap/ts-builder": "15.85.0",
+    "@genesislcap/uvu-playwright-builder": "15.85.0",
+    "@genesislcap/vite-builder": "15.85.0",
+    "@genesislcap/webpack-builder": "15.85.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2",
     "esbuild": "0.25.12"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "15.84.2",
-    "@genesislcap/foundation-logger": "15.84.2",
-    "@genesislcap/foundation-notifications": "15.84.2",
-    "@genesislcap/foundation-redux": "15.84.2",
-    "@genesislcap/foundation-ui": "15.84.2",
-    "@genesislcap/foundation-utils": "15.84.2",
-    "@genesislcap/rapid-design-system": "15.84.2",
-    "@genesislcap/web-core": "15.84.2",
+    "@genesislcap/foundation-ai": "15.85.0",
+    "@genesislcap/foundation-logger": "15.85.0",
+    "@genesislcap/foundation-notifications": "15.85.0",
+    "@genesislcap/foundation-redux": "15.85.0",
+    "@genesislcap/foundation-ui": "15.85.0",
+    "@genesislcap/foundation-utils": "15.85.0",
+    "@genesislcap/rapid-design-system": "15.85.0",
+    "@genesislcap/web-core": "15.85.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
   "peerDependencies": {
-    "@genesislcap/foundation-comms": "^15.84.2"
+    "@genesislcap/foundation-comms": "^15.85.0"
   },
   "peerDependenciesMeta": {
     "@genesislcap/foundation-comms": {