Skip to content

Commit f85925d

Browse files
fix(server): promote scoped caller conversation headers (#6554)
Preserve explicit caller session markers and promote safe fallback markers with principal isolation before admission. Retain body/abort semantics and existing routing precedence. Validated at89ae31b9ed1b74f85ed32135f19cdeac764d6343 by Cross-platform CI37173659981 and independent scoped code/security review. Co-authored-by: mayigululu-hash <[email protected]>
1 parent 5965256 commit f85925d

15 files changed

Lines changed: 485 additions & 8 deletions

File tree

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Two independent cache-identity fixes
2+
3+
Public callers can provide a conversation marker without the session header consumed downstream, while Devin currently allocates a trajectory for every turn. This unit prepares separate replacements for #6521 and #6488, preserving their useful behavior and adding deterministic identity/lifetime coverage. Maintainers use this record to review coverage and decide future integration; publication is the terminal outcome, not merge or release.
4+
5+
## Scope and completion
6+
7+
Satisfy-spec HOTL, triggered by the next-release cache lane. Class C4 for identity and credential scoping. First lock this docs-only roadmap, then execute `010_caller.md`, then `020_devin.md` serially on independent branches from dev. The serial order avoids shared-checkout branch collisions; neither runtime patch depends on the other.
8+
9+
Allowed: scoped local commits, pushes, two ordinary dev PRs, focused verification, read-only GitHub evidence and gpt-6.1-sol leaf implementation/review through the available V1 tools. Excluded: merges, release/version edits, installed-runtime changes, live upstream/account writes, source closure, branch deletion, native stacks, unrelated edits, outbound peer messages. Security working notes stay in ignored scratch. No token/cost or wall-clock budget was imposed; use local fixtures and ordinary PR CI only, no paid/live provider probes.
10+
11+
DONE requires published attached replacement PRs, source coverage and author trailers, passing focused regressions/static gates, independent review and inspected current-head CI. Missing broad/native/live proof keeps a draft with explicit limits. A material scope conflict returns to main for decision; external blockage is reported truthfully under host rules. Evidence lives in ignored lane scratch and goalplan receipts; public records contain only source provenance and outcomes.
12+
13+
## Source and verification
14+
15+
Baseline: `0818ea1812a028e1c14cd0b0511b44863407bc52`.
16+
- #6521: `011ab507fcf03ae86933098de1994b25ecfd0495`, mayigululu-hash.
17+
- #6488: `a0b199fc6b96367fb174f6488a7a45eb58eccd54`, Hanqing Zhao (@HQ1995).
18+
19+
Original live-cache measurements are author evidence in the source PRs, not new measurements or promised savings. Both source diffs were inspected; neither is an inherited stack. Read-only native membership queries returned empty lists.
20+
21+
Focused baseline command: `bun test tests/providers/devin-prompt-cache.test.ts tests/providers/xai/grok-session-identity.test.ts tests/server/loopback-listener-admission.test.ts`: 59 pass, 0 fail. Dependencies installed with `bun install --frozen-lockfile` (exit 0). Each implementation runs its named behavior tests, typecheck, structure/privacy/layout/ratchet and docs build. Full local and changed suites are impractical during concurrent lanes and release; broader platform coverage belongs to hosted PR checks. CI triggers on every pull request; feature pushes alone do not trigger the main workflow. No manual release workflow is needed.
22+
23+
## Consultation
24+
25+
Architect 01a10493-64d4-76c2-b14e-d1307ad82a43 proposed CS-01..04 and DT-01..04. Main accepts caller principal scoping and promotion before admission, while preserving the original request for Bun timeout ownership. Main accepts the bounded provider-local trajectory store and whole-wire field chain. Own thread headers outrank a parent-derived `_clientThreadId`; direct internal callers without a parent may retain that field as fallback. No idle TTL/logout integration is claimed: fixed capacity bounds retention and credential rotation creates a different key. The executable documents carry the decisions; same-architect reflection and independent audit are required before implementation.
26+
27+
Architect reflection: ALIGNED, with three test refinements accepted: exercise actual combo recall separation; parent-only/direct fallback/session aliases; double release after reacquisition and named retry wire continuity. Baseline typecheck, structure, privacy, layout (18 tests) and ratchet passed. The gate commands are repository scripts/direct test paths and observe the planned target classes. No broad suite was run.
28+
29+
Roadmap D conclusion: independent reviewer 01a1049a-9a43-7ee1-9e7a-58073e8eb9e7 found no blockers (VERDICT: PASS). Fresh-reader check understood answer, evidence, and next action without revision. The docs-only cycle locks the two independent plans. Next: execute caller, then Devin. No cache savings or runtime improvement has been measured in this cycle.
Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Caller session header replacement
2+
3+
Depends on roadmap only. Branch `codex/next-release-261004-cache-caller`, independent dev PR. Implements source #6521 with CS-01..04 refinements. Runtime scope is caller helper and serve-options; no global recall redesign.
4+
5+
## File delta
6+
7+
NEW `src/server/caller-session-identity.ts`: retain source `callerSessionId(headers)` validation: any explicit session_id/session-id/thread-id presence suppresses promotion, trim x-session-id and accept /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/. `withCallerSessionIdentity(req, admission)` returns the same request on skip, raw validated ID for loopback, and a stable opaque SHA-256 digest of a structured tuple of trusted `contextPrincipalIdOf(admission)` and conversation for authenticated callers. Unknown principal declines promotion. No body read, no persistent map, no raw credential storage. Clone with `new Request(req, {headers})` only when promoting.
8+
9+
MODIFY `src/server/index/serve-options.ts`: import helper. Responses: after auth/origin checks form `sessionReq = withCallerSessionIdentity(withGrokSessionIdentity(req), admission)`; use sessionReq for runAdmittedHttpTurn and handleResponses. Messages: likewise form `sessionReq = withCallerSessionIdentity(req, admission)` for admission and handleClaudeMessages. Keep original req for timeout lookup, response CORS and cancellation callbacks. Grok and explicit identities win unchanged. Existing guards still run first.
10+
11+
NEW `tests/server/caller-session-identity.test.ts`: carry all source cases and mocked handleResponses upstream-wire test, adapting signature to explicit loopback admission. Add explicit-empty precedence, exact 128/129 boundary, whitespace normalization, conflicting Grok/caller values, two trusted principals with same conversation, credential rotation and absent principal. Verify body bytes/method/url/abort and no-op object identity. Add behavioral ingress coverage for both Responses and Messages and verify admission receives the same promoted identity; use existing local fixture patterns, no live requests. Public combo recall separation may be demonstrated by resulting session lane keys and existing recall APIs. Source pins remain secondary coverage.
12+
13+
MODIFY `tests/providers/xai/grok-session-identity.test.ts` and `tests/server/loopback-listener-admission.test.ts`: update changed source-wiring pins without dropping assertions. MODIFY `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`: add caller-session-identity to server. MODIFY `structure/runtime.md`, applicable inbound-compat/responses owner docs and `docs-site/src/content/docs/reference/proxy-formats.md`: describe headers, priority, trusted-principal namespace, loopback behavior, no cache-hit promise. Review mapped owner docs; update only affected contracts.
14+
15+
## Activation and coverage
16+
17+
Explicit or Grok header plus differing x-session-id -> explicit/Grok wire value. Invalid/absent x-session-id -> original request. Two different admitted principals with equal x-session-id -> distinct promoted lanes. Rotated trusted credential -> new lane. Abort original -> rewritten signal aborts. Responses/Messages fixture -> backend receives promoted header after ingress authorization. All original source behaviors are carried except authenticated raw-ID equality is deliberately replaced by principal-scoped identity, and unsupported cache-savings assertions are removed.
18+
19+
Field chain: x-session-id creation is external caller; ingress validates and serializes session_id on Request; existing parsers consume it for affinity/logging and passthrough forwards it. No new persisted schema or deserializer.
20+
21+
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.
22+
23+
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.
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Devin conversation trajectory replacement
2+
3+
Depends on roadmap; serial execution follows caller publication solely for checkout ownership. Branch `codex/next-release-261004-cache-devin` starts independently at refreshed dev. Implements #6488 with DT-01..04 refinements.
4+
5+
## File delta
6+
7+
NEW `src/adapters/devin/trajectory.ts`: small provider-local claim/release API and bounded process-local store. Key = fixed digest of structured tuple [devinCacheIdentity(resolvedApiKey,resolvedHost), conversation], retaining no raw token/conversation. Map holds at most 256 entries {id,active}; insertion order is recency. Existing inactive key becomes active and is refreshed. Matching active key -> unretained fresh request trajectory. For a new key evict oldest inactive entry; if all 256 active, return unretained fresh trajectory. Never evict active entries. Release closure marks only its entry inactive, safely repeatable. Unnamed turns return no override and keep per-request wire UUID fallback. No timers, persistence or new dependency.
8+
9+
MODIFY `src/adapters/devin.ts`: import claim helper; derive conversation from own thread-id, then session_id/session-id/x-session-affinity, then parsed._clientThreadId only when no parent header identifies it as a shared parent. Preserve source direct internal _clientThreadId behavior without coalescing explicit siblings. Claim inside outer try after credential, tenant host, catalog and cancellation guards; pass trajectoryId into the existing chat request; release in finally after all returns/errors/retries. Claim remains live through reset/signature retry.
10+
11+
MODIFY `src/adapters/devin/cloud-direct/chat.ts`: add optional trajectoryId to BuildArgs and CloudChatRequest, forward in streamChatEvents to buildGetChatMessageRequest, replace #15.1 randomUUID with `args.trajectoryId ?? crypto.randomUUID()`. Creation: adapter claim; serialization: protobuf #15.1; deserialization: none (outbound-only); consumer: remote Cognition plus local wire-decoding tests. No external support or hit-rate claim beyond original author report.
12+
13+
MODIFY `tests/providers/devin-prompt-cache.test.ts`: preserve source wire override/default tests and named reuse/unnamed/overlap/HTTP400-release cases. NEW `tests/providers/devin-trajectory.test.ts`: pure store isolation/bounds plus adapter cases as appropriate. Cases: new request-scoped adapters reuse named ID; changed credential/host/conversation separates; own sibling thread IDs outrank shared parent; three overlapping turns distinct; later sequential turn reuses original; post-claim abort and failure release; >256 inactive names evict oldest; 256 active entries never evict, overflow unretained and distinct. Use deterministic barriers with bounded failure deadline and finally teardown. Public claim API is production API, no test-only reset export.
14+
15+
MODIFY both test layout registries for the new providers test. MODIFY `structure/providers-and-adapters.md` and `docs-site/src/content/docs/reference/adapters.md`: describe credential/host/conversation scope, overlap, bounded process-local lifetime and no guarantee of upstream cache savings. Review other owning structure docs for affected semantics.
16+
17+
## Verification and source coverage
18+
19+
Carry all source runtime and regression behavior, with deliberate replacement of raw delimiter key, uncapped live set, and parent-first identity. Preserve optional field fallback and all existing reset/signature handling. Scoped implementation leaf owns runtime/tests/layout; main owns docs and verification.
20+
21+
Run `bun test tests/providers/devin-*.test.ts tests/adapters/adapter-inner-send-budget-wiring.test.ts`, including new tests and existing originals, then typecheck, structure/privacy/layout/ratchet and docs build. Each conditional path above has a fixture that activates it and checks wire UUIDs or claim IDs. Actual native/live cache-hit measurements remain unrun. Publish draft pending broader hosted/native evidence, inspect exact-head checks and repair in-scope defects.
22+
23+
Reflection refinements: parent-only request with populated parsed._clientThreadId must remain unnamed; direct fallback without a parent and each alias are exercised. Double release after reacquisition must not deactivate the new claim (release closure has a released flag). Named reset/signature retry wire requests retain the same trajectory within the live claim.

‎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 });

0 commit comments

Comments
 (0)