import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig } from "../../types"; import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "../base"; import { getConfigDir } from "../../config/paths"; import { CODING_AGENT_TOOL_LIMITS } from "../coding-agent/tool-catalog"; import { ConversationQueueFullError, ownedConversationHandle, withConversationLock } from "./conversation"; import { STEP_CLI_HOST, STEP_CLI_TOOL_SERVER } from "./constants"; import { sessionHandlers } from "./events"; import { mapSessionFailure, refusal } from "./errors"; import { abortSignal, composePrompt, hasImageInput, latestToolResult, pendingUserText, stepModelId, stepThinkingTokens, type StepProviderState, } from "./projection"; import { resolveStepCliProfile, STEP_CLI_PROFILE, type StepCliProfile } from "./profiles"; import { beginTurn, clearStepCliSessions, currentQuery, currentTurn, endTurn, forgetQuery, poolFor, rememberQuery, } from "./registry"; import { StepSessionError, type StepSessionDeps } from "./session"; import type { StepConversationHost, StepConversationRef, StepConversationSession } from "./session-pool"; import { buildStepSdkTools, StepToolCatalogError } from "./tool-bridge"; import type { StepFrame } from "./stdio-frames"; /** * Codex turns against a Step Plan subscription. * * This module is the ORCHESTRATION layer and nothing else: it decides what one turn is, in what order * it runs, and when it has produced a terminal event. Converting between the client's request shape * and the CLI's is `projection`, mapping the CLI's frames back is `events`, conversation identity and * turn ordering are `conversation`, and everything that must outlive a request is `registry`. */ export interface StepCliAdapterDeps extends StepSessionDeps { /** Injection seam so tests drive the real `runTurn` path without a CLI. */ openSession?: StepConversationHost; } /** * Per-request turn state, keyed by the process that owns it. * * `createStepCliAdapter` runs once per request, so nothing that has to survive a request boundary can * live in its closure: a reverse request arriving during request N+1 would be routed to an instance * that no longer exists, and the conversation would silently restart. `devin/trajectory.ts` keeps its * conversation map at module scope for the same reason. */ /** * Hard ceiling on waiting for a terminal event from the CLI. * * The turn would otherwise wait for the client's abort, and a client that never aborts (or a CLI that * went quiet) would hold the conversation lock for the life of the process. Set well above * StepCode's own 120s tool window so a legitimate slow tool is never cut short. */ const STEP_CLI_TERMINAL_DEADLINE_MS = 10 * 60_000; /** * Backoff for re-opening a query the runtime still considers busy. * * A turn settles when the CLI reports `turn_complete`, which can be a moment before the runtime frees * its single query slot. Measured on the real CLI: the very next request on the same conversation then * failed with `SESSION_BUSY`. The conversation lock means no other turn of ours is in flight while this * runs, so retrying here cannot collide with our own work — it is only bridging the runtime's own * handover delay. */ const STEP_CLI_QUERY_RETRY_DELAYS_MS = [200, 600, 1500] as const; /** * Run Codex turns against a StepCode subscription. * * One StepCode process serves one conversation, and this adapter never executes a tool itself: it * declares the client's catalog as StepCode SDK tools, allows the permission check the client's own * request already implies, and holds the tool call open so the result the client computes on its next * request is delivered back into the query the model is running. */ export function createStepCliAdapter( provider: OcxProviderConfig, deps: StepCliAdapterDeps = {}, ): ProviderAdapter { const profile: StepCliProfile | undefined = resolveStepCliProfile(provider.baseUrl); return { name: STEP_CLI_HOST, buildRequest(): AdapterRequest { return { url: provider.baseUrl, method: "POST", headers: {}, body: "" }; }, async *parseStream(): AsyncGenerator { yield { type: "error", message: "StepCode CLI adapter uses runTurn; the fetch/parseStream path is disabled.", }; }, async runTurn(parsed, incoming, emit): Promise { if (!profile) { emit( refusal( "This provider row is not pointed at StepCode's canonical destination, so the CLI's own account is never reached.", 400, "step_cli_profile_mismatch", ), ); return; } if (incoming.abortSignal?.aborted) return emitPreDispatchAbort(emit); if (hasImageInput(parsed)) { emit( refusal( "StepCode image input is not enabled because this CLI route has no verified multimodal contract.", 400, "unsupported_input_modality", ), ); return; } let tools: ReturnType; try { tools = buildStepSdkTools(parsed, STEP_CLI_TOOL_SERVER); } catch (error) { if (!(error instanceof StepToolCatalogError)) throw error; // Name the numbers. Codex with many MCP servers flattens every remote tool into the function // catalog (measured on a real Codex 0.162.0 client: 1749 tools, 2.5 MB), and the shared // CLI-family ceiling is 128 tools / 2 MiB — the same bound `qoder`, `codebuddy` and // `claude-cli` enforce. An operator seeing only "exceeds tool count limit" cannot tell a // malformed catalog from an oversized one. const declared = parsed.context.tools?.length ?? 0; emit( refusal( `This request declares ${declared} tools, over the ${CODING_AGENT_TOOL_LIMITS.maxTools}-tool ceiling ` + `every CLI-backed provider shares. Codex flattens each MCP server's tools into this catalog, so an ` + `MCP-heavy setup reaches the ceiling; drop or disable MCP servers for this provider, or narrow the ` + `tool set in the request. Detail: ${error.message}`, 400, "tool_catalog_invalid", ), ); return; } let sessions: StepConversationHost; try { sessions = deps.openSession ?? poolFor(getConfigDir(), deps, sessionHandlers); } catch (error) { emit(mapSessionFailure(error)); return; } // Admission owns the namespace; thread headers only select a conversation within it. // Requests without caller ownership receive a private process. const identified = ownedConversationHandle(parsed, incoming, provider); const ref: StepConversationRef = identified ? { handle: identified, sessionId: "" } : sessions.nextRef(); let session!: StepConversationSession; try { session = await sessions.open(ref); await session.handshake(); } catch (error) { await session?.close(); emit(mapSessionFailure(error)); return; } // From here on this turn owns the conversation's process and its turn state, so anything else // arriving for the same conversation waits rather than corrupting it. try { await withConversationLock(ref.handle, () => driveTurn(parsed, incoming, emit, { sessions, session, ref, tools, setTimer: deps.setTimeout ?? setTimeout, clearTimer: deps.clearTimeout ?? clearTimeout, }), ); } catch (error) { if (error instanceof ConversationQueueFullError) { // The queue cap is a refusal, not a crash, and this caller never owned the conversation: the // session it was handed is the one serving the accepted turn and its queue. Closing it here // would disconnect every one of them to turn away a single extra request. emit( refusal(error.message, 409, "step_cli_conversation_busy", "rate_limit_error", true), ); return; } // Anything else was raised by this turn after it owned the conversation, so the session state // is no longer trustworthy and is closed. emit(mapSessionFailure(error)); await session.close(); } finally { // Keyless callers have no cross-request ownership proof. Their process is request-local. if (!identified) await session.close(); } }, }; } /** * Open a query, retrying only while the runtime reports its single slot is still busy. * * Every other failure propagates immediately: a capability or transport problem must not be turned * into three silent attempts. */ async function startQueryWithBusyRetry( session: StepConversationSession, options: { model: string | undefined; maxThinkingTokens: number | undefined; sdkTools: readonly unknown[]; streamingInput: boolean }, signal: AbortSignal | undefined, delay: (ms: number) => Promise = ms => new Promise(resolve => setTimeout(resolve, ms)), ): Promise<{ queryId: string; sessionId: string } | undefined> { let attempt = 0; while (!signal?.aborted) { try { return await session.startQuery(options); } catch (error) { const busy = error instanceof StepSessionError && error.code === "step_cli_session_busy"; if (!busy || attempt >= STEP_CLI_QUERY_RETRY_DELAYS_MS.length) throw error; if (signal?.aborted) return; await delay(STEP_CLI_QUERY_RETRY_DELAYS_MS[attempt]!); attempt += 1; } } } function emitPreDispatchAbort(emit: (event: AdapterEvent) => void): void { emit({ type: "error", message: "StepCode turn was aborted before start.", retryable: false }); } async function driveTurn( parsed: OcxParsedRequest, incoming: IncomingMeta, emit: (event: AdapterEvent) => void, context: { sessions: StepConversationHost; session: StepConversationSession; ref: StepConversationRef; tools: ReturnType; setTimer: typeof setTimeout; clearTimer: typeof clearTimeout; }, ): Promise { if (incoming.abortSignal?.aborted) return emitPreDispatchAbort(emit); const { sessions, session, ref, tools, setTimer, clearTimer } = context; // A matching held result resumes its original query. An abandoned call must finish // unwinding without a turn before the replacement is registered. const held = sessions.takeHeldTool(ref); const heldResult = held ? latestToolResult(parsed) : undefined; // Matched by CALL ID, never by position: a client may follow a tool call with a new user // message instead of a result, in which case the newest result in the transcript belongs to an // earlier call and delivering it would answer the wrong question. // A client that cancels the call and sends only new user text has no tool result in its // transcript at all, so `heldResult` can be undefined while `held` exists. const heldMatches = held !== undefined && heldResult !== undefined && heldResult.toolCallId === held.callId; // This turn IS the answer to a captured call: the model already has the instruction and is // mid-query, so nothing is prompted again. const continuedQuery = Boolean(held) && heldMatches; // The client sent something other than the held call's result — typically a new user message. // The query that owned the call is unwinding; leaving it running would make this request's own // text unstartable, and swallowing that text would lose the user's turn entirely. const abandonedQueryId = Boolean(held) && !heldMatches; const catalogKey = JSON.stringify(tools.sdkTools); if (held && (held.queryId !== currentQuery(session) || held.catalogKey !== catalogKey)) { emit(refusal("The held StepCode call belongs to a different query or tool catalog.", 409, "step_cli_tool_owner_mismatch")); await session.close(); return; } // Text is suppressed ONLY when this turn really is the answer to the held call; a turn that // abandoned the call still carries the user's message and must keep it. const userText = continuedQuery ? undefined : pendingUserText(parsed); if (!continuedQuery && !userText) { emit( refusal( "StepCode carries conversation history inside its own process, so a turn must end with either user text or a tool result.", 400, "step_cli_no_user_text", ), ); return; } if (abandonedQueryId && held) { // Detach the old owner before releasing its hold: completion can arrive synchronously. endTurn(session); forgetQuery(session); session.resolveHeldToolResult( { id: held.frameId, method: "sdk_tool.invoke" } as StepFrame, { content: [{ type: "text", text: "" }], isError: true }, ); await session.interrupt(held.queryId); await session.endInput(held.queryId); } let settle!: () => void; const done = new Promise(resolve => { settle = resolve; }); beginTurn(session, { ref, pool: sessions, emit, settle, emittedNames: tools.emittedNameMap, catalogKey, ...(continuedQuery && held ? { queryId: held.queryId } : {}), }); // Registered FIRST, delivered second. See the comment above: the CLI can answer the moment it // receives the result. if (held && continuedQuery) { const delivered = session.resolveHeldToolResult( { id: held.frameId, method: "sdk_tool.invoke" } as StepFrame, heldResult!, ); if (!delivered) { endTurn(session); emit( refusal( "The held StepCode tool call expired before the tool result arrived; StepCode only waits two minutes for one.", 504, "step_cli_tool_result_too_late", "upstream_error", ), ); await session.close(); return; } } let queryId: string | undefined; let deadlineTimer: unknown; try { if (!continuedQuery) { const started = await startQueryWithBusyRetry(session, { model: stepModelId(parsed.modelId), maxThinkingTokens: stepThinkingTokens(parsed), sdkTools: tools.sdkTools, streamingInput: true, }, incoming.abortSignal); if (!started) { endTurn(session); settle(); return emitPreDispatchAbort(emit); } queryId = started.queryId; rememberQuery(session, queryId); if (!incoming.abortSignal?.aborted) { await session.sendInput(queryId, composePrompt(parsed, userText ?? "")); } } } catch (error) { endTurn(session); settle(); emit(mapSessionFailure(error)); await session.close(); return; } // The turn owns the response until it settles: text, a captured tool call, a completion, the // client's abort, or the hard deadline. Returning before that leaves the stream without a // terminal event; never returning would hold the conversation lock forever. await Promise.race([ done, abortSignal(incoming), new Promise(resolve => { deadlineTimer = setTimer(resolve, STEP_CLI_TERMINAL_DEADLINE_MS); }), ]); clearTimer(deadlineTimer as never); if (currentTurn(session) === undefined) return; // The turn is still registered, so nothing terminated it: either the client aborted, or the CLI // went quiet. Either way the query is still running inside StepCode, and since it serves one // query at a time the NEXT request for this conversation would be rejected or blocked by it. // Interrupt it, and close the session when the interrupt cannot be confirmed. endTurn(session); emit({ type: "error", message: "The StepCode turn ended without a terminal event.", status: 502, errorType: "upstream_error", code: "step_cli_turn_abandoned", retryable: true, }); settle(); if (queryId) { await session.interrupt(queryId); if (session.closed) return; } await session.close(); } export { STEP_CLI_PROFILE, clearStepCliSessions };