fix: README 5-minute tutorial inaccuracies (closes #51)#121
Merged
KunalJavelin merged 4 commits intomainfrom May 6, 2026
Merged
fix: README 5-minute tutorial inaccuracies (closes #51)#121KunalJavelin merged 4 commits intomainfrom
KunalJavelin merged 4 commits intomainfrom
Conversation
Issue #51 reported five problems in the Quick Start / 5-Minute Tutorial. Two were already fixed (the @highflame/zeroid → @highflame/sdk package name correction and the corresponding TS import). Three remained: 3. `build_jwt_assertion` was a ghost function — referenced 5 times in the README but defined nowhere in the SDK or codebase. Tutorial readers couldn't actually run the snippets. 4. Step 2 (Delegate to a Sub-Agent) had a Python example but no TypeScript example, breaking parity with the rest of the tutorial. 5. The Python example in step 2 referenced a `sub_agent_private_key` variable but never showed how to generate it. ## Fix - Defined `generate_ec_keypair` and `build_jwt_assertion` inline at the top of step 2's Python snippet, with a pointer at the production-grade reference (examples/openclaw/agent-identity-sidecar.py:450) that does the full DER → IEEE P1363 signature conversion ES256 requires. - Added a parallel TypeScript snippet using the `jose` package's SignJWT + generateKeyPair / exportJWK helpers, mirroring the Python flow byte-for-byte (header + payload + sign). - Updated the multi-agent example (Pattern 3) and the authorization_code example (Pattern 4) to match the new helper signature `build_jwt_assertion(private_pem, wimse_uri)` (was the arguments-flipped fictional version) and added explicit `generate_ec_keypair()` calls so a reader can actually run them. - Added back-references in the later examples noting the helpers were defined in §2. No code changes — README only.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the README.md to provide complete, runnable examples for sub-agent registration and token exchange. It introduces Python helper functions for key generation and JWT signing, adds a corresponding TypeScript example, and updates existing snippets for consistency. Review feedback suggests adding descriptive comments to the TypeScript example for parity with the Python version and fixing an undefined variable in the Pattern 4 Python snippet.
- TypeScript ZEROID_ISSUER: add 'set to your ZeroID base URL' comment for parity with the Python snippet. - TypeScript subAgent registration: annotate public_key_pem with 'required for token_exchange' for parity with Python. - Pattern 4 (authorization_code): generate the assistant's keypair explicitly with generate_ec_keypair() so assistant_private_key does not appear from nowhere; widen the cross-reference comment to mention both helpers.
KunalJavelin
approved these changes
May 6, 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
2 participants
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
Closes #51. Fixes the three remaining points in @safayavatsal's documentation report:
(Points 1 and 2 — `@highflame/zeroid` → `@highflame/sdk` package name + import — were fixed in a prior README pass and are already on main.)
Changes
All in
README.md. No code changes.Step 2 — Delegate to a Sub-Agent
generate_ec_keypairandbuild_jwt_assertionhelpers at the top of the Python snippet so readers can actually run the tutorial. Both use only thecryptographystdlib package. A pointer to the production-grade reference atexamples/openclaw/agent-identity-sidecar.py:450lives above the snippet — that file does the same DER → IEEE P1363 signature conversion ES256 requires, with full validation.sub_agent_private_keybeing generated via the newgenerate_ec_keypair()helper. The public PEM is registered with ZeroID inclient.agents.register(public_key_pem=...); the private PEM stays with the agent.josepackage (SignJWT,generateKeyPair,exportJWK,importJWK) plusnode:cryptofor the JWK → SPKI PEM conversion needed foragents.register. Same flow as the Python version, byte-for-byte equivalent ES256 assertion.Pattern 3 / Pattern 4 — multi-agent and user-delegation examples
build_jwt_assertion(wimse_uri, private_key)(the ghost function's fictional signature). Nowbuild_jwt_assertion(private_key, wimse_uri)to match the inlined helper.generate_ec_keypair()calls so the*_private_keyvariables don't appear from nowhere.# build_jwt_assertion is defined in §2 above.back-reference at the top of each example so a reader landing mid-document knows where to find the helper.What's NOT in this PR
build_jwt_assertionto the Python or TypeScript SDKs would be the proper long-term fix — the helper is generic enough that every consumer will reinvent it. That's a separate PR against@highflame/sdk(Python) and@highflame/sdk(npm), which live outside this repo. Filing a follow-up issue is reasonable; for now, the inlined helper unblocks tutorial readers.Test plan
build_actor_assertionatexamples/openclaw/agent-identity-sidecar.py:450(same DER → P1363 conversion, same JWT shape).jose+node:cryptoAPIs that are stable in Node 18+.build_jwt_assertioncall sites in the README now use the new(private_pem, wimse_uri)signature consistent with the helper definition (was previously(wimse_uri, private_key)— wrong order, fictional helper).