Skip to content

Commit 355ca7d

Browse files
t3dotggclaude
andcommitted
fix(server): Codex turns reach newer models with T3 Code's instructions again
Newer Codex model catalogs ship their own collaboration mode text, and Codex uses it instead of the client's developer_instructions. That dropped T3 Code's runtime info, PR linking, and browser/device tool guidance. Send that context through turn/start additionalContext instead, and keep only the mode prompt in the collaboration mode. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 568c9bc commit 355ca7d

3 files changed

Lines changed: 135 additions & 130 deletions

File tree

‎apps/server/src/provider/CodexDeveloperInstructions.ts‎

Lines changed: 42 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,18 @@
11
import type { ProviderInteractionMode } from "@t3tools/contracts";
2+
import type { V2TurnStartParams__AdditionalContextEntry } from "effect-codex-app-server/schema";
23
import { buildRuntimeInstructions } from "./RuntimeInstructions.ts";
34

4-
const T3_CODE_BROWSER_TOOL_INSTRUCTIONS = `
5-
6-
## T3 Code collaborative browser
5+
const T3_CODE_BROWSER_TOOL_INSTRUCTIONS = `## T3 Code collaborative browser
76
87
You are running inside T3 Code. The \`t3-code\` MCP server is the product-native collaborative browser shared with the user. When it exposes \`preview_*\` tools, prefer those tools for browser navigation, inspection, interaction, screenshots, and recordings.
98
109
For browser work, first call \`preview_status\`. If no automation-capable preview is attached, call \`preview_open\` before concluding that the browser is unavailable. Then use \`preview_navigate\`, \`preview_snapshot\`, and the focused interaction tools. Prefer snapshot-provided locators over coordinates.
1110
12-
Do not switch to global browser skills, Chrome, Node REPL browser automation, standalone Playwright, or agent-browser merely because the preview is initially closed or a first call fails. Use an alternative browser system only when the T3 preview tools are absent, the user explicitly requests another browser, or \`preview_open\` returns an explicit unsupported/unavailable error. A failed T3 preview tool call should be inspected and retried with corrected arguments when the error is actionable.
13-
`;
14-
15-
const T3_CODE_DEVICE_TOOL_INSTRUCTIONS = `
11+
Do not switch to global browser skills, Chrome, Node REPL browser automation, standalone Playwright, or agent-browser merely because the preview is initially closed or a first call fails. Use an alternative browser system only when the T3 preview tools are absent, the user explicitly requests another browser, or \`preview_open\` returns an explicit unsupported/unavailable error. A failed T3 preview tool call should be inspected and retried with corrected arguments when the error is actionable.`;
1612

17-
## T3 Code devices
13+
const T3_CODE_DEVICE_TOOL_INSTRUCTIONS = `## T3 Code devices
1814
19-
The \`t3-code\` MCP server also exposes \`device_*\` tools for iOS Simulators and Android Emulators on this environment. For mobile verification, call \`device_list\`, then \`device_open\` so the user can watch the device in their Device panel; its result explains how to drive the device. Driving happens through the \`agent-device\` CLI, which is on PATH. Keep the host config and session flags returned by \`device_open\` on every command so concurrent devices stay independent: prefer \`agent-device snapshot -i\` refs over coordinates, and use \`device_screenshot\` when you need to see the screen. Do not call simctl, adb, xcrun, or serve-sim directly while these tools are present. If \`device_list\` reports a platform as unavailable, say so instead of trying another route.
20-
`;
15+
The \`t3-code\` MCP server also exposes \`device_*\` tools for iOS Simulators and Android Emulators on this environment. For mobile verification, call \`device_list\`, then \`device_open\` so the user can watch the device in their Device panel; its result explains how to drive the device. Driving happens through the \`agent-device\` CLI, which is on PATH. Keep the host config and session flags returned by \`device_open\` on every command so concurrent devices stay independent: prefer \`agent-device snapshot -i\` refs over coordinates, and use \`device_screenshot\` when you need to see the screen. Do not call simctl, adb, xcrun, or serve-sim directly while these tools are present. If \`device_list\` reports a platform as unavailable, say so instead of trying another route.`;
2116

2217
export interface T3CodeToolAvailability {
2318
readonly browser: boolean;
@@ -36,16 +31,17 @@ const normalizeAvailability = (
3631
* from Playwright, agent-browser, and raw simctl/adb, so leaving them in would
3732
* talk it out of the only automation it still has.
3833
*/
39-
const browserToolInstructions = (availability: boolean | T3CodeToolAvailability): string => {
34+
const toolInstructions = (availability: boolean | T3CodeToolAvailability): string => {
4035
const tools = normalizeAvailability(availability);
41-
return `${tools.browser ? T3_CODE_BROWSER_TOOL_INSTRUCTIONS : ""}${
42-
tools.device ? T3_CODE_DEVICE_TOOL_INSTRUCTIONS : ""
43-
}`;
36+
return [
37+
tools.browser ? T3_CODE_BROWSER_TOOL_INSTRUCTIONS : "",
38+
tools.device ? T3_CODE_DEVICE_TOOL_INSTRUCTIONS : "",
39+
]
40+
.filter(Boolean)
41+
.join("\n\n");
4442
};
4543

46-
const codexPlanModeDeveloperInstructions = (
47-
browserToolsAvailable: boolean | T3CodeToolAvailability,
48-
): string => `<collaboration_mode># Plan Mode (Conversational)
44+
const CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Plan Mode (Conversational)
4945
5046
You work in 3 phases, and you should *chat your way* to a great plan before finalizing it. A great plan is very detailed-intent- and implementation-wise-so that it can be handed to another engineer or agent to be implemented right away. It must be **decision complete**, where the implementer does not need to make any decisions.
5147
@@ -173,12 +169,9 @@ Do not ask "should I proceed?" in the final output. The user can easily switch o
173169
Only produce at most one \`<proposed_plan>\` block per turn, and only when you are presenting a complete spec.
174170
175171
If the user stays in Plan mode and asks for revisions after a prior \`<proposed_plan>\`, any new \`<proposed_plan>\` must be a complete replacement. If the user indicates that the prior plan is not acceptable but does not provide enough information to produce a complete replacement, address the concern and continue planning without producing a \`<proposed_plan>\` block. If the follow-up neither requires changes nor calls the plan into question (e.g. clarifying question), answer it before the block, then reproduce the prior \`<proposed_plan>\` unchanged.
176-
${browserToolInstructions(browserToolsAvailable)}
177172
</collaboration_mode>`;
178173

179-
const codexDefaultModeDeveloperInstructions = (
180-
browserToolsAvailable: boolean | T3CodeToolAvailability,
181-
): string => `<collaboration_mode># Collaboration Mode: Default
174+
const CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Collaboration Mode: Default
182175
183176
You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
184177
@@ -189,29 +182,45 @@ Your active mode changes only when new developer instructions with a different \
189182
Use the \`request_user_input\` tool only when it is listed in the available tools for this turn.
190183
191184
In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
192-
${browserToolInstructions(browserToolsAvailable)}
193185
</collaboration_mode>`;
194186

195187
export interface CodexRuntimeInfo {
196188
readonly model: string;
197189
readonly reasoningEffort: string;
198190
}
199191

200-
export function buildCodexDeveloperInstructions(
201-
interactionMode: ProviderInteractionMode,
192+
/** Mode prompt for `turn/start.collaborationMode.settings.developer_instructions`. */
193+
export function buildCodexDeveloperInstructions(interactionMode: ProviderInteractionMode): string {
194+
return interactionMode === "plan"
195+
? CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS
196+
: CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS;
197+
}
198+
199+
/**
200+
* T3 Code context for `turn/start.additionalContext`. Codex renders each entry
201+
* as a `<key>value</key>` developer message and resends it only when the value
202+
* changes.
203+
*
204+
* This must stay out of the collaboration mode: when the model catalog ships
205+
* its own text for a mode, as newer models do, Codex uses that text and drops
206+
* the client's `developer_instructions` entirely.
207+
*/
208+
export function buildCodexAdditionalContext(
202209
runtime: CodexRuntimeInfo,
203210
/**
204211
* Whether the `t3-code` MCP server is attached to this turn. Callers derive
205212
* it from the session's actual MCP configuration rather than re-reading the
206213
* setting, so the prompt cannot claim tools the turn doesn't have.
207214
*/
208-
browserToolsAvailable: boolean | T3CodeToolAvailability = true,
209-
): string {
210-
const base =
211-
interactionMode === "plan"
212-
? codexPlanModeDeveloperInstructions(browserToolsAvailable)
213-
: codexDefaultModeDeveloperInstructions(browserToolsAvailable);
214-
return `${base}
215-
216-
${buildRuntimeInstructions({ harness: "Codex", ...runtime })}`;
215+
toolsAvailable: boolean | T3CodeToolAvailability = true,
216+
): Record<string, V2TurnStartParams__AdditionalContextEntry> {
217+
const tools = toolInstructions(toolsAvailable);
218+
// Separate keys keep each value under Codex's per-entry token cap.
219+
return {
220+
t3_code_runtime: {
221+
kind: "application",
222+
value: buildRuntimeInstructions({ harness: "Codex", ...runtime }),
223+
},
224+
...(tools ? { t3_code_tools: { kind: "application", value: tools } } : {}),
225+
};
217226
}

‎apps/server/src/provider/Layers/CodexSessionRuntime.test.ts‎

Lines changed: 72 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@ import * as CodexErrors from "effect-codex-app-server/errors";
99
import * as CodexRpc from "effect-codex-app-server/rpc";
1010
import * as EffectCodexSchema from "effect-codex-app-server/schema";
1111

12-
import { buildCodexDeveloperInstructions } from "../CodexDeveloperInstructions.ts";
12+
import {
13+
buildCodexAdditionalContext,
14+
buildCodexDeveloperInstructions,
15+
} from "../CodexDeveloperInstructions.ts";
1316
import { codexSessionAppServerArgs } from "./codexLaunchArgs.ts";
1417
import {
1518
buildTurnStartParams,
@@ -232,12 +235,13 @@ describe("buildTurnStartParams", () => {
232235
settings: {
233236
model: "gpt-5.3-codex",
234237
reasoning_effort: "medium",
235-
developer_instructions: buildCodexDeveloperInstructions("plan", {
236-
model: "gpt-5.3-codex",
237-
reasoningEffort: "medium",
238-
}),
238+
developer_instructions: buildCodexDeveloperInstructions("plan"),
239239
},
240240
},
241+
additionalContext: buildCodexAdditionalContext({
242+
model: "gpt-5.3-codex",
243+
reasoningEffort: "medium",
244+
}),
241245
});
242246
});
243247

@@ -281,12 +285,13 @@ describe("buildTurnStartParams", () => {
281285
settings: {
282286
model: "gpt-5.3-codex",
283287
reasoning_effort: "medium",
284-
developer_instructions: buildCodexDeveloperInstructions("default", {
285-
model: "gpt-5.3-codex",
286-
reasoningEffort: "medium",
287-
}),
288+
developer_instructions: buildCodexDeveloperInstructions("default"),
288289
},
289290
},
291+
additionalContext: buildCodexAdditionalContext({
292+
model: "gpt-5.3-codex",
293+
reasoningEffort: "medium",
294+
}),
290295
});
291296
});
292297

@@ -303,7 +308,9 @@ describe("buildTurnStartParams", () => {
303308
const settings = params.collaborationMode?.settings;
304309
NodeAssert.equal(settings?.model, DEFAULT_MODEL);
305310
NodeAssert.equal(settings?.reasoning_effort, "medium");
306-
NodeAssert.ok(settings?.developer_instructions?.includes(`as ${DEFAULT_MODEL} with medium`));
311+
NodeAssert.ok(
312+
params.additionalContext?.t3_code_runtime?.value.includes(`as ${DEFAULT_MODEL} with medium`),
313+
);
307314
});
308315

309316
it.effect("routes approvals to the auto reviewer in auto mode", () =>
@@ -560,99 +567,82 @@ describe("Codex MCP elicitation approvals", () => {
560567
});
561568

562569
describe("buildCodexDeveloperInstructions", () => {
563-
it("appends runtime info after the mode instructions", () => {
564-
const instructions = buildCodexDeveloperInstructions("default", {
565-
model: "gpt-5.3-codex",
566-
reasoningEffort: "high",
567-
});
568-
569-
NodeAssert.match(instructions, /^<collaboration_mode># Collaboration Mode: Default/);
570-
NodeAssert.match(instructions, /T3 Code/);
571-
NodeAssert.match(instructions, /Codex harness/);
572-
NodeAssert.match(instructions, /as gpt-5\.3-codex with high reasoning effort/);
573-
});
574-
575-
it("describes Markdown media support in the runtime context in both modes", () => {
570+
it("keeps T3 context out of the mode prompt, which the model catalog can replace", () => {
576571
for (const mode of ["default", "plan"] as const) {
577-
const instructions = buildCodexDeveloperInstructions(mode, {
578-
model: "gpt-5.3-codex",
579-
reasoningEffort: "high",
580-
});
581-
NodeAssert.match(
582-
instructions,
583-
/<runtime_info>.*embed images and videos.*Markdown.*<\/runtime_info>/,
584-
);
572+
const instructions = buildCodexDeveloperInstructions(mode);
573+
NodeAssert.match(instructions, /^<collaboration_mode>[\s\S]*<\/collaboration_mode>$/);
574+
NodeAssert.doesNotMatch(instructions, /runtime_info|pull_request_linking|preview_|device_/);
585575
}
586576
});
577+
});
587578

588-
it("includes runtime info alongside plan mode instructions", () => {
589-
const instructions = buildCodexDeveloperInstructions("plan", {
590-
model: "gpt-5.3-codex",
591-
reasoningEffort: "medium",
592-
});
579+
describe("buildCodexAdditionalContext", () => {
580+
const runtime = { model: "gpt-5.3-codex", reasoningEffort: "high" };
581+
const runtimeValue = (context: ReturnType<typeof buildCodexAdditionalContext>) =>
582+
context.t3_code_runtime?.value ?? "";
583+
584+
it("describes the harness, model, effort, and Markdown media support", () => {
585+
const context = buildCodexAdditionalContext(runtime);
593586

594-
NodeAssert.match(instructions, /^<collaboration_mode># Plan Mode/);
595-
NodeAssert.match(instructions, /as gpt-5\.3-codex with medium reasoning effort/);
587+
NodeAssert.equal(context.t3_code_runtime?.kind, "application");
588+
NodeAssert.match(
589+
runtimeValue(context),
590+
/<runtime_info>.*Codex harness, as gpt-5\.3-codex with high reasoning effort.*embed images and videos.*Markdown.*<\/runtime_info>/,
591+
);
596592
});
597593

598594
it("varies with the model and effort of each turn", () => {
599-
const first = buildCodexDeveloperInstructions("default", {
600-
model: "gpt-5.3-codex",
601-
reasoningEffort: "medium",
602-
});
603-
const second = buildCodexDeveloperInstructions("default", {
604-
model: "gpt-5.4",
605-
reasoningEffort: "high",
606-
});
607-
608-
NodeAssert.notEqual(first, second);
595+
NodeAssert.notEqual(
596+
runtimeValue(
597+
buildCodexAdditionalContext({ model: "gpt-5.3-codex", reasoningEffort: "medium" }),
598+
),
599+
runtimeValue(buildCodexAdditionalContext({ model: "gpt-5.4", reasoningEffort: "high" })),
600+
);
609601
});
610602

611603
it("flattens multiline metadata into single-line runtime info", () => {
612-
const instructions = buildCodexDeveloperInstructions("default", {
613-
model: "gpt\n5.3\ncodex",
614-
reasoningEffort: " high\neffort ",
615-
});
604+
const value = runtimeValue(
605+
buildCodexAdditionalContext({ model: "gpt\n5.3\ncodex", reasoningEffort: " high\neffort " }),
606+
);
616607

617-
NodeAssert.match(instructions, /as gpt 5\.3 codex with high effort reasoning effort/);
618-
NodeAssert.doesNotMatch(instructions, /<runtime_info>[^<]*\n/);
608+
NodeAssert.match(value, /as gpt 5\.3 codex with high effort reasoning effort/);
609+
NodeAssert.doesNotMatch(value, /<runtime_info>[^<]*\n/);
610+
});
611+
612+
it("keeps every entry under Codex's 1,000 token cap per entry", () => {
613+
const context = buildCodexAdditionalContext(runtime, { browser: true, device: true });
614+
for (const entry of Object.values(context)) {
615+
// Codex estimates 4 bytes per token and truncates the middle of longer values.
616+
NodeAssert.ok(Buffer.byteLength(entry.value) < 4_000);
617+
}
619618
});
620619
});
621620

622-
describe("T3 browser developer instructions", () => {
621+
describe("T3 tool instructions", () => {
623622
const runtime = { model: "gpt-5.3-codex", reasoningEffort: "high" };
624623

625-
it("prefers the product-native preview tools in both collaboration modes", () => {
626-
for (const mode of ["default", "plan"] as const) {
627-
const instructions = buildCodexDeveloperInstructions(mode, runtime, true);
628-
NodeAssert.match(instructions, /t3-code/);
629-
NodeAssert.match(instructions, /preview_status/);
630-
NodeAssert.match(instructions, /preview_open/);
631-
NodeAssert.match(instructions, /Do not switch to global browser skills/);
632-
}
624+
it("prefers the product-native preview tools when they are attached", () => {
625+
const tools = buildCodexAdditionalContext(runtime, true).t3_code_tools?.value ?? "";
626+
NodeAssert.match(tools, /t3-code/);
627+
NodeAssert.match(tools, /preview_status/);
628+
NodeAssert.match(tools, /preview_open/);
629+
NodeAssert.match(tools, /Do not switch to global browser skills/);
630+
NodeAssert.doesNotMatch(tools, /device_open/);
633631
});
634632

635-
it("omits the browser block entirely when the preview tools are not attached", () => {
636-
for (const mode of ["default", "plan"] as const) {
637-
const instructions = buildCodexDeveloperInstructions(mode, runtime, false);
638-
NodeAssert.doesNotMatch(instructions, /preview_status/);
639-
NodeAssert.doesNotMatch(instructions, /preview_open/);
640-
NodeAssert.doesNotMatch(instructions, /T3 Code collaborative browser/);
641-
// Steering away from other browser automation must go with the tools;
642-
// keeping it would leave the model talked out of its only option.
643-
NodeAssert.doesNotMatch(instructions, /Do not switch to global browser skills/);
644-
// The rest of the collaboration mode is untouched.
645-
NodeAssert.match(instructions, /<collaboration_mode>/);
646-
NodeAssert.match(instructions, /<\/collaboration_mode>/);
647-
}
633+
it("describes device tools only when the credential grants them", () => {
634+
const tools =
635+
buildCodexAdditionalContext(runtime, { browser: false, device: true }).t3_code_tools?.value ??
636+
"";
637+
NodeAssert.match(tools, /device_open/);
638+
NodeAssert.doesNotMatch(tools, /preview_open/);
648639
});
649640

650-
it("tracks the turn's MCP configuration rather than defaulting to on", () => {
651-
NodeAssert.match(buildCodexDeveloperInstructions("default", runtime, true), /preview_open/);
652-
NodeAssert.doesNotMatch(
653-
buildCodexDeveloperInstructions("default", runtime, false),
654-
/preview_open/,
655-
);
641+
it("omits the tool entry entirely when no tools are attached", () => {
642+
// Steering away from other browser automation must go with the tools;
643+
// keeping it would leave the model talked out of its only option.
644+
const context = buildCodexAdditionalContext(runtime, false);
645+
NodeAssert.deepStrictEqual(Object.keys(context), ["t3_code_runtime"]);
656646
});
657647
});
658648

0 commit comments

Comments
 (0)