tinker-agent 1.5.0 → 1.6.0

package/src/tools/bash-guard.ts

@@ -0,0 +1,131 @@
+import path from "node:path";
+
+export type BashRisk =
+  | { readonly dangerous: false }
+  | { readonly dangerous: true; readonly reason: string };
+
+export type BashRiskContext = {
+  readonly workspaceRoot?: string;
+};
+
+const SAFE: BashRisk = Object.freeze({ dangerous: false });
+
+export function classifyBashRisk(
+  command: string,
+  context: BashRiskContext = {},
+): BashRisk {
+  const normalized = command.trim();
+  if (normalized === "") {
+    return SAFE;
+  }
+
+  if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(normalized)) {
+    return dangerous("fork bomb");
+  }
+
+  for (const segment of shellSegments(normalized)) {
+    const words = shellWords(segment);
+    const commandIndex = commandWordIndex(words);
+    if (commandIndex === -1) {
+      continue;
+    }
+    const name = basename(words[commandIndex] ?? "");
+    const args = words.slice(commandIndex + 1);
+
+    if (["shutdown", "reboot", "halt", "poweroff"].includes(name)) {
+      return dangerous(`system power command ${name}`);
+    }
+    if (name === "wipefs" || name.startsWith("mkfs.")) {
+      return dangerous(`block-device command ${name}`);
+    }
+    if (name === "dd" && args.some((word) => /^of=\/dev\/[^/]/.test(word))) {
+      return dangerous("dd writes directly to a device");
+    }
+    if ((name === "chmod" || name === "chown") && hasRecursiveFlag(args)) {
+      const operands = args.filter((word) => !word.startsWith("-"));
+      if (operands.at(-1) === "/") {
+        return dangerous(`${name} recursively targets the filesystem root`);
+      }
+    }
+    if (name === "rm" && hasRecursiveFlag(args) && hasForceFlag(args)) {
+      const operands = args.filter((word) => !word.startsWith("-"));
+      if (
+        operands.some((target) => isDestructiveRmTarget(target, context.workspaceRoot))
+      ) {
+        return dangerous("recursive forced removal targets a protected root");
+      }
+    }
+  }
+
+  return SAFE;
+}
+
+function dangerous(reason: string): BashRisk {
+  return Object.freeze({ dangerous: true, reason });
+}
+
+function shellSegments(command: string): string[] {
+  return command.split(/(?:&&|\|\||[;|\n])/);
+}
+
+function shellWords(segment: string): string[] {
+  return segment.match(/"(?:\\.|[^"])*"|'[^']*'|[^\s]+/g)?.map(unquote) ?? [];
+}
+
+function unquote(word: string): string {
+  if (
+    (word.startsWith('"') && word.endsWith('"')) ||
+    (word.startsWith("'") && word.endsWith("'"))
+  ) {
+    return word.slice(1, -1);
+  }
+  return word;
+}
+
+function commandWordIndex(words: readonly string[]): number {
+  let index = 0;
+  while (index < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index] ?? "")) {
+    index += 1;
+  }
+  if (basename(words[index] ?? "") === "sudo") {
+    index += 1;
+    while ((words[index] ?? "").startsWith("-")) {
+      index += 1;
+    }
+  }
+  return index < words.length ? index : -1;
+}
+
+function basename(word: string): string {
+  return word.slice(word.lastIndexOf("/") + 1);
+}
+
+function hasRecursiveFlag(args: readonly string[]): boolean {
+  return args.some((word) => /^-[^-]*[rR]/.test(word) || word === "--recursive");
+}
+
+function hasForceFlag(args: readonly string[]): boolean {
+  return args.some((word) => /^-[^-]*f/.test(word) || word === "--force");
+}
+
+function isDestructiveRmTarget(
+  target: string,
+  workspaceRoot: string | undefined,
+): boolean {
+  if (target === "/" || target === "/*" || target === "~" || target === "~/*") {
+    return true;
+  }
+  if (
+    target === "$HOME" ||
+    target === "${HOME}" ||
+    target === "$HOME/*" ||
+    target === "${HOME}/*"
+  ) {
+    return true;
+  }
+  if (workspaceRoot === undefined || !path.isAbsolute(target)) {
+    return false;
+  }
+  const normalizedTarget = path.resolve(target.replace(/\/\*$/, ""));
+  return normalizedTarget === path.resolve(workspaceRoot);
+}

package/src/tools/bash.ts

@@ -12,6 +12,7 @@ import { defineToolExecutor } from "./types";
 import type { TaskOutputSnapshot } from "./task-output";
 import type { BashRawResult, ToolExecutionContext, ToolExecutor } from "./types";
 import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../cli/public-config-contract";
+import { classifyBashRisk } from "./bash-guard";
 
 type BashArgs = {
   command: string;
@@ -91,6 +92,36 @@ export function createBashToolExecutor(options: BashToolOptions): ToolExecutor {
       }
 
       const input = parsed.value;
+      const risk = classifyBashRisk(input.command, {
+        workspaceRoot: options.workspaceRoot,
+      });
+      if (risk.dangerous && context.confirmBashCommand !== undefined) {
+        const decision = await context.confirmBashCommand({
+          command: input.command,
+          reason: risk.reason,
+        });
+        throwIfTurnCancelled(context.signal);
+        if (decision === "deny") {
+          const suffix =
+            context.bashGuardSurface === "one-shot"
+              ? "Non-interactive mode cannot confirm; rerun with --yolo."
+              : "The user declined this command.";
+          return {
+            ok: false,
+            command: input.command,
+            taskId: "",
+            sessionId: call.sessionId,
+            status: "failed",
+            cwd: options.cwdState.cwd,
+            outputFilePath: "",
+            outputBytes: 0,
+            outputLines: 0,
+            preview: "",
+            truncated: false,
+            error: `Command denied: ${risk.reason}. ${suffix}`,
+          };
+        }
+      }
       const foregroundTimeoutMs = input.timeout ?? defaultTimeoutMs;
       throwIfTurnCancelled(context.signal);
       const task = await options.taskManager.start({

package/src/tools/delete.ts

@@ -0,0 +1,182 @@
+import { lstat, readFile, rm } from "node:fs/promises";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { resolveWorkspacePath } from "./path-safety";
+import type { TurnUndoManager } from "./turn-undo-manager";
+import { defineToolExecutor } from "./types";
+import type {
+  DeleteFileRawResult,
+  FileSnapshotStore,
+  ToolExecutionContext,
+  ToolExecutor,
+} from "./types";
+
+type DeleteArgs = {
+  file_path: string;
+};
+
+export type DeleteToolOptions = {
+  workspaceRoot: string;
+  snapshots: FileSnapshotStore;
+  undoManager?: TurnUndoManager;
+};
+
+export function createDeleteToolExecutor(options: DeleteToolOptions): ToolExecutor {
+  return defineToolExecutor("delete", {
+    definition: {
+      name: "Delete",
+      description:
+        "Delete one existing regular file. Directories and symbolic links are not supported.",
+      parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          file_path: {
+            type: "string",
+            description: "Workspace-relative path or absolute path.",
+          },
+        },
+        required: ["file_path"],
+      },
+    },
+    async execute(
+      args,
+      call,
+      context: ToolExecutionContext,
+    ): Promise<DeleteFileRawResult> {
+      throwIfTurnCancelled(context.signal);
+      const parsed = parseDeleteArgs(args);
+
+      if (!parsed.ok) {
+        return {
+          ok: false,
+          filePath: "",
+          error: parsed.error,
+        };
+      }
+
+      const input = parsed.value;
+      let absolutePath: string;
+
+      try {
+        absolutePath = resolveWorkspacePath(options.workspaceRoot, input.file_path);
+      } catch (error) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          error: errorMessage(error),
+        };
+      }
+
+      let info: Awaited<ReturnType<typeof lstat>>;
+      try {
+        info = await lstat(absolutePath);
+      } catch (error) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: deleteErrorMessage(error),
+        };
+      }
+
+      if (info.isSymbolicLink()) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: "Symbolic links are not supported.",
+        };
+      }
+
+      if (!info.isFile()) {
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: "Path is not a regular file.",
+        };
+      }
+
+      const undoCapture = await options.undoManager?.captureBeforeMutation({
+        turnId: call.turnId,
+        turnNumber: call.turnNumber,
+        absolutePath,
+        displayPath: input.file_path,
+        knownByteLength: info.size,
+        loadBefore: async () => ({
+          state: "present",
+          bytes: await readFile(absolutePath),
+        }),
+      });
+
+      try {
+        throwIfTurnCancelled(context.signal);
+        await rm(absolutePath);
+      } catch (error) {
+        if (undoCapture !== undefined) {
+          await options.undoManager?.recordMutationFailure(undoCapture);
+        }
+        if (context.signal.aborted) {
+          throw error;
+        }
+        return {
+          ok: false,
+          filePath: input.file_path,
+          absolutePath,
+          error: deleteErrorMessage(error),
+        };
+      }
+
+      if (undoCapture !== undefined) {
+        options.undoManager?.recordMutationResult(undoCapture, { state: "absent" });
+      }
+      options.snapshots.delete(absolutePath);
+
+      return {
+        ok: true,
+        filePath: input.file_path,
+        absolutePath,
+      };
+    },
+  });
+}
+
+function parseDeleteArgs(
+  args: unknown,
+): { ok: true; value: DeleteArgs } | { ok: false; error: string } {
+  if (!isRecord(args)) {
+    return { ok: false, error: "Delete arguments must be an object." };
+  }
+
+  if (typeof args.file_path !== "string") {
+    return { ok: false, error: "Delete.file_path must be a string." };
+  }
+
+  return {
+    ok: true,
+    value: {
+      file_path: args.file_path,
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function deleteErrorMessage(error: unknown): string {
+  return isNotFound(error) ? "File does not exist." : errorMessage(error);
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/tools/edit.ts

@@ -1,10 +1,12 @@
 import { Buffer } from "node:buffer";
 import { readFile, stat, writeFile } from "node:fs/promises";
+import type { ToolCall } from "../agent/types";
 import { throwIfTurnCancelled } from "../agent/turn-cancellation";
 import { computeFilePatch } from "./file-diff";
 import { ensureParentDirectory } from "./ensure-parent-directory";
 import { sha256Bytes, sha256Text } from "./hash";
 import { resolveWorkspacePath } from "./path-safety";
+import type { TurnUndoManager } from "./turn-undo-manager";
 import { defineToolExecutor } from "./types";
 import type {
   EditFileRawResult,
@@ -23,6 +25,7 @@ type EditArgs = {
 export type EditToolOptions = {
   workspaceRoot: string;
   snapshots: FileSnapshotStore;
+  undoManager?: TurnUndoManager;
 };
 
 export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
@@ -58,7 +61,7 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
     },
     async execute(
       args,
-      _call,
+      call,
       context: ToolExecutionContext,
     ): Promise<EditFileRawResult> {
       throwIfTurnCancelled(context.signal);
@@ -102,6 +105,8 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
           target,
           newContent: input.new_string,
           snapshots: options.snapshots,
+          undoManager: options.undoManager,
+          call,
           signal: context.signal,
         });
       }
@@ -173,6 +178,9 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
         expectedSha256: target.sha256,
         readRequiredOnChange: true,
         snapshots: options.snapshots,
+        undoManager: options.undoManager,
+        call,
+        initialBefore: target,
         signal: context.signal,
       });
     },
@@ -219,6 +227,8 @@ async function writeEmptyTarget(input: {
   target: TargetFileState;
   newContent: string;
   snapshots: FileSnapshotStore;
+  undoManager?: TurnUndoManager;
+  call: ToolCall;
   signal: AbortSignal;
 }): Promise<EditFileRawResult> {
   if (input.target.exists && input.target.content.length > 0) {
@@ -242,6 +252,9 @@ async function writeEmptyTarget(input: {
     expectedSha256: input.target.exists ? input.target.sha256 : undefined,
     readRequiredOnChange: false,
     snapshots: input.snapshots,
+    undoManager: input.undoManager,
+    call: input.call,
+    initialBefore: input.target,
     signal: input.signal,
   });
 }
@@ -258,10 +271,14 @@ async function writeEditedContent(input: {
   expectedSha256?: string;
   readRequiredOnChange: boolean;
   snapshots: FileSnapshotStore;
+  undoManager?: TurnUndoManager;
+  call: ToolCall;
+  initialBefore: TargetFileState;
   signal: AbortSignal;
 }): Promise<EditFileRawResult> {
   throwIfTurnCancelled(input.signal);
 
+  let verifiedBefore = input.initialBefore;
   if (input.expectedSha256 !== undefined) {
     const currentState = await targetFileState(input.absolutePath);
     throwIfTurnCancelled(input.signal);
@@ -296,12 +313,27 @@ async function writeEditedContent(input: {
           : "File changed while Edit was being prepared. Retry Edit with the current file state.",
       };
     }
+    verifiedBefore = currentState;
   }
 
+  const undoCapture = await input.undoManager?.captureBeforeMutation({
+    turnId: input.call.turnId,
+    turnNumber: input.call.turnNumber,
+    absolutePath: input.absolutePath,
+    displayPath: input.filePath,
+    loadBefore: async () =>
+      verifiedBefore.exists
+        ? { state: "present", bytes: verifiedBefore.bytes }
+        : { state: "absent" },
+  });
+
   if (input.created) {
     try {
       await ensureParentDirectory(input.absolutePath);
     } catch (error) {
+      if (undoCapture !== undefined) {
+        await input.undoManager?.recordMutationFailure(undoCapture);
+      }
       return {
         ok: false,
         filePath: input.filePath,
@@ -312,14 +344,39 @@ async function writeEditedContent(input: {
     throwIfTurnCancelled(input.signal);
   }
 
-  await writeFile(input.absolutePath, input.newContent, "utf8");
-  const newSha256 = sha256Text(input.newContent);
-  const writtenInfo = await stat(input.absolutePath);
-  input.snapshots.set(input.absolutePath, {
-    sha256: newSha256,
-    mtimeMs: writtenInfo.mtimeMs,
-    source: "edit",
-  });
+  let newSha256: string;
+  try {
+    throwIfTurnCancelled(input.signal);
+    await writeFile(input.absolutePath, input.newContent, "utf8");
+    const expectedSha256 = sha256Text(input.newContent);
+    const written = await targetFileState(input.absolutePath);
+    if (!written.ok) {
+      throw new Error(`Failed to verify edited file: ${written.error}`);
+    }
+    if (!written.exists) {
+      throw new Error("Failed to verify edited file: File does not exist.");
+    }
+    if (written.sha256 !== expectedSha256) {
+      throw new Error("File changed while Edit was being verified.");
+    }
+    newSha256 = written.sha256;
+    if (undoCapture !== undefined) {
+      input.undoManager?.recordMutationResult(undoCapture, {
+        state: "present",
+        sha256: newSha256,
+      });
+    }
+    input.snapshots.set(input.absolutePath, {
+      sha256: newSha256,
+      mtimeMs: written.mtimeMs,
+      source: "edit",
+    });
+  } catch (error) {
+    if (undoCapture !== undefined) {
+      await input.undoManager?.recordMutationFailure(undoCapture);
+    }
+    throw error;
+  }
 
   const patch = computeFilePatch({
     filePath: input.filePath,
@@ -348,6 +405,7 @@ type TargetFileState =
       ok: true;
       exists: true;
       content: string;
+      bytes: Buffer;
       sha256: string;
       mtimeMs: number;
     };
@@ -371,6 +429,7 @@ async function targetFileState(
       ok: true,
       exists: true,
       content: bytes.toString("utf8"),
+      bytes,
       sha256: sha256Bytes(bytes),
       mtimeMs: currentInfo.mtimeMs,
     };

package/src/tools/registry.ts

@@ -1,6 +1,7 @@
 import { createBashToolExecutor } from "./bash";
 import { ShellTaskManager } from "./bash-task";
 import { createCwdState } from "./cwd-state";
+import { createDeleteToolExecutor } from "./delete";
 import { createEditToolExecutor } from "./edit";
 import { createGlobToolExecutor } from "./glob";
 import { createGrepToolExecutor } from "./grep";
@@ -13,6 +14,7 @@ import { createWebFetchToolExecutor } from "./web-fetch";
 import type { Refiner } from "./web-fetch/refiner";
 import { createWebSearchToolExecutor } from "./web-search";
 import { createWriteToolExecutor } from "./write";
+import { TurnUndoManager } from "./turn-undo-manager";
 import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
 import type {
   RuntimeSessionContext,
@@ -62,7 +64,17 @@ export class ToolRegistry {
 }
 
 export class ToolRuntime {
-  constructor(private readonly registry: ToolRegistry) {}
+  constructor(
+    private readonly registry: ToolRegistry,
+    private readonly bashGuard?: {
+      readonly surface: "tui" | "one-shot";
+      confirm(
+        call: ToolCall,
+        request: { command: string; reason: string },
+        signal: AbortSignal,
+      ): Promise<"allow" | "deny">;
+    },
+  ) {}
 
   async execute(call: ToolCall, context: ToolExecutionContext): Promise<ToolRawResult> {
     throwIfTurnCancelled(context.signal);
@@ -88,7 +100,16 @@ export class ToolRuntime {
     }
 
     try {
-      return await tool.execute(call.args, call, context);
+      return await tool.execute(call.args, call, {
+        ...context,
+        ...(this.bashGuard === undefined
+          ? {}
+          : {
+              bashGuardSurface: this.bashGuard.surface,
+              confirmBashCommand: (request: { command: string; reason: string }) =>
+                this.bashGuard!.confirm(call, request, context.signal),
+            }),
+      });
     } catch (error) {
       if (context.signal.aborted) {
         throw cancellationError(context.signal, error);
@@ -113,6 +134,7 @@ export type DefaultTooling = {
   snapshots: FileSnapshotStore;
   bashState: BashToolingState;
   taskManager: ShellTaskManager;
+  turnUndoManager?: TurnUndoManager;
   dispose(reason?: SessionDisposeReason["type"]): Promise<void>;
 };
 
@@ -134,8 +156,20 @@ export function createDefaultTooling(options: {
   skillCoordinator?: SkillActivationCoordinator;
   toolingConfig?: PublicToolingConfig;
   memorySearch?: ToolExecutor;
+  enableTurnUndo?: boolean;
+  bashGuard?: {
+    readonly surface: "tui" | "one-shot";
+    confirm(
+      call: ToolCall,
+      request: { command: string; reason: string },
+      signal: AbortSignal,
+    ): Promise<"allow" | "deny">;
+  };
 }): DefaultTooling {
   const snapshots: FileSnapshotStore = new Map();
+  const turnUndoManager = options.enableTurnUndo
+    ? new TurnUndoManager({ snapshots })
+    : undefined;
   const registry = new ToolRegistry();
   const runtimeSession = options.runtimeSession;
   const toolingConfig = options.toolingConfig ?? DEFAULT_PUBLIC_TOOLING_CONFIG;
@@ -194,12 +228,21 @@ export function createDefaultTooling(options: {
     createWriteToolExecutor({
       workspaceRoot: options.workspaceRoot,
       snapshots,
+      ...(turnUndoManager === undefined ? {} : { undoManager: turnUndoManager }),
     }),
   );
   registry.register(
     createEditToolExecutor({
       workspaceRoot: options.workspaceRoot,
       snapshots,
+      ...(turnUndoManager === undefined ? {} : { undoManager: turnUndoManager }),
+    }),
+  );
+  registry.register(
+    createDeleteToolExecutor({
+      workspaceRoot: options.workspaceRoot,
+      snapshots,
+      ...(turnUndoManager === undefined ? {} : { undoManager: turnUndoManager }),
     }),
   );
   registry.register(
@@ -232,9 +275,10 @@ export function createDefaultTooling(options: {
 
   return {
     registry,
-    runtime: new ToolRuntime(registry),
+    runtime: new ToolRuntime(registry, options.bashGuard),
     snapshots,
     taskManager,
+    ...(turnUndoManager === undefined ? {} : { turnUndoManager }),
     bashState: {
       get cwd() {
         return cwdState.cwd;