pi-better-background-tasks 0.1.6 → 0.1.8

package/README.md

@@ -6,6 +6,10 @@
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,8 @@
     "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",

package/src/logs.ts

@@ -1,8 +1,13 @@
-import { appendFileSync, readFileSync } from "node:fs";
+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`;
@@ -17,14 +22,63 @@ export function appendLine(logPath: string, line: string): void {
 }
 
 export function readLog(logPath: string, tailLines?: number): { text: string; truncated: boolean } {
-  let text: string;
+  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 {
-    text = readFileSync(logPath, "utf8");
+    truncateSync(logPath, 0);
+    if (retained.length) appendFileSync(logPath, retained);
+    appendFileSync(logPath, `--- log retention discarded ${discardedBytes} bytes; newest output retained ---\n`);
+    return { discardedBytes };
   } catch {
-    return { text: "", truncated: false };
+    return undefined;
   }
-  if (!tailLines || tailLines <= 0) return { text, truncated: false };
-  const lines = text.split(/\r?\n/);
-  if (lines.length <= tailLines) return { text, truncated: false };
-  return { text: lines.slice(-tailLines).join("\n"), truncated: true };
 }

package/src/navigator-provider.ts

@@ -133,6 +133,10 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
   if (meta.lastCheckedAt) metadata.push({ label: "checked", value: `${formatDuration(now - meta.lastCheckedAt)} ago` });
   if (meta.lastExitCode !== undefined) metadata.push({ label: "exit", value: String(meta.lastExitCode) });
   if (meta.error) metadata.push({ label: "error", value: meta.error });
+  if (meta.logDiscardedBytes) {
+    const count = meta.logRetentionEvents ?? 1;
+    metadata.push({ label: "log dropped", value: `${formatBytes(meta.logDiscardedBytes)} in ${count} compaction${count === 1 ? "" : "s"}` });
+  }
   return {
     providerId: "background-tasks",
     id: meta.id,
@@ -146,6 +150,7 @@ function detailFromMeta(meta: BackgroundTaskMeta | undefined, now: number, optio
       label: "command",
       text: command,
       collapsedText: compactCommandLabel(meta),
+      expandedByDefault: true,
     }],
     evidence: {
       label: log.truncated ? "log tail" : "log",
@@ -210,3 +215,9 @@ function formatDuration(ms: number): string {
   const min = minutes % 60;
   return `${hours}h ${min.toString().padStart(2, "0")}m`;
 }
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { appendLine, appendWatchResult } from "./logs.js";
+import { appendLine, appendWatchResult, retainLogTail, resolveMaxLogBytes } from "./logs.js";
 import { evaluateCondition } from "./conditions.js";
 import { processExists, runCommandOnce, spawnCommand, stopProcessGroup } from "./process.js";
 import { ensureTaskDir, logPathFor, nextTaskId, readMeta, writeMeta } from "./registry.js";
@@ -8,6 +8,8 @@ import { isTerminalStatus } from "./types.js";
 
 const watcherTimers = new Map<string, ReturnType<typeof setTimeout>>();
 const activePolls = new Set<string>();
+const logRetentionTimers = new Map<string, ReturnType<typeof setInterval>>();
+const LOG_RETENTION_CHECK_MS = 1000;
 
 export const DEFAULT_WATCH_TIMEOUT_SECONDS = 15 * 60;
 
@@ -17,6 +19,7 @@ export interface SpawnTaskParams extends CommandSpec {
   name?: string;
   callback?: boolean;
   timeout_seconds?: number;
+  max_log_bytes?: number;
 }
 
 export interface WatchTaskParams extends CommandSpec {
@@ -24,6 +27,7 @@ export interface WatchTaskParams extends CommandSpec {
   callback?: boolean;
   interval_seconds?: number;
   timeout_seconds?: number;
+  max_log_bytes?: number;
   success_when: Condition;
   failure_when?: Condition;
 }
@@ -56,15 +60,20 @@ export function spawnTask(
     shell: params.shell ?? true,
     cwd,
     env: params.env,
+    maxLogBytes: resolveMaxLogBytes(params.max_log_bytes),
     pid: spawned.child.pid,
     pgid: spawned.pgid,
     spawnPid: process.pid,
   };
   writeMeta(meta);
+  scheduleLogRetention(id);
   spawned.child.unref();
   spawned.child.on("close", (exitCode, signal) => {
+    stopLogRetention(id);
     const latest = readMeta(id);
-    if (!latest || isTerminalStatus(latest.status)) return;
+    if (!latest) return;
+    enforceLogRetention(latest);
+    if (isTerminalStatus(latest.status)) return;
     latest.status = exitCode === 0 ? "succeeded" : "failed";
     latest.endedAt = Date.now();
     latest.lastExitCode = exitCode;
@@ -104,6 +113,7 @@ export function startWatchTask(
     shell: params.shell ?? true,
     cwd,
     env: params.env,
+    maxLogBytes: resolveMaxLogBytes(params.max_log_bytes),
     spawnPid: process.pid,
     successWhen: params.success_when,
     failureWhen: params.failure_when,
@@ -135,6 +145,7 @@ export function resumeRunningTask(
     scheduleWatch(pi, meta.id, 0, getActiveSession);
     return meta;
   }
+  if (meta.kind === "process") scheduleLogRetention(meta.id);
   if (meta.kind === "process" && meta.pid && !processExists(meta.pid)) {
     meta.status = "failed";
     meta.endedAt = Date.now();
@@ -158,6 +169,7 @@ export function stopTask(pi: ExtensionAPI, id: string, getActiveSession?: Active
   meta.result = { reason: "cancelled" };
   writeMeta(meta);
   clearWatchTimer(id);
+  stopLogRetention(id);
   if (meta.kind === "process" && meta.pid) {
     try {
       stopProcessGroup(meta.pid, meta.pgid);
@@ -198,6 +210,7 @@ async function pollWatch(pi: ExtensionAPI, id: string, getActiveSession?: Active
     appendWatchResult(meta.logPath, result);
     const latest = readMeta(id);
     if (!latest || latest.status !== "running") return;
+    enforceLogRetention(latest);
     latest.lastCheckedAt = Date.now();
     latest.lastExitCode = result.exitCode;
     latest.lastSignal = result.signal;
@@ -253,6 +266,7 @@ function finalize(
   }
   writeMeta(meta);
   clearWatchTimer(meta.id);
+  stopLogRetention(meta.id);
   void notifyTerminal(pi, meta, getActiveSession);
 }
 
@@ -336,6 +350,34 @@ function commandSpecFromMeta(meta: BackgroundTaskMeta): CommandSpec {
   };
 }
 
+function scheduleLogRetention(id: string): void {
+  stopLogRetention(id);
+  const timer = setInterval(() => {
+    const meta = readMeta(id);
+    if (!meta || meta.status !== "running" || meta.kind !== "process") {
+      stopLogRetention(id);
+      return;
+    }
+    enforceLogRetention(meta);
+  }, LOG_RETENTION_CHECK_MS);
+  timer.unref();
+  logRetentionTimers.set(id, timer);
+}
+
+function stopLogRetention(id: string): void {
+  const timer = logRetentionTimers.get(id);
+  if (timer) clearInterval(timer);
+  logRetentionTimers.delete(id);
+}
+
+function enforceLogRetention(meta: BackgroundTaskMeta): void {
+  const compacted = retainLogTail(meta.logPath, resolveMaxLogBytes(meta.maxLogBytes));
+  if (!compacted) return;
+  meta.logDiscardedBytes = (meta.logDiscardedBytes ?? 0) + compacted.discardedBytes;
+  meta.logRetentionEvents = (meta.logRetentionEvents ?? 0) + 1;
+  writeMeta(meta);
+}
+
 function extractLastState(result: { stdout: string }): unknown {
   try {
     return JSON.parse(result.stdout);

package/src/shared-log-utils.ts

@@ -0,0 +1,104 @@
+// Generated from packages/log-utils/index.ts. Do not edit directly.
+import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+
+export interface TailRead {
+  text: string;
+  truncated: boolean;
+  totalBytes: number;
+  error?: string;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Read no more than `maxBytes` from a file's end. This avoids whole-file
+ * allocation for live logs that can grow past Node's string-size limit.
+ */
+export function readBoundedTail(path: string, maxBytes: number): TailRead {
+  const budget = Math.max(1, Math.floor(maxBytes));
+  let totalBytes: number;
+  try {
+    totalBytes = statSync(path).size;
+  } catch (error) {
+    return { text: "", truncated: false, totalBytes: 0, error: errorText(error) };
+  }
+  if (totalBytes === 0) return { text: "", truncated: false, totalBytes };
+  if (totalBytes <= budget) {
+    try {
+      return { text: readFileSync(path, "utf8"), truncated: false, totalBytes };
+    } catch (error) {
+      return { text: "", truncated: false, totalBytes, error: errorText(error) };
+    }
+  }
+
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, "r");
+    const buffer = Buffer.allocUnsafe(budget);
+    const start = totalBytes - budget;
+    let offset = 0;
+    while (offset < budget) {
+      const read = readSync(fd, buffer, offset, budget - offset, start + offset);
+      if (read <= 0) break;
+      offset += read;
+    }
+    return { text: buffer.toString("utf8", 0, offset), truncated: true, totalBytes };
+  } catch (error) {
+    return { text: "", truncated: true, totalBytes, error: errorText(error) };
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+  }
+}
+
+/**
+ * Convert terminal-like output into display rows. A bare carriage return is a
+ * cursor reset, so repeated progress redraws collapse to their latest state;
+ * CRLF remains a normal newline. Individual rows are capped defensively.
+ */
+export function terminalDisplayRows(text: string, maxRowChars = 8 * 1024): string[] {
+  const rowLimit = Math.max(64, Math.floor(maxRowChars));
+  const rows: string[] = [];
+  let current = "";
+  let progress = "";
+
+  const append = (value: string) => {
+    current += value;
+    if (current.length > rowLimit) current = `...${current.slice(-(rowLimit - 3))}`;
+  };
+  const emit = () => {
+    const value = current || progress;
+    if (value) rows.push(value);
+    current = "";
+    progress = "";
+  };
+
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i]!;
+    if (char === "\r") {
+      if (text[i + 1] === "\n") {
+        emit();
+        i += 1;
+      } else {
+        progress = current || progress;
+        current = "";
+      }
+    } else if (char === "\n") {
+      emit();
+    } else {
+      append(char);
+    }
+  }
+  const final = current || progress;
+  if (final) rows.push(final);
+  return rows;
+}
+
+export function tailTerminalDisplay(text: string, rows: number, maxRowChars?: number): string {
+  const rendered = terminalDisplayRows(text, maxRowChars);
+  const count = Math.max(1, Math.floor(rows));
+  return rendered.slice(-count).join("\n");
+}

package/src/shared-navigator.ts

@@ -35,7 +35,7 @@ export type BackgroundWorkDetail = {
   statusTone: BackgroundWorkStatusTone;
   subtitle?: string;
   metadata: Array<{ label: string; value: string }>;
-  foldedSections?: Array<{ id: string; label: string; text: string; collapsedText?: string }>;
+  foldedSections?: Array<{ id: string; label: string; text: string; collapsedText?: string; expandedByDefault?: boolean }>;
   evidence: { label: string; text: string };
   footerActions?: string[];
 };
@@ -94,7 +94,7 @@ export const MAIN_LIST_WIDGET_KEY = "background-work-list";
 export const DETAIL_TICK_MS = 1000;
 export const CLOSE_ARM_MS = 3000;
 export const DEFAULT_LOG_TAIL_ROWS = 10;
-export const LOG_TAIL_ROW_CHOICES = [10, 25, 50, 100] as const;
+export const LOG_TAIL_ROW_CHOICES = [10, 25] as const;
 // Row rebuild cadence. Each tick asks every provider for rows, which stats and
 // parses run logs, so this is a per-provider I/O cadence and not a paint rate:
 // the widget repaints from render() whenever the TUI asks. 1 Hz matches
@@ -671,6 +671,7 @@ function createOverlayComponent(
   const expandedSections = new Set<string>();
   let detailId: string | null = initialDetailId ?? null;
   let detail: BackgroundWorkDetail | null = detailId ? (detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? null) : null;
+  applyDefaultExpandedSections(detail, expandedSections);
   if (detailId) {
     const idx = overlayState.rows.findIndex((row) => row.navigatorId === detailId);
     if (idx >= 0) overlayState.selected = idx;
@@ -729,6 +730,7 @@ function createOverlayComponent(
     detailId = row.navigatorId;
     expandedSections.clear();
     detail = detailFor(row.navigatorId, Date.now(), { logTailLines: logTailRows }) ?? fallbackDetail(row);
+    applyDefaultExpandedSections(detail, expandedSections);
     mode = "detail";
     startDetailTimer();
     requestRender();
@@ -815,16 +817,6 @@ function createOverlayComponent(
             requestRender();
           }
         }
-        else if (data === "[") {
-          logTailRows = previousLogTailRows(logTailRows);
-          if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
-          requestRender();
-        }
-        else if (data === "]") {
-          logTailRows = nextLogTailRows(logTailRows);
-          if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
-          requestRender();
-        }
         else if (data === "l" || data === "L") {
           logTailRows = cycleLogTailRows(logTailRows);
           if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
@@ -939,7 +931,7 @@ function buildDetailLines(
   const foldedAction = toggleableSectionId
     ? (options.expandedSections?.has(toggleableSectionId) ? "Enter collapse" : "Enter expand")
     : null;
-  const actions = [foldedAction, ...(detail.footerActions?.length ? detail.footerActions : ["x close"]), "[ fewer", "] more", "l cycle", "Esc close"].filter(Boolean).join(" · ");
+  const actions = [foldedAction, ...(detail.footerActions?.length ? detail.footerActions : ["x close"]), "l 10/25", "Esc close"].filter(Boolean).join(" · ");
   lines.push(dim(`   ← back · ${actions}`, fg));
   lines.push("");
   lines.push(`   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`);
@@ -1004,6 +996,12 @@ function firstToggleableSectionId(detail: BackgroundWorkDetail | null | undefine
   return detail && isFoldableEvidence(detail) ? EVIDENCE_SECTION_ID : undefined;
 }
 
+function applyDefaultExpandedSections(detail: BackgroundWorkDetail | null, expandedSections: Set<string>): void {
+  for (const section of detail?.foldedSections ?? []) {
+    if (section.expandedByDefault) expandedSections.add(section.id);
+  }
+}
+
 function isFoldableEvidence(detail: BackgroundWorkDetail): boolean {
   return !/log/i.test(detail.evidence.label);
 }
@@ -1043,19 +1041,6 @@ function wrapEvidenceText(text: string, width: number): string[] {
   return rows.length ? rows : ["(no output yet)"];
 }
 
-function nextLogTailRows(current: number): number {
-  for (const value of LOG_TAIL_ROW_CHOICES) if (value > current) return value;
-  return LOG_TAIL_ROW_CHOICES[LOG_TAIL_ROW_CHOICES.length - 1];
-}
-
-function previousLogTailRows(current: number): number {
-  for (let i = LOG_TAIL_ROW_CHOICES.length - 1; i >= 0; i -= 1) {
-    const value = LOG_TAIL_ROW_CHOICES[i]!;
-    if (value < current) return value;
-  }
-  return LOG_TAIL_ROW_CHOICES[0];
-}
-
 function cycleLogTailRows(current: number): number {
   const idx = LOG_TAIL_ROW_CHOICES.findIndex((value) => value === current);
   return LOG_TAIL_ROW_CHOICES[(idx + 1) % LOG_TAIL_ROW_CHOICES.length];

package/src/tools.ts

@@ -22,6 +22,7 @@ const CommandFields = {
   shell: Type.Optional(Type.Boolean({ description: "Run command through the package's bash-compatible shell. Default true." })),
   cwd: Type.Optional(Type.String({ description: "Working directory. Defaults to the current pi cwd." })),
   env: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Extra environment variables." })),
+  max_log_bytes: Type.Optional(Type.Number({ description: "Maximum retained raw-log bytes. Default 4194304 (4 MiB). Older output is compacted while the task runs." })),
   callback: Type.Optional(Type.Boolean({ description: "Queue a follow-up when the task reaches a terminal state. Default true." })),
   timeout_seconds: Type.Optional(Type.Number({ description: "Optional timeout in seconds. Command watchers default to 900 seconds when omitted; pass 0 to disable. Spawned processes have no default timeout." })),
 };
@@ -143,7 +144,7 @@ export function registerTools(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "bg_task_log",
     label: "BG Log",
-    description: "Read a background task log. Default output is a compact 20-line tail for model ingestion. Pass tail_lines for a bounded tail; pass tail_lines:0 only when the full log is explicitly required. Nonblocking.",
+    description: "Read a background task log. Default output is a compact 20-line terminal-aware tail for model ingestion. Pass tail_lines for a bounded tail; tail_lines:0 returns the retained raw log, capped at 512 KiB for safe recovery. Nonblocking.",
     parameters: LogParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
       return renderBackgroundTaskLogDisplay(result, options, theme);
@@ -299,8 +300,9 @@ function formatCompactStatus(meta: BackgroundTaskMeta): string {
   if (reason) lines.push(`result: ${reason}`);
   if (meta.error) lines.push(`error: ${oneLine(meta.error, 500)}`);
   if (meta.lastState !== undefined) lines.push(`last state: ${oneLine(meta.lastState, 800)}`);
+  if (meta.logDiscardedBytes) lines.push(`log retention: ${meta.logDiscardedBytes} bytes discarded in ${meta.logRetentionEvents ?? 1} compaction(s).`);
   lines.push(`log: ${meta.logPath}`);
-  lines.push(`For full metadata use bg_task_status id=${meta.id} verbose=true. For logs use bg_task_log id=${meta.id} tail_lines=20, or tail_lines=0 for the full log.`);
+  lines.push(`For full metadata use bg_task_status id=${meta.id} verbose=true. For logs use bg_task_log id=${meta.id} tail_lines=20, or tail_lines=0 for the retained raw log.`);
   return lines.join("\n");
 }
 

package/src/types.ts

@@ -62,6 +62,9 @@ export interface BackgroundTaskMeta {
   shell?: boolean;
   cwd: string;
   env?: Record<string, string>;
+  maxLogBytes?: number;
+  logDiscardedBytes?: number;
+  logRetentionEvents?: number;
   pid?: number;
   pgid?: number;
   spawnPid: number;