Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ billion-context/
4. **Tee logger**: all proxy logs go through `src/logger.ts` (file + stderr). Do NOT use `console.error` in server-side modules — use `loggerLog()`.
5. **acp-kernel MUST be pinned to an exact version** (e.g. `"acp-kernel": "0.0.17"`, NEVER `"^0.0.17"`). Because acp-kernel is a build-time dependency that tsup bundles inline into `dist`, a caret range makes the resolved version drift if `package-lock.json` is regenerated or absent, breaking reproducible builds. When bumping acp-kernel: set the exact version in `package.json`, run `npm install` to refresh the lockfile, then rebuild. The `package-lock.json` is committed and kept in sync.
6. **Two compression modes with different summary carriers** — `pluginMode` (the `x-bili-plugin` header / registered agent, e.g. `bili pi`) means the ACP-native agent OWNS compression: it executes `compress` locally, the call+result live in its own re-sent history, and the summary carrier on the wire is the **tool call** (the proxy suppresses tool + nudge injection; the agent's view never renders the kernel's `acp_summary`). Proxy mode (plain client, no header) means the proxy executes `compress` server-side: the tool call is ephemeral (never enters the client's history) and preflight blocks have none, so the summary carrier is the **`acp_summary` message**, which the kernel renders as role `system` but `systemToUser` (`src/util.ts`) re-voices as a **`user` message** (leaving it at its anchor) so strict backends (SGLang: exactly one system at index 0, #377) accept it and the head system message stays byte-stable for the prefix cache. The mode is decided per request and bound per session (`session.metadata.pluginAgent`, sticky, upgrade-only). See README "Two compression modes".
7. **修复重启、切模型或失败重试时**:`plugin-conversations` 也包含普通缓存键映射,不能据此认定插件身份;保留旧映射的压缩状态,并以原始历史边界约束重算后的可压缩范围,回归入口是 `tests/subagent-namespace.test.ts` 和 `tests/preflight-fail-fast.test.ts`。

### Kernel Contract: Message Ids Are Never Reused

Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag

### Fixes

- **Compress failures are retryable in the same turn (#743)**: hosts (claude-code/openai/codex) pre-validate tool arguments against the served schema and reject a missing `content` CLIENT-side — the model only ever sees a bare `content: is required` and, observed in production, gives up instead of retrying, leaving the nudge pending forever. `content` is no longer schema-required on any served surface (the description now documents that validation happens at execution); a malformed call reaches the executor and gets the actionable `[Compression FAILED …]` receipt it can fix in the same loop. Failed compress call+result pairs are dropped from CLOSED turns before forwarding — a failed compress in history is dead weight once its turn has ended (the success that replaced it, or nothing, follows), and stale failure text under sustained pressure teaches the wrong lesson; current-turn pairs stay for in-place retry and successful compresses are never matched (they remain as plugin-mode block carriers). Tests in `tests/compress-retry.test.ts`; #349 and #841 pin the schema deltas.

- **Failed compress receipts name the live compressible span**: after a fold the model keeps anchoring on refs an earlier block already consumed — a live session (01a0b0c4) burned 28 minutes on three consecutive `[Compression FAILED]` receipts (already compressed → cannot be anchored → no valid ranges), wasted two full T1 checkpoints, then gave up and let the nudge re-fire every turn. The kernel errors say "run acp_status and retry", but recovery needs two more round-trips a mid-task model won't take. Both failure receipts (no valid ranges, zero blocks created) now append the concrete span that is still raw and directly compressible — `Live compressible refs: m05373–m05448 (everything up to m05372 is already inside active blocks). Retry NOW in this same turn` — computed as the highest mapped raw ref minus the newest active-block boundary; when no raw refs remain it falls back to suggesting a run of ACTIVE blocks. Tests in `tests/compress-retry.test.ts`.

- **Omp compression survives model switches and restored session mappings**: only an actual `omp` registration or persisted plugin ownership bypasses instruction-based subagent partitioning; a plain `prompt_cache_key` does not. Existing conversation mappings restore their original session and compression blocks instead of creating an empty bare-id session. Failed preflight freezes the original history boundary and recomputes remaining viable ranges after each fold, including soft-protected history when needed, without absorbing turns appended during the failure window.
- **Preflight no longer wedges on a stale usage baseline while the prepared payload fits (#739 follow-up)**: the preflight trigger floors on `session.stats.lastInputTokens`, and after an earlier as-is forward under preflight (#300) that measured baseline can stay pinned above the window — a live session kept a 257,613-token floor against a 256,000 window while its real prepared payload was ~127k. Every turn then re-ran the fold walk on ranges the payload no longer needed: three 60s non-stream summarization attempts (~3.4min stall), an upstream 500 → structured 502, a 5-minute dead-end cooldown, repeat. The trigger now forwards as-is when a known-baseline session's payload estimate fits yet its measured baseline sits above the window (#301: as-is is safe; the next usage report self-heals the baseline). Inside-window folding is untouched — the codex headroom target still walks fitting 90-100% payloads. `tests/preflight-fail-fast.test.ts` pins it: fitting payload + stale floor above the window → forwarded with zero summarization calls.
- **Claude Code subagent requests no longer queue behind the main turn's lock (#970)**: Claude Code stamps the SAME `x-claude-code-session-id` on every model request of a session — background subagents (Task tool) included — so main turn and all subagents landed on ONE session and serialized on `withSessionLock` (which covers prepare + forward + the whole streamed response). A slow subagent first token head-of-line-blocked the main turn (and vice versa) for the full upstream latency; observed live as 116-142s first-byte stalls when two subagents launched concurrently. Discrimination is two-signal, both verified against live Claude Code 2.1.274 traffic (`-p` mode, general-purpose AND custom agent types like Explore): (1) the request carries `x-claude-code-agent-id` and/or `x-claude-code-parent-agent-id` — the parent header alone is NOT reliable (`-p` general-purpose subagents send it, custom agent types do not; main turns carry agent-id only from their second request on); (2) the MAIN agent's system always contains a block starting with "You are Claude Code…" (interactive) or "You are an interactive agent…" (`-p`/SDK), while a subagent's system blocks are its agent definition ("This session is a background job…", "You are a file search specialist for…", …) — no stable positive marker exists across agent types, so the check is negative (none of the main prefixes may match). The anthropic identity branch derives `<id>|sub:<agent-id>` only when BOTH signals say subagent (`claudeSubagentAgentId`/`claudeSubagentSplit` in `src/session-id.ts`, mirroring the codex #316 / Responses `subagentNamespace` precedents): each subagent gets its own lock chain and its own compression state (a subagent is its own conversation — same isolation semantics as #150). Failure degrades in the safe direction: a future rewording of the main prompts only stops the split (back to serial), never mis-splits the main session. `anthropicIdentity` itself is NOT rewritten — `affinityToken`/`clientLabel` keep the raw value, so upstream prefix caches and the UI label stay continuous across main and subagent sessions. Two guards keep the plugin layer honest: a split session's first request cannot claim the ROOT's pending register (#317 mirror), and `recordPluginSession` keys a subagent session under its split id instead of the raw conversation value — the single-valued conversations map used to flip between main and subagent sessions on every interleaved request, breaking `/acp` lookups and MCP tool routing. Older Claude Code (no headers), other agents, and curl are untouched (no split, previous behavior). Opt out with `BILI_SUBAGENT_SPLIT=0` or `"subagentSplit": false` in the config file. Tests pin: two-signal discrimination across the captured system shapes, stable namespaces, session isolation with main-identity stability, a deterministic no-stall case (upstream gates the main stream 1200ms; the subagent's first byte must beat it by a wide margin — pre-fix it arrives after, reproduced at 1238ms), and the off-switch restoring single-session behavior. End-to-end verified against live traffic: two concurrent Task subagents through the proxy land on `…|sub:<agent-id>` sessions in the log and complete in parallel.

### Features
Expand Down
64 changes: 60 additions & 4 deletions src/compress-tool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,14 @@
import {
parseCompressArgs,
ABSORB_TOOL_OPENAI,
COMPRESS_TOOL,
COMPRESS_TOOL_OPENAI,
COMPRESS_TOOL_RESPONSES,
SEARCH_CONTEXT_TOOL,
SEARCH_CONTEXT_TOOL_OPENAI,
SEARCH_CONTEXT_TOOL_RESPONSES,
SEARCH_CONTEXT_TOOL_NAME,
COMPRESS_TOOL_NAME,
ACP_TOOLS_ANTHROPIC,
ACP_TOOLS_OPENAI,
ACP_TOOLS_RESPONSES,
Expand Down Expand Up @@ -102,10 +106,62 @@ export const BILI_SEARCH_CONTEXT_TOOL_RESPONSES = {
parameters: withConversationId(SEARCH_CONTEXT_TOOL_RESPONSES.parameters),
};

export const BILI_ACP_TOOLS_ANTHROPIC = ACP_TOOLS_ANTHROPIC.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL : t));
export const BILI_ACP_TOOLS_OPENAI = ACP_TOOLS_OPENAI.map((t) => (t.function.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_OPENAI : t));
export const BILI_ACP_TOOLS_RESPONSES = ACP_TOOLS_RESPONSES.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t));
export const BILI_ACP_READONLY_TOOLS_RESPONSES = ACP_READONLY_TOOLS_RESPONSES.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t));
// compress-retry: hosts pre-validate tool args against the served schema and
// reject a missing `content` CLIENT-side — the model only sees a bare
// "content: is required" and, observed in production, gives up instead of
// retrying. Softening `required` routes those calls to the executor, which
// answers with the actionable [Compression FAILED ...] receipt (src/stream.ts
// applyRanges) the model can fix in the same loop.
const COMPRESS_RETRY_NOTE =
"\n\n[NOTE: `content` is validated when the call EXECUTES, not by the schema. An omitted or invalid `content` returns a retry error and compresses NOTHING — re-issue the call with content: [{startId, endId, summary}].]";

function withoutRequiredContent(schema: JsonSchemaObject): JsonSchemaObject {
return { ...schema, required: (schema.required ?? []).filter((n) => n !== "content") };
}

export const BILI_COMPRESS_TOOL = {
...COMPRESS_TOOL,
description: COMPRESS_TOOL.description + COMPRESS_RETRY_NOTE,
input_schema: withoutRequiredContent(COMPRESS_TOOL.input_schema),
};

export const BILI_COMPRESS_TOOL_OPENAI = {
...COMPRESS_TOOL_OPENAI,
function: {
...COMPRESS_TOOL_OPENAI.function,
description: COMPRESS_TOOL_OPENAI.function.description + COMPRESS_RETRY_NOTE,
parameters: withoutRequiredContent(COMPRESS_TOOL_OPENAI.function.parameters),
},
};

export const BILI_COMPRESS_TOOL_RESPONSES = {
...COMPRESS_TOOL_RESPONSES,
description: COMPRESS_TOOL_RESPONSES.description + COMPRESS_RETRY_NOTE,
parameters: withoutRequiredContent(COMPRESS_TOOL_RESPONSES.parameters),
};

function replaceTool<T extends { name: string }>(toolList: T[], name: string, replacement: T): T[] {
return toolList.map((t) => (t.name === name ? replacement : t));
}

export const BILI_ACP_TOOLS_ANTHROPIC = replaceTool(
ACP_TOOLS_ANTHROPIC.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL : t)),
COMPRESS_TOOL_NAME,
BILI_COMPRESS_TOOL,
);
export const BILI_ACP_TOOLS_OPENAI = ACP_TOOLS_OPENAI
.map((t) => (t.function.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_OPENAI : t))
.map((t) => (t.function.name === COMPRESS_TOOL_NAME ? BILI_COMPRESS_TOOL_OPENAI : t));
export const BILI_ACP_TOOLS_RESPONSES = replaceTool(
ACP_TOOLS_RESPONSES.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t)),
COMPRESS_TOOL_NAME,
BILI_COMPRESS_TOOL_RESPONSES,
);
export const BILI_ACP_READONLY_TOOLS_RESPONSES = replaceTool(
ACP_READONLY_TOOLS_RESPONSES.map((t) => (t.name === SEARCH_CONTEXT_TOOL_NAME ? BILI_SEARCH_CONTEXT_TOOL_RESPONSES : t)),
COMPRESS_TOOL_NAME,
BILI_COMPRESS_TOOL_RESPONSES,
);

// The kernel ships no Responses-format absorb const (the four ACP tools have
// *_RESPONSES variants; absorb is host-registered opt-in). Synthesize it in
Expand Down
12 changes: 11 additions & 1 deletion src/plugin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
import type { ServerResponse } from "node:http";
import fs from "node:fs";
import path from "node:path";
import { acquireInFlight, effectiveConfig, findSessionByCanonicalId, listSessions, markCompactionBoundary, markDirty, peekSession, releaseInFlight, withSessionLock, type Session } from "./session.js";
import { acquireInFlight, effectiveConfig, findSessionByCanonicalId, getSession, listSessions, markCompactionBoundary, markDirty, peekSession, releaseInFlight, withSessionLock, type Session } from "./session.js";
import { ABSORB_TOOL, ABSORB_TOOL_NAME, ABSORB_TOOL_OPENAI, ABSORB_TOOL_RESPONSES, BILI_ACP_TOOLS_ANTHROPIC, BILI_ACP_TOOLS_OPENAI, BILI_ACP_TOOLS_RESPONSES, PROXY_TOOL_NAMES, SEARCH_CONTEXT_CONVERSATION_ID_PARAM, SEARCH_CONTEXT_TOOL_NAME } from "./compress-tool.js";
import { effectiveAbsorbConfig, isProxyToolFor } from "./absorb.js";
import { executeProxyTool } from "./loop/core.js";
Expand Down Expand Up @@ -240,6 +240,16 @@ export function recordPluginSession(conversationId: string, sessionId: string):
scheduleSaveConversations();
}

/** Omp assigns each subagent its own UUID; a plain prompt_cache_key does not.
* Reuse the mapped session, including an existing |sub: namespace, rather
* than creating an empty bare-id session when the model changes. */
export function registeredPluginSessionId(conversationId: string): string | undefined {
const mappedId = conversations.get(conversationId)?.sessionId;
const mapped = mappedId ? getSession(mappedId) : undefined;
const agent = registeredIds.get(conversationId) ?? mapped?.metadata.pluginAgent;
return agent === "omp" ? mappedId ?? conversationId : undefined;
}

/** Keep the last prepare()'s view for a plugin session so tool-API execution
* sees the exact refs the model was shown (mirrors the wire-mode loop, which
* runs executeProxyTool against prepared.processedMessages). */
Expand Down
Loading