@justjoshn/pi-pstack-v2 0.1.7 → 0.2.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/src/sweep.ts DELETED
@@ -1,187 +0,0 @@
1
- import { appendFileSync, chmodSync, cpSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
2
- import { basename, dirname, join } from 'node:path';
3
-
4
- import { z } from 'zod';
5
-
6
- /**
7
- * What a checkout held when a job started, so that the unsandboxed wrapper can quarantine, after the job, every path an
8
- * unsandboxed process would later execute from that the job made appear. A job can make one appear even where it may
9
- * not write it directly, by renaming a directory it built into place or by linking a parent elsewhere.
10
- */
11
- export interface Inventory {
12
- /** Checkouts the job may write, walked without following links. */
13
- roots: string[];
14
- /** Protected paths absent at launch, each with whether its parent was already a link. */
15
- absent: { path: string; parentWasLink: boolean }[];
16
- /** Code entries present at launch, which the sweep leaves alone. */
17
- present: string[];
18
- /** Where swept paths go, and where the job's output notes them. */
19
- quarantine: string;
20
- output: string;
21
- }
22
-
23
- // The inventory is read as written, since this file runs alone in the job's output directory and a missing or odd key is
24
- // reported by the sweep's own catch into the job's output, as it always was.
25
- const InventorySchema = z.custom<Inventory>((value) => typeof value === 'object' && value !== null);
26
-
27
- /** Pi loads code from these entries of any `.pi` directory, at any depth, once the project is trusted. */
28
- export const PI_CODE = ['extensions', 'settings.json', 'mcp.json', 'npm', 'git'] as const;
29
-
30
- /**
31
- * Editors and other agent harnesses run what these hold, unsandboxed, once you open the checkout in them: VS Code and
32
- * JetBrains tasks, and agent-harness hooks and MCP servers. pstack's sandbox refuses writing them at any depth. Every
33
- * entry of a harness directory is code apart from its instructions, which a job may still write.
34
- */
35
- export const EDITOR_CODE = ['.vscode', '.idea', '.cursorignore'] as const;
36
- export const WORKSPACE_SUFFIX = '.code-workspace';
37
- export const HARNESS_DIRS = ['.cursor', '.claude'] as const;
38
- export const HARNESS_INSTRUCTIONS = ['rules', 'commands', 'worktrees', 'skills', 'agents'] as const;
39
-
40
- const includes = (list: readonly string[], name: string): boolean => list.includes(name);
41
- /** Which entries of each such directory are code. */
42
- const CODE_DIRS = new Map<string, (entry: string) => boolean>([['.pi', (entry) => includes(PI_CODE, entry)], ...HARNESS_DIRS.map((dir) => [dir, (entry: string) => !includes(HARNESS_INSTRUCTIONS, entry)] as const)]);
43
- /** Entries that are code whole: any .git, and editor configuration. */
44
- const wholeCode = (name: string): boolean => name === '.git' || includes(EDITOR_CODE, name) || name.endsWith(WORKSPACE_SUFFIX);
45
-
46
- const exists = (path: string): boolean => {
47
- try {
48
- lstatSync(path);
49
- return true;
50
- } catch {
51
- return false;
52
- }
53
- };
54
-
55
- /**
56
- * Code entries (Pi, git, editor, and harness) under the roots, found without following links or descending into heavy or git
57
- * directories. With `repair`, a directory the job made unreadable gets its owner permissions back so it can be searched,
58
- * and anything still unreadable lands in `unreadable`, since a job could otherwise hide code from the sweep that way.
59
- */
60
- export function codePaths(roots: string[], repair = false): string[] {
61
- return scanCode(roots, repair).found;
62
- }
63
-
64
- type Scan = { found: string[]; unreadable: string[] };
65
- const EMPTY_SCAN: Scan = { found: [], unreadable: [] };
66
- const joinScans = (scans: Scan[]): Scan => ({ found: scans.flatMap((scan) => scan.found), unreadable: scans.flatMap((scan) => scan.unreadable) });
67
-
68
- /** Reads with `read`, and with `repair` retries once after restoring owner permissions. Fails with the path as unreadable. */
69
- function attempt<T>(path: string, repair: boolean, read: () => T): { value?: T; unreadable: string[] } {
70
- try {
71
- return { value: read(), unreadable: [] };
72
- } catch {
73
- if (!repair) return { unreadable: [] };
74
- }
75
- try {
76
- chmodSync(path, (lstatSync(path).mode & 0o7777) | 0o700);
77
- return { value: read(), unreadable: [] };
78
- } catch {
79
- return { unreadable: [path] };
80
- }
81
- }
82
-
83
- /** Like `codePaths`, and also names every directory that stayed unreadable even after repair. */
84
- function scanCode(roots: string[], repair: boolean): Scan {
85
- // Links are never followed, so the walk cannot loop and needs no depth limit.
86
- const walk = (dir: string): Scan => {
87
- // Inside a code directory such as `.pi` or `.claude`, its code entries are found and the rest is searched like any directory.
88
- const isCode = CODE_DIRS.get(basename(dir));
89
- const listing = attempt(dir, repair, () => readdirSync(dir));
90
- const entries = (listing.value ?? []).map((name) => {
91
- const path = join(dir, name);
92
- const stat = attempt(dir, repair, () => lstatSync(path));
93
- return { name, path, stat: stat.value, unreadable: stat.unreadable };
94
- });
95
- const scans = entries.map(({ name, path, stat, unreadable }): Scan => {
96
- if (!stat) return { found: [], unreadable };
97
- if (wholeCode(name) || isCode?.(name) || (CODE_DIRS.has(name) && stat.isSymbolicLink())) return { found: [path], unreadable };
98
- return stat.isDirectory() && name !== 'node_modules' ? joinScans([{ found: [], unreadable }, walk(path)]) : { found: [], unreadable };
99
- });
100
- return joinScans([{ found: [], unreadable: listing.unreadable }, ...scans]);
101
- };
102
- return joinScans([EMPTY_SCAN, ...roots.map(walk)]);
103
- }
104
-
105
- export function inventory(roots: string[], protect: string[], quarantine: string, output: string): Inventory {
106
- const absent = protect.filter((path) => !exists(path)).map((path) => ({ path, parentWasLink: exists(dirname(path)) && lstatSync(dirname(path)).isSymbolicLink() }));
107
- return { roots, absent, present: codePaths(roots), quarantine, output };
108
- }
109
-
110
- // Moving a path out needs write permission on its parent, and a directory also on itself, which a job can take away.
111
- // chmod follows links, so only real directories are touched.
112
- function makeWritable(path: string): void {
113
- const stat = lstatSync(path);
114
- if (stat.isDirectory()) chmodSync(path, (stat.mode & 0o7777) | 0o700);
115
- }
116
-
117
- /** Renames into quarantine, which can sit on another filesystem. Copying keeps links as links and removing never follows one. */
118
- function relocate(path: string, target: string): void {
119
- try {
120
- renameSync(path, target);
121
- } catch (error) {
122
- if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
123
- cpSync(path, target, { recursive: true, verbatimSymlinks: true });
124
- rmSync(path, { recursive: true, force: true });
125
- }
126
- }
127
-
128
- /** Quarantines one path and notes it in the job's output. Returns whether it moved. */
129
- function quarantine(inv: Inventory, path: string, reason: string, serial: number): boolean {
130
- if (!exists(path)) return false;
131
- try {
132
- mkdirSync(inv.quarantine, { recursive: true });
133
- const target = join(inv.quarantine, `${Date.now()}-${serial}-${basename(path)}`);
134
- makeWritable(dirname(path));
135
- makeWritable(path);
136
- relocate(path, target);
137
- appendFileSync(inv.output, `pstack quarantined ${path}, ${reason}, in ${inv.quarantine}.\n`);
138
- return true;
139
- } catch (error) {
140
- appendFileSync(inv.output, `pstack could not quarantine ${path}, ${reason}: ${String(error)}. Check it before you start Pi in this checkout.\n`);
141
- return false;
142
- }
143
- }
144
-
145
- type Move = { path: string; reason: string };
146
-
147
- /** What to move for a protected path that was absent at launch: a link that appeared over its parent, else the path itself. */
148
- function absentMoveOf({ path, parentWasLink }: Inventory['absent'][number]): Move {
149
- const parent = dirname(path);
150
- if (!parentWasLink && exists(parent) && lstatSync(parent).isSymbolicLink()) return { path: parent, reason: 'a link that appeared over a protected path while the job ran' };
151
- return { path, reason: 'which appeared while the job ran' };
152
- }
153
-
154
- /** Moves each path in order, then returns the earlier moves with the ones that happened. */
155
- const moveAll = (inv: Inventory, moves: Move[], moved: string[]): string[] => {
156
- const [head, ...rest] = moves;
157
- if (head === undefined) return moved;
158
- return moveAll(inv, rest, quarantine(inv, head.path, head.reason, moved.length) ? moved.concat(head.path) : moved);
159
- };
160
-
161
- /** Moves each path that appeared during the job into quarantine, never following a link, and returns what it moved. */
162
- export function sweep(inv: Inventory): string[] {
163
- // Each path is decided after the earlier moves, since a move can change what its parent is.
164
- const afterAbsent = inv.absent.reduce((moved, entry) => moveAll(inv, [absentMoveOf(entry)], moved), [] as string[]);
165
- const present = new Set(inv.present);
166
- const scan = scanCode(inv.roots, true);
167
- const moved = moveAll(
168
- inv,
169
- scan.found.filter((path) => !present.has(path)).map((path) => ({ path, reason: 'Pi, git, editor, or harness code that appeared while the job ran' })),
170
- afterAbsent,
171
- );
172
- for (const path of new Set(scan.unreadable)) appendFileSync(inv.output, `pstack could not search ${path} for Pi, git, editor, or harness code the job may have left there. Check it before you start Pi in this checkout.\n`);
173
- return moved;
174
- }
175
-
176
- // The wrapper runs this file directly once the job has ended: `node sweep.ts <inventory.json>`.
177
- const argv = z.array(z.string()).parse(process.argv);
178
- if (argv[1] && basename(argv[1]) === 'sweep.ts' && argv[2]) {
179
- const inv = InventorySchema.parse(JSON.parse(readFileSync(argv[2], 'utf8')));
180
- try {
181
- sweep(inv);
182
- } catch (error) {
183
- appendFileSync(inv.output, `pstack could not finish checking this job's checkout for Pi, git, editor, or harness code it left behind: ${String(error)}\n`);
184
- }
185
- }
186
-
187
- export const inventoryFile = (out: string): string => join(out, 'inventory.json');
package/src/transcript.ts DELETED
@@ -1,79 +0,0 @@
1
- import { lstatSync, readdirSync, readFileSync } from 'node:fs';
2
- import { join } from 'node:path';
3
-
4
- import { parseSessionEntries, type SessionEntry } from '@earendil-works/pi-coding-agent';
5
-
6
- type Report = { path: string; answers: string[]; toolCalls: number };
7
- type Assistant = Extract<SessionEntry, { type: 'message' }>;
8
-
9
- const isAssistant = (entry: SessionEntry): entry is Assistant => entry.type === 'message' && entry.message.role === 'assistant';
10
-
11
- /** The entries from the last one back to the root, oldest first. A cycle in parent ids ends the walk. */
12
- function branchOf(turns: SessionEntry[]): SessionEntry[] {
13
- const byId = new Map(turns.map((entry) => [entry.id, entry]));
14
- const walk = (entry: SessionEntry | undefined, seen: ReadonlySet<string>): SessionEntry[] => (entry && !seen.has(entry.id) ? [entry, ...walk(entry.parentId ? byId.get(entry.parentId) : undefined, new Set([...seen, entry.id]))] : []);
15
- return walk(turns.at(-1), new Set()).toReversed();
16
- }
17
-
18
- /** What one assistant turn contributes to the answers, or nothing. */
19
- function answerOf(entry: Assistant, last: boolean): string[] {
20
- const message = entry.message;
21
- if (message.role !== 'assistant') return [];
22
- const text = message.content
23
- .filter((block) => block.type === 'text')
24
- .map((block) => block.text)
25
- .join('\n');
26
- const ended = [`[Worker answer ended with ${message.stopReason}]`, text, message.errorMessage].filter(Boolean).join('\n');
27
- switch (message.stopReason) {
28
- case 'stop':
29
- return text.trim() ? [text] : [];
30
- case 'error':
31
- case 'aborted':
32
- // A failed turn the worker went on from was retried, so only the one it ended on is its answer.
33
- return last ? [ended] : [];
34
- case 'length':
35
- return [ended];
36
- case 'toolUse':
37
- case 'pending':
38
- case 'deferred':
39
- return [];
40
- default: {
41
- const unhandled: never = message.stopReason;
42
- throw new Error(`Unhandled worker stop reason: ${unhandled}`);
43
- }
44
- }
45
- }
46
-
47
- function reportOf(path: string, entries: ReturnType<typeof parseSessionEntries>, since: string): Report {
48
- const turns = entries.filter((entry): entry is SessionEntry => entry.type !== 'session');
49
- const branch = branchOf(turns);
50
- const prompt = branch.findLastIndex((entry) => entry.type === 'message' && entry.message.role === 'user');
51
- if (prompt < 0 || !(Date.parse(branch[prompt]?.timestamp ?? '') >= Date.parse(since))) return { path, answers: [], toolCalls: 0 };
52
- const after = branch.slice(prompt + 1);
53
- const assistants = after.filter(isAssistant);
54
- return {
55
- path,
56
- answers: assistants.flatMap((entry) => answerOf(entry, entry === assistants.at(-1))),
57
- toolCalls: after.filter((entry) => entry.type === 'message' && entry.message.role === 'toolResult').length,
58
- };
59
- }
60
-
61
- /** A worker's completed answers since its brief, and how many tool calls it made. */
62
- export function workerReport(sessionDir: string | undefined, since: string): Report | undefined {
63
- if (!sessionDir) return undefined;
64
- try {
65
- if (!lstatSync(sessionDir).isDirectory()) return undefined;
66
- const files = readdirSync(sessionDir)
67
- .filter((name) => name.endsWith('.jsonl'))
68
- .map((name) => ({ path: join(sessionDir, name), stat: lstatSync(join(sessionDir, name)) }))
69
- .filter(({ stat }) => stat.isFile())
70
- .toSorted((a, b) => b.stat.mtimeMs - a.stat.mtimeMs);
71
- for (const { path } of files) {
72
- const entries = parseSessionEntries(readFileSync(path, 'utf8'));
73
- if (entries[0]?.type === 'session') return reportOf(path, entries, since);
74
- }
75
- } catch {
76
- return undefined;
77
- }
78
- return undefined;
79
- }