docs(readme): align with Mode A pivot, protocol 0.2.0, and shipped L3 wrappers#21
Merged
Merged
Conversation
… wrappers This README was significantly out of date with recent changes: - PR #8 (Mode A pivot): Replaced stdio JSON-RPC wire protocol with subprocess driver model (argv in / JSON envelope out). README still documented Mode B (--stdio flag, agent/initialize JSON-RPC methods) as primary interface. - PR #17: Bumped protocol version 0.1.0 → 0.2.0, changed --mcp-servers (inline JSON) to --mcp-config-path (file path) for MCP config delivery. Neither reflected in README. - PR #20: Changed OpenAI default from gpt-4 to gpt-5.5 (matches extended_thinking=true in bundle). README used outdated default. - PR #7: TypeScript wrapper shipped at 0.4.0 on npm, Python wrapper shipped in wrappers/python/. README claimed L3 wrappers were 'designed, implementation next'. Applied 10 targeted corrections across README: 1. 'What it is' section — removed Mode B bullet, fixed lifecycle 2. 'Why' section — removed JSON-RPC-mirrors-MCP claim 3. 'Quick start' — removed --stdio example, pointed at wrapper SDKs 4. 'Modes' table — collapsed to Mode A only, added historical design-doc note 5. 'Admin commands' — added missing 'prepare' and 'verify' commands 6. 'Approval flow' — removed unimplemented 'c' response, removed stdio paragraph 7. 'Embedding in Python' — replaced broken classmethod example with correct constructor and instance method usage 8. 'Architecture diagram' — updated arrow label to reflect Mode A transport 9. 'Wire protocol' section — replaced Mode B docs with Mode A (0.2.0 argv flags, JSON envelope schema, stdout/stderr split) 10. 'Status' — updated from 'Phase 1, L3 next' to shipped state (0.3.0 engine, 0.4.0 TS wrapper, Python wrapper, 0.2.0 protocol, conformance suite, path-based MCP) with next steps (L2 host adapters, container packaging). Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
- Added "TypeScript / Node.js SDK" section documenting the shipped npm package (amplifier-agent-ts@0.4.0) with install command, quick-start example, Node ≥ 20 requirement, and pointers to full README and type definitions. - Fixed broken Python install commands: replaced bare PyPI references (uv tool install / pipx install) with git+URL form pinned to engine-v0.3.0. Package is not yet published to PyPI; this fixes the broken install path demonstrated by user feedback. Added explanatory note about separate engine vs wrapper version tagging (engine-v0.3.0 vs wrapper-v0.4.0). Both gaps were identified during PR #21 review: TypeScript SDK was effectively undocumented for consumers despite npm publication, and Python install was impossible without the git+URL form. Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
The Python engine hasn't been published to any registry. Removed all registry-style install commands (uv tool install amplifier-agent, pipx install amplifier-agent, and git+URL forms with PEP 508 specs) as they were misleading. From-source install via git clone + uv tool install -e . is now the only documented path. Added note that engine and wrapper releases are tagged separately (engine-v0.3.0 vs wrapper-v0.4.0) so users can git checkout <tag> before installing if they want a pinned version. This does not affect the TypeScript section — amplifier-agent-ts is published to npm and npm install amplifier-agent-ts is correct. 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
uv tool install works fine with a raw git+https://... argument; no PEP 508 name @ url wrapper, no registry, no separate clone+sync step. Pinning supported via @<tag>. From-source editable install retained as a contributor note. Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
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
The README was significantly out of date with recent changes across multiple PRs. The most impactful: PR #8 (Mode A pivot) replaced the stdio JSON-RPC wire protocol with a subprocess driver (argv in / JSON envelope out), but the README still documented Mode B (
--stdioflag, JSON-RPC methods) as the primary interface. Additionally, PR #17 bumped protocol version 0.1.0 → 0.2.0 and changed MCP config delivery from inline JSON (--mcp-servers) to file-path-based (--mcp-config-path), PR #20 changed the OpenAI default to gpt-5.5, and PR #7 shipped L3 wrappers (TypeScript 0.4.0 on npm, Python inwrappers/python/), yet the README claimed they were 'designed, implementation next'.Changes Applied
--stdiobullet; corrected lifecycle (noagent/shutdownJSON-RPC)amplifier-agent run --stdioexample; pointed at wrapper SDKsprepareandverifycommandsc(cancel) response; removed 'in stdio mode' paragraphcnot implemented; onlyyvs anything-else; no stdio modeEngine.boot()is instance method, constructor requiresturn_handler+protocol_points,CliDisplaySystemrequiresstream=kwargVerification
Ran
grep -n 'stdio\|Mode B\|--stdio\|Engine.boot(\|JSON-RPC over stdio\|agent/initialize' README.mdto verify only legitimate references remain:Engine.boot()clarification in embedding exampleNo stale
--stdioflag references, no surviving JSON-RPC method references outside the historical context.Generated with Amplifier