From c0e72e272d0489822b38c4e94554736827bc87bd Mon Sep 17 00:00:00 2001 From: david-fraley <67079030+david-fraley@users.noreply.github.com> Date: Tue, 5 May 2026 09:00:27 -0400 Subject: [PATCH] docs(docs/ai-coder/agents): correct chat statuses, watch events, auto-archive default, and add attach_file tool (#24828) --- docs/ai-coder/agents/architecture.md | 19 ++++++++++--------- docs/ai-coder/agents/chats-api.md | 21 ++++++++++----------- docs/ai-coder/agents/index.md | 1 + 3 files changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/ai-coder/agents/architecture.md b/docs/ai-coder/agents/architecture.md index 37cbfda95e..4e8c5461ce 100644 --- a/docs/ai-coder/agents/architecture.md +++ b/docs/ai-coder/agents/architecture.md @@ -132,15 +132,16 @@ approach, discussing architecture) never provision or connect to a workspace. These tools execute inside the workspace via the workspace daemon's HTTP API. They traverse the same Tailnet tunnel used by web terminals and IDE connections. -| Tool | What it does | -|------------------|--------------------------------------------------------------------| -| `read_file` | Reads file contents with line-number pagination. | -| `write_file` | Writes content to a file. | -| `edit_files` | Performs atomic search-and-replace edits across one or more files. | -| `execute` | Runs a shell command, waiting for completion up to a timeout. | -| `process_output` | Retrieves output from a tracked process. | -| `process_list` | Lists all tracked processes in the workspace. | -| `process_signal` | Sends a signal (SIGTERM or SIGKILL) to a tracked process. | +| Tool | What it does | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `read_file` | Reads file contents with line-number pagination. | +| `write_file` | Writes content to a file. | +| `edit_files` | Performs atomic search-and-replace edits across one or more files. | +| `execute` | Runs a shell command, waiting for completion up to a timeout. | +| `process_output` | Retrieves output from a tracked process. | +| `process_list` | Lists all tracked processes in the workspace. | +| `process_signal` | Sends a signal (SIGTERM or SIGKILL) to a tracked process. | +| `attach_file` | Attach a workspace file to the current chat so the user can download it directly from the conversation. Use this when the user should receive an artifact such as a screenshot, log, patch, or document. Pass an absolute file path. The file must already exist in the workspace. | ### Platform tools diff --git a/docs/ai-coder/agents/chats-api.md b/docs/ai-coder/agents/chats-api.md index 568b04a7d6..d85a395b33 100644 --- a/docs/ai-coder/agents/chats-api.md +++ b/docs/ai-coder/agents/chats-api.md @@ -226,13 +226,14 @@ indicator without polling. Each event is a JSON object with `kind` and `chat` fields: -| Kind | Description | -|----------------------|----------------------------------| -| `created` | A new chat was created. | -| `status_change` | A chat's status changed. | -| `title_change` | A chat's title was updated. | -| `diff_status_change` | A chat's diff/PR status changed. | -| `deleted` | A chat was deleted. | +| Kind | Description | +|----------------------|--------------------------------------| +| `created` | A new chat was created. | +| `status_change` | A chat's status changed. | +| `title_change` | A chat's title was updated. | +| `diff_status_change` | A chat's diff/PR status changed. | +| `action_required` | A chat is waiting for a tool result. | +| `deleted` | A chat was deleted. | ### List chats @@ -373,8 +374,6 @@ appear in the `files` field on subsequent | `waiting` | Idle. Newly created, finished successfully, or interrupted. | | `pending` | Queued for processing. | | `running` | Agent is actively working. | -| `paused` | Agent is paused (for example, waiting for user input). | -| `completed` | Agent finished and the task is complete. | | `error` | Agent encountered an error. | | `requires_action` | Agent invoked a client-provided tool and needs the result before continuing. | @@ -389,13 +388,13 @@ deployment-admin privileges. Chats whose newest non-deleted message is older than `auto_archive_days` are automatically archived by a background job. Pinned chats and chats belonging to a still-active thread are -exempt. `0` disables the feature; the default is 90. +exempt. `0` disables the feature, which is the default. ```sh # Read curl -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ https://coder.example.com/api/experimental/chats/config/auto-archive-days -# { "auto_archive_days": 90 } +# { "auto_archive_days": 0 } # Update curl -X PUT -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \ diff --git a/docs/ai-coder/agents/index.md b/docs/ai-coder/agents/index.md index fd894c9192..b00b959868 100644 --- a/docs/ai-coder/agents/index.md +++ b/docs/ai-coder/agents/index.md @@ -244,6 +244,7 @@ tasks: | `process_output` | Retrieve output from a background process | | `process_list` | List all tracked processes in the workspace | | `process_signal` | Send a signal (terminate/kill) to a tracked process | +| `attach_file` | Attach a workspace file to the chat as a durable downloadable attachment | | `spawn_agent` (`type=general` or `explore`) | Delegate a task to a sub-agent running in parallel | | `wait_agent` | Wait for a sub-agent to complete and collect its result | | `message_agent` | Send a follow-up message to a running sub-agent |