Architecture — Grida's Agent System Implementation
This page records how Grida composes its local agent system. The behavior, policy, and component contracts are the agent RFC.
Composition
| Process | Owns |
|---|---|
| Native agent host | Chat execution: the master, runtime, durable sessions, tools, permissions, confinement, and the ACP client protocol. Desktop supervises it over private stdio; headless runs use it directly. |
| Retained media sidecar | Image, video, and audio generation, provider custody for those operations, and host capabilities such as files, recents, and workspaces, behind the loopback daemon perimeter. No chat. |
| Desktop main | Supervision, UI and IPC routing, editor endpoint registration, the supervised provider transport, and the subscription sign-in ceremony. |
| Desktop renderer | Presentation of chat state received through main. |
Native chat reaches model providers either directly or through main's supervised transport, which owns Gateway grants and subscription credentials. The native client protocol and the tool-host contract bind the native host to Desktop. Package and crate inventories live in each package's or crate's README.
Capacity providers
Native providers supply model capacity to the same Grida-owned loop. BYOK, Grida Gateway (GG), configured endpoint/local capacity, and the experimental ChatGPT Subscription native provider remain distinct provider-qualified surfaces. A provider supplies capacity only; it never owns sessions, tools, approvals, or the loop. ACP is an external-agent boundary, not a native provider.
A chat keeps the provider authority it was created under. Continuation, retry, compaction, and recovery refuse rather than move a chat onto another credential or cost boundary; changing provider is an explicit user selection. The provider selection section owns the ordering for new chats.
Host and tenant split
The retained sidecar is a general daemon: a loopback HTTP server, the GRIDA-SEC-004 perimeter, and the host capability route groups (files, recents, workspaces, the secrets store). Media generation is one tenant mounted through a static, typed tenant list — deliberately not a plugin registry. Dependency direction is one-way: the tenant imports the daemon; the daemon knows no tenant. A non-AI host capability targets the daemon and never touches an AI package.
Every route, tenant routes included, passes the same perimeter: per-spawn
Basic Auth carried only in the Authorization header, Referer, and
Origin. There is no secrets/get; key material never returns to the
renderer.
Shared contracts and host capabilities
Agent lifecycle behavior belongs to the native host and is exercised through its headless executable. Editor-specific capabilities execute in the owning editor process. Controlled headless adapters prove protocol and lifecycle contracts, while real editor document behavior and rendering require Desktop checks. The tool-host contract separates those responsibilities.
Anti-goals
- No renderer-owned provider credentials or OAuth lifecycle.
- No native-provider shortcut through ACP.
- No model-name-only provider inference.
- No silent provider failover during a turn.
- No window/UX framework — hosts render; the agent host stores and runs.
- No plugin/extension registry — tools and capabilities are fixed by the RFC, and the daemon's tenant list is static.
- No free process spawning — commands go through the host's confined command authority.
Reading order
- This doc.
- agent/components.md.
- agent/tools.md and agent/components.md / storage and recovery.
- tools-fundamentals.md.
- desktop/process-model.md.
- GRIDA-SEC-004.