Skip to content

Commit ffc24bc

Browse files
kimrinking-celllidge-jun
authored andcommitted
preserve foreground Luna turns
1 parent 538d755 commit ffc24bc

6 files changed

Lines changed: 101 additions & 11 deletions

File tree

‎docs-site/src/content/docs/reference/configuration/server.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,9 @@ subscription with a warning when detection is inconclusive. See
120120
Codex uses small helper models for tasks such as titles and commit messages. Enable
121121
`shadowCallIntercept` to redirect recognized source-model prefixes to another configured model. The
122122
replacement runs at low effort. Set `sourceModels` only when a client uses different helper ids.
123+
Codex 0.145.0+ marks request purpose in `x-codex-turn-metadata`: normal `request_kind: "turn"`
124+
requests keep the selected model, while recognized maintenance requests can be redirected. Clients
125+
without that metadata retain the legacy prefix behavior.
123126

124127
```json
125128
{

‎docs/shadow-call-intercept.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -63,14 +63,18 @@ the defaults rather than extending them:
6363

6464
### Behavior
6565

66-
- When enabled, ALL requests whose bare model id starts with one of the source-model prefixes
67-
(default `gpt-5.4-mini`, `gpt-5.6-luna`) are rewritten to the configured model
66+
- Matching maintenance requests, including `prewarm`, `compaction`, and `memory`, are
67+
rewritten to the configured model
68+
- Normal user turns identified by `x-codex-turn-metadata` with `request_kind: "turn"` are
69+
never rewritten
70+
- Headerless legacy clients retain the original prefix behavior: matching bare model ids are
71+
rewritten
72+
- Missing, malformed, or unrecognized turn metadata retains the legacy prefix behavior
6873
- Reasoning effort is forced to `low` (matching the original behavior)
6974
- The original model ID is logged as `shadowCallRewrittenFrom` in request logs
7075
- When disabled (default), no interception occurs
7176

7277
### Warning
7378

74-
Enabling this redirects every request for a source model, not just Codex's background helper turns.
75-
`gpt-5.6-luna` is also a selectable chat model, so if you pick it as your main model while the
76-
intercept is on, those turns are redirected too — narrow `sourceModels` if that matters to you.
79+
Headerless clients cannot distinguish foreground turns from background helper calls. If such a
80+
client uses `gpt-5.6-luna` as its main model, narrow `sourceModels` or disable the intercept.

‎src/lib/shadow-call.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,27 @@ export function isShadowSourceModel(modelId: string, configured?: unknown): bool
2828
if (modelId.includes("/")) return false;
2929
return shadowSourceModels(configured).some(prefix => modelId.startsWith(prefix));
3030
}
31+
32+
/**
33+
* Decide whether a matching source model should use the opt-in intercept.
34+
*
35+
* Codex 0.145.0+ identifies normal user turns and maintenance requests in
36+
* x-codex-turn-metadata. Only an explicit normal turn bypasses interception;
37+
* missing or unrecognized metadata retains the legacy opt-in prefix behavior.
38+
*/
39+
export function shouldInterceptShadowCall(
40+
modelId: string,
41+
configured: unknown,
42+
headers: Headers,
43+
): boolean {
44+
if (!isShadowSourceModel(modelId, configured)) return false;
45+
const rawMetadata = headers.get("x-codex-turn-metadata");
46+
if (rawMetadata === null) return true;
47+
48+
try {
49+
const parsed = JSON.parse(rawMetadata) as { request_kind?: unknown };
50+
return parsed?.request_kind !== "turn";
51+
} catch {
52+
return true;
53+
}
54+
}

‎src/server/responses/core.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ export function sidecarOutcomeRecorder(
186186

187187

188188

189-
import { isShadowSourceModel } from "../../lib/shadow-call";
189+
import { isShadowSourceModel, shouldInterceptShadowCall } from "../../lib/shadow-call";
190190

191191
export { DEFAULT_SHADOW_SOURCE_MODELS, isShadowSourceModel, shadowSourceModels } from "../../lib/shadow-call";
192192

@@ -1271,7 +1271,11 @@ async function handleResponsesInner(
12711271
// Shadow call intercept: rewrite Codex's hard-coded helper calls
12721272
// (gpt-5.4-mini on older clients, gpt-5.6-luna on 0.145.0+)
12731273
const _sci = config.shadowCallIntercept;
1274-
if (_sci?.enabled && _sci.model && isShadowSourceModel(parsed.modelId, _sci.sourceModels)) {
1274+
if (_sci?.enabled && _sci.model && shouldInterceptShadowCall(
1275+
parsed.modelId,
1276+
_sci.sourceModels,
1277+
req.headers,
1278+
)) {
12751279
const _sciOriginal = parsed.modelId;
12761280
parsed.modelId = _sci.model;
12771281
if (parsed._rawBody && typeof parsed._rawBody === "object") {

‎src/types.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -645,7 +645,8 @@ export interface OcxConfig {
645645
* Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
646646
* commit messages, skill orchestration) to a user-chosen model. Default intercepted
647647
* source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
648-
* Opt-in; disabled by default. When enabled, effort is forced to low.
648+
* Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
649+
* Normal Codex turns identified by request_kind=turn are never rewritten.
649650
*/
650651
shadowCallIntercept?: {
651652
/** When true, requests for known shadow/helper source models are rewritten to the configured model. */

‎tests/responses-shadow-intercept.test.ts‎

Lines changed: 57 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import { mkdtempSync, rmSync } from "node:fs";
88
import { tmpdir } from "node:os";
99
import { join } from "node:path";
1010
import { handleResponses, isShadowSourceModel } from "../src/server/responses";
11+
import { shouldInterceptShadowCall } from "../src/lib/shadow-call";
1112
import { handleManagementAPI } from "../src/server/management-api";
1213
import type { OcxConfig } from "../src/types";
1314

@@ -51,6 +52,42 @@ describe("isShadowSourceModel", () => {
5152
});
5253
});
5354

55+
describe("shouldInterceptShadowCall", () => {
56+
const metadata = (requestKind: string) => new Headers({
57+
"x-codex-turn-metadata": JSON.stringify({ request_kind: requestKind }),
58+
});
59+
60+
test("intercepts recognized maintenance kinds but not normal turns", () => {
61+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, metadata("memory"))).toBe(true);
62+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, metadata("compaction"))).toBe(true);
63+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, metadata("prewarm"))).toBe(true);
64+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, metadata("turn"))).toBe(false);
65+
});
66+
67+
test("keeps legacy matching for headerless, malformed, and unrecognized metadata", () => {
68+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, new Headers())).toBe(true);
69+
expect(shouldInterceptShadowCall(
70+
"gpt-5.6-luna",
71+
undefined,
72+
new Headers({ "x-codex-turn-metadata": "{" }),
73+
)).toBe(true);
74+
expect(shouldInterceptShadowCall(
75+
"gpt-5.6-luna",
76+
undefined,
77+
new Headers({ "x-codex-turn-metadata": "{}" }),
78+
)).toBe(true);
79+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, metadata("future-kind"))).toBe(true);
80+
});
81+
82+
test("uses case-insensitive Headers lookup and still excludes non-source models", () => {
83+
const headers = new Headers({
84+
"X-CoDeX-TuRn-MeTaDaTa": JSON.stringify({ request_kind: "turn" }),
85+
});
86+
expect(shouldInterceptShadowCall("gpt-5.6-luna", undefined, headers)).toBe(false);
87+
expect(shouldInterceptShadowCall("gpt-5.6-terra", undefined, metadata("memory"))).toBe(false);
88+
});
89+
});
90+
5491
function interceptConfig(): OcxConfig {
5592
return {
5693
port: 0,
@@ -67,10 +104,14 @@ function interceptConfig(): OcxConfig {
67104
} as OcxConfig;
68105
}
69106

70-
async function post(config: OcxConfig, model: string): Promise<Response> {
107+
async function post(config: OcxConfig, model: string, requestKind?: string): Promise<Response> {
108+
const headers: Record<string, string> = { "content-type": "application/json" };
109+
if (requestKind) {
110+
headers["x-codex-turn-metadata"] = JSON.stringify({ request_kind: requestKind });
111+
}
71112
return handleResponses(new Request("http://localhost/v1/responses", {
72113
method: "POST",
73-
headers: { "content-type": "application/json" },
114+
headers,
74115
body: JSON.stringify({
75116
model,
76117
input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
@@ -91,7 +132,7 @@ describe("shadow call intercept request path (issue #311)", () => {
91132
}), { status: 200, headers: { "content-type": "application/json" } });
92133
}) as typeof fetch;
93134

94-
await post(interceptConfig(), "gpt-5.6-luna");
135+
await post(interceptConfig(), "gpt-5.6-luna", "memory");
95136

96137
expect(bodies.length).toBe(1);
97138
// Routed through xai openai-chat: upstream model is the decoded routed id, not the helper id
@@ -101,6 +142,19 @@ describe("shadow call intercept request path (issue #311)", () => {
101142
expect(effort).toBe("low");
102143
});
103144

145+
test("does not rewrite a foreground gpt-5.6-luna turn", async () => {
146+
let sawFetch = false;
147+
globalThis.fetch = (async () => {
148+
sawFetch = true;
149+
return new Response(JSON.stringify({ error: { message: "unreachable" } }), { status: 500 });
150+
}) as typeof fetch;
151+
152+
const response = await post(interceptConfig(), "gpt-5.6-luna", "turn");
153+
154+
expect(sawFetch).toBe(false);
155+
expect(response.status).toBe(404);
156+
});
157+
104158
test("leaves gpt-5.6-terra requests unrewritten", async () => {
105159
let sawFetch = false;
106160
globalThis.fetch = (async () => {

0 commit comments

Comments
 (0)