@asterxsk/kiln 0.1.0 → 0.3.0

package/agent.bak.20260905-190020/extensions/background-terminals/src/output.ts

@@ -0,0 +1,84 @@
+/**
+ * OutputBuffer — bounded in-memory capture of one process stream.
+ *
+ * Newest output is always retained; when the retained size exceeds the cap,
+ * whole chunks are evicted from the head and counted in `truncatedBytes`.
+ * A single chunk larger than the cap itself is trimmed to its tail (on a
+ * UTF-8 boundary) so retention is strictly bounded even for one giant write.
+ * An optional spill callback receives every chunk (in order, before any
+ * eviction) 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";
+
+export class OutputBuffer {
+  private chunks: string[] = [];
+  /** Bytes currently retained across `chunks`. */
+  private retainedBytes = 0;
+  /** Cached join of `chunks`; invalidated on push so 1Hz UI ticks are cheap. */
+  private cachedText: string | undefined = "";
+  /** Bumped on every push; lets the UI cache derived line layouts. */
+  version = 0;
+  totalBytes = 0;
+  truncatedBytes = 0;
+  spillPath?: string;
+
+  private readonly maxRetainedBytes: number;
+  private readonly spill?: (chunk: string) => unknown;
+
+  constructor(maxRetainedBytes: number, spill?: (chunk: string) => unknown) {
+    this.maxRetainedBytes = maxRetainedBytes;
+    this.spill = spill;
+  }
+
+  push(chunk: string) {
+    if (chunk.length === 0) return true;
+    let bytes = Buffer.byteLength(chunk, "utf8");
+    this.totalBytes += bytes;
+    const spillAccepted = this.spill?.(chunk) !== false;
+    if (bytes > this.maxRetainedBytes) {
+      // A single pathological chunk larger than the whole cap: everything
+      // retained so far precedes it in the stream, so evict all of it, then
+      // keep only the chunk's tail (cut on a UTF-8 code point boundary).
+      // Retention stays strictly bounded even for one giant write, and the
+      // retained view stays contiguous (no hole in the middle).
+      this.truncatedBytes += this.retainedBytes;
+      this.chunks = [];
+      this.retainedBytes = 0;
+      const raw = Buffer.from(chunk, "utf8");
+      let start = raw.length - this.maxRetainedBytes;
+      while (start < raw.length && (raw[start] & 0xc0) === 0x80) start++;
+      this.truncatedBytes += start;
+      chunk = raw.subarray(start).toString("utf8");
+      bytes = raw.length - start;
+    }
+    this.chunks.push(chunk);
+    this.retainedBytes += bytes;
+    while (
+      this.retainedBytes > this.maxRetainedBytes &&
+      this.chunks.length > 1
+    ) {
+      const evicted = this.chunks.shift();
+      if (evicted === undefined) break;
+      const evictedBytes = Buffer.byteLength(evicted, "utf8");
+      this.retainedBytes -= evictedBytes;
+      this.truncatedBytes += evictedBytes;
+    }
+    this.cachedText = undefined;
+    this.version++;
+    return spillAccepted;
+  }
+
+  view(): OutputView {
+    this.cachedText ??= this.chunks.join("");
+    return {
+      text: this.cachedText,
+      totalBytes: this.totalBytes,
+      truncatedBytes: this.truncatedBytes,
+      spillPath: this.spillPath,
+    };
+  }
+}

package/agent.bak.20260905-190020/extensions/background-terminals/src/prompt.ts

@@ -0,0 +1,142 @@
+/** All model-facing strings for the background-terminals tools. */
+
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateTail,
+} from "@earendil-works/pi-coding-agent";
+import { formatElapsed, formatExit, type TerminalSnapshot } from "./domain.ts";
+import { MAX_RUNNING, type KillResult } from "./manager.ts";
+
+/** bg_status stdout tail. */
+export const STATUS_STDOUT_MAX = 16 * 1024;
+/** bg_status stderr tail. */
+export const STATUS_STDERR_MAX = 8 * 1024;
+/** Completion follow-up stdout tail. Keep this concise; /ps has the detailed view. */
+export const RESULT_STDOUT_MAX = 8 * 1024;
+/** Completion follow-up stderr tail. Keep this concise; /ps has the detailed view. */
+export const RESULT_STDERR_MAX = 4 * 1024;
+const STATUS_STDOUT_MAX_LINES = 400;
+const STATUS_STDERR_MAX_LINES = 200;
+const RESULT_STDOUT_MAX_LINES = 40;
+const RESULT_STDERR_MAX_LINES = 20;
+
+export const BG_START_TOOL_DESCRIPTION =
+  "Start a long-running shell command as a background terminal (executed via the platform shell — sh -c on POSIX, cmd.exe /d /s /c on Windows). " +
+  "Fire-and-forget: this returns immediately with an id, and you get a message with the final output when the process exits. " +
+  "The process receives NO stdin (immediate EOF) and there is no way to send input later — interactive commands will not work; use bg_kill to stop a stuck one. " +
+  `Terminals are session-scoped: they are killed when the session ends or reloads. Output shown to you is tail-truncated (stdout ${formatSize(STATUS_STDOUT_MAX)}, stderr ${formatSize(STATUS_STDERR_MAX)}); the full logs are captured to files and in the /ps viewer. ` +
+  `Max ${MAX_RUNNING} background terminals can run at once.`;
+
+export const BG_START_PROMPT_SNIPPET =
+  "Run a long-lived shell command in the background (dev servers, builds, watchers); output is captured and you're notified on exit";
+
+export const BG_START_PROMPT_GUIDELINES = [
+  "Use bg_start for commands expected to run long or indefinitely (servers, watch modes, long builds); use the regular bash tool for quick commands.",
+  "bg_start processes receive no stdin — never start a command that requires interactive input.",
+  "After bg_start, keep working; the exit result arrives automatically. Use bg_status only when you need current output before continuing.",
+];
+
+export const BG_START_PARAMETER_DESCRIPTIONS = {
+  command:
+    "Shell command line to run in the background (sh -c on POSIX, cmd.exe /d /s /c on Windows). It receives no stdin (EOF immediately); interactive commands will not work.",
+  title: "Short human-readable name shown in listings and the UI",
+  workingDir: "Working directory (default: current working directory)",
+};
+
+export const BG_STATUS_TOOL_DESCRIPTION =
+  "Peek at a background terminal's status and current output (tail-truncated) without blocking. If the terminal already exited, this returns its final state.";
+
+export const BG_STATUS_PARAMETER_DESCRIPTIONS = {
+  id: 'Terminal id, e.g. "bt-1"',
+};
+
+export const BG_LIST_TOOL_DESCRIPTION =
+  "List all background terminals (running and settled) with pid, elapsed time, exit status, and output sizes.";
+
+export const BG_KILL_TOOL_DESCRIPTION =
+  "Stop one or more running background terminals (SIGTERM to the whole process tree, escalating to SIGKILL). Returns each terminal's final state; already-settled ids are reported as such.";
+
+export const BG_KILL_PARAMETER_DESCRIPTIONS = {
+  ids: 'Terminal ids to stop, e.g. ["bt-1"]',
+};
+
+export function buildStartResult(snap: TerminalSnapshot) {
+  return (
+    `Started background terminal ${snap.id} "${snap.title}" (pid ${snap.pid ?? "?"}, ${snap.cwd}).\n` +
+    `It runs in the background with no stdin. You'll get a message when it exits, ` +
+    `or use bg_status(id: "${snap.id}") to peek, bg_kill to stop it, bg_list to see all.`
+  );
+}
+
+/** 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)}`,
+  ];
+  return `${snap.id} [${snap.status}] "${snap.title}" (${details.join(", ")})`;
+}
+
+/** Tail-truncated labeled output section with a pointer at the full log. */
+function outputSection(
+  label: string,
+  view: TerminalSnapshot["stdout"],
+  maxBytes: number,
+  maxLines: number,
+) {
+  if (view.totalBytes === 0) return `${label}: (empty)`;
+  const truncation = truncateTail(view.text, {
+    maxBytes: Math.min(maxBytes, DEFAULT_MAX_BYTES),
+    maxLines: Math.min(maxLines, DEFAULT_MAX_LINES),
+  });
+  let text = `${label}:\n${truncation.content}`;
+  const shownBytes = truncation.outputBytes;
+  if (truncation.truncated || view.truncatedBytes > 0) {
+    const where = view.spillPath
+      ? `Full log: ${view.spillPath}`
+      : "Full output in the /ps viewer";
+    text += `\n[${label} truncated: showing last ${formatSize(shownBytes)} of ${formatSize(view.totalBytes)}. ${where}]`;
+  }
+  return text;
+}
+
+export function buildStatusResult(snap: TerminalSnapshot) {
+  let text = describeTerminal(snap);
+  if (snap.errorText) text += `\nError: ${snap.errorText}`;
+  text += `\n\n${outputSection("stdout", snap.stdout, STATUS_STDOUT_MAX, STATUS_STDOUT_MAX_LINES)}`;
+  text += `\n\n${outputSection("stderr", snap.stderr, STATUS_STDERR_MAX, STATUS_STDERR_MAX_LINES)}`;
+  return text;
+}
+
+/** The async completion follow-up injected into the model's context. */
+export function buildTerminalResultMessage(snap: TerminalSnapshot) {
+  const how =
+    snap.status === "killed" ? "was killed" : `exited (${formatExit(snap)})`;
+  let text = `Background terminal ${snap.id} "${snap.title}" ${how} after ${formatElapsed(snap)}.`;
+  if (snap.errorText) text += `\nError: ${snap.errorText}`;
+  text += `\n\n${outputSection("stdout", snap.stdout, RESULT_STDOUT_MAX, RESULT_STDOUT_MAX_LINES)}`;
+  if (snap.stderr.totalBytes > 0) {
+    text += `\n\n${outputSection("stderr", snap.stderr, RESULT_STDERR_MAX, RESULT_STDERR_MAX_LINES)}`;
+  }
+  return text;
+}
+
+export function buildKillReport(results: ReadonlyArray<KillResult>) {
+  return results
+    .map((entry) => {
+      if (entry.killed) {
+        return `Killed ${entry.id} "${entry.title}" (${entry.exit}).`;
+      }
+      if (entry.wasRunning) {
+        // The natural exit won the race with the kill signal.
+        return `${entry.id} "${entry.title}" exited on its own before the kill landed (${entry.exit}).`;
+      }
+      return `${entry.id} "${entry.title}" was already ${entry.status} (${entry.exit}).`;
+    })
+    .join("\n");
+}

package/agent.bak.20260905-190020/extensions/background-terminals/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 a tool call (bg_kill / bg_status) that already
+ * returned the settlement itself. 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/agent.bak.20260905-190020/extensions/background-terminals/src/runtime.ts

@@ -0,0 +1,36 @@
+/**
+ * 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, 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.");
+  }
+  const [first] = Cause.prettyErrors(exit.cause);
+  throw new Error(first?.message ?? Cause.pretty(exit.cause));
+}

package/agent.bak.20260905-190020/extensions/background-terminals/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;
+    },
+  };
+}