One page per area: frontend UI, agent, workflows, daemon (task lifecycle and event automation together), State Store, control plane and settings, and processes and wiring, with merging work kept separate.
2.6 KiB
2.6 KiB
Agent
Authority: docs/architecture/agent-system.md (execution boundary, the model
never runs git) and the Deployment Model section of CLAUDE.md.
The daemon prepares a workspace, starts one container per task from a profile's
image, and hands the whole task to archie-agent over NATS in one
taskrun.Request. The agent reaches the State Store, forge and worktree push
only through the daemon's RPC servers, using task-scoped credentials.
Giving the agent something new
- Data about the task goes in
taskrun.Requestor the task brief (container.TaskPayload), never in an environment variable. Add a test that the request carries it (TestRunViaAgentSendsMCPServersis the pattern). - A credential is scoped to the task and revoked when it ends, like the State Store grant and the worktree publication grant. The daemon's own administrative token never enters a container.
- A tool reaches the agent through the central registry, MCP, a repository
script or a skill plugin. A profile's
toolslist filters those; ai-sdk agentloop's built-in file tools are outside it. A tool that must stay inside the workspace uses the agent loop's confinement, not its own path handling.
Changing the agent image or a profile image
- The agent image is
Dockerfile; example profile images live inexamples/profiles/, each with a build-only service indocker-compose.yml(profiles: ["build"], soup -dnever starts it). - Anything the agent runs must be in the image. The container gets no package manager at run time beyond what the image ships.
- A locally built image needs
containers.pull_policy = "missing";"always"tries to pull it and fails. - Profiles are configured under
[containers.profiles.<name>]and resolved by the daemon before the container starts (pinTaskProfile). An unknown profile parks the task; it never falls back to the default image.
Changing how a task runs
- Workspace preparation happens in the daemon (
prepareWorkspace) before the container starts, because the container binds the directory. Clones need the daemon's forge credential; the agent never clones. - A task with no repository gets
worktree.Manager.ScratchDir, which is removed when the task ends. - The agent runs as root in the container. Anything it writes into the
bind-mounted workspace is handed back to the daemon's UID
(
restoreWorktreeOwnership); a new write path must stay inside that workspace. - NATS rules are in
CLAUDE.md: task responses usemsg.Respond, a responder is flushed after it registers, andARCHIE_TASKSis a work queue.