@sunerpy/kiro-provider 0.3.1 → 0.5.0-rc.1

package/README.md

@@ -1,6 +1,6 @@
 # kiro-provider
 
-> A standalone OpenAI-compatible HTTP gateway for AWS Kiro (CodeWhisperer) — point any OpenAI SDK or agent at your own Kiro accounts.
+> A protocol-fidelity gateway exposing a verified OpenAI Responses and Anthropic Messages subset over AWS Kiro (CodeWhisperer).
 
 [![CI](https://github.com/sunerpy/kiro-provider/actions/workflows/ci.yml/badge.svg)](https://github.com/sunerpy/kiro-provider/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/sunerpy/kiro-provider/branch/main/graph/badge.svg)](https://codecov.io/gh/sunerpy/kiro-provider)
@@ -12,25 +12,77 @@
 ## Table of Contents
 
 - [Features](#features)
+- [Protocol compatibility](#protocol-compatibility)
 - [Install](#install)
 - [Quickstart](#quickstart)
+- [Run as a background service](#run-as-a-background-service)
 - [Configuration](#configuration)
 - [Proxy](#proxy)
 - [Security](#security)
 - [Using with an LLM](#using-with-an-llm)
+- [Use with Zuno](#use-with-zuno)
 - [Use with Codex CLI](#use-with-codex-cli)
+- [Use with Claude Code](#use-with-claude-code)
 - [Development](#development)
 - [License](#license)
 
 ## Features
 
-- OpenAI-compatible `POST /v1/chat/completions` (streaming SSE and non-streaming JSON), `POST /v1/responses` (OpenAI Responses API, streaming typed SSE and non-streaming JSON), `GET /v1/models`, and `GET /health`.
+- OpenAI Responses `POST /v1/responses` and Anthropic Messages `POST /v1/messages` (both streaming and non-streaming), plus `POST /v1/messages/count_tokens`, `GET /v1/models`, `GET /health`, and authenticated `GET /ready`.
+- Legacy OpenAI Chat Completions is available at `POST /v1/chat/completions`, but is disabled by default and must be explicitly enabled with `enable_legacy_chat_completions`.
 - Bearer API-key gate that fails closed: the server refuses to start with no configured keys, and defaults to binding `127.0.0.1`.
-- Multi-account rotation with automatic token refresh and failover, backed by a local `bun:sqlite` account store with tombstone-based removal.
-- `accounts import` to reuse accounts already authenticated by [OpenCode's Kiro auth](https://opencode.ai/) instead of repeating device-code login.
+- Live OpenCode authentication reuse by default: `auth_source: "opencode-shared"` reads the same `~/.config/opencode/kiro.db`, honors tombstones, updates shared health/usage, and uses the account schema and refresh-lock behavior of `opencode-kiro-auth` v0.20.7.
+- Explicit-only session affinity by default: Responses requests can opt in through standard `metadata`, compatibility `client_metadata`, or `prompt_cache_key`; requests without an explicit key never derive identity from prompt text. A matching Zuno native OpenAI transport supplies `metadata.zuno_session_id` automatically.
+- Account-scoped scheduling and cached SDK/transport objects: unrelated accounts can run concurrently, while one account is protected from overlapping Kiro streams; access-token refresh updates the cached client instead of rebuilding it. Kiro model-call HTTP keep-alive is disabled by default and is an explicit transport opt-in.
+- Zero provider-owned prompt injection in the default `safe` mode: a canonical IR preserves client text, roles, content-block boundaries, tool identity, ordering, and source paths; unsupported guarantees are rejected before Kiro instead of being emulated with hidden instructions.
+- Encrypted reasoning replay for complete native Kiro envelopes: opaque `kr1_...` tokens, AES-256-GCM storage, tenant/model/account/conversation/output binding, TTL/LRU cleanup, and account-locked replay.
+- Multi-account rotation with automatic token refresh and failover. Shared mode treats OpenCode's database as the authentication authority; the provider database stores session affinity only.
+- An explicit `auth_source: "local"` compatibility mode retains `kiro-provider login` and `accounts import`; imported accounts are snapshots and must not be confused with live shared authentication.
 - A single global `proxy_url` that, when set, routes all upstream egress (model requests, token refresh, device-code login) through one HTTP(S) proxy.
 - Ships as a self-contained compiled binary via `bun build --compile` — no runtime install required on the target machine.
 
+## Protocol compatibility
+
+v0.5 is intentionally a **verified compatibility subset**. It does not accept
+fields and silently discard them. The default `protocol_projection_mode:
+"safe"` never prepends or rewrites client instructions, merges adjacent
+messages, clears repeated assistant output, removes trailing text such as `{`,
+or creates model-visible compensation prose.
+
+Key boundaries:
+
+- plain text, consecutive same-role turns, function/custom tool declarations,
+  calls, and results retain their original structure and order;
+- a message containing multiple top-level text blocks returns
+  `unsupported_content_block_projection`, because Kiro exposes only one text
+  field and concatenation would erase block boundaries;
+- `instructions`, `system`, and `developer` return
+  `unsupported_instruction_projection` in safe mode because the tested Kiro
+  `additionalContext` channel was rejected;
+- `tool_choice: auto` is supported; required/named choice,
+  `parallel_tool_calls: false`, strict schemas, custom grammars, and namespace
+  tools are rejected rather than weakened;
+- base64/data-URL images are supported, while remote image URLs and detail
+  controls are rejected;
+- an output-token limit is probe-confirmed only for `claude-sonnet-5` variants
+  in the range 1,024–128,000;
+- stateful Responses fields and native Web Search remain unsupported, and the
+  provider never fabricates search/citation events.
+
+Current compiled-binary acceptance on 2026-08-26: OpenAI JavaScript SDK 7.5.0
+passes Responses, explicit Chat, function/custom tool loops, and encrypted
+reasoning replay across restart. OpenCode Responses passes only in explicit
+`legacy-user-prefix` mode with Claude Sonnet 5; OpenCode Chat is blocked by
+its nonstandard `cache_control`. Codex 0.149.0-alpha.4.1 is blocked by
+`parallel_tool_calls: false`, and Claude Code 2.1.209 is blocked by
+`output_config.format`, `context_management`, and its retry that places
+`system` in `messages.1.role`. These are RC findings; stable v0.5.0 remains
+gated rather than silently discarding or relocating those fields.
+
+For the complete capability matrix, error codes, reasoning replay contract,
+and v0.4 migration steps, see
+[`docs/PROTOCOL_COMPATIBILITY.md`](docs/PROTOCOL_COMPATIBILITY.md).
+
 ## Install
 
 Pick one of three channels.
@@ -91,15 +143,20 @@ In the rest of this README, `./dist/kiro-provider` refers to any of the above; s
 
 ## Quickstart
 
-1. **Get an account into the local store.** Either sign in interactively:
+1. **Authenticate Kiro through OpenCode.** The default shared-auth mode uses
+   OpenCode's live account database:
 
    ```bash
-   ./dist/kiro-provider login
+   opencode auth login
    ```
 
-   or import accounts already authenticated by OpenCode:
+   Select Kiro and complete the normal login flow. If you intentionally want
+   an independent compatibility store instead, set `"auth_source": "local"`
+   and then use:
 
    ```bash
+   ./dist/kiro-provider login
+   # or take a one-time snapshot:
    ./dist/kiro-provider accounts import
    ```
 
@@ -117,7 +174,7 @@ In the rest of this README, `./dist/kiro-provider` refers to any of the above; s
    ./dist/kiro-provider serve
    ```
 
-4. **Call it with an OpenAI-compatible client.**
+4. **Call the default Responses endpoint.**
 
    ```bash
    curl -fsS http://127.0.0.1:8787/v1/models \
@@ -132,15 +189,18 @@ In the rest of this README, `./dist/kiro-provider` refers to any of the above; s
      apiKey: "sk-your-private-key",
    });
 
-   const completion = await client.chat.completions.create({
+   const response = await client.responses.create({
      model: "auto",
-     messages: [{ role: "user", content: "Explain this repository." }],
+     input: "Explain this repository.",
    });
 
-   console.log(completion.choices[0]?.message.content);
+   console.log(response.output_text);
    ```
 
-   Or with the [Vercel AI SDK](https://sdk.vercel.ai/) via `@ai-sdk/openai-compatible`:
+   OpenAI-compatible libraries that only implement Chat Completions require
+   `"enable_legacy_chat_completions": true` in the gateway config. For example,
+   with the [Vercel AI SDK](https://sdk.vercel.ai/) via
+   `@ai-sdk/openai-compatible`:
 
    ```ts
    import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
@@ -158,6 +218,230 @@ In the rest of this README, `./dist/kiro-provider` refers to any of the above; s
    });
    ```
 
+## Run as a background service
+
+For an agent host, run **one long-lived provider per OS user** and point
+compatible OpenAI/Anthropic clients, OpenCode, Zuno, and compatibility probes
+for Codex or Claude Code at that local endpoint.
+Do not start a new provider for every agent or conversation. Keeping one
+process alive lets requests with an explicit affinity key reuse their
+persisted account/Kiro-conversation binding, while all requests can reuse
+process-local, account-scoped SDK clients and transport objects. A request
+without an explicit key gets a fresh Kiro conversation. Kiro model-call HTTP
+sockets are fresh by default (`sdk_http_keep_alive: false`); enabling it is a
+best-effort transport optimization, never a promise that one session owns one
+physical TCP connection.
+
+Use a pinned standalone binary for a service rather than fetching through
+`bunx` on every start. The examples below assume the release installers'
+defaults:
+
+- binary: `~/.local/bin/kiro-provider` on Linux,
+  `%USERPROFILE%\.local\bin\kiro-provider.exe` on Windows;
+- config: `~/.config/kiro-provider/config.json`;
+- service/task name: `kiro-provider`.
+
+Run the service as the **same OS user** that ran `opencode auth login`.
+Default `auth_source: "opencode-shared"` resolves that user's OpenCode
+database and home/XDG directories; running as `root`, `LocalSystem`, or
+another user will normally select different credentials. Use absolute paths,
+keep the API key in the protected config file rather than service arguments,
+and set `opencode_auth_db_path` explicitly if the service has a different XDG
+environment.
+
+### Linux: systemd user service
+
+Verify the installed binary and config first:
+
+```bash
+test -x "$HOME/.local/bin/kiro-provider"
+test -r "$HOME/.config/kiro-provider/config.json"
+chmod 600 "$HOME/.config/kiro-provider/config.json"
+```
+
+Install a [systemd user service](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html):
+
+```bash
+SERVICE_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
+install -d -m 700 "$SERVICE_DIR"
+cat > "$SERVICE_DIR/kiro-provider.service" <<'EOF'
+[Unit]
+Description=kiro-provider local Kiro gateway
+
+[Service]
+Type=exec
+ExecStart=%h/.local/bin/kiro-provider serve --config %h/.config/kiro-provider/config.json
+Restart=on-failure
+RestartSec=5s
+TimeoutStopSec=30s
+UMask=0077
+
+[Install]
+WantedBy=default.target
+EOF
+chmod 600 "$SERVICE_DIR/kiro-provider.service"
+
+systemctl --user daemon-reload
+systemctl --user enable --now kiro-provider.service
+```
+
+If the binary or config is elsewhere, replace `ExecStart` with those absolute
+paths. For a custom `XDG_CONFIG_HOME`, also add an explicit
+`Environment=XDG_CONFIG_HOME=/absolute/path` line or configure
+`opencode_auth_db_path`.
+
+Operate and inspect the service:
+
+```bash
+systemctl --user is-active kiro-provider.service
+systemctl --user restart kiro-provider.service
+journalctl --user -u kiro-provider.service -n 100 --no-pager
+```
+
+User services normally start with that user's service manager. If the
+provider must start at boot and remain after logout, an administrator may
+enable lingering with `loginctl enable-linger <user>` after reviewing the
+machine's security policy.
+
+To remove the unit:
+
+```bash
+systemctl --user disable --now kiro-provider.service
+rm "${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/kiro-provider.service"
+systemctl --user daemon-reload
+```
+
+### Windows: per-user scheduled task
+
+`kiro-provider.exe` is a normal foreground executable, not a native Windows
+Service Control Manager executable. Do not register it directly with
+`sc.exe`. The built-in, dependency-free option is a
+[Scheduled Task](https://learn.microsoft.com/powershell/module/scheduledtasks/register-scheduledtask)
+that starts at sign-in, runs as the current user, and restarts after failure.
+
+Run the following in PowerShell as the same user that owns the OpenCode
+credentials. It creates a small launcher so stdout/stderr are retained under
+`%LOCALAPPDATA%\kiro-provider`:
+
+```powershell
+$Binary = Join-Path $HOME ".local\bin\kiro-provider.exe"
+$Config = Join-Path $HOME ".config\kiro-provider\config.json"
+$ServiceDir = Join-Path $HOME ".config\kiro-provider"
+$LogDir = Join-Path $env:LOCALAPPDATA "kiro-provider"
+$Launcher = Join-Path $ServiceDir "service.ps1"
+
+if (-not (Test-Path -LiteralPath $Binary -PathType Leaf)) {
+  throw "kiro-provider binary not found: $Binary"
+}
+if (-not (Test-Path -LiteralPath $Config -PathType Leaf)) {
+  throw "kiro-provider config not found: $Config"
+}
+
+New-Item -ItemType Directory -Force -Path $ServiceDir, $LogDir | Out-Null
+@'
+$ErrorActionPreference = "Stop"
+$Binary = Join-Path $HOME ".local\bin\kiro-provider.exe"
+$Config = Join-Path $HOME ".config\kiro-provider\config.json"
+$LogDir = Join-Path $env:LOCALAPPDATA "kiro-provider"
+$Log = Join-Path $LogDir "service.log"
+$PreviousLog = Join-Path $LogDir "service.previous.log"
+
+New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+if ((Test-Path -LiteralPath $Log) -and ((Get-Item -LiteralPath $Log).Length -gt 10MB)) {
+  Move-Item -Force -LiteralPath $Log -Destination $PreviousLog
+}
+
+& $Binary serve --config $Config *>> $Log
+exit $LASTEXITCODE
+'@ | Set-Content -LiteralPath $Launcher -Encoding UTF8
+
+$User = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
+$PowerShell = (Get-Command powershell.exe).Source
+$Action = New-ScheduledTaskAction `
+  -Execute $PowerShell `
+  -Argument ('-NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "{0}"' -f $Launcher)
+$Trigger = New-ScheduledTaskTrigger -AtLogOn -User $User
+$Principal = New-ScheduledTaskPrincipal `
+  -UserId $User `
+  -LogonType Interactive `
+  -RunLevel Limited
+$Settings = New-ScheduledTaskSettingsSet `
+  -RestartCount 999 `
+  -RestartInterval (New-TimeSpan -Minutes 1) `
+  -ExecutionTimeLimit ([TimeSpan]::Zero) `
+  -MultipleInstances IgnoreNew `
+  -AllowStartIfOnBatteries `
+  -DontStopIfGoingOnBatteries `
+  -StartWhenAvailable
+
+Stop-ScheduledTask -TaskName "kiro-provider" -ErrorAction SilentlyContinue
+Register-ScheduledTask `
+  -TaskName "kiro-provider" `
+  -Action $Action `
+  -Trigger $Trigger `
+  -Principal $Principal `
+  -Settings $Settings `
+  -Description "Local AWS Kiro gateway for AI agents" `
+  -Force | Out-Null
+Start-ScheduledTask -TaskName "kiro-provider"
+```
+
+Inspect, restart, and follow logs:
+
+```powershell
+Get-ScheduledTask -TaskName "kiro-provider" | Get-ScheduledTaskInfo
+Stop-ScheduledTask -TaskName "kiro-provider"
+Start-ScheduledTask -TaskName "kiro-provider"
+Get-Content "$env:LOCALAPPDATA\kiro-provider\service.log" -Tail 100 -Wait
+```
+
+To remove the task and launcher:
+
+```powershell
+Stop-ScheduledTask -TaskName "kiro-provider" -ErrorAction SilentlyContinue
+Unregister-ScheduledTask -TaskName "kiro-provider" -Confirm:$false
+Remove-Item "$HOME\.config\kiro-provider\service.ps1"
+```
+
+This task intentionally runs only in the current user's interactive session,
+so it can use that user's network access and OpenCode credentials without
+storing a Windows password. A true pre-login Windows service requires a
+service wrapper and a deliberately configured user account; do not run it as
+`LocalSystem` and expect the same OpenCode database.
+
+### Health checks and automation contract
+
+After either installation, verify both process liveness and authenticated
+readiness:
+
+```bash
+curl -fsS http://127.0.0.1:8787/health
+curl -fsS http://127.0.0.1:8787/ready \
+  -H 'Authorization: Bearer sk-your-private-key'
+```
+
+PowerShell equivalent:
+
+```powershell
+Invoke-RestMethod "http://127.0.0.1:8787/health"
+$Headers = @{ Authorization = "Bearer sk-your-private-key" }
+Invoke-RestMethod "http://127.0.0.1:8787/ready" -Headers $Headers
+```
+
+For an AI agent or installer, treat setup as successful only when:
+
+1. the binary and explicit config path exist;
+2. the service/task runs as the credential-owning user;
+3. `/health` succeeds;
+4. authenticated `/ready` succeeds, proving a readable auth source, at least
+   one active account, writable provider state, an available reasoning keyring,
+   and coverage for every key ID referenced by an unexpired replay record.
+
+Use the fixed service/task name above so repeated setup is idempotent. Restart
+it after changing the config or replacing the binary. Do not make the client
+responsible for starting a private provider process; configure clients only
+with the stable base URL and gateway API key.
+
 ## Configuration
 
 Config is loaded from `~/.config/kiro-provider/config.json` (or `$XDG_CONFIG_HOME/kiro-provider/config.json`), overridable by `KIRO_PROVIDER_*` environment variables and, for `serve`, by CLI flags. Precedence is **CLI flag > environment variable > config file > schema default**.
@@ -167,9 +451,21 @@ Config is loaded from `~/.config/kiro-provider/config.json` (or `$XDG_CONFIG_HOM
 | `host` | `127.0.0.1` | `KIRO_PROVIDER_HOST` |
 | `port` | `8787` | `KIRO_PROVIDER_PORT` |
 | `api_keys` | required, non-empty | `KIRO_PROVIDER_API_KEYS` |
+| `enable_legacy_chat_completions` | `false` | `KIRO_PROVIDER_ENABLE_LEGACY_CHAT_COMPLETIONS` |
+| `protocol_projection_mode` | `safe` | `KIRO_PROVIDER_PROTOCOL_PROJECTION_MODE` |
+| `session_affinity_mode` | `explicit-only` | `KIRO_PROVIDER_SESSION_AFFINITY_MODE` |
+| `auth_source` | `opencode-shared` | `KIRO_PROVIDER_AUTH_SOURCE` |
+| `opencode_auth_db_path` | `null` (uses the OpenCode default) | `KIRO_PROVIDER_OPENCODE_AUTH_DB_PATH` |
 | `proxy_url` | `null` | `KIRO_PROVIDER_PROXY_URL` |
 | `default_region` | `us-east-1` | `KIRO_PROVIDER_DEFAULT_REGION` |
+| `sdk_http_keep_alive` | `false` | `KIRO_PROVIDER_SDK_HTTP_KEEP_ALIVE` |
 | `account_selection_strategy` | `lowest-usage` | `KIRO_PROVIDER_ACCOUNT_SELECTION_STRATEGY` |
+| `session_affinity_ttl_ms` | `86400000` | `KIRO_PROVIDER_SESSION_AFFINITY_TTL_MS` |
+| `session_affinity_max_entries` | `10000` | `KIRO_PROVIDER_SESSION_AFFINITY_MAX_ENTRIES` |
+| `reasoning_replay_key_path` | auto-generated config path | `KIRO_PROVIDER_REASONING_REPLAY_KEY_PATH` |
+| `reasoning_replay_keys` | `[]` | `KIRO_PROVIDER_REASONING_REPLAY_KEYS` |
+| `reasoning_replay_ttl_ms` | `86400000` | `KIRO_PROVIDER_REASONING_REPLAY_TTL_MS` |
+| `reasoning_replay_max_entries` | `10000` | `KIRO_PROVIDER_REASONING_REPLAY_MAX_ENTRIES` |
 | `log_level` | `info` | `KIRO_PROVIDER_LOG_LEVEL` |
 
 The full field reference, including retry/timeout tuning and the test-only `test_upstream_endpoint`, lives in [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md).
@@ -180,36 +476,139 @@ Some networks reach one model family directly while another needs a proxy (for e
 
 ## Security
 
-- **Fail-closed authentication.** The server will not start without at least one non-empty `api_keys` entry, and every route requires `Authorization: Bearer <key>`.
+- **Fail-closed authentication.** The server will not start without at least one non-empty `api_keys` entry. OpenAI routes require `Authorization: Bearer <key>`; Anthropic routes also accept `x-api-key: <key>`.
 - **Local bind by default.** `host` defaults to `127.0.0.1`; only bind `0.0.0.0` behind a firewall or authenticated reverse proxy.
-- **Locked-down account store.** `accounts.db` (and its WAL/SHM files) are created with mode `0600`.
-- **No secrets in logs.** Proxy URLs and account tokens are never printed; don't commit a real config file, account database, or gateway key.
+- **Single authentication authority.** Shared mode reads and updates OpenCode's existing Kiro database and fails closed on an incompatible schema; it never runs provider-owned migrations against that database.
+- **Locked-down provider state.** `accounts.db` (and its WAL/SHM files) are created with mode `0600`; in shared mode this database contains affinity/state, not the authoritative credentials.
+- **Authenticated reasoning replay.** The database stores token/fingerprint hashes and AES-256-GCM ciphertext, not raw `kr1_...` tokens. Missing active decryption keys fail startup.
+- **No sensitive content in logs.** Gateway/account secrets, replay tokens, signatures, reasoning, and request prompt text are not logged; structured audit fields contain hashes and field names only. Don't commit a real config file, account database, keyring, or gateway key.
 
 > **Responsible use.** kiro-provider reuses AWS Kiro accounts you already control and consumes your own account quota. Supply your own accounts — this project is not a way to share or resell someone else's Kiro access, and it should not be used to circumvent per-account usage limits.
 
 ## Using with an LLM
 
-Point any OpenAI-compatible client (`openai`, `@ai-sdk/openai-compatible`, LangChain, etc.) at `http://<host>:<port>/v1` with one of your configured `api_keys`.
+Use `POST /v1/responses` for OpenAI Responses clients. Use
+`POST /v1/messages` for Anthropic Messages clients. Only point a
+Chat-Completions-only client (`@ai-sdk/openai-compatible`, older LangChain
+adapters, or an OpenCode custom provider using that package) at
+`POST /v1/chat/completions` after explicitly enabling the legacy endpoint.
+
+Standard clients must also stay within the verified subset. In safe mode a
+client that always sends system/developer instructions, custom grammars,
+namespace tools, or Anthropic `cache_control` receives a field-level 400; the
+gateway does not modify that request to force it through Kiro. The optional
+`legacy-user-prefix` projection is a temporary instruction-only migration aid
+for v0.5.x/v0.6.x and is scheduled for removal in v0.7.0.
+
+The default `session_affinity_mode: "explicit-only"` never hashes prompt text
+to guess a conversation. Responses checks, in order,
+`metadata.zuno_session_id`, `metadata.kiro_provider_session_id`, compatibility
+`client_metadata.thread_id|session_id|conversation_id`, and
+`prompt_cache_key`. Chat checks only `prompt_cache_key`; Anthropic Messages
+has no verified explicit affinity field. With no key, the request gets a
+fresh Kiro conversation but can still reuse account-scoped SDK clients and
+transport objects. The Kiro SDK's direct/proxy agents use fresh sockets by default;
+set `sdk_http_keep_alive: true` only when the deployment has validated pooled
+socket behavior.
+The temporary `legacy-initial-input` mode restores only the old affinity
+heuristics and logs a startup warning; it does not alter request content.
+
+Stateful Responses fields `previous_response_id` and `conversation` are
+rejected until the gateway has a real response-state store, so clients must
+resend the complete input.
 
 <details>
 <summary>Agent command reference</summary>
 
 - `kiro-provider serve [--config <path>] [--host <host>] [--port <port>] [--proxy <url>]` — start the gateway.
-- `kiro-provider login [--config <path>] [--start-url <url>] [--region <region>]` — device-code login (AWS Builder ID, or IAM Identity Center with `--start-url`).
-- `kiro-provider accounts list` — list stored accounts and their health.
-- `kiro-provider accounts import [--from <path>] [--config <path>]` — import accounts from an OpenCode `kiro.db` (default source: `~/.config/opencode/kiro.db`).
-- `kiro-provider accounts remove <id|email>` — remove one account (writes a tombstone).
+- `kiro-provider login [--config <path>] [--start-url <url>] [--region <region>]` — local compatibility mode only; shared mode directs you to `opencode auth login`.
+- `kiro-provider accounts list` — list accounts in the local compatibility store.
+- `kiro-provider accounts import [--from <path>] [--config <path>]` — take a one-time snapshot into the local compatibility store.
+- `kiro-provider accounts remove <id|email>` — remove one account from the local compatibility store.
 
-Contract: human-readable status lines go to stdout, errors to stderr, non-zero exit on failure. `GET /v1/models` and `GET /health` return structured JSON.
+Contract: human-readable status lines go to stdout, errors to stderr, non-zero exit on failure. `GET /v1/models`, `GET /health`, and authenticated `GET /ready` return structured JSON.
 
 </details>
 
+## Use with Zuno
+
+Run one compiled kiro-provider service as the credential-owning OS user, then
+configure Zuno's native Rust OpenAI transport. No Node package, AI SDK, private
+header, or provider-spawn hook is required:
+
+```json
+{
+  "model": "kiro/auto",
+  "small_model": "kiro/auto",
+  "provider": {
+    "kiro": {
+      "name": "Local kiro-provider",
+      "transport": "openai",
+      "surface": "responses",
+      "env": ["KIRO_GATEWAY_API_KEY"],
+      "options": {
+        "baseURL": "http://127.0.0.1:8787/v1",
+        "maxTokens": null
+      },
+      "models": {
+        "auto": {
+          "name": "Kiro Auto",
+          "reasoning": true,
+          "tool_call": true
+        }
+      }
+    }
+  }
+}
+```
+
+Set `KIRO_GATEWAY_API_KEY` to one key from the provider's `api_keys`, then
+verify the native route:
+
+```bash
+export KIRO_GATEWAY_API_KEY='sk-your-private-key'
+zuno debug config
+zuno models kiro --verbose
+```
+
+The matching Zuno OpenAI Responses transport maps the durable Zuno session ID
+to standard `metadata.zuno_session_id` on every main turn and tool
+continuation. It does not add that ID to input, messages, instructions, tool
+descriptions, or any other model-visible field; internal title/summary calls
+do not join the main provider conversation. Therefore one Zuno session is
+serialized onto one persisted account/Kiro-conversation binding, while
+different sessions remain isolated even if their first prompt and upstream
+tool aliases are identical. Tool declaration and alias state remains local to
+each request.
+
+Keep `surface: "responses"` for this integration. Selecting `chat` requires
+the separately enabled legacy endpoint and does not carry the Zuno Responses
+session metadata.
+
+Current Zuno sends agent instructions, while the live Kiro
+`additionalContext` probe did not prove a lossless instruction projection.
+Consequently the verified functional path currently requires the provider's
+explicit `protocol_projection_mode: "legacy-user-prefix"`; `safe` correctly
+returns `unsupported_instruction_projection` and never rewrites the request.
+Set Zuno `options.maxTokens` to `null` as shown so its generic layer does not
+add the unsupported `max_output_tokens: 32000`. Neither setting uses a private
+Header or client-side prompt patch; the legacy mode is an explicit migration
+exception scheduled for removal in v0.7.0.
+
 ## Use with Codex CLI
 
-kiro-provider's `POST /v1/responses` endpoint speaks the OpenAI Responses wire format, so [Codex CLI](https://github.com/openai/codex) (verified against 0.144.6) can use it as a custom `model_provider` with `wire_api = "responses"`. Test it with an isolated `CODEX_HOME` so your real `~/.codex` config is never touched:
+Codex uses the correct Responses endpoint, but the current compiled RC gate
+against 0.149.0-alpha.4.1 does not pass: Codex sends
+`parallel_tool_calls: false`, and Kiro cannot guarantee that constraint. The
+provider returns `unsupported_parallel_tool_calls` before Kiro instead of
+ignoring the field. The following isolated configuration reproduces the
+compatibility check without touching the real `~/.codex` state:
 
 ```bash
-export CODEX_HOME="$(mktemp -d)"        # isolated; your real ~/.codex is untouched
+export CODEX_TEST_ROOT="$(mktemp -d)"
+export CODEX_HOME="$CODEX_TEST_ROOT/home"
+export CODEX_SQLITE_HOME="$CODEX_TEST_ROOT/sqlite"
+mkdir -p "$CODEX_HOME" "$CODEX_SQLITE_HOME"
 export LOCALGW_KEY="sk-...your gateway api key..."
 cat > "$CODEX_HOME/config.toml" <<'EOF'
 model = "gpt-5.6-sol"
@@ -223,14 +622,48 @@ EOF
 codex exec --skip-git-repo-check "say hi"
 ```
 
-Requires the gateway running (`kiro-provider serve`) with an account already imported or logged in. Reasoning models work through Codex the same way they do for `/v1/chat/completions` (Claude via your configured proxy, GPT direct). Full details, plus a ready-made isolated smoke test (`scripts/codex-smoke.sh`), live in [`docs/CODEX.md`](docs/CODEX.md).
+For Codex 0.149.0-alpha.4.1 the expected RC result is a non-zero exit carrying
+that field-level error. A future successful basic request must still pass a
+real shell/custom-tool loop, continuation, and restart reasoning replay before
+Codex is marked supported. Full details live in
+[`docs/CODEX.md`](docs/CODEX.md).
+
+## Use with Claude Code
+
+Claude Code uses Anthropic Messages, but Claude Code 2.1.209 currently sends
+`output_config.format` and `context_management`; after the first rejection it
+also retries with `system` inside `messages.1.role`, which is not a valid
+Anthropic Messages role and cannot be silently moved. The provider rejects
+these shapes before Kiro in both safe and legacy instruction modes. The
+standard configuration below is therefore a compatibility probe, not a
+current support claim:
+
+```bash
+export ANTHROPIC_BASE_URL="http://127.0.0.1:8787"
+export ANTHROPIC_AUTH_TOKEN="sk-your-private-key"
+claude
+```
+
+The gateway accepts either `Authorization: Bearer <key>` or `x-api-key:
+<key>` for Anthropic routes. Direct Messages requests within the verified
+subset support typed JSON/SSE and tools, while `/v1/messages/count_tokens` is
+an explicit estimate. See
+[`docs/CLAUDE_CODE.md`](docs/CLAUDE_CODE.md).
+
+The current compiled-service validation record is in
+[`docs/audits/kiro-provider-v0.5.0-rc.1-validation-2026-08-26.md`](docs/audits/kiro-provider-v0.5.0-rc.1-validation-2026-08-26.md).
+The older [`docs/E2E_VALIDATION_2026-08-22.md`](docs/E2E_VALIDATION_2026-08-22.md)
+is retained as historical v0.4 evidence only.
 
 ## Development
 
 ```bash
 bun install
+bun run lint
 bun run typecheck
 bun test
+bun run build
+bun run build:binary
 bash scripts/security-check.sh   # security regression suite (Linux, needs openssl/curl/ss)
 ```