@ian-pascoe/pi-termctrl 0.2.0 → 0.4.0

package/README.md

@@ -33,7 +33,9 @@ For a local checkout, run `pi -e ./packages/pi-termctrl/src/index.ts`.
 
 `terminal_start` runs `command` through the shell Pi's `bash` uses (the
 `shellPath` setting, otherwise Pi's default bash), applies `shellCommandPrefix`,
-and opens a PTY sized by `termctrl.defaultViewport`.
+and opens a PTY sized by `termctrl.defaultViewport`. A relative `cwd` resolves against
+the session's directory. A `cwd` that is missing or not a directory fails with an
+error naming the resolved path.
 
 `terminal_start` and `terminal_send` wait until the Terminal **settles**: at the
 first of 250 ms of screen quiet, a `wait_for_text` match, process exit, or
@@ -45,6 +47,14 @@ with input, and 30 s for a `terminal_send` with neither `text` nor `keys` (a
 poll, which settles on quiet only after new output). Every `wait_ms` clamps to
 5 minutes.
 
+Results say why the wait ended in `settle_reason` (`matched`, `timeout`, `quiet`
+or `exited`) and in their first line, such as `t1 running · settled: timeout`; a
+`wait_for_text` that timed out adds that the pattern was not seen. Polls report
+their reason too.
+
+Sending `text` or `keys` to an exited Terminal is an error that names its exit
+code or signal; a poll (neither `text` nor `keys`) still returns its final screen.
+
 Results contain the visible screen, the log lines that scrolled off since the
 agent's previous result, `state`, `exit_code` or `signal` once exited, and
 `changed: false` when the screen matches the previous result. Scrolled-off lines
@@ -82,7 +92,10 @@ another fails and lists the caller's live entries.
 `terminal_stop` stops a running entry (termctrl stop, then `SIGKILL` of the
 Terminal's process group if it is still alive after 3 s) and forgets it. For a
 Terminal it returns the final screen and scrolled-off lines; for a Background
-job, its recent output. Exited entries stay
+job, its recent output. When a Terminal had already exited and its screen is
+unchanged since the agent's last result, the result omits the screen and reports
+`changed: false` with `state` and `exit_code` or `signal`; `scrolled_off` still
+appears when lines scrolled off since that result. Exited entries stay
 readable and listed until the agent stops them, the user removes them in `/ps`,
 or their session shuts down. `terminal_list` lists the caller's Terminals and,
 in a separate `background_jobs` section, its Background jobs with their log
@@ -97,6 +110,10 @@ for the agent, such as the user steering or another entry's Exit notification;
 a watched entry that exits after that is notified as usual. With nothing to
 wait for it returns at once. Terminal exits are noticed within about 500 ms.
 
+### Tool annotations
+
+Each terminal tool declares MCP-style `annotations`, which Pi reports through `pi.getAllTools()` for permission extensions and does not send to model providers. `terminal_start` and `terminal_send` run arbitrary programs, so they are marked destructive and open-world; neither is idempotent. `terminal_stop` kills processes: destructive and idempotent, closed-world. `terminal_list` and `terminal_wait` are read-only and closed-world. The `bash` replacement keeps the annotations of Pi's built-in `bash`, which declares none.
+
 ## `bash` replacement
 
 With `termctrl.replaceBash` (default `true`), Pi Termctrl replaces Pi's `bash`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [
@@ -37,8 +37,8 @@
     "@kitlangton/terminal-control": "^1.2.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": "*"
   },
   "engines": {
@@ -53,7 +53,7 @@
     ]
   },
   "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/src/bash-replacement.ts

@@ -248,10 +248,12 @@ export interface BashReplacementOptions {
   readonly definitionFactory?: typeof createBashToolDefinition;
 }
 
+/** Pi's `bash` declares an object `outputSchema` since 0.99.0; extend it with the background fields. */
 function backgroundOutputSchema(builtin: TSchema | undefined) {
-  const properties = builtin !== undefined && Type.IsObject(builtin) ? builtin.properties : {};
+  if (builtin === undefined || !Type.IsObject(builtin))
+    throw new Error("Pi's bash tool does not declare an object outputSchema");
   return Type.Object({
-    ...properties,
+    ...builtin.properties,
     exit_code: Type.Optional(
       Type.Number({ description: "Absent only when the command was moved to the background" }),
     ),

package/src/terminal-tools.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, stat, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import {
   DEFAULT_MAX_BYTES,
@@ -77,9 +77,18 @@ export interface TerminalToolRuntime {
 
 const TerminalStateSchema = Type.Union([Type.Literal("running"), Type.Literal("exited")]);
 
+const SettleReasonSchema = Type.Union(
+  [Type.Literal("matched"), Type.Literal("timeout"), Type.Literal("quiet"), Type.Literal("exited")],
+  {
+    description:
+      "Why the wait ended: wait_for_text matched, wait_ms ran out or the call was cancelled, the screen was quiet for 250 ms, or the Terminal exited",
+  },
+);
+
 const TerminalResultSchema = Type.Object({
   id: Type.String(),
   state: TerminalStateSchema,
+  settle_reason: SettleReasonSchema,
   exit_code: Type.Optional(Type.Number({ description: "Present once the Terminal has exited" })),
   signal: Type.Optional(Type.String({ description: "Present when a signal ended the Terminal" })),
   changed: Type.Boolean({ description: "Whether the screen differs from the previous result" }),
@@ -128,7 +137,12 @@ const StopResultSchema = Type.Object({
       description: "Terminal only: whether the screen differs from the previous result",
     }),
   ),
-  screen: Type.Optional(Type.String({ description: "Terminal only: the final screen" })),
+  screen: Type.Optional(
+    Type.String({
+      description:
+        "Terminal only: the final screen; omitted for an exited Terminal whose screen is unchanged since your previous result",
+    }),
+  ),
   scrolled_off: Type.Optional(
     Type.String({
       description: "Terminal only: lines that scrolled off since the previous result",
@@ -270,7 +284,7 @@ export function parseWaitPattern(pattern: string): (screen: string) => boolean {
 
 type SettleMode = "start" | "input" | "poll";
 /** Why a Terminal wait ended. */
-export type SettleReason = "quiet" | "matched" | "exited" | "timeout";
+export type SettleReason = Static<typeof SettleReasonSchema>;
 
 interface SettleRequest {
   readonly mode: SettleMode;
@@ -369,12 +383,32 @@ function locateCursor(
   return undefined;
 }
 
+/**
+ * Find where the result's screen starts in termctrl's log. The screen is read before the log, in a
+ * separate termctrl request, so output in between can already have pushed the screen's top lines
+ * above the log's last screenful. Output only adds lines to the end of the log, so the screen is at
+ * the end or higher up, no higher than the log cursor. The screen is matched by every line except
+ * its last, which the program may still be writing. When nothing matches, as when the screen was
+ * redrawn in between, the log's last screenful is taken as the screen.
+ */
+function locateScreen(lines: readonly string[], screen: readonly string[], floor: number): number {
+  const end = Math.max(0, lines.length - screen.length);
+  for (let start = end; start >= floor; start--) {
+    let matches = true;
+    for (let row = 0; row < screen.length - 1 && matches; row++) {
+      matches = lines[start + row] === screen[row];
+    }
+    if (matches) return start;
+  }
+  return end;
+}
+
 /**
  * Lines that left the screen since the previous result, advancing the Terminal's log cursor.
- * Lines still on the screen stay unread, so a line rewritten after the agent saw it, such as a
- * progress line, is reported in its final form once it scrolls off. When the cursor cannot be found
- * again, because termctrl dropped lines the agent never received or the screen was cleared, every
- * line termctrl still holds is reported and the result says that earlier output is missing.
+ * Lines still on the result's screen stay unread, so a line rewritten after the agent saw it, such
+ * as a progress line, is reported in its final form once it scrolls off. When the cursor cannot be
+ * found again, because termctrl dropped lines the agent never received or the screen was cleared,
+ * every line termctrl still holds is reported and the result says that earlier output is missing.
  */
 async function takeScrolledOff(entry: TerminalEntry, screen: string): Promise<ScrolledOff> {
   let logs: string;
@@ -385,8 +419,8 @@ async function takeScrolledOff(entry: TerminalEntry, screen: string): Promise<Sc
   }
   const lines = logs === "" ? [] : logs.split("\n");
   const located = locateCursor(lines, entry.logCursor, entry.logAnchor);
-  const screenLines = screen === "" ? 0 : screen.split("\n").length;
-  const boundary = Math.max(0, lines.length - screenLines);
+  const screenLines = screen === "" ? [] : screen.split("\n");
+  const boundary = locateScreen(lines, screenLines, located ?? 0);
   const scrolled = lines.slice(Math.min(located ?? 0, boundary), boundary);
   entry.logCursor = boundary;
   entry.logAnchor =
@@ -480,6 +514,13 @@ async function truncateOutput(
   return { ...fitted, fullOutputPath: path, notice: `${range} Full output: ${path}]` };
 }
 
+/** Says that `wait_for_text` was not seen when its wait timed out. */
+function unmatchedNote(reason: SettleReason, pattern: string | undefined): string | undefined {
+  return reason === "timeout" && pattern !== undefined
+    ? `wait_for_text ${JSON.stringify(pattern)} was not seen before the wait ended.`
+    : undefined;
+}
+
 function formatTerminalText(
   result: TerminalResult,
   note: string | undefined,
@@ -489,7 +530,9 @@ function formatTerminalText(
     result.state === "running"
       ? "running"
       : describeExit({ code: result.exit_code ?? null, signal: result.signal ?? null });
-  const parts = [`${result.id} ${exit}${result.changed ? "" : " · screen unchanged"}`];
+  const parts = [
+    `${result.id} ${exit} · settled: ${result.settle_reason}${result.changed ? "" : " · screen unchanged"}`,
+  ];
   if (note !== undefined) parts.push(note);
   if (result.scrolled_off !== "") {
     parts.push(`--- scrolled off ---\n${result.scrolled_off}`);
@@ -504,6 +547,7 @@ async function terminalResult(
   registry: TermctrlRegistry,
   entry: TerminalEntry,
   snapshot: TerminalSnapshot | undefined,
+  settleReason: SettleReason,
   note?: string,
 ) {
   const screen = snapshot?.screen ?? entry.finalScreen ?? entry.lastScreen ?? "";
@@ -520,6 +564,7 @@ async function terminalResult(
   const result: TerminalResult = {
     id: entry.id,
     state: exited ? "exited" : "running",
+    settle_reason: settleReason,
     ...exitFields(exited ? entry.exit : null),
     changed: entry.lastScreen !== screen,
     screen: output.screen,
@@ -567,6 +612,23 @@ function unknownId(id: string): Error {
   );
 }
 
+/** Resolve `cwd` against the session's directory and check it is a directory termctrl can start in. */
+async function resolveWorkingDirectory(base: string, cwd: string | undefined): Promise<string> {
+  const resolved = resolve(base, cwd ?? ".");
+  let isDirectory: boolean;
+  try {
+    isDirectory = (await stat(resolved)).isDirectory();
+  } catch (cause) {
+    const code = cause instanceof Error && "code" in cause ? cause.code : undefined;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      throw new Error(`Working directory does not exist: ${resolved}`, { cause });
+    }
+    throw cause;
+  }
+  if (!isDirectory) throw new Error(`Working directory is not a directory: ${resolved}`);
+  return resolved;
+}
+
 function shellCommand(shell: TerminalShell, command: string): [string, ...string[]] {
   const script = shell.commandPrefix ? `${shell.commandPrefix}\n${command}` : command;
   return [shell.shell, ...shell.args, script];
@@ -585,19 +647,26 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
       "Terminals keep limited scrollback, so long output can be lost; run commands whose full output you need with bash, or redirect their output to a file.",
     ],
     parameters: StartParameters,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     outputSchema: TerminalResultSchema,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
+      const cwd = await resolveWorkingDirectory(context.cwd, params.cwd);
       const entry = await runtime.registry.startTerminal(ownerOf(context), {
         command: shellCommand(runtime.shell(), params.command),
         displayCommand: params.command,
-        cwd: resolve(context.cwd, params.cwd ?? "."),
+        cwd,
         viewport: runtime.viewport(),
         notify: params.notify ?? true,
       });
       // Launching, including a cold driver start, does not count toward the quiet period.
       const startedAt = Date.now();
       return driveTerminal(runtime.registry, entry, async () => {
-        const { snapshot } = await settleTerminal(entry, {
+        const { snapshot, reason } = await settleTerminal(entry, {
           mode: "start",
           waitMs: clampWait(params.wait_ms, START_WAIT_MS),
           startedAt,
@@ -605,12 +674,18 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
           baseline: undefined,
           signal,
         });
-        return terminalResult(runtime.registry, entry, snapshot);
+        return terminalResult(runtime.registry, entry, snapshot, reason);
       });
     },
   });
 }
 
+function inputToExited(id: string, exit: TerminalExit | null): Error {
+  return new Error(
+    `${id} ${describeExit(exit)} and accepts no input. Poll it with terminal_send for its final screen, or remove it with terminal_stop.`,
+  );
+}
+
 /** `terminal_send`: type text and keys into a Terminal, or poll it, and wait for it to settle. */
 export function createTerminalSendTool(runtime: TerminalToolRuntime) {
   return defineTool<typeof SendParameters, TerminalResult>({
@@ -620,6 +695,12 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
       "Type text and press keys in a Terminal, then return its screen once it settles: 250 ms of quiet, a wait_for_text match, exit, or wait_ms (default 500). With neither text nor keys it polls: it waits up to wait_ms (default 30000) for new output. Results include the lines that scrolled off since your previous result; a truncated result names a file with its full output.",
     promptSnippet: "Send input to a Terminal, or poll it, and read its screen",
     parameters: SendParameters,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     outputSchema: TerminalResultSchema,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       const entry = runtime.registry.find(ownerOf(context), params.id);
@@ -638,22 +719,30 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
       }
       const hasInput = (params.text ?? "") !== "" || keys.length > 0;
       if (entry.state === "exited") {
-        return terminalResult(
-          runtime.registry,
-          entry,
-          undefined,
-          hasInput ? "Input was not sent because the Terminal has exited." : undefined,
-        );
+        if (hasInput) {
+          // The error tells the agent about the exit, so a deferred Exit notification is redundant.
+          runtime.registry.markSeen(entry.id);
+          throw inputToExited(entry.id, entry.exit);
+        }
+        return terminalResult(runtime.registry, entry, undefined, "exited");
       }
       return driveTerminal(runtime.registry, entry, async () => {
         const matches =
           params.wait_for_text === undefined ? undefined : parseWaitPattern(params.wait_for_text);
-        const baseline = matches === undefined ? undefined : (await entry.handle.snapshot()).screen;
+        const before =
+          hasInput || matches !== undefined ? await entry.handle.snapshot() : undefined;
+        if (hasInput && before?.state === "exited") {
+          // The exit watcher has not noticed this exit yet.
+          const exit = before.exit ?? { code: null, signal: null };
+          runtime.registry.terminalExited(entry.id, exit, before.screen, true);
+          throw inputToExited(entry.id, exit);
+        }
+        const baseline = matches === undefined ? undefined : before?.screen;
         const startedAt = Date.now();
         if (params.text !== undefined && params.text !== "") await entry.handle.type(params.text);
         const validKeys = keys.filter(isKey);
         if (validKeys.length > 0) await entry.handle.press(validKeys);
-        const { snapshot } = await settleTerminal(entry, {
+        const { snapshot, reason } = await settleTerminal(entry, {
           mode: hasInput ? "input" : "poll",
           waitMs: clampWait(params.wait_ms, hasInput ? INPUT_WAIT_MS : POLL_WAIT_MS),
           startedAt,
@@ -661,7 +750,13 @@ export function createTerminalSendTool(runtime: TerminalToolRuntime) {
           baseline,
           signal,
         });
-        return terminalResult(runtime.registry, entry, snapshot);
+        return terminalResult(
+          runtime.registry,
+          entry,
+          snapshot,
+          reason,
+          unmatchedNote(reason, params.wait_for_text),
+        );
       });
     },
   });
@@ -688,9 +783,15 @@ export function createTerminalStopTool(registry: TermctrlRegistry) {
     name: "terminal_stop",
     label: "terminal_stop",
     description:
-      "Stop a Terminal (t1) or Background job (b1) and forget it. Running processes are killed; exited ones are removed. Returns a Terminal's final screen and scrolled-off lines, or a Background job's recent output.",
+      "Stop a Terminal (t1) or Background job (b1) and forget it. Running processes are killed; exited ones are removed. Returns a Terminal's final screen (omitted when unchanged since your previous result) and scrolled-off lines, or a Background job's recent output.",
     promptSnippet: "Stop a Terminal or Background job",
     parameters: StopParameters,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     outputSchema: StopResultSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
       const owner = ownerOf(context);
@@ -714,14 +815,18 @@ export function createTerminalStopTool(registry: TermctrlRegistry) {
       const parts = [header];
       if (entry.kind === "terminal") {
         const screen = entry.finalScreen ?? "";
-        const output = await fitOutput(registry, entry, screen, scrolled);
+        // An exited Terminal's screen the agent already saw is not repeated.
+        const repeated = !wasRunning && previousScreen === screen;
+        const output = await fitOutput(registry, entry, repeated ? "" : screen, scrolled);
         result.changed = previousScreen !== screen;
-        result.screen = output.screen;
-        result.scrolled_off = output.scrolledOff;
+        if (!repeated) result.screen = output.screen;
+        if (!repeated || output.scrolledOff !== "") result.scrolled_off = output.scrolledOff;
         if (output.gap) result.output_missing = true;
         if (output.fullOutputPath !== undefined) result.full_output_path = output.fullOutputPath;
         if (output.scrolledOff !== "") parts.push(`--- scrolled off ---\n${output.scrolledOff}`);
-        parts.push(`--- final screen ---\n${output.screen === "" ? "(blank)" : output.screen}`);
+        if (repeated) parts.push("Its screen is unchanged since your last result.");
+        else
+          parts.push(`--- final screen ---\n${output.screen === "" ? "(blank)" : output.screen}`);
         if (output.notice !== undefined) parts.push(`\n${output.notice}`);
       } else {
         result.output = entry.child.tail();
@@ -832,6 +937,12 @@ export function createTerminalWaitTool(runtime: TerminalWaitRuntime) {
       "Do not poll a Background job's log or a Terminal in a loop to learn when it finishes: keep working and rely on its Exit notification, or call terminal_wait when nothing else can proceed.",
     ],
     parameters: WaitParameters,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     outputSchema: WaitResultSchema,
     async execute(_toolCallId, params, signal, _onUpdate, context) {
       const owner = ownerOf(context);
@@ -898,6 +1009,12 @@ export function createTerminalListTool(registry: TermctrlRegistry) {
       "List your Terminals and Background jobs, running and exited, with their state. Background jobs include their log path.",
     promptSnippet: "List Terminals and Background jobs",
     parameters: ListParameters,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
     outputSchema: ListResultSchema,
     async execute(_toolCallId, _params, _signal, _onUpdate, context) {
       const now = Date.now();