@qduc/term2 0.14.0 → 0.16.0

package/dist/services/conversation/conversation-orchestrator.js

@@ -1,7 +1,7 @@
 import { describeError, isAbortLikeError } from '../../utils/error-helpers.js';
 import { createMessageIdFactory } from '../../utils/message-id-factory.js';
 import { isCommandMessage, isUserMessage } from '../../types/message.js';
-import { isDeniedReadApproveAnswer } from '../../contracts/conversation.js';
+import { CHECK_IN_TOOL_NAME, isDeniedReadApproveAnswer } from '../../contracts/conversation.js';
 import { createStreamingSession } from '../../utils/streaming/streaming-session-factory.js';
 import { enhanceApiKeyError, isMaxTurnsError } from '../../utils/conversation/conversation-utils.js';
 import { clearStreamingBotMessage, computeNextMessages } from '../../utils/conversation/apply-conversation-result.js';
@@ -10,6 +10,13 @@ import { ASK_USER_NO_ANSWER_RESULT } from '../../tools/agent/ask-user-constants.
 import { annotateApprovedCommandMessage, filterPendingCommandMessagesForApproval, } from '../approval/approval-presentation-policy.js';
 import { formatUserTurnForDisplay, hasUserTurnContent, injectSkillIntoTurn, normalizeUserTurn, } from '../../types/user-turn.js';
 const REASONING_RESPONSE_THROTTLE_MS = 200;
+function formatRunBudgetEvidence(event) {
+    if (event.type === 'tool_stall') {
+        return `Repeated tool call: ${event.toolName} (${event.count}/${event.threshold})\narguments: ${event.argumentsText}`;
+    }
+    const { evidence } = event;
+    return `${event.stage} budget stage: ${evidence.dimension}; used ${evidence.used}/${evidence.limit}; headroom ${evidence.headroom}`;
+}
 /**
  * Render settled background runs as one instruction to the main agent. Previews
  * are already capped by the notification store, so the full output is offered
@@ -18,9 +25,11 @@ const REASONING_RESPONSE_THROTTLE_MS = 200;
 function formatBackgroundSubagentNotifications(notifications) {
     const completions = notifications.filter((notification) => notification.kind === 'completion');
     const questions = notifications.filter((notification) => notification.kind === 'question');
+    const budgets = notifications.filter((notification) => notification.kind === 'budget');
     const shellCompletions = notifications.filter((notification) => notification.kind === 'shell_completion');
     const shellOutputs = notifications.filter((notification) => notification.kind === 'shell_output');
     const userControls = notifications.filter((notification) => notification.kind === 'user_control');
+    const checkIns = notifications.filter((notification) => notification.kind === 'check_in');
     const sections = [];
     if (completions.length > 0) {
         const noun = completions.length === 1 ? 'run' : 'runs';
@@ -60,6 +69,23 @@ function formatBackgroundSubagentNotifications(notifications) {
             'Decide the answer, investigate it yourself, or escalate to the user if needed. To answer a specific waiting subagent, call send_message({ target, reply_to: messageId, message }). The subagent has no direct user channel; an answer resumes only its waiting tool call.',
         ].join('\n'));
     }
+    if (budgets.length > 0) {
+        const entries = budgets.map((notification) => {
+            const target = notification.name ?? notification.runId;
+            return `- target: ${target} | runId: ${notification.runId} | role: ${notification.role}\n  ${formatRunBudgetEvidence(notification.event)}`;
+        });
+        sections.push([
+            `Background subagent budget/stall evidence (${budgets.length}). This is an automatic system notification, not a user message.`,
+            '',
+            ...entries,
+            '',
+            // Do not offer continue-with-extension: no child-targeted grant API
+            // exists, so the run keeps going inside its own envelope regardless.
+            // Promising an action the parent cannot take produces confident,
+            // ineffective replies and teaches it to ignore this lane.
+            'Judge the evidence and act only if the run is going wrong: steer it with specific corrective guidance via send_message({ target, message }), or stop it with the background task controls. Doing nothing is a valid judgement — the run continues within its own budget and, at critical, ends itself with a summary of what it completed.',
+        ].join('\n'));
+    }
     if (shellCompletions.length > 0) {
         const noun = shellCompletions.length === 1 ? 'job' : 'jobs';
         const entries = shellCompletions.map((notification) => [
@@ -98,6 +124,24 @@ function formatBackgroundSubagentNotifications(notifications) {
             'Assess whether the matched output changes what you should do next and continue through the next necessary steps yourself, telling the user concisely, in your own words, what you concluded.',
         ].join('\n'));
     }
+    if (checkIns.length > 0) {
+        const noun = checkIns.length === 1 ? 'task' : 'tasks';
+        const entries = checkIns.map((notification) => {
+            const { details } = notification;
+            const label = details.kind === 'subagent'
+                ? `background subagent ${details.name ?? details.id} | role: ${details.role} | task: ${details.task}`
+                : `background shell | jobId: ${details.id} | command: ${details.command}`;
+            const elapsedSeconds = Math.round(notification.elapsedMs / 1000);
+            return `- ${label}\n  still running, elapsed ${elapsedSeconds}s, check-in #${notification.checkInIndex}`;
+        });
+        sections.push([
+            `Periodic check-in on ${checkIns.length} still-running background ${noun}. This is an automatic system notification, not a user message, and does not by itself mean anything is wrong.`,
+            '',
+            ...entries,
+            '',
+            'Decide freely: doing nothing and letting it keep running is a valid choice. Only report to the user or intervene (steer or stop the task) if the elapsed time or task nature makes that the right call.',
+        ].join('\n'));
+    }
     if (userControls.length > 0) {
         const stopControls = userControls.filter((notification) => notification.action === 'stop');
         const backgroundMoves = userControls.filter((notification) => notification.action === 'background');
@@ -117,10 +161,19 @@ function formatBackgroundSubagentNotifications(notifications) {
             ].join('\n'));
         }
         if (backgroundMoves.length > 0) {
+            const movedSubagents = backgroundMoves.filter((notification) => notification.details.kind === 'subagent').length;
+            const movedShells = backgroundMoves.length - movedSubagents;
+            const movedWhat = movedSubagents > 0 && movedShells === 0
+                ? movedSubagents === 1
+                    ? 'a foreground subagent into the background'
+                    : 'foreground subagents into the background'
+                : movedShells > 0 && movedSubagents === 0
+                    ? movedShells === 1
+                        ? 'a foreground shell into the background'
+                        : 'foreground shells into the background'
+                    : 'foreground work into the background';
             sections.push([
-                `The user moved ${backgroundMoves.length === 1
-                    ? 'a foreground shell into the background'
-                    : 'foreground shells into the background'}. This is an automatic user control notification, not a user message.`,
+                `The user moved ${movedWhat}. This is an automatic user control notification, not a user message.`,
                 '',
                 ...entriesFor(backgroundMoves, 'moved to'),
                 '',
@@ -141,6 +194,12 @@ function formatBackgroundSubagentNotificationDisplay(notifications) {
                 `question: ${notification.question}`,
             ].join('\n');
         }
+        if (notification.kind === 'budget') {
+            return [
+                `- runId: ${notification.runId} | role: ${notification.role}`,
+                `  ${formatRunBudgetEvidence(notification.event)}`,
+            ].join('\n');
+        }
         if (notification.kind === 'shell_completion') {
             return [
                 `- jobId: ${notification.jobId} | command: ${notification.command} | status: ${notification.status}`,
@@ -155,6 +214,14 @@ function formatBackgroundSubagentNotificationDisplay(notifications) {
                 ...(notification.matchedLines ? [`  matchedLines: ${notification.matchedLines}`] : []),
             ].join('\n');
         }
+        if (notification.kind === 'check_in') {
+            const { details } = notification;
+            const elapsedSeconds = Math.round(notification.elapsedMs / 1000);
+            const label = details.kind === 'subagent'
+                ? `background subagent ${details.name ?? details.id} (${details.role})`
+                : `background shell ${details.command}`;
+            return `Check-in #${notification.checkInIndex}: ${label} still running, elapsed ${elapsedSeconds}s`;
+        }
         if (notification.kind === 'user_control') {
             const details = notification.details;
             if (notification.action === 'background') {
@@ -220,6 +287,9 @@ export class ConversationOrchestrator {
         if (typeof config.conversationService.setQueuedTurnStartObserver === 'function') {
             config.conversationService.setQueuedTurnStartObserver((execution) => {
                 if (execution.suppressUserMessageDisplay) {
+                    // Still retire any matching pending row. A suppressed start is a
+                    // real delivery; leaving the queued indicator would lie.
+                    this.config.ui.onQueuedMessageStarted?.(execution.requestId);
                     return;
                 }
                 // Deferred submissions activate their orchestrator turn here — the only
@@ -280,6 +350,43 @@ export class ConversationOrchestrator {
         this.#editedSteerTurns.clear();
         this.#reportedStrandedCallIds.clear();
     }
+    /**
+     * Replace the live UI projection with a persisted conversation after the
+     * caller has moved the service to the restored session id.
+     */
+    restoreConversation(restored) {
+        this.config.conversationService.importState({
+            history: restored.history,
+            previousResponseId: restored.previousResponseId,
+            toolLedger: restored.toolLedger,
+            updatedAt: restored.updatedAt,
+        });
+        this.config.messages.setMessages(() => [...restored.messages]);
+        this.config.approvedContext.current = null;
+        this.config.conversationService.clearPendingInteraction?.();
+        this.config.ui.onResetAll();
+        this.config.usageAccumulator?.reset();
+        this.config.subagentUsageAccumulator?.reset();
+        this.config.costAccumulator?.reset();
+        if (restored.usage) {
+            this.config.usageAccumulator?.add(restored.usage, { alreadyBillable: true });
+            this.config.ui.onUsageUpdate(restored.usage);
+        }
+        if (restored.subagentUsage) {
+            this.config.subagentUsageAccumulator?.add(restored.subagentUsage, { alreadyBillable: true });
+        }
+        if (restored.costRecords?.length) {
+            const costAccumulator = this.config.costAccumulator;
+            costAccumulator?.addRecords(restored.costRecords);
+            if (costAccumulator)
+                this.config.ui.onCostUpdate?.(costAccumulator.getSummary());
+        }
+        this.#directlyAppendedMessageIds.clear();
+        this.#displayedBackgroundNotificationMessageIds.clear();
+        this.#retractedSteerIds.clear();
+        this.#editedSteerTurns.clear();
+        this.#reportedStrandedCallIds.clear();
+    }
     stopProcessing() {
         // The user asked everything to stop, so background subagent runs go too.
         // Undo and retry, by contrast, only abort the turn.
@@ -291,7 +398,7 @@ export class ConversationOrchestrator {
         this.#stoppingByUser = true;
         try {
             this.config.conversationService.interruptFromUser();
-            this.config.messages.setMessages((messages) => messages.map((message) => message.sender === 'command' && message.status === 'running'
+            this.config.messages.setMessages((messages) => messages.map((message) => message.sender === 'command' && (message.status === 'running' || message.status === 'pending')
                 ? { ...message, status: 'aborted' }
                 : message));
             this.config.approvedContext.current = null;
@@ -392,6 +499,16 @@ export class ConversationOrchestrator {
             this.#endTurn();
         }
     }
+    async compactContext() {
+        this.#activeTurns += 1;
+        this.config.ui.onTurnStart();
+        try {
+            return await this.config.conversationService.compactContext();
+        }
+        finally {
+            this.#endTurn();
+        }
+    }
     async sendUserMessage(input, options) {
         const turn = normalizeUserTurn(input);
         if (!hasUserTurnContent(turn)) {
@@ -428,16 +545,16 @@ export class ConversationOrchestrator {
             messageId: userMessage.id,
         });
         if (queueOwnsSubmission) {
-            // A turn is already in flight or the queue is paused with retained work.
-            // Show the message above the input box until the queue actually starts
-            // processing it; the message list will be updated when the queue pops
-            // this turn.
-            this.config.ui.onQueuedMessagePending?.(userMessage.id, userMessage.text);
+            const delivery = options?.busyMode === 'steer' ? 'steer' : 'follow_up';
             // A steer belongs to the turn already running: hand it to that turn so
             // the model reads it at its next request, rather than making the user
             // wait for the whole turn to end. The message joins the transcript at the
             // moment the turn takes it, which is when the model actually sees it.
-            if (options?.busyMode === 'steer' && this.config.conversationService.steerActiveTurn) {
+            if (delivery === 'steer' && this.config.conversationService.steerActiveTurn) {
+                // Show "Steering" while the active turn may still be waiting for its
+                // next request boundary. A follow-up (Alt+Enter) is the only case that
+                // should read as "Queued" here.
+                this.config.ui.onQueuedMessagePending?.(userMessage.id, userMessage.text, delivery);
                 // Diagnostics for "my steer just queued". The three fields below
                 // separate the ways delivery can fail, which otherwise look identical
                 // in the UI because the queued label is drawn before this even runs:
@@ -485,6 +602,10 @@ export class ConversationOrchestrator {
                     return;
                 }
                 this.#editedSteerTurns.delete(userMessage.id);
+                this.config.ui.onQueuedMessageReclassified?.(userMessage.id, 'follow_up');
+            }
+            else {
+                this.config.ui.onQueuedMessagePending?.(userMessage.id, userMessage.text, delivery);
             }
         }
         else {
@@ -515,7 +636,7 @@ export class ConversationOrchestrator {
             const turnToSend = turn.skill ? injectSkillIntoTurn(turn) : turn;
             const result = await this.config.conversationService.sendMessage(turnToSend, {
                 onEvent: this.createOnEventHandler(applyConversationEvent),
-                bypassInputSurgeGuard: options?.bypassInputSurgeGuard,
+                inputSurgeApproval: options?.inputSurgeApproval,
                 busyMode: options?.busyMode,
                 preferredMessageId: userMessage.id,
             });
@@ -557,10 +678,10 @@ export class ConversationOrchestrator {
             if (isMaxTurnsError(errorMessage)) {
                 const pendingApproval = {
                     agentName: 'System',
-                    toolName: 'max_turns_exceeded',
+                    toolName: CHECK_IN_TOOL_NAME,
                     argumentsText: errorMessage,
                     rawInterruption: null,
-                    isMaxTurnsPrompt: true,
+                    checkIn: 'max_turns',
                 };
                 this.config.conversationService.presentPendingInteraction?.(pendingApproval);
                 this.config.ui.onApprovalRequested(pendingApproval);
@@ -574,6 +695,14 @@ export class ConversationOrchestrator {
             this.#deferredTurnActivators.delete(userMessage.id);
             reasoningUpdater.flush();
             botResponseUpdater.cancel();
+            // The start observer is the normal way a queued row leaves the pending
+            // list. If that callback is skipped — recovered snapshot, suppressed
+            // display, or a test/service path that settles sendMessage without
+            // starting — the submission has still left the queue. Drop the row
+            // here so a delivered message cannot stay painted as queued.
+            if (queueOwnsSubmission) {
+                this.config.ui.onQueuedMessageStarted?.(userMessage.id);
+            }
             if (turnActivated) {
                 this.#endTurn();
             }
@@ -592,7 +721,8 @@ export class ConversationOrchestrator {
         if (resolution.kind === 'awaiting_next_question')
             return;
         const pendingApproval = resolution.approval;
-        const isMaxTurnsPrompt = pendingApproval.isMaxTurnsPrompt;
+        const isMaxTurnsPrompt = pendingApproval.checkIn === 'max_turns';
+        const runBudgetEvent = pendingApproval.runBudgetEvent;
         this.config.ui.onApprovalResolved();
         if (answer === 'y' || isDeniedReadApproveAnswer(answer)) {
             this.config.approvedContext.current = {
@@ -600,11 +730,11 @@ export class ConversationOrchestrator {
                 toolName: pendingApproval.toolName,
             };
         }
-        if (isMaxTurnsPrompt && answer === 'n') {
+        if (isMaxTurnsPrompt && !runBudgetEvent && answer === 'n') {
             this.#endTurn();
             return;
         }
-        if (isMaxTurnsPrompt && answer === 'y') {
+        if (isMaxTurnsPrompt && !runBudgetEvent && answer === 'y') {
             const { botResponseUpdater, reasoningUpdater, applyConversationEvent, streamingState } = this.#beginTurn('maxTurnsContinuation');
             try {
                 const result = await this.config.conversationService.sendMessage('Please continue with your previous task.', {
@@ -629,6 +759,22 @@ export class ConversationOrchestrator {
             }
             return;
         }
+        // Steer is part of the judge's vocabulary, but no human surface produces it
+        // here: the prompt offers Continue and Stop only, and collecting corrective
+        // text would need an input surface this prompt does not own. A human steers
+        // by continuing and then typing. Parent agents steer with send_message.
+        if (runBudgetEvent && answer === 'y') {
+            // Take the grant here rather than leaving it to the resume, because a
+            // refusal has to be shown to the human instead of silently stopping.
+            const grant = this.config.conversationService.grantRunBudgetExtension?.() ?? {
+                granted: false,
+                extensionsGranted: 0,
+            };
+            if (!grant.granted) {
+                this.#presentRunBudgetInteraction(runBudgetEvent, 'No further budget extension is available.');
+                return;
+            }
+        }
         const { botResponseUpdater, reasoningUpdater, applyConversationEvent, streamingState } = this.#beginTurn('approvalDecision');
         try {
             const result = await this.config.conversationService.handleApprovalDecision(answer, rejectionReason, {
@@ -711,10 +857,10 @@ export class ConversationOrchestrator {
             return;
         const stranded = this.config.messages
             .getMessages()
-            .filter((message) => isCommandMessage(message) && message.status === 'running');
+            .filter((message) => isCommandMessage(message) && (message.status === 'running' || message.status === 'pending'));
         if (stranded.length === 0)
             return;
-        this.config.messages.setMessages((messages) => messages.map((message) => message.sender === 'command' && message.status === 'running'
+        this.config.messages.setMessages((messages) => messages.map((message) => message.sender === 'command' && (message.status === 'running' || message.status === 'pending')
             ? { ...message, status: 'aborted' }
             : message));
         const unreported = stranded.filter((message) => !this.#reportedStrandedCallIds.has(message.callId ?? message.id));
@@ -742,7 +888,7 @@ export class ConversationOrchestrator {
         for (const notification of newlyDisplayed) {
             this.#displayedBackgroundNotificationMessageIds.add(notification.messageId);
         }
-        const subagentNotifications = newlyDisplayed.filter((notification) => notification.kind === 'completion' || notification.kind === 'question');
+        const subagentNotifications = newlyDisplayed.filter((notification) => notification.kind === 'completion' || notification.kind === 'question' || notification.kind === 'budget');
         const runs = subagentNotifications
             .filter((notification) => notification.kind === 'completion')
             .map(({ name, role, status, error }) => ({
@@ -754,6 +900,7 @@ export class ConversationOrchestrator {
         const shellJobs = newlyDisplayed.filter((notification) => notification.kind === 'shell_completion');
         const shellOutputs = newlyDisplayed.filter((notification) => notification.kind === 'shell_output');
         const userControls = newlyDisplayed.filter((notification) => notification.kind === 'user_control');
+        const checkIns = newlyDisplayed.filter((notification) => notification.kind === 'check_in');
         this.config.messages.appendMessages([
             ...(subagentNotifications.length > 0
                 ? [
@@ -801,12 +948,14 @@ export class ConversationOrchestrator {
                         success: true,
                         toolName: 'background_shell_output_notification',
                         toolArgs: {
-                            firings: shellOutputs.map(({ jobId, command, watchId, seq, matchedLines, droppedBytes }) => ({
+                            firings: shellOutputs.map(({ jobId, command, watchId, seq, matchedLines, coalescedCount, seqRange, droppedBytes }) => ({
                                 jobId,
                                 command,
                                 watchId,
                                 seq,
                                 matchedLines,
+                                ...(coalescedCount !== undefined ? { coalescedCount } : {}),
+                                ...(seqRange !== undefined ? { seqRange } : {}),
                                 ...(droppedBytes !== undefined ? { droppedBytes } : {}),
                             })),
                         },
@@ -829,6 +978,26 @@ export class ConversationOrchestrator {
                     },
                 ]
                 : []),
+            ...(checkIns.length > 0
+                ? [
+                    {
+                        id: this.createMessageId(),
+                        sender: 'command',
+                        status: 'completed',
+                        command: 'background_check_in_notification',
+                        output: formatBackgroundSubagentNotificationDisplay(checkIns),
+                        success: true,
+                        toolName: 'background_check_in_notification',
+                        toolArgs: {
+                            checkIns: checkIns.map(({ target, checkInIndex, elapsedMs }) => ({
+                                target,
+                                checkInIndex,
+                                elapsedMs,
+                            })),
+                        },
+                    },
+                ]
+                : []),
         ]);
     }
     /**
@@ -922,6 +1091,7 @@ export class ConversationOrchestrator {
             loggingService: this.config.loggingService,
             setLastUsage: (usage) => this.config.ui.onUsageUpdate(usage),
             setCodexRateLimit: (rateLimit) => this.config.ui.onRateLimitUpdate(rateLimit),
+            setRunBudgetNotice: (event) => this.config.ui.onRunBudgetNotice?.(event),
             reasoningThrottleMs: REASONING_RESPONSE_THROTTLE_MS,
             now: this.config.now,
         }, label);
@@ -972,9 +1142,39 @@ export class ConversationOrchestrator {
                 }
                 this.config.costAccumulator?.addRecords(event.result.costRecords ?? []);
                 this.emitCostSummary();
+                if (!this.hasActiveBackgroundWork()) {
+                    this.config.notifier?.turnComplete();
+                }
+            }
+            if (eventType === 'background_shell_completed') {
+                if (!this.hasActiveBackgroundWork()) {
+                    this.config.notifier?.turnComplete();
+                }
             }
         };
     }
+    hasActiveBackgroundWork() {
+        const details = this.config.conversationService?.backgroundTaskControl?.listDetails?.() ?? [];
+        for (const d of details) {
+            if (d.kind === 'subagent') {
+                if (d.status === 'running' ||
+                    d.status === 'awaiting_approval' ||
+                    d.status === 'waiting_for_answer' ||
+                    d.status === 'cancelling') {
+                    return true;
+                }
+            }
+            else if (d.kind === 'shell') {
+                if (d.status === 'running' || d.status === 'cancelling') {
+                    return true;
+                }
+            }
+        }
+        const approvals = this.config.conversationService?.backgroundSubagentApprovals?.getSnapshot?.();
+        if (approvals && approvals.pendingCount > 0)
+            return true;
+        return false;
+    }
     /** Push the accumulator's current summary to the UI after any cost add. */
     emitCostSummary() {
         const summary = this.config.costAccumulator?.getSummary();
@@ -1006,7 +1206,9 @@ export class ConversationOrchestrator {
             clearStreamingBotMessage(streamingState);
         }
         this.config.ui.onApprovalResolved();
-        this.config.notifier?.turnComplete();
+        if (!this.hasActiveBackgroundWork()) {
+            this.config.notifier?.turnComplete();
+        }
         if (result.usage) {
             this.config.usageAccumulator?.add(result.usage);
             this.config.ui.onUsageUpdate(latestStreamedUsage ?? result.usage);
@@ -1067,6 +1269,22 @@ export class ConversationOrchestrator {
             eventType === 'tool_call_streaming_delta' ||
             eventType === 'final');
     }
+    /** Reuse the established pending-approval surface for human budget judgement. */
+    #presentRunBudgetInteraction(event, prefix) {
+        if (this.config.conversationService.getPendingInteractionSnapshot?.())
+            return;
+        const approval = {
+            agentName: 'System',
+            toolName: CHECK_IN_TOOL_NAME,
+            argumentsText: `${prefix ? `${prefix}\n\n` : ''}${formatRunBudgetEvidence(event)}`,
+            rawInterruption: null,
+            checkIn: 'run_budget',
+            runBudgetEvent: event,
+        };
+        this.config.conversationService.presentPendingInteraction?.(approval);
+        this.config.ui.onApprovalRequested(approval);
+        this.config.notifier?.approvalNeeded();
+    }
     appendBotError(errorMessage) {
         const botErrorMessage = {
             id: this.createMessageId(),
@@ -1077,6 +1295,11 @@ export class ConversationOrchestrator {
         this.config.messages.appendMessages([botErrorMessage]);
     }
     logError(message, error) {
+        // Abort-like failures are expected control flow for user cancellation and
+        // must not be emitted as application errors. Keep this at the logging
+        // boundary so every orchestrator call site shares the same classification.
+        if (isAbortLikeError(error))
+            return;
         this.config.loggingService.error(message, {
             error: error instanceof Error ? error.message : String(error),
             stack: error instanceof Error ? error.stack : undefined,