Skip to main content

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​

ProcessOwns
Native agent hostChat 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 sidecarImage, 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 mainSupervision, UI and IPC routing, editor endpoint registration, the supervised provider transport, and the subscription sign-in ceremony.
Desktop rendererPresentation 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​

  1. This doc.
  2. agent/components.md.
  3. agent/tools.md and agent/components.md / storage and recovery.
  4. tools-fundamentals.md.
  5. desktop/process-model.md.
  6. GRIDA-SEC-004.

See also​