v0.12 migration notes

Operator-facing summary of what changes when you upgrade pmk gateway from v0.11.x to v0.12.0.

TL;DR

✅ Zero config changes required if you already have ANTHROPIC_API_KEY set.
✅ Existing ~/.pmk/gateway.json is back-fill-compatible (apiKey field
   is optional and additive).
✅ Users without an API key keep running on the claude-agent fallback —
   no behavioural change.
✅ Cap defaults bumped 25k/12k/16k → 60k/30k/40k. PMK_*_CAP still
   overrides per host.

What changed

Provider auto-resolution

Before (v0.11.x):

1. local `claude` binary → ClaudeAgentSdkProvider
2. ANTHROPIC_API_KEY → AnthropicApiKeyProvider
3. fail

After (v0.12.0):

1. ANTHROPIC_API_KEY (or config.apiKey) → AnthropicApiKeyProvider
2. local `claude` binary → ClaudeAgentSdkProvider (fallback)
3. fail

Why: ClaudeAgentSdkProvider spawns the local claude CLI and inherits the host's ~/.claude/ config (skills/hooks/MCP descriptions) as un-budgeted system context. On a heavy host this can add 10s of thousands of tokens to every API call. AnthropicApiKeyProvider calls the API directly with a clean system prompt — no overhead, predictable budgets.

gateway init prompts for the API key

After the Slack token prompts, init now asks for ANTHROPIC_API_KEY. The value is stored in ~/.pmk/gateway.json at mode 0600 alongside Slack tokens. Skip with empty input to fall back to the env var.

Already-running gateway daemons do not pick up a newly-saved apiKey until they restart. This matches the existing audience/escalation config-mutation pattern. Restart with the standard kill $(cat ~/.pmk/gateway/gateway.pid) && nohup pmk gateway start &; the v0.11.0 marker mechanism keeps the restart silent in Slack within the 5-minute window.

New token.usage event in events log

JSONL line (synthetic sample — actor: "U…" is a redacted Slack user ID; at is ISO-8601):

{"at":"…","type":"token.usage","actor":"U…","provider":"anthropic-api","model":"claude-sonnet-4-6","inputTokens":12345,"outputTokens":678,"cacheReadTokens":9000}

cacheReadTokens / cacheCreationTokens present only when prompt caching was active. The claude-agent fallback path does not emit token.usage (the SDK does not surface per-call usage in a comparable way) — this event is anthropic-api-only.

pmk gateway audit Token usage section

Token usage
  total in / out:                12.3k / 0.7k tokens
  cache read:                    9.0k tokens
  per-actor (top 3):             U… 8.2k in, U… 3.1k in, U… 1.0k in
  per-model:                     claude-sonnet-4-6 (12.3k in / 0.7k out)

Always rendered (zero counts visible as (none)). cache read line shown only when non-zero. No $ calculation — that's deferred to a future release.

Cap defaults bumped

Env var	v0.11.1 default	v0.12.0 default
PMK_MAX_SESSION_TOKENS	25_000	60_000
PMK_SEED_CAP	12_000	30_000
PMK_MRA_RESULT_CAP	16_000	40_000

If you're on the claude-agent fallback (no API key), tighten these back down — the SDK overhead is still in play on that path.

Upgrade checklist (v0.11.x → v0.12.0)

1. git pull && npm run cli:build — no schema migration.
2. If you have ANTHROPIC_API_KEY set: restart the gateway. v0.12 auto-switches to anthropic-api. Verify with tail -f ~/.pmk/gateway/events-$(date -u +%Y-%m).log | grep token.usage.
3. If you don't: nothing to do — v0.12 invisible except for the bumped caps. Optionally run pmk gateway init to set the API key (writes to gateway.json).
4. After a week, run pmk gateway audit --days 7 and check the Token usage section.
5. To stay on claude-agent explicitly: export PMK_PROVIDER=claude-agent (overrides auto). The fallback path is supported indefinitely.

See also

• v0.11 migration notes — preceding milestone
• Changelog