Workspace tools

Generated from the built-in tools registry. Do not edit by hand.

A run whose task declares workspace.* tools gets a throwaway clone of the repository named in its repo input. The repository sets the clone up itself (its .os/workspace.yml, or an install the runner detects), and the clone is destroyed when the run ends. A task without workspace.* tools never gets one.

These tools work on that clone only. Issues and pull requests stay with the enterprise's own GitHub tools. What a task may change is its write policy: writeAllow, rewriteAllow, writeDeny and appendOnly on the task version.

workspace.read_file

Read a file from the clone, whole or one numbered window of it.

What the model reads:

Read a file from the run workspace. Pass path for the whole file, or add startLine (1-based) and limit to read one numbered window of a large file. Prefer a window over a scratch script.

• Effect: read.
• Retry: Safe: repeating the call changes nothing.
• Called by: a run.
• Needs:
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
• Returns: The file as UTF-8 text, or the requested window of it with line numbers.

Example:

{
  "path": "src/index.ts"
}

Example:

{
  "path": "src/index.ts",
  "startLine": 200,
  "limit": 80
}

workspace.list_dir

List a directory in the clone.

What the model reads:

List a directory in the run workspace. Pass path (default .).

• Effect: read.
• Retry: Safe: repeating the call changes nothing.
• Called by: a run.
• Needs:
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
• Returns: The directory listing.

Example:

{
  "path": "src"
}

workspace.write_file

Write a whole file in the clone.

What the model reads:

Write a file in the run workspace. Pass path and content.

• Effect: write.
• Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Writing the same content again leaves the same file.
• Called by: a run.
• Needs:
  • The task version's workspace.writeAllow, rewriteAllow, writeDeny and appendOnly decide which paths it may change.
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
• Returns: { ok: true }.

Example:

{
  "path": "src/greeting.ts",
  "content": "export const greeting = 'hello'\n"
}

workspace.delete_file

Delete a file from the clone outright.

What the model reads:

Delete a file in the run workspace outright, instead of overwriting it empty. Pass path.

• Effect: write.
• Retry: Not retry-safe: a repeat acts again. A repeat finds nothing to delete and fails delete_file_missing; the file stays deleted.
• Called by: a run.
• Needs:
  • The task version's workspace.writeAllow, rewriteAllow, writeDeny and appendOnly decide which paths it may change.
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.

Example:

{
  "path": "src/unused.ts"
}

workspace.edit

Replace one exact piece of text in a file.

What the model reads:

Replace one exact piece of text in a workspace file. Pass path, oldString and newString. oldString must appear exactly once unless you pass replaceAll. Use this to change a file, not write_file, which rewrites the whole file.

• Effect: write.
• Retry: Not retry-safe: a repeat acts again. A repeat no longer finds oldString and fails edit_no_match; the first edit stands.
• Called by: a run.
• Needs:
  • The task version's workspace.writeAllow, rewriteAllow, writeDeny and appendOnly decide which paths it may change.
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.

Example:

{
  "path": "src/greeting.ts",
  "oldString": "'hello'",
  "newString": "'hello, world'"
}

workspace.search

Search the clone for a string or pattern.

What the model reads:

Search the run workspace for a string. Pass pattern, optionally globs (e.g. ["apps/api/**/*.ts"]), ignoreCase, regex, maxResults. Returns path, line and text per match. Use this instead of writing a script to grep.

• Effect: read.
• Retry: Safe: repeating the call changes nothing.
• Called by: a run.
• Needs:
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
• Returns: Path, line and text for each match.

Example:

{
  "pattern": "TODO",
  "globs": [
    "src/**/*.ts"
  ],
  "maxResults": 20
}

workspace.run_command

Run one allowlisted binary in the clone, with no shell.

What the model reads:

Run an allowlisted binary in the run workspace. Pass argv as a JSON array of strings. Example: {"argv":["git","status"]}. No shell, no pipes, no cd. Allowed bins: git, pnpm, npm, node, mise.

• Effect: write.
• Retry: Not retry-safe: a repeat acts again. The command runs again.
• Called by: a run.
• Needs:
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
• Returns: { code, stdout, stderr }.

Example:

{
  "argv": [
    "git",
    "status"
  ]
}

Example:

{
  "argv": [
    "npm",
    "test"
  ]
}

workspace.git_commit

Commit the tracked changes and the files this run wrote.

What the model reads:

Commit in the run workspace. Pass message. Stages tracked changes and the files you wrote or edited; a new file only a command created may be left out, so `git add` it with workspace.run_command first if it belongs in the commit.

• Effect: write.
• Retry: Not retry-safe: a repeat acts again. A repeat makes another commit, even an empty one.
• Called by: a run.
• Needs:
  • The task version's workspace.writeAllow, rewriteAllow, writeDeny and appendOnly decide which paths it may change.
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.

Example:

{
  "message": "Add the greeting"
}

workspace.git_push

Push the current branch, never the default one.

What the model reads:

Push the current non-default branch. No arguments.

No declared fields: the schema accepts any object.

• Effect: write.
• Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. A repeat with nothing new to push changes nothing.
• Called by: a run.
• Needs:
  • The task version's workspace.writeAllow, rewriteAllow, writeDeny and appendOnly decide which paths it may change.
  • A repo input on the run — a git remote address, or whatever short form the code host binding's git.repoTemplate custom prop expands — which the runner clones. A code host binding may name the repository instead, in its git.repo prop. A task without workspace.* tools never gets a clone.
  • A code host tool bound in the run's cascade whose git.host custom prop matches the remote: the push authenticates with that binding's credential, and with no other.