@pi-claudian/auto-save-to-markdown 0.1.2 → 0.2.0

package/README.md

@@ -78,11 +78,15 @@ session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.json
 
 # Fix login redirect loop
 
-## User · 13:05:12
+User · 13:05:12
+===
 
 The login page redirects in a loop after the auth refactor...
 
-## Assistant · 13:05:40 · claude-sonnet-4-5
+---
+
+Assistant · 13:05:40 · claude-sonnet-4-5
+===
 
 <details>
 <summary>Thinking</summary>
@@ -98,6 +102,8 @@ I'll trace the middleware order first.
 - `read` — {"filePath":"/Users/me/project/src/auth/middleware.ts"}
 
 > **Tool · read** /Users/me/project/src/auth/middleware.ts — 120 lines …
+
+---
 ```
 
 The body renders user and assistant messages in full (assistant thinking is
@@ -105,6 +111,13 @@ kept in a collapsible `<details>` block) and summarizes each tool call and
 result in one line, so the file stays readable while still showing what the
 agent did.
 
+Each message block opens with a setext level-1 info header (`User · …`,
+underlined with `===`) — one level above the `##` headings AI content
+typically starts with, and distinguishable from content `#` headings when
+parsing — and ends with a `---` separator wrapped in single blank lines
+(extra blank lines are trimmed), so blocks are easy to tell apart both when
+reading and when splitting the file programmatically.
+
 ### Fragmented thinking repair
 
 Some upstream reasoning streams (observed with z-ai/GLM via OpenRouter) store

package/README.zh.md

@@ -68,11 +68,15 @@ session_file: "~/.pi/agent/sessions/--Users-me-project-20260829-050500_ab12.json
 
 # 修复登录重定向死循环
 
-## User · 13:05:12
+User · 13:05:12
+===
 
 auth 重构之后登录页一直重定向死循环……
 
-## Assistant · 13:05:40 · claude-sonnet-4-5
+---
+
+Assistant · 13:05:40 · claude-sonnet-4-5
+===
 
 <details>
 <summary>Thinking</summary>
@@ -88,12 +92,19 @@ auth 重构之后登录页一直重定向死循环……
 - `read` — {"filePath":"/Users/me/project/src/auth/middleware.ts"}
 
 > **Tool · read** /Users/me/project/src/auth/middleware.ts — 120 lines …
+
+---
 ```
 
 正文完整渲染 user / assistant 消息（assistant 的 thinking 放在可折叠的
 `<details>` 块中），每个工具调用和结果各压缩成一行摘要，既可读又能看出
 agent 做了什么。
 
+每个消息块以 setext 一级信息头（`User · …`，下一行以 `===` 下划）开头——
+高于 AI 内容常见的 `##` 二级标题，解析时也能与内容中的 `#` 一级标题区分
+开——并以"上下各一个空行"包裹的 `---` 分隔线结尾（多余空行会被裁剪），
+无论是阅读还是程序化切分，都能清楚地区分每个消息块。
+
 ### 碎片化 thinking 修复
 
 部分上游推理流（在 z-ai/GLM 经 OpenRouter 的场景中观察到）会把 thinking

package/index.ts

@@ -20,6 +20,18 @@
  * - Frontmatter: title, session id, tree (branch key), model, provider,
  *   cumulative cost and tokens (input, output, cache read/write), message
  *   count, created/updated timestamps, project root and session file.
+ * - Body format: every message block opens with a setext-H1 info header
+ *   (`User · HH:MM:SS` / `Assistant · HH:MM:SS · model`, underlined with
+ *   `===`, distinct from the `#`/`##` ATX headings AI content uses) and
+ *   ends with a `---` separator 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 `<details><summary>Tool Calls</summary>` section. Previews stay
+ *   short (500 chars): full content is one Obsidian link away, and oversized
+ *   details bodies render unfolded in Obsidian. A result whose call was
+ *   saved in an earlier file (mid-turn manual save) falls back to a
+ *   standalone one-line block.
  * - Branching: each file records exactly ONE branch (the root→leaf path
  *   returned by sessionManager.getBranch()). State is persisted via
  *   `pi.appendEntry()` custom entries, which are part of the session tree
@@ -66,7 +78,7 @@ const NOTIFY_TAG = "[AutoSave]";
 
 const MAX_TITLE_LENGTH = 60;
 const TITLE_FALLBACK_LENGTH = 40;
-const TOOL_RESULT_PREVIEW = 300;
+const TOOL_RESULT_PREVIEW = 500;
 const TOOL_ARGS_PREVIEW = 160;
 
 type AgentMessage = SessionMessageEntry["message"];
@@ -278,10 +290,76 @@ export default function (pi: ExtensionAPI) {
 
   // ---------- markdown rendering ----------
 
-  function renderAssistant(m: AssistantMessage, t: string): string {
+  /**
+   * Strip leading blank lines and trailing whitespace from a rendered block,
+   * so joins and separators always keep exactly one blank line around them
+   * no matter what blank lines the content itself starts or ends with.
+   */
+  function tighten(s: string): string {
+    return s.replace(/^(?:[ \t]*\n)+/, "").replace(/\s+$/, "");
+  }
+
+  /** One tool call with its paired result preview (null when no result entry exists). */
+  interface RenderedToolCall {
+    name: string;
+    args: string;
+    result: string | null;
+  }
+
+  /** Flattened, length-capped result preview with error status suffix. */
+  function resultPreview(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();
+  }
+
+  /** Standalone one-line block for a result whose call is not in this file. */
+  function renderToolResult(m: ToolResultMessage): string {
+    return `> **Tool · ${m.toolName}** ${resultPreview(m)}`.trim();
+  }
+
+  /** "read, web_search ×2" — tool names with repeat counts, first-seen order. */
+  function summarizeToolNames(names: string[]): string {
+    const counts = new Map<string, number>();
+    for (const n of names) counts.set(n, (counts.get(n) ?? 0) + 1);
+    return [...counts].map(([n, c]) => (c > 1 ? `${n} ×${c}` : n)).join(", ");
+  }
+
+  /**
+   * Fold tool calls and their paired results into one collapsible section.
+   * Deliberately compact: Obsidian only collapses a details body it can
+   * render in view, so long previews make the section render unfolded.
+   */
+  function renderToolCallsDetails(calls: RenderedToolCall[]): string {
+    const summary = summarizeToolNames(calls.map((c) => c.name));
+    const items = calls.map((c) => {
+      const head = c.args ? `**\`${c.name}\`** \`${c.args}\`` : `**\`${c.name}\`**`;
+      const result = c.result === null ? "_(no result)_" : c.result || "_(empty result)_";
+      return `${head}\n\n> ${result}`;
+    });
+    return (
+      `<details>\n<summary>Tool Calls · ${calls.length} (${summary})</summary>\n\n` +
+      `${items.join("\n\n")}\n\n</details>`
+    );
+  }
+
+  function renderAssistant(
+    m: AssistantMessage,
+    t: string,
+    results: Map<string, ToolResultMessage>,
+  ): string {
     // Render blocks in their original chronological order: thinking always
     // precedes the text it produced, instead of being grouped after the fact.
-    const header = `## Assistant · ${t}${m.model ? ` · ${m.model}` : ""}`;
+    // Setext H1 (`===` underline): one level above the `##` headings AI
+    // content typically starts with, and distinct from content `#` headings.
+    const header = `Assistant · ${t}${m.model ? ` · ${m.model}` : ""}\n===`;
     const parts: string[] = [];
     const thinkings: string[] = [];
     const flushThinking = () => {
@@ -292,7 +370,7 @@ export default function (pi: ExtensionAPI) {
         thinkings.length = 0;
       }
     };
-    const calls: string[] = [];
+    const calls: RenderedToolCall[] = [];
     for (const b of m.content) {
       if (b.type === "text") {
         flushThinking();
@@ -301,47 +379,57 @@ export default function (pi: ExtensionAPI) {
         thinkings.push(repairThinking(b.thinking));
       } else if (b.type === "toolCall") {
         flushThinking();
-        calls.push(`- \`${b.name}\` — ${previewArgs(b.arguments)}`);
+        const r = results.get(b.id);
+        results.delete(b.id);
+        calls.push({
+          name: b.name,
+          args: previewArgs(b.arguments),
+          result: r ? resultPreview(r) : null,
+        });
       }
     }
     flushThinking();
-    if (calls.length) parts.push(`**Tool calls**\n\n${calls.join("\n")}`);
+    if (calls.length) parts.push(renderToolCallsDetails(calls));
     if (m.errorMessage) parts.push(`> Error: ${m.errorMessage.replace(/\s+/g, " ").trim()}`);
     if (parts.length === 0) parts.push("_(empty response)_");
     return `${header}\n\n${parts.join("\n\n")}`;
   }
 
-  function renderToolResult(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)" : "";
-    const line = `> **Tool · ${m.toolName}${status}** ${capped}`.trim();
-    return line;
-  }
-
   /** Render a chronological list of message entries as markdown blocks. */
   function renderEntries(entries: SessionMessageEntry[]): string {
+    // Tool calls sit in assistant entries while their results are separate
+    // toolResult entries, paired by toolCall id. Collect results first so
+    // each assistant block can fold its calls together with their results;
+    // results left unclaimed (their call was saved in an earlier file, e.g.
+    // a mid-turn manual save) render as standalone blocks.
+    const results = new Map<string, ToolResultMessage>();
+    for (const e of entries) {
+      if (e.message.role === "toolResult") results.set(e.message.toolCallId, e.message);
+    }
+
     const blocks: string[] = [];
     for (const e of entries) {
       const m = e.message;
       const t = clock(e.timestamp);
       if (m.role === "user") {
-        blocks.push(`## User · ${t}\n\n${userText(m.content)}`);
+        blocks.push(`User · ${t}\n===\n\n${userText(m.content)}`);
       } else if (m.role === "assistant") {
-        blocks.push(renderAssistant(m, t));
+        blocks.push(renderAssistant(m, t, results));
       } else if (m.role === "toolResult") {
+        // Claimed results (deleted from the map by their assistant block)
+        // were already folded inline; the rest have no call in this file.
+        if (!results.has(m.toolCallId)) continue;
         blocks.push(renderToolResult(m));
       }
       // Other roles (custom, bashExecution, branchSummary, compactionSummary)
       // are not part of the rendered conversation record.
     }
-    return blocks.join("\n\n");
+    if (blocks.length === 0) return "";
+    // Every block ends with a `---` separator wrapped in single blank lines
+    // (the blank line above also keeps `---` from turning the last content
+    // line into a setext H2). The trailing separator after the final block
+    // makes later appends uniform: new blocks simply continue after it.
+    return `${blocks.map(tighten).join("\n\n---\n\n")}\n\n---\n`;
   }
 
   // ---------- frontmatter ----------
@@ -560,8 +648,8 @@ export default function (pi: ExtensionAPI) {
 
     if (fullCreate) {
       const meta = computeMeta(ctx, plan.pathMessages, plan.branchKey, undefined);
-      const body = renderEntries(plan.pathMessages);
-      const content = `${frontmatter(meta)}\n\n# ${meta.title}\n\n${body}\n`;
+      const body = renderEntries(plan.pathMessages); // ends with the trailing separator
+      const content = `${frontmatter(meta)}\n\n# ${meta.title}\n\n${body}`;
       await atomicWrite(filePath, content);
       debug("created conversation file:", filePath);
       return {
@@ -584,10 +672,15 @@ export default function (pi: ExtensionAPI) {
 
     const existing = await fs.readFile(filePath, "utf-8");
     const meta = computeMeta(ctx, plan.pathMessages, plan.branchKey, parseCreated(existing));
-    const appended = renderEntries(plan.appendEntries);
+    const appended = renderEntries(plan.appendEntries); // ends with the trailing separator
     let updated = replaceFrontmatter(existing, frontmatter(meta));
-    if (!updated.endsWith("\n")) updated += "\n";
-    updated += `\n${appended}\n`;
+    // Collapse trailing blank lines to a single newline so the separator
+    // always has exactly one blank line above it, whatever earlier saves
+    // (or a manual edit) left behind.
+    updated = updated.replace(/\s*$/, "\n");
+    // Files written by the old format end without a `---` separator; add one
+    // at the boundary so old and new content stay delimited.
+    updated += updated.endsWith("---\n") ? `\n${appended}` : `\n---\n\n${appended}`;
     await atomicWrite(filePath, updated);
     debug("appended", plan.appendEntries.length, "entries to:", filePath);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-claudian/auto-save-to-markdown",
-  "version": "0.1.2",
+  "version": "0.2.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",