@asterxsk/kiln 0.3.0 → 0.4.0

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

@@ -1,84 +0,0 @@
-/**
- * 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

@@ -1,142 +0,0 @@
-/** 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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,36 +0,0 @@
-/**
- * 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

@@ -1,79 +0,0 @@
-/**
- * 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;
-    },
-  };
-}