@herbertgao/pi-extensions 2026.8.8 → 2026.8.9

package/node_modules/@herbertgao/pi-handoff/src/index.ts

@@ -1,27 +1,25 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core"
-import { complete, type Message } from "@earendil-works/pi-ai/compat"
-import {
-  generateRename,
-  getUserMessageContext,
-  sanitizeRenameText,
-} from "@herbertgao/pi-rename/naming"
+import type { Message } from "@earendil-works/pi-ai/compat"
+import { sanitizeRenameText } from "@herbertgao/pi-rename/naming"
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
-  SessionEntry,
   SlashCommandInfo,
 } from "@earendil-works/pi-coding-agent"
 import {
   BorderedLoader,
   convertToLlm,
   serializeConversation,
+  sessionEntryToContextMessages,
 } from "@earendil-works/pi-coding-agent"
+import { completeText } from "./complete-text.js"
 import { existsSync } from "node:fs"
 import { mkdir, readFile, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 
 const HANDOFF_SKILL_COMMAND = "skill:handoff"
+const HANDOFF_BRIDGE_COMMAND = "__pi-handoff-session"
 
 const HANDOFF_SYSTEM_PROMPT = `You are a context transfer assistant. Generate a handoff markdown document for a fresh coding agent.
 
@@ -42,50 +40,6 @@ type HandoffSkill = {
   instructions: string
 }
 
-function entryToMessage(entry: SessionEntry): AgentMessage | undefined {
-  if (entry.type === "message") return entry.message
-  if (entry.type === "compaction") {
-    return {
-      role: "compactionSummary",
-      summary: entry.summary,
-      tokensBefore: entry.tokensBefore,
-      timestamp: new Date(entry.timestamp).getTime(),
-    }
-  }
-  return undefined
-}
-
-function getHandoffMessages(branch: SessionEntry[]): AgentMessage[] {
-  let compactionIndex = -1
-  for (let index = branch.length - 1; index >= 0; index -= 1) {
-    if (branch[index]?.type === "compaction") {
-      compactionIndex = index
-      break
-    }
-  }
-
-  if (compactionIndex < 0) {
-    return branch.map(entryToMessage).filter((message) => message !== undefined)
-  }
-
-  const compaction = branch[compactionIndex]
-  const firstKeptIndex =
-    compaction?.type === "compaction"
-      ? branch.findIndex((entry) => entry.id === compaction.firstKeptEntryId)
-      : -1
-  const compactedBranch = [
-    compaction,
-    ...(firstKeptIndex >= 0
-      ? branch.slice(firstKeptIndex, compactionIndex)
-      : []),
-    ...branch.slice(compactionIndex + 1),
-  ].filter((entry) => entry !== undefined)
-
-  return compactedBranch
-    .map(entryToMessage)
-    .filter((message) => message !== undefined)
-}
-
 async function loadHandoffSkill(
   pi: ExtensionAPI,
 ): Promise<HandoffSkill | undefined> {
@@ -104,28 +58,6 @@ async function loadHandoffSkill(
   }
 }
 
-function textFromMessage(message: AgentMessage): string | undefined {
-  if (message.role !== "user") return undefined
-  const content = message.content
-  if (typeof content === "string") return content.trim()
-  if (!Array.isArray(content)) return undefined
-
-  return content
-    .filter((part): part is { type: "text"; text: string } => {
-      return (
-        typeof part === "object" &&
-        part !== null &&
-        "type" in part &&
-        part.type === "text" &&
-        "text" in part &&
-        typeof part.text === "string"
-      )
-    })
-    .map((part) => part.text)
-    .join("\n")
-    .trim()
-}
-
 function dateStamp(): string {
   const [date] = new Date().toISOString().split("T")
   return date ?? "handoff"
@@ -145,17 +77,6 @@ async function nextHandoffPath(slug: string): Promise<string> {
   throw new Error("Could not allocate a unique handoff file path")
 }
 
-async function generateSessionName(
-  ctx: ExtensionCommandContext,
-  messages: readonly AgentMessage[],
-): Promise<string> {
-  const context = getUserMessageContext(messages)
-  if (!context) return "handoff-session"
-
-  const result = await generateRename(ctx, { kind: "missing" }, context)
-  return result?.name ?? "handoff-session"
-}
-
 function buildNewSessionPrompt(handoffPath: string): string {
   return [
     "Continue from this handoff:",
@@ -164,35 +85,11 @@ function buildNewSessionPrompt(handoffPath: string): string {
   ].join("\n\n")
 }
 
-function summarizePromptContext(ctx: ExtensionCommandContext): string {
-  const promptOptions = ctx.getSystemPromptOptions()
-  const skills = (promptOptions.skills ?? [])
-    .map((skill) => skill.name)
-    .toSorted()
-  const contextFiles = (promptOptions.contextFiles ?? [])
-    .map((file) => file.path)
-    .toSorted()
-
-  const lines = ["## Loaded pi context", ""]
-  lines.push("### Skills", "")
-  lines.push(
-    ...(skills.length > 0 ? skills.map((name) => `- \`${name}\``) : ["- None"]),
-  )
-  lines.push("", "### Context files", "")
-  lines.push(
-    ...(contextFiles.length > 0
-      ? contextFiles.map((filePath) => `- \`${filePath}\``)
-      : ["- None"]),
-  )
-  return lines.join("\n")
-}
-
 function buildDocumentWithMetadata(options: {
   generated: string
   focus: string
   handoffSkillPath: string
   parentSession: string | undefined
-  promptContext: string
 }): string {
   const previousSession = options.parentSession
     ? [
@@ -216,8 +113,6 @@ function buildDocumentWithMetadata(options: {
     "",
     previousSession,
     "",
-    options.promptContext,
-    "",
     "## Handoff policy",
     "",
     "- Skill: `handoff`",
@@ -239,9 +134,6 @@ async function generateHandoffDocument(options: {
   const model = options.ctx.model
   if (!model) throw new Error("No model selected")
 
-  const auth = await options.ctx.modelRegistry.getApiKeyAndHeaders(model)
-  if (!auth.ok) throw new Error(auth.error)
-
   const conversationText = serializeConversation(convertToLlm(options.messages))
   const userMessage: Message = {
     role: "user",
@@ -271,140 +163,143 @@ async function generateHandoffDocument(options: {
     timestamp: Date.now(),
   }
 
-  const response = await complete(
+  return completeText(
+    options.ctx,
     model,
-    { systemPrompt: HANDOFF_SYSTEM_PROMPT, messages: [userMessage] },
-    {
-      ...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
-      ...(auth.headers ? { headers: auth.headers } : {}),
-      ...(options.signal ? { signal: options.signal } : {}),
-    },
+    HANDOFF_SYSTEM_PROMPT,
+    userMessage,
+    options.signal,
   )
-
-  if (response.stopReason === "aborted") return null
-
-  return response.content
-    .filter((content): content is { type: "text"; text: string } => {
-      return content.type === "text"
-    })
-    .map((content) => content.text)
-    .join("\n")
-    .trim()
 }
 
-export default function (pi: ExtensionAPI): void {
-  pi.registerCommand("handoff-session", {
-    description:
-      "Create a new session from a handoff generated by the handoff skill",
-    handler: async (_args, ctx) => {
-      if (ctx.mode !== "tui") {
-        ctx.ui.notify("handoff-session requires interactive TUI mode.", "error")
-        return
-      }
+const DEFAULT_HANDOFF_FOCUS = "continue the current work"
+const HANDOFF_REQUEST_RE = /(^|\s)-handoff(?=\s|$)/
 
-      if (!ctx.model) {
-        ctx.ui.notify("No model selected.", "error")
-        return
-      }
+function getHandoffFocus(text: string): string | undefined {
+  if (!HANDOFF_REQUEST_RE.test(text)) return undefined
+  return text.replace(HANDOFF_REQUEST_RE, " ").trim() || DEFAULT_HANDOFF_FOCUS
+}
 
-      const handoffSkill = await loadHandoffSkill(pi)
-      if (!handoffSkill) {
-        ctx.ui.notify(
-          "handoff-session requires a discoverable skill named exactly `handoff`. Install it, then run /reload.",
-          "error",
-        )
-        return
-      }
+async function runHandoff(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  focus: string,
+): Promise<void> {
+  if (!ctx.model) {
+    ctx.ui.notify("No model selected.", "error")
+    return
+  }
 
-      const focus = (
-        await ctx.ui.input(
-          "What will the next session be used for?",
-          "continue the current work",
-        )
-      )?.trim()
-      if (!focus) {
-        ctx.ui.notify("Handoff session cancelled.", "warning")
-        return
-      }
+  const handoffSkill = await loadHandoffSkill(pi)
+  if (!handoffSkill) {
+    ctx.ui.notify(
+      "Handoff requires a discoverable skill named exactly `handoff`. Install it, then run /reload.",
+      "error",
+    )
+    return
+  }
 
-      const branch = ctx.sessionManager.getBranch()
-      const messages = getHandoffMessages(branch)
-      if (messages.length === 0) {
-        ctx.ui.notify("No conversation to hand off.", "error")
-        return
-      }
+  const messages = ctx.sessionManager
+    .buildContextEntries()
+    .flatMap(sessionEntryToContextMessages)
+  if (messages.length === 0) {
+    ctx.ui.notify("No conversation to hand off.", "error")
+    return
+  }
 
-      const parentSession = ctx.sessionManager.getSessionFile() ?? undefined
-      const generated = await ctx.ui.custom<string | null>(
-        (tui, theme, _kb, done) => {
-          const model = ctx.model
-          const modelLabel = model
-            ? `${model.provider}/${"id" in model ? model.id : "selected"}`
-            : "selected model"
-          const loader = new BorderedLoader(
-            tui,
-            theme,
-            `Generating handoff with ${modelLabel}...`,
-          )
-          loader.onAbort = () => done(null)
-
-          generateHandoffDocument({
-            ctx: ctx as ExtensionCommandContext,
-            handoffSkill,
-            messages,
-            focus,
-            parentSession,
-            signal: loader.signal,
-          })
-            .then(done)
-            .catch((error) => {
-              console.error("Handoff generation failed:", error)
-              done(
-                `__ERROR__${error instanceof Error ? error.message : String(error)}`,
-              )
-            })
-
-          return loader
-        },
+  const parentSession = ctx.sessionManager.getSessionFile() ?? undefined
+  const generated = await ctx.ui.custom<string | null>(
+    (tui, theme, _kb, done) => {
+      const model = ctx.model
+      const modelLabel = model
+        ? `${model.provider}/${"id" in model ? model.id : "selected"}`
+        : "selected model"
+      const loader = new BorderedLoader(
+        tui,
+        theme,
+        `Generating handoff with ${modelLabel}...`,
       )
+      loader.onAbort = () => done(null)
 
-      if (generated === null) {
-        ctx.ui.notify("Handoff session cancelled.", "warning")
-        return
-      }
-      if (generated.startsWith("__ERROR__")) {
-        ctx.ui.notify(generated.slice("__ERROR__".length), "error")
-        return
-      }
-
-      const sessionName = await generateSessionName(
-        ctx as ExtensionCommandContext,
+      generateHandoffDocument({
+        ctx,
+        handoffSkill,
         messages,
-      )
-      const firstUserText = messages.map(textFromMessage).find(Boolean)
-      const handoffSlug =
-        sanitizeRenameText(pi.getSessionName() ?? firstUserText ?? focus) ||
-        "session"
-      const handoffPath = await nextHandoffPath(handoffSlug)
-      const document = buildDocumentWithMetadata({
-        generated,
         focus,
-        handoffSkillPath: handoffSkill.path,
         parentSession,
-        promptContext: summarizePromptContext(ctx as ExtensionCommandContext),
-      })
-      await writeFile(handoffPath, document, "utf8")
-
-      await (ctx as ExtensionCommandContext).newSession({
-        ...(parentSession ? { parentSession } : {}),
-        setup: async (sessionManager) => {
-          sessionManager.appendSessionInfo(sessionName)
-        },
-        withSession: async (newCtx) => {
-          newCtx.ui.setEditorText(buildNewSessionPrompt(handoffPath))
-          newCtx.ui.notify(`Handoff written: ${handoffPath}`, "info")
-        },
+        signal: loader.signal,
       })
+        .then(done)
+        .catch((error) => {
+          console.error("Handoff generation failed:", error)
+          done(
+            `__ERROR__${error instanceof Error ? error.message : String(error)}`,
+          )
+        })
+
+      return loader
+    },
+  )
+
+  if (generated === null) {
+    ctx.ui.notify("Handoff session cancelled.", "warning")
+    return
+  }
+  if (generated.startsWith("__ERROR__")) {
+    ctx.ui.notify(generated.slice("__ERROR__".length), "error")
+    return
+  }
+
+  const sessionName =
+    sanitizeRenameText(ctx.sessionManager.getSessionName() ?? focus) ||
+    "handoff-session"
+  const handoffPath = await nextHandoffPath(sessionName)
+  const document = buildDocumentWithMetadata({
+    generated,
+    focus,
+    handoffSkillPath: handoffSkill.path,
+    parentSession,
+  })
+  await writeFile(handoffPath, document, "utf8")
+
+  await ctx.newSession({
+    ...(parentSession ? { parentSession } : {}),
+    setup: async (sessionManager) => {
+      sessionManager.appendSessionInfo(sessionName)
+    },
+    withSession: async (newCtx) => {
+      newCtx.ui.notify(`Handoff written: ${handoffPath}`, "info")
+      await newCtx.sendUserMessage(buildNewSessionPrompt(handoffPath))
+    },
+  })
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.registerCommand(HANDOFF_BRIDGE_COMMAND, {
+    description: "Internal handoff bridge; use the -handoff marker instead.",
+    handler: async (args, ctx) => {
+      const focus = args.trim() || DEFAULT_HANDOFF_FOCUS
+      try {
+        await runHandoff(pi, ctx, focus)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        console.error("Handoff session failed:", error)
+        ctx.ui.notify(message, "error")
+      }
     },
   })
+
+  pi.on("input", (event, ctx) => {
+    if (event.source === "extension" || ctx.mode !== "tui") {
+      return { action: "continue" }
+    }
+
+    const focus = getHandoffFocus(event.text)
+    if (focus === undefined) return { action: "continue" }
+
+    pi.sendUserMessage(`/${HANDOFF_BRIDGE_COMMAND} ${focus}`, {
+      expandPromptTemplates: true,
+    })
+    return { action: "handled" }
+  })
 }

package/node_modules/@herbertgao/pi-handoff/src/session-query.ts

@@ -1,11 +1,12 @@
-import { complete, type Message } from "@earendil-works/pi-ai/compat"
+import type { Message } from "@earendil-works/pi-ai/compat"
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import {
   SessionManager,
   convertToLlm,
   serializeConversation,
-  type SessionEntry,
+  sessionEntryToContextMessages,
 } from "@earendil-works/pi-coding-agent"
+import { completeText } from "./complete-text.js"
 import { Text } from "@earendil-works/pi-tui"
 import { Type } from "typebox"
 
@@ -79,13 +80,9 @@ export default function (pi: ExtensionAPI): void {
         return errorResult(`Error loading session: ${err}`)
       }
 
-      const branch = sessionManager.getBranch()
-      const messages = branch
-        .filter(
-          (entry): entry is SessionEntry & { type: "message" } =>
-            entry.type === "message",
-        )
-        .map((entry) => entry.message)
+      const messages = sessionManager
+        .buildContextEntries()
+        .flatMap(sessionEntryToContextMessages)
 
       if (messages.length === 0) {
         return {
@@ -104,11 +101,6 @@ export default function (pi: ExtensionAPI): void {
         )
       }
 
-      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model)
-      if (!auth.ok) {
-        return errorResult(`Error: Query model unavailable: ${auth.error}`)
-      }
-
       const conversationText = serializeConversation(convertToLlm(messages))
       const userMessage: Message = {
         role: "user",
@@ -122,29 +114,20 @@ export default function (pi: ExtensionAPI): void {
       }
 
       try {
-        const response = await complete(
+        const answer = await completeText(
+          ctx,
           model,
-          { systemPrompt: QUERY_SYSTEM_PROMPT, messages: [userMessage] },
-          {
-            ...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
-            ...(auth.headers ? { headers: auth.headers } : {}),
-            ...(signal ? { signal } : {}),
-          },
+          QUERY_SYSTEM_PROMPT,
+          userMessage,
+          signal,
         )
-
-        if (response.stopReason === "aborted") {
+        if (answer === null) {
           return {
             content: [{ type: "text" as const, text: "Query was cancelled." }],
             details: { cancelled: true },
           }
         }
 
-        const answer = response.content
-          .filter((c): c is { type: "text"; text: string } => c.type === "text")
-          .map((c) => c.text)
-          .join("\n")
-          .trim()
-
         return {
           content: [{ type: "text" as const, text: answer }],
           details: {
@@ -154,7 +137,9 @@ export default function (pi: ExtensionAPI): void {
           },
         }
       } catch (err) {
-        return errorResult(`Error querying session: ${err}`)
+        return errorResult(
+          `Error querying session: ${err instanceof Error ? err.message : String(err)}`,
+        )
       }
     },
   })

package/node_modules/@herbertgao/pi-mermaid-open/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @tifan/pi-mermaid-open
 
+## 0.2.0
+
+### Minor Changes
+
+- [#116](https://github.com/HerbertGao/pi-extensions/pull/116) [`ecda398`](https://github.com/HerbertGao/pi-extensions/commit/ecda398b9a95212c512d53325c617e485e6ded8d) Thanks [@HerbertGao](https://github.com/HerbertGao)! - Open Mermaid diagrams skipped by Pi's native renderer with reason-aware selection, terminal image viewing, and an optional Herdr overlay.
+
+## 0.2.0
+
+### Minor Changes
+
+- [`b9d0e7e`](https://github.com/tifandotme/pi-extensions/commit/b9d0e7ec0e5e74afafba59e38334311f50e8615f) Thanks [@tifandotme](https://github.com/tifandotme)! - Add a Herdr overlay for viewing rendered Mermaid diagrams with Kitty graphics, zoom, and pan controls.
+
+- [`efc30c3`](https://github.com/tifandotme/pi-extensions/commit/efc30c353f435081efa00d3d30c0cd5293b33f8b) Thanks [@tifandotme](https://github.com/tifandotme)! - Update `/mermaid-open` to focus on diagrams Pi skipped, label skip reasons, show progress while rendering, and display selected diagrams as temporary PNGs in a terminal image popup instead of opening a browser.
+
 ## 0.1.3
 
 ### Patch Changes

package/node_modules/@herbertgao/pi-mermaid-open/README.md

@@ -2,9 +2,19 @@
 
 > HerbertGao-maintained fork of [@tifan/pi-mermaid-open](https://github.com/tifandotme/pi-extensions/tree/master/packages/pi-mermaid-open), distributed under MIT with the original attribution preserved.
 
-Extract Mermaid diagrams from recent pi assistant messages, render them to SVG, and open them in the system viewer.
+Find Mermaid diagrams that Pi left unrendered and show one in a terminal image viewer.
 
-The command scans the last 50 assistant messages for ` ```mermaid ` or ` ```mmd ` fences. If it finds more than one diagram, pi shows a picker with the message offset, diagram type, and title. Rendering uses `@mermaid-js/mermaid-cli` via `bunx`. SVGs are written under `<agent-dir>/artifacts/mermaid/` and opened with `open` on macOS, `xdg-open` on Linux, or `start` on Windows.
+<https://github.com/user-attachments/assets/d0c1d46f-0cba-4bf3-a44e-9aa0f4b8e3fd>
+
+## How it works
+
+- Scans assistant messages in the current branch for ` ```mermaid ` and ` ```mmd ` fences.
+- Hides diagrams that Pi already rendered and labels skipped diagrams by reason.
+- Renders diagrams as 4x PNGs with `@mermaid-js/mermaid-cli`.
+- Uses a non-blocking Herdr overlay with Kitty graphics when available.
+- Uses Pi's image viewer in other TUI sessions.
+- Saves PNGs under `<agent-dir>/artifacts/mermaid/` outside TUI mode.
+- In Herdr, use `+`/`=` and `-` to zoom, `h`/`j`/`k`/`l` or the arrow keys to pan, `0` to reset, and Enter or Escape to close.
 
 ## Install
 
@@ -12,13 +22,20 @@ The command scans the last 50 assistant messages for ` ```mermaid ` or ` ```mmd
 pi install npm:@herbertgao/pi-mermaid-open
 ```
 
+## Requirements
+
+- Bun is optional. The extension uses `bunx -y @mermaid-js/mermaid-cli` when Bun is available and falls back to `npx -y @mermaid-js/mermaid-cli`.
+- Herdr with Kitty graphics support is optional. In a compatible Herdr TUI session, `/mermaid-open` automatically links the bundled Herdr plugin, so you do not need to install it separately. Other TUI sessions use Pi's image viewer.
+- Network access on first use unless Mermaid CLI is already cached.
+- A Chromium browser available to Puppeteer. The extension skips Puppeteer's automatic browser download, so Puppeteer must find an existing cache or configured browser executable.
+
 ## Commands
 
-- `/mermaid-open`: Pick a Mermaid diagram from recent assistant messages, render it, and open the SVG.
+- `/mermaid-open`: Pick a Mermaid diagram from recent assistant messages, render it, and open the PNG.
 
 ## Release notes
 
-See [CHANGELOG.md](CHANGELOG.md)
+See [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

package/node_modules/@herbertgao/pi-mermaid-open/herdr-plugin/herdr-plugin.toml

@@ -0,0 +1,11 @@
+id = "pi-mermaid-open"
+name = "Pi Mermaid Open"
+version = "0.1.3"
+min_herdr_version = "0.8.0"
+platforms = ["linux", "macos", "windows"]
+
+[[panes]]
+id = "viewer"
+title = "Mermaid"
+command = ["node", "viewer.mjs"]
+placement = "overlay"