tinker-agent 1.6.0 → 1.7.0

package/src/tools/shell-process.ts

@@ -0,0 +1,296 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { TERMINAL_SCREEN_COLUMNS, TERMINAL_SCREEN_ROWS } from "./terminal-screen";
+
+export type ShellProcessMode = "pipe" | "pty";
+
+export type ProcessExitResult = {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  error?: string;
+};
+
+export type ShellProcessHandle = {
+  readonly pid: number;
+  readonly mode: ShellProcessMode;
+  readonly exitCode: number | null;
+  readonly signalCode: NodeJS.Signals | null;
+  wait(): Promise<ProcessExitResult>;
+  waitForOutputClose(): Promise<void>;
+  write?(chars: string): Promise<number>;
+  close(): void;
+};
+
+export class ShellProcessWriteError extends Error {
+  constructor(
+    message: string,
+    readonly writtenBytes: number,
+  ) {
+    super(message);
+    this.name = "ShellProcessWriteError";
+  }
+}
+
+export async function spawnShellProcess(input: {
+  mode: ShellProcessMode;
+  command: string;
+  cwd: string;
+  cwdFilePath: string;
+  onOutput(bytes: Uint8Array): void;
+}): Promise<ShellProcessHandle> {
+  const env = {
+    ...process.env,
+    NO_COLOR: "1",
+    TINKER_BASH_COMMAND: input.command,
+    TINKER_BASH_CWD_FILE: input.cwdFilePath,
+  };
+
+  if (input.mode === "pty") {
+    return spawnPtyShellProcess({ ...input, env });
+  }
+
+  return spawnPipeShellProcess({ ...input, env });
+}
+
+async function spawnPipeShellProcess(input: {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  onOutput(bytes: Uint8Array): void;
+}): Promise<ShellProcessHandle> {
+  const child = spawn("bash", ["-lc", bashWrapperScript], {
+    cwd: input.cwd,
+    detached: true,
+    env: input.env,
+  });
+  pipeOutput(child.stdout, (bytes) => input.onOutput(bytes));
+  pipeOutput(child.stderr, (bytes) => input.onOutput(bytes));
+
+  const exit = waitForNodeProcessExit(child);
+  const close = waitForNodeProcessClose(child);
+  if (child.pid === undefined) {
+    const result = await exit;
+    throw new Error(result.error ?? "Bash process failed to start.");
+  }
+
+  return {
+    pid: child.pid,
+    mode: "pipe",
+    get exitCode() {
+      return child.exitCode;
+    },
+    get signalCode() {
+      return child.signalCode;
+    },
+    wait: () => exit,
+    waitForOutputClose: () => close,
+    close() {},
+  };
+}
+
+function spawnPtyShellProcess(input: {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  onOutput(bytes: Uint8Array): void;
+}): ShellProcessHandle {
+  let terminalEnded = false;
+  let resolveTerminalExit: (() => void) | undefined;
+  let drainGeneration = 0;
+  const drainWaiters = new Set<() => void>();
+  const terminalExit = new Promise<void>((resolve) => {
+    resolveTerminalExit = resolve;
+  });
+  const notifyDrain = () => {
+    drainGeneration += 1;
+    for (const resolve of drainWaiters) {
+      resolve();
+    }
+    drainWaiters.clear();
+  };
+  const settleTerminalExit = () => {
+    if (terminalEnded) {
+      return;
+    }
+    terminalEnded = true;
+    notifyDrain();
+    resolveTerminalExit?.();
+  };
+
+  const subprocess = Bun.spawn(["bash", "-lc", bashWrapperScript], {
+    cwd: input.cwd,
+    detached: true,
+    env: {
+      ...input.env,
+      TERM: "xterm-256color",
+      NO_COLOR: "1",
+      PAGER: "cat",
+      GIT_PAGER: "cat",
+    },
+    terminal: {
+      cols: TERMINAL_SCREEN_COLUMNS,
+      rows: TERMINAL_SCREEN_ROWS,
+      name: "xterm-256color",
+      data(_terminal, bytes) {
+        input.onOutput(new Uint8Array(bytes));
+      },
+      exit() {
+        // Linux reports slave closure as EIO; subprocess.exited owns task status.
+        settleTerminalExit();
+      },
+      drain() {
+        notifyDrain();
+      },
+    },
+  });
+  const terminal = subprocess.terminal!;
+
+  let writeQueue = Promise.resolve();
+  const write = (chars: string): Promise<number> => {
+    const bytes = new TextEncoder().encode(chars);
+    const operation = writeQueue.then(async () => {
+      let writtenBytes = 0;
+      try {
+        while (writtenBytes < bytes.byteLength) {
+          if (terminalEnded || terminal.closed) {
+            throw new Error("PTY is closed.");
+          }
+
+          const generationBeforeWrite = drainGeneration;
+          const accepted = terminal.write(bytes.subarray(writtenBytes));
+          if (accepted < 0 || accepted > bytes.byteLength - writtenBytes) {
+            throw new Error(`PTY accepted an invalid byte count: ${accepted}.`);
+          }
+          writtenBytes += accepted;
+
+          if (writtenBytes < bytes.byteLength) {
+            await waitForDrainOrExit({
+              generationBeforeWrite,
+              currentGeneration: () => drainGeneration,
+              terminalEnded: () => terminalEnded || terminal.closed,
+              drainWaiters,
+            });
+          }
+        }
+        return writtenBytes;
+      } catch (error) {
+        throw new ShellProcessWriteError(
+          error instanceof Error ? error.message : String(error),
+          writtenBytes,
+        );
+      }
+    });
+    writeQueue = operation.then(
+      () => undefined,
+      () => undefined,
+    );
+    return operation;
+  };
+
+  const exit = subprocess.exited.then(
+    (code): ProcessExitResult => ({
+      code: subprocess.signalCode === null ? code : null,
+      signal: subprocess.signalCode,
+    }),
+    (error): ProcessExitResult => ({
+      code: null,
+      signal: null,
+      error: error instanceof Error ? error.message : String(error),
+    }),
+  );
+
+  return {
+    pid: subprocess.pid,
+    mode: "pty",
+    get exitCode() {
+      return subprocess.exitCode;
+    },
+    get signalCode() {
+      return subprocess.signalCode;
+    },
+    wait: () => exit,
+    waitForOutputClose: () => terminalExit,
+    write,
+    close() {
+      if (!terminal.closed) {
+        terminal.close();
+      }
+    },
+  };
+}
+
+async function waitForDrainOrExit(input: {
+  generationBeforeWrite: number;
+  currentGeneration(): number;
+  terminalEnded(): boolean;
+  drainWaiters: Set<() => void>;
+}): Promise<void> {
+  if (
+    input.currentGeneration() !== input.generationBeforeWrite ||
+    input.terminalEnded()
+  ) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    input.drainWaiters.add(resolve);
+    if (
+      input.currentGeneration() !== input.generationBeforeWrite ||
+      input.terminalEnded()
+    ) {
+      input.drainWaiters.delete(resolve);
+      resolve();
+    }
+  });
+}
+
+function waitForNodeProcessExit(
+  process: ChildProcessWithoutNullStreams,
+): Promise<ProcessExitResult> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result: ProcessExitResult) => {
+      if (!settled) {
+        settled = true;
+        resolve(result);
+      }
+    };
+
+    process.once("error", (error) => {
+      finish({ code: null, signal: null, error: error.message });
+    });
+    process.once("exit", (code, signal) => {
+      finish({ code, signal });
+    });
+  });
+}
+
+function waitForNodeProcessClose(
+  process: ChildProcessWithoutNullStreams,
+): Promise<void> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (!settled) {
+        settled = true;
+        resolve();
+      }
+    };
+
+    process.once("error", finish);
+    process.once("close", finish);
+  });
+}
+
+function pipeOutput(
+  stream: NodeJS.ReadableStream,
+  onOutput: (bytes: Uint8Array) => void,
+): void {
+  stream.on("data", (chunk: Buffer | string) => {
+    onOutput(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  });
+}
+
+const bashWrapperScript = `
+eval "$TINKER_BASH_COMMAND"
+exit_code=$?
+pwd -P > "$TINKER_BASH_CWD_FILE"
+exit "$exit_code"
+`;

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();
+  }
+}

package/src/tools/types.ts

@@ -130,6 +130,10 @@ export type BashRawResult = {
   backgrounded?: boolean;
   backgroundedDueToTimeout?: boolean;
   returnCodeInterpretation?: string;
+  tty: boolean;
+  screenRows?: number;
+  screenColumns?: number;
+  screen?: string;
   error?: string;
 };
 
@@ -152,9 +156,36 @@ export type TaskOutputRawResult = {
   truncated?: boolean;
   omittedLines?: number;
   outputFilePath?: string;
+  screenRows?: number;
+  screenColumns?: number;
+  screen?: string;
   error?: string;
 };
 
+export type TaskInputRawResult =
+  | {
+      ok: true;
+      taskId: string;
+      task: ShellTaskSnapshot;
+      status: ShellTaskStatus;
+      writtenBytes: number;
+      waitedMs: number;
+      screenRows: number;
+      screenColumns: number;
+      screen: string;
+      outputBytes: number;
+      outputLines: number;
+      outputFilePath: string;
+    }
+  | {
+      ok: false;
+      taskId: string;
+      task?: ShellTaskSnapshot;
+      status?: ShellTaskStatus;
+      writtenBytes?: number;
+      error: string;
+    };
+
 export type TaskStopRawResult = {
   ok: boolean;
   taskId: string;
@@ -326,6 +357,7 @@ export type ToolRawResultByKind = {
   bash: BashRawResult;
   task_list: TaskListRawResult;
   task_output: TaskOutputRawResult;
+  task_input: TaskInputRawResult;
   task_stop: TaskStopRawResult;
   web_search: WebSearchRawResult;
   web_fetch: WebFetchRawResult;