compress: restructure schema with topic primary, content nested (startString/endString)

Author: spoons-and-mirrors

lib/prompts/compress.md

@@ -1,58 +1,35 @@
-Collapses a contiguous range of conversation into a single summary.
+Use this tool to collapse a contiguous range of conversation into a preserved summary.
 
-## When to Use This Tool
+THE PHILOSOPHY OF COMPRESS
+`compress` transforms verbose conversation sequences into dense, high-fidelity summaries. This is not cleanup - it is crystallization. Your summary becomes the authoritative record of what transpired.
 
-Use `compress` when you want to condense an entire sequence of work into a brief summary:
+Think of compression as phase transitions: raw exploration becomes refined understanding. The original context served its purpose; your summary now carries that understanding forward.
 
-- **Phase Completion:** You completed a phase (research, tool calls, implementation) and want to collapse the entire sequence into a summary.
-- **Exploration Done:** You explored multiple files or ran multiple commands and only need a summary of what you learned.
-- **Failed Attempts:** You tried several unsuccessful approaches and want to condense them into a brief note.
-- **Verbose Output:** A section of conversation has grown large but can be summarized without losing critical details.
+THE SUMMARY
+Your summary must be COMPLETE. Capture file paths, function signatures, decisions made, constraints discovered, key findings... EVERYTHING that maintains context integrity. This is not a brief note - it is a technical substitute so faithful that the original conversation adds no value.
 
-## When NOT to Use This Tool
+Yet be LEAN. Strip away the noise: failed attempts that led nowhere, verbose tool outputs, back-and-forth exploration. What remains should be pure signal - golden nuggets of detail that preserve full understanding with zero ambiguity.
 
-- **If you need specific details:** If you'll need exact code, file contents, or error messages from the range, keep them.
-- **For individual tool outputs:** Use `prune` or `distill` for single tool outputs. Compress targets conversation ranges.
-- **If it's recent content:** You may still need recent work for the current phase.
+WHEN TO COMPRESS
+Compress when a phase of work is truly complete and the raw conversation is no longer needed:
 
-## How It Works
+Research concluded and findings are clear
+Implementation finished and verified
+Exploration exhausted and patterns understood
 
-1. `startString` — A unique text string that marks the start of the range to compress
-2. `endString` — A unique text string that marks the end of the range to compress
-3. `topic` — A short label (3-5 words) describing the compressed content
-4. `summary` — The replacement text that will be inserted
+Do NOT compress when:
+You may need exact code, error messages, or file contents from the range
+Work in that area is still active or may resume
+You're mid-sprint on related functionality
 
-Everything between startString and endString (inclusive) is removed and replaced with your summary.
+Before compressing, ask: _"Am I certain this phase is complete?"_ Compression is irreversible. The summary replaces everything in the range.
 
-**Important:** The compress will FAIL if `startString` or `endString` is not found in the conversation. The compress will also FAIL if either string is found multiple times. Provide a larger string with more surrounding context to uniquely identify the intended match.
+BOUNDARY MATCHING
+You specify boundaries by matching unique text strings in the conversation. CRITICAL: In code-centric conversations, strings repeat often. Provide sufficiently unique text to match exactly once. If a match fails (not found or found multiple times), the tool will error - extend your boundary string with more surrounding context in order to make SURE the tool does NOT error.
 
-## Best Practices
-
-- **Choose unique strings:** Pick text that appears only once in the conversation.
-- **Write concise topics:** Examples: "Auth System Exploration", "Token Logic Refactor"
-- **Write comprehensive summaries:** Include key information like file names, function signatures, and important findings.
-- **Timing:** Best used after finishing a work phase, not during active exploration.
-
-## Format
-
-- `input`: Array with four elements: [startString, endString, topic, summary]
-
-## Example
-
-<example_compress>
-Conversation: [Asked about auth] -> [Read 5 files] -> [Analyzed patterns] -> [Found "JWT tokens with 24h expiry"]
-
-[Uses compress with:
-input: [
-"Asked about authentication",
-"JWT tokens with 24h expiry",
-"Auth System Exploration",
-"Auth: JWT 24h expiry, bcrypt passwords, refresh rotation. Files: auth.ts, tokens.ts, middleware/auth.ts"
-]
-]
-</example_compress>
-
-<example_keep>
-Assistant: [Just finished reading auth.ts]
-I've read the auth file and now need to make edits based on it. I'm keeping this in context rather than compressing.
-</example_keep>
+THE FORMAT OF COMPRESS
+`topic`: Short label (3-5 words) for display - e.g., "Auth System Exploration"
+  `content`: Object containing:
+    `startString`: Unique text string marking the beginning of the range
+    `endString`: Unique text string marking the end of the range
+    `summary`: Complete technical summary replacing all content in the range

lib/prompts/distill.md

@@ -23,6 +23,6 @@ UNCERTAINTY REMAINS: If you might need to re-examine the original, defer. Distil
 Before distilling, ask yourself: _"Will I need the raw output for upcoming work?"_ If you plan to edit a file you just read, keep it intact. Distillation is for completed exploration, not active work.
 
 THE FORMAT OF DISTILL
-`items`: Array of objects, each containing:
+`targets`: Array of objects, each containing:
   `id`: Numeric ID (as string) from the `<prunable-tools>` list
   `distillation`: Complete technical substitute for that tool output

lib/tools/compress.ts

@@ -19,11 +19,22 @@ export function createCompressTool(ctx: PruneToolContext): ReturnType<typeof too
     return tool({
         description: COMPRESS_TOOL_DESCRIPTION,
         args: {
-            input: tool.schema
-                .array(tool.schema.string())
-                .describe(
-                    "[startString, endString, topic, summary] - 4 required strings: (1) startString: unique text from conversation marking range start, (2) endString: unique text marking range end, (3) topic: short 3-5 word label for UI, (4) summary: comprehensive text replacing all compressed content",
-                ),
+            topic: tool.schema
+                .string()
+                .describe("Short label (3-5 words) for display - e.g., 'Auth System Exploration'"),
+            content: tool.schema
+                .object({
+                    startString: tool.schema
+                        .string()
+                        .describe("Unique text from conversation marking the beginning of range"),
+                    endString: tool.schema
+                        .string()
+                        .describe("Unique text marking the end of range"),
+                    summary: tool.schema
+                        .string()
+                        .describe("Complete technical summary replacing all content in range"),
+                })
+                .describe("The compression details: boundaries and replacement summary"),
         },
         async execute(args, toolCtx) {
             const { client, state, logger } = ctx
@@ -36,30 +47,20 @@ export function createCompressTool(ctx: PruneToolContext): ReturnType<typeof too
                 metadata: {},
             })
 
-            if (!Array.isArray(args.input)) {
-                throw new Error(
-                    'input must be an array of 4 strings: ["startString", "endString", "topic", "summary"]',
-                )
-            }
-            if (args.input.length !== 4) {
-                throw new Error(
-                    `input must be an array of exactly 4 strings: ["startString", "endString", "topic", "summary"], got ${args.input.length} elements`,
-                )
-            }
-
-            const [startString, endString, topic, summary] = args.input
+            const { topic, content } = args
+            const { startString, endString, summary } = content || {}
 
+            if (!topic || typeof topic !== "string") {
+                throw new Error("topic is required and must be a non-empty string")
+            }
             if (!startString || typeof startString !== "string") {
-                throw new Error("startString is required and must be a non-empty string")
+                throw new Error("content.startString is required and must be a non-empty string")
             }
             if (!endString || typeof endString !== "string") {
-                throw new Error("endString is required and must be a non-empty string")
-            }
-            if (!topic || typeof topic !== "string") {
-                throw new Error("topic is required and must be a non-empty string")
+                throw new Error("content.endString is required and must be a non-empty string")
             }
             if (!summary || typeof summary !== "string") {
-                throw new Error("summary is required and must be a non-empty string")
+                throw new Error("content.summary is required and must be a non-empty string")
             }
 
             logger.info("Compress tool invoked")

lib/tools/distill.ts

@@ -10,7 +10,7 @@ export function createDistillTool(ctx: PruneToolContext): ReturnType<typeof tool
     return tool({
         description: DISTILL_TOOL_DESCRIPTION,
         args: {
-            items: tool.schema
+            targets: tool.schema
                 .array(
                     tool.schema.object({
                         id: tool.schema
@@ -21,31 +21,31 @@ export function createDistillTool(ctx: PruneToolContext): ReturnType<typeof tool
                             .describe("Complete technical distillation for this tool output"),
                     }),
                 )
-                .describe(
-                    "Array of distillation entries, each pairing an ID with its distillation",
-                ),
+                .describe("Tool outputs to distill, each pairing an ID with its distillation"),
         },
         async execute(args, toolCtx) {
-            if (!args.items || !Array.isArray(args.items) || args.items.length === 0) {
-                ctx.logger.debug("Distill tool called without items: " + JSON.stringify(args))
-                throw new Error("Missing items. Provide at least one { id, distillation } entry.")
+            if (!args.targets || !Array.isArray(args.targets) || args.targets.length === 0) {
+                ctx.logger.debug("Distill tool called without targets: " + JSON.stringify(args))
+                throw new Error("Missing targets. Provide at least one { id, distillation } entry.")
             }
 
-            for (const item of args.items) {
-                if (!item.id || typeof item.id !== "string" || item.id.trim() === "") {
-                    ctx.logger.debug("Distill item missing id: " + JSON.stringify(item))
+            for (const target of args.targets) {
+                if (!target.id || typeof target.id !== "string" || target.id.trim() === "") {
+                    ctx.logger.debug("Distill target missing id: " + JSON.stringify(target))
                     throw new Error(
-                        "Each item must have an id (numeric string from <prunable-tools>).",
+                        "Each target must have an id (numeric string from <prunable-tools>).",
                     )
                 }
-                if (!item.distillation || typeof item.distillation !== "string") {
-                    ctx.logger.debug("Distill item missing distillation: " + JSON.stringify(item))
-                    throw new Error("Each item must have a distillation string.")
+                if (!target.distillation || typeof target.distillation !== "string") {
+                    ctx.logger.debug(
+                        "Distill target missing distillation: " + JSON.stringify(target),
+                    )
+                    throw new Error("Each target must have a distillation string.")
                 }
             }
 
-            const ids = args.items.map((item) => item.id)
-            const distillations = args.items.map((item) => item.distillation)
+            const ids = args.targets.map((t) => t.id)
+            const distillations = args.targets.map((t) => t.distillation)
 
             return executePruneOperation(
                 ctx,