howtofixcli 0.7.24 → 0.7.26

package/dist/dcp/commands.js

@@ -0,0 +1,172 @@
+/**
+ * `/dcp` — the switch and the inspector.
+ *
+ * DCP is on by default and costs nothing when idle: with no blocks and no stale
+ * output the transform returns the transcript unchanged. The switch exists so a
+ * user who suspects the pruning is hurting can turn it off without losing the
+ * session, and the override is persisted, so it survives a restart.
+ *
+ * `readConfigEnabled` is consulted only to report *where* the current value
+ * came from. Resolution order is session override → env → config → default, and
+ * the session override always wins: a user who typed `/dcp off` did not mean
+ * "unless a config file disagrees".
+ *
+ * The functions return text rather than printing, so the workbench keeps owning
+ * rendering — the same contract every other slash command in `ui.ts` follows.
+ */
+import { activeCompressedRanges } from "./compress-state.js";
+import { getDcpState, readConfigEnabled, resolveDcpEnabled, saveDcpState } from "./state.js";
+/** One `/dcp` subcommand, kept in one table so help and dispatch cannot drift. */
+export const DCP_USAGE = {
+    on: "turn the transform on for this session",
+    off: "turn it off; the full transcript is sent unchanged",
+    status: "the switch, the block count, and the tokens saved",
+    blocks: "list the active compressed blocks",
+    stats: "prune and compress totals for this session",
+    context: "what the next request will carry, and what was saved",
+    decompress: "reopen one block by id, e.g. /dcp decompress b2",
+    sweep: "drop blocks no longer referenced by the ref state",
+};
+function formatChars(chars) {
+    return chars < 1000 ? `${chars}` : `${(chars / 1000).toFixed(1)}k`;
+}
+/**
+ * Apply a `/dcp` subcommand and return what to show the user.
+ *
+ * `sessionId` keys the state file; `cwd` is where a project config would live.
+ * Both are passed in rather than read from a context so this stays callable
+ * from the workbench, where there is no extension context to hand.
+ */
+export function runDcpCommand(args, cwd, sessionId) {
+    // A default in the destructuring does NOT fire for an empty string - only for
+    // `undefined` - so `/dcp` with no argument produced `""` and reported it as an
+    // unknown subcommand. The status view is what a bare `/dcp` must show, and
+    // the TUI probe caught it; no unit fixture had tried the bare form.
+    const [first] = args.trim().split(/\s+/);
+    const sub = first === undefined || first === "" ? "status" : first;
+    const state = getDcpState(sessionId);
+    switch (sub) {
+        case "on":
+            state.enabled = true;
+            saveDcpState(sessionId);
+            return "dcp: on";
+        case "off":
+            state.enabled = false;
+            saveDcpState(sessionId);
+            return "dcp: off; the full transcript is sent unchanged";
+        case "blocks": {
+            const blocks = activeCompressedRanges(state);
+            if (blocks.length === 0)
+                return "dcp: no active blocks";
+            return blocks
+                .map((block) => {
+                const anchor = String(block.anchorIndex).padStart(4, "0");
+                return `b${block.blockId}  covers ${block.coveredIndices.length} message(s), anchored at m${anchor}`;
+            })
+                .join("\n");
+        }
+        case "status": {
+            const resolved = resolveDcpEnabled({ runtime: state.enabled, config: readConfigEnabled(cwd) });
+            const blocks = activeCompressedRanges(state);
+            const saved = Object.values(state.prune.tools).reduce((sum, chars) => sum + chars, 0);
+            return [
+                `dcp: ${resolved.enabled ? "on" : "off"} (source: ${resolved.source})`,
+                `messages tracked: ${Object.keys(state.messageIds.keyToRef).length}`,
+                `active blocks: ${blocks.length}`,
+                `pruned tool calls: ${Object.keys(state.prune.tools).length} (${formatChars(saved)} chars)`,
+                `compressed tokens total: ${state.stats.totalCompressTokens}`,
+            ].join("\n");
+        }
+        case "stats": {
+            const blocks = state.prune.messages.blocks;
+            const active = blocks.filter((block) => block.active).length;
+            const prunedTokens = Object.values(state.prune.tools).reduce((sum, chars) => sum + chars, 0);
+            return [
+                `blocks: ${active} active of ${blocks.length} total`,
+                `compressed tokens: ${state.stats.totalCompressTokens}`,
+                `pruned tool calls: ${Object.keys(state.prune.tools).length} (${formatChars(prunedTokens)} chars)`,
+                `messages tracked: ${Object.keys(state.messageIds.keyToRef).length}`,
+                `refs allocated: ${state.messageIds.nextRef - 1}`,
+            ].join("\n");
+        }
+        case "context": {
+            // What the next request carries. This is the question `/dcp` exists to
+            // answer: a compression changes the provider payload and nothing on
+            // screen, so "how much is being sent" is otherwise unknowable.
+            const blocks = activeCompressedRanges(state);
+            const covered = new Set();
+            for (const block of blocks)
+                for (const index of block.coveredIndices)
+                    covered.add(index);
+            const tracked = Object.keys(state.messageIds.keyToRef).length;
+            const prunedChars = Object.values(state.prune.tools).reduce((sum, chars) => sum + chars, 0);
+            return [
+                `messages tracked: ${tracked}`,
+                `messages replaced by a block: ${covered.size}`,
+                `messages sent: ${Math.max(0, tracked - covered.size)}`,
+                `active blocks: ${blocks.length}`,
+                `compressed tokens total: ${state.stats.totalCompressTokens}`,
+                `pruned tool calls: ${Object.keys(state.prune.tools).length} (${formatChars(prunedChars)} chars)`,
+            ].join("\n");
+        }
+        case "decompress": {
+            // Reopening a block is what makes a compression safe to try: the summary
+            // is lossy by construction, and this is the way back. Blocks that a later
+            // block consumed are reopened BEFORE their consumer, so the consumer's
+            // inherited coverage is released first and the range it covered becomes
+            // visible again.
+            const target = args.trim().split(/\s+/)[1];
+            const match = target === undefined ? null : /^b?(\d+)$/i.exec(target);
+            if (!match)
+                return "dcp: give a block id, e.g. /dcp decompress b2";
+            const blockId = Number(match[1]);
+            const blocks = state.prune.messages.blocks;
+            const block = blocks.find((candidate) => candidate.blockId === blockId);
+            if (!block)
+                return `dcp: no block b${blockId}`;
+            // The consumer is checked BEFORE `active`. A block a later one consumed is
+            // already inactive, so testing `active` first answered "already open" for
+            // exactly the case that needs the other message - and the guard against
+            // reopening a covered range would never have run.
+            const parents = blocks.filter((candidate) => candidate.active && candidate.consumedBlockIds.includes(blockId));
+            if (parents.length > 0) {
+                const names = parents.map((candidate) => `b${candidate.blockId}`).join(", ");
+                return `dcp: b${blockId} was consumed by ${names}; decompress that one first`;
+            }
+            if (!block.active)
+                return `dcp: b${blockId} is already open`;
+            block.active = false;
+            block.deactivatedByUser = true;
+            block.deactivatedAt = Date.now();
+            for (const parentBlockId of block.parentBlockIds) {
+                const parent = blocks.find((candidate) => candidate.blockId === parentBlockId);
+                if (!parent)
+                    continue;
+                parent.consumedBlockIds = parent.consumedBlockIds.filter((id) => id !== blockId);
+            }
+            saveDcpState(sessionId);
+            return `dcp: b${blockId} reopened; ${block.coveredIndices.length} message(s) are back`;
+        }
+        case "sweep": {
+            // A block whose covered refs no longer resolve cannot be rendered, so it
+            // contributes nothing but a stale entry in the state file. Sweeping it is
+            // safe for the same reason: there is nothing left for it to hide.
+            const refs = new Set(Object.keys(state.messageIds.refToKey).map(Number));
+            const blocks = state.prune.messages.blocks;
+            const before = blocks.length;
+            const orphaned = blocks.filter((block) => block.active && !block.coveredIndices.some((index) => refs.has(index)));
+            for (const block of orphaned) {
+                block.active = false;
+                block.deactivatedAt = Date.now();
+            }
+            state.prune.messages.blocks = blocks.filter((block) => block.active || block.deactivatedByUser);
+            const dropped = before - state.prune.messages.blocks.length;
+            saveDcpState(sessionId);
+            if (orphaned.length === 0)
+                return "dcp: nothing to sweep";
+            return `dcp: ${orphaned.length} orphaned block(s) closed, ${dropped} dropped from state`;
+        }
+        default:
+            return `dcp: unknown subcommand '${sub}'. try: ${Object.keys(DCP_USAGE).join(", ")}`;
+    }
+}

package/dist/dcp/compress-state.js

@@ -0,0 +1,139 @@
+/**
+ * Compressed block state: the stored blocks, id allocation, and the wrapper
+ * that turns a summary into a self-contained block.
+ *
+ * Port of DCP's `lib/compress/state.ts`, trimmed to what the spec (§3.5, §3.6)
+ * asks for: no duration tracking, no tool-id bookkeeping, and no Map/Set state —
+ * everything here is plain JSON so `SessionState` round-trips through
+ * `~/.howtofix/agent/dcp/<session>.json` with a plain `JSON.stringify`/`parse`
+ * and no custom replacer. The active set and the anchor index are derived from
+ * `blocks` rather than stored, so there is no redundant index to desync.
+ */
+import { formatBlockRef, formatMessageIdTag } from "./ids.js";
+export const COMPRESSED_BLOCK_HEADER = "[Compressed conversation section]";
+/**
+ * Token estimate for stored text. DCP counts with a bundled tokenizer; we may
+ * not add a dependency, so use the same length/4 fallback DCP itself uses
+ * when its tokenizer throws.
+ */
+export function estimateSummaryTokens(text) {
+    return Math.round(text.length / 4);
+}
+/** Allocate the next block id, repairing a corrupted counter instead of emitting `b0`. */
+export function allocateBlockId(state) {
+    const next = state.prune.messages.nextBlockId;
+    if (!Number.isInteger(next) || next < 1) {
+        state.prune.messages.nextBlockId = 2;
+        return 1;
+    }
+    state.prune.messages.nextBlockId = next + 1;
+    return next;
+}
+/** Allocate the next compress run id; one tool call shares one run id. */
+export function allocateRunId(state) {
+    const next = state.prune.messages.nextRunId;
+    if (!Number.isInteger(next) || next < 1) {
+        state.prune.messages.nextRunId = 2;
+        return 1;
+    }
+    state.prune.messages.nextRunId = next + 1;
+    return next;
+}
+/**
+ * Wrap a summary so the block is self-contained: the header marks it in
+ * context, the trailing tag names the block it belongs to.
+ */
+export function wrapCompressedSummary(blockId, summary, format = "xml") {
+    const footer = formatMessageIdTag(formatBlockRef(blockId, format), undefined, format);
+    const body = summary.trim();
+    if (body.length === 0) {
+        return `${COMPRESSED_BLOCK_HEADER}\n${footer}`;
+    }
+    return `${COMPRESSED_BLOCK_HEADER}\n${body}\n\n${footer}`;
+}
+/**
+ * Active blocks as the replacement view the prompt pass consumes: the anchor
+ * where the summary is placed, every ref index it replaces, and the text that
+ * replaces them.
+ */
+export function activeCompressedRanges(state) {
+    return state.prune.messages.blocks
+        .filter((block) => block.active)
+        .map((block) => ({
+        blockId: block.blockId,
+        anchorIndex: block.anchorIndex,
+        coveredIndices: block.coveredIndices,
+        summary: block.summary,
+    }));
+}
+/**
+ * Attach a new compressed block: store it, fold the consumed blocks into it,
+ * and account for the content it replaced.
+ *
+ * Newness is measured against every block that was active before this call, so
+ * content already compressed into a consumed block is never counted twice —
+ * the same rule DCP applies through `wasActive`/`isNowActive`.
+ */
+export function applyCompressionState(state, input, selection, anchorIndex, blockId, summary, consumedBlockIds) {
+    const messagesState = state.prune.messages;
+    const consumed = [...new Set(consumedBlockIds.filter((id) => Number.isInteger(id) && id > 0))];
+    const preCovered = new Set();
+    for (const block of messagesState.blocks) {
+        if (!block.active) {
+            continue;
+        }
+        for (const index of block.coveredIndices) {
+            preCovered.add(index);
+        }
+    }
+    const covered = new Set(selection.indices);
+    for (const consumedBlockId of consumed) {
+        const consumedBlock = messagesState.blocks.find((block) => block.blockId === consumedBlockId);
+        if (!consumedBlock) {
+            continue;
+        }
+        for (const index of consumedBlock.coveredIndices) {
+            covered.add(index);
+        }
+    }
+    const coveredIndices = [...covered].sort((left, right) => left - right);
+    const newlyCoveredIndices = coveredIndices.filter((index) => !preCovered.has(index));
+    let compressedTokens = 0;
+    for (const index of newlyCoveredIndices) {
+        compressedTokens += selection.tokenByIndex.get(index) ?? 0;
+    }
+    const block = {
+        blockId,
+        runId: input.runId,
+        active: true,
+        deactivatedByUser: false,
+        mode: input.mode,
+        topic: input.topic,
+        startId: input.startId,
+        endId: input.endId,
+        anchorIndex,
+        compressedTokens,
+        summaryTokens: estimateSummaryTokens(summary),
+        coveredIndices,
+        consumedBlockIds: consumed,
+        parentBlockIds: [],
+        createdAt: Date.now(),
+        summary,
+    };
+    messagesState.blocks.push(block);
+    const deactivatedAt = Date.now();
+    for (const consumedBlockId of consumed) {
+        const consumedBlock = messagesState.blocks.find((block) => block.blockId === consumedBlockId);
+        if (!consumedBlock || !consumedBlock.active) {
+            continue;
+        }
+        consumedBlock.active = false;
+        consumedBlock.deactivatedAt = deactivatedAt;
+        consumedBlock.deactivatedByBlockId = blockId;
+        if (!consumedBlock.parentBlockIds.includes(blockId)) {
+            consumedBlock.parentBlockIds.push(blockId);
+        }
+    }
+    state.stats.totalCompressTokens += compressedTokens;
+    return { compressedTokens, coveredIndices, newlyCoveredIndices };
+}

package/dist/dcp/compress.js

@@ -0,0 +1,329 @@
+/**
+ * The `compress` tool: validate a batch of ranges, resolve them against the
+ * live state and the last-assigned message snapshot, then store one block per
+ * range.
+ *
+ * Port of DCP's `lib/compress/range.ts` + `range-utils.ts` with the spec's
+ * stricter validation (§5): DCP silently repairs summaries whose placeholders
+ * are invented, duplicated, or missing — we reject them, so the preflight rule
+ * in `rangePrompt()` is enforced rather than hoped for. Validation runs in the
+ * order the spec fixes (args → overlap → placeholders → resolve) and completes
+ * before any mutation, so a rejected call leaves the state untouched.
+ */
+import { Type } from "@netrodev/hxf-ai";
+import { defineTool } from "@netrodev/hxf-coding-agent";
+import { formatBlockRef, formatMessageRef, parseBoundaryId } from "./ids.js";
+import { COMPRESSED_BLOCK_HEADER, estimateSummaryTokens, allocateBlockId, allocateRunId, applyCompressionState, wrapCompressedSummary } from "./compress-state.js";
+/** All `(bN)` placeholders in a summary, in document order. */
+export function parseBlockPlaceholders(summary, format = "xml") {
+    const placeholders = [];
+    const regex = format === "compact" ? /@b([1-9]\d*)@/gi : /\(b(\d+)\)/gi;
+    let match;
+    while ((match = regex.exec(summary)) !== null) {
+        const blockId = Number.parseInt(match[1], 10);
+        if (!Number.isInteger(blockId)) {
+            continue;
+        }
+        placeholders.push({
+            raw: match[0],
+            blockId,
+            startIndex: match.index,
+            endIndex: match.index + match[0].length,
+        });
+    }
+    return placeholders;
+}
+export function validateArgs(args) {
+    if (typeof args.topic !== "string" || args.topic.trim().length === 0) {
+        throw new Error("topic is required and must be a non-empty string");
+    }
+    if (!Array.isArray(args.content) || args.content.length === 0) {
+        throw new Error("content is required and must be a non-empty array");
+    }
+    for (let index = 0; index < args.content.length; index++) {
+        const entry = args.content[index];
+        const prefix = `content[${index}]`;
+        if (typeof entry?.startId !== "string" || entry.startId.trim().length === 0) {
+            throw new Error(`${prefix}.startId is required and must be a non-empty string`);
+        }
+        if (typeof entry?.endId !== "string" || entry.endId.trim().length === 0) {
+            throw new Error(`${prefix}.endId is required and must be a non-empty string`);
+        }
+        if (typeof entry?.summary !== "string" || entry.summary.trim().length === 0) {
+            throw new Error(`${prefix}.summary is required and must be a non-empty string`);
+        }
+    }
+}
+/**
+ * Plan one range: resolve both boundaries to window indices, collect the
+ * window, the required blocks, and the token estimates.
+ *
+ * A message boundary resolves to its own ref index; a block boundary resolves
+ * to the block's anchor — the same rule DCP applies in `resolveBoundaryIds`,
+ * which is why consuming an end block pulls its full coverage into the new
+ * block.
+ */
+function planRange(state, entry, snapshot, format) {
+    const present = new Set();
+    const tokenByIndex = new Map();
+    for (const row of snapshot) {
+        present.add(row.index);
+        tokenByIndex.set(row.index, row.tokenCount ?? 0);
+    }
+    const start = boundaryIndex(state, present, entry.startId, "startId", format);
+    const end = boundaryIndex(state, present, entry.endId, "endId", format);
+    if (start.index > end.index) {
+        throw new Error(`startId ${start.ref} appears after endId ${end.ref} in the conversation. Start must come before end.`);
+    }
+    const indices = [];
+    for (const row of snapshot) {
+        if (row.index >= start.index && row.index <= end.index) {
+            indices.push(row.index);
+        }
+    }
+    const window = new Set(indices);
+    // Required = active blocks whose anchor sits inside the window; the anchor
+    // must also be present, so a block whose anchor fell out of context is not
+    // demanded from a model that cannot see it.
+    const requiredBlockIds = state.prune.messages.blocks.filter((block) => block.active && window.has(block.anchorIndex)).map((block) => block.blockId);
+    return {
+        startIdx: start.index,
+        endIdx: end.index,
+        indices,
+        requiredBlockIds,
+        tokenByIndex,
+    };
+}
+function boundaryIndex(state, present, id, role, format) {
+    const parsed = parseBoundaryId(id, format);
+    if (parsed === null) {
+        const messageExample = format === "compact" ? "@4@" : "mNNNN";
+        const blockExample = format === "compact" ? "@b1@" : "bN";
+        throw new Error(`${role} is invalid. Use an injected message ID (${messageExample}) or block ID (${blockExample}).`);
+    }
+    let index;
+    if (parsed.kind === "message") {
+        index = parsed.index;
+    }
+    else {
+        const block = state.prune.messages.blocks.find((candidate) => candidate.blockId === parsed.blockId && candidate.active);
+        index = block ? block.anchorIndex : -1;
+    }
+    if (index < 0 || !present.has(index)) {
+        throw new Error(`${role} ${parsed.ref} is not available in the current conversation context. Choose an injected ID visible in context.`);
+    }
+    return { ref: parsed.ref, index };
+}
+/** Reject batches whose ranges overlap. Touching at a shared boundary counts as overlap. */
+export function validateNonOverlapping(content, state, snapshot, format = "xml") {
+    const plans = content.map((raw, index) => {
+        const entry = {
+            startId: raw.startId.trim(),
+            endId: raw.endId.trim(),
+            summary: raw.summary,
+        };
+        return { index, entry, selection: planRange(state, entry, snapshot, format) };
+    });
+    const sortedPlans = [...plans].sort((left, right) => left.selection.startIdx - right.selection.startIdx || left.selection.endIdx - right.selection.endIdx || left.index - right.index);
+    const issues = [];
+    for (let index = 1; index < sortedPlans.length; index++) {
+        const previous = sortedPlans[index - 1];
+        const current = sortedPlans[index];
+        if (!previous || !current) {
+            continue;
+        }
+        if (current.selection.startIdx > previous.selection.endIdx) {
+            continue;
+        }
+        issues.push(`content[${previous.index}] (${previous.entry.startId}..${previous.entry.endId}) overlaps content[${current.index}] (${current.entry.startId}..${current.entry.endId}). Overlapping ranges cannot be compressed in the same batch.`);
+    }
+    if (issues.length > 0) {
+        throw new Error(issues.length === 1 ? issues[0] : issues.map((issue) => `- ${issue}`).join("\n"));
+    }
+}
+/**
+ * Enforce the preflight rule from `rangePrompt()`: the placeholders in a
+ * summary must be exactly the required set — nothing invented, nothing
+ * duplicated, nothing missing. Returns each entry's parsed placeholders in
+ * document order, ready for expansion.
+ */
+export function validateSummaryPlaceholders(content, state, snapshot, format = "xml") {
+    const activeBlockIds = new Set(state.prune.messages.blocks.filter((block) => block.active).map((block) => block.blockId));
+    return content.map((raw, index) => {
+        const entry = {
+            startId: raw.startId.trim(),
+            endId: raw.endId.trim(),
+            summary: raw.summary,
+        };
+        const selection = planRange(state, entry, snapshot, format);
+        const required = new Set(selection.requiredBlockIds);
+        const parsed = parseBlockPlaceholders(entry.summary, format);
+        const seen = new Set();
+        const prefix = `content[${index}]`;
+        for (const placeholder of parsed) {
+            if (seen.has(placeholder.blockId)) {
+                throw new Error(`${prefix}.summary duplicates placeholder ${placeholder.raw}`);
+            }
+            seen.add(placeholder.blockId);
+            if (!required.has(placeholder.blockId)) {
+                throw new Error(activeBlockIds.has(placeholder.blockId) ? `${prefix}.summary references ${placeholder.raw}, which is outside the selected range` : `${prefix}.summary references ${placeholder.raw}, which is not an active compressed block`);
+            }
+        }
+        for (const blockId of selection.requiredBlockIds) {
+            if (!seen.has(blockId)) {
+                const token = format === "compact" ? `@b${blockId}@` : `(b${blockId})`;
+                throw new Error(`${prefix}.summary is missing the required placeholder ${token}`);
+            }
+        }
+        return parsed;
+    });
+}
+/** Resolve every entry into a windowed selection; the last step before applying. */
+export function resolveRanges(content, state, snapshot, format = "xml") {
+    return content.map((raw, index) => {
+        const entry = {
+            startId: raw.startId.trim(),
+            endId: raw.endId.trim(),
+            summary: raw.summary,
+        };
+        const selection = planRange(state, entry, snapshot, format);
+        return { index, entry, selection, anchorIndex: selection.startIdx };
+    });
+}
+/** Strip a stored block's header and trailing id tag, leaving its body. */
+function restoreSummary(summary) {
+    const headerMatch = summary.match(/^\s*\[Compressed conversation(?: section)?(?: b\d+)?\]/i);
+    if (!headerMatch) {
+        return summary;
+    }
+    const afterHeader = summary.slice(headerMatch[0].length).replace(/^(?:\r?\n)+/, "");
+    return afterHeader
+        .replace(/(?:\r?\n)*<dcp-message-id>b\d+<\/dcp-message-id>\s*$/i, "")
+        .replace(/(?:\r?\n)*@b[1-9]\d*@\s*$/i, "")
+        .replace(/(?:\r?\n)+$/, "");
+}
+/**
+ * Replace each placeholder with the stored block's body so the new block is
+ * self-contained, and report which blocks it consumes. Boundary handling needs
+ * no append path here: validation guarantees the placeholder set is exactly
+ * the required set, so an unreferenced boundary block cannot occur.
+ */
+function expandPlaceholders(summary, parsed, state) {
+    if (parsed.length === 0) {
+        return { expanded: summary, consumedBlockIds: [] };
+    }
+    let expanded = "";
+    let cursor = 0;
+    const consumedBlockIds = [];
+    for (const placeholder of parsed) {
+        const target = state.prune.messages.blocks.find((block) => block.blockId === placeholder.blockId && block.active);
+        if (!target) {
+            throw new Error(`Compressed block not found: ${placeholder.raw}`);
+        }
+        expanded += summary.slice(cursor, placeholder.startIndex);
+        expanded += restoreSummary(target.summary);
+        cursor = placeholder.endIndex;
+        consumedBlockIds.push(placeholder.blockId);
+    }
+    expanded += summary.slice(cursor);
+    return { expanded, consumedBlockIds };
+}
+/**
+ * The compress execution shared by every entry point: validate, resolve, then
+ * per range allocate a block id, expand placeholders, wrap the summary, and
+ * attach the block to its anchor message. Mutates `state` in place; every
+ * validation failure throws before the first mutation.
+ */
+export function compressRanges(args, state, snapshot, format = "xml") {
+    validateArgs(args);
+    validateNonOverlapping(args.content, state, snapshot, format);
+    const placeholdersByEntry = validateSummaryPlaceholders(args.content, state, snapshot, format);
+    const plans = resolveRanges(args.content, state, snapshot, format);
+    const runId = allocateRunId(state);
+    const outcomes = [];
+    for (const [position, plan] of plans.entries()) {
+        const parsed = placeholdersByEntry[position] ?? [];
+        const { expanded, consumedBlockIds } = expandPlaceholders(plan.entry.summary, parsed, state);
+        const blockId = allocateBlockId(state);
+        const wrapped = wrapCompressedSummary(blockId, expanded, format);
+        const applied = applyCompressionState(state, {
+            topic: args.topic,
+            startId: plan.entry.startId,
+            endId: plan.entry.endId,
+            mode: "range",
+            runId,
+        }, plan.selection, plan.anchorIndex, blockId, wrapped, consumedBlockIds);
+        outcomes.push({
+            blockId,
+            runId,
+            coveredCount: applied.coveredIndices.length,
+            compressedTokens: applied.compressedTokens,
+            // The same estimator `applyCompressionState` used to store it, so the
+            // figure reported here and the figure in the block cannot disagree.
+            summaryTokens: estimateSummaryTokens(wrapped),
+            expandedSummary: expanded,
+        });
+    }
+    return outcomes;
+}
+/** The model-facing tool. The wiring supplies state and the ref snapshot. */
+export function createCompressTool(deps) {
+    const format = deps.format ?? "xml";
+    const messageExample = formatMessageRef(1, format);
+    const blockExample = formatBlockRef(2, format);
+    return defineTool({
+        name: "compress",
+        label: "compress",
+        description: "Collapse conversation ranges into stored compressed summaries, each marked " +
+            `with "${COMPRESSED_BLOCK_HEADER}". Copy startId and endId from the injected IDs in context ` +
+            `(message IDs like ${messageExample}, block IDs like ${blockExample}); startId must come before endId. ` +
+            "Ranges in one call must not overlap, and each summary must reference every required " +
+            "block placeholder exactly once.",
+        promptSnippet: "compress: replace a conversation range with a stored summary",
+        parameters: Type.Object({
+            topic: Type.String({
+                description: "Short label (3-5 words) for display - e.g., 'Auth System Exploration'",
+            }),
+            content: Type.Array(Type.Object({
+                startId: Type.String({
+                    description: `Message or block ID marking the beginning of range (e.g. ${messageExample}, ${blockExample})`,
+                }),
+                endId: Type.String({
+                    description: `Message or block ID marking the end of range (e.g. ${formatMessageRef(12, format)}, ${formatBlockRef(5, format)})`,
+                }),
+                summary: Type.String({
+                    description: "Complete technical summary replacing all content in range",
+                }),
+            }), { description: "One or more ranges to compress, each with start/end boundaries and a summary" }),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const outcomes = compressRanges(params, deps.state(), deps.messages(), format);
+                const blockIds = outcomes.map((outcome) => outcome.blockId);
+                const messages = outcomes.reduce((sum, outcome) => sum + outcome.coveredCount, 0);
+                const compressedTokens = outcomes.reduce((sum, outcome) => sum + outcome.compressedTokens, 0);
+                const summaryTokens = outcomes.reduce((sum, outcome) => sum + outcome.summaryTokens, 0);
+                const saved = Math.max(0, compressedTokens - summaryTokens);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            // The saving belongs in the result the model reads too: it is the
+                            // reason to compress again rather than avoid the tool.
+                            text: `Compressed ${messages} messages into ${COMPRESSED_BLOCK_HEADER}` + (compressedTokens > 0 ? ` - ${compressedTokens} tokens replaced by ${summaryTokens}, saving ${saved}.` : "."),
+                        },
+                    ],
+                    details: { blockIds, runId: outcomes[0]?.runId, messages, compressedTokens, summaryTokens },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [{ type: "text", text: message }],
+                    details: { error: message },
+                    isError: true,
+                };
+            }
+        },
+    });
+}