@justjoshn/pi-pstack-v2 0.1.6 → 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.
@@ -0,0 +1,96 @@
1
+ import * as path from 'node:path';
2
+
3
+ import type { VM } from '@earendil-works/gondolin';
4
+ import { DEFAULT_MAX_BYTES, formatSize, type GrepToolDetails, type GrepToolInput, truncateHead, truncateLine } from '@earendil-works/pi-coding-agent';
5
+ import { toGuestPath } from './paths.ts';
6
+ import { type GuestFile, matchesToolGlob, signalOption, throwIfAborted, walkGuestFiles } from './search.ts';
7
+
8
+ const DEFAULT_GREP_LIMIT = 100;
9
+ const MIN_GREP_LIMIT = 1;
10
+
11
+ type TextToolResult<TDetails> = { content: Array<{ type: 'text'; text: string }>; details: TDetails | undefined };
12
+ /** One match's output lines, with its context, and whether any of them was cut for length. */
13
+ type GrepBlock = { lines: readonly string[]; truncated: boolean };
14
+ type GrepSearch = { glob: string | undefined; matcher: (line: string) => boolean; contextLines: number; rootIsDirectory: boolean };
15
+
16
+ function createLineMatcher(pattern: string, literal: boolean | undefined, ignoreCase: boolean | undefined): (line: string) => boolean {
17
+ if (literal) {
18
+ const needle = ignoreCase ? pattern.toLowerCase() : pattern;
19
+ return (line) => (ignoreCase ? line.toLowerCase() : line).includes(needle);
20
+ }
21
+ const regex = new RegExp(pattern, ignoreCase ? 'i' : undefined);
22
+ return (line) => regex.test(line);
23
+ }
24
+
25
+ const splitLines = (content: string): string[] => content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
26
+
27
+ function grepBlock(lines: readonly string[], displayPath: string, lineIndex: number, contextLines: number): GrepBlock {
28
+ const start = contextLines > 0 ? Math.max(0, lineIndex - contextLines) : lineIndex;
29
+ const end = contextLines > 0 ? Math.min(lines.length - 1, lineIndex + contextLines) : lineIndex;
30
+ const rendered = Array.from({ length: end - start + 1 }, (_, offset) => {
31
+ const index = start + offset;
32
+ const { text, wasTruncated } = truncateLine((lines[index] ?? '').replace(/\r/g, ''));
33
+ const separator = index === lineIndex ? ':' : '-';
34
+ return { line: `${displayPath}${separator}${index + 1}${separator} ${text}`, wasTruncated };
35
+ });
36
+ return { lines: rendered.map((entry) => entry.line), truncated: rendered.some((entry) => entry.wasTruncated) };
37
+ }
38
+
39
+ function* matchingLineIndexes(lines: readonly string[], matcher: (line: string) => boolean, signal: AbortSignal | undefined): Generator<number> {
40
+ for (let index = 0; index < lines.length; index++) {
41
+ throwIfAborted(signal);
42
+ if (matcher(lines[index] ?? '')) yield index;
43
+ }
44
+ }
45
+
46
+ async function* grepBlocks(vm: VM, files: AsyncIterable<GuestFile>, search: GrepSearch, signal: AbortSignal | undefined): AsyncGenerator<GrepBlock> {
47
+ for await (const file of files) {
48
+ if (search.glob && !matchesToolGlob(file.relativePath, search.glob)) continue;
49
+ // A file that cannot be read as text, or vanished, is skipped like the built-in grep skips it.
50
+ const content = await vm.fs.readFile(file.guestPath, { encoding: 'utf8', ...signalOption(signal) }).catch(() => undefined);
51
+ if (content === undefined) continue;
52
+ const lines = splitLines(content);
53
+ const displayPath = search.rootIsDirectory ? file.relativePath : path.posix.basename(file.guestPath);
54
+ for (const index of matchingLineIndexes(lines, search.matcher, signal)) yield grepBlock(lines, displayPath, index, search.contextLines);
55
+ }
56
+ }
57
+
58
+ /** Collects the first `limit` blocks and then stops the source, so the walk ends at the last match it needs. */
59
+ async function firstBlocks(blocks: AsyncIterable<GrepBlock>, limit: number): Promise<readonly GrepBlock[]> {
60
+ let taken: readonly GrepBlock[] = [];
61
+ for await (const block of blocks) {
62
+ taken = [...taken, block];
63
+ if (taken.length >= limit) break;
64
+ }
65
+ return taken;
66
+ }
67
+
68
+ function formatGrep(blocks: readonly GrepBlock[], limit: number): TextToolResult<GrepToolDetails> {
69
+ const truncation = truncateHead(blocks.flatMap((block) => block.lines).join('\n'), { maxLines: Number.MAX_SAFE_INTEGER });
70
+ const limitReached = blocks.length >= limit;
71
+ const linesTruncated = blocks.some((block) => block.truncated);
72
+ const details: GrepToolDetails = {
73
+ ...(limitReached ? { matchLimitReached: limit } : {}),
74
+ ...(linesTruncated ? { linesTruncated: true } : {}),
75
+ ...(truncation.truncated ? { truncation } : {}),
76
+ };
77
+ const notices = [limitReached ? `${limit} matches limit reached` : '', linesTruncated ? 'long lines truncated' : '', truncation.truncated ? `${formatSize(DEFAULT_MAX_BYTES)} limit reached` : ''].filter(Boolean);
78
+ const output = notices.length > 0 ? `${truncation.content}\n\n[${notices.join('. ')}]` : truncation.content;
79
+ return { content: [{ type: 'text', text: output }], details: Object.keys(details).length > 0 ? details : undefined };
80
+ }
81
+
82
+ /** Runs grep over guest files through the VM filesystem, matching the built-in grep's output format and limits. */
83
+ export async function executeGondolinGrep(vm: VM, localCwd: string, params: GrepToolInput, signal?: AbortSignal): Promise<TextToolResult<GrepToolDetails>> {
84
+ const root = toGuestPath(localCwd, params.path ?? '.');
85
+ const rootStat = await vm.fs.stat(root, signalOption(signal));
86
+ const search: GrepSearch = {
87
+ glob: params.glob,
88
+ rootIsDirectory: rootStat.isDirectory(),
89
+ matcher: createLineMatcher(params.pattern, params.literal, params.ignoreCase),
90
+ contextLines: params.context && params.context > 0 ? params.context : 0,
91
+ };
92
+ const limit = Math.max(MIN_GREP_LIMIT, params.limit ?? DEFAULT_GREP_LIMIT);
93
+ const blocks = await firstBlocks(grepBlocks(vm, walkGuestFiles(vm, root, signal), search, signal), limit);
94
+ if (blocks.length === 0) return { content: [{ type: 'text', text: 'No matches found' }], details: undefined };
95
+ return formatGrep(blocks, limit);
96
+ }
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Gondolin tool routing, ported from Pi's gondolin example extension.
3
+ *
4
+ * Runs Pi's built-in tools inside a local Gondolin micro-VM. The host working directory is mounted at /workspace in
5
+ * the guest. File changes under /workspace write through to the host; other guest filesystem changes stay in the VM.
6
+ * Needs QEMU on the host.
7
+ */
8
+
9
+ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
10
+ import { createGondolinBashOps } from './bash.ts';
11
+ import { GUEST_WORKSPACE } from './paths.ts';
12
+ import { registerGuestTools } from './tools.ts';
13
+ import { createGondolinVm, type GondolinVm } from './vm.ts';
14
+
15
+ /** Points the model at the guest workspace in place of the host cwd line, or appends the line when Pi's is absent. */
16
+ export function guestSystemPrompt(systemPrompt: string, localCwd: string): string {
17
+ const localLine = `Current working directory: ${localCwd}`;
18
+ const guestLine = `Current working directory: ${GUEST_WORKSPACE} (Gondolin VM; host workspace mounted from ${localCwd})`;
19
+ return systemPrompt.includes(localLine) ? systemPrompt.replace(localLine, guestLine) : `${systemPrompt}\n\n${guestLine}`;
20
+ }
21
+
22
+ function registerStatusCommand(pi: ExtensionAPI, guest: GondolinVm, localCwd: string): void {
23
+ pi.registerCommand('gondolin', {
24
+ description: 'Show Gondolin VM status',
25
+ handler: async (_args, ctx) => {
26
+ const activeVm = await guest.ensure(ctx);
27
+ const status = [`Gondolin VM: ${activeVm.id}`, `Host workspace: ${localCwd}`, `Guest workspace: ${GUEST_WORKSPACE}`, `Shell: ${guest.shellPath()}`];
28
+ ctx.ui.notify(status.join('\n'), 'info');
29
+ },
30
+ });
31
+ }
32
+
33
+ export default function gondolin(pi: ExtensionAPI): void {
34
+ const localCwd = process.cwd();
35
+ const guest = createGondolinVm(localCwd);
36
+
37
+ pi.on('session_start', async (_event, ctx) => {
38
+ await guest.ensure(ctx);
39
+ });
40
+ pi.on('session_shutdown', async (_event, ctx) => guest.close(ctx));
41
+ registerStatusCommand(pi, guest, localCwd);
42
+ registerGuestTools(pi, guest, localCwd);
43
+ pi.on('user_bash', async (_event, ctx) => {
44
+ const activeVm = await guest.ensure(ctx);
45
+ return { operations: createGondolinBashOps(activeVm, localCwd, guest.shellPath()) };
46
+ });
47
+ pi.on('before_agent_start', async (event, ctx) => {
48
+ await guest.ensure(ctx);
49
+ return { systemPrompt: guestSystemPrompt(event.systemPrompt, localCwd) };
50
+ });
51
+ }
@@ -0,0 +1,34 @@
1
+ import * as path from 'node:path';
2
+
3
+ /** The guest directory the host working directory is mounted at. */
4
+ export const GUEST_WORKSPACE = '/workspace';
5
+ const GUEST_ROOT = '/';
6
+
7
+ const stripAtPrefix = (value: string): string => (value.startsWith('@') ? value.slice(1) : value);
8
+
9
+ export const toPosix = (value: string): string => value.split(path.sep).join(path.posix.sep);
10
+
11
+ const isInsideHostPath = (root: string, value: string): boolean => {
12
+ const relativePath = path.relative(root, value);
13
+ return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
14
+ };
15
+
16
+ const hostPathToGuest = (localCwd: string, hostPath: string): string => {
17
+ const relativePath = path.relative(localCwd, hostPath);
18
+ if (!isInsideHostPath(localCwd, hostPath)) return toPosix(hostPath);
19
+ return relativePath ? path.posix.join(GUEST_WORKSPACE, toPosix(relativePath)) : GUEST_WORKSPACE;
20
+ };
21
+
22
+ /**
23
+ * Maps a path a tool received to the guest. Relative paths and host paths inside the working directory land under
24
+ * the workspace mount; other absolute paths name the same path in the guest's own filesystem.
25
+ */
26
+ export function toGuestPath(localCwd: string, inputPath: string): string {
27
+ const trimmed = stripAtPrefix(inputPath.trim());
28
+ if (!trimmed) return GUEST_WORKSPACE;
29
+ if (path.isAbsolute(trimmed)) {
30
+ if (isInsideHostPath(localCwd, trimmed)) return hostPathToGuest(localCwd, trimmed);
31
+ return path.posix.resolve(GUEST_ROOT, toPosix(trimmed));
32
+ }
33
+ return path.posix.resolve(GUEST_WORKSPACE, toPosix(trimmed));
34
+ }
@@ -0,0 +1,67 @@
1
+ import * as path from 'node:path';
2
+
3
+ import type { VM } from '@earendil-works/gondolin';
4
+ import type { FindOperations } from '@earendil-works/pi-coding-agent';
5
+ import { guestExists } from './fs-operations.ts';
6
+ import { toGuestPath, toPosix } from './paths.ts';
7
+
8
+ // The built-in find and grep skip these too, and walking them through the VM would be slow.
9
+ const SKIPPED_ENTRIES: ReadonlySet<string> = new Set(['.git', 'node_modules']);
10
+ export const ABORTED_MESSAGE = 'Operation aborted';
11
+ const POSIX_SEPARATOR = '/';
12
+
13
+ export type GuestFile = { guestPath: string; relativePath: string };
14
+
15
+ /** Gondolin reads a missing signal and an undefined one alike, and its option types accept only the first. */
16
+ export const signalOption = (signal: AbortSignal | undefined): { signal?: AbortSignal } => (signal ? { signal } : {});
17
+
18
+ export const throwIfAborted = (signal: AbortSignal | undefined): void => {
19
+ if (signal?.aborted) throw new Error(ABORTED_MESSAGE);
20
+ };
21
+
22
+ async function* walkDirectory(vm: VM, dir: string, relativeDir: string, signal: AbortSignal | undefined): AsyncGenerator<GuestFile> {
23
+ throwIfAborted(signal);
24
+ const entries = await vm.fs.listDir(dir, signalOption(signal));
25
+ for (const entry of entries.filter((name) => !SKIPPED_ENTRIES.has(name))) {
26
+ const guestPath = path.posix.join(dir, entry);
27
+ const relativePath = relativeDir ? path.posix.join(relativeDir, entry) : entry;
28
+ // An entry that vanished or cannot be read is skipped, not fatal to the walk.
29
+ const entryStat = await vm.fs.stat(guestPath, signalOption(signal)).catch(() => undefined);
30
+ if (!entryStat) continue;
31
+ if (entryStat.isDirectory()) yield* walkDirectory(vm, guestPath, relativePath, signal);
32
+ else yield { guestPath, relativePath };
33
+ }
34
+ }
35
+
36
+ /** Yields files under root lazily, so a caller that stops iterating also stops the walk and its VM round trips. */
37
+ export async function* walkGuestFiles(vm: VM, root: string, signal?: AbortSignal): AsyncGenerator<GuestFile> {
38
+ throwIfAborted(signal);
39
+ const stat = await vm.fs.stat(root, signalOption(signal));
40
+ if (stat.isDirectory()) yield* walkDirectory(vm, root, '', signal);
41
+ else yield { guestPath: root, relativePath: path.posix.basename(root) };
42
+ }
43
+
44
+ // Like the built-in find and grep: a pattern with '/' is relative to the search root, one without '/' matches file
45
+ // names at any depth.
46
+ export function matchesToolGlob(relativePath: string, pattern: string): boolean {
47
+ const normalizedPattern = toPosix(pattern).replace(/^(?:\.\/)+/, '');
48
+ if (normalizedPattern.includes(POSIX_SEPARATOR)) return path.posix.matchesGlob(relativePath, normalizedPattern);
49
+ return path.posix.matchesGlob(path.posix.basename(relativePath), normalizedPattern);
50
+ }
51
+
52
+ async function firstMatches(files: AsyncIterable<GuestFile>, pattern: string, limit: number): Promise<string[]> {
53
+ let results: readonly string[] = [];
54
+ for await (const file of files) {
55
+ if (results.length >= limit) break;
56
+ if (matchesToolGlob(file.relativePath, pattern)) results = [...results, file.guestPath];
57
+ if (results.length >= limit) break;
58
+ }
59
+ return [...results];
60
+ }
61
+
62
+ export function createGondolinFindOps(vm: VM, localCwd: string): FindOperations {
63
+ return {
64
+ exists: async (filePath) => guestExists(vm, localCwd, filePath),
65
+ glob: async (pattern, cwd, options) => firstMatches(walkGuestFiles(vm, toGuestPath(localCwd, cwd)), pattern, options.limit),
66
+ };
67
+ }
@@ -0,0 +1,40 @@
1
+ import type { VM } from '@earendil-works/gondolin';
2
+ import {
3
+ type AgentToolResult,
4
+ type AgentToolUpdateCallback,
5
+ createBashTool,
6
+ createEditTool,
7
+ createFindTool,
8
+ createGrepTool,
9
+ createLsTool,
10
+ createReadTool,
11
+ createWriteTool,
12
+ type ExtensionAPI,
13
+ type ToolDefinition,
14
+ } from '@earendil-works/pi-coding-agent';
15
+ import type { Static, TSchema } from 'typebox';
16
+ import { createGondolinBashOps } from './bash.ts';
17
+ import { createGondolinEditOps, createGondolinLsOps, createGondolinReadOps, createGondolinWriteOps } from './fs-operations.ts';
18
+ import { executeGondolinGrep } from './grep.ts';
19
+ import { GUEST_WORKSPACE } from './paths.ts';
20
+ import { createGondolinFindOps } from './search.ts';
21
+ import type { GondolinVm } from './vm.ts';
22
+
23
+ type GuestRun<TParams extends TSchema, TDetails> = (vm: VM, id: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined) => Promise<AgentToolResult<TDetails>>;
24
+
25
+ /** Keeps the local tool's name, schema, and prompt text, and runs each call in the session VM instead. */
26
+ const routeToGuest = <TParams extends TSchema, TDetails>(local: Omit<ToolDefinition<TParams, TDetails>, 'execute'>, guest: GondolinVm, run: GuestRun<TParams, TDetails>): ToolDefinition<TParams, TDetails> => ({
27
+ ...local,
28
+ execute: async (id, params, signal, onUpdate, ctx) => run(await guest.ensure(ctx), id, params, signal, onUpdate),
29
+ });
30
+
31
+ /** Overrides the seven built-in file and shell tools so each call reaches the guest through the workspace mount. */
32
+ export function registerGuestTools(pi: ExtensionAPI, guest: GondolinVm, localCwd: string): void {
33
+ pi.registerTool(routeToGuest(createReadTool(localCwd), guest, (vm, ...call) => createReadTool(GUEST_WORKSPACE, { operations: createGondolinReadOps(vm, localCwd) }).execute(...call)));
34
+ pi.registerTool(routeToGuest(createWriteTool(localCwd), guest, (vm, ...call) => createWriteTool(GUEST_WORKSPACE, { operations: createGondolinWriteOps(vm, localCwd) }).execute(...call)));
35
+ pi.registerTool(routeToGuest(createEditTool(localCwd), guest, (vm, ...call) => createEditTool(GUEST_WORKSPACE, { operations: createGondolinEditOps(vm, localCwd) }).execute(...call)));
36
+ pi.registerTool(routeToGuest(createBashTool(localCwd), guest, (vm, ...call) => createBashTool(GUEST_WORKSPACE, { operations: createGondolinBashOps(vm, localCwd, guest.shellPath()) }).execute(...call)));
37
+ pi.registerTool(routeToGuest(createLsTool(localCwd), guest, (vm, ...call) => createLsTool(GUEST_WORKSPACE, { operations: createGondolinLsOps(vm, localCwd) }).execute(...call)));
38
+ pi.registerTool(routeToGuest(createFindTool(localCwd), guest, (vm, ...call) => createFindTool(GUEST_WORKSPACE, { operations: createGondolinFindOps(vm, localCwd) }).execute(...call)));
39
+ pi.registerTool(routeToGuest(createGrepTool(localCwd), guest, (vm, _id, params, signal) => executeGondolinGrep(vm, localCwd, params, signal)));
40
+ }
@@ -0,0 +1,62 @@
1
+ import * as path from 'node:path';
2
+
3
+ import { RealFSProvider, VM } from '@earendil-works/gondolin';
4
+ import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
5
+ import { GUEST_WORKSPACE } from './paths.ts';
6
+
7
+ export const STATUS_KEY = 'gondolin';
8
+ const DEFAULT_SHELL = '/bin/sh';
9
+ const BASH_PROBE = [DEFAULT_SHELL, '-lc', 'command -v bash || true'];
10
+ const SHORT_ID_LENGTH = 8;
11
+
12
+ /** The session's one VM, started on first use and shared by every tool call until shutdown. */
13
+ export type GondolinVm = {
14
+ ensure: (ctx?: ExtensionContext) => Promise<VM>;
15
+ close: (ctx: ExtensionContext) => Promise<void>;
16
+ shellPath: () => string;
17
+ };
18
+
19
+ export function createGondolinVm(localCwd: string): GondolinVm {
20
+ let vm: VM | undefined;
21
+ let starting: Promise<VM> | undefined;
22
+ // Commands run in bash when the guest image has it, and in the POSIX shell otherwise.
23
+ let shellPath = DEFAULT_SHELL;
24
+
25
+ const start = async (ctx?: ExtensionContext): Promise<VM> => {
26
+ ctx?.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg('accent', `Gondolin: starting ${GUEST_WORKSPACE}`));
27
+ const created = await VM.create({
28
+ sessionLabel: `pi ${path.basename(localCwd)}`,
29
+ vfs: { mounts: { [GUEST_WORKSPACE]: new RealFSProvider(localCwd) } },
30
+ });
31
+ const bashProbe = await created.exec(BASH_PROBE);
32
+ shellPath = bashProbe.stdout.trim() || DEFAULT_SHELL;
33
+ vm = created;
34
+ ctx?.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg('accent', `Gondolin: ${created.id.slice(0, SHORT_ID_LENGTH)} (${GUEST_WORKSPACE})`));
35
+ ctx?.ui.notify(`Gondolin VM ready. ${localCwd} is mounted at ${GUEST_WORKSPACE}.`, 'info');
36
+ return created;
37
+ };
38
+
39
+ // Concurrent callers share one start, so a burst of tool calls at session start boots a single VM.
40
+ const ensure = async (ctx?: ExtensionContext): Promise<VM> => {
41
+ if (vm) return vm;
42
+ starting ??= start(ctx).finally(() => {
43
+ starting = undefined;
44
+ });
45
+ return starting;
46
+ };
47
+
48
+ const close = async (ctx: ExtensionContext): Promise<void> => {
49
+ const activeVm = vm;
50
+ vm = undefined;
51
+ starting = undefined;
52
+ if (!activeVm) return;
53
+ ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg('muted', 'Gondolin: stopping'));
54
+ try {
55
+ await activeVm.close();
56
+ } finally {
57
+ ctx.ui.setStatus(STATUS_KEY, undefined);
58
+ }
59
+ };
60
+
61
+ return { ensure, close, shellPath: () => shellPath };
62
+ }
package/src/index.ts CHANGED
@@ -1,53 +1,36 @@
1
1
  import { spawnSync } from 'node:child_process';
2
- import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
2
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
3
3
  import { dirname, join, resolve } from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
 
6
6
  import { type ExtensionAPI, type ExtensionContext, getAgentDir, stripFrontmatter } from '@earendil-works/pi-coding-agent';
7
7
  import { Type } from 'typebox';
8
8
  import { z } from 'zod';
9
- import { jobAgentDir, makeJobAgentDir, syncTokens } from './credentials.ts';
10
- import { gitPath, projectPath, protectedPaths } from './git.ts';
11
- import { hostEnv } from './host-env.ts';
12
- import { claimWake, clip, excerpt, exitPath, type Job, type JobSpec, launch, list, newJobId, outputPath, read, request, stop, tail, tmuxSocket } from './jobs.ts';
13
- import { within } from './paths.ts';
14
- import { serveRequests, sweepFor } from './requests.ts';
15
- import { JOB_DIR_ENV, SANDBOX_ENV, type SandboxPolicy, sandboxed, TOP_DIR_ENV } from './sandbox.ts';
16
- import { workerReport } from './transcript.ts';
9
+ import { claimWake, exitPath, type Job, type JobSpec, launch, list, newJobId, outputPath, read, stop, tail, tmuxSocket } from './jobs.ts';
17
10
 
18
11
  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
19
12
  const POLL_MS = 2000;
20
13
  const SECONDS_PER_MINUTE = 60;
21
14
  const MS_PER_SECOND = 1000;
22
- const STDERR_TAIL_LINES = 40;
23
15
  const RAW_OUTPUT_TAIL_LINES = 60;
24
16
  const DEFAULT_OUTPUT_LINES = 80;
25
17
  const DEFAULT_WAIT_SECONDS = 300;
26
- const REPORT_LIMIT = 20000;
27
- // A report's first lines hold its verdict, so they are kept ahead of the end when a report is cut.
28
- const REPORT_HEAD = 4000;
29
18
 
30
19
  export const modelsFile = (agentDir: string): string => join(agentDir, 'pstack-v2-models.md');
31
- const insideJob = (): boolean => hostEnv()[SANDBOX_ENV] === '1';
32
- const topJobsRoot = (): string => join(getAgentDir(), 'pstack-v2', 'jobs');
33
- // A sandboxed worker can write only inside its own job directory's `nested/`, so the jobs it starts live there.
34
- const jobsRoot = (env: Readonly<Record<string, string | undefined>> = hostEnv()): string => {
35
- const parent = env[JOB_DIR_ENV];
36
- return env[SANDBOX_ENV] === '1' && parent ? join(parent, 'nested') : topJobsRoot();
37
- };
20
+ const jobsRoot = (): string => join(getAgentDir(), 'pstack-v2', 'jobs');
38
21
  // A plain string enum, which every provider accepts, typed for TypeBox inference.
39
22
  const stringEnum = <T extends readonly string[]>(values: T, description?: string) => Type.Unsafe<T[number]>({ type: 'string', enum: [...values], ...(description ? { description } : {}) });
40
23
  const tmuxRunParameters = Type.Object({
41
24
  name: Type.String({ description: 'Short label, such as "watch-pr-123" or "dev-server".' }),
42
25
  command: Type.String({ description: 'Shell command, run with bash -c.' }),
43
- cwd: Type.Optional(Type.String({ description: 'Working directory inside this project. Default this session cwd. The command may write only here, in its git directory, and in temp directories.' })),
26
+ cwd: Type.Optional(Type.String({ description: 'Working directory, relative to this session cwd. Default this session cwd.' })),
44
27
  wake: Type.Optional(Type.String({ description: 'Message to wake this session with when the command exits. Omit for a server you will stop yourself.' })),
45
28
  repeat: Type.Optional(Type.Boolean({ description: 'Restart the command after each clean exit and wake each time. Requires wake. Stop it with tmux_jobs stop.' })),
46
29
  });
47
30
  const tmuxJobsParameters = Type.Object({
48
31
  action: stringEnum(['list', 'output', 'wait', 'stop'] as const),
49
32
  ids: Type.Optional(Type.Array(Type.String(), { description: 'Job ids. Required for output and stop.' })),
50
- lines: Type.Optional(Type.Number({ description: 'Lines for raw output. Exited Pi workers show their completed answers instead. Default 80.' })),
33
+ lines: Type.Optional(Type.Number({ description: 'Lines of output. Default 80.' })),
51
34
  timeout_seconds: Type.Optional(Type.Number({ description: 'Longest wait. Default 300.' })),
52
35
  });
53
36
  // Mirror the TypeBox parameters, which Pi checks before a tool runs, so these accept exactly the calls that reach it.
@@ -67,9 +50,6 @@ const modeSection = (name: string): string => {
67
50
  const file = join(skillsDir, name, 'SKILL.md');
68
51
  return `The user turned on ${name} mode with /pstack-mode. Follow this skill on every turn until the user turns it off with /pstack-mode off or switches modes. Do not drift back to default agent behavior.\n\n<skill name="${name}" location="${file}">\nReferences are relative to ${dirname(file)}.\n\n${stripFrontmatter(readFileSync(file, 'utf8')).trim()}\n</skill>`;
69
52
  };
70
- const SANDBOX_NOTE =
71
- 'You run in the pstack sandbox. The shared /tmp, macOS per-user temp directory, and user caches are read-only. Keep temp files in $TMPDIR, your own temp directory. Chromium uses the same private directory through MAC_CHROMIUM_TMPDIR. Tools that ignore both variables cannot write shared temp files. `ps` and `top` are refused, so read the load with `uptime`. In a checkout you cannot write, a bash here-document fails, so `cd "$TMPDIR"` first or write the file with printf. Unix sockets are refused, so ssh-agent, gpg-agent, and git over SSH with agent-held keys fail: use an HTTPS remote (`gh auth setup-git`) or leave the push to the session that started you. Code that runs outside the sandbox later stays read-only: `.git/hooks` and git config, `.pi` extensions and settings, and editor and harness configuration (`.vscode`, `.idea`, `*.code-workspace`, `.cursorignore`, and `.cursor` and `.claude` apart from their rules, commands, worktrees, skills, and agents). Any such file you create anyway moves to quarantine when your job ends.';
72
- const flagValue = (command: string[], flag: string): string | undefined => (command.includes(flag) ? command[command.indexOf(flag) + 1] : undefined);
73
53
 
74
54
  const duration = (ms: number): string => {
75
55
  const seconds = Math.max(0, Math.round(ms / MS_PER_SECOND));
@@ -77,65 +57,18 @@ const duration = (ms: number): string => {
77
57
  };
78
58
 
79
59
  function report(job: Job): string {
80
- const output = outputPath(job.spec.out);
81
- const transcript = job.spec.kind === 'pi' ? workerReport(flagValue(job.spec.command, '--session-dir'), job.spec.createdAt) : undefined;
82
- // The run's duration and tool-call count show at a glance a worker that spun or did nothing.
83
- const exit = exitPath(job.spec.out);
84
- const took = [existsSync(exit) ? duration(statSync(exit).mtimeMs - Date.parse(job.spec.createdAt)) : '', transcript ? `${transcript.toolCalls} tool calls` : ''].filter(Boolean).join(', ');
85
- const state = `${job.status.state === 'exited' ? `exited with code ${job.status.code}` : 'was lost (its tmux session ended without an exit code)'}${took ? ` (${took})` : ''}`;
86
- const answers = transcript?.answers ?? [];
87
- const body =
88
- answers.length && transcript
89
- ? clip(answers.join('\n\n[Later completed answer]\n\n'), REPORT_HEAD, REPORT_LIMIT - REPORT_HEAD, transcript.path)
90
- : job.spec.kind === 'pi'
91
- ? excerpt(output, REPORT_HEAD, REPORT_LIMIT - REPORT_HEAD)
92
- : tail(output, RAW_OUTPUT_TAIL_LINES);
93
- // A worker that fails at startup, such as on a bad model or credential, says why only on stderr.
94
- const failed = job.status.state !== 'exited' || job.status.code !== 0 || !body.trim();
95
- const errors = failed ? tail(join(job.spec.out, 'stderr.log'), STDERR_TAIL_LINES).trim() : '';
96
- return [
97
- `tmux job ${job.spec.name} (${job.spec.id}) ${state}. Raw output: ${output}`,
98
- transcript ? `Transcript: ${transcript.path}` : '',
99
- job.spec.wake ?? '',
100
- job.spec.kind === 'pi' && !answers.length ? '[No completed transcript answers available; showing raw stdout.]' : '',
101
- `<output>\n${body.trim()}\n</output>`,
102
- errors ? `<stderr>\n${errors}\n</stderr>` : '',
103
- ]
60
+ const exit = exitPath(job.dir);
61
+ const took = existsSync(exit) ? ` (${duration(statSync(exit).mtimeMs - Date.parse(job.spec.createdAt))})` : '';
62
+ const state = job.status.state === 'exited' ? `exited with code ${job.status.code}` : 'was lost (its tmux session ended without an exit code)';
63
+ return [`tmux job ${job.spec.name} (${job.spec.id}) ${state}${took}. Raw output: ${outputPath(job.dir)}`, job.spec.wake ?? '', `<output>\n${tail(outputPath(job.dir), RAW_OUTPUT_TAIL_LINES).trim()}\n</output>`]
104
64
  .filter(Boolean)
105
65
  .join('\n\n');
106
66
  }
107
67
 
108
68
  function describe(job: Job): string {
109
69
  const state = job.status.state === 'exited' ? `exited ${job.status.code}` : job.status.state;
110
- const attach = job.spec.socket && job.status.state === 'running' ? `\n attach: tmux -S ${job.spec.socket} attach -t ${job.spec.id}` : '';
111
- return `${job.spec.id} ${job.spec.kind} ${state} ${job.spec.name}\n follow: tail -f ${outputPath(job.spec.out)}${attach}`;
112
- }
113
-
114
- // A sandboxed worker asks the root Pi to launch for it on every platform, so nested jobs get the same sandbox everywhere
115
- // and no job needs a tmux server of its own. macOS could not apply a second Seatbelt profile anyway.
116
- const brokering = (): boolean => insideJob();
117
-
118
- /** Starts a job under its own sandbox, or writes it as a request for the root Pi when this process cannot. */
119
- function start(root: string, spec: JobSpec, files: Record<string, string> = {}, resolved: Record<string, string> = {}): Job {
120
- const jobDir = join(root, spec.id);
121
- // A job started from inside another uses its top-level job's agent directory, which that start already created.
122
- const top = insideJob() ? (hostEnv()[TOP_DIR_ENV] ?? jobDir) : jobDir;
123
- if (!insideJob()) makeJobAgentDir(getAgentDir(), jobAgentDir(jobDir), resolved);
124
- // Every job gets a private temp directory, since the shared ones hold code unsandboxed programs load, and writes
125
- // credentials only to its top-level job's copy.
126
- // A command a worker starts shares the worker's temp directory, so a path the worker hands it under $TMPDIR exists for both.
127
- const parent = hostEnv()[JOB_DIR_ENV];
128
- const tmp = insideJob() && parent && spec.kind === 'command' ? join(parent, 'tmp') : undefined;
129
- const sized: SandboxPolicy = { ...spec.policy, jobDir, credentials: jobAgentDir(top), writable: [...new Set([...spec.policy.writable, join(jobDir, 'tmp'), ...(tmp ? [tmp] : [])])] };
130
- // A writable path that holds Pi's agent directory would let the job rewrite Pi's own code and settings.
131
- const holder = sized.writable.find((path) => within(sized.agentDir, [path]));
132
- if (holder) throw new Error(`pstack will not let a job write ${holder}, because it contains Pi's agent directory ${sized.agentDir}. Run Pi from a project directory.`);
133
- spec = { ...spec, sweep: sweepFor(sized), ...(tmp ? { tmp } : {}) };
134
- const policy: SandboxPolicy = { ...sized, checkouts: spec.sweep.roots };
135
- // bubblewrap binds only paths that exist, so the private temp directory exists before the sandbox is built.
136
- mkdirSync(join(jobDir, 'tmp'), { recursive: true });
137
- if (brokering()) return request(root, { ...spec, policy }, files);
138
- return launch(root, { ...spec, policy, argv: sandboxed(spec.command, policy) }, files);
70
+ const attach = job.status.state === 'running' ? `\n attach: tmux -S ${job.spec.socket} attach -t ${job.spec.id}` : '';
71
+ return `${job.spec.id} ${state} ${job.spec.name}\n follow: tail -f ${outputPath(job.dir)}${attach}`;
139
72
  }
140
73
 
141
74
  type Waiter = { signal: AbortSignal | undefined; update: ((partial: ReturnType<typeof text>) => void) | undefined; ctx: ExtensionContext };
@@ -149,7 +82,7 @@ async function blockWhileRunning(current: () => Job[], deadline: number, { signa
149
82
  }
150
83
  }
151
84
 
152
- const outputOf = (job: Job, lines: number): string => (job.spec.kind === 'pi' && job.status.state !== 'running' ? report(job) : `${describe(job)}\n${tail(outputPath(job.spec.out), lines)}`);
85
+ const outputOf = (job: Job, lines: number): string => `${describe(job)}\n${tail(outputPath(job.dir), lines)}`;
153
86
 
154
87
  /** A heartbeat or a server never stops on its own, so waiting on everything leaves them out. */
155
88
  const waitableIds = (root: string, owner: string): string[] =>
@@ -224,15 +157,20 @@ const finish = (state: PstackState, job: Job): string => {
224
157
  if (job.status.state !== 'exited' || job.status.code !== 0) return `${report(job)}\n\nThis heartbeat did not exit cleanly, so it was not restarted.`;
225
158
  try {
226
159
  if (state.stoppedSeries().has(job.spec.series)) return report(job);
227
- // The next run gets its own temp directory in place of this one's.
228
- const policy = { ...job.spec.policy, writable: job.spec.policy.writable.filter((path) => path !== join(job.dir, 'tmp')) };
229
- start(jobsRoot(), { ...job.spec, policy, id: newJobId(job.spec.name), brokered: false, createdAt: new Date().toISOString() });
160
+ launch(jobsRoot(), { ...job.spec, id: newJobId(job.spec.name), createdAt: new Date().toISOString() });
230
161
  return report(job);
231
162
  } catch (error) {
232
163
  return `${report(job)}\n\nThis heartbeat could not be restarted: ${error instanceof Error ? error.message : String(error)}`;
233
164
  }
234
165
  };
235
166
 
167
+ /** The job's directory, from the model's cwd, which tmux needs to exist. */
168
+ function workingDir(base: string, cwd: string | undefined): string {
169
+ const dir = resolve(base, cwd ?? '.');
170
+ if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`cwd ${dir} is not a directory.`);
171
+ return dir;
172
+ }
173
+
236
174
  const interactive = (ctx: ExtensionContext): boolean => ctx.mode === 'tui' || ctx.mode === 'rpc';
237
175
 
238
176
  const deliverFinished = (pi: ExtensionAPI, state: PstackState, ctx: ExtensionContext): void => {
@@ -247,31 +185,12 @@ const deliverFinished = (pi: ExtensionAPI, state: PstackState, ctx: ExtensionCon
247
185
  }
248
186
  };
249
187
 
250
- const serve = (ctx: ExtensionContext): void => {
251
- if (brokering()) return;
252
- const owner = ctx.sessionManager.getSessionId();
253
- for (const top of list(jobsRoot(), owner)) if (top.spec.kind === 'pi') serveRequests(top, tmuxSocket(owner), join(top.dir, 'nested'), top.status.state !== 'running');
254
- };
255
-
256
- // Carries refreshed OAuth tokens between your credentials and each top-level job's copy, once more after the job ends.
257
- const syncCredentials = (ctx: ExtensionContext): void => {
258
- if (insideJob()) return;
259
- for (const job of list(jobsRoot(), ctx.sessionManager.getSessionId())) {
260
- const copy = jobAgentDir(job.dir);
261
- if (!existsSync(join(copy, 'auth.json')) || existsSync(join(job.dir, 'tokens-synced'))) continue;
262
- if (syncTokens(getAgentDir(), copy) && job.status.state !== 'running') writeFileSync(join(job.dir, 'tokens-synced'), '');
263
- }
264
- };
265
-
266
- // Each step runs on its own, so one failing does not stop the others.
267
188
  const tick = (pi: ExtensionAPI, state: PstackState, ctx: ExtensionContext): void => {
268
- const deliverable = interactive(ctx) || (!state.settling() && !ctx.isIdle());
269
- for (const step of [() => syncCredentials(ctx), () => serve(ctx), () => deliverable && deliverFinished(pi, state, ctx)]) {
270
- try {
271
- step();
272
- } catch (error) {
273
- if (ctx.hasUI) ctx.ui.notify(`pstack job watcher: ${error instanceof Error ? error.message : String(error)}`, 'error');
274
- }
189
+ if (!interactive(ctx) && (state.settling() || ctx.isIdle())) return;
190
+ try {
191
+ deliverFinished(pi, state, ctx);
192
+ } catch (error) {
193
+ if (ctx.hasUI) ctx.ui.notify(`pstack job watcher: ${error instanceof Error ? error.message : String(error)}`, 'error');
275
194
  }
276
195
  };
277
196
 
@@ -304,7 +223,6 @@ function registerWatcher(pi: ExtensionAPI, state: PstackState): void {
304
223
  state.setSettling(true);
305
224
  try {
306
225
  while (pending().some((job) => job.status.state === 'running')) await new Promise((done) => setTimeout(done, POLL_MS));
307
- syncCredentials(ctx);
308
226
  const finished = pending().filter(claimWake);
309
227
  return {
310
228
  entries: [...event.entries, ...finished.map((job) => ({ type: 'custom_message' as const, customType: 'pstack-job', content: finish(state, job), display: true }))],
@@ -357,9 +275,8 @@ function promptSections(transcript: string | undefined, mode: string | undefined
357
275
  const models = modelsFile(getAgentDir());
358
276
  return {
359
277
  ...(transcript && {
360
- 'pstack-session': `This session's transcript is ${transcript}. A worker's Pi agent directory is its job's own, so it cannot find this file by itself. Put the path in any brief that asks a worker to read the transcript.`,
278
+ 'pstack-session': `This session's transcript is ${transcript}. A worker cannot find this file by itself, so put the path in any brief that asks a worker to read the transcript.`,
361
279
  }),
362
- ...(insideJob() && { 'pstack-sandbox': SANDBOX_NOTE }),
363
280
  ...(mode && { [MODE]: modeSection(mode) }),
364
281
  ...(existsSync(models) && { 'pstack-models': `Role lines from ${models}, written by /skill:setup-pstack:\n${readFileSync(models, 'utf8').trim()}` }),
365
282
  };
@@ -383,7 +300,7 @@ function registerTmuxRun(pi: ExtensionAPI): void {
383
300
  name: 'tmux_run',
384
301
  label: 'Run in tmux',
385
302
  description:
386
- 'Run a shell command in its own tmux session, inside the pstack sandbox, instead of a background shell. Use it for watchers, dev servers, long builds, and heartbeat timers. With wake set, you are woken with that message and the output tail when the command exits. With repeat, the command restarts each time it exits cleanly, so `sleep 3600` plus a wake message is an hourly tick. The shared /tmp is read-only to the command, so it keeps temp files in $TMPDIR, its own temp directory. The command reads no input.',
303
+ 'Run a shell command in its own tmux session instead of a background shell. Use it for watchers, dev servers, long builds, and heartbeat timers. With wake set, you are woken with that message and the output tail when the command exits. With repeat, the command restarts each time it exits cleanly, so `sleep 3600` plus a wake message is an hourly tick. The command reads no input.',
387
304
  promptSnippet: 'Run a long-lived or watched command in tmux and get woken when it exits',
388
305
  promptGuidelines: ['Use tmux_run for any command that would otherwise run in the background. Never background a command with &, nohup, setsid, or disown.'],
389
306
  parameters: tmuxRunParameters,
@@ -391,37 +308,21 @@ function registerTmuxRun(pi: ExtensionAPI): void {
391
308
  TmuxRunParamsSchema.parse(params);
392
309
  const input = params;
393
310
  if (input.repeat && input.wake === undefined) throw new Error('repeat needs a wake message, or nothing would ever notice the ticks.');
394
- const root = jobsRoot();
395
- const id = newJobId(input.name);
396
311
  const owner = ctx.sessionManager.getSessionId();
397
- const cwd = projectPath(ctx, input.cwd);
398
- const common = gitPath(cwd, '--git-common-dir');
399
- const guarded = protectedPaths(cwd, common);
400
- const policy = { writable: [cwd, ...(common ? [common] : [])], protect: guarded.protect, lock: guarded.lock, gitDirs: guarded.gitDirs, checkouts: [], credentials: '', agentDir: getAgentDir(), jobDir: join(root, id) };
312
+ const id = newJobId(input.name);
401
313
  const spec: JobSpec = {
402
314
  id,
403
315
  name: input.name,
404
- kind: 'command',
405
- cwd,
406
- argv: [],
316
+ cwd: workingDir(ctx.cwd, input.cwd),
407
317
  command: ['bash', '-c', input.command],
408
- policy,
409
- brokered: false,
410
318
  owner,
411
319
  wake: input.wake ?? null,
412
320
  repeat: input.repeat ?? false,
413
321
  series: id,
414
- socket: brokering() ? '' : tmuxSocket(owner),
415
- sweep: { roots: [], protect: [] },
416
- out: join(root, id),
322
+ socket: tmuxSocket(owner),
417
323
  createdAt: new Date().toISOString(),
418
324
  };
419
- try {
420
- return text(`Started ${describe(start(root, spec))}`);
421
- } catch (error) {
422
- rmSync(join(root, id), { recursive: true, force: true });
423
- throw error;
424
- }
325
+ return text(`Started ${describe(launch(jobsRoot(), spec))}`);
425
326
  },
426
327
  });
427
328
  }