@docyrus/docyrus 0.0.66 → 0.0.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",

package/resources/pi-agent/extensions/context.ts

@@ -13,6 +13,7 @@ import { DynamicBorder, getAgentDir as piGetAgentDir, loadProjectContextFiles as
 import { Container, Key, Text, matchesKey, type Component, type TUI } from "@mariozechner/pi-tui";
 import os from "node:os";
 import path from "node:path";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 function formatUsd(cost: number): string {
   if (!Number.isFinite(cost) || cost <= 0) {return "$0.00";}
@@ -390,22 +391,27 @@ export default function contextExtension(pi: ExtensionAPI) {
   };
 
   pi.on("tool_result", (event: ToolResultEvent, ctx: ExtensionContext) => {
-		// Only count successful reads.
-    if ((event as any).toolName !== "read") {return;}
-    if ((event as any).isError) {return;}
-
-    const input = (event as any).input as { path?: unknown } | undefined;
-    const p = typeof input?.path === "string" ? input.path : "";
-    if (!p) {return;}
-
-    ensureCaches(ctx);
-    const abs = normalizeReadPath(p, ctx.cwd);
-    const skillName = matchSkillForPath(abs);
-    if (!skillName) {return;}
-
-    if (!cachedLoadedSkills.has(skillName)) {
-      cachedLoadedSkills.add(skillName);
-      pi.appendEntry<SkillLoadedEntryData>(SKILL_LOADED_ENTRY, { name: skillName, path: abs });
+    try {
+			// Only count successful reads.
+      if ((event as any).toolName !== "read") {return;}
+      if ((event as any).isError) {return;}
+
+      const input = (event as any).input as { path?: unknown } | undefined;
+      const p = typeof input?.path === "string" ? input.path : "";
+      if (!p) {return;}
+
+      ensureCaches(ctx);
+      const abs = normalizeReadPath(p, ctx.cwd);
+      const skillName = matchSkillForPath(abs);
+      if (!skillName) {return;}
+
+      if (!cachedLoadedSkills.has(skillName)) {
+        cachedLoadedSkills.add(skillName);
+        pi.appendEntry<SkillLoadedEntryData>(SKILL_LOADED_ENTRY, { name: skillName, path: abs });
+      }
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
     }
   });
 

package/resources/pi-agent/extensions/control.ts

@@ -52,6 +52,7 @@ import { promises as fs } from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 const CONTROL_FLAG = "session-control";
 const CONTROL_TARGET_FLAG = "control-session";
@@ -1080,42 +1081,57 @@ export default function(pi: ExtensionAPI) {
   };
 
   pi.on("session_start", async(_event, ctx) => {
-    await refreshServer(ctx);
-    if (!cliSendHandled) {
-      cliSendHandled = true;
-      await maybeHandleStartupControlSend(pi, ctx);
+    try {
+      await refreshServer(ctx);
+      if (!cliSendHandled) {
+        cliSendHandled = true;
+        await maybeHandleStartupControlSend(pi, ctx);
+      }
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
     }
   });
 
   pi.on("session_shutdown", async() => {
-    if (state.aliasTimer) {
-      clearInterval(state.aliasTimer);
-      state.aliasTimer = null;
+    try {
+      if (state.aliasTimer) {
+        clearInterval(state.aliasTimer);
+        state.aliasTimer = null;
+      }
+      updateStatus(state.context, false);
+      updateSessionEnv(state.context, false);
+      await stopControlServer(state);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
     }
-    updateStatus(state.context, false);
-    updateSessionEnv(state.context, false);
-    await stopControlServer(state);
   });
 
 	// Fire turn_end events to subscribers
   pi.on("turn_end", (event: TurnEndEvent, ctx: ExtensionContext) => {
-    if (state.turnEndSubscriptions.length === 0) {return;}
-
-    void syncAlias(state, ctx);
-    const lastMessage = getLastAssistantMessage(ctx);
-    const eventData = { message: lastMessage, turnIndex: event.turnIndex };
-
-		// Fire to all subscribers (one-shot)
-    const subscriptions = [...state.turnEndSubscriptions];
-    state.turnEndSubscriptions = [];
-
-    for (const sub of subscriptions) {
-      writeEvent(sub.socket, {
-        type: "event",
-        event: "turn_end",
-        data: eventData,
-        subscriptionId: sub.subscriptionId,
-      });
+    try {
+      if (state.turnEndSubscriptions.length === 0) {return;}
+
+      void syncAlias(state, ctx);
+      const lastMessage = getLastAssistantMessage(ctx);
+      const eventData = { message: lastMessage, turnIndex: event.turnIndex };
+
+			// Fire to all subscribers (one-shot)
+      const subscriptions = [...state.turnEndSubscriptions];
+      state.turnEndSubscriptions = [];
+
+      for (const sub of subscriptions) {
+        writeEvent(sub.socket, {
+          type: "event",
+          event: "turn_end",
+          data: eventData,
+          subscriptionId: sub.subscriptionId,
+        });
+      }
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
     }
   });
 }

package/resources/pi-agent/extensions/knowledge.ts

@@ -10,6 +10,7 @@ import type {
 } from "@mariozechner/pi-coding-agent";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import { Box, Markdown, Text } from "@mariozechner/pi-tui";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 const KNOWLEDGE_STATE_TYPE = "knowledge-session";
 const KNOWLEDGE_WIDGET_KEY = "knowledge";
@@ -458,35 +459,60 @@ export default function(pi: ExtensionAPI) {
   });
 
   pi.on("tool_result", (event: ToolResultEvent, ctx: ExtensionContext) => {
-    trackToolResult(pi, ctx, event);
+    try {
+      trackToolResult(pi, ctx, event);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("session_start", async(_event, ctx) => {
-    await refreshKnowledgeState(pi, ctx, {
-      runCheck: false,
-      allowReminder: true,
-    });
+    try {
+      await refreshKnowledgeState(pi, ctx, {
+        runCheck: false,
+        allowReminder: true,
+      });
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("turn_end", async(_event: TurnEndEvent, ctx) => {
-    await refreshKnowledgeState(pi, ctx, {
-      runCheck: false,
-      allowReminder: true,
-    });
+    try {
+      await refreshKnowledgeState(pi, ctx, {
+        runCheck: false,
+        allowReminder: true,
+      });
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("agent_end", async(_event, ctx) => {
-    const state = await refreshKnowledgeState(pi, ctx, {
-      runCheck: true,
-      allowReminder: true,
-    });
-    if (ctx.hasUI && state.commitWouldFail) {
-      ctx.ui.notify("Knowledge drift is severe or integrity checks failed. A commit would likely be blocked until knowledge is updated.", "warning");
+    try {
+      const state = await refreshKnowledgeState(pi, ctx, {
+        runCheck: true,
+        allowReminder: true,
+      });
+      if (ctx.hasUI && state.commitWouldFail) {
+        ctx.ui.notify("Knowledge drift is severe or integrity checks failed. A commit would likely be blocked until knowledge is updated.", "warning");
+      }
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
     }
   });
 
   pi.on("session_shutdown", async(_event, ctx) => {
-    updateKnowledgeWidget(ctx, defaultKnowledgeState());
+    try {
+      updateKnowledgeWidget(ctx, defaultKnowledgeState());
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.registerMessageRenderer("knowledge-reminder", (message, { expanded }, theme) => {

package/resources/pi-agent/extensions/loop.ts

@@ -12,6 +12,7 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 import { compact } from "@mariozechner/pi-coding-agent";
 import { Container, type SelectItem, SelectList, Text } from "@mariozechner/pi-tui";
 import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 type LoopMode = "tests" | "custom" | "self";
 
@@ -385,39 +386,50 @@ export default function loopExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("agent_end", async(event, ctx) => {
-    if (!loopState.active) {return;}
-
-    if (ctx.hasUI && wasLastAssistantAborted(event.messages)) {
-      const confirm = await ctx.ui.confirm(
-        "Break active loop?",
-        "Operation aborted. Break out of the loop?",
-      );
-      if (confirm) {
-        breakLoop(ctx);
-        return;
+    try {
+      if (!loopState.active) {return;}
+
+      if (ctx.hasUI && wasLastAssistantAborted(event.messages)) {
+        const confirm = await ctx.ui.confirm(
+          "Break active loop?",
+          "Operation aborted. Break out of the loop?",
+        );
+        if (confirm) {
+          breakLoop(ctx);
+          return;
+        }
       }
-    }
 
-    triggerLoopPrompt(ctx);
+      triggerLoopPrompt(ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("session_before_compact", async(event, ctx) => {
-    if (!loopState.active || !loopState.mode || !ctx.model) {return;}
-    const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
-    if (!apiKey) {return;}
-
-    const instructionParts = [event.customInstructions, getCompactionInstructions(loopState.mode, loopState.condition)]
-      .filter(Boolean)
-      .join("\n\n");
-
     try {
-      const compaction = await compact(event.preparation, ctx.model, apiKey, instructionParts, event.signal);
-      return { compaction };
-    } catch (error) {
-      if (ctx.hasUI) {
-        const message = error instanceof Error ? error.message : String(error);
-        ctx.ui.notify(`Loop compaction failed: ${message}`, "warning");
+      if (!loopState.active || !loopState.mode || !ctx.model) {return;}
+      const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
+      if (!apiKey) {return;}
+
+      const instructionParts = [event.customInstructions, getCompactionInstructions(loopState.mode, loopState.condition)]
+        .filter(Boolean)
+        .join("\n\n");
+
+      try {
+        const compaction = await compact(event.preparation, ctx.model, apiKey, instructionParts, event.signal);
+        return { compaction };
+      } catch (error) {
+        if (ctx.hasUI) {
+          const message = error instanceof Error ? error.message : String(error);
+          ctx.ui.notify(`Loop compaction failed: ${message}`, "warning");
+        }
+        return;
       }
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
       return;
     }
   });
@@ -440,6 +452,11 @@ export default function loopExtension(pi: ExtensionAPI): void {
   }
 
   pi.on("session_start", async(_event, ctx) => {
-    await restoreLoopState(ctx);
+    try {
+      await restoreLoopState(ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 }

package/resources/pi-agent/extensions/plan.ts

@@ -21,6 +21,7 @@ import {
   type IAskUserQuestion,
   type IAskUserResponse,
 } from "../shared/askUserProtocol";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 const PLAN_OUTPUT_ROOT_SEGMENTS = [".docyrus", "plans"] as const;
 const PLAN_STATE_TYPE = "plan-session";
@@ -1360,71 +1361,109 @@ export default function planExtension(pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", (event, ctx) => {
-    const planState = getPlanState(ctx);
-    const readOnlyState = getReadOnlyState(ctx);
-    const overlays: string[] = [];
+    try {
+      const planState = getPlanState(ctx);
+      const readOnlyState = getReadOnlyState(ctx);
+      const overlays: string[] = [];
 
-    if (planState?.active) {
-      overlays.push(buildPlanPromptOverlay(planState));
-    }
+      if (planState?.active) {
+        overlays.push(buildPlanPromptOverlay(planState));
+      }
 
-    if (readOnlyState?.active) {
-      overlays.push(READONLY_MODE_SYSTEM_PROMPT);
-    }
+      if (readOnlyState?.active) {
+        overlays.push(READONLY_MODE_SYSTEM_PROMPT);
+      }
 
-    if (overlays.length === 0) {
+      if (overlays.length === 0) {
+        return;
+      }
+
+      return {
+        systemPrompt: [event.systemPrompt, ...overlays].filter(Boolean).join("\n\n"),
+      };
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
       return;
     }
-
-    return {
-      systemPrompt: [event.systemPrompt, ...overlays].filter(Boolean).join("\n\n"),
-    };
   });
 
   pi.on("tool_call", (event, ctx) => {
-    return handleToolCallDuringPlan(event, ctx) ?? handleToolCallDuringReadOnly(event, ctx);
+    try {
+      return handleToolCallDuringPlan(event, ctx) ?? handleToolCallDuringReadOnly(event, ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+      return;
+    }
   });
 
   pi.on("user_bash", (event, ctx) => {
-    return handleUserBashDuringPlan(event, ctx) ?? handleUserBashDuringReadOnly(event, ctx);
+    try {
+      return handleUserBashDuringPlan(event, ctx) ?? handleUserBashDuringReadOnly(event, ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+      return;
+    }
   });
 
   pi.on("agent_end", async(event, ctx) => {
-    const state = getPlanState(ctx);
-    if (state?.active) {
-      const text = extractLastAssistantText(event.messages ?? []);
-      const askUserRequest = text ? parseAskUserRequestFromText(text) : undefined;
-      if (askUserRequest && ctx.hasUI) {
-        const response = await collectAskUserResponse(ctx, askUserRequest);
-        if (response) {
-          pi.sendUserMessage(formatAskUserResponsePrompt(response));
+    try {
+      const state = getPlanState(ctx);
+      if (state?.active) {
+        const text = extractLastAssistantText(event.messages ?? []);
+        const askUserRequest = text ? parseAskUserRequestFromText(text) : undefined;
+        if (askUserRequest && ctx.hasUI) {
+          const response = await collectAskUserResponse(ctx, askUserRequest);
+          if (response) {
+            pi.sendUserMessage(formatAskUserResponsePrompt(response));
+          }
+          return;
         }
-        return;
       }
-    }
 
-    await writePlanArtifactFromEvent(event, ctx);
-    await writeArchitectArtifactFromEvent(event, ctx);
+      await writePlanArtifactFromEvent(event, ctx);
+      await writeArchitectArtifactFromEvent(event, ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("session_start", async(_event, ctx) => {
-    await syncPlanState(pi, ctx);
-    const readOnlyState = getReadOnlyState(ctx);
-    currentReadOnlyState = readOnlyState;
-    setReadOnlyWidget(ctx, readOnlyState);
+    try {
+      await syncPlanState(pi, ctx);
+      const readOnlyState = getReadOnlyState(ctx);
+      currentReadOnlyState = readOnlyState;
+      setReadOnlyWidget(ctx, readOnlyState);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("session_tree", async(_event, ctx) => {
-    await syncPlanState(pi, ctx);
-    const readOnlyState = getReadOnlyState(ctx);
-    currentReadOnlyState = readOnlyState;
-    setReadOnlyWidget(ctx, readOnlyState);
+    try {
+      await syncPlanState(pi, ctx);
+      const readOnlyState = getReadOnlyState(ctx);
+      currentReadOnlyState = readOnlyState;
+      setReadOnlyWidget(ctx, readOnlyState);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("session_shutdown", async(_event, ctx) => {
-    currentPlanState = undefined;
-    setPlanWidget(ctx, undefined);
-    currentReadOnlyState = undefined;
-    setReadOnlyWidget(ctx, undefined);
+    try {
+      currentPlanState = undefined;
+      setPlanWidget(ctx, undefined);
+      currentReadOnlyState = undefined;
+      setReadOnlyWidget(ctx, undefined);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 }

package/resources/pi-agent/extensions/prompt-url-widget.ts

@@ -1,5 +1,6 @@
 import { DynamicBorder, type ExtensionAPI, type ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { Container, Text } from "@mariozechner/pi-tui";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 const PR_PROMPT_PATTERN = /^\s*You are given one or more GitHub PR URLs:\s*(\S+)/im;
 const ISSUE_PROMPT_PATTERN = /^\s*Analyze GitHub issue\(s\):\s*(\S+)/im;
@@ -92,20 +93,30 @@ export default function promptUrlWidgetExtension(pi: ExtensionAPI) {
   };
 
   pi.on("before_agent_start", async(event, ctx) => {
-    if (!ctx.hasUI) {return;}
-    const match = extractPromptMatch(event.prompt);
-    if (!match) {
-      return;
+    try {
+      if (!ctx.hasUI) {return;}
+      const match = extractPromptMatch(event.prompt);
+      if (!match) {
+        return;
+      }
+
+      setWidget(ctx, match);
+      applySessionName(ctx, match);
+      void fetchGhMetadata(pi, match.kind, match.url).then((meta) => {
+        try {
+          const title = meta?.title?.trim();
+          const authorText = formatAuthor(meta?.author);
+          setWidget(ctx, match, title, authorText);
+          applySessionName(ctx, match, title);
+        }
+        catch (error: unknown) {
+          if (!isStaleExtensionError(error)) {throw error;}
+        }
+      });
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
     }
-
-    setWidget(ctx, match);
-    applySessionName(ctx, match);
-    void fetchGhMetadata(pi, match.kind, match.url).then((meta) => {
-      const title = meta?.title?.trim();
-      const authorText = formatAuthor(meta?.author);
-      setWidget(ctx, match, title, authorText);
-      applySessionName(ctx, match, title);
-    });
   });
 
   const getUserText = (content: string | { type: string; text?: string }[] | undefined): string => {
@@ -141,14 +152,24 @@ export default function promptUrlWidgetExtension(pi: ExtensionAPI) {
     setWidget(ctx, match);
     applySessionName(ctx, match);
     void fetchGhMetadata(pi, match.kind, match.url).then((meta) => {
-      const title = meta?.title?.trim();
-      const authorText = formatAuthor(meta?.author);
-      setWidget(ctx, match, title, authorText);
-      applySessionName(ctx, match, title);
+      try {
+        const title = meta?.title?.trim();
+        const authorText = formatAuthor(meta?.author);
+        setWidget(ctx, match, title, authorText);
+        applySessionName(ctx, match, title);
+      }
+      catch (error: unknown) {
+        if (!isStaleExtensionError(error)) {throw error;}
+      }
     });
   };
 
   pi.on("session_start", async(_event, ctx) => {
-    rebuildFromSession(ctx);
+    try {
+      rebuildFromSession(ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 }

package/resources/pi-agent/extensions/review.ts

@@ -42,6 +42,7 @@ import {
 } from "@mariozechner/pi-tui";
 import path from "node:path";
 import { promises as fs } from "node:fs";
+import { isStaleExtensionError } from "../shared/extensionLifecycle";
 
 // State to track fresh session review (where we branched from).
 // Module-level state means only one review can be active at a time.
@@ -935,11 +936,21 @@ export default function reviewExtension(pi: ExtensionAPI) {
   }
 
   pi.on("session_start", (_event, ctx) => {
-    applyAllReviewState(ctx);
+    try {
+      applyAllReviewState(ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
   pi.on("session_tree", (_event, ctx) => {
-    applyAllReviewState(ctx);
+    try {
+      applyAllReviewState(ctx);
+    }
+    catch (error: unknown) {
+      if (!isStaleExtensionError(error)) {throw error;}
+    }
   });
 
 	/**

package/resources/pi-agent/shared/extensionLifecycle.ts

@@ -0,0 +1,11 @@
+/**
+ * pi invalidates the captured `pi` / `ctx` held by an extension factory closure
+ * after session replacement (`/new`, `/clear`, `/resume`, `/reload`, etc.).
+ * Async handlers that started before the replacement resume against the stale
+ * runtime and throw — the runner catches and rethrows via `emitError`, which
+ * surfaces as a visible TUI error. Use this helper to ignore only that one
+ * well-known error and let every other failure bubble.
+ */
+export function isStaleExtensionError(error: unknown): boolean {
+  return error instanceof Error && /stale after session replacement or reload/i.test(error.message);
+}