@cortexkit/aft-bridge 0.60.0 → 0.62.0

package/dist/bridge.js

@@ -6,6 +6,7 @@ import { binaryContentHash, binaryStampKey, peekBinaryContentHash } from "./bina
 import { spawn } from "./child-process.js";
 import { isPassiveCommand, PASSIVE_COMMAND_TIMEOUT_MS } from "./command-timeouts.js";
 import { withPathPrepended } from "./path-env.js";
+import { isTerminalBashStatus } from "./protocol.js";
 import { HOST_TOOL_NAMES_FIELD, WORKER_SESSION_FIELD } from "./transport.js";
 const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
 const BRIDGE_HANG_TIMEOUT_THRESHOLD = 2;
@@ -14,19 +15,6 @@ const MAX_STDOUT_BUFFER = 64 * 1024 * 1024; // 64MB
 const MALFORMED_STDOUT_LOG_CHARS = 512;
 const HASHLINE_REGISTRATION_LOG_INTERVAL_MS = 60_000;
 const HASHLINE_REGISTRATION_LOG_STATE_LIMIT = 256;
-const TERMINAL_BASH_STATUSES = new Set([
-    "completed",
-    "failed",
-    "killed",
-    "timed_out",
-    "fate_unknown",
-    // Historical/defensive aliases seen in plugin-side compatibility code.
-    "cancelled",
-    "timeout",
-]);
-function isTerminalBashStatus(status) {
-    return typeof status === "string" && TERMINAL_BASH_STATUSES.has(status);
-}
 function bashTaskIdFrom(response) {
     const snakeCase = response.task_id;
     if (typeof snakeCase === "string" && snakeCase.length > 0)
@@ -115,47 +103,49 @@ export function shouldSurfaceStderrLine(line) {
         normalized === BENIGN_CPUINFO_PROC_CPUINFO_PARSE_FAILURE);
 }
 export function compareSemver(a, b) {
-    const [aMain, aPre] = a.split("-", 2);
-    const [bMain, bPre] = b.split("-", 2);
-    const aParts = aMain.split(".").map(Number);
-    const bParts = bMain.split(".").map(Number);
+    const parse = (version) => {
+        const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(version);
+        const pre = match?.[4]?.split(".") ?? [];
+        if (!match || pre.some((id) => /^\d+$/.test(id) && id.length > 1 && id[0] === "0")) {
+            throw new Error(`Invalid semantic version: ${version}`);
+        }
+        return { core: match.slice(1, 4), pre };
+    };
+    // Compare numeric identifiers as strings so even large valid identifiers
+    // retain their order without Number rounding or overflow.
+    const numeric = (a, b) => a.length !== b.length ? a.length - b.length : a === b ? 0 : a < b ? -1 : 1;
+    const left = parse(a);
+    const right = parse(b);
     for (let i = 0; i < 3; i++) {
-        if (aParts[i] !== bParts[i])
-            return (aParts[i] ?? 0) - (bParts[i] ?? 0);
-    }
-    if (!aPre && !bPre)
-        return 0;
-    if (!aPre)
-        return 1;
-    if (!bPre)
-        return -1;
-    const aIds = aPre.split(".");
-    const bIds = bPre.split(".");
-    for (let i = 0; i < Math.max(aIds.length, bIds.length); i++) {
-        const ai = aIds[i];
-        const bi = bIds[i];
+        const diff = numeric(left.core[i], right.core[i]);
+        if (diff !== 0)
+            return diff;
+    }
+    if (left.pre.length === 0 || right.pre.length === 0) {
+        return left.pre.length === right.pre.length ? 0 : left.pre.length === 0 ? 1 : -1;
+    }
+    for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+        const ai = left.pre[i];
+        const bi = right.pre[i];
         if (ai === undefined)
             return -1;
         if (bi === undefined)
             return 1;
         const aNum = /^\d+$/.test(ai);
         const bNum = /^\d+$/.test(bi);
-        if (aNum && bNum) {
-            const diff = Number.parseInt(ai, 10) - Number.parseInt(bi, 10);
-            if (diff !== 0)
-                return diff;
-        }
-        else if (aNum) {
-            return -1;
-        }
-        else if (bNum) {
-            return 1;
-        }
-        else {
-            const cmp = ai.localeCompare(bi);
-            if (cmp !== 0)
-                return cmp;
-        }
+        const diff = aNum && bNum
+            ? numeric(ai, bi)
+            : aNum !== bNum
+                ? aNum
+                    ? -1
+                    : 1
+                : ai === bi
+                    ? 0
+                    : ai < bi
+                        ? -1
+                        : 1;
+        if (diff !== 0)
+            return diff;
     }
     return 0;
 }
@@ -195,13 +185,45 @@ export class BridgeTransportTimeoutError extends Error {
     command;
     timeoutMs;
     code = "transport_timeout";
-    constructor(command, timeoutMs, message) {
+    /**
+     * For a `bash`/`powershell` call, what the bridge learned about the command
+     * while it waited a short grace period after the deadline. Undefined for
+     * other commands.
+     */
+    shellOutcome;
+    constructor(command, timeoutMs, message, shellOutcome) {
         super(message);
         this.command = command;
         this.timeoutMs = timeoutMs;
         this.name = "BridgeTransportTimeoutError";
+        this.shellOutcome = shellOutcome;
     }
 }
+/** Commands that start a shell task in AFT and answer with its task id. */
+const SHELL_TASK_COMMANDS = new Set(["bash", "powershell"]);
+/**
+ * How long a timed-out shell call keeps listening for AFT's late reply. AFT
+ * can start the command and answer just after the bridge's deadline (for
+ * example while it is busy with other work); that reply carries the task id,
+ * which is the only way the agent can find the running command. Kept short
+ * because the agent waits this much longer for its error.
+ */
+const DEFAULT_LATE_SHELL_REPLY_GRACE_MS = 10_000;
+function shellOutcomeFromLateReply(response) {
+    const taskId = bashTaskIdFrom(response);
+    if (taskId)
+        return { kind: "task_started", taskId };
+    if (response.success === false) {
+        return {
+            kind: "not_started",
+            ...(typeof response.code === "string" ? { code: response.code } : {}),
+            ...(typeof response.message === "string" ? { message: response.message } : {}),
+        };
+    }
+    // A successful reply without a task id is not a shape AFT sends for a shell
+    // command, so it proves nothing either way.
+    return { kind: "unknown" };
+}
 /** A standalone bridge cannot carry a request because its process transport died. */
 export class BridgeTransportUnavailableError extends Error {
     code = "bridge_transport_unavailable";
@@ -279,6 +301,7 @@ export class BinaryBridge {
     _shuttingDown = false;
     timeoutMs;
     hangThreshold;
+    lateShellReplyGraceMs;
     maxRestarts;
     configured = false;
     _configurePromise = null;
@@ -296,6 +319,7 @@ export class BinaryBridge {
     statusListeners = new Set();
     /** Notification clients keyed by session_id for async configure warning pushes. */
     configureWarningClients = new Map();
+    restartTimer = null;
     restartResetTimer = null;
     /** Updated after every successfully parsed stdout frame from the child. */
     lastChildActivityAt = 0;
@@ -314,6 +338,8 @@ export class BinaryBridge {
         this.cwd = cwd;
         this.timeoutMs = options?.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS;
         this.hangThreshold = options?.hangThreshold ?? BRIDGE_HANG_TIMEOUT_THRESHOLD;
+        this.lateShellReplyGraceMs =
+            options?.lateShellReplyGraceMs ?? DEFAULT_LATE_SHELL_REPLY_GRACE_MS;
         this.maxRestarts = options?.maxRestarts ?? 3;
         this.errorPrefix = options?.errorPrefix ?? "[aft-bridge]";
         // P1 config relocation: semantic config now arrives as raw `config` tiers and
@@ -666,13 +692,6 @@ export class BinaryBridge {
                 ? params.session_id
                 : undefined;
             this.ensureSpawned(requestSessionId);
-            // Auto-configure can reuse the initiating session's notification client
-            // when the deferred configure warning frame arrives later. One project
-            // bridge can serve many sessions, so keep this per-session instead of one
-            // bridge-wide "last client".
-            if (requestSessionId && options?.configureWarningClient !== undefined) {
-                this.configureWarningClients.set(requestSessionId, options.configureWarningClient);
-            }
             // Per-op timeout override: tool wrappers can pass longer budgets for
             // commands that legitimately need them (callers, trace_to, grep on big
             // repos). Defaults to the bridge-wide timeout otherwise.
@@ -697,6 +716,13 @@ export class BinaryBridge {
             if (!this.configured) {
                 if (command !== "configure" && command !== "version") {
                     if (!this._configurePromise) {
+                        // Only the initiating session owns configure's deferred delivery.
+                        // Later requests must not retain unrelated notification clients.
+                        if (this.onConfigureWarnings &&
+                            requestSessionId &&
+                            options?.configureWarningClient !== undefined) {
+                            this.configureWarningClients.set(requestSessionId, options.configureWarningClient);
+                        }
                         const configuringChild = this.process;
                         const requireConfiguringChild = () => {
                             if (this.process !== configuringChild) {
@@ -737,6 +763,11 @@ export class BinaryBridge {
                                 }
                                 this.configured = true;
                             }
+                            catch (error) {
+                                if (sessionIdForConfigure)
+                                    this.configureWarningClients.delete(sessionIdForConfigure);
+                                throw error;
+                            }
                             finally {
                                 this._configurePromise = null;
                             }
@@ -792,6 +823,10 @@ export class BinaryBridge {
                     const entry = this.pending.get(id);
                     if (!entry)
                         return;
+                    if (keepBridgeOnTimeout &&
+                        this.holdForLateShellReply(id, entry, effectiveTimeoutMs, requestSessionId)) {
+                        return;
+                    }
                     this.pending.delete(id);
                     clearTimeout(entry.timer);
                     entry.onSettled?.();
@@ -899,6 +934,13 @@ export class BinaryBridge {
         }
     }
     async deliverConfigureWarnings(configResult, params, options) {
+        const sessionId = typeof params.session_id === "string" ? params.session_id : undefined;
+        const client = options?.configureWarningClient ??
+            (sessionId ? this.configureWarningClients.get(sessionId) : undefined);
+        // Capture ownership before dispatch. A hung host callback must neither hold
+        // configure readiness nor delay releasing the terminal delivery's client.
+        if (sessionId && configResult.warnings_pending !== true)
+            this.configureWarningClients.delete(sessionId);
         if (!this.onConfigureWarnings)
             return;
         const warnings = Array.isArray(configResult.warnings)
@@ -907,57 +949,40 @@ export class BinaryBridge {
         const configDroppedKeys = coerceConfigureDroppedKeys(configResult.config_dropped_keys);
         if (warnings.length === 0 && configDroppedKeys.length === 0)
             return;
-        const sessionId = typeof params.session_id === "string" ? params.session_id : undefined;
         const context = {
             projectRoot: this.cwd,
             sessionId,
-            client: options?.configureWarningClient ??
-                (sessionId ? this.configureWarningClients.get(sessionId) : undefined),
+            client,
             warnings,
         };
-        if (configDroppedKeys.length > 0) {
+        if (configDroppedKeys.length > 0)
             context.configDroppedKeys = configDroppedKeys;
-        }
-        try {
-            await this.onConfigureWarnings(context);
-        }
-        catch (err) {
-            this.warnVia(`configure warning delivery failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        finally {
-            if (sessionId) {
-                this.configureWarningClients.delete(sessionId);
-            }
-        }
+        this.dispatchHostCallback("configure warning", () => this.onConfigureWarnings?.(context));
     }
-    /**
-     * Handle the `configure_warnings` push frame the Rust binary emits after
-     * configure has returned. The frame carries the warnings produced by the
-     * deferred file walk + missing-binary detection. Forwards to the same
-     * `onConfigureWarnings` handler used for synchronous warnings so plugins
-     * don't need to know about the async path.
-     */
+    /** Release deferred-warning ownership even when the terminal frame has no warnings. */
     async handleConfigureWarningsFrame(frame) {
-        if (!this.onConfigureWarnings)
-            return;
-        const warnings = frame.warnings;
-        if (!Array.isArray(warnings) || warnings.length === 0)
+        const sessionId = typeof frame.session_id === "string" && frame.session_id.length > 0 ? frame.session_id : null;
+        const client = sessionId ? this.configureWarningClients.get(sessionId) : undefined;
+        if (sessionId)
+            this.configureWarningClients.delete(sessionId);
+        if (!this.onConfigureWarnings || !Array.isArray(frame.warnings) || frame.warnings.length === 0)
             return;
-        const projectRoot = typeof frame.project_root === "string" ? frame.project_root : this.cwd;
-        const rawSessionId = frame.session_id;
-        const sessionId = typeof rawSessionId === "string" && rawSessionId.length > 0 ? rawSessionId : null;
+        this.dispatchHostCallback("configure warning", () => this.onConfigureWarnings?.({
+            projectRoot: typeof frame.project_root === "string" ? frame.project_root : this.cwd,
+            sessionId,
+            client,
+            warnings: frame.warnings,
+        }));
+    }
+    dispatchHostCallback(label, callback) {
+        const failed = (error) => {
+            this.warnVia(`${label} delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+        };
         try {
-            await this.onConfigureWarnings({
-                projectRoot,
-                sessionId,
-                client: sessionId ? this.configureWarningClients.get(sessionId) : undefined,
-                warnings: warnings,
-            });
+            void Promise.resolve(callback()).catch(failed);
         }
-        finally {
-            if (sessionId) {
-                this.configureWarningClients.delete(sessionId);
-            }
+        catch (error) {
+            failed(error);
         }
     }
     handleStatusChangedFrame(frame) {
@@ -985,6 +1010,7 @@ export class BinaryBridge {
         this._shuttingDown = true;
         this.spawnedBinaryFingerprint = null;
         this.clearRestartResetTimer();
+        this.clearRestartTimer();
         this.configureWarningClients.clear();
         this.rejectAllPending(new BridgeTransportUnknownOutcomeError(`${this.errorPrefix} Bridge shutting down`));
         if (this.process) {
@@ -1073,6 +1099,7 @@ export class BinaryBridge {
         this.spawnProcess(triggeringSessionId);
     }
     spawnProcess(triggeringSessionId) {
+        this.clearRestartTimer();
         this._retiringDueToBinaryChange = false;
         if (triggeringSessionId) {
             this.sessionLogVia(triggeringSessionId, `Spawning binary: ${this.binaryPath} (cwd: ${this.cwd})`);
@@ -1157,6 +1184,13 @@ export class BinaryBridge {
             env: spawnEnv,
         });
         const currentChild = child;
+        // Writable streams emit an error in addition to invoking write callbacks.
+        // Keep retired children observed too, but only retire the current transport.
+        child.stdin?.on("error", (cause) => {
+            if (this.process !== currentChild)
+                return;
+            this.invalidateTransportProcess(new BridgeTransportUnknownOutcomeError(`${this.errorPrefix} Failed to write to stdin: ${cause.message}`, { cause }));
+        });
         const stdoutDecoder = new StringDecoder("utf8");
         child.stdout?.on("data", (chunk) => {
             if (this.process !== currentChild)
@@ -1288,11 +1322,12 @@ export class BinaryBridge {
         return `\n  --- last ${this.stderrTail.length} stderr lines ---\n  ${tail}`;
     }
     onStdoutData(data) {
-        // Unprocessed bytes are the carried partial line plus this chunk.
-        if (this.stdoutPendingLength + data.length > MAX_STDOUT_BUFFER) {
+        const exceedsLimit = (fragment) => {
+            if (this.stdoutPendingLength + Buffer.byteLength(fragment, "utf8") <= MAX_STDOUT_BUFFER)
+                return false;
             this.handleCrash(new Error(`aft bridge stdout buffer exceeded ${MAX_STDOUT_BUFFER} bytes — killing bridge`));
-            return;
-        }
+            return true;
+        };
         // Only the new chunk is searched for newlines: the carried chunks are
         // already known to contain none.
         this.stdoutScannedChars += data.length;
@@ -1301,6 +1336,8 @@ export class BinaryBridge {
         let newlineIdx = data.indexOf("\n");
         while (newlineIdx !== -1) {
             let line = data.slice(start, newlineIdx);
+            if (exceedsLimit(line))
+                return;
             if (this.stdoutPending.length > 0) {
                 this.stdoutPending.push(line);
                 line = this.stdoutPending.join("");
@@ -1320,8 +1357,10 @@ export class BinaryBridge {
         }
         if (start < data.length) {
             const rest = start === 0 ? data : data.slice(start);
+            if (exceedsLimit(rest))
+                return;
             this.stdoutPending.push(rest);
-            this.stdoutPendingLength += rest.length;
+            this.stdoutPendingLength += Buffer.byteLength(rest, "utf8");
         }
     }
     flushStdoutBuffer() {
@@ -1365,15 +1404,15 @@ export class BinaryBridge {
                 if (taskId)
                     this.outstandingBackgroundTaskIds.delete(taskId);
                 this.syncEventLoopHold();
-                this.onBashCompletion?.(response, this);
+                this.dispatchHostCallback("bash completion", () => this.onBashCompletion?.(response, this));
                 return;
             }
             if (response.type === "bash_long_running") {
-                this.onBashLongRunning?.(response, this);
+                this.dispatchHostCallback("bash long-running", () => this.onBashLongRunning?.(response, this));
                 return;
             }
             if (response.type === "bash_pattern_match") {
-                this.onBashPatternMatch?.(response, this);
+                this.dispatchHostCallback("bash pattern-match", () => this.onBashPatternMatch?.(response, this));
                 return;
             }
             if (response.type === "configure_warnings") {
@@ -1411,6 +1450,18 @@ export class BinaryBridge {
                 this.accountForBashTaskResponse(entry.command, response);
                 entry.resolve(response);
             }
+            else if (id && typeof response.type !== "string") {
+                // A reply for a request that already settled (its deadline and any
+                // grace period passed). One that names a task is a warning: the task
+                // may still be running, and this log line is the only record of its id.
+                const taskId = bashTaskIdFrom(response);
+                if (taskId) {
+                    this.warnVia(`Dropped late reply for settled request id=${id} task_id=${taskId}`);
+                }
+                else {
+                    this.logVia(`Dropped late reply for settled request id=${id}`);
+                }
+            }
             else if (typeof response.type === "string") {
                 this.logVia(`Ignoring unknown stdout push frame type: ${response.type}`);
             }
@@ -1423,11 +1474,54 @@ export class BinaryBridge {
             this.warnVia(`Failed to parse stdout line: ${quoted}`);
         }
     }
+    /**
+     * Keep a timed-out shell call listening for AFT's reply for a short grace
+     * period instead of rejecting it at once. AFT may already have started the
+     * command; its late reply carries the task id, and dropping it would leave the
+     * agent with a running task it cannot find, which it may then start twice.
+     *
+     * The entry stays in `pending`, so the ordinary reply path still records the
+     * task (see accountForBashTaskResponse) and clears the grace timer. The call
+     * then rejects with a timeout error whose `shellOutcome` says what AFT
+     * answered, or that nothing arrived. Returns false when the call is not a
+     * shell command or the grace period is disabled; the caller then rejects as
+     * before.
+     */
+    holdForLateShellReply(id, entry, effectiveTimeoutMs, requestSessionId) {
+        const graceMs = this.lateShellReplyGraceMs;
+        if (!SHELL_TASK_COMMANDS.has(entry.command) || graceMs <= 0)
+            return false;
+        const timeoutMsg = `Request "${entry.command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms; waiting up to ${graceMs}ms for a late reply naming its task`;
+        if (requestSessionId) {
+            this.sessionWarnVia(requestSessionId, timeoutMsg);
+        }
+        else {
+            this.warnVia(timeoutMsg);
+        }
+        const message = `${this.errorPrefix} Request "${entry.command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms`;
+        const rejectWith = entry.reject;
+        const settle = (outcome) => {
+            rejectWith(new BridgeTransportTimeoutError(entry.command, effectiveTimeoutMs, message, outcome));
+        };
+        // A reply now arrives after the caller's deadline, so it settles the call
+        // as a timeout that reports what AFT answered.
+        entry.resolve = (response) => settle(shellOutcomeFromLateReply(response));
+        clearTimeout(entry.timer);
+        entry.timer = setTimeout(() => {
+            if (this.pending.get(id) !== entry)
+                return;
+            this.pending.delete(id);
+            entry.onSettled?.();
+            this.warnVia(`Request "${entry.command}" (id=${id}) got no reply within ${graceMs}ms after its deadline`);
+            settle({ kind: "unknown" });
+        }, graceMs);
+        return true;
+    }
     accountForBashTaskResponse(command, response) {
         const taskId = bashTaskIdFrom(response);
         if (!taskId)
             return;
-        if (isTerminalBashStatus(response.status)) {
+        if (isTerminalBashStatus(response.status, true)) {
             this.outstandingBackgroundTaskIds.delete(taskId);
             return;
         }
@@ -1486,6 +1580,7 @@ export class BinaryBridge {
         }
     }
     handleCrash(cause) {
+        this.clearRestartTimer();
         const proc = this.process;
         this.process = null;
         this.spawnedBinaryFingerprint = null;
@@ -1517,7 +1612,8 @@ export class BinaryBridge {
             const delay = 100 * 2 ** this._restartCount; // 100ms, 200ms, 400ms
             this._restartCount++;
             this.logVia(`Auto-restart #${this._restartCount} in ${delay}ms`);
-            const restartTimer = setTimeout(() => {
+            this.restartTimer = setTimeout(() => {
+                this.restartTimer = null;
                 if (!this._shuttingDown && !this.isAlive()) {
                     try {
                         this.spawnProcess();
@@ -1529,7 +1625,7 @@ export class BinaryBridge {
             }, delay);
             // The crash already rejected every pending request, so nothing waits on
             // this restart; it must not keep a host that is otherwise done alive.
-            restartTimer.unref?.();
+            this.restartTimer.unref?.();
             // Also decay the counter over time so repeated crashes without any
             // successful response don't permanently wedge the bridge.
             this.scheduleRestartCountReset();
@@ -1540,6 +1636,7 @@ export class BinaryBridge {
         }
     }
     rejectAllPending(error) {
+        this.configureWarningClients.clear();
         for (const [_id, entry] of this.pending) {
             clearTimeout(entry.timer);
             entry.onSettled?.();
@@ -1548,6 +1645,8 @@ export class BinaryBridge {
         this.pending.clear();
     }
     scheduleRestartCountReset() {
+        if (this._restartCount === 0)
+            return;
         this.clearRestartResetTimer();
         this.restartResetTimer = setTimeout(() => {
             this._restartCount = 0;
@@ -1556,6 +1655,11 @@ export class BinaryBridge {
         // Bookkeeping only: a five-minute counter reset must not hold the host open.
         this.restartResetTimer.unref?.();
     }
+    clearRestartTimer() {
+        if (this.restartTimer)
+            clearTimeout(this.restartTimer);
+        this.restartTimer = null;
+    }
     clearRestartResetTimer() {
         if (this.restartResetTimer) {
             clearTimeout(this.restartResetTimer);