@justjoshn/pi-pstack 0.15.36-pi.14 → 0.15.36-pi.15

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.15.36-pi.15] - 2026-11-04
+
+- Match watched shell output before a newline or process exit. Count every occurrence within a chunk and retain matches across chunk boundaries.
+- Match the captured observer's batching, minimum debounce, completion flush, and 100-occurrence limit notice.
+- Decode stdout and stderr independently so split UTF-8 characters reach the output file and monitor intact.
+- Pin `re2js` 1.2.2 for output-watch patterns. Invalid patterns warn without stopping the command. A missing dependency leaves unrelated tools available but rejects a valid requested watch before the command runs.
+- Record the pinned reference, original-component comparisons, and open requirements in `parity/pstack-full-parity-2026-11-04/`. Whole-plugin parity remains `NOT VERIFIED`.
+
 ## [0.15.36-pi.14] - 2026-11-04
 
 Each item below was checked against Cursor CLI 2026.10.22 with pstack and cursor-team-kit loaded, through live captures. `parity/pstack-native-parity-2026-11-04/` in the repository records the evidence and the decisions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justjoshn/pi-pstack",
-  "version": "0.15.36-pi.14",
+  "version": "0.15.36-pi.15",
   "description": "pstack 0.15.36 for Pi with its soft-dependency team-kit skills vendored in: rigorous agent workflows and principles as Pi skills, with the host features they use: subagents, todos, modes, plan mode, the model rule, /loop, subscriptions and routines, AskQuestion, SwitchMode, image generation, and visualize",
   "type": "module",
   "license": "MIT",
@@ -65,6 +65,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.79",
+    "re2js": "1.2.2",
     "yaml": "2.9.0"
   },
   "peerDependencies": {

package/src/background-shell.ts

@@ -5,12 +5,14 @@ import { type ChildProcess, spawn } from 'node:child_process';
 import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, statSync, writeSync } from 'node:fs';
 import { constants } from 'node:os';
 import { join, resolve } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
 
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { getShellConfig, truncateTail } from '@earendil-works/pi-coding-agent';
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
 import { isOneShot } from './modes.ts';
+import { OutputWatchDependencyError, type OutputWatchRequest, ShellOutputWatch } from './shell-output-watch.ts';
 
 export const SHELL_NOTICE_TYPE = 'pstack/shell';
 const BACKGROUND_TOOL = 'bash_background';
@@ -18,7 +20,6 @@ const AWAIT_TOOL = 'AwaitShell';
 
 const FIELD_WIDTH = 9;
 const HEADER_REFRESH_MS = 5_000;
-const MIN_DEBOUNCE_MS = 5_000;
 const DEFAULT_AWAIT_MS = 30_000;
 const MAX_AWAIT_MS = 7_140_000;
 const KILL_GRACE_MS = 2_000;
@@ -27,20 +28,6 @@ const FOLLOW_UP = 'Briefly inform the user about the task result and perform any
 type JobStatus = 'running' | 'succeeded' | 'failed' | 'aborted';
 type NoticeStatus = 'success' | 'error' | 'aborted';
 
-interface OutputWatch {
-  readonly regex: RegExp;
-  readonly source: string;
-  readonly reason: string;
-  readonly debounceMs: number;
-  occurrences: number;
-  /** Matches since the last notification, sent when the debounce window closes. */
-  unreported: number;
-  latest: string;
-  notices: number;
-  window: ReturnType<typeof setTimeout> | undefined;
-  partial: string;
-}
-
 interface ShellJob {
   readonly id: string;
   readonly pid: number;
@@ -55,7 +42,7 @@ interface ShellJob {
   readonly statusOffset: number;
   readonly runningOffset: number;
   readonly child: ChildProcess;
-  readonly watch: OutputWatch | undefined;
+  readonly watch: ShellOutputWatch | undefined;
   readonly listeners: Set<() => void>;
   readonly done: Promise<void>;
   /** Where the next output byte goes; the header is rewritten in place, so the file is never opened for append. */
@@ -145,9 +132,6 @@ export function noticeText(notice: ShellNotice): string {
   ].join('\n');
 }
 
-const firstMatchDetail = (watch: OutputWatch) => `Shell output has pattern /${watch.source}/. This is occurrence number ${watch.occurrences}. Matched text: ${watch.latest}. The title message is being displayed to the user.`;
-const laterMatchesDetail = (watch: OutputWatch) => `Shell output matched /${watch.source}/ ${watch.unreported} more times since the previous notification. The title message is being displayed to the user. Latest match: ${watch.latest}.`;
-
 function exitStatus(code: number | null, signal: NodeJS.Signals | null): { status: JobStatus; exitCode: number } {
   if (signal !== null) return { status: 'aborted', exitCode: 128 + (constants.signals[signal] ?? 0) };
   const exitCode = code ?? 1;
@@ -215,7 +199,7 @@ export interface StartRequest {
   cwd: string;
   title: string;
   toolCallId: string;
-  watch?: { pattern: string; reason: string; debounceMs?: number };
+  watch?: OutputWatchRequest;
 }
 
 /** Every background shell this runtime started, and the notifications they owe the agent. */
@@ -245,50 +229,6 @@ export function createShellJobs(options: ShellJobsOptions, deliver: (notice: She
     for (const listener of [...job.listeners]) listener();
   };
 
-  const sendProgress = (job: ShellJob, watch: OutputWatch, detail: string) => {
-    watch.notices += 1;
-    deliver({ kind: 'progress', status: 'success', taskId: `${job.id}:task_progress:${watch.notices}`, shellId: job.id, title: watch.reason, toolCallId: job.toolCallId, detail, outputPath: job.path });
-  };
-  /** Trailing-edge debounce: the first match notifies at once, later ones in the window are counted and sent when it closes. */
-  const openWindow = (job: ShellJob, watch: OutputWatch) => {
-    watch.window = setTimeout(() => {
-      watch.window = undefined;
-      if (watch.unreported === 0) return;
-      sendProgress(job, watch, laterMatchesDetail(watch));
-      watch.unreported = 0;
-      openWindow(job, watch);
-    }, watch.debounceMs);
-    watch.window.unref();
-  };
-  const matchLine = (job: ShellJob, watch: OutputWatch, line: string) => {
-    const match = watch.regex.exec(line);
-    if (match === null) return;
-    watch.occurrences += 1;
-    watch.latest = match[0];
-    if (watch.window !== undefined) {
-      watch.unreported += 1;
-      return;
-    }
-    sendProgress(job, watch, firstMatchDetail(watch));
-    openWindow(job, watch);
-  };
-  const scan = (job: ShellJob, chunk: string, final: boolean) => {
-    const watch = job.watch;
-    if (watch === undefined) return;
-    const lines = (watch.partial + chunk).split('\n');
-    watch.partial = final ? '' : (lines.pop() ?? '');
-    for (const line of lines) if (line !== '' || final) matchLine(job, watch, line.replace(/\r$/, ''));
-  };
-  const flushWatch = (job: ShellJob) => {
-    const watch = job.watch;
-    if (watch === undefined) return;
-    scan(job, '', true);
-    if (watch.window !== undefined) clearTimeout(watch.window);
-    watch.window = undefined;
-    if (watch.unreported > 0) sendProgress(job, watch, laterMatchesDetail(watch));
-    watch.unreported = 0;
-  };
-
   const finish = (job: ShellJob, status: JobStatus, exitCode: number, announce: boolean) => {
     if (job.status !== 'running') return;
     const endedAt = Date.now();
@@ -299,8 +239,8 @@ export function createShellJobs(options: ShellJobsOptions, deliver: (notice: She
     job.bodyEnd = job.size;
     append(job, terminalFooter(exitCode, endedAt - job.startedAt, endedAt));
     closeSync(job.fd);
+    job.watch?.finish(announce);
     if (announce) {
-      flushWatch(job);
       if (!job.observed) {
         const noticeStatus: NoticeStatus = status === 'succeeded' ? 'success' : status === 'failed' ? 'error' : 'aborted';
         deliver({
@@ -313,17 +253,27 @@ export function createShellJobs(options: ShellJobsOptions, deliver: (notice: She
           ...(noticeStatus === 'error' ? { detail: `exit_code=${exitCode}` } : {}),
         });
       }
-    } else if (job.watch?.window !== undefined) clearTimeout(job.watch.window);
+    }
     notify(job);
   };
 
   const start = (ctx: ExtensionContext, request: StartRequest): ShellJob => {
     if (!existsSync(request.cwd) || !statSync(request.cwd).isDirectory()) throw new Error(`Working directory ${request.cwd} does not exist.`);
-    const watchRegex = request.watch === undefined ? undefined : compile(request.watch.pattern);
     const dir = options.terminalsDir(ctx);
     mkdirSync(dir, { recursive: true });
     const id = allocateId(dir);
     const path = join(dir, `${id}.txt`);
+    let watch: ShellOutputWatch | undefined;
+    if (request.watch !== undefined && request.watch.pattern.trim() !== '') {
+      try {
+        watch = new ShellOutputWatch(request.watch, (notice) => {
+          deliver({ kind: 'progress', status: 'success', taskId: `${id}:task_progress:${notice.sequence}`, shellId: id, title: notice.title, toolCallId: request.toolCallId, detail: notice.detail, outputPath: path });
+        });
+      } catch (error) {
+        if (error instanceof OutputWatchDependencyError) throw error;
+        console.warn('Invalid shell output notification pattern', { shellId: id, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
     const config = getShellConfig(options.shellPath());
     const viaStdin = config.commandTransport === 'stdin';
     const child = spawn(config.shell, viaStdin ? config.args : [...config.args, request.command], {
@@ -357,21 +307,7 @@ export function createShellJobs(options: ShellJobsOptions, deliver: (notice: She
       statusOffset: header.statusOffset,
       runningOffset: header.runningOffset,
       child,
-      watch:
-        request.watch === undefined || watchRegex === undefined
-          ? undefined
-          : {
-              regex: watchRegex,
-              source: request.watch.pattern,
-              reason: request.watch.reason,
-              debounceMs: Math.max(MIN_DEBOUNCE_MS, request.watch.debounceMs ?? MIN_DEBOUNCE_MS),
-              occurrences: 0,
-              unreported: 0,
-              latest: '',
-              notices: 0,
-              window: undefined,
-              partial: '',
-            },
+      watch,
       listeners: new Set(),
       done: new Promise<void>((resolveDone) => {
         release = resolveDone;
@@ -388,14 +324,24 @@ export function createShellJobs(options: ShellJobsOptions, deliver: (notice: She
     append(job, header.text);
     job.refresh = setInterval(() => refreshRunning(job), HEADER_REFRESH_MS);
     job.refresh.unref();
-    const onData = (chunk: Buffer) => {
-      if (job.status !== 'running') return;
-      append(job, chunk);
-      scan(job, chunk.toString('utf8'), false);
-      notify(job);
-    };
-    child.stdout?.on('data', onData);
-    child.stderr?.on('data', onData);
+    for (const stream of [child.stdout, child.stderr]) {
+      if (stream === null) continue;
+      const decoder = new StringDecoder('utf8');
+      stream.on('data', (chunk: Buffer) => {
+        if (job.status !== 'running') return;
+        const text = decoder.write(chunk);
+        append(job, text);
+        job.watch?.observe(text);
+        notify(job);
+      });
+      stream.on('end', () => {
+        if (job.status !== 'running') return;
+        const text = decoder.end();
+        append(job, text);
+        job.watch?.observe(text);
+        notify(job);
+      });
+    }
     child.on('error', (error) => {
       if (job.status === 'running') append(job, `${error.message}\n`);
       finish(job, 'failed', 127, true);

package/src/shell-output-watch.ts

@@ -0,0 +1,126 @@
+import { createRequire } from 'node:module';
+
+import type { RE2JS } from 're2js';
+
+const require = createRequire(import.meta.url);
+let regexEngine: typeof RE2JS | undefined;
+try {
+  regexEngine = (require('re2js') as { RE2JS: typeof RE2JS }).RE2JS;
+} catch {}
+
+export class OutputWatchDependencyError extends Error {}
+
+export interface OutputWatchRequest {
+  pattern: string;
+  reason: string;
+  debounceMs?: number;
+}
+
+export interface OutputMatchNotice {
+  sequence: number;
+  title: string;
+  detail: string;
+}
+
+interface MatchBatch {
+  start: number;
+  count: number;
+  matchedText: string;
+}
+
+const MATCH_LIMIT = 100;
+const MAX_CHUNK = 65_536;
+const MIN_DEBOUNCE_MS = 5_000;
+
+export class ShellOutputWatch {
+  private readonly request: OutputWatchRequest;
+  private readonly notify: (notice: OutputMatchNotice) => void;
+  private readonly regex: RE2JS;
+  private readonly title: string;
+  private readonly debounceMs: number;
+  private state: 'watching' | 'limited' | 'finished' = 'watching';
+  private carryover = '';
+  private occurrences = 0;
+  private notices = 0;
+  private batch: MatchBatch | undefined;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(request: OutputWatchRequest, notify: (notice: OutputMatchNotice) => void) {
+    this.request = request;
+    this.notify = notify;
+    if (request.pattern.length > 500) throw new Error('Output notification pattern exceeds 500 characters');
+    if (regexEngine === undefined) throw new OutputWatchDependencyError('Shell output monitoring needs the re2js dependency. Run bun install in the pi-pstack package directory, then reload Pi.');
+    this.regex = regexEngine.compile(request.pattern, regexEngine.MULTILINE);
+    const title = request.reason.trim() || `Shell output contains /${request.pattern}/`;
+    this.title = title.length <= 500 ? title : `${title.slice(0, 500)}...`;
+    this.debounceMs = Math.max(request.debounceMs ?? MIN_DEBOUNCE_MS, MIN_DEBOUNCE_MS);
+  }
+
+  observe(chunk: string): void {
+    if (this.state !== 'watching' || chunk.length === 0) return;
+    for (let offset = 0; offset < chunk.length && this.state === 'watching'; offset += MAX_CHUNK) {
+      const previous = this.carryover.length;
+      const text = this.carryover + chunk.slice(offset, offset + MAX_CHUNK);
+      const matcher = this.regex.matcher(text);
+      while (this.state === 'watching' && matcher.find()) {
+        if (matcher.end() > previous) this.match(matcher.group() ?? '');
+      }
+      this.carryover = text.slice(-1_024);
+    }
+  }
+
+  finish(announce = true): void {
+    if (this.state === 'finished') return;
+    this.state = 'finished';
+    if (announce) this.flush();
+    this.batch = undefined;
+    this.clearTimer();
+  }
+
+  private match(text: string): void {
+    this.occurrences += 1;
+    const label = this.occurrences === 1 ? 'Matched text' : 'Latest match';
+    const matchedText = text.length <= 5_000 ? `${label}: ${text}` : `${label} is ${text.length} characters; omitted from notification detail.`;
+    if (this.occurrences === 1) {
+      this.emit({ start: 1, count: 1, matchedText });
+    } else {
+      this.batch = this.batch === undefined ? { start: this.occurrences, count: 1, matchedText } : { start: this.batch.start, count: this.batch.count + 1, matchedText };
+      if (this.occurrences < MATCH_LIMIT && this.timer === undefined) {
+        this.timer = setTimeout(() => this.flush(), this.debounceMs);
+        this.timer.unref();
+      }
+    }
+    if (this.occurrences === MATCH_LIMIT) {
+      this.state = 'limited';
+      this.flush();
+      this.notices += 1;
+      this.notify({
+        sequence: this.notices,
+        title: `Notification limit reached (${MATCH_LIMIT})`,
+        detail: `Shell output matched /${this.request.pattern}/ ${MATCH_LIMIT} times and has reached the notification limit. No further notifications will be sent for this pattern. To continue monitoring, read the output file directly at the output path.`,
+      });
+    }
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== undefined) clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+
+  private flush(): void {
+    const batch = this.batch;
+    this.batch = undefined;
+    this.clearTimer();
+    if (batch !== undefined) this.emit(batch);
+  }
+
+  private emit(batch: MatchBatch): void {
+    this.notices += 1;
+    const pattern = this.request.pattern;
+    const detail =
+      batch.count === 1
+        ? `Shell output has pattern /${pattern}/. This is occurrence number ${batch.start}. ${batch.matchedText}. The title message is being displayed to the user.`
+        : `Shell output matched /${pattern}/ ${batch.count} more times since the previous notification. The title message is being displayed to the user. ${batch.matchedText}.`;
+    this.notify({ sequence: this.notices, title: this.title, detail });
+  }
+}