@cad0p/pi-napkin 0.3.1 → 0.3.2-20260801.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,7 +10,7 @@ pi-napkin depends on the [`@cad0p/napkin`](https://github.com/cad0p/napkin) CLI.
10
10
 
11
11
  ```bash
12
12
  npm install -g @cad0p/napkin
13
- # or: bun add -g @cad0p/napkin
13
+ # or: pnpm add -g @cad0p/napkin
14
14
  ```
15
15
 
16
16
  Then install the pi-napkin extension:
@@ -66,10 +66,6 @@ The [`napkin` skill](skills/napkin/SKILL.md) gives the agent a full CLI referenc
66
66
  - `/distill-auto-this-session` — Turn the automatic timer off / on for the current session. Persists across pi restarts.
67
67
  - `/distill-status` — Show active background distill processes for the current vault.
68
68
 
69
- ### Agent tool
70
-
71
- - `napkin_distill_status` — JSON version of `/distill-status`, for the agent to query programmatically before making concurrent vault edits.
72
-
73
69
  ## Auto-distill requires subdir vault layout
74
70
 
75
71
  Auto-distill (interval + shutdown) uses git worktrees for concurrency safety.
@@ -499,7 +495,7 @@ Why manual: PR #12 deliberately avoids automatic migration. The orphaned `.gitat
499
495
  CI uses bash-stub fixtures (`extensions/distill/test-fixtures/agent-stubs/`) to cover the agent-behavior space without burning tokens. For ad-hoc re-validation that the full runtime — wrapper subprocess + agent + JS-side polling — still walks cleanly through a real model, run:
500
496
 
501
497
  ```bash
502
- bun run verify:e2e
498
+ pnpm run verify:e2e
503
499
  ```
504
500
 
505
501
  The script (`scripts/verify-e2e.ts`) creates a tmpdir vault by invoking the real `napkin init` CLI, then drives the production session_start handler so auto-init's `git init` + managed `.gitignore` block + initial commit run end-to-end, then triggers the `/distill` command handler so the production `runDistillWith` path runs (real wrapper subprocess, real 2-second `setInterval` poller). It asserts on the dispatched UI notification's severity + message together with filesystem post-conditions: no conflict markers, HEAD on default branch, agent's squash commit landed, distill branch removed, worktree removed, outcome sidecar with class `merged-content`, and origin advanced.
@@ -31,7 +31,10 @@ import * as os from "node:os";
31
31
  import * as path from "node:path";
32
32
 
33
33
  import { Napkin } from "@cad0p/napkin";
34
- import { SessionManager } from "@earendil-works/pi-coding-agent";
34
+ import {
35
+ parseSessionEntries,
36
+ SessionManager,
37
+ } from "@earendil-works/pi-coding-agent";
35
38
  import { buildDistillPrompt } from "./distill-prompt";
36
39
  import { DISTILL_WRAPPER_SCRIPT } from "./scripts-paths";
37
40
 
@@ -148,6 +151,8 @@ export function generateDistillBranchName(
148
151
  */
149
152
  export const DISTILL_SUBDIR = path.join(".napkin", "distill");
150
153
 
154
+ export const DISTILL_PROMPT_CACHE_KEY_ENV = "NAPKIN_DISTILL_PROMPT_CACHE_KEY";
155
+
151
156
  /**
152
157
  * Resolve the root directory where this vault's distill worktrees live.
153
158
  * Follows XDG Base Directory Spec: `~/.cache/napkin-distill/<hash>/` by
@@ -218,6 +223,12 @@ function assertVaultIsGitRepo(vaultPath: string): void {
218
223
  }
219
224
  }
220
225
 
226
+ function readSessionId(sessionFile: string): string | undefined {
227
+ const entries = parseSessionEntries(fs.readFileSync(sessionFile, "utf-8"));
228
+ const header = entries.find((e) => e.type === "session");
229
+ return header?.id;
230
+ }
231
+
221
232
  /**
222
233
  * Invoke `git` inside a specific cwd. Returns `{status, stdout, stderr}`.
223
234
  * Does not throw on non-zero exit \u2014 callers decide how to react (retry,
@@ -939,6 +950,7 @@ export function spawnDistillInWorktree(
939
950
  const spawnFn = opts.spawnFn ?? spawn;
940
951
 
941
952
  const workspace = createDistillWorkspace(vault, sessionFile, parentCwd);
953
+ const parentSessionId = readSessionId(sessionFile);
942
954
 
943
955
  const defaultBranch = detectDefaultBranch(vault);
944
956
 
@@ -1007,6 +1019,9 @@ export function spawnDistillInWorktree(
1007
1019
  env: {
1008
1020
  ...process.env,
1009
1021
  NAPKIN_DISTILL_NO_RECURSE: "1",
1022
+ ...(parentSessionId
1023
+ ? { [DISTILL_PROMPT_CACHE_KEY_ENV]: parentSessionId }
1024
+ : {}),
1010
1025
  },
1011
1026
  });
1012
1027
  proc.unref();
@@ -1018,7 +1033,7 @@ export function spawnDistillInWorktree(
1018
1033
  }
1019
1034
 
1020
1035
  // ============================================================================
1021
- // Status helpers (/distill-status + napkin_distill_status tool, Phase C2)
1036
+ // Status helpers (/distill-status, Phase C2)
1022
1037
  // ============================================================================
1023
1038
 
1024
1039
  /**
@@ -1028,9 +1043,6 @@ export function spawnDistillInWorktree(
1028
1043
  * Liveness (`alive`) is decided at read time via `process.kill(pid, 0)`,
1029
1044
  * so a freshly crashed wrapper is reported with `alive: false` (and
1030
1045
  * `/distill-status` renders it as stale).
1031
- *
1032
- * Fields are kept flat + JSON-friendly so the pi tool can serialize the
1033
- * array directly.
1034
1046
  */
1035
1047
  export interface ActiveDistill {
1036
1048
  pid: number;
@@ -1066,8 +1078,8 @@ export interface ActiveDistill {
1066
1078
  *
1067
1079
  * Invokes `git worktree list --porcelain` exactly once and does NOT touch
1068
1080
  * the branch list — so callers that only need the active set (e.g. the
1069
- * `/distill-status` slash command and `napkin_distill_status` agent tool)
1070
- * don't pay for a `git branch` invocation they don't need.
1081
+ * `/distill-status` slash command) don't pay for a `git branch` invocation
1082
+ * they don't need.
1071
1083
  * (R2-4: restored a pre-CLN-3 fast path.)
1072
1084
  */
1073
1085
  export function getActiveDistills(vault: StaleCleanupVault): ActiveDistill[] {
@@ -12,7 +12,6 @@ import type {
12
12
  } from "@earendil-works/pi-coding-agent";
13
13
  import { SessionManager } from "@earendil-works/pi-coding-agent";
14
14
  import type { AutocompleteItem } from "@earendil-works/pi-tui";
15
- import { Type } from "@sinclair/typebox";
16
15
  import {
17
16
  countTrackedFiles,
18
17
  ensureVaultReadyForDistill,
@@ -22,6 +21,7 @@ import {
22
21
  type ActiveDistill,
23
22
  cleanupDistillWorkspace,
24
23
  cleanupStaleWorktrees,
24
+ DISTILL_PROMPT_CACHE_KEY_ENV,
25
25
  DistillError,
26
26
  type DistillOutcome,
27
27
  findDistillErrorLogForBranch,
@@ -35,6 +35,29 @@ import { surfaceHealthFindings, surfaceSetupError } from "./health-notify";
35
35
  import { getSessionTouchedFiles } from "./session-touched-files";
36
36
  import { shouldDistillOnShutdown } from "./should-distill-on-shutdown";
37
37
 
38
+ /**
39
+ * Distill subprocesses run on forked session files for persistence isolation,
40
+ * but OpenAI-style providers derive `prompt_cache_key` from the forked
41
+ * session id. When the wrapper provides the parent session id via env, patch
42
+ * only payloads that already opted into a concrete prompt_cache_key. This
43
+ * keeps unsupported providers / cacheRetention="none" payloads unchanged.
44
+ */
45
+ export function applyDistillPromptCacheKey(
46
+ payload: unknown,
47
+ promptCacheKey = process.env[DISTILL_PROMPT_CACHE_KEY_ENV],
48
+ ): unknown | undefined {
49
+ if (!promptCacheKey || typeof payload !== "object" || payload === null) {
50
+ return undefined;
51
+ }
52
+ if (Array.isArray(payload)) return undefined;
53
+ if (!Object.hasOwn(payload, "prompt_cache_key")) return undefined;
54
+
55
+ const current = (payload as { prompt_cache_key?: unknown }).prompt_cache_key;
56
+ if (current === undefined || current === promptCacheKey) return undefined;
57
+
58
+ return { ...payload, prompt_cache_key: promptCacheKey };
59
+ }
60
+
38
61
  export interface DistillConfig {
39
62
  enabled: boolean;
40
63
  intervalMinutes: number;
@@ -440,6 +463,10 @@ export default function (pi: ExtensionAPI) {
440
463
  };
441
464
  let uiRef: DistillUIRef | null = null;
442
465
 
466
+ pi.on("before_provider_request", (event) =>
467
+ applyDistillPromptCacheKey(event.payload),
468
+ );
469
+
443
470
  function renderIdleStatus(): void {
444
471
  if (!uiRef?.hasUI || !uiRef.showStatus) return;
445
472
  // While a distill is in flight the poll loop owns the status bar; leave it alone.
@@ -1597,18 +1624,24 @@ export default function (pi: ExtensionAPI) {
1597
1624
  });
1598
1625
 
1599
1626
  // ---------------------------------------------------------------------------
1600
- // /distill-status and napkin_distill_status
1627
+ // /distill-status
1601
1628
  //
1602
- // Shared state: both surfaces read the exact same data (active worktrees +
1603
- // unmerged branches) via module-level `collectDistillStatus`. The command
1604
- // formats it for humans via `formatDistillStatus`; the tool returns the
1605
- // JSON shape for the agent via `distillStatusToJson`. The formatters are
1606
- // module-level + exported so tests can verify their output without wiring
1629
+ // User-driven status surface. The command reads active worktrees +
1630
+ // unmerged branches via module-level `collectDistillStatus` and formats
1631
+ // them for humans via `formatDistillStatus`. The formatter is
1632
+ // module-level + exported so tests can verify its output without wiring
1607
1633
  // a full mock `ExtensionAPI`.
1634
+ //
1635
+ // Agent visibility for in-flight distills is handled proactively by the
1636
+ // per-distill-completion overlap notice posted via
1637
+ // `appendCustomMessageEntry` — there is no agent-callable tool because
1638
+ // worktree isolation means the agent can't race an in-flight distill on
1639
+ // main anyway, and the overlap notice fires exactly when files actually
1640
+ // change in the parent's view.
1608
1641
  // ---------------------------------------------------------------------------
1609
1642
 
1610
1643
  /**
1611
- * Resolve the main vault path from a command/tool `ctx`. Returns null when
1644
+ * Resolve the main vault path from a command `ctx`. Returns null when
1612
1645
  * no vault can be resolved (ctx.cwd isn't inside a napkin vault) — callers
1613
1646
  * surface a user-facing message in that case.
1614
1647
  */
@@ -1645,47 +1678,11 @@ export default function (pi: ExtensionAPI) {
1645
1678
  }
1646
1679
  },
1647
1680
  });
1648
-
1649
- // Parallel pi tool: the LLM can query the same state the human gets from
1650
- // /distill-status. Used by agents to decide whether to back off from
1651
- // vault edits while a background distill is in flight (see also the
1652
- // per-distill-completion overlap notice posted via
1653
- // `appendCustomMessageEntry` once the distill finishes).
1654
- pi.registerTool({
1655
- name: "napkin_distill_status",
1656
- label: "Napkin distill status",
1657
- description:
1658
- "Returns JSON listing active napkin distill subprocesses and unmerged distill branches for the current vault. Useful for checking if background vault writes are in progress before the agent makes concurrent edits.",
1659
- promptSnippet:
1660
- "Inspect in-flight napkin distill subprocesses before editing vault files.",
1661
- parameters: Type.Object({}),
1662
- async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
1663
- const vaultPath = resolveVaultPath(ctx.cwd);
1664
- if (!vaultPath) {
1665
- return {
1666
- content: [
1667
- {
1668
- type: "text",
1669
- text: JSON.stringify({ error: "no vault in cwd" }),
1670
- },
1671
- ],
1672
- details: { vault: null, active: [], unmerged: [] },
1673
- };
1674
- }
1675
- const { active, unmerged } = collectDistillStatus(vaultPath);
1676
- const json = distillStatusToJson(active, unmerged);
1677
- return {
1678
- content: [{ type: "text", text: json }],
1679
- details: { vault: vaultPath, active, unmerged },
1680
- };
1681
- },
1682
- });
1683
1681
  }
1684
1682
 
1685
1683
  /**
1686
- * Gather the shared status payload consumed by both `/distill-status` and
1687
- * `napkin_distill_status`. Empty arrays on any error (no git, git failure)
1688
- * — status surfaces must never throw.
1684
+ * Gather the status payload consumed by `/distill-status`. Empty arrays on
1685
+ * any error (no git, git failure) — status surfaces must never throw.
1689
1686
  *
1690
1687
  * Exported for unit tests. Callers pass the MAIN vault content path (not a
1691
1688
  * worktree). Both inspectors return [] when `.git/` is absent.
@@ -1743,57 +1740,6 @@ export function formatDistillStatus(
1743
1740
  return lines.join("\n");
1744
1741
  }
1745
1742
 
1746
- /**
1747
- * Serialise the same `(active, unmerged)` payload that `/distill-status`
1748
- * renders to a JSON string for the `napkin_distill_status` pi tool. Pure
1749
- * function; exported for unit tests.
1750
- *
1751
- * Return shape (see shutdown-distill.md — `/distill-status` command):
1752
- * {
1753
- * "active": [
1754
- * {
1755
- * pid: number, // -1 when meta.json is unreadable
1756
- * branch: string,
1757
- * elapsedSeconds: number,
1758
- * session: string|null, // basename of parent session .jsonl
1759
- * alive: boolean,
1760
- * startedAt: string|null,
1761
- * startSha?: string,
1762
- * }
1763
- * ],
1764
- * "unmerged": ["distill/xyz-456", ...]
1765
- * }
1766
- *
1767
- * `session` is the basename of the parent session file (matching the
1768
- * human-readable formatter) — the full path isn't useful to the agent and
1769
- * would leak $HOME. `elapsedSeconds` is an integer (floor).
1770
- *
1771
- * `alive` and `startSha` are retained because they materially change how
1772
- * the agent should interpret an entry (dead distills are candidates for
1773
- * manual cleanup; `startSha` is a forensic hint for recovery).
1774
- *
1775
- * Shape is stable: new keys may be added, existing keys MUST NOT be renamed
1776
- * or repurposed without a version bump.
1777
- */
1778
- export function distillStatusToJson(
1779
- active: ActiveDistill[],
1780
- unmerged: string[],
1781
- ): string {
1782
- const payload = {
1783
- active: active.map((d) => ({
1784
- pid: d.pid,
1785
- branch: d.branch,
1786
- elapsedSeconds: Math.floor(d.elapsedMs / 1000),
1787
- session: d.sessionPath !== null ? path.basename(d.sessionPath) : null,
1788
- alive: d.alive,
1789
- startedAt: d.startedAt,
1790
- startSha: d.startSha,
1791
- })),
1792
- unmerged,
1793
- };
1794
- return JSON.stringify(payload, null, 2);
1795
- }
1796
-
1797
1743
  /**
1798
1744
  * Compute the intersection of session-touched paths and distill-touched
1799
1745
  * paths. Matching is layered:
@@ -207,7 +207,7 @@ export function getSessionTouchedFiles(sm: SessionEntriesSource): Set<string> {
207
207
  for (const entry of sm.getEntries()) {
208
208
  if (entry.type !== "message") continue;
209
209
  const msg = (entry as { message?: AssistantMessageShape }).message;
210
- if (!msg || msg.role !== "assistant") continue;
210
+ if (msg?.role !== "assistant") continue;
211
211
  for (const p of extractFileOpsFromMessage(msg)) {
212
212
  out.add(p);
213
213
  }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Type shims for @cad0p/napkin's untyped transitive dependencies.
3
+ *
4
+ * napkin ships its TypeScript *sources* (no `dist/`, no bundled `.d.ts`),
5
+ * so importing `Napkin` pulls napkin's `src/` into this project's `tsc`
6
+ * compilation. napkin 0.10's `bases.ts`/`formula.ts` import `js-yaml`,
7
+ * `sql.js`, and `jexl`, none of which ship type declarations. napkin
8
+ * itself stays green because it carries `src/types.d.ts` shims — but
9
+ * those live inside `node_modules/@cad0p/napkin` and are NOT picked up
10
+ * by a consumer's compilation.
11
+ *
12
+ * The `sql.js` and `jexl` declarations below mirror napkin's own
13
+ * `src/types.d.ts` *verbatim* so that `bases.ts`/`formula.ts` typecheck
14
+ * here exactly as they do in napkin's repo. This is deliberately *not*
15
+ * `@types/sql.js`: the real `@types/sql.js` exposes a genuine internal
16
+ * mismatch in napkin's `bases.ts` (`unknown[][]` vs `SqlValue[][]`,
17
+ * TS2322) that this extension does not exercise and that belongs to
18
+ * napkin. `js-yaml` is declared as `any` (napkin's code only calls
19
+ * `yaml.load`, and napkin itself uses `@types/js-yaml`). These three
20
+ * modules are never imported by pi-napkin code directly.
21
+ */
22
+ declare module "js-yaml";
23
+
24
+ declare module "sql.js" {
25
+ interface Database {
26
+ run(sql: string, params?: unknown[]): void;
27
+ exec(sql: string): { columns: string[]; values: unknown[][] }[];
28
+ close(): void;
29
+ // biome-ignore lint/complexity/noBannedTypes: sql.js dynamic function registration
30
+ create_function(name: string, fn: Function): void;
31
+ }
32
+ interface SqlJsStatic {
33
+ Database: new () => Database;
34
+ }
35
+
36
+ export type { Database };
37
+ export default function initSqlJs(): Promise<SqlJsStatic>;
38
+ }
39
+
40
+ declare module "jexl" {
41
+ class Jexl {
42
+ eval(expr: string, context?: Record<string, unknown>): Promise<unknown>;
43
+ // biome-ignore lint/complexity/noBannedTypes: jexl dynamic function registration
44
+ addFunction(name: string, fn: Function): void;
45
+ // biome-ignore lint/complexity/noBannedTypes: jexl dynamic transform registration
46
+ addTransform(name: string, fn: Function): void;
47
+ }
48
+ export default { Jexl };
49
+ }
package/package.json CHANGED
@@ -1,7 +1,9 @@
1
1
  {
2
2
  "name": "@cad0p/pi-napkin",
3
- "version": "0.3.1",
3
+ "version": "0.3.2-20260801.0",
4
4
  "description": "📜 Napkin integration for pi — vault context, knowledge tools, and automatic distillation with git-worktree concurrency safety",
5
+ "type": "module",
6
+ "packageManager": "pnpm@11.10.0",
5
7
  "publishConfig": {
6
8
  "access": "public",
7
9
  "registry": "https://registry.npmjs.org"
@@ -48,19 +50,22 @@
48
50
  ]
49
51
  },
50
52
  "scripts": {
51
- "lint": "bunx biome check extensions/",
52
- "lint:fix": "bunx biome check --write extensions/",
53
- "typecheck": "bunx tsc --noEmit",
54
- "test": "bun test",
55
- "verify:e2e": "bun run scripts/verify-e2e.ts"
53
+ "lint": "biome check extensions/",
54
+ "lint:fix": "biome check --write extensions/",
55
+ "typecheck": "tsc --noEmit",
56
+ "test": "vitest run",
57
+ "test:watch": "vitest",
58
+ "verify:e2e": "node --import tsx scripts/verify-e2e.ts"
56
59
  },
57
60
  "devDependencies": {
58
61
  "@biomejs/biome": "^2.3.14",
59
- "@types/bun": "^1.3.0",
60
- "typescript": "^5.8.0"
62
+ "@types/node": "^22.0.0",
63
+ "tsx": "^4.19.0",
64
+ "typescript": "^5.8.0",
65
+ "vitest": "^2.1.0"
61
66
  },
62
67
  "dependencies": {
63
- "@cad0p/napkin": "^0.8.1"
68
+ "@cad0p/napkin": "^0.10.0"
64
69
  },
65
70
  "peerDependencies": {
66
71
  "@earendil-works/pi-coding-agent": ">=0.74.0",