@newheap/platform-ai-chat 0.19.0 → 0.21.0

package/fesm2022/newheap-platform-ai-chat-testing.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, inject, signal, Injectable, computed, DestroyRef, makeEnvironmentProviders } from '@angular/core';
-import { NH_ASSISTANT_AGENT_PACKAGE_MAX_AGENTS, NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION, NH_ASSISTANT_AGENT_PACKAGE_FORMAT, NH_ASSISTANT_PACKAGE_LOCK_ALL, NH_ASSISTANT_PACKAGE_LOCK_FIELDS, NH_ASSISTANT_AGENT_PACKAGE_MAX_BYTES, NH_ASSISTANT_UPLOAD_HEADER, ɵnhAssistantMediaTypeOf as _nhAssistantMediaTypeOf, NH_ASSISTANT_MAX_PROPOSAL_LOOKUP, NH_ASSISTANT_CONFIG, applyNhAssistantEvent, normalizeNhAssistantClientContext, applyNhAssistantApprovalDecision, NH_ASSISTANT_FETCH, NH_ASSISTANT_UPLOAD, NhAssistantLiveService, NH_ASSISTANT_MCP_AUTHORIZATION_WINDOW } from '@newheap/platform-ai-chat';
+import { NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION, NH_ASSISTANT_AGENT_PACKAGE_FORMAT, NH_ASSISTANT_AGENT_PACKAGE_MAX_AGENTS, NH_ASSISTANT_PACKAGE_LOCK_ALL, NH_ASSISTANT_PACKAGE_LOCK_FIELDS, NH_ASSISTANT_AGENT_PACKAGE_MAX_BYTES, NH_ASSISTANT_UPLOAD_HEADER, ɵnhAssistantMediaTypeOf as _nhAssistantMediaTypeOf, NH_ASSISTANT_MAX_PROPOSAL_LOOKUP, NH_ASSISTANT_CONFIG, applyNhAssistantEvent, normalizeNhAssistantClientContext, applyNhAssistantApprovalDecision, applyNhAssistantQuestionAnswer, NH_ASSISTANT_FETCH, NH_ASSISTANT_UPLOAD, NhAssistantLiveService, NH_ASSISTANT_MCP_AUTHORIZATION_WINDOW } from '@newheap/platform-ai-chat';
 import { Observable, Subject } from 'rxjs';
 
 /**
@@ -25,6 +25,8 @@ const statusTable = {
         'assistant-run-filter-invalid',
         'assistant-board-scope-invalid',
         'assistant-feedback-invalid',
+        'assistant-question-invalid',
+        'assistant-question-answer-invalid',
         'assistant-trigger-filter-not-found',
         'assistant-replay-not-shadow',
         'assistant-evaluation-not-variant',
@@ -55,6 +57,7 @@ const statusTable = {
         'assistant-context-unavailable',
         'assistant-owner-required',
         'assistant-approval-forbidden',
+        'assistant-question-forbidden',
         'assistant-turn-forbidden',
         'assistant-subject-access-denied',
         'assistant-approval-policy-denied',
@@ -71,6 +74,7 @@ const statusTable = {
         'assistant-metadata-entry-not-found',
         'assistant-instructions-asset-not-found',
         'assistant-approval-not-found',
+        'assistant-question-not-found',
         'assistant-share-link-invalid',
         'assistant-participant-not-found',
         'assistant-directory-unavailable',
@@ -111,6 +115,7 @@ const statusTable = {
         'assistant-agent-does-not-work-on',
         'assistant-moved-to-shadow',
         'assistant-shadow-variant',
+        'assistant-not-shadow-variant',
         'assistant-service-account-not-used',
         'assistant-consult-route-not-allowed',
         'assistant-consult-proposal-refused',
@@ -133,6 +138,9 @@ const statusTable = {
         'assistant-memory-conflict',
         'assistant-replay-active',
         'assistant-feedback-not-accepted',
+        'assistant-question-not-pending',
+        'assistant-question-expired',
+        'assistant-question-cancelled',
         'assistant-trigger-rate-limited',
         'assistant-version-conflict',
         'assistant-agent-exists',
@@ -391,6 +399,10 @@ function mockWorksOnErrors(worksOn, knownTypes, agentPolicies, divisions) {
 }
 /** Whether an agent works on subjects of the type, as the server's rule decides it. */
 function mockWorksOnCovers(agent, subjectType) {
+    // A chat-only agent (`ChatOnly()` in code) works on no subject at all.
+    if (agent.chatOnly === true) {
+        return false;
+    }
     if (subjectType === mockSystemSubjectType) {
         return agent.worksOnApplication === true;
     }
@@ -410,6 +422,8 @@ const consultationRoutes = [
 const mockChatProfile = 'chat';
 const autonomyLevels = ['observe', 'explain', 'propose', 'simulate', 'execute'];
 const dataClassifications$1 = ['public', 'internal', 'confidential', 'restricted'];
+/** The most MCP servers one agent is assigned to, as the server allows. */
+const maxServersPerAgent = 32;
 /**
  * The agents of the mock administration: agents in code and agents created as data, their state,
  * shadow modes, technical accounts, feedback, evaluation and replays. The mock runs no agents on
@@ -426,18 +440,24 @@ class NhAssistantMockAdminAgents {
         const agents = admin.agents
             ?? scenario.agents.map(agent => ({ ...codeAgentFromSummary(agent), source: 'code' }));
         // How an agent runs, in code or as data, belongs to its run configuration, not to the agent.
-        for (const { source, skills, shadowOf, shadow, serviceAccount, worksOnDeclared, knownSubjectTypes, consultations, consultationDescriptions, codeRunSettings: _, runConfiguration: __, consultableAsData: ___, dataConsultations: ____, consultationTools: _____, codeHandOffs: ______, ...input } of agents) {
+        for (const { source, skills, shadowOf, shadow, serviceAccount, worksOnDeclared, knownSubjectTypes, consultations, consultationDescriptions, chatOnly, codeRunSettings: _, runConfiguration: __, consultableAsData: ___, dataConsultations: ____, consultationTools: _____, codeHandOffs: ______, ...input } of agents) {
             const variant = typeof shadowOf === 'string';
             const agentShadow = variant || shadow === true;
+            // A chat-only agent has no shadow threads: it and its skills always work live.
+            const live = source === 'code' && chatOnly === true;
             const initial = this.toAgent(input, source, 1, false);
             this.agents.set(input.id, {
                 agent: {
                     ...initial,
                     // Code says what its agents work on; a scenario agent that says nothing works on all objects.
                     ...(source === 'code' ? { ...(mockWorksOnFromInput(input) ?? mockUndeclaredWorksOn), worksOnDeclared: worksOnDeclared ?? mockWorksOnFromInput(input) !== null } : {}),
+                    // A chat-only agent in code (`ChatOnly()`) works on nothing, said on purpose.
+                    ...(source === 'code' && chatOnly === true
+                        ? { chatOnly: true, worksOnSubjectTypes: [], worksOnAllSubjects: false, worksOnApplication: false, perDivision: false, worksOnDeclared: true }
+                        : {}),
                     knownSubjectTypes: knownSubjectTypes ?? [],
                     shadowOf: shadowOf ?? null,
-                    shadow: shadowState(agentShadow, variant || shadow === true, null, variant),
+                    shadow: shadowState(agentShadow, variant || shadow === true, null, variant || live),
                     serviceAccount: serviceAccount === undefined
                         ? null
                         : { actorId: serviceAccount, configuredActorId: serviceAccount, overridden: false, changedAt: null, changedBy: null, reason: null },
@@ -455,7 +475,7 @@ class NhAssistantMockAdminAgents {
                         dailyTokens: null,
                         cancelledRuns: 0,
                         startedRuns: 0,
-                        shadow: shadowState(agentShadow || skill.shadow === true, skill.shadow === true, null, variant)
+                        shadow: shadowState(!live && (agentShadow || skill.shadow === true), skill.shadow === true, null, variant || live)
                     }))
                 },
                 codeDefinition: source === 'code' ? structuredClone(input) : null,
@@ -500,6 +520,64 @@ class NhAssistantMockAdminAgents {
         stored.agent = { ...stored.agent, version: stored.agent.version + 1, updatedAt: this.now() };
         return stored.agent;
     }
+    /**
+     * Copies a data shadow variant's definition onto its live agent as the live agent's next version,
+     * as a promotion does on the server before it deletes the variant: the live agent keeps its name,
+     * MCP servers, state and shadow mode; an agent in code takes only the fields it can override, an
+     * agent created here also the variant's profile, classification, what it works on and its asset.
+     */
+    promote(variantId, liveId) {
+        const variant = this.agents.get(variantId);
+        const live = this.agents.get(liveId);
+        if (!variant || !live) {
+            throw new Error(`The mock has no agent '${variant ? liveId : variantId}'.`);
+        }
+        const from = variant.agent;
+        const runtime = live.agent.source === 'admin';
+        const definition = {
+            id: live.agent.id,
+            displayName: live.agent.displayName,
+            description: from.description,
+            instructions: runtime && from.instructionsAsset ? '' : from.instructions,
+            toolSelectors: [...from.toolSelectors],
+            mcpServerIds: [...live.agent.mcpServerIds],
+            requiredPolicy: from.requiredPolicy,
+            autonomy: from.autonomy,
+            ...(runtime
+                ? {
+                    ...pickWorksOn(from),
+                    profile: from.profile,
+                    dataClassification: from.dataClassification ?? null,
+                    instructionsAsset: from.instructionsAsset ?? null
+                }
+                : {})
+        };
+        live.agent = this.toAgent(definition, live.agent.source, live.agent.version + 1, live.agent.source === 'code', live.agent);
+        return live.agent;
+    }
+    /**
+     * Assigns an MCP server to an agent or removes the assignment, as `PUT` and
+     * `DELETE admin/mcp-servers/{id}/agents/{agentId}` do: only the assignment changes, never the agent's
+     * version; an agent has at most 32 servers.
+     */
+    setMcpAssignment(agentId, serverId, assign) {
+        const stored = this.agents.get(agentId);
+        if (!stored) {
+            return 'agent-not-found';
+        }
+        const assigned = stored.agent.mcpServerIds.includes(serverId);
+        if (assigned === assign) {
+            return 'unchanged';
+        }
+        if (assign && stored.agent.mcpServerIds.length >= maxServersPerAgent) {
+            return 'too-long';
+        }
+        stored.agent = {
+            ...stored.agent,
+            mcpServerIds: assign ? [...stored.agent.mcpServerIds, serverId] : stored.agent.mcpServerIds.filter(id => id !== serverId)
+        };
+        return 'changed';
+    }
     /** Removes a deleted MCP server from the agents it was assigned to. */
     removeServer(serverId) {
         for (const agent of this.agents.values()) {
@@ -557,7 +635,7 @@ class NhAssistantMockAdminAgents {
             if (refused) {
                 return refused;
             }
-            const created = this.toAgent(input, 'admin', 1, false);
+            const created = this.toAgent({ ...input, mcpServerIds: input.mcpServerIds ?? [] }, 'admin', 1, false);
             // A data shadow variant always works in shadow and is never offered in the chat.
             const agent = shadowOf === null
                 ? created
@@ -617,7 +695,8 @@ class NhAssistantMockAdminAgents {
                 return mockFailure('assistant-version-conflict');
             }
             const { expectedVersion, ...definition } = input;
-            const updated = this.toAgent(definition, stored.agent.source, stored.agent.version + 1, stored.agent.source === 'code', stored.agent);
+            // An omitted list keeps the agent's assignments; an empty list removes them.
+            const updated = this.toAgent({ ...definition, mcpServerIds: definition.mcpServerIds ?? stored.agent.mcpServerIds }, stored.agent.source, stored.agent.version + 1, stored.agent.source === 'code', stored.agent);
             // A data shadow variant keeps its live agent and stays out of the chat.
             stored.agent = stored.agent.source === 'admin' && stored.agent.shadowOf ? { ...updated, offeredInChat: false } : updated;
             return { status: 200, body: stored.agent };
@@ -671,6 +750,10 @@ class NhAssistantMockAdminAgents {
         if (request === null) {
             return mockValidationFailure();
         }
+        // The skills of a chat-only agent always work live.
+        if (stored.agent.chatOnly === true) {
+            return mockFailure('assistant-agent-does-not-work-on');
+        }
         const agentShadow = stored.agent.shadow ?? shadowState(false, false, null, false);
         if (agentShadow.locked) {
             return mockFailure('assistant-shadow-variant');
@@ -845,6 +928,10 @@ class NhAssistantMockAdminAgents {
         if (request === null) {
             return mockValidationFailure();
         }
+        // A chat-only agent has no runs that could work in shadow threads.
+        if (stored.agent.chatOnly === true) {
+            return mockFailure('assistant-agent-does-not-work-on');
+        }
         const current = stored.agent.shadow ?? shadowState(false, false, null, false);
         if (current.locked) {
             return mockFailure('assistant-shadow-variant');
@@ -1085,7 +1172,9 @@ class NhAssistantMockAdminAgents {
             typeof input.description === 'string' &&
             typeof input.instructions === 'string' && input.instructions.length <= mockMaxInstructions &&
             Array.isArray(input.toolSelectors) && input.toolSelectors.every(selector => /^[a-z0-9*][a-z0-9.*-]*$/.test(selector)) &&
-            Array.isArray(input.mcpServerIds) && input.mcpServerIds.every(serverId => this.rules.hasServer(serverId)) &&
+            // Omitted, a new agent has no servers and an update keeps them, as on the server.
+            (input.mcpServerIds === undefined || input.mcpServerIds === null ||
+                (Array.isArray(input.mcpServerIds) && input.mcpServerIds.every(serverId => this.rules.hasServer(serverId)))) &&
             (input.requiredPolicy === null || (typeof input.requiredPolicy === 'string' && (!policies || policies.includes(input.requiredPolicy)))) &&
             autonomyLevels.includes(input.autonomy) &&
             (input.isEnabled === undefined || typeof input.isEnabled === 'boolean');
@@ -1108,6 +1197,8 @@ class NhAssistantMockAdminAgents {
         const classification = chosenClassification(dataClassification);
         return this.withWarnings({
             ...definition,
+            // The callers name the servers; an omitted list keeps those of the agent, or none.
+            mcpServerIds: definition.mcpServerIds ?? previous?.mcpServerIds ?? [],
             // An agent created here keeps its profile when the input omits it; code decides for the others.
             profile: chosenProfile ?? previous?.profile ?? mockChatProfile,
             // The same for its classification; an agent in code keeps the one of its scenario.
@@ -1274,6 +1365,9 @@ const readerPriority = { min: -1000, max: 1000 };
 const classifications$1 = ['public', 'internal', 'confidential', 'restricted'];
 const mediaTypePattern$1 = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
 const controlCharacters = /[\u0000-\u001f\u007f]/;
+/** The longest remote tool name a sync stores, and the most tools of a server that wait for a sync. */
+const maxRemoteName = 128;
+const maxToolsAwaitingSync = 100;
 /**
  * The MCP servers of the mock administration and the caller's own connections: secrets are
  * write-only, new tools start disabled as mutations, a changed remote schema disables a tool, OAuth
@@ -1701,19 +1795,20 @@ class NhAssistantMockAdminMcp {
         if (length === 5 && action === 'tools' && method === 'PUT' && child !== undefined) {
             const tool = stored.tools.get(child);
             const input = body;
-            if (!tool) {
-                return mockFailure('assistant-mcp-tool-not-found');
-            }
             if (typeof input?.isEnabled !== 'boolean' || (input.effect !== 'read-only' && input.effect !== 'mutation') ||
                 (input.descriptionOverride !== null && typeof input.descriptionOverride !== 'string')) {
                 return mockValidationFailure();
             }
-            if (input.isEnabled && tool.status === 'missing') {
-                return mockValidationFailure('isEnabled');
-            }
             const override = typeof input.descriptionOverride === 'string' && input.descriptionOverride.trim().length > 0
                 ? input.descriptionOverride.slice(0, 1_000)
                 : null;
+            if (!tool) {
+                return this.reviewBeforeSync(stored, child, input.isEnabled, input.effect, override);
+            }
+            // A tool the server no longer lists cannot be enabled; one that no sync has seen yet can.
+            if (input.isEnabled && tool.status === 'missing' && !tool.awaitingSync) {
+                return mockFailure('assistant-mcp-tool-disabled');
+            }
             const updated = {
                 ...tool,
                 isEnabled: input.isEnabled,
@@ -1724,14 +1819,77 @@ class NhAssistantMockAdminMcp {
             stored.tools.set(child, updated);
             return { status: 200, body: toTool(updated) };
         }
+        if (length === 5 && action === 'agents' && child !== undefined) {
+            if (method !== 'PUT' && method !== 'DELETE') {
+                return { status: 405 };
+            }
+            // Only the assignment changes, never the agent's version, as on the server.
+            const changed = this.context.setAssignment(stored.server.id, child, method === 'PUT');
+            if (changed === 'agent-not-found') {
+                return mockFailure('assistant-agent-not-found');
+            }
+            if (changed === 'too-long') {
+                return mockFailure('assistant-validation', { mcpServerIds: ['too-long'] });
+            }
+            return { status: 200, body: this.toServer(stored) };
+        }
         return mockFailure('assistant-not-found');
     }
+    /**
+     * The reviewed settings of a tool that no sync has seen yet, as the server stores them: a missing tool
+     * without a schema that waits for its sync, with a name a sync could store and no other spelling of
+     * a stored tool's name; at most 100 per server.
+     */
+    reviewBeforeSync(stored, remoteName, isEnabled, effect, descriptionOverride) {
+        if (remoteName.trim().length === 0) {
+            return mockFailure('assistant-validation', { remoteName: ['required'] });
+        }
+        if (remoteName.length > maxRemoteName) {
+            return mockFailure('assistant-validation', { remoteName: ['too-long'] });
+        }
+        const lower = remoteName.toLowerCase();
+        if (controlCharacters.test(remoteName) || [...stored.tools.keys()].some(name => name.toLowerCase() === lower)) {
+            return mockFailure('assistant-validation', { remoteName: ['invalid'] });
+        }
+        if ([...stored.tools.values()].filter(tool => tool.awaitingSync).length >= maxToolsAwaitingSync) {
+            return mockFailure('assistant-configuration-limit');
+        }
+        const tool = {
+            remoteName,
+            localId: `mcp.${stored.server.id}.${kebab(remoteName)}`,
+            description: '',
+            descriptionOverride,
+            isEnabled,
+            effect,
+            status: 'missing',
+            readOnlyHint: null,
+            awaitingSync: true,
+            inputSchemaHash: ''
+        };
+        stored.tools.set(remoteName, tool);
+        return { status: 200, body: toTool(tool) };
+    }
     sync(stored) {
         const seen = new Set();
         for (const remote of stored.remoteTools) {
             seen.add(remote.remoteName);
-            const existing = stored.tools.get(remote.remoteName);
+            const existing = stored.tools.get(remote.remoteName) ?? this.reviewedInOtherSpelling(stored, remote.remoteName);
             const description = remote.description.slice(0, 1_000);
+            if (existing?.awaitingSync) {
+                // The first sync that sees a reviewed tool keeps its settings and takes the server's spelling.
+                stored.tools.delete(existing.remoteName);
+                stored.tools.set(remote.remoteName, {
+                    ...existing,
+                    remoteName: remote.remoteName,
+                    localId: `mcp.${stored.server.id}.${kebab(remote.remoteName)}`,
+                    description,
+                    status: 'available',
+                    readOnlyHint: remote.readOnlyHint ?? null,
+                    awaitingSync: false,
+                    inputSchemaHash: remote.inputSchemaHash
+                });
+                continue;
+            }
             if (!existing) {
                 stored.tools.set(remote.remoteName, {
                     remoteName: remote.remoteName,
@@ -1757,11 +1915,19 @@ class NhAssistantMockAdminMcp {
             });
         }
         for (const [name, tool] of stored.tools) {
-            if (!seen.has(name)) {
+            // A reviewed tool that this sync does not see keeps waiting with its settings.
+            if (!seen.has(name) && !tool.awaitingSync) {
                 stored.tools.set(name, { ...tool, isEnabled: false, status: 'missing' });
             }
         }
     }
+    /** A reviewed tool that waits for its sync under another spelling of a name no remote tool has. */
+    reviewedInOtherSpelling(stored, remoteName) {
+        const lower = remoteName.toLowerCase();
+        const names = new Set(stored.remoteTools.map(remote => remote.remoteName));
+        return [...stored.tools.values()]
+            .find(tool => tool.awaitingSync && !names.has(tool.remoteName) && tool.remoteName.toLowerCase() === lower);
+    }
     /**
      * The field errors of a server change, as the server reports them in one refusal: the fields
      * themselves, the credential and the OAuth settings. Empty when the change is valid.
@@ -2439,7 +2605,7 @@ function allowedServerUrl(value) {
     }
 }
 function toTool({ inputSchemaHash, ...tool }) {
-    return tool;
+    return { ...tool, awaitingSync: tool.awaitingSync === true };
 }
 function toTools(stored) {
     return [...stored.tools.values()].map(toTool);
@@ -2740,10 +2906,16 @@ class NhAssistantMockHandOffs {
             allowsDataVariants: allowed,
             maxDataVariants: allowed ? this.maxVariants() : 0,
             variants: [
-                ...code.map(agent => ({ agentId: agent.id, displayName: agent.displayName, source: 'code', hasRunSettings: true, inEffect: true, problem: null })),
+                ...code.map(agent => ({
+                    agentId: agent.id, displayName: agent.displayName, source: 'code', hasRunSettings: true, inEffect: true, problem: null, version: agent.version
+                })),
                 ...data.map(agent => {
                     const hasRunSettings = this.agents.isConfigured(agent);
-                    return { agentId: agent.id, displayName: agent.displayName, source: 'data', hasRunSettings, inEffect: hasRunSettings, problem: null };
+                    return {
+                        agentId: agent.id, displayName: agent.displayName, source: 'data', hasRunSettings, inEffect: hasRunSettings, problem: null, version: agent.version,
+                        packageId: null,
+                        packageVersion: null
+                    };
                 })
             ]
         };
@@ -4166,6 +4338,54 @@ class NhAssistantMockRunConfiguration {
         existing.reason = typeof request.reason === 'string' && request.reason.trim().length > 0 ? request.reason.trim() : null;
         return { status: 200, body: withoutOwner(existing) };
     }
+    /**
+     * The ids of the variant's data skills that would move to `live` and the failure of one that cannot,
+     * as a promotion with `moveSkills` checks them before anything changes: a skill the live agent has
+     * in code stays (`assistant-skill-in-code`).
+     */
+    skillsToMove(variantId, live) {
+        const skillIds = this.liveSkills(variantId).map(skill => skill.skillId);
+        const inCode = (live.skills ?? []).some(skill => skillIds.includes(skill.skillId) && !this.skills.has(key$1(live.id, skill.skillId)));
+        return { skillIds, failure: inCode ? mockFailure('assistant-skill-in-code') : null };
+    }
+    /**
+     * Moves the variant's data skills to `live` as a promotion does: each becomes the next live version
+     * of the live agent's skill with the same id, or a new skill, which starts in shadow. Answers the ids
+     * that moved, in order, or the failure of the first save.
+     */
+    moveSkills(variantId, live, reason) {
+        const moved = [];
+        for (const skill of this.liveSkills(variantId)) {
+            const current = (this.skills.get(key$1(live.id, skill.skillId)) ?? []).find(version => version.status === 'live');
+            const request = {
+                description: skill.description,
+                instructions: skill.instructionsAsset ? null : skill.instructions,
+                tools: [...skill.tools],
+                profile: skill.profile,
+                ruleHandler: skill.ruleHandler,
+                maxTokensPerRun: skill.maxTokensPerRun,
+                dailyToolCalls: skill.dailyToolCalls,
+                dailyTokens: skill.dailyTokens,
+                approvalPolicy: skill.approvalPolicy,
+                expectedVersion: current?.version ?? null,
+                reason,
+                ...(current ? { apply: 'live' } : {}),
+                dataClassification: skill.dataClassification ?? null,
+                acceptsFiles: skill.acceptsFiles ?? false,
+                maxFileBytes: skill.maxFileBytes ?? null,
+                maxFilePages: skill.maxFilePages ?? null,
+                maxFilesPerTurn: skill.maxFilesPerTurn ?? null,
+                maxFileTokensPerTurn: skill.maxFileTokensPerTurn ?? null,
+                instructionsAsset: skill.instructionsAsset ?? null
+            };
+            const saved = this.skill('PUT', live, skill.skillId, request, new URLSearchParams());
+            if (saved.status !== 200) {
+                return { moved, failure: saved };
+            }
+            moved.push(skill.skillId);
+        }
+        return { moved, failure: null };
+    }
     /** An agent in code has a run configuration; one created in the administration once it has run settings. */
     isConfigured(agent) {
         return agent.source === 'code' || this.settings.has(agent.id);
@@ -4340,6 +4560,7 @@ class NhAssistantMockAdmin {
             agents: () => this.agents.all(),
             chatAgentIds: () => this.agents.chatAgents().map(agent => agent.id),
             removeServer: serverId => this.agents.removeServer(serverId),
+            setAssignment: (serverId, agentId, assign) => this.agents.setMcpAssignment(agentId, serverId, assign),
             canAdminister: () => this.canAdminister
         });
         this.presetRunConfigurations(admin.agents ?? []);
@@ -4468,6 +4689,9 @@ class NhAssistantMockAdmin {
                 if (id !== undefined && (action === 'replay' || action === 'replays') && segments.length === 4) {
                     return this.agents.agentReplay(method, id, action, body);
                 }
+                if (id !== undefined && action === 'promote' && segments.length === 4) {
+                    return this.promote(method, id, body);
+                }
                 if (id !== undefined && (action === 'hand-offs' || action === 'shadow-variants')) {
                     const handed = this.handOffs.handle(method, id, segments.slice(3), body, query);
                     if (handed) {
@@ -4495,6 +4719,56 @@ class NhAssistantMockAdmin {
                 return mockFailure('assistant-not-found');
         }
     }
+    /**
+     * `POST admin/agents/{id}/promote`: a data shadow variant's definition becomes its live agent's next
+     * version, its skills move along with `moveSkills`, and the variant is deleted, as on the server. A
+     * stale version of either agent answers `409`; a skill the live agent has in code stops the promotion
+     * before anything changes.
+     */
+    promote(method, variantId, body) {
+        if (method !== 'POST') {
+            return { status: 405 };
+        }
+        const variant = this.agents.find(variantId);
+        if (!variant) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        if (variant.source !== 'admin' || !variant.shadowOf) {
+            return mockFailure('assistant-not-shadow-variant');
+        }
+        const request = body;
+        if (typeof request?.expectedVersion !== 'number') {
+            return mockFailure('assistant-validation', { expectedVersion: ['required'] });
+        }
+        if (typeof request.reason === 'string' && request.reason.length > 500) {
+            return mockFailure('assistant-validation', { reason: ['too-long'] });
+        }
+        const live = this.agents.find(variant.shadowOf);
+        if (!live) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        if (request.expectedVersion !== live.version
+            || (typeof request.expectedVariantVersion === 'number' && request.expectedVariantVersion !== variant.version)) {
+            return mockFailure('assistant-version-conflict');
+        }
+        if (request.moveSkills === true) {
+            const refused = this.runConfiguration.skillsToMove(variant.id, live).failure;
+            if (refused) {
+                return refused;
+            }
+        }
+        // In the server's order: the definition, the skills, then the variant leaves.
+        const agent = this.agents.promote(variant.id, live.id);
+        const moved = request.moveSkills === true
+            ? this.runConfiguration.moveSkills(variant.id, agent, typeof request.reason === 'string' ? request.reason.trim() || null : null)
+            : { moved: [], failure: null };
+        if (moved.failure) {
+            return moved.failure;
+        }
+        this.agents.agentsEndpoint('DELETE', variant.id, undefined, undefined, 3);
+        const promotion = { agent: this.agents.find(agent.id), variantId: variant.id, movedSkills: moved.moved };
+        return { status: 200, body: promotion };
+    }
     context(method, sub, body) {
         const current = this.contextVersions[this.contextVersions.length - 1];
         if (sub === 'versions' && method === 'GET') {
@@ -4718,8 +4992,139 @@ class NhAssistantMockAgentPackages {
         if (segments[1] === 'agents' && segments[3] === 'package' && segments[4] === 'unlink' && segments.length === 5) {
             return method === 'POST' ? this.unlink(segments[2], body) : { status: 405 };
         }
+        // A promotion as the package's version is an import of the variant's parts onto its live agent.
+        if (segments[1] === 'agents' && segments[3] === 'promote' && segments.length === 4
+            && body?.asPackageVersion === true) {
+            return method === 'POST' ? this.promoteAsPackageVersion(segments[2], body) : { status: 405 };
+        }
         return null;
     }
+    /**
+     * `POST admin/agents/{id}/promote` with `asPackageVersion` (FB11): a data shadow variant whose every
+     * part is linked to one package becomes that package's next version of its live agent. Its parts,
+     * as an export reads them, are imported onto the live agent with the import's rules and relinked;
+     * the live agent keeps its name and chat offer, an agent in code its run settings in code. The
+     * variant leaves first, with its links, so its trigger ids are free, and the live agent leaves the
+     * package it belonged to; a refused part puts everything back and answers the import's
+     * `409 assistant-package-refused`. A part without a link answers `404 assistant-package-not-linked`.
+     */
+    promoteAsPackageVersion(variantId, body) {
+        const listed = this.context.call('GET', 'admin/agents');
+        if (listed.status !== 200) {
+            return listed;
+        }
+        const request = (body ?? {});
+        if (typeof request.expectedVersion !== 'number') {
+            return mockFailure('assistant-validation', { expectedVersion: ['required'] });
+        }
+        if (request.moveSkills === true) {
+            return mockFailure('assistant-validation', { moveSkills: ['not-allowed'] });
+        }
+        const variantRead = this.read(variantId);
+        if (!variantRead) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        const variant = variantRead.agent;
+        if (variant.source !== 'admin' || !variant.shadowOf) {
+            return mockFailure('assistant-not-shadow-variant');
+        }
+        const liveRead = this.read(variant.shadowOf);
+        if (!liveRead) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        const live = liveRead.agent;
+        if (request.expectedVersion !== live.version
+            || (typeof request.expectedVariantVersion === 'number' && request.expectedVariantVersion !== variant.version)) {
+            return mockFailure('assistant-version-conflict');
+        }
+        // Every part of the variant is linked to its package.
+        const link = this.links.get(variantId);
+        const parts = this.packageAgentOf(variantRead);
+        if (!link || [...partsOf(parts).keys()].some(part => !link.parts.has(part))) {
+            return mockFailure('assistant-package-not-linked');
+        }
+        const inCode = live.source === 'code';
+        const carried = parts.definition;
+        const definition = !carried
+            ? null
+            : inCode
+                ? {
+                    description: carried.description,
+                    instructions: carried.instructions,
+                    toolSelectors: carried.toolSelectors,
+                    requiredPolicy: carried.requiredPolicy,
+                    autonomy: carried.autonomy
+                }
+                : { ...carried, displayName: live.displayName, offeredInChat: live.offeredInChat !== false, shadowOf: null, startsOff: null, startsInShadow: null };
+        const locks = Object.fromEntries([...link.parts]
+            .filter(([part, partLink]) => partLink.lockedFields.length > 0 && (part !== 'runSettings' || !inCode))
+            .map(([part, partLink]) => [part, [...partLink.lockedFields]]));
+        const agent = withoutNulls({
+            ...parts,
+            id: live.id,
+            source: live.source,
+            definition,
+            runSettings: inCode ? null : parts.runSettings,
+            groups: null,
+            hashes: null,
+            locks: Object.keys(locks).length > 0 ? locks : null
+        });
+        const agentPackage = {
+            format: NH_ASSISTANT_AGENT_PACKAGE_FORMAT,
+            formatVersion: NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION,
+            package: { id: link.packageId, version: link.packageVersion },
+            agents: [agent]
+        };
+        // The live agent's technical account stays; without one it takes the variant's.
+        const account = liveRead.configuration?.runSettings?.serviceAccountActorId
+            ?? variantRead.configuration?.runSettings?.serviceAccountActorId
+            ?? null;
+        // All of it or nothing: the variant leaves first, and the package's other agents stay linked.
+        const restore = [this.context.snapshot(), this.snapshot()];
+        const others = [...this.links].filter(([agentId, item]) => item.packageId === link.packageId && agentId !== variantId);
+        this.links.delete(variantId);
+        const deleted = this.context.call('DELETE', `admin/agents/${encodeURIComponent(variantId)}`);
+        if (deleted.status >= 300) {
+            restore.forEach(put => put());
+            return deleted;
+        }
+        for (const [agentId] of others) {
+            this.links.delete(agentId);
+        }
+        this.links.delete(live.id);
+        for (const installed of this.installed.values()) {
+            installed.agents = installed.agents.filter(agentId => agentId !== live.id && agentId !== variantId);
+        }
+        const imported = this.importPackage({
+            package: agentPackage,
+            options: { relink: [{ agentId: live.id }], serviceAccounts: account ? { [live.id]: account } : null }
+        }, true);
+        if (imported.status !== 200) {
+            restore.forEach(put => put());
+            return imported;
+        }
+        for (const [agentId, item] of others) {
+            this.links.set(agentId, item);
+        }
+        this.installed.set(link.packageId, {
+            version: link.packageVersion,
+            agents: [...others.map(([agentId]) => agentId), live.id].sort()
+        });
+        const result = imported.body;
+        const promoted = this.read(live.id).agent;
+        return {
+            status: 200,
+            body: {
+                agent: this.withAgentPackage(promoted),
+                variantId,
+                movedSkills: result.parts
+                    .filter(part => part.part.startsWith('skill:') && part.outcome !== 'refused' && part.outcome !== 'left-behind' && part.outcome !== 'kept-local')
+                    .map(part => part.part.slice('skill:'.length))
+                    .sort(),
+                package: result
+            }
+        };
+    }
     /**
      * Runs a save of the administration under the package locks: a save may keep a locked field's value
      * or take the package's, never another; such a change is undone and refused with `{field}: locked`.
@@ -4827,6 +5232,22 @@ class NhAssistantMockAgentPackages {
                     return { ...result, body: this.withLink(agentId, `metadata:${id}`, body) };
                 }
                 return { ...result, body: body.map(entry => this.withLink(agentId, `metadata:${entry.name}`, entry)) };
+            case 'shadow-variants': {
+                // A data variant names the package its parts are linked to.
+                const listing = body;
+                return {
+                    ...result,
+                    body: {
+                        ...listing,
+                        variants: listing.variants.map(variant => {
+                            const link = this.links.get(variant.agentId);
+                            return variant.source === 'data' && link && link.parts.size > 0
+                                ? { ...variant, packageId: link.packageId, packageVersion: link.packageVersion }
+                                : variant;
+                        })
+                    }
+                };
+            }
             default:
                 return result;
         }
@@ -7544,7 +7965,8 @@ class NhAssistantMockAgentMetadata {
             name: entry.name,
             editable: entry.editable === true,
             maxBytes: entry.maxBytes ?? defaultMaxBytes,
-            indexed: entry.indexBy !== undefined
+            indexed: entry.indexBy !== undefined || entry.indexByEach !== undefined,
+            indexedByEach: entry.indexByEach !== undefined
         }));
     }
     /**
@@ -7660,8 +8082,10 @@ class NhAssistantMockAgentMetadata {
             version: inCode ? stored?.version ?? null : agent.version,
             agentVersion: agent.version,
             codeValue: inCode && code !== undefined ? structuredClone(code) : null,
-            indexed: entry.indexBy !== undefined,
+            indexed: entry.indexBy !== undefined || entry.indexByEach !== undefined,
             indexValue: value !== undefined ? indexOf(entry, value) : null,
+            indexedByEach: entry.indexByEach !== undefined,
+            indexValues: value !== undefined ? indexValuesOf(entry, value) : [],
             changedAt: stored?.changedAt ?? null,
             changedBy: stored?.changedBy ?? null
         };
@@ -7703,6 +8127,20 @@ function indexOf(entry, value) {
     const trimmed = typeof text === 'string' ? text.trim() : '';
     return trimmed.length > 0 ? trimmed.toLowerCase() : null;
 }
+/**
+ * The searchable values of an `IndexByEach` entry's value as the server stores them: trimmed, in
+ * lowercase, without empty values or repeats, in ordinal order.
+ */
+function indexValuesOf(entry, value) {
+    const texts = entry.indexByEach === undefined ? undefined : value[entry.indexByEach];
+    if (!Array.isArray(texts)) {
+        return [];
+    }
+    const values = texts
+        .map(text => (typeof text === 'string' ? text.trim().toLowerCase() : ''))
+        .filter(text => text.length > 0);
+    return [...new Set(values)].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
 
 /** How long the application may take to report after a hand-off in the mock. */
 const reportWithinMs = 4 * 60 * 60 * 1000;
@@ -7799,7 +8237,8 @@ class NhAssistantMockProposals {
                     parent: item.parent ?? null,
                     canGiveFeedback: false,
                     consultationId: item.consultationId ?? null,
-                    consultationRoute: route
+                    consultationRoute: route,
+                    ...(item.supersededByApprovalId ? { supersededByApprovalId: item.supersededByApprovalId } : {})
                 },
                 divisionId: item.divisionId ?? null,
                 canDecide,
@@ -7895,15 +8334,22 @@ class NhAssistantMockProposals {
         if (divisionId !== null && !guid.test(divisionId)) {
             return { status: 400 };
         }
+        // What waits for a decision by default; what waits for the application's report or for an
+        // approver to resolve an uncertain execution on request, with the same visibility.
+        const status = query.get('status') || 'pending';
+        if (!isInboxStatus(status)) {
+            return mockFailure('assistant-message-invalid');
+        }
         const grouped = query.get('grouped') === 'true';
         const items = this.visible()
-            .filter(item => item.proposal.status === 'pending' && item.canDecide)
+            .filter(item => item.proposal.status === status && item.canDecide)
             .filter(item => divisionId === null || sameGuid(item.divisionId, divisionId))
             .map(item => item.proposal)
             .filter(proposal => (subjectType === null || proposal.subjectType === subjectType)
             && (agentId === null || proposal.agentId === agentId)
             && (runId === null || proposal.runId === runId))
-            .sort((left, right) => left.expiresAt.localeCompare(right.expiresAt) || left.approvalId.localeCompare(right.approvalId));
+            .sort((left, right) => inboxSortAt(left, status).localeCompare(inboxSortAt(right, status))
+            || left.approvalId.localeCompare(right.approvalId));
         const ordered = grouped ? groupedOrder(items) : items;
         const offset = (page - 1) * itemsPerPage;
         const pageItems = ordered.slice(offset, offset + itemsPerPage);
@@ -7912,6 +8358,7 @@ class NhAssistantMockProposals {
         const body = {
             items: pageItems,
             total: items.length,
+            status,
             scopeKey,
             lastVisitedAt,
             newApprovalIds: pageItems
@@ -8075,6 +8522,23 @@ function consultationRefusal(route, initiatorActorId, actorId) {
     }
     return route === 'subject-agent-rights' && initiatorActorId === actorId ? fourEyesCode : null;
 }
+function isInboxStatus(status) {
+    return status === 'pending' || status === 'awaiting-application' || status === 'execution-unknown';
+}
+/**
+ * The time the inbox lists a proposal by, as the server: a pending one by its expiry, one handed to the
+ * application by its report deadline, an uncertain execution by its decision.
+ */
+function inboxSortAt(proposal, status) {
+    switch (status) {
+        case 'awaiting-application':
+            return proposal.executionReportDueAt ?? proposal.expiresAt;
+        case 'execution-unknown':
+            return proposal.decidedAt ?? proposal.createdAt;
+        default:
+            return proposal.expiresAt;
+    }
+}
 /** The scope of the inbox's visits: `global`, or the scope key of a division. */
 function scopeKeyOf(divisionId) {
     return divisionId === null ? 'global' : `division:${divisionId.replaceAll('-', '').toLowerCase()}`;
@@ -8209,6 +8673,8 @@ const NH_ASSISTANT_MOCK_SCENARIO = new InjectionToken('NH_ASSISTANT_MOCK_SCENARI
 const NH_ASSISTANT_MOCK_HUB_PATH = '/hub/assistant-mock';
 const defaultLimits = { maxMessageChars: 4_000, maxToolCallsPerTurn: 8 };
 const defaultUser = { actorId: 'mock-user', displayName: 'You' };
+/** The tool of `ask_question`, as the server records its call. */
+const askQuestionToolId = 'assistant.ask-question';
 /** When the scenario's consultations started, when they name no time. */
 const consultationStart = new Date().toISOString();
 class RunStopped extends Error {
@@ -8224,6 +8690,7 @@ class NhAssistantMockBackend {
         this.config = inject(NH_ASSISTANT_CONFIG);
         this.conversations = new Map();
         this.pendingApprovals = new Map();
+        this.pendingQuestions = new Map();
         this.runs = new Map();
         /** Page context of the latest message per conversation, as the server stores it. */
         this.pageContexts = new Map();
@@ -8543,6 +9010,7 @@ class NhAssistantMockBackend {
             if (method === 'DELETE') {
                 this.conversations.delete(conversation.id);
                 this.pendingApprovals.delete(conversation.id);
+                this.pendingQuestions.delete(conversation.id);
                 this.emitLive({ kind: 'removed', data: { conversationId: conversation.id } });
                 return this.empty(204);
             }
@@ -8587,6 +9055,12 @@ class NhAssistantMockBackend {
         if (method === 'POST' && segments.length === 5 && segments[2] === 'approvals' && segments[4] === 'decide') {
             return this.decide(conversation, segments[3], body);
         }
+        if (method === 'POST' && segments.length === 5 && segments[2] === 'approvals' && segments[4] === 'resolve') {
+            return this.resolve(conversation, segments[3], body);
+        }
+        if (method === 'POST' && segments.length === 5 && segments[2] === 'questions' && segments[4] === 'answer') {
+            return this.answer(conversation, segments[3], body);
+        }
         return this.empty(404);
     }
     list(query) {
@@ -8630,7 +9104,10 @@ class NhAssistantMockBackend {
         if (filesCode) {
             return this.error(filesCode);
         }
-        if (!acceptsMessage(conversation.status)) {
+        // Like the server: a question or an approval that passed its lifetime closes as expired, and the
+        // message starts its turn (CS9).
+        this.closeExpiredWait(conversation);
+        if (!acceptsMessage(this.conversations.get(conversation.id)?.status ?? conversation.status)) {
             return this.empty(409);
         }
         // Like the server: an invalid page context is dropped, never a 400.
@@ -8730,12 +9207,114 @@ class NhAssistantMockBackend {
             }
         });
     }
+    /**
+     * `POST conversations/{id}/approvals/{approvalId}/resolve`: the person who approved a proposal in this
+     * chat resolves its uncertain hand-off (`canResolve`), as the server does: `hand-to-application` hands
+     * it to the application again with a new report deadline, `mark-resolved` confirms it. Another action
+     * is refused, as are an approval in another status and one the caller may not resolve. Returns the
+     * conversation.
+     */
+    resolve(conversation, approvalId, request) {
+        const part = conversation.messages
+            .flatMap(message => message.parts)
+            .find((item) => item.type === 'approval' && item.approvalId === approvalId);
+        if (!part) {
+            return this.error('assistant-approval-not-found');
+        }
+        const action = request?.action;
+        if (action !== 'hand-to-application' && action !== 'mark-resolved') {
+            return this.error('assistant-approval-decision-invalid');
+        }
+        if (part.status !== 'execution-unknown') {
+            return this.error('assistant-execution-not-uncertain');
+        }
+        if (part.canResolve !== true) {
+            return this.error('assistant-approval-forbidden');
+        }
+        const reportDueAt = new Date(Date.now() + mockReportWithinMs).toISOString();
+        this.update(conversation.id, current => withResolvedApproval(current, approvalId, action, reportDueAt));
+        return this.json(200, this.view(this.conversations.get(conversation.id) ?? conversation));
+    }
+    /**
+     * `POST conversations/{id}/questions/{questionId}/answer`: the addressee answers the question the
+     * turn waits for with the index of a choice, as on the server. Anyone else is refused, as are a
+     * choice the question does not offer and a question whose wait ended, which releases the
+     * conversation. The answer resumes the turn with the step's answered steps.
+     */
+    answer(conversation, questionId, request) {
+        const pending = this.pendingQuestions.get(conversation.id);
+        const known = conversation.messages.some(message => message.parts.some(part => part.type === 'question' && part.questionId === questionId));
+        if (!known) {
+            return this.error('assistant-question-not-found');
+        }
+        if (pending?.question.questionId === questionId && pending.question.addresseeActorId !== this.currentUser.actorId) {
+            return this.error('assistant-question-forbidden');
+        }
+        if (!pending || pending.question.questionId !== questionId) {
+            return this.error('assistant-question-not-pending');
+        }
+        const choice = request?.choice;
+        if (typeof choice !== 'number' || !Number.isInteger(choice) || choice < 0 || choice >= pending.question.choices.length) {
+            return this.error('assistant-question-answer-invalid');
+        }
+        if (Date.parse(pending.question.expiresAt) <= Date.now()) {
+            this.pendingQuestions.delete(conversation.id);
+            this.update(conversation.id, current => withClosedQuestion(current, questionId, 'expired'));
+            return this.error('assistant-question-expired');
+        }
+        this.pendingQuestions.delete(conversation.id);
+        this.activeActors.set(conversation.id, this.currentUser.actorId);
+        const lastUser = [...conversation.messages].reverse().find(message => message.role === 'user');
+        this.update(conversation.id, current => applyNhAssistantQuestionAnswer(current, questionId, choice));
+        const answer = pending.question.choices[choice];
+        const steps = typeof pending.step.answered === 'function' ? pending.step.answered(answer, choice) : pending.step.answered;
+        const assistantMessageId = this.nextId();
+        return this.stream(conversation.id, async (emit) => {
+            await emit({ type: 'turn.started', data: { turnId: this.nextId(), userMessageId: lastUser?.id ?? questionId, assistantMessageId } });
+            await emit({
+                type: 'tool.completed',
+                data: { invocationId: questionId, status: 'succeeded', resultCode: null, resultPreview: JSON.stringify({ answer }) }
+            });
+            await emit({
+                type: 'question.answered',
+                data: { ...pending.question, status: 'answered', answerIndex: choice, closedAt: new Date().toISOString() }
+            });
+            await this.playSteps(conversation.id, assistantMessageId, steps, emit);
+        });
+    }
+    /**
+     * Closes the question or the approval a chat waits for once its lifetime passed, as a late answer or
+     * decision closes it on the server; one that is still valid keeps the chat busy. Agent threads keep
+     * their own rules.
+     */
+    closeExpiredWait(conversation) {
+        if (conversation.status !== 'waiting-for-approval' || conversation.kind === 'thread') {
+            return;
+        }
+        const now = Date.now();
+        const question = this.pendingQuestions.get(conversation.id);
+        if (question && Date.parse(question.question.expiresAt) <= now) {
+            this.pendingQuestions.delete(conversation.id);
+            this.update(conversation.id, current => withClosedQuestion(current, question.question.questionId, 'expired'));
+            return;
+        }
+        const pending = this.pendingApprovals.get(conversation.id);
+        if (pending && Date.parse(pending.approval.expiresAt) <= now) {
+            this.pendingApprovals.delete(conversation.id);
+            this.update(conversation.id, current => withExpiredApproval(current, pending.approval.approvalId, pending.invocationId));
+        }
+    }
     cancel(conversation) {
         const run = this.runs.get(conversation.id);
         if (run) {
             run.cancelled = true;
             return this.empty(202);
         }
+        const question = this.pendingQuestions.get(conversation.id);
+        if (question) {
+            this.pendingQuestions.delete(conversation.id);
+            this.update(conversation.id, current => withClosedQuestion(current, question.question.questionId, 'cancelled'));
+        }
         const pending = this.pendingApprovals.get(conversation.id);
         if (pending) {
             this.pendingApprovals.delete(conversation.id);
@@ -8786,6 +9365,12 @@ class NhAssistantMockBackend {
                 await emit({ type: 'turn.completed', data: { turnId: this.nextId(), status: 'waiting-for-approval', usage, errorCode: null } });
                 return;
             }
+            else if ('question' in step) {
+                await this.pauseForQuestion(conversationId, step.question, emit);
+                usage.toolCalls++;
+                await emit({ type: 'turn.completed', data: { turnId: this.nextId(), status: 'waiting-for-approval', usage, errorCode: null } });
+                return;
+            }
             else if ('error' in step) {
                 await emit({ type: 'error', data: step.error });
                 // The mock keeps the conversation usable after a failed turn.
@@ -8853,6 +9438,31 @@ class NhAssistantMockBackend {
         this.pendingApprovals.set(conversationId, { approval, invocationId, assistantMessageId, step });
         await emit({ type: 'approval.required', data: approval });
     }
+    /** Records the `ask_question` call and posts the question; the turn then waits for its answer. */
+    async pauseForQuestion(conversationId, step, emit) {
+        const questionId = this.nextId();
+        await emit({
+            type: 'tool.started',
+            data: {
+                invocationId: questionId,
+                toolId: askQuestionToolId,
+                toolVersion: 1,
+                displayName: 'ask_question',
+                argumentsPreview: JSON.stringify({ question: step.question, choices: step.choices })
+            }
+        });
+        const question = {
+            type: 'question',
+            questionId,
+            question: step.question,
+            choices: [...step.choices],
+            addresseeActorId: step.addresseeActorId ?? this.activeActors.get(conversationId) ?? this.currentUser.actorId,
+            expiresAt: new Date(Date.now() + (step.expiresInSeconds ?? 900) * 1000).toISOString(),
+            status: 'pending'
+        };
+        this.pendingQuestions.set(conversationId, { question, step });
+        await emit({ type: 'question.asked', data: question });
+    }
     stream(conversationId, play) {
         const timing = this.scenario.timing ?? {};
         const firstDelay = timing.firstEventDelayMs ?? 200;
@@ -9233,6 +9843,72 @@ function withMovedApproval(conversation, approvalId, movedToApprovalId) {
         messages: conversation.messages.map(message => ({ ...message, parts: message.parts.map(moved) }))
     };
 }
+/** How long the mock's application may take to report after a hand-off. */
+const mockReportWithinMs = 4 * 60 * 60 * 1000;
+/**
+ * The approval after its uncertain hand-off was resolved: handed to the application again, waiting for
+ * its report until `reportDueAt`, or resolved. Either way nobody resolves it again.
+ */
+function withResolvedApproval(conversation, approvalId, action, reportDueAt) {
+    const resolved = (part) => {
+        if (part.type !== 'approval' || part.approvalId !== approvalId) {
+            return part;
+        }
+        const { canResolve: _resolved, ...rest } = part;
+        return action === 'hand-to-application'
+            ? { ...rest, status: 'awaiting-application', executionResultCode: 'hand-off-acknowledged', executionReportDueAt: reportDueAt }
+            : { ...rest, status: 'resolved', executionResultCode: 'resolved-by-approver' };
+    };
+    return {
+        ...conversation,
+        messages: conversation.messages.map(message => ({ ...message, parts: message.parts.map(resolved) }))
+    };
+}
+/**
+ * A question that closed without an answer, as the server reads it afterwards: expired or withdrawn
+ * with its stopped turn. Its call ends, and the conversation takes the next message.
+ */
+function withClosedQuestion(conversation, questionId, status) {
+    const closedAt = new Date().toISOString();
+    const closed = (part) => {
+        if (part.type === 'question' && part.questionId === questionId) {
+            return { ...part, status, closedAt };
+        }
+        if (part.type === 'tool-call' && part.invocationId === questionId) {
+            return status === 'expired'
+                ? { ...part, status: 'failed', resultCode: 'assistant-question-expired' }
+                : { ...part, status: 'not-executed', resultCode: 'assistant-question-cancelled' };
+        }
+        return part;
+    };
+    return {
+        ...conversation,
+        status: 'idle',
+        pendingQuestion: null,
+        messages: conversation.messages.map(message => ({ ...message, parts: message.parts.map(closed) }))
+    };
+}
+/**
+ * An approval that passed its lifetime, as the server closes it when the next message arrives: it
+ * expired, its call failed with `assistant-approval-expired`, and the conversation takes the message.
+ */
+function withExpiredApproval(conversation, approvalId, invocationId) {
+    const expired = (part) => {
+        if (part.type === 'approval' && part.approvalId === approvalId) {
+            return { ...part, status: 'expired' };
+        }
+        if (part.type === 'tool-call' && part.invocationId === invocationId) {
+            return { ...part, status: 'failed', resultCode: 'assistant-approval-expired' };
+        }
+        return part;
+    };
+    return {
+        ...conversation,
+        status: 'idle',
+        pendingApproval: null,
+        messages: conversation.messages.map(message => ({ ...message, parts: message.parts.map(expired) }))
+    };
+}
 /** Like the server: a new message starts in an idle conversation or after a failed turn. */
 function acceptsMessage(status) {
     return status === 'idle' || status === 'failed';