xonecas.io
64875
Mc

mini-coder / commit 5f7d426

fix: get Codex (gpt-5.3-codex) working via Responses API + autonomy prompt

- Route gpt-* models through sdk.responses() instead of the default
  chat completions endpoint — required for all GPT-5.x Codex models
- Add CODEX_AUTONOMY directives to the system prompt when a codex model
  is detected: bias to action, no preambles, no asking permission
- Extract parseModelString() helper in providers.ts; use it in
  isOpenAIGPT (turn.ts), isCodexModel (agent.ts), and getContextWindow
  (providers.ts) to eliminate duplicated indexOf/slice logic
- Drop dead modelString !== undefined guard in useInstructions (typed string)
- Remove GPT_CONTINUATION nudge — superseded by CODEX_AUTONOMY

Sean2026-03-01 5f7d4263f4c181db40c5f7e7cc1a094a6013f94e parent ee72662

4 files changed

codex-lazy-fix.md+169−0
@@ -0,0 +1,169 @@
1+# Codex Lazy Fix Plan
2+
3+## Analysis: Why Codex Refuses to Work
4+
5+### Session Evidence
6+
7+All recent Codex sessions (`zen/gpt-5.3-codex`) were examined from the DB (`~/.config/mini-coder/sessions.db`). The pattern is consistent across every session:
8+
9+1. **Model receives task** → calls a tool or two (usually `glob` or `read`) showing initial compliance.
10+2. **Stalls immediately after first exploration** → instead of continuing to implement, outputs a verbose multi-paragraph response saying it *will* do the work, then hands control back to the user.
11+3. **Ralph mode doesn't help** — In ralph mode the session just re-starts clean each iteration, so the model sees the original prompt again, does 1-2 tool calls, then stalls again and outputs the planning text. The loop repeats without progress. In one session (12 messages), the model read three files and stopped five times asking to "proceed" before the user gave up.
12+
13+#### Concrete Example (session `mm7yk178-ctvsx`)
14+```
15+user: [long plan] "please implement this plan, start working on each turn"
16+assistant: [glob tool call] → [3x read tool calls]
17+assistant: "I can't complete that in one pass safely. This is a large multi-workstream refactor...
18+ Reply **"proceed"** and I'll start implementing batch 1 immediately."
19+```
20+
21+The model never wrote a single file. It read files, described what it *would* do, then stopped and asked for permission. Every Codex session ends this same way.
22+
23+---
24+
25+### Root Cause: Three Compounding Problems
26+
27+#### 1. Wrong API endpoint — Chat Completions instead of Responses API
28+
29+**mini-coder** uses `@ai-sdk/openai` via `createOpenAI()`, which defaults to the **Chat Completions** endpoint (`/v1/chat/completions`).
30+
31+**OpenAI's own Codex CLI**, **opencode**, and the official [Codex Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide/) all use the **Responses API** (`/v1/responses`). The Responses API is the only supported pathway for GPT-5.x Codex models — the prompting guide explicitly states: *"This model is only supported with the Responses API."*
32+
33+In opencode's `provider.ts`, for the `openai` provider:
34+```ts
35+openai: async () => {
36+ return {
37+ autoload: false,
38+ async getModel(sdk: any, modelID: string) {
39+ return sdk.responses(modelID) // ← Responses API, not sdk.chat()
40+ },
41+ }
42+}
43+```
44+
45+In mini-coder's `providers.ts`:
46+```ts
47+function zenOpenAI() {
48+ _zenOpenAI = createOpenAI({ apiKey: ..., baseURL: ZEN_BASE })
49+ // createOpenAI()(...) defaults to chat completions, not responses
50+}
51+```
52+
53+The `@ai-sdk/openai` SDK v3+ exposes `.responses(modelId)` to select the Responses API. mini-coder never calls it — so Codex receives requests on the wrong endpoint. This alone can cause the model to fail or fall back to a degraded behaviour mode.
54+
55+#### 2. System prompt delivered in wrong position
56+
57+The Responses API treats the `instructions` field as a high-authority system prompt. A `system`-role message in the `input` array is treated as a lower-priority user turn and **deprioritised** by the model.
58+
59+mini-coder's `turn.ts` already has partial mitigation — it sends `instructions` via `providerOptions.openai.instructions` for GPT models:
60+```ts
61+const useInstructions = systemPrompt !== undefined && isOpenAIGPT(modelString)
62+// ...
63+providerOptions: { openai: { instructions: systemPrompt + GPT_CONTINUATION } }
64+```
65+
66+However, `isOpenAIGPT` only returns `true` for `zen/*` and `openai/*` prefixes with model IDs starting with `"gpt-"`. The model id `gpt-5.3-codex` does start with `gpt-`, so this *should* be active. But if the Responses API isn't being invoked at all (problem #1), this is moot — the `instructions` field has no effect on Chat Completions.
67+
68+#### 3. System prompt content drives the stall behaviour
69+
70+The mini-coder system prompt is terse and generic:
71+```
72+Be concise and precise. Avoid unnecessary preamble.
73+Prefer small, targeted edits over large rewrites.
74+...
75+When in doubt, ask the user before making destructive changes.
76+```
77+
78+GPT-5.3-Codex is a **reasoning model tuned for agentic autonomy**. Its training specifically rewards:
79+- Asking for confirmation before proceeding
80+- Breaking large tasks into batches and requesting approval
81+- Hedging about "one pass" safety
82+
83+This is why it keeps stopping and asking "Reply 'proceed'". Its training RLHF pushes it toward collaborative, permission-seeking behaviour unless the system prompt explicitly overrides this with **strong autonomy and persistence directives**.
84+
85+The official Codex prompting guide is emphatic:
86+> *"Remove all prompting for the model to communicate an upfront plan, preambles, or other status updates during the rollout, as this can cause the model to stop abruptly before the rollout is complete."*
87+> *"You should also remove any prompting for the model to communicate an upfront plan, preambles, or other status updates during the rollout."*
88+
89+mini-coder's prompt has no autonomy directives. The `GPT_CONTINUATION` hint (`"Always make tool calls rather than describing them. Keep going until the task is complete, then stop."`) is a good start, but it's appended to instructions that never reach the model through the correct channel.
90+
91+---
92+
93+## Fix Plan
94+
95+### Fix 1 — Wire the Responses API for Codex/GPT models (critical)
96+
97+In `src/llm-api/providers.ts`, the `zenOpenAI` and `directOpenAI` factory functions must call `.responses(modelId)` instead of the default `.chat()`:
98+
99+```ts
100+// Current (wrong for Codex):
101+createOpenAI({ apiKey, baseURL })("gpt-5.3-codex")
102+// → resolves to chat completions endpoint
103+
104+// Correct:
105+createOpenAI({ apiKey, baseURL }).responses("gpt-5.3-codex")
106+// → resolves to Responses API endpoint
107+```
108+
109+The `@ai-sdk/openai` provider exposes `sdk.responses(modelId)` to opt into the Responses API. We need to route `gpt-*` models through `.responses()` and leave others on the default.
110+
111+**Implementation:**
112+- Add a helper `isGPTModel(modelId: string): boolean` — returns true for `gpt-` prefixed IDs.
113+- In `resolveModel()`, when provider is `zen` or `openai` and model is a GPT, call `.responses(modelId)` on the created SDK instance.
114+
115+This mirrors exactly what opencode does in its `CUSTOM_LOADERS.openai` and what official Codex CLI does.
116+
117+### Fix 2 — Strengthen the Codex-specific system prompt (critical)
118+
119+Add a Codex-aware system prompt variant in `src/agent/agent.ts` (or a new `src/llm-api/codex-prompt.ts`). When the model is a Codex model, append (or replace) the system prompt with autonomy-first directives drawn from the official Codex prompting guide:
120+
121+Key additions:
122+- **Autonomy and persistence**: "Once given a direction, proactively gather context, plan, implement, test, and refine without waiting for additional prompts. Persist until the task is fully handled end-to-end."
123+- **Bias to action**: "Default to implementing with reasonable assumptions. Do not end your turn with clarifications unless truly blocked."
124+- **No preambles / no plans**: "Do not output an upfront plan, preambles, or status updates before working. Start working immediately."
125+- **No asking permission**: "Do not ask 'shall I proceed?' or 'shall I start?'. Start working."
126+
127+A helper `isCodexModel(modelString: string): boolean` should gate this (e.g., `modelId.includes("codex")`).
128+
129+### Fix 3 — Add `reasoningEffort` for Codex models (important)
130+
131+opencode sets `reasoningEffort: "medium"` by default for `gpt-5.*` models, and supports `high`/`xhigh` for Codex. The official guide recommends `"medium"` as the all-around default and `"high"`/`"xhigh"` for hardest tasks.
132+
133+In `turn.ts`, when building `streamOpts` for a Codex model, include:
134+```ts
135+providerOptions: {
136+ openai: {
137+ instructions: ...,
138+ store: false,
139+ reasoningEffort: "medium",
140+ }
141+}
142+```
143+
144+### Fix 4 — Strip `itemId` from Responses API messages (correctness)
145+
146+opencode strips the `itemId` field from items in the `input` array when re-submitting to the Responses API (following what Codex CLI itself does). Without this, the API may reject or misbehave on multi-turn conversations. This should be done at the fetch layer or message serialisation layer.
147+
148+---
149+
150+## Implementation Order
151+
152+1. **Fix 1** — Responses API wiring in `providers.ts` (unblocks everything)
153+2. **Fix 2** — Codex system prompt additions in `agent.ts` / `turn.ts`
154+3. **Fix 3** — `reasoningEffort: "medium"` default in `turn.ts`
155+4. **Fix 4** — Strip `itemId` from outbound messages (multi-turn correctness)
156+
157+Fixes 1 and 2 together should be sufficient to get Codex performing. Fixes 3 and 4 are polish/correctness.
158+
159+---
160+
161+## Files to Change
162+
163+| File | Change |
164+|---|---|
165+| `src/llm-api/providers.ts` | Route `gpt-*` through `.responses()` for `zen`/`openai` providers |
166+| `src/llm-api/turn.ts` | Add `reasoningEffort`, update `isOpenAIGPT` to cover codex, strip itemIds |
167+| `src/agent/agent.ts` | Add Codex-specific autonomy directives to system prompt when Codex model detected |
168+
169+No new dependencies needed — `@ai-sdk/openai` already exposes `.responses()`.
src/agent/agent.ts+34−7
@@ -25,7 +25,11 @@ import {
2525 } from "../cli/output.ts";
2626 import { loadSkills } from "../cli/skills.ts";
2727
28-import { getContextWindow, resolveModel } from "../llm-api/providers.ts";
28+import {
29+ getContextWindow,
30+ parseModelString,
31+ resolveModel,
32+} from "../llm-api/providers.ts";
2933 import { type CoreMessage, runTurn } from "../llm-api/turn.ts";
3034 import type { ToolDef } from "../llm-api/types.ts";
3135 import { connectMcpServer } from "../mcp/client.ts";
@@ -95,7 +99,26 @@ function loadContextFile(cwd: string): string | null {
9599
96100 // ─── System prompt ────────────────────────────────────────────────────────────
97101
98-function buildSystemPrompt(cwd: string): string {
102+// Extra directives injected when the model is a Codex variant.
103+// Codex is RLHF-tuned to be collaborative and permission-seeking by default;
104+// without these overrides it will read a few files, describe what it *plans*
105+// to do, and then stop — even in ralph mode. The Responses API `instructions`
106+// field (used for all gpt-* models) is the authoritative channel for these.
107+const CODEX_AUTONOMY = `
108+# Autonomy and persistence
109+- You are an autonomous senior engineer. Once given a direction, proactively gather context, implement, test, and refine without waiting for additional prompts at each step.
110+- Persist until the task is fully handled end-to-end within the current turn: do not stop at analysis or partial work; carry changes through to implementation and verification.
111+- Bias to action: default to implementing with reasonable assumptions. Do not end your turn with clarifications or requests to "proceed" unless you are truly blocked on information only the user can provide.
112+- Do NOT output an upfront plan, preamble, or status update before working. Start making tool calls immediately.
113+- Do NOT ask "shall I proceed?", "shall I start?", "reply X to continue", or any equivalent. Just start.
114+- If something is ambiguous, pick the most reasonable interpretation, implement it, and note the assumption at the end.`;
115+
116+function isCodexModel(modelString: string): boolean {
117+ const { modelId } = parseModelString(modelString);
118+ return modelId.includes("codex");
119+}
120+
121+function buildSystemPrompt(cwd: string, modelString?: string): string {
99122 const contextFile = loadContextFile(cwd);
100123 const cwdDisplay = tildePath(cwd);
101124 const now = new Date().toLocaleString(undefined, { hour12: false });
@@ -111,8 +134,11 @@ Guidelines:
111134 - Prefer small, targeted edits over large rewrites.
112135 - Always read a file before editing it.
113136 - Use glob to discover files, grep to find patterns, read to inspect contents.
114-- Use shell for tests, builds, and git operations.
115-- When in doubt, ask the user before making destructive changes.`;
137+- Use shell for tests, builds, and git operations.`;
138+
139+ if (modelString && isCodexModel(modelString)) {
140+ prompt += CODEX_AUTONOMY;
141+ }
116142
117143 if (contextFile) {
118144 prompt += `\n\n# Project context\n\n${contextFile}`;
@@ -209,7 +235,8 @@ export async function runAgent(opts: AgentOptions): Promise<void> {
209235 }
210236
211237 const model = modelOverride ?? agentConfig?.model ?? currentModel;
212- const systemPrompt = agentConfig?.systemPrompt ?? buildSystemPrompt(cwd);
238+ const systemPrompt =
239+ agentConfig?.systemPrompt ?? buildSystemPrompt(cwd, model);
213240
214241 const subMessages: CoreMessage[] = [{ role: "user", content: prompt }];
215242 const laneId = nextLaneId++;
@@ -518,7 +545,7 @@ export async function runAgent(opts: AgentOptions): Promise<void> {
518545 const coreContent = planMode
519546 ? `${resolvedText}\n\n<system-message>PLAN MODE ACTIVE: Help the user gather context for the plan -- READ ONLY</system-message>`
520547 : ralphMode
521- ? `${resolvedText}\n\n<system-message>RALPH MODE: You are in an autonomous loop. You MUST use tools to complete the task above before outputting \`/ralph\`. Do NOT output \`/ralph\` without first making tool calls and doing the work. Only output \`/ralph\` as your final message once all changes are made and verified.</system-message>`
548+ ? `${resolvedText}\n\n<system-message>RALPH MODE: You are in an autonomous loop. You MUST make actual file changes (create, edit, or write files) to complete the requested task before outputting \`/ralph\`. Reading files, running tests, or exploring the codebase does NOT count as doing the work. Only output \`/ralph\` as your final message after all requested changes are implemented and tests pass.</system-message>`
522549 : resolvedText;
523550
524551 // Build the message content — multi-part when images are present
@@ -556,7 +583,7 @@ export async function runAgent(opts: AgentOptions): Promise<void> {
556583 coreHistory.push(userMsg);
557584
558585 const llm = resolveModel(currentModel);
559- const systemPrompt = buildSystemPrompt(cwd);
586+ const systemPrompt = buildSystemPrompt(cwd, currentModel);
560587
561588 let lastAssistantText = "";
562589 // Tracks whether the catch block stub has already been saved, to avoid
src/llm-api/providers.ts+23−5
@@ -12,7 +12,7 @@ const ZEN_BASE = "https://opencode.ai/zen/v1";
1212 // Zen endpoint routing — matched in order, fallthrough to OpenAI-compatible
1313 function zenEndpointFor(modelId: string) {
1414 if (modelId.startsWith("claude-")) return zenAnthropic()(modelId);
15- if (modelId.startsWith("gpt-")) return zenOpenAI()(modelId);
15+ if (modelId.startsWith("gpt-")) return zenOpenAI().responses(modelId);
1616 if (modelId.startsWith("gemini-")) return zenGoogle()(modelId);
1717 return zenCompat()(modelId);
1818 }
@@ -109,6 +109,24 @@ function directGoogle() {
109109 return _directGoogle;
110110 }
111111
112+// ─── Model string parsing ─────────────────────────────────────────────────────
113+
114+/**
115+ * Split a "<provider>/<model-id>" string into its two parts.
116+ * When there is no slash, provider is the full string and modelId is "".
117+ */
118+export function parseModelString(modelString: string): {
119+ provider: string;
120+ modelId: string;
121+} {
122+ const slashIdx = modelString.indexOf("/");
123+ if (slashIdx === -1) return { provider: modelString, modelId: "" };
124+ return {
125+ provider: modelString.slice(0, slashIdx),
126+ modelId: modelString.slice(slashIdx + 1),
127+ };
128+}
129+
112130 // ─── Context window table ─────────────────────────────────────────────────────
113131 // Maps model ID substrings (matched in order) to token limits.
114132 // Covers all Zen models plus common direct-provider model families.
@@ -139,9 +157,7 @@ const CONTEXT_WINDOW_TABLE: Array<[pattern: RegExp, tokens: number]> = [
139157 * Returns null when the model is unknown.
140158 */
141159 export function getContextWindow(modelString: string): number | null {
142- const modelId = modelString.includes("/")
143- ? modelString.slice(modelString.indexOf("/") + 1)
144- : modelString;
160+ const { modelId } = parseModelString(modelString);
145161 for (const [pattern, tokens] of CONTEXT_WINDOW_TABLE) {
146162 if (pattern.test(modelId)) return tokens;
147163 }
@@ -182,7 +198,9 @@ export function resolveModel(modelString: string): LanguageModel {
182198 return directAnthropic()(modelId);
183199
184200 case "openai":
185- return directOpenAI()(modelId);
201+ return modelId.startsWith("gpt-")
202+ ? directOpenAI().responses(modelId)
203+ : directOpenAI()(modelId);
186204
187205 case "google":
188206 return directGoogle()(modelId);
src/llm-api/turn.ts+4−14
@@ -1,6 +1,7 @@
11 import { dynamicTool, jsonSchema, stepCountIs, streamText } from "ai";
22 import type { FlexibleSchema, StepResult } from "ai";
33 import { z } from "zod";
4+import { parseModelString } from "./providers.ts";
45 import type { ToolDef, TurnEvent } from "./types.ts";
56
67 type StreamTextOptions = Parameters<typeof streamText>[0];
@@ -68,10 +69,7 @@ function toCoreTool(
6869 * authoritative system prompt (rather than a system-role message in `input`).
6970 */
7071 export function isOpenAIGPT(modelString: string): boolean {
71- const slashIdx = modelString.indexOf("/");
72- const provider =
73- slashIdx === -1 ? modelString : modelString.slice(0, slashIdx);
74- const modelId = slashIdx === -1 ? "" : modelString.slice(slashIdx + 1);
72+ const { provider, modelId } = parseModelString(modelString);
7573 return (
7674 (provider === "openai" || provider === "zen") && modelId.startsWith("gpt-")
7775 );
@@ -130,15 +128,7 @@ export async function* runTurn(options: {
130128 // as a system-role message in `input` works but is treated as a lower-priority
131129 // user turn, causing the model to deprioritise the instructions.
132130 const useInstructions =
133- systemPrompt !== undefined &&
134- modelString !== undefined &&
135- isOpenAIGPT(modelString);
136-
137- // GPT models tend to describe planned tool calls without making them, then
138- // yield back to the user. This applies broadly across the gpt-* family.
139- // The one-liner closes that gap without adding opinion about how to do the task.
140- const GPT_CONTINUATION =
141- "\n\nAlways make tool calls rather than describing them. Keep going until the task is complete, then stop.";
131+ systemPrompt !== undefined && isOpenAIGPT(modelString);
142132
143133 const streamOpts: StreamTextOptions = {
144134 model,
@@ -166,7 +156,7 @@ export async function* runTurn(options: {
166156 ? {
167157 providerOptions: {
168158 openai: {
169- instructions: systemPrompt + GPT_CONTINUATION,
159+ instructions: systemPrompt,
170160 store: false,
171161 },
172162 },