pi-better-harness 0.1.7 → 0.1.9

package/README.md

@@ -12,6 +12,10 @@ Use `pi-better-harness` when you want the full background-work bundle for Pi in
 
 `pi-better-read-aloud` is intentionally not included yet.
 
+## Screenshots
+
+<p><img src="https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-harness.png" alt="pi-better-harness rendered in Pi" width="49%" /><img src="https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/overview/pi-better-harness.png" alt="pi-better-harness package overview" width="49%" /></p>
+
 ## Install
 
 ```sh

package/node_modules/pi-better-background-tasks/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1aboveio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/pi-better-background-tasks/README.md

@@ -0,0 +1,57 @@
+# pi-better-background-tasks
+
+`pi-better-background-tasks` is a Pi extension for durable background shell tasks, watchers, logs, and status inspection.
+
+## Quick Answer
+
+Use `pi-better-background-tasks` when a command should keep running while the foreground Pi session stays free. It is best for dev servers, long scripts, queue watchers, deploy checks, log tails, and other command-driven work.
+
+## Screenshots
+
+<p><img src="https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-background-tasks.png" alt="pi-better-background-tasks rendered in Pi" width="49%" /><img src="https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/overview/pi-better-background-tasks.png" alt="pi-better-background-tasks package overview" width="49%" /></p>
+
+## Core Features
+
+- Start long-running commands without blocking the current turn.
+- Watch commands until success, failure, or timeout.
+- Keep task metadata and logs available across reloads.
+- Show active work in Pi's background-work navigator.
+
+## Install
+
+```sh
+pi install npm:pi-better-background-tasks
+```
+
+Try it for one run:
+
+```sh
+pi -e npm:pi-better-background-tasks
+```
+
+## When To Use
+
+Use this package for shell commands that need logs, status, cancellation, or completion notifications across a Pi turn.
+
+Do not use it for short commands where the foreground session should wait for the result directly.
+
+## Compatibility
+
+| Requirement | Support |
+|-------------|---------|
+| Pi | Required |
+| Install method | `pi install npm:pi-better-background-tasks` |
+| Development runtime | Node.js 22+ |
+
+## Update Or Remove
+
+```sh
+pi update npm:pi-better-background-tasks
+pi remove npm:pi-better-background-tasks
+```
+
+## More Detail
+
+- Repository: https://github.com/1aboveio/pi-better-harness
+- Detailed notes: https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-background-tasks/docs/usage.md
+- License: https://github.com/1aboveio/pi-better-harness/blob/main/LICENSE

package/node_modules/pi-better-background-tasks/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-better-background-tasks",
+  "version": "0.1.9",
+  "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "background-tasks",
+    "watchers"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/package-gallery/pi-better-background-tasks.png"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-background-tasks"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-background-tasks#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pretest": "node ../../scripts/sync-shared-log-utils.mjs",
+    "prepack": "node ../../scripts/sync-shared-log-utils.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run src/conditions.test.ts src/runtime.test.ts",
+    "test:e2e": "vitest run src/e2e.test.ts",
+    "test:cross-session": "vitest run src/e2e.test.ts -t \"different session\"",
+    "test:golden": "vitest run src/golden-path.test.ts",
+    "test:integration": "npm run test:e2e && npm run test:golden"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typebox": "^1.1.38",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/node_modules/pi-better-background-tasks/src/conditions.ts

@@ -0,0 +1,92 @@
+import type { CommandResult, Condition } from "./types.js";
+
+export interface ConditionMatch {
+  matched: boolean;
+  value?: unknown;
+  error?: string;
+}
+
+export function evaluateCondition(condition: Condition, result: CommandResult): ConditionMatch {
+  switch (condition.type) {
+    case "exit_code":
+      return { matched: result.exitCode === condition.equals, value: result.exitCode };
+    case "stdout_contains":
+      return { matched: result.stdout.includes(condition.value) };
+    case "stderr_contains":
+      return { matched: result.stderr.includes(condition.value) };
+    case "json_path_equals": {
+      const resolved = resolveJsonPath(result.stdout, condition.path);
+      if (!resolved.ok) return { matched: false, error: resolved.error };
+      return { matched: deepEqual(resolved.value, condition.value), value: resolved.value };
+    }
+    case "json_path_exists": {
+      const resolved = resolveJsonPath(result.stdout, condition.path);
+      return resolved.ok ? { matched: true, value: resolved.value } : { matched: false, error: resolved.error };
+    }
+  }
+}
+
+export function resolveJsonPath(jsonText: string, path: string): { ok: true; value: unknown } | { ok: false; error: string } {
+  let current: unknown;
+  try {
+    current = JSON.parse(jsonText);
+  } catch (error) {
+    return { ok: false, error: `stdout is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+
+  const tokens = parseJsonPath(path);
+  if (!tokens) return { ok: false, error: `unsupported JSON path: ${path}` };
+
+  for (const token of tokens) {
+    if (typeof token === "number") {
+      if (!Array.isArray(current) || token < 0 || token >= current.length) {
+        return { ok: false, error: `JSON path not found: ${path}` };
+      }
+      current = current[token];
+      continue;
+    }
+    if (current === null || typeof current !== "object" || !(token in current)) {
+      return { ok: false, error: `JSON path not found: ${path}` };
+    }
+    current = (current as Record<string, unknown>)[token];
+  }
+
+  return { ok: true, value: current };
+}
+
+function parseJsonPath(path: string): Array<string | number> | undefined {
+  if (!path.startsWith("$")) return undefined;
+  const tokens: Array<string | number> = [];
+  let i = 1;
+  while (i < path.length) {
+    if (path[i] === ".") {
+      i += 1;
+      const start = i;
+      while (i < path.length && /[A-Za-z0-9_$-]/.test(path[i]!)) i += 1;
+      if (i === start) return undefined;
+      tokens.push(path.slice(start, i));
+      continue;
+    }
+    if (path[i] === "[") {
+      const end = path.indexOf("]", i);
+      if (end === -1) return undefined;
+      const raw = path.slice(i + 1, end).trim();
+      const quoted = raw.match(/^['\"](.+)['\"]$/);
+      if (quoted) {
+        tokens.push(quoted[1]!);
+      } else if (/^\d+$/.test(raw)) {
+        tokens.push(Number(raw));
+      } else {
+        return undefined;
+      }
+      i = end + 1;
+      continue;
+    }
+    return undefined;
+  }
+  return tokens;
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}

package/node_modules/pi-better-background-tasks/src/goal-provider.ts

@@ -0,0 +1,116 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { listMetas } from "./registry.js";
+import type { BackgroundTaskMeta } from "./types.js";
+import { isTerminalStatus } from "./types.js";
+
+const GOAL_READY_EVENT = "pi-better-goal:ready";
+const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
+const readySubscriptions = new WeakSet<ExtensionAPI>();
+
+export interface GoalBackgroundWorkItem {
+  id: string;
+  label?: string;
+  status: string;
+  active: boolean;
+  unhealthy?: boolean;
+  terminal?: boolean;
+  attention?: boolean;
+  startedAt?: number;
+  endedAt?: number;
+  details?: Record<string, unknown>;
+}
+
+export interface GoalBackgroundProviderSnapshot {
+  providerId: string;
+  label?: string;
+  items: GoalBackgroundWorkItem[];
+}
+
+export function collectBackgroundTaskGoalActivity(
+  metas: BackgroundTaskMeta[] = listMetas(),
+  ctx?: ExtensionContext,
+  now = Date.now(),
+): GoalBackgroundProviderSnapshot {
+  return {
+    providerId: "background-tasks",
+    label: "Background Tasks",
+    items: metas
+      .filter((meta) => isVisibleGoalActivity(meta, ctx, now))
+      .map(backgroundTaskToGoalItem),
+  };
+}
+
+export function registerBackgroundTasksGoalProvider(pi: ExtensionAPI): void {
+  const emitProvider = (): void => {
+    pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
+      id: "background-tasks",
+      label: "Background Tasks",
+      getActivity: (ctx: ExtensionContext) => collectBackgroundTaskGoalActivity(listMetas(), ctx),
+    });
+  };
+
+  if (!readySubscriptions.has(pi)) {
+    pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
+    readySubscriptions.add(pi);
+  }
+  emitProvider();
+}
+
+const TERMINAL_GOAL_ACTIVITY_RETENTION_MS = 30_000;
+
+function isVisibleGoalActivity(meta: BackgroundTaskMeta, ctx: ExtensionContext | undefined, now: number): boolean {
+  if (meta.dismissedAt !== undefined) return false;
+  if (ctx && !belongsToGoalActivitySession(meta, ctx)) return false;
+  if (meta.status === "running") return true;
+  if (!ctx) return true;
+  if (typeof meta.endedAt !== "number") return true;
+  return now - meta.endedAt < TERMINAL_GOAL_ACTIVITY_RETENTION_MS;
+}
+
+function belongsToGoalActivitySession(meta: BackgroundTaskMeta, ctx: ExtensionContext): boolean {
+  const active = getGoalActivityOrigin(ctx);
+  const origin = meta.callbackOrigin;
+  if (origin) {
+    if (origin.cwd !== active.cwd) return false;
+    if (origin.sessionId || active.sessionId) return origin.sessionId === active.sessionId;
+    return true;
+  }
+  if (active.sessionId) return false;
+  return meta.cwd === active.cwd;
+}
+
+function getGoalActivityOrigin(ctx: ExtensionContext) {
+  let sessionId: string | undefined;
+  try {
+    sessionId = ctx.sessionManager?.getSessionId();
+  } catch {
+    sessionId = undefined;
+  }
+  return { cwd: ctx.cwd, sessionId };
+}
+
+function backgroundTaskToGoalItem(meta: BackgroundTaskMeta): GoalBackgroundWorkItem {
+  const active = meta.status === "running";
+  const terminal = isTerminalStatus(meta.status);
+  const attention = terminal && meta.status !== "succeeded";
+  const item: GoalBackgroundWorkItem = {
+    id: meta.id,
+    status: meta.status,
+    active,
+    terminal,
+    attention,
+    startedAt: meta.startedAt,
+    details: {
+      kind: meta.kind,
+      callback: meta.callback !== false,
+      cwd: meta.cwd,
+      command: meta.command,
+      argv: meta.argv,
+      logPath: meta.logPath,
+      spawnPid: meta.spawnPid,
+    },
+  };
+  if (meta.name !== undefined) item.label = meta.name;
+  if (meta.endedAt !== undefined) item.endedAt = meta.endedAt;
+  return item;
+}

package/node_modules/pi-better-background-tasks/src/index.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { disposeBackgroundWorkNavigator } from "./shared-navigator.ts";
+import { registerBackgroundTasksGoalProvider } from "./goal-provider.js";
+import { clearBackgroundTasksNavigatorSession, ensureBackgroundTasksNavigator, ensureBackgroundTasksNavigatorProvider } from "./navigator-provider.js";
+import { registerTools } from "./tools.js";
+
+export default function backgroundTasksExtension(pi: ExtensionAPI): void {
+  registerBackgroundTasksGoalProvider(pi);
+  ensureBackgroundTasksNavigatorProvider(pi);
+  pi.on("session_start", async (_event, ctx) => {
+    registerBackgroundTasksGoalProvider(pi);
+    ensureBackgroundTasksNavigator(ctx);
+  });
+  pi.on("session_before_switch", async () => {
+    clearBackgroundTasksNavigatorSession();
+    disposeBackgroundWorkNavigator();
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    clearBackgroundTasksNavigatorSession();
+    disposeBackgroundWorkNavigator(ctx);
+  });
+  registerTools(pi);
+}

package/node_modules/pi-better-background-tasks/src/logs.ts

@@ -0,0 +1,84 @@
+import { appendFileSync, closeSync, openSync, readSync, statSync, truncateSync } from "node:fs";
+import { dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+import { readBoundedTail, tailTerminalDisplay, terminalDisplayRows } from "./shared-log-utils.js";
+import type { CommandResult } from "./types.js";
+
+export const DEFAULT_MAX_LOG_BYTES = 4 * 1024 * 1024;
+export const MAX_LOG_TAIL_READ_BYTES = 512 * 1024;
+const RETAINED_LOG_FRACTION = 0.75;
+
+export function appendWatchResult(logPath: string, result: CommandResult): void {
+  mkdirSync(dirname(logPath), { recursive: true });
+  const header = `\n--- check ${new Date(result.startedAt).toISOString()} exit=${result.exitCode ?? "null"} signal=${result.signal ?? "null"} duration_ms=${result.endedAt - result.startedAt} ---\n`;
+  appendFileSync(logPath, header);
+  if (result.stdout) appendFileSync(logPath, result.stdout.endsWith("\n") ? result.stdout : `${result.stdout}\n`);
+  if (result.stderr) appendFileSync(logPath, `[stderr]\n${result.stderr.endsWith("\n") ? result.stderr : `${result.stderr}\n`}`);
+}
+
+export function appendLine(logPath: string, line: string): void {
+  mkdirSync(dirname(logPath), { recursive: true });
+  appendFileSync(logPath, `${line}\n`);
+}
+
+export function readLog(logPath: string, tailLines?: number): { text: string; truncated: boolean } {
+  const requestedRows = tailLines && tailLines > 0 ? Math.floor(tailLines) : undefined;
+  const tail = readBoundedTail(logPath, MAX_LOG_TAIL_READ_BYTES);
+  if (!tail.text) return { text: "", truncated: tail.truncated };
+  if (!requestedRows) return { text: tail.text, truncated: tail.truncated };
+  const rows = terminalDisplayRows(tail.text);
+  return {
+    text: tailTerminalDisplay(tail.text, requestedRows),
+    truncated: tail.truncated || rows.length > requestedRows,
+  };
+}
+
+export function resolveMaxLogBytes(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) return DEFAULT_MAX_LOG_BYTES;
+  return Math.max(64 * 1024, Math.floor(value));
+}
+
+/**
+ * Compact in place so detached children keep writing to the same inode. A
+ * rename-based rotation would leave their inherited descriptor unbounded.
+ */
+export function retainLogTail(logPath: string, maxBytes: number): { discardedBytes: number } | undefined {
+  let size: number;
+  try {
+    size = statSync(logPath).size;
+  } catch {
+    return undefined;
+  }
+  if (size <= maxBytes) return undefined;
+
+  const start = Math.max(0, size - Math.floor(maxBytes * RETAINED_LOG_FRACTION));
+  let fd: number | undefined;
+  let retained: Buffer;
+  try {
+    fd = openSync(logPath, "r");
+    retained = Buffer.allocUnsafe(size - start);
+    let offset = 0;
+    while (offset < retained.length) {
+      const read = readSync(fd, retained, offset, retained.length - offset, start + offset);
+      if (read <= 0) break;
+      offset += read;
+    }
+    retained = retained.subarray(0, offset);
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+  }
+
+  const discardedBytes = Math.max(0, size - retained.length);
+  try {
+    truncateSync(logPath, 0);
+    if (retained.length) appendFileSync(logPath, retained);
+    appendFileSync(logPath, `--- log retention discarded ${discardedBytes} bytes; newest output retained ---\n`);
+    return { discardedBytes };
+  } catch {
+    return undefined;
+  }
+}