@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
text/typescript
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 };