chore(release): cut amplifier-agent 0.17.0

[David Koleczek (DavidKoleczek)]

Coordinated engine + TypeScript SDK release.

Artifact	Version	Tag pushed after merge	Publishes to
amplifier-agent (engine + CLI)	0.16.0 -> 0.17.0	v0.17.0	PyPI + GitHub Release
amplifier-agent-ts (TS SDK)	0.7.1 -> 0.8.0	wrapper-v0.8.0	npm + GitHub Release
amplifier-agent-py (Py SDK)	0.3.0, unchanged	none	not released

What changed for a user

Real per-turn token and cost usage. metadata.tokensIn / tokensOut were hardcoded to 0 on every path; they now report what the turn actually spent, summed across every LLM call including those made by delegated sub-agents. Three new metadata fields carry the rest: cacheReadTokens, cacheWriteTokens, and costUsd (a decimal string, never a float). Both wrapper SDKs surface the same data on their terminal events via a new Usage type, and gain a stderr_tail_bytes option.

amplifier-agent run --prompt-file <path>. A second transport for the prompt, since argv is a bounded channel (Linux caps a single element at 131072 bytes, Windows the whole command line at 32767 chars) and a prompt is unbounded caller data. Wrappers spill automatically at 16384 bytes.

HTTP face: usage.prompt_tokens was over-reported. extract_usage() summed inputTokens + cacheReadTokens + cacheWriteTokens on the premise the three are disjoint. They are not — inputTokens is the gross total and already contains the cache reads, so the cached portion was counted twice. On a cache-heavy turn, the normal case in an agent loop, that roughly doubles the reported prompt for any OpenAI-compatible client doing its own cost arithmetic.

Plus wrapper fixes: -- is now emitted before the positional prompt (a prompt beginning with - previously died with exit 2 before the engine booted), the stderr_tail cap measures UTF-8 bytes rather than characters, and the Python wrapper's MCP config spill writes with an explicit UTF-8 encoding instead of inheriting the locale codepage.

Scope of impact

Coordinated cross-component. PROTOCOL_VERSION moved 0.3.0 -> 0.4.0, purely additive — no existing field changed shape or meaning; the minor moves so a host can gate on the new fields being present.

The engine and amplifier-agent-ts must be upgraded together. A wrapper pinned to 0.3.0 refuses an engine on 0.4.0 with protocol_version_mismatch, and the reverse holds. The refusal is deliberate and loud; there is no silent-degradation path.

amplifier-agent-py is not part of this release. It has never been published, so its 0.3.0 manifest is not behind any tag. Its source already carries the 0.4.0 pin and the prompt-spill and MCP-encoding fixes; those reach consumers with that package's first release, which will also be the first exercise of its OIDC trusted-publisher handshake.

amplifier-app-paperclip and amplifier-app-nanoclaw caret-pin amplifier-agent-ts, so a minor wrapper release propagates to them without action.

Downstream: amplifier-app-opencode needs a floor bump

Yes — MIN_AGENT_VERSION should move 0.16.0 -> 0.17.0, in a separate PR on that repo.

Worth being precise about why, because the obvious reason is the wrong one. opencode drives the engine through the HTTP face only — serve, /v1/models, /v1/chat/completions, /v1/skills, /v1/modes. It never spawns through a wrapper SDK, so it has no stdio protocol handshake and PROTOCOL_VERSION does not gate it.

What does reach it is the prompt_tokens fix above, on /v1/chat/completions — opencode's own surface. Its Python launcher does not parse the usage block, but opencode's TUI displays those counts, so below this floor a user sees a prompt figure inflated by the entire cached portion of every turn.

That makes this a correctness bump rather than a capability requirement: opencode runs against 0.16.0, it just reports wrong numbers. It is a stronger rationale than the last two floor moves, which prereqs.py records as pure adoption bumps to keep AGENT_PINNED_REF from drifting a release behind.

Verification

make verify passes clean on this branch — lint, format, pyright, verify-codegen (spec.md + 32 schemas), verify-wheel (6 checks against a built amplifier_agent-0.17.0-py3-none-any.whl), verify-parity (Python and TypeScript runners agree on every fixture), and the TypeScript build plus 157 wrapper tests across 21 files.

tests/e2e/ is not covered here or in CI, since e2e and evals need a DTU.

Merging this publishes nothing

The tag push is the release, and it happens after merge. install.sh and amplifier-agent update install from git and resolve "latest" through the GitHub Releases API, which release-notes.yml creates on tag push.

🤖 Generated with Amplifier