@ian-pascoe/pi-termctrl 0.0.0

package/src/exit-notification.ts

@@ -0,0 +1,113 @@
+import type { MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import type { ExitNotice } from "./termctrl-registry.js";
+import type { TerminalExit } from "./terminal-driver.js";
+
+/** `customType` of Exit notification messages. */
+export const EXIT_NOTIFICATION_TYPE = "pi-termctrl.exit";
+
+const ExitNotificationDetailsSchema = Type.Object({
+  exits: Type.Array(
+    Type.Object({
+      id: Type.String(),
+      kind: Type.Union([Type.Literal("terminal"), Type.Literal("background_job")]),
+      command: Type.String(),
+      exit_code: Type.Union([Type.Number(), Type.Null()]),
+      signal: Type.Union([Type.String(), Type.Null()]),
+      duration_ms: Type.Number(),
+    }),
+  ),
+});
+/** Structured details carried by an Exit notification message. */
+export type ExitNotificationDetails = Static<typeof ExitNotificationDetailsSchema>;
+
+/** Describe how a process ended in words the agent and user both read. */
+export function describeExitStatus(exit: TerminalExit): string {
+  if (exit.signal !== null && exit.code !== null)
+    return `exited with code ${exit.code} (${exit.signal})`;
+  if (exit.signal !== null) return `ended by ${exit.signal}`;
+  return `exited with code ${exit.code ?? "unknown"}`;
+}
+
+/** Format a duration as `850ms`, `12s`, `3m 4s` or `2h 5m`. */
+export function formatDuration(milliseconds: number): string {
+  if (milliseconds < 1_000) return `${Math.max(0, Math.round(milliseconds))}ms`;
+  const seconds = Math.round(milliseconds / 1_000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+  return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+function lastLines(output: string, count: number): string {
+  if (count === 0) return "";
+  const lines = output.replace(/\n+$/u, "").split("\n");
+  return lines.slice(-count).join("\n");
+}
+
+function headline(notice: ExitNotice): string {
+  const label = notice.kind === "terminal" ? "Terminal" : "Background job";
+  return `${label} ${notice.id} ${describeExitStatus(notice.exit)} after ${formatDuration(notice.durationMs)}: ${notice.command}`;
+}
+
+/** The text and details of one Exit notification message. */
+export interface ExitNotificationMessage {
+  readonly content: string;
+  readonly details: ExitNotificationDetails;
+}
+
+/** Build the message text and details for one batch of Exit notifications. */
+export function formatExitNotification(
+  notices: readonly ExitNotice[],
+  tailLines: number,
+): ExitNotificationMessage {
+  const content = notices
+    .map((notice) => {
+      const tail = lastLines(notice.output, tailLines);
+      const source = notice.kind === "terminal" ? "final screen" : "output";
+      return tail === ""
+        ? headline(notice)
+        : `${headline(notice)}\nLast lines of ${source}:\n${tail}`;
+    })
+    .join("\n\n");
+  return {
+    content,
+    details: {
+      exits: notices.map((notice) => ({
+        id: notice.id,
+        kind: notice.kind === "job" ? ("background_job" as const) : ("terminal" as const),
+        command: notice.command,
+        exit_code: notice.exit.code,
+        signal: notice.exit.signal,
+        duration_ms: notice.durationMs,
+      })),
+    },
+  };
+}
+
+type ExitNotificationRenderer = MessageRenderer<ExitNotificationDetails>;
+type RenderedMessage = Parameters<ExitNotificationRenderer>[0];
+
+function messageText(content: RenderedMessage["content"]): string {
+  if (Value.Check(Type.String(), content)) return content;
+  return content.map((part) => (part.type === "text" ? part.text : "")).join("");
+}
+
+/** Compact renderer: one line per exit, with the full text when expanded. */
+export const renderExitNotification: ExitNotificationRenderer = (
+  message,
+  options,
+  theme,
+): Component => {
+  if (options.expanded || !Value.Check(ExitNotificationDetailsSchema, message.details)) {
+    return new Text(theme.fg("muted", messageText(message.content)), options.outputPad, 0);
+  }
+  const lines = message.details.exits.map((exit) => {
+    const failed = exit.exit_code !== 0 || exit.signal !== null;
+    const status = describeExitStatus({ code: exit.exit_code, signal: exit.signal });
+    return `${theme.fg(failed ? "warning" : "success", "■")} ${theme.bold(exit.id)} ${status} · ${formatDuration(exit.duration_ms)} · ${theme.fg("muted", exit.command)}`;
+  });
+  return new Text(lines.join("\n"), options.outputPad, 0);
+};

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./pi-termctrl-extension.js";

package/src/pi-termctrl-extension.ts

@@ -0,0 +1,186 @@
+import {
+  getAgentDir,
+  getShellConfig,
+  SettingsManager,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ExtensionFactory,
+  type SessionShutdownEvent,
+} from "@earendil-works/pi-coding-agent";
+import { createBashReplacement, RunningBashCalls } from "./bash-replacement.js";
+import {
+  EXIT_NOTIFICATION_TYPE,
+  formatExitNotification,
+  renderExitNotification,
+} from "./exit-notification.js";
+import { TermctrlPsController } from "./ps-panel.js";
+import { resolveTermctrlBinary, type TermctrlBinaryResolution } from "./termctrl-binary.js";
+import { createTermctrlDriver } from "./termctrl-driver.js";
+import { TermctrlRegistry } from "./termctrl-registry.js";
+import { resolveTermctrlSettings, type TerminalViewport } from "./pi-termctrl-settings.js";
+import type { TerminalDriver } from "./terminal-driver.js";
+import {
+  createTerminalListTool,
+  createTerminalSendTool,
+  createTerminalStartTool,
+  createTerminalStopTool,
+  type TerminalShell,
+} from "./terminal-tools.js";
+
+/** Collaborators tests replace; production uses Pi's agent directory and the packaged binary. */
+export interface PiTermctrlExtensionOptions {
+  readonly getAgentDirectory?: () => string;
+  readonly resolveBinary?: () => TermctrlBinaryResolution;
+  readonly createDriver?: (binaryPath: string) => Promise<TerminalDriver>;
+}
+
+interface ActiveSession {
+  readonly owner: string;
+  readonly calls: RunningBashCalls;
+  readonly ps: TermctrlPsController;
+  readonly shell: () => TerminalShell;
+  readonly viewport: TerminalViewport;
+}
+
+/**
+ * Owns one Pi session's binding to the process-wide registry, its tools, and its UI. Terminal
+ * tools register at load so hosts that check tool availability before `session_start`, such as
+ * Minimal Subagents child agents, see them; tools that depend on settings register at
+ * `session_start`.
+ */
+class PiTermctrlController {
+  private active: ActiveSession | undefined;
+  private readonly binary: TermctrlBinaryResolution;
+  private readonly registry: TermctrlRegistry;
+
+  constructor(
+    private readonly pi: ExtensionAPI,
+    private readonly options: PiTermctrlExtensionOptions,
+  ) {
+    const binary = (options.resolveBinary ?? resolveTermctrlBinary)();
+    const createDriver = options.createDriver ?? createTermctrlDriver;
+    this.binary = binary;
+    this.registry = TermctrlRegistry.acquire({
+      createDriver: () =>
+        binary.kind === "available"
+          ? createDriver(binary.path)
+          : Promise.reject(new Error(`termctrl is unavailable: ${binary.reason}`)),
+    });
+  }
+
+  register(): void {
+    this.pi.registerMessageRenderer(EXIT_NOTIFICATION_TYPE, renderExitNotification);
+    this.pi.registerCommand("ps", {
+      description: "Show and stop Terminals and Background jobs",
+      handler: async () => {
+        await this.active?.ps.open();
+      },
+    });
+    if (this.binary.kind === "available") {
+      const runtime = {
+        registry: this.registry,
+        shell: () => this.session().shell(),
+        viewport: () => this.session().viewport,
+      };
+      this.pi.registerTool(createTerminalStartTool(runtime));
+      this.pi.registerTool(createTerminalSendTool(runtime));
+      this.registerManagementTools();
+    }
+    this.pi.on("session_start", (_event, context) => this.start(context));
+    this.pi.on("session_shutdown", (event) => this.shutdown(event));
+  }
+
+  private registerManagementTools(): void {
+    this.pi.registerTool(createTerminalStopTool(this.registry));
+    this.pi.registerTool(createTerminalListTool(this.registry));
+  }
+
+  private session(): ActiveSession {
+    if (this.active === undefined) throw new Error("Pi Termctrl has no active session.");
+    return this.active;
+  }
+
+  private start(context: ExtensionContext): void {
+    const settingsManager = SettingsManager.create(
+      context.cwd,
+      (this.options.getAgentDirectory ?? getAgentDir)(),
+      { projectTrusted: context.isProjectTrusted() },
+    );
+    const settings = resolveTermctrlSettings(settingsManager);
+    if (settings.warnings.length > 0) {
+      context.ui.notify(`Pi Termctrl settings:\n- ${settings.warnings.join("\n- ")}`, "warning");
+    }
+    const registry = this.registry;
+    const owner = context.sessionManager.getSessionId();
+    registry.bindOwner(owner, (notices) => {
+      const message = formatExitNotification(notices, settings.exitTailLines);
+      this.pi.sendMessage(
+        {
+          customType: EXIT_NOTIFICATION_TYPE,
+          content: message.content,
+          display: true,
+          details: message.details,
+        },
+        { triggerTurn: true, deliverAs: "steer" },
+      );
+    });
+
+    const shellPath = settingsManager.getShellPath();
+    const commandPrefix = settingsManager.getShellCommandPrefix();
+    if (this.binary.kind === "missing") {
+      context.ui.notify(
+        `Pi Termctrl: Terminal tools are unavailable: ${this.binary.reason}`,
+        "warning",
+      );
+      if (settings.replaceBash) this.registerManagementTools();
+    }
+    const currentRegistry = () => TermctrlRegistry.current() ?? registry;
+    const calls = new RunningBashCalls(currentRegistry);
+    if (settings.replaceBash) {
+      this.pi.registerTool(
+        createBashReplacement({
+          cwd: context.cwd,
+          commandPrefix,
+          shellPath,
+          registry: currentRegistry,
+          calls,
+        }),
+      );
+    }
+    this.active = {
+      owner,
+      calls,
+      ps: new TermctrlPsController(registry, context),
+      shell: () => {
+        const shell = getShellConfig(shellPath);
+        return { shell: shell.shell, args: shell.args, commandPrefix };
+      },
+      viewport: settings.defaultViewport,
+    };
+  }
+
+  private async shutdown(event: SessionShutdownEvent): Promise<void> {
+    const active = this.active;
+    this.active = undefined;
+    if (active === undefined) return;
+    active.calls.dispose();
+    const reload = event.reason === "reload";
+    active.ps.dispose(!reload);
+    if (reload) {
+      this.registry.unbindOwner(active.owner);
+      return;
+    }
+    await this.registry.shutdownOwner(active.owner);
+  }
+}
+
+/** Compose the Pi Termctrl extension. Nothing starts until a Terminal or Background job is needed. */
+export function createPiTermctrlExtension(
+  options: PiTermctrlExtensionOptions = {},
+): ExtensionFactory {
+  return (pi) => new PiTermctrlController(pi, options).register();
+}
+
+const piTermctrlExtension = createPiTermctrlExtension();
+
+export default piTermctrlExtension;

package/src/pi-termctrl-settings.ts

@@ -0,0 +1,128 @@
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+const VIEWPORT_LIMIT = 1_000;
+const EXIT_TAIL_LIMIT = 1_000;
+
+type JsonObject = { readonly [key: string]: JsonValue };
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
+type SettingsScope = "global" | "project";
+
+/** A Terminal's size in character cells. */
+export interface TerminalViewport {
+  readonly cols: number;
+  readonly rows: number;
+}
+
+/** The effective `settings.termctrl` values after layering global and trusted project settings. */
+export interface ResolvedTermctrlSettings {
+  readonly replaceBash: boolean;
+  readonly defaultViewport: TerminalViewport;
+  readonly exitTailLines: number;
+  readonly warnings: readonly string[];
+}
+
+/** Pi's core settings type or a test document carrying the extension-owned `termctrl` value. */
+export type TermctrlSettingsDocumentInput =
+  | ReturnType<SettingsManager["getGlobalSettings"]>
+  | { readonly termctrl?: JsonValue };
+
+/** Reads Pi's already trust-filtered global and project settings documents. */
+export interface TermctrlSettingsReader {
+  getGlobalSettings(): TermctrlSettingsDocumentInput;
+  getProjectSettings(): TermctrlSettingsDocumentInput;
+}
+
+interface TermctrlLayer {
+  replaceBash?: boolean;
+  cols?: number;
+  rows?: number;
+  exitTailLines?: number;
+}
+
+export const DEFAULT_TERMCTRL_SETTINGS: Omit<ResolvedTermctrlSettings, "warnings"> = {
+  replaceBash: true,
+  defaultViewport: { cols: 120, rows: 40 },
+  exitTailLines: 20,
+};
+
+const JsonObjectSchema = Type.Record(Type.String(), Type.Any());
+const SettingsDocumentSchema = Type.Object({ termctrl: Type.Optional(Type.Any()) });
+const BooleanSchema = Type.Boolean();
+const ViewportDimensionSchema = Type.Integer({ minimum: 1, maximum: VIEWPORT_LIMIT });
+const ExitTailLinesSchema = Type.Integer({ minimum: 0, maximum: EXIT_TAIL_LIMIT });
+
+function isJsonObject(value: JsonValue): value is JsonObject {
+  return Value.Check(JsonObjectSchema, value);
+}
+
+function readLayer(
+  document: TermctrlSettingsDocumentInput,
+  scope: SettingsScope,
+  warnings: string[],
+): TermctrlLayer {
+  const layer: TermctrlLayer = {};
+  if (!Value.Check(SettingsDocumentSchema, document)) {
+    warnings.push(`${scope} settings: expected a JSON object`);
+    return layer;
+  }
+  const section: JsonValue | undefined = document.termctrl;
+  if (section === undefined) return layer;
+  if (!isJsonObject(section)) {
+    warnings.push(`${scope} termctrl: expected a JSON object`);
+    return layer;
+  }
+  for (const [key, value] of Object.entries(section)) {
+    const path = `${scope} termctrl.${key}`;
+    switch (key) {
+      case "replaceBash":
+        if (Value.Check(BooleanSchema, value)) layer.replaceBash = value;
+        else warnings.push(`${path}: expected a boolean`);
+        break;
+      case "exitTailLines":
+        if (Value.Check(ExitTailLinesSchema, value)) layer.exitTailLines = value;
+        else warnings.push(`${path}: expected an integer from 0 to ${EXIT_TAIL_LIMIT}`);
+        break;
+      case "defaultViewport":
+        readViewport(value, path, layer, warnings);
+        break;
+      default:
+        warnings.push(`${path}: unknown field`);
+    }
+  }
+  return layer;
+}
+
+function readViewport(value: JsonValue, path: string, layer: TermctrlLayer, warnings: string[]) {
+  if (!isJsonObject(value)) {
+    warnings.push(`${path}: expected a JSON object`);
+    return;
+  }
+  for (const [key, dimension] of Object.entries(value)) {
+    if (key !== "cols" && key !== "rows") {
+      warnings.push(`${path}.${key}: unknown field`);
+      continue;
+    }
+    if (Value.Check(ViewportDimensionSchema, dimension)) layer[key] = dimension;
+    else warnings.push(`${path}.${key}: expected an integer from 1 to ${VIEWPORT_LIMIT}`);
+  }
+}
+
+/** Resolve global and trusted-project `termctrl` settings, keeping valid fields around warnings. */
+export function resolveTermctrlSettings(reader: TermctrlSettingsReader): ResolvedTermctrlSettings {
+  const warnings: string[] = [];
+  const globalLayer = readLayer(reader.getGlobalSettings(), "global", warnings);
+  const projectLayer = readLayer(reader.getProjectSettings(), "project", warnings);
+  const defaults = DEFAULT_TERMCTRL_SETTINGS;
+  return {
+    replaceBash: projectLayer.replaceBash ?? globalLayer.replaceBash ?? defaults.replaceBash,
+    defaultViewport: {
+      cols: projectLayer.cols ?? globalLayer.cols ?? defaults.defaultViewport.cols,
+      rows: projectLayer.rows ?? globalLayer.rows ?? defaults.defaultViewport.rows,
+    },
+    exitTailLines:
+      projectLayer.exitTailLines ?? globalLayer.exitTailLines ?? defaults.exitTailLines,
+    warnings,
+  };
+}