pi-context 2.0.0-beta.0 → 2.1.0

package/src/index.ts

@@ -3,6 +3,7 @@ import {
     type SessionManager,
     type SessionEntry,
     type ExtensionCommandContext,
+    type ContextUsage,
 } from "@earendil-works/pi-coding-agent";
 import {
     Type,
@@ -20,12 +21,23 @@ interface SessionTreeNode {
     label?: string;
 }
 
-const InternalTools = ["context_checkpoint", "context_timeline", "context_rewind"];
+const InternalTools = ["context_checkpoint", "context_timeline", "context_compact"];
+const PiContextCustomMessageType = "pi-context";
+const AcmEnableFollowUp = "Agentic context management is now enabled";
 let CommandCtx: ExtensionCommandContext | null = null;
-let RewindParams: any = null;
+let CompactParams: any = null;
 
 const isInternal = (name: string) => InternalTools.includes(name);
 
+const formatContextUsage = (usage: ContextUsage | undefined, includeTokens = false): string => {
+    if (usage?.percent == null) return "Unknown";
+
+    const percent = `${usage.percent.toFixed(1)}%`;
+    if (!includeTokens || usage.tokens == null) return percent;
+
+    return `${percent} (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
+};
+
 const resolveTargetId = (sm: SessionManager, target: string): string => {
     if (target.toLowerCase() === "root") {
         const tree = sm.getTree();
@@ -47,20 +59,23 @@ const resolveTargetId = (sm: SessionManager, target: string): string => {
     return target;
 };
 
+const ContextTimelineDescription = "Inspect the active conversation path as a structural map: checkpoints, summaries/compactions, branch points, user turns, and current position. Use when orientation or compact target selection depends on the shape of history.";
 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), collapse intermediate AI steps and only show milestones, user messages, checkpoints, branch points, and summaries." })),
+    limit: Type.Optional(Type.Number({ description: "Maximum visible timeline entries (default: 50)." })),
+    verbose: Type.Optional(Type.Boolean({ description: "If true, show all messages including internal context-tool traffic. If false (default), collapse to structural milestones." })),
 });
 
-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 ContextCompactDescription = "Create a summarized continuation branch from an earlier checkpoint or history node. The selected target is the branch point; the summary must restore the useful state from the compacted path after that target. This changes conversation history only; it does not modify or roll back disk files or external systems.";
+const ContextCompactParams = Type.Object({
+    target: Type.String({ description: "Checkpoint name, history node ID, or root to use as the branch point for the summarized continuation." }),
+    summary: Type.String({ description: "Handoff summary injected into the new continuation branch. Restore current task/state, decisions/constraints, important external side effects (changed files, processes, browser/tickets/remote state), validation status, source anchors/evidence/open questions likely needed soon, and explicit next step. Do not rely on backupCheckpoint for details needed in the next phase." }),
+    backupCheckpoint: Type.Optional(Type.String({ description: "Optional checkpoint name to label the current conversation state before branching. This is only a recovery pointer; the summary must still contain the state needed to continue." })),
 });
 
+const ContextCheckpointDescription = "Create a named anchor by labeling a conversation history node. This does not branch, summarize, or affect external state; it only makes the point easy to find later in timeline or compact target selection.";
 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." })),
+    name: Type.String({ description: "Unique semantic anchor name that encodes the task and phase/purpose, e.g. parser-fix-start or timeout-investigation-search. Avoid generic names like start, checkpoint-1, or retry." }),
+    target: Type.Optional(Type.String({ description: "Optional history node ID or checkpoint name to label. Defaults to the current meaningful position near the conversation head." })),
 });
 
 export default function (pi: ExtensionAPI) {
@@ -69,15 +84,8 @@ export default function (pi: ExtensionAPI) {
         handler: async (args, ctx) => {
             CommandCtx = ctx;
             ctx.ui.notify("Agentic Context Management enabled.", "info");
-            pi.sendMessage({
-                customType: "pi-context",
-                content: "use context-management skill",
-                display: false,
-            }, {
-                deliverAs: "followUp"
-            });
             if (args) {
-                pi.sendUserMessage(args)
+                pi.sendUserMessage(args, { deliverAs: "followUp" });
             }
         }
     });
@@ -102,7 +110,7 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool({
         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.",
+        description: ContextCheckpointDescription,
         parameters: ContextCheckpointParams,
         async execute(_id, params: Static<typeof ContextCheckpointParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
@@ -157,14 +165,20 @@ export default function (pi: ExtensionAPI) {
             }
 
             pi.setLabel(id, params.name);
-            return { content: [{ type: "text", text: `Created checkpoint '${params.name}' at ${id}` }], details: {} };
+            return {
+                content: [{
+                    type: "text",
+                    text: `Created checkpoint '${params.name}' at ${id}.`
+                }],
+                details: {}
+            };
         },
     });
 
     pi.registerTool({
         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.",
+        description: ContextTimelineDescription,
         parameters: ContextTimelineParams,
         async execute(_id, params: Static<typeof ContextTimelineParams>, _signal, _onUpdate, ctx) {
             const sm = ctx.sessionManager as SessionManager;
@@ -342,11 +356,7 @@ export default function (pi: ExtensionAPI) {
             }
 
             // --- Context Dashboard (HUD) ---
-            const usage = await ctx.getContextUsage();
-            let usageStr = "Unknown";
-            if (usage?.percent != null && usage.tokens != null && usage.contextWindow != null) {
-                usageStr = `${usage.percent.toFixed(1)}% (${formatTokens(usage.tokens)}/${formatTokens(usage.contextWindow)})`;
-            }
+            const usageStr = formatContextUsage(ctx.getContextUsage(), true);
 
             // Find the distance to the nearest checkpoint
             let stepsSinceCheckpoint = 0;
@@ -361,10 +371,15 @@ export default function (pi: ExtensionAPI) {
                 stepsSinceCheckpoint++;
             }
 
+            const compactCue = nearestCheckpointName === "None"
+                ? "create a checkpoint before the next noisy phase"
+                : `if this segment has produced a stable result and another phase remains, compact to '${nearestCheckpointName}' with a handoff summary before continuing`;
+
             const hud = [
                 `[Context Dashboard]`,
                 `• Context Usage:    ${usageStr}`,
                 `• Segment Size:     ${stepsSinceCheckpoint} steps since last checkpoint '${nearestCheckpointName}'`,
+                `• Compact Cue:      ${compactCue}`,
                 `---------------------------------------------------`
             ].join("\n");
 
@@ -373,13 +388,17 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.registerTool({
-        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) {
+        name: "context_compact",
+        label: "Context Compact",
+        description: ContextCompactDescription,
+        parameters: ContextCompactParams,
+        async execute(_id, params: Static<typeof ContextCompactParams>, _signal, _onUpdate, ctx) {
             if (!CommandCtx) {
-                ctx.ui.setEditorText(`/acm ${ctx.ui.getEditorText() || "continue"}`)
+                const editorText = ctx.ui.getEditorText();
+                const followUp = editorText
+                    ? `${AcmEnableFollowUp}\n${editorText}`
+                    : AcmEnableFollowUp;
+                ctx.ui.setEditorText(`/acm ${followUp}`)
                 return {
                     content: [{
                         type: "text",
@@ -389,6 +408,7 @@ export default function (pi: ExtensionAPI) {
                 };
             }
             const sm = ctx.sessionManager as SessionManager;
+            const usageBeforeText = formatContextUsage(ctx.getContextUsage());
 
             const tid = resolveTargetId(sm, params.target);
 
@@ -402,46 +422,74 @@ export default function (pi: ExtensionAPI) {
             const currentLabel = currentLeaf ? sm.getLabel(currentLeaf) : undefined;
             const origin = currentLabel ? `checkpoint: ${currentLabel}` : (currentLeaf || "unknown");
 
-            const enrichedMessage = `(summary from ${origin})\n${params.message}`;
+            const enrichedMessage = `(handoff summary from ${origin})\n${params.summary}`;
 
-            const nid = await sm.branchWithSummary(tid, enrichedMessage);
-            RewindParams = params;
-            RewindParams.nid = nid;
-            RewindParams.tid = tid;
-            RewindParams.enrichedMessage = enrichedMessage;
+            CompactParams = params;
+            CompactParams.tid = tid;
+            CompactParams.enrichedMessage = enrichedMessage;
+            CompactParams.usageBeforeText = usageBeforeText;
 
-            return { content: [{ type: "text", text: "rewind start" }], details: {} };
+            return { content: [{ type: "text", text: "compact start" }], details: {} };
         },
     });
 
     pi.on("turn_end", async (_event, ctx) => {
-        if (!RewindParams) {
+        if (!CompactParams) {
             return
         }
         ctx.abort()
     });
 
     pi.on("agent_end", async (_event, ctx) => {
-        if (!RewindParams) {
+        if (!CompactParams) {
             return
         }
         if (!CommandCtx) {
             return
         }
 
-        await CommandCtx.navigateTree(RewindParams.nid, {
-            summarize: false,
-        });
-
-        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;
+        const sm = ctx.sessionManager as SessionManager;
+        const compactParams = CompactParams;
+        const commandCtx = CommandCtx;
+        CompactParams = null;
+
+        // `agent_end` is emitted before the core Agent is actually idle. If we
+        // call pi.sendMessage({ triggerTurn: true }) inside this handler, pi still
+        // sees an active stream and queues the message as steering; after
+        // `agent_end` the loop has already stopped, so that queued message is not
+        // drained. Defer navigation + continuation until the current run settles.
+        setTimeout(async () => {
+            try {
+                await commandCtx.waitForIdle();
+                const nid = sm.branchWithSummary(compactParams.tid, compactParams.enrichedMessage);
+                compactParams.nid = nid;
+                // branchWithSummary advances the leaf to the summary entry. Reset
+                // it so navigateTree(nid) can rebuild agent state instead of
+                // returning early as a no-op.
+                sm.branch(compactParams.tid);
+                await commandCtx.navigateTree(compactParams.nid, {
+                    summarize: false,
+                });
 
-        pi.sendMessage({
-            customType: "pi-context",
-            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,
-        });
+                const usageAfter = commandCtx.getContextUsage();
+                commandCtx.ui.notify([
+                    `Compacted to ${compactParams.target}${compactParams.target === compactParams.tid ? "" : `(${compactParams.tid})`}`,
+                    `Context Usage: ${compactParams.usageBeforeText} -> ${formatContextUsage(usageAfter)}`,
+                    `Backup checkpoint created: ${compactParams.backupCheckpoint || "none"}`,
+                    `Summary: ${compactParams.enrichedMessage}`,
+                ].join("\n"), "info");
+
+                pi.sendMessage({
+                    customType: PiContextCustomMessageType,
+                    content: "context_compact complete. A handoff 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,
+                    deliverAs: "followUp",
+                });
+            } catch (err) {
+                commandCtx.ui.notify(`context_compact failed to continue: ${err instanceof Error ? err.message : String(err)}`, "error");
+            }
+        }, 0);
     });
 }