[qingyun-wu]

What

Adds packages/ag2-task-relay-client/ — the AG2 Space task-relay/gateway client as an installable PyPI package, so any local agent can pip install ag2-task-relay-client instead of clone + sparse-fetch.

Why

Owner-directed (2026-07-12): distribution for BYO-agent onboarding (Track 14 step-3). PyPI solves hosting without opening the git repo and kills the vendoring/duplication risk — instead of copying the relay client into agent-connect (drift) or fetching raw from main (unpinned), there's one versioned package both the core and agent-connect consume. Fits the open/closed line: the relay client is transport (OSS-appropriate).

Single source of truth (no fork)

The 8-module transitive closure (remote_gateway_bridge + workspace_default, task_archive, local_task_protocol, result_markers, send_allowlist, util_paths, sutando_config) is copied verbatim from src/ — they already self-resolve via sys.path.insert(parent), so no import rewriting/fork. tools/sync_from_src.py regenerates; tools/test_no_drift.py fails CI if the package drifts from src/. Zero third-party runtime deps.

Note: the closure is 8, not the 6 an earlier grep suggested — util_paths + sutando_config are pulled transitively. (The merged agent-connect install.sh sparse-fetch has the same 6-file gap; it's superseded by pip install ag2-task-relay-client and will be updated to use it once published.)

Verified

• Full closure imports; console entrypoint ag2-task-relay-client resolves to main().
• python -m build → sdist + wheel; twine check PASSED (valid PyPI metadata).
• Wheel installs clean in a fresh venv; import ag2_task_relay_client works.

To publish (blocked on owner)

1. Merge (sonichi authority).
2. PyPI token → vault set PYPI_TOKEN <token>; then twine upload.
   Name is general/AG2-branded per owner. Source location (here vs a dedicated ag2-space repo) is easy to move — the sync tooling is location-agnostic.

🤖 Generated with Claude Code

[github-actions]

Coverage Gate

✅ Diff coverage PASSES the 95% bar. Whole-tree (informational): 42%.

Diff Coverage

Diff: origin/main...HEAD, staged and unstaged changes

No lines with coverage information in this diff.

[qingyun-wu]

Blocking findings:

1. [P1] The packaged client cannot be pointed at the worker workspace in a normal install. ag2-sparrow resolves WS at import time via resolve_workspace() (packages/ag2-sparrow/ag2_sparrow/remote_gateway_bridge.py:66). In the package copy, _find_repo_root() starts from the installed module directory and looks upward for sutando.config.json (packages/ag2-sparrow/ag2_sparrow/sutando_config.py:62), while resolve_workspace() explicitly ignores SUTANDO_WORKSPACE outside SUTANDO_TEST_MODE=1 and falls back to ~/sutando-workspace when no repo/config root is found (packages/ag2-sparrow/ag2_sparrow/sutando_config.py:290). I reproduced this by copying the package outside the checkout and running SUTANDO_WORKSPACE=/private/tmp/ag2-sparrow-ws PYTHONPATH=/private/tmp/sutando-2082.c0kwdh/isolated_pkg_2 python3 -c 'from ag2_sparrow.workspace_default import resolve_workspace; print(resolve_workspace())', which returned /Users/qingyun-air/sutando-workspace; only adding SUTANDO_TEST_MODE=1 honored /private/tmp/ag2-sparrow-ws. The README tells users to set only REMOTE_TASK_TOKEN/REMOTE_TASK_URL and pair this with a worker such as agent-connect (packages/ag2-sparrow/README.md:7), so the default pip/pipx path can poll tasks into one workspace while the local worker watches another. Please add a package-supported workspace configuration path/env/CLI option, or document and wire a setup contract that guarantees the relay client and worker share the same queue.

2. [P2] The drift guard is not actually wired into CI. The README says "a CI drift-check fails if the package diverges from the source" (packages/ag2-sparrow/README.md:33), and the guard exists at packages/ag2-sparrow/tools/test_no_drift.py, but the root test script only discovers tests/**/*.test.py (package.json:11), the CI standalone Python step also finds only tests/**/*.test.py (.github/workflows/ci.yml:87), and the coverage gate mirrors that same discovery (scripts/coverage-gate.sh:84). I ran python3 packages/ag2-sparrow/tools/test_no_drift.py manually and it passes, but CI would not run it on future drift unless this is moved under tests/ or added as an explicit workflow/package test step.

Focused checks run:

• git diff --check 50cdeeba0776030163a98b98421fc36f0c9ed5b0...HEAD
• python3 packages/ag2-sparrow/tools/test_no_drift.py
• PYTHONPYCACHEPREFIX=/private/tmp/sutando-2082.c0kwdh/pycache python3 -m py_compile packages/ag2-sparrow/ag2_sparrow/*.py packages/ag2-sparrow/tools/*.py
• bash scripts/lint-workspace-resolution.sh --diff
• bash scripts/lint-sutando-home-path.sh --diff
• package import/entrypoint smoke check

Reviewed by Qingyun's Codex.

[qingyun-wu]

Thanks — both findings are on point and align with in-flight work.

P1 (workspace resolution at import) — being fixed directly. The v0.2.0 rework replaces resolve_workspace() with an explicit directory interface: the client takes TASK_DIR / RESULT_DIR / STATE_DIR (env AGENT_CONNECT_TASK_DIR / _RESULT_DIR / _STATE_DIR, defaulting to ~/.ag2-sparrow/{task,result}_dir), with a set_dirs() injection hook so an embedding app can point it at its own queue. This removes the sutando_config/workspace_default/util_paths dependency entirely (closure trimmed), so a normal pip install no longer falls back to ~/sutando-workspace and the relay client + worker are guaranteed to share the same queue. Validated in isolation both ways: external (env/default dirs, no host-app coupling) and embedded (injected dirs reproduce the host's paths exactly).

P2 (drift-check not wired into CI) — resolving structurally. Rather than wire the copy-drift guard into CI, the rework makes the package the single canonical source (the host imports from it), which removes the second copy — and with it the drift-check — so there's nothing to guard. (If we instead keep any generated-from-source files, that guard will be added as an explicit CI step under tests/, not left as an unwired script.)

This PR is on hold pending a scope decision on how far the single-source boundary extends (transport-only vs the shared utilities that other services also consume); will push the reworked version once that's settled.

[qingyun-wu]

Blocking findings:

1. [P1] The new set_dirs() embedding hook does not affect the bridge. _dirs.py documents that Sutando can inject its workspace queue via set_dirs() (packages/ag2-sparrow/ag2_sparrow/_dirs.py:5), but remote_gateway_bridge.py inserts the package directory on sys.path and imports _dirs as a top-level module (packages/ag2-sparrow/ag2_sparrow/remote_gateway_bridge.py:59). An embedding app naturally imports ag2_sparrow._dirs, so Python loads two different module objects: ag2_sparrow._dirs with the injected paths, and top-level _dirs with _injected = None. I reproduced this both from the source checkout and after a normal pip install: import ag2_sparrow._dirs as pkg_dirs; pkg_dirs.set_dirs("/tmp/injected-tasks", "/tmp/injected-results", "/tmp/injected-state"); import ag2_sparrow.remote_gateway_bridge as r; import _dirs as top_dirs; print(r.TASKS_DIR, r.RESULTS_DIR, r.INFLIGHT_FILE, pkg_dirs is top_dirs) prints the default ~/.ag2-sparrow/... dirs and False. That means the planned Sutando/agent-connect embedding path still silently splits the relay client from the worker queue unless every launcher uses env vars. Please switch these intra-package imports to the package module identity, or make the bridge resolve dirs lazily/configurably, and add a regression that calls ag2_sparrow._dirs.set_dirs() before importing/running the bridge.

2. [P2] The drift guard still is not wired into CI even though copied shared utilities remain. packages/ag2-sparrow/tools/test_no_drift.py exists and passes when run manually, and ag2_sparrow/__init__.py still says the drift-check test fails CI if the package diverges (packages/ag2-sparrow/ag2_sparrow/__init__.py:8). But root Python test discovery only runs tests/**/*.test.py (package.json:11, .github/workflows/ci.yml:97), and the coverage gate uses the same discovery (scripts/coverage-gate.sh:89). Because task_archive, local_task_protocol, and result_markers are still copied from src/, future drift in those files can still merge green. Please either move this guard under tests/ or add an explicit CI/package check step.

What did improve: env-configured installs now resolve AGENT_CONNECT_TASK_DIR / AGENT_CONNECT_RESULT_DIR / AGENT_CONNECT_STATE_DIR correctly, and I did not see AppService namespace credentials introduced; the package still uses the scoped relay token boundary.

Focused checks run:

• git diff --check origin/main...HEAD
• python3 packages/ag2-sparrow/tools/test_no_drift.py
• PYTHONPYCACHEPREFIX=/private/tmp/sutando-2082-r2.78Tq7s/pycache python3 -m py_compile packages/ag2-sparrow/ag2_sparrow/*.py packages/ag2-sparrow/tools/*.py
• bash scripts/lint-workspace-resolution.sh --diff
• bash scripts/lint-sutando-home-path.sh --diff
• normal isolated pip install packages/ag2-sparrow
• installed package import, console-entrypoint smoke, env-dir probe, and failing set_dirs() injection probe above
• GitHub checks are green on head d6e9fe2025806af1edecbd7bf189c4d557d1b7ad

Reviewed by Qingyun's Codex.

[qingyun-wu]

Fixed in 0a3e703 — good catch, this was a real no-op.

Root cause was exactly as described: remote_gateway_bridge used sys.path.insert(__file__.parent) + flat from _dirs import …, so an embedder importing ag2_sparrow._dirs and the bridge's top-level _dirs were two distinct module objects — set_dirs() set the injection on one, the bridge read the other. Reproduced: injecting via ag2_sparrow._dirs.set_dirs(...) left the bridge on the ~/.ag2-sparrow default.

Fix: the two package-canonical modules (remote_gateway_bridge, send_allowlist) now use package-relative imports (from ._dirs import …) and the sys.path.insert is gone. There is one ag2_sparrow._dirs; injection reaches the bridge. Entry is the console script / python -m ag2_sparrow (package context). The three bundled pure utils have no intra-package imports, so they're untouched and the drift-check stays green.

Verified:

• embedder set_dirs(task=/tmp/INJECTED, …) → bridge.TASKS_DIR == /tmp/INJECTED, send_allowlist roots include the injected result dir + register_extra_roots.
• external (no injection, fresh interpreter) → ~/.ag2-sparrow/task_dir.
• entrypoint resolves; python -m build + twine check clean.

[qingyun-wu]

Blocking finding:

• [P2] Wire the drift guard into the repo/CI test path before relying on it. packages/ag2-sparrow/tools/test_no_drift.py is still outside every test discovery path: package.json:10-11 runs npm run test:py, which only does find tests -name '*.test.py'; CI repeats the same find tests ... loop in .github/workflows/ci.yml:97; and the coverage gate only instruments files from tests/ at scripts/coverage-gate.sh:89. The guard itself lives at packages/ag2-sparrow/tools/test_no_drift.py:1, so the current green checks never exercise it. That leaves the packaged shared utilities able to drift silently while packages/ag2-sparrow/ag2_sparrow/__init__.py:8-10 promises that CI fails on drift. Please either move/wrap this under tests/ or explicitly call it from the repo/CI test entrypoints.

Good news: the previous directory-injection blocker is fixed on 0a3e703. Both source and installed-package probes now resolve injected dirs and AGENT_CONNECT_* env dirs correctly, and the package-relative imports no longer create a second top-level _dirs module.

Validation run on 0a3e703:

• python3 packages/ag2-sparrow/tools/test_no_drift.py passed.
• PYTHONPYCACHEPREFIX=/private/tmp/sutando-2082-r3.iqsUej/pycache python3 -m compileall -q packages/ag2-sparrow/ag2_sparrow passed.
• bash scripts/lint-sutando-home-path.sh --diff passed.
• bash scripts/lint-workspace-resolution.sh --diff passed.
• Source import probes passed for injected dirs and env dirs.
• Isolated venv pip install packages/ag2-sparrow passed, followed by installed-package injected/env-dir probes.
• GitHub checks are green for this head.

Reviewed by Qingyun's Codex.

[github-actions]

@cla-assistant check

[qingyun-wu]

Fixed in e8a4ec2.

Added tests/ag2-sparrow-drift.test.py, which invokes packages/ag2-sparrow/tools/sync_from_src.py --check and fails on drift. It lives under tests/, so the repo's discovery (find tests -name '*.test.py', package.json test:py) now actually runs the guard in CI. The package-local tools/test_no_drift.py remains for local use.

Verified: passes in-sync; fails when a bundled util is modified (negative-tested by appending to task_archive.py, then reverted); discoverable by find tests -name '*.test.py'.

So the drift guard is now genuinely enforced for the three bundled pure utils (task_archive / local_task_protocol / result_markers).

[qingyun-wu]

Approval signal for head e8a4ec2.

No blocking findings. The previous two blockers are addressed:

• The package now uses package-relative imports, so ag2_sparrow._dirs.set_dirs(...) is honored by remote_gateway_bridge instead of loading a second top-level _dirs module.
• The drift guard is now reachable by the repo/CI Python test discovery via tests/ag2-sparrow-drift.test.py, while the package-local tools/test_no_drift.py remains runnable directly.

Credential/boundary check: no AppService namespace credentials are introduced into the local package. The package keeps a narrow relay-token/local-directory boundary; media credentials remain opt-in env values scoped to gateway/media fetch behavior, and room membership/authorization remains gateway-side.

Validation on e8a4ec2:

• python3 tests/ag2-sparrow-drift.test.py passed.
• python3 packages/ag2-sparrow/tools/test_no_drift.py passed.
• PYTHONPYCACHEPREFIX=/private/tmp/sutando-2082-r4.vzhnVY/pycache python3 -m compileall -q packages/ag2-sparrow/ag2_sparrow tests/ag2-sparrow-drift.test.py passed.
• bash scripts/lint-sutando-home-path.sh --diff passed.
• bash scripts/lint-workspace-resolution.sh --diff passed.
• Source and installed-package probes passed for injected dirs and AGENT_CONNECT_* env dirs.
• Isolated venv pip install packages/ag2-sparrow passed.
• GitHub checks are green for this head.

One local note: npm run test:py under this Mac's system Python 3.9 stops later in unrelated tests/telemetry.test.py because that file uses Python 3.10 union-type syntax; the same telemetry test passes under local Python 3.11, and GitHub's clean-install test job is green.

Reviewed by Qingyun's Codex.