delete_file

Delete a file from the workspace. By default the file is moved into a per-workspace trash directory instead of being unlinked outright, so the operation is recoverable. Pass permanent: true to skip the trash. Recursive directory deletion is supported via recursive: true but is never the default — a missing flag against a directory returns an error.

import { createAgent } from "@comma-agents/core";

const agent = createAgent({
  name: "janitor",
  model: "openai/gpt-4o",
  tools: ["delete_file"],
});

DeleteFileToolConfig

Optional configuration for the factory.

DeleteFileData

The structured payload returned on success.

Trash semantics

Recoverable deletes compress the target into a .tar.gz archive at <dataDir>/trash/<sha256(workspaceRoot)>/<timestamp>-<sessionId>-<runId>-<basename>.tar.gz. The archive contains the file at its original workspace-relative path and a metadata.json record. Trash entries persist until explicitly cleared via the daemon or restore_file.

// Recoverable (default).
await tool.delete_file({ path: "tmp/scratch.log" });

// Permanent — no trash.
await tool.delete_file({ path: "tmp/scratch.log", permanent: true });

// Recursive directory delete.
await tool.delete_file({ path: "build", recursive: true });

Cross-device fallback

If the trash directory lives on a different filesystem than the target (an EXDEV rename error), delete_file falls back to copy-then-unlink. The deleted bytes still reach the trash and the operation appears atomic to the caller.

Errors

Related

• Trash — how recoverable deletes are stored and reclaimed.
• move_file — to relocate instead of delete.