diff --git a/PLUGIN.md b/PLUGIN.md index 8faf25363b..11d3714b52 100644 --- a/PLUGIN.md +++ b/PLUGIN.md @@ -42,7 +42,8 @@ Fetch once at plugin startup. "headers": { "agent": "x-bili-plugin", "conversation": "x-bili-plugin-conversation", - "contextWindow": "x-bili-plugin-context-window" + "contextWindow": "x-bili-plugin-context-window", + "instructionsMutable": "x-bili-plugin-instructions-mutable" }, "toolEndpoint": "/__bili/plugin/tool", "statusEndpoint": "/__bili/plugin/status" @@ -58,6 +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. Effects on the proxy for that session: diff --git a/src/agent/opencode-native.ts b/src/agent/opencode-native.ts index 20e91f44a4..035b272b11 100644 --- a/src/agent/opencode-native.ts +++ b/src/agent/opencode-native.ts @@ -539,6 +539,10 @@ export function createV1ServerHooks(origin: string, ctx: V1PluginContext, deps: } output.headers["x-bili-plugin"] = "opencode"; output.headers["x-bili-plugin-conversation"] = input.sessionID; + // #1102: opencode mints one session id per persona (task-tool + // subagents get fresh child ids), so instruction drift (AGENTS.md + // reconcile) must not fork the compression session. + output.headers["x-bili-plugin-instructions-mutable"] = "1"; const model = input.model; if (model && typeof model.providerID === "string" && typeof model.id === "string") { const key = `${model.providerID}/${model.id}`; diff --git a/src/agent/opencode-v2.ts b/src/agent/opencode-v2.ts index 7ef228ca48..1d0ac63271 100644 --- a/src/agent/opencode-v2.ts +++ b/src/agent/opencode-v2.ts @@ -167,6 +167,10 @@ export function createOpencodeV2Setup(options: OpencodeV2SetupOptions = {}): (ct if (!headers || typeof headers.set !== "function" || !sid || !state.proxyBase) return; headers.set("x-bili-plugin-conversation", sid); headers.set("x-bili-plugin", "opencode"); + // #1102: one session id per persona (subagents get child ids) — + // instruction drift (AGENTS.md reconcile) must not fork the + // compression session. + headers.set("x-bili-plugin-instructions-mutable", "1"); const model = e.model; if (model && typeof model.providerID === "string" && typeof model.id === "string") { const key = `${model.providerID}/${model.id}`; diff --git a/src/plugin.ts b/src/plugin.ts index b65e9ae290..ca455ef891 100644 --- a/src/plugin.ts +++ b/src/plugin.ts @@ -59,6 +59,14 @@ 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. */ +export const PLUGIN_INSTRUCTIONS_MUTABLE_HEADER = "x-bili-plugin-instructions-mutable"; export const PLUGIN_PROTOCOL_VERSION = 1; @@ -532,7 +540,7 @@ export function handlePluginManifest(res: import("node:http").ServerResponse): v openai: withSearchContextConversationDescription([...BILI_ACP_TOOLS_OPENAI, ABSORB_TOOL_OPENAI, RULE_TOOL_OPENAI].map(withConversationIdParam)), responses: withSearchContextConversationDescription([...BILI_ACP_TOOLS_RESPONSES, ABSORB_TOOL_RESPONSES, RULE_TOOL_RESPONSES].map(withConversationIdParam)), }, - headers: { agent: PLUGIN_AGENT_HEADER, conversation: PLUGIN_CONVERSATION_HEADER, contextWindow: PLUGIN_CONTEXT_WINDOW_HEADER, maxOutput: PLUGIN_MAX_OUTPUT_HEADER, model: PLUGIN_MODEL_HEADER }, + headers: { agent: PLUGIN_AGENT_HEADER, conversation: PLUGIN_CONVERSATION_HEADER, contextWindow: PLUGIN_CONTEXT_WINDOW_HEADER, maxOutput: PLUGIN_MAX_OUTPUT_HEADER, model: PLUGIN_MODEL_HEADER, instructionsMutable: PLUGIN_INSTRUCTIONS_MUTABLE_HEADER }, toolEndpoint: "/__bili/plugin/tool", statusEndpoint: "/__bili/plugin/status", runtimeInfoEndpoint: "/__bili/plugin/runtime-info", diff --git a/src/server.ts b/src/server.ts index efe6b9c096..27797fccbb 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, preferPromptCacheKeyIdentity, type ConversationIdentity } from "./session-id.js"; +import { affinityToken, claudeSubagentAgentId, claudeSubagentSplit, clientConversationHeader, codexTurnIdentity, instructionsFingerprintExempt, 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,10 +1345,20 @@ async function handle( // kernel's empty-instructions non-anchoring path is left // untouched for metadata-less clients). ? codexTurn.value - : subagentNamespace( - responsesIdentity?.value ?? conversationSignalResponses(parsed as ResponsesRequestBody, convHeader), - (parsed as ResponsesRequestBody).instructions, - ); + : 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( + responsesIdentity?.value ?? conversationSignalResponses(parsed as ResponsesRequestBody, convHeader), + (parsed as ResponsesRequestBody).instructions, + ); // 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 ab881466e0..e2c30aa5f3 100644 --- a/src/session-id.ts +++ b/src/session-id.ts @@ -34,6 +34,13 @@ export type ConversationIdentity = { /** Pull a client-provided conversation signal from headers, if any. */ export function clientConversationHeader(headers: Record): string | undefined { + return conversationHeaderSource(headers)?.value; +} + +/** Same header walk as clientConversationHeader, but also reports WHICH header + * won — needed by callers whose trust decision depends on the signal's origin + * (#1102), not just its value. */ +export function conversationHeaderSource(headers: Record): { name: string; value: string } | undefined { // x-bili-plugin-conversation first: a cooperative plugin's explicit // statement of which conversation it is driving (see src/plugin.ts). // It outranks every other signal — the plugin owns the session identity @@ -61,11 +68,49 @@ export function clientConversationHeader(headers: Record 0) return v.trim(); + if (typeof v === "string" && v.trim().length > 0) return { name, value: v.trim() }; } return undefined; } +/** #1102: whether the winning conversation signal is a VERIFIED persona-scoped + * native identifier, in which case the Responses-wire instructions fingerprint + * must be skipped when keying the compression session. + * + * subagentNamespace's instructions fingerprint exists to separate PERSONAS that + * share one conversation id (Codex threads reuse the task-level session id, + * #150). For clients whose native conversation id is persona-scoped — one id is + * minted per persona, so an id can never be reused across personas — the same + * id carrying different instructions mid-conversation means "same persona, + * updated system context" (opencode's system-context reconcile after an + * AGENTS.md edit), not a new persona. Fingerprinting there forks an orphan + * |sub: session and resets all compression state. + * + * 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. + * + * 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. + */ +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; +} + /** * Return only an identity the client already supplied. Generated identities * remain proxy-internal so billion-context does not invent upstream headers. diff --git a/tests/responses-instructions-drift.test.ts b/tests/responses-instructions-drift.test.ts new file mode 100644 index 0000000000..fa0ae776fd --- /dev/null +++ b/tests/responses-instructions-drift.test.ts @@ -0,0 +1,229 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import http from "node:http"; +import { once } from "node:events"; +import { defaultConfig } from "acp-kernel"; +import { startServer } from "../src/server.ts"; +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"; + +// #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. + +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("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("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("instructionsFingerprintExempt: plugin declaration requires marker + conversation + flag", () => { + 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); +}); + +test("conversationHeaderSource: reports the winning header with priority order intact", () => { + assert.deepEqual(conversationHeaderSource({ "x-bili-plugin": "pi", "x-bili-plugin-conversation": "p1", "x-session-affinity": "ses_z" }), { name: "x-bili-plugin-conversation", value: "p1" }); + assert.deepEqual(conversationHeaderSource({ "x-session-affinity": " ses_a ", "x-session-id": "s-b" }), { name: "x-session-affinity", value: "ses_a" }); + assert.equal(conversationHeaderSource({ "x-bili-plugin-conversation": "orphan" }), undefined); +}); + +function listen(server: http.Server): Promise { + if (server.listening) return Promise.resolve(); + return once(server, "listening").then(() => undefined); +} + +function close(server: http.Server): Promise { + return new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))); +} + +function sse(type: string, data: unknown): string { + return `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`; +} + +function completed(inputTokens: number): string { + return sse("response.completed", { response: { id: "resp_done", status: "completed", output: [], usage: { input_tokens: inputTokens, output_tokens: 5, total_tokens: inputTokens + 5 } } }); +} + +function fcEvents(outputIndex: number, callId: string, name: string, args: string): string { + return [ + sse("response.output_item.added", { item: { type: "function_call", id: `fc_${callId}`, call_id: callId, name }, output_index: outputIndex }), + sse("response.function_call_arguments.delta", { item_id: `fc_${callId}`, delta: args }), + sse("response.output_item.done", { item: { type: "function_call", id: `fc_${callId}`, call_id: callId, name, arguments: args }, output_index: outputIndex }), + ].join(""); +} + +function textEvents(delta: string): string { + return [ + sse("response.output_item.added", { item: { type: "message", id: "msg_1", role: "assistant", content: [] }, output_index: 0 }), + sse("response.output_text.delta", { item_id: "msg_1", output_index: 0, content_index: 0, delta }), + sse("response.output_item.done", { item: { type: "message", id: "msg_1", role: "assistant", content: [{ type: "output_text", text: delta }] }, output_index: 0 }), + ].join(""); +} + +async function withProxy(upstreamHandler: (req: http.IncomingMessage, res: http.ServerResponse, bodies: string[]) => void, fn: (url: string, statsUrl: string, bodies: string[]) => Promise): Promise { + const bodies: string[] = []; + const upstream = http.createServer((req, res) => { + const chunks: Buffer[] = []; + req.on("data", (chunk: Buffer) => chunks.push(chunk)); + req.on("end", () => { + bodies.push(Buffer.concat(chunks).toString("utf8")); + upstreamHandler(req, res, bodies); + }); + }); + upstream.listen(0, "127.0.0.1"); + await listen(upstream); + const upstreamPort = (upstream.address() as { port: number }).port; + + const opts: ProxyOptions = { + port: 0, + host: "127.0.0.1", + upstream: "http://127.0.0.1", + routes: { + [`http://127.0.0.1:${upstreamPort}`]: { models: { "gpt-drift-e2e": { context: 400_000 } } }, + }, + modelContextLimit: 400_000, + kernelConfig: defaultConfig(400_000), + compress: { injectTool: true, injectNudge: true }, + promptCache: { routing: "auto" }, + sessionHeader: "x-acp-session", + log: false, + debug: false, + passthrough: false, + autoUpdate: false, + mitm: { enabled: false, domains: [] }, + }; + const proxy = await startServer(opts); + await listen(proxy); + const proxyPort = (proxy.address() as { port: number }).port; + try { + await fn(`http://127.0.0.1:${proxyPort}/bili/http://127.0.0.1:${upstreamPort}/v1/responses`, `http://127.0.0.1:${proxyPort}/__bili/stats`, bodies); + } finally { + await close(proxy); + await close(upstream); + } +} + +test("e2e #1102: opencode AGENTS.md edit (instructions drift) keeps ONE session and carries compression state", async () => { + _setStoreForTest(new SessionStore({ enabled: false })); + _resetSessionsForTest(); + setRegistryForTest({}); + + const AFFINITY = "ses_drift_e2e"; + const INSTRUCTIONS_V1 = "You are OpenCode, the coding agent.\n\n# AGENTS.md\nBuild with npm."; + const INSTRUCTIONS_V2 = "You are OpenCode, the coding agent.\n\n# AGENTS.md\nBuild with npm.\nUse pnpm for scripts."; + const SEED_USER = "Kick off the working session."; + const SEED_ASSISTANT = "Understood, starting now."; + const TURN_1 = `DRIFT-FILLER-A ${"y".repeat(6000)}`; + const TURN_2 = "DRIFT-FILLER-B acknowledged"; + // kernel refs are per-session snapshots assigned in render order: + // m00001/m00002 = seed pair, m00003 = TURN_1, m00004 = TURN_2 + const REF_1 = "m00003"; + const REF_2 = "m00004"; + + await withProxy((req, res, bodies) => { + res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); + if (bodies.length === 1) { + const compressArgs = JSON.stringify({ + content: [{ startId: REF_1, endId: REF_2, topic: "session setup", summary: "DRIFT-SUMMARY-SETUP-CONTEXT-FOLDED-BY-COMPRESSION-LONG-ENOUGH-FOR-KERNEL-MIN-LENGTH-CHECK" }], + }); + res.write(fcEvents(0, "call_d", "compress", compressArgs)); + res.write(completed(1600)); + } else { + res.write(textEvents("post-edit answer")); + res.write(completed(1700)); + } + res.end(); + }, async (url, statsUrl, bodies) => { + // The seed pair precedes the compress target because the kernel's + // rebuildMessages pins the session's FIRST user message to the wire + // even when covered by an active block — targeting it would leave raw + // bytes on the wire and break the fold assertion below. Six medium + // turns AFTER the target keep m00003/m00004 outside the kernel's + // protected zone (last 5 messages AND last 5000 tokens), so the mock + // compress call actually executes and folds them. + const med = (i: number) => `Message ${i} of the working session. ` + `WORK_${i}_content_`.repeat(290); + const baseInput = [ + { type: "message", role: "user", content: SEED_USER }, + { type: "message", role: "assistant", content: SEED_ASSISTANT }, + { type: "message", role: "user", content: TURN_1 }, + { type: "message", role: "assistant", content: TURN_2 }, + { type: "message", role: "user", content: med(5) }, + { type: "message", role: "assistant", content: med(6) }, + { type: "message", role: "user", content: med(7) }, + { type: "message", role: "assistant", content: med(8) }, + { type: "message", role: "user", content: med(9) }, + { type: "message", role: "assistant", content: med(10) }, + ]; + const req1 = await fetch(url, { method: "POST", headers: { "content-type": "application/json", "x-session-affinity": AFFINITY }, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: INSTRUCTIONS_V1, input: baseInput }) }); + assert.equal(req1.status, 200); + await req1.text(); + assert.equal(bodies.length, 2, "original + post-compress re-request"); + + const userEditsAgentsMd = "AGENTS.md edited mid-session: use pnpm for scripts (TURN-MARKER-1102)"; + const req2 = await fetch(url, { method: "POST", headers: { "content-type": "application/json", "x-session-affinity": AFFINITY }, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: INSTRUCTIONS_V2, input: [...baseInput, { type: "message", role: "user", content: userEditsAgentsMd }] }) }); + assert.equal(req2.status, 200); + await req2.text(); + + assert.equal(bodies.length, 3); + assert.ok(!bodies[2].includes("DRIFT-FILLER-A"), "compressed state carried across the instructions drift — no orphan re-seeding"); + assert.ok(!bodies[2].includes("DRIFT-FILLER-B"), "both folded messages are off the wire after the drift"); + assert.ok(bodies[2].includes("DRIFT-SUMMARY-SETUP"), "the folded summary renders in place of the compressed range"); + assert.ok(bodies[2].includes(userEditsAgentsMd), "the new turn is forwarded"); + + const stats = await (await fetch(statsUrl)).json(); + assert.equal(stats.sessions.length, 1, "same logical conversation stays in ONE compression namespace despite instructions drift"); + assert.equal(stats.sessions[0].id, AFFINITY, "no |sub: fork"); + }); +}); + +test("e2e #1102: plugin-declared opencode session keeps ONE session across instructions drift", 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" }; + + await withProxy((_req, res) => { + res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" }); + res.write(textEvents("plugin lane answer")); + res.write(completed(800)); + res.end(); + }, async (url, statsUrl, bodies) => { + const input = [{ type: "message", role: "user", content: "initial turn" }]; + const req1 = await fetch(url, { method: "POST", headers, body: JSON.stringify({ model: "gpt-drift-e2e", stream: true, instructions: "persona v1", 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: "persona v1 with updated AGENTS.md section", 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, "plugin-declared persona-scoped id must not fork on instruction drift"); + assert.equal(stats.sessions[0].id, CONVERSATION); + }); +});