Thanks to visit codestin.com
Credit goes to github.com

Skip to content

feat(connectors): emit connector.activation.changed for CLI/SDK activation writes (#1226)#1309

Merged
itomek merged 1 commit into
amd:mainfrom
alexey-tyurin:feat/emit-activation-changed-events
Jun 1, 2026
Merged

feat(connectors): emit connector.activation.changed for CLI/SDK activation writes (#1226)#1309
itomek merged 1 commit into
amd:mainfrom
alexey-tyurin:feat/emit-activation-changed-events

Conversation

@alexey-tyurin

@alexey-tyurin alexey-tyurin commented May 30, 2026

Copy link
Copy Markdown
Contributor

Summary

CLI and SDK activation toggles now drive the same live connector.activation.changed SSE update that the HTTP router already emitted, so the Agent UI's "Active for" panel reflects them without a manual refresh.

Why

Activation writes from gaia connectors activations activate/deactivate (CLI) and direct SDK calls landed in ~/.gaia/connectors/activations.json silently — only the HTTP PUT/DELETE handlers emitted connector.activation.changed. With the Agent UI Settings tab open, a CLI-driven toggle took effect on disk but the panel kept showing stale state until the user navigated away and back to force a refetch, making CLI ↔ UI workflows confusing. This was filed as an explicit follow-up on #1219.

Linked issue

Closes #1226

Changes

  • Centralized the emit (src/gaia/connectors/api.py). activate() / deactivate() now emit connector.activation.changed ({connector_id, agent_id, active}) after the ledger write, so HTTP, SDK, and any in-process caller all notify through one path — mirroring how feat(connectors): per-agent MCP tool-visibility activations (#1005) #1219 centralized the MCP-only guard in api.py.
  • New emit_change() helper (src/gaia/connectors/events.py). A sync, loop-aware fire-and-forget wrapper so synchronous callers (api, CLI) can publish without being async. Inside the server loop it schedules on that loop and fans out to SSE subscribers; in a bare process it runs against the registered emitter (the no-op logging emitter). Failures are logged, never swallowed.
  • Server-side ledger watcher (src/gaia/connectors/activation_watcher.py, new). The CLI runs in a separate process from the UI server, where the SSE bus lives. A background watcher polls activations.json, diffs against a snapshot, and emits one event per changed (connector, agent) pair (~1 s) so cross-process CLI/SDK writes reach connected UI clients. In-process writes call note_local_write(...) to advance the snapshot per-pair, so they don't double-emit — and a concurrent change to a different pair is still caught.
  • Watcher lifecycle (src/gaia/ui/server.py). Started/stopped in the FastAPI lifespan, mirroring the existing DocumentMonitor.
  • Router cleanup + guard fix (src/gaia/ui/routers/connectors.py). Removed the now-duplicate inline emits from PUT/DELETE; DELETE now routes through api.deactivate instead of the bare ledger call, closing a pre-existing MCP-only-guard bypass on that route.
  • Tests. New tests/unit/connectors/test_activation_watcher.py (diff, poll-emit, dedup, don't-mask-other-pair) and extended tests/unit/connectors/test_activation_api.py (CLI→SSE path: emits on success, nothing on failure/rejection).
  • Docs (docs/sdk/infrastructure/connectors.mdx). Updated the activation SSE section to describe the centralized emit + watcher. No frontend changes — useConnectorsSSE.ts already consumes connector.activation.changed.

Test plan

  • python util/lint.py --all — all quality checks pass (Black, isort, Pylint, Flake8 green; pre-existing MyPy/Bandit/agent-convention warnings only, none in touched files).
  • python -m pytest tests/unit/connectors/test_activation_api.py tests/unit/connectors/test_activation_watcher.py tests/unit/connectors/test_router_connectors.py — 77 passed.
  • python -m pytest tests/unit/connectors/ — 436 passed, 3 skipped.
  • Manual cross-process live update: start the UI server, open Settings → Connectors → expand an MCP connector's "Active for"; in a second terminal run gaia connectors activations activate mcp-github builtin:connectors-demo --scopes use → panel flips to active with no refresh; gaia connectors activations deactivate mcp-github builtin:connectors-demo → flips back live.

Follow-ups (not in this PR — gaps found while doing this work)

  • DispatchQueue worker logs after the test stream closes (pre-existing). Any UI test that boots a TestClient prints repeated --- Logging error --- ValueError: I/O operation on closed file blocks pointing at src/gaia/ui/server.py:267 (_import_modules logging the faiss-load line). Root cause: DispatchQueue.shutdown (src/gaia/ui/dispatch.py:104-105) calls self._executor.shutdown(wait=False), so a boot-init worker thread (the slow faiss import) is still running and logs after pytest closed the captured stream. Cosmetic (tests pass, exit 0) and reproduces on main with this PR stashed. Suggested fix: have shutdown drain in-flight boot jobs with a bounded wait, e.g. await loop.run_in_executor(None, lambda: self._executor.shutdown(wait=True, cancel_futures=True)) under a timeout, so no worker logs post-teardown.
  • StarletteDeprecationWarning: Using httpx with starlette.testclient is deprecated; install httpx2 (pre-existing, repo-wide). Emitted by any test using the shared ui_api_client TestClient fixture (origin tests/conftest.py:355); pytest dedupes it to a single "1 warning" line. Not introduced here (reproduces on main with this PR stashed). Suggested fix: bump to httpx2 per Starlette's guidance, or add a scoped filterwarnings entry in pyproject.toml.

Checklist

  • I have linked a GitHub issue above (Closes #1226).
  • I have described why this change is being made, not just what changed.
  • I have run linting and tests locally (python util/lint.py --all, pytest tests/unit/).
  • I have updated documentation if user-visible behavior changed (see CONTRIBUTING.md).

@github-actions github-actions Bot added documentation Documentation changes tests Test changes labels May 30, 2026
@github-actions

github-actions Bot commented May 31, 2026

Copy link
Copy Markdown
Contributor

Solid, focused PR that closes a real UX gap cleanly. The centralization strategy is correct, the dedup mechanism is provably race-free, and the tests cover all the edge cases that matter. Three cosmetic nits below, none blocking.

Summary

CLI/SDK activation writes now flow through api.activate/deactivate, which emit connector.activation.changed through a single path. The file watcher bridges the remaining cross-process gap (CLI is a separate process from the SSE bus). The note_local_write dedup is sound: because emit_change only schedules a task and note_local_write runs synchronously in the same call chain, the event loop can't interleave the watcher's poll_once between them — no double-emit race is possible.

Issues Found

🟢 _RecordingEmitter + recording_emitter fixture duplicated across two test files
(test_activation_api.py:73–99, test_activation_watcher.py:21–37)

Both files define identical classes and fixtures. These belong in tests/unit/connectors/conftest.py so future tests get them for free.

# tests/unit/connectors/conftest.py  (add alongside existing autouse fixtures)

class _RecordingEmitter:
    def __init__(self):
        self.events = []

    async def emit(self, event_type, payload):
        self.events.append((event_type, dict(payload)))


@pytest.fixture
def recording_emitter():
    """Capture events published through the connectors event bus."""
    from gaia.connectors import events

    rec = _RecordingEmitter()
    events.set_emitter(rec)
    try:
        yield rec
    finally:
        events.reset_emitter()

Then remove the duplicate class + fixture from both test files and import nothing — pytest discovers the conftest fixture automatically.

🟢 Issue references in inline comments (activation_watcher.py:48, test_activation_watcher.py:7)

CLAUDE.md: "Don't reference the current task, fix, or callers inline … they belong in the PR description and commit body." The (#1226) tags in the module docstring and test header comment will rot as the code evolves.

"""Background watcher that emits ``connector.activation.changed`` for
out-of-process activation writes.

"""Unit tests for the activation file-watcher.

🟢 deactivate() missing a logger.info that activate() has (src/gaia/connectors/api.py:347–353)

Pre-existing omission (not introduced here), but since this PR is already touching both functions it's a good moment to make them symmetric. No suggestion required — just noting it for awareness.

Strengths

  • emit_change handles both contexts correctly. Loop-present → create_task (non-blocking, logged on failure). Loop-absent → asyncio.run with exception logging. Neither path can break the caller's write.
  • Dedup is elegant and argument-free. note_local_write advances only the written pair, so a concurrent out-of-process change to a different pair is still detected — as test_note_local_write_does_not_mask_other_pair proves explicitly.
  • Test suite covers all meaningful scenarios — diff logic, poll-emit, dedup suppression, partial-pair isolation, failure-path emits nothing — with clean separation between TestDiffLedgers (pure) and TestPollOnce (async + I/O).
  • Router cleanup is a genuine improvement. delete_activation now routes through api.deactivate instead of bypassing the centralized guard, consistent with put_activation.

Verdict

Approve. The nits are cosmetic and don't affect correctness or behavior. The core implementation is well-reasoned, the dedup analysis is correct, and the test coverage is thorough. The fixture consolidation is a nice-to-have that can be done as a follow-up.

@alexey-tyurin alexey-tyurin mentioned this pull request May 31, 2026
Closed
3 tasks
@itomek itomek self-assigned this Jun 1, 2026
itomek
itomek approved these changes Jun 1, 2026
View reviewed changes

@itomek itomek left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve. I reproduced the test and lint evidence locally on the PR branch and traced the change against issue #1226's acceptance criteria; this is solid, well-scoped plumbing that does exactly what the description says.

Independent verification:

  • Reran the new suites on this branch: the 4 API emit tests (activate emits active:true, deactivate emits active:false, failed activate emits nothing, rejected-OAuth activate emits nothing) and the 5 watcher tests (external activate/deactivate, no-change emits nothing, note_local_write suppresses the duplicate, and note_local_write does not mask an unrelated pair) all pass — 27 passed across the two new/changed files, 316 passed / 3 skipped for the broader connectors suite. black + isort clean.
  • ACs mapped: AC1/AC2/AC4 are directly covered by the new unit tests; AC3 (live UI refresh without nav) is cross-process and only manually verifiable, which your PR body documents — TestPollOnce covers it indirectly. Good enough.
  • One note for anyone seeing local failures: test_router_connectors.py errors here from a missing python-multipart, but that reproduces on main too and CI's unit-test check is green — pre-existing env gap, not a PR defect.

One thing worth calling out as a strength: routing the DELETE path through deactivate_connector_for_agent(...) instead of the bare deactivate_agent(...) ledger call (routers/connectors.py:829) means the MCP-only activation guard that api.deactivate() enforces now also applies on the HTTP delete path — previously DELETE bypassed it. The description frames this as cleanup; can you confirm closing that guard gap on DELETE was intentional and not just an incidental side effect of the refactor? Worth a line in the body so it isn't lost.

One non-blocking question: in emit_change() the no-loop branch swallows the failure (except Exception: logger.exception(...)) rather than re-raising. I think that's the right call here — the SSE notification is non-transactional with respect to the committed ledger write, and you don't want a notification hiccup to fail an otherwise-successful write — so I'd keep it. Just flagging it against the "fail loudly" convention so it's a conscious choice; a one-line why-comment naming that invariant would settle it.

On the cosmetic points already raised in the automated review (the duplicated _RecordingEmitter/fixture, the inline (#1226) references, and the deactivate() log asymmetry) — I concur, no need to repeat them; worth folding into the same touch-up pass.

Nice that this cleanly unblocks the stacked #1310. Thanks @alexey-tyurin.

Generated by Claude Code

@itomek itomek added this pull request to the merge queue Jun 1, 2026
Merged via the queue into amd:main with commit 72390d8 Jun 1, 2026
26 checks passed
@kovtcharov-amd kovtcharov-amd mentioned this pull request Jun 1, 2026
Merged
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@itomek itomek itomek approved these changes
@kovtcharov-amd kovtcharov-amd Awaiting requested review from kovtcharov-amd kovtcharov-amd is a code owner

Assignees

@itomek itomek

Labels

documentation Documentation changes tests Test changes

Projects

None yet

Milestone

v0.20 — Test & CI Hardening [OSS]

Development

Successfully merging this pull request may close these issues.

feat(connectors): emit connector.activation.changed for CLI/SDK activation writes

2 participants

@alexey-tyurin @itomek