> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claw.boo/llms.txt
> Use this file to discover all available pages before exploring further.

# @clawboo/agent-registry

> The AgentSource trait, neutral agent/team/session record types, and the AgentRegistry multiplexer, the agent-registry-of-record seam.

|                    |                                                                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Version**        | `0.1.0`                                                                                                                                                                |
| **Purity**         | pure zero-dep (browser-safe; no `node:*`, no workspace runtime deps)                                                                                                   |
| **Purpose**        | The neutral record types + the `AgentSource` trait + the `AgentRegistry` multiplexer that make SQLite the agent-registry of record and OpenClaw one source among many. |
| **Workspace deps** | none                                                                                                                                                                   |
| **External deps**  | none (`@clawboo/tsconfig`, `tsup`, `typescript`, `vitest` are dev-only)                                                                                                |

This package answers a single question: *where does the agent list come from?*, and nothing else. It holds the clawboo-native record shapes (`AgentRecord`/`TeamRecord`/`SessionRecord`), the `AgentSource` interface (SQLite-backed reads that work when the upstream is down; writes + file I/O + sessions that route to the upstream and mirror into SQLite), and a thin `AgentRegistry` catalog. It deliberately mirrors how [`@clawboo/executor`](/reference/packages/executor) holds the `RuntimeAdapter` trait: the trait + types live here (zero deps, browser-safe), the concrete server-side implementations (`OpenClawAgentSource`, `ClawbooNativeAgentSource`) live in `apps/web`.

<Info>
  The concern boundary is hard: `AgentSource` is about **who exists** (the registry). It is NOT about **how agents run**; that is the `RuntimeAdapter` in [`@clawboo/executor`](/reference/packages/executor). The two interfaces must not entangle.
</Info>

One barrel, one subpath: `.` → `src/index.ts`. The package ships type-only exports plus two values (`AGENT_FILE_NAMES`, `AgentRegistry`).

## Public API

`.`: main barrel (`src/index.ts`)

### Classes

| Export          | Signature | Contract                                                                                                                                                                                                                                                                             |
| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AgentRegistry` | `class`   | Catalog of `AgentSource`s keyed by `RuntimeId`: `register(source)`, `unregister(id)`, `get(id)`, `has(id)`, `list()`, `default()`. `default()` returns the first registered source and throws when none are registered. Phase A holds exactly one source; mirrors `RuntimeRegistry`. |

### Constants

| Export             | Value                      | Contract                                                                                                                                                                                                                                                   |
| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENT_FILE_NAMES` | `readonly AgentFileName[]` | The seven agent files of record: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `TOOLS.md`, `HEARTBEAT.md`, `MEMORY.md`. A local literal that mirrors [`@clawboo/protocol`](/reference/packages/protocol)'s list so this package stays dependency-free. |

### Types & interfaces

| Export              | Kind       | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AgentRecord`       | interface  | The neutral agent shape the rest of the codebase reads (via `AgentSource` / `GET /api/agents`), NOT the OpenClaw protocol shape. Each field is documented Gateway-synced (overwritten every sync) vs SQLite-native (clawboo-owned, preserved across re-sync). Carries `id`/`sourceId`/`sourceAgentId`, merged display fields, live runtime state, clawboo-native config (`teamId`/`personalityConfig`/`execConfig`), the dormant `participantKind`/`runtime`/`capabilities`/`tenantId` seams, and the `archivedAt` soft-delete tombstone. |
| `AgentRecordStatus` | union type | `'idle' \| 'running' \| 'error' \| 'sleeping' \| 'archived'`, a superset of the Gateway's status plus the clawboo-owned `archived` tombstone.                                                                                                                                                                                                                                                                                                                                                                                             |
| `ParticipantKind`   | union type | `'agent' \| 'human'`, open-set; `'human'` is a dormant seam (no human path yet).                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `RuntimeId`         | union type | `'openclaw' \| 'claude-code' \| 'codex' \| 'hermes' \| (string & {})`, known runtime ids as autocomplete hints over an open `string` set. `'openclaw'` is the only live source today (the native source registers under its own id).                                                                                                                                                                                                                                                                                                      |
| `TeamRecord`        | interface  | `{ id, name, icon, color, colorCollectionId, templateId, leaderAgentId, isArchived, agentCount, tenantId, createdAt, updatedAt }`. `agentCount` is computed (mirrors the `teamsGET` subquery); `tenantId` is the dormant multi-tenant seam.                                                                                                                                                                                                                                                                                               |
| `SessionRecord`     | interface  | `{ id, sourceId, sourceSessionId, agentId, teamId, status: 'active' \| 'idle' \| 'closed', createdAt, updatedAt }`. `sourceSessionId` is the upstream (OpenClaw) session key.                                                                                                                                                                                                                                                                                                                                                             |
| `AgentSource`       | interface  | The registry-of-record seam. Reads (`listAgents`/`getAgent`/`listTeams`) are SQLite-backed and work offline; `listSessions` delegates live to the upstream. Writes (`createAgent`/`updateAgent`/`archiveAgent`) + file I/O (`readFile`/`writeFile`) require a live upstream. Lifecycle: `start`/`stop`/`health`/`sync` + `events(): AsyncIterable<AgentEvent>` (consumer-terminated, mirrors `RuntimeAdapter.events()`). `readonly id: RuntimeId`.                                                                                        |
| `AgentFileName`     | union type | The seven agent-file names that `AGENT_FILE_NAMES` enumerates; the `:name` validated by the agent-files REST routes.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `CreateAgentInput`  | interface  | `{ name, teamId?, personalityConfig?, execConfig?, avatarSeed?, files? }`; `files` is `Partial<Record<string, string>>` (agent files written at create time).                                                                                                                                                                                                                                                                                                                                                                             |
| `UpdateAgentInput`  | interface  | `{ displayName?, teamId?, personalityConfig?, execConfig?, avatarSeed?, status? }`, partial patch.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `HealthResult`      | interface  | `{ ok, connection: 'connected' \| 'connecting' \| 'reconnecting' \| 'disconnected', lastSyncedAt, message? }`.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `SyncResult`        | interface  | `{ upserted, archived, durationMs, at }`, the outcome of an idempotent upstream→SQLite reconcile. `archived` counts agents present in SQLite but gone upstream.                                                                                                                                                                                                                                                                                                                                                                           |
| `AgentEvent`        | union type | A live registry change: `agent-upserted`, `agent-status`, `agent-archived`, `sync-complete`, `connection`. Each carries `at` (epoch ms) plus its payload.                                                                                                                                                                                                                                                                                                                                                                                 |

## Used by

* **`apps/web/server/lib/agentSource/`**: `registry.ts` constructs the `AgentRegistry`; `openClawAgentSource.ts` and `clawbooNativeAgentSource.ts` implement `AgentSource` and emit `AgentEvent`/`SyncResult`/`HealthResult`.
* **`apps/web/server/api/agents.ts`**: imports `AGENT_FILE_NAMES` + `AgentFileName` (validates the `:name` route param) and the `AgentSource` type for the REST handlers.
* **`apps/web/src/lib/agentSourceClient.ts`**: the browser-side REST client types its calls with `AgentRecord`/`SessionRecord`/`AgentFileName`.
* **[`@clawboo/capability-registry`](/reference/packages/capability-registry)**: follows this package's dependency-free record-mirroring discipline (referenced, not a runtime import).

## Source

* Barrel: [`packages/agent-registry/src/index.ts`](https://github.com/clawboo/clawboo/blob/main/packages/agent-registry/src/index.ts)
* Records: `packages/agent-registry/src/records.ts`
* Trait: `packages/agent-registry/src/source.ts`
* Registry: `packages/agent-registry/src/registry.ts`

## See also

* [AgentSource registry of record (internals)](/internals/agent-source)
* [Agents REST API](/reference/rest-api/agents)
* [Agent model concept](/concepts/agent-model)
* [@clawboo/executor](/reference/packages/executor), the sibling `RuntimeAdapter` trait
* [Package overview](/reference/packages/index)