tinker-agent 1.0.65

package/src/tools/task-output.ts

@@ -0,0 +1,159 @@
+import { mkdir } from "node:fs/promises";
+import { createWriteStream, type WriteStream } from "node:fs";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+export type TaskOutputSnapshot = {
+  outputBytes: number;
+  outputLines: number;
+  preview: string;
+  truncated: boolean;
+  omittedLines?: number;
+};
+
+const maxPreviewLines = 200;
+const previewEdgeLines = 100;
+
+export class TaskOutput {
+  private readonly decoder = new StringDecoder("utf8");
+  private readonly stream: WriteStream;
+  private outputBytes = 0;
+  private outputLines = 0;
+  private pendingLine = "";
+  private fullPreviewLines: string[] | undefined = [];
+  private readonly firstLines: string[] = [];
+  private readonly lastLines: string[] = [];
+  private endPromise?: Promise<TaskOutputSnapshot>;
+
+  private constructor(readonly filePath: string) {
+    this.stream = createWriteStream(filePath, { flags: "a" });
+  }
+
+  static async create(filePath: string): Promise<TaskOutput> {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    return new TaskOutput(filePath);
+  }
+
+  write(chunk: Buffer): void {
+    this.outputBytes += chunk.byteLength;
+    this.stream.write(chunk);
+    this.appendText(this.decoder.write(chunk));
+  }
+
+  async end(): Promise<TaskOutputSnapshot> {
+    this.endPromise ??= this.finish();
+    return this.endPromise;
+  }
+
+  private async finish(): Promise<TaskOutputSnapshot> {
+    this.appendText(this.decoder.end());
+    if (this.pendingLine !== "") {
+      this.pushLine(this.pendingLine);
+      this.pendingLine = "";
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      this.stream.end((error?: Error | null) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve();
+      });
+    });
+
+    return this.snapshot();
+  }
+
+  snapshot(): TaskOutputSnapshot {
+    const outputLines = this.outputLines + (this.pendingLine === "" ? 0 : 1);
+    const lines = this.previewLines();
+
+    if (outputLines <= maxPreviewLines) {
+      return {
+        outputBytes: this.outputBytes,
+        outputLines,
+        preview: lines.join("\n"),
+        truncated: false,
+      };
+    }
+
+    const omittedLines = outputLines - maxPreviewLines;
+    const omittedStartLine = previewEdgeLines + 1;
+    const omittedEndLine = outputLines - previewEdgeLines;
+    return {
+      outputBytes: this.outputBytes,
+      outputLines,
+      preview: [
+        ...this.firstLines,
+        `... output omitted: lines ${omittedStartLine}-${omittedEndLine} (${omittedLines} ${omittedLines === 1 ? "line" : "lines"}). Full output is available at outputFilePath.`,
+        ...this.lastPreviewLines(),
+      ].join("\n"),
+      truncated: true,
+      omittedLines,
+    };
+  }
+
+  private appendText(text: string): void {
+    if (text === "") {
+      return;
+    }
+
+    const parts = text.split("\n");
+    parts[0] = this.pendingLine + parts[0];
+
+    for (const line of parts.slice(0, -1)) {
+      this.pushLine(trimTrailingCarriageReturn(line));
+    }
+
+    this.pendingLine = parts.at(-1) ?? "";
+  }
+
+  private pushLine(line: string): void {
+    this.outputLines += 1;
+
+    if (this.firstLines.length < previewEdgeLines) {
+      this.firstLines.push(line);
+    }
+
+    this.lastLines.push(line);
+    if (this.lastLines.length > previewEdgeLines) {
+      this.lastLines.shift();
+    }
+
+    if (this.fullPreviewLines !== undefined) {
+      this.fullPreviewLines.push(line);
+      if (this.fullPreviewLines.length > maxPreviewLines) {
+        this.fullPreviewLines = undefined;
+      }
+    }
+  }
+
+  private previewLines(): string[] {
+    const lines =
+      this.fullPreviewLines === undefined
+        ? [...this.firstLines, ...this.lastLines]
+        : [...this.fullPreviewLines];
+
+    if (this.pendingLine !== "") {
+      lines.push(this.pendingLine);
+    }
+
+    return lines;
+  }
+
+  private lastPreviewLines(): string[] {
+    const lines = [...this.lastLines];
+
+    if (this.pendingLine !== "") {
+      lines.push(this.pendingLine);
+    }
+
+    return lines.slice(-previewEdgeLines);
+  }
+}
+
+function trimTrailingCarriageReturn(line: string): string {
+  return line.endsWith("\r") ? line.slice(0, -1) : line;
+}

package/src/tools/task-stop.ts

@@ -0,0 +1,59 @@
+import type { ShellTaskManager } from "./bash-task";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { parseTaskIdArgs } from "./task-tool-args";
+import { defineToolExecutor } from "./types";
+import type { TaskStopRawResult, ToolExecutionContext, ToolExecutor } from "./types";
+
+export function createTaskStopToolExecutor(options: {
+  taskManager: ShellTaskManager;
+}): ToolExecutor {
+  return defineToolExecutor("task_stop", {
+    definition: {
+      name: "TaskStop",
+      description: "Stop a running background shell task.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          task_id: {
+            type: "string",
+            description: "The running task ID to stop.",
+          },
+        },
+        required: ["task_id"],
+      },
+    },
+    async execute(
+      args,
+      _call,
+      context: ToolExecutionContext,
+    ): Promise<TaskStopRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseTaskIdArgs(args, "TaskStop");
+      if (!parsed.ok) {
+        return { ok: false, taskId: "", error: parsed.error };
+      }
+
+      try {
+        const result = await options.taskManager.stopTask(parsed.taskId, "tool");
+        return {
+          ok: true,
+          taskId: parsed.taskId,
+          task: result.task,
+          status: result.task.status,
+          requestedSignal: result.requestedSignal,
+          escalated: result.escalated,
+        };
+      } catch (error) {
+        const inspection = options.taskManager.inspectTask(parsed.taskId);
+        return {
+          ok: false,
+          taskId: parsed.taskId,
+          task: inspection?.task,
+          status: inspection?.task.status,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,29 @@
+export function parseTaskIdArgs(
+  args: unknown,
+  toolName: "TaskOutput" | "TaskStop",
+): { ok: true; taskId: string } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: `${toolName} arguments must be an object.` };
+  }
+
+  const unexpected = Object.keys(args).filter((key) => key !== "task_id");
+  if (unexpected.length > 0) {
+    return {
+      ok: false,
+      error: `${toolName} received unexpected argument: ${unexpected[0]}.`,
+    };
+  }
+
+  if (typeof args.task_id !== "string" || args.task_id.trim() === "") {
+    return {
+      ok: false,
+      error: `${toolName}.task_id must be a non-empty string.`,
+    };
+  }
+
+  return { ok: true, taskId: args.task_id };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tools/types.ts

@@ -0,0 +1,330 @@
+import type { ToolCall } from "../agent/types";
+import type { SessionId } from "../ids/runtime-id";
+import type {
+  RecallGetPage,
+  RecallSearchFilters,
+  RecallSearchPage,
+} from "../session/session-history-reader";
+import type { ShellTaskSnapshot, ShellTaskStatus } from "./bash-task";
+
+export type JsonSchema = Record<string, unknown>;
+
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  parameters: JsonSchema;
+};
+
+export type DiffHunk = {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+};
+
+export type ReadFileRawResult = {
+  ok: boolean;
+  filePath: string;
+  absolutePath?: string;
+  content?: string;
+  contentBytes?: number;
+  sizeBytes?: number;
+  totalLines?: number;
+  startLine?: number;
+  endLine?: number;
+  sha256?: string;
+  error?: string;
+};
+
+export type WriteFileRawResult = {
+  ok: boolean;
+  filePath: string;
+  absolutePath?: string;
+  bytesWritten?: number;
+  oldSha256?: string | null;
+  newSha256?: string;
+  created?: boolean;
+  patch?: DiffHunk[];
+  patchTruncated?: boolean;
+  requiredReadBeforeWrite?: boolean;
+  currentSha256?: string;
+  lastReadSha256?: string;
+  error?: string;
+};
+
+export type EditFileRawResult = {
+  ok: boolean;
+  filePath: string;
+  absolutePath?: string;
+  bytesWritten?: number;
+  oldSha256?: string | null;
+  newSha256?: string;
+  replacementCount?: number;
+  replaceAll?: boolean;
+  created?: boolean;
+  patch?: DiffHunk[];
+  patchTruncated?: boolean;
+  requiredReadBeforeEdit?: boolean;
+  currentMtimeMs?: number;
+  lastObservedMtimeMs?: number;
+  error?: string;
+};
+
+export type GlobRawResult = {
+  ok: boolean;
+  pattern: string;
+  searchPath: string;
+  absoluteSearchPath?: string;
+  matches?: string[];
+  matchCount?: number;
+  ignored?: string[];
+  error?: string;
+};
+
+export type GrepOutputMode = "content" | "files_with_matches" | "count";
+
+export type GrepRawResult = {
+  ok: boolean;
+  pattern: string;
+  searchPath: string;
+  absoluteSearchPath?: string;
+  mode: GrepOutputMode;
+  filenames: string[];
+  numFiles: number;
+  content?: string;
+  numLines?: number;
+  numMatches?: number;
+  appliedLimit?: number;
+  appliedOffset?: number;
+  ignored?: string[];
+  truncated?: boolean;
+  error?: string;
+};
+
+export type BashRawResult = {
+  ok: boolean;
+  command: string;
+  taskId: string;
+  sessionId: SessionId;
+  status: "completed" | "failed" | "running" | "killed";
+  exitCode?: number;
+  signal?: string;
+  cwd: string;
+  outputFilePath: string;
+  outputBytes: number;
+  outputLines: number;
+  preview: string;
+  truncated: boolean;
+  omittedLines?: number;
+  timedOut?: boolean;
+  timeoutMs?: number;
+  backgrounded?: boolean;
+  backgroundedDueToTimeout?: boolean;
+  returnCodeInterpretation?: string;
+  error?: string;
+};
+
+export type TaskListRawResult = {
+  ok: boolean;
+  runningCount: number;
+  tasks: ShellTaskSnapshot[];
+  error?: string;
+};
+
+export type TaskOutputRawResult = {
+  ok: boolean;
+  taskId: string;
+  task?: ShellTaskSnapshot;
+  status?: ShellTaskStatus;
+  command?: string;
+  outputBytes?: number;
+  outputLines?: number;
+  preview?: string;
+  truncated?: boolean;
+  omittedLines?: number;
+  outputFilePath?: string;
+  error?: string;
+};
+
+export type TaskStopRawResult = {
+  ok: boolean;
+  taskId: string;
+  task?: ShellTaskSnapshot;
+  status?: ShellTaskStatus;
+  requestedSignal?: "SIGTERM";
+  escalated?: boolean;
+  error?: string;
+};
+
+export type WebSearchResultItem = {
+  title: string;
+  url: string;
+  publishedDate?: string;
+  author?: string;
+  highlights?: string[];
+};
+
+export type WebSearchRawResult = {
+  ok: boolean;
+  query: string;
+  searchType?: string;
+  requestId?: string;
+  results?: WebSearchResultItem[];
+  resultCount?: number;
+  allowedDomains?: string[];
+  blockedDomains?: string[];
+  costDollars?: number;
+  durationMs?: number;
+  error?: string;
+};
+
+export type WebFetchRawResult = {
+  ok: boolean;
+  url: string;
+  route?: "local" | "exa" | "local-browser";
+  finalUrl?: string;
+  redirectUrl?: string;
+  title?: string;
+  publishedDate?: string;
+  refined?: boolean;
+  content?: string;
+  highlights?: string[];
+  source?: "cached" | "crawled";
+  cacheHit?: boolean;
+  errorTag?: string;
+  httpStatusCode?: number;
+  costDollars?: number;
+  durationMs?: number;
+  error?: string;
+};
+
+export type GenericToolRawResult = {
+  ok: false;
+  toolName: string;
+  error: string;
+};
+
+export type RecallToolErrorCode =
+  | "RECALL_ARGS_INVALID"
+  | "RECALL_SOURCE_INVALID"
+  | "RECALL_SOURCE_NOT_FOUND"
+  | "RECALL_PAGE_INVALID"
+  | "RECALL_SNAPSHOT_INVALID";
+
+export type RecallSearchRawResult =
+  | {
+      ok: true;
+      mode: "search";
+      historical: true;
+      query: string;
+      filters: RecallSearchFilters;
+      page: RecallSearchPage;
+    }
+  | {
+      ok: false;
+      mode: "search";
+      errorCode: RecallToolErrorCode;
+      error: string;
+    };
+
+export type RecallGetRawResult =
+  | {
+      ok: true;
+      mode: "get";
+      historical: true;
+      page: RecallGetPage;
+    }
+  | {
+      ok: false;
+      mode: "get";
+      errorCode: RecallToolErrorCode;
+      error: string;
+    };
+
+export type RecallRawResult = RecallSearchRawResult | RecallGetRawResult;
+
+export type McpToolRawResult = {
+  ok: boolean;
+  toolName: string;
+  serverName: string;
+  serverToolName: string;
+  isError?: boolean;
+  text?: string;
+  truncated?: boolean;
+  contentBlockCount?: number;
+  error?: string;
+};
+
+export type ToolRawResultByKind = {
+  read: ReadFileRawResult;
+  write: WriteFileRawResult;
+  edit: EditFileRawResult;
+  glob: GlobRawResult;
+  grep: GrepRawResult;
+  bash: BashRawResult;
+  task_list: TaskListRawResult;
+  task_output: TaskOutputRawResult;
+  task_stop: TaskStopRawResult;
+  web_search: WebSearchRawResult;
+  web_fetch: WebFetchRawResult;
+  recall: RecallRawResult;
+  mcp: McpToolRawResult;
+  generic: GenericToolRawResult;
+};
+
+export type ToolRawResultKind = keyof ToolRawResultByKind;
+
+export type ToolRawResult = {
+  [TKind in ToolRawResultKind]: ToolRawResultByKind[TKind] & { kind: TKind };
+}[ToolRawResultKind];
+
+export type ToolExecutor = {
+  definition: ToolDefinition;
+  execute(
+    args: unknown,
+    call: ToolCall,
+    context: ToolExecutionContext,
+  ): Promise<ToolRawResult>;
+};
+
+type UntaggedToolExecutor<TKind extends ToolRawResultKind> = {
+  definition: ToolDefinition;
+  execute(
+    args: unknown,
+    call: ToolCall,
+    context: ToolExecutionContext,
+  ): Promise<ToolRawResultByKind[TKind]>;
+};
+
+export function defineToolExecutor<TKind extends ToolRawResultKind>(
+  kind: TKind,
+  executor: UntaggedToolExecutor<TKind>,
+): ToolExecutor {
+  return {
+    definition: executor.definition,
+    async execute(args, call, context) {
+      const raw = await executor.execute(args, call, context);
+      return { ...raw, kind } as ToolRawResult;
+    },
+  };
+}
+
+export type ToolExecutionContext = {
+  signal: AbortSignal;
+};
+
+export class ToolExecutionFatalError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "ToolExecutionFatalError";
+  }
+}
+
+export type FileSnapshot = {
+  sha256: string;
+  mtimeMs: number;
+  source: "read" | "write" | "edit";
+};
+
+export type ReadSnapshotStore = Map<string, FileSnapshot>;

package/src/tools/web-fetch/backend.ts

@@ -0,0 +1,27 @@
+import type { ToolExecutionContext } from "../types";
+
+export type WebFetchRoute = "local" | "exa" | "local-browser";
+
+export type WebFetchBackendResult = {
+  ok: boolean;
+  finalUrl?: string;
+  redirectUrl?: string;
+  title?: string;
+  publishedDate?: string;
+  markdown?: string;
+  refined?: string;
+  highlights?: string[];
+  source?: "cached" | "crawled";
+  errorTag?: string;
+  httpStatusCode?: number;
+  costDollars?: number;
+  error?: string;
+};
+
+export type WebFetchBackend = {
+  route: WebFetchRoute;
+  fetch(
+    input: { url: string; prompt: string },
+    context: ToolExecutionContext,
+  ): Promise<WebFetchBackendResult>;
+};