@ian-pascoe/pi-termctrl 0.2.0 → 0.3.0

package/README.md

@@ -97,6 +97,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.3.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": {

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

@@ -369,12 +369,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 +405,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 =
@@ -585,6 +605,12 @@ 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 entry = await runtime.registry.startTerminal(ownerOf(context), {
@@ -620,6 +646,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);
@@ -691,6 +723,12 @@ export function createTerminalStopTool(registry: TermctrlRegistry) {
       "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.",
     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);
@@ -832,6 +870,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 +942,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();