Skip to main content
Version0.1.0
Puritypure zero-dep (browser-safe; no node:*, no workspace runtime deps)
PurposeThe neutral record types + the AgentSource trait + the AgentRegistry multiplexer that make SQLite the agent-registry of record and OpenClaw one source among many.
Workspace depsnone
External depsnone (@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

ExportSignatureContract
AgentRegistryclassCatalog of AgentSources 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

ExportValueContract
AGENT_FILE_NAMESreadonly 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

ExportKindContract
AgentRecordinterfaceThe 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.
AgentRecordStatusunion type'idle' | 'running' | 'error' | 'sleeping' | 'archived', a superset of the Gateway’s status plus the clawboo-owned archived tombstone.
ParticipantKindunion type'agent' | 'human', open-set; 'human' is a dormant seam (no human path yet).
RuntimeIdunion 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).
TeamRecordinterface{ 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.
SessionRecordinterface{ id, sourceId, sourceSessionId, agentId, teamId, status: 'active' | 'idle' | 'closed', createdAt, updatedAt }. sourceSessionId is the upstream (OpenClaw) session key.
AgentSourceinterfaceThe 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.
AgentFileNameunion typeThe seven agent-file names that AGENT_FILE_NAMES enumerates; the :name validated by the agent-files REST routes.
CreateAgentInputinterface{ name, teamId?, personalityConfig?, execConfig?, avatarSeed?, files? }; files is Partial<Record<string, string>> (agent files written at create time).
UpdateAgentInputinterface{ displayName?, teamId?, personalityConfig?, execConfig?, avatarSeed?, status? }, partial patch.
HealthResultinterface{ ok, connection: 'connected' | 'connecting' | 'reconnecting' | 'disconnected', lastSyncedAt, message? }.
SyncResultinterface{ upserted, archived, durationMs, at }, the outcome of an idempotent upstream→SQLite reconcile. archived counts agents present in SQLite but gone upstream.
AgentEventunion typeA 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

​
See also