@genesislcap/ai-assistant 15.60.0 → 15.62.0

package/dist/esm/components/chat-bubble/chat-bubble.template.js

@@ -14,6 +14,11 @@ const genesisIconTemplate = html `
 `;
 export const AiChatBubbleTemplate = () => {
     return html `
+    <!-- Mounted once, before it has anything to say, and only its text changes: a status region
+    inserted already holding its text is widely missed by screen readers. It announces the badge. -->
+    <span class="visually-hidden" role="status">
+      ${(x) => (x.needsUser && !x.dialogOpen ? x.needsInputLabel : '')}
+    </span>
     ${when((x) => !x.dialogOpen, html `
         <div
           class="bubble ${(x) => (x.hovered ? 'hovered' : '')}"
@@ -29,6 +34,14 @@ export const AiChatBubbleTemplate = () => {
             `)}
           ${when((x) => !x.imageSrc, genesisIconTemplate)}
           <div class="pulse-ring" part="pulse-ring"></div>
+          ${when((x) => x.needsUser, html `
+              <span
+                class="needs-you-badge"
+                part="needs-you-badge"
+                aria-hidden="true"
+                title="${(x) => x.needsInputLabel}"
+              ></span>
+            `)}
           <div class="tooltip" part="tooltip" style="${(x) => x.tooltipStyle}" ${ref('tooltipEl')}>
             ${(x) => x.title}
           </div>

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

@@ -6,9 +6,10 @@ 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 { DEFAULT_DELEGATE_FRAMING, delegatedFields, frameDelegatedContent, } from '../../utils/delegated-message';
 import { applyHistoryCap, buildCompactionSummaryPrompt, planCompaction, normalizeForProvider, } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
+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';
@@ -103,26 +104,42 @@ const budgetDetailOf = (e) => {
     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.
+ * Add what an interceptor did 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` and
+ * `editedOnUsersBehalf`, anything else a sentence per record. Each decision is `{ framing, choice?,
+ * shownToUser?, edits? }`; `edits` lists what the claimant changed in the widget before deciding,
+ * and is omitted when it changed nothing. Each edited record is `{ framing, edits }`: the person
+ * answered, but only after the claimant had changed the widget. Unchanged when there are none,
+ * which is every call the person answered on a widget nobody else touched.
  */
-function withDelegatedDecisions(result, content, decisions, hasImages) {
-    if (decisions.length === 0)
+function withDelegatedDecisions(result, content, done, hasImages) {
+    const { decided, edited } = done;
+    if (decided.length === 0 && edited.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 JSON.stringify(Object.assign(Object.assign(Object.assign({}, result), (decided.length ? { decidedOnUsersBehalf: decided } : {})), (edited.length ? { editedOnUsersBehalf: edited } : {})));
     }
-    return [content, ...decisions.map(describeDelegatedDecision)].join('\n\n');
+    return [
+        content,
+        ...decided.map(describeDelegatedDecision),
+        ...edited.map(describeDelegatedEdits),
+    ].join('\n\n');
+}
+/** Edits the person then confirmed, as a sentence for a text tool result. */
+function describeDelegatedEdits(edited) {
+    return `${edited.framing}: ${edited.edits.map((edit) => `"${edit}"`).join(', ')}.`;
 }
 /** One decision as a sentence for a text tool result, e.g. `Decided on the user's behalf: "Skip".` */
 function describeDelegatedDecision(decision) {
+    var _a;
     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}`;
+    const edited = ((_a = decision.edits) === null || _a === void 0 ? void 0 : _a.length)
+        ? ` Before deciding it changed the widget: ${decision.edits.map((edit) => `"${edit}"`).join(', ')}.`
+        : '';
+    return `${decision.framing}${choice}.${shown}${edited}`;
 }
 /**
  * Where the tool calls still waiting for their results start: the last assistant message with a
@@ -975,6 +992,9 @@ export class ChatDriver extends EventTarget {
      * release, then the active agent.
      */
     dispatchAgentTransition(t) {
+        // The flow ended, so a checkpoint nothing took over has nothing left to resume (§4.12).
+        if (t.flowOwnerChangedTo === null)
+            this.interactions.clearCheckpoint('flow-ended');
         if (t.flowOwnerChangedTo !== undefined) {
             this.dispatchEvent(new CustomEvent('flow-owner-changed', { detail: t.flowOwnerChangedTo }));
         }
@@ -1635,6 +1655,10 @@ export class ChatDriver extends EventTarget {
                     // re-derived from the transcript would otherwise fall by exactly this much
                     // on every compaction. Summarising a turn does not refund what it cost.
                     rolledUpUsage: sumUsage(toCompact),
+                    // The user's own words survive word for word, beside the paraphrase (GENC-1660, C2): this
+                    // range's own only. An earlier summary's kept messages are not carried forward; the
+                    // summariser read them with it and folded them into this paraphrase.
+                    preservedUserMessages: freshUserMessages(toCompact),
                 },
             };
             this.loadHistory([summaryMessage, ...tail]);
@@ -1806,6 +1830,14 @@ export class ChatDriver extends EventTarget {
     getInteractionContext(interactionId) {
         return this.interactions.context(interactionId);
     }
+    /** {@inheritDoc AiDriver.getInteractionCheckpoint} */
+    getInteractionCheckpoint() {
+        return this.interactions.getCheckpoint();
+    }
+    /** {@inheritDoc AiDriver.restoreInteractionCheckpoint} */
+    restoreInteractionCheckpoint(saved) {
+        this.interactions.restoreCheckpoint(saved);
+    }
     /**
      * Replace the history message owning `interactionId`. `false` when it is no longer in history.
      * Does not announce the change — the interaction paths differ on whether they should.
@@ -1856,7 +1888,7 @@ export class ChatDriver extends EventTarget {
             this.aiServiceWall = undefined;
             this.aiServiceNoticesShown.clear();
             this.aiServiceNoticesQueued = [];
-            this.appendToHistory(Object.assign({ role: 'user', content: userInput, attachments }, (delegate ? { delegate, delegateFraming } : {})));
+            this.appendToHistory(Object.assign({ role: 'user', content: userInput, attachments }, delegatedFields(options)));
             this.turnStartedAt = Date.now();
             recordMetaEvent(this.sessionKey, 'turn.start', {
                 phase: 'sendMessage',
@@ -1923,7 +1955,7 @@ 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, decisions) {
+    buildHandlerContext(activeToolCallId, traceCapture, done) {
         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.
@@ -1933,10 +1965,13 @@ export class ChatDriver extends EventTarget {
         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).
+            // What an interceptor did to an interaction is reported in THIS call's result
+            // (GENC-1660): its answer, or the edits it made before the person answered.
             (settled) => {
                 if (settled.decision)
-                    decisions === null || decisions === void 0 ? void 0 : decisions.push(settled.decision);
+                    done === null || done === void 0 ? void 0 : done.decided.push(settled.decision);
+                if (settled.edited)
+                    done === null || done === void 0 ? void 0 : done.edited.push(settled.edited);
             }), recordInteractionOutcome: (outcome) => {
                 var _a;
                 if (!opened)
@@ -3123,10 +3158,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 = [];
+                        // What an interceptor did to the interactions this call awaited (GENC-1660).
+                        const done = { decided: [], edited: [] };
                         try {
-                            const result = yield handler(tc.args, this.buildHandlerContext(tc.id, traceCapture, decisions));
+                            const result = yield handler(tc.args, this.buildHandlerContext(tc.id, traceCapture, done));
                             // 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.
@@ -3140,7 +3175,7 @@ export class ChatDriver extends EventTarget {
                                     : JSON.stringify(Object.assign(Object.assign({}, result), { attachments: undefined }))
                                 : typeof result === 'string'
                                     ? result
-                                    : JSON.stringify(result), decisions, !!resultImages);
+                                    : JSON.stringify(result), done, !!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,8 +1,69 @@
+import { __awaiter } from "tslib";
 import { recordMetaEvent } from '../../state/debug-event-log';
 import { createInteractionContext, } from '../../state/interaction-context';
+import { getInteractionRegistration } from '../../state/interaction-registry';
+import { bindStepRecorder } from '../../state/run-steps';
 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";
+/** The framing of {@link DelegatedEdits} whose claimant declares none. */
+const DEFAULT_EDIT_FRAMING = "Changed on the user's behalf before the user answered; the user then finished it, confirming the changes";
+/** Why a `hold.invoke` was refused while another of the claimant's actions was still running. */
+const BUSY = {
+    error: 'busy',
+    message: 'Another action on this interaction is still running, so this one was not run. Once that one has returned, try this again if it still applies.',
+};
+/** Whether `value` is a promise, or anything else awaiting it would wait on. */
+const isThenable = (value) => value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof value.then === 'function';
+/** One editing action a claimant ran, as it is recorded on the interaction (GENC-1660). */
+function editOf(by, action, choice, args) {
+    const copy = jsonCopy(args);
+    return Object.assign({ by, action, choice }, (copy !== undefined && { args: copy }));
+}
+/**
+ * A JSON copy of an action's arguments, so the record cannot change under a widget that mutates
+ * what it was given. `undefined` when there are none (nothing, an empty object, list or string),
+ * or when they cannot be copied.
+ */
+function jsonCopy(args) {
+    if (args === undefined || args === null)
+        return undefined;
+    try {
+        const copy = JSON.parse(JSON.stringify(args));
+        const empty = copy === '' ||
+            (Array.isArray(copy) && copy.length === 0) ||
+            (copy !== null && typeof copy === 'object' && Object.keys(copy).length === 0);
+        return empty ? undefined : copy;
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+/**
+ * What the requester is told a claimant did (GENC-1660): its decision, when it answered; or, when
+ * the person answered one it had changed first, those edits — the answer is theirs, but the agent
+ * still learns the widget was changed on their behalf before they answered.
+ */
+function doneOnUsersBehalf(interaction, answeredBy) {
+    var _a, _b, _c, _d, _e;
+    const edits = ((_a = interaction.edits) === null || _a === void 0 ? void 0 : _a.length)
+        ? interaction.edits.map((edit) => edit.choice)
+        : undefined;
+    if (answeredBy && answeredBy !== 'user') {
+        const recorded = interaction.decision;
+        return {
+            decision: Object.assign(Object.assign(Object.assign({ framing: (_c = (_b = interaction.claimant) === null || _b === void 0 ? void 0 : _b.decisionFraming) !== null && _c !== void 0 ? _c : DEFAULT_DECISION_FRAMING }, (edits && { edits })), ((recorded === null || recorded === void 0 ? void 0 : recorded.choice) !== undefined && { choice: recorded.choice })), ((recorded === null || recorded === void 0 ? void 0 : recorded.shownToUser) !== undefined && { shownToUser: recorded.shownToUser })),
+        };
+    }
+    if (answeredBy === 'user' && edits) {
+        return {
+            edited: { framing: (_e = (_d = interaction.claimant) === null || _d === void 0 ? void 0 : _d.editFraming) !== null && _e !== void 0 ? _e : DEFAULT_EDIT_FRAMING, edits },
+        };
+    }
+    return {};
+}
 /** What an interaction closed by its `signal` resolves with: unanswered, like a timeout. */
 const STOPPED = {
     status: 'timeout',
@@ -34,6 +95,70 @@ export class InteractionController {
          */
         this.interceptors = [];
     }
+    /** See `ChatDriver.getInteractionCheckpoint`. */
+    getCheckpoint() {
+        const cp = this.checkpoint;
+        return cp ? { componentName: cp.componentName, value: cp.value } : undefined;
+    }
+    /** See `ChatDriver.restoreInteractionCheckpoint`. Restored means cut: its interaction is gone. */
+    restoreCheckpoint(saved) {
+        this.checkpoint = saved
+            ? { componentName: saved.componentName, value: saved.value, cut: true }
+            : undefined;
+    }
+    /** Drop the checkpoint, used or not, when its flow ends. */
+    clearCheckpoint(why) {
+        const cp = this.checkpoint;
+        if (!cp)
+            return;
+        this.checkpoint = undefined;
+        recordMetaEvent(this.deps.sessionKey, 'interaction.checkpoint', Object.assign({ action: 'cleared', component: cp.componentName, why }, (cp.interactionId ? { interactionId: cp.interactionId } : {})));
+    }
+    /**
+     * Hand a cut checkpoint to a new request of the same widget type, if its registration's
+     * `sameWork` agrees. Only the first such request is asked: a refused checkpoint is dropped, and
+     * the work starts fresh as it would have without one.
+     */
+    takeOverCheckpoint(componentName, data, interactionId) {
+        var _a;
+        const cut = this.checkpoint;
+        if (!(cut === null || cut === void 0 ? void 0 : cut.cut) || cut.componentName !== componentName)
+            return undefined;
+        this.checkpoint = undefined;
+        const sameWork = (_a = getInteractionRegistration(componentName)) === null || _a === void 0 ? void 0 : _a.sameWork;
+        let agrees = true;
+        if (sameWork) {
+            try {
+                agrees = sameWork(cut.value, data);
+            }
+            catch (e) {
+                logger.warn(`InteractionController: "${componentName}" sameWork threw; starting fresh:`, e);
+                agrees = false;
+            }
+        }
+        recordMetaEvent(this.deps.sessionKey, 'interaction.checkpoint', Object.assign({ action: agrees ? 'resumed' : 'refused', component: componentName, interactionId }, (agrees ? {} : { saved: cut.value })));
+        if (!agrees)
+            return undefined;
+        this.checkpoint = { componentName, value: cut.value, interactionId };
+        return cut.value;
+    }
+    /** A controller's `ctx.saveCheckpoint`: kept as JSON, the form it is persisted in. */
+    saveCheckpoint(interactionId, componentName, value) {
+        var _a;
+        if (!this.pending.has(interactionId))
+            return;
+        let copy;
+        try {
+            copy = JSON.parse((_a = JSON.stringify(value)) !== null && _a !== void 0 ? _a : 'null');
+        }
+        catch (e) {
+            logger.warn(`InteractionController: a "${componentName}" checkpoint is not storable as JSON:`, e);
+            return;
+        }
+        this.checkpoint = { componentName, value: copy, interactionId };
+        // A finished step changes no message, so autosave would not see it: ask for a save.
+        this.deps.emit(new CustomEvent('checkpoint-saved', { detail: { interactionId } }));
+    }
     /** See `ChatDriver.addInteractionInterceptor`. Returns a remover. */
     addInterceptor(interceptor) {
         if (!interceptor.id || interceptor.id === 'user') {
@@ -92,11 +217,21 @@ export class InteractionController {
     holdFor(handle, interceptor, isClaimant) {
         return {
             set: (holder) => {
+                var _a;
                 if (!isClaimant())
                     return false;
                 const next = holder === 'user' ? 'user' : interceptor.id;
                 if (!handle.setHeldBy(next))
                     return false;
+                // With the person now, so whatever settles it next is their answer — even if an editing
+                // action the claimant started is still unwinding. A finishing action still in flight keeps
+                // its credit: it is the claimant's choice, already made, and a pause must not pass it off as
+                // the person's. If that run does not settle it after all, its own restore clears the credit.
+                if (next === 'user') {
+                    const pending = this.pending.get(handle.context.interactionId);
+                    if (pending && !((_a = pending.running) === null || _a === void 0 ? void 0 : _a.finishes))
+                        pending.settledBy = undefined;
+                }
                 recordMetaEvent(this.deps.sessionKey, 'interaction.held', {
                     interactionId: handle.context.interactionId,
                     heldBy: next,
@@ -122,8 +257,114 @@ export class InteractionController {
                 pending.decision = { choice: decision.choice, shownToUser: decision.shownToUser };
                 return true;
             },
+            invoke: (action, args, options) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c;
+                const { interactionId } = handle.context;
+                const pending = this.pending.get(interactionId);
+                if (!isClaimant() || !pending || handle.context.heldBy !== interceptor.id) {
+                    return {
+                        ok: false,
+                        error: 'not-held',
+                        message: pending
+                            ? 'This interaction is with the person now, so it cannot be acted on.'
+                            : 'This interaction has already ended.',
+                    };
+                }
+                const { surface } = handle;
+                if (!surface) {
+                    return { ok: false, error: 'no-surface', message: 'Nothing has been exposed here yet.' };
+                }
+                // One action at a time: the claimant's calls may run in parallel, and a second run would
+                // overwrite the first's record and attribution while it is still in flight. Refused, with
+                // nothing run, so the caller can try again once the first has returned.
+                if (pending.running) {
+                    return Object.assign(Object.assign({ ok: false }, BUSY), { actions: surface.actions() });
+                }
+                const prepared = surface.prepare(action, args);
+                if ('error' in prepared) {
+                    return Object.assign(Object.assign({ ok: false }, prepared), { actions: surface.actions() });
+                }
+                // What a finishing run records before it runs, put back unless the run settles it: one that
+                // throws, or one that leaves it open, must not leave the next settle credited to it. An
+                // editing action records neither, so it has nothing to put back.
+                const previous = { decision: pending.decision, settledBy: pending.settledBy };
+                const restore = () => {
+                    if (!prepared.finishes)
+                        return;
+                    pending.decision = previous.decision;
+                    // Handed to the person meanwhile: whatever settles it next is theirs (see `set`).
+                    pending.settledBy =
+                        handle.context.heldBy === interceptor.id ? previous.settledBy : undefined;
+                };
+                // Recorded BEFORE running: a finishing action resolves inside `run`, and the record and the
+                // attribution have to be in place when it does. A finishing action is the claimant's
+                // answer, as `hold.resolve` is; handing the interaction back clears it. An editing action
+                // is never an answer, so a settle while one is in flight is not credited to it.
+                if (prepared.finishes) {
+                    pending.decision = { choice: prepared.choice, shownToUser: options === null || options === void 0 ? void 0 : options.note };
+                    pending.settledBy = interceptor.id;
+                }
+                // The note is what the person is shown about the choice, in the assistant's voice: a
+                // delegated, display-only message. The platform stamps `delegate`, so it cannot be claimed
+                // falsely. Shown only once the action has run: when it settles, `resolve` appends it so it
+                // precedes the outcome; otherwise it is appended below.
+                const content = (_a = options === null || options === void 0 ? void 0 : options.note) === null || _a === void 0 ? void 0 : _a.trim();
+                const note = content ? { content, delegate: interceptor.id } : undefined;
+                const token = {};
+                pending.running = { token, finishes: prepared.finishes, note };
+                let output;
+                try {
+                    // A run that returns at once is over at once: the claimant's parallel calls start in the
+                    // same tick, so awaiting it anyway would refuse the next one as busy for nothing.
+                    const ran = prepared.run();
+                    output = isThenable(ran) ? yield ran : ran;
+                }
+                catch (e) {
+                    logger.warn(`InteractionController: action "${action}" threw:`, e);
+                    if (pending.settledInRun !== token)
+                        restore();
+                    return {
+                        ok: false,
+                        error: 'threw',
+                        message: e instanceof Error ? e.message : String(e),
+                    };
+                }
+                finally {
+                    if (((_b = pending.running) === null || _b === void 0 ? void 0 : _b.token) === token)
+                        pending.running = undefined;
+                }
+                // This run settled it — not merely "it is no longer pending", which a settle by someone
+                // else while the action was in flight would also satisfy.
+                const finished = pending.settledInRun === token;
+                // An editing action is not an answer: whoever finishes it later is credited with that. It
+                // is remembered as an edit instead, so the resolved view can mark it, and the working agent
+                // is told of it whoever finishes: in the claimant's decision when the claimant finishes it,
+                // or as edits made on the user's behalf that the person then confirmed.
+                if (!finished) {
+                    restore();
+                    if (note && this.pending.has(interactionId))
+                        this.appendNote(note);
+                    ((_c = pending.edits) !== null && _c !== void 0 ? _c : (pending.edits = [])).push(editOf(interceptor.id, action, prepared.choice, args));
+                }
+                recordMetaEvent(this.deps.sessionKey, 'interaction.invoked', {
+                    interactionId,
+                    claimant: interceptor.id,
+                    action,
+                    finished,
+                });
+                return Object.assign({ ok: true, finished, actions: finished ? [] : surface.actions() }, (output !== undefined && !finished ? { output } : {}));
+            }),
         };
     }
+    /** A claimant's note about its choice: a delegated, display-only message in the assistant's voice. */
+    appendNote(note) {
+        this.deps.appendToHistory({
+            role: 'assistant',
+            content: note.content,
+            delegate: note.delegate,
+            excludeFromProvider: true,
+        });
+    }
     /** See `ChatDriver.setHostInteractionRequester`. */
     setHostRequester(fn, recordOutcome) {
         this.hostRequester = fn;
@@ -175,8 +416,39 @@ export class InteractionController {
             // 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);
+            // `ctx.resolve` settles through the same path a widget's `interaction-completed` takes —
+            // including a controller resolving in its constructor, before its message is appended,
+            // which `resolve` holds back until there is a message to patch.
+            const handle = createInteractionContext(interactionId, {
+                resolve: (result) => this.resolve(interactionId, result),
+                checkpoint: this.takeOverCheckpoint(componentName, data, interactionId),
+                saveCheckpoint: (value) => this.saveCheckpoint(interactionId, componentName, value),
+            });
             this.contexts.set(interactionId, handle);
+            bindStepRecorder(handle.context, (step, outcome) => recordMetaEvent(this.deps.sessionKey, 'interaction.step', {
+                interactionId,
+                component: componentName,
+                step,
+                outcome,
+            }), (reason, saved) => recordMetaEvent(this.deps.sessionKey, 'interaction.checkpoint', {
+                action: 'refused',
+                component: componentName,
+                interactionId,
+                reason,
+                saved,
+            }));
+            // Build the widget's controller from its registration (GENC-1660) BEFORE the interceptors are
+            // asked, so a pure question's surface is ready at the handoff.
+            const registration = getInteractionRegistration(componentName);
+            if (registration === null || registration === void 0 ? void 0 : registration.controller) {
+                try {
+                    handle.setController(registration.controller(data, handle.context));
+                }
+                catch (e) {
+                    // The widget still renders and the person can still answer it; it just has no surface.
+                    logger.error(`InteractionController: the "${componentName}" controller threw:`, e);
+                }
+            }
             const heldBy = this.offer(handle, {
                 interactionId,
                 componentName,
@@ -235,7 +507,7 @@ export class InteractionController {
      * report twice, and the second report has nothing left to settle.
      */
     resolve(interactionId, result) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _a, _b, _c, _d, _e, _f, _g;
         const interaction = this.pending.get(interactionId);
         if (!interaction) {
             logger.warn(`Interaction with ID ${interactionId} not found.`);
@@ -268,15 +540,19 @@ export class InteractionController {
         // 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;
+        // Settled under a claimant's `hold.invoke` run, credited to it: that run's note goes first, so
+        // it precedes the outcome, and the run learns that it was the one that finished it.
+        const run = answeredBy && answeredBy !== 'user' ? interaction.running : undefined;
+        if (run) {
+            interaction.settledInRun = run.token;
+            if (run.note)
+                this.appendNote(run.note);
+        }
+        const edits = ((_d = interaction.edits) === null || _d === void 0 ? void 0 : _d.length) ? interaction.edits : undefined;
+        const { decision, edited } = doneOnUsersBehalf(interaction, answeredBy);
         const patched = this.deps.patchInteractionMessage(interactionId, (message) => {
             var _a;
-            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 } : {})));
+            return (Object.assign(Object.assign(Object.assign({}, message), { interaction: Object.assign(Object.assign(Object.assign(Object.assign({}, message.interaction), { resolved: result }), (answeredBy ? { answeredBy } : {})), (edits ? { edits } : {})) }), (costUsd != null ? { externalCostUsd: ((_a = message.externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd } : {})));
         });
         if (patched)
             this.deps.notifyHistoryUpdated();
@@ -304,23 +580,32 @@ export class InteractionController {
         if (interaction.overrideId) {
             this.deps.emit(new CustomEvent('interaction-stop', { detail: { interactionId } }));
         }
-        recordMetaEvent(this.deps.sessionKey, 'interaction.resolved', Object.assign({ interactionId }, (answeredBy ? { answeredBy } : {})));
+        recordMetaEvent(this.deps.sessionKey, 'interaction.resolved', Object.assign(Object.assign({ interactionId }, (answeredBy ? { answeredBy } : {})), (edits ? { edits: edits.length } : {})));
         // 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 });
+            (_e = interaction.onSettled) === null || _e === void 0 ? void 0 : _e.call(interaction, Object.assign({ answeredBy, decision }, (edited ? { edited } : {})));
         }
         catch (e) {
             logger.warn('InteractionController: onSettled threw:', e);
         }
+        // For the host, whoever settled it (GENC-1660): a controller resolving through `ctx.resolve`
+        // never passes through the host's `interaction-completed` handler, which is where it started
+        // its loading indicator.
+        this.deps.emit(new CustomEvent('interaction-settled', {
+            detail: Object.assign({ interactionId }, (answeredBy ? { answeredBy } : {})),
+        }));
         interaction.resolve(result);
         this.pending.delete(interactionId);
+        // Settled, so its work is finished with: nothing is left to resume.
+        if (((_f = this.checkpoint) === null || _f === void 0 ? void 0 : _f.interactionId) === interactionId)
+            this.checkpoint = undefined;
         // 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)
-        (_j = this.contexts.get(interactionId)) === null || _j === void 0 ? void 0 : _j.dispose();
+        (_g = this.contexts.get(interactionId)) === null || _g === void 0 ? void 0 : _g.dispose();
         this.contexts.delete(interactionId);
     }
     /**

package/dist/esm/components/chat-interaction-wrapper/chat-interaction-wrapper.js

@@ -22,6 +22,12 @@ let AiChatInteractionWrapper = class AiChatInteractionWrapper extends GenesisEle
         this.resolved = undefined;
         /** See `AiChatInteraction`'s resolved `outcome`: recorded after the answer, by the tool. */
         this.outcome = undefined;
+        /**
+         * See `AiChatInteraction`'s resolved `edits`: what a claimant changed before it was settled. The
+         * template binds the message's `edits` straight over this, so `undefined` arrives whenever there
+         * were none: it means "no edits", never an error.
+         */
+        this.edits = undefined;
     }
     connectedCallback() {
         super.connectedCallback();
@@ -67,9 +73,14 @@ let AiChatInteractionWrapper = class AiChatInteractionWrapper extends GenesisEle
     outcomeChanged() {
         this.resolvedChanged();
     }
-    /** The resolved descriptor, with the outcome when one has been recorded. */
+    /** Edits a claimant made reach a widget already showing the answer, the same way. */
+    editsChanged() {
+        this.resolvedChanged();
+    }
+    /** The resolved descriptor, with the outcome and the claimant's edits when there are any. */
     resolvedInteraction() {
-        return Object.assign({ status: 'resolved', data: this.data, result: this.resolved }, (this.outcome !== undefined ? { outcome: this.outcome } : {}));
+        var _a;
+        return Object.assign(Object.assign({ status: 'resolved', data: this.data, result: this.resolved }, (this.outcome !== undefined ? { outcome: this.outcome } : {})), (((_a = this.edits) === null || _a === void 0 ? void 0 : _a.length) ? { edits: this.edits } : {}));
     }
     /**
      * Watch the rendered widget element for box-size changes. When the widget
@@ -213,6 +224,9 @@ __decorate([
 __decorate([
     observable
 ], AiChatInteractionWrapper.prototype, "outcome", void 0);
+__decorate([
+    observable
+], AiChatInteractionWrapper.prototype, "edits", void 0);
 AiChatInteractionWrapper = __decorate([
     customElement({
         name: 'ai-chat-interaction-wrapper',