Skip to content
Merged
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
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ acp-kernel/
│ ├── rebuild.ts # Fork recovery + state rebuilding
│ ├── hide.ts # Hide compressed messages from visible context
│ ├── keep-markers.ts # KEEP/REF marker preservation in summaries
│ ├── ccr.ts # CCR: placeholder contract, storeLargeResults, retrieveByRef, applyRetrieve, ccrStoreNode
│ ├── content-store.ts # MessageContentStore — per-session content-addressed dedup store (per-ref append-only)
│ ├── prompts.ts # Prompts (4 load-bearing rules) + defaultPrompts + resolvePrompts
│ ├── compress-tools.ts # ACP tool schemas (3 wire shapes) + standing-prompt builders
│ ├── surface-config.ts # Surface-text overrides: applySectionOverrides, cloneWithDescriptions, applyAcpToolOverrides
Expand Down
17 changes: 14 additions & 3 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,20 +113,31 @@ type Config = {
interface CompressionCore {
// Per-turn node pipeline (replaces the message-transform hook's algorithm part).
// Runs every turn (canonical order): assign-refs → sync-blocks → merge-blocks →
// prune → filter → hide-compress-calls → nudge-inject → emergency-truncate →
// render-refs. Survives/promotes blocks via advanceSurvival (no age-based
// deactivation). Returns transformed messages + updated state + nudge decision.
// prune → ccr-store → filter → hide-compress-calls → nudge-inject →
// emergency-truncate → render-refs. Survives/promotes blocks via advanceSurvival
// (no age-based deactivation). Returns transformed messages + updated state +
// nudge decision + the (possibly grown) content store.
processTurn(input: {
messages: CoreMessage[];
state: CompressionState;
config: Config;
tokenCount: number;
/** Per-session CCR content store from the previous turn (optional; an
* empty store is created when omitted). */
contentStore?: MessageContentStore;
}): {
messages: CoreMessage[];
state: CompressionState;
nudge?: NudgeDecision;
/** Always present; pass back as input.contentStore next turn. */
contentStore: MessageContentStore;
};

// When the model calls acp_retrieve. Pure lookup over the host-provided store
// plus an ephemeral injection message (id prefix acp_retrieved_*) that consumes
// no ref and never enters fold space. Hallucinated refs → not-found ack.
retrieve(store: MessageContentStore, ref: string): ApplyRetrieveResult;

// When the model calls compress. `ranges[].summary` is model-produced text.
// Allocates block(s), deactivates consumed blocks, updates indices, resets the
// nudge growth baseline on success (§5.7 feedback-loop fix).
Expand Down
76 changes: 73 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,12 @@ const state = createInitialState();
const config = defaultConfig(200000); // modelContextLimit (positional); optional overrides as 2nd arg

// processTurn runs the canonical node pipeline every turn:
// assign-refs → sync-blocks → prune → absorb-hide → crush → absorb-prompt
// → filter → hide-compress-calls → recommend → nudge-inject
// assign-refs → sync-blocks → prune → ccr-store → absorb-hide → crush →
// absorb-prompt → filter → hide-compress-calls → recommend → nudge-inject
// → emergency-truncate → render-refs
const { messages, state: nextState, nudge } = core.processTurn({
const { messages, state: nextState, nudge, contentStore } = core.processTurn({
messages, state, config, tokenCount,
contentStore, // previous turn's content store (optional; see CCR below)
});

// When the model emits a compress decision (summary written by the model):
Expand Down Expand Up @@ -86,6 +87,74 @@ processTurn({ messages, state, config, tokenCount, renderTags: "none" });
`renderTags` is optional and defaults to `"all"`, so existing call sites keep
working unchanged.

#### CCR — content-cached retrieval (lossless tool-result offload)

CCR is the lossless alternative to absorb's lossy distillation. When enabled,
a tool result at or above `ccr.minToolTokens` is stored **once, at arrival** in
the per-session content store, and its visible copy is replaced with a
deterministic placeholder carrying enough signal (kind, size, command/head
preview, ref) to judge relevance without retrieving. The model pulls the
original back via the `acp_retrieve` tool; the retrieved text rides back as an
ephemeral trailing message that never consumes a ref and never enters the fold
space. Disabled by default — no behavior change unless opted in.

```ts
const config = defaultConfig(200000, { ccr: { enabled: true } }); // opt-in

// Turn N: pass the previous turn's store back in.
const { messages, state, contentStore } = core.processTurn({
messages, state, config, tokenCount,
contentStore, // persisted from turn N-1 (host owns persistence)
});

// When the model calls acp_retrieve({ ref }):
const hit = core.retrieve(contentStore, "m00042");
if (hit.ok) {
// hit.text — the original bytes
// hit.injection — trailing request-only message to append for this request
// hit.ackText — short tool-result ack string
} else {
// hit.ackText — not-found notice (hallucinated ref costs one tool call)
}
```

Placeholder wire shape (deterministic — same inputs always produce identical
bytes, so the visible text is byte-stable after arrival and prefix-cache
friendly):

```
📦 [acp-stored #m00423 · shell output · 4,213 tok] `npm run build`
→ acp_retrieve("m000423") returns the full text
```

Contract guarantees:

- **Replace-once-at-arrival.** The visible bytes change exactly once
(original → placeholder); every later turn sees identical bytes.
- **Tool-pair integrity.** Only the tool-result's own content shrinks; the
paired assistant `tool_calls` survive untouched (OpenAI-family wire pairing).
- **id-never-reused safe.** The store is per-ref append-only, first-write-wins,
and never reissues or recycles refs. Refs stay retrievable even if a host
prunes its own `messageRefs` map after compaction (e.g. billion-context
archive), because lookup happens against the store, not the ref map.
- **Ephemeral retrieval.** `acp_retrieved_*` messages are skipped by assign-refs
and excluded from block coverage — they consume no ref and enter no fold
space. Hosts may strip them after the request (nudge channel); if they
round-trip anyway, the kernel handles them safely.
- **Coexists with absorb.** Placeholder-marked results are never absorb
candidates (ID-reference wins); absorb keeps handling semantic distillation
of everything else.

Persistence: the store is plain JSON (`{ version: 1, byHash, byRef }`) — hosts
persist it alongside `CompressionState` (same StateStore envelope path as
blockContents). Content-addressed dedup means identical bytes are written once.
`core.status(...)` reports `breakdown.storedMessages` and
`breakdown.retrievals` so a host can measure retrieve rate.

For folded-range retention (v2 groundwork), hosts can call
`storeCoveredOriginals(store, messages, compressedState, [blockId], countTokens)`
right after `applyCompression` so pruned originals stay retrievable by ref.

**Token counts in rendered tags are snapshots.** Each message's
`<acp tokens="N">` attribute is frozen at the tag's first render (the
per-message `tokenSnapshot` in state) and is not recomputed when the message
Expand All @@ -103,6 +172,7 @@ live-recomputed tags, use `renderVisibleRefs` directly.
| `buildStatusReport` / `buildRecap` | Context-usage report + block recap |
| `mergeMarkedBlocks` / `collectOldGenBlocks` | Batch merge old-gen blocks into one summary |
| `rebuildCompressionState` | Fork-recovery: replay historical compress calls |
| `MessageContentStore` / `storeLargeResults` / `retrieveByRef` / `storeCoveredOriginals` | CCR content store: per-session, content-addressed dedup of tool-result originals + on-demand retrieval (see "CCR" above) |
| `applyMessageFilters` | Pluggable message-filter framework |
| `resolveTransformChannel` | Channel-selection policy: an explicit preference wins; the default is the wire channel only when the caller reports it viable |
| `applySectionOverrides` / `cloneWithDescriptions` / `applyAcpToolOverrides` | Prompt/tool *surface* customization (see below) |
Expand Down
6 changes: 5 additions & 1 deletion src/absorb.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { rawForRef, refForRaw, BLOCKED_REF } from "./refs.js";
import { ACP_TOOL_NAMES, ABSORB_TOOL_NAME } from "./compress-tools.js";
import { isStoredPlaceholderText } from "./ccr.js";
import {
collectLatestProtected,
isMessageLatestProtected,
Expand Down Expand Up @@ -31,7 +32,9 @@ export const ABSORB_PROMPT_MARKER = "[ACP absorb]";
export const DEFAULT_ABSORB_CONFIG: AbsorbConfig = {
enabled: false,
toolName: ABSORB_TOOL_NAME,
minToolTokens: 1000,
// Raised 1000 → 4000 (issue #352): lossless CCR takes over large-result
// handling; absorb's forced distillation only fires above the new bar.
minToolTokens: 4000,
contextThresholdPct: 0,
excludeTools: [],
};
Expand Down Expand Up @@ -86,6 +89,7 @@ export function isAbsorbCandidate(
latest?: LatestProtected,
): boolean {
if (msg.contentType !== "tool-result" || !msg.toolCallId) return false;
if (isStoredPlaceholderText(msg.text ?? "")) return false;
const cfg = resolveAbsorbConfig(config);
if (isAcpOrConfiguredTool(msg.toolName, cfg)) return false;
if (isMessageProtected(msg, config)) return false;
Expand Down
13 changes: 9 additions & 4 deletions src/boundaries.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { activeBlocks, blockById } from "./state.js";
import { isRenderedSummaryMessage, summaryMessageId } from "./prune.js";
import { isRetrievedMessage } from "./ccr.js";
import type {
CompressionBlock,
CompressionState,
Expand Down Expand Up @@ -118,10 +119,14 @@ export function resolveBoundaries(
const messageIds: string[] = [];
for (let index = startIndex; index <= endIndex; index++) {
const message = input.messages[index];
// Synthetic summary messages are transient view representations, not
// compressible content: exclude them so they never leak into a new
// block's effectiveMessageIds/directMessageIds.
if (message && !isRenderedSummaryMessage(message))
// Synthetic summary and retrieval-injection messages are transient view
// representations, not compressible content: exclude them so they never
// leak into a new block's effectiveMessageIds/directMessageIds.
if (
message &&
!isRenderedSummaryMessage(message) &&
!isRetrievedMessage(message)
)
messageIds.push(message.id);
}

Expand Down
Loading
Loading