mirror of
https://github.com/coder/coder.git
synced 2026-09-22 05:05:20 +08:00
Kyle Carberry
1742003785
## Problem
Workspace context surfaced in chat (Coder Agents) is incomplete and racy
on a fresh boot:
- The context panel is missing personal skills (only repo-level skills
under `.claude/skills` show up).
- The MCP section lists `.mcp.json` files but no MCP servers are
registered.
- The Issues panel reports instruction files as unreadable, e.g.
`CLAUDE.md (file: unreadable)` and `.cursorrules (file: unreadable)`
with `symlink resolve: lstat .../AGENTS.md: no such file or directory`.
## Root cause
`agentcontext.Manager` collected and pushed context too eagerly:
- `NewManager` ran an eager resolve at agent `init()`.
- `RunPush` starts as a normal connection routine (`startAgentAPI210`)
with no lifecycle gating, so the first snapshot was pushed
(`Initial=true`) as soon as the agent API connected.
Both happened **before startup scripts finish** and before the lifecycle
reaches `ready`. At that point:
- `CLAUDE.md` / `.cursorrules` symlinks to `AGENTS.md` don't resolve
yet, so `EvalSymlinks` fails and the resolver emits `StatusUnreadable`
"symlink resolve" issues.
- Personal skills haven't synced yet, so they're missing.
- MCP servers connect via `mcpManager.Reload(...)` only **after**
`ready`, so only `.mcp.json` configs appear, with no servers.
That partial, error-laden snapshot is persisted by coderd and can
hydrate a chat.
## Fix
Gate `agentcontext.Manager` until the agent is ready, unconditionally:
- The Manager always starts gated. `NewManager` leaves the zero-value
(version 0) snapshot in place and never walks the filesystem; `RunPush`
withholds version-0 snapshots, so nothing reaches coderd.
- The agent calls `Manager.SetReady()` from the lifecycle transition in
`handleManifest`, right after startup scripts finish (`ready`, or
terminal `start_error` / `start_timeout` so a failed startup still
surfaces whatever context exists).
- On `SetReady`, the Manager performs the first real resolve (version 1)
and broadcasts it; `RunPush` ships it with `Initial=true`. Later changes
(MCP connect, skill edits) re-resolve and push as before.
Eager resolution before `ready` was the bug, not a mode worth
preserving, so the gate is always on rather than an opt-in option. This
aligns the agent-side push with chatd, which already waits for agent
readiness before loading context. No proto/coderd/DB changes: coderd
simply never receives a pre-ready snapshot.
<details>
<summary>Design notes & decisions</summary>
- **Unconditional, not opt-in.** An earlier iteration added the gate as
an opt-in `ManagerOptions.GateUntilReady`. Since the eager
resolve-on-construct was the defect, the option, the eager first
resolve, and the now-dead `resolveLocked` helper were all removed; the
Manager is always gated until `SetReady`.
- **Version 0 is the pre-ready sentinel.** The gated placeholder is just
the zero-value snapshot (version 0); the first real resolve is version
1, so the push loop withholds anything at version 0. An earlier revision
carried a dedicated `Snapshot.Initializing` bool plus an HTTP `/resync`
field, but the push loop was the only consumer and nothing read the HTTP
field, so both were dropped.
- **Defer, don't retry symlinks.** Transient "unreadable" symlinks are
an artifact of collecting before checkout. Deferring until `ready` fixes
all three symptom classes at once and avoids masking genuine post-ready
errors (a broken symlink at `ready` is still reported).
- **Release on terminal startup states too** (`start_error`,
`start_timeout`), so a failed startup still surfaces whatever context
exists instead of gating forever. On reconnect the Manager instance is
reused and stays ready.
</details>
## Tests
- `agentcontext.TestManager_WithholdsCollectionUntilReady` simulates
collection running before startup finishes (broken `CLAUDE.md` /
`.cursorrules` -> `AGENTS.md` symlinks): asserts the gated snapshot is
the empty version-0 placeholder with no resources and no `unreadable`
issues, and that after `SetReady` (target now present) the inventory
resolves cleanly to a single instruction file with no spurious issues.
- `agentcontext.TestRunPush_WaitsForReady` asserts the push loop ships
nothing while gated even when content exists, then ships the full
inventory with `Initial=true` after `SetReady`.
- `agentcontext.TestManager_SetReadyIsIdempotent` covers the version-0
placeholder before ready, the single resolve to version 1 on `SetReady`,
and idempotency across repeated calls.
- Updated `agent.TestAgent_ContextStatePushed`: the first push now
already contains `AGENTS.md` with `Initial=true` and no `UNREADABLE`
resources (no pre-startup empty/partial push).
Validated on the changed packages: `go test -race
./agent/agentcontext/...`, `go test ./agent/ -run
TestAgent_ContextStatePushed`, `golangci-lint run`, `go vet`, `gofmt`
(all clean).
---
🤖 Generated by Coder Agents on behalf of @kylecarbs.
40 lines
2.2 KiB
Go
40 lines
2.2 KiB
Go
// Package agentcontext consolidates the agent-side plumbing that
|
|
// resolves, watches, and pushes workspace context (instruction
|
|
// files, skills, and MCP configuration) to coderd.
|
|
//
|
|
// This is the agent half of the design described in
|
|
// "RFC: Workspace Context Sources for Coder Agents". It owns:
|
|
//
|
|
// - User-declared scan roots (Sources) layered on top of
|
|
// built-in defaults and the working directory.
|
|
// - A resolver that classifies files at fixed locations under
|
|
// each scan root into typed Resources (instruction files,
|
|
// skills, MCP configs, MCP servers). Discovery is shallow:
|
|
// instruction files (AGENTS.md, CLAUDE.md, .cursorrules) and
|
|
// .mcp.json are read only at a scan root's top level, skills
|
|
// only from fixed container directories (skills, .agents/skills,
|
|
// .claude/skills, .codex/skills), and the resolver never walks
|
|
// the tree downward or up to a parent directory.
|
|
// - A fixed-location fsnotify watcher that signals a re-resolve
|
|
// when any recognized file changes.
|
|
// - A readiness gate (Manager.SetReady). The Manager starts gated,
|
|
// publishing only an empty version-0 snapshot until the agent calls
|
|
// SetReady from the workspace lifecycle transition once startup
|
|
// scripts finish. This keeps pre-startup partial state out of
|
|
// coderd and chats.
|
|
// - An HTTP API at /api/v0/context/sources for source CRUD
|
|
// and /api/v0/context/resync for synchronous push barriers.
|
|
// - A Pusher abstraction so the latest Snapshot can be shipped
|
|
// to coderd without coupling this package to any particular
|
|
// drpc client version.
|
|
//
|
|
// Live MCP server tool lists come from the shared MCP engine in
|
|
// agent/x/agentmcp, which owns the single set of MCP server connections
|
|
// used for both tool discovery and tool-call execution. This package
|
|
// reads that engine's catalog through the injected MCPCatalog option and
|
|
// surfaces the servers and their tools as KindMCPServer resources, so
|
|
// MCP servers are pushed to coderd alongside instruction files and
|
|
// skills. The engine notifies this package through the Manager's Trigger
|
|
// when its catalog changes, driving a re-resolve and re-push.
|
|
package agentcontext
|