@ian-pascoe/pi-termctrl 0.3.0 → 0.4.1

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's 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-termctrl",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Interactive Terminals, Background jobs, and a /ps panel for Pi.",
   "keywords": [
@@ -53,7 +53,7 @@
     ]
   },
   "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit -p tsconfig.json"
   }
 }

package/src/termctrl-driver.ts

@@ -36,19 +36,38 @@ async function readPid(pidFile: string): Promise<number | undefined> {
   return undefined;
 }
 
+/**
+ * The requests made to one driver. termctrl answers every request sent before its shutdown request
+ * and none sent after it, and the SDK sends a request while its close is in flight without ever
+ * failing it, so that request would wait forever. The registry closes an idle driver without
+ * waiting, and a tool call may still read one of its exited Terminals, as `terminal_stop` does.
+ * Requests are therefore refused once closing starts, with the SDK's message for a closed driver.
+ */
+class DriverRequests {
+  private closing = false;
+
+  send<T>(request: () => Promise<T>): Promise<T> {
+    return this.closing ? Promise.reject(new Error("termctrl driver is closed")) : request();
+  }
+
+  close(shutdown: () => Promise<void>): Promise<void> {
+    this.closing = true;
+    return shutdown();
+  }
+}
+
 class TermctrlTerminal implements TerminalHandle {
   constructor(
     private readonly session: Session,
+    private readonly requests: DriverRequests,
     private readonly pid: number | undefined,
   ) {}
 
   async snapshot(): Promise<TerminalSnapshot> {
-    const status = await this.session.status();
-    const capture = await this.session.screen.capture({
-      allowIncomplete: true,
-      settleMs: 0,
-      deadlineMs: 0,
-    });
+    const status = await this.requests.send(() => this.session.status());
+    const capture = await this.requests.send(() =>
+      this.session.screen.capture({ allowIncomplete: true, settleMs: 0, deadlineMs: 0 }),
+    );
     return {
       screen: capture.text,
       state: status.state,
@@ -58,19 +77,19 @@ class TermctrlTerminal implements TerminalHandle {
   }
 
   logs(): Promise<string> {
-    return this.session.logs.text();
+    return this.requests.send(() => this.session.logs.text());
   }
 
   type(text: string): Promise<void> {
-    return this.session.keyboard.type(text);
+    return this.requests.send(() => this.session.keyboard.type(text));
   }
 
   press(keys: readonly Key[]): Promise<void> {
-    return this.session.keyboard.sequence(keys);
+    return this.requests.send(() => this.session.keyboard.sequence(keys));
   }
 
   stop(): Promise<void> {
-    return this.session.stop();
+    return this.requests.send(() => this.session.stop());
   }
 
   isAlive(): boolean {
@@ -98,6 +117,8 @@ class TermctrlTerminal implements TerminalHandle {
 }
 
 class TermctrlDriver implements TerminalDriver {
+  private readonly requests = new DriverRequests();
+
   constructor(private readonly control: TerminalControl) {}
 
   async launch(request: TerminalLaunchRequest): Promise<TerminalHandle> {
@@ -105,19 +126,21 @@ class TermctrlDriver implements TerminalDriver {
     await mkdir(directory, { recursive: true });
     const pidFile = join(directory, `${process.pid}-${request.id}.pid`);
     try {
-      const session = await this.control.launch({
-        command: ["/bin/sh", "-c", PID_WRAPPER, "pi-termctrl", pidFile, ...request.command],
-        cwd: request.cwd,
-        viewport: request.viewport,
-      });
-      return new TermctrlTerminal(session, await readPid(pidFile));
+      const session = await this.requests.send(() =>
+        this.control.launch({
+          command: ["/bin/sh", "-c", PID_WRAPPER, "pi-termctrl", pidFile, ...request.command],
+          cwd: request.cwd,
+          viewport: request.viewport,
+        }),
+      );
+      return new TermctrlTerminal(session, this.requests, await readPid(pidFile));
     } finally {
       await rm(pidFile, { force: true });
     }
   }
 
   close(): Promise<void> {
-    return this.control.close();
+    return this.requests.close(() => this.control.close());
   }
 }
 

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 when 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;
@@ -500,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,
@@ -509,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}`);
@@ -524,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 ?? "";
@@ -540,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,
@@ -587,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];
@@ -613,17 +655,18 @@ export function createTerminalStartTool(runtime: TerminalToolRuntime) {
     },
     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,
@@ -631,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>({
@@ -670,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,
@@ -693,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),
+        );
       });
     },
   });
@@ -720,7 +783,7 @@ 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: {
@@ -752,14 +815,19 @@ export function createTerminalStopTool(registry: TermctrlRegistry) {
       const parts = [header];
       if (entry.kind === "terminal") {
         const screen = entry.finalScreen ?? "";
-        const output = await fitOutput(registry, entry, screen, scrolled);
-        result.changed = previousScreen !== screen;
-        result.screen = output.screen;
-        result.scrolled_off = output.scrolledOff;
+        const changed = previousScreen !== screen;
+        // A screen the agent already saw is not repeated, whether the Terminal was running or exited.
+        const repeated = !changed;
+        const output = await fitOutput(registry, entry, repeated ? "" : screen, scrolled);
+        result.changed = changed;
+        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();