diff --git a/PLUGIN.md b/PLUGIN.md index 11d3714b52..ca5341f6ab 100644 --- a/PLUGIN.md +++ b/PLUGIN.md @@ -59,7 +59,7 @@ On **every model request** the plugin sends: - `x-bili-plugin: ` — announces plugin mode for this session. - `x-bili-plugin-conversation: ` — the agent's real conversation/session id, stable for the whole conversation. - `x-bili-plugin-context-window: ` (optional but recommended) — the model's context window as configured inside the agent (e.g. a pinned/overridden `contextWindow`). This becomes the authoritative "native" window for nudge decisions — it outranks the proxy's built-in table and the models.dev registry (most valuable for private relays and MITM mode), while operator tuning (`compress.modelContextLimit`) still outranks it. -- `x-bili-plugin-instructions-mutable: 1` (optional; send only if true) — declares that your conversation ids are **persona-scoped**: one id per persona, and the request's system/instructions text may change mid-conversation without changing the persona (e.g. opencode re-renders AGENTS.md into `instructions` on every edit). With this flag the proxy stops mixing the instructions text into the compression-namespace fingerprint, so instruction drift no longer forks the session into an orphan `|sub:` namespace that resets all compression state. Without it, drifted instructions still fork — that is the safe default for agents whose ids are not persona-scoped. +- `x-bili-plugin-instructions-mutable: 1` (optional; send only if true) — declares that your conversation ids are **persona-scoped**: one id per persona, and the request's system/instructions text may change mid-conversation without changing the persona (e.g. opencode re-renders AGENTS.md into `instructions` on every edit). The proxy now keys plugin conversation ids verbatim by default (#1106), so this flag is vestigial for current proxies — keep stamping it for compatibility with older proxy versions, which use it to stop mixing the instructions text into the compression-namespace fingerprint. Effects on the proxy for that session: diff --git a/src/plugin.ts b/src/plugin.ts index ca455ef891..3604f4cf5c 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -59,13 +59,12 @@ export const PLUGIN_BYPASS_HEADER = "x-bili-plugin-bypass"; export const PLUGIN_CONTEXT_WINDOW_HEADER = "x-bili-plugin-context-window"; export const PLUGIN_MAX_OUTPUT_HEADER = "x-bili-plugin-max-output"; export const PLUGIN_MODEL_HEADER = "x-bili-plugin-model"; -/** #1102: stamped "1" by plugins whose host mints one conversation id per - * persona (opencode: subagents get their own child session ids), so - * mid-conversation instruction drift (AGENTS.md reconcile) must NOT fork the - * compression session via the instructions fingerprint. Honored only together - * with x-bili-plugin + x-bili-plugin-conversation (see - * instructionsFingerprintExempt in src/session-id.ts); hosts whose id - * semantics are unverified never stamp it. */ +/** #1102/#1106: stamped "1" by plugins whose host mints one conversation id per + * persona (opencode: subagents get their own child session ids). Since the + * instructions fingerprint became an allowlist (#1106 — exempt is the + * default for every non-codex/non-claude signal), this declaration is + * vestigial: hosts keep stamping it for protocol compatibility with older + * proxies, but current proxies key verbatim regardless. */ export const PLUGIN_INSTRUCTIONS_MUTABLE_HEADER = "x-bili-plugin-instructions-mutable"; export const PLUGIN_PROTOCOL_VERSION = 1; diff --git a/src/server.ts b/src/server.ts index 27797fccbb..8632518731 100644 --- a/src/server.ts +++ b/src/server.ts @@ -91,7 +91,7 @@ import { rewriteGoogleJsonResponse } from "./stream-google.js"; import { rewriteResponsesJsonResponse } from "./stream-responses.js"; import { observeResponsesTerminalState } from "./stream-terminal.js"; import { emitPreflightError, emitStreamError } from "./stream-error.js"; -import { affinityToken, claudeSubagentAgentId, claudeSubagentSplit, clientConversationHeader, codexTurnIdentity, instructionsFingerprintExempt, preferPromptCacheKeyIdentity, type ConversationIdentity } from "./session-id.js"; +import { affinityToken, claudeSubagentAgentId, claudeSubagentSplit, clientConversationHeader, codexTurnIdentity, instructionsFingerprintApplies, preferPromptCacheKeyIdentity, type ConversationIdentity } from "./session-id.js"; import { prefixAffinity, type AnonymousAffinity } from "./prefix-affinity.js"; import { maybeAdoptForkBlocks } from "./fork-adoption.js"; import { flushPrefixAffinity, hydratePrefixAffinity, scheduleAffinityPersist } from "./affinity-persist.js"; @@ -1345,20 +1345,22 @@ async function handle( // kernel's empty-instructions non-anchoring path is left // untouched for metadata-less clients). ? codexTurn.value - : instructionsFingerprintExempt(req.headers) - // #1102: verified persona-scoped native conversation ids - // (opencode ses_ headers / plugin declaration) may see - // instruction drift mid-conversation (AGENTS.md reconcile) - // without a persona change — key them verbatim like the - // trusted codexTurn branch above instead of forking an - // orphan |sub: session. Trust set + why every other - // signal keeps the fingerprint: see - // instructionsFingerprintExempt in src/session-id.ts. - ? (responsesIdentity?.value ?? conversationSignalResponses(parsed as ResponsesRequestBody, convHeader)) - : subagentNamespace( + : instructionsFingerprintApplies(req.headers) + // #1106: the instructions fingerprint is an inverted + // allowlist — it applies ONLY to codex traffic (root + // threads / older builds; subagent threads key by thread-id + // above) and claude-over-Responses (#150/#970 id-sharing + // personas). Everyone else (opencode #1102, grok/mcode, + // plugin lanes, generic x-session-id / body session_id) + // keys verbatim: instructions drift there means the same + // conversation evolved (upgrade / plugin / AGENTS.md), + // not a new persona. See instructionsFingerprintApplies + // in src/session-id.ts. + ? subagentNamespace( responsesIdentity?.value ?? conversationSignalResponses(parsed as ResponsesRequestBody, convHeader), (parsed as ResponsesRequestBody).instructions, - ); + ) + : (responsesIdentity?.value ?? conversationSignalResponses(parsed as ResponsesRequestBody, convHeader)); // The session ID is the client-provided conversation value VERBATIM — // no hash, no protocol/credential/upstream dimensions (#286): those // are all mutable mid-conversation (bearer rotation, relay switching, diff --git a/src/session-id.ts b/src/session-id.ts index e2c30aa5f3..aadf539773 100644 --- a/src/session-id.ts +++ b/src/session-id.ts @@ -1,3 +1,5 @@ +import { isCodexClient } from "./codex-compact.js"; + export type ConversationIdentity = { value: string; source: "header" | "body-session" | "metadata-session" | "previous-response" | "prompt-cache-key" | "content-fingerprint" | "generated"; @@ -73,42 +75,47 @@ export function conversationHeaderSource(headers: Record session and resets all compression state. + * share one conversation id. Exactly two defendants ever needed it: + * - codex (#150): task-level session ids are REUSED across tasks, so + * different task instructions under one id must not merge. Modern codex + * (>=0.147) already isolates subagent threads via x-codex-turn-metadata -> + * thread-id verbatim (server.ts keys those directly, bypassing this + * predicate); the fingerprint still matters for root threads and older + * codex builds, detected by the turn-metadata header or the user agent + * (same convention as isCodexClient, #645). + * - claude over Responses (#970): subagents SHARE the main agent's session + * id (the Anthropic path splits them via claudeSubagentSplit; a claude + * client on the Responses wire only has this fingerprint). * - * Trust set (each verified against the client's own source): - * - x-session-affinity with a ses_… value / x-opencode-session: opencode stamps - * its session id on every model request and mints a fresh child session id - * for every task-tool subagent (sessions.create({ parentID })). - * - x-bili-plugin-conversation + x-bili-plugin-instructions-mutable: 1 — the - * plugin declares its host's conversation ids are persona-scoped. Only the - * opencode plugin stamps the declaration today; unverified hosts (dsh, - * hermes, …) stay on the fingerprinted path. + * Everyone else keys VERBATIM: instructions drift mid-id means "same + * conversation, evolved system context" (software upgrade, plugin install, + * AGENTS.md edit - the relay-station majority case, #1106), and forking there + * resets all compression state for no defending bug. opencode (persona-scoped + * ses_ ids, #1102/#1104), grok/mcode (per-session ids by their own source), + * plugin conversation ids, and generic x-session-id / body session_id all + * stay on the verbatim path now. The x-bili-plugin-instructions-mutable + * declaration (#1104) is vestigial: exempt is the default; hosts keep + * stamping it for protocol compatibility with older proxies. * - * Everything else deliberately keeps the fingerprint: Codex body/header/metadata - * session ids (#150), x-claude-code-session-id (Claude subagents SHARE the main - * agent's session id, #970), grok/mcode/generic x-session-id, prompt-cache-key. + * A future client that shares one id across personas and separates them ONLY + * by instructions must be added here (same evidence-per-client discipline as + * #1104, inverted). */ -export function instructionsFingerprintExempt(headers: Record): boolean { - const src = conversationHeaderSource(headers); - if (!src) return false; - if (src.name === "x-opencode-session") return true; - if (src.name === "x-session-affinity" && src.value.startsWith("ses_")) return true; - if (src.name === "x-bili-plugin-conversation") { - const flag = headers["x-bili-plugin-instructions-mutable"]; - return typeof flag === "string" && flag.trim() === "1"; - } - return false; +export function instructionsFingerprintApplies(headers: Record): boolean { + const turnMeta = headers["x-codex-turn-metadata"]; + if (typeof turnMeta === "string" && turnMeta.trim().length > 0) return true; + // One definition of "codex traffic" process-wide (every other codex path in + // server.ts uses isCodexClient, #645): case-sensitive by convention. A + // case-insensitive match would pull non-codex relays with "Codex"-shaped + // UAs back into the fingerprint and re-fork them mid-conversation (#1106). + if (isCodexClient(headers)) return true; + return conversationHeaderSource(headers)?.name === "x-claude-code-session-id"; } /** diff --git a/tests/responses-instructions-drift.test.ts b/tests/responses-instructions-drift.test.ts index fa0ae776fd..f5fec5e368 100644 --- a/tests/responses-instructions-drift.test.ts +++ b/tests/responses-instructions-drift.test.ts @@ -8,40 +8,48 @@ import type { ProxyOptions } from "../src/config.ts"; import { SessionStore, _setStoreForTest } from "../src/persist.ts"; import { _setForTest as setRegistryForTest } from "../src/registry.ts"; import { _resetSessionsForTest } from "../src/session.ts"; -import { conversationHeaderSource, instructionsFingerprintExempt } from "../src/session-id.ts"; +import { conversationHeaderSource, instructionsFingerprintApplies } from "../src/session-id.ts"; // #1102: opencode's system-context reconcile rewrites `instructions` whenever // AGENTS.md is edited mid-session. Its conversation ids are persona-scoped // (one session id per persona; task-tool subagents mint fresh child ids), so // same-id + drifted instructions must NOT fork the compression namespace. +// #1106 inverts the default: the fingerprint is an allowlist (codex + +// claude-over-Responses only); everyone else keys verbatim. -test("instructionsFingerprintExempt: opencode native session ids are persona-scoped", () => { - assert.equal(instructionsFingerprintExempt({ "x-session-affinity": "ses_abc123XYZ" }), true); - assert.equal(instructionsFingerprintExempt({ "x-session-affinity": " ses_trimmed " }), true); - assert.equal(instructionsFingerprintExempt({ "x-opencode-session": "zen-sess-1" }), true); +test("instructionsFingerprintApplies: codex traffic keeps the fingerprint (#150)", () => { + assert.equal(instructionsFingerprintApplies({ "x-codex-turn-metadata": '{"thread_source":"user","thread_id":"t-1"}', "thread-id": "t-1", "session-id": "sess-150" }), true); + assert.equal(instructionsFingerprintApplies({ "x-codex-turn-metadata": "not-json", "session-id": "sess-150" }), true); + assert.equal(instructionsFingerprintApplies({ "user-agent": "codex_cli_rs/0.147.0 (Ubuntu)", "session-id": "sess-150" }), true); }); -test("instructionsFingerprintExempt: non-opencode senders of generic headers stay fingerprinted", () => { - assert.equal(instructionsFingerprintExempt({ "x-session-affinity": "task-123" }), false); - assert.equal(instructionsFingerprintExempt({ "x-session-id": "ses_looks_like_opencode" }), false); - assert.equal(instructionsFingerprintExempt({ "session-id": "thread-9" }), false); - assert.equal(instructionsFingerprintExempt({ "x-claude-code-session-id": "uuid-1" }), false); - assert.equal(instructionsFingerprintExempt({}), false); +test("instructionsFingerprintApplies: claude-over-Responses keeps the fingerprint (#970)", () => { + assert.equal(instructionsFingerprintApplies({ "x-claude-code-session-id": "uuid-1" }), true); + assert.equal(instructionsFingerprintApplies({ "x-claude-code-session-id": "uuid-1", "x-session-affinity": "ses_abc" }), true); + // only counts when the claude header WINS the walk — an outranking plugin + // conversation id moves the request onto the verbatim default + assert.equal(instructionsFingerprintApplies({ "x-bili-plugin": "host", "x-bili-plugin-conversation": "c-1", "x-claude-code-session-id": "uuid-1" }), false); }); -test("instructionsFingerprintExempt: claude header outranks affinity (shared-id subagents must stay split)", () => { - assert.equal(instructionsFingerprintExempt({ "x-claude-code-session-id": "uuid-1", "x-session-affinity": "ses_abc" }), false); +test("instructionsFingerprintApplies: everyone else keys verbatim (#1106)", () => { + assert.equal(instructionsFingerprintApplies({ "x-session-affinity": "ses_abc123XYZ" }), false); + assert.equal(instructionsFingerprintApplies({ "x-opencode-session": "zen-sess-1" }), false); + assert.equal(instructionsFingerprintApplies({ "x-session-id": "generic-relay-client-7" }), false); + assert.equal(instructionsFingerprintApplies({ "session-id": "thread-9" }), false); + assert.equal(instructionsFingerprintApplies({ "x-grok-session-id": "gr-1" }), false); + assert.equal(instructionsFingerprintApplies({ "x-mavis-session-id": "mc-1" }), false); + assert.equal(instructionsFingerprintApplies({ "user-agent": "CherryStudio/1.0", "x-session-id": "cs-1" }), false); + // codex UA detection stays case-sensitive (isCodexClient convention, #645) + // so relays with "Codex"-shaped UAs are not pulled back into the fingerprint + assert.equal(instructionsFingerprintApplies({ "user-agent": "CodeXchange/1.0", "x-session-id": "cx-1" }), false); + assert.equal(instructionsFingerprintApplies({}), false); }); -test("instructionsFingerprintExempt: plugin declaration requires marker + conversation + flag", () => { +test("instructionsFingerprintApplies: plugin declaration flag is vestigial (#1106)", () => { const base = { "x-bili-plugin": "opencode", "x-bili-plugin-conversation": "c-1", "x-bili-plugin-instructions-mutable": "1" }; - assert.equal(instructionsFingerprintExempt(base), true); - assert.equal(instructionsFingerprintExempt({ ...base, "x-bili-plugin-instructions-mutable": undefined }), false); - assert.equal(instructionsFingerprintExempt({ ...base, "x-bili-plugin": undefined }), false); - assert.equal(instructionsFingerprintExempt({ ...base, "x-bili-plugin-conversation": undefined }), false); - // the protocol honors the declaration from any cooperative plugin — the - // contract is that only hosts with VERIFIED persona-scoped ids stamp it - assert.equal(instructionsFingerprintExempt({ "x-bili-plugin": "future-host", "x-bili-plugin-conversation": "c-2", "x-bili-plugin-instructions-mutable": "1" }), true); + assert.equal(instructionsFingerprintApplies(base), false); + assert.equal(instructionsFingerprintApplies({ ...base, "x-bili-plugin-instructions-mutable": undefined }), false); + assert.equal(instructionsFingerprintApplies({ "x-bili-plugin": "future-host", "x-bili-plugin-conversation": "c-2", "x-bili-plugin-instructions-mutable": "1" }), false); }); test("conversationHeaderSource: reports the winning header with priority order intact", () => { @@ -199,13 +207,15 @@ test("e2e #1102: opencode AGENTS.md edit (instructions drift) keeps ONE session }); }); -test("e2e #1102: plugin-declared opencode session keeps ONE session across instructions drift", async () => { +test("e2e #1106: plugin conversation without the mutable flag stays ONE session (flag is vestigial)", async () => { _setStoreForTest(new SessionStore({ enabled: false })); _resetSessionsForTest(); setRegistryForTest({}); const CONVERSATION = "plg-drift-e2e"; - const headers = { "content-type": "application/json", "x-bili-plugin": "opencode", "x-bili-plugin-conversation": CONVERSATION, "x-bili-plugin-instructions-mutable": "1" }; + // no x-bili-plugin-instructions-mutable — under #1104 this forked; under + // the #1106 allowlist default the plugin lane keys verbatim regardless + const headers = { "content-type": "application/json", "x-bili-plugin": "opencode", "x-bili-plugin-conversation": CONVERSATION }; await withProxy((_req, res) => { res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); @@ -223,7 +233,74 @@ test("e2e #1102: plugin-declared opencode session keeps ONE session across instr assert.equal(bodies.length, 2); const stats = await (await fetch(statsUrl)).json(); - assert.equal(stats.sessions.length, 1, "plugin-declared persona-scoped id must not fork on instruction drift"); + assert.equal(stats.sessions.length, 1, "plugin lane keys verbatim; the mutable flag is no longer required"); assert.equal(stats.sessions[0].id, CONVERSATION); }); }); + +test("e2e #1106: generic relay client (x-session-id) keeps ONE session across instructions drift", async () => { + _setStoreForTest(new SessionStore({ enabled: false })); + _resetSessionsForTest(); + setRegistryForTest({}); + + const GENERIC_ID = "relay-client-conv-42"; + const headers = { "content-type": "application/json", "x-session-id": GENERIC_ID, "user-agent": "SomeRelayClient/2.3" }; + + await withProxy((_req, res) => { + res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); + res.write(textEvents("relay lane answer")); + res.write(completed(800)); + res.end(); + }, async (url, statsUrl, bodies) => { + const input = [{ type: "message", role: "user", content: "initial turn" }]; + // system prompt rewritten mid-conversation: software upgrade / plugin + // install / AGENTS.md edit — the #1106 relay majority case + const req1 = await fetch(url, { method: "POST", headers, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: "system prompt v1 (base)", input }) }); + assert.equal(req1.status, 200); + await req1.text(); + const req2 = await fetch(url, { method: "POST", headers, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: "system prompt v2 (upgraded, new plugin tools, AGENTS.md edited)", input: [...input, { type: "message", role: "assistant", content: "ok" }, { type: "message", role: "user", content: "second turn" }] }) }); + assert.equal(req2.status, 200); + await req2.text(); + + assert.equal(bodies.length, 2); + const stats = await (await fetch(statsUrl)).json(); + assert.equal(stats.sessions.length, 1, "generic id + instructions drift = same conversation evolving, no fork"); + assert.equal(stats.sessions[0].id, GENERIC_ID); + }); +}); + +test("e2e #150: codex root thread reusing a task id across personas still splits by instructions fingerprint", async () => { + _setStoreForTest(new SessionStore({ enabled: false })); + _resetSessionsForTest(); + setRegistryForTest({}); + + const TASK_ID = "codex-task-id-9"; + const headers = { + "content-type": "application/json", + "user-agent": "codex_cli_rs/0.147.0", + "session-id": TASK_ID, + "x-codex-turn-metadata": JSON.stringify({ thread_source: "user", thread_id: "t-root" }), + "thread-id": "t-root", + }; + + await withProxy((_req, res) => { + res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); + res.write(textEvents("codex answer")); + res.write(completed(700)); + res.end(); + }, async (url, statsUrl, _bodies) => { + const input = [{ type: "message", role: "user", content: "task turn" }]; + const req1 = await fetch(url, { method: "POST", headers, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: "task A persona instructions", input }) }); + assert.equal(req1.status, 200); + await req1.text(); + const req2 = await fetch(url, { method: "POST", headers, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: "task B persona instructions (different task reusing the id)", input }) }); + assert.equal(req2.status, 200); + await req2.text(); + + const stats = await (await fetch(statsUrl)).json(); + assert.equal(stats.sessions.length, 2, "codex id-sharing personas stay split (#150 allowlist entry)"); + const ids = stats.sessions.map((s: { id: string }) => s.id).sort(); + assert.equal(ids[0], TASK_ID); + assert.ok(ids[1].startsWith(`${TASK_ID}|sub:`), `forked namespace, got ${ids[1]}`); + }); +}); diff --git a/tests/subagent-namespace.test.ts b/tests/subagent-namespace.test.ts index 44b2832996..cbc7dca03f 100644 --- a/tests/subagent-namespace.test.ts +++ b/tests/subagent-namespace.test.ts @@ -158,16 +158,20 @@ test("e2e #150: guardian subagent request bypasses the main session's compressio }; try { - const mainResp = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(mainBody) }); + // Metadata-less codex build (pre-0.147: no x-codex-turn-metadata), but + // still self-identified by its user agent — the #1106 fingerprint + // allowlist keeps the instructions split exactly for codex traffic. + const headers = { "content-type": "application/json", "user-agent": "codex_cli_rs/0.146.0" }; + const mainResp = await fetch(url, { method: "POST", headers, body: JSON.stringify(mainBody) }); assert.equal(mainResp.status, 200); await mainResp.text(); - const guardianResp = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(guardianBody) }); + const guardianResp = await fetch(url, { method: "POST", headers, body: JSON.stringify(guardianBody) }); assert.equal(guardianResp.status, 200); const guardianOut = await guardianResp.text(); assert.ok(guardianOut.includes("APPROVED"), "guardian round completes upstream"); - const replayResp = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(mainBody) }); + const replayResp = await fetch(url, { method: "POST", headers, body: JSON.stringify(mainBody) }); assert.equal(replayResp.status, 200); await replayResp.text();