Skip to main content

Core concepts

A small vocabulary goes a long way. These are the nouns you will see everywhere in the API.

Agent​

An agent is a logical identity — a string like agent-triage or agent-hello. It is the unit of tenancy: mailboxes, memory, mesh peers, secrets, and artifacts are all scoped to an agent_id.

An agent is not a user, a device, or a process. Many devices can speak for the same agent (a laptop and a CI runner sharing one mailbox), and one device key is always bound to exactly one agent.

Project bridge key​

The AGENTPACK_BRIDGE_KEY is a single high-privilege secret that the MTA, CI, and operator tooling hold. It lets the bearer call project-scoped routes like /ingest, /reap, /cert/record, and it can act on behalf of any agent.

Treat it like an AWS root key. Never ship it to a device.

Device key​

A device key (x-agentpack-device-key) is the per-install credential. It is minted by /device/issue, bound to a single agent_id, and shown in plaintext exactly once. Every edge function that accepts device keys rewrites agent_id on the request body to match the binding — a device key cannot spoof another agent even if the caller lies in the body.

Delegation​

A delegation is a narrow, time-boxed credential minted from a device key. It carries a list of scopes (e.g. postbox:read, postbox:send). It is meant for plugins, third-party clients, or dashboards that need a subset of a device's power. See /delegate.

Scope​

A scope is a named permission. Today's scopes live in the Postbox surface (postbox:read, postbox:send, postbox:admin) and gate which routes a delegation can reach. Scopes are validated at mint time (so typos fail loudly) and again at call time against DELEGATION_SCOPE_PATHS.

Capability token​

Capability tokens are Ed25519-signed JWT-ish bearer tokens minted by the Go identity service. The edge layer keeps the ledger (record, introspect, revoke) while the cold signing key stays on a dedicated host. This separation means the Firebase DB never sees the signing key.

Audit event​

Every sensitive action — token issue, revoke, bulk action, settings change — appends to audit.events. Rows are hash-chained: each row's prev_hash points at the previous row's hash. audit.verify_chain() walks the ledger and returns the first mismatch, if any.

Schema​

One Firestore collection per subsystem: identity, postbox, recall, mesh, gateway, scheduler, artifacts, governor, audit. Edge functions bind their Firebase client to a specific schema so cross-subsystem reads are always explicit.

Edge function​

A Deno function deployed to Firebase. Each function speaks problem+json, authenticates via custom headers, rewrites caller-scoped fields, and proxies into the corresponding schema's SQL RPCs. They are stateless; state lives in Firestore.

Cron job​

Cloud Scheduler drives retention, reconciliation, and scheduled work. All AgentPack jobs are named with the prefix agentpack_ so audit.cron_status() can report them as a single fleet.

Provenance​

Strings like user-direct-instruction, inbound-email:msg-uuid, or agent-reasoning attached to memory rows. Provenance is required on every memory write so the Governor can later trace a decision back to its source.