feat(pi-ext-metered-model): @agentic-kit/pi-ext-metered-model — meter a pi session through the gateway

[pyramation]

Summary

Package 3 of the additive @agentic-kit/* series (plan): a pi extension that makes agentic-server the session's model provider, so a coding-agent run lands in inference_log like every other metered call instead of a parallel accounting scheme.

No custom streaming code is needed — the gateway already speaks OpenAI's /v1/chat/completions, one of pi's built-in api types, so the whole thing is a provider config plus a one-shot model selection:

const metered = createMeteredModelExtension({
  gatewayUrl: 'https://agentic.example.com',   // gateway ROOT; pi appends /v1/...
  identity: { databaseId, entityId, actorId, runToken },
  models: [{ id: 'anthropic/claude-sonnet-4', contextWindow: 200000, maxTokens: 8192 }]
});
// → pi.registerProvider('constructive-gateway', { baseUrl, api: 'openai-completions', headers, models })

Three things that aren't obvious from the code:

• Selection has to happen on session_start. pi.setModel takes a resolved Model, and the registry that resolves it (ctx.modelRegistry.find(provider, id)) is only reachable from an event context — session_start is the first one and fires before the first turn. It throws if the model is absent after registration or if pi refuses it for lack of credentials, rather than leaving the session on whatever model it had.
• Every misconfiguration fails at construction, not at the first turn. Blank databaseId, relative/non-http gatewayUrl, a gatewayUrl ending in /v1 (pi appends its own → /v1/v1/chat/completions), empty model list, and a selectModel that isn't one of the registered ids — that last one is the failure the package exists to prevent, since it would leave pi quietly running an unmetered model.
• Identity can't be shadowed. Caller headers are merged under X-Database-Id/X-Entity-Id/X-Actor-Id, and apiKey falls back to the runToken (then a placeholder) purely to satisfy pi's "models need a key" check — the gateway authenticates on identity. Header trust boundary is documented in the README: off-cluster hosts must send runToken and let the ingress pin identity.

Cost fields default to zeros: the gateway is the pricing authority, and zeros mean "not priced client-side", not free.

This is the cloud lane only; the local/own-keys self-reporting lane is the next package (pi-ext-usage-report).

Verification

pnpm test (25 tests: identity/url/model builders directly, extension driven through a fake ExtensionAPI — no gateway or credentials needed), pnpm build, pnpm lint, and pnpm install --frozen-lockfile. Added to the agentic CI batch in run-tests.yaml.

Developed on top of the pi-ext-run-log branch (#1724, CI green); targets main.

Link to Devin session: https://app.devin.ai/sessions/450ce6d6659c47759c184ae6ec19a2a8
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring