Commit Graph
52 Commits
Author SHA1 Message Date
Nick Vigilante 7846490770 docs: reconcile H1/label mismatches into front-matter titles (Phase 3) (#28036)
## Summary

**Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the
**124** hand-authored pages whose leading body H1 differed from the
manifest nav label, this promotes the richer body H1 to the front-matter
**page title** and drops the duplicate H1, while keeping the short
manifest **label** as the sidebar entry.

Policy agreed with the docs owner:
- Short sidebar labels win. Duplicate sidebar labels are acceptable.
- Identical **page titles** across two pages are not. On a collision,
rename the non-generated page's title.

## Page-title collisions resolved

Promoting the H1 created 4 page-title collisions; each is disambiguated
by renaming the non-generated / secondary page (sidebar labels left
unchanged):

| page | sidebar label | body H1 | → page title |
|------|---------------|---------|--------------|
| `install/index.md` | Install | Installing Coder | **Install Coder in
your infrastructure** |
| `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder
CLI** |
| `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs |
**JetBrains** |
| `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs |
Web IDEs *(kept — primary user guide)* |
| `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs
| **Web IDEs in templates** |
| `workspace-management.md` | Workspace Management | Workspaces |
**Manage workspaces** *(vs generated `api/workspaces.md`)* |

These titles are the only non-mechanical editorial calls in this PR.

## Deliberately excluded: generated pages

`admin/security/audit-logs.md` and
`admin/setup/configuration-reference.md` are `make gen` outputs
(`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a
hand-added title would be reverted on the next generation. They're
excluded here and need their generators taught to emit front matter
first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the
same issue for three other generated pages; it has been corrected there
too.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Promote = set front-matter `title` to the body H1 (or the
disambiguated title above) and remove that one duplicate H1. No other
body prose is reflowed.
- Every added front-matter block parses as YAML; all files pass `pnpm
check-docs` (markdownlint-cli2 + table formatter): `Summary: 0
error(s)`.
- Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in
`ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into
the retitled pages found no real breakage.


Anchor-change note

Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each
page's effective title from the manifest label to the body H1, so the
rendered H1 **anchor slug changes**. An audit of cross-file
`.md#fragment` links into these pages surfaced no links that break as a
result (the only hits were false positives against a still-present `##
TLS & Reverse Proxy` heading). Same-file fragments are enforced by
markdownlint MD051, which is green.

## Title casing (follow-up, DOCS-742)

A follow-up commit puts the promoted titles into sentence case and
removes leading gerunds (for example, `Managing workspace schedules` →
`Manage workspace schedules`): 57 of the 120 titles changed, the other
63 were already compliant. Proper nouns and branded names (Coder
Validated Architecture, JetBrains, File Browser, Dev Containers,
Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the
Premium license tier, and maturity labels (Beta, Experimental) are
preserved. The four `Nk-users` pages become `Reference architecture: up
to N users` (lowercase, matching the CVA landing page's own usage); the
CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0
error(s)`.

Linear: DOCS-484, DOCS-742

> This PR was created with AI assistance (Coder Agents).
2026-09-08 16:34:00 +00:00
Nick Vigilante bc77c40296 docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary

**Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`). Adds a front-matter `title` to every navigable docs
page whose title can be migrated **mechanically**, with no editorial
judgment.

This is the content step that Phase 1 (renderers prefer front-matter
title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware,
`DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged
and live.

**Rendered no-op.** The renderers already resolve the page title from
the manifest and hide the leading body H1 (Phase 1), so no page changes
visually. This just moves the title into front matter where Fumadocs and
the migrated tooling can read it.

## What's in this batch

Dry-run on `main` (464 navigable pages) splits into:

| category | count | this PR |
|----------|-------|---------|
| already has front-matter title (Reference, from Phase 2 generators) |
196 | skipped (idempotent) |
| **mechanical** — leading body H1 equals the manifest label | 138 | ✅
add front-matter `title`, drop the duplicate H1 |
| **no body H1** — renders under the manifest label only | 4 | ✅ add
front-matter `title` only |
| **mismatch** — body H1 differs from the manifest label | 126 | ⏭️
deferred (needs an editorial decision, see below) |

142 files changed, all under `docs/`.

## Deliberately out of scope: the 126 mismatches

Pages where the body H1 is richer than the short sidebar label (e.g.
label **Modules** / H1 *Contributing modules*, label **Install** / H1
*Installing Coder*) need a canonical-title decision, not a script. A few
even look like the body H1 is the redundant one (`install/cli.md` and
`install/index.md` both carry the H1 *Installing Coder*). These will
land in follow-up batches **by nav section** once the policy is set, so
each gets real review.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Every added front-matter block parses as YAML and its `title`
round-trips to the manifest label (checked programmatically across all
142 files).
- Every removed line is a leading `# H1` that equalled the manifest
title; no body prose was reflowed. Front matter is correctly hoisted
above pre-existing `<!-- markdownlint-disable -->` comments on the two
pages that had them.
- `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the
changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in
Phase 4); `MD025` is not tripped because the duplicate body H1s are
removed.

```
$ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main)
Linting: 142 file(s)
Summary: 0 error(s)
```

Linear: DOCS-484

> This PR was created with AI assistance (Coder Agents).
2026-08-27 12:34:13 -04:00
Nick VigilanteandIan Evans 47a77016c4 feat(docs/.style): enable Coder.SelectClick, use "select" over "click" (#28599)
Adds a Vale rule enforcing the existing "select, not click" style
guidance: "click" assumes the reader has a mouse, and touch, keyboard,
and assistive-technology users don't click.

`Coder.SelectClick` (warning severity) flags
`click`/`clicks`/`clicked`/`clicking` in prose, exempting:

- Literal mouse-button phrasing (`left-click`, `right-click`,
`middle-click`, `mouse click`, and combinations) — these name an actual
mouse action with no device-agnostic equivalent.
- `one-click`/`single-click` as a compound feature descriptor
("one-click install").

Reworded every existing instructional "click" in `docs/` to the matching
`select` form (`select`/`selects`/`selections`/`selected`/`selecting`)
so the rule ships with a clean baseline, per this repo's Vale-rule
doctrine.

Left alone, deliberately: two generated API reference pages
(`docs/reference/api/enterprise.md`, `schemas.md`) use "click" as an
analytics-event noun, tied to a Go source doc comment and an operation
ID (`report-a-premium-paywall-click`). Fixing those means editing
generated code and an API operation ID, which is out of scope for a
docs-style PR — see the rule's own comments for the reasoning. That
leaves 2 non-zero-baseline findings for this rule.

---
🤖 Built with AI assistance.

---------

Co-authored-by: Ian Evans <5760366+ianjevans@users.noreply.github.com>
2026-08-27 16:24:06 +00:00
Michael Suchacz 35cbca080e feat: allow sharing MCP servers with users and groups (#28593)
## Summary

Adds the missing user-facing half of MCP server config ACLs: admins can
now share an MCP server with individual users and groups from the UI,
backed by a new permission-safe candidate-discovery endpoint.

## Problem

The MCP server config ACL backend already existed (share RBAC action,
hydrated `GET .../acl`, sparse `PATCH .../acl`), but there was no
frontend for it. There was also no way to populate a sharing
autocomplete without the generic organization member/group APIs, which
require `organization_member:read` and `group:read` and would wrongly
couple MCP sharing to the workspace-sharing mode (the same bug fixed for
chat models in #28542).

## Changes

Backend:

- New v2-only `GET
/api/v2/organizations/{organization}/mcp-servers/{mcpserverconfig}/acl/available`
returning `codersdk.ACLAvailable`; because this API is new, it is not
mounted under the experimental compatibility prefix. Gated on
`ActionShare` for the specific server config; performs bounded
org-scoped member/group lookups via `dbauthz.AsSystemRestricted`;
excludes system users; supports `q`, `limit`, `offset`, and `after_id`
with template/chat-model autocomplete semantics.
- Tests cover authorization (404 without share), search, pagination,
system-user exclusion, org scoping, and a share-only custom role under
all three workspace-sharing modes (`none`, `service_accounts`,
`everyone`).

Frontend:

- `shareMCPServerConfig` permission plumbing; the MCP servers list,
details page, and AI settings sidebar now admit share-only users (share
does not require update; share-only users cannot edit the server form).
- Share-only access follows the established permission contract: a
bare-share role manages sharing through the list and ACL endpoints (the
detail route still requires read, update, or delete, matching the
existing enterprise permission-matrix tests), and the disabled-config
gate now also admits the share permission so a sharer with read access
can open a disabled server. Top-level navigation (Admin settings menu
and the /ai/settings index redirect) discovers organization-level MCP
sharers and surfaces permission lookup failures instead of silently
falling back.
- "Share server" action on the MCP server edit page opening a sharing
dialog: hydrated ACL grants render from the `GET .../acl` response,
adds/removals are saved as sparse `PATCH` deltas (`"read"` / `""`).
- Principal autocomplete backed exclusively by the new `/acl/available`
endpoint; the sharing flow never calls the generic org member/group APIs
(Storybook enforces this by rejecting those API spies). A discovery
error surfaces under the autocomplete without hiding existing grants.
- Storybook interaction coverage for the dialog (hydrated rendering,
add/remove, sparse deltas, error/cancel/reopen paths, autocomplete
exclusion and failure) and share-only access to the page/form.

Dogfood UAT ran remotely against a dev instance and passed, including
verifying via the network log that candidate discovery only hits
`/acl/available`. The share-only custom role UI flow could not be
exercised there (no premium license on the dev instance); it is covered
by the backend permission-matrix tests.

> 🤖 This PR was authored by Xum (an AI coding agent) acting on Mike's
behalf.
2026-08-26 19:49:43 +02:00
Nick Vigilante 8afd0020ea docs: fix chat status names and auto-archive behavior claims (#28570)
Two Coder Agents pages describe chat statuses that no longer exist and
attribute auto-archive to the wrong subsystem. The valid status set is
`waiting`, `running`, `error`, `requires_action`, `interrupting`.

- `architecture.md`: a submitted prompt marks the chat `running`, not
`pending`; there is no queued state.
- `chat-auto-archive.md`: the excluded status set is `running`,
`interrupting`, `requires_action`.
- `chat-auto-archive.md`: the job runs in the chatd chat worker on an
hourly tick, not in `dbpurge`.
- `chat-auto-archive.md`: documents the dashboard control at **AI
Settings** > **Coder Agents** > **Lifecycle**, and the 25-title cap on
the digest notification.

API paths on the auto-archive page are intentionally untouched; a
separate PR fixes the `/api/v2` to `/api/experimental` drift.

Linear: DOCS-722 https://linear.app/codercom/issue/DOCS-722

<details><summary>Analysis evidence</summary>

- `codersdk/chats.go`: `ChatStatus` constants are `waiting`, `running`,
`error`, `requires_action`, `interrupting`. No `pending`, `paused`, or
`completed`.
- `coderd/x/chatd/chatstate/transitions.go`:
`sendMessageQueueAndSetStatus` and the send paths apply
`database.ChatStatusRunning`, so a submitted prompt is `running`
immediately. `docs/ai-coder/agents/tasks-to-chats-migration.md` already
states that chats have no separate queued state.
- `coderd/database/queries/chats.sql`,
`GetAutoArchiveInactiveChatCandidates`: `status NOT IN ('running',
'interrupting', 'requires_action')`, plus `archived = false`, `pin_order
= 0`, `parent_chat_id IS NULL`.
- `coderd/x/chatd/auto_archive.go`: `archiveLoop` runs from
`coderd/x/chatd/worker.go` on `opts.ArchiveInterval`;
`coderd/x/chatd/options.go` sets `defaultArchiveInterval = time.Hour`.
Nothing in `dbpurge` performs chat auto-archive.
- `coderd/x/chatd/auto_archive.go`: `chatAutoArchiveDigestMaxChats =
25`; `buildAutoArchiveDigestData` truncates to 25 titles and reports the
remainder as `additional_archived_count`.
- `coderd/x/chatd/options.go`: `defaultArchiveBatchSize = int32(1000)`,
so the existing "up to 1,000 root chats" claim stands.
- `site/src/pages/AISettingsPage/LifecyclePage/LifecyclePageView.tsx`
mounts `AutoArchiveSettings`;
`site/src/modules/management/AISettingsSidebarView.tsx` places the
Lifecycle sub-nav item under Coder Agents.

Validation: `pnpm run format-docs` (no changes) and `pnpm run lint-docs`
(0 errors).

</details>

Generated by Coder Agents on behalf of @nickvigilante.
2026-08-26 11:36:36 -04:00
Michael Suchacz 351bb14032 feat: mount chat API routes under /api/v2 (#28496)
## Stack context

This is the base of a 3-PR stack promoting the chat API from
`/api/experimental` to `/api/v2`: server compatibility mounts (this PR),
codersdk promotion (#28497), and frontend path updates (#28498).

## Summary

Double-mount the stable chat and MCP handlers under `/api/v2` while
retaining the existing experimental routes for the one-release
compatibility window decided in CODAGT-921. CODAGT-922 tracks removing
the compatibility mounts.

The shared route builders preserve existing authentication and
middleware behavior. Experiment-gated, debug, tombstone, and legacy
default-organization model routes remain experimental-only. Signed file
URLs, external OAuth callback URLs, and mixed-version replica relays
also remain on the experimental prefix during the transition.

Update Swagger and the generated API reference for the promoted routes,
including the workspace lookup and a runnable raw-body chat file upload
example. Retain internal endpoints outside the published reference,
share chat-file rate limits across both prefixes, enable CORS for the v2
MCP routes, and cover dual mounts plus exclusions with compatibility
tests. Remote dogfood UAT passed for the promoted chat, model, MCP, and
file flows.

> [!NOTE]
> Xum acted on Mike's behalf in this pull request.
<!-- xum-attribution: model=claude-fable-5 thinking=high -->
2026-08-26 16:17:06 +02:00
Nick Vigilante ce59a86a81 docs: fix Coder Agents tool tables, search filters, attachments, template ranking (#28575)
Corrects four independent factual errors in the Coder Agents
documentation, each verified against the current implementation.

- **Missing tools in the tool tables.** `stop_workspace` was absent from
the built-in tool table in `docs/ai-coder/agents/index.md` and the
platform tool table in `docs/ai-coder/agents/architecture.md`, and from
the root-chat-only tool list. `find_tools` was undocumented entirely;
both docs now list it with its `mcp-tool-search` experiment gating.
- **Missing `source:` search filter.**
`docs/ai-coder/agents/chat-search-syntax.md` documented every chat
filter except `source:`, while also stating that unrecognized keys
return HTTP 400. Adds the filter row and an example.
- **Attachments described as images only.** The attachments section
claimed PNG, JPEG, GIF, and WebP up to 10 MB. The upload allowlist also
accepts plain text, Markdown, CSV, JSON, and PDF; the cap is 10 MiB per
upload with at most 50 attachments per conversation, and Anthropic
models cap inline images at 5 MiB. Also notes that providers differ in
accepted file types and that rejected parts are downgraded to text.
- **Template ranking described as popularity sort.**
`docs/ai-coder/agents/platform-controls/template-optimization.md` said
templates are sorted by active developer count. `list_templates` ranks
by query relevance tiers first, then by an affinity score that weights
the user's own recent usage far above organization popularity. Wording
now matches `docs/ai-coder/agents/tools/index.md`, which already
documents the formula, and links to it.

Linear: DOCS-716 https://linear.app/codercom/issue/DOCS-716

<details><summary>Analysis evidence</summary>

| Claim | Source |
|-------|--------|
| `stop_workspace` is a root-chat platform tool registered alongside
`create_workspace` and `start_workspace` |
`coderd/x/chatd/chattool/stopworkspace.go`; registration in
`coderd/x/chatd/chatd.go` (`chattool.StopWorkspace`), root-only gate in
`builtinPlanToolAllowed`, disabled for explore sub-agents in
`allowedExploreToolNames` |
| `find_tools` requires the `mcp-tool-search` experiment and deferrable
MCP candidates | `coderd/x/chatd/chattool/findtools.go`;
`decideMCPToolSearch` in `coderd/x/chatd/mcp_tool_search.go` returns
false without `codersdk.ExperimentMCPToolSearch` or with no candidates;
wired in `coderd/x/chatd/generation_preparer.go` |
| `source:` accepts `created_by_me` and `shared_with_me`; passing both
returns owned plus shared; default is owned only |
`coderd/searchquery/search.go` (`Chats`): filter defaults to `OwnedOnly:
true`; the `source` parser rejects any other value, and both values
together set `OwnedOnly` and `SharedOnly`. The literal value `all`
appears in the doc comment but is not accepted by the parser, so it is
not documented. |
| Attachment allowlist, size caps, and per-conversation limit |
`codersdk/chats.go`: `AllChatAttachmentMediaTypes` covers
`application/json`, `application/pdf`, `image/gif`, `image/jpeg`,
`image/png`, `image/webp`, `text/csv`, `text/markdown`, `text/plain`;
`MaxChatFileSizeBytes = 10 * 1024 * 1024`; `MaxChatFileIDs = 50`;
`AnthropicInlineImageCapBytes = 5 * 1024 * 1024` |
| Anthropic and Bedrock share the inline image cap; rejected file parts
are downgraded to text | `coderd/x/chatd/chatprovider/chatprovider.go`:
`InlineImageCapBytes` and `Model.AcceptsFilePartMediaType` |
| Template ranking is relevance tiers then a composite affinity score |
`coderd/x/chatd/chattool/listtemplates.go`: `rankTemplates` sorts by
query score first; `computeAffinityScore` adds recency-decayed personal
usage at `listTemplatesPersonalWeight = 10.0` to `ln(1 +
active_developers)` at `listTemplatesOrgWeight = 1.0` |

Note: `MaxChatFileIDs` is enforced per chat, not per message
(`coderd/exp_chats.go`: "A chat can reference at most %d attachments"),
so the docs say per conversation.

Validation: `pnpm run format-docs` and `pnpm run lint-docs` both pass (0
errors). The formatter widened the touched tables, which accounts for
the reformatted rows in the diff.

</details>

Generated by Coder Agents on behalf of @nickvigilante.
2026-08-25 15:13:21 -04:00
Nick Vigilante b146e6f262 docs: align Coder Agents docs with GA framing and licensing terms (#28571)
Removes early-access-program framing from the Coder Agents docs, drops a
stale `early access` manifest tag, and standardizes the licensing
wording on "Premium license with the Agent Hours entitlement".

- `docs/ai-coder/agents/getting-started.md`: replaces the "collaborative
evaluation between your team and Coder" and customer-specific Slack
channel feedback path with GitHub issues plus normal Coder support
channels, and rewrites the remaining evaluation-period wording to GA
tone. Rollout guidance (pilot group, cost planning, concurrency) is
kept.
- `docs/manifest.json`: removes `"state": ["early access"]` from
`ai-coder/agents/platform-controls/chat-debug-logging.md`, which is not
experiment-gated.
- Licensing terminology aligned across `getting-started.md`,
`licensing-usage.md`, and `platform-controls/index.md`.

No changes to `docs/reference/api/**` and no API path changes.

<details><summary>Analysis evidence</summary>

**Manifest state tag decisions (all `ai-coder/agents` pages)**

| Page | Tag before | Tag after | Why |
|------|-----------|-----------|-----|
| `platform-controls/chat-debug-logging.md` | `["early access"]` | none
| Routes at `coderd/coderd.go` (`GET`/`PUT /debug-logging`, `GET`/`PUT
/user-debug-logging`) sit outside any `RequireExperimentWithDevBypass`
group, there is no matching experiment in the `codersdk.Experiment`
list, and the page body already states the feature is not
experiment-gated. |
| `platform-controls/advisor.md` | `["early access"]` | unchanged |
Gated by `codersdk.ExperimentChatAdvisor` (`chat-advisor`); routes
wrapped in `RequireExperimentWithDevBypass`. |
| `platform-controls/virtual-desktop.md` | `["early access"]` |
unchanged | Gated by `codersdk.ExperimentChatVirtualDesktop`
(`chat-virtual-desktop`); routes wrapped in
`RequireExperimentWithDevBypass`. |
| `platform-controls/spend-management.md` | `["premium"]` | unchanged |
`premium` is a licensing tag, not a maturity tag, and the page states
budget endpoints require a license that includes AI Gateway. Flagging
for awareness rather than changing it. |
| All other `ai-coder/agents` pages | none | none | No maturity tags to
review. |

**Licensing mechanics**

`enterprise/coderd/license/license.go` decodes
`agent_runtime_hours_allocation`, `agent_runtime_hours_limit_soft`, and
`agent_runtime_hours_limit_hard` into
`codersdk.FeatureAgentRuntimeHours` on Premium licenses.
`enterprise/coderd/x/chatd/agentadmission.go` lifts the concurrency cap
only when that feature is enabled and usage is below the hard limit. So
the entitlement, not the license tier alone, is what removes the cap.
Wording is now "Premium license with the Agent Hours entitlement".

`licensing-usage.md` keeps "Agent Time" as the name of the measured
usage metric (matching `runtime_ms` reporting) and now says explicitly
that Agent Time draws down the Agent Hours entitlement. Renaming the
metric itself was left out of scope; flagging in case the product team
wants one name for both.

**Validation**

`pnpm install --frozen-lockfile`, `pnpm run format-docs` (no table
changes), `pnpm run lint-docs` (499 files, 0 errors).

</details>

Linear: DOCS-718 https://linear.app/codercom/issue/DOCS-718

Generated by Coder Agents on behalf of @nickvigilante.
2026-08-25 13:10:03 -04:00
Nick Vigilante 827c11f43a docs: update Coder Agents admin navigation to AI Settings (#28572)
## Summary

Fixes stale admin navigation on the three Coder Agents platform-controls
pages not covered by #28482: the retention pages pointed at tabs that do
not exist ("Behavior", the old Agents settings "Lifecycle" tab), and
template optimization pointed at the removed **Agents** > **Settings** >
**Manage Agents** navigation.

Breadcrumbs follow the **Admin settings** > **AI** > **Coder Agents**
convention established by #28482.

## Changes

- `docs/ai-coder/agents/platform-controls/chat-retention.md`: replace
the nonexistent **Behavior** tab with **Admin settings** > **AI** >
**Coder Agents** > **Lifecycle**.
- `docs/ai-coder/agents/platform-controls/chat-debug-retention.md`: same
page, same convention, aligned with chat-retention.md.
- `docs/ai-coder/agents/platform-controls/template-optimization.md`:
replace **Agents** > **Settings** > **Manage Agents** > **Templates**
with **Admin settings** > **AI** > **Coder Agents** > **Templates**.

## Scope note

The first revision also fixed `models.md`, `advisor.md`,
`chat-debug-logging.md`, and `platform-controls/index.md`. Those pages
are covered by #28482 with the same corrections, so this PR reverted
them to avoid conflicting edits and adopted that PR's breadcrumb
convention instead.

Linear: DOCS-715 https://linear.app/codercom/issue/DOCS-715

<details><summary>Analysis evidence</summary>

- `site/src/router.tsx` (~735-780):
`/ai/settings/{lifecycle,templates,coder-agents}` are the live routes;
`/agents/settings/{admin pages}` (~833-890) are `Navigate`-only
redirects.
- No "Behavior" tab exists in any router revision;
`RetentionPeriodSettings` and `DebugRetentionSettings` both render in
`LifecyclePageView.tsx`.
- Breadcrumb convention **Admin settings** > **AI** verified against
`AdminSettings.tsx` / `AISettingsSidebarView.tsx` in #28482.

</details>

Generated by Coder Agents on behalf of @nickvigilante.
2026-08-25 12:49:27 -04:00
Ethan 409049d1d8 docs: document org-scoped admin configuration for agents (#28482)
## Summary

Documents the organization scoping of Coder Agents admin configuration,
and corrects the navigation paths, access wording, and default-model
instructions that no longer matched the product. Documentation only, no
product code changes.

Follows #28473, which moved the organization model overrides into an
**Organization settings** section on **Admin settings > AI > Coder
Agents**. #28473 is merged, so this targets `main`.

Closes CODAGT-715

## Changes

- **New page**
`docs/ai-coder/agents/platform-controls/organizations.md`, registered in
`docs/manifest.json`. Covers the deployment/organization scope split,
what an upgrade changes, how an organization without models or MCP
servers behaves, who configures each scope, and how model and MCP server
sharing works.
- **`models.md`**: models are organization-scoped while providers and
their credentials stay deployment-wide. Each organization has one
default model, and the first model added becomes it. Documents the
**Default** badge and the **Set as Coder Agents default model** form
option in place of the star action that no longer exists, and points
model overrides at **Organization settings**.
- **`getting-started.md`**: replaces the Owner-only claim with the
actual access model, adds an organization selection step, and uses the
**Add model** label.
- **`platform-controls/index.md`**: separates deployment-wide controls
from organization-scoped controls, documents personal model overrides
alongside the model configuration section rather than as an enforcement
caveat, and adds `--agents-allowed` plus the `agents-allowed:` search
filter.
- **`platform-controls/advisor.md`** and
**`platform-controls/virtual-desktop.md`**: the Advisor and Virtual
desktop settings are cards in the **Deployment settings** section of the
**Coder Agents** page, not sidebar entries. **Providers** is a sidebar
item, not a tab.
- **`platform-controls/mcp-servers.md`**: slug uniqueness is per
organization, the **Add server** label is correct, and the page is no
longer described as admin-only.
- **`architecture.md`**, **`index.md`**,
**`tasks-to-chats-migration.md`**: organization scope corrections and
organization-scoped model routes.
- Breadcrumbs standardized to **Admin settings > AI > ...**, verified
against `AdminSettings.tsx` and `AISettingsSidebarView.tsx`.

<details>
<summary>Review follow-ups</summary>

The first revision leaked implementation detail into user-facing pages
and contained several claims that did not match the UI. The follow-up
commit removed and corrected the following.

Removed as implementation detail:

- The `chat_model_config` RBAC resource, its actions, and the token
scopes.
- The `available`, `unavailable_reason`, and `unsupported_providers`
response fields, along with the `missing_api_key`, `fetch_failed`, and
`user_api_key_required` values.
- Role and permission tables, ACL storage mechanics, audit internals,
and JSON error bodies on the new organizations page.
- Migration mechanics with no effect on what a user does.

Corrected against the product:

- The star action does not exist. The list shows a **Default** badge and
the add/edit form offers **Set as Coder Agents default model**
(`ModelRow.tsx`, `ModelFormFields.tsx`).
- The first model added to an organization becomes its default
automatically (`coderd/exp_chats.go`). An organization without a stored
default does not fail every chat, so that claim is gone.
- Advisor and Virtual desktop are cards under **Deployment settings**
(`CoderAgentsPageView.tsx`).
- The MCP servers page does not require deployment configuration edit
permission (`AISettingsSidebarView.tsx`).
- Button labels: **Add model** and **Add server**.
- The organization query parameter is `org`, confirmed by
`modelOrganizationSearchParam`.

Left alone deliberately: pre-existing defects outside the introduced
text, including the `/api/v2/chats` route prefixes, create-chat examples
missing `organization_id`, and the pre-existing MCP permissions table.

</details>

## Testing

- `pnpm run format-docs` and `pnpm run lint-docs` pass.
- `make lint/emdash` passes. No emdash or endash added.
- `grep -rn "Defaults & overrides" docs/` returns nothing.
- Every navigation path, button label, and access claim checked against
the corresponding file under `site/src/pages/AISettingsPage/` and
`site/src/modules/management/`.

---

This pull request was generated by Coder Agents on behalf of
@ethanndickson.
2026-08-25 17:24:39 +01:00
Michael SuchaczandEthan Dickson 0ef331fcd0 feat!: scope chat model override settings to organizations (#28442)
Moves chat model override settings from deployment scope to organization
scope, following the org-scoping of chat model configs in #28440.

Depends on #28440 (based on
`ethan/chat-models-availability-consolidation`).

Remote dogfood UAT passed on this change, including multi-organization
scenarios on a licensed deployment with real models.

## Problem

Chat model configs are now owned by organizations, but the override
settings that reference them stayed deployment-wide: admin
subagent/title/compaction overrides in `site_configs`, personal
overrides in `user_configs`, and the advisor model embedded in the
advisor runtime JSON. A single deployment-level override can only point
at one organization's model config, so overrides effectively worked for
the default organization only, and title generation had to soften its
hard-failure contract to tolerate unusable overrides.

## Fix

Admin overrides (general, explore, title generation, compaction,
advisor) and personal overrides (root, general, explore) become
organization-scoped rows in two new typed tables,
`chat_organization_model_overrides` and `chat_user_model_overrides`.
Composite foreign keys on `(organization_id, model_config_id)` make
cross-organization model references unrepresentable. The migration
deletes the legacy serialized `site_configs`/`user_configs` override
keys instead of migrating them; admins and users re-select models in the
new organization-scoped settings.

New endpoints live under
`/api/experimental/organizations/{organization}/chats/model-overrides`
(admin defaults) and
`/api/experimental/organizations/{organization}/members/{user}/chats/model-overrides`
(personal overrides); the legacy deployment-level routes are removed.
chatd resolves overrides via the chat's organization, restoring the
hard-failure contract for configured-but-unusable title generation
overrides. The deployment-level `AllowUsers` switch and advisor runtime
limits stay deployment-scoped.

The Coder Agents settings UI gains a per-organization "Defaults &
overrides" page under AI Settings > Models, and the personal overrides
page gains an organization selector for users in multiple organizations.
Advisor telemetry now reports per-organization override rows.

**BREAKING CHANGE**: Existing deployment-level overrides are dropped,
not migrated. Every organization starts with no overrides after upgrade,
and model selections must be re-applied in the new settings. The legacy
deployment-level override endpoints are removed.

Closes https://linear.app/coder/issue/CODAGT-872

> [!NOTE]
> Xum (AI agent) authored this PR on behalf of @ibetitsmike.

<!-- xum-attribution: model=claude-opus-4-6 thinking=high -->

---------

Co-authored-by: Ethan Dickson <ethan@coder.com>
2026-08-24 11:20:26 +01:00
Michael Suchacz 24b83dc727 feat: add organization picker to MCP server settings pages (#28150)
Adds an organization picker to the MCP server settings pages so
multi-org deployments can manage every organization's MCP servers
through the UI, not just the default organization's. Closes CODAGT-714
(scoped to MCP servers only; model configs stay deployment-wide until
CODAGT-709 lands).

## Stack Context

Top of the CODAGT-711/717/712/806 stack: MCP server configs are
org-scoped with RBAC, audit logging, per-config ACLs, and owner-scoped
user tokens. This layer makes the admin UI org-aware, resolving the
"default org only" limitation documented in the bottom PR.

## Summary

- The MCP servers list and add pages resolve the working organization
from an `org` search param (falling back to the default org), and render
an organization picker built on the existing `OrganizationAutocomplete`.
The picker only appears when more than one organization is visible, so
single-org deployments see no change.
- Selecting an organization rewrites the search param, refetches the
list for that org, and threads through to the add page so creation posts
to the selected organization.
- The update page now loads the server by ID (new organization-scoped
`GET /api/experimental/organizations/{organization}/mcp-servers/{id}`
frontend binding) instead of listing the default org and searching
client-side, so servers from any organization can be edited. Post-save
navigation returns to the owning organization's list via the server's
`organization_id`.
- Removes the now-unused `getDefaultOrganizationId` helper.
- Review hardening: organization display labels are disambiguated with
the unique org name when effective display names collide (picker
options, trigger text, and accessible name). Access is no longer
restricted to deployment admins: the pages, sidebar item, and nav entry
accept org-scoped `mcp_server_config` permissions, the picker lists only
organizations the user can view, content and affordances (add, edit,
delete) are gated on the selected organization's permissions, and
deployment admins keep full access everywhere.

## Testing

Storybook interaction stories cover: picker hidden with one org,
switching orgs refetches and swaps list contents, add posting to the
URL-selected org, add posting after an in-form org switch (asserting
typed form state survives the switch), and update loading by ID.
Red-green verified by breaking the search-param resolution and observing
the new stories fail.

> Mux acted on Mike's behalf for this PR.
2026-08-19 19:46:23 +00:00
Michael Suchacz 7ca7c30f40 feat: add group and user ACLs to MCP server configs (#27944)
Adds group and user ACLs to org-scoped MCP server configs so
organizations can restrict specific MCP servers to subsets of members,
mirroring the template ACL pattern.

## Summary

- Migration adds `group_acl`/`user_acl` JSONB columns (nested `{"<id>":
{"permissions": [...]}}` shape) and seeds every existing config with its
organization's Everyone group read entry (the Everyone group ID equals
the org ID), so member access is unchanged by default. Creation seeds
the same entry.
- The blanket org-member read grant from the base PR is replaced by ACL
evaluation: Rego requires org membership for every ACL grant, and
`GetAuthorizedMCPServerConfigs` compiles ACL-aware SQL filters.
- New `ActionShare` (org admins) gates `GET|PATCH
/api/experimental/organizations/{organization}/mcp-servers/{mcpserverconfig}/acl`
(nested under the organization like the rest of the config surface).
PATCH validates principals against the config's organization, merges
sparse updates under a row lock, stamps `updated_by`/`updated_at`, and
is audited as a Write with `Old` captured before authorization. A config
deleted concurrently between the middleware fetch and the locked
re-fetch is concealed as 404, matching the update and delete handlers.
ACL columns are tracked in the audit table.
- ACL management is available in all editions (no enterprise
entitlement), documented in the MCP servers page. Revoking an ACL does
not retro-strip already-selected configs from existing chats; new
selection is blocked at chat create.
- Force On respects the ACL: the forced set is loaded as the chat owner,
so a `force_on` server whose ACL denies the owner never attaches at
create, send, or generation time.
- No rolling-upgrade machinery: upgrades run in scheduled maintenance
downtime, so the migration only backfills existing rows; the API sets
the Everyone read grant explicitly on every insert.

Stacked on #27943. Part of the MCP org-separation stack.

Closes https://linear.app/codercom/issue/CODAGT-712

UAT: verified on a dogfood instance with two members and a custom group:
Everyone-seed default visibility, group grant with Everyone removal
(non-member loses list/fetch/selection), foreign-principal rejection,
non-admin share denial (audited 403 / concealed 404), user_acl restore,
and audited ACL diffs.

> Mux (AI agent) authored this PR on Mike's behalf.

<!-- mux-attribution: model=claude-fable-5 thinking=high -->
2026-08-19 19:25:18 +00:00
Michael Suchacz f7a0de7a11 fix: harden org-scoped MCP config chat gating, updates, and visibility (#28065)
Hardens the org-scoped MCP server config surface from #27942 with fixes
and regression pins that are independent of the core cutover:

- Keep chats sendable after a selected MCP server is disabled (persisted
selections are exempt from message-time rejection).
- Keep cached MCP selections usable after a background refetch error
(gate the composer on missing data, not `isSuccess`).
- Merge PATCH updates onto the current row so unset fields are not
clobbered.
- Give auditors the full management view of MCP configs their audit logs
reference (site and org auditor roles).
- Regression pins: frozen OAuth2 callback path, cross-org concealment
for item routes, OAuth callback token binding, and disconnect responses
indistinguishable from nonexistent config IDs.
- Storybook: semantic textbox queries in MCP loading stories; docs note
that the MCP settings page needs deployment access.

## Stack context

Part of the MCP org-separation stack (CODAGT-711 org scope -> apidocs ->
hardening -> CODAGT-717 audit -> CODAGT-712 ACLs -> CODAGT-806 token
RBAC). Split out of #27942 to keep the core cutover reviewable; each
change here builds on the org-scoped routes and chat gating introduced
below it.

> Mux (AI agent) authored this PR on Mike's behalf.

<!-- mux-attribution: model=claude-fable-5 thinking=high -->
2026-08-19 18:50:31 +00:00
Michael SuchaczandMathias Fredriksson 443e3b9b80 feat!: org-scope MCP server configs with RBAC (#27942)
Moves `mcp_server_configs` from deployment scope to organization scope
so each organization fully controls the MCP servers its members can use
with Coder Agents.

## Summary

- Migration: adds `organization_id` (NOT NULL, FK) and keeps existing
rows as the default organization's originals with credentials intact.
Other organizations start with no MCP servers and configure their own;
nothing is copied across organizations. Chats outside the default
organization keep any now-cross-organization `mcp_server_ids` entries;
the runtime already ignores IDs that do not resolve in the chat's
organization, so no data rewrite is needed. Slug uniqueness becomes
`(organization_id, slug)`.
- RBAC: new org-scoped `ResourceMCPServerConfig` with regosql converter
and `GetAuthorizedMCPServerConfigs`; org admins get in-org CRUD, org
members get read (replaced by ACL evaluation in the follow-up ACL PR in
this stack).
- API: all config routes nest under the organization, matching
templates: `POST|GET
/api/experimental/organizations/{organization}/mcp-servers` and
`GET|PATCH|DELETE .../mcp-servers/{mcpserverconfig}` (plus
`oauth2/connect`), resolved by a read-only param middleware that
conceals read-denied and cross-organization access as 404. Two routes
stay on the frozen `/api/experimental/mcp/servers/{mcpServer}` block:
the OAuth2 callback (the redirect URI baked into existing AS-side client
registrations) and `oauth2/disconnect`, which must remain reachable by
users removed from the organization so they can still revoke their token
grant.
- Chat runtime: selection validation and generation resolve configs
strictly by IDs, enabled state, and the chat's organization in SQL;
requested duplicates are normalized; invalid or cross-org IDs are
rejected with the precise ID list. IDs already persisted on a chat are
exempt from message-time rejection so disabling a selected server never
blocks sends; generation skips servers that are no longer usable.
- Frontend: API layer and admin settings pages target the new endpoints.
The admin page manages the default organization's servers; the org
picker is tracked separately (CODAGT-714).

- Security hardening from review: OAuth user grants are additionally
bound to `oauth2_revocation_url` (changing it invalidates grants, and a
racing OAuth callback gets 409 instead of recreating a grant).
Stack-wide SSRF protection for MCP config-directed traffic was split
into its own PR at the top of this stack (#28242) to keep this diff
reviewable; this PR keeps main's existing discovery IP-range guard.
OAuth2 auto-discovery now completes before the config row is inserted: a
failed discovery persists nothing, and there is no provisional row that
concurrent updates could race against.

Two follow-up PRs in this stack were split out to keep this diff
reviewable: #28064 completes the swagger annotations for the moved
routes (main already ships these experimental MCP handlers unannotated),
and #28065 carries hardening fixes and regression pins on top of the
cutover.

- Force On enforcement (landed on main mid-review) is org-scoped: the
forced set is read per chat organization
(`GetForcedMCPServerConfigsByOrganization`), so another organization's
`force_on` server never attaches to a chat.

## Breaking changes (experimental API)

The MCP server config endpoints move from the deployment-scoped
`/api/experimental/mcp/servers` block to organization-nested paths:
`POST|GET /api/experimental/organizations/{organization}/mcp-servers`
and `GET|PATCH|DELETE
/api/experimental/organizations/{organization}/mcp-servers/{mcpserverconfig}`
(plus `oauth2/connect`). The old paths are removed, so API consumers
must supply an organization. Two routes intentionally stay on the frozen
`/api/experimental/mcp/servers/{mcpServer}` block: the OAuth2 callback
(its redirect URI is baked into existing AS-side client registrations)
and `oauth2/disconnect` (must remain reachable by users removed from the
organization). These endpoints are under `/api/experimental`, so no
deprecation window is provided.

## Rolling upgrades

During a rolling deploy, an old replica creating an MCP config can fail
the new `NOT NULL organization_id` constraint until it is upgraded
(reads are unaffected: old binaries' generated queries select their own
column lists). This matches the repo's existing precedent for additive
NOT NULL migrations (000562) and affects only the admin config-create
path in the upgrade window.

Upgrades are expected to run in scheduled maintenance downtime with the
database locked during migration, so the migration ships no
rolling-upgrade compatibility machinery. The down migration deletes
organization-created configs (their chat references are cleaned by the
000510 delete trigger) and restores deployment-wide slug uniqueness.

Part of the MCP org-separation stack (CODAGT-711 -> CODAGT-717 audit ->
CODAGT-712 ACLs -> CODAGT-806 token RBAC).

Closes https://linear.app/codercom/issue/CODAGT-711

UAT: validated end to end on a two-org dogfood deployment, including a
real pre-migration to post-migration upgrade, cross-org isolation
(404s), same-slug-two-orgs, chat selection gating, and a live MCP tool
call through the org-scoped generation path. The migration was later
revised to keep existing rows in the default organization only (no
per-organization copies); that revision is covered by the migration test
suite.

> Mux (AI agent) authored this PR on Mike's behalf.

<!-- mux-attribution: model=claude-fable-5 thinking=high -->

---------

Co-authored-by: Mathias Fredriksson <mafredri@gmail.com>
2026-08-19 18:04:13 +00:00
Michael Suchacz 119f2b1dd9 feat: limit concurrent chat agents with pooled admission (#27902)
Limits concurrent chat generation on capped deployments to 5 root chats
and 10 delegated subagent chats. The pools are deployment-wide and
independent, so delegated work can continue while root capacity is full.

The default caps live in AGPL code. Enterprise contributes only a
licensing unlock, so unlicensed deployments stay capped and cannot fail
open. Licensed deployments are uncapped while Agent Hours usage stays
below an explicit hard limit. Deployments without a hard limit remain
uncapped, and reaching the Agent Hours allocation only triggers
warnings.

Admission happens before a worker takes chat ownership. Capped
deployments serialize admission across replicas with a
transaction-scoped advisory lock and derive active and queued state from
current ownership plus fresh runner heartbeats, rather than persisted
queue markers or per-replica state. The acquisition query returns a
bounded, pool-interleaved candidate set instead of ranking the whole
backlog; a migration replaces the acquisition index with a pool-aware
one. Refused chats stay running but unowned, and interrupt requests
bypass admission so users can stop queued or over-cap chats.

The single-chat API derives `queued_for_capacity` from live pool state;
list endpoints do not report it. The UI polls that value every 5 seconds
while a chat is running and shows a callout when the chat is waiting for
capacity.

Updates the administrator documentation and deployment-wide Prometheus
gauges for active and queued agents. Replica-level values must be
aggregated with `max`, not `sum`.

> Mux updated this PR on Mike's behalf.
2026-08-18 16:55:43 +02:00
Matt VollmerandNick Vigilante 75e0790cd7 docs: remove beta references from Coder Agents docs and manifest (#27939)
Removes all references to "beta" from the Coder Agents documentation
under `docs/ai-coder/agents/` and the corresponding `"state": ["beta"]`
entries in `docs/manifest.json`. Also updates screenshots, video, and
hero image, and regenerates the auto-generated feature-stages table.

**Beta reference removal:**
- `getting-started.md`: Removed "Coder Agents is in Beta" from the top
note, "is in beta" from the Chats API note, and "during Beta" from the
feedback section. Removed the version/stability note pinning 2.33.1.
- `index.md`: Removed the "Product status" section that stated Coder
Agents is in Beta.
- `manifest.json`: Removed `"state": ["beta"]` from 17 entries for pages
under `docs/ai-coder/agents/`. Preserved all `premium` and `early
access` states.
- `feature-stages.md`: Regenerated the auto-generated beta features
table, which no longer lists Coder Agents.

**Asset updates:**
- `coder-agents-ui.mp4`: Updated demo video on the agents landing page.
- `llm-providers.png`: Updated LLM provider support screenshot.
- `models-list.png`: Updated models list screenshot.
- `models-add-model.png`: Updated add model form screenshot.
- `agents-hero-image.png`: Updated hero image on the `docs/ai-coder`
landing page.

Two references in `models.md` (`v1beta` in the Google Gemini API URL and
`anthropic-beta` in the Anthropic header name) were left unchanged as
they are provider API identifiers, not product status labels.

PR generated with Coder Agents

---------

Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
2026-08-11 08:57:57 -04:00
Michael Suchacz 57f38b5c24 fix: keep chat attachments while a linking chat exists
Fixes https://linear.app/codercom/issue/CODAGT-616/keep-chat-attachments-while-chats-remain-unarchived

Chat attachments could disappear even though the chat was still available. This happened when a message was saved without recording which attachments it used, or when cleanup deleted attachments before an archived chat itself was removed.

Creating a chat, sending or queuing a message, and editing a message now record both the message and which attachments it uses as one operation. If the chat is already at the 50-attachment limit, the chat change fails without being partially saved.

Concurrent attachment writes serialize the 50-file cap per chat. Cleanup locks candidates and checks again for new links before deleting. If a file becomes unavailable after input validation, create, send, and edit return a clear client error and roll back the chat change.

An attachment stays available while any chat that uses it still exists. After an archived chat reaches the end of its retention period and is deleted, an old attachment that no remaining chat uses can be cleaned up. The retention guide and unavailable-attachment UI text document this lifecycle. This change cannot restore attachments that were already deleted.

The database migration adds two indexes so attachment cleanup stays fast as attachments accumulate.

> This PR was authored by Mux (AI) on Mike's behalf.
2026-08-11 13:53:15 +02:00
Ethan ee49107ea9 docs: document per-template agents_allowed (#27518)
Relates to CODAGT-713

Depends on #27517

This updates the Coder Agents platform controls documentation for the
per-template `agents_allowed` model. It replaces the deployment-wide
allowlist instructions with the **Agents allowed** controls in AI
Settings and template settings, documents that templates allow agents by
default, and explains that disabled templates are excluded from
`list_templates`, `read_template`, and `create_workspace`.

This is the final PR in the stack and aligns the template routing and
optimization guidance with the database, API, frontend, cleanup, and CLI
changes in the preceding PRs.
2026-08-07 17:23:28 +10:00
Michael Suchacz 6b8f820493 feat: remove native chat cost tracking in favor of AI Gateway cost data (#27330)
## Stack Context

This stack makes AI Gateway data and budgets the source of truth for AI
spend controls.

1. Re-back the per-chat cost endpoint with AI Gateway data (#27328,
merged).
2. Remove native chat usage limits (#27329, merged).
3. **This PR, now based on `main`:** remove native chat cost tracking
and its dedicated admin UI.

## Summary

Removes native per-message price calculation, model pricing fields, cost
persistence, aggregate cost queries, and admin cost API types. It also
deletes the Analytics and Spend pages plus their legacy redirects. The
AI Gateway-backed per-chat cost row and compact budget indicators
remain.

The spend documentation is renamed to `spend-management.md` and updated
for the remaining surfaces, group budget APIs, CSV export, upgrade
handling for native pricing and cost history, and the absence of a
deployment-wide spend dashboard. The per-chat cost API documents that
data follows AI Gateway retention and reports zero after all matching
requests are purged.

No schema is dropped in this release. `chat_messages.total_cost_micros`
remains nullable and unwritten so replicas from the previous release can
continue inserting messages during rolling upgrades. #27600 tracks
removal after the compatibility window.

> Mux prepared this PR on Mike's behalf.
2026-08-04 12:27:38 +02:00
Michael Suchacz f0e6ac64b3 feat: remove native chat usage limits in favor of AI Gateway budgets (#27329)
## Stack Context

This stack makes AI Gateway data and budgets the source of truth for AI
spend controls.

1. Re-back the per-chat cost endpoint with AI Gateway data (#27328,
merged).
2. **This PR:** remove native chat usage limits.
3. Remove native chat cost tracking and its dedicated admin UI (#27330).

## Summary

Removes the native usage-limit API, SDK types, SQL, and chat enforcement
for deployment, user, and group chat limits. Compact AI Gateway budget
indicators remain in the Agents sidebar, user menu, and group settings.
Gateway budget rejections and provider quota failures continue to
classify as usage-limit errors, including a 409 response for synchronous
title generation.

Budget-period labels now use the API's UTC boundaries, so users see the
same dates in every browser timezone. The documentation explains the AI
Gateway replacement, its licensing requirements, and the differences
from native limits.

No schema is dropped in this release. The usage-limit table, index, user
and group columns, constraints, audit mappings, and generated scan
fields remain for mixed-version rolling upgrades. #27600 tracks their
removal after the compatibility window.

## Breaking change

Native day, week, and month chat spend limits are removed and are not
migrated. AI Gateway budgets are month-based, group-scoped with per-user
overrides, and require the AI Gateway entitlement. Deployments without
that entitlement no longer have chat spend enforcement.

> Mux prepared this PR on Mike's behalf.
2026-08-04 11:36:49 +02:00
Michael Suchacz 9f4ddea571 feat: revoke MCP server OAuth grants at the provider on disconnect (#27300)
Closes
[CODAGT-805](https://linear.app/codercom/issue/CODAGT-805/revoke-oauth-grants-at-the-source-for-mcp-servers).

The experimental MCP server OAuth2 disconnect endpoint previously
deleted only the stored token row, leaving the grant active at the OAuth
provider. This PR adds provider-side token revocation while keeping
local disconnect independent of provider availability.

## Changes

- Add `mcp_server_configs.oauth2_revocation_url` in migration `000547`.
The value can be configured manually, discovered from RFC 8414 metadata,
and managed through the MCP server settings UI. Non-admin responses
redact it with the other OAuth2 fields.
- Revoke the refresh token first through the RFC 7009 endpoint, then
fall back to the access token only for `unsupported_token_type`. Public
clients send `client_id`; confidential clients use
`client_secret_basic`.
- Delete the local token transactionally before best-effort provider
revocation. Callers without a token receive the same response for hidden
and nonexistent config IDs, and provider failures return a generic
warning without exposing provider response bodies.
- Require HTTPS revocation endpoints except for HTTP loopback URLs.
Redirects must preserve the POST and remain on the configured origin.
Redirect errors omit provider-controlled paths and query strings so
reflected token material cannot enter logs.
- Treat `200 OK` and `204 No Content` as completed revocations. `202
Accepted` remains a failure because it does not confirm completion.
- Prevent an in-flight refresh from recreating a token deleted by
disconnect. Refresh persistence now uses an optimistic update keyed by
token ID and `updated_at`; only the OAuth callback can create a token
row. Refresh conflicts reload the current row or clear in-memory auth
when disconnect deleted it.
- Return `{token_revoked, token_revocation_error}` from disconnect,
while retaining SDK compatibility with the legacy `204` response. The UI
surfaces provider revocation failures as warning toasts.
- Document revocation endpoint discovery, HTTPS requirements, and
best-effort disconnect behavior.

No token or no configured revocation URL returns `token_revoked: false`
without an error, so disconnect remains idempotent.

> Updated by Mux, an AI coding agent, on Mike's behalf.
2026-07-20 00:14:03 +02:00
Nick Vigilante c84aa564ba docs: normalize code-fence languages for Shiki compatibility (#27161)
Normalizes non-standard code-fence language tags across `docs/**` so a
strict highlighter (Shiki, used by Fumadocs) won't fail the build on an
unrecognized language, and unifies redundant synonym tags onto one
canonical form per language. The current renderer (Speed-Highlight)
detects the language from the code content, not the fence label, so this
drift wasn't visible until now.

## Changes

- `hcl` -> `tf` (199 fences, including indented ones nested in
numbered/bulleted lists). Shiki ships `hcl` and `terraform` as two
distinct grammars (not aliases); every `hcl`-tagged fence in `docs/**`
is actually Terraform resource/data/provider syntax, so the more
specific `terraform` grammar is correct for all of them. `tf` is Shiki's
own alias for that grammar, and it's also what GitHub's own markdown
renderer resolves to the same HCL/Terraform highlighting.
- `pwsh`/`powershell` -> `ps1`. Both `ps` and `ps1` are registered
PowerShell aliases in Shiki, but on GitHub's renderer only `.ps1` is a
registered file extension (`.ps` isn't), so `ps1` renders identically to
`powershell` there today while bare `ps` would silently lose
highlighting.
- `env` -> `dotenv` (a dedicated Shiki grammar for `KEY=VALUE` files)
- `text`/`output`/`none`/`url` -> `txt`. Same built-in plain-text
fallback either way, just shorter.
- `Dockerfile` -> `dockerfile` (lowercase)
- `bash`/`shell` -> `sh` (732 fences). Shiki and GitHub both alias all
three to a single shell grammar; this was already the style guide's
stated preference, just not enforced across the existing corpus until
now.
- `markdown` -> `md` (4 fences). Alias of the same grammar in both Shiki
and GitHub.
- `jsonc` -> `json` (1 fence). The block has no comments or trailing
commas, so it doesn't need the comments-capable grammar.
- `ts` -> `tsx` (2 fences, `docs/about/contributing/frontend.md`).
Verified the actual content tokenizes identically under both grammars,
and a sibling block in the same file already needs `tsx` for real JSX,
so unifying to one tag is safe for this file. Documented a caveat: `tsx`
mis-tokenizes the legacy angle-bracket type-assertion syntax
(`<Type>value`), which is invalid in real `.tsx` files anyway, so use
`value as Type` instead.
- `yml` -> `yaml` (1 fence)
- Updated `docs/.style/style-guide/formatting.md` to document all
canonical tags

`promql` (2 fences) and `caddyfile` (2 fences) are left as-is. Shiki
doesn't bundle a grammar for either, so they need a custom grammar
registration when the site adopts Shiki, rather than degrading to `txt`.
Tracked as follow-up work under DOCS-118 and
[DOCS-544](https://linear.app/codercom/issue/DOCS-544/vendor-a-local-promql-grammar-for-shiki-syntax-highlighting)
(promql).

Does not touch `offlinedocs/`.

Linear:
[DOCS-476](https://linear.app/codercom/issue/DOCS-476/normalize-docs-code-fence-languages-de-risk-shikifumadocs)

<details>
<summary>How the fence tags were verified</summary>

Each tag was tested against a real `shiki@latest` highlighter instance
(`codeToHtml`/`codeToTokens`) and cross-checked against GitHub's
`@wooorm/starry-night` grammar sources (the renderer that actually
displays these `.md` files today, in repo browsing and PR diffs), since
that's what determines whether brevity is safe before Shiki adoption:

```text
FAIL  env        -- Language `env` is not included in this bundle.
FAIL  Dockerfile -- Language `Dockerfile` is not included in this bundle.
FAIL  promql     -- Language `promql` is not included in this bundle.
FAIL  caddyfile  -- Language `caddyfile` is not included in this bundle.
FAIL  pwsh       -- Language `pwsh` is not included in this bundle.
FAIL  output     -- Language `output` is not included in this bundle.
```

`hcl` doesn't error in Shiki, since it's a real grammar, but that's
exactly the trap: it was silently rendering every fence with the generic
HCL grammar instead of the Terraform-specific one. Every `hcl`-tagged
fence in `docs/**` was manually checked against `origin/main` and is
genuinely Terraform content.

For `ts`/`tsx`, tokenizing the actual doc content confirmed identical
output under both grammars; a synthetic test with the legacy
angle-bracket cast syntax confirmed `tsx` degrades on that specific
construct, which the style guide now calls out.

The first normalization pass only matched fence tags at column 0
(`^```tag$`), missing tags indented inside numbered/bulleted lists. A
follow-up pass caught the remaining occurrences at any indentation
level.

</details>


---

*This PR description and the underlying changes were prepared with Coder
Agents assistance.*
2026-07-15 14:07:09 -04:00
Michael Suchacz 55b06f14a3 feat: allow overriding advisor reasoning effort (#27196) 2026-07-14 11:01:51 +02:00
Thomas Kosiewski 9af3d31036 fix: relabel advisor max uses setting from per run to per turn (#27046) 2026-07-10 09:36:12 +02:00
Danielle Maywood 6b8c38b5a4 fix: gate chat advisor and virtual desktop behind experiments, delete experiments page (#26809) 2026-06-30 21:57:40 +01:00
TJ 5f42bbcdbf feat(site/src): nest agent pages under a Coder Agents subsection in AI nav (#26667)
Groups the agent-related AI settings pages under a new **Coder Agents**
parent in the sidebar, with a continuous left rule connecting the
children and an active-segment indicator that lights up the rule where
the current sub-item sits.

The new nav order:

- AI Governance
- AI Gateway keys
- Providers
- Coder Agents
  - Models
  - MCP servers
  - Templates
  - Spend
  - Instructions
  - Lifecycle

All target pages already exist on main (Danielle's recent migrations of
Models, MCP servers, Templates, Instructions, Lifecycle, Spend, and
Coder Agents into AI Settings). This PR only changes the sidebar visual
structure: the children move into an indented group with a `border-l
border-l-border` rule, and the active child paints a
`border-l-content-primary` segment over that rule via `-ml-px` so the
rule and indicator share a column instead of stacking.

<details>
<summary>Design notes</summary>

Concept 1 from the earlier exploration: always-expanded with indents,
the parent is its own page. Chosen because it adds no expand/collapse
state, no "which child is the default" question, and no animation work;
the parent reuses the existing nav-item, and the children sit in a
wrapper `div` with a left rule. The site bundle ships without Tailwind's
preflight, so the wrapper and sub-item borders are paired with
`border-solid` to actually paint, matching the pattern already in
`Sidebar.tsx`.

</details>

---

_This PR was prepared by Coder Agents on behalf of @tracyjohnsonux._
2026-06-29 13:46:09 +00:00
Cian Johnston 2d28c1b396 feat: surface template README to agent template tools (#26334)
Fixes CODAGT-447.

Alternative implementation of https://github.com/coder/coder/pull/26212
and https://github.com/coder/coder/pull/25978

- Adds up to the first 1000 characters of `README.md` (with leading
frontmatter stripped) to `chattool.list_templates` output
- Adds up to 800 characters of `README.md` to `chattool.read_template`.

**Note:** skipping `toolsdk` versions to keep scope small.

> 🤖 Generated by Coder Agents
2026-06-24 12:32:46 +01:00
Danielle Maywood 85652554f9 feat: move MCP servers to AI settings (#26642) 2026-06-24 12:30:15 +01:00
Danielle Maywood 3133a8b9c6 feat: move instructions to AI settings (#26624) 2026-06-24 12:29:58 +01:00
Michael Suchacz efbaedeefb docs: clarify Coder Agents AI Gateway routing (#25852)
> Mux updated this PR on behalf of Mike.

Clarifies that Coder Agents route through AI Gateway automatically,
while admins configure Agents providers with upstream provider or proxy
endpoint/base URLs.

Moves Agents-specific setup and credential guidance into the Agents
models page, removes the obsolete AI Gateway Coder Agents client page,
removes Coder Agents from the AI Gateway external client list, and links
BYOK credential selection to the global AI Gateway BYOK setting.
2026-06-02 14:59:29 +00:00
Cian Johnston 579daaff70 feat: add GitLab support to coderd/externalauth/gitprovider
Fixes CODAGT-146

Add GitLab support to the gitprovider package for gitsync/chatd PR
diff flows. This is a squashed stack of 3 PRs:

#25651 - refactor(coderd/externalauth): prepare gitprovider for multi-provider support
- Change gitprovider.New to return (Provider, error)
- Extract shared helpers (parseRetryAfter, checkRateLimitError,
  countDiffLines, escapePathPreserveSlashes) from github.go
- Update all callers (db2sdk, exp_chats, gitsync) for new signature
- Add error logging for provider construction failures
- Thread context through provider resolution

#25652 - feat(coderd/externalauth/gitprovider): add GitLab provider
- Implement full Provider interface: FetchPullRequestStatus,
  FetchPullRequestDiff, FetchBranchDiff, ResolveBranchPullRequest
- Handle nested groups, forks, and self-hosted instances
- Rate limit detection on both library and raw HTTP paths
- URL parsing/building with NormalizePullRequestURL support
- Unit tests covering error paths, URL parsing, state mapping
- Document GitLab configuration and known limitations

#25653 - test(coderd/externalauth/gitprovider): add GitLab VCR integration tests
- FetchPullRequestStatus: 4 fixtures (open, conflicts, merged, closed)
- FetchPullRequestDiff: 4 fixtures
- FetchBranchDiff: 3 fixtures (open, deleted, fork)
- ResolveBranchPullRequest: 3 fixtures
- go-vcr cassettes with sanitized GitLab API responses
2026-05-25 17:41:02 +01:00
Cian Johnston c8b1fa3196 fix: use UTC day boundaries for chat auto-archive eligibility (#25597)
Fixes CODAGT-311.

Users receive too many auto-archive notification emails because the
dbpurge loop runs every 10 minutes and archives chats on each tick using
timestamp-precise cutoffs, causing chats to trickle past the threshold
continuously.

Switch archive eligibility from timestamp arithmetic to date arithmetic
(UTC day boundaries). All chats whose last activity falls on the same
UTC date are now archived together on the first tick after midnight UTC,
reducing notification emails to ~at most~ probably one per day.
(Exception: if we hit the auto-archive limit)

- SQL compares `(last_activity AT TIME ZONE 'UTC')::date` against cutoff
date
- Go truncates current time to start-of-day before subtracting archive
days
- Tests verify date boundary semantics including late-activity and batch
edge cases
- Docs updated to describe UTC day boundary behavior and at-most-daily
notification cadence

> [!NOTE]
> Generated by Coder Agents
2026-05-22 11:39:44 +01:00
Thomas Kosiewski 969da320ec feat: export Coder Agents debug logs (#25039)
Adds JSON export actions to the Coder Agents Debug panel so users can download either the current chat's recent debug runs or one expanded run for support sharing.

The export reuses the existing chat debug endpoints and react-query cache, adds Storybook and unit coverage for the JSON envelope, and updates the chat debug logging docs with UI and cURL instructions.

Refs CODAGT-280.

Generated by Coder Agents.

<details>
<summary>Implementation notes</summary>

- Chat-level export fetches full detail for each listed debug run with `queryClient.fetchQuery(chatDebugRun(chatId, run.id))` and writes a single JSON file.
- Run-level export uses the already-loaded detail query data from an expanded run card.
- The JSON envelope includes `version`, `scope`, `exported_at`, `chat_id`, and either `runs` or `run`.
- The chat-level export reflects the current backend list endpoint behavior, up to the 100 newest debug runs.
- Agent-browser dogfooding verified files were downloaded and that `jq` validated the chat-level and run-level JSON contents.

</details>
2026-05-12 17:39:57 +02:00
Kyle Carberry b0b07536fc feat: add opt-in Coder identity headers for MCP servers (#25153) 2026-05-12 08:54:53 -04:00
Michael Suchacz 2874d4b4cd feat: add chat debug retention purge (#24943)
> Mux is acting on Mike's behalf.

Adds configurable retention for chat debug data, including the purge
query, updated_at index, site config, experimental API, SDK types,
frontend lifecycle setting, and docs.

The purge deletes debug runs older than the configured retention window
and relies on existing cascades to delete steps. The default retention
is 30 days, and setting the value to 0 disables the purge.
2026-05-05 22:37:13 +02:00
Matt Vollmer e189f73cc0 docs: close Coder Agents coverage gaps and align nav references (#24971)
Closes coverage gaps in `docs/ai-coder/agents/` and aligns nav
references with the current UI (post #24574 Behavior split, post #24644
Insights removal).

**Content fixes:**

- Replace site-wide `coder users edit-roles` flow with org-scoped
`agents-access` role (per migration `000475`). CLI examples now preserve
existing org roles since `edit-roles` overwrites the full set.
- Correct computer-use claim: supports Anthropic *and* OpenAI providers,
configured under the Virtual desktop experiment.
- New `platform-controls/experiments.md` covering Virtual desktop,
Advisor, and Chat debug logging (each as: what, how to enable, API).
Includes the Debug tab in the chat right panel.
- Trim `models.md` "Model overrides" to essentials: two layers (admin
subagent, user personal), contexts table, resolution order, API pointer.
- Remove retired `platform-controls/pr-insights.md` (page + manifest +
cross-links).

**Nav cleanup:**

- Admin-only tabs use the full `Agents > Settings > Manage Agents >
<Tab>` path; user-side tabs keep `Agents > Settings > <Tab>`.
- Replace stale "Behavior" references with Instructions / Lifecycle /
Experiments to match the current sidebar.
- Replace references to the removed top-bar Admin dialog with the
Settings sidebar.

<details>
<summary>Decision log</summary>

- Experimental features were originally drafted as a standalone Advisor
page plus inline sections in `platform-controls/index.md`. Consolidated
into one `experiments.md` since no individual feature warrants a full
page yet and parallel short sections are easier to scan.
- Reviewer feedback on early drafts: drop the inline experiments list
from `index.md` (avoid drift), drop the "users created before this role
was introduced" note (handled transparently by migration `000475`),
specify the full nav path for per-model pricing, link the
`type=computer_use` row in `architecture.md` to the Experiments page.
- CLI bulk-grant script previously called `edit-roles <user>
agents-access`. That replaces the user's full org role set, so the
script would silently strip `organization-admin`,
`organization-template-admin`, etc. Rewrote to read each user's current
roles, append `agents-access`, dedupe, and write the union back.

</details>

PR generated with Coder Agents.
2026-05-05 12:40:03 -04:00
Ben Potter 83f44dcaeb docs(docs/ai-coder/agents): note OpenAI as a supported computer-use provider (#24967)
PR #24772 (merged 2026-05-04) added OpenAI alongside Anthropic for
computer use, plus an admin selector under the virtual desktop toggle.
Three places in the agents docs still said "Anthropic only" — this
updates them.

No other content changes. Anthropic is still the default.

Fixes
[CODAGT-310](https://linear.app/codercom/issue/CODAGT-310/enable-openai-computer-use-in-codercoder)

---

@nickvigilante — heads up, the kind of release-train drift we keep
hitting:

- Feature is on `main`, so docs on `main` need to describe it.
- Feature is **not** in `release/2.33` and **not** in `v2.34.0-rc.0`
(both cut before #24772 merged). It will ship in v2.34.
- `coder.com/docs` follows `main`, so once this lands, v2.33 users see
"OpenAI is supported" and find no toggle.

Fwiw our [`doc-check`
workflow](https://github.com/coder/coder/blob/main/.github/workflows/doc-check.yaml)
would have caught this on #24772 — it's exactly what it's for. It [did
trigger](https://github.com/coder/coder/actions/runs/25326759671) but
the chat-create step errored out (curl exit 22) and nobody re-ran it, so
the analysis never happened. Worth tightening that path so a transient
API blip doesn't silently skip the check.

> Generated with [Coder Agents](https://coder.com/agents)
2026-05-05 10:39:05 -05:00
Kyle CarberryandCoder Agents d889ba1842 feat: add user_oidc auth type for MCP servers (#24793)
Adds a 5th MCP server authentication mode, `user_oidc` ("User OIDC
Identity"), that forwards the calling user's OIDC access token from
`user_links.oauth_access_token` to the upstream MCP server as
`Authorization: Bearer <token>`.

The token is read from `user_links` and refreshed transparently via
`oauth2.TokenSource` before each MCP request. No new per-MCP-server
secret storage and no per-user connect/disconnect step.

**Limitation**: only users who logged in via OIDC have a forwardable
token. Users authenticated via password or GitHub will see requests sent
without an `Authorization` header, and the upstream MCP server is
expected to respond with 401. A pluggable token source (e.g. CLI-minted
E2E tokens) is left as future work.

<details>
<summary>Implementation notes</summary>

- Schema: new
`coderd/database/migrations/000481_mcp_user_oidc_auth.{up,down}.sql`
relaxes the `mcp_server_configs.auth_type` CHECK constraint to include
`user_oidc`. Down migration deletes affected rows before restoring the
old constraint.
- SDK validation: `codersdk/mcp.go` extends `oneof` for
`CreateMCPServerConfigRequest` and `UpdateMCPServerConfigRequest`.
- Handler: `coderd/mcp.go` adds `case "user_oidc":` to the
field-clearing switch on update. The existing list and detail handlers
already report `auth_connected = true` for any non-`oauth2` auth type.
- Header construction: `coderd/x/chatd/mcpclient/mcpclient.go`
introduces a `UserOIDCTokenSource` interface and adds the `user_oidc`
case to `buildAuthHeaders`. `ConnectAll` / `connectOne` /
`buildAuthHeaders` gain `userID uuid.UUID, oidcSrc UserOIDCTokenSource`
parameters.
- Wiring: `coderd/x/chatd/chatd.go` adds `OIDCTokenSource` to `Config` /
`Server` and passes `chat.OwnerID` plus the source through `ConnectAll`.
`coderd/coderd.go` constructs the source next to the `chatd.New` call
when `options.OIDCConfig` is non-nil.
- Token source: `oidcMCPTokenSource` lives in `coderd/mcp.go`. It reads
the user's OIDC link, refreshes via `oauth2.TokenSource`, and writes the
refreshed token back to `user_links`. Logic is duplicated from
`provisionerdserver.ObtainOIDCAccessToken` to avoid an MCP ->
provisionerdserver dependency. The two copies must be kept in sync; a
comment on `oidcMCPTokenSource` records this.
- Frontend: `MCPServerAdminPanel.tsx` adds the new dropdown option, an
explanatory helper block (no admin-configurable fields), and a Storybook
story (`CreateServerUserOIDC`).
- Tests:
- `mcpclient_test.go`: `TestConnectAll_UserOIDCAuth`,
`TestConnectAll_UserOIDCAuth_NoLink`,
`TestConnectAll_UserOIDCAuth_NilSource`. All existing tests updated for
the new signature.
- `mcp_test.go`: extends `TestMCPServerConfigsAuthConnected` to assert
`auth_connected=true` for `user_oidc`; adds
`TestMCPServerConfigsUserOIDCClearsFields` and
`TestMCPServerConfigsUserOIDCDirect`.
- Docs: `docs/ai-coder/agents/platform-controls/mcp-servers.md`
describes the new mode and its OIDC-only limitation.

</details>

This PR was created by Coder Agents.

---------

Co-authored-by: Coder Agents <agents@coder.com>
2026-05-03 11:31:48 -04:00
Cian Johnston 70d6efa311 feat: chat auto-archive owner digest notifications (#24643)
Depends on #24642

Adds per-owner digest notifications onto the chat auto-archive
subsystem.

Each tick's archived rows are grouped by owner, the top 25 titles per
owner are rendered into a new `Chats Auto-Archived` notification
template, and any remainder surfaces as `and N more`. Each digest is
per-tick, so users with large amounts of purgeable data may get multiple
notifications in sequence (one per user per tick).

The template body branches on `retention_days`: when retention is
disabled (`retention_days=0`), users are told archived chats are kept
indefinitely rather than falsely claiming imminent deletion.

### Changes
- migration `000XXX_chat_auto_archive_notification_template` adds new
notification template
- `dbpurge`: threads `notifications.Enqueuer` through `New`; and
enqueues notification message.
- `cli/server.go`: passes `options.NotificationsEnqueuer` into
`dbpurge.New`.
- `coderd/notifications/events.go`: new `TemplateChatAutoArchiveDigest`
UUID.
- `coderd/inboxnotifications.go`: inbox registration.
- Docs: adds a `Notifications` section to `chat-auto-archive.md`.

> 🤖
2026-04-28 08:56:36 +01:00
Cian Johnston a876287d36 feat: auto-archive inactive chats with audit trail (#24642)
Adds a background job in `dbpurge` that periodically archives chats
inactive beyond a configurable threshold. Each archived root chat gets a
background audit entry tagged `chat_auto_archive`. Disabled by default.

* New `AutoArchiveInactiveChats` SQL query with LATERAL last-activity
subquery and partial index on archive candidates
* `site_configs`-backed `auto_archive_days` setting with admin-only PUT,
any-authenticated-user GET
* Cascade archive via `root_chat_id`; pinned chats and active threads
exempt
* Root-only audit dispatch on detached context, matching manual archive
(`patchChat`) behavior
* 11 subtests covering disabled no-op, boundary, deleted messages, child
activity, pinned exemption, multi-owner, idempotency, and batch
pagination

PR #24643 adds per-owner digest notifications.
PR #24704 adds the requisite UI controls.

> 🤖
2026-04-24 14:18:28 +01:00
Michael Suchacz f073323c89 refactor: unify subagent spawn behind spawn_subagent (#24535)
Unify the three subagent spawn tools (`spawn_agent`,
`spawn_explore_agent`, `spawn_computer_use_agent`) behind a single
`spawn_subagent` tool keyed by a `subagent_type` discriminant
(`general`, `explore`, `computer_use`). Mirrors the single-entry-point
pattern already used by `task` in mux while keeping `wait_agent`,
`message_agent`, and `close_agent` as separate lifecycle tools.

A new backend subagent definition catalog
(`coderd/x/chatd/subagent_catalog.go`) is the source of truth for tool
description, prompt guidance, availability rules (plan mode,
desktop/Anthropic gating), and child-chat option building.
`spawn_subagent` advertises only the types available in the current
context and validates `subagent_type` server-side; context inheritance
still flows through the existing `createChildSubagentChatWithOptions`
path. `wait_agent`, `message_agent`, and `close_agent` responses now
include a server-derived `subagent_type` so the UI stops inferring
lifecycle state from tool names.

The frontend gets a shared normalization helper
(`site/src/pages/AgentsPage/components/ChatElements/tools/subagentDescriptor.ts`)
that maps either legacy tool names or new `spawn_subagent` args into a
common descriptor (action, variant, icon, fallback copy). Legacy
transcripts still render identically; `Tool.tsx`, `SubagentTool.tsx`,
`ToolLabel.tsx`, `ToolIcon.tsx`, and `messageParsing.ts` now key off the
descriptor instead of hard-coded names. Existing UI copy is preserved
(`Spawning Explore agent...`, `Using the computer...`, computer-use
monitor icon and Open Desktop affordance).

> This PR was opened by Mux working on Mike's behalf.
2026-04-21 14:01:32 +02:00
Matt Vollmer cc4eaff248 docs: add git providers and PR Insights pages for Coder Agents (#24447)
Adds two new documentation pages under platform controls for Coder
Agents:

- **Git Providers** (`git-providers.md`) — documents the `API_BASE_URL`
configuration required for self-hosted GitHub Enterprise deployments.
Positions it as an extension of the existing [external
auth](https://coder.com/docs/admin/external-auth) setup to support Coder
Agents features that need richer git host API access: the in-chat diff
viewer and PR Insights.
- **PR Insights** (`pr-insights.md`) — documents the PR analytics
dashboard, requirements for PR data to appear, and troubleshooting.
Links to git-providers for GHE setup.

Also updates the platform controls index and docs manifest.

---

> PR generated with Coder Agents
2026-04-16 19:52:17 +00:00
Michael Suchacz 1cf0354f72 feat: add plan mode with restricted tool boundary (#24236)
> This PR was authored by Mux on behalf of Mike.

## Summary
- add persistent plan mode for chats and the chat-specific plan file
flow
- add structured planning tools such as `ask_user_question` and
`propose_plan`
- keep `write_file` and `edit_files` constrained to the chat-specific
plan file during plan turns
- allow shell exploration in plan mode, including subagents, via
`execute` and `process_output`
- block implementation-oriented, provider-native, MCP, dynamic, and
computer-use tools during plan turns
- update the chat UI, tests, and docs for the new planning flow
2026-04-16 11:12:01 +02:00
Danielle Maywood 29ad2c6201 feat: merge Limits + Usage into unified Spend page (#24093) 2026-04-09 13:17:03 +01:00
Matt Vollmer 506fba9ebf docs: add BYOK docs, fix tool tables, add platform controls (#24178)
Fixes several documentation gaps and inaccuracies in the Coder Agents
docs identified during a deep review against the current product state.

## BYOK (User API Keys)

`models.md` stated *"Developers cannot add their own providers, models,
or API keys"* — this has been incorrect since the provider key policy
system shipped (Apr 2, #23751/#23781).

- Added **Key policy** section documenting the three admin toggles
(`central_api_key_enabled`, `allow_user_api_key`,
`allow_central_api_key_fallback`) with a truth table showing all
resolution outcomes
- Added **User API keys (BYOK)** section covering the developer-facing
key management page, status indicators, selection priority, and key
removal
- Updated `platform-controls/index.md` to reference BYOK instead of
claiming keys are admin-only

## Reasoning effort enum fixes

- **OpenAI**: removed `none` — code accepts `minimal, low, medium, high,
xhigh`
- **OpenRouter**: narrowed to `low, medium, high` per
`ReasoningEffortFromChat` in `chatprovider.go`

## Tool table completeness

- Added `spawn_computer_use_agent`, `read_skill`, `read_skill_file` to
`index.md` tool table
- Added "Workspace extension tools" section to `architecture.md` for
`read_skill`/`read_skill_file`
- Fixed orchestration restriction note to list all 5 gated tools instead
of just `spawn_agent`
- Added conditional availability notes for desktop and skills tools

## Platform controls

Three admin-only settings existed in the Behavior tab with no
documentation:

- **Virtual desktop** — admin toggle, Anthropic + portabledesktop
requirements
- **Workspace autostop fallback** — default TTL for agent workspaces
without template-defined autostop
- **Data retention** — moved `chat-retention.md` into
`platform-controls/` since it's admin-only, fixed nav path

---

> PR generated with Coder Agents
2026-04-08 18:24:12 -04:00
Michael Suchacz 590235138f fix: pin fixed anthropic/fantasy forks for streaming token accounting (#24077) 2026-04-08 17:07:39 +00:00
Matt Vollmer ca879ffae6 docs: add extending-agents, mcp-servers, and usage-insights pages (#23810)
Adds three new documentation pages for major shipped features that had
no docs, and updates the platform controls index to reflect current
state.

## New pages

### Extending Agents (`extending-agents.md`)

Covers two workspace-level extension mechanisms:
- **Skills** — `.agents/skills/<name>/SKILL.md` directory structure,
frontmatter format, auto-discovery, `read_skill`/`read_skill_file`
tools, size limits, lazy loading
- **Workspace MCP tools** — `.mcp.json` format, stdio and HTTP
transports, tool name prefixing, discovery lifecycle and caching

### MCP Servers (`platform-controls/mcp-servers.md`)

Admin MCP server configuration:
- CRUD via **Agents** > **Settings** > **MCP Servers**
- Four auth modes: none, OAuth2 (with auto-discovery), API key, custom
headers
- Availability policies: `force_on`, `default_on`, `default_off`
- Tool governance via allow/deny lists
- Permission model and secret redaction

### Usage & Insights (`platform-controls/usage-insights.md`)

Three admin dashboards:
- **Usage limits** — spend caps with per-user and per-group overrides,
priority hierarchy, enforcement behavior
- **Cost tracking** — per-user rollup with token breakdowns, date
filtering, per-model and per-chat drill-down

## Updated files

- **`platform-controls/index.md`** — Moved MCP servers, usage limits,
and analytics from "Where we are headed" into "What platform teams
control today" with links to the new pages. Removed the tool
customization roadmap section (now covered by MCP servers page).
- **`manifest.json`** — Added nav entries for all three new pages.

## Resulting nav hierarchy

```
Coder Agents
├── Getting Started
├── Early Access
├── Architecture
├── Models
├── Platform Controls
│   ├── Template Optimization
│   ├── MCP Servers              ← NEW
│   └── Usage & Insights         ← NEW
├── Extending Agents             ← NEW
└── Chats API
```

---

*PR generated with Coder Agents*
2026-03-30 12:46:34 -04:00
Matt Vollmer 8e57498a87 docs: update Chats API and platform controls docs to match current state (#23803)
The Chats API docs and platform controls docs had fallen behind the
implementation. This brings them up to date.

## Chats API docs (`chats-api.md`)

### Breaking: archive/unarchive endpoints removed

The old `POST /{chat}/archive` and `POST /{chat}/unarchive` endpoints no
longer exist. Replaced with the `PATCH /{chat}` update endpoint
(`{"archived": true/false}`).

### Chat object updated

Added all new fields to the example response and a new reference table:
- `build_id`, `agent_id` — workspace agent binding
- `parent_chat_id`, `root_chat_id` — delegated/child chat lineage
- `pin_order` — pinned chats
- `labels` — general-purpose key-value labels
- `mcp_server_ids` — MCP server bindings
- `has_unread` — read/unread tracking
- `diff_status` — PR/diff metadata

### New endpoints documented

- `PATCH /{chat}` — update chat (title, archived, pin_order, labels)
- `PATCH /{chat}/messages/{message}` — edit a user message
- `GET /watch` — watch all chats via WebSocket
- `POST /{chat}/title/regenerate` — regenerate title
- `GET /{chat}/diff` — get diff/PR status
- `DELETE /{chat}/queue/{id}` / `POST /{chat}/queue/{id}/promote` —
queue management

### Updated existing endpoint docs

- Create chat: added `mcp_server_ids` and `labels` fields
- Send message: added `mcp_server_ids` field
- List chats: added `q` and `label` query parameters
- Stream: noted read cursor behavior on connect/disconnect

## Platform controls docs

### Template allowlist (`platform-controls/index.md`)

- Updated the "Template routing" section to document the template
allowlist setting (**Agents** > **Settings** > **Templates**)
- Removed the "Template scoping for agents" bullet from "Where we are
headed" since it shipped

### Template optimization (`template-optimization.md`)

- Added "Restrict available templates" section documenting the allowlist
UI, behavior, and scope (agents only, not manual workspace creation)

---

*PR generated with Coder Agents*
2026-03-30 10:28:15 -04:00
Matt Vollmer 481c132135 docs: clarify agent permission inheritance and default security posture (#23194)
Addresses five documentation gaps identified from an internal agents
briefing Q&A, specifically around what permissions an agent inherits
from the user:

1. **No privilege escalation** — Added explicit statement that the agent
has the exact same permissions as the user. No escalation, no shared
service account.
2. **Cross-user workspace isolation** — Added statement that agents
cannot access workspaces belonging to other users.
3. **Default-state warning** — Added WARNING callouts that agent
workspaces inherit the user's full network access unless templates
explicitly restrict it.
4. **Tool boundary statement** — Added explicit statement that the agent
cannot act outside its defined tool set and has no direct access to the
Coder API.
5. **Template visibility scoped to user RBAC** — Clarified that template
selection respects the user's role and permissions.

Changes across 3 files:
- `docs/ai-coder/agents/index.md`
- `docs/ai-coder/agents/architecture.md`
- `docs/ai-coder/agents/platform-controls/template-optimization.md`

---
PR generated with Coder Agents
2026-03-18 12:15:50 +00:00