diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md index 17b70ce5e85c..9b57537a588f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/agents/index.md @@ -95,14 +95,27 @@ $ docker agent run agent.yaml /greet Commands support environment variable interpolation using JavaScript template literal syntax. Undefined variables expand to empty strings. -## Default Agent +## Built-in Agents -Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses a capable built-in default agent for quick tasks without needing any configuration. +Docker Agent includes two built-in agents: + +- **`default`**: A capable coding agent with a development workflow, file and shell tools, skills, environment information, and project instructions from `AGENTS.md`. +- **`minimal`**: A small general-purpose configuration with a concise instruction and file, shell, and fetch tools. It uses automatic model selection. + +The former `coder` built-in is now `default`; use `docker agent run default` for coding tasks. + +### Default Agent + +Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses `default`. ```bash # Use the project config or built-in default agent $ docker agent run +# Explicitly choose a built-in agent +$ docker agent run default +$ docker agent run minimal + # Override the default with an alias $ docker agent alias add default /path/to/my-agent.yaml $ docker agent run # now runs your custom agent diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md index cc20031517e3..d482e7fcc964 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/models/index.md @@ -96,7 +96,7 @@ Control how much the model "thinks" before responding: | Provider | Format | Values | Default | | ---------- | ---------- | ------------------------------------------------------------------- | -------------------------------- | | OpenAI | string | `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | `medium` (always-reasoning models only) | -| Anthropic | int or str | 1024–32768 tokens, or `adaptive`, `adaptive/`, effort level | off | +| Anthropic | int or str | Fixed budgets: ≥1024 and less than `max_tokens`; or `adaptive`, `adaptive/`, effort level | Model-dependent; Claude 5.x defaults to adaptive | | Gemini 2.5 | int | 0 (off), -1 (dynamic), or token count | -1 (dynamic) | | Gemini 3 | string | `minimal`, `low`, `medium`, `high` | varies | | All | string/int | `none` or `0` clears Docker Agent's local config | — | @@ -107,8 +107,9 @@ endpoints running GPT-5.x from 5.6 onward or GPT-6 Sol/Luna, `none` is a real reason. On GPT-6 Astra and older OpenAI models, `none`/`0` only clear the local `thinking_budget` — omitting the field has the same effect — and the model falls back to the API's own default effort (still reasoning internally for always-reasoning models like the o-series). -Providers with a true optional-thinking switch (Gemini 2.5, Claude, local -models) are fully disabled by `none`/`0`. See the +Models that support disabling thinking (including applicable Gemini 2.5, Claude, +and local models) can honor `none`/`0`. Claude models that require thinking +instead use adaptive thinking with low effort. See the [Thinking / Reasoning guide](../../guides/thinking/index.md#disabling-thinking) for the full per-provider breakdown. diff --git a/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md b/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md index 082a38ddf680..76bf18e116b6 100644 --- a/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/concepts/multi-agent/index.md @@ -64,9 +64,9 @@ transfer_task( ``` > [!NOTE] -> **Auto-Approved** +> **Approval rules still apply** > -> Unlike other tools, `transfer_task` is always auto-approved — no user confirmation needed. This allows seamless delegation between agents. +> `transfer_task` carries a read-only hint and normally runs without confirmation under the default policy. Strict mode, permission rules, and hooks can still require approval or block delegation. The delegated agent's own tool calls are checked separately. ## Handoffs Routing @@ -196,6 +196,18 @@ agents: toolsets: - type: think - type: background_agents + researcher: + model: anthropic/claude-sonnet-4-5 + description: Finds relevant research + instruction: Research the assigned topic and report your findings. + analyst: + model: anthropic/claude-sonnet-4-5 + description: Analyzes the project architecture + instruction: Analyze the assigned problem and explain your conclusions. + writer: + model: anthropic/claude-sonnet-4-5 + description: Drafts reports + instruction: Write a clear report from the provided findings. ``` The coordinator can then: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md index 586d2a5d03a5..5f8bd3b8d56b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/agents/index.md @@ -381,7 +381,7 @@ agents: ## Deferred Tool Loading -Toolsets support `defer` to load tools on-demand and speed up agent startup. See [Deferred Tool Loading](../tools/index.md#deferred-tool-loading) for details. +Toolsets support `defer` to expose tool definitions to the model on demand and reduce prompt size. The underlying toolsets still start normally. See [Deferred Tool Loading](../tools/index.md#deferred-tool-loading) for details. ```yaml agents: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md index 65e295131721..5be1649dbb78 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/agentsignore/index.md @@ -62,6 +62,10 @@ When `.agentsignore` contains at least one active pattern, the filesystem toolse > [!NOTE] > `.agentsignore` is independent of the filesystem toolset's [`ignore_vcs`](../tools/index.md) option. Setting `ignore_vcs: false` turns off `.gitignore` filtering but does **not** un-hide `.agentsignore` entries. +## Worktrees + +When a source checkout has a [`.worktreeinclude`](../../features/cli/index.md#copy-ignored-files-into-worktrees), files blocked by its `.agentsignore` are skipped even if they match the include patterns. The `.agentsignore` file itself is not copied by that mechanism. A worktree loads its own `.agentsignore` independently; commit or otherwise arrange its rules when needed, including for files already tracked in the worktree. + ## Relationship to `.gitignore` They are separate, and they do different amounts of work. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md index 0c96ce28b31f..acaaf12f288f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/budget/index.md @@ -194,6 +194,8 @@ This is the same granularity [`max_iterations`](../agents/index.md) has, and it The `max_tokens` in a budget is a **cumulative** count of tokens across the whole run: fresh input, cache-read input, cache-write input, and output all count towards it. It is unrelated to the provider- or model-level [`max_tokens`](../models/index.md), which caps the output of a single response. +When a server-side fallback (for example [Anthropic server-side fallbacks](../../providers/anthropic/index.md#server-side-fallbacks)) serves a turn, the token budgets count the tokens of every attempt, including declined ones, not just the final model's usage. + It is also not the session's context length: compaction resets that, while the budget keeps counting. ## Examples 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 d898512efdc9..f4840d32bedb 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 @@ -62,7 +62,7 @@ Docker Agent dispatches the following hook events: | `on_agent_switch` | When the runtime moves the active agent (transfer_task, handoff, return) | No | | `on_session_resume` | When the user explicitly approves continuation past `max_iterations` | No | | `on_tool_approval_decision` | After the runtime's approval chain (permissions / yolo / readonly / ask) resolves | No | -| `worktree_create` | After `docker agent run --worktree` creates a git worktree, before the session | Yes | +| `worktree_create` | After a git worktree is created — by `docker agent run --worktree` (before the session) or for a [background agent task](../../tools/background-agents/index.md#isolated-coding-tasks) with `worktree: true` (before the child's tools load) | Yes | | `before_agent_run` | Once per agent activation, before its model runs — can [route](#agent-routing-hooks) to another agent | Yes | | `after_agent_complete` | Once after an agent completes successfully — can [route](#agent-routing-hooks) onward | Yes | @@ -80,7 +80,7 @@ The shared catalog in `pkg/hooks/events` drives configuration validation, dispatch strategy, output aggregation, and strict output validation. Tests keep this table, the configuration fields, and the JSON schema synchronized. “Context” means additional context is consumed by the runtime; `worktree_create` -shows it to the CLI user. The internal preempting `pre_tool_use` lane is parallel, +shows it to the CLI user, or adds it to the instructions of an isolated background task. The internal preempting `pre_tool_use` lane is parallel, collects metadata, and does not rewrite input. | Event | Execution | Can block | Failure default | Context | Rewrite | @@ -293,6 +293,7 @@ Built-ins are typically zero-config and faster than equivalent shell hooks becau | `redact_secrets` | `tool_input_transform`, `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. | | `transform_json` | `tool_response_transform` | JSON field names | Keeps only the named top-level fields of a JSON object. Nested values are preserved; missing fields are omitted. No expression language or domain validation. | | `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`, `background_jobs`, `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 (up to 2,000 excerpt lines; 50 KiB including the notice): 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. If saving the payload fails, a bounded inline excerpt is returned without a file reference. Background-job excerpts retain status metadata before the log tail. The `session_end` leg deletes the temp directory. Internal toolsets (`memory`, `plan`, `tasks`, `think`, …) are not affected. | +| `keep_awake` | `session_start`, `session_end` | _none_ | CLI-owned sleep inhibitor, controlled by the disabled-by-default `settings.keep_awake` preference. | | `http_post` | Any event | `[URL, body]` | Sends an HTTP POST request with the optional body in `args[1]` to the URL in `args[0]`. Missing or empty URLs are ignored; only HTTP(S) destinations are accepted, using an SSRF-safe transport. | | `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 calls other than `shell` and `run_background_job`). | | `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). | @@ -311,6 +312,8 @@ Historical tool results are also bounded on outgoing chat and compaction request > `limit_large_tool_results` is injected unconditionally by the runtime — it is always active and cannot be removed from config. +The CLI also installs `keep_awake` on `session_start` and `session_end`. It uses [`github.com/rumpl/keepawake`](https://github.com/rumpl/keepawake) to hold a native sleep inhibitor for each run when `settings.keep_awake` is enabled. The setting is disabled by default and available in both TUIs. Cleanup runs even after cancellation or errors; acquisition failures warn without blocking the agent. This builtin is registered by the CLI, not the base runtime. + A minimal snapshot wiring looks like this: ```yaml @@ -1042,7 +1045,9 @@ hooks: fi ``` -Unlike most events, `worktree_create` is dispatched from the CLI rather than the run loop, because the worktree (and the working directory the runtime, session, tools, and snapshot machinery all capture) must be settled before the runtime and session exist. See [`examples/worktree_create_hook.yaml`](https://github.com/docker/docker-agent/blob/main/examples/worktree_create_hook.yaml) for the full file. +`worktree_create` also fires when `run_background_agent` is called with `worktree: true`. Hooks run inside the task's new checkout with `agent_name` and `parent_session_id` set, before the child's toolsets and skills are loaded. Their additional context is added to the child's instructions, and a blocking decision (or error) fails the task; the checkout and branch are retained. + +For `docker agent run --worktree`, `worktree_create` is dispatched from the CLI rather than the run loop, because the worktree (and the working directory the runtime, session, tools, and snapshot machinery all capture) must be settled before the runtime and session exist. See [`examples/worktree_create_hook.yaml`](https://github.com/docker/docker-agent/blob/main/examples/worktree_create_hook.yaml) for the full file. ### Pre-Compact: steer the summary @@ -1260,6 +1265,18 @@ request -> evaluator +-- specialist --------------+-> final answer ``` ```yaml +evaluators: + task_route: + provider: typesafe + model: jev-latest + type: choice + instructions: Classify the work required by the request in input. + choices: + simple: A narrow question or routine explanation. + complex: A problem requiring detailed analysis. + research: A request requiring investigation and evidence. + unclear: A request missing essential information. + agents: root: model: openai/gpt-5-mini @@ -1273,6 +1290,18 @@ agents: routing_policy: routes: {simple: quick, complex: specialist, research: researcher, unclear: clarifier} min_probability: 0.85 + quick: + model: openai/gpt-5-mini + instruction: Answer the question directly. + specialist: + model: openai/gpt-5-mini + instruction: Analyze the problem and explain your conclusions. + researcher: + model: openai/gpt-5-mini + instruction: Investigate the request and report evidence and limitations. + clarifier: + model: openai/gpt-5-mini + instruction: Ask for the missing information needed to answer the request. ``` See [`examples/hook_routing.yaml`](https://github.com/docker/docker-agent/blob/main/examples/hook_routing.yaml) diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md index 34b876ae26b4..e5901d83dbd5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/models/index.md @@ -18,11 +18,12 @@ models: first_available: [list] # Optional: candidate model refs, tried in order by available credentials. # Mutually exclusive with other model settings. provider: string # Required unless using first_available. One of: openai, anthropic, google, amazon-bedrock, - # dmr, mistral, xai, nebius, nvidia, minimax, baseten, daoxe, ovhcloud, groq, fireworks-ai, deepseek, cerebras, togetherai, huggingface, moonshotai, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, api-route, atlascloud, + # dmr, mistral, xai, nebius, nvidia, minimax, baseten, daoxe, ovhcloud, groq, fireworks-ai, deepseek, cerebras, togetherai, huggingface, moonshotai, vercel, cloudflare-workers-ai, cloudflare-ai-gateway, requesty, openrouter, opper, runcrate, api-route, lunaroute, orcarouter, atlascloud, cloudgpu, obscurify, hopbase, # azure, ollama, github-copilot, or a named provider defined # under the top-level `providers:` section. model: string # Required: model identifier description: string # Optional: human-readable summary of the model's purpose or strengths + stream_idle_timeout: duration|-1 # Optional: per-model stream idle limit temperature: float # Optional: 0.0–2.0 (provider-dependent; e.g. Anthropic caps at 1.0) max_tokens: integer # Optional: response length limit top_p: float # Optional: 0.0–1.0 @@ -55,14 +56,58 @@ models: bypass_models_gateway: boolean # Optional: skip the models gateway for this model (implied by a custom base_url) ``` +## Stream idle timeout + +`runtime.stream_idle_timeout` sets the default for agent conversation streams, +including subagents, inline models, model switches, fallbacks, routed models, +and LLM compaction summaries. Imported agent files use their own runtime +defaults. For each attempt, an explicit routed target setting takes precedence +over the router or fallback entry setting, which takes precedence over the +agent file's runtime setting. + +Use a positive Go duration such as `90s` or `2m30s`, or the integer `-1` to +disable the idle timer, overriding any lower-priority setting. Zero and other +negative values are invalid. An omitted or null value inherits the next setting; +when no setting applies, the idle timer is disabled for all models, including +Gemini Flex and routed requests. A short configured timeout can expire while a +Flex request is still queued. + +The timer measures silence while waiting for the first chunk and between chunks, +not total request duration. Each chunk resets it. If it expires, Docker Agent +cancels the model request and handles the stalled stream as a failure. Disabling +the timer leaves stalled streams waiting until the caller cancels or the +connection closes; normal cancellation still works. Title generation and model +hooks do not use this idle timer: they retain their separate total deadlines +(30 seconds for titles and the configured per-hook timeout). Setting `-1` does +not remove those deadlines. + +```yaml +runtime: + stream_idle_timeout: 10m +models: + slow: + provider: google + model: gemini-2.5-flash + stream_idle_timeout: 20m + local: + provider: ollama + model: llama3 + stream_idle_timeout: -1 +agents: + root: + model: slow + instruction: You are a helpful assistant. +``` + ## Properties Reference | Property | Type | Required | Description | | --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- | | `first_available` | array | ✗ | Candidate model references tried in order; selects the first whose credentials are configured. Mutually exclusive with other model settings. | -| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `api-route`, `atlascloud`, `azure`, `ollama`, `github-copilot`, `chatgpt`, `opencode`, `opencode-go`, or any [named provider](../../providers/custom/index.md). | +| `provider` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Provider: `openai`, `anthropic`, `google`, `amazon-bedrock`, `dmr`, `mistral`, `xai`, `nebius`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `opper`, `runcrate`, `api-route`, `lunaroute`, `orcarouter`, `atlascloud`, `cloudgpu`, `obscurify`, `hopbase`, `azure`, `ollama`, `github-copilot`, `chatgpt`, `opencode`, `opencode-go`, or any [named provider](../../providers/custom/index.md). | | `model` | string | ✓/✗ | Required for regular model definitions; omitted for `first_available` selectors. Model name (e.g., `gpt-4o`, `claude-sonnet-4-5`, `gemini-3.5-flash`) | | `description` | string | ✗ | Informational, human-readable summary of the model's purpose or strengths (e.g., "fast and cheap, good for summaries"). Not sent to the model. Can be combined with `first_available` (a selector's description is kept when it resolves). | +| `stream_idle_timeout` | duration/int | ✗ | Maximum silence between stream chunks; overrides `runtime.stream_idle_timeout`. See [Stream idle timeout](#stream-idle-timeout). | | `temperature` | float | ✗ | Sampling randomness. Range is provider-dependent — typically `0.0–2.0` (Anthropic caps at `1.0`). `0.0` is deterministic. | | `max_tokens` | int | ✗ | Maximum response length in tokens | | `top_p` | float | ✗ | Nucleus sampling threshold (`0.0–1.0`) | @@ -462,7 +507,7 @@ Use a string effort level. See [Gemini thinking budgets](../../providers/google/ thinking_budget: none # or 0 ``` -`none` and `0` both clear Docker Agent's local thinking configuration (omitting `thinking_budget` has the same effect). Whether that reaches the API as a real "off" switch depends on the model — see [Disabling Thinking](../../guides/thinking/index.md#disabling-thinking) in the guide. +`none` and `0` request disabled thinking, but their effect depends on the model. Omitting `thinking_budget` leaves model defaults in place and is not necessarily equivalent: some Claude models disable thinking explicitly, while those that require it use adaptive thinking with low effort. See [Disabling Thinking](../../guides/thinking/index.md#disabling-thinking) in the guide. ## Task Budget @@ -558,7 +603,7 @@ for a complete local-server configuration. ## Custom HTTP Headers For OpenAI-compatible providers (`openai`, `github-copilot`, `mistral`, `xai`, -`nebius`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `atlascloud`, `ollama`, and any custom provider using the OpenAI API), +`nebius`, `nvidia`, `minimax`, `baseten`, `daoxe`, `ovhcloud`, `groq`, `fireworks-ai`, `deepseek`, `cerebras`, `togetherai`, `huggingface`, `moonshotai`, `vercel`, `cloudflare-workers-ai`, `cloudflare-ai-gateway`, `requesty`, `openrouter`, `opper`, `runcrate`, `lunaroute`, `orcarouter`, `atlascloud`, `cloudgpu`, `obscurify`, `hopbase`, `ollama`, and any custom provider using the OpenAI API), `provider_opts.http_headers` adds arbitrary HTTP headers to every outgoing request: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md index 47ce1666e167..0a739bf01285 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/overview/index.md @@ -17,7 +17,7 @@ A Docker Agent config can be written in YAML or HCL. The examples on this page u A Docker Agent config has these main sections: -```bash +```yaml # 1. Version — configuration schema version (optional but recommended) version: 16 @@ -50,6 +50,7 @@ rag: strategies: - type: chunked-embeddings embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 # 6. MCPs — reusable MCP server definitions (optional) mcps: @@ -155,7 +156,7 @@ See [Provider Credentials](../../providers/overview/index.md#provider-credential | `DOCKER_AGENT_HIDE_TELEMETRY_BANNER`| Set to `1` to suppress the first-run telemetry notice. | | `DOCKER_AGENT_AUTO_UPDATE` | Set to a truthy value (`1`, `true`, `yes`, `on`) to let standalone release binaries self-update before running. See [Optional Self-Updates](../../getting-started/installation/index.md#optional-self-updates). | | `DOCKER_AGENT_NO_TOKEN_EXCHANGE` | Set to `1` to stop Docker Agent from exchanging the access token stored by `docker login` for a Docker token. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). | -| `DOCKER_AGENT_HUB_LOGIN_URL` | Point the token exchange at a Docker staging environment. Ignored unless it is an HTTPS `docker.com` URL. | +| `DOCKER_AGENT_HUB_LOGIN_URL` | Point the token exchange at a Docker staging environment. Ignored unless it is an HTTPS `docker.com` URL. A staging host, such as `hub-stage.docker.com`, also makes Docker Agent read staging sessions from the Docker secrets engine. | | `DOCKER_AGENT_DISABLE_DESKTOP_PROXY` | Set to a truthy value (`1`, `true`, `yes`, `on`) to bypass Docker Desktop's PAC adapter per request and restore standard `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY`/`NO_PROXY` routing. | > [!NOTE] @@ -278,13 +279,13 @@ Docker Agent validates your configuration at startup: - Named model references must exist in the `models` section - Provider names must be valid (`openai`, `anthropic`, `google`, `dmr`, etc.) - Required environment variables (API keys) must be set -- Tool-specific fields are validated (e.g., `path` is only valid for `memory`) +- Tool-specific fields are validated (e.g., `path` is only valid for `memory` and `tasks`) ## JSON Schema For YAML editor autocompletion and validation, use the [Docker Agent JSON Schema](https://github.com/docker/docker-agent/blob/main/agent-schema.json). Add this to the top of your YAML file: -```bash +```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/docker/docker-agent/main/agent-schema.json ``` @@ -467,7 +468,7 @@ agents: | Field | Description | | --------------------- | ---------------------------------------------------------------------------------------- | | `provider` | Underlying provider type: `openai` (default), `anthropic`, `google`, `amazon-bedrock`, etc. | -| `api_type` | API schema: `openai_chatcompletions` (default) or `openai_responses`. OpenAI-only. | +| `api_type` | API schema: `openai_chatcompletions` or `openai_responses`. If omitted, selected from the model: Responses for supported newer OpenAI models, Chat Completions otherwise. Applies to OpenAI-compatible providers. | | `base_url` | Base URL for the API endpoint. Required for OpenAI-compatible providers. | | `token_key` | Environment variable name for the API token. | | `temperature` | Default sampling temperature. | diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md index b04b6a5bfefa..3d194e99eaa7 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/permissions/index.md @@ -255,28 +255,39 @@ permissions: - "shell" ``` -### Safe Shell Agent +### Shell Agent with Safety Classification -Allow specific safe commands, block dangerous ones: +Use balanced safety without broad command-prefix allows: ```yaml -permissions: - allow: - - "shell:cmd=ls*" - - "shell:cmd=cat*" - - "shell:cmd=grep*" - - "shell:cmd=find*" - - "shell:cmd=head*" - - "shell:cmd=tail*" - - "shell:cmd=wc*" - deny: - - "shell:cmd=sudo*" - - "shell:cmd=rm*" - - "shell:cmd=mv*" - - "shell:cmd=chmod*" - - "shell:cmd=chown*" +runtime: + safety: balanced ``` +Balanced runs positively classified safe calls automatically and asks for approval +for unknown or destructive calls; it does not automatically deny them. This applies +to both `shell` and `run_background_job`. + +Explicit allow grants authorize matching arguments and override the safety mode's +fallback, including strict and restricted. For example, `shell:cmd=find*` also +authorizes `find / -exec rm -rf {} +` and +`find . -maxdepth 1 -name seed -exec sh -c 'touch marker' {} +`. A command name +alone does not establish that its arguments are safe. Avoid these broad grants +when you want classification to decide whether approval is needed. + +For these two builtin command tools, allow rules whose `cmd` value is a literal +followed by a single `*` reject shell chaining, redirection, and substitutions. +Command-name prefixes such as `cmd=ls*` additionally require a token boundary, +so they do not authorize `lsanything`. Argument and path prefixes such as +`cmd=ls *`, `cmd=git commit *`, and `cmd=ls /tmp/*` retain prefix matching. +Ordinary colons in values (quoted filenames or URLs) remain literal; only +`:key=` introduces another condition. + +This hardening does not inspect execution or write options such as `find -exec`. +Other glob shapes (`cmd=ls**`, `cmd=[l]s*`) and the `command=ls*` condition +retain generic matching and can authorize compound commands. Bare-tool grants, +`cmd=*`, and exact compound-command grants also remain broad explicit opt-ins. + ### MCP Tool Permissions Control MCP tools by their qualified names: diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md index fb2a4e704775..538f5adc42eb 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/sandbox/index.md @@ -98,7 +98,7 @@ weakening a kit's restrictions or silently copying local credentials. Any provider, registry, or tool endpoint the agent needs must be reachable under the cloud policy. CLI-specified model, safety, flavor, and prompt options still apply. -Docker Agent uses `sbx --cloud run --detached`, then `exec`: this supports sbx's +Docker Agent uses `sbx --cloud run --detach`, then `exec`: this supports sbx's v3 source builds and multi-kit assembly without launching a second agent TUI. Provisioning messages go to stderr, leaving stdout for the agent (including `--json` output). Piped/headless execution does not allocate a TTY. @@ -367,10 +367,10 @@ This host auto-kit is distinct from an sbx workload/mixin kit. It is built for l For the agent referenced on the command line, the kit collects: - **Local [skills](../../features/skills/index.md)** — every `SKILL.md` discovered on the host (global `~/.codex/skills/`, `~/.claude/skills/`, `~/.agents/skills/`, plus project `.claude/skills/`, `.github/skills/` and `.agents/skills/`) is copied under `/skills//`. The in-sandbox skills loader reads from the kit instead of the (non-existent) host `$HOME`. -- **Prompt files** — every file referenced via the agent's `add_prompt_files` (`AGENTS.md`, `CLAUDE.md`, …) is collected. Files that already live under the working directory are left alone (the live workspace mount surfaces them); files outside it (e.g. an `AGENTS.md` in `$HOME`) are copied under `/prompt_files/`. +- **Prompt files** — every file referenced via the agent's `add_prompt_files` (`AGENTS.md`, `CLAUDE.md`, …) is collected. Paths under the working directory are left to the live workspace mount, even when a file or intermediate directory is a symlink pointing outside it. Such links do not cause their host targets to be copied into the kit and may be unreadable inside the sandbox. Files discovered outside the workspace (e.g. an `AGENTS.md` in `$HOME` or a parent directory) are still copied under `/prompt_files/`, unless they resolve into the workspace. - **A manifest** — `/manifest.json` records what was staged. The on-disk copy is sanitised so it cannot be used to map the host filesystem from inside the sandbox. -Before launch, Docker Agent prints a summary of what was staged so you can see exactly which skills and prompt files the agent will have access to inside the sandbox. +Before launch, Docker Agent prints a summary of staged skills and prompt files, plus prompt-file paths left to the workspace mount. A workspace entry does not guarantee that its symlink target is accessible inside the sandbox. When building a kit, `add_prompt_files` entries must be local relative paths (e.g. `AGENTS.md` or `instructions/AGENTS.md`), not absolute paths or paths diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md index 1092dbfff410..0fee4ac7a22c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/structured-output/index.md @@ -252,4 +252,4 @@ agents: > [!WARNING] > **Tool Limitations** > -> When using native structured output, the agent typically cannot use tools since its response format is constrained to the schema. Design your agent workflow accordingly — native structured output agents work best for single-turn analysis or extraction tasks. Use `mode: tool` when the agent needs to call tools before producing its schema-constrained final answer. +> Native structured output can coexist with tool calls when the provider and model support both; Docker Agent sends the tools alongside the output schema. Check your provider's restrictions rather than assuming tools are disabled. Use `mode: tool` when native schemas are unsupported or you want the final response submitted through an explicit output tool. diff --git a/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md index e115044986f8..0f25785ccde3 100644 --- a/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/configuration/tools/index.md @@ -23,7 +23,7 @@ Built-in tools are included with Docker Agent and require no external dependenci | `shell` | Execute shell commands synchronously | [Shell](../../tools/shell/index.md) | | `background_jobs` | Run and manage long-running shell commands | [Background Jobs](../../tools/background-jobs/index.md) | | `scheduler` | Schedule instructions to run at a time or on a recurring interval | [Scheduler](../../tools/scheduler/index.md) | -| `environment` | Report the OS and resolved shell (read-only, no arguments, auto-approved) | [Environment](../../tools/environment/index.md) | +| `environment` | Report the OS and resolved shell (read-only, no arguments; subject to approval policy) | [Environment](../../tools/environment/index.md) | | `datetime` | Current date and time in a model-chosen format and timezone (read-only) | [Date and Time](../../tools/datetime/index.md) | | `calculator` | Exact arithmetic without code execution | [Calculator](../../tools/calculator/index.md) | | `think` | Reasoning scratchpad | [Think](../../tools/think/index.md) | @@ -374,7 +374,7 @@ See [`examples/toolset_instructions.yaml`](https://github.com/docker/docker-agen ## Deferred Tool Loading -Load tools on-demand to speed up agent startup. When a toolset is deferred, its tools are registered lazily — the tool server process is not started until the agent first calls one of its tools. This is useful for large toolsets (e.g., an MCP server with hundreds of tools) where startup time matters. +Expose tool definitions to the model on demand to reduce prompt size. Deferred toolsets still start normally, including their MCP server processes, but their tool definitions stay hidden until activated. This is useful for large toolsets, such as an MCP server with hundreds of tools; it does not delay server startup. ```yaml toolsets: @@ -426,7 +426,7 @@ models: Every deferred tool is then declared to the API with `defer_loading: true` next to a server-executed `tool_search` tool, so the model discovers and calls deferred tools directly, without a `search_tool`/`add_tool` round trip. `search_tool` and `add_tool` stay available. Toolset `tools`, `read_only`, and skill allow-lists apply to the catalog exactly as they do to regular tools, and so do permissions. -The option is ignored, and the legacy behaviour kept, for models without support (only `openai` models that support deferred tools qualify; the `chatgpt` provider and OpenAI-compatible endpoints, including `openai` with a custom `base_url`, do not), on Chat Completions requests, and on fallback models without the option. Agents using `code_mode_tools` keep the legacy behaviour: wrapped tools are reachable through `run_tools_with_javascript`, while todo and repeatable tools remain directly callable. +The option is ignored, and the legacy behaviour kept, for models without support (only `openai` models that support deferred tools qualify; the `chatgpt` provider and OpenAI-compatible endpoints, including `openai` with a custom `base_url` or `OPENAI_BASE_URL`, do not), on Chat Completions requests, and on fallback models without the option. Agents using `code_mode_tools` keep the legacy behaviour: wrapped tools are reachable through `run_tools_with_javascript`, while todo and repeatable tools remain directly callable. Native search also enables ordered response replay, including encrypted reasoning. For native-only workflows, tell the agent to prefer native tool search over `search_tool`/`add_tool`; those tools remain available for fallback models. 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 a0a689b9bff7..206c6ca41212 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 @@ -53,6 +53,8 @@ You rarely need to hand-edit this file. Most fields are managed from the TUI's ` | `sound` | boolean | `false` | Play a notification sound on task success or failure. | | `sound_threshold` | int | `10` | Minimum duration in seconds a task must run before a success sound plays (failures always play). | | `snapshot` | boolean | `false` | Enable automatic shadow-git snapshots at turn boundaries globally. See [Snapshots](../../features/snapshots/index.md). | +| `background_compaction` | boolean | `false` | Generate automatic compaction summaries while the agent continues working. Apply completed summaries between turns, preserving messages added during generation. Unfinished work is cancelled when the stream ends. | +| `background_compaction_threshold` | integer | `70` | Context-window percentage (1–99) at which background compaction starts. Invalid values fall back to 70. Set below the agent's blocking `compaction_threshold` (90% by default) to allow time for generation. | | `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. | @@ -107,6 +109,8 @@ settings: sound_threshold: 10 snapshot: true cache_stable_prompts: true + background_compaction: true + background_compaction_threshold: 70 warn_on_cache_miss: true busy_send_mode: queue interrupt_confirmation: double-tap diff --git a/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md b/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md index 5007be77313d..cb1e2e11cf0e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/acp/index.md @@ -24,7 +24,12 @@ ACP is built on the [ACP Go SDK](https://github.com/coder/acp-go-sdk) and provid ## Usage +Without an agent argument, the server uses the `default` built-in agent (or your `default` alias, if configured). + ```bash +# Start ACP server with the default agent +$ docker agent serve acp + # Start ACP server on stdio $ docker agent serve acp ./agent.yaml @@ -106,7 +111,7 @@ Send W3C context in **request/notification `params._meta`**, not at the JSON-RPC Each implemented agent request/notification starts an `acp.` SERVER span, linked to valid incoming context and enclosing its handler. These boundary spans record only the static RPC method, not request content, paths, credential metadata, or raw errors. Invalid/non-string/oversized trace fields are ignored; each accepted field is bounded to 512 bytes and validated by the W3C propagator. A bad tracestate does not invalidate a valid traceparent. Client baggage and arbitrary `_meta` fields are not imported into tracing. -The request context flows into existing runtime/model/tool instrumentation. Outgoing ACP session updates, permission requests, filesystem operations, terminal operations (including detached cleanup), and elicitation carry only `traceparent`/`tracestate` in `params._meta`. Metadata is copied before injection; stale trace fields and baggage are removed. Response metadata is never adopted as the current trace. MCP elicitation and sampling callbacks use the sole owning tool call's trace rather than the connection's setup trace; existing ambiguous-owner restrictions remain in effect. +The request context flows into existing runtime/model/tool instrumentation. Outgoing ACP session updates, permission requests, filesystem operations, terminal operations (including detached cleanup), and elicitation carry only `traceparent`/`tracestate` in `params._meta`. Metadata is copied before injection; stale trace fields and baggage are removed. Response metadata is never adopted as the current trace. MCP elicitation callbacks use the sole owning tool call's trace rather than the connection's setup trace; existing ambiguous-owner restrictions remain in effect. Traces are not stored on sessions: concurrent and later prompts use their own incoming context. Terminal final-close retries use the cleanup caller's context, not a remembered creation trace. Detached background/drain work may outlive the handler span while retaining its trace. This adds request SERVER spans and propagation, not separate ACP CLIENT spans for every outbound call, response metadata, or automatic metadata on unsupported SDK methods. Existing runtime/provider telemetry and its content-capture settings retain their own policy; the boundary-span restriction is not a global telemetry-redaction guarantee. @@ -433,7 +438,7 @@ Captured file contents are presentation-only metadata, excluded from generic res ## CLI Flags ```bash -docker agent serve acp | [flags] +docker agent serve acp [|] [flags] ``` See the [CLI reference](../cli/index.md#docker-agent-serve-acp) for all flags, defaults, and shared runtime options. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md b/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md index 963772bc1f0f..e89a8a8a6a4a 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/api-server/index.md @@ -211,7 +211,9 @@ Event types include: - `stream_started` / `stream_stopped` — Agent execution lifecycle - `agent_choice` — Streamed text content (partial responses) - `agent_choice_reasoning` — Streamed reasoning content +- `agent_choice_reasoning_reset` — Discard all reasoning accumulated for the identified `session_id` and `message_id` (for example, after a server fallback). Keep text, other messages, and tool calls; later reasoning deltas append to the now-empty buffer. This is an ordering barrier, never coalesced with deltas - `partial_tool_call` — Streamed tool-call arguments, keyed by `tool_call.id`. The first one also carries `tool_definition` +- `tool_calls_retracted` — Tool calls announced by `partial_tool_call` that will never run, listed in `tool_call_ids`: the model refused, the response was cut off by the output-token limit (`finish_reason: length`) while a tool call was still streaming, or a server fallback handed the turn to another model - `tool_call` — Agent requesting tool execution - `tool_call_output` — Streamed output of a running tool, keyed by `tool_call_id` - `tool_call_confirmation` — Tool call waiting for user approval @@ -219,6 +221,8 @@ Event types include: - `plan_changed` — A shared plan was created, updated, or deleted through the plan toolset. The payload carries the plan's `scope`, `name`, `action`, and `version` — never its content. Shared plans are deliberately process-global: every active stream served by the same process subscribes to the same shared plan notifier and receives the event regardless of which session performed the mutation, and the payload does not identify the mutating session (read the plan's `author` metadata for collaborative attribution). - `error` — Error during execution +Append-only outputs such as CLI `--exec` and ACP thought chunks cannot retract bytes already delivered; their consumers may still show declined reasoning. The mutable TUI, lean TUI, WASM demo and persisted transcript apply the reset. + ## Typical Workflow 1. **List agents** — `GET /api/agents` to discover available agents @@ -338,6 +342,11 @@ $ docker agent run agent.yaml --listen 127.0.0.1:8080 $ docker agent run agent.yaml --listen unix:///tmp/my-run.sock ``` +`fd://N` adopts an inherited listening socket (a Winsock socket handle on +Windows). It closes the supplied descriptor after duplicating it; callers must +not close that descriptor again. The inherited listener retains its bound +address and the same authentication requirements as a directly bound listener. + The run keeps its interactive TUI; the control plane runs alongside it. A follow-up delivered over HTTP is processed exactly as if it had been typed into the TUI: it starts a turn even when the agent is idle, generates the diff --git a/_vendor/github.com/docker/docker-agent/docs/features/board/index.md b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md index 176966a7e59c..cdb2a9dee86e 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/board/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/board/index.md @@ -76,7 +76,7 @@ board: projects: - name: my-app path: /Users/me/src/my-app - agent: coder # any agent ref; defaults to the built-in agent + agent: default # any agent ref; defaults to the built-in agent columns: - id: dev name: Dev 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 5b885cac9902..1e3961bb29a8 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 @@ -13,7 +13,7 @@ _Complete reference for all Docker Agent command-line commands and flags._ > [!TIP] > **No config needed** > -> Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses a built-in default agent that is perfect for quick experimentation. +> Running `docker agent run` without a config argument uses `docker-agent.yaml`, `docker-agent.yml`, or `docker-agent.hcl` from the current directory when present. Otherwise, it uses the built-in `default` coding agent. Use `docker agent run minimal` for a small general-purpose configuration. ## Commands @@ -51,13 +51,14 @@ $ docker agent run [config] [message...] [flags] | `--last` | Print only the final agent answer after all turns finish (requires `--exec`); omit thinking, tool calls/results, and intermediate responses | | `--hide-tool-calls` | Hide tool calls in the output | | `--hide-tool-results` | Hide tool call results in the output | -| `--sandbox` | Run the agent in sandbox mode using `sbx` (see [Sandbox](../../configuration/sandbox/index.md)) | +| `--sandbox` | Run the agent in sandbox mode using standalone `sbx` or the `docker sandbox` plugin (see [Sandbox](../../configuration/sandbox/index.md)) | +| `--sbx` | Prefer standalone `sbx` when available (default: `true`); set `--sbx=false` to force the `docker sandbox` plugin. | | `--cloud` | Run in a fresh cloud sandbox without uploading host files/config/credentials; implies `--sandbox`. See [cloud sandbox mode](../../configuration/sandbox/index.md#cloud-sandboxes). | | `--sandbox-kit`, `--kit`, `--kit-arg` | Select an sbx workload and mixins, and pass kit arguments. Supports kits v3 through sbx. | | `--sandbox-ttl` | Cloud sandbox lifetime, default `1h`; stopped on expiry and when the agent exits. | | `--template ` | Template image for the sandbox (default: `docker/docker-agent-sbx-templates:latest`) | | `--no-kit` | Disable the [auto-kit](../../configuration/sandbox/index.md#auto-kit): do not stage skills or prompt files into the sandbox | -| `--agent-picker [refs]` | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to the built-in `default` and `coder` agents plus any agent configs found in `~/.agents`). Arrow keys navigate; `?` toggles the YAML preview panel; `l` (or mouse-click) toggles the **Lean Mode** checkbox to launch in the lean TUI; `b` (or clicking **[ Open Board ]**) opens the Kanban board (`docker agent board`) instead of running an agent; Enter confirms. Not available in `--exec` or non-TTY modes. | +| `--agent-picker [refs]` | Show a full-screen interactive picker before launching, letting you browse and select an agent. Accepts an optional comma-separated list of agent references to show (defaults to the built-in `default` and `minimal` agents plus any agent configs found in `~/.agents`). Arrow keys navigate; `?` toggles the YAML preview panel; `l` (or mouse-click) toggles the **Lean Mode** checkbox to launch in the lean TUI; `b` (or clicking **[ Open Board ]**) opens the Kanban board (`docker agent board`) instead of running an agent; Enter confirms. Not available in `--exec` or non-TTY modes. | | `-w, --worktree [name]` | Run the agent in a fresh git worktree of the working directory, isolating its changes from your checkout. Optionally name it (`--worktree=my-feature`); otherwise a name is generated. Requires the working directory to be inside a git repository. Every tool (the shell included) runs inside the worktree. Combine with `--working-dir` to branch from another repository, and with `--session` to resume into the same worktree later. Cannot be combined with `--remote` or `--sandbox`. When the session ends, a clean worktree is removed automatically; one with work prompts to keep or remove (never in `--exec`). | | `--worktree-base ` | Branch the `--worktree` from `` (a branch, tag, commit, or remote-tracking ref like `origin/main`) instead of the current `HEAD`. A remote-tracking ref is fetched first so the worktree starts from the latest remote state. Requires `--worktree`; cannot be combined with `--worktree-pr`, `--remote`, or `--sandbox`. | | `--worktree-pr ` | Run the agent in a git worktree checked out on an existing GitHub pull request (PR number, `#123`, or PR URL). Continues the PR's branch so commits push back to it. Requires the [GitHub CLI](https://cli.github.com/) (`gh`). Cannot be combined with `--worktree`, `--remote`, or `--sandbox`. | @@ -147,6 +148,22 @@ $ docker agent run agent.yaml --worktree-pr https://github.com/owner/repo/pull/1 With `--worktree-pr`, the PR's head branch is checked out tracking its remote (via the [GitHub CLI](https://cli.github.com/)), so commits made during the run push straight back to the pull request. The worktree is stored under `/worktrees/pr-`. +#### Copy ignored files into worktrees + +Add a `.worktreeinclude` at the source repository root to copy selected **gitignored** files into new `--worktree`, `--worktree-pr`, and [background agent](../../tools/background-agents/index.md) worktrees before setup hooks run: + +```gitignore +.env.local +config/*.local.yaml +!config/private.local.yaml +``` + +Patterns use Git's `.gitignore` syntax, including comments, negations and directory patterns. Git's normal rules for ignored parent directories apply: to exclude a child, include the parent with a pattern such as `cache/*` rather than `cache/`. Only files ignored by Git in both the source and destination checkouts are copied. A file not ignored in the destination is skipped with a warning; add appropriate ignore rules to the destination base or PR if it is needed there. Destination checks retry failed batches up to a fixed limit; if the limit is reached, unverified files are skipped with a warning, even if some would otherwise be eligible. This differs from tools that treat `.worktreeinclude` as a list of paths or also copy non-ignored files. Tracked changes and other untracked files are not copied. Missing `.worktreeinclude` leaves worktree creation unchanged. + +File permissions are preserved except that group or other permissions are removed when source ancestor directories prevent traversal for that class. New parent directories are private (`0700`). Existing destination files are never overwritten; symlinks, special files, `.gitignore`, and `.gitattributes` files are skipped. This prevents copies from changing the destination's ignore rules or staging attributes. Failures and skipped protected files produce bounded warnings without undoing the worktree; repeated protected-file skips are aggregated, and omitted warnings are counted. Cancellation stops copying and removes an incomplete file, leaving the worktree in place. Background-task warnings appear in the task metadata and logs. Files blocked by the source checkout's nearest [`.agentsignore`](../../configuration/agentsignore/index.md) are not copied, even if included here. `.agentsignore` itself is not copied by this mechanism. As always, `.agentsignore` only governs the filesystem toolset, not shell or other independent tools. + +Copied files are independent copies. **Ignored files do not make a worktree dirty**, so an interactive run can remove a clean worktree and its copied files automatically. Changing the destination's ignore rules later can make copied files visible to ordinary `git add`; `git add -f` can stage ignored files even without such a change. Changes to those copies do not propagate back to the source checkout; save anything needed before cleanup. + When the interactive session ends, the worktree is cleaned up based on its state: - **Clean** (no uncommitted changes, untracked files, or new commits): the worktree and its branch are removed automatically. @@ -389,10 +406,10 @@ $ docker agent serve a2a myorg/agent:tag ### `docker agent serve acp` -Start an ACP (Agent Client Protocol) server over stdio. This allows external clients to interact with your agents using the ACP protocol. +Start an ACP (Agent Client Protocol) server over stdio. This allows external clients to interact with your agents using the ACP protocol. If no config is specified, uses the `default` built-in agent (or your `default` alias, if configured). ```bash -$ docker agent serve acp [flags] +$ docker agent serve acp [config] [flags] ``` | Flag | Default | Description | @@ -403,6 +420,7 @@ All [runtime configuration flags](#runtime-configuration-flags) are also accepte ```bash # Examples +$ docker agent serve acp $ docker agent serve acp agent.yaml $ docker agent serve acp ./team.yaml $ docker agent serve acp myorg/agent:tag @@ -801,7 +819,11 @@ $ docker agent debug oauth login agent.yaml github > > The text output of `debug auth` truncates the token to a short preview, but `--json` includes the complete, unredacted JWT in its `token` field. Never paste `debug auth --json` output into logs, issue trackers, or bug reports — anyone with that token can act as you against Docker. Use the plain-text output (or redact the `token` field yourself) when sharing diagnostic output. -The `Source` field says where the token came from: `docker desktop`, or `minted from the stored access token` when it was obtained by exchanging the access token `docker login` stored. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). +The `Source` field says where the token came from: `docker desktop secrets engine` when it was read from the secrets engine Docker Desktop serves, `docker desktop` when Docker Desktop's backend served it, or `minted from the stored access token` when it was obtained by exchanging the access token `docker login` stored. See [Docker authentication](../../guides/secrets/index.md#docker-authentication). + +`Username` and `Email` come from the secrets engine's session when the engine supplied the token, otherwise from Docker Desktop, and otherwise from the token itself. + +When the secrets engine couldn't be read, `Secrets engine` says why, `Socket` which socket was tried, and `Hint` how to fix it. The JSON output has them under `secrets_engine` as `reason`, `socket` and `hint`, along with the full `error`. A secrets engine that isn't running is only reported when no token was found, since machines without Docker Desktop don't have one. The `config`, `toolsets`, `tool`, `skills`, and `title` subcommands also accept [runtime configuration flags](#runtime-configuration-flags) (`--working-dir`, `--models-gateway`, …); `title` additionally accepts `--model` to override the model used to resolve the config before generating the title. diff --git a/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md b/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md index 218e242d9130..e7c647c8dd19 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/code-mode/index.md @@ -73,7 +73,7 @@ It is not a general-purpose replacement for direct tool calls: for an agent that - **One string result.** The script must return a string; use `console.*` inside the script to print debug information if something doesn't behave as expected — it comes back to the model as `stdout`/`stderr` alongside the result, but is not displayed by the terminal UIs. - **Failures are diagnosable.** If the script throws or returns unexpectedly, the response includes the tool calls it made before failing (name, arguments, and result or error), so the model can see what happened and adjust the script on the next attempt. -- **Not every tool is wrapped.** Tools in the `todo` category and repeatable tools such as `random_int` and `get_datetime` stay directly callable as ordinary tools. Repeatable tools are unavailable inside scripts so successful calls retain their duplicate-loop exemption without exempting failed or unrelated scripts. +- **Not every tool is wrapped.** Tools executed by the runtime itself, such as `transfer_task`, `handoff`, `run_skill`, and the background-agent tools, stay directly callable as ordinary tools because scripts can't invoke them. Tools in the `todo` category and repeatable tools such as `random_int` and `get_datetime` stay directly callable as ordinary tools. Repeatable tools are unavailable inside scripts so successful calls retain their duplicate-loop exemption without exempting failed or unrelated scripts. - **The script runs in an embedded, sandboxed JS engine** ([goja](https://github.com/dop251/goja)), not Node.js or a browser: there is no filesystem, network, or process access beyond the tool functions injected into it. - **Partial startup is supported.** If one toolset fails to initialize (for example, an MCP server that won't connect), Code Mode remains available with the successfully loaded toolsets. The failed toolset is omitted from the JavaScript environment and retried on subsequent turns. A warning is emitted once when the failure first occurs, but not on subsequent turns while the failure persists. When the toolset recovers, its tools silently reappear in the environment. When the failed toolset's cause is retryable (e.g. an MCP server or RAG knowledge base hitting rate limits), its retries are paced by the same [backoff gate](../../tools/mcp/index.md#lifecycle-auto-restart-profiles) used outside code mode, instead of retrying on every turn. @@ -86,4 +86,4 @@ In practice this means enabling `code_mode_tools` collapses the approval granula > [!WARNING] > **Coarser approval granularity** > -> Approving a `run_tools_with_javascript` call approves every tool it might invoke internally, including ones that would otherwise need a separate `ask` or be blocked by a `deny` pattern under [Permissions](../../configuration/permissions/index.md). If an agent's toolset includes anything destructive, consider whether Code Mode's coarser granularity is acceptable for that agent before enabling it. Delegating to a separate, non-Code-Mode agent isn't a way out either: [handoff](../../tools/handoff/index.md) and [transfer_task](../../tools/transfer-task/index.md) are themselves wrapped like any other tool once `code_mode_tools` is on, but they have no code-mode-compatible handler — the model's script gets `tool "handoff" is not available in code mode` if it tries to call them. This only rules out the model *choosing* to delegate from inside the script: a configured `force_handoff` target on the agent still runs deterministically after the agent's turn naturally stops, regardless of Code Mode, since it's applied by the runtime outside the tool-call dispatch path Code Mode replaces. Keep `code_mode_tools` off any agent whose model needs to hand off or transfer to one that holds a destructive toolset. +> Approving a `run_tools_with_javascript` call approves every tool it might invoke internally, including ones that would otherwise need a separate `ask` or be blocked by a `deny` pattern under [Permissions](../../configuration/permissions/index.md). If an agent's toolset includes anything destructive, consider whether Code Mode's coarser granularity is acceptable for that agent before enabling it. [handoff](../../tools/handoff/index.md) and [transfer_task](../../tools/transfer-task/index.md) are not affected: they are executed by the runtime itself and stay directly callable as ordinary tools, so the model can still delegate normally. They just can't be called from inside a script — a script that tries gets `tool "handoff" is not available in code mode`. A configured `force_handoff` target also still runs after the agent's turn naturally stops, regardless of Code Mode. 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 e664b7ad7982..35bb22efabc2 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 @@ -388,31 +388,26 @@ passing: a gate that cannot fail is worse than no gate. ### Provider Credentials -Eval containers are isolated from your host environment. Dedicated model -provider API keys (for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) are -forwarded into eval containers automatically, so most provider setups work -without extra flags. +Eval containers do not automatically receive host environment variables, including +provider API keys, gateway settings, Docker tokens, or credentials referenced by +evaluators and hooks. Pass each required variable explicitly with `-e`: -> [!WARNING] -> **`GITHUB_TOKEN` and `GH_TOKEN` are not forwarded automatically** -> -> GitHub tokens are broad credentials (git, `gh`, CI, packages), not dedicated -> model API keys, so for security reasons Docker Agent does not forward them -> into eval containers — even when they are set in your shell or in -> `~/.config/cagent/.env`. If your agent uses the `github-copilot` provider, -> pass the token explicitly by name: -> -> ```bash -> docker agent eval agent.yaml ./evals -e GITHUB_TOKEN -> ``` -> -> When using a custom env file, both flags are required: -> -> ```bash -> docker agent eval agent.yaml ./evals \ -> --env-from-file /path/to/secrets.env \ -> -e GITHUB_TOKEN -> ``` +```bash +docker agent eval agent.yaml ./evals -e OPENAI_API_KEY +``` + +`-e NAME` resolves the value from the configured environment sources; +`-e NAME=VALUE` supplies a literal value. Loading a custom env file does not +implicitly forward its contents: + +```bash +docker agent eval agent.yaml ./evals \ + --env-from-file /path/to/secrets.env \ + -e GITHUB_TOKEN +``` + +To use a models gateway inside the container, explicitly pass +`DOCKER_AGENT_MODELS_GATEWAY` and any authentication variables it requires. Note that the judge runs on the host, not inside the eval container. If the token is not forwarded, judge validation can succeed while every diff --git a/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md b/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md index 1dcb5b202e1d..b307e566b6f5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/harnesses/index.md @@ -78,7 +78,12 @@ agents: **not** a Docker Agent `provider/model` reference — the harness model never goes through Docker Agent's model providers or routing. - `effort` is forwarded as `--effort` and must be one of `low`, `medium`, - `high`, `xhigh`, or `max`. Omit it to use Claude Code's own default. + `high`, `xhigh`, or `max`. Omit it to use Claude Code's own default. In the + TUI, `/effort` and Shift+Tab change it for the + following turns of the session (`command-code` harnesses too). +- Session titles come from the CLI as well, since a harness agent has no + model: Docker Agent runs `claude --print` once on the `haiku` model, with + no tools, MCP servers or saved session, to title a new session. #### Authentication (Claude subscription, no API key) @@ -129,6 +134,29 @@ ready-to-run `claude-code-agent.yaml`. > harness unless the sandbox image is separately provisioned and > authenticated. +#### Questions and plan approval + +When you can answer, Claude Code's own questions reach you as an elicitation +form, like an MCP server's: in the TUI, through the API server's +`elicitation_request` events, or in any client that answers elicitations. + +- **`AskUserQuestion`**: one form per call, with each option's description + under it. You pick one option of a single-choice question and check any of + a multiple-choice one (Space toggles). A free answer replaces + the choices, like Claude Code's "Other". If you decline or dismiss the + form, Claude Code learns that you did not answer. +- **Plan approval** (`ExitPlanMode`): you see the plan and choose to proceed + or keep planning. Optional feedback goes back to Claude Code when you keep + planning. + +Docker Agent serves these prompts to the CLI through +`--permission-prompt-tool`, from an MCP server on loopback that lives for one +turn and requires a per-turn token. Other tools still run without asking. +Non-interactive sessions (`serve mcp`, A2A, background agents) keep the +previous behavior: Claude Code asks in plain text and ends its turn. +`docker agent run --exec` answers no forms, so it declines them and Claude +Code carries on without an answer. + ### Codex ```yaml diff --git a/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md b/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md index 3e8c5925b29e..9cd4468dacc0 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/remote-mcp/index.md @@ -62,6 +62,8 @@ For full configuration details, see the [Tool Config](../../configuration/tools/ Set `allow_private_ips: true` on a remote MCP toolset only when the MCP server or its OAuth registration/token endpoints intentionally resolve to private, loopback, or link-local addresses. The default blocks those OAuth helper requests to reduce SSRF risk. +Set `standalone_sse: true` on a `streamable` remote toolset to open the optional standalone SSE `GET` stream on the MCP endpoint. Some gateways (for example the sbx MCP gateway) send keepalive pings and `notifications/tools/list_changed` over that stream and drop sessions they cannot reach, so without it the session expires silently and the tool list goes stale. It defaults to `false` because a few servers hang when the stream is opened. It has no effect with `transport_type: "sse"`. + When Docker Desktop is running, eligible OAuth discovery, registration, token exchange, refresh, and helper requests use its PAC adapter before environment proxy settings. It does not apply to remote MCP Streamable HTTP/SSE transport. Set `DOCKER_AGENT_DISABLE_DESKTOP_PROXY=1` (or `true`, `yes`, or `on`) to restore standard `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` routing; `NO_PROXY` does not bypass Desktop PAC selection. Docker Agent does not evaluate PAC files or URLs directly—see [Docker Desktop proxy](../../tools/fetch/index.md#docker-desktop-proxy). > [!NOTE] diff --git a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md index adb982769f95..8db7bba5f38f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/features/tui/index.md @@ -93,7 +93,7 @@ Type `/` during a session to see available commands, or press Ctrl+`, or `/effort` alone to pick from the supported levels; reasoning models only). Press Tab after `/effort` and a space to complete a level the current model supports | +| `/effort` | Set the current model's reasoning-effort level (`/effort `, or `/effort` alone to pick from the supported levels; reasoning models and `claude-code` / `command-code` harnesses only). Press Tab after `/effort` and a space to complete a level the current model supports | | `/settings` | Manage appearance, behavior, and notification preferences | | `/yolo` | Toggle automatic tool call approval | | `/title` | Set or regenerate session title | @@ -202,7 +202,7 @@ The thinking state of each model is shown with a gauge + value on the card and a The **effort gauge** is a fixed-width six-cell indicator (`▰` filled, `▱` empty) so the badge column stays aligned. It maps the six selectable levels one-to-one onto filled-cell counts — `minimal` → `▰▱▱▱▱▱`, `low` → `▰▰▱▱▱▱`, `medium` → `▰▰▰▱▱▱`, `high` → `▰▰▰▰▱▱`, `xhigh` → `▰▰▰▰▰▱`, `max` → `▰▰▰▰▰▰` — so the cell count alone is lossless, with a low→high color ramp as a secondary cue. A capable-but-disabled model shows a dim empty gauge (`▱▱▱▱▱▱` `off`), adaptive budgets show `auto`, and token budgets keep `◉ `. The same gauge + value renders on the focus card, the Agent Inspector, and the row. -Harness-backed agents (e.g. `claude-code`) show the harness type as their model and no thinking gauge. Press **Shift+Tab** to cycle the current model's thinking-effort level; a `✻ Thinking: ` toast confirms the change (useful when the sidebar is hidden). +Harness-backed agents (e.g. `claude-code`) show the harness type as their model. `claude-code` and `command-code` harnesses show their `effort` on the gauge, or `auto` while the CLI picks it; other harnesses show no thinking gauge. Press **Shift+Tab** to cycle the current model's thinking-effort level; a `✻ Thinking: ` toast confirms the change (useful when the sidebar is hidden). ### Agent Delegation Feedback @@ -299,7 +299,7 @@ Unsupported or syntactically invalid LaTeX expressions fall back to displaying t The TUI fetches and renders images referenced in agent responses using the Kitty graphics protocol. When an assistant message contains a standard Markdown image reference, the TUI downloads the image in the background and displays it inline at the point of the reference. While the image is loading a placeholder is shown; once loaded, the message re-renders with the image in place. -Only `http://`, `https://`, and `data:image/…;base64,…` URIs are resolved. `file://`, `sandbox://`, and any other URI scheme are rejected as a security measure against prompt-injection attacks that could otherwise read local files. Bare relative paths (e.g. `./output.png`, used for agent-generated images) are read via the local filesystem. Images that fail to load are silently dropped — the surrounding message text is unaffected. Image rendering requires a terminal that supports the Kitty graphics protocol; it is automatically disabled when the terminal does not support it. Support is checked before the TUI starts; an unanswered probe waits up to 300 ms. You can disable rendering and skip this check via `render_images: false` in `~/.config/cagent/config.yaml` or the **Render images** toggle in `/settings`. Disabling and re-enabling images applies immediately when startup confirmed support. If the startup check was skipped, enabling images takes effect on the next launch. +Only `http://`, `https://`, and `data:image/…;base64,…` URIs are resolved. `file://`, `sandbox://`, and any other URI scheme are rejected as a security measure against prompt-injection attacks that could otherwise read local files. Bare relative paths (e.g. `./output.png`, used for agent-generated images) are read via the local filesystem. Images that fail to load are silently dropped — the surrounding message text is unaffected. Image rendering requires a terminal that supports the Kitty graphics protocol; it is automatically disabled when the terminal does not support it. Support is checked before the TUI starts. Terminals without Kitty graphics answer right away; only a terminal that answers nothing at all waits out the 300 ms timeout. You can disable rendering and skip this check via `render_images: false` in `~/.config/cagent/config.yaml` or the **Render images** toggle in `/settings`. Disabling and re-enabling images applies immediately when startup confirmed support. If the startup check was skipped, enabling images takes effect on the next launch. ### Snapshots, `/undo`, and `/snapshots` @@ -581,19 +581,6 @@ Run `/settings` to open the settings dialog. Click a category tab, or use T > > This section covers the `/settings` dialog. For the complete list of `settings:` fields (including ones with no dialog UI, like `permissions`, `hooks`, and `keybindings`) and how they interact with CLI flags and aliases, see [User Settings](../../configuration/user-settings/index.md). -The **Appearance** tab selects the theme and customizes the layout. Layout changes apply immediately to the UI behind the dialog. On wide terminals, a schematic preview appears beside the controls without reducing the space available to the settings list: - -- **Sidebar position**: `Right` (default), `Left`, `Top`, or `Bottom`. Left/right keep the full vertical sidebar next to the chat; top/bottom render it as a compact horizontal band above or below the chat (session title, working directory, token usage, plus a one-line summary of the current agent and its model; in multi-agent configurations all team agents are listed by name after the current agent). -- **Sidebar info mode**: `Compact` (default) or `Detailed`. Controls how the Agents panel renders agent rows — see [Agents Panel](#agents-panel) for details. Persisted as `settings.layout.sidebar_info_mode: detailed`; compact is the default and omitted from the config. -- **Section spacing**: `Compact`, `Normal` (default), or `Relaxed`, the number of blank lines between the sidebar sections (1, 2, or 3). -- **Sidebar sections**: toggle the visibility of the **Session path** (the working directory line, including its git branch) and the **Token usage**, **Agents**, **Tools**, **Plans**, and **Todos** sections. All are visible by default except [Plans](#plans-sidebar), which is opt-in. The session title is always shown. - -Appearance also controls split-diff rendering, expanded thinking, whether tool results are hidden by default, and **Show startup banner** — the ASCII-art banner drawn on an empty conversation (persisted as `settings.show_banner: false` when turned off, and honored by the lean TUI too). Select **Theme** to open the theme picker. - -The **Behavior** tab controls busy-message handling, the auto-approve default, tab restoration, automatic snapshots, lean UI, and the maximum tab-title length. Restore-tabs and lean-UI changes take effect on the next launch. Enabling auto-approve requires confirmation. - -The **Notifications** tab enables completion sounds and sets the minimum task duration before a sound plays. - Press Enter to apply and persist, or Escape to cancel and restore the previous layout. The settings are saved globally in `~/.config/cagent/config.yaml`: ```yaml diff --git a/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md b/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md index ba2e9cc90338..bdcdafa4b1dd 100644 --- a/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/getting-started/quickstart/index.md @@ -120,7 +120,7 @@ Use `docker agent run --exec` for one-shot tasks: $ docker agent run --exec agent.yaml "Create a Dockerfile for a Node.js app" # Pipe input -$ cat error.log | docker agent run --exec agent.yaml "What's wrong in this log?" +$ { printf "What's wrong in this log?\n\n"; cat error.log; } | docker agent run --exec agent.yaml - ``` ## Add More Power diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md index 67027ff65c03..b5a8c0156b5b 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/compaction/index.md @@ -146,4 +146,4 @@ Compaction summarizes history, but it never resets what a session has actually c ## Related: deferred tool loading -Compaction and result trimming manage context that's already in the session. If large toolsets are inflating your **starting** context instead — many MCP servers, hundreds of tools — look at [deferred tool loading](../../configuration/tools/index.md#deferred-tool-loading), which registers a toolset's tools lazily instead of eagerly at startup. +Compaction and result trimming manage context that's already in the session. If large toolsets are inflating your **starting** context instead — many MCP servers, hundreds of tools — look at [deferred tool loading](../../configuration/tools/index.md#deferred-tool-loading), which exposes tool definitions to the model only when needed. The underlying toolsets still start normally. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md index 2c6a68719976..88dad286797a 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/go-sdk/index.md @@ -135,12 +135,30 @@ The CLI uses this helper for both its initial runtime and TUI-spawned runtimes. The HTTP API wires the same manifest budgets into its native runtimes; other serving adapters retain their existing wiring and budget behavior. +## Remote execution + +Remote HTTP/SSE execution lives in `pkg/runtime/remote`: + +```go +client, err := remote.NewClient(serverURL) +if err != nil { + return err +} +rt, err := remote.NewRuntime(client) +``` + +Import `github.com/docker/docker-agent/pkg/runtime/remote` for these constructors. +Shared interfaces and events remain in `pkg/runtime` (`runtime.Runtime`, +`runtime.Event`, and the concrete event types). The remote implementation imports +those types; local execution does not import remote transport. There are no +compatibility re-exports of remote clients or constructors in `pkg/runtime`. + ## Execution Capability Inspection `(*runtime.LocalRuntime).AgentExecutionCapabilities(name)` returns a static native/harness profile without starting tools, constructing drivers or initializing budget counters. Unknown agents return nil. The same optional -profile is available on `runtime.AgentConfigInfo`, `runtime.AgentDetails` in +profile is available on `inspection.AgentConfigInfo`, `runtime.AgentDetails` in `team_info`, and local startup/refresh `runtime.AgentInfoEvent` values. See [Execution capabilities](../../features/api-server/index.md#execution-capabilities) for field meanings and unknown/remote behavior. @@ -275,7 +293,7 @@ For anything beyond that, call `chat.Runtime()` to access the underlying `runtim > still works and falls back to resolving the sole pending request. > > If you implement your own `runtime.Runtime` (rather than embedding -> `runtime.LocalRuntime`/`runtime.RemoteRuntime`), you do need to update your +> `runtime.LocalRuntime`/`remote.Runtime`), you do need to update your > method's signature to match, and also add an `OnElicitationRequest(handler > func(runtime.Event))` method (a no-op is fine if your runtime never raises > elicitations) — both are required interface methods, matching the existing @@ -325,7 +343,7 @@ if err != nil { ts := ragtool.New(mgr, mgr.ToolName(), ragtool.WithIndexingTimeout(ragCfg.GetIndexingTimeout())) ``` -`cmd/wasm/toolsets.go` registers exactly this as the browser's `type: rag` creator, fed by `createSession`'s `documents` option. +With `-tags docker_agent_wasm_rag`, `cmd/wasm/rag.go` registers this as the browser's `type: rag` creator, fed by `createSession`'s `documents` option. RAG is excluded from the default WASM build. ## Loading YAML with Hand-Picked Registries (lean embedding) @@ -360,6 +378,7 @@ team, err := teamloader.Load(ctx, ocisource.New("myorg/agent:v1"), runConfig, - **Agent sources**: `config.NewFileSource` / `config.NewBytesSource` / `config.NewURLSource` live in `pkg/config`; the OCI source lives in `pkg/config/ocisource`; HCL support is a source decorator, `hcl.NewSource(inner)`, in `pkg/config/hcl`. `pkg/config/sources` resolves any reference (files, directories, URLs, OCI, user aliases, built-in agents) at the cost of linking all of them. Sub-agents referencing external agents (`sub_agents: [myorg/reviewer]`) need a `teamloader.WithSourceResolver` that wraps `sources.Resolve` (as `loaderdefaults.Opts()` does) — or your own resolver. - **Optional loader features**: everything the loader used to link unconditionally is now an option, so `pkg/teamloader` adds no module over `pkg/runtime`. Enable what your configs use: `teamloader.WithExpander(js.NewJsExpander)` for `${...}` JavaScript in instructions/commands (the default only resolves `${env.NAME}`; also call `jscommands.Register()` for slash commands), `teamloader.WithCodeMode(codemode.Wrap)` for `code_mode_tools`, `teamloader.WithToon(toon.Wrap)` for the `toon` field, `teamloader.WithDeferredTools(deferred.New)` for `defer`, and `runtime.RegisterHarness(codingharness.Factory)` for `harness:` agents. A config that uses a feature you did not enable fails to load with an error naming the option. - **Strict mode**: `teamloader.WithStrict(features...)` fails the load with a `*config.UnsupportedError` listing **every** provider type, toolset type and optional feature the config relies on that you did not enable, with the config locations that need them. Optional features are `config.FeatureHooks`, `config.FeatureHarness`, `config.FeatureAgentRouting`, `config.FeatureSkills`, `config.FeatureExternalAgents`, `config.FeatureCodeMode`, `config.FeatureToon` and `config.FeatureDeferredTools`; none is enabled unless listed. Agents on the `auto` model are resolved eagerly so the provider they land on is checked too. Without `WithStrict`, unknown toolset types stay load-time warnings and unknown providers fail when their model is built. +- **Template-based hooks**: the `add_context` builtin and `type: model` hooks render Go templates. `text/template` looks methods up by name at run time, so linking it makes the Go linker keep every exported method of every reachable type, which roughly doubles a WASM binary. Build with `-tags docker_agent_no_hook_templates` to drop it; those two hooks then fail with `hooks.ErrHookTemplatesDisabled`. Hosts that load with `WithStrict()` and don't enable `config.FeatureHooks` lose nothing. `config.Requires(cfg)` exposes the same audit for your own checks. `pkg/embeddedchat` accepts all of this through `Config.LoadOpts`. A complete example lives in [examples/golibrary/yamlstrict](https://github.com/docker/docker-agent/tree/main/examples/golibrary/yamlstrict). @@ -370,6 +389,63 @@ team, err := teamloader.Load(ctx, ocisource.New("myorg/agent:v1"), runConfig, > > If you call `teamloader.Load` without `loaderdefaults.Opts()`, JavaScript expansion, code mode, TOON, deferred tools and harness agents are now off until you enable them (see *Optional loader features* above). Code-built teams that use `harness:` agents must call `runtime.RegisterHarness(codingharness.Factory)`; `codingharness.Label` moved into the runtime. +### Optional YAML history and embedded model catalog + +The core packages do not link historical YAML schemas or a model catalog snapshot. +Both capabilities are independent opt-ins; the CLI and the shipped WASM demo enable +both to preserve their existing behavior. + +`config.Load` and `teamloader.Load` accept only the current schema by default +(version omitted or `latest.Version`). To accept historical YAML, import +`pkg/config/legacy` and pass its registrar: + +```go +cfg, err := config.Load(ctx, source, config.WithVersions(legacy.Register)) + +team, err := teamloader.Load(ctx, source, runConfig, + teamloader.WithConfigVersions(legacy.Register), + // ...provider and toolset registries... +) +``` + +This retains the usual strict parsing, validation, flavor patches and migrations. +The selection is per load and inherited by external sub-agents. `loaderdefaults` +already includes it. Without it, old versions fail with an unsupported-version +error; historical syntax hints are only available when history is selected. + +`modelsdev.NewStore` still uses its disk cache and the live models.dev API, but a +cache/network miss returns an empty catalog unless a fallback is supplied. To +include the optional embedded data, import `pkg/modelsdev/embedded`: + +```go +store, err := modelsdev.NewStore(modelsdev.WithFallback(embedded.Snapshot)) + +// Or configure the shared store used by a team and its runtime: +runConfig := &config.RuntimeConfig{ + ModelsDevFallback: embedded.Snapshot, +} + +// Entirely in-memory; no cache or network discovery: +store = modelsdev.NewDatabaseStore(embedded.Snapshot()) +``` + +`runtime.WithModelsDevFallback(embedded.Snapshot)` configures a standalone +runtime's lazy default store. An explicit `runtime.WithModelStore` or the store +carried by its model-switcher configuration takes precedence. A fallback callback +runs only when needed and is not cached as authoritative, so live discovery can +recover after a failed request. Callback results are shared; treat them as read-only +and make callbacks safe for concurrent use across stores. + +For a small offline host, use an empty in-memory store instead and omit the +`embedded` import. No metadata means no reliable catalog pricing or capability +inference; specify model limits and capabilities when required. Removing the +snapshot alone does not disable network discovery in a normal `NewStore`. + +**Go API migration:** `modelsdev.EmbeddedSnapshot()` is now `embedded.Snapshot()`; +`modelsdev.SnapshotDate()` is now `embedded.SnapshotDate()`. Existing applications +loading old YAML must opt in with `legacy.Register`. No build tags or process-wide +registration are needed for either capability. + ### Per-runtime feature configuration Prefer instance options over `runtime.RegisterHarness` and @@ -904,7 +980,6 @@ embedding, context-discovery or compaction capabilities. | Caller | Clone failure behavior | | --- | --- | | Session title | Tries the next configured candidate; exhaustion does not interrupt chat. | -| MCP sampling, with or without tools | Returns the actionable clone error before inference. | | LLM compaction | Reports failure and leaves the session history intact. | | Compaction window resolution | The checked resolver returns zero plus the error; the LLM compaction path reports it. UI gauges remain best-effort. | diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md index 1a80c3100e47..be4334541a3c 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/headless/index.md @@ -97,7 +97,7 @@ Hooks run asynchronously and are never waited on: each is spawned detached from ## Running Unattended in CI -Interactively, the TUI prompts for confirmation before a tool call runs unless it's covered by an `allow` permission pattern. There's no one to answer that prompt in CI, so an unattended `--exec` run needs an explicit policy for what may run without asking — otherwise every tool call the model attempts is rejected outright (there's no stdin to prompt, so `--exec` without one just answers "no" on your behalf; see [`--json`'s auto-reject behavior](#structured-output-for-machines) above). +Under the default policy, read-only tools run without confirmation and other calls prompt for approval unless a permission rule overrides that decision. An interactive `--exec` run can still prompt for tool approval; it does not inherently mean unattended execution. In CI, configure an explicit safety mode and permission rules for the calls that must run without asking. With `--json` or `--last`, pending confirmations are always declined; plain-text exec output redirected to a pipe or file also declines them. See [structured output behavior](#structured-output-for-machines) above. Two different questions come up here, and it's worth keeping them separate: @@ -106,7 +106,7 @@ Two different questions come up here, and it's worth keeping them separate: ### `--sandbox`: the isolation boundary -For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a VM managed by [`sbx`](https://docs.docker.com/ai/sandboxes/): a misbehaving or successfully-prompt-injected agent can't touch anything outside the mounted working directory or reach other host/CI state, regardless of which command it runs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How It Works](../../configuration/sandbox/index.md#how-it-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, `sbx` requirement, network allowlist, and kit staging behavior. +For an untrusted or autonomous agent — anything acting without a human watching approvals — **`--sandbox` is the isolation boundary to reach for**, not a cleverer allow-list. It runs the entire agent, shell calls included, inside a VM managed by [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/), using standalone `sbx` or the `docker sandbox` plugin. The working directory is mounted read-write; configuration directories and staged kits may also be exposed read-only. Treat every mounted file and configured network destination as accessible to the agent, and mount only what the task needs. That VM isn't disposable or ephemeral — a sandbox matching the current workspace and mount set is retained and reused across subsequent runs rather than torn down when the session ends (see [How local sandbox mode works](../../configuration/sandbox/index.md#how-local-sandbox-mode-works)). See [Sandbox Mode](../../configuration/sandbox/index.md) for the full flag reference, `sbx` requirement, network allowlist, and kit staging behavior. ```bash $ docker agent run --sandbox --exec agent.yaml --json "Fix the failing test" diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md index 7accef7fce3d..b2345b9064bc 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/secrets/index.md @@ -18,7 +18,7 @@ Docker Agent needs API keys to talk to model providers (OpenAI, Anthropic, etc.) | 2 | [Docker Compose secrets](#docker-compose-secrets) | Files in `/run/secrets/` | | 3 | [Docker Agent env file](#docker-agent-env-file) | `~/.config/cagent/.env`, written by `docker agent setup` | | 4 | [ChatGPT login](../../providers/chatgpt/index.md) | `CHATGPT_OAUTH_TOKEN` from the account login created by `docker agent setup` | -| 5 | [Credential helper](#credential-helper) | Custom command declared in `~/.config/cagent/config.yaml` under `credential_helper:` | +| 5 | [Credential helper](#credential-helper) | Custom command declared in `~/.config/cagent/config.yaml` under `credential_helper:`; supplies `DOCKER_TOKEN` only | | 6 | [Docker Desktop](#docker-desktop) | Secrets stored by the Docker Desktop backend (no setup on a Desktop install) | The first provider that has a value wins. You can mix and match — for example, use environment variables for one key and the Docker Agent env file for another. @@ -26,7 +26,7 @@ The first provider that has a value wins. You can mix and match — for example, > [!NOTE] > Older Docker Agent versions could also read secrets from the macOS Keychain and the `pass` password manager. These sources are no longer consulted: migrate any keys stored there to one of the sources above, e.g. by re-running `docker agent setup`. -Whatever provider returns the value, if that value looks like a [1Password secret reference](#1password-references) (it starts with `op://`), Docker Agent resolves it through the `op` CLI before handing it to a model provider or tool. +Whatever provider returns the value, if that value looks like a [1Password secret reference](#1password-references) (it starts with `op://`), Docker Agent resolves it through the `op` CLI before handing it to a model provider or tool. This applies to every variable, API keys included, and needs no credential helper: `ANTHROPIC_API_KEY=op://Personal/Anthropic/api-key` in any source above is enough. When Docker Agent runs an agent with `--sandbox` and a Docker AI gateway is configured, the sandbox proxy authenticates gateway requests itself: it injects your Docker login token into HTTPS requests to the gateway host (docker.com domains only). The token never enters the sandbox — inside it, `DOCKER_TOKEN` is a proxy-managed placeholder. @@ -52,6 +52,26 @@ toolsets: GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_PERSONAL_ACCESS_TOKEN ``` +### Docker Agent-only variables + +Other tools read the same variables: Claude Code reads `ANTHROPIC_API_KEY`, Codex reads `OPENAI_API_KEY`. To give Docker Agent its own value, prefix the name with `DOCKER_AGENT_ENV_`. Docker Agent looks up `DOCKER_AGENT_ENV_` before ``, and other tools ignore it: + +```bash +export ANTHROPIC_API_KEY=sk-ant-... # used by other tools +export DOCKER_AGENT_ENV_ANTHROPIC_API_KEY="op://Personal/Anthropic/api-key" # used by Docker Agent +docker agent run agent.yaml +``` + +- The prefix works for every variable Docker Agent resolves through its secret chain: provider API keys, `${VAR}` references in MCP `env`, `DOCKER_TOKEN`, and the OpenAI key used by `/speak`. +- `DOCKER_AGENT_ENV_` wins over `` across all [sources](#overview) and `--env-from-file`: an override in the Docker Agent env file beats a plain shell export. +- An empty override is ignored: `export DOCKER_AGENT_ENV_ANTHROPIC_API_KEY=` falls back to an override in a later source, then to `ANTHROPIC_API_KEY`. +- Docker Agent's own settings (`DOCKER_AGENT_*`) are never overridden this way. +- The value can be a [1Password reference](#1password-references). +- `docker agent doctor` shows which name supplied each credential. + +> [!NOTE] +> With `--sandbox`, the provider API keys that the sandbox proxy injects itself (such as `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`) are not read through Docker Agent, so neither the prefix nor `op://` references apply to them. Other variables are resolved on the host, prefix included, and forwarded under their plain name. + ## Env Files For convenience, you can store secrets in a `.env` file and pass it to Docker Agent with `--env-from-file`: @@ -158,7 +178,17 @@ secrets: ## Credential Helper -Docker Agent can shell out to an external credential helper you define in your user config. This is useful when your organisation already has a secrets daemon you want to reuse (HashiCorp Vault, 1Password CLI, `bitwarden-cli`, etc.). +Docker Agent can shell out to an external credential helper you define in your user config to obtain the **Docker token** (`DOCKER_TOKEN`) used by the [Docker models gateway](../../configuration/models/index.md). This is useful when your organisation already keeps that token in a secrets daemon (HashiCorp Vault, 1Password CLI, `bitwarden-cli`, etc.). + +> [!IMPORTANT] +> **The credential helper does not serve API keys.** It is consulted for `DOCKER_TOKEN` only. To load provider API keys or MCP tokens from 1Password, store an `op://` reference in any other source instead, for example in the [Docker Agent env file](#docker-agent-env-file): +> +> ```bash +> # ~/.config/cagent/.env +> ANTHROPIC_API_KEY=op://Personal/Anthropic/api-key +> ``` +> +> See [1Password References](#1password-references). Declare the helper in `~/.config/cagent/config.yaml`: @@ -166,10 +196,10 @@ Declare the helper in `~/.config/cagent/config.yaml`: # ~/.config/cagent/config.yaml credential_helper: command: op - args: ["read", "op://Personal/docker-agent"] + args: ["read", "op://Personal/Docker/token"] ``` -The command is invoked with the variable name appended as the final argument, and must print the secret value to stdout. +The command is run exactly as configured, with no extra arguments, and must print the token to stdout. ## Docker Desktop @@ -177,7 +207,16 @@ On machines where Docker Desktop is installed, Docker Agent queries Docker Deskt ## Docker Authentication -Routing model traffic through the [Docker models gateway](../../configuration/models/index.md) needs a Docker token. Docker Desktop hands out one that is valid for 15 minutes and cannot be renewed by Docker Agent, so when Desktop has nothing usable to offer — it is signed out, not running, or its own refresh is stuck — Docker Agent exchanges the long-lived access token that `docker login` left in your credential store for a fresh Docker token, the same exchange `docker login` itself performs. Signing in with `docker login` is therefore enough; Docker Desktop is not required. +Routing model traffic through the [Docker models gateway](../../configuration/models/index.md) needs a Docker token. A `DOCKER_TOKEN` you provide yourself — an environment variable, a Compose secret, an env file or a credential helper, as is common in CI — always takes precedence, and none of the sources below are consulted. + +Otherwise, Docker Agent tries these sources in order and uses the first token that is not expired or about to expire: + +1. **The Docker secrets engine**, which Docker Desktop serves on a local socket and which holds the session of the account signed in to Desktop. It is skipped when it is unavailable (Docker Desktop is not installed or not running, or predates the engine), holds no session, or holds a session that is incomplete: an access token that is missing or not a JWT, or no account or expiry. A request waits for the engine for at most five seconds, and never more than half of its own time limit, so the other sources still get a turn. An engine that fails or does not answer is skipped for the next 30 seconds. Production sessions are read unless `DOCKER_AGENT_HUB_LOGIN_URL` points at a Docker Hub staging host, such as `hub-stage.docker.com`; staging sessions are read instead. Docker Agent cannot tell which environment Docker Desktop is signed in to, so set that variable when Desktop is signed in to staging. +2. **Docker Desktop's backend.** +3. **The access token `docker login` stored.** Docker Agent exchanges the long-lived access token in your credential store for a fresh Docker token, the same exchange `docker login` itself performs. Signing in with `docker login` is therefore enough; Docker Desktop is not required. +4. **A refresh of Docker Desktop's session**, as a last resort. + +The tokens Docker Desktop hands out are valid for 15 minutes, and only Desktop can renew them. That is why the exchange exists: it keeps Docker Agent working when Desktop has nothing usable to offer because it is signed out, not running, or its own refresh is stuck. Tokens are looked up again as they near expiry, so a long-running session keeps working. Only Docker access tokens are exchanged — the `dckr_…` secrets `docker login` stores — never an account password, and the exchange goes to Docker Hub over HTTPS. The resulting bearer token is cached in a private file under Docker Agent's cache directory so sibling processes reuse it instead of minting their own, and it stops being used within seconds of a `docker logout` or an account switch. Run `docker agent debug auth` to see which token is in use and where it came from. @@ -201,6 +240,9 @@ References follow the `op:////` format. Make sure the `op` C > > If the value starts with `op://` but the `op` CLI is not installed, or the reference cannot be read (not signed in, wrong path, locked vault), Docker Agent logs a warning and uses an **empty value** — it never forwards the raw `op://` reference to a model provider or tool. Resolved references (and deterministic failures) are cached for the lifetime of the run; transient failures such as a cancelled lookup are not cached, so a later attempt can retry. +> [!TIP] +> Other tools that read the same variables (Claude Code, Codex, provider SDKs) do not understand `op://` values. To keep references out of your shell, put them in the [Docker Agent env file](#docker-agent-env-file), which only Docker Agent reads, or point a model at a dedicated variable with [`token_key`](../../configuration/models/index.md). + ## Choosing a Method | Method | Best for | Setup effort | @@ -209,7 +251,7 @@ References follow the `op:////` format. Make sure the `op` C | Env files | Team projects, multiple keys | Low | | Docker Agent env file | Keys used across all projects, written by `docker agent setup` | Low | | Docker Compose secrets | Containerized deployments, CI/CD | Medium | -| Credential helper | Reusing an existing secrets daemon (Vault, 1Password CLI, ...) | Medium | +| Credential helper | Fetching `DOCKER_TOKEN` from an existing secrets daemon (Vault, 1Password CLI, ...) | Medium | | 1Password references (`op://`) | Teams already using 1Password | Low | You can combine methods. For example, store long-lived provider keys in the Docker Agent env file and pass project-specific MCP tokens via env files. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md index bfe2b34d43ed..c7aa6eb7a556 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/thinking/index.md @@ -24,10 +24,10 @@ Docker Agent exposes this through a single `thinking_budget` field on any named | Provider | Format | Values | Default | | ------------------- | ---------- | --------------------------------------------------------------------------------------- | ------------------ | | OpenAI | string | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; `xhigh` on gpt-5.2+, `max` on gpt-5.6+; API-level `none` on GPT-5.x from 5.6 onward and GPT-6 Sol/Luna, `minimal` dropped on gpt-5.6+ | `medium` (API default) | -| Anthropic | int or str | 1024–32768 tokens, or `minimal`–`max`, `adaptive`, `adaptive/`, `none` | off | +| Anthropic | int or str | Fixed budgets: ≥1024 and less than `max_tokens`; or `minimal`–`max`, `adaptive`, `adaptive/`, `none` | Model-dependent; Claude 5.x defaults to adaptive | | Gemini 2.5 | int | `0` (off), `-1` (dynamic), or token count (max 24576 / 32768) | `-1` (dynamic) | | Gemini 3 | string | `minimal`, `low`, `medium`, `high` | API default (model-dependent) | -| AWS Bedrock | int or str | 1024–32768 tokens (`minimal`–`max` mapped to tokens); `adaptive`, `adaptive/` for Opus 4.6+ (rejected by older Claude models) | off | +| AWS Bedrock | int or str | Fixed budgets: ≥1024 and less than `max_tokens`; `minimal`–`max` mapped to tokens on older models; adaptive on supported newer Claude models | Model-dependent; Claude 5.x defaults to adaptive | | Docker Model Runner | int or str | token count, `minimal`–`max` (mapped to tokens), `adaptive` (unlimited), `none` | engine default | String values are case-insensitive. The full set of accepted strings is `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `adaptive`, and `adaptive/` — but each provider only honors the subset listed above. Unsupported values either fail at request time (OpenAI) or are mapped/ignored as described per provider below. @@ -71,7 +71,7 @@ Anthropic Claude supports two thinking modes: a **token budget** (older models) ### Token budget (Claude 4 and earlier) -Set an explicit number of thinking tokens (1024–32768). This must be less than `max_tokens`: +Set an explicit number of thinking tokens (at least 1024). This must be less than `max_tokens` and within the model's supported range: ```yaml models: @@ -85,7 +85,7 @@ Docker Agent auto-adjusts `max_tokens` when you set a thinking budget but leave ### Adaptive thinking (Opus 4.6+ and Sonnet 4.6) -Newer Claude models support adaptive thinking, where the model decides how much to think. **Claude Opus 4.6, 4.7, 4.8, and Sonnet 4.6 only support adaptive thinking** — they reject token-based budgets. Use `adaptive`, `adaptive/`, or a bare effort level — on Anthropic, a bare effort level like `high` is shorthand for adaptive thinking at that effort: +Newer Claude models support adaptive thinking, where the model decides how much to think. **Claude Opus 4.6, 4.7, and 4.8 only support adaptive thinking** — they reject token-based budgets. Sonnet 4.6 supports both token budgets and adaptive thinking. Use `adaptive`, `adaptive/`, or a bare effort level — on Anthropic, a bare effort level like `high` is shorthand for adaptive thinking at that effort: ```yaml models: @@ -118,9 +118,9 @@ models: `minimal` is treated as `low` (bare form only). `high` is the default when `adaptive` is used without an effort level. > [!WARNING] -> **Effort strings require adaptive-capable models** +> **Effort strings are adapted to the model** > -> Every string effort value on Anthropic is sent as adaptive thinking (`output_config.effort`), which only newer Claude models (Opus 4.6+, Sonnet 4.6) accept. For older models like Sonnet 4.5, use an integer token budget instead. Conversely, models that _only_ support adaptive thinking (Opus 4.6, 4.7, 4.8, Sonnet 4.6) automatically have token budgets coerced to `adaptive` (a warning is logged). +> On adaptive-capable Claude models, effort strings use adaptive thinking (`output_config.effort`). For older models such as Sonnet 4.5 and Haiku 4.5, Docker Agent converts effort strings, including `adaptive/`, into fixed token budgets and logs a warning. Models that only support adaptive thinking have positive token budgets converted to `adaptive` instead. ### Disabling thinking (Claude) @@ -128,6 +128,10 @@ models: thinking_budget: none # or 0 ``` +Models that support disabling thinking honor this setting. Claude models that +require thinking use adaptive thinking with low effort instead. Claude 5.x +models think adaptively by default; see the [per-model rules](../../providers/anthropic/index.md#claude-5x-models). + ### Interleaved thinking Interleaved thinking lets the model reason between tool calls — useful for complex agentic tasks. Docker Agent auto-enables it whenever a thinking budget is configured on a Claude model, so you only need to set it explicitly to turn it off: @@ -308,7 +312,7 @@ models: thinking_budget: 0 ``` -`none` and `0` clear Docker Agent's thinking configuration — no thinking parameter is sent. Models that always reason (OpenAI o-series, gpt-5 through gpt-5.5, GPT-6 Astra, Gemini 3) then fall back to the API's default behavior and still reason internally; GPT-5.x from 5.6 onward and GPT-6 Sol/Luna send `none` as a real API value that genuinely disables reasoning. +On OpenAI o-series, gpt-5 through gpt-5.5, GPT-6 Astra, and Gemini 3, `none` and `0` clear the local budget and leave the API's default reasoning behavior in effect. GPT-5.x from 5.6 onward and GPT-6 Sol/Luna instead send `none` as an API value that disables reasoning. Claude models follow the [model-specific rules above](#disabling-thinking-claude). Local models and other OpenAI-compatible backends may reason by default even when `thinking_budget` is cleared. Use @@ -333,7 +337,7 @@ support that field. While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config, or type `/effort ` to jump straight to a specific level (e.g. `/effort high`). Running `/effort` without an argument opens a picker listing the levels the current model supports: -- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → xhigh → max → none` on gpt-5.6+ (no `minimal`), `none → low → medium → high → max → none` on Anthropic Opus 4.6 and Sonnet 4.6, and `none → low → medium → high → xhigh → max → none` on Anthropic Opus 4.7+, Fable 5, and Mythos 5. For older Anthropic models (e.g. Sonnet 4.5) that only accept token budgets, effort-string cycling has no effect — use an integer `thinking_budget` in your YAML config instead. +- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → xhigh → max → none` on gpt-5.6+ (no `minimal`), `none → low → medium → high → max → none` on Anthropic Opus 4.6 and Sonnet 4.6, and `none → low → medium → high → xhigh → max → none` on Anthropic Opus 4.7+, Fable 5, and Mythos 5. For older Anthropic models (e.g. Sonnet 4.5) that only accept token budgets, Docker Agent maps effort levels to fixed token budgets. - The current level is shown in the sidebar next to the model name (e.g. `openai/gpt-5 • high`). - This applies as a session override — it is **not** saved to the config file. The next session starts from the level defined in your YAML. - For models that don't support reasoning, and for remote runtimes, Shift+Tab is a no-op and an informational message is displayed. diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md index f84803d49cbe..c6cc235f28ea 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/tips/index.md @@ -57,23 +57,28 @@ agents: ### Model Aliases Are Auto-Pinned -Docker Agent automatically resolves model aliases to their latest pinned versions. This ensures reproducible behavior: +Docker Agent resolves named-model aliases to dated IDs when a matching pinned model exists in its model catalog. Inline `provider/model` references and models with a custom `base_url` are left unchanged: ```yaml -# You write: -model: anthropic/claude-sonnet-4-5 +models: + claude: + provider: anthropic + model: claude-sonnet-4-5 # resolves to a matching dated ID from the catalog -# docker-agent resolves to: -# anthropic/claude-sonnet-4-5-20250929 (or latest available) +agents: + root: + model: claude ``` -To use a specific version, specify it explicitly in your config. +To guarantee the same version across catalog updates, specify a dated model ID explicitly in your config. ## Performance Tips -### Defer Tools for Faster Startup + + +### Defer Tools to Reduce Prompt Size -Large MCP toolsets can slow down agent startup. Use `defer` to load tools on-demand: +Large MCP toolsets add tool definitions to the model's context. Use `defer` to expose those definitions on demand and reduce prompt size. The MCP servers still start normally: ```yaml agents: @@ -429,6 +434,19 @@ settings: If a sound is enough, set `settings: { sound: true }` instead — Docker Agent plays a failure sound when a task errors, and a success sound when a task that ran longer than `sound_threshold` seconds (default 10) completes. +### Keep the machine awake + +Enable **Keep machine awake** in `/settings` in either TUI to prevent idle system sleep while an agent is running. It is disabled by default, and changes apply to the next agent run. The display can still turn off; the inhibitor is released when the run finishes, errors, or is canceled. + +You can also enable it in your user configuration: + +```yaml +settings: + keep_awake: true +``` + +This uses native macOS and Windows power APIs, or systemd-logind over D-Bus on Linux, with no helper executables required. Linux requires a running system bus and logind with permission to inhibit sleep. If acquisition fails, the hook reports the error without stopping the agent. It does not guarantee protection against deliberate sleep, lid closure, or administrator policy. + See the [Hooks documentation](../../configuration/hooks/index.md) for the full list of events, their payloads, and per-hook options (`env`, `working_dir`, `timeout`). ### Inject the Current Session ID with Hooks diff --git a/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md b/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md index a38c4cf9dedd..4216e4915182 100644 --- a/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/guides/troubleshooting/index.md @@ -144,6 +144,19 @@ Model names must match the provider's naming exactly. Common mistakes: - Using a deprecated model name (e.g. `gpt-4` instead of `gpt-5-mini` or `gpt-4o`) - Model references are case-sensitive: `openai/gpt-5-mini` ≠ `openai/GPT-5-mini` +### Conversation ends without a final reply + +A model can end a turn after using tools without returning an answer, or return +only reasoning. This can happen with thinking models such as Claude Fable 5.2. +Docker Agent emits a warning with the model and stop reason; `--exec --json` +includes it as a `warning` event. An empty `stop` does not prove that the task +finished or that the request was rate-limited. + +Check the preceding tool results before sending a follow-up: tools may already +have changed files or created commits. Docker Agent does not automatically retry +these turns. Use `--session ` to continue the session. When reporting +an unexplained stop, include the warning and sanitized `--debug` logs. + ### Network connectivity If the agent hangs or times out, check that you can reach the provider's API endpoint. Firewalls, VPNs, or proxy settings may block requests. Docker Agent does not evaluate PAC files or URLs directly. When Docker Desktop is running, eligible requests use its PAC adapter before environment proxy settings; `NO_PROXY` does not bypass that selection. Set `DOCKER_AGENT_DISABLE_DESKTOP_PROXY=1` (or `true`, `yes`, or `on`) to restore `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` routing per request; see [Docker Desktop proxy](../../tools/fetch/index.md#docker-desktop-proxy) for scope and SSRF behavior. @@ -276,7 +289,7 @@ A few things that catch people out: ### Delegated task appears stalled before its first response -A direct `transfer_task` delegation automatically retries once when the child model stream is silent before sending any response payload. It emits the existing warning event, and the retry is immediate and applies once to the complete child run, including later turns and fallback models. Each nested native `transfer_task` starts a new child run with its own fresh retry allowance. The retry does not apply after partial output, to `background_agents`, or when cancellation or a run budget blocks it. +When a configured [stream idle timeout](../../configuration/models/index.md#stream-idle-timeout) expires before the child model sends any response payload, a direct `transfer_task` delegation automatically retries once. The idle timeout is disabled by default. It emits the existing warning event, and the retry is immediate and applies once to the complete child run, including later turns and fallback models. Each nested native `transfer_task` starts a new child run with its own fresh retry allowance. The retry does not apply after partial output, to `background_agents`, or when cancellation or a run budget blocks it. Run with `--debug` and look for `Delegated model stream idle before response; retrying immediately`. If the child still fails, check provider connectivity, fallback configuration, cancellation, and run-budget events; Docker Agent does not retry when the context is canceled or the run budget is exhausted. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md index 0f77d8206aa6..fad8dc03c16f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/anthropic/index.md @@ -125,11 +125,10 @@ make two endpoints interchangeable. | Bedrock runtime | `amazon-bedrock`; **`ConverseStream`** | Regional Bedrock runtime endpoint | AWS SigV4 credentials or Bedrock bearer token | Exact AWS model or inference-profile ID | | OpenAI-compatible aggregators | OpenAI client, Chat Completions for Claude | Alias/custom endpoint (e.g. OpenRouter, Vercel, Azure, OpenCode) | Host-specific key | Host's catalogue ID, not necessarily a Claude API ID | -These are existing adapter paths, not a guarantee of complete Claude 5.x -compatibility. Model-specific request rules, signed history, thinking and fallback -compatibility remain the subject of the planned [core work (#4583)](https://github.com/docker/docker-agent/issues/4583) -and [fallback work (#4584)](https://github.com/docker/docker-agent/issues/4584). -This guide does not mark those changes as implemented. +These are the adapter paths Docker Agent uses. Claude 5.x request rules, signed +history and thinking ([#4583](https://github.com/docker/docker-agent/issues/4583)) +and server-side fallback ([#4584](https://github.com/docker/docker-agent/issues/4584)) +are described in the sections below. - The built-in `opencode` alias is OpenAI-compatible; the [custom OpenCode Messages provider](../opencode-zen/index.md#anthropic-compatible-messages-api) @@ -167,12 +166,14 @@ limited Google access, but the audited Google directory has no dedicated model c | Sonnet 5.5 | `claude-sonnet-5-5` | Documented | Documented | Documented | | Fable 5 | `claude-fable-5` | Documented | Documented | Documented | | Fable 5.1 | `claude-fable-5-1` | Documented | Documented | Documented | +| Fable 5.2 | `claude-fable-5-2` | Documented | Documented | Documented | | Mythos 5 | `claude-mythos-5` | Documented, gated | Limited announcement | **Unsupported** (Mantle only) | | Mythos 5.1 | `claude-mythos-5-1` | Documented, gated | Limited announcement | Documented, gated (not Mantle) | +| Mythos 5.2 | `claude-mythos-5-2` | Documented, gated | Limited announcement | Documented, gated | -The audit found **24 corroborated native model/platform pairs** (9 Claude API + -7 Vertex + 8 Bedrock runtime), **2 limited-access Mythos/Google announcements** and -**1 explicitly unsupported Mythos 5/Converse pair**. This is not 26 implemented +The audit found **29 corroborated native model/platform pairs** (11 Claude API + +8 Vertex + 10 Bedrock runtime), **3 limited-access Mythos/Google announcements** and +**1 explicitly unsupported Mythos 5/Converse pair**. These are not implemented or live-tested successes. All documented rows still require model access for your account and chosen endpoint. An absent Google card proves neither unavailability nor entitlement. @@ -181,7 +182,10 @@ Sources: [Claude model overview](https://platform.claude.com/docs/en/models/over [Claude on Vertex](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), [Google's Claude directory](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/claude), [Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), -[Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview) and +[Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), +[Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), +[Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), +[Google Fable 5.2](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/partner-models/claude/fable-5-2) and [AWS endpoint availability](https://docs.aws.amazon.com/bedrock/latest/userguide/models-endpoint-availability.html). According to [model IDs and versions](https://platform.claude.com/docs/en/about-claude/models/model-ids-and-versions), @@ -205,8 +209,10 @@ For regional profiles, regions and access requirements, follow the linked card. | [Sonnet 5.5](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-sonnet-5-5.html) | `anthropic.claude-sonnet-5-5` | `global.anthropic.claude-sonnet-5-5` | | [Fable 5](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-fable-5.html) | `anthropic.claude-fable-5` | `global.anthropic.claude-fable-5` | | [Fable 5.1](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-fable-5-1.html) | `anthropic.claude-fable-5-1` | `global.anthropic.claude-fable-5-1` | +| [Fable 5.2](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-fable-5-2.html) | `anthropic.claude-fable-5-2` | `global.anthropic.claude-fable-5-2` | | [Mythos 5](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-mythos-5.html) | `anthropic.claude-mythos-5` (Mantle only) | None; no runtime access | | [Mythos 5.1](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-mythos-5-1.html) | `anthropic.claude-mythos-5-1` | `global.anthropic.claude-mythos-5-1` | +| [Mythos 5.2](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-mythos-5-2.html) | `anthropic.claude-mythos-5-2` | `global.anthropic.claude-mythos-5-2` | Do not copy one model's regional prefix set onto another. The bundled models.dev snapshot's prefix coverage differs from these cards in both directions; it is a @@ -255,19 +261,19 @@ Anthropic accepts either an integer token budget or a string effort value. When ### Claude 5.x models -Docker Agent recognizes nine Claude 5.x models by ID: `claude-haiku-5-5`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-fable-5`, `claude-fable-5-1`, `claude-mythos-5` and `claude-mythos-5-1`. Bedrock (`us.anthropic.…`) and Vertex (`…@date`) spellings are recognized too. For these models: +Docker Agent recognizes eleven Claude 5.x models by ID: `claude-haiku-5-5`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5`, `claude-sonnet-5-5`, `claude-fable-5`, `claude-fable-5-1`, `claude-fable-5-2`, `claude-mythos-5`, `claude-mythos-5-1` and `claude-mythos-5-2`. Bedrock (`us.anthropic.…`) and Vertex (`…@date`) spellings are recognized too. For these models: - Thinking is adaptive by default and accepts every effort level: `low`, `medium`, `high`, `xhigh` and `max`. -- With `thinking_budget` unset, Haiku 5.5, Opus 5.5, Sonnet 5.5 and Fable 5.1 are sent explicit adaptive thinking (summarized display, no effort) so the server can check replayed thinking blocks; the other five keep their API default. +- With `thinking_budget` unset, Haiku 5.5, Opus 5.5, Sonnet 5.5, Fable 5.1/5.2 and Mythos 5.2 are sent explicit adaptive thinking (summarized display, no effort) so the server can check replayed thinking blocks; the other five keep their API default. - An integer token budget becomes adaptive thinking with the model's default effort; `max_tokens` is not raised. - `temperature`, `top_p` and `top_k` are never sent. -- `thinking_budget: none` (or `0`) sends `thinking: disabled` on Haiku 5.5, Opus 5 and Sonnet 5. The other six cannot disable thinking: they get adaptive thinking with `low` effort, and Docker Agent logs a warning at startup. -- Server-side `fallbacks` involving any of these models are rejected at startup until [#4584](https://github.com/docker/docker-agent/issues/4584). +- `thinking_budget: none` (or `0`) sends `thinking: disabled` on Haiku 5.5, Opus 5 and Sonnet 5. The other eight cannot disable thinking: they get adaptive thinking with `low` effort, and Docker Agent logs a warning at startup. +- Server-side `fallbacks` work with these models on the Claude API, except Haiku 5.5, which has none (see [Server-Side Fallbacks](#server-side-fallbacks)). - A request that ends on an assistant message (a response prefill) is rejected before it is sent. Tool-mode structured output therefore fails after the first plain-text answer instead of retrying with a reminder. Other Claude IDs keep the existing name-based rules. -**Token budget** (1024–32768 on models that accept manual extended thinking): +**Token budget** (at least 1024 and less than `max_tokens`, within the supported range of a model that accepts manual extended thinking): ```yaml models: @@ -345,11 +351,78 @@ Object form (forward-compatible with future budget types): See the full schema on the [Model Configuration](../../configuration/models/index.md#task-budget) page. +## Fast Mode + +Set `provider_opts.speed` to `fast` to request Anthropic's [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode), which runs the same model at up to 2.5× higher output tokens per second: + +```yaml +models: + fast-opus: + provider: anthropic + model: claude-opus-5-5 + provider_opts: + speed: fast +``` + +Fast mode is available on supported models such as Claude Opus 5.5 and Claude Fable 5.2, and in research preview on Claude Opus 5 and Claude Opus 4.8. See Anthropic's documentation for the current list. Docker Agent does not maintain a model allowlist: on an unsupported model, or when the separate fast-mode rate limit is exceeded, the API error is returned as-is. It applies to all requests using the configured model, including internal calls such as title generation, compaction, and reranking. + +Setting `fast` routes requests through the Beta Messages API, sends `speed: "fast"`, and attaches the `fast-mode-2026-02-01` beta header. Per Anthropic's documentation, only Opus 5 and Opus 4.8 require the beta header; Docker Agent sends it on every fast-mode request. `standard` and an empty value send nothing, leaving the API's default behavior unchanged, which lets a model override a `fast` default inherited from the provider configuration. Any other value, including a non-string, is rejected when the model is loaded. + +> [!WARNING] +> Fast mode is billed at premium pricing, has its own rate limit, and switching speed invalidates the prompt cache. It is a Claude API feature and is not supported on Amazon Bedrock; availability on Vertex AI and Microsoft Foundry differs, so check Anthropic's documentation before enabling it there. It cannot be combined with the Batch API or Priority Tier. + +Cost estimates use the **actual response speed** (`usage.speed`), not the requested one: a request for `fast` that the API serves as `standard` is priced at standard rates. Anthropic [publishes](https://platform.claude.com/docs/en/build-with-claude/fast-mode#pricing) fast input and output prices at exactly twice standard (for example Claude Fable 5.2 at $16/$80 and Claude Opus 5.5 at $8/$40 per million tokens). It publishes no separate cache prices for fast mode and states that prompt-caching multipliers apply on top, so cache reads and cache writes are doubled as well, matching the fast entries gateways list for Claude Opus. Each catalogue rate, including the rates of any long-context band, is therefore multiplied by 2 for a `fast` response, when the model is served by `provider: anthropic` at the default Anthropic endpoint. Cache writes use the catalogue's single cache-write rate. Any `base_url` or `ANTHROPIC_BASE_URL` override, including proxies, keeps catalogue pricing. The factor is derived from Anthropic's published fast-mode pricing at the time of writing and may drift if Anthropic changes it. + +> [!NOTE] +> Server-side fallback attempts retain standard pricing, because attempts do not report a speed, so a fast response that used fallbacks may be under-estimated. A request routed by a rule-based router is priced by the model that served it, under the rules above. Estimates do not include negotiated discounts. A model's [`cost` override](../../configuration/models/index.md#custom-token-pricing) replaces the entire price table and is never adjusted for fast mode. + +### Global default + +To enable fast mode without editing each agent file, set it in your user configuration (`~/.config/cagent/config.yaml`). A `providers` entry with `provider: anthropic` is a native Anthropic provider, so it needs no `base_url`. Select it with its name: + +```yaml +# ~/.config/cagent/config.yaml +providers: + fast-claude: + provider: anthropic + provider_opts: + speed: fast +``` + +```bash +docker agent run agent.yaml --model fast-claude/claude-opus-5-5 +``` + +Naming the entry `anthropic` instead applies it to every model whose provider is `anthropic`, whether it comes from `--model anthropic/...`, an agent file, or `first_available`. It fills only the options a model leaves unset, so credentials and the endpoint still come from the built-in defaults: + +```yaml +providers: + anthropic: + provider: anthropic # required; an entry without it is ignored with a warning + provider_opts: + speed: fast +``` + +Alternatively, `default_model` in its full form applies fast mode when a model resolves to `auto` (`--model auto` or `model: auto`). The `DOCKER_AGENT_DEFAULT_MODEL` environment variable only accepts `provider/model` and carries no options. + +```yaml +default_model: + provider: anthropic + model: claude-opus-5-5 + provider_opts: + speed: fast +``` + +A model-level `provider_opts.speed: standard` overrides the global value, and an agent file that defines its own `providers.anthropic` replaces the user-config entry entirely. A global entry named `anthropic` covers every Anthropic request, including sub-agents, title generation, and compaction, all at premium pricing. An invalid value fails when the first Anthropic model is created. + +See [`examples/anthropic-fast-mode.yaml`](https://github.com/docker/docker-agent/blob/main/examples/anthropic-fast-mode.yaml) for a complete example. + ## Server-Side Fallbacks -When the primary model refuses a request (stop reason `refusal`), Anthropic -can retry the request with backup models in a single round trip. Set -`fallbacks` in `provider_opts` to a list of model IDs, in priority order: +When the primary model refuses a request (stop reason `refusal`), the Claude +API can retry it on a fallback model in a single round trip. Set `fallbacks` +in `provider_opts` to `default`, to use the fallback Anthropic recommends for +the refusal's category: ```yaml models: @@ -357,25 +430,72 @@ models: provider: anthropic model: claude-opus-4-8 provider_opts: + fallbacks: default +``` + +Or list up to three distinct models, tried in order: + +```yaml fallbacks: - claude-opus-4-7 - claude-sonnet-4-6 ``` -> [!WARNING] -> **Not yet available with Claude 5.x** -> -> A fallback can change the serving model mid-response, which Docker Agent does not handle yet. A `fallbacks` list is rejected at startup when the primary model or any fallback is a Claude 5.x model (Haiku 5.5, Opus 5/5.5, Sonnet 5/5.5, Fable 5/5.1, Mythos 5/5.1). Support is tracked in [#4584](https://github.com/docker/docker-agent/issues/4584). - -Docker Agent automatically attaches the required -`server-side-fallback-2026-06-01` beta header and forwards the option as -`fallbacks: [{"model": "..."}]`. The response's `model` field reports which -model actually served the request. +When a model declines mid-response, the turn continues on the fallback model. +Docker Agent never runs a tool call the declining model made, stores the turn +under the model that served it, and replays it on the next request as the API +requires. The turn's cost adds up each model hop at its own rates, combining +all of that hop's server-tool iterations. The dispatched hop retains its +configured price override when the first marker echoes the requested model, +including an alias; fallback hops use their own catalogue prices. Sticky hops +never inherit the primary's override, including across server-tool iterations. +A declined hop that produced output is billed. Before-output refusals are billed +for `bio`, `frontier_llm`, and `reasoning_extraction`; other named categories and +an explicit JSON-null category are unbilled. This also applies to the final +refusal if the fallback chain is exhausted. Missing or invalid categories, or +markers that cannot be matched to the usage hops in model order, remain billed +conservatively. The top-level usage is not added again. + +Docker Agent sends the `server-side-fallback-2026-07-01` beta header, which +accepts both forms, through the beta Messages API. The response's `model` +field reports which model actually served the request. + +For sticky routing without a handoff marker, Docker Agent uses a different +`message_start.model` provisionally when it matches an explicit fallback target +or a replayed handoff target. This preserves attribution on clean EOF before +final usage. A completed usage event clears the candidate unless a +`fallback_message` confirms fallback routing; an explicit handoff marker takes +precedence over both. Ordinary responses keep the configured model ID, display +name and cost override. A truncated alias that collides with a historical target +can still be attributed to that target; explicit fallback aliases without a +matching history marker have no early attribution. + +Rules checked at startup: + +- A list holds at most three models, each distinct and different from the + primary model. Any other value is a configuration error. +- Server-side fallback is a Claude API feature: `fallbacks` is rejected on + Vertex AI, Bedrock, a gateway, or a base URL (`base_url` or + `ANTHROPIC_BASE_URL`) whose host isn't `api.anthropic.com`. It isn't + available on the Message Batches API either. +- Claude Haiku 5.5 has no server-side fallback: a list is rejected, and + `default` only logs that it has no effect. +- The request must be valid for every listed model, or the API rejects it up + front. A configuration is rejected when a listed fallback (such as a Claude + 5.x model) refuses what the request sends: `temperature` or `top_p` (sent + only with thinking off), `top_k`, or token-budget thinking, including an + effort level that an older model without adaptive thinking turns into a + token budget. Fallback models receive the exact same request as the primary model (thinking configuration, task budget, beta features, ...), so list only -models that accept the same request shape. Not available on Bedrock, Vertex -AI, or the Message Batches API. +models that accept the same request shape. With `default` the server picks +the fallback, so per-model options such as `thinking_display` are checked +against the primary model only. The API makes one exception itself: when a Claude +Sonnet 5.5 request with `between_tools` thinking falls back to Claude Sonnet 5, +that attempt runs with thinking disabled ([fallback list rules](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#naming-your-own-fallback-models)). + +See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). ## Native Compaction @@ -396,9 +516,10 @@ and replaces the whole history with a signed compaction block. This first implementation is synchronous and compacts the whole history: it does not run in the background or preserve a recent tail. Legacy per-call hook extras are not included in the compaction snapshot; they are applied again on the next -normal turn. The block is persisted alongside a readable summary; the -Anthropic provider replays the block on later requests (including after a model -switch), while other providers receive the readable text. +normal turn. The block is persisted alongside a readable summary; Anthropic +models with `native_compaction` set replay the block on later requests +(including after a model switch), while other models, Vertex AI included, +receive the readable text. - The compaction request goes through the same `before_llm_call` hooks and message transforms as a regular model call, so builtins such as @@ -449,7 +570,7 @@ changed since: declared at the end of `tools` with `defer_loading: true` and surfaced by a `tool_addition`; - an effort change becomes a per-message `output_config.effort` on Claude - Opus 5, Fable 5.1 and Mythos 5.1; + Opus 5, Fable 5.1/5.2 and Mythos 5.1/5.2; - per-call system extras (environment information, prompt files and hook reminders) become text-only, turn-scoped system messages. They remain in history verbatim but stop applying at the next user turn. If the prompt ends @@ -475,8 +596,8 @@ Docker Agent attaches the `mid-conversation-tool-changes-2026-07-01`, that actually carry a tool change, a per-message effort or a turn-scoped reminder. -Supported on Claude Opus 4.8, Opus 5, Fable 5, Fable 5.1, Mythos 5 and -Mythos 5.1 (and their server-side fallbacks); Sonnet 5 and older models are +Supported on Claude Opus 4.8, Opus 5, Fable 5/5.1/5.2 and Mythos 5/5.1/5.2 +(and their server-side fallbacks); Sonnet 5 and older models are rejected at configuration time. Fallback models must also support the request's per-message effort features. The option requires the Beta Messages API. ## Thinking Display @@ -497,7 +618,7 @@ Valid values: - `summarized`: thinking blocks are returned with summarized thinking text (Docker Agent's default for adaptive/effort-based budgets). - `display`: thinking blocks are returned for display. Only accepted by pre-4.6 token-thinking models (e.g. Sonnet 4.5, Haiku 4.5); models from the adaptive-thinking generation onward (Opus/Sonnet 4.6+, Sonnet 5, Fable 5) reject it, and Docker Agent fails fast with a configuration error instead of sending a request the API would refuse. -- `updates`: short progress updates between tool calls, with reasoning text omitted. Available on Fable 5/5.1 and Mythos 5.1; automatically enables `thinking-display-updates-2026-08-18`. No explicit budget is required, and an unset effort keeps the model default. Other models (including configured fallbacks) are rejected locally. +- `updates`: short progress updates between tool calls, with reasoning text omitted. Available on Fable 5/5.1/5.2 and Mythos 5.1/5.2; automatically enables `thinking-display-updates-2026-08-18`. No explicit budget is required, and an unset effort keeps the model default. Other models (including configured fallbacks) are rejected locally. - `omitted`: thinking blocks are returned with an empty thinking field; the signature is still returned for multi-turn continuity. Useful to reduce time-to-first-text-token when streaming. Note: `thinking_display` applies to both `thinking_budget` with token counts and adaptive/effort-based budgets. For token-count budgets no default is applied (the API already defaults to `summarized`). Full thinking tokens are billed regardless of the `thinking_display` value. @@ -512,14 +633,20 @@ multiple thinking blocks, omitted thinking, redacted thinking and their signatur A hook or user edit invalidates raw replay so stale content cannot override it. When only the rest of the turn changed (for example a sanitized tool name or a redacted tool argument), its recorded thinking is still replayed in its original -place, with the current text and tool calls substituted. When the thinking itself changed, the turn loses it, -with a warning in the logs. If that turn belongs to the tool loop the next -request continues, and thinking is on, the API needs its original signed +place, with the current tool calls substituted. Unchanged text blocks retain their +contents and positions, including around fallback markers. Edited text can replace +a single original text block only when no thinking block follows it. New text can +be inserted before the first tool call (or at the end without tools) only when no +thinking block is at or after that position. Other text edits, including edits +spanning multiple blocks, cannot preserve the recorded thinking safely. When +thinking itself changed or text edits cannot be placed safely, the turn is sent +without thinking, with a warning in the logs. If that turn belongs to the tool +loop the next request continues, and thinking is on, the API needs its original signed thinking: Docker Agent refuses the request with an error instead, and a new user turn starts a fresh loop. On Claude models whose server checks thinking prefixes (Haiku 5.5, Opus 5.5, -Sonnet 5.5 and Fable 5.1), Docker Agent defaults to +Sonnet 5.5, Fable 5.1/5.2 and Mythos 5.2), Docker Agent defaults to `thinking.block_binding.prefix_mismatch_behavior: drop_block`: when earlier history changes, the API drops invalidated thinking instead of rejecting the request. Dropped blocks are reported in logs. Docker Agent does not default to @@ -531,6 +658,8 @@ history strictly anyway, set `provider_opts.thinking_prefix_mismatch: error`, an avoid compaction, handoffs, `num_history_items` and toolsets that start late. You can explicitly select `drop_block` on other supported Claude models too. Both modes attach `thinking-binding-controls-2026-08-01`; neither repairs corrupted signatures. +For the Bedrock Converse policy and observability limits, see the +[Bedrock guide](../bedrock/index.md#claude-5x-models). ## Strict Tool Arguments diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md index e72407d6fabf..7da1ad36a666 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/baseten/index.md @@ -30,7 +30,7 @@ The simplest way to use Baseten: ```yaml agents: root: - model: baseten/deepseek-ai/DeepSeek-V4-Pro + model: baseten/deepseek-ai/DeepSeek-V4-Pro-0813 description: Assistant using Baseten instruction: You are a helpful assistant. ``` @@ -43,7 +43,7 @@ For more control over parameters: models: baseten_model: provider: baseten - model: deepseek-ai/DeepSeek-V4-Pro + model: deepseek-ai/DeepSeek-V4-Pro-0813 temperature: 0.7 max_tokens: 8192 @@ -58,12 +58,12 @@ agents: Baseten hosts various open models through its Model APIs. Check the [Baseten documentation](https://docs.baseten.co/) for the current model catalog. -| Model | Description | -| ------------------------------ | ------------------------------ | -| `deepseek-ai/DeepSeek-V4-Pro` | DeepSeek V4 Pro model | -| `moonshotai/Kimi-K2.5` | Moonshot Kimi K2.5 model | -| `openai/gpt-oss-120b` | GPT-OSS 120B model | -| `zai-org/GLM-5` | GLM-5 model | +| Model | Description | +| ------------------------------- | ------------------------- | +| `deepseek-ai/DeepSeek-V4-Pro-0813` | DeepSeek V4 Pro 0813 model | +| `moonshotai/Kimi-K3` | Moonshot Kimi K3 model | +| `openai/gpt-oss-120b` | GPT-OSS 120B model | +| `zai-org/GLM-5.3` | GLM-5.3 model | ## How It Works @@ -78,10 +78,10 @@ Baseten is implemented as a built-in alias in Docker Agent: ```yaml agents: coder: - model: baseten/deepseek-ai/DeepSeek-V4-Pro + model: baseten/deepseek-ai/DeepSeek-V4-Pro-0813 description: Code assistant using DeepSeek instruction: | - You are an expert programmer using DeepSeek V4 Pro. + You are an expert programmer using DeepSeek V4 Pro 0813. Write clean, well-documented code. Follow best practices for the language being used. toolsets: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md index 6d1e4c249854..d336650ef018 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/bedrock/index.md @@ -126,7 +126,7 @@ Claude 5.x profile in this audit; do not generate IDs by copying prefixes. ## Thinking Budget (Claude on Bedrock) -Bedrock Claude models support extended thinking — an internal reasoning phase before the model produces its response. Set `thinking_budget` to a token count (1024–32768) or an effort level string that maps automatically: +Bedrock Claude models support extended thinking — an internal reasoning phase before the model produces its response. On models that accept fixed token budgets, set `thinking_budget` to at least 1024 and less than `max_tokens`, or use an effort level string that maps automatically: | Effort level | Token budget | | ------------ | ------------ | @@ -140,7 +140,7 @@ Bedrock Claude models support extended thinking — an internal reasoning phase models: bedrock-claude-thinking: provider: amazon-bedrock - model: global.anthropic.claude-sonnet-5 + model: global.anthropic.claude-sonnet-4-5-20250929-v1:0 thinking_budget: 8192 # tokens, or use an effort string like "medium" max_tokens: 16384 # must be > thinking_budget provider_opts: @@ -172,18 +172,30 @@ Docker Agent recognizes these models (including Bedrock-style IDs) and transpare ### Claude 5.x models -The nine Claude 5.x models listed in the [Anthropic provider guide](../anthropic/index.md#claude-5x-models) follow the same rules on Bedrock, including Bedrock-style IDs such as `us.anthropic.claude-sonnet-5-5-v1:0`: +The eleven Claude 5.x models listed in the [Anthropic provider guide](../anthropic/index.md#claude-5x-models) follow the same rules on Bedrock, including Bedrock-style IDs such as `us.anthropic.claude-sonnet-5-5-v1:0`: - Effort levels and `adaptive` are sent as adaptive thinking. An integer token budget becomes adaptive thinking with the model's default effort. - `temperature`, `top_p` and `top_k` are never sent. -- `thinking_budget: none` sends `thinking: {"type": "disabled"}` on Haiku 5.5, Opus 5 and Sonnet 5. The other six get adaptive thinking with `low` effort and a startup warning. +- `thinking_budget: none` sends `thinking: {"type": "disabled"}` on Haiku 5.5, Opus 5 and Sonnet 5. The other eight get adaptive thinking with `low` effort and a startup warning. - Reasoning blocks are stored and replayed exactly as Bedrock returned them, in order: signed thinking (including signature-only thinking, the default display on these models), redacted thinking and the text and tool calls around them. If a message changed after it was received but its reasoning did not (for example a sanitized tool name or a redacted tool argument), its recorded reasoning is still replayed in its original place, with the current text and tool calls substituted. If the reasoning itself changed, it is sent without it, with a warning in the logs; inside the tool loop the next request continues, with thinking on, the request is refused instead, and a new user turn starts a fresh loop. Sessions saved by older versions keep that flattened replay; older versions ignore the stored blocks. - Mythos 5 is refused at startup: AWS serves it only through Bedrock Mantle, which Docker Agent does not support. Use Mythos 5.1, which is available on Converse, or the Claude API. +For Haiku 5.5, Opus 5.5, Sonnet 5.5, Fable 5.1/5.2 and Mythos 5.2, +Converse uses adaptive thinking with the `thinking-binding-controls-2026-08-01` +beta and `thinking.block_binding.prefix_mismatch_behavior: drop_block` by default. +This lets AWS drop invalidated thinking blocks when compaction, handoffs or other +history edits change their prefix. Set `provider_opts.thinking_prefix_mismatch` +to `error` to reject such requests instead, or `drop_block` to select the default +explicitly. This option is only applied to the listed models while thinking is on; +invalid option values are rejected. Neither behavior repairs corrupted signatures. +Unlike the Claude API integration, the Bedrock client does not report dropped +blocks: Converse stream transformation reporting has not been verified. +See [AWS preserved thinking documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-thinking-block-binding.html). + > [!NOTE] > **Not yet verified live** > -> The `disabled` value follows the Claude Messages contract; it has not yet been verified against live Bedrock Converse. +> The `disabled` value and prefix-binding controls follow the documented Claude Messages contract; they have not yet been verified against live Bedrock Converse. ## Interleaved Thinking (Claude on Bedrock) diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/cloudgpu/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/cloudgpu/index.md new file mode 100644 index 000000000000..4deb1ddafa7f --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/cloudgpu/index.md @@ -0,0 +1,114 @@ +--- +title: "CloudGPU" +description: "Use CloudGPU models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, cloudgpu +weight: 26 +canonical: https://docs.docker.com/ai/docker-agent/providers/cloudgpu/ +--- + +_Use CloudGPU models with Docker Agent._ + +## Overview + +[CloudGPU](https://cloudgpu.app/api/docs) serves DeepSeek, Kimi, GLM and MiniMax +models through an OpenAI-compatible API. Docker Agent includes built-in support +for CloudGPU as an alias provider. Current model IDs are on the live +[model list](https://cloudgpu.app/v1/models). + +## Setup + +1. Create an API key in the [CloudGPU console](https://cloudgpu.app/) +2. Set the environment variable: + + ```bash + export CLOUDGPU_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Use a CloudGPU model by prefixing its model ID with `cloudgpu/`: + +```yaml +agents: + root: + model: cloudgpu/deepseek-v4.1-flash + description: Assistant using CloudGPU + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + cloudgpu_kimi: + provider: cloudgpu + model: kimi-k3 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: cloudgpu_kimi + description: Assistant using CloudGPU + instruction: You are a helpful assistant. +``` + +When CloudGPU is selected automatically from available credentials, the default +model is `deepseek-v4.1-flash`. + +## Available Models + +Some chat model IDs CloudGPU serves: + +| Model ID | Model | +| --- | --- | +| `deepseek-v4.1-flash` | DeepSeek V4.1 Flash (default) | +| `deepseek-v4-pro` | DeepSeek V4 Pro | +| `kimi-k3` | Kimi K3 | +| `glm-5.2` | GLM 5.2 | +| `minimax-m3` | MiniMax M3 | + +Model IDs are case-sensitive. The live [`/v1/models` endpoint](https://cloudgpu.app/v1/models) +lists current IDs, and the [API docs](https://cloudgpu.app/api/docs) describe +the endpoints. A listing does not guarantee that inference is currently available. + +CloudGPU is absent from the embedded models.dev catalog. Docker Agent does not +import context limits or attachment capabilities from CloudGPU's model list. +Attachment capabilities fall back to text-only, so image and PDF attachments +are dropped, with a warning logged once per model. + +If you have verified that your chosen model accepts a particular attachment +type, set `models..capabilities` to override detection. See +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides) +for all supported flags. + +## How It Works + +CloudGPU is a built-in alias in Docker Agent: + +- **API type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://cloudgpu.app/v1` +- **Token variable:** `CLOUDGPU_API_KEY` + +Some models CloudGPU serves require a single leading system message, so Docker +Agent coalesces consecutive system messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: cloudgpu/deepseek-v4.1-flash + description: Code assistant using CloudGPU + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md index ee522a0e6a78..363bb64aaa49 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/custom/index.md @@ -166,6 +166,51 @@ agents: > > Models that stream reasoning under `delta.reasoning` (e.g. Qwen3 served via OVHcloud AI Endpoints, OpenRouter, or a self-hosted vLLM / SGLang deployment) are fully supported. Docker Agent reads both the `delta.reasoning_content` and `delta.reasoning` fields from the stream, so thinking blocks are captured and shown in the TUI regardless of which field the server uses. +### Replaying reasoning on later turns + +Captured reasoning is sent back to the model on subsequent requests as a `reasoning_content` field on the assistant message. Servers that understand the field read it back, so the model sees its own earlier reasoning instead of re-deriving it after every tool call. Reasoning that is only useful to the model is not free: replaying it can multiply the size of a long request, so it is limited to turns the session keeps anyway (those with content or a tool call). + +Chat Completions reasoning replay defaults on. Because `reasoning_content` is a +non-standard extension, set `provider_opts.replay_reasoning: false` for a model +or provider whose endpoint rejects or must not receive it. An invalid, +non-boolean value also fails closed and disables replay. + +Set the opt-out on a model, or once on a provider and let its models inherit it. +A model that sets the option itself wins over the provider: + +```yaml +providers: + local_llm: + base_url: http://localhost:8000/v1 + provider_opts: + replay_reasoning: false # opt out every local_llm model + +models: + qwen_default: + provider: local_llm + model: qwen3 # inherits the opt-out + + qwen_replay: + provider: local_llm + model: qwen3 + provider_opts: + replay_reasoning: true # opts this model back in + +agents: + root: + model: qwen_default +``` + +This option is specific to the Chat Completions API and its `reasoning_content` +field. It is not the same as `preserve_reasoning`, which replays the encrypted +reasoning items of first-party OpenAI Responses sessions; neither option +applies to the other API. See [Reasoning state preservation](../openai/index.md#reasoning-state-preservation). + +The field is worth a look if you switch models mid-session or use fallbacks: +Docker Agent stores reasoning from every provider in one place, so a later Chat +Completions model may otherwise receive reasoning captured from another vendor. +Set `replay_reasoning: false` on that destination when this is undesirable. + ### API Router (Requesty, LiteLLM) ```yaml @@ -193,7 +238,7 @@ models: ### Anthropic Team Setup -Agents can use different models backed by the same named provider. Starting from the [Default Inheritance](#default-inheritance) example: +Agents can use different models backed by the same named provider. Keep the `providers` and `models` sections from the [Default Inheritance](#default-inheritance) example and replace its `agents` section with: ```yaml agents: @@ -270,6 +315,10 @@ that automatic model selection (`model: auto`) never picks a custom provider, so reference its models explicitly with `--model /` or `default_model`. +An entry with a native `provider` (such as `provider: anthropic`) needs no +`base_url` and can carry `provider_opts`; see +[Anthropic fast mode](../anthropic/index.md#global-default) for an example. + ## How It Works When you reference a provider: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md index 40b16848c8cf..d6c9f4828e4f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/dmr/index.md @@ -196,6 +196,14 @@ Accepted values: any Go duration string (`"30s"`, `"5m"`, `"1h"`, `"2h30m"`), `" In multi-agent setups where two DMR models can't fit in GPU memory simultaneously, wire the [`unload`](../../configuration/hooks/index.md#available-built-ins) built-in hook into each agent's `on_agent_switch` chain. Every time the active agent transfers control, the runtime POSTs to the engine's `_unload` endpoint to free the previous model's resources before the next one is loaded: ```yaml +models: + qwen3-large: + provider: dmr + model: ai/qwen3 + qwen3-coder: + provider: dmr + model: ai/smollm2 + agents: coder: model: qwen3-large diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md index 7981da6e7d30..e33ad1284d7f 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/google/index.md @@ -20,6 +20,8 @@ Docker Agent reads the first credential it finds from these environment variable | `GOOGLE_CLOUD_PROJECT` | GCP project used when `GOOGLE_GENAI_USE_VERTEXAI` is enabled or for Vertex AI Model Garden. | | `GOOGLE_CLOUD_LOCATION` | GCP region for Vertex AI (defaults to the SDK default). | +When the model sets no `base_url`, the Google SDK's endpoint override applies: `GOOGLE_GEMINI_BASE_URL` for the Gemini Developer API or `GOOGLE_VERTEX_BASE_URL` for Vertex AI. An explicit `base_url` takes precedence, even when it equals the default endpoint. + Explicit `provider_opts.project` or `provider_opts.location` selects Vertex AI regardless of the flag. On the Gemini Developer API, a model or [custom provider](../custom/index.md) that sets `token_key` reads its key from that variable instead of `GOOGLE_API_KEY` / `GEMINI_API_KEY`. The Vertex AI backends use Application Default Credentials and ignore `token_key`. @@ -280,7 +282,7 @@ models: The value is forwarded unchanged as the top-level `serviceTier` of every `generateContent` request on the Gemini Developer API, Vertex AI, and the Docker models gateway; the endpoint must support it. It applies to all requests using the configured model, including reranking, title generation, and compaction. Other values are passed through for the API to validate. When omitted or empty, no `serviceTier` is sent, leaving the API's default behavior unchanged. Non-string values are ignored. [Vertex AI Model Garden](#vertex-ai-model-garden) models do not use this option. -Flex requests can sit in Google's queue for up to 15 minutes before the first byte arrives. Docker Agent normally treats a stream that stays silent for 5 minutes as stalled; for `google` models with `service_tier: flex` it waits 15 minutes instead. Other tiers and providers keep the 5 minute limit. Rate-limit (`429`) and overloaded (`503`) responses are retried like any other Gemini request; Docker Agent never upgrades a request to a different tier on your behalf. +Flex requests can sit in Google's queue for up to 15 minutes before the first byte arrives. Docker Agent has no stream idle timeout by default. A short [configured stream idle timeout](../../configuration/models/index.md#stream-idle-timeout) can time out a queued Flex request. Rate-limit (`429`) and overloaded (`503`) responses are retried like any other Gemini request; Docker Agent never upgrades a request to a different tier on your behalf. > [!WARNING] > Docker Agent's cost estimates do not adjust for `service_tier`. They use the catalogue's standard pricing, which overestimates `flex` and underestimates `priority` charges. Set the model's [`cost` override](../../configuration/models/index.md#custom-token-pricing) to the applicable input, output, and cache token rates for your tier. @@ -313,7 +315,7 @@ announcements but no dedicated Google card in the 2026-10-13 audit; this proves neither unavailability nor account entitlement. See [Claude access paths](../anthropic/index.md#claude-access-paths) for model IDs, evidence and policy prerequisites. -Title, sampling and compaction clones keep the selected Model Garden transport. +Title and compaction clones keep the selected Model Garden transport. Claude requests remain on the Anthropic-native Vertex endpoints, with the model in the URL and `anthropic_version: vertex-2023-10-16` in the body. Project, location, regional/global host selection and Google OAuth authentication survive diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/hopbase/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/hopbase/index.md new file mode 100644 index 000000000000..8147d7ceb802 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/hopbase/index.md @@ -0,0 +1,158 @@ +--- +title: "HopBase" +description: "Use HopBase models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, hopbase +weight: 135 +canonical: https://docs.docker.com/ai/docker-agent/providers/hopbase/ +--- + +_Use HopBase models with Docker Agent._ + +## Overview + +[HopBase](https://hop-base.com) is a hosted AI API gateway. It serves GPT, +Claude, Gemini and Grok models next to DeepSeek, Zhipu GLM, Moonshot Kimi, +Alibaba Qwen and Doubao behind one base URL with an OpenAI-compatible API. +Docker Agent includes HopBase as a built-in provider in its embedded provider +catalog. + +## Setup + +1. Create an API key in the [HopBase console](https://api.hop-base.com/login). +2. Set the environment variable: + + ```bash + export HOPBASE_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Prefix a HopBase model ID with `hopbase/`: + +```yaml +agents: + root: + model: hopbase/glm-5.3 + description: Assistant using HopBase + instruction: You are a helpful assistant. +``` + +### Named Model + +For more control over parameters: + +```yaml +models: + hopbase_gpt: + provider: hopbase + model: gpt-6.1-sol + max_tokens: 8192 + +agents: + root: + model: hopbase_gpt + description: Assistant using HopBase + instruction: You are a helpful assistant. +``` + +When HopBase is selected automatically from available credentials, the default +model is `glm-5.3`. Model IDs are passed through as supplied. + +## Available Models + +The examples on this page use `glm-5.3`, `gpt-6.1-sol` and `claude-sonnet-5-5`. +The models endpoint returns exactly the model IDs your key can call, so +retrieve the list before choosing another model: + +```bash +curl https://api.hop-base.com/v1/models \ + -H "Authorization: Bearer $HOPBASE_API_KEY" +``` + +Use an ID from the response unchanged as the `model` value. The list can also +contain image, video and speech models, which are not usable for chat. The +[model catalog](https://hop-base.com/models) and the +[HopBase docs](https://hop-base.com/en/docs) describe each model. + +HopBase is absent from Docker Agent's embedded models.dev catalog. Docker Agent +does not import pricing, context limits or attachment capabilities from +HopBase's model list. Attachment detection falls back to text-only, so image +and PDF attachments are dropped, with a warning logged once per model. If you +have verified that your chosen model accepts an attachment type, set +`models..capabilities`; see +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides). +For example, `gpt-6.1-sol` accepts image input and `glm-5.3` does not: + +```yaml +models: + hopbase_vision: + provider: hopbase + model: gpt-6.1-sol + capabilities: + image: true +``` + +## How It Works + +HopBase is an entry in Docker Agent's built-in provider catalog +(`pkg/model/provider/catalog/providers.json`) that uses the existing OpenAI +implementation: + +- **API type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://api.hop-base.com/v1` +- **Token variable:** `HOPBASE_API_KEY` + +As with other multi-model hosts, Docker Agent combines consecutive system +messages for compatibility with models that require a single leading system +message. + +Claude models are callable through this alias like any other model, for +example `hopbase/claude-sonnet-5-5`. + +## Anthropic Messages Endpoint + +The same host also exposes an Anthropic Messages-compatible endpoint at +`https://api.hop-base.com` (no `/v1`). To send Claude requests in the Messages +format instead of Chat Completions, define a +[named provider](../custom/index.md) that reuses the same key: + +```yaml +providers: + hopbase_messages: + provider: anthropic + base_url: https://api.hop-base.com + token_key: HOPBASE_API_KEY + +models: + hopbase_claude: + provider: hopbase_messages + model: claude-sonnet-5-5 + +agents: + root: + model: hopbase_claude + description: Assistant using Claude through HopBase + instruction: You are a helpful assistant. +``` + +A custom Anthropic `base_url` does not inherit Claude API capability, beta or +price metadata; see +[Claude access paths](../anthropic/index.md#claude-access-paths). + +## Example: Code Assistant + +```yaml +agents: + coder: + model: hopbase/glm-5.3 + description: Code assistant using HopBase + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/lunaroute/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/lunaroute/index.md new file mode 100644 index 000000000000..f8b3994749f9 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/lunaroute/index.md @@ -0,0 +1,71 @@ +--- +title: "Lunaroute" +description: "Use Lunaroute models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, lunaroute +weight: 232 +canonical: https://docs.docker.com/ai/docker-agent/providers/lunaroute/ +--- + +_Use Lunaroute models with Docker Agent._ + +## Setup + +Obtain an API key from [Lunaroute](https://lunaroute.com/). Lunaroute keys are +prefixed with `lr_`. Set the environment variable: + +```bash +export LUNAROUTE_API_KEY=lr_your-api-key +``` + +## Usage + +Use the inline model reference: + +```yaml +agents: + root: + model: lunaroute/glm-5.3 + description: Assistant using Lunaroute + instruction: You are a helpful assistant. +``` + +Or configure a named model: + +```yaml +models: + lunaroute_glm: + provider: lunaroute + model: glm-5.3 + +agents: + root: + model: lunaroute_glm + instruction: You are a helpful assistant. +``` + +When Lunaroute is selected automatically from available credentials, the default +model is `glm-5.3`. Model IDs are passed through as supplied. + +## Model discovery and capabilities + +Run `docker agent models --provider lunaroute` with `LUNAROUTE_API_KEY` set to +query the authenticated `https://gw.lunaroute.com/v1/models` endpoint. The +listing also includes the configured default. Discovery is best-effort: if the +endpoint fails, the default remains available. The gateway's listing may contain +models that are not usable for chat. + +Lunaroute is absent from the embedded models.dev catalog. Discovery imports model +IDs, not pricing, context limits, or capabilities; cost tracking and automatic +capability detection therefore lack catalog metadata. Unknown attachment +capabilities fall back to text-only, so image and PDF attachments are dropped +with a warning. If you have verified a model supports them, set a +[capability override](../../configuration/models/index.md#attachment-capability-overrides). + +## How it works + +Direct requests use OpenAI-compatible Chat Completions at +`https://gw.lunaroute.com/v1` with `LUNAROUTE_API_KEY`. When a Docker Agent +models gateway is configured, the built-in alias routes through that gateway +instead; the gateway must support the Lunaroute provider and model. To use +Lunaroute directly, set `bypass_models_gateway: true` on a named model. See +[Gateway Bypass](../../configuration/models/index.md#gateway-bypass). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md index deadbaaea4b3..02eb065db4af 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/nebius/index.md @@ -1,20 +1,20 @@ --- -title: "Nebius" -description: "Use Nebius AI models with Docker Agent." -keywords: docker agent, ai agents, model providers, llm, nebius +title: "Nebius Token Factory" +description: "Use Nebius Token Factory models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, nebius, token factory weight: 190 canonical: https://docs.docker.com/ai/docker-agent/providers/nebius/ --- -_Use Nebius AI models with Docker Agent._ +_Use Nebius Token Factory models with Docker Agent._ ## Overview -Nebius provides AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Nebius as an alias provider. +[Nebius Token Factory](https://tokenfactory.nebius.com/) (formerly Nebius AI Studio) provides hosted AI models through an OpenAI-compatible API. Docker Agent includes built-in support for Token Factory as the `nebius` alias provider. ## Setup -1. Get an API key from [Nebius AI](https://nebius.ai/) +1. Create an API key in the [Nebius Token Factory console](https://tokenfactory.nebius.com/project/api-keys) 2. Set the environment variable: ```bash @@ -30,8 +30,8 @@ The simplest way to use Nebius: ```yaml agents: root: - model: nebius/deepseek-ai/DeepSeek-V3 - description: Assistant using Nebius + model: nebius/MiniMaxAI/MiniMax-M3.1-Flash + description: Assistant using Nebius Token Factory instruction: You are a helpful assistant. ``` @@ -43,33 +43,35 @@ For more control over parameters: models: nebius_model: provider: nebius - model: deepseek-ai/DeepSeek-V3 + model: openai/gpt-oss-120b temperature: 0.7 max_tokens: 8192 agents: root: model: nebius_model - description: Assistant using Nebius + description: Assistant using Nebius Token Factory instruction: You are a helpful assistant. ``` ## Available Models -Nebius hosts various open models. Check the [Nebius documentation](https://nebius.ai/docs) for the current model catalog. +Token Factory's catalog changes as models launch and retire, so this page does not keep a static model table. With `NEBIUS_API_KEY` set, list the Nebius models Docker Agent knows about: -| Model | Description | -| ----------------------------------- | ------------------------------- | -| `deepseek-ai/DeepSeek-V3` | DeepSeek V3 model | -| `Qwen/Qwen2.5-72B-Instruct` | Qwen 2.5 72B instruction-tuned | -| `meta-llama/Llama-3.3-70B-Instruct` | Llama 3.3 70B instruction-tuned | +```bash +docker agent models --provider nebius +``` + +Add `--all` to list them without a key. Recent additions include `MiniMaxAI/MiniMax-M3.1-Flash`, `deepseek-ai/DeepSeek-V4.1-Flash-1017`, `zai-org/GLM-5.3` and `moonshotai/Kimi-K3`. + +The listing comes from the [models.dev](https://models.dev/providers/nebius/) catalog, which can lag behind Token Factory. The [Token Factory console](https://tokenfactory.nebius.com/) is the authoritative list of models available to your project. Model IDs are case-sensitive; copy the full ID, including the vendor prefix. ## How It Works Nebius is implemented as a built-in alias in Docker Agent: - **API Type:** OpenAI-compatible (`openai_chatcompletions`) -- **Base URL:** `https://api.studio.nebius.com/v1` +- **Base URL:** `https://api.tokenfactory.nebius.com/v1` - **Token Variable:** `NEBIUS_API_KEY` ## Example: Code Assistant @@ -77,10 +79,10 @@ Nebius is implemented as a built-in alias in Docker Agent: ```yaml agents: coder: - model: nebius/deepseek-ai/DeepSeek-V3 - description: Code assistant using DeepSeek + model: nebius/moonshotai/Kimi-K3 + description: Code assistant using Nebius Token Factory instruction: | - You are an expert programmer using DeepSeek V3. + You are an expert programmer. Write clean, well-documented code. Follow best practices for the language being used. toolsets: diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/obscurify/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/obscurify/index.md new file mode 100644 index 000000000000..e3c9f0dbe855 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/obscurify/index.md @@ -0,0 +1,120 @@ +--- +title: "Obscurify.ai" +description: "Use Obscurify.ai models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, obscurify +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/providers/obscurify/ +--- + +_Use Obscurify.ai models with Docker Agent._ + +## Overview + +[Obscurify.ai](https://obscurify.ai/?utm_source=docker-agent) is a +privacy-focused provider with an OpenAI-compatible API and 200+ models. +Accounts are a random account number with no email, and prompts and responses +are not stored on its servers. Obscurify.ai is a built-in provider in Docker +Agent's embedded provider catalog. + +The API works on every plan with a positive balance. Frontier models such as +`openai/gpt-5.5` or `anthropic/claude-sonnet-5.5` need a Casual or Pro plan; +see the [model list](https://obscurify.ai/model_cards) for prices. + +## Setup + +1. Create an account at [obscurify.ai](https://obscurify.ai/?utm_source=docker-agent) + and copy your key from the [account page](https://obscurify.ai/account) + ("Show API Key"). +2. Set the environment variable: + + ```bash + export OBSCURIFY_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Prefix an Obscurify.ai model ID with `obscurify/`: + +```yaml +agents: + root: + model: obscurify/deepseek/deepseek-v4-flash + description: Assistant using Obscurify.ai + instruction: You are a helpful assistant. +``` + +Only the first slash separates the provider, so the rest of the model ID +(`deepseek/deepseek-v4-flash`) is sent as is. + +### Named Model + +For more control over parameters: + +```yaml +models: + obscurify_kimi: + provider: obscurify + model: moonshotai/kimi-k2-0905 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: obscurify_kimi + description: Assistant using Obscurify.ai + instruction: You are a helpful assistant. +``` + +## Available Models + +A few of the chat model IDs: + +| Model ID | Context | +| --- | --- | +| `deepseek/deepseek-v4-flash` | 1,048,576 (default) | +| `z-ai/glm-5.3` | 1,048,576 | +| `moonshotai/kimi-k2-0905` | 262,144 | +| `qwen/qwen3-coder` | 262,000 | +| `meta-llama/llama-3.3-70b-instruct` | 131,072 | + +The public [`/v1/models` endpoint](https://obscurify.ai/v1/models) lists every +current ID with its context length and pricing; no key is needed to read it. + +Obscurify.ai is not in the models.dev catalog, so Docker Agent has no +catalog-derived pricing or context limits for these models. Attachment +capabilities fall back to text-only; image and PDF attachments are dropped, +with a warning logged once per model. If you know your model accepts a given +attachment type, set `models..capabilities` to override detection. See +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides). + +## How It Works + +Obscurify.ai is an entry in Docker Agent's built-in provider catalog +(`pkg/model/provider/catalog/providers.json`) that uses the existing OpenAI +implementation: + +- **API Type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://obscurify.ai/v1` +- **Token Variable:** `OBSCURIFY_API_KEY` + +Many of its models are open-weight models whose chat templates can reject +several leading system messages, so Docker Agent merges its per-source system +messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: obscurify/qwen/qwen3-coder + description: Code assistant using Obscurify.ai + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md index ccfb838f661b..11eb22dabd80 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/openai/index.md @@ -96,7 +96,7 @@ models: native_tool_search: true ``` -Deferred tools are declared with `defer_loading: true` alongside a server-executed `tool_search` tool on Responses API requests. Strictly opt-in: only `openai` models that support deferred tools (gpt-5.4 and later) qualify; the option is ignored elsewhere (`chatgpt`, OpenAI-compatible endpoints including a custom `base_url`, Chat Completions requests) and the legacy behaviour is kept. +Deferred tools are declared with `defer_loading: true` alongside a server-executed `tool_search` tool on Responses API requests. Strictly opt-in: only `openai` models that support deferred tools (gpt-5.4 and later) qualify; the option is ignored elsewhere (`chatgpt`, OpenAI-compatible endpoints including a custom `base_url` or `OPENAI_BASE_URL`, Chat Completions requests) and the legacy behaviour is kept. See [`examples/deferred_native_tool_search.yaml`](https://github.com/docker/docker-agent/blob/main/examples/deferred_native_tool_search.yaml) for a complete example. @@ -176,7 +176,7 @@ models: - Only works with Responses API models: `gpt-4.1+`, `o1`, `o3`, `o4`, `gpt-5` - NOT compatible with the `--models-gateway` flag (automatically falls back to SSE when a gateway is configured) -- Requires `OPENAI_API_KEY` environment variable +- Uses the configured credential source or `token_key`; defaults to `OPENAI_API_KEY` when neither is configured ### Example @@ -218,9 +218,9 @@ generated values. This option does not apply to the Responses API. ## Reasoning State Preservation -Reasoning replay is opt-in, so existing configurations keep their request and -session-storage behavior. Enable it for first-party OpenAI Responses sessions, -including the `chatgpt` provider: +Responses reasoning replay is opt-in, so existing configurations keep their +request and session-storage behavior. Enable it for first-party OpenAI +Responses sessions, including the `chatgpt` provider: ```yaml provider_opts: @@ -247,3 +247,9 @@ WebSocket requests replay the full history without also chaining it through `pre See [OpenAI's reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) and [cache diagnostics guide](https://developers.openai.com/api/docs/guides/prompt-caching/diagnostics). + +`preserve_reasoning` is unrelated to `provider_opts.replay_reasoning`, which +replays plain reasoning text as a `reasoning_content` field on Chat +Completions requests to OpenAI-compatible servers. It does not apply to the +Responses API, and `preserve_reasoning` does not apply to Chat Completions. +See [Replaying reasoning on later turns](../custom/index.md#replaying-reasoning-on-later-turns). diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/opper/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/opper/index.md new file mode 100644 index 000000000000..716d940b4909 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/opper/index.md @@ -0,0 +1,69 @@ +--- +title: "Opper" +description: "Use Opper models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, opper +weight: 225 +canonical: https://docs.docker.com/ai/docker-agent/providers/opper/ +--- + +_Use Opper models with Docker Agent._ + +## Overview + +[Opper](https://opper.ai) is an EU-hosted AI gateway that serves models from +many providers behind one OpenAI-compatible endpoint, with one API key. +Docker Agent includes built-in support for Opper as an alias provider. + +## Setup + +1. Create an API key at [platform.opper.ai](https://platform.opper.ai). +2. Set the environment variable: + + ```bash + export OPPER_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +```yaml +agents: + root: + model: opper/claude-sonnet-4-6 + description: Assistant using Opper + instruction: You are a helpful assistant. +``` + +### Named Model + +```yaml +models: + opper_model: + provider: opper + model: claude-sonnet-4-6 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: opper_model + description: Assistant using Opper + instruction: You are a helpful assistant. +``` + +## Available Models + +Opper model IDs come in two forms. A bare pool name such as +`claude-sonnet-4-6` or `gpt-5.4-mini` lets Opper pick a provider for each +request. A `provider/model` ID such as `anthropic/claude-sonnet-4-6` pins one +route. List the model IDs your key can call with: + +```bash +curl https://api.opper.ai/v3/compat/models \ + -H "Authorization: Bearer $OPPER_API_KEY" +``` + +The public catalogue is also available without a key at +`https://api.opper.ai/v3/models`. Docker Agent's default for Opper is +`claude-sonnet-4-6`. diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/orcarouter/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/orcarouter/index.md new file mode 100644 index 000000000000..cee70edf60af --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/orcarouter/index.md @@ -0,0 +1,88 @@ +--- +title: "OrcaRouter" +description: "Use OrcaRouter models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, orcarouter +weight: 231 +canonical: https://docs.docker.com/ai/docker-agent/providers/orcarouter/ +--- + +_Use OrcaRouter models with Docker Agent._ + +## Overview + +[OrcaRouter](https://www.orcarouter.ai) provides access to models from many providers through an OpenAI-compatible API. Docker Agent includes built-in support for OrcaRouter as an alias provider. + +## Setup + +1. Get an API key from [OrcaRouter](https://www.orcarouter.ai) +2. Set the environment variable: + + ```bash + $ export ORCAROUTER_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Set the provider and model in the agent definition: + +```yaml +agents: + root: + model: orcarouter/orcarouter/auto + description: Assistant using OrcaRouter + instruction: You are a helpful assistant. +``` + +`orcarouter/auto` is OrcaRouter's adaptive router. You can also reference a model served by the gateway with its upstream provider prefix, such as `orcarouter/anthropic/claude-sonnet-4.5` or `orcarouter/deepseek/deepseek-v4-pro`. Docker Agent splits only the first slash, so the full upstream model ID is preserved. + +### Named Model + +For more control over parameters: + +```yaml +models: + orca_router: + provider: orcarouter + model: orcarouter/auto + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: orca_router + description: Assistant using OrcaRouter + instruction: You are a helpful assistant. +``` + +## Pricing and Model Metadata + +Docker Agent fetches OrcaRouter model metadata from [models.dev](https://models.dev/), including pricing per 1M input/output tokens, cache pricing when available, context limits, output limits, and modalities. This powers cost tracking and the model picker in the same way as other first-class providers. + +If models.dev is unavailable, Docker Agent falls back to its embedded catalog snapshot. + +## How It Works + +OrcaRouter is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible (`openai`) +- **Base URL:** `https://api.orcarouter.ai/v1` +- **Token Variable:** `ORCAROUTER_API_KEY` + +## Example: Code Assistant + +```yaml +agents: + coder: + model: orcarouter/orcarouter/auto + description: Code assistant using OrcaRouter + instruction: | + You are an expert programmer. + Write clean, maintainable code. + Explain trade-offs when helpful. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md index 2f6e18ea85c9..9bc67ea172fc 100644 --- a/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/providers/overview/index.md @@ -67,8 +67,15 @@ Use this table to find a built-in provider's config key and authentication metho | Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_GATEWAY_ID` | | Requesty | `requesty` | `REQUESTY_API_KEY` | | OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | +| Opper | `opper` | `OPPER_API_KEY` | | API Route | `api-route` | `API_ROUTE_API_KEY` | +| Lunaroute | [`lunaroute`](../lunaroute/index.md) | `LUNAROUTE_API_KEY` | +| OrcaRouter | `orcarouter` | `ORCAROUTER_API_KEY` | | Atlas Cloud | [`atlascloud`](../atlascloud/index.md) | `ATLASCLOUD_API_KEY` | +| Runcrate | [`runcrate`](../runcrate/index.md) | `RUNCRATE_API_KEY` | +| CloudGPU | [`cloudgpu`](../cloudgpu/index.md) | `CLOUDGPU_API_KEY` | +| Obscurify.ai | [`obscurify`](../obscurify/index.md) | `OBSCURIFY_API_KEY` | +| HopBase | [`hopbase`](../hopbase/index.md) | `HOPBASE_API_KEY` | | Azure OpenAI | `azure` | `AZURE_API_KEY` + `base_url` (override the key with `token_key`) | | [Ollama](../local/index.md) | `ollama` | None (local; optional `base_url`) | | GitHub Copilot | `github-copilot` | `GITHUB_TOKEN` or `GH_TOKEN` (PAT with `copilot` scope) | diff --git a/_vendor/github.com/docker/docker-agent/docs/providers/runcrate/index.md b/_vendor/github.com/docker/docker-agent/docs/providers/runcrate/index.md new file mode 100644 index 000000000000..1431dafd7fa2 --- /dev/null +++ b/_vendor/github.com/docker/docker-agent/docs/providers/runcrate/index.md @@ -0,0 +1,120 @@ +--- +title: "Runcrate" +description: "Use Runcrate models with Docker Agent." +keywords: docker agent, ai agents, model providers, llm, runcrate +weight: 25 +canonical: https://docs.docker.com/ai/docker-agent/providers/runcrate/ +--- + +_Use Runcrate models with Docker Agent._ + +## Overview + +[Runcrate](https://www.runcrate.ai/?utm_source=docker-agent&utm_medium=directory&utm_campaign=gpu_pricing) +is a GPU cloud that also serves open models (DeepSeek, GLM, Qwen, gpt-oss and +others) through an OpenAI-compatible API. Docker Agent includes built-in +support for Runcrate as an alias provider. + +Some open models come with a limited free allowance for GitHub accounts at +least 30 days old. Once the allowance is used up, or when free capacity is +busy, requests from a workspace with credit are billed to that credit. See +[Runcrate's free inference terms](https://www.runcrate.ai/inference/free?utm_source=docker-agent&utm_medium=directory&utm_campaign=gpu_pricing) +for the current models, limits and prices. + +## Setup + +1. [Create a Runcrate API key](https://www.runcrate.ai/dashboard/api-keys) +2. Set the environment variable: + + ```bash + export RUNCRATE_API_KEY=your-api-key + ``` + +## Usage + +### Inline Syntax + +Use a Runcrate model by prefixing its model ID with `runcrate/`: + +```yaml +agents: + root: + model: runcrate/deepseek-ai/DeepSeek-V4.1-Flash + description: Assistant using Runcrate + instruction: You are a helpful assistant. +``` + +Docker Agent splits only the first slash, so model IDs that include an +organization prefix are preserved. + +### Named Model + +For more control over parameters: + +```yaml +models: + runcrate_glm: + provider: runcrate + model: zai-org/GLM-5.3 + temperature: 0.7 + max_tokens: 8192 + +agents: + root: + model: runcrate_glm + description: Assistant using Runcrate + instruction: You are a helpful assistant. +``` + +## Available Models + +Some chat model IDs Runcrate serves: + +| Model ID | Model | +| --- | --- | +| `deepseek-ai/DeepSeek-V4.1-Flash` | DeepSeek V4.1 Flash (default) | +| `zai-org/GLM-5.3` | GLM-5.3 | +| `Qwen/Qwen3.8-Flash` | Qwen3.8 Flash | +| `openai/gpt-oss-120b` | gpt-oss 120B | + +Model IDs are case-sensitive. The live [`/v1/models` endpoint](https://api.runcrate.ai/v1/models) +lists current IDs; it also lists image, video, speech and embedding models, +which this chat provider does not use. + +Runcrate is not in the models.dev catalog. Docker Agent does not import metadata +from Runcrate's model list, so it has no catalog-derived pricing or context limits +for these models. Attachment capabilities conservatively fall back to text-only; +image and PDF attachments are dropped, with a warning logged once per model. + +If you have verified that your chosen model accepts a particular attachment +type, set `models..capabilities` to override detection. See +[Attachment Capability Overrides](../../configuration/models/index.md#attachment-capability-overrides) +for all supported flags. + +## How It Works + +Runcrate is implemented as a built-in alias in Docker Agent: + +- **API Type:** OpenAI-compatible Chat Completions (`openai_chatcompletions`) +- **Base URL:** `https://api.runcrate.ai/v1` +- **Token Variable:** `RUNCRATE_API_KEY` + +Because Runcrate serves open-weight models whose chat templates can reject +multiple leading system messages, Docker Agent coalesces its per-source system +messages into one. + +## Example: Code Assistant + +```yaml +agents: + coder: + model: runcrate/deepseek-ai/DeepSeek-V4.1-Flash + description: Code assistant using Runcrate + instruction: | + You are an expert programmer. + Write clean code and follow language best practices. + toolsets: + - type: filesystem + - type: shell + - type: think +``` diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md index 7fd09a30fd79..c6a4c76db956 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/api/index.md @@ -69,9 +69,13 @@ The `api` toolset accepts the following toolset-level fields in addition to the ## HTTP Methods +Only `method: GET` carries the read-only hint. Other methods are classified as `unknown`: absent overriding permissions or hooks, Restricted mode denies them, while Balanced and the legacy/default mode require confirmation. For trusted unattended POST calls, use a narrowly scoped [allow rule](../../configuration/permissions/index.md). Non-GET tools are excluded when the agent or toolset sets `readonly: true`. + +Read-only classification is not a confidentiality guarantee: GET parameters are sent to the endpoint in the URL. Use trusted endpoints and appropriate data-access and egress controls. + ### GET Requests -For GET requests, parameters are interpolated into the URL: +For GET requests, parameters are interpolated into the URL. Declare GET arguments as strings, including numeric query parameters; the GET handler decodes arguments into a string map: ```yaml toolsets: @@ -86,9 +90,9 @@ toolsets: type: string description: Search query limit: - type: integer - description: Maximum results (default 10) - required: ["query"] + type: string + description: Maximum number of results + required: ["query", "limit"] ``` ### POST Requests 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 6e8840313c9f..73cfb06b276f 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 @@ -30,6 +30,7 @@ The background agents tool lets an orchestrator dispatch work to sub-agents conc | `agent` | string | ✓ | Name of the sub-agent to run. Must be listed under the caller's `sub_agents`. | | `task` | string | ✓ | Clear, concise description of the task the sub-agent should achieve. | | `expected_output` | string | ✗ | Optional description of the result format the caller expects. | +| `worktree` | bool | ✗ | Create an isolated Git checkout and branch for this task. Default `false`. | `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). @@ -66,7 +67,43 @@ A timeout returns available results and live output without stopping unfinished A stopped task can have `done: false` while its execution is still shutting down. The join waits for execution to exit, not just for the stop request to be acknowledged. Unknown or pruned IDs are reported individually as `status: "not_found"`, leave `all_done` false, and make the result a tool error; other requested tasks are still joined. Completed tasks may be pruned when the task-history limit is reached, so collect their results before dispatching many more tasks. -This is a synchronization tool, not workspace isolation: concurrent coding agents still need separate workspaces to avoid conflicting edits. +## Isolated coding tasks + +Set `worktree: true` to run concurrent coding tasks without sharing a checkout: + +```json +{"agent": "coder", "task": "Implement the backend change and commit it", "worktree": true} +``` + +This works when the calling session is in a Git repository **or an existing Git worktree**. Each task gets a fresh branch from that checkout's current `HEAD`, not the repository's default branch. Uncommitted and untracked files are **not copied**, except for gitignored files selected by the source repository's [`.worktreeinclude`](../../features/cli/index.md#copy-ignored-files-into-worktrees); commit shared starting changes before dispatching tasks. Copied ignored files can be lost when a worktree is removed and do not propagate back to the source. A missing repository or a failed setup is reported as a failed task. + +The child gets fresh toolsets and hooks rooted in its checkout; the parent's tools and process working directory are unchanged. Blocking delegations (`transfer_task` and forked skills) inherit the isolated workspace. Nested background dispatch is rejected: start parallel worktree tasks from the top-level orchestrator. Model clients are reused, and tasks share the parent's run budget and inherit its safety policy and permissions. Configured `worktree_create` hooks run before tools and skills are loaded, so setup-created ignore files and directories take effect. + +`list_background_agents` and `view_background_agent` report the checkout path, branch, and base commit once creation finishes. `wait_background_agents` includes them as `worktree`, `branch`, and `base_commit`, independently of truncated output and whether the task succeeded. + +### Review and merge at the top level + +1. Start all independent tasks with `worktree: true`. Describe files relative to the repository. The child is instructed to translate source-checkout paths to its own checkout; the child is instructed to treat attached files as read-only inputs at their original paths. +2. Have each child commit its changes on its own branch, following the project's signing policy. No commits are made automatically. +3. Wait for all tasks, check each status, and review each branch's diff. +4. Merge branches **one at a time** from the parent checkout, resolve conflicts, and run the combined tests. For example: + + ```sh + git diff HEAD...worktree-agent- + git merge --no-edit worktree-agent- + ``` + +5. After integrating the work, remove the now-unneeded checkout and branch: + + ```sh + git worktree remove /path/reported/by/the/task + git branch -d worktree-agent- + ``` + +Worktrees and branches are **retained**, including after failure, cancellation, and runtime shutdown. Uncommitted changes cannot be merged with `git merge`; inspect and commit them first. Never remove a task's checkout while it or its descendants are still running. Save the reported paths before task history is pruned. + +> [!NOTE] +> Worktrees isolate checkouts, not permissions or arbitrary external side effects. Explicit absolute tool/hook directories, external services, and shared Git configuration remain shared. External harness agents do not yet support `worktree: true`; their drivers currently inherit the process directory. Programmatic agents need a working-directory factory; configuration-loaded native agents supply one automatically. Adding tools after loading invalidates that factory unless the host supplies a replacement. Shared plans, shared todos, and default persistent memory remain shared intentionally. RAG indexes are scoped to the workspace unless an explicit database path selects shared storage. ## Configuration diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md index 520bb1f87d47..b9cf579674ed 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/file/index.md @@ -47,5 +47,5 @@ toolsets: - ".env" post_edit: - path: "*.go" - cmd: "gofmt -w ${file}" + cmd: 'gofmt -w "${file}"' ``` 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 e80aff67c352..87cfccae1256 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 @@ -119,7 +119,7 @@ restriction visible to the model so it can adjust its plan. ### Post-Edit Hooks -Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (`write_file` and `edit_file`). Use `${file}` as a placeholder for the absolute path of the edited file. +Automatically run formatting, linting, or other commands after the agent edits a file. The command fires once per file after each edit operation (`write_file` and `edit_file`). The command receives the absolute path in the `file` environment variable. With a POSIX shell, use `"${file}"` to preserve spaces and shell metacharacters in the path; use the corresponding environment-variable syntax for other shells. ```yaml toolsets: @@ -127,17 +127,17 @@ toolsets: ignore_vcs: false post_edit: - path: "*.go" - cmd: "gofmt -w ${file}" + cmd: 'gofmt -w "${file}"' - path: "*.ts" - cmd: "prettier --write ${file}" + cmd: 'prettier --write "${file}"' - path: "src/*/*.py" - cmd: "black ${file}" + 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 inside `src/`. | -| `cmd` | string | Shell command to run. `${file}` expands to the absolute path of the just-edited file. | +| `cmd` | string | Shell command to run. The `file` environment variable contains the absolute path of the just-edited file; quote its expansion using your shell's syntax. | Post-edit commands run with the same working directory as the agent. If a command exits non-zero, the tool reports that the write or edit succeeded but the post-edit command failed. The edit is not rolled back. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md index 97adbadeff5b..15c8a36a4f54 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/lsp/index.md @@ -63,7 +63,7 @@ agents: | ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- | | `command` | string | ✓ | LSP server executable command | | `args` | array | ✗ | Command-line arguments for the LSP server | -| `env` | object | ✗ | Environment variables for the LSP process | +| `env` | object | ✗ | Environment variables for the LSP process. When a key is also set in the host environment, the value from `env` wins. | | `file_types` | array | ✗ | File extensions this LSP handles (e.g., `[".go", ".mod"]`) | | `working_dir` | string | ✗ | Working directory for the LSP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. | | `version` | string | ✗ | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary | diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md index 408d4696729b..6014702e2c50 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/mcp/index.md @@ -68,7 +68,7 @@ toolsets: | `command` | string | Command to execute the MCP server. | | `args` | array | Command arguments. | | `tools` | array | Optional whitelist — only expose these tools. | -| `env` | object | Environment variables (key-value pairs). | +| `env` | object | Environment variables (key-value pairs) for the server process. The process also inherits the host environment; when a key is set in both, the value from `env` wins. | | `working_dir` | string | Working directory for the MCP server process. Relative paths are resolved against the agent's working directory. Defaults to the agent's working directory when omitted. Supports `${env.VAR}` (canonical), plus `~` and shell-style `$VAR`/`${VAR}` expansion ([details](../../configuration/overview/index.md#variable-expansion-in-config-fields)). | | `instruction` | string | Custom instructions injected into the agent's context. | | `version` | string | Package reference for [auto-installing](../../configuration/tools/index.md#auto-installing-tools) the command binary. | @@ -101,6 +101,7 @@ toolsets: | `remote.transport_type` | string | `streamable` or `sse`. | | `remote.headers` | object | HTTP headers sent on every request. Values support `${env.VAR}` and `${headers.NAME}` placeholders, resolved per request. See [Remote MCP Servers](../../features/remote-mcp/index.md#configuration) for details. | | `remote.oauth` | object | Explicit OAuth client credentials for servers that don't support DCR. See [Remote MCP Servers](../../features/remote-mcp/index.md#oauth-for-servers-without-dynamic-client-registration). | +| `remote.standalone_sse` | boolean | Open the streamable-HTTP standalone SSE `GET` stream (default `false`). Enable for gateways that send keepalive pings or `notifications/tools/list_changed` and close sessions they cannot reach, such as the sbx MCP gateway. Ignored for `sse`. | | `allow_private_ips` | boolean | Permit remote MCP OAuth helper requests to dial non-public IP addresses. Use only for trusted internal servers. | For a curated list of public remote MCP endpoints (Linear, GitHub, Vercel, Notion, …) and full OAuth configuration details, see [Remote MCP Servers](../../features/remote-mcp/index.md). @@ -109,7 +110,7 @@ When Docker Desktop is running, eligible MCP OAuth discovery, token, and helper ## MCP Prompts -MCP servers can expose **prompts** — named, parameterized templates that the server provides via the `/prompts` endpoint. Docker Agent discovers these at toolset startup and registers them as **slash commands** in the TUI, so you can invoke them directly from the input box. +MCP servers can expose **prompts** — named, parameterized templates that the server provides via the `prompts/list` and `prompts/get` protocol methods. Docker Agent discovers these at toolset startup and registers them as **slash commands** in the TUI, so you can invoke them directly from the input box. ```text # Type / to see available prompts alongside built-in commands @@ -126,7 +127,7 @@ MCP servers can expose **prompts** — named, parameterized templates that the s - When no argument is needed or all required arguments are supplied, the prompt runs immediately. > [!NOTE] -> MCP prompt discovery requires a YAML-declared `mcp` toolset. Prompts from servers activated through the [Docker MCP Catalog](../../tools/mcp-catalog/index.md) (`ref: docker:`) are not currently surfaced. +> MCP prompt discovery requires a YAML-declared `mcp` toolset. Prompts from servers activated through the [Docker MCP Catalog](../../tools/mcp-catalog/index.md) (`type: mcp_catalog`, activated with `enable_remote_mcp_server`) are not currently surfaced. YAML-declared `type: mcp` entries with `ref: docker:` do participate in prompt discovery. ## Embedded Resources @@ -134,7 +135,7 @@ MCP tool results can include embedded resources — images, PDFs, and text files - **Anthropic** — images become `image` blocks in the `tool_result`; PDFs and other documents become `document` blocks. - **OpenAI** — images are forwarded as `input_image` data URIs; PDFs as `input_file` data URIs in the tool result content. -- **OpenAI Chat Completions** (`api_type: openai_chatcompletions`, the default, and OpenAI-compatible providers) — tool messages only accept text, so images (including image documents) are sent as text in the tool message as their data URI or URL. PDFs and other documents are attached in a follow-up user message labeled "Attached content from tool result:". +- **OpenAI Chat Completions** (`api_type: openai_chatcompletions`, selected automatically for models without Responses API support or set explicitly) — tool messages only accept text, so images (including image documents) are sent as text in the tool message as their data URI or URL. PDFs and other documents are attached in a follow-up user message labeled "Attached content from tool result:". - **Bedrock** and **Gemini** — receive equivalent provider-native representations. No configuration is required. When an MCP server returns an embedded resource alongside its text output, the resource is automatically attached and sent to the model on the next turn. This is useful for MCP servers that generate charts, export PDFs, or return binary data as part of their responses. diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md index 53076c4c43ba..b4e1b147f6e5 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/plan/index.md @@ -13,7 +13,7 @@ _Shared persistent scratchpad for multi-agent collaboration._ The plan tool gives agents a shared, persistent scratchpad of named documents. Any agent in a multi-agent config that loads the `plan` toolset can read and write the same plans, and those plans survive across sessions. This makes it straightforward to wire a planner agent that sketches work and one or more executor agents that consume it without any custom tool wiring. -Plans are stored as JSON files in the Docker Agent data directory (`~/.cagent/plans/` by default). Agents that share a process serialize on a single mutex, and every write or delete additionally holds an advisory lock on a sentinel file in the plans directory, so writers in *separate* Docker Agent processes are serialized too: concurrent edits can never silently overwrite each other, and a stale revision always fails with a deterministic version conflict. Writes are atomic (temp file + rename), so a reader never observes partial content. +Plans are stored as JSON files in the Docker Agent data directory (`~/.cagent/plans/` by default). Agents that share a process serialize on a single mutex, and every write or delete additionally holds an advisory lock on a sentinel file in the plans directory, so writers in *separate* Docker Agent processes are serialized too: a stale revision fails with a deterministic version conflict when the caller supplies `last_known_revision`. Without that guard, updates are last-writer-wins. Writes are atomic (temp file + rename), so a reader never observes partial content. ## Configuration diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md index 6563e75390e4..a412f0d3e034 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/rag/index.md @@ -11,6 +11,12 @@ aliases: _Give your agents access to document knowledge bases with background indexing, multiple retrieval strategies, and hybrid search._ +> Relative document and database paths resolve from the agent's working directory +> (or the configuration directory when no working directory is set). Default +> database files are stored under the data directory, scoped by workspace, so +> isolated worktrees do not mix indexed documents. Explicit absolute database +> paths retain their sharing semantics. + ## Overview The `rag` toolset lets agents search through your documents to find relevant information before responding. Knowledge bases are declared once at the top of the config under `rag:` and then referenced from any agent via `type: rag, ref: `. Docker Agent supports: @@ -60,6 +66,12 @@ loaded with different credentials, gets its own index. Background indexing for a shared knowledge base is not attributed to any session. ```yaml +rag: + my_docs: + docs: [./documents] + strategies: + - type: bm25 + agents: researcher: model: anthropic/claude-sonnet-4-5 @@ -288,10 +300,9 @@ already detaches its file watcher. When the 30s budget expires: the tool is available immediately; if it is still running, that turn also proceeds without the tool. -This is a **visible behavior change**: knowledge bases that used to finish -indexing (and thus offer the tool) on the very first turn, within the old -30-second window, now do so on whichever turn happens to land after indexing -completes. If indexing takes under 30s, nothing changes. +Indexing that finishes within the 30-second wait budget can expose the tool on +the current turn. If indexing outlives that budget, the tool becomes available +on a later turn after indexing completes. `indexing_timeout` bounds indexing itself, independent of the 30s wait budget — it exists only so a hung provider connection cannot pin a knowledge @@ -305,6 +316,7 @@ rag: strategies: - type: chunked-embeddings embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 ``` - Default: `30m` when omitted. @@ -353,6 +365,8 @@ If you see persistent `429`, `5xx`, or `408` errors in the logs: docs: [./knowledge-base] strategies: - type: chunked-embeddings + embedding_model: openai/text-embedding-3-small + vector_dimensions: 1536 max_indexing_concurrency: 1 max_embedding_concurrency: 1 ``` @@ -387,7 +401,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | Field | Type | Default | Description | | ------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `docs` | []string | — | Document paths/directories (shared across strategies) | -| `description` | string | — | Human-readable description of this RAG source | +| `tool.description` | string | — | Description of the search tool shown to the model | | `respect_vcs` | boolean | `true` | Respect `.gitignore` files when indexing documents | | `indexing_timeout` | string | `30m` | Cap on a single indexing run, detached from the 30s toolset-start wait budget; `0s` = unbounded. See [Long indexing runs](#long-indexing-runs) | | `strategies` | []object | — | Array of retrieval strategy configurations | @@ -399,7 +413,7 @@ Look for log tags: `[RAG Manager]`, `[Chunked-Embeddings Strategy]`, `[BM25 Stra | --------------------------- | ------ | ------------------- | ------------------------------------------------------------ | | `embedding_model` | string | — | **Required.** Embedding model reference | | `database` | string | — | Path to local SQLite database | -| `vector_dimensions` | int | — | Embedding dimensions (e.g., 1536 for text-embedding-3-small) | +| `vector_dimensions` | int | — | **Required.** Embedding dimensions (e.g., 1536 for text-embedding-3-small) | | `similarity_metric` | string | `cosine_similarity` | Similarity metric | | `threshold` | float | `0.5` | Minimum similarity score (0–1) | | `limit` | int | `5` | Max results from this strategy | diff --git a/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md b/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md index 739892c93750..0e5b34cf3df9 100644 --- a/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md +++ b/_vendor/github.com/docker/docker-agent/docs/tools/user-prompt/index.md @@ -164,7 +164,7 @@ Agent: Deploying to staging... How the prompt appears depends on the interface: - **TUI**: Displays an interactive dialog with appropriate input controls -- **CLI (exec mode)**: Prints the prompt and reads from stdin +- **CLI (exec mode)**: Automatically declines form prompts; the agent must handle the decline without reading an answer from stdin - **API/MCP**: Returns an elicitation request to the client > [!TIP] @@ -183,4 +183,4 @@ The agent should handle all possible actions: > [!WARNING] > **Context Requirement** > -> The user prompt tool requires an elicitation handler to be configured. It works in the TUI and CLI modes but may not be available in all contexts (e.g., some MCP client configurations). +> The user prompt tool requires an elicitation handler. The TUI supports interactive form prompts; API/MCP clients must implement elicitation. Exec mode declines form prompts automatically. Interactive OAuth authorization in exec mode is a separate flow, not support for `user_prompt` forms. diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 73e452612154..84959245e15f 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -4,4 +4,4 @@ # github.com/docker/cli v29.9.3+incompatible # github.com/docker/compose/v5 v5.7.1 # github.com/docker/model-runner v1.1.36 -# github.com/docker/docker-agent v1.152.0 +# github.com/docker/docker-agent v1.161.0 diff --git a/go.mod b/go.mod index 7be09e2dc38d..ea135dc74d8e 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,7 @@ require ( github.com/docker/buildx v0.39.0 github.com/docker/cli v29.9.3+incompatible github.com/docker/compose/v5 v5.7.1 - github.com/docker/docker-agent v1.152.0 + github.com/docker/docker-agent v1.161.0 github.com/docker/model-runner v1.1.36 github.com/moby/buildkit v0.35.0 github.com/moby/moby/api v1.56.1 diff --git a/go.sum b/go.sum index fefaccb04bd4..943cf4f23046 100644 --- a/go.sum +++ b/go.sum @@ -198,6 +198,8 @@ github.com/docker/docker-agent v1.126.0 h1:GjX84SHcvS4Txo7dGjatWhKGFLNpDqKcGAoIs github.com/docker/docker-agent v1.126.0/go.mod h1:K38q6CsnSTHDOrLP46HLGhKwv3i+vjmu33cjmjpkAvg= github.com/docker/docker-agent v1.152.0 h1:inDwSlc963dTjThWXydrbxu4ehz/Yqmh3vd1+8hBhts= github.com/docker/docker-agent v1.152.0/go.mod h1:ZGCPdL/EinADY1IMcLoWXEsAjsDhciRw59ba96xI2FQ= +github.com/docker/docker-agent v1.161.0 h1:RG7KASlt13jX0pPoq1/h0lRGc63VBxwhjMJhMBJq+A8= +github.com/docker/docker-agent v1.161.0/go.mod h1:4K/oyeYLVtgwqidltwM9/9UF/nb1lWG+fhRybxqJFyw= 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=