@bbigbang/agent-node 0.1.0

package/dist/nativeWorkerHost.js

@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_GRACE_PERIOD_MS = 5_000;
+/**
+ * Manages the lifecycle of a single native mission worker subprocess:
+ * spawn, stdout/stderr streaming, timeout enforcement, and cancellation.
+ *
+ * On POSIX systems the worker is spawned detached so that it becomes the
+ * leader of a new process group. When a timeout or cancellation occurs the
+ * entire process group is signaled (SIGTERM, then SIGKILL after a grace
+ * period). This prevents orphan worker descendants from outliving the host.
+ */
+export class NativeWorkerHost {
+    options;
+    child = null;
+    timeoutTimer = null;
+    graceTimer = null;
+    ended = false;
+    pendingKillReason = null;
+    cancelBeforeSpawn = false;
+    constructor(options) {
+        this.options = options;
+    }
+    get pid() {
+        return this.child?.pid ?? null;
+    }
+    spawn() {
+        const { command, args, cwd, env } = this.options;
+        // Detaching on POSIX lets us signal the whole process group, ensuring
+        // any grandchildren spawned by the worker are reaped along with it.
+        this.child = spawn(command, args, {
+            cwd,
+            env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+        });
+        this.child.stdout?.on('data', (chunk) => {
+            this.options.onStdout(String(chunk));
+        });
+        this.child.stderr?.on('data', (chunk) => {
+            this.options.onStderr(String(chunk));
+        });
+        this.child.on('error', (error) => {
+            this.end({
+                exitCode: null,
+                signal: null,
+                error: String(error.message ?? error),
+            });
+        });
+        this.child.on('close', (exitCode, signal) => {
+            this.end({
+                exitCode: exitCode ?? null,
+                signal: signal ?? null,
+            });
+        });
+        // A cancellation request arrived before the child was spawned. Honor it
+        // immediately now that the process exists and can be signalled.
+        if (this.cancelBeforeSpawn) {
+            this.kill('cancel');
+        }
+        const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (timeoutMs > 0) {
+            this.timeoutTimer = setTimeout(() => {
+                this.kill('timeout');
+            }, timeoutMs);
+            this.timeoutTimer.unref?.();
+        }
+    }
+    cancel() {
+        // If spawn() has not yet created the child, record the cancellation so
+        // the worker is killed as soon as it spawns. This closes a small race
+        // where core dispatches a feature and immediately cancels it before the
+        // node has finished creating the host.
+        if (!this.child) {
+            this.cancelBeforeSpawn = true;
+            return;
+        }
+        this.kill('cancel');
+    }
+    kill(reason) {
+        if (!this.child || this.ended)
+            return;
+        // A kill sequence is already in progress. Repeated cancel/timeout calls
+        // while SIGTERM is being honored should not queue additional signals.
+        if (this.pendingKillReason)
+            return;
+        this.pendingKillReason = reason;
+        this.signalProcess('SIGTERM');
+        const graceMs = this.options.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+        this.graceTimer = setTimeout(() => {
+            if (!this.ended) {
+                this.signalProcess('SIGKILL');
+            }
+        }, graceMs);
+        this.graceTimer.unref?.();
+    }
+    signalProcess(signal) {
+        if (!this.child || this.child.pid == null || this.ended)
+            return;
+        try {
+            if (process.platform !== 'win32') {
+                // Negative PID sends the signal to the entire process group.
+                process.kill(-this.child.pid, signal);
+            }
+            else {
+                this.child.kill(signal);
+            }
+        }
+        catch (error) {
+            const errno = error;
+            // ESRCH means the process is already gone; treat that as a clean reap.
+            if (errno.code !== 'ESRCH' && !this.ended) {
+                this.end({
+                    exitCode: null,
+                    signal: signal,
+                    error: `Failed to send ${signal}: ${String(errno.message ?? error)}`,
+                });
+            }
+        }
+    }
+    end(result) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+        if (this.graceTimer) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = null;
+        }
+        if (this.pendingKillReason && !result.error) {
+            const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+            result.error =
+                this.pendingKillReason === 'timeout'
+                    ? `Worker timed out after ${timeoutMs}ms`
+                    : 'Worker was cancelled';
+        }
+        this.options.onExit(result);
+    }
+}

package/dist/nodeSink.js

@@ -0,0 +1,142 @@
+/**
+ * OutboundSink that forwards agent output to core as run.event / permission.request messages.
+ */
+export class NodeSink {
+    runId;
+    conversationId;
+    send;
+    hooks;
+    constructor(runId, conversationId, send, hooks) {
+        this.runId = runId;
+        this.conversationId = conversationId;
+        this.send = send;
+        this.hooks = hooks;
+    }
+    async sendAgentText(text) {
+        this.emitEvent({ type: 'content.delta', text });
+    }
+    async sendActivityText(text) {
+        this.emitEvent({ type: 'activity.delta', text });
+    }
+    async sendText(text) {
+        this.emitEvent({ type: 'content.delta', text });
+    }
+    async sendThinkingText(text) {
+        this.emitEvent({ type: 'thinking.delta', text });
+    }
+    async requestPermission(req) {
+        this.hooks?.onPermissionRequest?.();
+        this.send({
+            type: 'permission.request',
+            runId: this.runId,
+            conversationId: this.conversationId,
+            requestId: req.requestId,
+            toolName: req.toolName ?? req.toolTitle,
+            toolArgs: req.toolArgs ?? null,
+            toolKind: req.toolKind,
+            ...(req.approvalKind ? { approvalKind: req.approvalKind } : {}),
+            ...(req.title ? { title: req.title } : {}),
+            ...(req.description ? { description: req.description } : {}),
+            ...(req.input !== undefined ? { input: req.input } : {}),
+            ...(req.actions?.length ? { actions: req.actions } : {}),
+        });
+    }
+    async sendUi(event) {
+        if (event.kind === 'tool') {
+            const toolEvent = event;
+            if (event.stage === 'complete') {
+                const normalizedStatus = event.status === 'cancelled'
+                    ? 'cancelled'
+                    : event.status === 'error' || event.status === 'failed' || event.status === 'declined'
+                        ? 'failed'
+                        : 'completed';
+                const isError = normalizedStatus === 'failed';
+                this.emitEvent({
+                    type: 'tool.result',
+                    toolCallId: event.toolCallId ?? '',
+                    output: toolEvent.output ?? event.detail ?? event.status ?? 'done',
+                    detail: event.detail,
+                    error: isError,
+                    status: normalizedStatus,
+                    metadata: event.metadata,
+                });
+            }
+            else {
+                const normalizedStatus = event.status === 'cancelled'
+                    ? 'cancelled'
+                    : event.status === 'error' || event.status === 'failed' || event.status === 'declined'
+                        ? 'failed'
+                        : event.status === 'completed'
+                            ? 'completed'
+                            : 'running';
+                this.emitEvent({
+                    type: 'tool.call',
+                    toolCallId: event.toolCallId ?? '',
+                    name: event.title,
+                    input: toolEvent.input ?? event.detail ?? null,
+                    detail: event.detail,
+                    status: normalizedStatus,
+                    metadata: event.metadata,
+                });
+            }
+        }
+        if (event.kind === 'usage') {
+            this.emitEvent({
+                type: 'run.usage',
+                inputTokens: event.inputTokens,
+                cachedInputTokens: event.cachedInputTokens,
+                outputTokens: event.outputTokens,
+                reasoningOutputTokens: event.reasoningOutputTokens,
+                totalTokens: event.totalTokens,
+                currentInputTokens: event.currentInputTokens,
+                currentCachedInputTokens: event.currentCachedInputTokens,
+                modelContextWindow: event.modelContextWindow,
+                createdAt: Date.now(),
+                metadata: event.metadata,
+            });
+        }
+        if (event.kind === 'compact') {
+            this.emitEvent({
+                type: 'runtime.compact',
+                threadId: event.threadId,
+                turnId: event.turnId,
+                itemId: event.itemId,
+                source: event.source,
+                eventKey: event.eventKey,
+                createdAt: Date.now(),
+            });
+        }
+        if (event.kind === 'plan_phase') {
+            this.emitEvent({
+                type: 'plan.phase',
+                phase: event.phase,
+                createdAt: Date.now(),
+            });
+        }
+        if (event.kind === 'plan' || event.kind === 'task') {
+            const createdAt = Date.now();
+            this.emitEvent({
+                type: event.kind === 'plan' ? 'plan.update' : 'task.update',
+                title: event.title,
+                detail: event.detail,
+                createdAt,
+            });
+            if (event.silent)
+                return;
+            const text = event.detail
+                ? `\n[${event.kind}] ${event.title}\n${event.detail}\n`
+                : `\n[${event.kind}] ${event.title}\n`;
+            this.emitEvent({ type: 'content.delta', text });
+        }
+    }
+    async breakTextStream() { }
+    async flush() { }
+    emitEvent(event) {
+        this.send({
+            type: 'run.event',
+            runId: this.runId,
+            conversationId: this.conversationId,
+            event,
+        });
+    }
+}

package/dist/panelHttpFetch.js

@@ -0,0 +1,334 @@
+import { lookup } from 'node:dns/promises';
+import { validatePanelApiJsonlUrl } from '@bbigbang/protocol';
+import { WorkspaceFsError } from './workspaceFs.js';
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+const MAX_ALLOWED_BYTES = 5 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 5_000;
+export async function fetchLoopbackHttpText(url, options = {}) {
+    const parsed = parseAllowedPanelHttpUrl(url, {
+        allowedOrigins: options.allowedOrigins ?? [],
+        allowedUrlPrefixes: options.allowedUrlPrefixes ?? [],
+    });
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const range = normalizeRange(options.rangeStart, options.rangeLength);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetch(parsed.toString(), {
+            method: 'GET',
+            redirect: 'error',
+            signal: controller.signal,
+            headers: {
+                Accept: 'application/x-ndjson, application/jsonl, application/json, text/plain;q=0.9',
+                ...(options.authHeaders ?? {}),
+                ...(typeof options.ifNoneMatch === 'string' && options.ifNoneMatch.trim()
+                    ? { 'If-None-Match': options.ifNoneMatch.trim() }
+                    : {}),
+                ...(typeof options.ifModifiedSince === 'string' && options.ifModifiedSince.trim()
+                    ? { 'If-Modified-Since': options.ifModifiedSince.trim() }
+                    : {}),
+                ...(typeof options.ifRange === 'string' && options.ifRange.trim()
+                    ? { 'If-Range': options.ifRange.trim() }
+                    : {}),
+                ...(range ? { Range: `bytes=${range.start}-${range.end}` } : {}),
+            },
+        });
+        const etag = response.headers.get('etag');
+        const lastModified = response.headers.get('last-modified');
+        if (response.status === 304) {
+            return {
+                url: parsed.toString(),
+                content: '',
+                status: response.status,
+                contentType: response.headers.get('content-type'),
+                size: 0,
+                notModified: true,
+                etag,
+                lastModified,
+            };
+        }
+        if (!response.ok) {
+            throw new WorkspaceFsError('io_error', `HTTP endpoint returned ${response.status}.`);
+        }
+        const rangeInfo = response.status === 206
+            ? parseContentRange(response.headers.get('content-range'))
+            : null;
+        const contentType = response.headers.get('content-type');
+        if (!isAllowedTextContentType(contentType)) {
+            throw new WorkspaceFsError('binary_file', 'HTTP endpoint must return JSON or text content.');
+        }
+        const declaredLength = Number(response.headers.get('content-length') ?? NaN);
+        if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+            throw new WorkspaceFsError('file_too_large', `HTTP response exceeds limit (${maxBytes} bytes).`);
+        }
+        const bytes = await readResponseBytes(response, maxBytes);
+        return {
+            url: parsed.toString(),
+            content: new TextDecoder('utf-8', { fatal: false }).decode(bytes),
+            status: response.status,
+            contentType,
+            size: bytes.byteLength,
+            ...(rangeInfo
+                ? {
+                    partialContent: true,
+                    rangeStart: rangeInfo.start,
+                    rangeEnd: rangeInfo.end,
+                    totalSize: rangeInfo.totalSize,
+                    hasMore: rangeInfo.totalSize == null ? bytes.byteLength >= maxBytes : rangeInfo.end + 1 < rangeInfo.totalSize,
+                }
+                : range
+                    ? { partialContent: false }
+                    : {}),
+            etag,
+            lastModified,
+        };
+    }
+    catch (error) {
+        if (error instanceof WorkspaceFsError)
+            throw error;
+        if (error?.name === 'AbortError') {
+            throw new WorkspaceFsError('io_error', 'HTTP endpoint request timed out.');
+        }
+        throw new WorkspaceFsError('io_error', String(error?.message ?? error));
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function proxyWorkspaceServiceHttp(url, options = {}) {
+    const parsed = await parseWorkspaceServiceUrl(url, options.lookupHostname);
+    const method = normalizeWorkspaceServiceMethod(options.method);
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const headers = normalizeWorkspaceServiceHeaders(options.headers);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetch(parsed.toString(), {
+            method,
+            redirect: 'error',
+            signal: controller.signal,
+            headers: {
+                Accept: 'application/json, text/plain;q=0.9',
+                ...headers,
+            },
+            ...(method === 'GET' || method === 'DELETE' ? {} : { body: options.body ?? '' }),
+        });
+        const contentType = response.headers.get('content-type');
+        if (!isAllowedTextContentType(contentType)) {
+            throw new WorkspaceFsError('binary_file', 'Workspace service response must be JSON or text content.');
+        }
+        const declaredLength = Number(response.headers.get('content-length') ?? NaN);
+        if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+            throw new WorkspaceFsError('file_too_large', `Workspace service response exceeds limit (${maxBytes} bytes).`);
+        }
+        const bytes = await readResponseBytes(response, maxBytes);
+        return {
+            url: parsed.toString(),
+            method,
+            status: response.status,
+            body: new TextDecoder('utf-8', { fatal: false }).decode(bytes),
+            contentType,
+            size: bytes.byteLength,
+        };
+    }
+    catch (error) {
+        if (error instanceof WorkspaceFsError)
+            throw error;
+        if (error?.name === 'AbortError') {
+            throw new WorkspaceFsError('io_error', 'Workspace service proxy request timed out.');
+        }
+        throw new WorkspaceFsError('io_error', String(error?.message ?? error));
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function parseAllowedPanelHttpUrl(rawUrl, options) {
+    const validation = validatePanelApiJsonlUrl(rawUrl, options);
+    if (!validation.ok) {
+        const code = validation.reason.includes('valid URL') || validation.reason.includes('control characters')
+            ? 'invalid_request'
+            : 'path_outside_workspace';
+        throw new WorkspaceFsError(code, formatHttpEndpointValidationReason(validation.reason));
+    }
+    return new URL(validation.url);
+}
+async function parseWorkspaceServiceUrl(rawUrl, lookupHostname = resolveHostnameAddresses) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new WorkspaceFsError('invalid_request', 'Workspace service URL must be a valid URL.');
+    }
+    if (parsed.username || parsed.password) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Workspace service URL must not include credentials.');
+    }
+    if (parsed.protocol !== 'http:') {
+        throw new WorkspaceFsError('path_outside_workspace', 'Workspace service proxy only supports http loopback URLs.');
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (hostname === 'localhost') {
+        const addresses = await lookupHostname(hostname);
+        if (addresses.length === 0 || addresses.some((address) => !isLoopbackAddress(address))) {
+            throw new WorkspaceFsError('path_outside_workspace', 'Workspace service localhost must resolve only to loopback addresses.');
+        }
+        if (!parsed.port) {
+            throw new WorkspaceFsError('invalid_request', 'Workspace service URL must include an explicit port.');
+        }
+        return parsed;
+    }
+    if (!isLoopbackAddress(hostname)) {
+        throw new WorkspaceFsError('path_outside_workspace', 'Workspace service URL must target localhost, 127.0.0.1, or ::1.');
+    }
+    if (!parsed.port) {
+        throw new WorkspaceFsError('invalid_request', 'Workspace service URL must include an explicit port.');
+    }
+    return parsed;
+}
+async function resolveHostnameAddresses(hostname) {
+    const entries = await lookup(hostname, { all: true, verbatim: true });
+    return entries.map((entry) => entry.address);
+}
+function isLoopbackAddress(hostname) {
+    const normalized = hostname.replace(/^\[/u, '').replace(/\]$/u, '').toLowerCase();
+    return normalized === '::1' || normalized.startsWith('127.');
+}
+function normalizeWorkspaceServiceMethod(method) {
+    if (method === undefined)
+        return 'GET';
+    if (method === 'GET' || method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE') {
+        return method;
+    }
+    throw new WorkspaceFsError('invalid_request', 'Workspace service proxy method is not supported.');
+}
+function normalizeWorkspaceServiceHeaders(headers) {
+    if (!headers)
+        return {};
+    const normalized = {};
+    for (const [rawName, rawValue] of Object.entries(headers)) {
+        const name = rawName.trim().toLowerCase();
+        if (!name || /[\r\n:]/u.test(name)) {
+            throw new WorkspaceFsError('invalid_request', 'Workspace service proxy header name is invalid.');
+        }
+        if (isForbiddenWorkspaceServiceHeader(name)) {
+            throw new WorkspaceFsError('invalid_request', `Workspace service proxy cannot forward header "${rawName}".`);
+        }
+        if (typeof rawValue !== 'string' || /[\r\n]/u.test(rawValue)) {
+            throw new WorkspaceFsError('invalid_request', `Workspace service proxy header "${rawName}" value is invalid.`);
+        }
+        normalized[rawName] = rawValue;
+    }
+    return normalized;
+}
+function isForbiddenWorkspaceServiceHeader(name) {
+    return name === 'authorization'
+        || name === 'cookie'
+        || name === 'forwarded'
+        || name === 'host'
+        || name === 'connection'
+        || name === 'content-length'
+        || name === 'transfer-encoding'
+        || name === 'x-real-ip'
+        || name === 'x-forwarded-for'
+        || name === 'x-forwarded-host'
+        || name === 'x-forwarded-port'
+        || name === 'x-forwarded-proto'
+        || name === 'x-forwarded-protocol'
+        || name === 'x-forwarded-server'
+        || name === 'x-forwarded-ssl'
+        || name === 'proxy-authorization'
+        || name === 'proxy-authenticate'
+        || name.startsWith('proxy-')
+        || name.startsWith('x-forwarded-')
+        || name.startsWith('sec-');
+}
+function formatHttpEndpointValidationReason(reason) {
+    return reason
+        .replace(/^api_jsonl url/u, 'HTTP endpoint URL')
+        .replace(/^api_jsonl endpoints/u, 'HTTP endpoint')
+        .replace(/^api_jsonl only supports/u, 'HTTP endpoint only supports');
+}
+function normalizeMaxBytes(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_BYTES;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_ALLOWED_BYTES) {
+        throw new WorkspaceFsError('invalid_request', `maxBytes must be between 1 and ${MAX_ALLOWED_BYTES}.`);
+    }
+    return value;
+}
+function normalizeRange(rangeStart, rangeLength) {
+    if (rangeStart === undefined && rangeLength === undefined)
+        return null;
+    if (typeof rangeStart !== 'number'
+        || typeof rangeLength !== 'number'
+        || !Number.isInteger(rangeStart)
+        || !Number.isInteger(rangeLength)
+        || rangeStart < 0
+        || rangeLength <= 0
+        || rangeLength > MAX_ALLOWED_BYTES) {
+        throw new WorkspaceFsError('invalid_request', `rangeStart/rangeLength must describe a byte range with length 1-${MAX_ALLOWED_BYTES}.`);
+    }
+    return {
+        start: rangeStart,
+        end: rangeStart + rangeLength - 1,
+    };
+}
+function parseContentRange(raw) {
+    if (!raw)
+        return null;
+    const match = /^bytes\s+(\d+)-(\d+)\/(\d+|\*)$/iu.exec(raw.trim());
+    if (!match)
+        return null;
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    const totalSize = match[3] === '*' ? null : Number(match[3]);
+    if (!Number.isSafeInteger(start)
+        || !Number.isSafeInteger(end)
+        || end < start
+        || (totalSize !== null && (!Number.isSafeInteger(totalSize) || totalSize < end + 1))) {
+        return null;
+    }
+    return { start, end, totalSize };
+}
+function isAllowedTextContentType(contentType) {
+    if (!contentType)
+        return true;
+    const normalized = contentType.toLowerCase();
+    return normalized.includes('json')
+        || normalized.startsWith('text/')
+        || normalized.includes('x-ndjson');
+}
+async function readResponseBytes(response, maxBytes) {
+    if (!response.body) {
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (!value)
+            continue;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // ignore cancellation errors after we have already decided to fail
+            }
+            throw new WorkspaceFsError('file_too_large', `HTTP response exceeds limit (${maxBytes} bytes).`);
+        }
+        chunks.push(value);
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+}

package/dist/runtimeDrivers.js

@@ -0,0 +1,62 @@
+import { spawnSync } from 'node:child_process';
+import { listRuntimeDrivers, } from '@bbigbang/protocol';
+const CODEX_APP_SERVER_PROBE_TIMEOUT_MS = 10_000;
+export function resolveAvailableRuntimeDrivers(params = {}) {
+    const runtimeDrivers = [];
+    const unavailableRuntimeDrivers = [];
+    for (const driver of listRuntimeDrivers()) {
+        const reason = getDriverUnavailableReason(driver, params);
+        if (reason) {
+            unavailableRuntimeDrivers.push({
+                agentType: driver.agentType,
+                reason,
+            });
+            continue;
+        }
+        runtimeDrivers.push(driver);
+    }
+    return {
+        runtimeDrivers,
+        unavailableRuntimeDrivers,
+    };
+}
+function getDriverUnavailableReason(driver, params) {
+    if (driver.agentType !== 'codex_app_server') {
+        return null;
+    }
+    const probe = probeCodexAppServer({
+        command: driver.command,
+        args: driver.args,
+        spawnSyncImpl: params.spawnSyncImpl,
+        env: params.env,
+        timeoutMs: params.timeoutMs,
+    });
+    return probe.available ? null : (probe.reason ?? 'launch probe failed.');
+}
+function probeCodexAppServer(params) {
+    const spawnSyncImpl = params.spawnSyncImpl ?? spawnSync;
+    const result = spawnSyncImpl(params.command, [...params.args, '--help'], {
+        env: params.env ?? process.env,
+        stdio: 'ignore',
+        timeout: params.timeoutMs ?? CODEX_APP_SERVER_PROBE_TIMEOUT_MS,
+    });
+    if (result.error) {
+        return {
+            available: false,
+            reason: result.error.message || 'launch probe failed.',
+        };
+    }
+    if (typeof result.status === 'number' && result.status !== 0) {
+        return {
+            available: false,
+            reason: `probe exited with status ${result.status}.`,
+        };
+    }
+    if (result.signal) {
+        return {
+            available: false,
+            reason: `probe exited via signal ${result.signal}.`,
+        };
+    }
+    return { available: true };
+}