ai-foreman 1.7.17 → 1.7.19

package/dist/adapters/claude.js

@@ -1,3 +1,4 @@
+import { OperationDeadline } from "../util/deadline.js";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
@@ -11,12 +12,14 @@ export async function requireClaudeSDK() {
             "Or use Codex for this run with --agent codex.");
     }
 }
+import { QuestionRoundTripTrace } from "../questionTrace.js";
 import { AsyncQueue } from "../util/asyncQueue.js";
-import { BuilderEventQueue, withActivityPhase } from "../activity.js";
+import { BuilderEventQueue, currentActivity, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 import { classifyClaudeSdkFailure, resolveExecutablePath, sanitizeDiagnostics, } from "../runtimeReadiness.js";
 import { createProviderSessionRef, validateProviderSessionScope, canonicalSessionPath } from "../sessionIdentity.js";
 import { SessionUnavailableError, sessionUnavailableResult } from "./sessionFailure.js";
+const DEFAULT_PROVIDER_IDLE_TIMEOUT_MS = 30 * 60_000;
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
@@ -177,6 +180,8 @@ export class ClaudeAdapter {
     structuredError;
     apiErrorStatus;
     compactResult;
+    manualCompactionDeadline;
+    compactionPromise;
     autoCompactionPrepared = false;
     preparedAutoCompactThreshold;
     preparedAutoCompactionPolicy;
@@ -189,6 +194,8 @@ export class ClaudeAdapter {
     activeProviderTurnSpanId;
     toolSpans = new Map();
     pending;
+    questionTrace;
+    responseOnlyTurn = false;
     terminalResult;
     streamEnded = false;
     closed = false;
@@ -239,6 +246,10 @@ export class ClaudeAdapter {
             this.rejectSessionIdentity = reject;
         });
         void this.sessionIdentityReady.catch(() => { });
+        this.questionTrace = new QuestionRoundTripTrace(opts.runtimePhase ?? "builder", opts.onQuestionTrace, opts.observer ? {
+            start: (attemptId) => opts.observer.store.startSpan(this.observationContext(), { kind: "provider_wait", name: "Waiting for Claude after question answer", attributes: { attemptId } }),
+            finish: (spanId, outcome) => opts.observer.store.finishSpan(spanId, { outcome }),
+        } : undefined);
         this.query = query({
             prompt: this.inbox,
             options: {
@@ -258,18 +269,38 @@ export class ClaudeAdapter {
                                 }] }] },
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
-                    const decision = await opts.permission({
-                        toolName,
-                        input,
-                        signal: requestOptions.signal,
-                        title: requestOptions.title,
-                        displayName: requestOptions.displayName,
-                        description: requestOptions.description,
-                        decisionReason: requestOptions.decisionReason,
-                        blockedPath: requestOptions.blockedPath,
-                        toolUseID: requestOptions.toolUseID,
-                    });
-                    return permissionDecisionToClaudeResult(decision, requestOptions.toolUseID);
+                    if (this.responseOnlyTurn)
+                        return { behavior: "deny", message: "QA response correction forbids all tools, including read-only tools", interrupt: true };
+                    const isProviderQuestion = toolName === "AskUserQuestion";
+                    const questionAttempt = isProviderQuestion ? this.questionTrace?.begin() : undefined;
+                    if (isProviderQuestion)
+                        this.beginProviderQuestionWait();
+                    try {
+                        const decision = await opts.permission({
+                            toolName,
+                            input,
+                            signal: requestOptions.signal,
+                            title: requestOptions.title,
+                            displayName: requestOptions.displayName,
+                            description: requestOptions.description,
+                            decisionReason: requestOptions.decisionReason,
+                            blockedPath: requestOptions.blockedPath,
+                            toolUseID: requestOptions.toolUseID,
+                        });
+                        const result = permissionDecisionToClaudeResult(decision, requestOptions.toolUseID);
+                        if (questionAttempt)
+                            this.questionTrace?.returned(questionAttempt, decision.behavior === "allow" ? "allowed" : "denied");
+                        if (isProviderQuestion)
+                            this.endProviderQuestionWait(decision.behavior === "allow");
+                        return result;
+                    }
+                    catch (error) {
+                        if (questionAttempt)
+                            this.questionTrace?.returned(questionAttempt, "callback-error");
+                        if (isProviderQuestion)
+                            this.endProviderQuestionWait(false);
+                        throw error;
+                    }
                 },
             },
         });
@@ -283,6 +314,7 @@ export class ClaudeAdapter {
             }
         }
         catch (err) {
+            this.questionTrace?.finish(this.closed ? "closed" : "stream-error");
             // Suppress the AbortError that fires when close() aborts the stream.
             const isShutdownAbort = this.closed &&
                 (err instanceof Error &&
@@ -298,6 +330,7 @@ export class ClaudeAdapter {
             }
         }
         finally {
+            this.questionTrace?.finish(this.closed ? "closed" : "stream-ended");
             this.streamEnded = true;
             if (!this.closed && this.pending) {
                 const result = this.streamFailureResult("Claude stream ended without a result", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId));
@@ -313,6 +346,16 @@ export class ClaudeAdapter {
         }
     }
     handle(msg) {
+        const questionStreamOutcome = msg.type === "system" && msg.subtype === "api_retry" ? "provider-retry"
+            : msg.type === "auth_status" && msg.error ? "provider-auth-error"
+                : msg.type === "assistant" && (msg.error === "authentication_failed" || msg.error === "oauth_org_not_allowed") ? "provider-auth-error"
+                    : msg.type === "assistant" && msg.error ? "provider-error" : "stream-message";
+        this.questionTrace?.message(questionStreamOutcome);
+        if (this.pending?.providerQuestionAnswered && !this.pending.providerQuestionWaits) {
+            this.pending.providerQuestionAnswered = false;
+            currentActivity()?.update("Claude stream resumed");
+        }
+        this.touchPendingTurn();
         if ("session_id" in msg && typeof msg.session_id === "string") {
             this.observeSession(msg.session_id, "cwd" in msg && typeof msg.cwd === "string" ? msg.cwd : undefined);
         }
@@ -356,8 +399,11 @@ export class ClaudeAdapter {
                 this.turnSignals.push(...msg.output.map((line) => `auth: ${line}`));
         }
         else if (msg.type === "system" && msg.subtype === "status") {
-            if (msg.status === "compacting")
+            if (msg.status === "compacting") {
+                if (this.manualCompactionInFlight && msg.session_id === this._sessionId)
+                    this.manualCompactionDeadline?.extendForCorrelatedProgress();
                 this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
+            }
             if (msg.compact_result === "success") {
                 this.compactResult = { ok: true };
                 this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
@@ -462,7 +508,10 @@ export class ClaudeAdapter {
             this.stderrChunks.length = 0;
         }
     }
-    async sendTurn(text) {
+    async sendTurn(text, policy) {
+        if (this.pending)
+            throw new Error("a turn is already in progress");
+        this.responseOnlyTurn = Boolean(policy?.responseOnly);
         const turnId = randomUUID();
         this.activeProviderTurnId = turnId;
         const observer = this.opts.observer;
@@ -472,6 +521,7 @@ export class ClaudeAdapter {
             }
             finally {
                 this.activeProviderTurnId = undefined;
+                this.responseOnlyTurn = false;
             }
         }
         const context = this.observationContext();
@@ -498,6 +548,7 @@ export class ClaudeAdapter {
             }
             this.activeProviderTurnId = undefined;
             this.activeProviderTurnSpanId = undefined;
+            this.responseOnlyTurn = false;
         }
     }
     sendTurnInternal(text) {
@@ -513,7 +564,8 @@ export class ClaudeAdapter {
             this.turnSignals = [];
             this.structuredError = undefined;
             this.apiErrorStatus = undefined;
-            this.pending = { resolve, reject, instruction: text, turnId: this.activeProviderTurnId ?? randomUUID() };
+            const pending = this.pending = { resolve, reject, instruction: text, turnId: this.activeProviderTurnId ?? randomUUID() };
+            this.armPendingTurn(pending);
             this.inbox.push({
                 type: "user",
                 message: { role: "user", content: text },
@@ -562,7 +614,7 @@ export class ClaudeAdapter {
         return this._sessionId;
     }
     sessionRef() { return this._sessionRef; }
-    async prepareSession(timeoutMs = 30_000) {
+    async prepareSession(timeoutMs = this.opts.preparationTimeoutMs ?? 120_000) {
         if (this.closed || this.streamEnded || this.terminalResult)
             throw new Error(this.terminalResult?.text ?? "Claude session is closed");
         if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
@@ -577,7 +629,24 @@ export class ClaudeAdapter {
                     aborted();
                 timer = setTimeout(() => reject(new Error(`Claude did not expose a scoped session identity within ${timeoutMs}ms`)), timeoutMs);
             });
-            const [, ref] = await Promise.race([Promise.all([this.query.initializationResult(), this.sessionIdentityReady]), interrupted]);
+            const prepare = async () => {
+                await this.query.initializationResult();
+                if (!this._sessionRef?.validatedAt && typeof this.query.supportedCommands === "function") {
+                    const commands = await this.query.supportedCommands();
+                    // Some SDK/CLI pairs expose init identity only after their first input.
+                    // Require an advertised built-in local command; never substitute a
+                    // model-generated warm-up for QA's pre-dispatch identity validation.
+                    if (commands.some(command => command.name === "context" && "builtin" in command && command.builtin === true)) {
+                        this.opts.onLifecycleTrace?.({ phase: "local-context-initialization-start", at: new Date().toISOString() });
+                        const result = await this.sendTurn("/context", { responseOnly: true });
+                        this.opts.onLifecycleTrace?.({ phase: "local-context-initialization-complete", at: new Date().toISOString() });
+                        if (result.isError || result.failure || result.costUsd > 0)
+                            throw new Error("Claude local context initialization did not complete without model work");
+                    }
+                }
+                return this.sessionIdentityReady;
+            };
+            const ref = await Promise.race([prepare(), interrupted]);
             if (!ref.validatedAt)
                 throw new Error("Claude session identity was not provider-validated during initialization");
             return ref;
@@ -612,19 +681,38 @@ export class ClaudeAdapter {
         });
     }
     async compact() {
-        return this.opts.observer
+        if (this.compactionPromise)
+            return this.compactionPromise;
+        const operation = this.opts.observer
             ? this.opts.observer.span("compaction", "Claude context compaction", () => this.compactInternal())
             : this.compactInternal();
+        this.compactionPromise = operation;
+        try {
+            return await operation;
+        }
+        finally {
+            if (this.compactionPromise === operation)
+                this.compactionPromise = undefined;
+        }
     }
     async compactInternal() {
         this.compactResult = undefined;
         this.manualCompactionInFlight = true;
+        const normalMs = Math.min(180_000, Math.max(1, this.opts.compactionTimeoutMs ?? 120_000));
+        const deadline = new OperationDeadline("Claude compaction", normalMs, Math.min(180_000, normalMs * 1.5));
+        this.manualCompactionDeadline = deadline;
         let result;
         try {
-            result = await this.sendTurn("/compact");
+            result = await deadline.run(() => this.sendTurn("/compact"), () => this.abort.abort());
+        }
+        catch (error) {
+            const failure = new SessionUnavailableError({ runtime: "claude", phase: "turn", dispatchState: "unknown", executable: this.opts.runtimeExecutable ?? "claude", cwd: this.opts.cwd, diagnostics: String(error) });
+            await this.close();
+            return { ok: false, error: failure.message, failure: failure.failure };
         }
         finally {
             this.manualCompactionInFlight = false;
+            this.manualCompactionDeadline = undefined;
         }
         if (result.failure?.category === "session-unavailable") {
             return { ok: false, error: result.text || result.failure.diagnostics, failure: result.failure };
@@ -634,15 +722,23 @@ export class ClaudeAdapter {
         return { ok: false, error: sanitizeDiagnostics(result.text || "Claude did not emit an explicit compact status") };
     }
     async prepareAutoCompaction(thresholdPercent = this.opts.autoCompactThresholdPercent) {
+        return new OperationDeadline("Claude auto-compaction preparation", this.opts.preparationTimeoutMs ?? 120_000).run(() => this.prepareAutoCompactionInternal(thresholdPercent), () => this.abort.abort());
+    }
+    async prepareAutoCompactionInternal(thresholdPercent = this.opts.autoCompactThresholdPercent) {
         if (thresholdPercent === undefined)
             return;
         const threshold = validThreshold(thresholdPercent);
         if (this.autoCompactionPrepared && this.preparedAutoCompactThreshold === threshold)
             return this.preparedAutoCompactionPolicy;
         this.opts.autoCompactThresholdPercent = threshold;
-        await this.query.initializationResult();
-        await this.query.applyFlagSettings({ autoCompactEnabled: true });
-        const baseline = await this.query.getContextUsage();
+        await new OperationDeadline("Claude initialization", this.opts.preparationTimeoutMs ?? 120_000).run(() => this.query.initializationResult());
+        // The SDK can acknowledge initialization while its CLI is still waiting
+        // for first input. Sending getContextUsage then deadlocks the control
+        // queue, including a later local command. Establish identity first.
+        if (!this._sessionRef?.validatedAt && typeof this.query.supportedCommands === "function")
+            await this.prepareSession();
+        await new OperationDeadline("Claude settings", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.applyFlagSettings({ autoCompactEnabled: true }));
+        const baseline = await new OperationDeadline("Claude context usage", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.getContextUsage());
         if (!Number.isFinite(baseline.maxTokens) || baseline.maxTokens <= 0
             || !Number.isFinite(baseline.autoCompactThreshold) || baseline.autoCompactThreshold === undefined
             || !baseline.isAutoCompactEnabled) {
@@ -655,8 +751,8 @@ export class ClaudeAdapter {
         if (reserve < 0)
             throw new Error("Claude reported an invalid automatic-compaction reserve");
         const requestedWindow = tokenLimit(baseline.maxTokens, threshold) + reserve;
-        await this.query.applyFlagSettings({ autoCompactEnabled: true, autoCompactWindow: requestedWindow });
-        const installed = await this.query.getContextUsage();
+        await new OperationDeadline("Claude settings", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.applyFlagSettings({ autoCompactEnabled: true, autoCompactWindow: requestedWindow }));
+        const installed = await new OperationDeadline("Claude context usage", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.getContextUsage());
         if (!installed.isAutoCompactEnabled || !Number.isFinite(installed.maxTokens) || installed.maxTokens <= 0
             || !Number.isFinite(installed.autoCompactThreshold) || installed.autoCompactThreshold === undefined) {
             throw new Error("Claude did not expose an enabled native automatic-compaction threshold after configuration");
@@ -685,7 +781,7 @@ export class ClaudeAdapter {
     restoreNativeCompactions(compactions) { this.nativeCompactions.unshift(...compactions); }
     async contextUsage() {
         try {
-            const usage = await this.query.getContextUsage();
+            const usage = await new OperationDeadline("Claude context usage", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.query.getContextUsage());
             const result = { used: usage.totalTokens, maximum: usage.maxTokens, percentage: usage.percentage, observedAt: new Date().toISOString(), source: "provider-query" };
             this.eventQueue.push({ kind: "context-usage", ...result });
             return result;
@@ -702,12 +798,13 @@ export class ClaudeAdapter {
             return { ok: false, error: "Claude SDK cannot change reasoning/fast controls on an existing transport" };
         if (settings.model === this.opts.model)
             return { ok: true };
-        const result = await this.sendTurn(`/model ${settings.model ?? "default"}`);
+        const result = await new OperationDeadline("Claude model settings", this.opts.rpcTimeoutMs ?? 60_000).run(() => this.sendTurn(`/model ${settings.model ?? "default"}`), () => this.abort.abort());
         if (result.isError)
             return { ok: false, error: result.text, ...(result.failure ? { failure: result.failure } : {}) };
         this.opts.model = settings.model;
         return { ok: true };
     }
+    observeEvents(listener) { return this.eventQueue.observe(listener); }
     events() {
         return this.eventQueue;
     }
@@ -715,16 +812,18 @@ export class ClaudeAdapter {
         if (this.closed)
             return;
         this.closed = true;
+        this.questionTrace?.finish("closed");
         this.rejectSessionIdentity(new Error("Claude session closed during initialization"));
         this.abort.abort();
         this.inbox.close();
         try {
-            await this.query.interrupt();
+            await new OperationDeadline("Claude interrupt", this.opts.shutdownTimeoutMs ?? 10_000).run(() => this.query.interrupt());
         }
         catch {
             // interrupt is best-effort — ignore if no turn is active
         }
-        await this.pumpDone.catch(() => { });
+        this.query.close?.();
+        await new OperationDeadline("Claude shutdown", this.opts.shutdownTimeoutMs ?? 10_000).run(() => this.pumpDone).catch(() => { });
     }
     failSessionIdentity(error) {
         this.rejectSessionIdentity(error);
@@ -769,10 +868,15 @@ export class ClaudeAdapter {
             this.resolveSessionIdentity(this._sessionRef);
     }
     settlePending(result, emit = true) {
+        this.questionTrace?.finish(result.isError ? "result-error" : "result");
         const pending = this.pending;
         if (!pending)
             return;
         this.pending = undefined;
+        if (pending.idleTimer)
+            clearTimeout(pending.idleTimer);
+        if (pending.hardTimer)
+            clearTimeout(pending.hardTimer);
         if (!result.turnId) {
             result.turnId = pending.turnId;
             result.hostInstruction = pending.instruction;
@@ -785,6 +889,69 @@ export class ClaudeAdapter {
             this.eventQueue.push({ kind: "turn-complete", result, turnId: result.turnId });
         pending.resolve(result);
     }
+    touchPendingTurn() {
+        if (this.pending)
+            this.armPendingTurn(this.pending);
+    }
+    beginProviderQuestionWait() {
+        const pending = this.pending;
+        if (!pending)
+            return;
+        pending.providerQuestionWaits = (pending.providerQuestionWaits ?? 0) + 1;
+        if (pending.idleTimer)
+            clearTimeout(pending.idleTimer);
+        pending.idleTimer = undefined;
+        if (pending.hardTimer) {
+            clearTimeout(pending.hardTimer);
+            pending.hardTimer = undefined;
+            pending.hardRemainingMs = Math.max(0, (pending.hardRemainingMs ?? this.opts.turnDeadlineMs ?? 3_600_000) - (performance.now() - (pending.hardArmedAt ?? performance.now())));
+        }
+    }
+    endProviderQuestionWait(answered) {
+        const pending = this.pending;
+        if (!pending)
+            return;
+        pending.providerQuestionWaits = Math.max(0, (pending.providerQuestionWaits ?? 1) - 1);
+        pending.providerQuestionAnswered ||= answered;
+        if (pending.providerQuestionWaits === 0)
+            this.armPendingTurn(pending);
+    }
+    armPendingTurn(pending) {
+        if (pending.idleTimer)
+            clearTimeout(pending.idleTimer);
+        if ((pending.providerQuestionWaits ?? 0) > 0)
+            return;
+        if (!pending.hardTimer) {
+            pending.hardRemainingMs ??= this.opts.turnDeadlineMs ?? 3_600_000;
+            pending.hardArmedAt = performance.now();
+            pending.hardTimer = setTimeout(() => {
+                if (this.pending !== pending)
+                    return;
+                this.settlePending(this.streamFailureResult("Claude active turn deadline exceeded; dispatched work requires reconciliation", false));
+                void this.close();
+            }, pending.hardRemainingMs);
+            pending.hardTimer.unref();
+        }
+        const timeoutMs = this.providerIdleTimeoutMs();
+        pending.idleTimer = setTimeout(() => {
+            if (this.pending !== pending || this.closed)
+                return;
+            this.questionTrace?.finish("idle-timeout");
+            const context = pending.providerQuestionAnswered ? " after your answer was sent; Claude has not resumed its stream yet" : "";
+            const message = `Claude provider was silent for ${Math.round(timeoutMs / 60_000)} minutes${context}; the turn may have been dispatched and will not be retried automatically`;
+            const result = this.streamFailureResult(message, false);
+            this.eventQueue.push({ kind: "error", message });
+            this.settlePending(result);
+            // Do not leave a hidden stream running after the host has declared its
+            // result uncertain.  close() is intentionally not awaited here.
+            void this.close();
+        }, timeoutMs);
+        pending.idleTimer.unref();
+    }
+    providerIdleTimeoutMs() {
+        const configured = this.opts.providerIdleTimeoutMs;
+        return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PROVIDER_IDLE_TIMEOUT_MS;
+    }
     streamFailureResult(message, sessionUnavailable) {
         if (sessionUnavailable) {
             const availability = {

package/dist/adapters/codex.d.ts

@@ -25,6 +25,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     private usage?;
     private usageRevision;
     private providerSessionUsage?;
+    private turnUsageBaseline?;
     private lastTurnTokens?;
     private stderr;
     private nativeAutoCompactTokenLimit?;
@@ -34,6 +35,9 @@ export declare class CodexAdapter implements BuilderAdapter {
     private nativeCompactions;
     private nativeCompactionSequence;
     private manualCompactionInFlight;
+    private compactionPromise?;
+    private compactionActive;
+    private compactionUncertain;
     private observedToolCalls;
     private activeProviderTurnId?;
     private activeProviderTurnSpanId?;
@@ -43,11 +47,16 @@ export declare class CodexAdapter implements BuilderAdapter {
     buildAppServerArgs(): string[];
     /** Deprecated fixture helper. Runtime execution uses only app-server. */
     buildArgs(instruction: string): string[];
-    sendTurn(instruction: string): Promise<TurnResult>;
+    sendTurn(instruction: string, policy?: {
+        handback?: boolean;
+        responseOnly?: boolean;
+        logicalActionId?: string;
+    }): Promise<TurnResult>;
     private sendTurnInternal;
     compact(): Promise<CompactResult>;
     private compactInternal;
     prepareAutoCompaction(thresholdPercent?: number | undefined): Promise<NativeAutoCompactionPolicy | void>;
+    private prepareAutoCompactionInternal;
     requiresAutoCompactionSetupTurn(): boolean;
     autoCompactionPolicy(): NativeAutoCompactionPolicy | undefined;
     drainNativeCompactions(): NativeCompaction[];
@@ -61,9 +70,11 @@ export declare class CodexAdapter implements BuilderAdapter {
     prepareSession(): Promise<ProviderSessionRefV1>;
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
+    observeEvents(listener: (event: BuilderEvent) => void): () => void;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
     private ensureThread;
+    private ensureThreadInternal;
     private threadAttached;
     private ensureConnection;
     private request;
@@ -71,6 +82,9 @@ export declare class CodexAdapter implements BuilderAdapter {
     private handle;
     private observationContext;
     private waitFor;
+    private traceLifecycle;
+    private touchWaiters;
+    private providerIdleTimeoutMs;
     private disconnect;
     private restartForAutoCompaction;
     private buildSkillsAppendix;