tinker-agent 1.5.1 → 1.7.0

package/src/tools/task-input.ts

@@ -0,0 +1,229 @@
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import type { ShellTaskManager, ShellTaskSnapshot } from "./bash-task";
+import { ShellProcessWriteError } from "./shell-process";
+import { defineToolExecutor } from "./types";
+import type { TaskInputRawResult, ToolExecutionContext, ToolExecutor } from "./types";
+
+type TaskInputArgs = {
+  taskId: string;
+  chars: string;
+  waitMs: number;
+};
+
+const defaultWaitMs = 250;
+const maxWaitMs = 30_000;
+
+export function createTaskInputToolExecutor(options: {
+  taskManager: ShellTaskManager;
+}): ToolExecutor {
+  return defineToolExecutor("task_input", {
+    definition: {
+      name: "TaskInput",
+      description:
+        "Write characters to a PTY shell task and return its current terminal screen.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The PTY task ID returned by Bash or TaskList.",
+          },
+          chars: {
+            type: "string",
+            description:
+              "Characters to write exactly as provided. Use an empty string to poll without writing.",
+          },
+          wait_ms: {
+            type: "integer",
+            minimum: 0,
+            maximum: maxWaitMs,
+            description:
+              "Milliseconds to wait before returning the current screen. Defaults to 250.",
+          },
+        },
+        required: ["task_id", "chars"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<TaskInputRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseTaskInputArgs(args);
+      if (!parsed.ok) {
+        return { ok: false, taskId: "", error: parsed.error };
+      }
+
+      const { taskId, chars, waitMs } = parsed.value;
+      const initial = options.taskManager.inspectTask(taskId);
+      if (initial === undefined) {
+        return { ok: false, taskId, error: `Unknown task ID: ${taskId}` };
+      }
+      if (!initial.task.tty) {
+        return taskInputFailure(
+          initial.task,
+          `Task ${taskId} does not accept terminal input; start it with Bash tty=true.`,
+        );
+      }
+      if (chars !== "" && initial.task.status !== "running") {
+        return taskInputFailure(
+          initial.task,
+          `Task ${taskId} is not running (status=${initial.task.status}).`,
+        );
+      }
+
+      let writtenBytes = 0;
+      if (chars !== "") {
+        try {
+          writtenBytes = await options.taskManager.writeTaskInput(taskId, chars);
+        } catch (error) {
+          const current = options.taskManager.inspectTask(taskId)?.task ?? initial.task;
+          return {
+            ...taskInputFailure(
+              current,
+              error instanceof Error ? error.message : String(error),
+            ),
+            writtenBytes:
+              error instanceof ShellProcessWriteError
+                ? error.writtenBytes
+                : writtenBytes,
+          };
+        }
+      }
+
+      throwIfTurnCancelled(context.signal);
+      const waitStartedAt = Date.now();
+      await waitForCollectionWindow({
+        waitMs,
+        completion: options.taskManager.taskCompletion(taskId),
+        signal: context.signal,
+      });
+      throwIfTurnCancelled(context.signal);
+
+      const inspection = await options.taskManager.inspectTaskOutput(taskId);
+      if (inspection === undefined) {
+        return {
+          ok: false,
+          taskId,
+          writtenBytes,
+          error: `Task disappeared while waiting for terminal output: ${taskId}`,
+        };
+      }
+      if (
+        inspection.screen === undefined ||
+        inspection.screenRows === undefined ||
+        inspection.screenColumns === undefined
+      ) {
+        throw new Error(`PTY task ${taskId} has no terminal screen.`);
+      }
+
+      return {
+        ok: true,
+        taskId,
+        task: inspection.task,
+        status: inspection.task.status,
+        writtenBytes,
+        waitedMs: Math.max(0, Date.now() - waitStartedAt),
+        screenRows: inspection.screenRows,
+        screenColumns: inspection.screenColumns,
+        screen: inspection.screen,
+        outputBytes: inspection.output.outputBytes,
+        outputLines: inspection.output.outputLines,
+        outputFilePath: inspection.task.outputFilePath,
+      };
+    },
+  });
+}
+
+export function parseTaskInputArgs(
+  args: unknown,
+): { ok: true; value: TaskInputArgs } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "TaskInput arguments must be an object." };
+  }
+
+  const allowed = new Set(["task_id", "chars", "wait_ms"]);
+  const unexpected = Object.keys(args).find((key) => !allowed.has(key));
+  if (unexpected !== undefined) {
+    return {
+      ok: false,
+      error: `TaskInput received unexpected argument: ${unexpected}.`,
+    };
+  }
+  if (typeof args.task_id !== "string" || args.task_id.trim() === "") {
+    return { ok: false, error: "TaskInput.task_id must be a non-empty string." };
+  }
+  if (typeof args.chars !== "string") {
+    return { ok: false, error: "TaskInput.chars must be a string." };
+  }
+  if (
+    args.wait_ms !== undefined &&
+    (!Number.isInteger(args.wait_ms) ||
+      typeof args.wait_ms !== "number" ||
+      args.wait_ms < 0 ||
+      args.wait_ms > maxWaitMs)
+  ) {
+    return {
+      ok: false,
+      error: `TaskInput.wait_ms must be an integer between 0 and ${maxWaitMs}.`,
+    };
+  }
+
+  return {
+    ok: true,
+    value: {
+      taskId: args.task_id,
+      chars: args.chars,
+      waitMs: args.wait_ms ?? defaultWaitMs,
+    },
+  };
+}
+
+function taskInputFailure(task: ShellTaskSnapshot, error: string): TaskInputRawResult {
+  return {
+    ok: false,
+    taskId: task.taskId,
+    task,
+    status: task.status,
+    error,
+  };
+}
+
+async function waitForCollectionWindow(input: {
+  waitMs: number;
+  completion: Promise<ShellTaskSnapshot>;
+  signal: AbortSignal;
+}): Promise<void> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+
+  try {
+    await Promise.race([
+      input.completion.then(() => undefined),
+      new Promise<void>((resolve) => {
+        timeout = setTimeout(resolve, input.waitMs);
+      }),
+      new Promise<void>((resolve) => {
+        onAbort = () => resolve();
+        if (input.signal.aborted) {
+          onAbort();
+          return;
+        }
+        input.signal.addEventListener("abort", onAbort, { once: true });
+      }),
+    ]);
+  } finally {
+    if (timeout !== undefined) {
+      clearTimeout(timeout);
+    }
+    if (onAbort !== undefined) {
+      input.signal.removeEventListener("abort", onAbort);
+    }
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/task-output-tool.ts

@@ -34,7 +34,7 @@ export function createTaskOutputToolExecutor(options: {
         return { ok: false, taskId: "", error: parsed.error };
       }
 
-      const inspection = options.taskManager.inspectTask(parsed.taskId);
+      const inspection = await options.taskManager.inspectTaskOutput(parsed.taskId);
       throwIfTurnCancelled(context.signal);
       if (inspection === undefined) {
         return {
@@ -56,6 +56,9 @@ export function createTaskOutputToolExecutor(options: {
         truncated: inspection.output.truncated,
         omittedLines: inspection.output.omittedLines,
         outputFilePath: inspection.task.outputFilePath,
+        screenRows: inspection.screenRows,
+        screenColumns: inspection.screenColumns,
+        screen: inspection.screen,
       };
     },
   });

package/src/tools/terminal-screen.ts

@@ -0,0 +1,105 @@
+import { Unicode11Addon } from "@xterm/addon-unicode11";
+import { Terminal } from "@xterm/headless";
+
+export const TERMINAL_SCREEN_ROWS = 24;
+export const TERMINAL_SCREEN_COLUMNS = 80;
+
+export type TerminalScreen = {
+  write(bytes: Uint8Array): Promise<void>;
+  flush(): Promise<void>;
+  text(): string;
+  dispose(): void;
+};
+
+export function createTerminalScreen(): TerminalScreen {
+  return new HeadlessTerminalScreen(TERMINAL_SCREEN_ROWS, TERMINAL_SCREEN_COLUMNS);
+}
+
+export class HeadlessTerminalScreen implements TerminalScreen {
+  private readonly terminal: Terminal;
+  private readonly unicodeAddon: Unicode11Addon;
+  private pendingWrite = Promise.resolve();
+  private disposed = false;
+  private currentRows: number;
+  private currentColumns: number;
+
+  constructor(rows: number, columns: number) {
+    this.currentRows = rows;
+    this.currentColumns = columns;
+    this.terminal = new Terminal({
+      allowProposedApi: true,
+      cols: columns,
+      rows,
+      scrollback: 0,
+    });
+    this.unicodeAddon = new Unicode11Addon();
+    this.terminal.loadAddon(this.unicodeAddon);
+    this.terminal.unicode.activeVersion = "11";
+  }
+
+  get rows(): number {
+    return this.currentRows;
+  }
+
+  get columns(): number {
+    return this.currentColumns;
+  }
+
+  get bracketedPasteMode(): boolean {
+    return this.terminal.modes.bracketedPasteMode;
+  }
+
+  write(bytes: Uint8Array): Promise<void> {
+    const copy = new Uint8Array(bytes);
+    const pending = this.pendingWrite.then(
+      () =>
+        new Promise<void>((resolve, reject) => {
+          if (this.disposed) {
+            reject(new Error("Cannot write to a disposed terminal screen."));
+            return;
+          }
+
+          try {
+            this.terminal.write(copy, resolve);
+          } catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+          }
+        }),
+    );
+    this.pendingWrite = pending;
+    return pending;
+  }
+
+  async resize(rows: number, columns: number): Promise<void> {
+    await this.pendingWrite;
+    this.terminal.resize(columns, rows);
+    this.currentRows = rows;
+    this.currentColumns = columns;
+  }
+
+  async flush(): Promise<void> {
+    await this.pendingWrite;
+  }
+
+  text(): string {
+    const buffer = this.terminal.buffer.active;
+    const lines: string[] = [];
+    for (let row = 0; row < this.rows; row += 1) {
+      lines.push(buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? "");
+    }
+    while (lines.at(-1) === "") {
+      lines.pop();
+    }
+    return lines.join("\n");
+  }
+
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+
+    this.disposed = true;
+    this.unicodeAddon.dispose();
+    this.terminal.dispose();
+  }
+}