chore: raise amplifier-agent floor to 0.12.0, document raw LLM payload capture (0.4.0) (#20)

* chore: raise amplifier-agent floor to 0.12.0 (0.4.0)

--host-config has always been forwarded verbatim to
`amplifier-agent serve --config`, but below agent 0.12.0 the agent's HTTP face
dropped the file's provider.config block on every turn: _session_runner cleared
mount_plan["providers"] before per-request injection and called inject_provider
with no extra_config. So the flag silently did less under `serve` than the same
file does under `run`. 0.12.0 is the first version where it actually applies.

This also makes the agent's new debug.rawLlmPayloads key reachable from here.
Below 0.12.0 the agent's closed top-level schema rejects it outright as an
unknown key, so a user following our --host-config docs would get a hard config
error rather than raw payload capture.

No launcher change was needed. The passthrough was already correct
(cli.py forwards --host-config as --config, covered by tests/test_host_config.py);
only the engine it points at had to catch up. AGENT_PINNED_REF derives from
MIN_AGENT_VERSION, so the launch-time auto-install and self-heal now target
v0.12.0.

README, docs/E2E_TESTING.md, and the prereqs rationale comment updated to match.
The comment keeps the older floors on record (0.11.0 for namespaced reseller
model ids, 0.10.0 for /v1/skills and /v1/modes, 0.9.3 for auth set --stdin)
since each is still the reason a distinct feature works.

Requires amplifier-agent 0.12.0, which is not yet tagged upstream.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>

* docs: document raw LLM payload capture via --host-config

Adds a "Capture raw LLM requests and responses" section under Advanced usage,
next to the existing --host-config docs, since that is the mechanism users
already know for configuring the engine.

Covers the host_config.json to write, the events.jsonl path the payloads land
in, and a snippet for reading fields out of it. The snippet is there because
those lines are large enough that opening the file whole is a bad first move;
it was run against a live DTU session rather than written from memory.

Three warnings are called out rather than left to be discovered: the capture is
unredacted full conversation text on disk with no size cap, the value must be a
real JSON boolean, and github-copilot accepts the flag but only emits counts and
lengths so it will not produce bodies.

Troubleshooting gains a pointer to it, plus the three log paths. The doctor
covers "is the stack healthy"; nothing there helps when the stack is fine but a
reply is wrong, which is exactly when this feature is wanted.

🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier)

Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>

---------

Co-authored-by: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>

Author: DavidKoleczek

CHANGELOG.md

@@ -10,6 +10,19 @@ in 0.2.0.
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-07-29
+
+### Changed
+
+- **Agent floor and pinned ref raised to 0.12.0.** `--host-config` has always
+  been forwarded to `amplifier-agent serve --config`, but below 0.12.0 the
+  agent's HTTP face dropped the file's `provider.config` block on every turn, so
+  the flag silently did less under `serve` than it does under `run`. 0.12.0 is
+  the first version where it actually applies. This also makes the agent's new
+  `debug.rawLlmPayloads` key reachable from opencode: below 0.12.0 it is
+  rejected as an unknown top-level key. No launcher change was needed — the
+  passthrough was already correct; only the engine it points at had to catch up.
+
 ## [0.3.0] — 2026-07-29
 
 ### Added

README.md

@@ -254,6 +254,19 @@ Common failures and their fix:
 | `Could not run \`amplifier-agent providers list --json\`` | Install/upgrade amplifier-agent so the doctor command can query it |
 | `opencode config ... is malformed JSON` | Open `~/.config/opencode/opencode.jsonc`, fix or delete it, retry |
 
+If the stack is healthy but a *reply* is wrong, the doctor cannot help. To see
+exactly what was sent to the model and what came back, see
+[Capture raw LLM requests and responses](#capture-raw-llm-requests-and-responses)
+under Advanced usage.
+
+Logs, when you need them:
+
+```
+<tempdir>/amplifier-agent.log                 the backend server's stdout/stderr
+~/.local/share/opencode/log/opencode.log      opencode's own log
+~/.amplifier-agent/state/workspaces/          per-session state and event logs
+```
+
 ---
 
 ## Advanced usage
@@ -291,7 +304,7 @@ Why: `git` is required because amplifier-agent and amplifier-app-opencode are
 installed via `git+https://...` URLs (neither is on PyPI yet). `curl` is
 required by the uv and opencode one-line installers.
 
-#### 1. amplifier-agent — the backend server (>= 0.11.0 required)
+#### 1. amplifier-agent — the backend server (>= 0.12.0 required)
 
 `amplifier-agent` is the OpenAI-compatible HTTP server this adapter talks to.
 Use the official one-line installer — it pulls the latest released binary and
@@ -300,19 +313,19 @@ primes the bundle cache so the first run is instant:
 ```bash
 curl -fsSL https://raw.githubusercontent.com/microsoft/amplifier-agent/main/install.sh | bash
 
-# to pin a specific version instead of latest (must be >= 0.11.0, the floor
+# to pin a specific version instead of latest (must be >= 0.12.0, the floor
 # amplifier-opencode enforces):
-#   curl -fsSL https://raw.githubusercontent.com/microsoft/amplifier-agent/main/install.sh | bash -s -- --tag v0.11.0
+#   curl -fsSL https://raw.githubusercontent.com/microsoft/amplifier-agent/main/install.sh | bash -s -- --tag v0.12.0
 
 # ensure ~/.local/bin is on PATH, then verify:
-amplifier-agent version --json   # → {"version":"0.11.0","protocolVersion":"0.3.0"}
+amplifier-agent version --json   # → {"version":"0.12.0","protocolVersion":"0.3.0"}
 ```
 
 The installer needs [`uv`](https://docs.astral.sh/uv/) and `curl` on PATH and
 will tell you exactly what to install if either is missing — it will not
 bootstrap them silently.
 
-> **Version requirement: `amplifier-agent >= 0.11.0` is mandatory.** Older
+> **Version requirement: `amplifier-agent >= 0.12.0` is mandatory.** Older
 > versions lack the pieces amplifier-opencode depends on (the `serve
 > chat-completions` HTTP face, multi-provider routing, the `auth` subcommand,
 > the `/v1/skills` and `/v1/modes` routes the skills and modes bridges read,
@@ -469,6 +482,66 @@ amplifier-opencode launch --host-config /path/to/host_config.json
 
 See [amplifier-agent's host_config documentation](https://github.com/microsoft/amplifier-agent) for the full schema.
 
+### Capture raw LLM requests and responses
+
+When you need to see exactly what went to the model and came back (debugging a
+bad reply, a tool call that misfired, or a prompt that did not look the way you
+expected), turn on raw payload capture in your `host_config.json`:
+
+```json
+{
+  "provider": { "module": "anthropic" },
+  "debug": { "rawLlmPayloads": true }
+}
+```
+
+```bash
+amplifier-opencode launch --host-config /path/to/host_config.json
+```
+
+Every turn then records the complete outbound request (full message list, system
+prompt, and tool schemas) and the complete response (content blocks, usage,
+stop reason) into the session's event log:
+
+```
+~/.amplifier-agent/state/workspaces/opencode/sessions/http-<session-id>/context-intelligence/events.jsonl
+```
+
+The payloads ride on the `llm:request` and `llm:response` events under a `raw`
+key. Those lines are large, so pull the fields you want rather than opening the
+file whole:
+
+```bash
+# summarize the most recent session's captured request and response
+python3 - <<'PY'
+import glob, json, os
+f = max(glob.glob(os.path.expanduser(
+    "~/.amplifier-agent/state/workspaces/opencode/sessions/*/context-intelligence/events.jsonl"
+)), key=os.path.getmtime)
+for line in open(f):
+    e = json.loads(line); d = e.get("data") or {}
+    if isinstance(d, dict) and "raw" in d and e.get("event", "").startswith("llm:"):
+        print(e["event"], "->", sorted(d["raw"])[:8])
+PY
+```
+
+Three things to know before you turn this on:
+
+- **It writes your full conversation text to disk, unredacted.** Secret
+  redaction matches by key name only and never scans string values, so prompts,
+  tool results, and file contents are stored as-is. There is no truncation and no
+  size cap. Do not leave it on for routine work, and be careful where those
+  session directories end up.
+- **The value must be a real JSON boolean.** `"true"` as a string is rejected
+  with a config error rather than silently accepted.
+- **Coverage depends on the provider.** `anthropic`, `openai`, and
+  `azure-openai` record full payloads. `ollama` records full payloads but does
+  not redact secrets. `github-copilot` accepts the flag but only emits counts and
+  lengths, so it will not give you prompt or response bodies.
+
+Requires `amplifier-agent >= 0.12.0`. Older versions reject `debug` as an unknown
+config key, and their HTTP face ignored `provider.config` entirely.
+
 ### Point at a different amplifier-agent
 
 ```bash

docs/E2E_TESTING.md

@@ -72,7 +72,7 @@ Transitive runtimes:
 
 The provisioned DTU installs `opencode` at a pinned version (`1.17.20`), plus
 `amplifier-agent` (from latest main; must satisfy amplifier-opencode's minimum,
-currently `>= 0.11.0`) and `amplifier-opencode`, plus `git`, `curl`, `uv`, and `tmux`.
+currently `>= 0.12.0`) and `amplifier-opencode`, plus `git`, `curl`, `uv`, and `tmux`.
 
 ## Running
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amplifier-app-opencode"
-version = "0.3.0"
+version = "0.4.0"
 description = "Launch the opencode TUI with auto-discovered amplifier-agent models — checks/starts the chat-completions server, queries /v1/models, writes opencode.json, exec's opencode."
 readme = "README.md"
 requires-python = ">=3.11"

src/amplifier_app_opencode/__init__.py

@@ -1,3 +1,3 @@
 """amplifier-app-opencode — launch opencode with auto-discovered amplifier-agent models."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

src/amplifier_app_opencode/prereqs.py

@@ -52,16 +52,20 @@
 OPENCODE_INSTALL_SH = "https://opencode.ai/install"
 OPENCODE_NPM_PACKAGE = "opencode-ai"
 
-# Minimum amplifier-agent version amplifier-opencode requires. >= 0.11.0 is the
-# first version that namespaces reseller model ids (`github-copilot/<model>`).
-# Below it, Copilot serves `claude-sonnet-5` and `claude-opus-5` under ids
-# byte-identical to the native anthropic provider's, and whichever provider is
-# enumerated last silently captures the other's traffic. Since we document the
-# Copilot setup, the floor has to be the version where that is safe.
-# (0.10.0 remains the floor for `GET /v1/skills` and `GET /v1/modes`, which the
-# skills and modes bridges read; 0.9.3 for `auth set --stdin`, which onboarding
-# uses to hand the provider key to the agent off-argv. 0.11.0 subsumes both.)
-MIN_AGENT_VERSION = "0.11.0"
+# Minimum amplifier-agent version amplifier-opencode requires. >= 0.12.0 is the
+# first version whose HTTP face honours `provider.config` from the host config
+# we pass via `--host-config`. Below it, `serve` accepted the file but dropped
+# that block on every turn, so `--host-config` silently did less than it does
+# under `run` -- and `debug.rawLlmPayloads` is rejected outright as an unknown
+# key. Since we document `--host-config` as the way to configure the engine, the
+# floor has to be the version where it actually applies.
+# (0.11.0 remains the floor for namespaced reseller model ids
+# (`github-copilot/<model>`), without which Copilot's `claude-sonnet-5` collides
+# with the native anthropic provider's; 0.10.0 for `GET /v1/skills` and
+# `GET /v1/modes`, which the skills and modes bridges read; 0.9.3 for
+# `auth set --stdin`, which onboarding uses to hand the provider key to the
+# agent off-argv. 0.12.0 subsumes all three.)
+MIN_AGENT_VERSION = "0.12.0"
 # The silent, launch-time auto-install/self-heal targets this exact known-good
 # git tag rather than a moving branch, so a reliability tool never drags users
 # onto un-vetted ``main``. Kept in lockstep with MIN_AGENT_VERSION: to adopt a