billion-context-dsh 0.1.0

package/dist/index.js

@@ -0,0 +1,724 @@
+// src/index.ts
+import {
+  CompactionEngine,
+  ManualCompactionError
+} from "@deepseek-ai/dsh-compaction";
+import { createCore } from "acp-kernel";
+
+// src/state.ts
+import { createInitialState } from "acp-kernel";
+var AcpStateStore = class {
+  states = /* @__PURE__ */ new Map();
+  /** Kernel state for one session, initialised on first access. */
+  stateFor(session) {
+    const id = session.id;
+    const existing = this.states.get(id);
+    if (existing !== void 0) return existing;
+    const state = createInitialState();
+    this.states.set(id, state);
+    return state;
+  }
+  set(session, state) {
+    this.states.set(session.id, state);
+  }
+  delete(session) {
+    this.states.delete(session.id);
+  }
+};
+
+// src/tools.ts
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { estimateTokensFast } from "acp-kernel";
+
+// src/config.ts
+import { defaultConfig } from "acp-kernel";
+function kernelConfigFor(input) {
+  const nudgePatch = {};
+  if (input.nudgeMinContextLimitPct !== void 0) nudgePatch.minContextLimitPct = input.nudgeMinContextLimitPct;
+  if (input.nudgeMaxContextLimitPct !== void 0) nudgePatch.maxContextLimitPct = input.nudgeMaxContextLimitPct;
+  if (input.nudgeEmergencyThresholdPct !== void 0) nudgePatch.emergencyThresholdPct = input.nudgeEmergencyThresholdPct;
+  const overrides = { ...input.coreOverrides };
+  if (Object.keys(nudgePatch).length > 0) {
+    overrides.nudge = { ...defaultConfig(input.modelContextLimit).nudge, ...nudgePatch };
+  }
+  return defaultConfig(input.modelContextLimit, overrides);
+}
+
+// src/region.ts
+import { randomUUID } from "crypto";
+import {
+  CompactionId,
+  compactCheckpointSource,
+  toolPairingBalancedAfter,
+  toolPairingBalancedBefore
+} from "@deepseek-ai/dsh-compaction";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+
+// src/messages.ts
+function extractText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const block of content) {
+    if (block === null || typeof block !== "object") continue;
+    const b = block;
+    if (b.type === "text" && typeof b.text === "string") {
+      parts.push(b.text);
+    } else if (Array.isArray(b.content)) {
+      parts.push(extractText(b.content));
+    }
+  }
+  return parts.join("\n");
+}
+function toolCallsOf(content) {
+  if (!Array.isArray(content)) return [];
+  return content.filter((b) => b.type === "tool-call");
+}
+function stringifyArgs(args) {
+  if (!args) return "";
+  if (typeof args === "string") return args;
+  try {
+    return JSON.stringify(args);
+  } catch {
+    return String(args);
+  }
+}
+function projectEvent(event) {
+  switch (event.type) {
+    case "user/message": {
+      const text = extractText(event.data.content);
+      return text.length > 0 ? [{ id: String(event.seq), role: "user", contentType: "text", text }] : [];
+    }
+    case "assistant/message": {
+      const content = event.data.message?.content;
+      const calls = toolCallsOf(content);
+      const text = extractText(content);
+      if (calls.length === 0) {
+        return text.trim().length > 0 ? [{ id: String(event.seq), role: "assistant", contentType: "text", text }] : [];
+      }
+      if (calls.length === 1) {
+        const call = calls[0];
+        const argStr = stringifyArgs(call.arguments);
+        const body = argStr && text ? `${text}
+${argStr}` : argStr || text;
+        return [{
+          id: String(event.seq),
+          role: "assistant",
+          contentType: "tool-call",
+          toolName: call.name ?? "",
+          toolCallId: call.id ?? "",
+          text: body
+        }];
+      }
+      return calls.map((call) => ({
+        id: `${event.seq}#${call.id ?? ""}`,
+        role: "assistant",
+        contentType: "tool-call",
+        toolName: call.name ?? "",
+        toolCallId: call.id ?? "",
+        text: stringifyArgs(call.arguments) || text
+      }));
+    }
+    case "tool/result": {
+      const message = event.data.message;
+      const text = extractText(message?.content);
+      if (text.length === 0) return [];
+      return [{
+        id: String(event.seq),
+        role: "tool",
+        contentType: "tool-result",
+        toolName: message?.toolName ?? "",
+        toolCallId: message?.toolCallId ?? "",
+        text
+      }];
+    }
+    default:
+      return [];
+  }
+}
+function eventsToCoreMessages(events) {
+  const out = [];
+  for (const event of events) out.push(...projectEvent(event));
+  return out;
+}
+function surfaceEventsOf(session) {
+  return session.surface.nodes.map((seq) => session.events[seq]).filter((event) => event !== void 0);
+}
+function extractEventText(event) {
+  switch (event.type) {
+    case "user/message":
+      return extractText(event.data.content);
+    case "assistant/message":
+      return extractText(event.data.message?.content);
+    case "tool/result":
+      return extractText(event.data.message?.content);
+    default:
+      return "";
+  }
+}
+
+// src/region.ts
+function findOpenTurn(events) {
+  let open = null;
+  for (const event of events) {
+    if (event.type === "turn/start") open = event.data.turn;
+    else if (event.type === "turn/end" && event.data.turn === open) open = null;
+  }
+  return open;
+}
+function assertNoActiveCompaction(events) {
+  let active = false;
+  for (const event of events) {
+    if (event.type === "compaction/start") active = true;
+    else if (event.type === "compaction/end") active = false;
+  }
+  if (active) {
+    throw new Error("billion-context-dsh: another compaction is already active for this session");
+  }
+}
+function resolveSurfaceRange(session, start, end) {
+  const nodes = session.surface.nodes;
+  let startIdx = nodes.indexOf(start);
+  let endIdx = nodes.indexOf(end);
+  if (startIdx < 0 || endIdx < 0) {
+    throw new Error(`billion-context-dsh: seq ${start}..${end} not in the current surface`);
+  }
+  if (startIdx > endIdx) {
+    throw new Error(`billion-context-dsh: reversed range ${start}..${end}`);
+  }
+  while (startIdx <= endIdx && !toolPairingBalancedBefore(session, nodes[startIdx])) {
+    startIdx += 1;
+  }
+  while (endIdx >= startIdx && !toolPairingBalancedAfter(session, nodes[endIdx])) {
+    endIdx -= 1;
+  }
+  if (startIdx > endIdx) {
+    throw new Error(
+      `billion-context-dsh: no tool-pairing-balanced range inside seq ${start}..${end} \u2014 narrow the range or consult acp_status for the current surface`
+    );
+  }
+  return { start: nodes[startIdx], end: nodes[endIdx] };
+}
+function shadowedSeqsOf(session, start, end) {
+  const nodes = session.surface.nodes;
+  const startIdx = nodes.indexOf(start);
+  const endIdx = nodes.indexOf(end);
+  return nodes.slice(startIdx, endIdx + 1);
+}
+function runCompactionTransaction(session, input) {
+  assertNoActiveCompaction(session.events);
+  const turn = findOpenTurn(session.events);
+  const compactionId = CompactionId(randomUUID());
+  const seqs = [];
+  seqs.push(session.append("compaction/start", { compactionId, turn }).seq);
+  seqs.push(session.append("compaction/summary", {
+    compactionId,
+    summary: input.summary,
+    shadowedRange: { start: input.start, end: input.end },
+    shadowedSeqs: [...input.shadowedSeqs],
+    shadowedTokenCount: input.shadowedTokenCount,
+    provider: input.provider,
+    model: input.model
+  }).seq);
+  const message = createUserMessage({
+    content: input.summary,
+    source: compactCheckpointSource(compactionId)
+  });
+  seqs.push(session.append("user/message", message, {
+    surfaceOp: { op: "replace", start: input.start, end: input.end },
+    sourceEventSeqs: [...input.shadowedSeqs]
+  }).seq);
+  seqs.push(session.append("compaction/end", { compactionId, turn }).seq);
+  return { compactionId, seqs };
+}
+function rebuildBlockLedger(events) {
+  const ledger = [];
+  for (const event of events) {
+    if (event.type !== "compaction/summary") continue;
+    const data = event.data;
+    ledger.push({
+      blockId: data.compactionId,
+      summary: extractText(data.summary),
+      shadowedSeqs: [...data.shadowedSeqs],
+      shadowedTokenCount: data.shadowedTokenCount,
+      start: data.shadowedRange.start,
+      end: data.shadowedRange.end
+    });
+  }
+  return ledger;
+}
+
+// src/tools.ts
+function textOutput() {
+  return {
+    schema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      additionalProperties: false
+    },
+    render: (_args, value) => [{ type: "text", text: value.text }]
+  };
+}
+function requireAgent(exec) {
+  if (exec.agent === void 0) {
+    throw new Error("billion-context-dsh: tool requires an agent execution context");
+  }
+  return exec.agent;
+}
+var compressParameters = {
+  topic: { type: "string", description: "Fallback topic for entries without their own." },
+  content: {
+    type: "array",
+    required: true,
+    description: "One or more ranges to compress, each with startSeq/endSeq boundaries (surface seqs) and a dense summary.",
+    items: {
+      type: "object",
+      properties: {
+        startSeq: {
+          oneOf: [
+            { type: "integer", description: "First surface seq of the range." },
+            { type: "string", description: "Seq as text; a trailing #callId fragment is ignored." }
+          ]
+        },
+        endSeq: {
+          oneOf: [
+            { type: "integer", description: "Inclusive last surface seq of the range." },
+            { type: "string", description: "Seq as text; a trailing #callId fragment is ignored." }
+          ]
+        },
+        summary: { type: "string", description: "Complete technical summary replacing the range; keep paths, decisions, values verbatim. Minimum 50 characters." },
+        topic: { type: "string", description: "Short label (3-5 words) for this range." }
+      },
+      additionalProperties: false
+    }
+  }
+};
+function parseSeq(value) {
+  const text = String(value).split("#")[0].trim();
+  const seq = Number(text);
+  if (!Number.isInteger(seq) || seq < 0) {
+    throw new Error(`billion-context-dsh: invalid seq "${String(value)}" \u2014 use a surface seq like 295`);
+  }
+  return seq;
+}
+async function handleCompress(env, args, exec) {
+  const agent = requireAgent(exec);
+  const session = agent.session;
+  const state = env.store.stateFor(session);
+  const coreMessages = eventsToCoreMessages(surfaceEventsOf(session));
+  const tokenCount = coreMessages.reduce((sum, message) => sum + estimateTokensFast(message.text ?? ""), 0);
+  const config = kernelConfigFor(env);
+  const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount });
+  env.store.set(session, turn.state);
+  const byRaw = turn.state.messageRefs.byRaw;
+  const ranges = args.content.map((range) => {
+    const startSeq = parseSeq(range.startSeq);
+    const endSeq = parseSeq(range.endSeq);
+    const startRef = byRaw[String(startSeq)];
+    const endRef = byRaw[String(endSeq)];
+    if (startRef === void 0 || endRef === void 0) {
+      throw new Error(
+        `billion-context-dsh: seq ${startSeq}..${endSeq} has no assigned ref \u2014 the range must be on the current surface (run acp_status for the live seq list)`
+      );
+    }
+    return {
+      startSeq,
+      endSeq,
+      startRef,
+      endRef,
+      summary: range.summary,
+      ...(range.topic ?? args.topic) === void 0 ? {} : { topic: range.topic ?? args.topic }
+    };
+  });
+  const applied = env.kernel.applyCompression({
+    ranges: ranges.map(({ startRef, endRef, summary, topic }) => ({ startRef, endRef, summary, topic })),
+    messages: coreMessages,
+    state: turn.state,
+    config
+  });
+  if (applied.result.errors.length > 0) {
+    return { text: `compress failed: ${applied.result.errors.join("; ")}` };
+  }
+  env.store.set(session, applied.state);
+  const lines = [];
+  for (let index = 0; index < ranges.length; index += 1) {
+    const range = ranges[index];
+    const original = args.content[index];
+    const { start, end } = resolveSurfaceRange(session, range.startSeq, range.endSeq);
+    const shadowed = shadowedSeqsOf(session, start, end);
+    const { compactionId } = runCompactionTransaction(session, {
+      start,
+      end,
+      shadowedSeqs: shadowed,
+      summary: [{ type: "text", text: original.summary }],
+      shadowedTokenCount: 0,
+      provider: agent.options.provider ?? "",
+      model: agent.options.model ?? ""
+    });
+    const adjusted = start !== range.startSeq || end !== range.endSeq;
+    lines.push(
+      `  block ${compactionId.slice(0, 8)}: seqs ${start}..${end}, ${shadowed.length} messages shadowed` + (adjusted ? ` (adjusted from ${range.startSeq}..${range.endSeq} to balanced edges)` : "")
+    );
+  }
+  return {
+    text: `Compressed ${applied.result.blocksCreated} block(s), ~${applied.result.tokensCompressed} tokens reclaimed.
+${lines.join("\n")}`
+  };
+}
+var decompressParameters = {
+  blockId: { type: "string", required: true, description: "Block id from acp_status or search_context (the compaction id)." }
+};
+function handleDecompress(_env, args, exec) {
+  const session = requireAgent(exec).session;
+  const ledger = rebuildBlockLedger(session.events);
+  const block = ledger.find((entry) => entry.blockId.startsWith(args.blockId));
+  if (block === void 0) {
+    return { text: `decompress: block "${args.blockId}" not found (see acp_status for the block list)` };
+  }
+  const parts = [];
+  for (const seq of block.shadowedSeqs) {
+    const event = session.events[seq];
+    const text = event === void 0 ? "" : extractEventText(event);
+    if (text.length > 0) parts.push(`[seq ${seq}] ${text}`);
+  }
+  return {
+    text: `Block ${block.blockId} \u2014 ${block.summary}
+
+${parts.join("\n\n") || "(no recoverable content)"}`
+  };
+}
+var searchParameters = {
+  query: { type: "string", required: true, description: "Search terms to find inside compressed blocks." },
+  limit: { type: "integer", description: "Maximum results (default 5)." }
+};
+function handleSearch(_env, args, exec) {
+  const session = requireAgent(exec).session;
+  const ledger = rebuildBlockLedger(session.events);
+  const terms = args.query.toLowerCase().split(/\s+/).filter(Boolean);
+  const scored = [];
+  for (const block of ledger) {
+    const original = block.shadowedSeqs.map((seq) => extractEventText(session.events[seq])).join("\n");
+    const haystack = `${block.summary}
+${original}`.toLowerCase();
+    let score = 0;
+    for (const term of terms) score += haystack.split(term).length - 1;
+    if (score > 0) scored.push({ blockId: block.blockId, score, summary: block.summary });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.slice(0, args.limit ?? 5);
+  if (top.length === 0) return { text: `search_context: no matches for "${args.query}"` };
+  return {
+    text: `Matches for "${args.query}":
+` + top.map((hit) => `  - ${hit.blockId} (score ${hit.score}): ${hit.summary.slice(0, 160)}`).join("\n") + "\n\nDecompress with: decompress({ blockId })"
+  };
+}
+var statusParameters = {};
+function handleStatus(env, _args, exec) {
+  const session = requireAgent(exec).session;
+  const ledger = rebuildBlockLedger(session.events);
+  const totalTokens = ledger.reduce((sum, block) => sum + block.shadowedTokenCount, 0);
+  const coreMessages = eventsToCoreMessages(surfaceEventsOf(session));
+  const estimated = coreMessages.reduce((sum, message) => sum + estimateTokensFast(message.text ?? ""), 0);
+  const limit = env.modelContextLimit;
+  const lines = [
+    `ACP status \u2014 session ${session.id}`,
+    `  blocks: ${ledger.length}`,
+    `  tokens compressed: ${totalTokens}`,
+    `  estimated context: ${estimated} / ${limit} (${Math.round(estimated / limit * 100)}%)`
+  ];
+  for (const block of ledger.slice(0, 10)) {
+    lines.push(`  - ${block.blockId.slice(0, 8)}: seqs ${block.start}..${block.end} (${block.shadowedSeqs.length} msgs) \u2014 ${block.summary.slice(0, 80)}`);
+  }
+  return { text: lines.join("\n") };
+}
+function makeTools(env) {
+  return [
+    defineTool({
+      name: "compress",
+      description: "Replace older conversation ranges with dense summaries you write. Each message seq is a surface reference. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated ranges in one call. Never compress content the current step is actively using.",
+      parameters: compressParameters,
+      output: textOutput(),
+      async execute(args, exec) {
+        return handleCompress(env, args, exec);
+      }
+    }),
+    defineTool({
+      name: "decompress",
+      description: "Recover the original content of a compressed block by its blockId (read-only; does not unshadow the range).",
+      parameters: decompressParameters,
+      output: textOutput(),
+      execute(args, exec) {
+        return Promise.resolve(handleDecompress(env, args, exec));
+      }
+    }),
+    defineTool({
+      name: "search_context",
+      description: "Search inside compressed blocks (summaries and original content) for information the model no longer sees in context.",
+      parameters: searchParameters,
+      output: textOutput(),
+      execute(args, exec) {
+        return Promise.resolve(handleSearch(env, args, exec));
+      }
+    }),
+    defineTool({
+      name: "acp_status",
+      description: "Report the ACP block ledger: compressed blocks, reclaimed tokens, and current context pressure.",
+      parameters: statusParameters,
+      output: textOutput(),
+      execute(args, exec) {
+        return Promise.resolve(handleStatus(env, args, exec));
+      }
+    })
+  ];
+}
+
+// src/commands.ts
+import { estimateTokensFast as estimateTokensFast2 } from "acp-kernel";
+function statusText(env, agent) {
+  const session = agent.session;
+  const ledger = rebuildBlockLedger(session.events);
+  const totalTokens = ledger.reduce((sum, block) => sum + block.shadowedTokenCount, 0);
+  const coreMessages = eventsToCoreMessages(surfaceEventsOf(session));
+  const estimated = coreMessages.reduce((sum, message) => sum + estimateTokensFast2(message.text ?? ""), 0);
+  const limit = env.modelContextLimit;
+  const lines = [
+    `ACP status \u2014 session ${session.id}`,
+    `  blocks: ${ledger.length}`,
+    `  tokens compressed: ${totalTokens}`,
+    `  estimated context: ${estimated} / ${limit} (${Math.round(estimated / limit * 100)}%)`
+  ];
+  for (const block of ledger.slice(0, 10)) {
+    lines.push(`  - ${block.blockId.slice(0, 8)}: seqs ${block.start}..${block.end} \u2014 ${block.summary.slice(0, 80)}`);
+  }
+  return lines.join("\n");
+}
+function compressText(env, agent, args) {
+  if (args.length < 3) {
+    return "/acp compress <startSeq> <endSeq> <summary...>";
+  }
+  const startSeq = Number(args[0]);
+  const endSeq = Number(args[1]);
+  const summary = args.slice(2).join(" ");
+  if (!Number.isInteger(startSeq) || !Number.isInteger(endSeq)) {
+    return "/acp compress: startSeq and endSeq must be integers";
+  }
+  const session = agent.session;
+  const { start, end } = resolveSurfaceRange(session, startSeq, endSeq);
+  const shadowed = shadowedSeqsOf(session, startSeq, endSeq);
+  const { compactionId } = runCompactionTransaction(session, {
+    start,
+    end,
+    shadowedSeqs: shadowed,
+    summary: [{ type: "text", text: summary }],
+    shadowedTokenCount: 0,
+    provider: agent.options.provider ?? "",
+    model: agent.options.model ?? ""
+  });
+  return `Compressed seqs ${start}..${end} (${shadowed.length} messages) as block ${compactionId.slice(0, 8)}`;
+}
+function decompressText(_env, agent, args) {
+  if (args.length < 1) return "/acp decompress <blockId>";
+  const session = agent.session;
+  const ledger = rebuildBlockLedger(session.events);
+  const block = ledger.find((entry) => entry.blockId.startsWith(args[0]));
+  if (block === void 0) return `block "${args[0]}" not found (see /acp status)`;
+  const parts = block.shadowedSeqs.map((seq) => extractEventText(session.events[seq])).filter((text) => text.length > 0);
+  return `Block ${block.blockId} \u2014 ${block.summary}
+
+${parts.join("\n\n") || "(no recoverable content)"}`;
+}
+function acpCommand(env) {
+  return {
+    name: "acp",
+    description: "Active Context Pruning \u2014 model-driven context compression. Usage: /acp status | /acp compress <startSeq> <endSeq> <summary> | /acp decompress <blockId>",
+    handler: async (invocation) => {
+      const raw = invocation.rawInput.trim();
+      if (raw === "" || raw === "status") {
+        return { kind: "success", text: statusText(env, invocation.agent) };
+      }
+      if (raw.startsWith("compress")) {
+        return { kind: "success", text: compressText(env, invocation.agent, raw.slice("compress".length).trim().split(/\s+/)) };
+      }
+      if (raw.startsWith("decompress")) {
+        return { kind: "success", text: decompressText(env, invocation.agent, raw.slice("decompress".length).trim().split(/\s+/)) };
+      }
+      return { kind: "error", text: `unknown /acp subcommand "${raw.split(/\s+/)[0]}" \u2014 use status | compress | decompress` };
+    }
+  };
+}
+
+// src/nudge.ts
+import {
+  estimateTokensFast as estimateTokensFast3
+} from "acp-kernel";
+import { createUserMessage as createUserMessage2 } from "@deepseek-ai/dsh-llm";
+function rangeTable(nudge, state) {
+  const byRef = state.messageRefs.byRef;
+  const lines = nudge.compressibleRanges.slice(0, 6).map((range) => {
+    const startRaw = byRef[range.startRef];
+    const endRaw = byRef[range.endRef];
+    if (startRaw === void 0 || endRaw === void 0) return null;
+    return `  - seq ${startRaw}..${endRaw} \u2014 ${range.count} messages, ~${range.tokens} tokens`;
+  });
+  const visible = lines.filter((line) => line !== null);
+  if (visible.length === 0) return "";
+  return [
+    "",
+    "Compressible ranges (refs are surface seqs):",
+    ...visible,
+    "Compress with: compress({ content: [{ startSeq, endSeq, summary }] })"
+  ].join("\n");
+}
+function buildNudge(agent, env, lastNudgeTurn) {
+  const session = agent.session;
+  const state = env.store.stateFor(session);
+  const coreMessages = eventsToCoreMessages(surfaceEventsOf(session));
+  const tokenCount = coreMessages.reduce((sum, message2) => sum + estimateTokensFast3(message2.text ?? ""), 0);
+  const config = kernelConfigFor(env);
+  const turn = env.kernel.processTurn({ messages: coreMessages, state, config, tokenCount });
+  env.store.set(session, turn.state);
+  const nudge = turn.nudge;
+  if (nudge === void 0 || !nudge.shouldInject) return null;
+  const emergency = nudge.breakdown?.emergencyOverride === 1;
+  const turnNumber = findOpenTurn(session.events) ?? 0;
+  const alreadyShown = !emergency && lastNudgeTurn.get(session.id) === turnNumber;
+  if (alreadyShown) return null;
+  lastNudgeTurn.set(session.id, turnNumber);
+  const text = buildNudgeText(nudge, emergency, turn.state);
+  const message = createUserMessage2({
+    content: [{ type: "text", text }],
+    source: { kind: "plugin", plugin: "acp-nudge" }
+  });
+  return { message, emergency };
+}
+function buildNudgeText(nudge, emergency, state) {
+  const pct = Math.round(nudge.contextUsage * 100);
+  const frame = emergency ? `\u26A0\uFE0F Context usage is at ${pct}% of the window \u2014 nearly full. Consider compressing consumed ranges soon so working context stays available; the choice and timing are yours.` : `Context usage is at ${pct}%. This is a suggestion, not a requirement \u2014 you decide whether and when to compress.`;
+  const guidance = "Compress by need, not by percentage: replace only ranges you have genuinely consumed, with dense self-contained summaries.";
+  return [frame, "", guidance, rangeTable(nudge, state)].join("\n");
+}
+
+// src/system-prompt.ts
+import { COMPRESS_PHILOSOPHY } from "acp-kernel";
+var ACP_SYSTEM_PROMPT = `Active Context Pruning \u2014 model-driven context management
+
+YOU decide whether and when to compress context. Nothing forces you: the injected "nudge" is a suggestion, not an order, and you may ignore it when compression would not help. Compress only ranges you have genuinely consumed (read tool outputs, finished explorations, superseded steps) that the current work no longer needs verbatim.
+
+${COMPRESS_PHILOSOPHY}
+
+Compression tools (refs are SURFACE SEQS, not ids):
+- compress: replace a seq range with your dense self-contained summary. compress({ content: [{ startSeq, endSeq, summary }] }). Edges are auto-balanced to tool-call/result boundaries; a trailing #callId fragment in a seq is ignored. Ranges must be on the current surface \u2014 stale seqs fail with guidance.
+- decompress: recover a compressed block's original content, read-only. decompress({ blockId }).
+- search_context: find information inside compressed blocks BEFORE decompressing. search_context({ query }).
+- acp_status: current context usage and the live compressible-range list. Run it before compressing when in doubt.
+
+When you write a summary, it becomes the ONLY record of that range: keep file paths, signatures, exact values, decisions, and error strings verbatim so a later reader (or you, after decompress) can continue without the original. Never reuse historical seqs \u2014 the surface moves as messages land and compress; verify with acp_status.`;
+var ACP_SYSTEM_PROMPT_ORDER = 150;
+
+// src/index.ts
+var DEFAULT_CONFIG = {
+  modelContextLimit: 128e3,
+  autoTools: true,
+  autoCommand: true,
+  autoNudge: true
+};
+function resolveAcpConfig(config = {}) {
+  return { ...DEFAULT_CONFIG, ...config };
+}
+var AcpCompactionEngine = class extends CompactionEngine {
+  /** The framework-agnostic ACP compression core, reused verbatim. */
+  kernel;
+  /** Per-session kernel state. */
+  store;
+  /** Resolved engine configuration. */
+  config;
+  lastNudgeTurn = /* @__PURE__ */ new Map();
+  constructor(ctx, config = {}) {
+    super(ctx);
+    this.config = resolveAcpConfig(config);
+    this.kernel = createCore({});
+    this.store = new AcpStateStore();
+    const env = {
+      kernel: this.kernel,
+      store: this.store,
+      modelContextLimit: this.config.modelContextLimit,
+      nudgeMinContextLimitPct: this.config.nudgeMinContextLimitPct,
+      nudgeMaxContextLimitPct: this.config.nudgeMaxContextLimitPct,
+      nudgeEmergencyThresholdPct: this.config.nudgeEmergencyThresholdPct,
+      coreOverrides: this.config.coreOverrides
+    };
+    if (this.config.autoTools) {
+      const tools = ctx.get("tools");
+      if (tools !== void 0) {
+        for (const tool of makeTools(env)) tools.register(tool);
+      }
+    }
+    if (this.config.autoCommand) {
+      const commands = ctx.get("commands");
+      if (commands !== void 0) commands.register(acpCommand(env));
+    }
+    if (this.config.autoNudge) {
+      ctx.on("agent/pre-step", async (payload, next) => {
+        const decision = await next();
+        if (decision.kind === "reject") return decision;
+        const outcome = buildNudge(payload.agent, env, this.lastNudgeTurn);
+        if (outcome === null) return decision;
+        return { kind: "enter", messages: [...decision.messages, outcome.message] };
+      });
+    }
+    const systemPrompt = ctx.get("systemPrompt");
+    if (systemPrompt !== void 0) {
+      systemPrompt.section({
+        name: "billion-context-dsh",
+        order: ACP_SYSTEM_PROMPT_ORDER,
+        text: ACP_SYSTEM_PROMPT
+      });
+    }
+  }
+  /** ACP is model-driven: automatic pressure policy never summarizes by itself. */
+  async compactIfNeeded(_agent, _trigger, signal) {
+    signal.throwIfAborted();
+    return null;
+  }
+  /** Explicit idle-session compaction: ACP leaves the decision to the model. */
+  async compactNow(_agent, signal) {
+    signal.throwIfAborted();
+    return null;
+  }
+  /**
+   * The model-driven path lands through the `compress` tool, which runs the
+   * full durable transaction directly. This seam method rejects with guidance:
+   * automatic summarization is exactly what ACP replaces.
+   */
+  async compactRegion(_start, _end, _agent, signal) {
+    signal?.throwIfAborted();
+    throw new ManualCompactionError(
+      "summary",
+      "billion-context-dsh is model-driven: use the compress tool instead of automatic summarization"
+    );
+  }
+};
+var index_default = AcpCompactionEngine;
+export {
+  ACP_SYSTEM_PROMPT,
+  ACP_SYSTEM_PROMPT_ORDER,
+  AcpCompactionEngine,
+  AcpStateStore,
+  acpCommand,
+  assertNoActiveCompaction,
+  buildNudge,
+  index_default as default,
+  eventsToCoreMessages,
+  extractEventText,
+  findOpenTurn,
+  kernelConfigFor,
+  makeTools,
+  projectEvent,
+  rebuildBlockLedger,
+  resolveAcpConfig,
+  resolveSurfaceRange,
+  runCompactionTransaction,
+  shadowedSeqsOf,
+  surfaceEventsOf
+};
+//# sourceMappingURL=index.js.map