Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

fix(mcp): a timed-out tool call aborts its work (CL-14)

KageBinary3ffd40be2dc2
diff --git a/ix-cli/src/cli/__tests__/mcp-runner.test.ts b/ix-cli/src/cli/__tests__/mcp-runner.test.ts
index f3c7937e..7c9a07ec 100644
--- a/ix-cli/src/cli/__tests__/mcp-runner.test.ts
+++ b/ix-cli/src/cli/__tests__/mcp-runner.test.ts
@@ -315,6 +315,9 @@ describe("in-process ix runner", () => {
version: "test-version",
createProgram: createTestProgram,
orphanGraceMs: 60,
+ // This map ignores the abort (as work the run signal cannot reach
+ // does), and is abandoned at once rather than waited for.
+ abortSettleMs: 0,
});
// Abandoned at 40ms, grace fires at ~100ms, still working until ~400ms.
diff --git a/ix-cli/src/cli/__tests__/mcp-timeout-abort.test.ts b/ix-cli/src/cli/__tests__/mcp-timeout-abort.test.ts
new file mode 100644
index 00000000..592b48a8
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/mcp-timeout-abort.test.ts
@@ -0,0 +1,165 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { createServer, type Server } from "node:http";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { Command } from "commander";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { createClient } from "../../client/factory.js";
+import { combineSignals, currentRunSignal } from "../../client/run-signal.js";
+import { createInProcessRunner } from "../../mcp/runner.js";
+import { createIxMcpServer, type IxRunner } from "../../mcp/server.js";
+
+/**
+ * CL-14: an `ix mcp` tool call that hit its deadline returned, but the command
+ * kept running: its backend request stayed open until the backend answered, and
+ * its late exit code made the next failing call report ok=true. The runner now
+ * aborts the run's signal at the deadline; clients and children take it.
+ */
+
+// A backend whose /v1/search never answers in time, recording when the
+// connection closed and whether a response was ever sent.
+let server: Server;
+let endpoint: string;
+const closes: Array<{ atMs: number; finished: boolean }> = [];
+let started = 0;
+
+beforeAll(async () => {
+ server = createServer((req, res) => {
+ req.resume();
+ req.on("end", () => {
+ if (req.url?.startsWith("/v1/search")) {
+ res.on("close", () => closes.push({ atMs: Date.now() - started, finished: res.writableFinished }));
+ setTimeout(() => { if (!res.destroyed) res.end("[]"); }, 3_000);
+ return;
+ }
+ res.end("{}");
+ });
+ });
+ await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+ const addr = server.address();
+ endpoint = `http://127.0.0.1:${typeof addr === "object" && addr ? addr.port : 0}`;
+});
+
+afterAll(async () => {
+ server.closeAllConnections();
+ await new Promise<void>((r) => server.close(() => r()));
+});
+
+function program(): Command {
+ const p = new Command();
+ p.name("ix").exitOverride();
+ p.command("hang-search").action(async () => {
+ // Built through the factory, as every command's client is.
+ await createClient({ endpoint }).search("x");
+ console.log("answered");
+ });
+ p.command("abortable").action(async () => {
+ await new Promise<void>((resolve, reject) => {
+ const signal = currentRunSignal();
+ const timer = setTimeout(resolve, 5_000);
+ signal?.addEventListener("abort", () => { clearTimeout(timer); reject(signal.reason); });
+ });
+ });
+ p.command("ignores-abort").option("--ms <ms>", "", "300").action(async (o: { ms: string }) => {
+ await new Promise((resolve) => setTimeout(resolve, Number(o.ms)));
+ process.exitCode = 1;
+ });
+ p.command("soft-fail").action(() => {
+ console.log("error code=backend_error");
+ process.exitCode = 1;
+ });
+ p.command("stderr-only-fail").action(() => {
+ console.error("Error: 500: stats exploded");
+ process.exitCode = 1;
+ });
+ return p;
+}
+
+describe("a timed-out tool call aborts its work", () => {
+ it("closes the backend connection at the deadline instead of when the backend answers", async () => {
+ const run = createInProcessRunner({ version: "t", createProgram: program });
+ closes.length = 0;
+ started = Date.now();
+ const result = await run(["hang-search"], 200);
+ expect(result.ok).toBe(false);
+ expect(result.stderr).toMatch(/timed out after 200ms/);
+ expect(Date.now() - started).toBeLessThan(1_500);
+ // Closed by the client, unanswered, long before the backend's 3 s reply.
+ await new Promise((r) => setTimeout(r, 100));
+ expect(closes).toHaveLength(1);
+ expect(closes[0]!.finished).toBe(false);
+ expect(closes[0]!.atMs).toBeLessThan(1_000);
+ });
+
+ it("leaves no orphan when the command honours the abort, so the next failure is reported", async () => {
+ const run = createInProcessRunner({ version: "t", createProgram: program });
+ const timedOut = await run(["abortable"], 50);
+ expect(timedOut.ok).toBe(false);
+ // With an orphan alive the exit code is distrusted and this came back ok.
+ expect((await run(["soft-fail"], 5_000)).ok).toBe(false);
+ });
+
+ it("waits only a bounded time for a command that ignores the abort", async () => {
+ const run = createInProcessRunner({ version: "t", createProgram: program, abortSettleMs: 100, orphanGraceMs: 2_000 });
+ const t0 = Date.now();
+ const result = await run(["ignores-abort", "--ms", "1500"], 50);
+ expect(result.ok).toBe(false);
+ expect(Date.now() - t0).toBeLessThan(800);
+ });
+
+ it("reports stderr-only output as a failure while an orphan makes the exit code untrustworthy", async () => {
+ const run = createInProcessRunner({ version: "t", createProgram: program, abortSettleMs: 0, orphanGraceMs: 2_000 });
+ expect((await run(["ignores-abort", "--ms", "400"], 20)).ok).toBe(false);
+ // An orphan is alive: the exit code cannot be read, but a command that
+ // printed nothing on stdout and an error on stderr did not succeed.
+ const result = await run(["stderr-only-fail"], 5_000);
+ expect(result.ok).toBe(false);
+ expect(result.stderr).toMatch(/stats exploded/);
+ await new Promise((r) => setTimeout(r, 450));
+ });
+});
+
+describe("run signal plumbing", () => {
+ it("there is no run signal outside a run, and combining keeps whichever exists", () => {
+ expect(currentRunSignal()).toBeUndefined();
+ const a = new AbortController();
+ const b = new AbortController();
+ expect(combineSignals(a.signal, undefined)).toBe(a.signal);
+ expect(combineSignals(undefined, b.signal)).toBe(b.signal);
+ expect(combineSignals()).toBeUndefined();
+ const both = combineSignals(a.signal, b.signal)!;
+ b.abort();
+ expect(both.aborted).toBe(true);
+ });
+});
+
+describe("the MCP server never reports a silent JSON failure as {}", () => {
+ async function callMap(runIx: IxRunner): Promise<CallToolResult> {
+ const mcp = createIxMcpServer({ version: "test", runIx, tools: "all" });
+ const client = new Client({ name: "t", version: "1" });
+ const [ct, st] = InMemoryTransport.createLinkedPair();
+ await mcp.connect(st);
+ await client.connect(ct);
+ try {
+ return (await client.callTool({ name: "ix_map", arguments: {} })) as CallToolResult;
+ } finally {
+ await client.close();
+ }
+ }
+
+ it("empty stdout with stderr is an error carrying the stderr", async () => {
+ const result = await callMap(async () => ({ ok: true, stdout: "", stderr: "Error: 500: stats exploded" }));
+ expect(result.isError).toBe(true);
+ expect(JSON.stringify(result.content)).toMatch(/stats exploded/);
+ });
+
+ it("both empty keeps the old {} answer", async () => {
+ const result = await callMap(async () => ({ ok: true, stdout: "", stderr: "" }));
+ expect(result.isError).toBeFalsy();
+ expect(result.content[0]).toEqual({ type: "text", text: "{}" });
+ });
+});
diff --git a/ix-cli/src/cli/commands/callers.ts b/ix-cli/src/cli/commands/callers.ts
index 0f4e4ab4..1c24f9d8 100644
--- a/ix-cli/src/cli/commands/callers.ts
+++ b/ix-cli/src/cli/commands/callers.ts
@@ -14,6 +14,7 @@ import { stderr } from "../stderr.js";
import { llmLine } from "../llm.js";
import { edgeTargetFor, rankTextUses, withEdgeSites } from "../edge-sites.js";
import { renderWarning } from "../ui.js";
+import { currentRunSignal } from "../../client/run-signal.js";
const execFileAsync = promisify(execFile);
@@ -77,7 +78,7 @@ export function registerCallersCommand(program: Command): void {
const root = resolveWorkspaceRoot();
// The timeout bounds a search that rg could otherwise run for ever.
const { stdout } = await execFileAsync("rg", callersTextSearchArgs(target.name, root), {
- maxBuffer: 5 * 1024 * 1024, timeout: 10_000,
+ maxBuffer: 5 * 1024 * 1024, timeout: 10_000, signal: currentRunSignal(),
});
const allTextResults: any[] = [];
diff --git a/ix-cli/src/cli/commands/text.ts b/ix-cli/src/cli/commands/text.ts
index 579114de..7dfd4d9a 100644
--- a/ix-cli/src/cli/commands/text.ts
+++ b/ix-cli/src/cli/commands/text.ts
@@ -8,12 +8,14 @@ import { formatTextResults, printJson, sliceRanked, type TextResult } from "../f
import { isPathInsideResolvedRoot, resolveWorkspaceRoot } from "../config.js";
import { stderr } from "../stderr.js";
import { llmError } from "../llm.js";
+import { currentRunSignal } from "../../client/run-signal.js";
type RunRipgrep = (args: string[], limit: number) => Promise<{ stdout: string }>;
async function runRipgrep(args: string[], limit: number): Promise<{ stdout: string }> {
return new Promise((resolve, reject) => {
- const child = spawn("rg", args, { stdio: ["ignore", "pipe", "pipe"] });
+ // Killed when an `ix mcp` tool call that runs it times out (run-signal.ts).
+ const child = spawn("rg", args, { stdio: ["ignore", "pipe", "pipe"], signal: currentRunSignal() });
const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
const matches: string[] = [];
let errorOutput = "";
diff --git a/ix-cli/src/cli/explain/history.ts b/ix-cli/src/cli/explain/history.ts
index 01503f37..d4419136 100644
--- a/ix-cli/src/cli/explain/history.ts
+++ b/ix-cli/src/cli/explain/history.ts
@@ -3,6 +3,7 @@
import { execFile } from "node:child_process";
import { isTestPath } from "./related-files.js";
+import { currentRunSignal } from "../../client/run-signal.js";
/**
* What git remembers about a context target's file.
@@ -131,7 +132,8 @@ export function gitRunner(root: string): GitRunner {
execFile(
"git",
args,
- { cwd: root, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024, timeout: GIT_TIMEOUT_MS },
+ // Killed with the `ix mcp` tool call that runs it (run-signal.ts).
+ { cwd: root, encoding: "utf-8", maxBuffer: 16 * 1024 * 1024, timeout: GIT_TIMEOUT_MS, signal: currentRunSignal() },
(err, stdout) => resolve(err ? undefined : stdout),
);
});
diff --git a/ix-cli/src/client/factory.ts b/ix-cli/src/client/factory.ts
index 28d43c4e..eba50e22 100644
--- a/ix-cli/src/client/factory.ts
+++ b/ix-cli/src/client/factory.ts
@@ -3,6 +3,7 @@
import { getEndpoint, getLocalToken } from "../cli/config.js";
import { IxClient } from "./api.js";
import { QUERY_CLIENT_OPTIONS } from "./request-memo.js";
+import { combineSignals, currentRunSignal } from "./run-signal.js";
export interface CreateClientOptions {
/** Backend URL. Defaults to `getEndpoint()` (IX_ENDPOINT, then config.yaml). */
@@ -27,7 +28,9 @@ export function createClient(opts: CreateClientOptions = {}): IxClient {
const token = getLocalToken(endpoint);
return new IxClient(
endpoint,
- opts.deadlineSignal,
+ // Under `ix mcp`, the tool call's own deadline as well: its timeout aborts
+ // this client's requests instead of leaving them open (see run-signal.ts).
+ combineSignals(opts.deadlineSignal, currentRunSignal()),
{ ...(opts.query ? QUERY_CLIENT_OPTIONS : {}), ...(token ? { token } : {}) },
);
}
diff --git a/ix-cli/src/client/run-signal.ts b/ix-cli/src/client/run-signal.ts
new file mode 100644
index 00000000..d10fd2da
--- /dev/null
+++ b/ix-cli/src/client/run-signal.ts
@@ -0,0 +1,34 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * The abort signal of the command run this code belongs to, if any.
+ *
+ * `ix mcp` runs many commands in one process, each under a deadline. Racing
+ * the command against a timer returned the tool call but left the command
+ * running: its backend requests stayed open and its late writes landed in
+ * whichever call ran next. The runner now aborts at the deadline, and every
+ * client the command builds (`createClient`) and every child it spawns reads
+ * this signal, so the abort actually stops the work.
+ *
+ * Kept in `client/` so the factory can read it without importing the MCP
+ * runner. Outside a run there is no signal and nothing changes.
+ */
+const store = new AsyncLocalStorage<AbortSignal>();
+
+/** Run `fn` with `signal` as the current run's abort signal. */
+export function runWithSignal<T>(signal: AbortSignal, fn: () => T): T {
+ return store.run(signal, fn);
+}
+
+/** The current run's abort signal, or undefined outside one. */
+export function currentRunSignal(): AbortSignal | undefined {
+ return store.getStore();
+}
+
+/** Both signals, either, or neither. */
+export function combineSignals(a?: AbortSignal, b?: AbortSignal): AbortSignal | undefined {
+ if (a && b) return AbortSignal.any([a, b]);
+ return a ?? b;
+}
diff --git a/ix-cli/src/mcp/runner.ts b/ix-cli/src/mcp/runner.ts
index f2c6a153..37e08458 100644
--- a/ix-cli/src/mcp/runner.ts
+++ b/ix-cli/src/mcp/runner.ts
@@ -15,12 +15,20 @@ import { tryLoadProCommands } from "../cli/register/pro-loader.js";
import { resetReadScope } from "../cli/resolve.js";
import { releaseLocksOwnedBy, setLockOwnerResolver } from "../cli/single-flight.js";
import { IX_CALLER_ENV } from "../cli/next-step.js";
+import { runWithSignal } from "../client/run-signal.js";
const execFileAsync = promisify(execFile);
const CLI_ENTRYPOINT = fileURLToPath(new URL("../cli/main.js", import.meta.url));
export const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * How long a command aborted at its timeout gets to unwind before it is
+ * treated as an orphan. An aborted fetch rejects at once, so a command whose
+ * work is backend requests settles well inside this.
+ */
+const ABORT_SETTLE_MS = 1_000;
+
/**
* Cap on a single command's captured output. The subprocess runner got this
* for free from `execFile`'s `maxBuffer`; in-process nothing bounds it, and an
@@ -93,8 +101,11 @@ const runContext = new AsyncLocalStorage<ActiveRun>();
/**
* Commands abandoned at their timeout that are still running.
*
- * Nothing cancels a timed-out command — no Ix command takes an abort signal —
- * so it keeps writing to the process globals after the queue has moved on.
+ * A timed-out command is aborted (its clients and children take the run's
+ * signal) and given a moment to unwind, so this is normally empty. What still
+ * lands here is work the signal does not reach -- a synchronous loop, a call
+ * outside the factory -- which keeps writing to the process globals after the
+ * queue has moved on.
* Output is attributed per run through {@link runContext}; `process.exitCode`
* cannot be, because it is a non-configurable accessor and so cannot be made
* context-local (verified on Node 26: `Object.defineProperty` throws).
@@ -290,10 +301,18 @@ function throwOnUsageError(program: Command): Command {
return program;
}
+/** A run that hit its deadline, as distinct from a command that threw. */
+class RunTimeoutError extends Error {
+ constructor(label: string, timeoutMs: number) {
+ super(`${label} timed out after ${timeoutMs}ms`);
+ this.name = "RunTimeoutError";
+ }
+}
+
function withTimeout<T>(work: Promise<T>, timeoutMs: number, label: string): Promise<T> {
let timer: NodeJS.Timeout;
const deadline = new Promise<never>((_, reject) => {
- timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+ timer = setTimeout(() => reject(new RunTimeoutError(label, timeoutMs)), timeoutMs);
});
return Promise.race([work, deadline]).finally(() => clearTimeout(timer)) as Promise<T>;
}
@@ -315,6 +334,11 @@ export interface InProcessRunnerOptions {
* given. Tests shorten it; nothing else should need to.
*/
orphanGraceMs?: number;
+ /**
+ * How long a command aborted at its timeout may take to settle before it is
+ * left running as an orphan. Defaults to {@link ABORT_SETTLE_MS}.
+ */
+ abortSettleMs?: number;
}
/**
@@ -380,6 +404,7 @@ async function executeInProcess(
createProgram: (version: string) => Command | Promise<Command>,
maxBytes: number,
orphanGraceMs?: number,
+ abortSettleMs: number = ABORT_SETTLE_MS,
): Promise<IxRunResult> {
const program = throwOnUsageError(await createProgram(version));
const run: ActiveRun = {
@@ -409,7 +434,12 @@ async function executeInProcess(
let failure: string | null = null;
let commandExitCode: number | string | undefined;
- const work = runContext.run(run, () => program.parseAsync(args, { from: "user" }));
+ // Aborted at the deadline. Every client the command builds and every child it
+ // spawns takes this signal, so a timeout closes the backend connections
+ // rather than leaving the command running behind the next tool call.
+ const abort = new AbortController();
+ const work = runContext.run(run, () =>
+ runWithSignal(abort.signal, () => program.parseAsync(args, { from: "user" })));
// Settles either way and never rejects, so it can be watched without adding a
// second rejection handler to `work`.
let commandSettled = false;
@@ -433,6 +463,18 @@ async function executeInProcess(
if (error.exitCode !== 0) failure = error.message;
} else {
failure = error instanceof Error ? error.message : String(error);
+ if (error instanceof RunTimeoutError) {
+ // Stop the work, then give it a bounded moment to unwind, so the normal
+ // outcome is a settled command and no orphan. Its output and exit code
+ // in that moment are still this run's: the run is not closed yet.
+ abort.abort(error);
+ let settleTimer: NodeJS.Timeout | undefined;
+ await Promise.race([
+ finished,
+ new Promise<void>((resolve) => { settleTimer = setTimeout(resolve, abortSettleMs); }),
+ ]);
+ clearTimeout(settleTimer);
+ }
}
} finally {
commandExitCode = commandExitCode ?? (exitCodeIsOurs ? process.exitCode : undefined);
@@ -495,7 +537,14 @@ async function executeInProcess(
}
}
- const ok = !run.truncated && failure === null && (commandExitCode === undefined || commandExitCode === 0);
+ // While an orphan made the exit code untrustworthy, a command that printed
+ // nothing on stdout and something on stderr failed: success always prints
+ // its answer. Without this, such a failure came back ok with empty output,
+ // which the server then turned into `{}`.
+ const silentFailure = !exitCodeIsOurs && commandExitCode === undefined &&
+ run.stdout.join("").trim() === "" && run.stderr.join("").trim() !== "";
+ const ok = !run.truncated && failure === null && !silentFailure &&
+ (commandExitCode === undefined || commandExitCode === 0);
return {
ok,
stdout: run.stdout.join(""),
@@ -526,12 +575,13 @@ export function createInProcessRunner(options: InProcessRunnerOptions = {}): IxR
const createProgram = options.createProgram ?? buildProgram;
const maxBytes = options.maxOutputBytes ?? MAX_OUTPUT_BYTES;
const orphanGraceMs = options.orphanGraceMs;
+ const abortSettleMs = options.abortSettleMs;
let queue: Promise<unknown> = Promise.resolve();
return (args, timeoutMs = DEFAULT_TIMEOUT_MS) => {
const result = queue.then(() =>
- executeInProcess(args, timeoutMs, version, createProgram, maxBytes, orphanGraceMs),
+ executeInProcess(args, timeoutMs, version, createProgram, maxBytes, orphanGraceMs, abortSettleMs),
);
// The chain must survive a rejection, or one failed run would strand every
// later call behind it. executeInProcess resolves rather than throws for
diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.ts
index 6486a6a9..9af0b8e7 100644
--- a/ix-cli/src/mcp/server.ts
+++ b/ix-cli/src/mcp/server.ts
@@ -944,9 +944,26 @@ async function runCommand(
return textResult(JSON.stringify({ error: capErrorDetail(detail), tool }), true);
}
+ if (args.includes("--format=json")) {
+ const silent = silentJsonFailure(result, tool);
+ if (silent) return silent;
+ }
return textResult(result.stdout.trim() || "{}");
}
+/**
+ * A JSON-mode run that "succeeded" with nothing on stdout and something on
+ * stderr: a command that failed without saying so through its exit code. A
+ * JSON command always prints its answer, so this is reported as the failure it
+ * is; turning the empty stdout into `{}` told the client the tool succeeded
+ * with nothing to say. Both empty is left to the caller, as before.
+ */
+function silentJsonFailure(result: { stdout: string; stderr: string }, tool: string): CallToolResult | null {
+ if (result.stdout.trim()) return null;
+ const stderr = result.stderr.trim();
+ return stderr ? textResult(JSON.stringify({ error: capErrorDetail(stderr), tool }), true) : null;
+}
+
/**
* Expose the parsed JSON object as structuredContent so clients receive a typed
* value instead of a string to re-parse.
@@ -972,6 +989,8 @@ async function runSmells(runIx: IxRunner, input: ToolInput): Promise<CallToolRes
return textResult(JSON.stringify({ error: capErrorDetail(detail), tool: "ix_smells" }), true);
}
+ const silent = silentJsonFailure(result, "ix_smells");
+ if (silent) return silent;
const parsed = parseJsonOutput(result.stdout);
if (!isRecord(parsed) || !Array.isArray(parsed.candidates)) {
const text = textResult(result.stdout.trim() || "{}");