@tangle-network/create-agent-app 0.46.43 → 0.46.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/create-agent-app",
-  "version": "0.46.43",
+  "version": "0.46.44",
   "description": "Create a tested Tangle agent application with either a tool loop or a complete chat interface.",
   "keywords": [
     "tangle",

package/template/_package.json

@@ -21,17 +21,17 @@
     "@tangle-network/agent-app": "__AGENT_APP_VERSION__"
   },
   "peerDependencies": {
-    "@tangle-network/agent-eval": "0.172.1",
+    "@tangle-network/agent-eval": "0.173.1",
     "@tangle-network/agent-integrations": ">=0.53.55 <0.54.0",
-    "@tangle-network/agent-interface": "2.2.0",
-    "@tangle-network/agent-runtime": "0.189.0"
+    "@tangle-network/agent-interface": "2.3.0",
+    "@tangle-network/agent-runtime": "0.191.0"
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.172.1",
+    "@tangle-network/agent-eval": "0.173.1",
     "@tangle-network/agent-integrations": "0.53.55",
-    "@tangle-network/agent-interface": "2.2.0",
-    "@tangle-network/agent-knowledge": "13.0.0",
-    "@tangle-network/agent-runtime": "0.189.0",
+    "@tangle-network/agent-interface": "2.3.0",
+    "@tangle-network/agent-knowledge": "13.0.1",
+    "@tangle-network/agent-runtime": "0.191.0",
     "@tangle-network/sandbox": "0.36.4",
     "@types/node": "^22.20.1",
     "typescript": "^7.0.2",

package/template-chat/AGENTS.md

@@ -3,9 +3,10 @@
 You are a coding agent working in a project generated by `create-agent-app --chat`.
 This project is a thin customization layer on top of `@tangle-network/agent-app`
 (the shell): the whole server chat vertical — auth, thread/message persistence,
-streaming turns with buffered replay, multimodal uploads, human-in-the-loop asks —
-is ASSEMBLED from shell factories, not written here. Walk this contract before you
-touch anything. It is a checklist, not prose — follow it in order.
+streaming turns with buffered replay, multimodal uploads, human-in-the-loop asks,
+and API access — is ASSEMBLED from shell factories, not written here.
+Walk this contract before you touch anything.
+It is a checklist, not prose — follow it in order.
 
 ## 0. Orient
 
@@ -30,14 +31,16 @@ touch anything. It is a checklist, not prose — follow it in order.
 ## 2. DATA vs CODE — know which file you're in
 
 - [ ] DATA → `agent.config.ts`: name, system prompt, model default + effort,
-      harness, renderable ask kinds. Plain values. If you're writing an `if`,
-      you're in the wrong file.
+      provider input limit, harness, gateway pricing, and renderable ask kinds.
+      Plain values. If you're writing an `if`, you're in the wrong file.
 - [ ] DATA → `prompts/system.md`: the persona. State intents and hard rules,
       never implementations — no shell commands, CLI flags, or install scripts.
       The executing agent chooses tools at execution time.
 - [ ] CODE → `src/chat.ts`: the COMPOSER. Wires config + env into the shell's
       factories. Extend seams here (billing hooks, `transformFinalText`,
       `onTurnComplete`); never re-implement what a factory already does.
+- [ ] CODE → `src/gateway.ts`: API keys and OpenAI-compatible requests enter
+      the same owned thread and chat route.
 - [ ] CODE → `src/sandbox.ts`: the sandbox lane (box naming, credentials,
       profile). All agent intelligence lives IN the sandbox; this file only
       reaches it.

package/template-chat/CUSTOMIZE.md

@@ -26,6 +26,8 @@ Discovery: **Whose job does this agent do, in whose voice, under what hard rules
 Discovery: **Which model answers by default, at what effort, on which harness?**
 
 - [ ] Set `model.default` to a model your Tangle Router key can reach.
+- [ ] Set `gateway.maxProviderInputTokens` to that model's full input limit.
+      This covers retained tool and sidecar history that the transcript omits.
 - [ ] Pick `harness` (`opencode` default; vendor-locked harnesses like
       `claude-code` must pair with their own provider's models).
 - [ ] Define the selectable profile catalog for the UI and map each selected
@@ -43,9 +45,11 @@ Discovery: **Where does this app live and what may it spend?**
 - [ ] `wrangler d1 create <name>` → paste `database_id` into `wrangler.toml`.
 - [ ] Copy `.dev.vars.example` → `.dev.vars`; fill `BETTER_AUTH_SECRET`,
       `TANGLE_API_KEY`, `SANDBOX_API_KEY`, `SANDBOX_GATEWAY_URL`.
-- [ ] `pnpm db:migrate:local` — applies `migrations/0001_init.sql` (auth +
-      chat + turn buffer). The e2e test executes this same file, so it cannot
-      silently drift from the schema.
+- [ ] `pnpm db:migrate:local` — applies both migrations (auth, chat, turn
+      buffer, API keys, usage, and request limits).
+      The e2e test executes these same files, so they cannot drift from the schema.
+- [ ] Existing generated app: copy and apply `0002_agent_gateway.sql`.
+      Never edit its already-applied `0001_init.sql`.
 - [ ] Existing app only: add `sandbox_prewarm_claims` in a new migration.
       Do not edit an applied `0001_init.sql`; Wrangler will not run it again.
 - [ ] R2 stays commented out unless the product stores artifacts.
@@ -59,6 +63,9 @@ Discovery: **Does a real message round-trip through a real box?**
       and a usage receipt, and a second turn continues the same agent session.
 - [ ] Kill the tab mid-turn, reopen the thread — the persisted row is intact
       (the turn keeps running server-side and buffers for replay).
+- [ ] Create a key through the signed-in `/api/keys` route.
+- [ ] Call `/v1/agents/<slug>/chat/completions` with that key.
+      Open the returned `X-Tangle-Thread-Url` and confirm it shows the same durable conversation.
 
 ## ⑤ The product UI — replace the dev page
 

package/template-chat/README.md

@@ -4,7 +4,8 @@ A multimodal chat agent product scaffolded with `create-agent-app --chat`, built
 on [`@tangle-network/agent-app`](https://github.com/tangle-network/agent-app):
 the whole server chat vertical — better-auth sessions, thread/message
 persistence with typed parts + usage receipts, streaming turns with buffered
-replay, file uploads, human-in-the-loop asks — assembled from shell factories.
+replay, file uploads, human-in-the-loop asks, personal API keys, and
+OpenAI-compatible access — assembled from shell factories.
 The agent itself runs in a Tangle sandbox (a full harness: skills, tools, bash,
 MCP); this app coordinates UI, durability, and access around it.
 
@@ -15,9 +16,11 @@ MCP); this app coordinates UI, durability, and access around it.
 | `agent.config.ts` | DATA — name, model default, harness, ask kinds | defining the agent |
 | `prompts/system.md` | DATA — the persona (imported as a Text module) | shaping behavior |
 | `src/chat.ts` | CODE — the composer (factories → the chat vertical) | extending seams |
+| `src/gateway.ts` | CODE — API keys → the same chat vertical | API pricing or publication changes |
 | `src/sandbox.ts` | CODE — the sandbox lane (boxes, credentials, profile) | provisioning changes |
 | `src/worker.ts` | CODE — HTTP routing only | adding an endpoint |
 | `src/db/schema.ts` | CODE — auth tables + `createChatTables()` | schema changes (+ migration) |
+| `migrations/0002_agent_gateway.sql` | CODE — API keys, usage, and request claims | upgrading an existing generated app |
 | `migrations/` | SQL the e2e test executes for real | schema changes |
 | `public/index.html` | the dev chat page (not the product UI) | never — replace it (CUSTOMIZE ⑤) |
 | `tests/` | the e2e turn gate this app ships with | extending coverage |

package/template-chat/_package.json

@@ -20,21 +20,23 @@
   },
   "dependencies": {
     "@tangle-network/agent-app": "__AGENT_APP_VERSION__",
-    "@tangle-network/agent-interface": "2.2.0",
-    "@tangle-network/agent-runtime": "0.189.0",
+    "@tangle-network/agent-gateway": "0.8.16",
+    "@tangle-network/agent-interface": "2.3.0",
+    "@tangle-network/agent-runtime": "0.191.0",
     "@tangle-network/sandbox": "0.36.4",
     "better-auth": "^1.7.2",
     "drizzle-orm": "^0.45.2",
+    "hono": "^4.13.5",
     "viem": "^2.0.0"
   },
   "peerDependencies": {
-    "@tangle-network/agent-eval": "0.172.1",
+    "@tangle-network/agent-eval": "0.173.1",
     "@tangle-network/agent-integrations": ">=0.53.55 <0.54.0"
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.172.1",
+    "@tangle-network/agent-eval": "0.173.1",
     "@tangle-network/agent-integrations": "0.53.55",
-    "@tangle-network/agent-knowledge": "13.0.0",
+    "@tangle-network/agent-knowledge": "13.0.1",
     "@cloudflare/workers-types": "^5.20260827.1",
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^22.20.1",

package/template-chat/agent.config.ts

@@ -44,7 +44,7 @@ export const config = {
      * and review it with your default: a stale ladder degrades to today's
      * behavior (the turn fails), never to a silent wrong-model answer.
      */
-    fallbacks: ['gemini-2.5-flash-lite', 'gpt-5-mini'],
+    fallbacks: ['gemini-3.7-flash', 'glm-5.3'],
     /** Default reasoning effort for turns that don't specify one. */
     effort: 'auto',
   },
@@ -62,12 +62,35 @@ export const config = {
    * a card no client will show.
    */
   interactions: { question: true, plan: true },
+
+  /** API-key access to this workspace agent. The browser and API share one
+   *  thread store and one sandbox turn path. */
+  gateway: {
+    enabled: true,
+    description: '__PROJECT_NAME__ workspace agent',
+    pricePerTokenUsd: 0.00002,
+    platformFeePercent: 0.20,
+    /** Maximum provider input for the configured model. Include retained
+     *  sidecar history and tool output that is absent from the transcript. */
+    maxProviderInputTokens: 1_000_000,
+    defaultOutputTokens: 1024,
+    maxOutputTokens: 4096,
+  },
 } as const satisfies {
   name: string
   systemPrompt: string
   model: { default: string; fallbacks: readonly string[]; effort: 'auto' | 'low' | 'medium' | 'high' }
   harness: Harness
   interactions: { question?: boolean; permission?: boolean; plan?: boolean }
+  gateway: {
+    enabled: boolean
+    description: string
+    pricePerTokenUsd: number
+    platformFeePercent: number
+    maxProviderInputTokens: number
+    defaultOutputTokens: number
+    maxOutputTokens: number
+  }
 }
 
 export type Config = typeof config

package/template-chat/migrations/0002_agent_gateway.sql

@@ -0,0 +1,65 @@
+-- External OpenAI-compatible API storage from @tangle-network/agent-gateway.
+-- Keep this separate from 0001 so an existing generated app can apply it.
+
+CREATE TABLE IF NOT EXISTS agent_api_key (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  key_hash TEXT NOT NULL,
+  key_prefix TEXT NOT NULL,
+  scopes TEXT NOT NULL,
+  rate_limit INTEGER NOT NULL,
+  daily_limit INTEGER NOT NULL,
+  spending_limit_cents BIGINT,
+  spent_cents BIGINT NOT NULL DEFAULT 0,
+  last_used_at BIGINT,
+  expires_at BIGINT,
+  created_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_agent_api_key_user ON agent_api_key (user_id, created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_api_key_hash_unique ON agent_api_key (key_hash);
+
+CREATE TABLE IF NOT EXISTS agent_api_key_usage (
+  request_id TEXT PRIMARY KEY,
+  key_id TEXT NOT NULL,
+  cost_cents BIGINT NOT NULL,
+  created_at BIGINT NOT NULL,
+  FOREIGN KEY (key_id) REFERENCES agent_api_key(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_agent_api_key_usage_key ON agent_api_key_usage (key_id, created_at);
+
+CREATE TABLE IF NOT EXISTS agent_api_key_request (
+  request_id TEXT PRIMARY KEY,
+  key_id TEXT NOT NULL,
+  claim_sequence BIGINT NOT NULL,
+  day_bucket BIGINT NOT NULL,
+  created_at BIGINT NOT NULL,
+  FOREIGN KEY (key_id) REFERENCES agent_api_key(id) ON DELETE CASCADE
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_api_key_request_sequence
+  ON agent_api_key_request (key_id, claim_sequence);
+CREATE INDEX IF NOT EXISTS idx_agent_api_key_request_window
+  ON agent_api_key_request (key_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_agent_api_key_request_day
+  ON agent_api_key_request (key_id, day_bucket);
+
+CREATE TABLE IF NOT EXISTS agent_gateway_usage (
+  request_id TEXT PRIMARY KEY,
+  agent_id TEXT NOT NULL,
+  agent_slug TEXT NOT NULL,
+  consumer_id TEXT NOT NULL,
+  payment_method TEXT NOT NULL,
+  input_tokens INTEGER NOT NULL,
+  output_tokens INTEGER NOT NULL,
+  reasoning_tokens INTEGER,
+  tool_tokens INTEGER,
+  tool_call_count INTEGER,
+  provider_cost_nanodollars BIGINT,
+  total_cost_nanodollars BIGINT NOT NULL,
+  owner_earned_nanodollars BIGINT NOT NULL,
+  platform_fee_nanodollars BIGINT NOT NULL,
+  duration_ms BIGINT NOT NULL,
+  settlement_basis TEXT,
+  created_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_agent_gateway_usage_agent ON agent_gateway_usage (agent_id, created_at);

package/template-chat/public/index.html

@@ -73,6 +73,7 @@
 
 <script type="module">
 const $ = (id) => document.getElementById(id)
+const initialThreadId = new URL(location.href).searchParams.get('threadId')
 const state = { threadId: null, parts: [], signUp: false }
 
 const api = async (path, init) => {
@@ -148,6 +149,9 @@ function renderParts(container, parts = []) {
 
 async function openThread(id) {
   state.threadId = id
+  const url = new URL(location.href)
+  url.searchParams.set('threadId', id)
+  history.replaceState(null, '', url)
   const { messages } = await api(`/api/threads/${id}/messages`)
   $('transcript').replaceChildren()
   for (const m of messages) {
@@ -227,10 +231,25 @@ $('composer').onsubmit = async (e) => {
   await runTurn(content, parts).catch((err) => { $('error').textContent = err.message })
 }
 
-$('new-thread').onclick = () => { state.threadId = null; $('transcript').replaceChildren() }
+$('new-thread').onclick = () => {
+  state.threadId = null
+  const url = new URL(location.href)
+  url.searchParams.delete('threadId')
+  history.replaceState(null, '', url)
+  $('transcript').replaceChildren()
+}
 
 await ensureSession()
 await loadThreads()
+if (initialThreadId) {
+  await openThread(initialThreadId).catch((err) => {
+    state.threadId = null
+    $('error').textContent = err.message
+    const url = new URL(location.href)
+    url.searchParams.delete('threadId')
+    history.replaceState(null, '', url)
+  })
+}
 </script>
 </body>
 </html>

package/template-chat/src/chat.ts

@@ -58,6 +58,9 @@ export interface ChatAppOverrides {
   produce?: (args: ChatTurnProduceArgs<void>) => ChatTurnRouteProducer | Promise<ChatTurnRouteProducer>
   /** Test seam: where large uploads land. Default: the workspace box's fs. */
   uploadSink?: (scope: { workspaceId: string; userId: string }) => Promise<SandboxUploadSink | null>
+  /** Server-trusted identity for a private gateway chat assembly. Never read
+   *  this value from a request body or header. */
+  trustedUserId?: string
 }
 
 export interface ChatApp {
@@ -94,6 +97,9 @@ export function buildChatApp(env: AppEnv, overrides: ChatAppOverrides = {}): Cha
   /** Session → identity + thread access, for both routes and seams. Guards
    *  throw JSON Responses; `guardResolution` adapts them to `{ ok, response }`. */
   async function requireUser(request: Request) {
+    if (overrides.trustedUserId) {
+      return { ok: true as const, value: { user: { id: overrides.trustedUserId } } }
+    }
     return guardResolution(() => auth.requireApiUser(request))
   }
 

package/template-chat/src/gateway.ts

@@ -0,0 +1,162 @@
+/**
+ * API-key access to the same persisted chat path the browser uses.
+ *
+ * The gateway translates OpenAI-compatible requests. The chat route still owns
+ * the sandbox turn, transcript, replay buffer, and failure handling.
+ */
+
+import { config } from '../agent.config'
+import { streamChatRouteAsSandboxEvents } from '@tangle-network/agent-app/chat-routes'
+import {
+  createAgentGateway,
+  createApiKeyRequestClaim,
+  createApiKeyRoutes,
+  createApiKeyUsageSettlement,
+  d1ToSqlAdapter,
+  SqlApiKeyStore,
+  SqlGatewayUsageStore,
+  verifyApiKeyFromStore,
+  type SqlAdapter,
+} from '@tangle-network/agent-gateway'
+import { Hono } from 'hono'
+import { buildChatApp, type ChatApp } from './chat'
+import type { AppEnv } from './env'
+import { appSlug } from './sandbox'
+
+export interface GatewayAppOptions {
+  /** Keep the persisted chat turn alive after an API client disconnects. */
+  waitUntil?: (promise: Promise<unknown>) => void
+  /** Test override. Production uses the D1 adapter from agent-gateway. */
+  sql?: SqlAdapter
+  /** Test override. Production builds one private, trusted chat assembly. */
+  createTrustedChatApp?: (ownerId: string) => ChatApp
+}
+
+async function sessionUserId(app: ChatApp, request: Request): Promise<string | null> {
+  try {
+    return (await app.auth.getSession(request))?.user.id ?? null
+  } catch {
+    return null
+  }
+}
+
+async function ensureOwnedThread(
+  app: ChatApp,
+  threadId: string,
+  ownerId: string,
+  firstMessage: string,
+): Promise<void> {
+  const existing = await app.store.getThread(threadId)
+  if (existing) {
+    if (existing.workspaceId !== ownerId) throw new Error('Gateway thread is unavailable')
+    return
+  }
+
+  try {
+    await app.store.createThread({ id: threadId, workspaceId: ownerId, firstMessage })
+  } catch (error) {
+    // Two requests can create the same caller-supplied conversation at once.
+    // The primary key chooses one winner; the loser adopts that owned row.
+    const raced = await app.store.getThread(threadId)
+    if (!raced || raced.workspaceId !== ownerId) throw error
+  }
+}
+
+/** Build the external API surface. The Worker mounts only these Hono routes. */
+export function buildGatewayApp(
+  env: AppEnv,
+  chatApp: ChatApp,
+  options: GatewayAppOptions = {},
+) {
+  const sql = options.sql ?? d1ToSqlAdapter(env.DB)
+  const apiKeys = new SqlApiKeyStore(sql)
+  const usage = new SqlGatewayUsageStore(sql)
+  const trustedChatApp = options.createTrustedChatApp
+    ?? ((ownerId: string) => buildChatApp(env, { trustedUserId: ownerId }))
+
+  const verifyKey = (authorization: string) =>
+    verifyApiKeyFromStore(authorization, apiKeys)
+
+  const gateway = createAgentGateway({
+    resolveAgent: async (slug) => slug === appSlug && config.gateway.enabled
+      ? {
+          id: appSlug,
+          ownerId: appSlug,
+          slug: appSlug,
+          systemPrompt: config.systemPrompt,
+          pricePerTokenUsd: config.gateway.pricePerTokenUsd,
+          platformFeePercent: config.gateway.platformFeePercent,
+          sandboxEndpoint: null,
+          remoteSandboxId: null,
+          remoteBearerToken: null,
+          enabled: true,
+          harness: config.harness,
+          harnessModel: config.model.default,
+          description: config.gateway.description,
+        }
+      : null,
+    verifyApiKey: verifyKey,
+    claimApiKeyRequest: createApiKeyRequestClaim(apiKeys),
+    apiKeyPrefix: 'ak_',
+    conversationMode: 'thread',
+    // A2A task control remains off until the shared gateway owns durable
+    // cross-isolate cancel and replay. OpenAI-compatible calls are independent.
+    a2a: false,
+    authorizeConsumer: async (_agent, consumer) => {
+      if (consumer.method !== 'apikey' || !consumer.ownerId || !consumer.threadId) {
+        return { allow: false, reason: 'API key owner is unavailable', code: 'owner_unavailable' }
+      }
+      const thread = await chatApp.store.getThread(consumer.threadId)
+      if (thread && thread.workspaceId !== consumer.ownerId) {
+        return { allow: false, reason: 'Thread is unavailable', code: 'thread_unavailable' }
+      }
+      return { allow: true }
+    },
+    // A sandbox session can retain private tool output that is absent from the
+    // visible transcript. The model input limit is the only complete bound.
+    unauthenticatedInputTokenBound: config.gateway.maxProviderInputTokens,
+    getSandbox: async (_agent, context) => {
+      const ownerId = context?.keyInfo?.ownerId
+      const threadId = context?.threadId
+      if (!ownerId || !threadId) throw new Error('Gateway request has no verified owner or thread')
+
+      const firstMessage = context.messages
+        .filter((message) => message.role === 'user')
+        .at(-1)?.content ?? ''
+      const app = trustedChatApp(ownerId)
+      await ensureOwnedThread(app, threadId, ownerId, firstMessage)
+
+      return {
+        streamPrompt: (message, streamOptions) => streamChatRouteAsSandboxEvents({
+          routes: app.routes,
+          request: new Request(`${env.BETTER_AUTH_URL}/api/chat`, {
+            headers: { 'X-Gateway-Request-Id': context.requestId },
+          }),
+          payload: {
+            workspaceId: ownerId,
+            threadId,
+            content: message,
+            turnId: context.requestId,
+          },
+          waitUntil: options.waitUntil,
+          signal: streamOptions?.signal,
+          executionLimits: streamOptions?.executionBudget,
+        }),
+      }
+    },
+    recordUsage: usage.recordUsage,
+    ...(options.waitUntil ? { continueOnDisconnect: options.waitUntil } : {}),
+    settlePayment: createApiKeyUsageSettlement(apiKeys),
+    defaultOutputTokens: config.gateway.defaultOutputTokens,
+    maxOutputTokens: config.gateway.maxOutputTokens,
+  })
+
+  const app = new Hono()
+  app.route('/api/keys', createApiKeyRoutes({
+    store: apiKeys,
+    prefix: 'ak_',
+    getAuthUserId: (request) => sessionUserId(chatApp, request),
+  }))
+  app.route('/v1/agents', gateway)
+  return app
+}

package/template-chat/src/sandbox.ts

@@ -107,6 +107,7 @@ export function createSandboxProduce(env: AppEnv) {
     identity,
     prompt,
     executionId,
+    executionLimits,
   }: ChatTurnProduceArgs<void>): Promise<ChatTurnRouteProducer> => {
     const box = await ensureForegroundWorkspaceSandbox(env, shell, {
       workspaceId: identity.tenantId,
@@ -131,7 +132,24 @@ export function createSandboxProduce(env: AppEnv) {
           executionId: attempt === 1 ? executionId : `${executionId}-f${attempt}`,
           model: attemptModel,
           signal,
-          effort: body.effort ?? config.model.effort,
+          // A zero reasoning allowance maps to the profile's supported
+          // no-reasoning control. Positive limits use token ceilings below.
+          effort: executionLimits?.maxReasoningTokens === 0
+            ? 'none'
+            : (body.effort ?? config.model.effort),
+          ...(executionLimits?.maxOutputTokens
+            ? { maxOutputTokens: executionLimits.maxOutputTokens }
+            : {}),
+          ...(executionLimits?.maxReasoningTokens
+            ? { maxReasoningTokens: executionLimits.maxReasoningTokens }
+            : {}),
+          ...(executionLimits?.maxOutputTokens !== undefined
+            && executionLimits.maxReasoningTokens !== undefined
+            ? {
+                maxTotalOutputTokens:
+                  executionLimits.maxOutputTokens + executionLimits.maxReasoningTokens,
+              }
+            : {}),
           harness: config.harness,
           systemPrompt: config.systemPrompt,
           // Durable by default: the run keeps executing server-side if the operator

package/template-chat/src/worker.ts

@@ -14,45 +14,120 @@
  *   POST /api/chat/upload               multipart upload → prompt parts
  *   GET  /api/chat/interactions         outstanding agent asks (?threadId=)
  *   POST /api/chat/interactions         answer an ask
+ *   CRUD /api/keys                      manage personal API keys
+ *   POST /v1/agents/:slug/chat/completions  OpenAI-compatible API
  */
 
-import { buildChatApp } from './chat'
+import { config } from '../agent.config'
+import { buildChatApp, type ChatApp } from './chat'
 import type { AppEnv } from './env'
+import {
+  buildGatewayApp,
+  type GatewayAppOptions,
+} from './gateway'
 
-export default {
-  async fetch(request: Request, env: AppEnv, ctx: ExecutionContext): Promise<Response> {
-    // Per-request assembly is the standard Workers pattern: env only exists
-    // inside fetch, and the factories are cheap closures over it.
-    const app = buildChatApp(env)
-    const url = new URL(request.url)
-    const { pathname } = url
-    const method = request.method
-
-    if (pathname.startsWith('/api/auth/')) return app.auth.auth.handler(request)
-
-    if (pathname === '/api/chat' && method === 'POST') {
-      // Pass waitUntil so the turn keeps running (and buffering for replay)
-      // after a client disconnect.
-      return app.routes.turn(request, ctx)
-    }
-    const replay = pathname.match(/^\/api\/chat\/replay\/([^/]+)$/)
-    if (replay && method === 'GET') return app.routes.replay(request, { turnId: replay[1]! })
-    // Reconnect discovery: which turns are still live on a thread, so a page
-    // reloaded mid-turn re-attaches via /replay instead of losing the run.
-    if (pathname === '/api/chat/running' && method === 'GET') return app.routes.running(request)
-    if (pathname === '/api/chat/upload' && method === 'POST') return app.upload(request)
-    if (pathname === '/api/chat/interactions' && app.routes.interactions) {
-      if (method === 'GET') return app.routes.interactions.list(request)
-      if (method === 'POST') return app.routes.interactions.answer(request)
-    }
-
-    if (pathname === '/api/threads' && method === 'POST') return app.routes.createThread(request)
-    if (pathname === '/api/threads' && method === 'GET') return app.routes.listThreads(request)
-    const transcript = pathname.match(/^\/api\/threads\/([^/]+)\/messages$/)
-    if (transcript && method === 'GET') {
-      return app.routes.threadMessages(request, { threadId: transcript[1]! })
-    }
-
-    return Response.json({ error: 'Not found' }, { status: 404 })
-  },
-} satisfies ExportedHandler<AppEnv>
+export interface WorkerAssembly {
+  buildChatApp(env: AppEnv): ChatApp
+  buildGatewayApp(
+    env: AppEnv,
+    app: ChatApp,
+    options?: GatewayAppOptions,
+  ): ReturnType<typeof buildGatewayApp>
+  /** Test override. Production follows agent.config.ts. */
+  gatewayEnabled?: boolean
+}
+
+function attachThreadUrl(response: Response, request: Request): Response {
+  const threadId = response.headers.get('X-Tangle-Thread-Id')
+  if (!threadId) return response
+  const threadUrl = new URL('/', request.url)
+  threadUrl.searchParams.set('threadId', threadId)
+  const headers = new Headers(response.headers)
+  headers.set('X-Tangle-Thread-Url', threadUrl.toString())
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  })
+}
+
+const defaultAssembly: WorkerAssembly = {
+  buildChatApp,
+  buildGatewayApp,
+  gatewayEnabled: config.gateway.enabled,
+}
+
+/** Build the Worker around one app assembly. Tests inject the real app with a test database. */
+export function createWorker(assembly: WorkerAssembly = defaultAssembly): ExportedHandler<AppEnv> {
+  // Reuse the database-backed chat assembly within one Worker environment.
+  // Build the gateway per request so its background work binds to that
+  // request's ExecutionContext. Durable stores remain authoritative.
+  const instances = new WeakMap<object, ChatApp>()
+
+  const resolveApp = (env: AppEnv) => {
+    const key = env as object
+    const existing = instances.get(key)
+    if (existing) return existing
+    const app = assembly.buildChatApp(env)
+    instances.set(key, app)
+    return app
+  }
+
+  return {
+    async fetch(request: Request, env: AppEnv, ctx: ExecutionContext): Promise<Response> {
+      const url = new URL(request.url)
+      const { pathname } = url
+      const method = request.method
+
+      const isGatewayPath = pathname === '/api/keys'
+        || pathname.startsWith('/api/keys/')
+        || pathname === '/v1/agents'
+        || pathname.startsWith('/v1/agents/')
+      const isUnsupportedA2APath = /^\/v1\/agents\/[^/]+(?:\/\.well-known\/agent\.json)?$/.test(pathname)
+      if (isGatewayPath && assembly.gatewayEnabled === false) {
+        return Response.json({ error: 'Not found' }, { status: 404 })
+      }
+      // Long-running A2A task control is not mounted until agent-gateway owns
+      // durable cross-isolate cancel and replay. OpenAI-compatible calls do
+      // not depend on that unfinished path.
+      if (isUnsupportedA2APath) return Response.json({ error: 'Not found' }, { status: 404 })
+
+      const app = resolveApp(env)
+      if (isGatewayPath) {
+        const gateway = assembly.buildGatewayApp(env, app, {
+          waitUntil: (promise) => ctx.waitUntil(promise),
+        })
+        return attachThreadUrl(await gateway.fetch(request), request)
+      }
+
+      if (pathname.startsWith('/api/auth/')) return app.auth.auth.handler(request)
+
+      if (pathname === '/api/chat' && method === 'POST') {
+        // Pass waitUntil so the turn keeps running (and buffering for replay)
+        // after a client disconnect.
+        return app.routes.turn(request, ctx)
+      }
+      const replay = pathname.match(/^\/api\/chat\/replay\/([^/]+)$/)
+      if (replay && method === 'GET') return app.routes.replay(request, { turnId: replay[1]! })
+      // Reconnect discovery: which turns are still live on a thread, so a page
+      // reloaded mid-turn re-attaches via /replay instead of losing the run.
+      if (pathname === '/api/chat/running' && method === 'GET') return app.routes.running(request)
+      if (pathname === '/api/chat/upload' && method === 'POST') return app.upload(request)
+      if (pathname === '/api/chat/interactions' && app.routes.interactions) {
+        if (method === 'GET') return app.routes.interactions.list(request)
+        if (method === 'POST') return app.routes.interactions.answer(request)
+      }
+
+      if (pathname === '/api/threads' && method === 'POST') return app.routes.createThread(request)
+      if (pathname === '/api/threads' && method === 'GET') return app.routes.listThreads(request)
+      const transcript = pathname.match(/^\/api\/threads\/([^/]+)\/messages$/)
+      if (transcript && method === 'GET') {
+        return app.routes.threadMessages(request, { threadId: transcript[1]! })
+      }
+
+      return Response.json({ error: 'Not found' }, { status: 404 })
+    },
+  }
+}
+
+export default createWorker()

package/template-chat/tests/chat-turn.e2e.test.ts

@@ -16,7 +16,7 @@
  * contract (or the migration from the schema). Fix the drift, not the test.
  */
 
-import { readFileSync } from 'node:fs'
+import { readdirSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import Database from 'better-sqlite3'
@@ -26,6 +26,7 @@ import { describe, expect, it } from 'vitest'
 import {
   createSandboxChatProducer,
   normalizeChatPromptForSandbox,
+  type ChatTurnProduceArgs,
   type ChatTurnRouteProducer,
 } from '@tangle-network/agent-app/chat-routes'
 import type { ChatDatabase } from '@tangle-network/agent-app/chat-store'
@@ -34,28 +35,59 @@ import {
   createMemoryTurnEventStore,
   TURN_EVENTS_MIGRATION_SQL,
 } from '@tangle-network/agent-app/stream'
+import {
+  sqlApiKeyStoreSchemaStatements,
+  sqlGatewayUsageStoreSchemaStatements,
+  type SqlAdapter,
+} from '@tangle-network/agent-gateway'
 
 import { config } from '../agent.config'
 import { buildChatApp, type ChatApp } from '../src/chat'
 import type { AppEnv } from '../src/env'
+import { buildGatewayApp } from '../src/gateway'
+import { appSlug } from '../src/sandbox'
+import { createWorker } from '../src/worker'
 
 const BASE = 'http://localhost:8787'
 const MODEL = 'test/model-1'
 
 // ── fixtures ────────────────────────────────────────────────────────────────
 
-const MIGRATION = join(dirname(fileURLToPath(import.meta.url)), '..', 'migrations', '0001_init.sql')
+const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'migrations')
+const MIGRATIONS = readdirSync(MIGRATIONS_DIR)
+  .filter((name) => /^\d+.*\.sql$/.test(name))
+  .sort()
+  .map((name) => join(MIGRATIONS_DIR, name))
+const BASE_MIGRATION = join(MIGRATIONS_DIR, '0001_init.sql')
+const GATEWAY_MIGRATION = join(MIGRATIONS_DIR, '0002_agent_gateway.sql')
 
 /** The real migration, executed against a real SQLite database. Every query
  *  the test makes afterwards runs over THESE tables — schema drift between
  *  `migrations/` and `src/db/schema.ts` fails here, not in production. */
-function openMigratedDb(): ChatDatabase {
+function openMigratedDb(migrations = MIGRATIONS): {
+  db: ChatDatabase
+  sql: SqlAdapter
+  applyMigration(path: string): void
+} {
   const sqlite = new Database(':memory:')
   sqlite.pragma('foreign_keys = ON')
-  sqlite.exec(readFileSync(MIGRATION, 'utf8'))
+  for (const migration of migrations) sqlite.exec(readFileSync(migration, 'utf8'))
   // better-sqlite3's sync drizzle handle narrows the driver generic; the store
   // treats sync and async drivers identically (builders are awaited).
-  return drizzle(sqlite) as unknown as ChatDatabase
+  return {
+    db: drizzle(sqlite) as unknown as ChatDatabase,
+    sql: {
+      async exec(statement, params = []) {
+        return { rowsAffected: sqlite.prepare(statement).run(...params).changes }
+      },
+      async query<TRow>(statement: string, params: readonly unknown[] = []) {
+        return sqlite.prepare(statement).all(...params) as TRow[]
+      },
+    },
+    applyMigration(path) {
+      sqlite.exec(readFileSync(path, 'utf8'))
+    },
+  }
 }
 
 /** Raw sidecar events, exactly as `streamSandboxPrompt` would yield them from
@@ -84,18 +116,28 @@ const env: AppEnv = {
 
 interface Harness {
   app: ChatApp
+  workerFetch(request: Request): Promise<Response>
+  sql: SqlAdapter
   cookie: string
+  gatewayBuilds(): number
   settle(): Promise<unknown>
 }
 
 async function createHarness(
-  produce: () => ChatTurnRouteProducer = () =>
+  produce: (args: ChatTurnProduceArgs<void>) => ChatTurnRouteProducer = () =>
     createSandboxChatProducer({ events: feed(RAW_TURN_EVENTS), model: MODEL }),
 ): Promise<Harness> {
-  const app = buildChatApp(env, {
-    db: openMigratedDb(),
+  const database = openMigratedDb()
+  const pending: Promise<unknown>[] = []
+  let gatewayBuildCount = 0
+  const chatOverrides = {
+    db: database.db,
     turnStore: createMemoryTurnEventStore(),
     produce,
+    uploadSink: async () => null,
+  }
+  const app = buildChatApp(env, {
+    ...chatOverrides,
     uploadSink: async () => null, // inline uploads only; no box in tests
   })
   // Real sign-up through better-auth; the returned cookie is what a browser
@@ -113,11 +155,42 @@ async function createHarness(
     .map((c) => c.split(';')[0]!)
     .join('; ')
 
-  const pending: Promise<unknown>[] = []
   const originalTurn = app.routes.turn
   app.routes.turn = (request) =>
     originalTurn(request, { waitUntil: (p) => void pending.push(p) })
-  return { app, cookie, settle: () => Promise.all(pending) }
+  const worker = createWorker({
+    buildChatApp: () => app,
+    buildGatewayApp: (_env, chatApp, options) => {
+      gatewayBuildCount += 1
+      return buildGatewayApp(env, chatApp, {
+        ...options,
+        sql: database.sql,
+        createTrustedChatApp: (ownerId) => buildChatApp(env, {
+          ...chatOverrides,
+          trustedUserId: ownerId,
+        }),
+      })
+    },
+  })
+  const executionContext = {
+    waitUntil: (promise: Promise<unknown>) => void pending.push(promise),
+    passThroughOnException: () => undefined,
+    props: {},
+  } as ExecutionContext
+  const workerHandler = worker.fetch
+  if (!workerHandler) throw new Error('Generated Worker has no fetch handler')
+  return {
+    app,
+    workerFetch: async (request) => workerHandler(
+      request as Parameters<typeof workerHandler>[0],
+      env,
+      executionContext,
+    ),
+    sql: database.sql,
+    cookie,
+    gatewayBuilds: () => gatewayBuildCount,
+    settle: () => Promise.all(pending),
+  }
 }
 
 function post(path: string, cookie: string, body: unknown): Request {
@@ -142,6 +215,22 @@ function eventsOf(lines: Array<Record<string, unknown>>): Array<Record<string, u
   return lines.map((l) => (l.kind === 'event' ? (l.event as Record<string, unknown>) : l))
 }
 
+async function readGatewayText(response: Response): Promise<string> {
+  const body = await response.text()
+  return body
+    .split('\n')
+    .filter((line) => line.startsWith('data: ') && line !== 'data: [DONE]')
+    .map((line) => JSON.parse(line.slice(6)) as {
+      choices?: Array<{ delta?: { content?: string } }>
+      error?: { message?: string }
+    })
+    .map((frame) => {
+      if (frame.error) throw new Error(frame.error.message ?? 'gateway stream failed')
+      return frame.choices?.[0]?.delta?.content ?? ''
+    })
+    .join('')
+}
+
 // ── the gate ────────────────────────────────────────────────────────────────
 
 describe('e2e: fake sandbox producer → streamed turn → persisted transcript', () => {
@@ -215,7 +304,10 @@ describe('e2e: fake sandbox producer → streamed turn → persisted transcript'
       | undefined
     expect(toolCall?.call?.toolName).toBe('record_search')
     expect(events).toContainEqual(
-      expect.objectContaining({ type: 'usage', usage: { promptTokens: 40, completionTokens: 20 } }),
+      expect.objectContaining({
+        type: 'usage',
+        usage: expect.objectContaining({ promptTokens: 40, completionTokens: 20 }),
+      }),
     )
     await settle()
 
@@ -272,12 +364,337 @@ describe('e2e: fake sandbox producer → streamed turn → persisted transcript'
 
   it('the migration carries the turn-buffer DDL the /stream store expects, verbatim', () => {
     const normalize = (sql: string) => sql.replace(/\s+/g, ' ').trim()
-    expect(normalize(readFileSync(MIGRATION, 'utf8'))).toContain(normalize(TURN_EVENTS_MIGRATION_SQL))
+    expect(normalize(readFileSync(BASE_MIGRATION, 'utf8'))).toContain(normalize(TURN_EVENTS_MIGRATION_SQL))
   })
 
   it('the migration carries the fenced sandbox claim table, verbatim', () => {
     const normalize = (sql: string) => sql.replace(/\s+/g, ' ').replace(/;$/, '').trim()
-    expect(normalize(readFileSync(MIGRATION, 'utf8'))).toContain(normalize(PREWARM_CLAIM_TABLE_DDL))
+    expect(normalize(readFileSync(BASE_MIGRATION, 'utf8'))).toContain(normalize(PREWARM_CLAIM_TABLE_DDL))
+  })
+
+  it('the migration carries every agent-gateway SQL store statement', () => {
+    const migration = readFileSync(GATEWAY_MIGRATION, 'utf8')
+    const normalize = (sql: string) => sql.replace(/\s+/g, ' ').replace(/;$/, '').trim()
+    const statements = [
+      ...sqlApiKeyStoreSchemaStatements(),
+      ...sqlGatewayUsageStoreSchemaStatements(),
+    ]
+
+    for (const statement of statements) {
+      expect(normalize(migration)).toContain(normalize(statement))
+    }
+  })
+
+  it('upgrades a database that already applied the original chat migration', async () => {
+    const migrated = openMigratedDb([BASE_MIGRATION])
+    const tableNames = async () => (await migrated.sql.query<{ name: string }>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'agent_%' ORDER BY name",
+    )).map((row) => row.name)
+
+    expect(await tableNames()).toEqual([])
+    migrated.applyMigration(GATEWAY_MIGRATION)
+    expect(await tableNames()).toEqual([
+      'agent_api_key',
+      'agent_api_key_request',
+      'agent_api_key_usage',
+      'agent_gateway_usage',
+    ])
+  })
+
+  it('shares one owned thread across OpenAI-compatible API calls', async () => {
+    const { app, workerFetch, sql, cookie, gatewayBuilds, settle } = await createHarness()
+    const cardResponse = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/.well-known/agent.json`,
+    ))
+    expect(cardResponse.status).toBe(404)
+
+    const keyResponse = await workerFetch(post('/api/keys', cookie, {
+      name: 'coding agent',
+      rateLimit: 2,
+      dailyLimit: 2,
+    }))
+    expect(keyResponse.status).toBe(201)
+    const { key } = (await keyResponse.json()) as { key: string }
+
+    const openAiResponse = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/chat/completions`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: 'File my lease summary' }],
+          stream: true,
+        }),
+      },
+    ))
+    expect(openAiResponse.status).toBe(200)
+    const threadId = openAiResponse.headers.get('X-Tangle-Thread-Id')
+    expect(threadId).toBeTruthy()
+    expect(openAiResponse.headers.get('X-Tangle-Thread-Url')).toBe(
+      `${BASE}/?threadId=${encodeURIComponent(threadId!)}`,
+    )
+    expect(await readGatewayText(openAiResponse)).toBe('Filed the summary.')
+    await settle()
+
+    const thread = await app.store.getThread(threadId!)
+    expect(thread).toMatchObject({ id: threadId, workspaceId: expect.any(String) })
+    expect(await app.store.listMessages(threadId!)).toHaveLength(2)
+    expect(await sql.query(`
+      SELECT input_tokens, output_tokens, reasoning_tokens, tool_tokens,
+        tool_call_count, provider_cost_nanodollars, total_cost_nanodollars,
+        settlement_basis
+      FROM agent_gateway_usage
+    `)).toEqual([{
+      input_tokens: 40,
+      output_tokens: 20,
+      reasoning_tokens: 5,
+      tool_tokens: 0,
+      tool_call_count: 1,
+      provider_cost_nanodollars: 12_300_000,
+      total_cost_nanodollars: 12_300_000,
+      settlement_basis: 'usage-receipt',
+    }])
+    expect(await sql.query('SELECT request_id FROM agent_api_key_usage')).toHaveLength(1)
+    expect(await sql.query('SELECT request_id FROM agent_api_key_request')).toHaveLength(1)
+
+    const continuedResponse = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/chat/completions`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${key}`,
+          'Content-Type': 'application/json',
+          'X-Tangle-Thread-Id': threadId!,
+        },
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: 'Continue the same work' }],
+          stream: true,
+        }),
+      },
+    ))
+    expect(continuedResponse.status).toBe(200)
+    expect(continuedResponse.headers.get('X-Tangle-Thread-Id')).toBe(threadId)
+    expect(await readGatewayText(continuedResponse)).toBe('Filed the summary.')
+    await settle()
+    expect(await app.store.listMessages(threadId!)).toHaveLength(4)
+    expect(await sql.query('SELECT request_id FROM agent_api_key_request')).toHaveLength(2)
+    expect(await sql.query('SELECT request_id FROM agent_gateway_usage')).toHaveLength(2)
+    expect(await sql.query('SELECT request_id FROM agent_api_key_usage')).toHaveLength(2)
+
+    await app.store.createThread({
+      id: 'another-users-thread',
+      workspaceId: 'another-user',
+      title: 'Private',
+    })
+    const probeKeyResponse = await workerFetch(post('/api/keys', cookie, {
+      name: 'thread probe',
+      rateLimit: 1,
+      dailyLimit: 1,
+    }))
+    expect(probeKeyResponse.status).toBe(201)
+    const { key: probeKey } = (await probeKeyResponse.json()) as { key: string }
+    const denied = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/chat/completions`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${probeKey}`,
+          'Content-Type': 'application/json',
+          'X-Tangle-Thread-Id': 'another-users-thread',
+        },
+        body: JSON.stringify({ messages: [{ role: 'user', content: 'Open it' }] }),
+      },
+    ))
+    expect(denied.status).toBe(403)
+    expect(await sql.query('SELECT request_id FROM agent_api_key_request')).toHaveLength(2)
+
+    const rateLimited = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/chat/completions`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: 'This third turn must not run' }],
+          stream: true,
+        }),
+      },
+    ))
+    expect(rateLimited.status).toBe(429)
+    expect(await app.store.listMessages(threadId!)).toHaveLength(4)
+    expect(await sql.query('SELECT request_id FROM agent_api_key_request')).toHaveLength(2)
+    expect(gatewayBuilds()).toBe(6)
+  })
+
+  it('finishes the linked browser transcript after the API client disconnects', async () => {
+    let releaseTurn = () => {}
+    const canFinish = new Promise<void>((resolve) => {
+      releaseTurn = resolve
+    })
+    async function* delayedEvents(): AsyncGenerator<Record<string, unknown>> {
+      yield {
+        type: 'message.part.updated',
+        data: {
+          part: { type: 'text', id: 'answer', text: 'Started. ' },
+          delta: 'Started. ',
+        },
+      }
+      await canFinish
+      yield {
+        type: 'message.part.updated',
+        data: {
+          part: { type: 'text', id: 'answer', text: 'Started. Finished.' },
+          delta: 'Finished.',
+        },
+      }
+      yield {
+        type: 'message.part.updated',
+        data: {
+          part: {
+            type: 'step-finish',
+            reason: 'stop',
+            tokens: { input: 7, output: 3, reasoning: 1 },
+            cost: 0.00021,
+          },
+        },
+      }
+      yield { type: 'result', data: { finalText: 'Started. Finished.' } }
+    }
+    const { app, workerFetch, sql, cookie, settle } = await createHarness(() =>
+      createSandboxChatProducer({ events: delayedEvents(), model: MODEL }))
+    const keyResponse = await workerFetch(post('/api/keys', cookie, {
+      name: 'disconnect test',
+      rateLimit: 1,
+      dailyLimit: 1,
+    }))
+    const { key } = (await keyResponse.json()) as { key: string }
+
+    const response = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/chat/completions`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: 'Complete this after I leave' }],
+          stream: true,
+        }),
+      },
+    ))
+    expect(response.status).toBe(200)
+    const threadId = response.headers.get('X-Tangle-Thread-Id')
+    expect(response.headers.get('X-Tangle-Thread-Url')).toBe(
+      `${BASE}/?threadId=${encodeURIComponent(threadId!)}`,
+    )
+
+    const reader = response.body!.getReader()
+    const decoder = new TextDecoder()
+    let visible = ''
+    while (!visible.includes('Started.')) {
+      const chunk = await reader.read()
+      if (chunk.done) throw new Error('Gateway stream ended before its first answer text')
+      visible += decoder.decode(chunk.value, { stream: true })
+    }
+    await reader.cancel()
+
+    const runningResponse = await app.routes.running(new Request(
+      `${BASE}/api/chat/running?threadId=${encodeURIComponent(threadId!)}`,
+      { headers: { cookie } },
+    ))
+    expect(runningResponse.status).toBe(200)
+    const { running } = (await runningResponse.json()) as { running: string[] }
+    expect(running).toHaveLength(1)
+    const replay = await app.routes.replay(
+      new Request(`${BASE}/api/chat/replay/${running[0]}?fromSeq=0`, { headers: { cookie } }),
+      { turnId: running[0]! },
+    )
+    const replayLines = readLines(replay)
+
+    releaseTurn()
+    await settle()
+
+    const messages = await app.store.listMessages(threadId!)
+    expect(messages).toHaveLength(2)
+    expect(messages[1]).toMatchObject({ role: 'assistant', content: 'Started. Finished.' })
+    const events = eventsOf(await replayLines)
+    expect(events.filter((event) => event.type === 'text').map((event) => event.text).join(''))
+      .toBe('Started. Finished.')
+    expect(events.at(-1)).toMatchObject({ type: 'turn_status', status: 'complete' })
+    expect(await sql.query(`
+      SELECT input_tokens, output_tokens, reasoning_tokens, provider_cost_nanodollars
+      FROM agent_gateway_usage
+    `)).toEqual([{
+      input_tokens: 7,
+      output_tokens: 3,
+      reasoning_tokens: 1,
+      provider_cost_nanodollars: 210_000,
+    }])
+    expect(await sql.query('SELECT request_id FROM agent_api_key_usage')).toHaveLength(1)
+  })
+
+  it('passes the complete provider budget into the shared chat turn', async () => {
+    let receivedLimits: ChatTurnProduceArgs<void>['executionLimits']
+    const { workerFetch, cookie, settle } = await createHarness((args) => {
+      receivedLimits = args.executionLimits
+      return createSandboxChatProducer({ events: feed(RAW_TURN_EVENTS), model: MODEL })
+    })
+    const keyResponse = await workerFetch(post('/api/keys', cookie, {
+      name: 'budget test',
+      rateLimit: 1,
+      dailyLimit: 1,
+    }))
+    const { key } = (await keyResponse.json()) as { key: string }
+
+    const response = await workerFetch(new Request(
+      `${BASE}/v1/agents/${appSlug}/chat/completions`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: 'Use the bounded path' }],
+          max_tokens: 321,
+          stream: true,
+        }),
+      },
+    ))
+
+    expect(response.status).toBe(200)
+    await readGatewayText(response)
+    await settle()
+    expect(receivedLimits).toMatchObject({
+      maxInputTokens: config.gateway.maxProviderInputTokens,
+      maxOutputTokens: 321,
+      maxReasoningTokens: 321,
+      maxToolTokens: 321,
+      maxToolCalls: 8,
+    })
+    expect(receivedLimits?.maxProviderCostUsd).toBeGreaterThan(0)
+  })
+
+  it('does not mount API-key or agent routes when the gateway is disabled', async () => {
+    const database = openMigratedDb()
+    const app = buildChatApp(env, {
+      db: database.db,
+      turnStore: createMemoryTurnEventStore(),
+      produce: () => createSandboxChatProducer({ events: feed(RAW_TURN_EVENTS), model: MODEL }),
+    })
+    const worker = createWorker({
+      buildChatApp: () => app,
+      buildGatewayApp: (_env, chatApp) => buildGatewayApp(env, chatApp, { sql: database.sql }),
+      gatewayEnabled: false,
+    })
+    const fetch = worker.fetch
+    if (!fetch) throw new Error('Generated Worker has no fetch handler')
+    const context = {
+      waitUntil: () => undefined,
+      passThroughOnException: () => undefined,
+      props: {},
+    } as unknown as ExecutionContext
+
+    const [keys, agents] = await Promise.all([
+      fetch(new Request(`${BASE}/api/keys`), env, context),
+      fetch(new Request(`${BASE}/v1/agents/${appSlug}/.well-known/agent.json`), env, context),
+    ])
+    expect(keys.status).toBe(404)
+    expect(agents.status).toBe(404)
   })
 
   it('agent.config carries a real system prompt (prompts/system.md is wired)', () => {