docs(agent-workflows): subscription-sidecar recipe: compose network, internal API URL, extension rebuild

[mmabrouk]

Context

This PR is now docs-only. It originally fixed the agent service's handler registration: the SDK statically seeds a bare default handler for agenta:builtin:agent:v0, and because register_handler used setdefault, the service's real handler (with tracing, credentials, and capability gating) was silently ignored. Every invoke ran the bare handler, which caused missing trace ids, session-persist 401s from the sidecar, and a capability-gating bypass.

JP's #5081 fixed the same root cause upstream, in a simpler form: register_handler now always replaces, and the bare handler itself became ambient-aware. This branch has been reverted to those merged semantics and its now-obsolete regression test deleted.

What remains

One file: the subscription-sidecar recipe (docs/design/agent-workflows/projects/subscription-sidecar/README.md, +13 lines). It captures two operational facts we learned while live-debugging the 401s, and they exist nowhere else:

1. The ad-hoc sidecar container must join the app stack's compose network and set AGENTA_API_INTERNAL_URL=http://api:8000, so the runner's session calls (persist, heartbeat, interactions) reach the API over the direct network hop and authenticate correctly.
2. A sidecar that mounts the runner source must rebuild the Pi extension at startup (node scripts/build-extension.mjs). Its startup command does not do this today, so a plain restart loads a stale bundle.

How to review

Read the README diff. Check the two facts against your own sidecar setup; both were validated live on the dev box on 2026-07-05/06.

https://claude.ai/code/session_014iPB7HL5PjgT9npyPHaFMT

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 6, 2026 1:00pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a47cdc3e-02e0-40e4-873b-180fd66e1d0e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a keyword-only replace parameter to register_handler in the Python SDK, enabling explicit overwrite of existing registry entries versus default first-writer-wins behavior. The agent service now overrides the SDK-seeded builtin handler using replace=True. New unit tests cover both behaviors. A README documents updated sidecar docker networking configuration.

Changes

Handler Registry Replace Semantics

Layer / File(s)	Summary
register_handler replace parameter sdks/python/agenta/sdk/engines/running/utils.py	Adds keyword-only replace: bool = False; registration logic branches to overwrite (bucket[version] = fn) or preserve existing (bucket.setdefault(version, fn)) behavior, with updated docstring.
Agent service handler override services/oss/src/agent/app.py	Registers the instrumented _agent handler for agent:v0 with replace=True, overriding the SDK-seeded default, with comments explaining consequences of not overriding (missing telemetry, 401s).
Unit tests for ownership semantics sdks/python/oss/tests/pytest/unit/test_register_handler_replace.py	New test module with registry snapshot/restore fixture and helper functions verifying default no-op behavior and replace=True overwrite behavior, including overriding the seeded builtin agent.

Subscription Sidecar Documentation

Layer / File(s)	Summary
README docker networking update docs/design/agent-workflows/projects/subscription-sidecar/README.md	Docker run command adds --network <app-stack-compose-network> and AGENTA_API_INTERNAL_URL=http://api:8000; explanation section extended describing compose-network connectivity and internal URL routing.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• Agenta-AI/agenta#5064: Related work moving handler-owned invoke negotiation logic into the SDK and registering it in HANDLER_REGISTRY, directly connected to the replace=True override introduced here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title matches the subscription-sidecar docs updates, though it omits the handler-registration code changes.
Description check	✅ Passed	The description is related to the changeset and covers the sidecar recipe updates, despite mentioning the branch as docs-only.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/runner-sessions-persist-auth

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

@coderabbitai review

[mmabrouk]

Feedback needed: (1) is replace=True on register_handler the right ownership mechanism, or should the SDK drop the static agent.v0 handler seed instead (it exists so a bare-SDK run of the builtin URI works)? (2) sanity-check that no other consumer relied on first-writer-wins for agenta:builtin:agent:v0. Live before/after evidence is in the description; the fix is verified on the EE dev stack (persist ingest OK + trace_id restored).

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[mmabrouk]

This PR became docs-only: its code fix was superseded by #5081 (merged), the branch is reverted to the merged semantics, and what remains is the sidecar recipe note (+13 lines, one file). Feedback needed: a quick yes/no on merging the recipe note.