AGENTS.md@internal/server/chatagent git:20260911.bfe7269A

Immutable. This exact content is served forever at /api/v1/blob/963ce23fd77f5500.

# Chatagent (Product Orchestration)

Binds `pkg/agent` to REST (`/chatagent/*`), Web (`/service/web/agents/*`), platform sinks, store, and scheduled tasks. Must not become a second agent engine. Repo-wide standing orders: root [AGENTS.md](../../../AGENTS.md).

## Boundaries

- **Allowed**: `pkg/agent/*`, `internal/store/*`, views via handlers. Product tools: `tools/clip`, `tools/notify`, `tools/gateway`, `tools/htmlpreview`.
- **Forbidden**: `internal/store` inside `pkg/agent`; store types in engine APIs ([pkg-boundaries.md](../../../docs/architecture/pkg-boundaries.md)).

## Entry points

- REST: `internal/server/chatagent_http*.go` — primary `POST .../messages` (SSE); observer `GET .../events` (subset via `IsObserverStreamEvent` in `protocol.go`: confirm, confirm_resolved, canceled, mode_change, run_complete)
- Web SSE: `internal/modules/web/chatagent_web_stream.go`
- Platform DM: `chatagent_handler.go`
- Shared `*Service`: `server.ChatAgentService()` (`chatagent_bootstrap.go`) → `BindSharedService` (`service_state.go`) + `web.SetChatAgentService`
- Scripts: `pkg/views/partials/chatagent_scripts.templ` (`FlowbotChatAgent` only)

Hot-path files: `service.go` (Run), `service_state.go`, `run_io.go` (`withRunIO`), `hooks.go` (approval modes + permission), `harness_pool.go`, `api_stream.go` / `api_run.go`, `protocol.go`, `confirm.go`, `approval_store.go` / `approval_reviewer.go`, `session_events.go`. Non-interactive: `pipeline_run.go` (not Run phases), `ephemeral_run.go`, `scheduled_run.go`.

## Run pipeline

`StreamAPIRun` → `RunAPI` → `Service.Run`: prepare → lock → harness → hooks/permission/confirm (wired at harness build; ask via `withRunIO`) → stream → deliver → cleanup (abort path). Inject publisher/confirm via `withRunIO`; do not look up from session maps in hooks.

SSE / streaming write rules: [server AGENTS.md](../AGENTS.md). The chatagent SSE framing and event protocol is a settled seam ([deps policy](../../../.agents/notes/implemented/process/2026-08-13-dependencies-over-hand-rolling.md)).

Protocol changes: update `docs/agent/chatagent-feature-checklist.md` + tests first. Keep HTTP handlers thin.

## Testing

Which layer: [docs/testing/README.md](../../../docs/testing/README.md). This package owns **product policy** transcripts (permission / DCG).

```bash
go test ./internal/server/chatagent -count=1
go test ./internal/server/chatagent/eval -count=1
```

Policy outcome fixtures live under `eval/testdata/safety/`. BDD coverage for deny/allow env reads is in `tests/specs/agent_spec_test.go` (`Agent Eval Policy`).