pi-auto-save-to-markdown 0.8.1 → 0.9.0

package/README.md

@@ -28,6 +28,10 @@ pi install npm:pi-auto-save-to-markdown
 Automatic: after every settled agent turn (`agent_settled`), the current
 conversation branch is written to `<cwd>/<folder>/<title>-<key>-<time>.md`.
 
+Sessions Pi does not persist (in-memory, `--no-session` — including the
+ephemeral auxiliary agents host clients spawn next to the real conversation,
+such as Claudian's title generation) are skipped by every automatic save; only
+the explicit `/save-conversation` command archives such a session on demand.
 Manual: run `/save-conversation` to save the current branch immediately and
 report the file path.
 
@@ -88,11 +92,11 @@ original creation timestamp — and rewrites the frontmatter title and the
 document heading to match. The rename happens at most once: later `/name`
 changes never touch the filename, and manually renamed files are left alone.
 
-```markdown
+````markdown
 ---
 title: "Fix login redirect loop"
 agent: "pi"
-format_version: "1.5"
+format_version: "1.6"
 session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
 session_key: "c2088d77"
 branch_last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
@@ -137,21 +141,27 @@ I'll trace the middleware order first.
 > [!quote]- Tool Calls · 1 (read)
 > **`read`** `{"filePath":"/Users/me/project/src/auth/middleware.ts"}`
 >
-> > `import { NextResponse } from "next/server"; export function middleware(…) …`
+> ```
+> import { NextResponse } from "next/server";
+> export function middleware(…) …
+> ```
 
 ---
-```
+````
 
 The body renders user and assistant messages in full (assistant thinking and
 per-turn tool calls are each folded into a collapsed Obsidian callout —
-`> [!tldr]- Thinking` and `> [!quote]- Tool Calls · …`) and summarizes each
-tool call and result in one line, so the file stays readable while still
-showing what the agent did. Callouts are used instead of HTML `<details>`
-because Obsidian renders markdown inside HTML blocks unreliably; outside
-Obsidian the callouts degrade to plain blockquotes. Result and argument
-previews are wrapped in inline code spans (with a delimiter sized to survive
-backticks inside the content), so raw tool output renders literally instead of
-being parsed as markdown.
+`> [!tldr]- Thinking` and `> [!quote]- Tool Calls · …`), recording every tool
+call with its full raw result: the file is a documentary record that may be
+@-referenced back into a conversation, and a truncated half-result would be
+wasted when the tool is called again and misleading when it is not, while
+local reading (grep, ranged reads) makes size a non-issue. Callouts are used
+instead of HTML `<details>` because Obsidian renders markdown inside HTML
+blocks unreliably; outside Obsidian the callouts degrade to plain blockquotes.
+Arguments render as full JSON in inline code spans and results verbatim —
+whitespace intact, nothing capped — in fenced code blocks (with a delimiter
+sized to survive backticks inside the content), so raw tool output renders
+literally instead of being parsed as markdown.
 
 Prompt blocks the client or the agent injects into a user message — the
 editor's active selection, attached or referenced notes, loaded skills — are

package/README.zh.md

@@ -21,6 +21,10 @@ pi install npm:pi-auto-save-to-markdown
 
 自动：每个 agent 轮次完全结束（`agent_settled`，含自动重试与压缩全部完成）后，当前对话分支写入 `<cwd>/<文件夹>/<标题>-<key>-<时间>.md`。
 
+Pi 未持久化的会话（内存态、`--no-session`——包括宿主客户端在真实对话旁派生的临时辅助
+agent，例如 Claudian 的标题生成）会被所有自动保存路径跳过；只有显式的
+`/save-conversation` 命令才会按需归档此类会话。
+
 手动：运行 `/save-conversation` 立即保存当前分支并显示文件路径。
 
 批量：运行 `/save-conversation-all` 保存**当前项目的全部 session**——即项目的
@@ -62,11 +66,11 @@ PI_SAVE_CONVERSATION_DIR=notes/ai pi
 
 会话的真实名称在建文件之后才到达时（如 Claudian 在首轮回复后才生成标题），下一次保存会把文件一次性改名为 `<名称>-<key>-<原时间戳>.md`（保留原创建时间戳），并同步改写 frontmatter 标题与正文标题。改名至多发生一次：之后的 `/name` 改名不再影响文件名，手动整理过的文件名也不会被动。
 
-```markdown
+````markdown
 ---
 title: "修复登录重定向死循环"
 agent: "pi"
-format_version: "1.5"
+format_version: "1.6"
 session_id: "d0a4f541-976d-4d1b-8e1c-30a1f2b3c4d5"
 session_key: "c2088d77"
 branch_last_entry_id: "019be3a2-1f4d-7c8a-9b01-d23e45f6a7b8"
@@ -111,19 +115,24 @@ Assistant <span style="font-size: 0.5em; color: var(--text-faint);">2026-08-29 1
 > [!quote]- Tool Calls · 1 (read)
 > **`read`** `{"filePath":"/Users/me/project/src/auth/middleware.ts"}`
 >
-> > `import { NextResponse } from "next/server"; export function middleware(…) …`
+> ```
+> import { NextResponse } from "next/server";
+> export function middleware(…) …
+> ```
 
 ---
-```
+````
 
 正文完整渲染 user / assistant 消息（assistant 的 thinking 与每轮工具调用
 分别折叠在可折叠的 Obsidian callout 中——`> [!tldr]- Thinking` 和
-`> [!quote]- Tool Calls · …`），每个工具调用和结果各压缩成一行摘要，既可读
-又能看出 agent 做了什么。之所以用 callout 而不是 HTML `<details>`，是因为
-Obsidian 对 HTML 块内嵌 Markdown 的渲染不可靠；在非 Obsidian 环境下 callout
-退化为普通引用块。结果与参数预览会包在 inline code 里（分隔符长度会自动
-压过内容中的反引号序列），工具的原始输出因此按字面渲染，不会被当作
-Markdown 解析。
+`> [!quote]- Tool Calls · …`），每次工具调用连同其完整原始结果一起记录：
+归档文件是可能被 @ 引回对话的史料，截断的半个结果在工具重调时是浪费、在
+不再调用时是误导，而局部阅读（grep、按行段读取）让体积不成问题。之所以用
+callout 而不是 HTML `<details>`，是因为 Obsidian 对 HTML 块内嵌 Markdown 的
+渲染不可靠；在非 Obsidian 环境下 callout 退化为普通引用块。参数以完整 JSON
+包在 inline code 里，结果逐字保真——空白原样、不截断——放在 fenced code
+block 中（分隔符长度会自动压过内容中的反引号序列），工具的原始输出因此按
+字面渲染，不会被当作 Markdown 解析。
 
 客户端或 agent 注入到用户消息中的提示块——编辑器当前选区、附加或引用的
 笔记、加载的 skill——会从原始 XML（Obsidian 无法渲染，只会显示成裸露的

package/index.ts

@@ -9,6 +9,15 @@
  * - Trigger: `agent_settled` — fires once per user prompt, after the turn is
  *   fully done (including automatic retries and compaction), so each save
  *   captures a settled state of the conversation.
+ * - Skip rule: every automatic path (the `agent_settled` save and the batch
+ *   command's live save) skips sessions Pi does not persist — no session
+ *   file, i.e. an in-memory SessionManager (`--no-session`): those are
+ *   ephemeral auxiliary agents host clients spawn next to the real
+ *   conversation (Claudian's title generation, instruction refinement,
+ *   inline edits) or one-shot `pi --no-session` runs, not project
+ *   conversations, and archiving them would mint junk "User's request …"
+ *   files. The manual /save-conversation command still saves such a session
+ *   on explicit demand; the batch never sees them (no jsonl on disk).
  * - Location: a subfolder of the session's working directory (`ctx.cwd`, the
  *   directory the session was started in), defaulting to `ai-conversations`.
  *   Override with the PI_SAVE_CONVERSATION_DIR environment variable; set it to
@@ -42,18 +51,22 @@
  *   wrapped in single blank lines.
  * - Tool call/result folding: calls live in the assistant entry while their
  *   results are separate toolResult entries; saves pair them by toolCall id
- *   and fold each assistant block's calls, with a short result preview each,
- *   into one collapsed Obsidian callout (`> [!quote]- Tool Calls · …`).
- *   Thinking folds the same way into `> [!tldr]- Thinking`. Callouts are used
- *   instead of HTML `<details>` because Obsidian's views render embedded
- *   markdown inside HTML blocks unreliably, while callouts fold and render
- *   markdown in both Live Preview and Reading view. Outside Obsidian the
- *   callouts degrade to plain blockquotes. Argument previews and result
- *   previews are wrapped in inline code spans (delimiter sized to survive
- *   backticks inside the content), so raw output renders literally instead
- *   of being parsed as markdown. A result whose call was saved in
- *   an earlier file (mid-turn manual save) falls back to a standalone
- *   one-line block.
+ *   and fold each assistant block's calls, with their FULL results, into one
+ *   collapsed Obsidian callout (`> [!quote]- Tool Calls · …`). Thinking folds
+ *   the same way into `> [!tldr]- Thinking`. Callouts are used instead of
+ *   HTML `<details>` because Obsidian's views render embedded markdown
+ *   inside HTML blocks unreliably, while callouts fold and render markdown
+ *   in both Live Preview and Reading view. Outside Obsidian the callouts
+ *   degrade to plain blockquotes. Arguments render as full JSON in inline
+ *   code spans and results verbatim — whitespace intact, nothing capped —
+ *   in fenced code blocks (delimiters sized to survive backticks inside the
+ *   content), so raw output renders literally instead of being parsed as
+ *   markdown. Nothing is truncated because the file is a documentary record
+ *   that may be @-referenced back into a conversation: a half result is
+ *   wasted when the tool is called again and misleading when it is not,
+ *   while local reading (grep, ranged reads) makes size a non-issue. A
+ *   result whose call was saved in an earlier file (mid-turn manual save)
+ *   renders as a standalone block with the same full content.
  * - Injected prompt blocks: the host client and the agent runtime append
  *   machine-readable XML to user messages — the editor's active selection
  *   (CDATA content), note references and attachments (linked_note /
@@ -185,7 +198,13 @@ import * as fsSync from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { debug } from "./debug.js";
-import { callout, inlineCode, renderUserMessageText, stripInjectedBlocks } from "./markdown.js";
+import {
+  callout,
+  fencedCode,
+  inlineCode,
+  renderUserMessageText,
+  stripInjectedBlocks,
+} from "./markdown.js";
 
 const CUSTOM_TYPE = "pi-claudian-auto-save-markdown";
 const ENV_SUBDIR = "PI_SAVE_CONVERSATION_DIR";
@@ -225,7 +244,7 @@ const SAVE_STATE_SCHEMA = "1.2";
  * the frontmatter and the document heading); additive frontmatter fields do
  * NOT bump it — they are invisible to any within-major parser.
  */
-const FORMAT_VERSION = "1.5";
+const FORMAT_VERSION = "1.6";
 
 /**
  * Package version of this extension, read best-effort from the adjacent
@@ -246,9 +265,6 @@ const EXTENSION_VERSION: string | null = (() => {
 
 const MAX_TITLE_LENGTH = 60;
 const TITLE_FALLBACK_LENGTH = 40;
-const TOOL_RESULT_PREVIEW = 500;
-const TOOL_ARGS_PREVIEW = 160;
-
 type AgentMessage = SessionMessageEntry["message"];
 type UserMessage = Extract<AgentMessage, { role: "user" }>;
 type AssistantMessage = Extract<AgentMessage, { role: "assistant" }>;
@@ -950,15 +966,13 @@ export default function (pi: ExtensionAPI) {
     return "untitled";
   }
 
-  function previewArgs(args: unknown): string {
-    let s: string;
+  /** Full argument JSON on one line (JSON.stringify escapes newlines), never truncated. */
+  function renderArgs(args: unknown): string {
     try {
-      s = JSON.stringify(args) ?? "";
+      return JSON.stringify(args) ?? "";
     } catch {
-      s = String(args);
+      return String(args);
     }
-    s = s.replace(/\s+/g, " ").trim();
-    return s.length > TOOL_ARGS_PREVIEW ? s.slice(0, TOOL_ARGS_PREVIEW) + " …" : s;
   }
 
   // ---------- markdown rendering ----------
@@ -972,30 +986,37 @@ export default function (pi: ExtensionAPI) {
     return s.replace(/^(?:[ \t]*\n)+/, "").replace(/\s+$/, "");
   }
 
-  /** One tool call with its paired result preview (null when no result entry exists). */
+  /** One tool call with its paired full result (null when no result entry exists). */
   interface RenderedToolCall {
     name: string;
     args: string;
     result: string | null;
+    error: boolean;
   }
 
-  /** Flattened, length-capped result preview with error status suffix. */
-  function resultPreview(m: ToolResultMessage): string {
+  /**
+   * Full raw result text: text blocks joined with blank lines, non-text
+   * blocks as placeholders. Error status stays OUT of the content (it rides
+   * the call's head line) so the saved text is exactly what the tool
+   * returned.
+   */
+  function resultText(m: ToolResultMessage): string {
     const texts: string[] = [];
     for (const b of m.content) {
       if (b.type === "text") texts.push(b.text);
       else texts.push(`_[image: ${b.mimeType}]_`);
     }
-    const flat = texts.join(" ").replace(/\s+/g, " ").trim();
-    const capped =
-      flat.length > TOOL_RESULT_PREVIEW ? flat.slice(0, TOOL_RESULT_PREVIEW) + " …" : flat;
-    const status = m.isError ? " (error)" : "";
-    return `${capped}${status}`.trim();
+    return texts.join("\n\n").trim();
   }
 
-  /** Standalone one-line block for a result whose call is not in this file. */
+  /**
+   * Standalone block for a result whose call is not in this file — same full
+   * content as folded results.
+   */
   function renderToolResult(m: ToolResultMessage): string {
-    return `> **Tool · ${m.toolName}** ${inlineCode(resultPreview(m))}`.trim();
+    const text = resultText(m);
+    const err = m.isError ? " (error)" : "";
+    return `**Tool · ${m.toolName}**${err}\n\n${text ? fencedCode(text) : "_(empty result)_"}`;
   }
 
   /** "read, web_search ×2" — tool names with repeat counts, first-seen order. */
@@ -1007,16 +1028,20 @@ export default function (pi: ExtensionAPI) {
 
   /**
    * Fold tool calls and their paired results into one collapsed callout.
-   * Argument JSON and result previews are wrapped in inline code spans, so
-   * raw output renders literally instead of being parsed as markdown.
+   * Arguments render as full JSON in inline code spans and results verbatim
+   * in fenced code blocks, so raw output renders literally instead of being
+   * parsed as markdown.
    */
   function renderToolCallsCallout(calls: RenderedToolCall[]): string {
     const summary = summarizeToolNames(calls.map((c) => c.name));
     const items = calls.map((c) => {
-      const head = c.args ? `**\`${c.name}\`** ${inlineCode(c.args)}` : `**\`${c.name}\`**`;
+      const err = c.error ? " (error)" : "";
+      const head = c.args
+        ? `**\`${c.name}\`**${err} ${inlineCode(c.args)}`
+        : `**\`${c.name}\`**${err}`;
       const result =
-        c.result === null ? "_(no result)_" : inlineCode(c.result || "_(empty result)_");
-      return `${head}\n\n> ${result}`;
+        c.result === null ? "_(no result)_" : c.result ? fencedCode(c.result) : "_(empty result)_";
+      return `${head}\n\n${result}`;
     });
     return callout("quote", `Tool Calls · ${calls.length} (${summary})`, items.join("\n\n"));
   }
@@ -1052,8 +1077,9 @@ export default function (pi: ExtensionAPI) {
         results.delete(b.id);
         calls.push({
           name: b.name,
-          args: previewArgs(b.arguments),
-          result: r ? resultPreview(r) : null,
+          args: renderArgs(b.arguments),
+          result: r ? resultText(r) : null,
+          error: r ? r.isError : false,
         });
       }
     }
@@ -1925,6 +1951,15 @@ export default function (pi: ExtensionAPI) {
 
   // 1. Automatic: save after every settled agent turn.
   pi.on("agent_settled", async (_event: AgentSettledEvent, ctx: ExtensionContext) => {
+    // Non-persisted sessions (in-memory, `--no-session`) are ephemeral
+    // auxiliary agents — see the skip rule in the header. The manual
+    // /save-conversation command below is the explicit-demand escape hatch.
+    if (!ctx.sessionManager.getSessionFile()) {
+      debug(
+        "agent_settled — session has no session file (in-memory / --no-session); skipping auto-save",
+      );
+      return;
+    }
     debug("agent_settled — saving conversation");
     try {
       const live = liveContext(ctx);
@@ -2005,28 +2040,36 @@ export default function (pi: ExtensionAPI) {
 
     // The live session first, through the normal path: its in-memory tree may
     // be fresher than disk, and its state entry goes through pi.appendEntry.
-    try {
-      const r = await runSave(live);
-      count(r);
-      if (ctx.hasUI) {
-        const target = r.file ? relativeForUser(live, r.file) : "";
-        ctx.ui.notify(`${NOTIFY_TAG} ${r.message}${target ? ` → ${target}` : ""}`, "info");
-        if (r.recovered && r.file) {
-          ctx.ui.notify(`${NOTIFY_TAG} ${r.recovered} → ${target}`, "warning");
+    // A non-persisted current session (in-memory / --no-session) is skipped —
+    // see the skip rule in the header.
+    if (!ctx.sessionManager.getSessionFile()) {
+      debug(
+        "/" + COMMAND_ALL + " — current session not persisted (in-memory / --no-session); skipped",
+      );
+    } else {
+      try {
+        const r = await runSave(live);
+        count(r);
+        if (ctx.hasUI) {
+          const target = r.file ? relativeForUser(live, r.file) : "";
+          ctx.ui.notify(`${NOTIFY_TAG} ${r.message}${target ? ` → ${target}` : ""}`, "info");
+          if (r.recovered && r.file) {
+            ctx.ui.notify(`${NOTIFY_TAG} ${r.recovered} → ${target}`, "warning");
+          }
+          if (r.switchedFrom && r.file) {
+            ctx.ui.notify(
+              `${NOTIFY_TAG} branch changed — new branch file ${target}; the earlier branch file ${r.switchedFrom} is kept`,
+              "info",
+            );
+          }
         }
-        if (r.switchedFrom && r.file) {
-          ctx.ui.notify(
-            `${NOTIFY_TAG} branch changed — new branch file ${target}; the earlier branch file ${r.switchedFrom} is kept`,
-            "info",
-          );
+      } catch (e) {
+        failed.push("<current session>");
+        debug("/" + COMMAND_ALL + " live save failed:", String(e));
+        if (ctx.hasUI) {
+          ctx.ui.notify(`${NOTIFY_TAG} save failed: ${String(e)}`, "error");
         }
       }
-    } catch (e) {
-      failed.push("<current session>");
-      debug("/" + COMMAND_ALL + " live save failed:", String(e));
-      if (ctx.hasUI) {
-        ctx.ui.notify(`${NOTIFY_TAG} save failed: ${String(e)}`, "error");
-      }
     }
 
     // The project's sessions directory — every session jsonl lives there.

package/markdown.ts

@@ -27,6 +27,19 @@ export function inlineCode(text: string): string {
   return `${fence}${text}${fence}`;
 }
 
+/**
+ * Fenced code block for arbitrary raw output (full tool results): the fence
+ * is always one backtick longer than the longest backtick run inside the
+ * text (and at least three), so content that itself contains backticks
+ * cannot break out of the block. Tool output renders literally, whitespace
+ * intact, instead of being parsed as markdown.
+ */
+export function fencedCode(text: string): string {
+  const longest = (text.match(/`+/g) ?? []).reduce((a, r) => Math.max(a, r.length), 0);
+  const fence = "`".repeat(Math.max(3, longest + 1));
+  return `${fence}\n${text}\n${fence}`;
+}
+
 /**
  * Obsidian callout (`> [!type]- title`) wrapping a markdown body: every body
  * line is prefixed with `>` (empty lines become bare `>`), so the body keeps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-auto-save-to-markdown",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Pi extension that automatically saves each completed conversation turn as a markdown file with YAML frontmatter, one file per session-tree branch.",
   "type": "module",
   "license": "MIT",