pi-context 1.0.2 → 1.0.3

package/README.md

@@ -4,6 +4,8 @@ A Git-like context management tool that allows AI agents to proactively manage t
 
 Inspired by kimi-cli d-mail, implementing lossless time travel on the Pi session tree.
 
+Blog: [中文](https://blog.xlab.app/p/6a966aeb/) [EN](https://blog.xlab.app/p/51d26495/)
+
 ## Installation
 
 ```bash

package/dist/index.js

@@ -0,0 +1,443 @@
+import { DynamicBorder, } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Container, Text, Spacer } from "@mariozechner/pi-tui";
+const ContextLogParams = Type.Object({
+    limit: Type.Optional(Type.Number({ description: "History limit for visible entries (default: 50)." })),
+    verbose: Type.Optional(Type.Boolean({ description: "If true, show ALL messages. If false (default), collapses intermediate AI steps and only shows 'milestones': User messages, Tags, Branch Points, and Summaries." })),
+});
+const ContextCheckoutParams = Type.Object({
+    target: Type.String({ description: "Where to jump/squash to. Can be a tag name (e.g., 'task-start'), a commit ID, or 'root'. This is the base for your new branch." }),
+    message: Type.String({ description: "The 'Carryover Message' for the new branch. A summary of your *current* progress/lessons that you want to bring with you to the new state. This ensures you don't lose key information when switching contexts. Good summary message: '[Status] + [Reason] + [Important Changes] + [Carryover Data]'" }),
+    backupTag: Type.Optional(Type.String({ description: "Optional tag name to apply to the CURRENT state before checking out. Use this to create an automatic backup of the history you are about to leave/squash." })),
+});
+const ContextTagParams = Type.Object({
+    name: Type.String({ description: "The tag/milestone name. Use meaningful names." }),
+    target: Type.Optional(Type.String({ description: "The commit ID to tag. Defaults to HEAD (current state)." })),
+});
+const isInternal = (name) => ["context_tag", "context_log", "context_checkout"].includes(name);
+const resolveTargetId = (sm, target) => {
+    if (target.toLowerCase() === "root") {
+        const tree = sm.getTree();
+        return tree.length > 0 ? tree[0].entry.id : target;
+    }
+    if (/^[0-9a-f]{8,}$/i.test(target))
+        return target;
+    const find = (nodes) => {
+        for (const n of nodes) {
+            if (sm.getLabel(n.entry.id) === target)
+                return n.entry.id;
+            const r = find(n.children);
+            if (r)
+                return r;
+        }
+        return null;
+    };
+    // sm.getTree() returns the SDK's SessionTreeNode[], which is structurally compatible
+    return find(sm.getTree()) || target;
+};
+const formatTokens = (n) => {
+    if (n >= 1_000_000)
+        return (n / 1_000_000).toFixed(1) + "M";
+    if (n >= 1_000)
+        return Math.round(n / 1_000) + "k";
+    return n.toString();
+};
+export default function (pi) {
+    pi.registerTool({
+        name: "context_tag",
+        label: "Context Tag",
+        description: "Creates a 'Save Point' (Bookmark) in the history. Use this before trying risky changes or when a feature is stable. 'Untagged progress is risky'.",
+        parameters: ContextTagParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const sm = ctx.sessionManager;
+            let id = params.target ? resolveTargetId(sm, params.target) : undefined;
+            if (!id) {
+                // Auto-resolve: Find the last "interesting" node to tag.
+                // We skip ToolResults (which look ugly tagged) and internal-only Assistant messages (which look empty).
+                const branch = sm.getBranch();
+                for (let i = branch.length - 1; i >= 0; i--) {
+                    const entry = branch[i];
+                    // 1. Check ToolResults
+                    if (entry.type === 'message' && entry.message.role === 'toolResult') {
+                        const tr = entry.message;
+                        if (isInternal(tr.toolName))
+                            continue;
+                        // Public tool result is a valid target
+                        id = entry.id;
+                        break;
+                    }
+                    // 2. Check Assistant messages for visibility
+                    if (entry.type === 'message' && entry.message.role === 'assistant') {
+                        const m = entry.message;
+                        let hasText = false;
+                        let hasPublicTools = false;
+                        const content = m.content;
+                        if (typeof content === 'string') {
+                            hasText = content.trim().length > 0;
+                        }
+                        else if (Array.isArray(content)) {
+                            hasText = content.some((c) => c.type === 'text' && typeof c.text === 'string' && c.text.trim().length > 0);
+                            const toolCalls = content.filter((c) => c.type === 'toolCall');
+                            hasPublicTools = toolCalls.some((tc) => !isInternal(tc.name));
+                        }
+                        // If it has visible text or public tools, it's a valid target
+                        if (hasText || hasPublicTools) {
+                            id = entry.id;
+                            break;
+                        }
+                        // Otherwise (only internal tools like context_tag), skip it
+                        continue;
+                    }
+                    // 3. User messages, Summaries, etc. are always valid targets
+                    id = entry.id;
+                    break;
+                }
+                // Fallback to leaf if search failed
+                if (!id)
+                    id = sm.getLeafId() ?? "";
+            }
+            pi.setLabel(id, params.name);
+            return { content: [{ type: "text", text: `Created tag '${params.name}' at ${id.slice(0, 7)}` }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "context_log",
+        label: "Context Log",
+        description: "Show the entire history structure (status, message, tags, milestones). Analogous to 'git log --graph --oneline --decorate'",
+        parameters: ContextLogParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const sm = ctx.sessionManager;
+            const branch = sm.getBranch();
+            const currentLeafId = sm.getLeafId();
+            const verbose = params.verbose ?? false;
+            const limit = params.limit ?? 50;
+            const backboneIds = new Set(branch.map((e) => e.id));
+            const sequence = [];
+            branch.forEach((entry) => {
+                sequence.push(entry);
+                // Preserve side-summary logic: Show branch summaries/compactions that are off-path
+                const children = sm.getChildren(entry.id);
+                children.forEach((child) => {
+                    if ((child.type === "branch_summary" || child.type === "compaction") && !backboneIds.has(child.id)) {
+                        sequence.push(child);
+                    }
+                });
+            });
+            const getMsgContent = (entry) => {
+                if (entry.type === "branch_summary" || entry.type === "compaction") {
+                    const e = entry;
+                    return e.summary || "[No summary provided]";
+                }
+                if (entry.type === "label") {
+                    return `tag: ${entry.label}`;
+                }
+                if (entry.type === "message") {
+                    const msg = entry.message;
+                    if (msg.role === "toolResult") {
+                        const tr = msg;
+                        if (!verbose && isInternal(tr.toolName))
+                            return "";
+                        const extractText = (content) => {
+                            return content
+                                .map((p) => (p.type === "text" ? p.text : ""))
+                                .join(" ")
+                                .trim();
+                        };
+                        let resText = extractText(tr.content);
+                        const details = tr.details;
+                        if ((tr.toolName === "read" || tr.toolName === "edit") && details && "path" in details && typeof details.path === "string") {
+                            resText = `${details.path}: ${resText}`;
+                        }
+                        return `(${tr.toolName}) ${resText}`;
+                    }
+                    if (msg.role === "bashExecution") {
+                        return `[Bash] ${msg.command}`;
+                    }
+                    if (msg.role === "user" || msg.role === "assistant") {
+                        let text = "";
+                        if (typeof msg.content === "string") {
+                            text = msg.content;
+                        }
+                        else if (Array.isArray(msg.content)) {
+                            text = msg.content
+                                .map((p) => {
+                                if (typeof p === "object" && p !== null && "text" in p)
+                                    return p.text;
+                                return "";
+                            })
+                                .join(" ")
+                                .trim();
+                        }
+                        let toolCallsText = "";
+                        if (msg.role === "assistant") {
+                            const toolCalls = msg.content.filter((c) => c.type === "toolCall");
+                            toolCallsText = toolCalls
+                                .filter((tc) => verbose || !isInternal(tc.name))
+                                .map((tc) => `call: ${tc.name}(${JSON.stringify(tc.arguments)})`)
+                                .join("; ");
+                        }
+                        return [text, toolCallsText].filter(Boolean).join(" ");
+                    }
+                }
+                return "";
+            };
+            const isInteresting = (entry) => {
+                // 1. HEAD and Root
+                if (entry.id === currentLeafId)
+                    return true;
+                if (branch.length > 0 && entry.id === branch[0].id)
+                    return true;
+                // 2. Explicit Tags (Labels) - Only show the TAGGED node, not the label node itself
+                if (sm.getLabel(entry.id))
+                    return true;
+                if (entry.type === 'label')
+                    return false; // Hide label nodes, they are redundant
+                // 3. Structural Milestones (Summaries)
+                if (entry.type === 'branch_summary' || entry.type === 'compaction')
+                    return true;
+                // 4. Branch Points (Forks)
+                if (sm.getChildren(entry.id).length > 1)
+                    return true;
+                // 5. Natural Milestones (User Messages) - This is the key auto-tagging mechanism
+                if (entry.type === 'message' && entry.message.role === 'user')
+                    return true;
+                return false;
+            };
+            const visibleSequenceIds = new Set();
+            sequence.forEach(e => {
+                if (verbose || isInteresting(e)) {
+                    visibleSequenceIds.add(e.id);
+                }
+            });
+            let visibleEntries = sequence.filter(e => visibleSequenceIds.has(e.id));
+            if (visibleEntries.length > limit) {
+                const allowedIds = new Set(visibleEntries.slice(-limit).map(e => e.id));
+                visibleSequenceIds.clear();
+                allowedIds.forEach(id => visibleSequenceIds.add(id));
+            }
+            const lines = [];
+            let hiddenCount = 0;
+            sequence.forEach((entry) => {
+                if (!visibleSequenceIds.has(entry.id)) {
+                    hiddenCount++;
+                    return;
+                }
+                if (hiddenCount > 0) {
+                    lines.push(`  :  ... (${hiddenCount} hidden messages) ...`);
+                    hiddenCount = 0;
+                }
+                const isHead = entry.id === currentLeafId;
+                const label = sm.getLabel(entry.id);
+                const content = getMsgContent(entry).replace(/\s+/g, " ");
+                let role = entry.type.toUpperCase();
+                if (entry.type === "message") {
+                    const m = entry.message;
+                    role =
+                        m.role === "assistant"
+                            ? "AI"
+                            : m.role === "user"
+                                ? "USER"
+                                : m.role === "bashExecution"
+                                    ? "BASH"
+                                    : "TOOL";
+                }
+                else if (entry.type === "branch_summary" || entry.type === "compaction") {
+                    role = "SUMMARY";
+                }
+                const id = entry.id;
+                const isRoot = branch.length > 0 && entry.id === branch[0].id;
+                const meta = [isRoot ? "ROOT" : null, isHead ? "HEAD" : null, label ? `tag: ${label}` : null].filter(Boolean).join(", ");
+                const body = content.length > 100 ? content.slice(0, 100) + "..." : content;
+                const marker = isHead ? "*" : (role === "USER" ? "•" : "|");
+                lines.push(`${marker} ${id}${meta ? ` (${meta})` : ""} [${role}] ${body}`);
+            });
+            if (hiddenCount > 0) {
+                lines.push(`  :  ... (${hiddenCount} hidden messages) ...`);
+            }
+            // --- Context Dashboard (HUD) ---
+            const usage = await ctx.getContextUsage();
+            let usageStr = "Unknown";
+            if (usage) {
+                usageStr = `${usage.percent.toFixed(1)}% (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
+            }
+            // Find the distance to the nearest tag
+            let stepsSinceTag = 0;
+            let nearestTagName = "None";
+            for (let i = branch.length - 1; i >= 0; i--) {
+                const id = branch[i].id;
+                const label = sm.getLabel(id);
+                if (label) {
+                    nearestTagName = label;
+                    break;
+                }
+                stepsSinceTag++;
+            }
+            const hud = [
+                `[Context Dashboard]`,
+                `• Context Usage:    ${usageStr}`,
+                `• Segment Size:     ${stepsSinceTag} steps since last tag '${nearestTagName}'`,
+                `---------------------------------------------------`
+            ].join("\n");
+            return { content: [{ type: "text", text: hud + "\n" + (lines.join("\n") || "(Root Path Only)") }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "context_checkout",
+        label: "Context Checkout",
+        description: "Navigate to ANY point in the conversation history. This checkout only resets *conversation history*, NOT disk files. ALWAYS provide a detailed 'message' to bridge context.",
+        parameters: ContextCheckoutParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const sm = ctx.sessionManager;
+            const tid = resolveTargetId(sm, params.target);
+            const currentLeaf = sm.getLeafId();
+            if (currentLeaf === tid) {
+                return { content: [{ type: "text", text: `Already at target ${tid}` }], details: {} };
+            }
+            if (params.backupTag && currentLeaf) {
+                pi.setLabel(currentLeaf, params.backupTag);
+            }
+            const currentLabel = currentLeaf ? sm.getLabel(currentLeaf) : undefined;
+            const origin = currentLabel ? `tag: ${currentLabel}` : (currentLeaf || "unknown");
+            const enrichedMessage = `(summary from ${origin})\n${params.message}`;
+            await sm.branchWithSummary(tid, enrichedMessage);
+            return { content: [{ type: "text", text: `Checked out ${tid}\nBackup tag created: ${params.backupTag || "none"}\nmessage: ${enrichedMessage}` }], details: {} };
+        },
+    });
+    pi.registerCommand("context", {
+        description: "Show context usage visualization",
+        handler: async (args, ctx) => {
+            const usage = await ctx.getContextUsage();
+            if (!usage) {
+                ctx.ui.notify("Context usage info not available.", "warning");
+                return;
+            }
+            const sm = ctx.sessionManager;
+            const branch = sm.getBranch();
+            const systemPrompt = ctx.getSystemPrompt();
+            const tools = pi.getActiveTools();
+            const allTools = pi.getAllTools();
+            const activeToolDefs = allTools.filter(t => tools.includes(t.name));
+            const estimateTokens = (text) => Math.ceil(text.length / 4);
+            let msgTokensRaw = 0;
+            let toolUseTokensRaw = 0;
+            let toolResultTokensRaw = 0;
+            for (const entry of branch) {
+                if (entry.type === "message") {
+                    const m = entry.message;
+                    if (m.role === "user") {
+                        if (typeof m.content === "string")
+                            msgTokensRaw += estimateTokens(m.content);
+                        else if (Array.isArray(m.content)) {
+                            for (const p of m.content)
+                                if (p.type === "text")
+                                    msgTokensRaw += estimateTokens(p.text);
+                        }
+                    }
+                    else if (m.role === "assistant") {
+                        if (typeof m.content === "string")
+                            msgTokensRaw += estimateTokens(m.content);
+                        else if (Array.isArray(m.content)) {
+                            for (const p of m.content) {
+                                if (p.type === "text")
+                                    msgTokensRaw += estimateTokens(p.text);
+                                if (p.type === "toolCall")
+                                    toolUseTokensRaw += estimateTokens(JSON.stringify(p));
+                            }
+                        }
+                    }
+                    else if (m.role === "toolResult") {
+                        if (Array.isArray(m.content)) {
+                            for (const p of m.content)
+                                if (p.type === "text")
+                                    toolResultTokensRaw += estimateTokens(p.text);
+                        }
+                    }
+                    else if (m.role === "bashExecution") {
+                        toolUseTokensRaw += estimateTokens(m.command || "");
+                    }
+                }
+                else if (entry.type === "branch_summary" || entry.type === "compaction") {
+                    msgTokensRaw += estimateTokens(entry.summary || "");
+                }
+            }
+            const systemTokensRaw = estimateTokens(systemPrompt);
+            const toolDefTokensRaw = estimateTokens(JSON.stringify(activeToolDefs));
+            const totalActual = usage.tokens;
+            const limit = usage.contextWindow;
+            const totalRaw = systemTokensRaw + toolDefTokensRaw + msgTokensRaw + toolUseTokensRaw + toolResultTokensRaw;
+            const ratio = totalRaw > 0 ? (totalActual / totalRaw) : 1;
+            const systemTokens = Math.round(systemTokensRaw * ratio);
+            const toolDefTokens = Math.round(toolDefTokensRaw * ratio);
+            const msgTokens = Math.round(msgTokensRaw * ratio);
+            const toolUseTokens = Math.round(toolUseTokensRaw * ratio);
+            const toolResultTokens = Math.round(toolResultTokensRaw * ratio);
+            await ctx.ui.custom((tui, theme, kb, done) => {
+                const container = new Container();
+                container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+                container.addChild(new Text(theme.fg("accent", theme.bold(" Context Usage")), 1, 0));
+                container.addChild(new Spacer(1));
+                // Grouped by function and color
+                const categories = [
+                    { label: "System Prompt", value: systemTokens, color: "muted" },
+                    { label: "System Tools", value: toolDefTokens, color: "dim" },
+                    { label: "Tool Call", value: toolUseTokens + toolResultTokens, color: "success" },
+                    { label: "Messages", value: msgTokens, color: "accent" },
+                ];
+                const otherTokens = Math.max(0, totalActual - (systemTokens + toolDefTokens + msgTokens + toolUseTokens + toolResultTokens));
+                if (otherTokens > 10)
+                    categories.push({ label: "Other", value: otherTokens, color: "dim" });
+                categories.push({ label: "Available", value: Math.max(0, limit - totalActual), color: "borderMuted" });
+                const gridWidth = 10;
+                const gridHeight = 5;
+                const totalBlocks = gridWidth * gridHeight;
+                const blocks = [];
+                categories.forEach((cat) => {
+                    if (cat.label === "Available")
+                        return;
+                    let count = Math.round((cat.value / limit) * totalBlocks);
+                    if (count === 0 && cat.value > 0)
+                        count = 1;
+                    for (let i = 0; i < count && blocks.length < totalBlocks; i++) {
+                        blocks.push({ color: cat.color, filled: true });
+                    }
+                });
+                while (blocks.length < totalBlocks) {
+                    blocks.push({ color: "borderMuted", filled: false });
+                }
+                const gridLines = [];
+                for (let r = 0; r < gridHeight; r++) {
+                    let rowStr = "";
+                    for (let c = 0; c < gridWidth; c++) {
+                        const b = blocks[r * gridWidth + c];
+                        rowStr += theme.fg(b.color, b.filled ? "■ " : "□ ");
+                    }
+                    gridLines.push(rowStr.trimEnd());
+                }
+                const totalUsageTitle = `${theme.fg("text", theme.bold("Total Usage".padEnd(16)))} ${theme.fg("text", theme.bold(formatTokens(totalActual).padStart(7)))} ${theme.fg("text", theme.bold(`(${usage.percent.toFixed(1).padStart(5)}%)`))}`;
+                const catDetailLines = categories.map(cat => {
+                    const labelStr = cat.label.padEnd(14);
+                    const valStr = formatTokens(cat.value).padStart(7);
+                    const rowPercent = ((cat.value / limit) * 100).toFixed(1).padStart(5);
+                    const icon = cat.label === "Available" ? "□" : "■";
+                    return `${theme.fg(cat.color, icon)} ${theme.fg("text", labelStr)} ${theme.fg("accent", valStr)} (${rowPercent}%)`;
+                });
+                const allDetailLines = [totalUsageTitle, "", ...catDetailLines];
+                const leftSideWidth = 20;
+                const maxH = Math.max(gridLines.length, allDetailLines.length);
+                for (let i = 0; i < maxH; i++) {
+                    const left = (gridLines[i] || "").padEnd(leftSideWidth);
+                    const right = allDetailLines[i] || "";
+                    container.addChild(new Text(`    ${left}      ${right}`, 1, 0));
+                }
+                container.addChild(new Spacer(1));
+                container.addChild(new Text(theme.fg("dim", " Press any key to close"), 1, 0));
+                container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+                return {
+                    render: (w) => container.render(w),
+                    invalidate: () => container.invalidate(),
+                    handleInput: (data) => done(undefined),
+                };
+            }, { overlay: true });
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "agent-driven context management tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,13 +22,8 @@
   "type": "module",
   "author": "",
   "license": "MIT",
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
-  },
-  "dependencies": {
-    "@sinclair/typebox": "^0.34.13"
-  },
   "devDependencies": {
+    "@sinclair/typebox": "^0.34.13",
     "typescript": "^5.7.2",
     "@mariozechner/pi-coding-agent": "latest"
   },

package/skills/context-management/SKILL.md

@@ -5,92 +5,124 @@ description: Strategies for efficient context management using context_log, cont
 
 # Context Management
 
-**CRITICAL: THIS SKILL MANAGES YOUR MEMORY (CONVERSATION HISTORY), NOT THE USER'S FILES.**
+**CRITICAL: THIS SKILL MANAGES YOUR MEMORY. WITHOUT IT, YOU WILL FORGET.**
 
-Your context window is a limited resource. As the conversation grows, "pollution" (noise, failed attempts, intermediate logs) degrades your reasoning.
+Your context window is limited. As conversations grow, "pollution" (noise, failed attempts) degrades your reasoning.
 
-**CRITICAL: YOU ARE RESPONSIBLE FOR YOUR CONTEXT STRUCTURE.**
-**DO NOT WAIT FOR THE USER TO TELL YOU TO MANAGE CONTEXT.**
+**YOU MUST PROACTIVELY MANAGE YOUR HISTORY.**
+Do not wait for the user to tell you.
 
-You must proactively use these tools to keep your reasoning sharp and your history structured.
+## The Core Philosophy: Build, Perceive, Navigate
 
-**Use this skill to optimize your "Context Economy":**
-1.  **Structure (Save Points)**: Use `context_tag` to bookmark stable states. **Untagged progress is risky.** Always tag before a major step.
-2.  **Monitor (Awareness)**: Use `context_log` to check your "Usage" and "Segment Size". **Don't fly blind.** High usage degrades your reasoning.
-3.  **Compress (Hygiene)**: Use `context_checkout` to squash history. **Finished tasks are noise.** Summarize them to reclaim memory.
-
-## The Context Dashboard
-
-Call `context_log` to see your status. It provides a **HUD** (Health Metrics) and a **Graph** (Map).
-
-### 1. The HUD (Health)
-```text
-• Context Usage:    85% (108k/128k)
-• Segment Size:     84 steps since last tag
 ```
+Context Window = RAM (Expensive, volatile, limited)
+Context Graph  = Disk (Cheap, persistent, unlimited)
 
-### 2. The Graph (Map)
-The log tree shows where you are and where you've been.
-```text
-| 1a2b3c4 (ROOT, tag: start) [USER] Start the project.
-| ... (50 hidden messages) ...
-| f9e8d7c (tag: task-a-done) [SUMMARY] Task A completed.
-| ... (5 hidden messages) ...
-* a1b2c3d (HEAD, tag: task-b-start) [AI] I have switched to Task B.
+→ Move finished tasks from RAM to the Graph.
 ```
-- **`*` (Asterisk)**: Your current location (HEAD).
-- **`... (hidden)`**: Low-value steps (thinking/tools) are auto-collapsed.
-- **`tag: name`**: Safe checkpoints to jump back to.
-- **`[SUMMARY]`**: A compressed history node (squashed context).
 
-## Decision Framework: When to Act?
-
-### 1. Resource Perspective (The Dashboard)
-*Check the `context_log` HUD.*
-
-| Signal | Diagnosis | Prescription |
+Manage your context window like a Git repository. You are the maintainer.
+
+1.  **BUILD the Skeleton (`context_tag`)**:
+    *   Raw conversation is a flat list. **Tags create structure.**
+    *   Without tags, `context_log` is just a list of IDs. With tags, it is a **Map**.
+2.  **PERCEIVE the State (`context_log`)**:
+    *   Check the HUD: Is "Segment Size" too big? You are drifting.
+    *   Check the Graph: Where are you? Are you in a deep branch?
+3.  **NAVIGATE & MERGE (`context_checkout`)**:
+    *   **Squash:** Convert a messy "feature branch" (thinking process) into a single "merge commit" (summary).
+    *   **Jump:** Move between tasks or retry paths without carrying baggage.
+
+## Quick Start: The Loop
+
+Follow this cycle for every major task:
+
+1.  **CHECK:** Verify state.
+    `context_log`
+2.  **START:** Tag the beginning.
+    `context_tag({ name: "task-start" })`
+3.  **WORK:** Execute steps.
+4.  **MILESTONE:** Tag intermediate stable states (e.g., "Plan done", "Part 1 done").
+    `context_tag({ name: "task-plan-done" })`
+5.  **SQUASH (Autonomous):** If history becomes noisy or low-density, **Squash with Backup**.
+    *   *Action:* `context_checkout({ target: "task-start", message: "Summarized debugging steps...", backupTag: "pre-squash-backup" })`
+    *   *Action (Optional):* `context_tag({ name: "clean-state" })`
+    *   *Safety:* If you need the details later, you can checkout `pre-squash-backup`.
+
+## Tool Reference
+
+| Tool | Analog | Purpose | When to Use |
+| :--- | :--- | :--- | :--- |
+| `context_tag` | `git tag` | Bookmark a stable state. | Before risky changes. Before starting a new task. |
+| `context_log` | `git log` | See where you are. | When you feel lost. To find IDs for checkout. |
+| `context_checkout`| `git reset --soft` | **Time Travel / Squash.** | To undo mistakes. To compress history. |
+
+## Critical Rules
+
+### Tag Wisely (Build The Skeleton)
+Tags are the "Table of Contents". Use them to mark **Start** and **Backups**.
+*   **Start:** `task-start`
+*   **Backup:** `task-raw-history` (Created automatically by `backupTag`)
+*   **Milestone:** `phase-1-done`
+
+
+### Squash Noise, Keep Signal, Focus on Goal (Context Hygiene)
+Think of your conversation as a "Feature Branch" full of messy thoughts.
+**You must distinguish Signal from Noise.**
+
+*   **Signal (High Value):** Design decisions, user constraints, final working code. -> **KEEP.**
+*   **Noise (Low Value):** Failed attempts, long tool outputs, "thinking" steps. -> **SQUASH.**
+*   **Focus on Goal:** Ask yourself: "Does this message help me achieve the current goal?" -> **KEEP.**
+
+**When to Squash:**
+1.  **Task Done:** Convert the messy process into one clean summary.
+2.  **Low Density:** You read 2000 lines but only found 1 error.
+
+**Safety:** Squashing is **LOSSLESS**.
+By using `backupTag`, you save the "Messy Branch" forever. You can always checkout the backup tag if the summary isn't enough.
+*   **Main Trunk:** Jump back to the summary.
+*   **Backup Tag:** Jump back to the raw details.
+
+### Fail Fast, Revert Faster
+If you fail 3 times:
+1.  **STOP.** Don't try a 4th time.
+2.  `context_checkout` back to the last safe tag.
+3.  Summarize the failure in the checkout message ("Tried X, failed because Y").
+4.  Try a new approach from the clean state.
+
+## Decision Matrix: When to Act
+
+| Situation | Action | Reason |
 | :--- | :--- | :--- |
-| **Usage > 50%** | **ATTENTION DECAY**: Recall fades, instruction adherence drops, and reasoning quality suffers. | **COMPRESS**: `context_checkout({ target: "task-start", message: "Consolidated progress...", tagName: "clean-up" })` |
-| **Segment > 10** | **LINEAR FATIGUE**: Hard to distinguish signal from noise in long threads. | **TAG**: `context_tag({ name: "safe-point" })` |
-| **Reading Huge Files / Web Search** | **LOW INFO DENSITY**: You read 500 lines but only need 5 lines. | **EXTRACT & REWIND**: `context_checkout({ target: "pre-read", message: "File content summary: [Key Configs...]", tagName: "extracted-info" })` |
+| **Starting Task** | `context_tag({ name: "task-X-start" })` | Create a rollback point. |
+| **Research / Logs** | `context_checkout` (Squash) | **Process is Noise.** Read 2000 lines -> Keep result. |
+| **Messy Debugging** | **Squash w/ Backup** | **Cleanup.** The error logs are noise once fixed. |
+| **Task Done (Candidate)**| **Squash w/ Backup** | **Assume Success.** Summary is usually enough. Backup exists if not. |
+| **Goal Shift** | `context_checkout` (Squash) | Old context is irrelevant. |
+| **Drift (some steps w/o tag)** | **Tag (Milestone)** | Maintain the skeleton. Don't fly blind. |
 
-### 2. Task Perspective (The Workflow)
-*Reflect on your current progress.*
+## The "Context Health" Check
 
-| Signal | Diagnosis | Prescription |
-| :--- | :--- | :--- |
-| **"I tried 3 times and failed"** | **POISONED CONTEXT**: Previous failures bias future attempts and eat up token budget. | **BACKTRACK**: `context_checkout({ target: "last-working-tag", message: "Approach A failed..." })` |
-| **"I think I finished the task"** | **PENDING**: User might ask for tweaks. | **TAG ONLY**: `context_tag({ name: "feature-x-candidate" })`. **Do not squash yet.** |
-| **"User starts a NEW task"** | **SAFE TO CLOSE**: Old context is now clutter. | **SQUASH**: `context_checkout({ target: "root", message: "Prev task done. Summary...", tagName: "clean-slate" })` |
+If you cannot answer these, run `context_log`:
 
-## Workflow Best Practices
+| Question | Answer Source |
+| :--- | :--- |
+| **Where is the skeleton?** | The sequence of `tag`s in the log. |
+| **Is this history useful?** | If "No" -> **SQUASH IT.** |
+| **Am I in a loop?** | Repeated entries in the graph. |
 
-### 1. Build the ToC (`context_tag`)
-Don't just work blindly. Tag your milestones so you (and the user) can see the structure.
-- *Good*: `start` -> `plan-v1` -> `impl-v1` -> `test-pass`
-- *Bad*: `start` -> (100 messages) -> `done`
 
-### 2. View the Map (`context_log`)
-Check where you are and how expensive the path is.
-- Use `verbose: false` (default) to see the high-level "ToC" (Milestones).
-
-### 3. Squash & Merge (`context_checkout`)
-**This is your Garbage Collector.** Use it to delete low-value history but keep high-value insights.
-
-> **CRITICAL REMINDER: CONTEXT IS NOT CODEBASE**
-> Checking out a new context branch **DOES NOT DELETE FILES**. It only resets your *conversation memory*. Your code on disk is safe.
-
-**Checkout Messages**
+## Good Checkout Messages
 
 The `message` is your lifeline to your past self.
 A good message preserves critical context that would otherwise be lost.
 
-Structure: `[Status] + [Reason] + [Important Changes] + [Carryover Data]`
+Structure: `[Status] + [Reason] + [Carryover Data] + [Important Changes]`
 
 *   **Status**: What did you just finish or stop doing?
 *   **Reason**: Why are you branching/moving? (e.g., "Too much noise", "Task complete", "Failed attempt")
+*   **Carryover**: What specific details (e.g., IDs, file paths, user constraints) must be remembered?
 *   **Important Changes**: What files or logic have been modified? (This checkout only resets *conversation history*, NOT disk files, so you must remember what changed.)
-*   **Carryover**: What specific details (IDs, file paths, user constraints) must be remembered?
 
 Examples:
 
@@ -99,82 +131,89 @@ Examples:
 *   *Bad*: "Switching context." (Too vague - you will forget why)
 *   *Bad*: "Done." (What is done? What did we learn?)
 
-**Safety Net (Undo Button):**
-`context_checkout` is non-destructive. If you squash too much, use `context_log` to find the old branch ID and checkout back to it.
+## Anti-Patterns
 
-**Checkout Failures**
-If `context_checkout` fails with "Target not found":
-1.  Run `context_log` immediately to see available commit IDs and tags.
-2.  Select a valid ID from the log.
-3.  Retry the checkout.
+| Don't | Do Instead |
+| :--- | :--- |
+| **Blind Tagging** (Tagging without looking) | **Check** (`context_log`) to avoid duplicates or tagging noise. |
+| **Over-Tagging** (Tagging every step) | **Tag** only major phase changes (`start`, `milestone`). |
+| **Hoard** (Keep all history "just in case") | **Squash** low-density history (research, logs). |
+| **Panic** (Apologize repeatedly for errors) | **Revert** (`context_checkout`) to before the error. |
+| **Blind Checkout** (Guessing IDs) | **Look** (`context_log`) first to get valid IDs. |
+| **Vague Summaries** ("Done", "Fixed") | **Detailed Summaries** ("Found bug in line 40. Fixed with patch X.") |
 
-## Scenarios
+## Recipes (Copy-Paste)
 
-**Scenario: Task Complete & Confirmed**
-You finished Feature A. **Wait for user confirmation.**
-*User*: "Looks good. Now let's work on Feature B."
-*Reasoning*: Feature A details are now noise. Feature B needs a clean slate.
+### 1. The "Miner" (Immediate Squash)
+**Goal:** Pure information gathering (Reading files, Searching web).
+**Why:** The *process* of searching is irrelevant. Only the *result* matters.
 
 ```javascript
-// 1. Tag the raw history (just in case)
-context_tag({ name: "feature-a-raw" });
+// 1. Tag BEFORE starting the noisy work
+context_tag({ name: "pre-research" });
+
+// ... (Read 5 files, search 3 sites, find 1 key fact) ...
 
-// 2. Squash to Root (or previous milestone)
+// 2. Squash IMMEDIATELY. Do not wait for user.
 context_checkout({
-  target: "root", // or "project-start"
-  message: "Feature A completed. All tests passed. Key files created: X, Y, Z.",
-  tagName: "feature-a-done"
+  target: "pre-research",
+  message: "Researched logs. Found root cause: DB timeout. Irrelevant logs discarded.",
+  backupTag: "raw-research-logs" // Safety backup
 });
+context_tag({ name: "research-done" });
 ```
-*Result*: You are now at a clean state with just the summary of Feature A. Cost dropped from 50 msgs to 1 msg.
 
-**Scenario: Pivot / Retry**
-You tried approach A and it failed 5 times (Pollution).
-*Solution*: Backtrack and summarize the failure.
+### 2. The "Candidate" (Wait for Confirmation)
+**Goal:** You finished a complex task.
+**Why:** The history is noisy. The result is clean.
+**Safety:** We create a backup tag automatically.
 
 ```javascript
-// Return to the state BEFORE the failed attempts
+// Squash to Summary (Optimistic Cleanup)
 context_checkout({
-  target: "task-start", 
-  message: "Approach A failed due to library incompatibility. Context clean. Starting Approach B.",
-  tagName: "retry-approach-b"
+  target: "feature-a-start", // Squash range: Start -> Now
+  message: "Feature A implemented. 5 files changed. Tests passed. Revert to 'feature-a-raw-history' for full logs.",
+  backupTag: "feature-a-raw-history"
 });
+context_tag({ name: "feature-a-candidate" });
 ```
 
-**Scenario: Data Extraction / Research**
-You read a huge file (e.g., 2000 lines) or searched the web, but only found 3 relevant lines.
-*Problem*: The context is now polluted with 1997 lines of noise.
-*Solution*: Send the 3 lines back to your past self.
+### 3. The "Undo" (Revert Squash)
+**Goal:** User asks about a detail you squashed away.
+**Action:** Jump back to the backup tag.
 
 ```javascript
-// 1. Tag BEFORE you start reading/searching (proactive)
-context_tag({ name: "pre-research" });
+// Jump back to the raw history
+context_checkout({
+  target: "feature-a-raw-history",
+  message: "Reverting to raw history to check specific error logs."
+});
+context_tag({ name: "restored-history" });
+```
 
-// ... (You read the huge file and find the key config) ...
+### 4. Branching (Alternative Approach)
+**Scenario:** Method A failed (and was squashed). You want to try Method B from the clean state.
+**Action:** Checkout the start point.
 
-// 2. Checkout back to the tag, bringing ONLY the key info
+```javascript
+// Jump back to start
 context_checkout({
-  target: "pre-research",
-  message: "Found the key configuration in line 150: 'MAX_CONNECTIONS=5'. The rest of the file was irrelevant.",
-  tagName: "research-complete"
+  target: "task-start", 
+  message: "Method A failed (see summary in 'method-a-fail'). Starting Method B from clean state."
 });
+context_tag({ name: "method-b-start" });
 ```
-*Result*: Your context now contains the prompt, the tag, and the single message with the key config. The 2000 lines of noise are gone.
 
-**Scenario: Code Fix / "Time Travel" Debugging**
-You wrote code, it failed, you fixed it after 10 tries.
-*Problem*: Context has 10 failed attempts and error logs.
-*Solution*: Send the *final working code* back to the moment before you started coding.
+### 5. The "Undo" (Failed Attempt)
+You tried to fix a bug but broke everything.
+**Goal:** Clean up a failed path.
 
 ```javascript
-// 1. You realize you are in a messy debug loop.
-// 2. You finally get the code working.
-// 3. Checkout back to BEFORE you started the implementation.
-
+// Jump back to safety.
 context_checkout({
-  target: "impl-start", 
-  message: "Implementation successful. Here is the working code: \n```javascript\n...\n```\nSkipped the debugging steps.",
-  tagName: "impl-done"
+  target: "pre-debug-tag",
+  message: "Attempted fix using Method A failed. Error: 'Timeout'.",
+  backupTag: "failed-attempt-1" // Save the failure just in case
 });
+context_tag({ name: "debug-retry" });
 ```
-*Result*: It looks like you got it right on the first try. Context is clean and focused.

package/src/index.ts

@@ -27,7 +27,7 @@ const ContextLogParams = Type.Object({
 const ContextCheckoutParams = Type.Object({
   target: Type.String({ description: "Where to jump/squash to. Can be a tag name (e.g., 'task-start'), a commit ID, or 'root'. This is the base for your new branch." }),
   message: Type.String({ description: "The 'Carryover Message' for the new branch. A summary of your *current* progress/lessons that you want to bring with you to the new state. This ensures you don't lose key information when switching contexts. Good summary message: '[Status] + [Reason] + [Important Changes] + [Carryover Data]'" }),
-  tagName: Type.Optional(Type.String({ description: "Optional tag name to apply to the target state immediately after checking out." })),
+  backupTag: Type.Optional(Type.String({ description: "Optional tag name to apply to the CURRENT state before checking out. Use this to create an automatic backup of the history you are about to leave/squash." })),
 });
 
 const ContextTagParams = Type.Object({
@@ -35,7 +35,7 @@ const ContextTagParams = Type.Object({
   target: Type.Optional(Type.String({ description: "The commit ID to tag. Defaults to HEAD (current state)." })),
 });
 
-const isInternal = (name: string) => ["context_log", "context_checkout", "context_tag"].includes(name);
+const isInternal = (name: string) => ["context_tag", "context_log", "context_checkout"].includes(name);
 
 const resolveTargetId = (sm: SessionManager, target: string): string => {
   if (target.toLowerCase() === "root") {
@@ -62,6 +62,55 @@ const formatTokens = (n: number) => {
 };
 
 export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "context_tag",
+    label: "Context Tag",
+    description: "Creates a 'Save Point' (Bookmark) in the history. Use this before trying risky changes or when a feature is stable. 'Untagged progress is risky'.",
+    parameters: ContextTagParams,
+    async execute(_id, params: Static<typeof ContextTagParams>, _signal, _onUpdate, ctx) {
+      const sm = ctx.sessionManager as SessionManager;
+      let id = params.target ? resolveTargetId(sm, params.target) : undefined;
+
+      if (!id) {
+        // Auto-resolve: Find the last "interesting" node to tag.
+        // We skip ToolResults (which look ugly tagged) and internal-only Assistant messages (which look empty).
+        const branch = sm.getBranch();
+        for (let i = branch.length - 1; i >= 0; i--) {
+          const entry = branch[i];
+
+          // 1. Check ToolResults
+          if (entry.type === 'message' && entry.message.role === 'toolResult') {
+            const tr = entry.message as any;
+            if (isInternal(tr.toolName)) continue;
+
+            // Public tool result is a valid target
+            id = entry.id;
+            break;
+          }
+
+          // 2. Check Assistant messages for visibility
+          if (entry.type === 'message' && entry.message.role === 'assistant') {
+            const m = entry.message;
+            const hasInternalTool = m.content.some(c => c.type === 'toolCall' && isInternal(c.name));
+
+            if (!hasInternalTool) {
+              id = entry.id;
+              break;
+            }
+          }
+
+          id = entry.id;
+          break;
+        }
+        // Fallback to leaf if search failed
+        if (!id) id = sm.getLeafId() ?? "";
+      }
+
+      pi.setLabel(id, params.name);
+      return { content: [{ type: "text", text: `Created tag '${params.name}' at ${id}` }], details: {} };
+    },
+  });
+
   pi.registerTool({
     name: "context_log",
     label: "Context Log",
@@ -69,28 +118,25 @@ export default function (pi: ExtensionAPI) {
     parameters: ContextLogParams,
     async execute(_id, params: Static<typeof ContextLogParams>, _signal, _onUpdate, ctx) {
       const sm = ctx.sessionManager as SessionManager;
-      const tree = sm.getTree();
+      const branch = sm.getBranch();
       const currentLeafId = sm.getLeafId();
       const verbose = params.verbose ?? false;
       const limit = params.limit ?? 50;
 
-      const parents = new Map<string, string>();
-      const entryMap = new Map<string, SessionEntry>();
-      const childrenMap = new Map<string, SessionEntry[]>();
-
-      const walk = (nodes: SessionTreeNode[], pId?: string) => {
-        for (const n of nodes) {
-          entryMap.set(n.entry.id, n.entry);
-          if (pId) {
-            parents.set(n.entry.id, pId);
-            const siblings = childrenMap.get(pId) || [];
-            siblings.push(n.entry);
-            childrenMap.set(pId, siblings);
+      const backboneIds = new Set(branch.map((e) => e.id));
+      const sequence: SessionEntry[] = [];
+
+      branch.forEach((entry) => {
+        sequence.push(entry);
+
+        // Preserve side-summary logic: Show branch summaries/compactions that are off-path
+        const children = sm.getChildren(entry.id);
+        children.forEach((child) => {
+          if ((child.type === "branch_summary" || child.type === "compaction") && !backboneIds.has(child.id)) {
+            sequence.push(child);
           }
-          walk(n.children, n.entry.id);
-        }
-      };
-      walk(tree);
+        });
+      });
 
       const getMsgContent = (entry: SessionEntry): string => {
         if (entry.type === "branch_summary" || entry.type === "compaction") {
@@ -157,40 +203,22 @@ export default function (pi: ExtensionAPI) {
         return "";
       };
 
-      const backboneIds: string[] = [];
-      let currId: string | undefined = currentLeafId ?? undefined;
-      while (currId) {
-        backboneIds.unshift(currId);
-        currId = parents.get(currId);
-      }
-
-      const sequence: SessionEntry[] = [];
-      backboneIds.forEach((id) => {
-        const entry = entryMap.get(id);
-        if (!entry) return;
-        sequence.push(entry);
-        const children = childrenMap.get(id) || [];
-        children.forEach((child) => {
-          if ((child.type === "branch_summary" || child.type === "compaction") && !backboneIds.includes(child.id)) {
-            sequence.push(child);
-          }
-        });
-      });
-
       const isInteresting = (entry: SessionEntry): boolean => {
         // 1. HEAD and Root
         if (entry.id === currentLeafId) return true;
-        if (!parents.has(entry.id)) return true;
+        if (branch.length > 0 && entry.id === branch[0].id) return true;
 
         // 2. Explicit Tags (Labels) - Only show the TAGGED node, not the label node itself
         if (sm.getLabel(entry.id)) return true;
         if (entry.type === 'label') return false; // Hide label nodes, they are redundant
 
-        // 3. Structural Milestones (Summaries, Forks)
+        // 3. Structural Milestones (Summaries)
         if (entry.type === 'branch_summary' || entry.type === 'compaction') return true;
-        if ((childrenMap.get(entry.id)?.length ?? 0) > 1) return true;
 
-        // 4. Natural Milestones (User Messages) - This is the key auto-tagging mechanism
+        // 4. Branch Points (Forks)
+        if (sm.getChildren(entry.id).length > 1) return true;
+
+        // 5. Natural Milestones (User Messages) - This is the key auto-tagging mechanism
         if (entry.type === 'message' && entry.message.role === 'user') return true;
 
         return false;
@@ -243,8 +271,8 @@ export default function (pi: ExtensionAPI) {
           role = "SUMMARY";
         }
 
-        const id = entry.id.slice(0, 8);
-        const isRoot = !parents.has(entry.id);
+        const id = entry.id;
+        const isRoot = branch.length > 0 && entry.id === branch[0].id;
         const meta = [isRoot ? "ROOT" : null, isHead ? "HEAD" : null, label ? `tag: ${label}` : null].filter(Boolean).join(", ");
 
         const body = content.length > 100 ? content.slice(0, 100) + "..." : content;
@@ -259,9 +287,6 @@ export default function (pi: ExtensionAPI) {
       }
 
       // --- Context Dashboard (HUD) ---
-      const totalNodes = entryMap.size;
-      const currentDepth = backboneIds.length;
-
       const usage = await ctx.getContextUsage();
       let usageStr = "Unknown";
       if (usage) {
@@ -271,8 +296,8 @@ export default function (pi: ExtensionAPI) {
       // Find the distance to the nearest tag
       let stepsSinceTag = 0;
       let nearestTagName = "None";
-      for (let i = backboneIds.length - 1; i >= 0; i--) {
-        const id = backboneIds[i];
+      for (let i = branch.length - 1; i >= 0; i--) {
+        const id = branch[i].id;
         const label = sm.getLabel(id);
         if (label) {
           nearestTagName = label;
@@ -299,40 +324,26 @@ export default function (pi: ExtensionAPI) {
     parameters: ContextCheckoutParams,
     async execute(_id, params: Static<typeof ContextCheckoutParams>, _signal, _onUpdate, ctx) {
       const sm = ctx.sessionManager as SessionManager;
+
       const tid = resolveTargetId(sm, params.target);
 
       const currentLeaf = sm.getLeafId();
       if (currentLeaf === tid) {
-        return { content: [{ type: "text", text: `Already at target ${tid.slice(0, 7)}` }], details: {} };
+        return { content: [{ type: "text", text: `Already at target ${tid}` }], details: {} };
+      }
+      if (params.backupTag && currentLeaf) {
+        pi.setLabel(currentLeaf, params.backupTag);
       }
-
       const currentLabel = currentLeaf ? sm.getLabel(currentLeaf) : undefined;
-      const origin = currentLabel ? `tag: ${currentLabel}` : (currentLeaf ? currentLeaf.slice(0, 8) : "unknown");
+      const origin = currentLabel ? `tag: ${currentLabel}` : (currentLeaf || "unknown");
 
-      const enrichedMessage = `${params.message} (branched from ${origin})`;
+      const enrichedMessage = `(summary from ${origin})\n${params.message}`;
       await sm.branchWithSummary(tid, enrichedMessage);
 
-      // Fix: Label the NEW leaf (the summary node or the checkout target), not necessarily the old target ID.
-      // This ensures 'tagName' acts like naming the NEW branch tip.
-      const newLeaf = sm.getLeafId();
-      if (params.tagName && newLeaf) pi.setLabel(newLeaf, params.tagName);
-
-      return { content: [{ type: "text", text: `Checked out ${tid.slice(0, 7)}` }], details: {} };
+      return { content: [{ type: "text", text: `Checked out ${tid}\nBackup tag created: ${params.backupTag || "none"}\nmessage: ${enrichedMessage}` }], details: {} };
     },
   });
 
-  pi.registerTool({
-    name: "context_tag",
-    label: "Context Tag",
-    description: "Creates a 'Save Point' (Bookmark) in the history. Use this before trying risky changes or when a feature is stable. 'Untagged progress is risky'.",
-    parameters: ContextTagParams,
-    async execute(_id, params: Static<typeof ContextTagParams>, _signal, _onUpdate, ctx) {
-      const sm = ctx.sessionManager as SessionManager;
-      const id = params.target ? resolveTargetId(sm, params.target) : (sm.getLeafId() ?? "");
-      pi.setLabel(id, params.name);
-      return { content: [{ type: "text", text: `Created tag '${params.name}' at ${id.slice(0, 7)}` }], details: {} };
-    },
-  });
 
   pi.registerCommand("context", {
     description: "Show context usage visualization",