integrations package

Reviewed against commit 8a2cb42ad on 2026-10-23.

Reference: package page (4 modules, 1,099 lines) · modules: fireflies_client, fireflies_sync, cheetahclaws. The gateway handler and the knowledge graph consume these adapters; see the overview for the wider system.

The story

Most of orchestrata-ultimate is inward-facing: volks talk to each other over CXP, the kernel dispatches work, and the knowledge graph remembers what happened. But some knowledge and some commands originate outside the system, and something has to translate at the boundary. That is the entire job of orchestrata_ultimate.integrations — a deliberately small package (its docstring reads simply "Integration adapters for external APIs and services") that bridges Orchestrata to two external worlds: the Fireflies meeting-transcript service and the CheetahClaws terminal UI. The two live side by side but point in opposite directions — one pulls knowledge in, the other lets an external tool drive agents from the outside.

The Fireflies side is a read/write pair. fireflies_client.py defines FirefliesClient, an async GraphQL client built on httpx that lists, fetches, searches, and summarizes meeting transcripts against https://api.fireflies.ai/graphql. Every public method carries a @traces decorator tying it to SPEC-018 requirements, and every method degrades gracefully: with no API key it returns an empty, well-shaped result rather than raising, and on any httpx.HTTPError or GraphQL errors payload it returns the same shape with an added error key. On top of the client sits fireflies_sync.py: FirefliesKnowledgeSync is the write-side of SPEC-018. It pulls recent transcripts together with their AI summaries through the client and upserts them into the operational graph (orchkg; Neo4j until its retirement on 2026-07-27) as idempotent :Document nodes via a single MERGE keyed on a deterministic ff_transcript_{id} id — so re-running a sync updates rather than duplicates. The effect is that a meeting held yesterday becomes a first-class, queryable citizen of the knowledge graph today, sitting alongside code entities and session facts. The syncer deliberately owns no scheduling and never builds its own graph repository: a gateway fireflies.sync RPC, a cron poller, or a CLI command is expected to be a thin wrapper that injects the shared AsyncGraphRepository and calls it.

The CheetahClaws side points the other way. The cheetahclaws/ subpackage (SPEC-050, FR-001..FR-015) is a single module implementing UltimateTUI, which wires 40+ CC slash commands to Orchestrata's kernel and agents. Its headline path is /edit: an edit request first passes through a GovernanceBridge — a PAM++ pre-edit gate that rejects missing files, directories, oversized (>10MB) or binary files, secret-looking names, and blocked path patterns like .env, .git/, or credentials. Only if governance allows does MultiAgentCoordinator fan the review out in parallel over CXP to several volks (U:Cd for correctness, U:Qa for tests, U:Ar for architecture, and U:Ux when the file is frontend). Each volk answers with an AgentFeedback carrying an AgentVerdict, and the coordinator aggregates them under a fail-closed rule: an edit commits only if every dispatched reviewer explicitly approved. A BLOCK, an ERROR, or even a TIMEOUT (which is what an unhandled review looks like) all withhold approval — there is no silent pass-through. Only after a clean sweep does UltimateTUI actually write the file to disk and return a populated EditResult with the diff and byte delta.

That flow explains the package's neighbours. The Fireflies modules lean only on core (the traces decorator), httpx, and — at write time — the operational graph via the shared graph repository. The CheetahClaws module imports cxp packets eagerly and lazily reaches into the orchestrator (PipelineRouter to resolve volk classes, PipelineRunner for the /intent full-pipeline command) and llm.config (for the /agents and /model commands) — deferred imports that keep the module cheap to load. Coverage lives in tests/integrations/test_fireflies_client.py, tests/knowledge_graph/test_fireflies_sync.py, and the end-to-end tests/integrations/test_cheetahclaws.py.

Key responsibilities

• Fireflies read access — FirefliesClient is the async GraphQL boundary for listing, fetching, searching, and summarizing meeting transcripts, with graceful (never-raising) degradation when the API key is absent or the call fails.
• Fireflies → graph ingestion — FirefliesKnowledgeSync upserts transcripts + AI summaries into the operational graph as idempotent :Document nodes (SPEC-018 write-side), keyed on a deterministic id so re-syncs never duplicate.
• CheetahClaws command routing — UltimateTUI maps CC slash commands (/edit, /intent, /read, /write, /agents, /model) onto Orchestrata kernel + agent actions (SPEC-050).
• Pre-edit governance — GovernanceBridge enforces PAM++ file-operation policy (existence, size, binary/secret detection, blocked paths) before any edit reaches an agent.
• Parallel multi-agent review — MultiAgentCoordinator dispatches an edit to Cd/Qa/Ar/Ux over CXP in parallel and applies a fail-closed approval gate: BLOCK, TIMEOUT, and ERROR all withhold approval.
• Traceability — every public method is @traces-decorated to keep the implementation linked to SPEC-018 / SPEC-050 requirements.

Class diagram

Fireflies cluster

The read client and its write-side syncer. FirefliesKnowledgeSync fetches through a FirefliesClient and writes :Document nodes through an injected AsyncGraphRepository (it never constructs its own). Generated from the real AST, render-verified:

CheetahClaws cluster

The command handler UltimateTUI composes a MultiAgentCoordinator and a GovernanceBridge. Reviews travel as EditRequest records; each volk returns an AgentFeedback whose verdict is an AgentVerdict (the package's lone StrEnum), and the coordinator folds them into an EditResult. Render-verified:

Module dependency diagram

What each module imports. traces and httpx/cxp_packet are eager; the orchestrator and llm imports inside cheetahclaws are lazy (function-local) to keep the module cheap to import. Render-verified:

Module inventory

fireflies_client.py

FirefliesClient is the read-side boundary to Fireflies — an async GraphQL client built on httpx. Construction takes an optional api_key (falling back to FIREFLIES_API_KEY from an injected env mapping or os.environ), an endpoint, an optional pre-built httpx.AsyncClient (for tests), and it tracks whether it owns that client so close() only closes clients it created. Its four public queries — list_transcripts, get_transcript, search_transcripts, summarize_transcript — each go through a private _request helper that attaches the bearer token and parses the JSON body. Two design points are load-bearing: with no API key each method short-circuits to an empty, correctly-shaped dict (never a raise), and on a GraphQL errors payload or an httpx.HTTPError each returns that same shape with an added error key and logs a warning. get_transcript additionally flattens the transcript's sentences into segments, a joined text, and a de-duplicated speakers list. Every public method is @traces-decorated (SPEC-018 / US-006). Its primary in-tree consumers are the gateway's FirefliesHandler (interactive queries) and FirefliesKnowledgeSync (the fetch layer during ingestion).

fireflies_sync.py

Where the client fetches on demand, this module persists. FirefliesKnowledgeSync implements the write-side of SPEC-018. It holds an optional FirefliesClient (needed only by sync_recent), a required, always-injected AsyncGraphRepository, and an optional tags dict merged into every node (e.g. a sync batch id). sync_recent(limit) lists recent transcripts, and for each one fetches the full transcript plus its summary and calls inject_transcript; a failure on any single transcript is caught and appended to an errors list so one bad meeting never aborts the whole batch, and the method returns {"synced": n, "node_ids": [...], "errors": [...]}. inject_transcript(transcript_id, transcript, summary) builds a :Document property bag and upserts it with a MERGE (d:Document {id: $id}) keyed on the deterministic ff_transcript_{id} — idempotent by construction. A small module-level _str_list(value) helper coerces list-ish API fields into the primitive string arrays the graph allows, JSON-encoding any non-string items. The module owns no scheduling: triggers are expected to be thin wrappers that inject the shared repo and call it (tests/knowledge_graph/test_fireflies_sync.py).

cheetahclaws/init.py

The CheetahClaws integration is a single-module subpackage implementing SPEC-050 (FR-001..FR-015). Four dataclasses/enums carry the state — AgentVerdict (a StrEnum: APPROVE / BLOCK / SUGGEST / TIMEOUT / ERROR), AgentFeedback, EditRequest, and EditResult — and three classes carry the behaviour:

• UltimateTUI is the command handler. route_command maps CC slash commands (/edit, /intent, /read, /write, /agents, /model) onto handlers; handle_edit runs the governed, multi-agent edit path; handle_intent shells the text through a full PipelineRunner (Concierge → BA → PM → Ar → Cd → QA → Cp). It owns a MultiAgentCoordinator and a GovernanceBridge.
• GovernanceBridge is the PAM++ pre-edit gate. can_edit(file_path) returns (allowed, reason), rejecting non-existent paths, directories, files over 10MB, binary files (null-byte sniff), secret-looking filenames, and any path containing a BLOCKED_PATTERNS entry (.env, .git/, credentials, id_rsa, …).
• MultiAgentCoordinator dispatches the review. dispatch_review sends a CXP packet to each chosen agent (EDIT_AGENTS = Cd/Qa/Ar, plus Ux for frontend files) in parallel with a per-agent timeout, lazily resolving volk classes through PipelineRouter. rejecting_feedback is the fail-closed gate: it returns the feedback whose verdict is in NON_APPROVING_VERDICTS (BLOCK, TIMEOUT, ERROR) — an empty result means every agent approved (SUGGEST is non-blocking). Because an unhandled review comes back as TIMEOUT, a dispatch no volk actually handles fails closed rather than silently letting the edit through.

The whole path — CC command in, governed multi-agent verdict out — is exercised end-to-end in tests/integrations/test_cheetahclaws.py.

Class map (generated)

Generated from the live source AST by scripts/gen-module-class-diagrams.py — do not hand-edit. Abstract classes have a green border; members listed are those defined on the class itself (inherited members excluded). Solid empty-triangle arrows = in-package inheritance; dashed arrows into dashed boxes = external/stdlib/cross-package bases; filled diamond = composition (constructed in __init__); open diamond = aggregation (annotated/injected reference); diamond edge labels name the owning attribute.