From 0198b9037d69bfdd7e8e9e9631f48ec450882af1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 6 Aug 2026 03:41:13 +0000 Subject: [PATCH] docker-agent: sync docs with docker-agent v1.122.0 --- .../docs/configuration/hooks/index.md | 2 +- .../docs/configuration/user-settings/index.md | 2 ++ .../docker-agent/docs/features/cli/index.md | 4 ++- .../docs/features/evaluation/index.md | 12 +++++--- .../docs/tools/background-agents/index.md | 2 ++ .../docs/tools/filesystem/index.md | 28 +++++++++++++------ .../docs/tools/session_plan/index.md | 2 +- .../docs/tools/transfer-task/index.md | 9 ++++++ _vendor/modules.txt | 2 +- go.mod | 2 +- go.sum | 2 ++ 11 files changed, 50 insertions(+), 17 deletions(-) diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md index 846287c4a858..34efe9d2b8e4 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/hooks/index.md @@ -216,7 +216,7 @@ Built-ins are typically zero-config and faster than equivalent shell hooks becau | `max_iterations` | `before_llm_call` | `[""]` (required) | Hard-stops the agent after `N` model calls. Stateless: the runtime supplies the iteration counter on every dispatch. | | `snapshot` | `session_start`, `turn_start`, `turn_end`, `pre_tool_use`, `post_tool_use`, `session_end` | _none_ | Records filesystem snapshots in a shadow git repo under the Docker Agent data directory. No-op outside git repos; respects the source repo's ignore rules and skips newly-added files larger than 2 MiB. | | `redact_secrets` | `pre_tool_use`, `before_llm_call`, `tool_response_transform` | _none_ | Scrubs detected secrets (API keys, tokens, private keys, …) out of tool call arguments, outgoing chat content, and tool output. The same builtin handles all three events and dispatches on the event name. Auto-registered on all three events by `redact_secrets: true` on the agent — see [`examples/redact_secrets_hooks.yaml`](https://github.com/docker/docker-agent/blob/main/examples/redact_secrets_hooks.yaml) for the manual wiring. | -| `limit_large_tool_results` | `tool_response_transform`, `session_end` | _none_ | **Always-on safety hook** — automatically injected by the runtime, no configuration required. When a tool result from the `filesystem`, `shell`, `mcp`, or `a2a` categories exceeds 2,000 lines or 50 KiB, the full payload is written to a per-session temp file and replaced in the conversation with a notice plus a bounded tail (last 2,000 lines, up to 50 KiB). The `session_end` leg deletes the temp directory. Internal toolsets (`memory`, `plan`, `tasks`, `think`, …) are not affected. | +| `limit_large_tool_results` | `tool_response_transform`, `session_end` | _none_ | **Always-on safety hook** — automatically injected by the runtime, no configuration required. When a tool result from the `filesystem`, `shell`, `mcp`, or `a2a` categories exceeds 2,000 lines or 50 KiB, the full payload is written to a per-session temp file and replaced in the conversation with a notice plus a bounded excerpt (2,000 lines, up to 50 KiB): the tail for most tools, but the head for the built-in filesystem `read_file`, whose notice suggests a follow-up call with `line`/`limit` to continue reading. The `session_end` leg deletes the temp directory. Internal toolsets (`memory`, `plan`, `tasks`, `think`, …) are not affected. | | `safer_shell` | `pre_tool_use` | _none_ | **Deprecated compatibility shim.** The runtime now classifies every shell command natively (`safe` / `destructive` / `unknown`) and gates it through the session's [safety mode](../permissions/index.md#safety-modes), so this builtin no longer emits verdicts. Pinned entries keep working as pure labellers that attach classification metadata (`safety_label`, `blast_radius`, `category`, `reason`) to the call. Filters by tool name internally (no-op for non-shell calls). | | `unload` | `on_agent_switch` | _none_ | POSTs `{"model": ""}` to each of the previous agent's DMR model endpoints (`/_unload` by default, overridable per-model via `unload_api`) to free the GPU/RAM the just-departing model was holding. Pure HTTP — reads the model snapshot the runtime ships on `on_agent_switch` and depends on no provider-specific runtime state. Non-DMR providers (OpenAI, Anthropic, …) are silently skipped, so cross-provider chains are safe. Errors are logged and swallowed; agent switching never blocks on a slow or unreachable engine (each call has a 10 s timeout). See [`examples/unload_on_switch.yaml`](https://github.com/docker/docker-agent/blob/main/examples/unload_on_switch.yaml). | diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md index 048f6fc1ce7c..4ff74860e8a6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/user-settings/index.md @@ -54,6 +54,7 @@ You rarely need to hand-edit this file. Most fields are managed from the TUI's ` | `cache_stable_prompts` | boolean | `false` | Keep changing trusted context (date, environment info, dynamic prompt files) out of the frozen system prefix and append chronological updates instead, improving prompt-cache hit rates on long sessions. | | `warn_on_cache_miss` | boolean | `false` | Warn when a model call after the first one in a session reports no cached input tokens (a prompt-cache miss). Managed from the **Notifications** tab of `/settings`. | | `busy_send_mode` | string | `steer` | What happens to a message sent while the agent is working: `steer` injects it into the ongoing stream; `queue` holds it until the current turn ends. | +| `interrupt_confirmation` | string | `always` | Controls how the Esc key interrupts a running stream: `always` (default) shows a confirmation dialog; `double-tap` requires pressing Esc twice within 1 second; `none` interrupts immediately without confirmation. Managed from the **Behavior** tab of `/settings`. | | `permissions` | object | _unset_ | Global tool-permission rules (`allow` / `ask` / `deny`), merged with agent-level and session-level permissions. See [Permissions](../permissions/index.md#global-permissions). | | `hooks` | object | _unset_ | Global lifecycle hooks applied to every agent, additive with agent-config and CLI hooks. See [Global (user-level) hooks](../hooks/index.md#global-user-level-hooks). | | `keybindings` | array | _unset_ | Remap TUI keyboard shortcuts. See [Custom Keybindings](../../features/tui/index.md#custom-keybindings) for the full list of actions and syntax. | @@ -101,6 +102,7 @@ settings: cache_stable_prompts: true warn_on_cache_miss: true busy_send_mode: queue + interrupt_confirmation: double-tap restore_tabs: true tab_title_max_length: 24 layout: diff --git a/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md index 5292a30277a8..23cac6ecfef4 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/cli/index.md @@ -461,7 +461,8 @@ $ docker agent eval | [|./evals] [flags] | `--judge-model` | `anthropic/claude-opus-5` | Model for LLM-as-a-judge relevance scoring (format: `provider/model`) | | `--output ` | `/results` | Directory for results, logs, and session databases | | `--only ` | (all) | Only run evals with file names matching these patterns (repeatable) | -| `--base-image` | (default) | Custom base Docker image for eval containers | +| `--base-image` | (default) | Custom base image for eval containers | +| `--container-runtime` | `docker` | Container runtime executable for building and running evaluations (e.g. `podman`) | | `--keep-containers` | `false` | Keep containers after evaluation (don't remove with `--rm`) | | `-e, --env` | (none) | Environment variables to pass to container (`KEY` or `KEY=VALUE`, repeatable) | | `--repeat ` | `1` | Number of times to repeat each evaluation (useful for computing baselines) | @@ -476,6 +477,7 @@ $ docker agent eval agent.yaml -c 8 # 8 concurrent evaluat $ docker agent eval agent.yaml --keep-containers # keep containers for debugging $ docker agent eval agent.yaml --only "auth*" # only run matching evals $ docker agent eval agent.yaml --repeat 5 # repeat each eval 5 times +$ docker agent eval agent.yaml --container-runtime podman # use a Docker-compatible runtime such as Podman ``` See [Evaluation](../evaluation/index.md) for details on creating eval sessions and interpreting results. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md b/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md index 8b1163afd342..03c36a9fc1c6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/evaluation/index.md @@ -15,9 +15,9 @@ _Measure agent quality with automated evaluations — tool call accuracy, respon The `docker agent eval` command runs your agent against a set of recorded sessions and scores the results. Each eval session captures a user question, the expected tool calls, and criteria the response must satisfy. Docker Agent replays the question, compares the agent's behavior to expectations, and produces a report. > [!NOTE] -> **Docker required** +> **Container runtime required** > -> Evaluations run inside Docker containers for isolation. Each eval gets a clean environment with optional setup scripts. Docker Desktop (or Docker Engine) must be running. +> Evaluations run inside containers for isolation. Each eval gets a clean environment with optional setup scripts. A running Docker-compatible container CLI/runtime is required: Docker Desktop or Docker Engine by default, or another Docker-compatible runtime such as Podman selected with `--container-runtime`. ## Quick Start @@ -39,6 +39,9 @@ $ docker agent eval agent.yaml --repeat 5 # Repeat a specific eval 5 times $ docker agent eval agent.yaml --only "auth*" --repeat 5 + +# Use a Docker-compatible runtime such as Podman +$ docker agent eval agent.yaml --container-runtime podman ``` ## Eval Directory Structure @@ -160,7 +163,8 @@ $ docker agent eval | [|./evals] | `--judge-model` | `anthropic/claude-opus-5` | Model for LLM-as-a-judge relevance scoring | | `--output` | `/results` | Directory for results, logs, and session databases | | `--only` | (all) | Only run evals with file names matching these patterns | -| `--base-image` | (default) | Custom base Docker image for eval containers (see [Custom Base Images](#custom-base-images)) | +| `--base-image` | (default) | Custom base image for eval containers (see [Custom Base Images](#custom-base-images)) | +| `--container-runtime` | `docker` | Container runtime executable for building and running evaluations (e.g. `podman`) | | `--keep-containers` | `false` | Keep containers after evaluation (don't remove with `--rm`) | | `-e, --env` | (none) | Environment variables to pass to container (`KEY` or `KEY=VALUE`) | | `--repeat` | `1` | Number of times to repeat each evaluation (useful for computing baselines) | @@ -219,7 +223,7 @@ After a run completes, Docker Agent produces: > [!TIP] > **Debugging Failed Evals** > -> Use `--keep-containers` to preserve containers after evaluation. You can then inspect them with `docker exec` to understand why an eval failed. The session database (`.db` file) contains the full conversation history for each eval. +> Use `--keep-containers` to preserve containers after evaluation. You can then inspect them with your selected runtime's `exec` command (`docker exec` by default, `podman exec` with `--container-runtime podman`) to understand why an eval failed. The session database (`.db` file) contains the full conversation history for each eval. ```bash $ docker agent eval demo.yaml ./evals diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md index 4ea266d4cfa0..0c6afbfaaed9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/background-agents/index.md @@ -32,6 +32,8 @@ The background agents tool lets an orchestrator dispatch work to sub-agents conc `run_background_agent` returns a **task ID** string. Tools run by the sub-agent inherit the parent session's permissions. Because background tasks run non-interactively, any tool call that would normally prompt the user for approval will be automatically denied. To allow background agents to run mutating tools, you must explicitly approve them in the parent session (e.g. via YOLO mode or explicit allow rules). +Background delegation shares the same runtime guards as `transfer_task`: delegation cycles are rejected and chains are capped at 10 nested delegations. See [Delegation Limits](../transfer-task/index.md#delegation-limits). + ### `view_background_agent` and `stop_background_agent` parameters | Parameter | Type | Required | Description | diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md index 8f0d49fe464b..921d25273518 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/filesystem/index.md @@ -11,13 +11,28 @@ _Read, write, list, search, and navigate files and directories._ ## Overview -The filesystem tool gives agents the ability to explore codebases, read and edit files, create new files, search across files, and navigate directory structures. Paths are resolved relative to the working directory, though agents can also use absolute paths. +The filesystem tool gives agents the ability to explore codebases, read and edit files, create new files, search across files, and navigate directory structures. + +### Path resolution + +Paths are resolved relative to the **working directory** (the directory where the agent session started, or the directory specified with `--workdir`): + +- **Relative paths** (e.g., `src/main.go`, `../README.md`) are joined with the working directory. +- **Absolute paths** must match the host operating system: + - Unix/Linux/macOS: `/home/user/project/file.txt` + - Windows: `C:\Users\user\project\file.txt` or `C:/Users/user/project/file.txt` +- **Home directory expansion**: paths starting with `~` or `~/` expand to the user's home directory. + +When a file is not found, error messages include the resolved absolute path to help diagnose incorrect base directories or path formats. + +> [!IMPORTANT] +> Agents must use paths appropriate for the host OS. A Windows absolute path like `C:\file.txt` on a Unix system (or vice versa) is rejected with a clear error message. ## Available Tools | Tool | Description | | ---------------------- | ------------------------------------------------------------------------- | -| `read_file` | Read the complete contents of a file | +| `read_file` | Read the contents of a file (whole file, or a line range of a text file) | | `read_multiple_files` | Read several files in one call (more efficient than multiple `read_file`) | | `write_file` | Create or overwrite a file with new content | | `edit_file` | Make line-based edits (find-and-replace) in an existing file | @@ -40,7 +55,7 @@ toolsets: | --- | --- | --- | --- | | `ignore_vcs` | boolean | `true` | When `true` (default), `.git` directories and `.gitignore` patterns are excluded from listings and searches. Set to `false` to include them. | | `post_edit` | array | `[]` | Commands to run after editing files matching a path pattern | -| `post_edit[].path` | string | — | Glob pattern for files (e.g., `*.go`, `src/**/*.ts`) | +| `post_edit[].path` | string | — | Glob pattern for files (e.g., `*.go`, `src/*/*.ts`) | | `post_edit[].cmd` | string | — | Command to run (use `${file}` for the edited file path) | | `allow_list` | array | `[]` | Directories the tools may access. Empty = unrestricted (default). | | `deny_list` | array | `[]` | Directories the tools must not access. Takes precedence over `allow_list`. | @@ -96,18 +111,15 @@ toolsets: cmd: "gofmt -w ${file}" - path: "*.ts" cmd: "prettier --write ${file}" - - path: "src/**/*.py" + - path: "src/*/*.py" cmd: "black ${file}" ``` | Property | Type | Description | | --- | --- | --- | -| `path` | string | Glob pattern matched against the file path. `*.go` matches any `.go` file; `src/**/*.ts` matches `.ts` files anywhere under `src/`. | +| `path` | string | Glob pattern matched against the file path. `*.go` matches any `.go` file; `src/*/*.ts` matches `.ts` files inside `src/`. | | `cmd` | string | Shell command to run. `${file}` expands to the absolute path of the just-edited file. | Post-edit commands run with the same working directory as the agent. If a command exits non-zero, the error is logged and surfaced to the model as a warning, but the edit is not rolled back. See [`examples/post_edit.yaml`](https://github.com/docker/docker-agent/blob/main/examples/post_edit.yaml) for a complete example. - -> [!TIP] -> The filesystem tool resolves paths relative to the working directory. Agents can also use absolute paths. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md index ad186a19900c..ea4c8e4970f0 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/session_plan/index.md @@ -81,7 +81,7 @@ Embedders that render the plan inline can subscribe and update without re-readin A session plan belongs to its session: hosts can read and export it, never change it. - **CLI** — the [`docker agent plans`](../../features/cli/index.md#docker-agent-plans) command group lists, reads (`get --session `), and exports session plans alongside shared plans. Mutations (`update`, `status`, `delete`) are refused with an `unsupported` error explaining the ownership rule. -- **TUI** — the `/plans` browser (see the [plan toolset docs](../plan/index.md#the-plans-browser-in-the-tui) for the full keybinding table) includes the **current session's** plan as the `session` scope row; plans of other sessions are never enumerated. Its identity is the session ID and its version column shows `-` — session plans have no versions. Enter opens the read-only detail (scope, session ID, update time, scrollable markdown) and x exports to `session-plan-.md` in the working directory (refusing to overwrite an existing file). Status, edit, and delete visibly report that session plans don't support them instead of attempting the write. The browser refreshes live on the `session_plan_updated` event, so a plan the agent just wrote appears without reopening. +- **TUI** — the `/plans` browser (see the [plan toolset docs](../plan/index.md#the-plans-browser-in-the-tui) for the full keybinding table) includes the **current session's** plan as the `session` scope row; plans of other sessions are never enumerated. Its identity is the session ID and its version column shows `-` — session plans have no versions. Enter opens the detail view (scope, session ID, update time, scrollable markdown) and x exports to `session-plan-.md` in the working directory (refusing to overwrite an existing file). e opens the plan body in your external editor (`$VISUAL` or `$EDITOR`) for editing — the write is unguarded and last-write-wins by design. Status and delete visibly report that session plans don't support them (session plans belong to their session and carry no shared-plan metadata). The browser refreshes live on the `session_plan_updated` event, so a plan the agent just wrote appears without reopening. ## Example diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md index ebbad5274615..9d3bc2a03a07 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/transfer-task/index.md @@ -58,6 +58,15 @@ The `transfer_task` tool takes three parameters: The call blocks until the sub-agent returns its result, which becomes the tool's response. For non-blocking parallel delegation, use [`background_agents`](../background-agents/index.md) instead. +## Delegation Limits + +Sub-agents can have `sub_agents` of their own, so multi-level delegation chains are supported. Two runtime guards keep chains sane, applied to both `transfer_task` and `run_background_agent`: + +- **Cycles are rejected.** A delegation targeting an agent that is already part of the active delegation chain (for example `a -> b -> a`) fails with an error naming the cycle. +- **Depth is capped at 10 nested delegations.** The root agent delegating to its first sub-agent counts as depth 1; a call that would exceed the cap fails with an error stating the attempted depth. + +A rejected delegation returns a tool error to the calling agent and never starts the sub-agent. + > [!TIP] > **See also** > diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 95c6fed01647..bf8f1dcb02a6 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -4,4 +4,4 @@ # github.com/docker/cli v29.7.1+incompatible # github.com/docker/compose/v5 v5.4.0 # github.com/docker/model-runner v1.1.36 -# github.com/docker/docker-agent v1.120.0 +# github.com/docker/docker-agent v1.122.0 diff --git a/go.mod b/go.mod index 757b6c39d7dc..3a95db34e741 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,7 @@ require ( github.com/docker/buildx v0.36.1 github.com/docker/cli v29.7.1+incompatible github.com/docker/compose/v5 v5.4.0 - github.com/docker/docker-agent v1.120.0 + github.com/docker/docker-agent v1.122.0 github.com/docker/model-runner v1.1.36 github.com/moby/buildkit v0.32.2 github.com/moby/moby/api v1.55.0 diff --git a/go.sum b/go.sum index a31a466255c7..69f1b492b3d7 100644 --- a/go.sum +++ b/go.sum @@ -148,6 +148,8 @@ github.com/docker/docker-agent v1.110.0 h1:B5LJRkEvIk1WLojMR09gD6ZAD2hD43SIRSbjK github.com/docker/docker-agent v1.110.0/go.mod h1:TcrFxPYbc9SL0ouAcb/YwwjePfS0ULYkzfTJkvDUfzY= github.com/docker/docker-agent v1.120.0 h1:aogSNNlZWiL/6EYmrXhEtkqIgEcL7wt2bhYItgjan4o= github.com/docker/docker-agent v1.120.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= +github.com/docker/docker-agent v1.122.0 h1:xOei5d7L1M0stvZNwULnOssOS4CzDRE2Xj7k192rS3Q= +github.com/docker/docker-agent v1.122.0/go.mod h1:HgHOV3OkqM1Hl0qD7iTCBZSBNWpy5mWN2s8tr2/NdOA= github.com/docker/docker-credential-helpers v0.9.3 h1:gAm/VtF9wgqJMoxzT3Gj5p4AqIjCBS4wrsOh9yRqcz8= github.com/docker/docker-credential-helpers v0.9.3/go.mod h1:x+4Gbw9aGmChi3qTLZj8Dfn0TD20M/fuWy0E5+WDeCo= github.com/docker/docker-credential-helpers v0.9.5 h1:EFNN8DHvaiK8zVqFA2DT6BjXE0GzfLOZ38ggPTKePkY=