pi-context 1.1.3 → 2.0.0-beta.0

package/src/index.ts

@@ -2,14 +2,15 @@ import {
     type ExtensionAPI,
     type SessionManager,
     type SessionEntry,
-} from "@mariozechner/pi-coding-agent";
-import type {
-    TextContent,
-    ImageContent,
-    ToolCall,
-} from "@mariozechner/pi-ai";
-import { Type, type Static } from "@sinclair/typebox";
-import { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+    type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import {
+    Type,
+    type Static,
+    type TextContent,
+    type ImageContent,
+    type ToolCall,
+} from "@earendil-works/pi-ai";
 import { formatTokens } from "./utils.js";
 
 // Define missing types locally as they are not exported from the main entry point
@@ -19,9 +20,9 @@ interface SessionTreeNode {
     label?: string;
 }
 
-const InternalTools = ["context_tag", "context_log", "context_checkout"];
+const InternalTools = ["context_checkpoint", "context_timeline", "context_rewind"];
 let CommandCtx: ExtensionCommandContext | null = null;
-let CheckoutParams: any = null;
+let RewindParams: any = null;
 
 const isInternal = (name: string) => InternalTools.includes(name);
 
@@ -46,20 +47,20 @@ const resolveTargetId = (sm: SessionManager, target: string): string => {
     return target;
 };
 
-const ContextLogParams = Type.Object({
+const ContextTimelineParams = 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." })),
+    verbose: Type.Optional(Type.Boolean({ description: "If true, show all messages. If false (default), collapse intermediate AI steps and only show milestones, user messages, checkpoints, 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 ContextRewindParams = Type.Object({
+    target: Type.String({ description: "Where to rewind or compact to. Can be a checkpoint name, a history node ID, or root. This becomes the starting point for a fresh continuation of the conversation." }),
+    message: Type.String({ description: "The carryover summary for the fresh continuation. Summarize current progress, lessons, important file changes, and the next step so the agent can continue from a clean context. A good summary message includes status, reason, important changes, and next step." }),
+    backupCheckpoint: Type.Optional(Type.String({ description: "Optional checkpoint name to apply to the current conversation state before rewinding. Use this to preserve a named backup of the noisy path you are about to compact away." })),
 });
 
-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 ContextCheckpointParams = Type.Object({
+    name: Type.String({ description: "The checkpoint or milestone name. Use meaningful names." }),
+    target: Type.Optional(Type.String({ description: "Optional history node ID or checkpoint name to label. Defaults to the current conversation position." })),
 });
 
 export default function (pi: ExtensionAPI) {
@@ -81,31 +82,38 @@ export default function (pi: ExtensionAPI) {
         }
     });
 
-    // Helper: Check if a tag name already exists in the tree
-    const findTagInTree = (sm: SessionManager, nodes: SessionTreeNode[], tagName: string): string | null => {
-        for (const n of nodes) {
-            if (sm.getLabel(n.entry.id) === tagName) return n.entry.id;
-            const r = findTagInTree(sm, n.children, tagName);
-            if (r) return r;
+    // Helper: Check if a checkpoint name already exists in the tree
+    // Iterative DFS to avoid call stack overflows on deep histories.
+    // Push children in reverse order to preserve left-to-right pre-order semantics.
+    const findCheckpointInTree = (sm: SessionManager, nodes: SessionTreeNode[], checkpointName: string): string | null => {
+        const stack: SessionTreeNode[] = [...nodes].reverse();
+        while (stack.length > 0) {
+            const n = stack.pop()!;
+            if (sm.getLabel(n.entry.id) === checkpointName) return n.entry.id;
+            if (n.children?.length) {
+                for (let i = n.children.length - 1; i >= 0; i--) {
+                    stack.push(n.children[i]);
+                }
+            }
         }
         return null;
     };
 
     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) {
+        name: "context_checkpoint",
+        label: "Context Checkpoint",
+        description: "Create a named checkpoint in the conversation history. Use this before risky work, before a long research pass, or whenever you reach a stable milestone.",
+        parameters: ContextCheckpointParams,
+        async execute(_id, params: Static<typeof ContextCheckpointParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
 
-            // Deduplication check: ensure tag name is unique
-            const existingTagId = findTagInTree(sm, sm.getTree(), params.name);
-            if (existingTagId) {
+            // Deduplication check: ensure checkpoint name is unique
+            const existingCheckpointId = findCheckpointInTree(sm, sm.getTree(), params.name);
+            if (existingCheckpointId) {
                 return {
                     content: [{
                         type: "text",
-                        text: `Error: Tag '${params.name}' already exists at ${existingTagId}. Tag names must be unique. Use a different name or delete the existing tag first.`
+                        text: `Error: Checkpoint '${params.name}' already exists at ${existingCheckpointId}. Checkpoint names must be unique. Use a different name or remove the existing one first.`
                     }],
                     details: {}
                 };
@@ -114,8 +122,8 @@ export default function (pi: ExtensionAPI) {
             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).
+                // Auto-resolve: Find the last interesting node to checkpoint.
+                // We skip ToolResults that look awkward when checkpointed and internal-only assistant messages that look empty.
                 const branch = sm.getBranch();
                 for (let i = branch.length - 1; i >= 0; i--) {
                     const entry = branch[i];
@@ -149,16 +157,16 @@ export default function (pi: ExtensionAPI) {
             }
 
             pi.setLabel(id, params.name);
-            return { content: [{ type: "text", text: `Created tag '${params.name}' at ${id}` }], details: {} };
+            return { content: [{ type: "text", text: `Created checkpoint '${params.name}' at ${id}` }], 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: Static<typeof ContextLogParams>, _signal, _onUpdate, ctx) {
+        name: "context_timeline",
+        label: "Context Timeline",
+        description: "Show the conversation timeline, checkpoints, summaries, and current position. Use this to understand session structure, monitor drift, and choose a checkpoint to return to.",
+        parameters: ContextTimelineParams,
+        async execute(_id, params: Static<typeof ContextTimelineParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
             const branch = sm.getBranch();
             const currentLeafId = sm.getLeafId();
@@ -186,7 +194,7 @@ export default function (pi: ExtensionAPI) {
                     return e.summary || "[No summary provided]";
                 }
                 if (entry.type === "label") {
-                    return `tag: ${entry.label}`;
+                    return `checkpoint: ${entry.label}`;
                 }
 
                 if (entry.type === "message") {
@@ -250,7 +258,7 @@ export default function (pi: ExtensionAPI) {
                 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
+                // 2. Explicit checkpoints (labels) - only show the checkpointed 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
 
@@ -320,7 +328,7 @@ export default function (pi: ExtensionAPI) {
 
                 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 meta = [isRoot ? "ROOT" : null, isHead ? "HEAD" : null, label ? `checkpoint: ${label}` : null].filter(Boolean).join(", ");
 
                 const body = content.length > 100 ? content.slice(0, 100) + "..." : content;
 
@@ -336,27 +344,27 @@ export default function (pi: ExtensionAPI) {
             // --- Context Dashboard (HUD) ---
             const usage = await ctx.getContextUsage();
             let usageStr = "Unknown";
-            if (usage) {
+            if (usage?.percent != null && usage.tokens != null && usage.contextWindow != null) {
                 usageStr = `${usage.percent.toFixed(1)}% (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
             }
 
-            // Find the distance to the nearest tag
-            let stepsSinceTag = 0;
-            let nearestTagName = "None";
+            // Find the distance to the nearest checkpoint
+            let stepsSinceCheckpoint = 0;
+            let nearestCheckpointName = "None";
             for (let i = branch.length - 1; i >= 0; i--) {
                 const id = branch[i].id;
                 const label = sm.getLabel(id);
                 if (label) {
-                    nearestTagName = label;
+                    nearestCheckpointName = label;
                     break;
                 }
-                stepsSinceTag++;
+                stepsSinceCheckpoint++;
             }
 
             const hud = [
                 `[Context Dashboard]`,
                 `• Context Usage:    ${usageStr}`,
-                `• Segment Size:     ${stepsSinceTag} steps since last tag '${nearestTagName}'`,
+                `• Segment Size:     ${stepsSinceCheckpoint} steps since last checkpoint '${nearestCheckpointName}'`,
                 `---------------------------------------------------`
             ].join("\n");
 
@@ -365,11 +373,11 @@ export default function (pi: ExtensionAPI) {
     });
 
     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: Static<typeof ContextCheckoutParams>, _signal, _onUpdate, ctx) {
+        name: "context_rewind",
+        label: "Conversation Rewind",
+        description: "Return to an earlier conversation checkpoint and start a fresh continuation with a carryover summary. This changes session history only and does not modify disk files. Always provide a detailed message.",
+        parameters: ContextRewindParams,
+        async execute(_id, params: Static<typeof ContextRewindParams>, _signal, _onUpdate, ctx) {
             if (!CommandCtx) {
                 ctx.ui.setEditorText(`/acm ${ctx.ui.getEditorText() || "continue"}`)
                 return {
@@ -388,49 +396,49 @@ export default function (pi: ExtensionAPI) {
             if (currentLeaf === tid) {
                 return { content: [{ type: "text", text: `Already at target ${tid}` }], details: {} };
             }
-            if (params.backupTag && currentLeaf) {
-                pi.setLabel(currentLeaf, params.backupTag);
+            if (params.backupCheckpoint && currentLeaf) {
+                pi.setLabel(currentLeaf, params.backupCheckpoint);
             }
             const currentLabel = currentLeaf ? sm.getLabel(currentLeaf) : undefined;
-            const origin = currentLabel ? `tag: ${currentLabel}` : (currentLeaf || "unknown");
+            const origin = currentLabel ? `checkpoint: ${currentLabel}` : (currentLeaf || "unknown");
 
             const enrichedMessage = `(summary from ${origin})\n${params.message}`;
 
             const nid = await sm.branchWithSummary(tid, enrichedMessage);
-            CheckoutParams = params;
-            CheckoutParams.nid = nid;
-            CheckoutParams.tid = tid;
-            CheckoutParams.enrichedMessage = enrichedMessage;
+            RewindParams = params;
+            RewindParams.nid = nid;
+            RewindParams.tid = tid;
+            RewindParams.enrichedMessage = enrichedMessage;
 
-            return { content: [{ type: "text", text: "checkout start" }], details: {} };
+            return { content: [{ type: "text", text: "rewind start" }], details: {} };
         },
     });
 
-    pi.on("turn_end", async (event, ctx) => {
-        if (!CheckoutParams) {
+    pi.on("turn_end", async (_event, ctx) => {
+        if (!RewindParams) {
             return
         }
         ctx.abort()
     });
 
     pi.on("agent_end", async (_event, ctx) => {
-        if (!CheckoutParams) {
+        if (!RewindParams) {
             return
         }
         if (!CommandCtx) {
             return
         }
 
-        await CommandCtx.navigateTree(CheckoutParams.nid, {
+        await CommandCtx.navigateTree(RewindParams.nid, {
             summarize: false,
         });
 
-        ctx.ui.notify(`Checked out ${CheckoutParams.target}${CheckoutParams.target === CheckoutParams.tid ? "" : `(${CheckoutParams.tid})`}\nBackup tag created: ${CheckoutParams.backupTag || "none"}\nmessage: ${CheckoutParams.enrichedMessage}`, "info");
-        CheckoutParams = null;
+        ctx.ui.notify(`Rewound to ${RewindParams.target}${RewindParams.target === RewindParams.tid ? "" : `(${RewindParams.tid})`}\nBackup checkpoint created: ${RewindParams.backupCheckpoint || "none"}\nmessage: ${RewindParams.enrichedMessage}`, "info");
+        RewindParams = null;
 
         pi.sendMessage({
             customType: "pi-context",
-            content: "context_checkout complete. A summary of your previous branch was injected above. Read it to understand your new state. Execute the 'Next Step' from the summary",
+            content: "context_rewind complete. A summary of your previous conversation path was injected above. Read it to understand your new state. Execute the 'Next Step' from the summary",
             display: false,
         }, {
             triggerTurn: true,