@asterxsk/kiln 0.1.0 → 0.2.0

package/agent/extensions/background-terminals/src/output.ts

@@ -1,84 +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,
-    };
-  }
-}
+/**
+ * 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/extensions/background-terminals/src/prompt.ts

@@ -1,142 +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");
-}
+/** 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/extensions/background-terminals/src/result-delivery.ts

@@ -1,27 +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();
-    },
-  };
-}
+/**
+ * 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/extensions/background-terminals/src/runtime.ts

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