pi-tian-background-terminals 0.1.0

package/src/output.ts

@@ -0,0 +1,163 @@
+/**
+ * OutputBuffer — bounded head+tail in-memory capture of one process stream.
+ *
+ * A stable prefix and rolling suffix are retained; once output exceeds the cap,
+ * bytes from the middle are omitted. A single oversized chunk is split only on
+ * UTF-8 code point boundaries. An optional spill callback receives every chunk
+ * in order before retention, so the caller can keep a complete on-disk copy.
+ *
+ * Plain TS by design: this is push-based accumulation driven by node stream
+ * 'data' callbacks, not stream transformation.
+ */
+
+import type { OutputView } from "./domain.ts";
+
+function utf8Prefix(raw: Buffer, maxBytes: number) {
+  if (raw.length <= maxBytes) return raw;
+  let end = Math.max(0, maxBytes);
+  while (end > 0 && (raw[end] & 0xc0) === 0x80) end--;
+  // Copy the bounded slice so retaining it cannot pin one giant source Buffer.
+  return Buffer.from(raw.subarray(0, end));
+}
+
+function utf8Tail(raw: Buffer, maxBytes: number) {
+  if (raw.length <= maxBytes) return raw;
+  let start = raw.length - Math.max(0, maxBytes);
+  while (start < raw.length && (raw[start] & 0xc0) === 0x80) start++;
+  // Copy the bounded slice so retaining it cannot pin one giant source Buffer.
+  return Buffer.from(raw.subarray(start));
+}
+
+export class OutputBuffer {
+  private headChunks: Buffer[] = [];
+  private tailChunks: Buffer[] = [];
+  private headBytes = 0;
+  private tailBytes = 0;
+  /** Once any byte spills past the head budget, later bytes can only be tail. */
+  private headSealed = false;
+  private cachedView: OutputView | undefined;
+
+  /** Bumped on every push; lets the UI cache derived line layouts. */
+  version = 0;
+  totalBytes = 0;
+  private _spillPath?: string;
+
+  get spillPath() {
+    return this._spillPath;
+  }
+
+  set spillPath(value: string | undefined) {
+    if (this._spillPath === value) return;
+    this._spillPath = value;
+    this.cachedView = undefined;
+  }
+
+  private readonly maxRetainedBytes: number;
+  private readonly headBudget: number;
+  private readonly tailBudget: number;
+  private readonly spill?: (chunk: string) => unknown;
+
+  constructor(
+    maxRetainedBytes: number,
+    spill?: (chunk: string) => unknown,
+    headRetainedBytes = Math.floor(maxRetainedBytes / 8),
+  ) {
+    this.maxRetainedBytes = Math.max(0, maxRetainedBytes);
+    this.headBudget = Math.min(
+      this.maxRetainedBytes,
+      Math.max(0, headRetainedBytes),
+    );
+    this.tailBudget = this.maxRetainedBytes - this.headBudget;
+    this.spill = spill;
+    this.headSealed = this.headBudget === 0;
+  }
+
+  push(chunk: string) {
+    if (chunk.length === 0) return true;
+
+    const raw = Buffer.from(chunk, "utf8");
+    this.totalBytes += raw.length;
+    const spillAccepted = this.spill?.(chunk) !== false;
+    let remainder = raw;
+
+    if (!this.headSealed) {
+      const available = this.headBudget - this.headBytes;
+      const prefix = utf8Prefix(raw, available);
+      if (prefix.length > 0) {
+        this.headChunks.push(prefix);
+        this.headBytes += prefix.length;
+      }
+      remainder = raw.subarray(prefix.length);
+      if (remainder.length > 0) this.headSealed = true;
+    }
+
+    this.pushTail(remainder);
+    this.cachedView = undefined;
+    this.version++;
+    return spillAccepted;
+  }
+
+  private pushTail(raw: Buffer) {
+    if (raw.length === 0 || this.tailBudget === 0) return;
+
+    if (raw.length >= this.tailBudget) {
+      const kept = utf8Tail(raw, this.tailBudget);
+      this.tailChunks = kept.length > 0 ? [kept] : [];
+      this.tailBytes = kept.length;
+      return;
+    }
+
+    this.tailChunks.push(raw);
+    this.tailBytes += raw.length;
+    while (this.tailBytes > this.tailBudget && this.tailChunks.length > 0) {
+      const excess = this.tailBytes - this.tailBudget;
+      const first = this.tailChunks[0];
+      if (first.length <= excess) {
+        this.tailChunks.shift();
+        this.tailBytes -= first.length;
+        continue;
+      }
+
+      let start = excess;
+      while (start < first.length && (first[start] & 0xc0) === 0x80) start++;
+      if (start >= first.length) {
+        this.tailChunks.shift();
+        this.tailBytes -= first.length;
+      } else {
+        this.tailChunks[0] = first.subarray(start);
+        this.tailBytes -= start;
+      }
+    }
+  }
+
+  view(): OutputView {
+    if (this.cachedView) return this.cachedView;
+
+    const head = Buffer.concat(this.headChunks, this.headBytes).toString("utf8");
+    const tail = Buffer.concat(this.tailChunks, this.tailBytes).toString("utf8");
+    const truncatedBytes = Math.max(
+      0,
+      this.totalBytes - this.headBytes - this.tailBytes,
+    );
+    const text =
+      truncatedBytes === 0
+        ? `${head}${tail}`
+        : [
+            head,
+            `... ${truncatedBytes} bytes omitted ...`,
+            tail,
+          ]
+            .filter((part) => part.length > 0)
+            .join("\n");
+
+    this.cachedView = {
+      text,
+      head,
+      tail,
+      totalBytes: this.totalBytes,
+      truncatedBytes,
+      spillPath: this._spillPath,
+    };
+    return this.cachedView;
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,195 @@
+/** Model-facing strings and bounded output formatting for the bash override. */
+
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+  truncateTail,
+} from "@earendil-works/pi-coding-agent";
+import { formatElapsed, formatExit, type TerminalSnapshot } from "./domain.ts";
+import {
+  DEFAULT_YIELD_TIME_MS,
+  MAX_RUNNING,
+  MAX_RUNTIME_TIMEOUT_SECONDS,
+  MAX_YIELD_TIME_MS,
+  MIN_YIELD_TIME_MS,
+} from "./manager.ts";
+
+/** Output returned by the initial bash call. */
+export const BASH_STDOUT_MAX = 16 * 1024;
+export const BASH_STDERR_MAX = 8 * 1024;
+/** Partial updates during the initial foreground wait. */
+const PROGRESS_STDOUT_MAX = 8 * 1024;
+const PROGRESS_STDERR_MAX = 4 * 1024;
+/** Completion follow-up output. Keep this concise; /ps has the detailed view. */
+export const RESULT_STDOUT_MAX = 8 * 1024;
+export const RESULT_STDERR_MAX = 4 * 1024;
+const BASH_STDOUT_MAX_LINES = 400;
+const BASH_STDERR_MAX_LINES = 200;
+const PROGRESS_STDOUT_MAX_LINES = 100;
+const PROGRESS_STDERR_MAX_LINES = 50;
+const RESULT_STDOUT_MAX_LINES = 40;
+const RESULT_STDERR_MAX_LINES = 20;
+
+export const BASH_TOOL_DESCRIPTION =
+  "Execute a Bash command with no interactive stdin through one managed execution path. " +
+  `Waits up to ${DEFAULT_YIELD_TIME_MS} ms by default: commands that finish return their final output; commands still running continue as a session-scoped background terminal and return an id. ` +
+  "A yielded command notifies you automatically exactly once when it exits; do not poll it. The user can inspect or stop it in /ps. " +
+  `Output is bounded head+tail with full private spill logs. Max ${MAX_RUNNING} commands can remain running at once.`;
+
+export const BASH_PROMPT_SNIPPET =
+  "Execute Bash commands; long-running commands automatically continue in the background and notify on exit";
+
+export const BASH_PROMPT_GUIDELINES = [
+  "Use bash for all shell commands; it automatically yields long-running commands instead of requiring a separate background tool.",
+  "bash processes receive no interactive stdin — never use bash for commands requiring prompts or terminal interaction.",
+  "When bash returns a background terminal id, keep working instead of polling; its final result arrives automatically, and the user manages it with /ps.",
+  "Inspect PI_* environment variables for current model and session details.",
+];
+
+export const BASH_PARAMETER_DESCRIPTIONS = {
+  command:
+    "Bash command to execute. It receives no interactive stdin; commands that prompt for input will see EOF.",
+  title:
+    "Optional short name shown in /ps. Defaults to a bounded one-line form of the command.",
+  workingDir: "Working directory relative to the current directory, or an absolute path (default: current working directory)",
+  yieldTimeMs:
+    `How long to wait for completion before returning a background terminal id (default ${DEFAULT_YIELD_TIME_MS} ms, range ${MIN_YIELD_TIME_MS}-${MAX_YIELD_TIME_MS} ms).`,
+  timeout:
+    `Optional hard total runtime timeout in seconds (no default, maximum ${MAX_RUNTIME_TIMEOUT_SECONDS}). Unlike yield_time_ms, this terminates the process tree.`,
+};
+
+/** One metadata line: `bt-1 [running] "dev server" (pid 12345, 3m12s, exit -, /path)`. */
+export function describeTerminal(snap: TerminalSnapshot) {
+  const details = [
+    `pid ${snap.pid ?? "?"}`,
+    formatElapsed(snap),
+    snap.status === "running" ? "exit -" : formatExit(snap),
+    snap.cwd,
+    `stdout ${formatSize(snap.stdout.totalBytes)}, stderr ${formatSize(snap.stderr.totalBytes)}`,
+  ];
+  if (snap.timeoutMs !== undefined) {
+    details.push(`timeout ${snap.timeoutMs / 1000}s`);
+  }
+  return `${snap.id} [${snap.status}] "${snap.title}" (${details.join(", ")})`;
+}
+
+/**
+ * Bounded model-facing view that preserves both startup context and recent
+ * output. The retained in-memory middle may already be omitted; spillPath is
+ * the authoritative complete stream whenever spilling succeeded.
+ */
+function outputSection(
+  label: string,
+  view: TerminalSnapshot["stdout"],
+  maxBytes: number,
+  maxLines: number,
+) {
+  if (view.totalBytes === 0) return `${label}: (empty)`;
+
+  const byteLimit = Math.min(maxBytes, DEFAULT_MAX_BYTES);
+  const lineLimit = Math.min(maxLines, DEFAULT_MAX_LINES);
+  if (view.truncatedBytes === 0) {
+    const completeCheck = truncateTail(view.text, {
+      maxBytes: byteLimit,
+      maxLines: lineLimit,
+    });
+    if (!completeCheck.truncated) {
+      return `${label}:\n${completeCheck.content}`;
+    }
+  }
+
+  const headBytes = Math.max(1, Math.floor(byteLimit / 4));
+  const tailBytes = Math.max(1, byteLimit - headBytes);
+  const headLines = Math.max(1, Math.floor(lineLimit / 4));
+  const tailLines = Math.max(1, lineLimit - headLines);
+  const start = truncateHead(view.head, {
+    maxBytes: headBytes,
+    maxLines: headLines,
+  });
+  const endSource = view.tail || view.head;
+  const end = truncateTail(endSource, {
+    maxBytes: tailBytes,
+    maxLines: tailLines,
+  });
+  const shownBytes = start.outputBytes + end.outputBytes;
+  const omittedBytes = Math.max(0, view.totalBytes - shownBytes);
+  const parts = [start.content];
+  if (omittedBytes > 0) {
+    parts.push(`... ${formatSize(omittedBytes)} omitted ...`);
+  }
+  if (end.content && end.content !== start.content) parts.push(end.content);
+
+  const where = view.spillPath
+    ? `Full log: ${view.spillPath}`
+    : "Retained output is available in the /ps viewer";
+  return `${label}:\n${parts.filter(Boolean).join("\n")}\n[${label} bounded head+tail: showing ${formatSize(shownBytes)} of ${formatSize(view.totalBytes)}. ${where}]`;
+}
+
+function appendOutput(
+  text: string,
+  snap: TerminalSnapshot,
+  stdoutBytes: number,
+  stdoutLines: number,
+  stderrBytes: number,
+  stderrLines: number,
+) {
+  text += `\n\n${outputSection("stdout", snap.stdout, stdoutBytes, stdoutLines)}`;
+  if (snap.stderr.totalBytes > 0) {
+    text += `\n\n${outputSection("stderr", snap.stderr, stderrBytes, stderrLines)}`;
+  }
+  return text;
+}
+
+/** Streaming tool-row update while bash is still in its initial wait. */
+export function buildBashProgress(snap: TerminalSnapshot) {
+  return appendOutput(
+    `Running as terminal ${snap.id} "${snap.title}" (pid ${snap.pid ?? "?"}, ${formatElapsed(snap)}). It will automatically yield if it outlives the initial wait.`,
+    snap,
+    PROGRESS_STDOUT_MAX,
+    PROGRESS_STDOUT_MAX_LINES,
+    PROGRESS_STDERR_MAX,
+    PROGRESS_STDERR_MAX_LINES,
+  );
+}
+
+/** Result of the initial bash wait, whether final or yielded. */
+export function buildBashResult(snap: TerminalSnapshot) {
+  let text =
+    snap.status === "running"
+      ? `Command is still running as background terminal ${snap.id} "${snap.title}" (pid ${snap.pid ?? "?"}). It has no interactive stdin; do not poll it. The final result will arrive automatically, and the user can inspect or stop it with /ps.`
+      : snap.status === "timed_out"
+        ? `Command timed out after ${formatElapsed(snap)}.`
+        : `Command finished in ${formatElapsed(snap)} (${formatExit(snap)}).`;
+  text += `\n${describeTerminal(snap)}`;
+  if (snap.errorText) text += `\nError: ${snap.errorText}`;
+  return appendOutput(
+    text,
+    snap,
+    BASH_STDOUT_MAX,
+    BASH_STDOUT_MAX_LINES,
+    BASH_STDERR_MAX,
+    BASH_STDERR_MAX_LINES,
+  );
+}
+
+/** Async completion follow-up injected only after bash yielded. */
+export function buildTerminalResultMessage(snap: TerminalSnapshot) {
+  const how =
+    snap.status === "killed"
+      ? "was killed"
+      : snap.status === "timed_out"
+        ? "timed out"
+        : `exited (${formatExit(snap)})`;
+  let text = `Background terminal ${snap.id} "${snap.title}" ${how} after ${formatElapsed(snap)}.`;
+  if (snap.errorText) text += `\nError: ${snap.errorText}`;
+  return appendOutput(
+    text,
+    snap,
+    RESULT_STDOUT_MAX,
+    RESULT_STDOUT_MAX_LINES,
+    RESULT_STDERR_MAX,
+    RESULT_STDERR_MAX_LINES,
+  );
+}

package/src/result-delivery.ts

@@ -0,0 +1,27 @@
+/**
+ * Deferred one-shot delivery map (same semantics as subagents'): a settled
+ * terminal's result is held here until it is either drained into a follow-up
+ * message or consumed by bash when its initial wait already
+ * returned the settlement. Keyed by id, so double delivery is
+ * structurally impossible — whoever drains first wins.
+ */
+export function createDeferredResultDelivery<T extends { id: string }>() {
+  const pending = new Map<string, T>();
+
+  return {
+    defer(result: T) {
+      pending.set(result.id, result);
+    },
+    consume(ids: Iterable<string>) {
+      for (const id of ids) pending.delete(id);
+    },
+    drain() {
+      const results = [...pending.values()];
+      pending.clear();
+      return results;
+    },
+    clear() {
+      pending.clear();
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,41 @@
+/**
+ * The async entry-point boundary: one ManagedRuntime shared by every tool
+ * handler, disposed on session_shutdown (which runs the manager finalizer →
+ * disposeAll → every process tree is killed).
+ */
+
+import { Cause, Exit, ManagedRuntime, Result, type Effect } from "effect";
+import { TerminalManagerLive } from "./manager.ts";
+
+export function createTerminalRuntime() {
+  return ManagedRuntime.make(TerminalManagerLive);
+}
+
+export type TerminalRuntime = ReturnType<typeof createTerminalRuntime>;
+
+/**
+ * Run an effect from an async tool handler. Typed failures and defects are
+ * converted to thrown Errors (what pi's tool contract expects); interruption
+ * (tool AbortSignal) throws `interruptMessage`.
+ */
+export async function runTool<A, E>(
+  runtime: TerminalRuntime,
+  effect: Effect.Effect<A, E>,
+  options: { signal?: AbortSignal; interruptMessage?: string } = {},
+) {
+  const exit = await runtime.runPromiseExit(
+    effect,
+    options.signal ? { signal: options.signal } : undefined,
+  );
+  if (Exit.isSuccess(exit)) return exit.value;
+  if (Cause.hasInterruptsOnly(exit.cause)) {
+    throw new Error(options.interruptMessage ?? "Operation was aborted.");
+  }
+  // Preserve typed Effect failures so callers can make narrow, safety-aware
+  // decisions (notably: foreground fallback only when SpawnError proves that
+  // no child was created). Defects still become ordinary Errors.
+  const failure = Cause.findFail(exit.cause);
+  if (Result.isSuccess(failure)) throw failure.success.error;
+  const [first] = Cause.prettyErrors(exit.cause);
+  throw new Error(first?.message ?? Cause.pretty(exit.cause));
+}

package/src/ui/output-view.ts

@@ -0,0 +1,79 @@
+/**
+ * Output rendering for the /ps detail view: turns a captured stream's text
+ * into sanitized, wrapped display lines. Sanitization happens here — at
+ * render time, never at capture time — because raw ANSI/control characters
+ * desync the TUI renderer and smear the overlay.
+ */
+
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+// OSC strings (window titles, hyperlinks, etc.) end in BEL or ST. Strip them
+// before the generic escape/control pass so their payload never becomes
+// visible text after only the leading ESC byte is removed.
+// eslint-disable-next-line no-control-regex
+const OSC_PATTERN =
+  /(?:\u001b\]|\u009d)(?:[^\u0007\u001b\u009c]|\u001b(?!\\))*(?:\u0007|\u001b\\|\u009c)/g;
+// Standards-shaped CSI matcher: parameters are deliberately unbounded; a
+// five-digit cursor movement is still one control sequence, not visible text.
+// eslint-disable-next-line no-control-regex
+const CSI_PATTERN = /(?:\u001b\[|\u009b)[0-?]*[ -/]*[@-~]/g;
+// Remaining two-byte/charset escape forms (for example ESC ( 0).
+// eslint-disable-next-line no-control-regex
+const ESCAPE_PATTERN = /\u001b(?:[()][0-2A-Z]|[ -/]*[@-~])/g;
+
+/**
+ * Strip raw ANSI codes, expand tabs, and drop control chars. Terminal-expanded
+ * tabs (and stray escapes) make lines wider than the width we declare to the
+ * TUI, which desyncs the renderer.
+ */
+export function sanitizeText(text: string) {
+  return text
+    .replace(OSC_PATTERN, "")
+    .replace(CSI_PATTERN, "")
+    .replace(ESCAPE_PATTERN, "")
+    .replaceAll("\t", "  ")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "");
+}
+
+/** Split, sanitize, and wrap a stream's text into display lines. */
+export function buildOutputLines(text: string, width: number) {
+  const safeWidth = Math.max(10, width);
+  const out: string[] = [];
+  for (const raw of text.split("\n")) {
+    // Carriage-return progress lines (npm, cargo): keep only the final state.
+    const segments = raw.split("\r");
+    const finalSegment = segments.at(-1) ?? "";
+    const lastSegment =
+      finalSegment || [...segments].reverse().find((segment) => segment) || "";
+    const clean = sanitizeText(lastSegment);
+    if (clean.length === 0) {
+      out.push("");
+      continue;
+    }
+    out.push(...wrapTextWithAnsi(clean, safeWidth));
+  }
+  // Drop one trailing empty line from a trailing "\n" so the tail pin sits
+  // on the last real output line.
+  if (out.length > 0 && out[out.length - 1] === "") out.pop();
+  return out;
+}
+
+/**
+ * Cache of wrapped lines keyed by (buffer version, width): a chatty process
+ * bumps the version per chunk, but renders between chunks (1Hz elapsed ticks,
+ * scrolling) must not re-wrap megabytes.
+ */
+export function createOutputLineCache() {
+  let key: string | undefined;
+  let lines: string[] = [];
+  return {
+    get(text: string, version: number, width: number) {
+      const nextKey = `${version}:${width}`;
+      if (key !== nextKey) {
+        key = nextKey;
+        lines = buildOutputLines(text, width);
+      }
+      return lines;
+    },
+  };
+}