@genesislcap/ai-assistant 15.58.2 → 15.59.0

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

@@ -6,6 +6,7 @@ import { clearSession, getMetaEvents, mergeMetaEvents, recordMetaEvent, recordTu
 import { generateSuggestions } from '../../suggestions/generate-suggestions';
 import { applyCondensation, condenseForPersistence, isValidCondenseTrigger, parsePersistedCondensePolicy, rebaseRestoredCondensePolicy, snapshotCondensePolicies, toolCallIdsIn, } from '../../utils/condense-history';
 import { estimatePreambleTokens, estimateRequestTokens, } from '../../utils/context-tokens';
+import { DEFAULT_DELEGATE_FRAMING, frameDelegatedContent, } from '../../utils/delegated-message';
 import { applyHistoryCap, buildCompactionSummaryPrompt, planCompaction, normalizeForProvider, } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { resolveTurnInput } from '../../utils/resolve-turn-input';
@@ -13,7 +14,7 @@ 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 { FoldController } from './fold-controller';
-import { InteractionController } from './interaction-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. */
@@ -101,6 +102,28 @@ const budgetDetailOf = (e) => {
         return undefined;
     return Object.assign(Object.assign({ budgetUsd: e.budgetUsd, spentUsd: e.spentUsd, vendorLabel: e.vendorLabel }, (vendor ? { vendor } : {})), (e.otherVendorAvailable != null ? { otherVendorAvailable: e.otherVendorAvailable } : {}));
 };
+/**
+ * Add the decisions an interceptor made on the user's behalf to a tool result (GENC-1660), so the
+ * working agent is told the truth about who chose: an object result gains `decidedOnUsersBehalf`,
+ * anything else a sentence per decision. Unchanged when there are none, which is every call that
+ * the person answered.
+ */
+function withDelegatedDecisions(result, content, decisions, hasImages) {
+    if (decisions.length === 0)
+        return content;
+    if (!hasImages && result !== null && typeof result === 'object' && !Array.isArray(result)) {
+        return JSON.stringify(Object.assign(Object.assign({}, result), { decidedOnUsersBehalf: decisions }));
+    }
+    return [content, ...decisions.map(describeDelegatedDecision)].join('\n\n');
+}
+/** One decision as a sentence for a text tool result, e.g. `Decided on the user's behalf: "Skip".` */
+function describeDelegatedDecision(decision) {
+    const choice = decision.choice !== undefined ? `: "${decision.choice}"` : '';
+    const shown = decision.shownToUser
+        ? ` What the user was shown, as your words: "${decision.shownToUser}"`
+        : ' Nothing was shown to the user about it.';
+    return `${decision.framing}${choice}.${shown}`;
+}
 /**
  * Where the tool calls still waiting for their results start: the last assistant message with a
  * call no later tool result answers. The history's length when every call has its answer.
@@ -272,6 +295,8 @@ export class ChatDriver extends EventTarget {
          * on that one was reset by every handoff inside a single message.
          */
         this.messageController = new AbortController();
+        /** Capabilities provided on this driver by decorators (GENC-1660). Only the root's are used. */
+        this.handlerCapabilities = new Map();
         /**
          * Caches validated provider lookups per name within the current agent. Cleared
          * by `installAgent` so each new agent's static/function-resolved names are
@@ -295,9 +320,17 @@ export class ChatDriver extends EventTarget {
          * 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.
          *
+         * **This driver raises the lifecycle events for every transition of the session**, whoever made
+         * it: itself, through {@link ChatDriver.activateAgent} or a release, or the orchestrator reaching
+         * through (GENC-1485). Before, only the orchestrator dispatched them, so a host on a bare
+         * `ChatDriver` never learned its flow owner.
+         *
          * @internal
          */
-        this.agentSession = new AgentSession({ sessionKey: () => this.sessionKey });
+        this.agentSession = new AgentSession({
+            sessionKey: () => this.sessionKey,
+            onTransition: (t) => this.dispatchAgentTransition(t),
+        });
         /**
          * A provider refusal was observed this turn, so the tool loop must not call the model again
          * (GENC-1506).
@@ -902,6 +935,55 @@ export class ChatDriver extends EventTarget {
             this.installAgent(config);
         });
     }
+    /**
+     * {@inheritDoc AiDriver.resumeRestoredFlow}
+     *
+     * This driver holds no list of agents, so it resumes only the `agent` it is handed (GENC-1660):
+     * whoever runs a bare `ChatDriver` knows which agent that is, and after a reload only the name
+     * survived. Without one it does nothing, as a driver without this member did before; given one
+     * that is not the restored flow owner, it refuses.
+     *
+     * For headless callers: the shipped host restores and resumes through `OrchestratingDriver`,
+     * and a bare `ChatDriver` does not answer `canRestoreFlowOwner`, so the host never plans a resume
+     * for one.
+     *
+     * The orchestrator does not delegate here, because it installs a decorated config of its own;
+     * this is the bare-driver path.
+     *
+     * @beta
+     */
+    resumeRestoredFlow(resumeNote, agent) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!agent)
+                return undefined;
+            // Only the flow owner's flow is restored, so only the flow owner may be resumed: a caller
+            // handing in some other config would otherwise install and run the wrong agent.
+            const owner = this.agentSession.getFlowOwner();
+            if (owner !== null && owner !== agent.name) {
+                logger.warn(`ChatDriver: resumeRestoredFlow was handed "${agent.name}", but the flow belongs to "${owner}" — not resuming.`);
+                return undefined;
+            }
+            yield this.activateAgent(agent);
+            if (!resumeNote || agent.resumeOnRestore === false)
+                return undefined;
+            return this.continueFromHistory(undefined, { tailNote: resumeNote });
+        });
+    }
+    /**
+     * Raise the host-facing lifecycle events for one session transition (GENC-1485), in the order
+     * the orchestrator raised them before it stopped doing so itself: the flow lock first, then the
+     * release, then the active agent.
+     */
+    dispatchAgentTransition(t) {
+        if (t.flowOwnerChangedTo !== undefined) {
+            this.dispatchEvent(new CustomEvent('flow-owner-changed', { detail: t.flowOwnerChangedTo }));
+        }
+        const active = this.agentSession.getActive();
+        if (!active && t.previousAgent) {
+            this.dispatchEvent(new CustomEvent('agent-released', { detail: t.previousAgent }));
+        }
+        this.dispatchEvent(new CustomEvent('agent-changed', { detail: active }));
+    }
     /**
      * {@inheritDoc AiDriver.getActiveAgent}
      *
@@ -937,6 +1019,14 @@ export class ChatDriver extends EventTarget {
     setFlowOwner(name) {
         this.agentSession.setFlowOwner(name);
     }
+    /**
+     * {@inheritDoc AiDriver.getFlowOwner}
+     *
+     * @beta
+     */
+    getFlowOwner() {
+        return this.agentSession.getFlowOwner();
+    }
     /**
      * Install `config` as the active agent **without firing lifecycle hooks**.
      *
@@ -1586,11 +1676,84 @@ export class ChatDriver extends EventTarget {
      *   and `presentation` to control whether the host wraps the widget in a chat
      *   bubble and/or shows the "Assistant" label.
      */
-    requestInteraction(componentName, data, options, onOpened) {
+    requestInteraction(componentName, data, options, onOpened, innerPath, onSettled) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.interactions.request(componentName, data, options, onOpened);
+            return this.interactions.request(componentName, data, options, onOpened, innerPath, onSettled);
         });
     }
+    /**
+     * {@inheritDoc AiDriver.addInteractionInterceptor}
+     *
+     * Consulted only on the root driver, where every interaction opens: a sub-agent's request
+     * travels up to its root, carrying its owner path, and is offered there once.
+     *
+     * @beta
+     */
+    addInteractionInterceptor(interceptor) {
+        return this.interactions.addInterceptor(interceptor);
+    }
+    /**
+     * {@inheritDoc AiDriver.presentInteraction}
+     *
+     * @beta
+     */
+    presentInteraction(componentName, data, options) {
+        return this.requestInteraction(componentName, data, options);
+    }
+    /**
+     * {@inheritDoc AiDriver.provideHandlerCapability}
+     *
+     * Throws if `name` is already provided: two decorators answering to one name would leave a
+     * handler unable to tell which it is talking to.
+     *
+     * @beta
+     */
+    provideHandlerCapability(name, factory) {
+        if (this.handlerCapabilities.has(name)) {
+            throw new Error(`provideHandlerCapability: "${name}" is already provided.`);
+        }
+        this.handlerCapabilities.set(name, factory);
+        return () => {
+            if (this.handlerCapabilities.get(name) === factory)
+                this.handlerCapabilities.delete(name);
+        };
+    }
+    /**
+     * The capabilities this driver's handlers see, and who they see them as: the root's factories,
+     * the root's flow owner, and the owner path from the root down to this driver's agent.
+     */
+    capabilityScope() {
+        const own = this.activeAgentName ? [this.activeAgentName] : [];
+        if (!this.capabilityParent) {
+            return {
+                factories: this.handlerCapabilities,
+                scope: { ownerPath: own, flowOwner: this.agentSession.getFlowOwner() },
+            };
+        }
+        const up = this.capabilityParent.capabilityScope();
+        return {
+            factories: up.factories,
+            scope: { ownerPath: [...up.scope.ownerPath, ...own], flowOwner: up.scope.flowOwner },
+        };
+    }
+    /** Build `context.capabilities` for one handler call, or `undefined` when nothing is provided. */
+    buildCapabilities() {
+        const { factories, scope } = this.capabilityScope();
+        if (factories.size === 0)
+            return undefined;
+        const capabilities = {};
+        for (const [name, factory] of factories) {
+            try {
+                const value = factory(scope);
+                if (value !== undefined)
+                    capabilities[name] = value;
+            }
+            catch (e) {
+                logger.warn(`ChatDriver: handler capability "${name}" threw — leaving it out:`, e);
+            }
+        }
+        return capabilities;
+    }
     /**
      * Record what came of an interaction, after it resolved, on its history message
      * (`interaction.outcome`): handed to its widget and persisted with the session, never sent to a
@@ -1662,10 +1825,17 @@ export class ChatDriver extends EventTarget {
         this.history = [...messages];
         this.notifyHistoryUpdated();
     }
-    sendMessage(userInput, attachments) {
+    sendMessage(userInput, attachments, options) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             if (this.busy || (!userInput.trim() && !(attachments === null || attachments === void 0 ? void 0 : attachments.length)))
                 return { reason: 'done' };
+            // Sent on the user's behalf (GENC-1660): stamped here, the only place that may, and framed for
+            // the model the same way on the first call (the input) as on every later one (history).
+            const delegate = options === null || options === void 0 ? void 0 : options.delegate;
+            const delegateFraming = delegate
+                ? ((_a = options === null || options === void 0 ? void 0 : options.delegateFraming) !== null && _a !== void 0 ? _a : DEFAULT_DELEGATE_FRAMING)
+                : undefined;
             this.busy = true;
             this.beginTurn();
             // A new user message. `continueFromHistory` keeps the scope, unless the message it would
@@ -1686,7 +1856,7 @@ export class ChatDriver extends EventTarget {
             this.aiServiceWall = undefined;
             this.aiServiceNoticesShown.clear();
             this.aiServiceNoticesQueued = [];
-            this.appendToHistory({ role: 'user', content: userInput, attachments });
+            this.appendToHistory(Object.assign({ role: 'user', content: userInput, attachments }, (delegate ? { delegate, delegateFraming } : {})));
             this.turnStartedAt = Date.now();
             recordMetaEvent(this.sessionKey, 'turn.start', {
                 phase: 'sendMessage',
@@ -1696,7 +1866,7 @@ export class ChatDriver extends EventTarget {
             // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
             let result = { reason: 'done' };
             try {
-                result = yield this.runToolLoop(userInput, attachments);
+                result = yield this.runToolLoop(delegate ? frameDelegatedContent(userInput, delegateFraming) : userInput, attachments);
                 return result;
             }
             catch (e) {
@@ -1753,14 +1923,20 @@ export class ChatDriver extends EventTarget {
      *   kept on a seven-way fan-out, reporting ~2.3x under the real cost, with the
      *   error growing as the fan-out widens.
      */
-    buildHandlerContext(activeToolCallId, traceCapture) {
+    buildHandlerContext(activeToolCallId, traceCapture, decisions) {
         var _a;
         // The interaction THIS call opened, if any: the only one its `recordInteractionOutcome` can
         // reach, so a tool can never write an outcome onto a widget another tool opened.
         let opened;
         let recorded = false;
-        return Object.assign(Object.assign({ requestInteraction: (componentName, data, options) => this.requestInteraction(componentName, data, options, (interactionId) => {
+        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) => {
                 opened = interactionId;
+            }, undefined, 
+            // An interaction an interceptor answered is reported in THIS call's result (GENC-1660).
+            (settled) => {
+                if (settled.decision)
+                    decisions === null || decisions === void 0 ? void 0 : decisions.push(settled.decision);
             }), recordInteractionOutcome: (outcome) => {
                 var _a;
                 if (!opened)
@@ -1776,7 +1952,7 @@ export class ChatDriver extends EventTarget {
             // The MESSAGE's scope: one object per `sendMessage`, kept across a handoff's continuation
             // and handed to a sub-agent, and aborted by `cancel()` as well as a dispose. Not the
             // per-request `turnController`, which every continuation replaces.
-            turnSignal: (_a = this.inheritedTurnSignal) !== null && _a !== void 0 ? _a : this.messageController.signal }, (this.subAgentsMap.size > 0 && {
+            turnSignal: (_a = this.inheritedTurnSignal) !== null && _a !== void 0 ? _a : this.messageController.signal }), (this.subAgentsMap.size > 0 && {
             requestSubAgent: (name, options) => this.invokeSubAgent(name, options).then(({ outcome, trace }) => {
                 // Append, never assign: see `traceCapture` on `buildHandlerContext`. Order
                 // is completion order, which is fine — every message carries its own
@@ -1907,11 +2083,14 @@ export class ChatDriver extends EventTarget {
             // parent's (ultimately the root's) history and resolve via the same
             // pending map the main UI is wired to. Recurses naturally for nested
             // sub-agents.
-            child.setHostInteractionRequester((componentName, data, opts, onOpened) => this.requestInteraction(componentName, data, opts, onOpened), 
+            child.setHostInteractionRequester((componentName, data, opts, onOpened, ownerPath, onSettled) => this.requestInteraction(componentName, data, opts, onOpened, ownerPath, onSettled), 
             // An outcome goes where its interaction went.
             (interactionId, outcome) => this.recordInteractionOutcome(interactionId, outcome));
             // The same route for a refusal the child absorbs, so the user sees it in the root transcript.
             child.hostAIServiceNotice = (code) => this.noticeAIServiceRefusal(code);
+            // And for the capabilities decorators provide (GENC-1660): the child's handlers see this
+            // driver's, scoped to this driver's flow, with the child's agent added to the owner path.
+            child.capabilityParent = this;
             const forwardTrace = (e) => {
                 this.dispatchEvent(new CustomEvent('sub-agent-history-updated', {
                     detail: { agentName: subConfig.name, history: e.detail },
@@ -2944,8 +3123,10 @@ export class ChatDriver extends EventTarget {
                         // `sumUsage` and `usageRows` would still agree with each other.
                         const traceCapture = { traces: [] };
                         const capturedTrace = () => traceCapture.traces.length ? traceCapture.traces.flat() : undefined;
+                        // Interactions this call awaited that an interceptor answered (GENC-1660).
+                        const decisions = [];
                         try {
-                            const result = yield handler(tc.args, this.buildHandlerContext(tc.id, traceCapture));
+                            const result = yield handler(tc.args, this.buildHandlerContext(tc.id, traceCapture, decisions));
                             // A handler that returns images gets them carried as real attachments instead of
                             // JSON-stringified into the text — the difference between a model reading
                             // `{"kind":"image","data":"iVBOR…"}` as prose and actually SEEING the render.
@@ -2953,13 +3134,13 @@ export class ChatDriver extends EventTarget {
                             // ordinary object return that happens to have an `attachments` key still
                             // stringifies exactly as before.
                             const resultImages = toolResultImages(result);
-                            const content = resultImages
+                            const content = withDelegatedDecisions(result, resultImages
                                 ? typeof result.content === 'string'
                                     ? result.content
                                     : JSON.stringify(Object.assign(Object.assign({}, result), { attachments: undefined }))
                                 : typeof result === 'string'
                                     ? result
-                                    : JSON.stringify(result);
+                                    : JSON.stringify(result), decisions, !!resultImages);
                             executedById.set(tc.id, Object.assign(Object.assign({ toolCallId: tc.id, content }, (resultImages ? { attachments: resultImages } : {})), { 
                                 // Concatenated when a handler invoked several children, so none is lost.
                                 // Stays `undefined` when nothing was captured — readers key off presence,

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

@@ -1,6 +1,8 @@
 import { recordMetaEvent } from '../../state/debug-event-log';
 import { createInteractionContext, } from '../../state/interaction-context';
 import { logger } from '../../utils/logger';
+/** The framing of a {@link DelegatedDecision} whose claimant declares none. */
+const DEFAULT_DECISION_FRAMING = "Decided on the user's behalf";
 /** What an interaction closed by its `signal` resolves with: unanswered, like a timeout. */
 const STOPPED = {
     status: 'timeout',
@@ -26,6 +28,101 @@ export class InteractionController {
          * one-interaction-at-a-time guard in `request`).
          */
         this.contexts = new Map();
+        /**
+         * Told about every interaction this controller opens (GENC-1660), in registration order. Only
+         * the root's are ever consulted: a sub-agent's request is opened by the root.
+         */
+        this.interceptors = [];
+    }
+    /** See `ChatDriver.addInteractionInterceptor`. Returns a remover. */
+    addInterceptor(interceptor) {
+        if (!interceptor.id || interceptor.id === 'user') {
+            throw new Error(`addInteractionInterceptor: an interceptor needs an id other than 'user' (got "${interceptor.id}").`);
+        }
+        this.interceptors.push(interceptor);
+        return () => {
+            const index = this.interceptors.indexOf(interceptor);
+            if (index >= 0)
+                this.interceptors.splice(index, 1);
+        };
+    }
+    /**
+     * Offer a new interaction to the interceptors and record who ends up holding it.
+     *
+     * **Outermost first.** A decorator installs its interceptor on the driver it wraps when it is
+     * constructed, and decorators are constructed innermost first, so registration order is
+     * innermost first and the walk runs it backwards. The first claim wins; later interceptors still
+     * see the interaction but their `hold` does nothing. A claim on a `userOnly` interaction is
+     * refused.
+     *
+     * Runs before the interaction's message is appended, so the widget's first render already knows
+     * its holder and nothing appears only to disappear.
+     */
+    offer(handle, opened) {
+        let claimant;
+        for (const interceptor of [...this.interceptors].reverse()) {
+            const hold = this.holdFor(handle, interceptor, () => claimant === interceptor);
+            let answer;
+            try {
+                answer = interceptor.onInteractionOpened(Object.assign(Object.assign({}, opened), { ctx: handle.context, hold }));
+            }
+            catch (e) {
+                logger.warn(`InteractionController: interceptor "${interceptor.id}" threw:`, e);
+                continue;
+            }
+            if (answer !== 'claim' || claimant)
+                continue;
+            if (opened.userOnly) {
+                recordMetaEvent(this.deps.sessionKey, 'interaction.claim-refused', {
+                    interactionId: opened.interactionId,
+                    claimant: interceptor.id,
+                    reason: 'userOnly',
+                });
+                continue;
+            }
+            claimant = interceptor;
+            handle.setHeldBy(interceptor.id);
+            const pending = this.pending.get(opened.interactionId);
+            if (pending)
+                pending.claimant = interceptor;
+        }
+        return handle.context.heldBy;
+    }
+    /** The {@link InteractionHold} for one interceptor: it applies only while that one is the claimant. */
+    holdFor(handle, interceptor, isClaimant) {
+        return {
+            set: (holder) => {
+                if (!isClaimant())
+                    return false;
+                const next = holder === 'user' ? 'user' : interceptor.id;
+                if (!handle.setHeldBy(next))
+                    return false;
+                recordMetaEvent(this.deps.sessionKey, 'interaction.held', {
+                    interactionId: handle.context.interactionId,
+                    heldBy: next,
+                    claimant: interceptor.id,
+                });
+                return true;
+            },
+            resolve: (result) => {
+                const { interactionId } = handle.context;
+                const pending = this.pending.get(interactionId);
+                if (!isClaimant() || !pending || handle.context.heldBy !== interceptor.id)
+                    return false;
+                pending.settledBy = interceptor.id;
+                this.resolve(interactionId, result);
+                return true;
+            },
+            recordDecision: (decision) => {
+                if (!isClaimant())
+                    return false;
+                const pending = this.pending.get(handle.context.interactionId);
+                if (!pending)
+                    return false;
+                pending.decision = { choice: decision.choice, shownToUser: decision.shownToUser };
+                return true;
+            },
+        };
     }
     /** See `ChatDriver.setHostInteractionRequester`. */
     setHostRequester(fn, recordOutcome) {
@@ -35,10 +132,15 @@ export class InteractionController {
     /**
      * See `ChatDriver.requestInteraction`. `onOpened` is told the id of the interaction this call
      * opens, wherever it opens it, so the caller can later record its outcome and no other's.
+     * `innerPath` is the owner path a sub-agent's request has gathered on its way up, and
+     * `onSettled` is told who answered, wherever it resolves (GENC-1660).
      */
-    request(componentName, data, options, onOpened) {
+    request(componentName, data, options, onOpened, innerPath = [], onSettled) {
+        // This driver's agent goes in front: the path reads outermost first, root to requester.
+        const agent = this.deps.activeAgentName();
+        const ownerPath = agent ? [agent, ...innerPath] : [...innerPath];
         if (this.hostRequester) {
-            return this.hostRequester(componentName, data, options, onOpened);
+            return this.hostRequester(componentName, data, options, onOpened, ownerPath, onSettled);
         }
         if (this.pending.size > 0) {
             throw new Error('requestInteraction: another user interaction is already in flight. ' +
@@ -54,6 +156,7 @@ export class InteractionController {
             this.pending.set(interactionId, {
                 resolve,
                 reject,
+                onSettled,
                 overrideId: chatInputDuringExecution ? interactionId : undefined,
                 // Resolve the interaction with a timeout result if the user does not
                 // respond in time. `resolve` runs the same teardown a normal resolution
@@ -68,11 +171,21 @@ export class InteractionController {
                     }, timeoutMs)
                     : undefined,
             });
-            recordMetaEvent(this.deps.sessionKey, 'interaction.requested', {
+            // Create the live context (GENC-1390) BEFORE the widget can mount, so the
+            // wrapper finds it when it builds the pending `interaction` descriptor, and
+            // offer it to the interceptors (GENC-1660) before it is appended, so the
+            // widget's first render already knows who holds it.
+            const handle = createInteractionContext(interactionId);
+            this.contexts.set(interactionId, handle);
+            const heldBy = this.offer(handle, {
                 interactionId,
-                component: componentName,
-                agent: this.deps.activeAgentName(),
+                componentName,
+                data,
+                ownerPath,
+                userOnly: (options === null || options === void 0 ? void 0 : options.userOnly) === true,
             });
+            recordMetaEvent(this.deps.sessionKey, 'interaction.requested', Object.assign({ interactionId, component: componentName, agent: this.deps.activeAgentName(), ownerPath,
+                heldBy }, ((options === null || options === void 0 ? void 0 : options.userOnly) ? { userOnly: true } : {})));
             // Signal the park boundary on the activity bus so turn-aware UI can tell
             // "actively computing" from "parked awaiting the user" — the latter is a
             // safe window for actions disallowed mid-request (e.g. switching provider
@@ -83,9 +196,6 @@ export class InteractionController {
                     detail: { interactionId, chatInputDuringExecution },
                 }));
             }
-            // Create the live context (GENC-1390) BEFORE the widget can mount, so the
-            // wrapper finds it when it builds the pending `interaction` descriptor.
-            this.contexts.set(interactionId, createInteractionContext(interactionId));
             this.deps.appendToHistory({
                 role: 'assistant',
                 content: '',
@@ -93,6 +203,14 @@ export class InteractionController {
                     componentName,
                     data }, (presentation ? { presentation } : {})),
             });
+            // A resolution that arrived while the interceptors were being asked — before there was a
+            // message to patch — is applied now that there is one.
+            const opened = this.pending.get(interactionId);
+            if (opened) {
+                opened.appended = true;
+                if (opened.early)
+                    this.resolve(interactionId, opened.early.result);
+            }
             // Closed by the caller's signal the way a timeout closes it: read-only, unanswered, and
             // through the same teardown. Wired after the widget is in history, so a signal that has
             // already aborted closes a widget that exists rather than one still to come.
@@ -117,17 +235,24 @@ export class InteractionController {
      * report twice, and the second report has nothing left to settle.
      */
     resolve(interactionId, result) {
-        var _a, _b;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
         const interaction = this.pending.get(interactionId);
         if (!interaction) {
             logger.warn(`Interaction with ID ${interactionId} not found.`);
             return;
         }
+        // Too early: an interceptor answered before the message was appended. Patching would find no
+        // message, and the append that follows would leave a widget pending forever, so hold it until
+        // the message is there. First answer wins, as it would have.
+        if (!interaction.appended) {
+            (_a = interaction.early) !== null && _a !== void 0 ? _a : (interaction.early = { result });
+            return;
+        }
         // Clear the timeout so a user resolution doesn't later fire a stale
         // timeout (and a timeout firing here clears its own already-fired handle).
         if (interaction.timeoutHandle)
             clearTimeout(interaction.timeoutHandle);
-        (_a = interaction.unlinkSignal) === null || _a === void 0 ? void 0 : _a.call(interaction);
+        (_b = interaction.unlinkSignal) === null || _b === void 0 ? void 0 : _b.call(interaction);
         // Harvest any out-of-band diagnostic entries the widget collated (e.g. from a server-side
         // ChatDriver) so the host's debug log + persisted diagnostics include them. Independent of the
         // message patched below — they describe the widget's own work, not this message.
@@ -138,9 +263,20 @@ export class InteractionController {
         const costUsd = typeof (result === null || result === void 0 ? void 0 : result.costUsd) === 'number' && Number.isFinite(result.costUsd) && result.costUsd > 0
             ? result.costUsd
             : undefined;
+        // Who answered (GENC-1660), by the route the answer took, not by who held it: the claimant
+        // only when it settled through its hold, the person otherwise — so a click on a widget a
+        // claimant holds is still the person's answer. A timeout or a stop is nobody's.
+        const unanswered = (result === null || result === void 0 ? void 0 : result.status) === 'timeout';
+        const answeredBy = unanswered ? undefined : ((_c = interaction.settledBy) !== null && _c !== void 0 ? _c : 'user');
+        const decision = answeredBy && answeredBy !== 'user'
+            ? Object.assign(Object.assign({ framing: (_e = (_d = interaction.claimant) === null || _d === void 0 ? void 0 : _d.decisionFraming) !== null && _e !== void 0 ? _e : DEFAULT_DECISION_FRAMING }, (((_f = interaction.decision) === null || _f === void 0 ? void 0 : _f.choice) !== undefined && {
+                choice: interaction.decision.choice,
+            })), (((_g = interaction.decision) === null || _g === void 0 ? void 0 : _g.shownToUser) !== undefined && {
+                shownToUser: interaction.decision.shownToUser,
+            })) : undefined;
         const patched = this.deps.patchInteractionMessage(interactionId, (message) => {
             var _a;
-            return (Object.assign(Object.assign(Object.assign({}, message), { interaction: Object.assign(Object.assign({}, message.interaction), { resolved: result }) }), (costUsd != null ? { externalCostUsd: ((_a = message.externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd } : {})));
+            return (Object.assign(Object.assign(Object.assign({}, message), { interaction: Object.assign(Object.assign(Object.assign({}, message.interaction), { resolved: result }), (answeredBy ? { answeredBy } : {})) }), (costUsd != null ? { externalCostUsd: ((_a = message.externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd } : {})));
         });
         if (patched)
             this.deps.notifyHistoryUpdated();
@@ -151,22 +287,40 @@ export class InteractionController {
         // the model already learns the outcome from this handler's return value.
         // Appended before `interaction.resolve` so it precedes the tool result and
         // any follow-up turn the resumed handler produces.
+        //
+        // When a claimant answered (GENC-1660), the echo is not something the user said: it is kept
+        // as a delegated, display-only assistant message, so it renders on the assistant's side and
+        // never as a user bubble the user did not write.
         if (typeof (result === null || result === void 0 ? void 0 : result.userMessage) === 'string' && result.userMessage.trim()) {
-            this.deps.appendToHistory({ role: 'synthetic-user', content: result.userMessage });
+            this.deps.appendToHistory(answeredBy && answeredBy !== 'user'
+                ? {
+                    role: 'assistant',
+                    content: result.userMessage,
+                    delegate: answeredBy,
+                    excludeFromProvider: true,
+                }
+                : { role: 'synthetic-user', content: result.userMessage });
         }
         if (interaction.overrideId) {
             this.deps.emit(new CustomEvent('interaction-stop', { detail: { interactionId } }));
         }
-        recordMetaEvent(this.deps.sessionKey, 'interaction.resolved', { interactionId });
+        recordMetaEvent(this.deps.sessionKey, 'interaction.resolved', Object.assign({ interactionId }, (answeredBy ? { answeredBy } : {})));
         // The park is ending and the loop is about to resume computing — paired
         // with `interaction-requested`. Fires for every resolution path (user
         // completion, timeout, cancellation), since all route through here.
         this.deps.activityBus.publish('interaction-resolved', undefined);
+        // Before the promise settles, so the record is in place when the handler carries on.
+        try {
+            (_h = interaction.onSettled) === null || _h === void 0 ? void 0 : _h.call(interaction, { answeredBy, decision });
+        }
+        catch (e) {
+            logger.warn('InteractionController: onSettled threw:', e);
+        }
         interaction.resolve(result);
         this.pending.delete(interactionId);
         // Tear down the live context on RESOLVE (not on element unmount) — this closes
         // any sockets/timers the widget parked on it via `onDispose`. (GENC-1390)
-        (_b = this.contexts.get(interactionId)) === null || _b === void 0 ? void 0 : _b.dispose();
+        (_j = this.contexts.get(interactionId)) === null || _j === void 0 ? void 0 : _j.dispose();
         this.contexts.delete(interactionId);
     }
     /**