UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

843 lines (780 loc) • 32.6 kB
import { spawn as nodeSpawn, type ChildProcess, type SpawnOptions } from "node:child_process"; import { mkdir } from "node:fs/promises"; import { dirname } from "node:path"; import { commandInvocation } from "../../lib/win-exec"; import { killWindowsProcessTreeAsync } from "../coding-agent/process-tree"; import type { WhichFn } from "../coding-agent/profile"; import { buildStepCliEnv } from "./env"; import { classifyStepChildError, StepSessionError } from "./errors"; import { findStepCliBinary, stepCliSessionDir, STEP_CLI_PROFILE, type StepCliProfile, } from "./profiles"; import { encodeStepFrame, stepErrorResponse, stepRequest, stepResponse, StepFrameDecoder, StepProtocolViolation, STEP_MAX_FRAME_BYTES, STEP_PROTOCOL_VERSION, type StepFrame, } from "./stdio-frames"; export type StepSpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess; /** * Capabilities this route cannot work without. * * Without `sdk-tools` the runtime answers text only while looking healthy, which is the one failure * this provider must never present as success: the client would conclude the model simply chose not * to call its tools, and a routed coding session would silently degrade into a chat. */ const REQUIRED_CAPABILITIES = ["streaming-input", "sdk-tools"] as const; const CLEANUP_ATTEMPTS = 2; const MAX_PARALLEL_CLEANUPS = 4; const KILL_CONFIRMATION_MS = 2_000; const SHUTDOWN_KILL_MARGIN_MS = 250; const PROCESS_EXIT_POLL_MS = 20; const POSIX_LEADER_EXITED = "StepCode POSIX process cleanup is incomplete because the process group leader exited before group termination."; const WINDOWS_PID_UNCONFIRMED = "StepCode Windows process cleanup is incomplete because ownership of the wrapper PID could not be confirmed."; // Share slots across pools and all close paths, including idle and late-opening sessions. let activeCleanups = 0; const cleanupWaiters = new Set<() => void>(); function withCleanupSlot(cleanup: () => Promise<void>, urgent: AbortSignal): Promise<void> { return new Promise((resolve, reject) => { const start = (): void => { cleanupWaiters.delete(start); urgent.removeEventListener("abort", start); if (urgent.aborted) { // At the shutdown margin a queued tree kill must start even if every slot is busy. void cleanup().then(resolve, reject); return; } activeCleanups++; const release = (): void => { activeCleanups--; cleanupWaiters.values().next().value?.(); }; void cleanup().finally(release).then(resolve, reject); }; if (urgent.aborted || activeCleanups < MAX_PARALLEL_CLEANUPS) start(); else { cleanupWaiters.add(start); urgent.addEventListener("abort", start, { once: true }); } }); } function processIsGone(pid: number): boolean { try { process.kill(pid, 0); return false; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") return true; throw error; } } export interface StepSessionDeps { spawn?: StepSpawnFn; which?: WhichFn; /** Injectable timer primitives so tests never sleep. */ setTimeout?: typeof setTimeout; clearTimeout?: typeof clearTimeout; now?: () => number; /** Test seam for Windows command-shim invocation. */ platform?: NodeJS.Platform; killWindowsProcessTree?: (pid: number) => Promise<void>; } export interface StepSessionOptions { binary: string; args: readonly string[]; env: Record<string, string>; /** Working directory; the session directory is created beneath it. */ cwd: string; /** Wall-clock ceiling for `initialize`, in ms. */ handshakeTimeoutMs: number; /** Ceiling on a request the runtime has not answered, in ms. */ requestTimeoutMs: number; /** * Ceiling on a reverse request this peer holds. * * StepCode's own `SDK_TOOL_TIMEOUT_MS` is 120s and answering late produces a `permission_denied` * message inside the model's context rather than a transport error. Bounding the hold shorter than * that turns a too-slow tool into a clean failed turn instead of a session the model believes was * denied. */ reverseRequestHoldMs: number; /** Reap a session with no activity for this long, in ms. */ idleTimeoutMs: number; /** SIGTERM-to-SIGKILL window, in ms. */ killGraceMs: number; } /** A request awaiting an answer from the runtime. */ interface PendingRequest { readonly method: string; readonly timer: ReturnType<typeof setTimeout>; readonly resolve: (frame: StepFrame) => void; readonly reject: (error: Error) => void; answered: boolean; } /** A reverse request the runtime is waiting on this peer to answer. */ interface HeldReverseRequest { readonly method: string; readonly frame: StepFrame; readonly timer: ReturnType<typeof setTimeout>; answered: boolean; } export { StepSessionError } from "./errors"; /** * What the adapter needs to hear while a session is live. * * Every event carries the session that produced it: the handler is shared across every conversation, * so the origin is the only way to route a frame to the turn that is waiting for it. */ export type StepSessionEvent = | { type: "event"; frame: StepFrame; session: StepCliSession } | { type: "reverse_request"; frame: StepFrame; session: StepCliSession }; export interface StepSessionHandlers { onEvent(event: StepSessionEvent): void; } /** * One long-lived `step --sdk-stdio` process, keyed by client conversation. * * StepCode carries conversation context only in process memory: `query.input` reduces every message * to plain text and images (`readQueryInput`), so an assistant turn, a declared tool call and its * result cannot be replayed through the wire. The session therefore has to outlive one proxied * request, and the client keeps it alive by echoing back the `providerState` this class mints — * the same mechanism Kiro uses for `conversationId`. * * That constraint is also why a captured tool call is held open rather than answered here. The * client executes the tool and reports it on its next request; delivering that result to this * reverse request is how it reaches the model, inside the query the model is already running. */ export class StepCliSession { readonly #options: StepSessionOptions; readonly #deps: StepSessionDeps; readonly #handlers: StepSessionHandlers; readonly #decoder = new StepFrameDecoder(); readonly #pending = new Map<string, PendingRequest>(); readonly #held = new Map<string, HeldReverseRequest>(); readonly #setTimer: typeof setTimeout; readonly #clearTimer: typeof clearTimeout; readonly #now: () => number; readonly #platform: NodeJS.Platform; readonly #killGraceMs: number; #child: ChildProcess | undefined; #leaderExited = false; #posixGroupSignalState: "pending" | "finished" | "lost" = "pending"; #windowsTreeKillAttempted = false; #closed = false; #closePromise: Promise<void> | undefined; #cleanupComplete = false; #shutdownDeadlineMs = Infinity; #shutdownTimer: ReturnType<typeof setTimeout> | undefined; readonly #urgentCleanup = new AbortController(); #handshake: Promise<StepFrame> | undefined; #sessionId: string | undefined; #lastActivityAt: number; #requestSeq = 0; #stderrTail = ""; #idleTimer: ReturnType<typeof setTimeout> | undefined; readonly #exitListeners = new Set<() => void>(); /** * Register a callback fired once the owned process cleanup is confirmed. * * The pool needs this to drop a conversation whose process died: a restart would come back with no * memory of the tool results the client already delivered, and those are not recoverable from the * transcript this route cannot replay. */ onExit(listener: () => void): () => void { if (this.#cleanupComplete) { listener(); return () => undefined; } this.#exitListeners.add(listener); return () => this.#exitListeners.delete(listener); } #announceExit(): void { if (this.#exitListeners.size === 0) return; const listeners = [...this.#exitListeners]; this.#exitListeners.clear(); for (const listener of listeners) { try { listener(); } catch { // An owner's bookkeeping must never keep a dead session from being reported. } } } private constructor(options: StepSessionOptions, deps: StepSessionDeps, handlers: StepSessionHandlers) { this.#options = options; this.#deps = deps; this.#handlers = handlers; this.#setTimer = deps.setTimeout ?? setTimeout; this.#clearTimer = deps.clearTimeout ?? clearTimeout; this.#now = deps.now ?? Date.now; this.#platform = deps.platform ?? process.platform; this.#killGraceMs = options.killGraceMs; this.#lastActivityAt = this.#now(); } static async open( options: StepSessionOptions, handlers: StepSessionHandlers, deps: StepSessionDeps = {}, own?: (session: StepCliSession) => void, ): Promise<StepCliSession> { const session = new StepCliSession(options, deps, handlers); own?.(session); try { await session.#start(); } catch (error) { void session.close(); throw error; } return session; } get sessionId(): string | undefined { return this.#sessionId; } get closed(): boolean { return this.#closed; } /** Bounded stderr tail, for diagnostics. Never logged wholesale. */ get stderrTail(): string { return this.#stderrTail; } /** Milliseconds since the last frame in either direction. */ idleMs(): number { return this.#now() - this.#lastActivityAt; } #touch(): void { this.#lastActivityAt = this.#now(); } #nextId(): string { this.#requestSeq += 1; return `ocx_${this.#requestSeq}`; } async #start(): Promise<void> { const invocation = commandInvocation(this.#options.binary, this.#options.args, this.#platform); try { await mkdir(this.#options.cwd, { recursive: true }); } catch { throw new StepSessionError("StepCode could not create its workspace.", "step_cli_workspace_unavailable"); } // A deadline-aware close can take ownership while workspace creation is pending. if (this.#closed) return; const spawn = this.#deps.spawn ?? nodeSpawn; const child = spawn(invocation.file, invocation.args, { ...invocation.options, env: this.#options.env, stdio: ["pipe", "pipe", "pipe"], windowsHide: true, detached: this.#platform !== "win32", cwd: this.#options.cwd, }); this.#child = child; child.once("exit", () => { this.#leaderExited = true; }); // stderr must be drained continuously: an unread pipe fills and blocks the child mid-turn. Only a // bounded tail is retained, and it is never logged as content. // // `setEncoding("utf8")` rather than decoding each chunk: StepCode prints CJK diagnostics (未登录), // and a multibyte character split across two chunks would decode to U+FFFD on both halves, so the // not-signed-in detection that matches on that text would stop firing. child.stderr?.setEncoding("utf8"); child.stderr?.on("data", (chunk: string) => { this.#touch(); this.#stderrTail = (this.#stderrTail + chunk).slice(-2000); }); child.stdout?.on("data", (chunk: Buffer) => this.#absorbStdout(chunk)); child.on("error", error => { // A spawn failure such as ENOENT can emit `error` without a following `close`, so the sweep has to // be stopped here too or it lingers on a session that no longer exists. this.#stopIdleSweep(); this.#failAll(error instanceof Error ? error : new Error(String(error))); if (child.pid === undefined) this.#child = undefined; void this.close(); }); child.on("close", () => { this.#leaderExited = true; this.#failAll(new StepSessionError("StepCode exited before the turn settled.")); this.#stopIdleSweep(); void this.close(); }); this.#installIdleSweep(); } #absorbStdout(chunk: Buffer): void { this.#touch(); let frames: StepFrame[]; try { frames = this.#decoder.push(chunk); } catch (error) { // The runtime answers a frame it cannot parse with silence, so writing on into it would hang the // client for the whole request timeout. Fail every waiter and tear the process down instead. this.#failAll(error instanceof StepProtocolViolation ? error : new Error(String(error))); void this.close(); return; } for (const frame of frames) this.#route(frame); } #route(frame: StepFrame): void { if (frame.kind === "response") { const replyTo = frame.replyTo; if (!replyTo) return; const pending = this.#pending.get(replyTo); if (!pending) return; this.#pending.delete(replyTo); this.#settle(pending, frame); return; } if (frame.kind === "request") { this.#holdReverse(frame); return; } this.#handlers.onEvent({ type: "event", frame, session: this }); } #holdReverse(frame: StepFrame): void { const timer = this.#setTimer(() => { if (!this.#held.delete(frame.id)) return; // The expiry is surfaced so the peer can answer the runtime. Without an answer here StepCode // waits out its own 120s window, and a later turn registered for this session would see the same // frame again and re-emit the tool call the client already received. this.#handlers.onEvent({ type: "reverse_request", frame: { ...frame, payload: { ...(frame.payload as object ?? {}), __expired: true } } as StepFrame, session: this, }); }, this.#options.reverseRequestHoldMs); this.#held.set(frame.id, { method: frame.method ?? "unknown", frame, timer, answered: false, }); this.#handlers.onEvent({ type: "reverse_request", frame, session: this }); } #settle(pending: PendingRequest, frame: StepFrame): void { if (pending.answered) return; pending.answered = true; this.#clearTimer(pending.timer as never); if (frame.error) { pending.reject(classifyStepChildError(frame.error)); return; } pending.resolve(frame); } #failAll(error: Error): void { for (const pending of this.#pending.values()) { if (pending.answered) continue; pending.answered = true; this.#clearTimer(pending.timer as never); pending.reject(error); } this.#pending.clear(); } #write(frame: StepFrame): void { const stdin = this.#child?.stdin; if (this.#closed || !stdin?.writable) { throw new StepSessionError("StepCode session is not writable."); } stdin.write(encodeStepFrame(frame, STEP_MAX_FRAME_BYTES)); } #send(id: string, method: string, payload?: unknown, timeoutMs?: number): Promise<StepFrame> { if (this.#closed) return Promise.reject(new StepSessionError("StepCode session is closed.")); let pending!: PendingRequest; const timer = this.#setTimer(() => { if (this.#pending.delete(id)) pending.reject(new StepSessionError(`StepCode did not answer ${method} in time.`, "timeout")); }, timeoutMs ?? this.#options.requestTimeoutMs); const promise = new Promise<StepFrame>((resolve, reject) => { pending = { method, timer, resolve, reject, answered: false }; }); this.#pending.set(id, pending); try { this.#write(stepRequest(id, method, payload)); } catch (error) { this.#pending.delete(id); this.#clearTimer(timer as never); return Promise.reject(error instanceof Error ? error : new Error(String(error))); } return promise; } #respondOk(replyTo: string, payload: unknown): void { try { this.#write(stepResponse(replyTo, payload)); } catch { // A peer that has gone away cannot be told; the session is already failing closed. } } #respondError(replyTo: string, code: string, message: string): void { try { this.#write(stepErrorResponse(replyTo, code, message)); } catch { /* see #respondOk */ } } /** * Negotiate the protocol and verify this route can actually keep tool ownership. */ async handshake(): Promise<StepFrame> { this.#handshake ??= this.#negotiate(); return this.#handshake; } async #negotiate(): Promise<StepFrame> { const response = await this.#send( this.#nextId(), "initialize", { protocolRange: { min: STEP_PROTOCOL_VERSION, max: STEP_PROTOCOL_VERSION } }, this.#options.handshakeTimeoutMs, ); const payload = (response.payload ?? {}) as Record<string, unknown>; const capabilities = Array.isArray(payload.capabilities) ? payload.capabilities.filter((value): value is string => typeof value === "string") : []; const missing = REQUIRED_CAPABILITIES.filter(capability => !capabilities.includes(capability)); if (missing.length > 0) { throw new StepSessionError( `This StepCode build does not advertise ${missing.join(", ")}, so it cannot keep tool ownership for a proxied turn.`, "step_cli_capability_missing", ); } return response; } /** * Open one query and return its ids. * * `hasPermissionCallback` is what disables StepCode's fail-closed default: without it an * approval-requiring tool is blocked and the run terminated before this peer is ever consulted. * `permissionMode` is sent explicitly for the same reason — the CLI otherwise starts in * "Full Access (auto-resume)". */ async startQuery(options: { model: string | undefined; maxThinkingTokens: number | undefined; sdkTools: readonly unknown[]; streamingInput: boolean; }): Promise<{ queryId: string; sessionId: string }> { const response = await this.#send(this.#nextId(), "query.start", { streamingInput: options.streamingInput, options: { ...(options.model ? { model: options.model } : {}), ...(typeof options.maxThinkingTokens === "number" ? { maxThinkingTokens: options.maxThinkingTokens } : {}), permissionMode: "default", hasPermissionCallback: true, includePartialMessages: true, sdkTools: options.sdkTools, }, }); const payload = (response.payload ?? {}) as Record<string, unknown>; if (typeof payload.sessionId === "string") this.#sessionId = payload.sessionId; const queryId = typeof payload.queryId === "string" ? payload.queryId : undefined; if (!queryId) throw new StepSessionError("query.start returned no queryId.", "step_cli_protocol_violation"); return { queryId, sessionId: this.#sessionId ?? "" }; } /** * Queue one user message. * * Only text and images survive this hop, which is exactly why the session must outlive a request * instead of being rebuilt from a replayed transcript. */ async sendInput(queryId: string, text: string): Promise<void> { await this.#send(this.#nextId(), "query.input", { queryId, message: { type: "user", message: { role: "user", content: [{ type: "text", text }] } }, }); } /** Answer a permission already checked against the owning turn and catalog. */ allowPermission(frame: StepFrame): void { this.#respondOk(frame.id, { behavior: "allow" }); this.#releaseReverse(frame.id); } /** * Refuse a tool call with a reason the model can act on. * * A tool result frame carrying only `{message}` is not a refusal: StepCode reads `payload.content` * and renders an absent content list as an EMPTY result, which the model reports as a tool that ran * and produced nothing. Only an `error` envelope throws inside the SDK tool wrapper. */ refuseToolCall(frame: StepFrame, reason: string): void { this.#respondError(frame.id, "TOOL_NOT_AVAILABLE", reason); this.#releaseReverse(frame.id); } #releaseReverse(id: string): void { const held = this.#held.get(id); if (held) { held.answered = true; this.#clearTimer(held.timer as never); this.#held.delete(id); } } /** Refuse a `permission.request` with a reason the model can act on. */ denyPermission(frame: StepFrame, reason: string): void { this.#respondOk(frame.id, { message: reason }); this.#releaseReverse(frame.id); } /** * Deliver a client-executed tool result to the call this session is holding open. * * Returns false when nothing is held for that frame — the runtime's own timer already fired, or * the session was reaped — so the caller reports a too-slow tool instead of continuing against a * call the model has already been told was denied. */ resolveHeldToolResult(frame: StepFrame, result: { content: readonly unknown[]; isError?: boolean }): boolean { const held = this.#held.get(frame.id); if (!held || held.answered || held.method !== "sdk_tool.invoke") return false; held.answered = true; this.#clearTimer(held.timer as never); this.#held.delete(frame.id); this.#respondOk(frame.id, { content: result.content, ...(result.isError === true ? { isError: true } : {}), }); this.#touch(); return true; } /** Reverse requests still waiting on this peer, in arrival order. */ heldReverseRequests(): StepFrame[] { return [...this.#held.values()].filter(entry => !entry.answered).map(entry => entry.frame); } /** * Close this query's input stream with `query.input_end`. * * Not optional housekeeping: StepCode's `#maybeFinish` refuses to finish a query whose input has * not ended, so without this the runtime's single query slot is never released and the NEXT * `query.start` on the same process fails with SESSION_BUSY. A multi-turn text conversation would * therefore work for exactly one turn. * * Deliberately not sent when a tool call was captured: that query is still owed the client's tool * result, and ending its input would let the runtime finish it before the model continues. */ async endInput(queryId: string): Promise<void> { if (this.#closed) return; await this.#send(this.#nextId(), "query.input_end", { queryId }, this.#options.requestTimeoutMs); } /** StepCode's `query.interrupt`, used when the client aborts a turn mid-flight. */ async interrupt(queryId: string): Promise<void> { if (this.#closed) return; await this.#send(this.#nextId(), "query.interrupt", { queryId }); } #installIdleSweep(): void { const interval = Math.max(1_000, Math.min(this.#options.idleTimeoutMs, 60_000)); const sweep = (): void => { if (this.#closed) return; if (this.idleMs() >= this.#options.idleTimeoutMs) { void this.close(); return; } this.#idleTimer = this.#setTimer(sweep, interval); }; this.#idleTimer = this.#setTimer(sweep, interval); } #stopIdleSweep(): void { if (!this.#idleTimer) return; this.#clearTimer(this.#idleTimer as never); this.#idleTimer = undefined; } closeBy(deadlineMs: number): void { if (deadlineMs < this.#shutdownDeadlineMs && !this.#cleanupComplete) { this.#shutdownDeadlineMs = deadlineMs; clearTimeout(this.#shutdownTimer); const delayMs = deadlineMs - SHUTDOWN_KILL_MARGIN_MS - Date.now(); if (delayMs <= 0) this.#urgentCleanup.abort(); else this.#shutdownTimer = setTimeout(() => this.#urgentCleanup.abort(), delayMs); } void this.close(); } /** Start queued tree kills and signal any still-owned POSIX group before returning. */ forceShutdown(): void { this.#urgentCleanup.abort(); const child = this.#child; if (this.#platform === "win32" || child?.pid === undefined) return; try { this.#signalPosixGroup(child, child.pid, "SIGKILL"); } catch (error) { // If the group operation failed, the child handle can still stop the leader. // Preserve the failure receipt because the descendants are unconfirmed. if (this.#hasLiveLeader(child)) child.kill("SIGKILL"); throw error; } } /** * Reap the owned process tree before releasing this session. Concurrent callers share cleanup. */ close(code = 0): Promise<void> { if (this.#closePromise) return this.#closePromise; this.#closed = true; this.#stopIdleSweep(); const child = this.#child; this.#failAll(new StepSessionError(`StepCode session closed (${code}).`)); for (const held of this.#held.values()) this.#clearTimer(held.timer as never); this.#held.clear(); // Publish the receipt before termination can emit close or notify pool bookkeeping. const receipt = Promise.withResolvers<void>(); this.#closePromise = receipt.promise; // Timer/protocol-initiated closes have no awaiting caller. Keep the rejection in the cached // receipt for close()/pool shutdown, while observing it here to avoid an unhandled rejection. void this.#closePromise.catch(() => {}); const terminate = async (): Promise<void> => { if (child) await withCleanupSlot(() => this.#terminateWithRetry(child), this.#urgentCleanup.signal); this.#cleanupComplete = true; this.#announceExit(); }; void terminate().finally(() => clearTimeout(this.#shutdownTimer)).then(receipt.resolve, receipt.reject); return this.#closePromise; } async #terminateWithRetry(child: ChildProcess): Promise<void> { const failures: unknown[] = []; const usesTaskkill = this.#platform === "win32" && child.pid !== undefined; const recordWindowsOwnershipLoss = (): void => { console.warn(WINDOWS_PID_UNCONFIRMED); failures.push(new StepSessionError(WINDOWS_PID_UNCONFIRMED, "step_cli_cleanup_failed")); }; for (let attempt = 0; attempt < CLEANUP_ATTEMPTS; attempt++) { if (usesTaskkill && !this.#hasLiveLeader(child)) { recordWindowsOwnershipLoss(); break; } try { await this.#terminate(child); return; } catch (error) { failures.push(error); if (usesTaskkill && this.#windowsTreeKillAttempted) { recordWindowsOwnershipLoss(); break; } if (this.#posixGroupSignalState === "lost") break; } } throw Object.assign(new StepSessionError( "StepCode process cleanup failed; conversation handle is quarantined.", "step_cli_cleanup_failed", ), { cause: new AggregateError(failures, "StepCode tree termination attempts failed.") }); } async #terminate(child: ChildProcess): Promise<void> { if (this.#platform !== "win32" && child.pid !== undefined) { await this.#terminatePosixGroup(child, child.pid); } else { await this.#terminateChild(child); } child.stdin?.destroy(); child.stdout?.destroy(); child.stderr?.destroy(); child.unref?.(); this.#child = undefined; } #hasLiveLeader(child: ChildProcess): boolean { return !this.#leaderExited && child.exitCode === null && child.signalCode === null; } #signalPosixGroup(child: ChildProcess, pid: number, signal: "SIGTERM" | "SIGKILL"): void { if (this.#posixGroupSignalState === "finished") return; // The detached leader anchors the PGID only until exit. Check on every signal. if (!this.#hasLiveLeader(child)) { if (this.#posixGroupSignalState === "pending") { this.#posixGroupSignalState = "lost"; console.warn(POSIX_LEADER_EXITED); } throw new StepSessionError(POSIX_LEADER_EXITED, "step_cli_cleanup_failed"); } try { process.kill(-pid, signal); if (signal === "SIGKILL") this.#posixGroupSignalState = "finished"; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; this.#posixGroupSignalState = "finished"; } } async #terminatePosixGroup(child: ChildProcess, pid: number): Promise<void> { const escalateAt = performance.now() + this.#killGraceMs; const deadline = escalateAt + KILL_CONFIRMATION_MS; if (!this.#urgentCleanup.signal.aborted && this.#shutdownDeadlineMs - Date.now() > SHUTDOWN_KILL_MARGIN_MS) { this.#signalPosixGroup(child, pid, "SIGTERM"); while (this.#posixGroupSignalState === "pending" && this.#hasLiveLeader(child) && !this.#urgentCleanup.signal.aborted) { const untilKill = Math.min(escalateAt - performance.now(), this.#shutdownDeadlineMs - Date.now() - SHUTDOWN_KILL_MARGIN_MS); if (untilKill <= 0) break; await Bun.sleep(Math.min(PROCESS_EXIT_POLL_MS, untilKill)); } } this.#signalPosixGroup(child, pid, "SIGKILL"); // Confirm the leader's exit using its child handle. The numeric PGID can be reused. while (this.#hasLiveLeader(child)) { const untilConfirm = Math.min(deadline - performance.now(), this.#shutdownDeadlineMs - Date.now()); if (untilConfirm <= 0) { throw new StepSessionError("StepCode process group cleanup could not be confirmed.", "step_cli_cleanup_failed"); } await Bun.sleep(Math.min(PROCESS_EXIT_POLL_MS, untilConfirm)); } } async #terminateChild(child: ChildProcess): Promise<void> { if ((child.exitCode !== null || child.signalCode !== null) && child.pid === undefined) return; let cancelWait = (): void => {}; const exited = new Promise<void>(resolve => { const finish = (): void => { cancelWait(); resolve(); }; child.once("close", finish); cancelWait = () => child.removeListener("close", finish); }); let timer: ReturnType<typeof setTimeout> | undefined; let deadline: ReturnType<typeof setTimeout> | undefined; let failCleanup!: (error: unknown) => void; const cleanupFailed = new Promise<never>((_, reject) => { failCleanup = reject; }); const gone = (): boolean => { return !this.#hasLiveLeader(child) || (child.pid !== undefined && processIsGone(child.pid)); }; const signal = (kind: NodeJS.Signals): void => { try { child.kill(kind); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; } }; try { if (child.pid !== undefined) { this.#windowsTreeKillAttempted = true; try { await (this.#deps.killWindowsProcessTree ?? killWindowsProcessTreeAsync)(child.pid); } catch (error) { // After a failed or timed-out taskkill, the wrapper may already have exited and Bun // may have released its handle. Retry only when taskkill itself failed to start. const failure = error instanceof Error ? error as NodeJS.ErrnoException : undefined; if ((failure?.code === "ENOENT" || failure?.code === "EACCES") && failure.syscall?.startsWith("spawn ")) { this.#windowsTreeKillAttempted = false; } throw error; } // Bun on Windows can retain null exit/signal fields after taskkill has reaped the tree. // Check the OS only when Bun has not already observed the original wrapper's exit. if (gone()) return; } else { signal("SIGTERM"); timer = this.#setTimer(() => { try { signal("SIGKILL"); } catch (error) { failCleanup(error); } }, this.#killGraceMs); } await Promise.race([exited, cleanupFailed, new Promise<void>((resolve, reject) => { deadline = this.#setTimer(() => { try { if (gone()) resolve(); else reject(new StepSessionError("StepCode process cleanup could not be confirmed.", "step_cli_cleanup_failed")); } catch (error) { reject(error); } }, this.#killGraceMs + KILL_CONFIRMATION_MS); })]); } finally { if (timer !== undefined) this.#clearTimer(timer as never); if (deadline !== undefined) this.#clearTimer(deadline as never); cancelWait(); } } } /** Resolve this route's binary, or explain how to install it. */ export function resolveStepCliBinaryPath(which?: WhichFn): string { const found = findStepCliBinary(STEP_CLI_PROFILE.binaryCandidates[0]!, which); if (found) return found; throw new StepSessionError( `${STEP_CLI_PROFILE.label} is not installed. ${STEP_CLI_PROFILE.installHint}.`, "step_cli_binary_missing", ); } /** Env and working directory for one session process. */ export function stepCliProcessEnvironment(openCodexHome: string): { env: Record<string, string>; cwd: string } { const sessions = stepCliSessionDir(openCodexHome); return { env: buildStepCliEnv(openCodexHome), cwd: dirname(sessions) }; } export { buildStepCliEnv } from "./env"; export type { StepCliProfile };