@clawboo/agent-registry


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 holds the RuntimeAdapter trait: the trait + types live here (zero deps, browser-safe), the concrete server-side implementations (OpenClawAgentSource, ClawbooNativeAgentSource) live in apps/web.

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. The two interfaces must not entangle.

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`’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: follows this package’s dependency-free record-mirroring discipline (referenced, not a runtime import).

Source

Barrel: 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

Reference

REST API

Packages

@clawboo/agent-registry

Public API

Classes

Constants

Types & interfaces

Used by

Source

See also

​Public API

​Classes

​Constants

​Types & interfaces

​Used by

​Source

​See also

Public API

Classes

Constants

Types & interfaces

Used by

Source

See also