Agent Task Schema

Disk Tamer is agent-authored, human-run. You write one task document describing an entire batch of file operations. The user reviews it, chooses a folder, and clicks Run. You never execute anything yourself, and you never specify a folder.

The cost of a task is the same whether it touches 5 files or 5,000 — which is the entire point. Listing a directory and emitting one tool call per file scales linearly; this does not.

Rules

Exactly one step per task. Multi-step tasks are rejected with the step count.
Use "selection": { "method": "rules", ... }. Tree selection refers to interactive checkbox state and cannot be encoded.
Never specify a folder. No field exists for one.
Placeholders {{counter}} and {{today}} are reserved; any other {{token}} must match a CSV column.

Machine-readable schema

https://disk-tamer.com/agent-task.schema.json

Examples

Rename every draft file

{
  "version": "1",
  "steps": [
    {
      "operation": "rename",
      "selection": { "method": "rules", "filenameContains": "draft", "extensionEquals": ".txt" },
      "params": { "findText": "draft", "replaceText": "final", "preserveExtensions": true }
    }
  ]
}

Generate one file per CSV row

{
  "version": "1",
  "steps": [
    {
      "operation": "create",
      "selection": { "method": "tree" },
      "params": {
        "numberOfFiles": 1,
        "fileNames": "{{client}}-contract.txt",
        "useEmptyContent": false,
        "fileContent": "Agreement for {{client}}, dated {{today}}.",
        "csvContent": "client\nAcme\nBeta Ltd",
        "csvFileName": "clients.csv"
      }
    }
  ]
}

Delete temporary logs

{
  "version": "1",
  "steps": [
    {
      "operation": "delete",
      "selection": { "method": "rules", "filenameContains": "tmp", "extensionEquals": ".log" },
      "params": {}
    }
  ]
}

Handing the task to a user

Deep link. base64url-encode the JSON and send https://disk-tamer.com/en/run#t=<encoded>. The fragment never reaches a server. Limit 8000 characters — tasks carrying CSV data will not fit.
Paste. Print the JSON; the user opens Import Task and pastes it. No length limit.
File. Write a .disktamer file for the user to import.

Validation errors

Every issue carries a path such as steps[0].params.findText, and all issues are reported at once so a single correction fixes everything.

Code	Meaning
`invalid_json`	The document is not valid JSON, or is not an object.
`unsupported_version`	version must be the string "1".
`empty_steps`	steps is missing, not an array, or empty.
`multi_step_unsupported`	More than one step. Split into one task per step.
`unknown_operation`	operation is not create, edit, rename, move or delete.
`invalid_selection_method`	selection.method is not tree or rules.
`missing_field`	A required parameter is absent. The path names it.
`wrong_type`	A parameter has the wrong JSON type.
`invalid_enum_value`	A parameter is outside its allowed values.
`unknown_field`	Warning only — an unrecognised parameter, usually a typo.

Result receipt

After a run the user can copy a compact receipt back to you:

disk-tamer-result v1
operation: rename
matched: 142
ok: 139
failed: 3
- "Q1 Report.txt": collision — "2024 Q1 Report.txt" already exists
- "notes.txt": permission denied

Counters are normalized across operations. failed aggregates every non-success outcome that was not a deliberate skip; the per-item lines carry the reason. Filenames only — never full paths.