add-event-source
Add a new agent source/provider to agent-office (e.g. LangGraph, OpenAI Agents SDK, OpenTelemetry GenAI spans, Claude Code hooks). Use when asked to support or ingest agents from another framework or
SKILL.md.claude/skills/add-event-source/SKILL.md
GitHubAdd an event source
Rules that apply: TESTING.md (TDD, ≥70%), ARCHITECTURE.md, PRIVACY_SECURITY.md.
First ask: can the producer just POST /api/events? If yes, document it in the README instead of adding code.
- Red —
packages/adapters/src/sources/<name>/*.test.ts: fixtures shaped like the real data with invented content. Test a pure mappertoEvent(raw, ctx): AgentEvent | null:- identity (
agentIdstable and namespaced, e.g.lg:<id>),parentIdfor sub-agents provider(the zone) andtopic(the row) — what would a user call this conversation?- status mapping onto
idle | thinking | tool | waiting | error | done - malformed input →
null
- identity (
- Green —
packages/adapters/src/sources/<name>/: a pure mapper plus a driving adapter withstart()/stop()/ a testabletick(). It depends only on core ports (ReportActivity, optionallyAgentInbox,Clock,Scheduler); put file/network access behind an adapter-local interface (likeTranscriptFiles) so it can be tested in memory. Never throw out oftick(). - Config — a setting in
shared/src/desktop-api.tsSettingsSchema(additive, with a default, and a restart field incore/src/domain/settings.ts), plus an env override inadapters/src/config.tsand.env.example. Start or stop it instartBackendindesktop/src/main/composition.ts. - E2E —
packages/adapters/test/e2e.<name>.test.ts: real source → real core →observe(office)sees the agent in the right zone and row. - Docs — README "Sources" section: what is read, what is ignored, privacy notes.
- Privacy check — only status, tool, title, model and ≤80-char snippets leave the source; nothing is logged raw.
make check(includingmake arch), then/run-officeto see the new zone.
Runtime-based providers (a CLI agent-office can also start and manage, such as Codex or an ACP agent): this skill is not enough. Follow the checklist in docs/provider-integrations.md §8 (declaration, profile or runner, probe, optional observation hooks, composition, contract suites).