@cad0p/pi-napkin 0.2.4 → 0.3.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 +99 -25
- package/extensions/distill/auto-setup.ts +29 -117
- package/extensions/distill/distill-prompt.md +58 -0
- package/extensions/distill/distill-prompt.ts +212 -0
- package/extensions/distill/distill-workspace.ts +115 -211
- package/extensions/distill/index.ts +116 -96
- package/extensions/distill/scripts/distill-wrapper.sh +1080 -300
- package/extensions/distill/scripts-paths.ts +0 -9
- package/package.json +5 -2
- package/extensions/distill/scripts/git_retry.sh +0 -65
- package/extensions/distill/scripts/napkin-distill-merge +0 -455
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Distill prompt loader.
|
|
3
|
+
*
|
|
4
|
+
* The agent-driven distill prompt lives as markdown at
|
|
5
|
+
* `extensions/distill/distill-prompt.md`, with template placeholders the
|
|
6
|
+
* wrapper resolves at spawn time. This module reads that .md at runtime,
|
|
7
|
+
* substitutes the placeholders, and returns the resolved string for the
|
|
8
|
+
* wrapper to pass to `pi -p`.
|
|
9
|
+
*
|
|
10
|
+
* Why markdown + a loader (PR #12 design — "DISTILL_PROMPT location"):
|
|
11
|
+
* - Easier to edit / iterate the prompt without touching code
|
|
12
|
+
* - Markdown rendering in editors makes the prompt readable as prose
|
|
13
|
+
* - Snapshot tests assert prompt content directly against the .md
|
|
14
|
+
* - Bundled with npm publish via `package.json` `files` entry
|
|
15
|
+
*
|
|
16
|
+
* The loader is strict on placeholder coverage: every required placeholder
|
|
17
|
+
* MUST be present in the .md OR the loader throws. This protects against
|
|
18
|
+
* silent drift where a refactor renames a placeholder in the .md but
|
|
19
|
+
* leaves the TS-side input shape intact, sending an unresolved
|
|
20
|
+
* `{{worktreePath}}` literal to the agent. Per the methodology guide's
|
|
21
|
+
* never-deferrable categories, "stale references to renamed concepts" are
|
|
22
|
+
* a fix-now class — failing fast at load time keeps them out of agent
|
|
23
|
+
* prompts entirely.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
import * as fs from "node:fs";
|
|
27
|
+
import * as path from "node:path";
|
|
28
|
+
import { fileURLToPath } from "node:url";
|
|
29
|
+
|
|
30
|
+
const _here = path.dirname(fileURLToPath(import.meta.url));
|
|
31
|
+
|
|
32
|
+
/** Absolute path to the distill prompt markdown file. */
|
|
33
|
+
export const DISTILL_PROMPT_PATH: string = path.join(
|
|
34
|
+
_here,
|
|
35
|
+
"distill-prompt.md",
|
|
36
|
+
);
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Inputs to {@link buildDistillPrompt}. All four placeholders MUST be
|
|
40
|
+
* provided; passing an empty string is disallowed because that would
|
|
41
|
+
* produce an agent prompt with `git merge ` (empty branch name) or
|
|
42
|
+
* `cd ` (empty path) — silent corruption rather than fail-fast.
|
|
43
|
+
*/
|
|
44
|
+
export interface DistillPromptInputs {
|
|
45
|
+
/** Absolute path to the per-distill git worktree. Substituted for `{{worktreePath}}`. */
|
|
46
|
+
worktreePath: string;
|
|
47
|
+
/** Absolute path to the main vault (the worktree's parent repo). Substituted for `{{vaultPath}}`. */
|
|
48
|
+
vaultPath: string;
|
|
49
|
+
/** Distill branch name, e.g. `distill/abc123-1700000000000`. Substituted for `{{branchName}}`. */
|
|
50
|
+
branchName: string;
|
|
51
|
+
/** Vault's default mainline branch (`main`, `master`, ...). Substituted for `{{defaultBranch}}`. */
|
|
52
|
+
defaultBranch: string;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Required placeholders the .md template must contain. Order matches the
|
|
57
|
+
* order they appear in the template; the validator below iterates this
|
|
58
|
+
* list to surface a precise diagnostic when one is missing.
|
|
59
|
+
*/
|
|
60
|
+
const REQUIRED_PLACEHOLDERS = [
|
|
61
|
+
"{{worktreePath}}",
|
|
62
|
+
"{{vaultPath}}",
|
|
63
|
+
"{{branchName}}",
|
|
64
|
+
"{{defaultBranch}}",
|
|
65
|
+
] as const;
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Validate a single substitution input. Used for every field of
|
|
69
|
+
* {@link DistillPromptInputs}. Hard rejects:
|
|
70
|
+
*
|
|
71
|
+
* 1. Non-string / empty string — silent prompt corruption (e.g.
|
|
72
|
+
* `git merge ` with empty branch name) is worse than a loud
|
|
73
|
+
* validation throw.
|
|
74
|
+
* 2. ASCII control characters (NUL, BEL, BS, TAB, LF, CR, ESC, DEL,
|
|
75
|
+
* …; the `\x00–\x1F` and `\x7F` ranges). A `\n` in
|
|
76
|
+
* `worktreePath` would inject a newline into the agent's prompt,
|
|
77
|
+
* letting an attacker who controls a single field break out of
|
|
78
|
+
* one prompt-step and inject prose into another (prompt-
|
|
79
|
+
* injection class). NUL bytes truncate strings on most C-side
|
|
80
|
+
* consumers (the wrapper's `printf`, `git`'s argv parsing). TAB
|
|
81
|
+
* isn't strictly malicious but its inclusion in agent prompts
|
|
82
|
+
* breaks the `git -C "<tab>worktree"` quoting we rely on.
|
|
83
|
+
* 3. Mustache-style `{{` or `}}` runs — collide with the
|
|
84
|
+
* placeholder syntax this loader uses. A vault path that
|
|
85
|
+
* contained `{{worktreePath}}` would silently re-substitute
|
|
86
|
+
* itself on a second pass; even though we don't multi-pass
|
|
87
|
+
* today, defending the input shape lets future refactors of
|
|
88
|
+
* the substitution loop stay safe.
|
|
89
|
+
*
|
|
90
|
+
* Defense-in-depth (SEC-A-5): the JS-side caller already controls
|
|
91
|
+
* three of the four inputs (`worktreePath`, `branchName`,
|
|
92
|
+
* `defaultBranch` come from `createDistillWorkspace` /
|
|
93
|
+
* `detectDefaultBranch` which produce well-formed strings).
|
|
94
|
+
* `vaultPath` originates from the user's config but is
|
|
95
|
+
* `path.resolve`d before reaching here. So the realistic threat
|
|
96
|
+
* surface is narrow — but the validator is cheap, the failure mode
|
|
97
|
+
* is "throw with a clear message", and a future caller that bypasses
|
|
98
|
+
* the helpers (or a malformed config) would otherwise let bad input
|
|
99
|
+
* reach the agent prompt.
|
|
100
|
+
*
|
|
101
|
+
* Slashes (`/`), spaces, hyphens, dots, and underscores are all
|
|
102
|
+
* allowed: `feat/foo` branch names and `~/My Vault/notes` paths must
|
|
103
|
+
* pass.
|
|
104
|
+
*/
|
|
105
|
+
function validateInput(name: string, value: unknown): asserts value is string {
|
|
106
|
+
if (typeof value !== "string" || value.length === 0) {
|
|
107
|
+
throw new Error(
|
|
108
|
+
`buildDistillPrompt: input '${name}' must be a non-empty string (got ${JSON.stringify(value)})`,
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
// Reject ASCII control chars (\x00–\x1F and \x7F). A literal `\n`
|
|
112
|
+
// in any input would break out of the prompt step it's embedded
|
|
113
|
+
// in — classic prompt-injection. JSON.stringify the value in the
|
|
114
|
+
// error so the offending char is visible (escaped) in the message.
|
|
115
|
+
// biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control chars IS the validator's job
|
|
116
|
+
if (/[\x00-\x1F\x7F]/.test(value)) {
|
|
117
|
+
throw new Error(
|
|
118
|
+
`buildDistillPrompt: input '${name}' contains control characters; reject (got ${JSON.stringify(value)})`,
|
|
119
|
+
);
|
|
120
|
+
}
|
|
121
|
+
// Reject placeholder-syntax collisions. A vault path that contained
|
|
122
|
+
// `{{worktreePath}}` would silently re-substitute on a second pass
|
|
123
|
+
// — defense-in-depth for future refactors of the substitution loop.
|
|
124
|
+
if (value.includes("{{") || value.includes("}}")) {
|
|
125
|
+
throw new Error(
|
|
126
|
+
`buildDistillPrompt: input '${name}' contains placeholder-syntax characters '{{' or '}}' (got ${JSON.stringify(value)})`,
|
|
127
|
+
);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Read a distill prompt markdown template from `promptPath` and
|
|
133
|
+
* substitute placeholders. The path-injected core of the loader.
|
|
134
|
+
*
|
|
135
|
+
* Test seam (CI-A-5): production callers should use
|
|
136
|
+
* {@link buildDistillPrompt}, which delegates to this helper with
|
|
137
|
+
* {@link DISTILL_PROMPT_PATH}. Tests that need to exercise template
|
|
138
|
+
* error paths (missing placeholder, empty template) point this at a
|
|
139
|
+
* tmpdir copy of the .md so the shipped artifact is never mutated.
|
|
140
|
+
*
|
|
141
|
+
* @throws Error if the .md file is missing, empty, or omits any required
|
|
142
|
+
* placeholder. Throws if any input value is empty (per the
|
|
143
|
+
* {@link DistillPromptInputs} contract).
|
|
144
|
+
*
|
|
145
|
+
* Pure function aside from the .md read: the loader does not cache, so
|
|
146
|
+
* tests that mutate the file (or replace it via mocked fs) see the
|
|
147
|
+
* fresh contents on each call. The .md is small (a few KB); re-reading
|
|
148
|
+
* it on each spawn is cheap relative to the agent task itself (60s+).
|
|
149
|
+
*/
|
|
150
|
+
export function buildDistillPromptFromFile(
|
|
151
|
+
promptPath: string,
|
|
152
|
+
inputs: DistillPromptInputs,
|
|
153
|
+
): string {
|
|
154
|
+
for (const [key, value] of Object.entries(inputs)) {
|
|
155
|
+
validateInput(key, value);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
let template: string;
|
|
159
|
+
try {
|
|
160
|
+
template = fs.readFileSync(promptPath, "utf-8");
|
|
161
|
+
} catch (err) {
|
|
162
|
+
throw new Error(
|
|
163
|
+
`buildDistillPrompt: failed to read prompt template at ${promptPath}: ${(err as Error).message}`,
|
|
164
|
+
);
|
|
165
|
+
}
|
|
166
|
+
if (template.length === 0) {
|
|
167
|
+
throw new Error(
|
|
168
|
+
`buildDistillPrompt: prompt template at ${promptPath} is empty`,
|
|
169
|
+
);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
for (const placeholder of REQUIRED_PLACEHOLDERS) {
|
|
173
|
+
if (!template.includes(placeholder)) {
|
|
174
|
+
throw new Error(
|
|
175
|
+
`buildDistillPrompt: prompt template at ${promptPath} is missing required placeholder '${placeholder}'`,
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
// Map placeholder → input key. Keep this aligned with REQUIRED_PLACEHOLDERS
|
|
181
|
+
// so the missing-placeholder error and the substitution loop never drift.
|
|
182
|
+
const substitutions: Array<[string, string]> = [
|
|
183
|
+
["{{worktreePath}}", inputs.worktreePath],
|
|
184
|
+
["{{vaultPath}}", inputs.vaultPath],
|
|
185
|
+
["{{branchName}}", inputs.branchName],
|
|
186
|
+
["{{defaultBranch}}", inputs.defaultBranch],
|
|
187
|
+
];
|
|
188
|
+
|
|
189
|
+
let result = template;
|
|
190
|
+
for (const [placeholder, value] of substitutions) {
|
|
191
|
+
// String#replaceAll on each placeholder; values are not regex-special
|
|
192
|
+
// because they're filesystem paths or branch names. Even if a path
|
|
193
|
+
// contained a `$` or `\`, replaceAll on a literal string (not regex)
|
|
194
|
+
// is escape-safe.
|
|
195
|
+
result = result.replaceAll(placeholder, value);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
return result;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* Read the shipped distill prompt markdown and substitute placeholders.
|
|
203
|
+
* Public API — production callers should use this. Delegates to
|
|
204
|
+
* {@link buildDistillPromptFromFile} with the bundled .md path.
|
|
205
|
+
*
|
|
206
|
+
* @throws Error if the .md file is missing, empty, or omits any required
|
|
207
|
+
* placeholder. Throws if any input value is empty (per the
|
|
208
|
+
* {@link DistillPromptInputs} contract).
|
|
209
|
+
*/
|
|
210
|
+
export function buildDistillPrompt(inputs: DistillPromptInputs): string {
|
|
211
|
+
return buildDistillPromptFromFile(DISTILL_PROMPT_PATH, inputs);
|
|
212
|
+
}
|
|
@@ -32,8 +32,22 @@ import * as path from "node:path";
|
|
|
32
32
|
|
|
33
33
|
import { Napkin } from "@cad0p/napkin";
|
|
34
34
|
import { SessionManager } from "@earendil-works/pi-coding-agent";
|
|
35
|
+
import { buildDistillPrompt } from "./distill-prompt";
|
|
36
|
+
import { DISTILL_WRAPPER_SCRIPT } from "./scripts-paths";
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
/**
|
|
39
|
+
* Per-subcommand wall-clock ceiling for `git` invocations from the
|
|
40
|
+
* JS-side. Typical git plumbing returns in milliseconds; this is a
|
|
41
|
+
* generous upper bound that catches truly stuck operations (network
|
|
42
|
+
* hangs, lock contention, fsmonitor wedges) without slowing the happy
|
|
43
|
+
* path. Tuned alongside the distill cleanup-trap budget so a single
|
|
44
|
+
* hung subcommand can't keep the wrapper alive past its overall
|
|
45
|
+
* `timeout(1)` wall-clock budget.
|
|
46
|
+
*
|
|
47
|
+
* Re-exported and consumed by `auto-setup.ts`'s sibling `runGit` so
|
|
48
|
+
* both call sites share a single source of truth.
|
|
49
|
+
*/
|
|
50
|
+
export const GIT_SUBCOMMAND_TIMEOUT_MS = 30_000;
|
|
37
51
|
|
|
38
52
|
/**
|
|
39
53
|
* Error class thrown by distill-workspace operations. Separate class so
|
|
@@ -83,9 +97,6 @@ export interface DistillMeta {
|
|
|
83
97
|
*
|
|
84
98
|
* git -C <vaultPath> log --name-only <startSha>..HEAD
|
|
85
99
|
*
|
|
86
|
-
* Also useful for the live `diffWorktreeSinceStart` helper while the
|
|
87
|
-
* worktree is still alive (status displays, debugging).
|
|
88
|
-
*
|
|
89
100
|
* Absent on meta.json files written by pre-Phase-C2 code paths — readers
|
|
90
101
|
* MUST tolerate undefined and fall back to scanning the whole worktree.
|
|
91
102
|
*/
|
|
@@ -226,7 +237,7 @@ function runGit(
|
|
|
226
237
|
const r = spawnSync("git", args, {
|
|
227
238
|
cwd,
|
|
228
239
|
encoding: "utf-8",
|
|
229
|
-
timeout:
|
|
240
|
+
timeout: GIT_SUBCOMMAND_TIMEOUT_MS,
|
|
230
241
|
env: process.env,
|
|
231
242
|
});
|
|
232
243
|
return {
|
|
@@ -236,75 +247,9 @@ function runGit(
|
|
|
236
247
|
};
|
|
237
248
|
}
|
|
238
249
|
|
|
239
|
-
/**
|
|
240
|
-
* Ensure the worktree's local git config has the napkin-distill-merge
|
|
241
|
-
* driver registered, and that `.gitattributes` routes `*.md` through it.
|
|
242
|
-
*
|
|
243
|
-
* Registration is per-worktree (`--local`, stays in the worktree's git config
|
|
244
|
-
* dir, never propagates to the main repo or gets committed). The
|
|
245
|
-
* `.gitattributes` line is per-file though \u2014 if the vault doesn't already
|
|
246
|
-
* have one routing `*.md` through the driver, we append one. The appended
|
|
247
|
-
* line gets committed along with the distill's content changes, which is
|
|
248
|
-
* fine: committing the merge-driver rule to the vault is what lets the
|
|
249
|
-
* driver actually fire during the merge back to main.
|
|
250
|
-
*
|
|
251
|
-
* Phase C's auto-init will pre-scaffold `.gitattributes` so this append
|
|
252
|
-
* becomes a no-op; until then, we self-heal.
|
|
253
|
-
*/
|
|
254
|
-
function registerMergeDriver(worktreePath: string): void {
|
|
255
|
-
// Register the driver in local git config. Local config lives in the
|
|
256
|
-
// worktree's `.git` file (actually in the main repo's .git/config, since
|
|
257
|
-
// worktrees share config by default \u2014 the config applies during all git
|
|
258
|
-
// operations from this worktree's perspective).
|
|
259
|
-
const nameRes = runGit(worktreePath, [
|
|
260
|
-
"config",
|
|
261
|
-
"--local",
|
|
262
|
-
"merge.napkin-distill-merge.name",
|
|
263
|
-
"napkin distill LLM merge driver",
|
|
264
|
-
]);
|
|
265
|
-
if (nameRes.status !== 0) {
|
|
266
|
-
throw new DistillError(
|
|
267
|
-
`failed to configure merge driver name: ${nameRes.stderr.trim()}`,
|
|
268
|
-
);
|
|
269
|
-
}
|
|
270
|
-
// Quote the driver path so spaces / shell metacharacters in the path
|
|
271
|
-
// don't break git's sh -c invocation of the driver command, and so a
|
|
272
|
-
// malicious path prefix (unlikely locally, possible in CI with a
|
|
273
|
-
// runner-controlled workspace path) can't inject arguments.
|
|
274
|
-
// Single-quote the path and escape any literal ' as '\''.
|
|
275
|
-
const quotedDriverPath = `'${MERGE_DRIVER_SCRIPT.replace(/'/g, "'\\''")}'`;
|
|
276
|
-
const driverRes = runGit(worktreePath, [
|
|
277
|
-
"config",
|
|
278
|
-
"--local",
|
|
279
|
-
"merge.napkin-distill-merge.driver",
|
|
280
|
-
`${quotedDriverPath} %O %A %B %P`,
|
|
281
|
-
]);
|
|
282
|
-
if (driverRes.status !== 0) {
|
|
283
|
-
throw new DistillError(
|
|
284
|
-
`failed to configure merge driver command: ${driverRes.stderr.trim()}`,
|
|
285
|
-
);
|
|
286
|
-
}
|
|
287
|
-
|
|
288
|
-
// Ensure `*.md merge=napkin-distill-merge` is in .gitattributes. This is
|
|
289
|
-
// the bit git consults during `git merge` to pick the driver. If
|
|
290
|
-
// .gitattributes is missing or the line isn't present, append it.
|
|
291
|
-
const attrsPath = path.join(worktreePath, ".gitattributes");
|
|
292
|
-
const attrLine = "*.md merge=napkin-distill-merge";
|
|
293
|
-
let existing = "";
|
|
294
|
-
if (fs.existsSync(attrsPath)) {
|
|
295
|
-
existing = fs.readFileSync(attrsPath, "utf-8");
|
|
296
|
-
}
|
|
297
|
-
if (!existing.split("\n").some((line) => line.trim() === attrLine)) {
|
|
298
|
-
const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
|
|
299
|
-
fs.writeFileSync(attrsPath, `${existing}${sep}${attrLine}\n`);
|
|
300
|
-
}
|
|
301
|
-
}
|
|
302
|
-
|
|
303
250
|
/**
|
|
304
251
|
* Create a git worktree at `worktreePath` checked out to a fresh branch
|
|
305
|
-
* `branchName` rooted at the vault's HEAD.
|
|
306
|
-
* driver in the worktree's local git config so subsequent `git merge`
|
|
307
|
-
* invocations can resolve conflicts via the LLM.
|
|
252
|
+
* `branchName` rooted at the vault's HEAD.
|
|
308
253
|
*
|
|
309
254
|
* Precondition: vault is a git repo with at least one commit (HEAD
|
|
310
255
|
* resolvable). Phase C's auto-init ensures both.
|
|
@@ -312,7 +257,6 @@ function registerMergeDriver(worktreePath: string): void {
|
|
|
312
257
|
* @throws DistillError if:
|
|
313
258
|
* - vault has no `.git/` directory
|
|
314
259
|
* - `git worktree add` exits non-zero (branch collision, dirty state, ...)
|
|
315
|
-
* - merge driver registration fails
|
|
316
260
|
*
|
|
317
261
|
* @returns absolute worktree path on success (same as input, for chaining).
|
|
318
262
|
*/
|
|
@@ -345,7 +289,7 @@ export function createDistillWorktree(
|
|
|
345
289
|
|
|
346
290
|
// Ensure the parent of worktreePath exists; `git worktree add` requires a
|
|
347
291
|
// non-existent target directory but will happily create intermediate dirs
|
|
348
|
-
// for us
|
|
292
|
+
// for us — except when the parent (e.g. the vault's XDG cache root
|
|
349
293
|
// `~/.cache/napkin-distill/<hash>/`) only exists after first use.
|
|
350
294
|
fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
|
|
351
295
|
|
|
@@ -363,21 +307,6 @@ export function createDistillWorktree(
|
|
|
363
307
|
);
|
|
364
308
|
}
|
|
365
309
|
|
|
366
|
-
try {
|
|
367
|
-
registerMergeDriver(worktreePath);
|
|
368
|
-
} catch (err) {
|
|
369
|
-
// Roll back the worktree if driver registration fails \u2014 an unregistered
|
|
370
|
-
// worktree would merge with plain conflict markers instead of going
|
|
371
|
-
// through the LLM, defeating the point.
|
|
372
|
-
try {
|
|
373
|
-
runGit(vaultPath, ["worktree", "remove", "--force", worktreePath]);
|
|
374
|
-
runGit(vaultPath, ["branch", "-D", branchName]);
|
|
375
|
-
} catch {
|
|
376
|
-
// ignore
|
|
377
|
-
}
|
|
378
|
-
throw err;
|
|
379
|
-
}
|
|
380
|
-
|
|
381
310
|
return worktreePath;
|
|
382
311
|
}
|
|
383
312
|
|
|
@@ -793,9 +722,9 @@ export function resolveDistillErrorDir(vault: string): string {
|
|
|
793
722
|
* Find the wrapper-emitted error log for a specific distill branch, if
|
|
794
723
|
* any. The wrapper writes ‘forensic’ logs to
|
|
795
724
|
* `<errorDir>/<ISO-timestamp>-<pid>-<branch-short>.log` whenever it
|
|
796
|
-
* fails (missing napkin, pi subprocess error,
|
|
797
|
-
* cd parent_cwd failure, …). Returns the absolute
|
|
798
|
-
* matching log file, or null when no log exists.
|
|
725
|
+
* fails (missing napkin, pi subprocess error, agent timeout, post-call
|
|
726
|
+
* validation failure, cd parent_cwd failure, …). Returns the absolute
|
|
727
|
+
* path to the first matching log file, or null when no log exists.
|
|
799
728
|
*
|
|
800
729
|
* `branchShort` is the part after `distill/`, e.g. for
|
|
801
730
|
* `distill/abc1234-1715198400` pass `abc1234-1715198400`.
|
|
@@ -829,34 +758,56 @@ export function findDistillErrorLogForBranch(
|
|
|
829
758
|
|
|
830
759
|
/**
|
|
831
760
|
* Find the most recent outcome sidecar for a distill branch. Returns
|
|
832
|
-
* `{ class, outcomePath
|
|
833
|
-
*
|
|
761
|
+
* `{ class, outcomePath }` when a `*.outcome` file exists for
|
|
762
|
+
* `branchShort`, else null.
|
|
834
763
|
*
|
|
835
764
|
* The outcome sidecar (POST-CONV-5) is written by the wrapper as the
|
|
836
765
|
* LAST action before any successful exit-0 path. One-line content is
|
|
837
|
-
* the class string: `merged-content` / `
|
|
838
|
-
* Used by the JS-side `runDistillWith` poller to
|
|
839
|
-
* severity (info vs warn) since multiple
|
|
840
|
-
* previously produced the same notification.
|
|
766
|
+
* the class string: `merged-content` / `merged-local` / `no-content` /
|
|
767
|
+
* `failed:<reason>`. Used by the JS-side `runDistillWith` poller to
|
|
768
|
+
* dispatch the right UI severity (info vs warn vs error) since multiple
|
|
769
|
+
* `exit 0` wrapper paths previously produced the same notification.
|
|
841
770
|
*
|
|
842
771
|
* Missing outcome AND missing fatal error log = abnormal termination
|
|
843
772
|
* (SIGKILL / `set -e` / disk full / race) — caller must surface this
|
|
844
773
|
* as a warn since the wrapper is detached and we have no other signal
|
|
845
774
|
* channel.
|
|
775
|
+
*/
|
|
776
|
+
/**
|
|
777
|
+
* Parsed outcome sidecar shape (POST-CONV-5 / PR #12 A4).
|
|
778
|
+
*
|
|
779
|
+
* One canonical type for the wrapper-emitted outcome record so callers
|
|
780
|
+
* (the `findDistillOutcomeForBranch` reader, the strategy `checkOutcome`
|
|
781
|
+
* callbacks in `index.ts`, the `formatOutcomeNotification` dispatcher)
|
|
782
|
+
* stay in sync as the shape evolves. Hand-redeclaring this shape at
|
|
783
|
+
* each call site causes drift on the next field addition / removal
|
|
784
|
+
* (CLEAN-7); pinning it here makes future changes single-edit.
|
|
846
785
|
*
|
|
847
|
-
*
|
|
848
|
-
*
|
|
849
|
-
*
|
|
850
|
-
*
|
|
786
|
+
* Field semantics:
|
|
787
|
+
* - `outcomeClass`: machine-readable class string (line 1 of the
|
|
788
|
+
* sidecar). Drives UI severity in `formatOutcomeNotification` per
|
|
789
|
+
* the locked notification severity contract
|
|
790
|
+
* (`merged-content`/`merged-local`/`no-content`/`failed:<reason>`).
|
|
791
|
+
* - `outcomePath`: absolute path to the sidecar file on disk. Used
|
|
792
|
+
* by tests (and ad-hoc forensic tooling) that need to inspect the
|
|
793
|
+
* raw bytes; consumers that only want the class/hint can ignore
|
|
794
|
+
* it.
|
|
795
|
+
* - `recoveryHint`: lines 2+ of the sidecar concatenated, or `null`
|
|
796
|
+
* when the wrapper wrote no hint (happy-path classes don't need
|
|
797
|
+
* one; legacy single-line sidecars have none either). Surfaced
|
|
798
|
+
* in the failure notification message so the user sees the
|
|
799
|
+
* recommended recovery action without opening the error log.
|
|
851
800
|
*/
|
|
801
|
+
export interface DistillOutcome {
|
|
802
|
+
outcomeClass: string;
|
|
803
|
+
outcomePath: string;
|
|
804
|
+
recoveryHint: string | null;
|
|
805
|
+
}
|
|
806
|
+
|
|
852
807
|
export function findDistillOutcomeForBranch(
|
|
853
808
|
errorDir: string,
|
|
854
809
|
branchShort: string,
|
|
855
|
-
): {
|
|
856
|
-
outcomeClass: string;
|
|
857
|
-
outcomePath: string;
|
|
858
|
-
partialMergeLogPath: string | null;
|
|
859
|
-
} | null {
|
|
810
|
+
): DistillOutcome | null {
|
|
860
811
|
if (!fs.existsSync(errorDir)) return null;
|
|
861
812
|
if (branchShort.length === 0) return null;
|
|
862
813
|
let entries: string[];
|
|
@@ -869,51 +820,26 @@ export function findDistillOutcomeForBranch(
|
|
|
869
820
|
const outcomes = entries.filter((f) => f.endsWith(outcomeSuffix)).sort();
|
|
870
821
|
if (outcomes.length === 0) return null;
|
|
871
822
|
const outcomePath = path.join(errorDir, outcomes[outcomes.length - 1]);
|
|
823
|
+
// PR #12 A4: outcome sidecar format is multi-line
|
|
824
|
+
// line 1 = outcome class (machine-readable, drives JS-side dispatch)
|
|
825
|
+
// lines 2+ = optional human-readable recovery hint (failed:* only)
|
|
826
|
+
// Pre-PR-12 sidecars are single-line; the split below handles both
|
|
827
|
+
// shapes: `lines[0]` is always the class, `lines.slice(1).join('\n')`
|
|
828
|
+
// is empty for legacy single-line sidecars.
|
|
872
829
|
let outcomeClass = "";
|
|
830
|
+
let recoveryHint: string | null = null;
|
|
873
831
|
try {
|
|
874
|
-
|
|
832
|
+
const raw = fs.readFileSync(outcomePath, "utf-8");
|
|
833
|
+
const lines = raw.split("\n");
|
|
834
|
+
outcomeClass = (lines[0] ?? "").trim();
|
|
835
|
+
const restRaw = lines.slice(1).join("\n").trim();
|
|
836
|
+
recoveryHint = restRaw.length > 0 ? restRaw : null;
|
|
875
837
|
} catch {
|
|
876
838
|
// Treat unreadable outcome as missing — caller will fall through to
|
|
877
839
|
// abnormal-termination handling.
|
|
878
840
|
return null;
|
|
879
841
|
}
|
|
880
|
-
|
|
881
|
-
if (outcomeClass === "partial-merge") {
|
|
882
|
-
const pmSuffix = `-${branchShort}.partial-merge.log`;
|
|
883
|
-
const pmMatches = entries.filter((f) => f.endsWith(pmSuffix)).sort();
|
|
884
|
-
if (pmMatches.length > 0) {
|
|
885
|
-
partialMergeLogPath = path.join(
|
|
886
|
-
errorDir,
|
|
887
|
-
pmMatches[pmMatches.length - 1],
|
|
888
|
-
);
|
|
889
|
-
}
|
|
890
|
-
}
|
|
891
|
-
return { outcomeClass, outcomePath, partialMergeLogPath };
|
|
892
|
-
}
|
|
893
|
-
|
|
894
|
-
/**
|
|
895
|
-
* Prefix prepended to the distill prompt only when running through the
|
|
896
|
-
* worktree spawn path. Tells the agent its writes must stay inside the
|
|
897
|
-
* per-distill worktree — critical because the agent inherits the parent
|
|
898
|
-
* session's full message history (which contains absolute paths to the
|
|
899
|
-
* MAIN vault) and would otherwise route writes there via `edit`/`write`
|
|
900
|
-
* with absolute paths, silently bypassing worktree isolation.
|
|
901
|
-
*
|
|
902
|
-
* The prefix is added inside `spawnDistillInWorktree` (not at call sites)
|
|
903
|
-
* so every worktree-mode caller gets it automatically. Legacy spawn
|
|
904
|
-
* (manual /distill on git-less or disabled vaults) does NOT prepend
|
|
905
|
-
* this — there's no isolation to preserve there.
|
|
906
|
-
*
|
|
907
|
-
* Exported for tests; production callers should rely on the implicit
|
|
908
|
-
* application inside `spawnDistillInWorktree`.
|
|
909
|
-
*
|
|
910
|
-
* See POST-R6-CACHE in features/pi-napkin-distill/deferred.md for context.
|
|
911
|
-
*/
|
|
912
|
-
export function buildWorktreeDistillPrompt(
|
|
913
|
-
worktreePath: string,
|
|
914
|
-
basePrompt: string,
|
|
915
|
-
): string {
|
|
916
|
-
return `You are running in an isolated git worktree at ${worktreePath}. Only modify files within the worktree. Do NOT use absolute paths from the conversation history — those refer to the main vault and bypass isolation, causing the distill to silently merge nothing.\n\n${basePrompt}`;
|
|
842
|
+
return { outcomeClass, outcomePath, recoveryHint };
|
|
917
843
|
}
|
|
918
844
|
|
|
919
845
|
/**
|
|
@@ -933,10 +859,20 @@ export interface SpawnDistillOptions {
|
|
|
933
859
|
* worktree is handled by the wrapper's napkin shim, NOT cwd resolution.
|
|
934
860
|
*/
|
|
935
861
|
parentCwd: string;
|
|
936
|
-
/** Prompt passed to `pi -p`. */
|
|
937
|
-
prompt: string;
|
|
938
862
|
/** Optional model override, `<provider>/<id>`. Undefined → pi's default. */
|
|
939
863
|
model?: string;
|
|
864
|
+
/**
|
|
865
|
+
* Hard wall-clock budget (seconds) for the agent's distill+merge+squash+
|
|
866
|
+
* push+cleanup task. Wired into the wrapper's `timeout(1)` invocation so
|
|
867
|
+
* the agent is SIGTERMed (then SIGKILLed after grace) on overrun. Derived
|
|
868
|
+
* from `distill.maxDurationMinutes` (default 10 min = 600s). Must be a
|
|
869
|
+
* positive integer.
|
|
870
|
+
*
|
|
871
|
+
* PR #12 collapses the old per-phase timeouts (distill / per-file merge /
|
|
872
|
+
* squash) into this single agent-task budget — there are no per-phase
|
|
873
|
+
* subprocesses anymore for the wrapper to time-bound separately.
|
|
874
|
+
*/
|
|
875
|
+
maxDurationSecs: number;
|
|
940
876
|
/**
|
|
941
877
|
* Override for the `spawn` function — wired by unit tests to capture calls
|
|
942
878
|
* without actually starting processes. Defaults to the node:child_process
|
|
@@ -999,20 +935,26 @@ export function detectDefaultBranch(vaultPath: string): string {
|
|
|
999
935
|
export function spawnDistillInWorktree(
|
|
1000
936
|
opts: SpawnDistillOptions,
|
|
1001
937
|
): SpawnDistillResult {
|
|
1002
|
-
const { vault, sessionFile, parentCwd,
|
|
938
|
+
const { vault, sessionFile, parentCwd, model, maxDurationSecs } = opts;
|
|
1003
939
|
const spawnFn = opts.spawnFn ?? spawn;
|
|
1004
940
|
|
|
1005
941
|
const workspace = createDistillWorkspace(vault, sessionFile, parentCwd);
|
|
1006
942
|
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
//
|
|
1010
|
-
//
|
|
1011
|
-
//
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
943
|
+
const defaultBranch = detectDefaultBranch(vault);
|
|
944
|
+
|
|
945
|
+
// Build the agent-driven distill prompt by substituting the four
|
|
946
|
+
// placeholders into `extensions/distill/distill-prompt.md`. The .md
|
|
947
|
+
// contains the full agent contract (steps 1–6 distill content + steps
|
|
948
|
+
// 7–10 merge/squash/push/cleanup) plus the worktree-isolation prefix
|
|
949
|
+
// from POST-R6-CACHE — see PR #12 design "Agent contract". The wrapper
|
|
950
|
+
// hands this directly to `pi -p` as the agent's task; PR #12 deletes the
|
|
951
|
+
// per-file merge driver entirely.
|
|
952
|
+
const finalPrompt = buildDistillPrompt({
|
|
953
|
+
worktreePath: workspace.worktreePath,
|
|
954
|
+
vaultPath: vault,
|
|
955
|
+
branchName: workspace.branchName,
|
|
956
|
+
defaultBranch,
|
|
957
|
+
});
|
|
1016
958
|
|
|
1017
959
|
// Error dir lives on the MAIN vault (not in the worktree — worktrees are
|
|
1018
960
|
// removed on cleanup, which would lose the logs). Resolve via Napkin's
|
|
@@ -1030,8 +972,20 @@ export function spawnDistillInWorktree(
|
|
|
1030
972
|
finalPrompt,
|
|
1031
973
|
errorDir,
|
|
1032
974
|
model ?? "",
|
|
1033
|
-
|
|
975
|
+
defaultBranch,
|
|
1034
976
|
parentCwd,
|
|
977
|
+
String(maxDurationSecs),
|
|
978
|
+
// SEC-2 / CORR-3: pass the resolved cache root as an explicit
|
|
979
|
+
// positional arg so the wrapper's safe_rm_worktree path-safety
|
|
980
|
+
// guard can require worktrees to be descendants of THIS cache
|
|
981
|
+
// root (not just any path containing `/napkin-distill/<x>/<y>/`).
|
|
982
|
+
// The JS side is the source of truth — `resolveCacheRoot()` here
|
|
983
|
+
// is the same function that built `workspace.worktreePath`, so
|
|
984
|
+
// a future refactor that changes the cache layout updates both
|
|
985
|
+
// sides at once. Without this arg, the wrapper had to fall back
|
|
986
|
+
// on a glob pattern that any path containing the napkin-distill
|
|
987
|
+
// segment would satisfy.
|
|
988
|
+
resolveCacheRoot(vault),
|
|
1035
989
|
];
|
|
1036
990
|
|
|
1037
991
|
// Detached spawn: stdio "ignore" + unref() so the parent can exit cleanly
|
|
@@ -1246,65 +1200,15 @@ function toActiveDistills(
|
|
|
1246
1200
|
return active;
|
|
1247
1201
|
}
|
|
1248
1202
|
|
|
1249
|
-
/**
|
|
1250
|
-
* Return the list of files an active distill worktree has changed since
|
|
1251
|
-
* it forked from the vault's HEAD. Used by live diagnostic surfaces
|
|
1252
|
-
* (status, debugging) while the worktree exists.
|
|
1253
|
-
*
|
|
1254
|
-
* For the per-distill-completion overlap notice (R7-PERF-2) the worktree
|
|
1255
|
-
* is already gone by the time we look — use
|
|
1256
|
-
* `getDistillTouchedFilesPostSquash(vault, startSha)` instead, which
|
|
1257
|
-
* runs against the main vault's commit log.
|
|
1258
|
-
*
|
|
1259
|
-
* Strategy:
|
|
1260
|
-
* - When `startSha` is recorded in meta.json (Phase C2+), diff
|
|
1261
|
-
* `<startSha>..HEAD` inside the worktree. That gives exactly the set
|
|
1262
|
-
* of files the distill has committed.
|
|
1263
|
-
* - When `startSha` is absent (legacy meta.json), fall back to
|
|
1264
|
-
* `git status --porcelain` inside the worktree — captures both
|
|
1265
|
-
* committed-and-not-merged AND uncommitted changes. Less precise but
|
|
1266
|
-
* still useful for overlap detection.
|
|
1267
|
-
*
|
|
1268
|
-
* All paths are returned relative to the worktree root (which is the same
|
|
1269
|
-
* as the vault root from a tracking perspective). Returns `[]` on any
|
|
1270
|
-
* error — overlap detection is best-effort and must not throw.
|
|
1271
|
-
*/
|
|
1272
|
-
export function diffWorktreeSinceStart(
|
|
1273
|
-
active: Pick<ActiveDistill, "worktreePath" | "startSha">,
|
|
1274
|
-
): string[] {
|
|
1275
|
-
if (!fs.existsSync(active.worktreePath)) return [];
|
|
1276
|
-
if (active.startSha) {
|
|
1277
|
-
const r = runGit(active.worktreePath, [
|
|
1278
|
-
"diff",
|
|
1279
|
-
"--name-only",
|
|
1280
|
-
`${active.startSha}..HEAD`,
|
|
1281
|
-
]);
|
|
1282
|
-
if (r.status !== 0) return [];
|
|
1283
|
-
return r.stdout
|
|
1284
|
-
.split("\n")
|
|
1285
|
-
.map((l) => l.trim())
|
|
1286
|
-
.filter((l) => l.length > 0);
|
|
1287
|
-
}
|
|
1288
|
-
// Legacy fallback: uncommitted + committed changes (porcelain lists both).
|
|
1289
|
-
// Format: `XY path` where XY is the 2-char status code.
|
|
1290
|
-
const r = runGit(active.worktreePath, ["status", "--porcelain"]);
|
|
1291
|
-
if (r.status !== 0) return [];
|
|
1292
|
-
return r.stdout
|
|
1293
|
-
.split("\n")
|
|
1294
|
-
.map((l) => l.slice(3).trim())
|
|
1295
|
-
.filter((l) => l.length > 0);
|
|
1296
|
-
}
|
|
1297
|
-
|
|
1298
1203
|
/**
|
|
1299
1204
|
* Return the list of files affected by commits in the main vault between
|
|
1300
1205
|
* `startSha` (the distill's fork point) and HEAD (post-squash, after the
|
|
1301
1206
|
* wrapper's squash-merge has landed). Used by per-completion overlap
|
|
1302
1207
|
* detection (R7-PERF-2) to compare against the parent session's writes.
|
|
1303
1208
|
*
|
|
1304
|
-
*
|
|
1305
|
-
* the
|
|
1306
|
-
*
|
|
1307
|
-
* `<startSha>..HEAD`'s name range.
|
|
1209
|
+
* Runs against the MAIN vault — the distill worktree has been removed by
|
|
1210
|
+
* the time we're called. The squash commit on main brings every file the
|
|
1211
|
+
* distill affected into `<startSha>..HEAD`'s name range.
|
|
1308
1212
|
*
|
|
1309
1213
|
* If `startSha` is missing (legacy distill meta) we cannot reliably
|
|
1310
1214
|
* compute the post-squash file set without scanning the now-removed
|