@maxiaochao/pi-toolkit 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,4 +1,13 @@
-## 2026-08-19 - v0.1.6
+## 2026-08-31 - v0.1.8
+
+- fix cache export branch attribution and update HTML artifact guidance
+
+## 2026-08-21 - v0.1.7
+
+- add the html-artifact skill for interactive HTML explanations and codebase visualizations
+- register and package the skill for Pi discovery
+- prefer `.cache/html/` for generated temporary HTML artifacts
+
 
 - expand global agent guidance and reuse-before-writing rules
 

package/extensions/cache-export/index.ts

@@ -63,7 +63,10 @@ export default function (pi) {
   pi.registerCommand("cache_export", {
     description: "Export a tau-style interactive cache dashboard (hit-rate charts, per-request table, events)",
     handler: async (args, ctx) => {
-      const entries = ctx.sessionManager.getEntries();
+      const sessionManager = ctx.sessionManager;
+      const entries = typeof sessionManager.getBranch === "function"
+        ? sessionManager.getBranch()
+        : sessionManager.getEntries();
       if (!entries || entries.length === 0) {
         ctx.ui.notify("No session entries to analyze.", "error");
         return;

package/extensions/cache-export/tests/run-tests.mjs

@@ -1,5 +1,9 @@
 // Deterministic test cases for analyzeStreaks / analyzeMisses / parseEntries.
 // Run: node --experimental-strip-types tests/run-tests.mjs
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import registerCacheExport from "../index.ts";
 import { parseEntries, analyzeStreaks, analyzeMisses, lineChartForTest } from "../render.ts";
 
 let pass = 0, fail = 0;
@@ -314,6 +318,53 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
     s.length === 2 && s.every((x) => x.hits.length === 3), JSON.stringify(s.map((x) => [x.from, x.to])));
 }
 
+// Q. subagent results remain visible as main-session tool input -----------
+{
+  const entries = [
+    req({ cached: 0, fresh: 10000, min: 1, content: [
+      { type: "toolCall", tool: "subagent", name: "subagent" },
+      { type: "toolCall", tool: "bash", name: "bash" },
+    ] }),
+    toolResult("delegated result", "subagent"),
+    toolResult("ordinary result", "bash"),
+    req({ cached: 9000, fresh: 10000, min: 2 }),
+  ];
+  const d = parseEntries(entries);
+  check("Q subagent invocation remains in main-session tool counts",
+    d.toolCalls.some(([name]) => name === "subagent") && d.toolCalls.some(([name]) => name === "bash"),
+    JSON.stringify(d.toolCalls));
+  check("Q subagent result remains available for main fresh-input attribution",
+    d.requests[1].gapTools.length === 2 && d.requests[1].gapTools.some(({ tool }) => tool === "subagent"),
+    JSON.stringify(d.requests[1].gapTools));
+}
+
+// R. command exports only the current main-session branch ----------------
+{
+  const root = mkdtempSync(join(tmpdir(), "cache-export-test-"));
+  const reportFile = join(root, "report.html");
+  const entry = (value, id, parentId) => ({ ...value, id, parentId });
+  const first = entry(req({ cached: 9000, fresh: 1000, min: 1, model: "main-first" }), "p1", null);
+  const abandoned = entry(req({ cached: 0, fresh: 9000, min: 2, model: "abandoned-model" }), "p2", "p1");
+  const active = entry(req({ cached: 8000, fresh: 2000, min: 3, model: "active-model" }), "p3", "p1");
+
+  let command;
+  registerCacheExport({ registerCommand: (name, definition) => { if (name === "cache_export") command = definition; } });
+  await command.handler(reportFile, {
+    sessionManager: {
+      getBranch: () => [first, active],
+      getEntries: () => [first, abandoned, active],
+      getSessionFile: () => join(root, "main.jsonl"),
+      getSessionId: () => "main",
+    },
+    ui: { notify: () => {} },
+  });
+  const html = readFileSync(reportFile, "utf8");
+  check("R current branch excludes abandoned requests",
+    html.includes("2 requests") && html.includes("active-model") && !html.includes("abandoned-model"));
+  check("R main-only report has no subagent dashboard", !html.includes("Subagent cache"));
+  rmSync(root, { recursive: true, force: true });
+}
+
 // K. degenerate inputs ---------------------------------------------------
 {
   check("K empty session -> no crash, no streaks", analyzeStreaks(parseEntries([]).requests).length === 0);

package/global/AGENTS.md

@@ -102,4 +102,9 @@ After each significant step:
 
 ---
 
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+## Output Format Preference
+
+For complex explanations, prefer a runnable HTML artifact over a long Markdown-only response when the content benefits from visual structure or interaction. This includes workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations. Keep ordinary prose, short answers, diffs, and focused code reviews in Markdown.
+
+When using HTML, create a self-contained, responsive artifact in the project's established output location, or `.cache/html/<descriptive-name>.html` when no convention exists. Use semantic HTML, accessible controls, escaped code blocks, and small useful interactions. Return a concise Markdown summary with a clickable local file path; if a preview/server tool is available, start it and return the preview URL only after verifying the page is not blank and its assets load.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Personal pi coding agent toolkit: /todos extension + /cache_export interactive cache dashboard.",
   "type": "module",
   "keywords": [
@@ -12,7 +12,8 @@
     "README.md",
     "CHANGELOG.md",
     "global/AGENTS.md",
-    "scripts/install-agents.mjs"
+    "scripts/install-agents.mjs",
+    "skills"
   ],
   "repository": {
     "type": "git",
@@ -22,6 +23,9 @@
     "extensions": [
       "./extensions/todo.ts",
       "./extensions/cache-export/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {

package/skills/html-artifact/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: html-artifact
+description: Create self-contained, responsive HTML artifacts for complex explanations that benefit from visual structure or interaction, including workflows, code/module relationships, state machines, event/data flows, architecture maps, timelines, comparisons, dashboards, and interactive demonstrations.
+---
+
+# HTML Artifact
+
+## Decide the format
+
+Use Markdown when the response is short, linear, text-first, or primarily a focused code review. Use an HTML artifact when visual layout, filtering, expanding details, tabs, highlighting, diagrams, timelines, or interactive state changes materially improve understanding.
+
+Do not create HTML merely to wrap a small answer. The artifact should reduce cognitive load and make the subject easier to inspect.
+
+## Create the artifact
+
+1. Read the relevant code and verify names, relationships, and behavior before visualizing them.
+2. Follow the project's existing output convention. If none exists, write to `.cache/html/<descriptive-name>.html`.
+3. Prefer one self-contained HTML file with inline CSS and JavaScript so it can be opened or previewed without a build step.
+4. Use semantic HTML, responsive layout, keyboard-accessible controls, visible focus states, and stable dimensions for interactive elements.
+5. Use restrained styling suited to the domain. Keep diagrams and panels scannable; do not hide important information behind interaction.
+6. Escape source code before placing it in `<pre><code>` blocks. Do not alter code identifiers, paths, or quoted source text for presentation.
+7. Add only interactions that answer a real viewing need: tabs, expand/collapse, search/filter, step-through state, highlighting, or a reset control.
+8. Keep external dependencies out unless the project already uses them. If a library is necessary, document the dependency and provide a usable fallback when practical.
+
+## Verify and report
+
+After writing the file, verify that it exists and contains a complete document. If a preview or dev-server tool is available, start it and check the returned health status before reporting success. Use the preview URL returned by that tool; never present `localhost` as a user-facing online URL when the environment uses a reverse proxy.
+
+Respond with a concise Markdown summary and a clickable file path or verified preview URL. Mention any limitation, such as a preview service not being available. Do not paste the entire HTML into the chat unless the user explicitly asks for it.