[AK-684] Evaluate + adopt Agent Auth open standard (discovery, OpenAPI→capabilities, approval-gated scoped JWTs)

[robinbraemer]

Migrated from Linear: AK-684

GitHub is the canonical source of truth. The Linear issue is archived.

---

Why

Two adjacent needs the Agent Auth open standard could solve at once: (1) the agent sandboxes we run still inherit raw env credentials with no short-lived, capability-scoped, audience-bound token to present back to /v1; (2) third parties hosting their own agents should discover + use our API natively, with human approvals surfacing in our existing dashboard — without a bespoke integration per partner. We're unusually well-positioned because CEP-0036 already shipped the hard parts (approvals resource + UI, JWT issuance with audience binding, device-authorization flow, per-operationId OpenAPI, MCP transport). This is a durable ecosystem bet worth not losing track of.

Full design exploration (every external claim cited to source): internal/superpowers/specs/2026-05-29-agent-auth-standard-design.md.

Description

Resolve the open decision forks in §7 of the design doc via a Superpowers brainstorm, then turn the chosen entry point into an implementation plan (writing-plans). The doc decomposes the work into three independent, separately-shippable layers — spec/plan/build each on its own cycle:

• Layer (b) — OpenAPI→capabilities (recommended first): generate one capability per operationId from docs/openapi-public.json (already emitted + CI-gated). Highest value-to-cost; leans entirely on artifacts we own.
• Layer (a) — discovery + MCP interop: author /.well-known/agent-configuration + standard agent-auth token verification so third-party / MCP agents interoperate. Small additive surface; cost depends on conformance depth.
• Layer (c) — approval-gated short-lived scoped JWTs: mint aud/capabilities/jti JWTs off approval decisions on the existing approvalRequests domain; replace the sandbox raw-env handoff (packages/domains/agents/src/runtime/harnesses/claude-code/adapter.ts:121-127). Closes the §1.1 gap but is security-boundary code — must be TDD'd hard, sequenced after a clear jti/minting design.

Already-resolved in the doc:

• Better Auth @better-auth/agent-auth plugin → reference-only for now (separate v0.x package, peer better-auth >=1.4.0 so no core upgrade needed; but young, two of its four tables — agent, approval — fork shipped CEP-0036 work, and the Convex adapter needs manual schema transcription). Re-evaluate only after a time-boxed spike.
• workspace = Better Auth organization? → keep native Convex workspace/org (§6 UPDATE). Agent grants anchor to our native workspaceId, consistent with the API-token plan. This lowers the plugin's marginal value and favors building layers over our own primitives.

Open forks to brainstorm (§7): conformance depth for (a); who owns capability generation in (b) — our own generator vs createFromOpenAPI; approval-strength policy + where it lives for (c); jti replay store + scoped-JWT minting location; sandbox mid-turn token refresh; delegated vs autonomous mode for ambient agents.

Acceptance Criteria

• §7 decision forks resolved and recorded in the design doc
• First implementation layer chosen (lean: layer (b)) and turned into a written plan under internal/superpowers/plans/
• Time-boxed spike scoped (or explicitly deferred) for the @better-auth/agent-auth plugin + Convex-adapter non-CRUD flow question

Out of Scope

• Building any layer before the brainstorm + plan land — this issue tracks the decision/plan, not the implementation
• Reopening the workspace=organization decision (resolved: keep native) → see §6 of the design doc