agent-blackboard

agent-blackboard

Client library, CLI, and MCP server for agent-blackboard. Requires Node 24+ and talks to a separately deployed HTTP service over fetch.

See the complete TypeScript API reference for the supported public surface and tooling integration details.

pnpm add agent-blackboard

Library

import { Auth, Entries, Sessions, Snapshots } from 'agent-blackboard'

const config = { baseUrl, token }
const sessions = new Sessions(config)
const entries = new Entries(config)
const snapshots = new Snapshots(config)

await sessions.create({
  id: 'root-123',
  parentSessionId: null,
  agent: 'claude-code',
  version: '1.0.13',
})
await sessions.create({
  id: 'worker-456',
  parentSessionId: 'root-123',
  agent: 'claude-code',
  version: '1.0.13',
})
await sessions.patch({ sessionId: 'worker-456', data: { branch: 'fix/retry' } })

await entries.append({
  sessionId: 'worker-456',
  data: { note: 'found a flaky retry' },
})

for await (const current of entries.get({ sessionId: 'worker-456' })) {
  console.log(current)
}

await sessions.archive('worker-456')

// The JSONL file stays local; the result contains only its verification metadata and cleanup capability.
const snapshot = await snapshots.export({ selection: { agent: 'claude-code' } })
console.log(snapshot.path, snapshot.checksum.value, snapshot.cleanupToken)
const partitions = await snapshots.partition({
  path: snapshot.path,
  cleanupToken: snapshot.cleanupToken,
  checksum: snapshot.checksum,
})
await snapshots.cleanup({
  path: snapshot.path,
  directory: partitions.directory,
  cleanupToken: partitions.cleanupToken,
})

const auth = new Auth({ baseUrl, adminToken })
await auth.createCredentials({ name: 'ci-bot' })

Versions are caller-provided. Session ids and agent names are too, unless the caller opts into session-id resolution (resolveSessionIdentity, or omitting them in the CLI/MCP). parentSessionId is required and nullable. The service generates createdAt/lastEntryAt/archivedAt timestamps. Entries.get() returns an AsyncIterable<SessionEntry> and uses incremental JSONL by default. Non-2xx responses throw AgentBlackboardError. Use the root formatError(error) export when rendering a caught value for users; it includes an AgentBlackboardError response body when present and safely handles any value JavaScript can throw. Unserializable response bodies and unprintable thrown values use deterministic fallback text instead of throwing while reporting the error.

CLI

agent-blackboard sessions create root-123 --agent claude-code --version 1.0.13
agent-blackboard sessions create worker-456 --parent-session-id root-123 \
  --agent claude-code --version 1.0.13
agent-blackboard sessions patch worker-456 --data '{"branch":"fix/retry"}'
agent-blackboard sessions list
agent-blackboard sessions list --inactive-for-hours 8
agent-blackboard sessions get worker-456
agent-blackboard append --session-id worker-456 '{"note":"investigating"}'
agent-blackboard append --session-id worker-456 --file findings.md
agent-blackboard get --session-id worker-456 --format jsonl
agent-blackboard sessions archive worker-456
agent-blackboard snapshot export --root-only --inactive-for-hours 8
agent-blackboard snapshot partition --path /tmp/agent-blackboard-snapshot-<uuid>.jsonl \
  --cleanup-token <cleanup-token>
agent-blackboard snapshot cleanup --path /tmp/agent-blackboard-snapshot-<uuid>.jsonl \
  --directory /tmp/agent-blackboard-partitions-<suffix> --cleanup-token <cleanup-token>
agent-blackboard mcp

partition only accepts a generated temporary snapshot, preserves each session and its ordered entries as a single unit, and defaults to 25 sessions or 1 MiB per read-only partition. It can verify the export checksum and counts. Both commands require the capability returned in the generated export result; this keeps ownership authorization out of forgeable filenames or markers. cleanup removes either generated temporary artifact, or both. An explicit absolute snapshot export --path destination remains caller-owned and is never accepted by either command.

Generated names, private modes, capabilities, and identity checks reject substitutions visible at operation boundaries. The pure-Node package does not defend against a malicious concurrent process with the same operating-system user identity that swaps a pathname between those checks, so keep snapshot artifacts out of mutually untrusted same-UID process environments.

The published package includes the canonical provider plugin at dist/plugin; it is copied during the package build from this repository's plugins/agent-blackboard source, so no second tracked skill copy can drift.

MCP

The stdio MCP server exposes session_create, session_ensure, session_search, session_patch, session_archive, entry_append, entry_get, and snapshot_export. snapshot_export writes a private, read-only JSONL file and returns only its path, counts, checksum, and terminal manifest; it never puts snapshot records on the MCP connection. Every session and entry operation requires explicit session ids where applicable. Credential management remains CLI/admin-only.

Configuration

Variable	Used by	Meaning
AGENT_BLACKBOARD_URL	CLI/MCP	Service base URL
AGENT_BLACKBOARD_TOKEN	CLI/MCP	Client credential (abb_sk_...)
AGENT_BLACKBOARD_ADMIN_TOKEN	CLI credentials	Admin credential (abb_admin_...)

Client and admin tokens are never interchangeable.

License

MIT