@agents-ensemble/core 0.13.0 → 0.14.0

package/dist/conductor/conductor-session.js

@@ -4,7 +4,7 @@ import { createAnswerOpenQuestionTool } from '../escalation/answer-open-question
 import { createAskHumanTool } from '../escalation/ask-human-tool.js';
 import { createOpenQuestionListTools } from '../escalation/open-question-list-tools.js';
 import { openQuestionToEscalationRecord } from '../escalation/open-question-to-escalation.js';
-import { OpenQuestionRegistry } from '../escalation/open-question.js';
+import { OpenQuestionRegistry, } from '../escalation/open-question.js';
 import { deny } from '../permission/permission-broker.js';
 import { PermissionPipeline } from '../permission/permission-pipeline.js';
 import { createPermissionDeadlockMonitor, } from '../permission/permission-deadlock-monitor.js';
@@ -37,8 +37,10 @@ import { isOperatorExitCommand } from './operator-exit.js';
 import { isOperatorCloseCommand } from './operator-close.js';
 import { isOperatorReconnectCommand } from './operator-reconnect.js';
 import { assertSessionSidecarMatches, requireSessionSidecarForResume, saveSessionSidecar, SESSION_SIDECAR_VERSION, sessionSidecarPath, } from '../session/session-sidecar.js';
+import { saveSessionStatusLine, sessionStateStorePath, } from '../session/session-state-store.js';
 import { loadToolCallSnapshotHistory, pruneExpiredToolCallSnapshotHistoryFiles, saveToolCallSnapshotHistory, toolCallSnapshotHistoryPath, } from '../session/tool-call-snapshot-history.js';
 import { loadOpenQuestionsStore, openQuestionsStorePath, saveOpenQuestionsStore, } from '../session/open-questions-store.js';
+import { OpenQuestionControlOperationError, startOpenQuestionControlServer, } from '../session/open-question-control.js';
 import { formatPermissionSummaryForOperator } from '../permission/format-permission-summary-for-operator.js';
 import { enrichSessionUsageWithCost } from '../usage/enrich-session-usage-cost.js';
 import { SessionUsageTracker } from '../usage/session-usage-tracker.js';
@@ -54,6 +56,12 @@ import { createRegisterGitHubWatchTool } from '../github/register-github-watch-t
 import { createUnregisterGitHubWatchTool } from '../github/unregister-github-watch-tool.js';
 import { compileConductorSystemPrompt } from '../prompt/compile-system-prompt.js';
 import { loadUserInstructions } from '../prompt/load-user-instructions.js';
+const OPEN_QUESTION_CONTROL_DRAIN_TIMEOUT_MS = 5_000;
+const RECORDED_ANSWER_UNKNOWN_DISPATCH = {
+    outcome: 'unknown',
+    answerStatus: 'recorded',
+    dispatchStatus: 'unknown',
+};
 export async function runConductorSession(options) {
     const userInstructions = await loadUserInstructions({
         userEnsembleRoot: options.mcpConfigOptions?.userEnsembleRoot,
@@ -79,7 +87,11 @@ export async function runConductorSession(options) {
     }
     const escalations = [];
     const openQuestions = new OpenQuestionRegistry();
+    let harnessSocketPath;
+    let openQuestionControlServer;
     const eventQueue = new SessionEventQueue();
+    const openQuestionDispatchReceipts = new WeakMap();
+    const pendingOpenQuestionDispatchReceipts = new Set();
     const dispatchHoldState = createDispatchHoldState();
     const onDispatchHoldChanged = (change) => {
         sessionLogger.emit({
@@ -105,11 +117,11 @@ export async function runConductorSession(options) {
     let resumeToolCallSnapshots = [];
     let toolCallHistoryNeedsRewrite = false;
     if (options.resumeAgentId) {
-        const sidecar = await requireSessionSidecarForResume({
+        const loadedSidecar = await requireSessionSidecarForResume({
             repoRoot: options.repoRoot,
             conductorAgentId: options.resumeAgentId,
         });
-        assertSessionSidecarMatches(sidecar, {
+        assertSessionSidecarMatches(loadedSidecar, {
             conductorAgentId: options.resumeAgentId,
             issueUrl: options.issueUrl,
             repoRoot: options.repoRoot,
@@ -117,6 +129,20 @@ export async function runConductorSession(options) {
             mcpConfigDigest,
             mcpConfigConfigured,
         });
+        // A previously completed lifecycle no longer describes this instance once
+        // resume begins. Persist unknown before restoring or attaching anything so
+        // a crash before the first regular sidecar flush cannot leave stale
+        // `closed` / `exited` data behind.
+        const sidecar = {
+            ...loadedSidecar,
+            lifecycle: 'unknown',
+            harnessSocketPath: undefined,
+            updatedAt: Date.now(),
+        };
+        await saveSessionSidecar(sessionSidecarPath({
+            repoRoot: options.repoRoot,
+            conductorAgentId: options.resumeAgentId,
+        }), sidecar);
         const history = await loadToolCallSnapshotHistory({
             repoRoot: options.repoRoot,
             conductorAgentId: options.resumeAgentId,
@@ -195,12 +221,62 @@ export async function runConductorSession(options) {
         ? new AbortController()
         : undefined;
     const shutdownSignal = options.shutdownSignal ?? shutdownController.signal;
+    const shutdownIntentController = new AbortController();
     const operatorTerminationController = new AbortController();
+    const drainedShutdownController = new AbortController();
     const driverShutdownSignal = AbortSignal.any([
-        shutdownSignal,
+        drainedShutdownController.signal,
         operatorTerminationController.signal,
     ]);
+    const abortAfterOpenQuestionDrain = (controller) => {
+        const activeControlServer = openQuestionControlServer;
+        if (!activeControlServer) {
+            controller.abort();
+            return;
+        }
+        const reportDrainFailure = (error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            sessionLogger.emit({
+                type: 'harness.warning',
+                message: `Open Question control drain failed: ${detail}`,
+            });
+        };
+        const quiescing = activeControlServer.quiesce();
+        if (!activeControlServer.hasInFlightRequests()) {
+            void quiescing.catch(reportDrainFailure);
+            controller.abort();
+            return;
+        }
+        let drainTimeout;
+        const drainDeadline = new Promise((resolve) => {
+            drainTimeout = setTimeout(() => resolve('timeout'), OPEN_QUESTION_CONTROL_DRAIN_TIMEOUT_MS);
+        });
+        const drainResult = quiescing.then(() => 'drained', (error) => {
+            reportDrainFailure(error);
+            return 'failed';
+        });
+        void Promise.race([drainResult, drainDeadline]).then((result) => {
+            if (drainTimeout)
+                clearTimeout(drainTimeout);
+            if (result === 'timeout') {
+                sessionLogger.emit({
+                    type: 'harness.warning',
+                    message: `Open Question control drain exceeded ${OPEN_QUESTION_CONTROL_DRAIN_TIMEOUT_MS}ms; aborting conductor dispatch. Accepted answers may have unknown notification outcomes.`,
+                });
+            }
+            controller.abort();
+        });
+    };
+    const onShutdownSignal = () => {
+        shutdownIntentController.abort();
+        abortAfterOpenQuestionDrain(drainedShutdownController);
+    };
+    shutdownSignal.addEventListener('abort', onShutdownSignal, { once: true });
+    if (shutdownSignal.aborted)
+        onShutdownSignal();
     let unregisterProcessSignalHandlers = () => { };
+    const removeShutdownDrainListener = () => shutdownSignal.removeEventListener('abort', onShutdownSignal);
+    unregisterProcessSignalHandlers = removeShutdownDrainListener;
     if (ownsShutdownController &&
         options.registerProcessSignalHandlers !== false) {
         const onSignal = () => shutdownController.abort();
@@ -209,11 +285,13 @@ export async function runConductorSession(options) {
         unregisterProcessSignalHandlers = () => {
             process.off('SIGINT', onSignal);
             process.off('SIGTERM', onSignal);
+            removeShutdownDrainListener();
         };
     }
     const permissionPipeline = options.permissionPipeline ??
         new PermissionPipeline({ policy: options.permissionPolicy });
     let scheduleSidecarFlush = () => { };
+    let flushSidecar = async () => { };
     let scheduleToolCallHistoryFlush = () => { };
     let flushToolCallHistory = async () => { };
     let toolCallHistoryDirty = toolCallHistoryNeedsRewrite;
@@ -535,9 +613,12 @@ export async function runConductorSession(options) {
             githubMonitorCursor ??= emptyGitHubMonitorCursor();
             return githubMonitorCursor;
         },
-        onRegistered: (registration) => {
+        onRegistered: async (registration) => {
             githubMonitor?.registerPullRequest?.(registration);
-            scheduleSidecarFlush();
+            // Do not report success to the conductor until the explicit watch is
+            // durable. This closes the crash window between the tool result and a
+            // later best-effort flush.
+            await flushSidecar();
         },
     });
     const unregisterGitHubWatchTools = createUnregisterGitHubWatchTool({
@@ -546,9 +627,9 @@ export async function runConductorSession(options) {
             githubMonitorCursor ??= emptyGitHubMonitorCursor();
             return githubMonitorCursor;
         },
-        onUnregistered: (prNumber) => {
+        onUnregistered: async (prNumber) => {
             githubMonitor?.unregisterPullRequest?.(prNumber);
-            scheduleSidecarFlush();
+            await flushSidecar();
         },
     });
     let conductorAgent;
@@ -560,7 +641,20 @@ export async function runConductorSession(options) {
             return usage.cost;
         },
     });
-    const reportSessionStateTool = createReportSessionStateTool();
+    let sessionStateWriteQueue = Promise.resolve();
+    const reportSessionStateTool = createReportSessionStateTool({
+        onReport: (statusLine) => {
+            if (teardownStarted) {
+                throw new Error('report_session_state is unavailable during teardown');
+            }
+            const write = sessionStateWriteQueue.then(() => saveSessionStatusLine(sessionStateStorePath({
+                repoRoot: options.repoRoot,
+                conductorAgentId: conductorAgent.agentId,
+            }), statusLine));
+            sessionStateWriteQueue = write.catch(() => { });
+            return write;
+        },
+    });
     const dispatchHoldTools = createSetDispatchHoldTool({
         state: dispatchHoldState,
         onChanged: onDispatchHoldChanged,
@@ -632,6 +726,7 @@ export async function runConductorSession(options) {
     const sendReconnect = {
         conductorAgentFactory,
         conductorOptions,
+        retrySuppressionSignal: shutdownIntentController.signal,
         onAuthReconnectAttempt: ({ agentId }) => {
             sessionLogger.emit({
                 type: 'conductor.auth.reconnect',
@@ -655,46 +750,59 @@ export async function runConductorSession(options) {
         },
     };
     let sidecarFlushQueue = Promise.resolve();
-    let flushSidecar = async () => { };
-    flushSidecar = () => {
-        const nextFlush = sidecarFlushQueue.then(async () => {
-            const workers = {};
-            for (const [name, worker] of workerSessions) {
-                workers[name] = {
-                    acpSessionId: worker.acpSessionId,
-                    ...(worker.acpCwd ? { acpCwd: worker.acpCwd } : {}),
-                    ...(worker.acpSpawn ? { acpSpawn: worker.acpSpawn } : {}),
-                };
-            }
-            const snapshot = openQuestions.snapshot();
-            const sidecar = {
-                version: SESSION_SIDECAR_VERSION,
-                conductorAgentId: conductorHandle.conductor.agentId,
-                conductorBackend,
-                lazyWorkers: activeLazyWorkers,
-                issueUrl: options.issueUrl,
-                repoRoot: options.repoRoot,
-                profile: structuredClone(activeProfile),
-                ...(options.profilePath ? { profilePath: options.profilePath } : {}),
-                openQuestions: snapshot.openQuestions,
-                sequence: snapshot.sequence,
-                workers,
-                mcpConfigDigest,
-                ...(githubMonitorCursor ? { githubMonitor: githubMonitorCursor } : {}),
-                updatedAt: Date.now(),
+    let terminalLifecycle;
+    const enqueueSidecarWrite = (write) => {
+        const nextWrite = sidecarFlushQueue.then(write);
+        sidecarFlushQueue = nextWrite.catch(() => { });
+        return nextWrite;
+    };
+    const createSessionSidecar = (snapshot, lifecycle) => {
+        const workers = {};
+        for (const [name, worker] of workerSessions) {
+            workers[name] = {
+                acpSessionId: worker.acpSessionId,
+                ...(worker.acpCwd ? { acpCwd: worker.acpCwd } : {}),
+                ...(worker.acpSpawn ? { acpSpawn: worker.acpSpawn } : {}),
             };
-            await saveOpenQuestionsStore(openQuestionsStorePath({
-                repoRoot: options.repoRoot,
-                conductorAgentId: conductorHandle.conductor.agentId,
-            }), snapshot);
-            await saveSessionSidecar(sessionSidecarPath({
-                repoRoot: options.repoRoot,
-                conductorAgentId: conductorHandle.conductor.agentId,
-            }), sidecar);
-        });
-        sidecarFlushQueue = nextFlush.catch(() => { });
-        return nextFlush;
+        }
+        return {
+            version: SESSION_SIDECAR_VERSION,
+            conductorAgentId: conductorHandle.conductor.agentId,
+            conductorBackend,
+            lazyWorkers: activeLazyWorkers,
+            ...(harnessSocketPath ? { harnessSocketPath } : {}),
+            issueUrl: options.issueUrl,
+            repoRoot: options.repoRoot,
+            profile: structuredClone(activeProfile),
+            ...(options.profilePath ? { profilePath: options.profilePath } : {}),
+            openQuestions: snapshot.openQuestions,
+            sequence: snapshot.sequence,
+            workers,
+            mcpConfigDigest,
+            ...((terminalLifecycle ?? lifecycle)
+                ? { lifecycle: terminalLifecycle ?? lifecycle }
+                : {}),
+            ...(githubMonitorCursor ? { githubMonitor: githubMonitorCursor } : {}),
+            updatedAt: Date.now(),
+        };
+    };
+    const persistOpenQuestionsSnapshot = async (snapshot) => {
+        await saveOpenQuestionsStore(openQuestionsStorePath({
+            repoRoot: options.repoRoot,
+            conductorAgentId: conductorHandle.conductor.agentId,
+        }), snapshot);
     };
+    const persistSessionSidecar = async (snapshot, lifecycle) => {
+        await saveSessionSidecar(sessionSidecarPath({
+            repoRoot: options.repoRoot,
+            conductorAgentId: conductorHandle.conductor.agentId,
+        }), createSessionSidecar(snapshot, lifecycle));
+    };
+    flushSidecar = (lifecycle) => enqueueSidecarWrite(async () => {
+        const snapshot = openQuestions.snapshot();
+        await persistOpenQuestionsSnapshot(snapshot);
+        await persistSessionSidecar(snapshot, lifecycle);
+    });
     const reportSidecarFlushFailure = (error) => {
         const detail = error instanceof Error ? error.message : String(error);
         sessionLogger.emit({
@@ -702,6 +810,13 @@ export async function runConductorSession(options) {
             message: `Open Question YAML / session sidecar を保存できませんでした。最新状態から再開できず、直前に保存された状態からの再開になる場合があります。 error=${detail}`,
         });
     };
+    const reportSessionSidecarWriteFailure = (error) => {
+        const detail = error instanceof Error ? error.message : String(error);
+        sessionLogger.emit({
+            type: 'harness.warning',
+            message: `Session sidecar の更新に失敗しました。Open Question YAML の保存は完了しており、sidecar は後続 flush で同期します。 error=${detail}`,
+        });
+    };
     scheduleSidecarFlush = () => {
         void flushSidecar().catch(reportSidecarFlushFailure);
     };
@@ -878,14 +993,16 @@ export async function runConductorSession(options) {
                     sessionLogger.emit({ type: 'session.operator_exit' });
                     workerSession.runtime.cancelAllActivePrompts();
                     operatorRequestedExit = true;
-                    operatorTerminationController.abort();
+                    shutdownIntentController.abort();
+                    abortAfterOpenQuestionDrain(operatorTerminationController);
                     return false;
                 }
                 if (isOperatorCloseCommand(message)) {
                     sessionLogger.emit({ type: 'session.operator_close' });
                     workerSession.runtime.cancelAllActivePrompts();
                     operatorRequestedClose = true;
-                    operatorTerminationController.abort();
+                    shutdownIntentController.abort();
+                    abortAfterOpenQuestionDrain(operatorTerminationController);
                     return false;
                 }
                 if (isOperatorReconnectCommand(message)) {
@@ -919,6 +1036,114 @@ export async function runConductorSession(options) {
         }
     }
     try {
+        openQuestionControlServer = await startOpenQuestionControlServer({
+            listOpenQuestions: () => openQuestions.listOpen(),
+            answerOpenQuestion: async ({ questionId, answer }) => {
+                if (teardownStarted) {
+                    throw new OpenQuestionControlOperationError(-32000, 'The session is shutting down.');
+                }
+                const current = openQuestions.get(questionId);
+                if (!current || current.status !== 'open') {
+                    throw new OpenQuestionControlOperationError(-32004, 'Open Question is not available.');
+                }
+                let accepted = false;
+                let sidecarWriteError;
+                let dispatchReceipt;
+                let answered;
+                const escalatedRecords = [];
+                await enqueueSidecarWrite(async () => {
+                    const stagedOpenQuestions = new OpenQuestionRegistry();
+                    stagedOpenQuestions.restore(openQuestions.snapshot());
+                    const stagedAccepted = submitOperatorInput({
+                        message: answer,
+                        targetOpenQuestionId: questionId,
+                        conductorTurn: sendCount + 1,
+                        openQuestions: stagedOpenQuestions,
+                        escalations: [],
+                        eventQueue: new SessionEventQueue(),
+                        sessionLogger: { emit: () => { } },
+                    });
+                    const stagedAnswer = stagedOpenQuestions.get(questionId);
+                    if (!stagedAccepted ||
+                        !stagedAnswer ||
+                        stagedAnswer.status !== 'answered') {
+                        return;
+                    }
+                    // The Open Questions YAML is the durable commit point. Do not expose
+                    // the answer in the live Registry or event queue until this succeeds.
+                    await persistOpenQuestionsSnapshot(stagedOpenQuestions.snapshot());
+                    // Another answer path may have won while the atomic YAML write was
+                    // in flight. Restore the current Registry snapshot before rejecting.
+                    if (openQuestions.get(questionId)?.status !== 'open') {
+                        await persistOpenQuestionsSnapshot(openQuestions.snapshot());
+                        return;
+                    }
+                    accepted = submitOperatorInput({
+                        message: answer,
+                        targetOpenQuestionId: questionId,
+                        answeredAt: stagedAnswer.answeredAt,
+                        conductorTurn: sendCount + 1,
+                        openQuestions,
+                        escalations,
+                        eventQueue,
+                        sessionLogger,
+                        onEscalated: (record) => escalatedRecords.push(record),
+                        onOperatorMessageQueued: (event) => {
+                            let receipt;
+                            dispatchReceipt = new Promise((resolve, reject) => {
+                                receipt = {
+                                    resolve: () => resolve(),
+                                    reject: (error) => reject(error),
+                                };
+                                openQuestionDispatchReceipts.set(event, receipt);
+                                pendingOpenQuestionDispatchReceipts.add(receipt);
+                            });
+                            void dispatchReceipt.catch(() => { });
+                        },
+                    });
+                    answered = openQuestions.get(questionId);
+                    if (!accepted || !answered || answered.status !== 'answered') {
+                        await persistOpenQuestionsSnapshot(openQuestions.snapshot());
+                        accepted = false;
+                        return;
+                    }
+                    try {
+                        await persistSessionSidecar(openQuestions.snapshot());
+                    }
+                    catch (error) {
+                        // YAML is authoritative and is already durable. Keep the accepted
+                        // answer/notification, report the mirror failure, then repair it.
+                        sidecarWriteError = error;
+                    }
+                });
+                if (!accepted || !answered || answered.status !== 'answered') {
+                    throw new OpenQuestionControlOperationError(-32004, 'Open Question could not be answered.');
+                }
+                for (const record of escalatedRecords) {
+                    try {
+                        options.onEscalated?.(record);
+                    }
+                    catch (error) {
+                        const detail = error instanceof Error ? error.message : String(error);
+                        sessionLogger.emit({
+                            type: 'harness.warning',
+                            message: `Open Question observer callback failed: ${detail}`,
+                        });
+                    }
+                }
+                if (sidecarWriteError !== undefined) {
+                    reportSessionSidecarWriteFailure(sidecarWriteError);
+                    scheduleSidecarFlush();
+                }
+                if (!dispatchReceipt) {
+                    throw new OpenQuestionControlOperationError(-32603, 'The answer was recorded, but its conductor notification was not queued. The outcome is unknown; do not resubmit the answer and inspect the session state.', RECORDED_ANSWER_UNKNOWN_DISPATCH);
+                }
+                await dispatchReceipt;
+                return answered;
+            },
+        });
+        harnessSocketPath = openQuestionControlServer.socketPath;
+        await flushSidecar().catch(reportSidecarFlushFailure);
         const driverResult = await runConductorSessionDriver({
             issueUrl: options.issueUrl,
             initialPrompt: conductorBackend === 'pi'
@@ -979,6 +1204,23 @@ export async function runConductorSession(options) {
                 });
             },
             onSendComplete: recordSendComplete,
+            onDispatchBatchSettled: ({ events, result, error }) => {
+                for (const event of events) {
+                    if (event.type !== 'operator.message')
+                        continue;
+                    const receipt = openQuestionDispatchReceipts.get(event);
+                    if (!receipt)
+                        continue;
+                    openQuestionDispatchReceipts.delete(event);
+                    pendingOpenQuestionDispatchReceipts.delete(receipt);
+                    if (error || result?.status !== 'finished') {
+                        receipt.reject(new OpenQuestionControlOperationError(-32005, 'The answer was recorded and persisted, but conductor notification could not be confirmed. The outcome is unknown; do not resubmit the answer and inspect the session state.', RECORDED_ANSWER_UNKNOWN_DISPATCH));
+                    }
+                    else {
+                        receipt.resolve();
+                    }
+                }
+            },
             onOpenQuestionEnqueued: (question) => {
                 sessionLogger.emit({ type: 'open.question.enqueued', question });
                 options.onOpenQuestionEnqueued?.(question);
@@ -1069,7 +1311,19 @@ export async function runConductorSession(options) {
         }
     }
     finally {
+        const lifecycle = operatorRequestedClose
+            ? 'closed'
+            : operatorRequestedExit
+                ? 'exited'
+                : shutdownSignal.aborted
+                    ? 'interrupted'
+                    : 'unknown';
+        terminalLifecycle = lifecycle;
         teardownStarted = true;
+        for (const receipt of pendingOpenQuestionDispatchReceipts) {
+            receipt.reject(new OpenQuestionControlOperationError(-32005, 'The answer was recorded and persisted, but the conductor session stopped before notification completed. The outcome is unknown; do not resubmit the answer and inspect the session state.', RECORDED_ANSWER_UNKNOWN_DISPATCH));
+        }
+        pendingOpenQuestionDispatchReceipts.clear();
         const forceShutdown = operatorRequestedExit ||
             operatorRequestedClose ||
             shutdownSignal.aborted;
@@ -1095,6 +1349,24 @@ export async function runConductorSession(options) {
             sessionLogger.emit({ type: 'harness.teardown.phase', phase });
         };
         try {
+            const activeControlServer = openQuestionControlServer;
+            openQuestionControlServer = undefined;
+            harnessSocketPath = undefined;
+            if (activeControlServer) {
+                emitTeardownPhase('openQuestionControl');
+                const phaseStart = Date.now();
+                try {
+                    await activeControlServer.close();
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    sessionLogger.emit({
+                        type: 'harness.warning',
+                        message: `Open Question control socket cleanup failed: ${detail}`,
+                    });
+                }
+                teardownPhases.openQuestionControl = Date.now() - phaseStart;
+            }
             disposeOperatorInput?.();
             if (permissionDeadlockMonitor) {
                 emitTeardownPhase('permissionDeadlockMonitor');
@@ -1212,6 +1484,14 @@ export async function runConductorSession(options) {
             }
         }
         finally {
+            try {
+                emitTeardownPhase('flushSidecar');
+                await sessionStateWriteQueue;
+                await flushSidecar(lifecycle);
+            }
+            catch (error) {
+                reportSidecarFlushFailure(error);
+            }
             process.off('SIGINT', onTeardownSignal);
             process.off('SIGTERM', onTeardownSignal);
         }