@asterxsk/kiln 0.1.0 → 0.3.0

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

@@ -0,0 +1,629 @@
+/**
+ * Background terminals — start long-running shell processes the model can
+ * inspect and stop, but never write to (stdin is ignored at the OS level).
+ *
+ * Tools (for the LLM):
+ * - bg_start: fire-and-forget spawn (command, title, working_dir). Max 8
+ *   running at once. The model is notified exactly once when a process exits.
+ * - bg_status: peek at one terminal's status + tail-truncated output.
+ * - bg_list: list all tracked terminals (running and settled).
+ * - bg_kill: SIGTERM→SIGKILL the whole process tree; returns final state.
+ *
+ * While ≥1 process runs, a one-line widget above the editor shows
+ * "N background terminal(s) running • /ps to view". `/ps` opens a two-stage
+ * full-screen overlay (list → read-only detail with stdout/stderr toggle).
+ *
+ * Architecture: Effect v4 core (manager service behind one ManagedRuntime);
+ * this file is the async boundary where tool handlers run effects via
+ * runTool. Node stream plumbing inside the manager is plain callbacks.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { TerminalSnapshot } from "./src/domain.ts";
+import { TerminalManager, type TerminalManagerShape } from "./src/manager.ts";
+import {
+  BG_KILL_PARAMETER_DESCRIPTIONS,
+  BG_KILL_TOOL_DESCRIPTION,
+  BG_LIST_TOOL_DESCRIPTION,
+  BG_START_PARAMETER_DESCRIPTIONS,
+  BG_START_PROMPT_GUIDELINES,
+  BG_START_PROMPT_SNIPPET,
+  BG_START_TOOL_DESCRIPTION,
+  BG_STATUS_PARAMETER_DESCRIPTIONS,
+  BG_STATUS_TOOL_DESCRIPTION,
+  buildKillReport,
+  buildStartResult,
+  buildStatusResult,
+  buildTerminalResultMessage,
+  describeTerminal,
+} from "./src/prompt.ts";
+import { createDeferredResultDelivery } from "./src/result-delivery.ts";
+import { hideOrderedWidget, setOrderedWidget } from "./src/widget-order.ts";
+import {
+  createTerminalRuntime,
+  runTool,
+  type TerminalRuntime,
+} from "./src/runtime.ts";
+import { sanitizeText } from "./src/ui/output-view.ts";
+import { openTerminalPicker } from "./src/ui/ps.ts";
+import { createBashTool } from "@earendil-works/pi-coding-agent";
+
+const WIDGET_KEY = "background-terminals";
+
+const AUTO_PROMOTE_MS = 50_000;
+const AUTO_PROMOTE_SEC = AUTO_PROMOTE_MS / 1000;
+
+const RESULT_PREVIEW_LINES = 10;
+
+/** Tool call line: bold-white tool name, 2-space indent (Box adds 1 + Text 1). */
+function renderToolCall(name: string, theme: any): Text {
+  return new Text(theme.fg("toolTitle", theme.bold(name)), 1, 0);
+}
+
+/** Tool result: grey text at 2-space indent, collapsed to a short preview. */
+function renderToolResult(result: any, theme: any): Text {
+  const text = (result?.content ?? [])
+    .filter((c: any) => c?.type === "text" && typeof c?.text === "string")
+    .map((c: any) => c.text)
+    .join("\n");
+  if (!text) return new Text("", 1, 0);
+  const lines = text.split("\n");
+  const preview = lines.slice(0, RESULT_PREVIEW_LINES);
+  let out = theme.fg("toolOutput", preview.join("\n"));
+  if (lines.length > RESULT_PREVIEW_LINES) {
+    out += theme.fg("dim", `\n... (${lines.length - RESULT_PREVIEW_LINES} more lines)`);
+  }
+  return new Text(out, 1, 0);
+}
+
+export default function (pi: ExtensionAPI) {
+  let runtime: TerminalRuntime | undefined;
+  let managerPromise: Promise<TerminalManagerShape> | undefined;
+  let sessionContext: ExtensionContext | undefined;
+  let ui: ExtensionUIContext | undefined;
+  let unsubStatus: (() => void) | undefined;
+  const resultDelivery = createDeferredResultDelivery<TerminalSnapshot>();
+
+  const getRuntime = () => (runtime ??= createTerminalRuntime());
+
+  /** Resolve the manager service once per runtime and wire the extension hooks. */
+  const getManager = () => {
+    managerPromise ??= getRuntime()
+      .runPromise(TerminalManager)
+      .then((manager) => {
+        manager.view.setOnSettled(onSettled);
+        unsubStatus?.();
+        unsubStatus = manager.view.subscribe(() => updateWidget(manager));
+        updateWidget(manager);
+        return manager;
+      });
+    return managerPromise;
+  };
+
+  /** One-line widget directly above the editor, only while ≥1 is running.
+   * Called on every manager notification (including per-output-chunk), so it
+   * only touches setWidget when the running count actually changes —
+   * replacing the widget factory hundreds of times a second would churn
+   * component creation for no visible difference. */
+  let widgetRunning = 0;
+  const updateWidget = (manager: TerminalManagerShape) => {
+    if (!ui) return;
+    try {
+      const running = manager.view
+        .list()
+        .filter((snap) => snap.status === "running").length;
+      if (running === widgetRunning) return;
+      widgetRunning = running;
+      if (running === 0) {
+        // Ordered helper keeps todos above us and subagents below us.
+        hideOrderedWidget(ui, WIDGET_KEY);
+        return;
+      }
+      setOrderedWidget(ui, WIDGET_KEY, (_tui, theme) => {
+        const line =
+          theme.fg("warning", "■ ") +
+          theme.fg(
+            "text",
+            `${running} background terminal${running === 1 ? "" : "s"} running`,
+          ) +
+          theme.fg("dim", " • ") +
+          theme.fg("accent", "/ps") +
+          theme.fg("dim", " to view");
+        return { render: () => [line], invalidate: () => {} };
+      });
+    } catch {
+      // UI may be unavailable (print/RPC modes or teardown).
+    }
+  };
+
+  const deliverResult = (snap: TerminalSnapshot) => {
+    try {
+      pi.sendMessage(
+        {
+          customType: "background-terminal-result",
+          content: buildTerminalResultMessage(snap),
+          display: true,
+          details: {
+            id: snap.id,
+            title: snap.title,
+            status: snap.status,
+            exitCode: snap.exitCode,
+            signal: snap.signal,
+          },
+        },
+        // followUp: queued until the agent has no more tool calls — never
+        // interrupts a mid-turn stream. triggerTurn: wakes the model
+        // immediately iff idle; if busy, the queued follow-up is delivered
+        // when the current run settles. Either way exactly one delivery.
+        { deliverAs: "followUp", triggerTurn: true },
+      );
+      return true;
+    } catch (error) {
+      // Session may be shutting down, but retain the snapshot so any later
+      // agent-settled flush can retry instead of silently dropping it.
+      console.error("background-terminals: failed to deliver result", error);
+      return false;
+    }
+  };
+
+  const flushResults = () => {
+    for (const snap of resultDelivery.drain()) {
+      if (!deliverResult(snap)) resultDelivery.defer(snap);
+    }
+  };
+
+  const onSettled = (snap: TerminalSnapshot, consumed: boolean) => {
+    if (consumed) {
+      // An in-flight bg_kill is returning this settlement itself.
+      resultDelivery.consume([snap.id]);
+      return;
+    }
+    // Defer a deep-enough copy: the live snapshot's output views keep
+    // mutating (late flushes) after settle.
+    resultDelivery.defer({
+      ...snap,
+      stdout: { ...snap.stdout },
+      stderr: { ...snap.stderr },
+    });
+    if (sessionContext?.isIdle()) flushResults();
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    sessionContext = ctx;
+    if (ctx.hasUI) ui = ctx.ui;
+  });
+
+  // Drain deferred results when the agent settles: together with the
+  // isIdle() fast path above and the Map-keyed delivery (drain clears),
+  // double delivery is structurally impossible — whoever drains first wins.
+  pi.on("agent_settled", flushResults);
+
+  // /new, /resume, /fork, /reload, and quit all emit session_shutdown for
+  // the old extension instance. Processes never survive a session
+  // transition: disposing the runtime runs the manager finalizer →
+  // disposeAll → every entry scope → SIGTERM→SIGKILL tree kill, each close
+  // bounded so a wedged process cannot hang shutdown.
+  pi.on("session_shutdown", async () => {
+    sessionContext = undefined;
+    resultDelivery.clear();
+    unsubStatus?.();
+    unsubStatus = undefined;
+    try {
+      hideOrderedWidget(ui, WIDGET_KEY);
+    } catch {
+      // UI may already be gone.
+    }
+    widgetRunning = 0;
+    ui = undefined;
+    const closing = runtime;
+    runtime = undefined;
+    managerPromise = undefined;
+    await closing?.dispose();
+  });
+
+  // --- Tools -------------------------------------------------------------
+
+  pi.registerTool({
+    name: "bg_start",
+    label: "Start Background Terminal",
+    renderCall: (_args: any, theme: any) => renderToolCall("bg_start", theme),
+    renderResult: (result: any, _options: any, theme: any) => renderToolResult(result, theme),
+    description: BG_START_TOOL_DESCRIPTION,
+    promptSnippet: BG_START_PROMPT_SNIPPET,
+    promptGuidelines: BG_START_PROMPT_GUIDELINES,
+    parameters: Type.Object({
+      command: Type.String({
+        description: BG_START_PARAMETER_DESCRIPTIONS.command,
+      }),
+      title: Type.String({
+        description: BG_START_PARAMETER_DESCRIPTIONS.title,
+      }),
+      working_dir: Type.Optional(
+        Type.String({
+          description: BG_START_PARAMETER_DESCRIPTIONS.workingDir,
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const manager = await getManager();
+
+      const command = params.command.trim();
+      if (!command) throw new Error("command must not be empty.");
+
+      const cwd = path.resolve(ctx.cwd, params.working_dir ?? ".");
+      if (!fs.existsSync(cwd) || !fs.statSync(cwd).isDirectory()) {
+        throw new Error(`working_dir is not a directory: ${cwd}`);
+      }
+
+      // Collapse whitespace (a newline inside a one-line UI row desyncs the
+      // TUI renderer) before bounding the length.
+      const title =
+        params.title.replace(/\s+/g, " ").trim().slice(0, 80) || "terminal";
+      const snap = await runTool(
+        getRuntime(),
+        manager.start({ command, title, cwd }),
+      );
+
+      return {
+        content: [{ type: "text", text: buildStartResult(snap) }],
+        details: { id: snap.id, title: snap.title, cwd, pid: snap.pid },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "bg_status",
+    label: "Check Background Terminal",
+    renderCall: (_args: any, theme: any) => renderToolCall("bg_status", theme),
+    renderResult: (result: any, _options: any, theme: any) => renderToolResult(result, theme),
+    description: BG_STATUS_TOOL_DESCRIPTION,
+    parameters: Type.Object({
+      id: Type.String({ description: BG_STATUS_PARAMETER_DESCRIPTIONS.id }),
+    }),
+    async execute(_toolCallId, params) {
+      const manager = await getManager();
+      const snap = manager.view.get(params.id);
+      if (!snap) {
+        const known = manager.view.list().map((s) => s.id);
+        throw new Error(
+          `Unknown terminal id "${params.id}". Known: ${known.join(", ") || "none"}.`,
+        );
+      }
+
+      // This status is returning the settlement itself; a pending automatic
+      // follow-up for the same settle would be a duplicate.
+      if (snap.status !== "running") resultDelivery.consume([snap.id]);
+
+      return {
+        content: [{ type: "text", text: buildStatusResult(snap) }],
+        details: {
+          id: snap.id,
+          status: snap.status,
+          pid: snap.pid,
+          exitCode: snap.exitCode,
+          signal: snap.signal,
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "bg_list",
+    label: "List Background Terminals",
+    renderCall: (_args: any, theme: any) => renderToolCall("bg_list", theme),
+    renderResult: (result: any, _options: any, theme: any) => renderToolResult(result, theme),
+    description: BG_LIST_TOOL_DESCRIPTION,
+    parameters: Type.Object({}),
+    async execute() {
+      const manager = await getManager();
+      const terminals = manager.view.list();
+      const text =
+        terminals.length === 0
+          ? "No background terminals."
+          : terminals.map((snap) => describeTerminal(snap)).join("\n");
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          terminals: terminals.map((snap) => ({
+            id: snap.id,
+            title: snap.title,
+            status: snap.status,
+            pid: snap.pid,
+          })),
+        },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "bg_kill",
+    label: "Kill Background Terminals",
+    renderCall: (_args: any, theme: any) => renderToolCall("bg_kill", theme),
+    renderResult: (result: any, _options: any, theme: any) => renderToolResult(result, theme),
+    description: BG_KILL_TOOL_DESCRIPTION,
+    parameters: Type.Object({
+      ids: Type.Array(Type.String(), {
+        description: BG_KILL_PARAMETER_DESCRIPTIONS.ids,
+      }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const manager = await getManager();
+      const ids = [...new Set(params.ids)];
+      if (ids.length === 0)
+        throw new Error("Provide at least one terminal id.");
+
+      const known = manager.view.list().map((snap) => snap.id);
+      const unknown = ids.filter((id) => !manager.view.get(id));
+      if (unknown.length > 0) {
+        throw new Error(
+          `Unknown terminal id(s): ${unknown.join(", ")}. Known: ${known.join(", ") || "none"}.`,
+        );
+      }
+
+      const report = await runTool(getRuntime(), manager.kill(ids), {
+        signal,
+        interruptMessage:
+          "Kill wait aborted; termination continues in the background.",
+      });
+
+      // Settlement may have happened before this kill began (or during it,
+      // via the killInterest consumed flag). Remove any deferred automatic
+      // delivery now that this tool returns the final state itself.
+      resultDelivery.consume(ids);
+
+      return {
+        content: [{ type: "text", text: buildKillReport(report) }],
+        details: {
+          results: report.map((entry) => ({
+            id: entry.id,
+            title: entry.title,
+            status: entry.status,
+            killed: entry.killed,
+          })),
+        },
+      };
+    },
+  });
+
+  // --- Result message rendering ------------------------------------------
+
+  pi.registerMessageRenderer(
+    "background-terminal-result",
+    (message, { expanded }, theme) => {
+      const details = (message.details ?? {}) as {
+        id?: string;
+        title?: string;
+        status?: string;
+        exitCode?: number;
+        signal?: string;
+      };
+      const failed = details.status === "failed";
+      const killed = details.status === "killed";
+      const icon = failed
+        ? theme.fg("error", "x")
+        : killed
+          ? theme.fg("muted", "■")
+          : theme.fg("success", "■");
+      const how = killed
+        ? "killed"
+        : (details.signal ?? `exit ${details.exitCode ?? "?"}`);
+      const header =
+        `${icon} ` +
+        theme.fg("accent", theme.bold(`terminal ${details.id ?? "?"}`)) +
+        theme.fg("muted", ` · ${details.title ?? ""} · ${how}`);
+
+      const content =
+        typeof message.content === "string" ? message.content : "";
+      // Remove only the summary line; the Error line (when present) is part
+      // of the actual result and must remain visible. The body carries raw
+      // process output — sanitize ANSI/control chars or the transcript smears.
+      const body = sanitizeText(content.split("\n").slice(1).join("\n").trim());
+
+      if (expanded) {
+        const md = new Markdown(`${body}`, 0, 0, getMarkdownTheme());
+        const container = new Text(header, 0, 0);
+        return {
+          render: (width: number) => [
+            ...container.render(width),
+            ...md.render(width),
+          ],
+          invalidate: () => {
+            container.invalidate();
+            md.invalidate();
+          },
+        };
+      }
+
+      const previewLines = body.split("\n").slice(0, 8);
+      let text = header;
+      for (const line of previewLines)
+        text += `\n${theme.fg("toolOutput", line)}`;
+      if (body.split("\n").length > 8)
+        text += `\n${theme.fg("dim", "... (ctrl+o to expand)")}`;
+      return new Text(text, 0, 0);
+    },
+  );
+
+  // --- Auto-promote long bash to background ---------------------------------
+  // If a bash tool call exceeds 50s, abort the blocking call, restart it
+  // as a background terminal, and alert the agent + UI. The background
+  // result is still delivered as a follow-up when it settles.
+  const baseBashTool: any = createBashTool(process.cwd());
+  pi.registerTool({
+    ...baseBashTool,
+    description: `${baseBashTool.description} If execution exceeds ${AUTO_PROMOTE_SEC}s it is automatically promoted to a background terminal (check with bg_status/bg_list or /ps; result arrives as follow-up).`,
+    async execute(
+      toolCallId: string,
+      params: any,
+      signal: AbortSignal | undefined,
+      onUpdate: any,
+      ctx: ExtensionContext,
+    ) {
+      const command: string = params.command;
+      const cwd = (ctx as any).cwd ?? process.cwd();
+      const title = command.replace(/\s+/g, " ").trim().slice(0, 80) || "bash auto-promoted";
+
+      // Delegate tool bound to the current cwd so built-in bash semantics
+      // (shell, env, truncation) stay identical for the fast path.
+      const delegateTool: any = createBashTool(cwd);
+
+      let lastPartial = "";
+      const wrappedOnUpdate = (update: any) => {
+        try {
+          const text = update?.content?.[0]?.text;
+          if (typeof text === "string") lastPartial = text;
+        } catch {}
+        if (onUpdate) try { onUpdate(update); } catch {}
+      };
+
+      const execAbortController = new AbortController();
+      const onIncomingAbort = () => execAbortController.abort();
+      if (signal) {
+        if (signal.aborted) execAbortController.abort();
+        else signal.addEventListener("abort", onIncomingAbort, { once: true });
+      }
+
+      const execPromise: Promise<{ kind: "done"; res: any } | { kind: "error"; err: unknown }> = delegateTool
+        .execute(toolCallId, params, execAbortController.signal, wrappedOnUpdate, ctx as any)
+        .then(
+          (res: any) => ({ kind: "done" as const, res }),
+          (err: unknown) => ({ kind: "error" as const, err }),
+        );
+
+      let timerId: ReturnType<typeof setTimeout> | undefined;
+      const timerPromise = new Promise<{ kind: "promote" }>((resolve) => {
+        timerId = setTimeout(() => resolve({ kind: "promote" }), AUTO_PROMOTE_MS);
+      });
+
+      const race = (await Promise.race([execPromise, timerPromise])) as
+        | { kind: "done"; res: any }
+        | { kind: "error"; err: unknown }
+        | { kind: "promote" };
+
+      if (race.kind !== "promote") {
+        if (timerId) clearTimeout(timerId);
+        if (signal) signal.removeEventListener("abort", onIncomingAbort);
+        if (race.kind === "done") return race.res;
+        throw race.err;
+      }
+
+      // Timer won — promote to background terminal.
+      // Abort the original blocking execution (kills its process tree).
+      execAbortController.abort();
+      if (signal) signal.removeEventListener("abort", onIncomingAbort);
+
+      // If the caller already aborted (Esc), don't promote — just propagate.
+      if (signal?.aborted) {
+        try {
+          const settled = await execPromise;
+          if (settled.kind === "error") throw settled.err;
+          return (settled as any).res;
+        } catch (e) {
+          throw e;
+        }
+      }
+
+      // Let the aborted exec settle (or timeout after 2s if it hangs).
+      try {
+        await Promise.race([
+          execPromise.catch(() => {}),
+          new Promise((r) => setTimeout(r, 2000)),
+        ]);
+      } catch {}
+
+      let snap: TerminalSnapshot | undefined;
+      let spawnError: unknown;
+      try {
+        const manager = await getManager();
+        snap = await runTool(getRuntime(), manager.start({ command, title, cwd }));
+      } catch (e) {
+        spawnError = e;
+      }
+
+      if (!snap || spawnError) {
+        const msg = spawnError instanceof Error ? spawnError.message : String(spawnError ?? "unknown error");
+        const text = [
+          `⚠️ Bash command exceeded ${AUTO_PROMOTE_SEC}s but could not be promoted to a background terminal: ${msg}`,
+          "",
+          `Command: ${command}`,
+          "",
+          lastPartial ? `Partial output (first ${AUTO_PROMOTE_SEC}s, truncated):\n${lastPartial.slice(-3000)}` : "No output captured before promotion attempt.",
+          "",
+          "The original blocking command was aborted. Retry with bg_start directly or free a slot with bg_kill (/ps).",
+        ].join("\n");
+        if ((ctx as any).hasUI) {
+          try { (ctx as any).ui.notify(`Bash auto-promote failed: ${msg}`, "warning"); } catch {}
+        }
+        return {
+          content: [{ type: "text", text }],
+          details: { promoted: false, error: msg, command, cwd, partialOutput: lastPartial },
+        };
+      }
+
+      const partialPreview = lastPartial ? lastPartial.slice(-3000) : "(no output yet)";
+      const text = [
+        `⏳ Bash command exceeded ${AUTO_PROMOTE_SEC}s and was automatically moved to a background terminal.`,
+        "",
+        `• Terminal ID: ${snap.id}`,
+        `• Title: ${snap.title}`,
+        `• Command: ${command}`,
+        `• CWD: ${cwd}`,
+        `• PID: ${snap.pid ?? "pending"}`,
+        "",
+        "The original blocking bash call was aborted and the command was restarted as a background terminal. It continues running in the background.",
+        `Use bg_status with id "${snap.id}" or bg_list or /ps to inspect output. Its result will be delivered automatically when it finishes.`,
+        "",
+        lastPartial ? `Partial output captured in first ${AUTO_PROMOTE_SEC}s (truncated):\n${partialPreview}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      if ((ctx as any).hasUI) {
+        try { (ctx as any).ui.notify(`Bash auto-promoted to background terminal ${snap.id} (${snap.title})`, "info"); } catch {}
+      }
+
+      return {
+        content: [{ type: "text", text }],
+        details: { promoted: true, id: snap.id, title: snap.title, pid: snap.pid, cwd, command },
+      };
+    },
+  });
+
+  // --- Command ------------------------------------------------------------
+
+  pi.registerCommand("ps", {
+    description: "List and inspect background terminals",
+    handler: async (_args, ctx) => {
+      const manager = await getManager();
+      if (ctx.mode !== "tui") {
+        if (ctx.hasUI) {
+          const terminals = manager.view.list();
+          ctx.ui.notify(
+            terminals.length === 0
+              ? "No background terminals."
+              : terminals.map((snap) => describeTerminal(snap)).join("\n"),
+            "info",
+          );
+        }
+        return;
+      }
+      if (manager.view.size() === 0) {
+        ctx.ui.notify(
+          "No background terminals yet. The agent starts them with bg_start.",
+          "info",
+        );
+        return;
+      }
+      await openTerminalPicker(ctx, manager.view);
+    },
+  });
+}

package/agent.bak.20260905-190020/extensions/background-terminals/install.ps1

@@ -0,0 +1,23 @@
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+$extDir = $PSScriptRoot
+if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
+if (-not (Test-Path "$extDir/package.json")) {
+  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
+  exit 0
+}
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "$extDir/package-lock.json") {
+  Write-Host "  - npm ci" -ForegroundColor DarkGray
+  npm --prefix $extDir ci --no-audit --no-fund
+} else {
+  Write-Host "  - npm install" -ForegroundColor DarkGray
+  npm --prefix $extDir install --no-audit --no-fund
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Write-Host "  + done" -ForegroundColor Green

package/agent.bak.20260905-190020/extensions/background-terminals/install.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ ! -f "$EXT_DIR/package.json" ]; then
+  echo "  · no package.json — skipping"
+  exit 0
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "  ✖ npm not found — install Node.js 22+" >&2
+  exit 1
+fi
+if [ -f "$EXT_DIR/package-lock.json" ]; then
+  echo "  · npm ci"
+  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
+else
+  echo "  · npm install"
+  npm --prefix "$EXT_DIR" install --no-audit --no-fund
+fi
+echo "  ✓ done"