Skip to content

Commit 89ae31b

Browse files
fix(server): promote scoped caller conversation headers
Refines #6521 with trusted-principal scoping and admission-time propagation. Co-authored-by: mayigululu-hash <[email protected]>
1 parent 61e2237 commit 89ae31b

13 files changed

Lines changed: 410 additions & 8 deletions

File tree

‎devlog/_plan/261004_cache_identity/010_caller.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,5 @@ Field chain: x-session-id creation is external caller; ingress validates and ser
2121
Verifier: `bun test tests/server/caller-session-identity.test.ts tests/providers/xai/grok-session-identity.test.ts tests/server/loopback-listener-admission.test.ts` plus typecheck, structure/privacy and both layout guards/file-size ratchet. These direct test paths observe this delta; source-only pins do not prove live behavior. Docs build observes the public page. No full/changed suite per resource contract. Independent security review required. Existing explicit/Grok caller-supplied identities retain existing semantics; this change makes no global authorization-isolation claim.
2222

2323
Reflection refinement: use real combo recall read/write APIs for equal caller markers under different principals; same principal retains continuity. Test through actual admitted ingress in addition to helper tests.
24+
25+
Implementation record: helper and both routes implemented; ingress regression moved into registered sibling `tests/server/caller-session-ingress.test.ts` to keep unit and endpoint concerns readable. The accidental compact-route edit found by main was removed before verification. Four behavior files passed 59 tests; layout/tooling/ratchet files passed 27 tests. Typecheck and docs build passed. Structure contracts consolidated into inbound-compat with links from capped runtime/Responses docs; their 600-line budgets are preserved. Publication waits for independent code review and current-head CI inspection.

‎docs-site/src/content/docs/reference/proxy-formats.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,24 @@ for final text and `session.updated` with `session.status="closed"`.
170170
This is the native opencodex data-plane shape. The request body must be a JSON object with a
171171
non-empty `model`. `input` may be a string or an array of Responses items.
172172

173+
### Caller conversation header
174+
175+
For HTTP `POST /v1/responses` and `POST /v1/messages`, a client can send a stable
176+
`x-session-id` for each conversation. When no `session_id`, `session-id`, or `thread-id`
177+
header is present, opencodex promotes the marker to `session_id`. Managed Grok identity
178+
on Responses takes precedence too. Even an empty explicit header suppresses promotion.
179+
180+
Use 1–128 ASCII letters, digits, `.`, `_`, `:`, or `-`, starting with a letter or digit.
181+
Surrounding whitespace is trimmed; missing or invalid markers are ignored. Loopback
182+
admission preserves the marker. Authenticated admission derives an opaque identifier
183+
from the marker and the admitted credential principal, so different credentials do not
184+
share a newly promoted identifier. Rotation changes this identifier; authenticated
185+
requests without a trusted principal are left unchanged.
186+
187+
Use distinct markers for distinct conversations. This preserves conversation continuity
188+
for downstream consumers, but does not guarantee an upstream cache hit or measured savings.
189+
Chat Completions, WebSocket frames, compact, and count_tokens do not use this promotion.
190+
173191
### Accepted request fields
174192

175193
| Area | Accepted shape |

‎scripts/test-layout/layout.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
"provider-antigravity-family-catalog.test.ts": "providers",
1010
"claude-subagent-model-force.test.ts": "claude-integration",
1111
"subagent-model-force-api.test.ts": "server",
12+
"caller-session-identity.test.ts": "server",
13+
"caller-session-ingress.test.ts": "server",
1214
"agent-subagent-force.test.ts": "cli",
1315
"compaction-event-ownership.test.ts": "responses",
1416
"zed-retained-budget.test.ts": "providers",
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/** Promote third-party conversation markers after ingress authentication and origin checks. */
2+
import { contextPrincipalIdOf, type DataPlaneAdmission } from "./auth-cors";
3+
4+
const SESSION_HEADERS = ["session_id", "session-id", "thread-id"] as const;
5+
const SAFE_CALLER_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
6+
7+
export function callerSessionId(headers: Headers): string | undefined {
8+
if (SESSION_HEADERS.some(name => headers.has(name))) return undefined;
9+
const value = headers.get("x-session-id")?.trim();
10+
if (!value || !SAFE_CALLER_SESSION_ID.test(value)) return undefined;
11+
return value;
12+
}
13+
14+
/** Authenticated callers share continuity only within their trusted credential principal. */
15+
export function withCallerSessionIdentity(req: Request, admission: DataPlaneAdmission): Request {
16+
const conversation = callerSessionId(req.headers);
17+
if (!conversation) return req;
18+
let sessionId = conversation;
19+
if (admission.kind !== "loopback") {
20+
const principal = contextPrincipalIdOf(admission);
21+
if (!principal) return req;
22+
sessionId = new Bun.CryptoHasher("sha256")
23+
.update(JSON.stringify(["opencodex-caller-session-v1", principal, conversation])).digest("hex");
24+
}
25+
const headers = new Headers(req.headers);
26+
headers.set("session_id", sessionId);
27+
// Preserve the unread body stream and propagate the original request's abort signal.
28+
return new Request(req, { headers });
29+
}

‎src/server/index/serve-options.ts‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -203,6 +203,7 @@ import { readyProtocolMetadata } from "../../remote/protocol";
203203
import { modelCapabilityFields } from "../models-capabilities";
204204
import { createWebsocketHandler } from "./websocket-handler";
205205
import { withGrokSessionIdentity } from "../../grok/session-identity";
206+
import { withCallerSessionIdentity } from "../caller-session-identity";
206207

207208
export type ServerIngress = "public" | "unauthenticated-loopback" | "hub-management" | "claude-intercept" | "hub-link";
208209

@@ -1474,10 +1475,11 @@ export function createServeOptions(ctx: ServeOptionsContext) {
14741475
logged = true;
14751476
addFinalRequestLog(requestId, start, logCtx, status, meta);
14761477
};
1477-
return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => {
1478+
const sessionReq = withCallerSessionIdentity(withGrokSessionIdentity(req), admission);
1479+
return runAdmittedHttpTurn(sessionReq, policy, async turnAdmissionLease => {
14781480
let response: Response;
14791481
try {
1480-
response = await handleResponses(withGrokSessionIdentity(req), config, logCtx, {
1482+
response = await handleResponses(sessionReq, config, logCtx, {
14811483
turnAdmissionLease,
14821484
admission,
14831485
onRequestBodyRead: () => disableResponsesRequestTimeout(req, requestServer),
@@ -1554,8 +1556,9 @@ export function createServeOptions(ctx: ServeOptionsContext) {
15541556
// Logging is finalized inside handleClaudeMessages (Responses-vocab tap on the
15551557
// pre-translation stream + native passthrough callbacks) — do not re-wrap the
15561558
// translated Anthropic stream here.
1557-
return runAdmittedHttpTurn(req, policy, async turnAdmissionLease => withCors(
1558-
await handleClaudeMessages(req, config, logCtx, { requestId, start, turnAdmissionLease, admission }, policy, { claudeIntercept: ingress === "claude-intercept" }),
1559+
const sessionReq = withCallerSessionIdentity(req, admission);
1560+
return runAdmittedHttpTurn(sessionReq, policy, async turnAdmissionLease => withCors(
1561+
await handleClaudeMessages(sessionReq, config, logCtx, { requestId, start, turnAdmissionLease, admission }, policy, { claudeIntercept: ingress === "claude-intercept" }),
15591562
req,
15601563
policy,
15611564
), { requestId, start, logCtx });

‎structure/data-planes/inbound-compat.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,10 @@ block buffer and tracks appended output bytes incrementally. A caller cancellati
190190
terminal returns 499 / `client_cancelled`; an already accepted terminal keeps its result. Reader,
191191
timer, turn, and translator ownership are released through the existing lifecycle.
192192

193+
## HTTP caller conversation identity
194+
195+
`src/server/caller-session-identity.ts` promotes validated `x-session-id` on HTTP Responses and Messages before turn admission in `src/server/index/serve-options.ts`. Explicit `session_id`, `session-id`, or `thread-id` presence wins, including empty values; managed Grok promotion runs first on Responses. The trimmed marker must start with an ASCII letter/digit, contain only letters, digits, dots, underscores, colons or hyphens, and stay within 128 characters. Loopback admission keeps it; authenticated admission scopes it with the trusted credential principal into an opaque SHA-256 identifier and skips promotion without that principal. Bodies and abort signals are preserved, and the original Request owns Bun timeout lookup. This provides continuity, not authorization or guaranteed cache hits. Existing explicit/Grok identities, Chat Completions, WebSocket frames, compact and count_tokens retain their behavior.
196+
193197
## Chat conversation identity forwarding
194198

195199
`src/server/chat-completions.ts` preserves caller `prompt_cache_key` on the Chat-to-Responses

‎structure/runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ TTL or lock-file deletion participates in recovery.
223223
An explicit Codex integration OFF skips startup cache invalidation before the user-scoped catalog
224224
serialization lock is resolved. Explicit `sync` and `sync-cache` retain their catalog-only override.
225225

226-
`startServer` composes up to four sockets in one synchronous startup transaction: the public data listener, optional unauthenticated data-loopback and hub-management listeners, and the optional `hub-link` listener, which opens only for a recorded link and persists its concrete `127.0.0.1:<listenerPort>`. Linked-machine data uses the [connection-bound relay contract](remote-link.md#connection-bound-relay-authentication); client-local credentials and routing policy remain unchanged.
226+
`startServer` composes up to four sockets in one synchronous startup transaction: the public data listener, optional unauthenticated data-loopback and hub-management listeners, and the optional `hub-link` listener, which opens only for a recorded link and persists its concrete `127.0.0.1:<listenerPort>`. HTTP Responses/Messages apply the [caller header contract](data-planes/inbound-compat.md#http-caller-conversation-identity) before turn admission and dispatch. Linked-machine data uses the [connection-bound relay contract](remote-link.md#connection-bound-relay-authentication); client-local credentials and routing policy remain unchanged.
227227
The data-loopback socket serves a fixed data-plane allowlist: Responses and its compact sibling,
228228
the native search relay, the standalone Images POSTs, keyed file/stream transcription, `GET /v1/models`, the realtime voice shapes,
229229
and the Anthropic and OpenAI chat wires the host's own local clients speak — `POST /v1/messages`,

‎structure/transports/responses.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ When a successful streamed native response has a missing or unrecognized non-JSO
1111

1212
## Responses HTTP/SSE
1313

14-
Optional Codex memory selection enters `src/server/responses/request-prepare.ts` for HTTP and WebSocket frames, as specified in [memory phase routing](responses-failover.md#memory-phase-routing); an unset phase keeps its existing route and starts no background work. Responses request preparation stabilizes incoming `<skills_instructions>` under `skills.catalog_refresh`: `per_session` (default) reuses the first received catalog for a conversation; `per_turn` leaves the supplied catalog unchanged. Other instruction sections and user/tool content remain untouched. Requests without a reliable conversation identity bypass snapshots; shared prompt-cache cohorts are not conversation identities. Only a body with exactly one catalog block across its instructions and developer/system content takes part; two or more pass through unchanged. A known snapshot is substituted before parsing, but a new catalog is stored only when preparation reaches its success return, so a request rejected by parsing or admission pins nothing. Without a named principal, snapshots are shared by conversation id only on a server that requires no data-plane auth. Snapshots are process-local, expire after four idle hours, and use bounded LRU retention; oversized blocks bypass caching. The dashboard's `src/codex/prompt-layers.ts` and `src/codex/prompt-text-probe.ts` continue observing current files for previews and do not own session snapshots.
14+
HTTP ingress applies the [caller header contract](../data-planes/inbound-compat.md#http-caller-conversation-identity) before admission and dispatch. Optional Codex memory selection enters `src/server/responses/request-prepare.ts` for HTTP and WebSocket frames, as specified in [memory phase routing](responses-failover.md#memory-phase-routing); an unset phase keeps its existing route and starts no background work. Responses request preparation stabilizes incoming `<skills_instructions>` under `skills.catalog_refresh`: `per_session` (default) reuses the first received catalog for a conversation; `per_turn` leaves the supplied catalog unchanged. Other instruction sections and user/tool content remain untouched. Requests without a reliable conversation identity bypass snapshots; shared prompt-cache cohorts are not conversation identities. Only a body with exactly one catalog block across its instructions and developer/system content takes part; two or more pass through unchanged. A known snapshot is substituted before parsing, but a new catalog is stored only when preparation reaches its success return, so a request rejected by parsing or admission pins nothing. Without a named principal, snapshots are shared by conversation id only on a server that requires no data-plane auth. Snapshots are process-local, expire after four idle hours, and use bounded LRU retention; oversized blocks bypass caching. The dashboard's `src/codex/prompt-layers.ts` and `src/codex/prompt-text-probe.ts` continue observing current files for previews and do not own session snapshots.
1515
`/v1/responses` is the main Codex-facing endpoint. The server parses Responses input, routes to a
1616
provider, lets the selected adapter speak the upstream protocol, then bridges adapter events back to
1717
Responses-compatible streaming output. The routed provider name follows every adapter build, including retries and continuations; only `github-copilot` injects a configured `modelContextTiers` value as upstream `contextTier`, while unconfigured passthrough retains the caller field. For an opted-in key-auth provider, a hosted-search continuation stays bound to the API-key selection that served the first leg; the contract is the [hosted-search continuation binding](../providers-and-adapters.md#hosted-search-continuation-binding).

‎tests/fixtures/test-layout-expected.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
"provider-antigravity-family-catalog.test.ts": "providers",
66
"claude-subagent-model-force.test.ts": "claude-integration",
77
"subagent-model-force-api.test.ts": "server",
8+
"caller-session-identity.test.ts": "server",
9+
"caller-session-ingress.test.ts": "server",
810
"agent-subagent-force.test.ts": "cli",
911
"compaction-event-ownership.test.ts": "responses",
1012
"zed-retained-budget.test.ts": "providers",

‎tests/providers/xai/grok-session-identity.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,5 +129,6 @@ describe("Grok turns reach the ChatGPT Codex backend with session_id", () => {
129129
test("the /v1/responses route hands handleResponses the Grok-promoted request", () => {
130130
// Pins the one-line wiring; the cases above call the helper directly.
131131
const source = readFileSync(repoPath("src", "server", "index", "serve-options.ts"), "utf8");
132-
expect(source).toContain("await handleResponses(withGrokSessionIdentity(req), config, logCtx, {");
132+
expect(source).toContain("const sessionReq = withCallerSessionIdentity(withGrokSessionIdentity(req), admission);");
133+
expect(source).toContain("await handleResponses(sessionReq, config, logCtx, {");
133134
});

0 commit comments

Comments
 (0)