rea-agents 2.5.0 → 3.0.0

package/dist/generatedPackageMetadata.js

@@ -1,9 +1,9 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "2.5.0", // x-release-please-version
-    serverSdkVersion: "2.0.0-beta.4",
-    clientSdkVersion: "2.0.0-beta.4",
-    coreSdkVersion: "2.0.0-beta.4",
+    version: "3.0.0", // x-release-please-version
+    serverSdkVersion: "2.0.0",
+    clientSdkVersion: "2.0.0",
+    coreSdkVersion: "2.0.0",
     skillVersion: "23",
 };

package/dist/ghidra/GhidraDefaults.js

@@ -17,4 +17,4 @@ export const GHIDRA_MAX_QUEUED_REQUESTS = 32;
 /** Maximum encoded response line accepted from the Java bridge. */
 export const GHIDRA_MAX_LINE_BYTES = 1024 * 1024;
 /** Version of REA's Java bridge handshake and request protocol. */
-export const GHIDRA_BRIDGE_VERSION = 5;
+export const GHIDRA_BRIDGE_VERSION = 6;

package/dist/ghidra/GhidraFunctionValues.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { AnalysisInputError, AnalysisOutputError } from "../domain/errors.js";
 import { functionInstructionWindowSchema, functionDossierSchema, } from "../domain/hopperValues.js";
 import { jsonObjectSchema, jsonValueSchema, } from "../domain/jsonValue.js";
+import { nativeApiBoundarySchema } from "../domain/nativeApiBoundary.js";
 import { err, ok } from "../domain/result.js";
 import { ghidraBoundedIdentifierSchema, ghidraCanonicalAddressSchema, } from "./GhidraInventoryValues.js";
 /** Read-only function operations admitted by the Ghidra adapter. */
@@ -191,7 +192,32 @@ const procedureInfo = z
     classification,
 })
     .strict();
-const ghidraFunctionDossier = functionDossierSchema.superRefine((value, context) => {
+const ghidraNativeApiBoundary = nativeApiBoundarySchema.superRefine((value, context) => {
+    if (!value.available)
+        return;
+    if (value.provenance !== "ghidra-high-function")
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra native API observations require HighFunction provenance",
+        });
+    const addresses = value.jump_tables.flatMap((table) => [
+        table.dispatch_address,
+        ...table.data_sources.map(({ address }) => address),
+        ...table.mappings.flatMap(({ target_address, data_addresses }) => [
+            target_address,
+            ...data_addresses,
+        ]),
+    ]);
+    if (addresses.some((address) => !ghidraCanonicalAddressSchema.safeParse(address).success))
+        context.addIssue({
+            code: "custom",
+            message: "Ghidra native API observation contains a non-canonical address",
+        });
+});
+const ghidraFunctionDossier = functionDossierSchema
+    .extend({ native_api: ghidraNativeApiBoundary })
+    .strict()
+    .superRefine((value, context) => {
     const addresses = [
         value.procedure.address,
         ...value.comments.items.map(({ address }) => address),

package/dist/ghidra/GhidraProviderCapabilities.js

@@ -1,4 +1,4 @@
-import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 import { GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS, GHIDRA_MAX_LINE_BYTES, GHIDRA_REQUEST_TIMEOUT_MS, } from "./GhidraDefaults.js";
 import { GHIDRA_FUNCTION_OPERATIONS } from "./GhidraFunctionValues.js";
 import { GHIDRA_INVENTORY_OPERATIONS } from "./GhidraInventoryValues.js";
@@ -8,10 +8,7 @@ export const GHIDRA_PROVIDER_IDENTITY = Object.freeze({
     name: "Ghidra",
     version: null,
 });
-const providerContractByName = new Map([...OFFICIAL_TOOL_CONTRACTS, ...ENHANCED_TOOL_CONTRACTS].map((contract) => [
-    contract.name,
-    contract,
-]));
+const providerContractByName = new Map(GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy" || kind === "enhanced").map((contract) => [contract.name, contract]));
 /** Provider-neutral read-only contracts implemented by the Ghidra adapter. */
 export const GHIDRA_PROVIDER_TOOL_CONTRACTS = Object.freeze([...GHIDRA_INVENTORY_OPERATIONS, ...GHIDRA_FUNCTION_OPERATIONS].map((operation) => {
     const contract = providerContractByName.get(operation);
@@ -137,39 +134,44 @@ export const limitationsFor = (operation) => {
     }
 };
 /** Provider-neutral capabilities advertised by every non-Windows Ghidra session. */
-export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
-    provider: GHIDRA_PROVIDER_IDENTITY,
-    operation: contract.name,
-    inputContractVersion: 1,
-    outputContractVersion: 1,
-    available: true,
-    reason: null,
-    pagination: PAGINATED_OPERATIONS.has(contract.name)
-        ? "offset"
-        : "none",
-    exhaustive: !PAGINATED_OPERATIONS.has(contract.name),
-    effects: Object.freeze({
-        mutatesArtifact: false,
-        launchesProcess: true,
-        mayShowUi: false,
-        mayAccessNetwork: false,
-        mayWriteFilesystem: true,
-        changesPermissions: false,
-        requiresRoot: false,
-    }),
-    limits: Object.freeze({
-        maxResults: PAGINATED_OPERATIONS.has(contract.name)
-            ? SEARCH_OPERATIONS.has(contract.name)
-                ? 100
-                : 500
-            : null,
-        maxPayloadBytes: GHIDRA_MAX_LINE_BYTES,
-        timeoutMs: DECOMPILE_OPERATIONS.has(contract.name)
-            ? GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS
-            : GHIDRA_REQUEST_TIMEOUT_MS,
-    }),
-    limitations: Object.freeze(limitationsFor(contract.name)),
-})));
+export const CAPABILITIES = Object.freeze(GHIDRA_PROVIDER_TOOL_CONTRACTS.map((contract) => {
+    const operation = contract.analysisOperation;
+    if (operation === null)
+        throw new TypeError(`Missing analysis operation for ${contract.name}`);
+    return Object.freeze({
+        provider: GHIDRA_PROVIDER_IDENTITY,
+        operation,
+        inputContractVersion: 1,
+        outputContractVersion: 1,
+        available: true,
+        reason: null,
+        pagination: PAGINATED_OPERATIONS.has(contract.name)
+            ? "offset"
+            : "none",
+        exhaustive: !PAGINATED_OPERATIONS.has(contract.name),
+        effects: Object.freeze({
+            mutatesArtifact: false,
+            launchesProcess: true,
+            mayShowUi: false,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: true,
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limits: Object.freeze({
+            maxResults: PAGINATED_OPERATIONS.has(contract.name)
+                ? SEARCH_OPERATIONS.has(contract.name)
+                    ? 100
+                    : 500
+                : null,
+            maxPayloadBytes: GHIDRA_MAX_LINE_BYTES,
+            timeoutMs: DECOMPILE_OPERATIONS.has(contract.name)
+                ? GHIDRA_DECOMPILE_REQUEST_TIMEOUT_MS
+                : GHIDRA_REQUEST_TIMEOUT_MS,
+        }),
+        limitations: Object.freeze(limitationsFor(contract.name)),
+    });
+}));
 /** Capabilities advertised for the experimental Windows x64 P0 boundary. */
 export const WINDOWS_P0_CAPABILITIES = Object.freeze(CAPABILITIES.map((capability) => Object.freeze({
     ...capability,

package/dist/hopper/HopperClient.js

@@ -15,7 +15,7 @@ import { connectHopperSocketOnce } from "./HopperSocketConnection.js";
 import { hopperLauncherFailureDiagnostic } from "./HopperProcessDiagnostic.js";
 import { HopperRequestQueue, } from "./HopperRequestQueue.js";
 import { HopperResponseStream } from "./HopperResponseStream.js";
-import { responseResult } from "./protocol.js";
+import { responseResult, } from "./protocol.js";
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 const MAX_QUEUED_REQUESTS = 64;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
@@ -76,7 +76,7 @@ export class HopperClient {
             });
         });
         this.#responses = new HopperResponseStream({
-            accept: (response) => this.#requests.accept(response.id, responseResult(response)),
+            accept: (message) => this.#acceptBridgeMessage(message),
             hasQueued: (id) => this.#requests.hasQueued(id),
             nextRequestId: () => this.#nextId,
             abort: (message, cause) => this.#abortProtocol(message, cause),
@@ -333,6 +333,30 @@ export class HopperClient {
         socket.on("error", this.#onSocketError);
         socket.on("close", this.#onSocketClose);
     }
+    #acceptBridgeMessage(message) {
+        if (!("event" in message))
+            return this.#requests.accept(message.id, responseResult(message));
+        if (!this.#requests.acceptEvent(message))
+            return false;
+        this.#emitBridgeDiagnostic(message);
+        return true;
+    }
+    #emitBridgeDiagnostic(message) {
+        if (message.event.type !== "diagnostic")
+            return;
+        try {
+            this.#options.onDiagnostic?.({
+                type: "bridge-diagnostic",
+                request_id: message.id,
+                code: message.event.error.code,
+                category: message.event.error.type,
+                message: message.event.error.message,
+            });
+        }
+        catch {
+            this.#logger.warn({ requestId: message.id }, "Hopper bridge diagnostic consumer rejected an event");
+        }
+    }
     #detachSocket(socket) {
         socket.off("data", this.#onSocketData);
         socket.off("error", this.#onSocketError);

package/dist/hopper/HopperProvider.js

@@ -3,7 +3,7 @@ import { accessSync, constants } from "node:fs";
 import { createAnalysisExecution } from "../application/AnalysisProvider.js";
 import { AnalysisCapabilityUnavailableError } from "../domain/errors.js";
 import { err } from "../domain/result.js";
-import { ENHANCED_TOOL_CONTRACTS, OFFICIAL_TOOL_CONTRACTS, } from "../contracts/toolContracts.js";
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 import { HopperApplicationLauncher } from "./BridgeLauncher.js";
 import { hopperLoaderArgsForTarget, resolveHopperAnalysisProfile, } from "./HopperAnalysisProfile.js";
 import { HopperClient } from "./HopperClient.js";
@@ -24,36 +24,47 @@ const MUTATING_OPERATIONS = new Set([
 ]);
 /** Tool contracts implemented directly by the Hopper adapter. */
 export const HOPPER_PROVIDER_TOOL_CONTRACTS = Object.freeze([
-    ...OFFICIAL_TOOL_CONTRACTS,
-    ...ENHANCED_TOOL_CONTRACTS.filter((contract) => contract.name === "analyze_function"),
+    ...GENERATED_MCP_TOOL_CATALOG.filter(({ kind }) => kind === "official-proxy"),
+    ...GENERATED_MCP_TOOL_CATALOG.filter(({ name }) => name === "analyze_function"),
 ]);
-const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract) => Object.freeze({
-    provider: IDENTITY,
-    operation: contract.name,
-    inputContractVersion: 1,
-    outputContractVersion: 1,
-    available: true,
-    reason: null,
-    pagination: "offset" in contract.inputSchema.shape ? "offset" : "none",
-    exhaustive: false,
-    effects: Object.freeze({
-        mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
-        launchesProcess: true,
-        mayShowUi: true,
-        mayAccessNetwork: false,
-        mayWriteFilesystem: MUTATING_OPERATIONS.has(contract.name),
-        changesPermissions: false,
-        requiresRoot: false,
-    }),
-    limits: Object.freeze({
-        maxResults: null,
-        maxPayloadBytes: contract.name === "read_bytes" ? 4_096 : null,
-        timeoutMs: null,
-    }),
-    limitations: Object.freeze([
-        "Results depend on Hopper's completed static analysis.",
-    ]),
-})));
+const CAPABILITIES = Object.freeze(HOPPER_PROVIDER_TOOL_CONTRACTS.map((contract) => {
+    const operation = contract.analysisOperation;
+    if (operation === null)
+        throw new TypeError(`Missing analysis operation for ${contract.name}`);
+    return Object.freeze({
+        provider: IDENTITY,
+        operation,
+        inputContractVersion: 1,
+        outputContractVersion: 1,
+        available: true,
+        reason: null,
+        pagination: isRecord(contract.inputSchema.properties) &&
+            "offset" in contract.inputSchema.properties
+            ? "offset"
+            : "none",
+        exhaustive: false,
+        effects: Object.freeze({
+            mutatesArtifact: MUTATING_OPERATIONS.has(contract.name),
+            launchesProcess: true,
+            mayShowUi: true,
+            mayAccessNetwork: false,
+            mayWriteFilesystem: MUTATING_OPERATIONS.has(contract.name),
+            changesPermissions: false,
+            requiresRoot: false,
+        }),
+        limits: Object.freeze({
+            maxResults: null,
+            maxPayloadBytes: contract.name === "read_bytes" ? 4_096 : null,
+            timeoutMs: null,
+        }),
+        limitations: Object.freeze([
+            "Results depend on Hopper's completed static analysis.",
+        ]),
+    });
+}));
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /** Concrete analysis provider backed by REA's private Hopper bridge. */
 export class HopperProvider {
     config;
@@ -178,6 +189,7 @@ export class HopperProvider {
             }),
             ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "bridge" }),
+            onDiagnostic: (diagnostic) => this.logger.info(diagnostic, "Hopper bridge reported a diagnostic"),
         });
         return {
             execute: async (operation, parameters, options) => {

package/dist/hopper/HopperRequestQueue.js

@@ -59,6 +59,28 @@ export class HopperRequestQueue {
         this.#drain();
         return true;
     }
+    /** Forward one correlated bridge event without releasing the wire request. */
+    acceptEvent(event) {
+        const entry = this.#active;
+        if (entry === undefined || entry.id !== event.id)
+            return false;
+        if (event.event.type === "progress" && !entry.callerSettled) {
+            if (event.event.terminal === true && entry.heartbeat !== undefined) {
+                clearInterval(entry.heartbeat);
+                entry.heartbeat = undefined;
+            }
+            this.#reportUpdate(entry, {
+                phase: event.event.phase,
+                completed: event.event.completed,
+                total: event.event.total,
+                message: event.event.message,
+                ...(event.event.terminal === undefined
+                    ? {}
+                    : { terminal: event.event.terminal }),
+            });
+        }
+        return true;
+    }
     /** Fail the active wire request and every request still waiting in the FIFO. */
     failAll(error) {
         const active = this.#active;
@@ -175,13 +197,19 @@ export class HopperRequestQueue {
             entry.signal.removeEventListener("abort", entry.onAbort);
     }
     #report(entry, message) {
-        void entry.progress
-            ?.report({
+        this.#reportUpdate(entry, {
             phase: "hopper_request",
             completed: 0,
             total: 1,
             message,
-        })
-            .catch(() => undefined);
+        });
+    }
+    #reportUpdate(entry, update) {
+        try {
+            void Promise.resolve(entry.progress?.report(update)).catch(() => undefined);
+        }
+        catch {
+            // Progress observation cannot change the request outcome.
+        }
     }
 }

package/dist/hopper/HopperResponseStream.js

@@ -1,4 +1,4 @@
-import { parseResponseLine } from "./protocol.js";
+import { parseBridgeMessageLine, } from "./protocol.js";
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
 /** Incrementally validates bounded Hopper NDJSON response frames. */
 export class HopperResponseStream {
@@ -29,7 +29,7 @@ export class HopperResponseStream {
         this.#buffer = "";
     }
     #acceptLine(line) {
-        const parsed = parseResponseLine(line);
+        const parsed = parseBridgeMessageLine(line);
         if (!parsed.ok) {
             this.options.abort(parsed.error.message, parsed.error);
             return false;

package/dist/hopper/protocol.js

@@ -2,30 +2,72 @@ import { z } from "zod";
 import { HopperProtocolError, HopperRemoteError } from "../domain/errors.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+const remoteErrorSchema = z
+    .object({
+    code: z.number().int(),
+    message: z.string().max(512),
+    type: z
+        .enum([
+        "remote",
+        "authorization",
+        "invalid_request",
+        "capability_unavailable",
+        "bridge_exception",
+    ])
+        .default("remote"),
+})
+    .strict();
 const responseSchema = z.union([
-    z.object({
+    z
+        .object({
         id: z.number().int().nonnegative(),
         result: jsonValueSchema,
-    }),
-    z.object({
+    })
+        .strict(),
+    z
+        .object({
         id: z.number().int().nonnegative(),
-        error: z.object({
-            code: z.number().int(),
-            message: z.string(),
-            type: z
-                .enum([
-                "remote",
-                "authorization",
-                "invalid_request",
-                "capability_unavailable",
-                "bridge_exception",
-            ])
-                .default("remote"),
-        }),
-    }),
+        error: remoteErrorSchema,
+    })
+        .strict(),
 ]);
-/** Parse one complete Hopper NDJSON response line. */
-export const parseResponseLine = (line) => {
+const eventSchema = z
+    .object({
+    id: z.number().int().nonnegative(),
+    event: z.discriminatedUnion("type", [
+        z
+            .object({
+            type: z.literal("progress"),
+            phase: z.string().min(1).max(64),
+            completed: z.number().nonnegative().finite(),
+            total: z.number().nonnegative().finite().nullable(),
+            message: z.string().min(1).max(512),
+            terminal: z.boolean().optional(),
+        })
+            .strict(),
+        z
+            .object({
+            type: z.literal("diagnostic"),
+            error: remoteErrorSchema,
+        })
+            .strict(),
+    ]),
+})
+    .strict()
+    .superRefine((message, context) => {
+    if (message.event.type === "progress" &&
+        message.event.total !== null &&
+        message.event.completed > message.event.total) {
+        context.addIssue({
+            code: "custom",
+            message: "Progress total cannot be less than completed",
+            path: ["event", "total"],
+        });
+    }
+});
+const messageSchema = z.union([responseSchema, eventSchema]);
+/** Parse one complete Hopper NDJSON response or event line. */
+export const parseBridgeMessageLine = (line) => {
     let decoded;
     try {
         decoded = JSON.parse(line);
@@ -33,10 +75,10 @@ export const parseResponseLine = (line) => {
     catch (cause) {
         return err(new HopperProtocolError("Hopper returned malformed JSON", { cause }));
     }
-    const parsed = responseSchema.safeParse(decoded);
+    const parsed = messageSchema.safeParse(decoded);
     return parsed.success
         ? ok(parsed.data)
-        : err(new HopperProtocolError("Hopper returned a response outside the bridge contract", { cause: parsed.error }));
+        : err(new HopperProtocolError("Hopper returned a message outside the bridge contract", { cause: parsed.error }));
 };
 /** Project a parsed response into its result or expected remote failure. */
 export const responseResult = (response) => "error" in response

package/dist/main/transport.js

@@ -1,4 +1,4 @@
-import { createServer } from "../server/createServer.js";
+import { createServer, } from "../server/createServer.js";
 import { MCP_CONNECTION_LOST, MCP_CONNECTION_START_FAILED, } from "./messages.js";
 export const startMcpTransport = async (dependencies, session, serverContext) => {
     const liveServers = new Set();
@@ -13,10 +13,7 @@ export const startMcpTransport = async (dependencies, session, serverContext) =>
                 investigationInputRoots: serverContext.runtimeState.investigationRoots,
                 analysisSnapshotFilePolicy: serverContext.runtimeState.snapshotPolicy,
                 permissionAuthority: serverContext.permissionAuthority,
-                browserObservation: serverContext.browserObservation,
-                browserScenarioCapture: serverContext.browserScenarioCapture,
-                electronObservation: serverContext.electronObservation,
-                javascriptRuntimeObservation: serverContext.javascriptRuntimeObservation,
+                loadOptionalProviders: serverContext.loadOptionalProviders,
                 artifactIntegrityContinueEnabled: () => serverContext.runtimeState.currentConfig
                     .artifactIntegrityContinueEnabled,
                 javascriptReplayPolicy: serverContext.runtimeState.javascriptReplayPolicy,

package/dist/main.js

@@ -7,10 +7,6 @@ import { createBinarySession } from "./application/runtime.js";
 import { createLogger } from "./logger.js";
 import { projectAnalysisError } from "./domain/errors.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
-import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
-import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
-import { V8InspectorProvider } from "./browser/V8InspectorProvider.js";
-import { PlaywrightBrowserScenarioProvider } from "./browser/PlaywrightBrowserScenarioProvider.js";
 import { SERVER_START_FAILED } from "./main/messages.js";
 import { createRuntimeState } from "./main/state.js";
 import { openInitialTarget } from "./main/startup.js";
@@ -60,10 +56,6 @@ export const run = async (dependencies = runtimeDependencies()) => {
         return 1;
     }
     const session = createBinarySession(config.value, logger);
-    const browserObservation = new CdpBrowserProvider();
-    const browserScenarioCapture = new PlaywrightBrowserScenarioProvider();
-    const electronObservation = new CdpElectronProvider();
-    const javascriptRuntimeObservation = new V8InspectorProvider();
     const opened = await openInitialTarget(session, config.value, serverLogger, dependencies.writeStderr);
     if (!opened.ok)
         return opened.exitCode;
@@ -71,10 +63,20 @@ export const run = async (dependencies = runtimeDependencies()) => {
     const transport = await startMcpTransport(dependencies, session, {
         logger,
         serverLogger,
-        browserObservation,
-        browserScenarioCapture,
-        electronObservation,
-        javascriptRuntimeObservation,
+        loadOptionalProviders: async () => {
+            const [{ CdpBrowserProvider }, { PlaywrightBrowserScenarioProvider }, { CdpElectronProvider }, { V8InspectorProvider },] = await Promise.all([
+                import("./browser/CdpBrowserProvider.js"),
+                import("./browser/PlaywrightBrowserScenarioProvider.js"),
+                import("./browser/CdpElectronProvider.js"),
+                import("./browser/V8InspectorProvider.js"),
+            ]);
+            return {
+                browserObservation: new CdpBrowserProvider(),
+                browserScenarioCapture: new PlaywrightBrowserScenarioProvider(),
+                electronObservation: new CdpElectronProvider(),
+                javascriptRuntimeObservation: new V8InspectorProvider(),
+            };
+        },
         permissionAuthority: permissionAuthority.value,
         runtimeState,
     });

package/dist/mcpDoctor.js

@@ -5,12 +5,12 @@ import { resolve } from "node:path";
 import { CATALOG_IDENTITY, MCP_RESOURCE_CATALOG, MCP_RESOURCE_TEMPLATE_CATALOG, } from "./catalogIdentity.js";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { PRODUCT_IDENTITY } from "./identity.js";
-const DEFAULT_DEADLINE_MS = 20_000;
+import { MCP_STARTUP_POLICY } from "./mcpStartupPolicy.js";
 const STDERR_LIMIT_BYTES = 64 * 1_024;
 const OUTPUT_FORMATS = ["toon", "json", "yaml", "md", "jsonl"];
 /** Diagnose the actual production stdio adapter with one bounded SDK session. */
 export const runProductionMcpDoctor = async (options) => {
-    const deadline = Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    const deadline = Date.now() + (options.deadlineMs ?? MCP_STARTUP_POLICY.doctorDeadlineMs);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(new Error("Production MCP doctor deadline expired")), Math.max(1, deadline - Date.now()));
     const stderr = boundedStderr();

package/dist/mcpStartupPolicy.js

@@ -0,0 +1,14 @@
+/**
+ * Supported MCP startup deadlines and regression budgets.
+ *
+ * The Codex timeout is caller-facing configuration. The smaller phase budgets
+ * preserve operational headroom, while the doctor deadline covers additional
+ * inventory requests after initialization.
+ */
+export const MCP_STARTUP_POLICY = {
+    codexStartupTimeoutSeconds: 30,
+    initializeBudgetMs: 15_000,
+    toolsListBudgetMs: 5_000,
+    firstCatalogBudgetMs: 20_000,
+    doctorDeadlineMs: 30_000,
+};