@newheap/platform-ai-chat 0.19.0 → 0.20.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_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, 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',
@@ -500,6 +508,41 @@ 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;
+    }
     /** Removes a deleted MCP server from the agents it was assigned to. */
     removeServer(serverId) {
         for (const agent of this.agents.values()) {
@@ -2740,10 +2783,14 @@ 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
+                    };
                 })
             ]
         };
@@ -4166,6 +4213,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);
@@ -4468,6 +4563,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 +4593,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') {
@@ -7544,7 +7692,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 +7809,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 +7854,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;
@@ -7895,15 +8060,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 +8084,7 @@ class NhAssistantMockProposals {
         const body = {
             items: pageItems,
             total: items.length,
+            status,
             scopeKey,
             lastVisitedAt,
             newApprovalIds: pageItems
@@ -8075,6 +8248,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 +8399,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 +8416,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 +8736,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 +8781,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) {
@@ -8730,12 +8930,92 @@ 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);
+        });
+    }
     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 +9066,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 +9139,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 +9544,51 @@ 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) }))
+    };
+}
 /** Like the server: a new message starts in an idle conversation or after a failed turn. */
 function acceptsMessage(status) {
     return status === 'idle' || status === 'failed';