docs(a2a): spell out dual-shape token parsing + INFO logging#412
Merged
docs(a2a): spell out dual-shape token parsing + INFO logging#412
Conversation
Both services decommissioned. Containers stopped + removed. Only reference in protoWorkstacean was the rollcall script. Note: homelab-iac/stacks/ai/docker-compose.yml still has a worldmonitor network reference at line 521 + service at line 833. Needs separate cleanup in that repo. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pairs with quinn#64 (accept both PushNotificationConfig token shapes) and quinn#62 (install logging.basicConfig at server boot). Both were worth a full day of polling-fallback silence; capturing the lessons on the gold-standard guide so the next agent author doesn't repeat them. - Push notifications section grows a dedicated "Token parsing — accept BOTH shapes" subsection with side-by-side JSON of the two A2A-spec-legal PushNotificationConfig variants, a pointer to Quinn's `_extract_push_token` helper, and the specific failure mode when you only read one shape (silent 401 on every delivery). - Task-store-hygiene checklist picks up two new items: dual-shape token parsing, and INFO-level delivery logging with the specific Python default-WARNING pitfall called out.
📝 WalkthroughWalkthroughDocumentation expanded with token-parsing guidance accepting both bearer token shapes and INFO-level logging requirements. Agent rollcall script updated to remove two service checks and modify one agent's display name. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/guides/build-an-a2a-agent.md`:
- Around line 274-290: The JSON examples under "Shape 1" and "Shape 2" include
inline JavaScript comments which make the fenced block invalid JSON; update the
doc so the fenced block is valid JSON by either removing the leading // comments
from inside the fenced code block or change the fence language to jsonc (or move
explanatory comments above/below the block), ensuring the two examples remain
syntactically valid and copy/pasteable as JSON.
- Line 302: The wording "curl the agent's container env" is incorrect; update
the line that suggests using curl to instead show proper container environment
inspection commands by replacing that phrase with concrete examples such as
`docker exec <container> printenv LOG_LEVEL` and add an alternative for k8s like
`kubectl exec -it <pod> -- printenv LOG_LEVEL` where the docs currently mention
"curl the agent's container env" so readers can reliably check LOG_LEVEL.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: f327e185-5bc7-43f6-b17c-e18c26c19a3a
📒 Files selected for processing (2)
docs/guides/build-an-a2a-agent.mdscripts/agent-rollcall.sh
Comment on lines
+274
to
+290
| ```json | ||
| // Shape 1 — top-level `token` (what @a2a-js/sdk serialises by default, | ||
| // what Workstacean's SkillDispatcherPlugin sends) | ||
| { | ||
| "url": "http://caller/api/a2a/callback/{taskId}", | ||
| "token": "per-task-secret" | ||
| } | ||
|
|
||
| // Shape 2 — structured RFC-8821 AuthenticationInfo | ||
| { | ||
| "url": "http://caller/api/a2a/callback/{taskId}", | ||
| "authentication": { | ||
| "schemes": ["Bearer"], | ||
| "credentials": "per-task-secret" | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Use valid JSON in copy/paste examples.
The fenced block is tagged json but includes // comments, which makes it invalid JSON. Consider moving comments outside the block or switching to jsonc to avoid copy/paste failures.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/build-an-a2a-agent.md` around lines 274 - 290, The JSON examples
under "Shape 1" and "Shape 2" include inline JavaScript comments which make the
fenced block invalid JSON; update the doc so the fenced block is valid JSON by
either removing the leading // comments from inside the fenced code block or
change the fence language to jsonc (or move explanatory comments above/below the
block), ensuring the two examples remain syntactically valid and copy/pasteable
as JSON.
| - Send `Authorization: Bearer <token>` if the caller registered a token | ||
| - Send `Authorization: Bearer <token>` if the caller registered a token (see token-parsing above) | ||
| - Do NOT log the webhook body or token — these carry task artifacts, which may contain sensitive data | ||
| - **Log delivery attempts at INFO, not DEBUG.** The default Python root level is WARNING; without `logging.basicConfig(level=INFO)` on your server, "webhook delivered" lines silently vanish and you can't tell delivery from silent-drop (Quinn #61). `curl` the agent's container env for `LOG_LEVEL` — if it's unset and the server doesn't set a basicConfig, you're flying blind. |
There was a problem hiding this comment.
Operational check wording is inaccurate.
“curl the agent’s container env” is misleading—curl won’t read container env vars. Recommend replacing with a container-env inspection command example (e.g., docker exec <container> printenv LOG_LEVEL).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/guides/build-an-a2a-agent.md` at line 302, The wording "curl the agent's
container env" is incorrect; update the line that suggests using curl to instead
show proper container environment inspection commands by replacing that phrase
with concrete examples such as `docker exec <container> printenv LOG_LEVEL` and
add an alternative for k8s like `kubectl exec -it <pod> -- printenv LOG_LEVEL`
where the docs currently mention "curl the agent's container env" so readers can
reliably check LOG_LEVEL.
This was referenced Apr 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pairs with quinn#64 (accept both PushNotificationConfig token shapes) and quinn#62 (install `logging.basicConfig` at server boot). Both were worth a full day of polling-fallback silence on Quinn; capturing the lessons on the gold-standard agent-building guide so the next agent author doesn't repeat them.
Changes
Closes
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
Documentation
Chores