ai-foreman 1.7.18 → 1.7.20

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,8 +12,9 @@ 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";
@@ -178,6 +180,8 @@ export class ClaudeAdapter {
     structuredError;
     apiErrorStatus;
     compactResult;
+    manualCompactionDeadline;
+    compactionPromise;
     autoCompactionPrepared = false;
     preparedAutoCompactThreshold;
     preparedAutoCompactionPolicy;
@@ -190,6 +194,8 @@ export class ClaudeAdapter {
     activeProviderTurnSpanId;
     toolSpans = new Map();
     pending;
+    questionTrace;
+    responseOnlyTurn = false;
     terminalResult;
     streamEnded = false;
     closed = false;
@@ -240,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: {
@@ -259,7 +269,10 @@ export class ClaudeAdapter {
                                 }] }] },
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
+                    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 {
@@ -274,11 +287,16 @@ export class ClaudeAdapter {
                             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 permissionDecisionToClaudeResult(decision, requestOptions.toolUseID);
+                        return result;
                     }
                     catch (error) {
+                        if (questionAttempt)
+                            this.questionTrace?.returned(questionAttempt, "callback-error");
                         if (isProviderQuestion)
                             this.endProviderQuestionWait(false);
                         throw error;
@@ -296,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 &&
@@ -311,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));
@@ -326,6 +346,15 @@ 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);
@@ -370,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" });
@@ -476,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;
@@ -486,6 +521,7 @@ export class ClaudeAdapter {
             }
             finally {
                 this.activeProviderTurnId = undefined;
+                this.responseOnlyTurn = false;
             }
         }
         const context = this.observationContext();
@@ -512,6 +548,7 @@ export class ClaudeAdapter {
             }
             this.activeProviderTurnId = undefined;
             this.activeProviderTurnSpanId = undefined;
+            this.responseOnlyTurn = false;
         }
     }
     sendTurnInternal(text) {
@@ -577,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)
@@ -592,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;
@@ -627,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 };
@@ -649,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) {
@@ -670,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");
@@ -700,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;
@@ -717,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;
     }
@@ -730,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);
@@ -784,12 +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;
@@ -814,6 +901,11 @@ export class ClaudeAdapter {
         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;
@@ -829,11 +921,23 @@ export class ClaudeAdapter {
             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;
-            const context = pending.providerQuestionAnswered ? " after your answer was sent" : "";
+            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 });

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,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     private handle;
     private observationContext;
     private waitFor;
+    private traceLifecycle;
     private touchWaiters;
     private providerIdleTimeoutMs;
     private disconnect;