@asterxsk/kiln 0.1.0

package/agent/extensions/background-terminals/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "background-terminals",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "tsc --noEmit -p .",
+    "prepare": "effect-tsgo patch",
+    "test": "node --test --experimental-strip-types manager.test.ts output.test.ts prompt.test.ts result-delivery.test.ts ps.test.ts"
+  },
+  "dependencies": {
+    "effect": "^4.0.0-beta.99"
+  },
+  "devDependencies": {
+    "@effect/tsgo": "^0.24.2",
+    "typescript": "^7.0.2"
+  }
+}

package/agent/extensions/background-terminals/prompt.test.ts

@@ -0,0 +1,125 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { OutputView, TerminalSnapshot } from "./src/domain.ts";
+import {
+  BG_START_PARAMETER_DESCRIPTIONS,
+  BG_START_TOOL_DESCRIPTION,
+  buildKillReport,
+  buildStatusResult,
+  buildTerminalResultMessage,
+} from "./src/prompt.ts";
+
+test("start descriptions identify the platform-specific shell contract", () => {
+  assert.match(BG_START_TOOL_DESCRIPTION, /sh -c on POSIX/);
+  assert.match(BG_START_TOOL_DESCRIPTION, /cmd\.exe \/d \/s \/c on Windows/);
+  assert.match(BG_START_PARAMETER_DESCRIPTIONS.command, /sh -c on POSIX/);
+  assert.match(
+    BG_START_PARAMETER_DESCRIPTIONS.command,
+    /cmd\.exe \/d \/s \/c on Windows/,
+  );
+});
+
+function view(overrides: Partial<OutputView> = {}): OutputView {
+  return { text: "", totalBytes: 0, truncatedBytes: 0, ...overrides };
+}
+
+function snap(overrides: Partial<TerminalSnapshot> = {}): TerminalSnapshot {
+  return {
+    id: "bt-1",
+    command: "sleep 999",
+    title: "test",
+    cwd: "/tmp",
+    pid: 123,
+    status: "done",
+    createdAt: Date.now() - 5_000,
+    settledAt: Date.now(),
+    exitCode: 0,
+    stdout: view(),
+    stderr: view(),
+    ...overrides,
+  };
+}
+
+test("kill report distinguishes killed / raced natural exit / already settled", () => {
+  const report = buildKillReport([
+    {
+      id: "bt-1",
+      title: "a",
+      status: "killed",
+      wasRunning: true,
+      killed: true,
+      exit: "SIGTERM",
+    },
+    {
+      id: "bt-2",
+      title: "b",
+      status: "done",
+      wasRunning: true,
+      killed: false,
+      exit: "exit 0",
+    },
+    {
+      id: "bt-3",
+      title: "c",
+      status: "failed",
+      wasRunning: false,
+      killed: false,
+      exit: "exit 1",
+    },
+  ]);
+  const lines = report.split("\n");
+  assert.equal(lines[0], 'Killed bt-1 "a" (SIGTERM).');
+  assert.match(lines[1], /exited on its own before the kill landed \(exit 0\)/);
+  assert.match(lines[2], /was already failed \(exit 1\)/);
+});
+
+test("status result marks head-truncated output with a pointer at the full log", () => {
+  const text = buildStatusResult(
+    snap({
+      stdout: view({
+        text: "tail of the log\n",
+        totalBytes: 5 * 1024 * 1024,
+        truncatedBytes: 5 * 1024 * 1024 - 16,
+        spillPath: "/tmp/bt-1.stdout.log",
+      }),
+    }),
+  );
+  assert.match(text, /stdout truncated: showing last /);
+  assert.match(text, /Full log: \/tmp\/bt-1\.stdout\.log/);
+});
+
+test("completion message reports kill vs exit and omits empty stderr", () => {
+  const killed = buildTerminalResultMessage(
+    snap({ status: "killed", exitCode: undefined, signal: "SIGTERM" }),
+  );
+  assert.match(killed, /was killed after/);
+  assert.ok(!killed.includes("stderr"), "empty stderr section omitted");
+
+  const failed = buildTerminalResultMessage(
+    snap({
+      status: "failed",
+      exitCode: 3,
+      stderr: view({ text: "boom\n", totalBytes: 5 }),
+    }),
+  );
+  assert.match(failed, /exited \(exit 3\)/);
+  assert.match(failed, /stderr:\nboom/);
+});
+
+test("completion output is a shorter tail than the detailed status view", () => {
+  const output = Array.from(
+    { length: 100 },
+    (_, index) => `line-${index + 1}`,
+  ).join("\n");
+  const terminal = snap({
+    stdout: view({ text: output, totalBytes: Buffer.byteLength(output) }),
+  });
+
+  const completion = buildTerminalResultMessage(terminal);
+  const status = buildStatusResult(terminal);
+
+  assert.ok(!completion.includes("line-1\n"));
+  assert.match(completion, /line-100/);
+  assert.match(completion, /stdout truncated/);
+  assert.match(status, /line-1\n/);
+});

package/agent/extensions/background-terminals/ps.test.ts

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  reconcileDashboardSelection,
+  type DashboardSelection,
+} from "./src/ui/ps.ts";
+import {
+  buildOutputLines,
+  createOutputLineCache,
+  sanitizeText,
+} from "./src/ui/output-view.ts";
+
+test("dashboard selection follows its terminal id and falls back by row", () => {
+  const selection: DashboardSelection = { id: "bt-7", index: 6 };
+
+  reconcileDashboardSelection(selection, [
+    { id: "bt-new" },
+    ...Array.from({ length: 8 }, (_, index) => ({ id: `bt-${index + 1}` })),
+  ]);
+  assert.deepEqual(selection, { id: "bt-7", index: 7 });
+
+  reconcileDashboardSelection(selection, [
+    ...Array.from({ length: 6 }, (_, index) => ({ id: `bt-${index + 1}` })),
+    { id: "bt-8" },
+    { id: "bt-9" },
+  ]);
+  assert.deepEqual(selection, { id: "bt-9", index: 7 });
+
+  reconcileDashboardSelection(selection, [{ id: "bt-1" }, { id: "bt-2" }]);
+  assert.deepEqual(selection, { id: "bt-2", index: 1 });
+
+  reconcileDashboardSelection(selection, []);
+  assert.deepEqual(selection, { id: undefined, index: 0 });
+});
+
+test("sanitizeText strips ANSI, tabs, and control characters", () => {
+  assert.equal(sanitizeText("\u001b[31mred\u001b[0m"), "red");
+  assert.equal(sanitizeText("\u001b[12345Cshifted"), "shifted");
+  assert.equal(sanitizeText("\u001b]0;window title\u0007output"), "output");
+  assert.equal(
+    sanitizeText("\u001b]8;;https://example.com\u001b\\link\u001b]8;;\u001b\\"),
+    "link",
+  );
+  assert.equal(sanitizeText("\u001b]0;title\u009coutput"), "output");
+  assert.equal(sanitizeText("\u009d0;title\u0007output"), "output");
+  assert.equal(sanitizeText("a\u0085b"), "ab");
+  assert.equal(sanitizeText("a\tb"), "a  b");
+  assert.equal(sanitizeText("a\u0007b\u0000c"), "abc");
+});
+
+test("output line cache reuses a version/width key and invalidates either dimension", () => {
+  const cache = createOutputLineCache();
+  const first = cache.get("first", 1, 80);
+  const sameKey = cache.get("different text is intentionally ignored", 1, 80);
+  assert.equal(sameKey, first);
+  assert.deepEqual(sameKey, ["first"]);
+
+  const newVersion = cache.get("second", 2, 80);
+  assert.notEqual(newVersion, first);
+  assert.deepEqual(newVersion, ["second"]);
+
+  const newWidth = cache.get("x".repeat(25), 2, 10);
+  assert.notEqual(newWidth, newVersion);
+  assert.ok(newWidth.length > 1);
+});
+
+test("buildOutputLines wraps long lines and keeps only the final CR segment", () => {
+  const lines = buildOutputLines("progress 1\rprogress 2\rdone\nnext", 80);
+  assert.deepEqual(lines, ["done", "next"]);
+  assert.deepEqual(buildOutputLines("progress 1\rprogress 2\r", 80), [
+    "progress 2",
+  ]);
+
+  const wrapped = buildOutputLines("x".repeat(25), 10);
+  assert.ok(wrapped.length > 1);
+  assert.equal(wrapped.join(""), "x".repeat(25));
+});
+
+test("buildOutputLines drops one trailing empty line from a trailing newline", () => {
+  assert.deepEqual(buildOutputLines("a\nb\n", 80), ["a", "b"]);
+  assert.deepEqual(buildOutputLines("a\n\n", 80), ["a", ""]);
+});

package/agent/extensions/background-terminals/result-delivery.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createDeferredResultDelivery } from "./src/result-delivery.ts";
+
+test("a result consumed by a kill/status is not delivered", () => {
+  const delivery = createDeferredResultDelivery<{
+    id: string;
+    output: string;
+  }>();
+
+  delivery.defer({ id: "bt-1", output: "done" });
+  delivery.consume(["bt-1"]);
+
+  assert.deepEqual(delivery.drain(), []);
+});
+
+test("unconsumed results are delivered once in settlement order", () => {
+  const delivery = createDeferredResultDelivery<{ id: string }>();
+  const first = { id: "bt-1" };
+  const second = { id: "bt-2" };
+
+  delivery.defer(first);
+  delivery.defer(second);
+
+  assert.deepEqual(delivery.drain(), [first, second]);
+  assert.deepEqual(delivery.drain(), []);
+});
+
+test("re-deferring the same id replaces rather than duplicates", () => {
+  const delivery = createDeferredResultDelivery<{ id: string; n: number }>();
+  delivery.defer({ id: "bt-1", n: 1 });
+  delivery.defer({ id: "bt-1", n: 2 });
+  assert.deepEqual(delivery.drain(), [{ id: "bt-1", n: 2 }]);
+});
+
+test("a drained result can be retained for retry after delivery fails", () => {
+  const delivery = createDeferredResultDelivery<{ id: string }>();
+  const result = { id: "bt-1" };
+  delivery.defer(result);
+
+  for (const drained of delivery.drain()) delivery.defer(drained);
+
+  assert.deepEqual(delivery.drain(), [result]);
+});

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

@@ -0,0 +1,87 @@
+/**
+ * Domain model for background terminals.
+ *
+ * A "terminal" is one long-running shell process started by the model. It
+ * receives no stdin (launched with stdin: "ignore"), captures stdout and
+ * stderr separately, and settles exactly once into a final state.
+ */
+
+import { Data } from "effect";
+
+export type TerminalStatus = "running" | "done" | "failed" | "killed";
+// "done"   = exited with code 0
+// "failed" = exited non-zero, or a spawn-level runtime error after start
+// "killed" = terminated by bg_kill, the /ps UI, or session teardown
+
+/** Read-only view over one captured output stream (stdout or stderr). */
+export interface OutputView {
+  /** Decoded, possibly head-trimmed text (bounded by the in-memory cap). */
+  readonly text: string;
+  /** True total bytes ever received on this stream. */
+  readonly totalBytes: number;
+  /** Bytes dropped from the head of the in-memory view (0 = complete). */
+  readonly truncatedBytes: number;
+  /** On-disk full capture; always the complete stream when spilling works. */
+  readonly spillPath?: string;
+}
+
+export interface TerminalSnapshot {
+  readonly id: string;
+  /** Exactly the command line the model asked to run. */
+  readonly command: string;
+  /** Short model-provided name, shown in listings and the UI. */
+  readonly title: string;
+  /** Resolved absolute cwd the process runs in. */
+  readonly cwd: string;
+  /** Undefined only if spawn itself failed before a pid was assigned. */
+  readonly pid?: number;
+  readonly status: TerminalStatus;
+  /** Date.now() at spawn. */
+  readonly createdAt: number;
+  /** Date.now() at settle (exit/kill). */
+  readonly settledAt?: number;
+  /** Set when the process exited via exit code (exactly one of exitCode/signal). */
+  readonly exitCode?: number;
+  /** Set when the process was terminated by a signal, e.g. "SIGTERM". */
+  readonly signal?: string;
+  /** Spawn error / kill-escalation notes, bounded. */
+  readonly errorText?: string;
+  readonly stdout: OutputView;
+  readonly stderr: OutputView;
+}
+
+export function formatElapsed(snap: TerminalSnapshot) {
+  const end = snap.settledAt ?? Date.now();
+  const totalSeconds = Math.max(0, Math.round((end - snap.createdAt) / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0
+    ? `${minutes}m${seconds.toString().padStart(2, "0")}s`
+    : `${seconds}s`;
+}
+
+/** "exit 0", "exit 137", "SIGTERM", or "running". */
+export function formatExit(snap: TerminalSnapshot) {
+  if (snap.status === "running") return "running";
+  if (snap.signal) return snap.signal;
+  if (snap.exitCode !== undefined) return `exit ${snap.exitCode}`;
+  return snap.status;
+}
+
+// --- Errors -------------------------------------------------------------------
+
+export class SpawnError extends Data.TaggedError("SpawnError")<{
+  readonly message: string;
+}> {}
+
+export class ConcurrencyLimitError extends Data.TaggedError(
+  "ConcurrencyLimitError",
+)<{
+  readonly message: string;
+}> {}
+
+export class UnknownTerminalError extends Data.TaggedError(
+  "UnknownTerminalError",
+)<{
+  readonly message: string;
+}> {}