@agent-native/core 0.92.12 → 0.94.0

package/dist/templates/workspace-core/.agents/skills/capture-learnings/SKILL.md

@@ -11,11 +11,14 @@ metadata:
 
 # Capture Learnings
 
-This is background knowledge, not a slash command. **Your memory index is loaded at the start of every conversation.** Use `save-memory` proactively when you learn something worth remembering.
+This is background knowledge, not a slash command. **Organization learnings and your personal memory index are loaded at the start of every conversation, including Slack/integration turns.** Capture durable context proactively when you learn something worth remembering.
 
 ## How to Read & Write Memories
 
-Memories are stored as **resources** in the SQL database (personal scope), not as files on disk.
+Memories are stored as **resources** in the SQL database, not as files on disk.
+
+- **Team/organization knowledge:** shared `LEARNINGS.md`. Read it first, merge the new fact, then write the full updated file with the `resources` tool using `scope: "shared"`. Shared scope resolves to the active organization; it must never leak to another organization in the same deployment.
+- **Personal knowledge:** `memory/MEMORY.md` plus `memory/<name>.md`, written with `save-memory`.
 
 - **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
 - **Read a memory:** `resource-read --path memory/<name>.md`
@@ -33,6 +36,14 @@ Memories are stored as **resources** in the SQL database (personal scope), not a
 
 ## When to Capture
 
+### Team and organization knowledge (`LEARNINGS.md`, shared scope)
+- Canonical destinations and workflows (for example, which Content database receives a type of Slack request)
+- Required intake fields, ownership, prioritization conventions, metric definitions, and approved terminology
+- Durable external references that the whole team needs, including the canonical page/database URL
+- Corrections or decisions that should affect every organization member's future Slack and app conversations
+
+Store the fact and a concise provenance link when available. Do not paste full private conversations, customer data, credentials, or secrets into learnings. Put stable always-on policy in shared `AGENTS.md`; put learned facts and evolving conventions in shared `LEARNINGS.md`.
+
 ### User Preferences & Memory (`user`)
 - **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
 - **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
@@ -58,19 +69,21 @@ Memories are stored as **resources** in the SQL database (personal scope), not a
 - Things obvious from reading the code
 - Standard language/framework behavior
 - Temporary debugging notes
-- Anything already in AGENTS.md or skills
+- Anything already in AGENTS.md, shared LEARNINGS.md, or skills
 - Ephemeral task details (use tasks/plans instead)
 
 ## Key Rules
 
-1. **Save proactively — don't ask permission.** When you learn something, save it immediately.
-2. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
-3. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
-4. **Keep descriptions concise** — the index is loaded every conversation
-5. **Memories are SQL-backed** — safe for personal info, persist across sessions, not in git
+1. **Save proactively — don't ask permission.** When you learn something durable, save it immediately at the correct scope.
+2. **Choose scope by audience.** Organization workflow or reference → shared `LEARNINGS.md`; one person's preference/context → personal memory.
+3. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
+4. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
+5. **Keep descriptions concise** — the index is loaded every conversation
+6. **Memories are SQL-backed** — they persist across sessions and are not in git; still minimize sensitive content
 
 ## Graduation
 
 When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
-- Saving a memory is lightweight (auto-apply, personal scope)
+- Saving a personal memory is lightweight (auto-apply, personal scope)
+- Shared LEARNINGS.md is the lightweight organization knowledge layer
 - Updating AGENTS.md or a skill is heavier (affects all users/agents)

package/dist/templates/workspace-core/.agents/skills/extension-points/SKILL.md

@@ -195,9 +195,12 @@ the `slot-installs` query and the host re-renders without the iframe.
 - **Not a slot manifest.** Slot targets live in the `tool_slots` table
   (Drizzle export `extensionSlots`), not in the extension's HTML content.
   The agent can re-target an extension without rewriting it.
-- **Not for arbitrary code modification.** If a user wants to change how
-  the app itself behaves (not add a sandboxed widget), use the
-  `self-modifying-code` skill instead.
+- **Not for arbitrary code modification.** If the exact request needs UI inside
+  a native component or at a location with no slot, do not stop at "slots
+  cannot do that" or silently move it elsewhere. Treat it as full app
+  customization: use `connect-builder` for the Builder.io Cloud Agent/local
+  editing handoff in hosted chat, or follow `self-modifying-code` in a local
+  code-editing surface.
 
 ## Cross-references
 

package/dist/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -51,6 +51,31 @@ and Alpine.js runtime.
 - Action files in `actions/`
 - Routes
 
+## When the Request Needs Code Instead
+
+Route by the user's exact outcome, not by whether they called it an
+"extension." Extensions render only on their own page or inside an existing
+named `ExtensionSlot`; they cannot inject UI into arbitrary native components,
+replace built-in views, or appear at a location where the host app has no slot.
+
+If the requested placement or behavior requires changing native components,
+host layout/styles/routes/business logic, or adding a new slot:
+
+1. Briefly explain the extension boundary.
+2. Do **not** stop at "an extension cannot do that," and do not silently move the
+   UI to a less useful slot.
+3. Continue through the normal source-code customization flow:
+   - In hosted/app-rendered chat, call `connect-builder`. When its
+     `builderEnabled` result is true, offer the Builder.io Cloud Agent handoff;
+     when false, say the change can be made with local code editing, Agent
+     Native Desktop, or Builder.io cloud editing.
+   - In a local development or outer code-editing surface, follow the
+     `self-modifying-code` skill and edit the app source directly.
+
+Full source-code customization is a core Agent Native capability. Extensions
+are the fast, sandboxed, no-deploy layer—not the limit of what the app can
+become.
+
 **When a user asks to "make an extension", "create an extension", or "build
 a ... extension" (or the older phrasings "make a tool" / "create a tool"):**
 

package/dist/templates/workspace-core/.agents/skills/integration-webhooks/SKILL.md

@@ -298,6 +298,21 @@ queue + retry job for at-least-once delivery.
 6. **Reply not delivered?** The processor likely succeeded but
    `adapter.sendResponse` failed — check the adapter's outbound logs.
 
+## Automation connectors
+
+Workflow systems such as n8n and Zapier are not messaging channels. Do not add
+them as `PlatformAdapter`s or route them through `provider-api`.
+
+For n8n-style workflow invocation and callbacks, use
+`@agent-native/core/automation` with static workflow IDs and allow-listed
+origins. Agents provide structured input, never a target URL or credential.
+Callbacks must verify a configured secret/signature, claim a durable event ID,
+enqueue work through the established queue, and acknowledge quickly.
+
+Zapier is blueprint-only unless the app implements Zapier's explicit REST Hook
+subscribe/unsubscribe contract or configures a separate Zapier MCP connection.
+Do not imply a generic Zapier workflow-execution API exists.
+
 ## Related Skills
 
 - `server-plugins` — How `/_agent-native/` routes get mounted

package/dist/templates/workspace-core/.agents/skills/voice-transcription/SKILL.md

@@ -13,17 +13,21 @@ metadata:
 
 # Voice Transcription
 
-Click-to-toggle microphone inside the sidebar composer turns speech into
-text. Users configure live transcription separately from AI cleanup in
-Settings → Voice Transcription. The feature is available in every template
-that renders `TiptapComposer`.
+The microphone inside the sidebar composer offers two distinct paths:
+editable dictation and an opt-in realtime speech-to-speech agent session.
+Users configure dictation separately from AI cleanup in Settings → Voice
+Transcription. Both paths are available in every template that renders the
+shared agent sidebar.
 
 ## UX rules
 
 - **Always show the mic alongside the send button.** Cursor replaces send
   with mic when the composer is empty; their users complain. We keep both
   visible — Lovable does the same.
-- **Click-to-toggle, not push-to-talk.** More forgiving in a sidebar, avoids
+- **Ask before switching modes.** The mic opens a shadcn popover offering
+  **Start voice mode** and **Keep dictating**; never silently replace the
+  established dictation behavior.
+- **Dictation is click-to-toggle, not push-to-talk.** More forgiving in a sidebar, avoids
   host-app hotkey clashes. Keyboard shortcut is `Cmd/Ctrl+Shift+M` and
   `Escape` cancels mid-recording.
 - **Transcript lands in the composer, editable, never auto-sent.** Insert at
@@ -34,6 +38,31 @@ that renders `TiptapComposer`.
   Never use a sparkle or robot icon.
 - **Errors via inline alert or toast, never `window.alert`.**
 
+## Realtime speech mode
+
+Realtime speech mode is a full-duplex OpenAI Realtime WebRTC session, separate
+from the dictation providers below. It requires the authenticated user's
+`OPENAI_API_KEY`, uses the server-owned `gpt-realtime-2.1` session
+configuration, and keeps the key out of browser code.
+
+- Starting voice mode collapses the chat into a persistent bottom-end speech
+  orb. Clicking the orb shows or hides chat without ending the session; ending
+  the session is a separate, explicit control.
+- Semantic VAD keeps listening, starts responses automatically, and supports
+  barge-in while the agent is speaking.
+- Function calls must cross the authenticated realtime tool bridge and enter
+  `executeAgentToolCall`. Never call `ActionEntry.run` directly: that bypasses
+  schema validation, approvals, audit/journal behavior, timeouts, redaction,
+  and mutation refreshes.
+- Preserve the active browser-tab id in request context so `set-url`,
+  `set-search-params`, `view-screen`, and tab-scoped application state affect
+  the app the user is actually speaking to.
+- Do not persist audio. Store only compact lifecycle and latest-transcript
+  context at `application_state["realtime-voice-session"]`; delete it when the
+  session ends.
+- Missing-key failures should open Settings focused on the user-scoped
+  `OPENAI_API_KEY` field. Never send, log, or echo the key to the browser.
+
 ## Source And Cleanup
 
 Settings must keep these as separate choices:
@@ -80,11 +109,14 @@ Default behavior:
 | --------------------------------------------------------------------- | --------------------------------------------------- |
 | `packages/core/src/client/composer/useVoiceDictation.ts`              | Provider-routing hook (MediaRecorder / Web Speech)  |
 | `packages/core/src/client/composer/VoiceButton.tsx`                   | Mic button + live amplitude + cancel overlay        |
+| `packages/core/src/client/composer/RealtimeVoiceMode.tsx`            | Opt-in popover + persistent speech orb              |
+| `packages/core/src/client/composer/useRealtimeVoiceMode.tsx`         | WebRTC lifecycle, provider events, and tool bridge  |
 | `packages/core/src/client/composer/TiptapComposer.tsx`                | Wires the hook, insertion, and keyboard shortcut    |
 | `packages/core/src/client/settings/VoiceTranscriptionSection.tsx`     | Live source + cleanup controls in sidebar settings  |
 | `packages/core/src/client/transcription/BuilderTranscriptionCta.tsx`  | CTA shown when Builder account isn't connected      |
 | `packages/core/src/client/transcription/use-live-transcription.ts`    | Web Speech live-transcription hook for recordings   |
 | `packages/core/src/server/transcribe-voice.ts`                        | Route handler (routes to Builder/Gemini/Groq/Whisper) |
+| `packages/core/src/server/realtime-voice.ts`                          | Authenticated OpenAI SDP and action-tool routes     |
 | `packages/core/src/transcription/builder-transcription.ts`            | Builder proxy transcription client                  |
 | `packages/core/src/voice/`                                            | Shared voice context pack, prompt, and replacement helpers |
 | `packages/core/src/secrets/register-framework-secrets.ts`             | Framework-level provider key registration           |
@@ -139,4 +171,6 @@ Templates can:
 - Don't call transcription providers from the client — go through `/_agent-native/transcribe-voice` so the user's secret stays server-side.
 - Don't remove the cancel affordance — mic permission abuse paranoia is real.
 - Don't auto-submit the transcript — users always edit before sending.
+- Don't route realtime tool calls around the central guarded agent executor.
+- Don't persist realtime audio or put provider keys in SDP/session payloads.
 - Don't copy Cursor's "hide send when empty" pattern — it confuses users.

package/dist/templates/workspace-core/AGENTS.md

@@ -71,8 +71,9 @@ agent should know.
 
 ## Adding Apps
 
-When a user asks from Dispatch chat or by tagging `@agent-native` in Slack to
-create, build, make, scaffold, or generate an "agent", classify the ask first.
+When a user asks from Dispatch chat or through `@agent-native` in Slack or
+Telegram to create, build, make, scaffold, or generate an "agent", classify
+the ask first.
 Simple Dispatch-native behavior such as a reminder, digest, monitor, routing
 rule, saved instruction, or recurring workflow can stay in Dispatch as a
 recurring job/resource/destination. Robust unique products or teammates that

package/dist/usage/store.d.ts

@@ -36,6 +36,13 @@ export interface UsageRecord {
      * provider-reported dollar cost so two surfaces agree exactly.
      */
     costCentsX100?: number;
+    orgId?: string;
+    runId?: string;
+    threadId?: string;
+    taskId?: string;
+    integrationScopeId?: string;
+    sourcePlatform?: string;
+    sourceId?: string;
 }
 /**
  * Calculate cost in centicents (1/100th of a cent).

package/dist/usage/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/usage/store.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,sCAAsC,OAAO,CAAC;AAC3D,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,iBAAiB,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,yBAAyB,GAAG,uBAAuB,CAAC;IAC5D,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,iBAAiB,EAAE,gBAK/B,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,gBAO1C,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,gBAAgB,CAIlB;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjE;AAqGD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAoGD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,eAAe,SAAI,EACnB,gBAAgB,SAAI,GACnB,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACtE,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAAC;AA6EjB,qEAAqE;AACrE,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS3E;AAID,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAID;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAqHvB"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/usage/store.ts"],"names":[],"mappings":"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"}

package/dist/usage/store.js

@@ -156,6 +156,13 @@ async function ensureUsageTable() {
           label TEXT NOT NULL DEFAULT 'chat',
           app TEXT NOT NULL DEFAULT '',
           ref_id TEXT NOT NULL DEFAULT '',
+          org_id TEXT,
+          run_id TEXT,
+          thread_id TEXT,
+          task_id TEXT,
+          integration_scope_id TEXT,
+          source_platform TEXT,
+          source_id TEXT,
           created_at ${intType()} NOT NULL
         )
       `;
@@ -166,6 +173,13 @@ async function ensureUsageTable() {
                 ["label", `TEXT NOT NULL DEFAULT 'chat'`],
                 ["app", `TEXT NOT NULL DEFAULT ''`],
                 ["ref_id", `TEXT NOT NULL DEFAULT ''`],
+                ["org_id", "TEXT"],
+                ["run_id", "TEXT"],
+                ["thread_id", "TEXT"],
+                ["task_id", "TEXT"],
+                ["integration_scope_id", "TEXT"],
+                ["source_platform", "TEXT"],
+                ["source_id", "TEXT"],
             ];
             if (isPostgres()) {
                 // Hot path: the `token_usage` table and its index are virtually always
@@ -244,7 +258,7 @@ export async function recordUsage(recordOrOwner, inputTokens, outputTokens, mode
             model: model ?? "",
         }
         : recordOrOwner;
-    const { ownerEmail, inputTokens: inTok, outputTokens: outTok, cacheReadTokens = 0, cacheWriteTokens = 0, model: modelName, label, app, refId, costCentsX100, } = record;
+    const { ownerEmail, inputTokens: inTok, outputTokens: outTok, cacheReadTokens = 0, cacheWriteTokens = 0, model: modelName, label, app, refId, costCentsX100, orgId, runId, threadId, taskId, integrationScopeId, sourcePlatform, sourceId, } = record;
     // Skip no-op writes (e.g. a stream aborted before any tokens flowed)
     if (!inTok && !outTok && !cacheReadTokens && !cacheWriteTokens)
         return;
@@ -269,8 +283,8 @@ export async function recordUsage(recordOrOwner, inputTokens, outputTokens, mode
     const id = Date.now() * 1000 + Math.floor(Math.random() * 1000);
     await client.execute({
         sql: `INSERT INTO token_usage
-      (id, owner_email, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, model, label, app, ref_id, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      (id, owner_email, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, model, label, app, ref_id, org_id, run_id, thread_id, task_id, integration_scope_id, source_platform, source_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         args: [
             id,
             ownerEmail,
@@ -283,6 +297,13 @@ export async function recordUsage(recordOrOwner, inputTokens, outputTokens, mode
             resolvedLabel,
             resolvedApp,
             resolvedRef,
+            orgId ?? null,
+            runId ?? null,
+            threadId ?? null,
+            taskId ?? null,
+            integrationScopeId ?? null,
+            sourcePlatform ?? null,
+            sourceId ?? null,
             Date.now(),
         ],
     });

package/dist/usage/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/usage/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Token usage tracking and cost monitoring.\n *\n * Every LLM call made by the framework records a row here so users can\n * see where their spend is going — chat vs automations vs background jobs\n * vs whatever else a template labels its prompts as.\n *\n * Cost is stored as \"centicents\" (1/100th of a cent) for integer precision.\n */\nimport { getDbExec, intType, isPostgres } from \"../db/client.js\";\nimport {\n  ensureColumnExists,\n  ensureIndexExists,\n  ensureTableExists,\n} from \"../db/ddl-guard.js\";\nimport { widenIntColumnsToBigInt } from \"../db/widen-columns.js\";\n\n/**\n * Per-million-token pricing in cents. Cache read is typically ~10% of\n * input; cache write (5m TTL) is ~125%. Pricing is best-effort — keep\n * this table in sync with Anthropic's published prices.\n */\ninterface ModelPricing {\n  input: number;\n  output: number;\n  cacheRead: number;\n  cacheWrite: number;\n}\n\nexport const BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER = 1.25;\nexport const BUILDER_AGENT_CREDITS_PER_USD = 20;\n\nexport type UsageBillingUnit = \"usd\" | \"builder-credits\";\n\nexport interface UsageBillingMode {\n  unit: UsageBillingUnit;\n  label: string;\n  shortLabel: string;\n  source: \"estimated-provider-cost\" | \"builder-agent-credits\";\n  hardCostMarginMultiplier?: number;\n  creditsPerUsd?: number;\n}\n\nexport const USD_USAGE_BILLING: UsageBillingMode = {\n  unit: \"usd\",\n  label: \"Estimated spend\",\n  shortLabel: \"Cost\",\n  source: \"estimated-provider-cost\",\n};\n\nexport const BUILDER_CREDIT_USAGE_BILLING: UsageBillingMode = {\n  unit: \"builder-credits\",\n  label: \"Builder.io credit spend\",\n  shortLabel: \"Credits\",\n  source: \"builder-agent-credits\",\n  hardCostMarginMultiplier: BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER,\n  creditsPerUsd: BUILDER_AGENT_CREDITS_PER_USD,\n};\n\nexport function usageBillingForEngine(\n  engineName: string | null | undefined,\n): UsageBillingMode {\n  return engineName === \"builder\"\n    ? BUILDER_CREDIT_USAGE_BILLING\n    : USD_USAGE_BILLING;\n}\n\nexport function builderCreditsFromCostCents(cents: number): number {\n  if (!Number.isFinite(cents) || cents <= 0) return 0;\n  const dollars = cents / 100;\n  const credits =\n    dollars *\n    BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER *\n    BUILDER_AGENT_CREDITS_PER_USD;\n  return Math.ceil(credits * 1000) / 1000;\n}\n\nconst PRICING: Array<{ match: RegExp; pricing: ModelPricing }> = [\n  // ── Anthropic ──────────────────────────────────────────────────────────────\n  // claude-fable-5: $10/$50 per MTok (Mythos-class, launched 2026-06-09)\n  {\n    match: /fable-5/i,\n    pricing: { input: 1000, output: 5000, cacheRead: 100, cacheWrite: 1250 },\n  },\n  // claude-opus-4-8: $5/$25 standard mode (fast mode same as fable-5 $10/$50)\n  // Use standard-mode pricing as default; fast-mode is a separate model id.\n  {\n    match: /opus-4-8/i,\n    pricing: { input: 500, output: 2500, cacheRead: 50, cacheWrite: 625 },\n  },\n  // claude-opus-4-7 and older opus: ~$15/$75 per MTok\n  {\n    match: /opus/i,\n    pricing: { input: 1500, output: 7500, cacheRead: 150, cacheWrite: 1875 },\n  },\n  {\n    match: /haiku/i,\n    pricing: { input: 100, output: 500, cacheRead: 10, cacheWrite: 125 },\n  },\n  // ── OpenAI / Codex ──────────────────────────────────────────────────────────\n  // Published rates as of 2026-07; OpenAI bills cached input at a discount\n  // and has no separate cache-write token charge, so cacheWrite is 0. Sol and\n  // Terra have higher large-context rates after 272K tokens; this table tracks\n  // the standard rate because usage rows do not preserve request context size.\n  {\n    match: /gpt-5[.-]6-sol/i,\n    pricing: { input: 500, output: 3000, cacheRead: 50, cacheWrite: 0 },\n  },\n  {\n    match: /gpt-5[.-]6-terra/i,\n    pricing: { input: 250, output: 1500, cacheRead: 25, cacheWrite: 0 },\n  },\n  {\n    match: /gpt-5[.-]6-luna/i,\n    pricing: { input: 100, output: 600, cacheRead: 10, cacheWrite: 0 },\n  },\n  {\n    match: /gpt-5/i,\n    pricing: { input: 125, output: 1000, cacheRead: 12.5, cacheWrite: 0 },\n  },\n  // ── Google Gemini ───────────────────────────────────────────────────────────\n  // Gemini 3 Pro / 3.1 Pro: ~$1.25/$10 per MTok (approximate; verify on billing)\n  {\n    match: /gemini-3[.-]1-pro/i,\n    pricing: { input: 125, output: 1000, cacheRead: 31, cacheWrite: 0 },\n  },\n  // Gemini 3.5 Flash / 3 Flash: ~$0.15/$0.60 per MTok\n  {\n    match: /gemini-3[.-][0-9]+-flash/i,\n    pricing: { input: 15, output: 60, cacheRead: 4, cacheWrite: 0 },\n  },\n  // Gemini 2.5 Pro/Flash (catch-all for older 2.5)\n  {\n    match: /gemini-2\\.5-pro/i,\n    pricing: { input: 125, output: 1000, cacheRead: 31, cacheWrite: 0 },\n  },\n  {\n    match: /gemini-2\\.5-flash/i,\n    pricing: { input: 15, output: 60, cacheRead: 4, cacheWrite: 0 },\n  },\n  // ── Groq ────────────────────────────────────────────────────────────────────\n  // Groq Llama 3.3 70B: $0.59/$0.79 per MTok\n  {\n    match: /llama-3\\.3-70b/i,\n    pricing: { input: 59, output: 79, cacheRead: 0, cacheWrite: 0 },\n  },\n  // Groq Llama 3.1 8B instant: $0.05/$0.08 per MTok\n  {\n    match: /llama-3\\.1-8b|llama3-8b/i,\n    pricing: { input: 5, output: 8, cacheRead: 0, cacheWrite: 0 },\n  },\n  // ── Mistral ─────────────────────────────────────────────────────────────────\n  // Mistral Large: ~$2/$6 per MTok\n  {\n    match: /mistral-large/i,\n    pricing: { input: 200, output: 600, cacheRead: 0, cacheWrite: 0 },\n  },\n  // Mistral Small/Medium: ~$0.2/$0.6 per MTok\n  {\n    match: /mistral-small|mistral-medium/i,\n    pricing: { input: 20, output: 60, cacheRead: 0, cacheWrite: 0 },\n  },\n  // default → sonnet pricing ($3/$15 per MTok)\n  {\n    match: /.*/,\n    pricing: { input: 300, output: 1500, cacheRead: 30, cacheWrite: 375 },\n  },\n];\n\nfunction pricingFor(model: string): ModelPricing {\n  for (const entry of PRICING) {\n    if (entry.match.test(model)) return entry.pricing;\n  }\n  return PRICING[PRICING.length - 1]!.pricing;\n}\n\nexport interface UsageRecord {\n  ownerEmail: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens?: number;\n  cacheWriteTokens?: number;\n  model: string;\n  /** Category for this call — e.g. \"chat\", \"automation\", \"job\", \"custom-agent\". */\n  label?: string;\n  /** Optional template/app name (e.g. \"mail\"). Falls back to AGENT_APP / APP_NAME env. */\n  app?: string;\n  /**\n   * Stable id of the thing this usage belongs to (e.g. a recap plan id). When\n   * set, any prior row(s) with the same (label, refId) are deleted before\n   * insert, so re-recording the same run overwrites instead of double-counting.\n   */\n  refId?: string;\n  /**\n   * Precomputed cost in centicents (1/100¢). When provided, it is stored\n   * verbatim instead of being derived from tokens — e.g. to mirror a\n   * provider-reported dollar cost so two surfaces agree exactly.\n   */\n  costCentsX100?: number;\n}\n\nlet _initPromise: Promise<void> | undefined;\n\nasync function ensureUsageTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = (async () => {\n      const client = getDbExec();\n      const createSql = `\n        CREATE TABLE IF NOT EXISTS token_usage (\n          id ${intType()} PRIMARY KEY,\n          owner_email TEXT NOT NULL,\n          input_tokens ${intType()} NOT NULL DEFAULT 0,\n          output_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_read_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_write_tokens ${intType()} NOT NULL DEFAULT 0,\n          cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,\n          model TEXT NOT NULL DEFAULT '',\n          label TEXT NOT NULL DEFAULT 'chat',\n          app TEXT NOT NULL DEFAULT '',\n          ref_id TEXT NOT NULL DEFAULT '',\n          created_at ${intType()} NOT NULL\n        )\n      `;\n\n      // Additive columns for older deployments that pre-date the label/cache fields.\n      const additions: Array<[string, string]> = [\n        [\"cache_read_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"cache_write_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"label\", `TEXT NOT NULL DEFAULT 'chat'`],\n        [\"app\", `TEXT NOT NULL DEFAULT ''`],\n        [\"ref_id\", `TEXT NOT NULL DEFAULT ''`],\n      ];\n\n      if (isPostgres()) {\n        // Hot path: the `token_usage` table and its index are virtually always\n        // already present in production. Issuing `CREATE TABLE`/`ALTER TABLE`/\n        // `CREATE INDEX` still takes a lock that, in a fresh background-worker\n        // process behind a concurrent connection on the shared Neon DB, can\n        // block ~indefinitely. The ensure* wrappers probe `information_schema`/\n        // `pg_indexes` first (plain reads, no lock) and run DDL ONLY for what is\n        // actually missing, bounded by a transaction-scoped `lock_timeout`. If a\n        // swallowed lock-timeout leaves the schema still missing they RE-PROBE\n        // and THROW rather than letting init memoize success against absent\n        // schema.\n        await ensureTableExists(\"token_usage\", createSql);\n        // Add columns on older deployments — guarded so the hot path (columns\n        // already present) skips the ACCESS EXCLUSIVE ALTER.\n        for (const [col, def] of additions) {\n          await ensureColumnExists(\n            \"token_usage\",\n            col,\n            `ALTER TABLE token_usage ADD COLUMN IF NOT EXISTS ${col} ${def}`,\n          );\n        }\n        // Older deployments created `created_at` as 32-bit `INTEGER`; on Postgres\n        // the `Date.now()` written per run by recordUsage() overflows int4. Widen\n        // it in place (no-op once done / on fresh BIGINT databases).\n        await widenIntColumnsToBigInt(\"token_usage\", [\"created_at\"]);\n        // Probe pg_indexes first (no lock) and skip the SHARE-locking CREATE\n        // INDEX when the index is already present.\n        await ensureIndexExists(\n          \"idx_token_usage_owner_created\",\n          `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,\n        );\n        return;\n      }\n\n      // SQLite (local dev): no lock problem — keep the original behaviour.\n      await client.execute(createSql);\n      // Add columns on older deployments that pre-date the label/cache\n      // fields. Each ALTER is wrapped so a dialect without IF NOT EXISTS\n      // (SQLite) still makes progress if only some columns are missing.\n      for (const [col, def] of additions) {\n        try {\n          await client.execute(\n            `ALTER TABLE token_usage ADD COLUMN ${col} ${def}`,\n          );\n        } catch {\n          // Column already exists — ignore\n        }\n      }\n      // Older deployments created `created_at` as 32-bit `INTEGER`; on Postgres\n      // the `Date.now()` written per run by recordUsage() overflows int4. Widen\n      // it in place (no-op once done / on fresh BIGINT databases).\n      await widenIntColumnsToBigInt(\"token_usage\", [\"created_at\"]);\n      try {\n        await client.execute(\n          `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,\n        );\n      } catch {}\n    })().catch((err) => {\n      // Retry init on the next call after a failed startup.\n      _initPromise = undefined;\n      throw err;\n    });\n  }\n  return _initPromise;\n}\n\n/**\n * Calculate cost in centicents (1/100th of a cent).\n * Accepts cache tokens so callers that use prompt caching are priced\n * correctly. Non-cache-aware callers can pass 0 for the cache fields.\n */\nexport function calculateCost(\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n  cacheReadTokens = 0,\n  cacheWriteTokens = 0,\n): number {\n  const p = pricingFor(model);\n  const rawCenticents =\n    (inputTokens / 1_000_000) * p.input * 100 +\n    (outputTokens / 1_000_000) * p.output * 100 +\n    (cacheReadTokens / 1_000_000) * p.cacheRead * 100 +\n    (cacheWriteTokens / 1_000_000) * p.cacheWrite * 100;\n  return rawCenticents > 0 ? Math.max(1, Math.round(rawCenticents)) : 0;\n}\n\n/**\n * Record token usage from an LLM call.\n *\n * Accepts an object with the full set of fields. A positional overload\n * remains for backward compatibility with the older 4-arg signature.\n */\nexport async function recordUsage(record: UsageRecord): Promise<void>;\nexport async function recordUsage(\n  ownerEmail: string,\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n): Promise<void>;\nexport async function recordUsage(\n  recordOrOwner: UsageRecord | string,\n  inputTokens?: number,\n  outputTokens?: number,\n  model?: string,\n): Promise<void> {\n  const record: UsageRecord =\n    typeof recordOrOwner === \"string\"\n      ? {\n          ownerEmail: recordOrOwner,\n          inputTokens: inputTokens ?? 0,\n          outputTokens: outputTokens ?? 0,\n          model: model ?? \"\",\n        }\n      : recordOrOwner;\n\n  const {\n    ownerEmail,\n    inputTokens: inTok,\n    outputTokens: outTok,\n    cacheReadTokens = 0,\n    cacheWriteTokens = 0,\n    model: modelName,\n    label,\n    app,\n    refId,\n    costCentsX100,\n  } = record;\n\n  // Skip no-op writes (e.g. a stream aborted before any tokens flowed)\n  if (!inTok && !outTok && !cacheReadTokens && !cacheWriteTokens) return;\n\n  await ensureUsageTable();\n  const client = getDbExec();\n  const resolvedApp =\n    app ?? process.env.AGENT_APP ?? process.env.APP_NAME ?? \"\";\n  const resolvedLabel = label ?? \"chat\";\n  const resolvedRef = refId ?? \"\";\n\n  // Replace any prior usage for this (label, refId) so re-recording the same\n  // run — e.g. a recap regenerated on a PR re-push — overwrites instead of\n  // double-counting. No-op when refId is unset (the common per-call path).\n  if (resolvedRef) {\n    await client.execute({\n      sql: `DELETE FROM token_usage WHERE label = ? AND ref_id = ?`,\n      args: [resolvedLabel, resolvedRef],\n    });\n  }\n\n  // Prefer an explicit precomputed cost (e.g. a provider-reported dollar cost);\n  // otherwise derive it from tokens via the pricing table.\n  const costX100 =\n    costCentsX100 ??\n    calculateCost(inTok, outTok, modelName, cacheReadTokens, cacheWriteTokens);\n  const id = Date.now() * 1000 + Math.floor(Math.random() * 1000);\n  await client.execute({\n    sql: `INSERT INTO token_usage\n      (id, owner_email, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, model, label, app, ref_id, created_at)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n    args: [\n      id,\n      ownerEmail,\n      inTok,\n      outTok,\n      cacheReadTokens,\n      cacheWriteTokens,\n      costX100,\n      modelName,\n      resolvedLabel,\n      resolvedApp,\n      resolvedRef,\n      Date.now(),\n    ],\n  });\n}\n\n/** Total cost (in cents) charged against a user, across all time. */\nexport async function getUserUsageCents(ownerEmail: string): Promise<number> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const { rows } = await client.execute({\n    sql: `SELECT COALESCE(SUM(cost_cents_x100), 0) as total FROM token_usage WHERE owner_email = ?`,\n    args: [ownerEmail],\n  });\n  const total = Number((rows[0] as { total?: number })?.total ?? 0);\n  return total / 100;\n}\n\n// ─── Admin / UI queries ─────────────────────────────────────────────────\n\nexport interface UsageSummaryOptions {\n  ownerEmail: string;\n  /** Inclusive lower bound (ms since epoch). Defaults to 30 days ago. */\n  sinceMs?: number;\n}\n\nexport interface UsageBucket {\n  key: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n  calls: number;\n}\n\nexport interface DailyBucket {\n  /** YYYY-MM-DD (UTC) */\n  date: string;\n  cents: number;\n  calls: number;\n}\n\nexport interface UsageRecentEntry {\n  id: number;\n  createdAt: number;\n  label: string;\n  app: string;\n  model: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n}\n\nexport interface UsageSummary {\n  billing?: UsageBillingMode;\n  totalCents: number;\n  totalCalls: number;\n  totalInputTokens: number;\n  totalOutputTokens: number;\n  totalCacheReadTokens: number;\n  totalCacheWriteTokens: number;\n  sinceMs: number;\n  byLabel: UsageBucket[];\n  byModel: UsageBucket[];\n  byApp: UsageBucket[];\n  byDay: DailyBucket[];\n  recent: UsageRecentEntry[];\n}\n\nconst DAY_MS = 86_400_000;\n\n/**\n * Produce an aggregated spend view for the Usage admin panel.\n * Scoped to the passed owner email; the UI always passes the session user.\n */\nexport async function getUsageSummary(\n  options: UsageSummaryOptions,\n): Promise<UsageSummary> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const sinceMs = options.sinceMs ?? Date.now() - 30 * DAY_MS;\n\n  const totalRow = await client.execute({\n    sql: `SELECT\n      COALESCE(SUM(cost_cents_x100), 0) AS cents,\n      COUNT(*) AS calls,\n      COALESCE(SUM(input_tokens), 0) AS in_tok,\n      COALESCE(SUM(output_tokens), 0) AS out_tok,\n      COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n      COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const t = (totalRow.rows[0] ?? {}) as Record<string, number | null>;\n\n  const bucketSql = (col: string) => ({\n    sql: `SELECT ${col} AS k,\n        COALESCE(SUM(cost_cents_x100), 0) AS cents,\n        COUNT(*) AS calls,\n        COALESCE(SUM(input_tokens), 0) AS in_tok,\n        COALESCE(SUM(output_tokens), 0) AS out_tok,\n        COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n        COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?\n      GROUP BY ${col}\n      ORDER BY cents DESC`,\n    args: [options.ownerEmail, sinceMs],\n  });\n\n  const mapBuckets = (rows: unknown[]): UsageBucket[] =>\n    rows.map((r) => {\n      const row = r as Record<string, number | string | null>;\n      return {\n        key: String(row.k ?? \"\"),\n        cents: Number(row.cents ?? 0) / 100,\n        calls: Number(row.calls ?? 0),\n        inputTokens: Number(row.in_tok ?? 0),\n        outputTokens: Number(row.out_tok ?? 0),\n        cacheReadTokens: Number(row.cr_tok ?? 0),\n        cacheWriteTokens: Number(row.cw_tok ?? 0),\n      };\n    });\n\n  const [byLabelR, byModelR, byAppR] = await Promise.all([\n    client.execute(bucketSql(\"label\")),\n    client.execute(bucketSql(\"model\")),\n    client.execute(bucketSql(\"app\")),\n  ]);\n\n  // By-day aggregation — done in JS so we don't depend on dialect-specific\n  // date functions (SQLite `strftime`, Postgres `to_char`). Cheap enough\n  // for a 30-day window; if this grows, swap for a dialect-aware query.\n  const dayRows = await client.execute({\n    sql: `SELECT created_at, cost_cents_x100 FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const dayMap = new Map<string, { cents: number; calls: number }>();\n  for (const row of dayRows.rows as Array<Record<string, number>>) {\n    const date = new Date(Number(row.created_at)).toISOString().slice(0, 10);\n    const prev = dayMap.get(date) ?? { cents: 0, calls: 0 };\n    prev.cents += Number(row.cost_cents_x100 ?? 0);\n    prev.calls += 1;\n    dayMap.set(date, prev);\n  }\n  const byDay: DailyBucket[] = [...dayMap.entries()]\n    .map(([date, v]) => ({\n      date,\n      cents: v.cents / 100,\n      calls: v.calls,\n    }))\n    .sort((a, b) => a.date.localeCompare(b.date));\n\n  const recentRows = await client.execute({\n    sql: `SELECT id, created_at, label, app, model,\n        input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,\n        cost_cents_x100\n      FROM token_usage\n      WHERE owner_email = ?\n      ORDER BY created_at DESC\n      LIMIT 50`,\n    args: [options.ownerEmail],\n  });\n  const recent: UsageRecentEntry[] = (\n    recentRows.rows as Array<Record<string, number | string | null>>\n  ).map((row) => ({\n    id: Number(row.id),\n    createdAt: Number(row.created_at),\n    label: String(row.label ?? \"chat\"),\n    app: String(row.app ?? \"\"),\n    model: String(row.model ?? \"\"),\n    inputTokens: Number(row.input_tokens ?? 0),\n    outputTokens: Number(row.output_tokens ?? 0),\n    cacheReadTokens: Number(row.cache_read_tokens ?? 0),\n    cacheWriteTokens: Number(row.cache_write_tokens ?? 0),\n    cents: Number(row.cost_cents_x100 ?? 0) / 100,\n  }));\n\n  return {\n    billing: USD_USAGE_BILLING,\n    totalCents: Number(t.cents ?? 0) / 100,\n    totalCalls: Number(t.calls ?? 0),\n    totalInputTokens: Number(t.in_tok ?? 0),\n    totalOutputTokens: Number(t.out_tok ?? 0),\n    totalCacheReadTokens: Number(t.cr_tok ?? 0),\n    totalCacheWriteTokens: Number(t.cw_tok ?? 0),\n    sinceMs,\n    byLabel: mapBuckets(byLabelR.rows),\n    byModel: mapBuckets(byModelR.rows),\n    byApp: mapBuckets(byAppR.rows),\n    byDay,\n    recent,\n  };\n}\n"]}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/usage/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Token usage tracking and cost monitoring.\n *\n * Every LLM call made by the framework records a row here so users can\n * see where their spend is going — chat vs automations vs background jobs\n * vs whatever else a template labels its prompts as.\n *\n * Cost is stored as \"centicents\" (1/100th of a cent) for integer precision.\n */\nimport { getDbExec, intType, isPostgres } from \"../db/client.js\";\nimport {\n  ensureColumnExists,\n  ensureIndexExists,\n  ensureTableExists,\n} from \"../db/ddl-guard.js\";\nimport { widenIntColumnsToBigInt } from \"../db/widen-columns.js\";\n\n/**\n * Per-million-token pricing in cents. Cache read is typically ~10% of\n * input; cache write (5m TTL) is ~125%. Pricing is best-effort — keep\n * this table in sync with Anthropic's published prices.\n */\ninterface ModelPricing {\n  input: number;\n  output: number;\n  cacheRead: number;\n  cacheWrite: number;\n}\n\nexport const BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER = 1.25;\nexport const BUILDER_AGENT_CREDITS_PER_USD = 20;\n\nexport type UsageBillingUnit = \"usd\" | \"builder-credits\";\n\nexport interface UsageBillingMode {\n  unit: UsageBillingUnit;\n  label: string;\n  shortLabel: string;\n  source: \"estimated-provider-cost\" | \"builder-agent-credits\";\n  hardCostMarginMultiplier?: number;\n  creditsPerUsd?: number;\n}\n\nexport const USD_USAGE_BILLING: UsageBillingMode = {\n  unit: \"usd\",\n  label: \"Estimated spend\",\n  shortLabel: \"Cost\",\n  source: \"estimated-provider-cost\",\n};\n\nexport const BUILDER_CREDIT_USAGE_BILLING: UsageBillingMode = {\n  unit: \"builder-credits\",\n  label: \"Builder.io credit spend\",\n  shortLabel: \"Credits\",\n  source: \"builder-agent-credits\",\n  hardCostMarginMultiplier: BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER,\n  creditsPerUsd: BUILDER_AGENT_CREDITS_PER_USD,\n};\n\nexport function usageBillingForEngine(\n  engineName: string | null | undefined,\n): UsageBillingMode {\n  return engineName === \"builder\"\n    ? BUILDER_CREDIT_USAGE_BILLING\n    : USD_USAGE_BILLING;\n}\n\nexport function builderCreditsFromCostCents(cents: number): number {\n  if (!Number.isFinite(cents) || cents <= 0) return 0;\n  const dollars = cents / 100;\n  const credits =\n    dollars *\n    BUILDER_AGENT_CREDIT_MARGIN_MULTIPLIER *\n    BUILDER_AGENT_CREDITS_PER_USD;\n  return Math.ceil(credits * 1000) / 1000;\n}\n\nconst PRICING: Array<{ match: RegExp; pricing: ModelPricing }> = [\n  // ── Anthropic ──────────────────────────────────────────────────────────────\n  // claude-fable-5: $10/$50 per MTok (Mythos-class, launched 2026-06-09)\n  {\n    match: /fable-5/i,\n    pricing: { input: 1000, output: 5000, cacheRead: 100, cacheWrite: 1250 },\n  },\n  // claude-opus-4-8: $5/$25 standard mode (fast mode same as fable-5 $10/$50)\n  // Use standard-mode pricing as default; fast-mode is a separate model id.\n  {\n    match: /opus-4-8/i,\n    pricing: { input: 500, output: 2500, cacheRead: 50, cacheWrite: 625 },\n  },\n  // claude-opus-4-7 and older opus: ~$15/$75 per MTok\n  {\n    match: /opus/i,\n    pricing: { input: 1500, output: 7500, cacheRead: 150, cacheWrite: 1875 },\n  },\n  {\n    match: /haiku/i,\n    pricing: { input: 100, output: 500, cacheRead: 10, cacheWrite: 125 },\n  },\n  // ── OpenAI / Codex ──────────────────────────────────────────────────────────\n  // Published rates as of 2026-07; OpenAI bills cached input at a discount\n  // and has no separate cache-write token charge, so cacheWrite is 0. Sol and\n  // Terra have higher large-context rates after 272K tokens; this table tracks\n  // the standard rate because usage rows do not preserve request context size.\n  {\n    match: /gpt-5[.-]6-sol/i,\n    pricing: { input: 500, output: 3000, cacheRead: 50, cacheWrite: 0 },\n  },\n  {\n    match: /gpt-5[.-]6-terra/i,\n    pricing: { input: 250, output: 1500, cacheRead: 25, cacheWrite: 0 },\n  },\n  {\n    match: /gpt-5[.-]6-luna/i,\n    pricing: { input: 100, output: 600, cacheRead: 10, cacheWrite: 0 },\n  },\n  {\n    match: /gpt-5/i,\n    pricing: { input: 125, output: 1000, cacheRead: 12.5, cacheWrite: 0 },\n  },\n  // ── Google Gemini ───────────────────────────────────────────────────────────\n  // Gemini 3 Pro / 3.1 Pro: ~$1.25/$10 per MTok (approximate; verify on billing)\n  {\n    match: /gemini-3[.-]1-pro/i,\n    pricing: { input: 125, output: 1000, cacheRead: 31, cacheWrite: 0 },\n  },\n  // Gemini 3.5 Flash / 3 Flash: ~$0.15/$0.60 per MTok\n  {\n    match: /gemini-3[.-][0-9]+-flash/i,\n    pricing: { input: 15, output: 60, cacheRead: 4, cacheWrite: 0 },\n  },\n  // Gemini 2.5 Pro/Flash (catch-all for older 2.5)\n  {\n    match: /gemini-2\\.5-pro/i,\n    pricing: { input: 125, output: 1000, cacheRead: 31, cacheWrite: 0 },\n  },\n  {\n    match: /gemini-2\\.5-flash/i,\n    pricing: { input: 15, output: 60, cacheRead: 4, cacheWrite: 0 },\n  },\n  // ── Groq ────────────────────────────────────────────────────────────────────\n  // Groq Llama 3.3 70B: $0.59/$0.79 per MTok\n  {\n    match: /llama-3\\.3-70b/i,\n    pricing: { input: 59, output: 79, cacheRead: 0, cacheWrite: 0 },\n  },\n  // Groq Llama 3.1 8B instant: $0.05/$0.08 per MTok\n  {\n    match: /llama-3\\.1-8b|llama3-8b/i,\n    pricing: { input: 5, output: 8, cacheRead: 0, cacheWrite: 0 },\n  },\n  // ── Mistral ─────────────────────────────────────────────────────────────────\n  // Mistral Large: ~$2/$6 per MTok\n  {\n    match: /mistral-large/i,\n    pricing: { input: 200, output: 600, cacheRead: 0, cacheWrite: 0 },\n  },\n  // Mistral Small/Medium: ~$0.2/$0.6 per MTok\n  {\n    match: /mistral-small|mistral-medium/i,\n    pricing: { input: 20, output: 60, cacheRead: 0, cacheWrite: 0 },\n  },\n  // default → sonnet pricing ($3/$15 per MTok)\n  {\n    match: /.*/,\n    pricing: { input: 300, output: 1500, cacheRead: 30, cacheWrite: 375 },\n  },\n];\n\nfunction pricingFor(model: string): ModelPricing {\n  for (const entry of PRICING) {\n    if (entry.match.test(model)) return entry.pricing;\n  }\n  return PRICING[PRICING.length - 1]!.pricing;\n}\n\nexport interface UsageRecord {\n  ownerEmail: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens?: number;\n  cacheWriteTokens?: number;\n  model: string;\n  /** Category for this call — e.g. \"chat\", \"automation\", \"job\", \"custom-agent\". */\n  label?: string;\n  /** Optional template/app name (e.g. \"mail\"). Falls back to AGENT_APP / APP_NAME env. */\n  app?: string;\n  /**\n   * Stable id of the thing this usage belongs to (e.g. a recap plan id). When\n   * set, any prior row(s) with the same (label, refId) are deleted before\n   * insert, so re-recording the same run overwrites instead of double-counting.\n   */\n  refId?: string;\n  /**\n   * Precomputed cost in centicents (1/100¢). When provided, it is stored\n   * verbatim instead of being derived from tokens — e.g. to mirror a\n   * provider-reported dollar cost so two surfaces agree exactly.\n   */\n  costCentsX100?: number;\n  orgId?: string;\n  runId?: string;\n  threadId?: string;\n  taskId?: string;\n  integrationScopeId?: string;\n  sourcePlatform?: string;\n  sourceId?: string;\n}\n\nlet _initPromise: Promise<void> | undefined;\n\nasync function ensureUsageTable(): Promise<void> {\n  if (!_initPromise) {\n    _initPromise = (async () => {\n      const client = getDbExec();\n      const createSql = `\n        CREATE TABLE IF NOT EXISTS token_usage (\n          id ${intType()} PRIMARY KEY,\n          owner_email TEXT NOT NULL,\n          input_tokens ${intType()} NOT NULL DEFAULT 0,\n          output_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_read_tokens ${intType()} NOT NULL DEFAULT 0,\n          cache_write_tokens ${intType()} NOT NULL DEFAULT 0,\n          cost_cents_x100 ${intType()} NOT NULL DEFAULT 0,\n          model TEXT NOT NULL DEFAULT '',\n          label TEXT NOT NULL DEFAULT 'chat',\n          app TEXT NOT NULL DEFAULT '',\n          ref_id TEXT NOT NULL DEFAULT '',\n          org_id TEXT,\n          run_id TEXT,\n          thread_id TEXT,\n          task_id TEXT,\n          integration_scope_id TEXT,\n          source_platform TEXT,\n          source_id TEXT,\n          created_at ${intType()} NOT NULL\n        )\n      `;\n\n      // Additive columns for older deployments that pre-date the label/cache fields.\n      const additions: Array<[string, string]> = [\n        [\"cache_read_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"cache_write_tokens\", `${intType()} NOT NULL DEFAULT 0`],\n        [\"label\", `TEXT NOT NULL DEFAULT 'chat'`],\n        [\"app\", `TEXT NOT NULL DEFAULT ''`],\n        [\"ref_id\", `TEXT NOT NULL DEFAULT ''`],\n        [\"org_id\", \"TEXT\"],\n        [\"run_id\", \"TEXT\"],\n        [\"thread_id\", \"TEXT\"],\n        [\"task_id\", \"TEXT\"],\n        [\"integration_scope_id\", \"TEXT\"],\n        [\"source_platform\", \"TEXT\"],\n        [\"source_id\", \"TEXT\"],\n      ];\n\n      if (isPostgres()) {\n        // Hot path: the `token_usage` table and its index are virtually always\n        // already present in production. Issuing `CREATE TABLE`/`ALTER TABLE`/\n        // `CREATE INDEX` still takes a lock that, in a fresh background-worker\n        // process behind a concurrent connection on the shared Neon DB, can\n        // block ~indefinitely. The ensure* wrappers probe `information_schema`/\n        // `pg_indexes` first (plain reads, no lock) and run DDL ONLY for what is\n        // actually missing, bounded by a transaction-scoped `lock_timeout`. If a\n        // swallowed lock-timeout leaves the schema still missing they RE-PROBE\n        // and THROW rather than letting init memoize success against absent\n        // schema.\n        await ensureTableExists(\"token_usage\", createSql);\n        // Add columns on older deployments — guarded so the hot path (columns\n        // already present) skips the ACCESS EXCLUSIVE ALTER.\n        for (const [col, def] of additions) {\n          await ensureColumnExists(\n            \"token_usage\",\n            col,\n            `ALTER TABLE token_usage ADD COLUMN IF NOT EXISTS ${col} ${def}`,\n          );\n        }\n        // Older deployments created `created_at` as 32-bit `INTEGER`; on Postgres\n        // the `Date.now()` written per run by recordUsage() overflows int4. Widen\n        // it in place (no-op once done / on fresh BIGINT databases).\n        await widenIntColumnsToBigInt(\"token_usage\", [\"created_at\"]);\n        // Probe pg_indexes first (no lock) and skip the SHARE-locking CREATE\n        // INDEX when the index is already present.\n        await ensureIndexExists(\n          \"idx_token_usage_owner_created\",\n          `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,\n        );\n        return;\n      }\n\n      // SQLite (local dev): no lock problem — keep the original behaviour.\n      await client.execute(createSql);\n      // Add columns on older deployments that pre-date the label/cache\n      // fields. Each ALTER is wrapped so a dialect without IF NOT EXISTS\n      // (SQLite) still makes progress if only some columns are missing.\n      for (const [col, def] of additions) {\n        try {\n          await client.execute(\n            `ALTER TABLE token_usage ADD COLUMN ${col} ${def}`,\n          );\n        } catch {\n          // Column already exists — ignore\n        }\n      }\n      // Older deployments created `created_at` as 32-bit `INTEGER`; on Postgres\n      // the `Date.now()` written per run by recordUsage() overflows int4. Widen\n      // it in place (no-op once done / on fresh BIGINT databases).\n      await widenIntColumnsToBigInt(\"token_usage\", [\"created_at\"]);\n      try {\n        await client.execute(\n          `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,\n        );\n      } catch {}\n    })().catch((err) => {\n      // Retry init on the next call after a failed startup.\n      _initPromise = undefined;\n      throw err;\n    });\n  }\n  return _initPromise;\n}\n\n/**\n * Calculate cost in centicents (1/100th of a cent).\n * Accepts cache tokens so callers that use prompt caching are priced\n * correctly. Non-cache-aware callers can pass 0 for the cache fields.\n */\nexport function calculateCost(\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n  cacheReadTokens = 0,\n  cacheWriteTokens = 0,\n): number {\n  const p = pricingFor(model);\n  const rawCenticents =\n    (inputTokens / 1_000_000) * p.input * 100 +\n    (outputTokens / 1_000_000) * p.output * 100 +\n    (cacheReadTokens / 1_000_000) * p.cacheRead * 100 +\n    (cacheWriteTokens / 1_000_000) * p.cacheWrite * 100;\n  return rawCenticents > 0 ? Math.max(1, Math.round(rawCenticents)) : 0;\n}\n\n/**\n * Record token usage from an LLM call.\n *\n * Accepts an object with the full set of fields. A positional overload\n * remains for backward compatibility with the older 4-arg signature.\n */\nexport async function recordUsage(record: UsageRecord): Promise<void>;\nexport async function recordUsage(\n  ownerEmail: string,\n  inputTokens: number,\n  outputTokens: number,\n  model: string,\n): Promise<void>;\nexport async function recordUsage(\n  recordOrOwner: UsageRecord | string,\n  inputTokens?: number,\n  outputTokens?: number,\n  model?: string,\n): Promise<void> {\n  const record: UsageRecord =\n    typeof recordOrOwner === \"string\"\n      ? {\n          ownerEmail: recordOrOwner,\n          inputTokens: inputTokens ?? 0,\n          outputTokens: outputTokens ?? 0,\n          model: model ?? \"\",\n        }\n      : recordOrOwner;\n\n  const {\n    ownerEmail,\n    inputTokens: inTok,\n    outputTokens: outTok,\n    cacheReadTokens = 0,\n    cacheWriteTokens = 0,\n    model: modelName,\n    label,\n    app,\n    refId,\n    costCentsX100,\n    orgId,\n    runId,\n    threadId,\n    taskId,\n    integrationScopeId,\n    sourcePlatform,\n    sourceId,\n  } = record;\n\n  // Skip no-op writes (e.g. a stream aborted before any tokens flowed)\n  if (!inTok && !outTok && !cacheReadTokens && !cacheWriteTokens) return;\n\n  await ensureUsageTable();\n  const client = getDbExec();\n  const resolvedApp =\n    app ?? process.env.AGENT_APP ?? process.env.APP_NAME ?? \"\";\n  const resolvedLabel = label ?? \"chat\";\n  const resolvedRef = refId ?? \"\";\n\n  // Replace any prior usage for this (label, refId) so re-recording the same\n  // run — e.g. a recap regenerated on a PR re-push — overwrites instead of\n  // double-counting. No-op when refId is unset (the common per-call path).\n  if (resolvedRef) {\n    await client.execute({\n      sql: `DELETE FROM token_usage WHERE label = ? AND ref_id = ?`,\n      args: [resolvedLabel, resolvedRef],\n    });\n  }\n\n  // Prefer an explicit precomputed cost (e.g. a provider-reported dollar cost);\n  // otherwise derive it from tokens via the pricing table.\n  const costX100 =\n    costCentsX100 ??\n    calculateCost(inTok, outTok, modelName, cacheReadTokens, cacheWriteTokens);\n  const id = Date.now() * 1000 + Math.floor(Math.random() * 1000);\n  await client.execute({\n    sql: `INSERT INTO token_usage\n      (id, owner_email, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, model, label, app, ref_id, org_id, run_id, thread_id, task_id, integration_scope_id, source_platform, source_id, created_at)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,\n    args: [\n      id,\n      ownerEmail,\n      inTok,\n      outTok,\n      cacheReadTokens,\n      cacheWriteTokens,\n      costX100,\n      modelName,\n      resolvedLabel,\n      resolvedApp,\n      resolvedRef,\n      orgId ?? null,\n      runId ?? null,\n      threadId ?? null,\n      taskId ?? null,\n      integrationScopeId ?? null,\n      sourcePlatform ?? null,\n      sourceId ?? null,\n      Date.now(),\n    ],\n  });\n}\n\n/** Total cost (in cents) charged against a user, across all time. */\nexport async function getUserUsageCents(ownerEmail: string): Promise<number> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const { rows } = await client.execute({\n    sql: `SELECT COALESCE(SUM(cost_cents_x100), 0) as total FROM token_usage WHERE owner_email = ?`,\n    args: [ownerEmail],\n  });\n  const total = Number((rows[0] as { total?: number })?.total ?? 0);\n  return total / 100;\n}\n\n// ─── Admin / UI queries ─────────────────────────────────────────────────\n\nexport interface UsageSummaryOptions {\n  ownerEmail: string;\n  /** Inclusive lower bound (ms since epoch). Defaults to 30 days ago. */\n  sinceMs?: number;\n}\n\nexport interface UsageBucket {\n  key: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n  calls: number;\n}\n\nexport interface DailyBucket {\n  /** YYYY-MM-DD (UTC) */\n  date: string;\n  cents: number;\n  calls: number;\n}\n\nexport interface UsageRecentEntry {\n  id: number;\n  createdAt: number;\n  label: string;\n  app: string;\n  model: string;\n  inputTokens: number;\n  outputTokens: number;\n  cacheReadTokens: number;\n  cacheWriteTokens: number;\n  cents: number;\n}\n\nexport interface UsageSummary {\n  billing?: UsageBillingMode;\n  totalCents: number;\n  totalCalls: number;\n  totalInputTokens: number;\n  totalOutputTokens: number;\n  totalCacheReadTokens: number;\n  totalCacheWriteTokens: number;\n  sinceMs: number;\n  byLabel: UsageBucket[];\n  byModel: UsageBucket[];\n  byApp: UsageBucket[];\n  byDay: DailyBucket[];\n  recent: UsageRecentEntry[];\n}\n\nconst DAY_MS = 86_400_000;\n\n/**\n * Produce an aggregated spend view for the Usage admin panel.\n * Scoped to the passed owner email; the UI always passes the session user.\n */\nexport async function getUsageSummary(\n  options: UsageSummaryOptions,\n): Promise<UsageSummary> {\n  await ensureUsageTable();\n  const client = getDbExec();\n  const sinceMs = options.sinceMs ?? Date.now() - 30 * DAY_MS;\n\n  const totalRow = await client.execute({\n    sql: `SELECT\n      COALESCE(SUM(cost_cents_x100), 0) AS cents,\n      COUNT(*) AS calls,\n      COALESCE(SUM(input_tokens), 0) AS in_tok,\n      COALESCE(SUM(output_tokens), 0) AS out_tok,\n      COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n      COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const t = (totalRow.rows[0] ?? {}) as Record<string, number | null>;\n\n  const bucketSql = (col: string) => ({\n    sql: `SELECT ${col} AS k,\n        COALESCE(SUM(cost_cents_x100), 0) AS cents,\n        COUNT(*) AS calls,\n        COALESCE(SUM(input_tokens), 0) AS in_tok,\n        COALESCE(SUM(output_tokens), 0) AS out_tok,\n        COALESCE(SUM(cache_read_tokens), 0) AS cr_tok,\n        COALESCE(SUM(cache_write_tokens), 0) AS cw_tok\n      FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?\n      GROUP BY ${col}\n      ORDER BY cents DESC`,\n    args: [options.ownerEmail, sinceMs],\n  });\n\n  const mapBuckets = (rows: unknown[]): UsageBucket[] =>\n    rows.map((r) => {\n      const row = r as Record<string, number | string | null>;\n      return {\n        key: String(row.k ?? \"\"),\n        cents: Number(row.cents ?? 0) / 100,\n        calls: Number(row.calls ?? 0),\n        inputTokens: Number(row.in_tok ?? 0),\n        outputTokens: Number(row.out_tok ?? 0),\n        cacheReadTokens: Number(row.cr_tok ?? 0),\n        cacheWriteTokens: Number(row.cw_tok ?? 0),\n      };\n    });\n\n  const [byLabelR, byModelR, byAppR] = await Promise.all([\n    client.execute(bucketSql(\"label\")),\n    client.execute(bucketSql(\"model\")),\n    client.execute(bucketSql(\"app\")),\n  ]);\n\n  // By-day aggregation — done in JS so we don't depend on dialect-specific\n  // date functions (SQLite `strftime`, Postgres `to_char`). Cheap enough\n  // for a 30-day window; if this grows, swap for a dialect-aware query.\n  const dayRows = await client.execute({\n    sql: `SELECT created_at, cost_cents_x100 FROM token_usage\n      WHERE owner_email = ? AND created_at >= ?`,\n    args: [options.ownerEmail, sinceMs],\n  });\n  const dayMap = new Map<string, { cents: number; calls: number }>();\n  for (const row of dayRows.rows as Array<Record<string, number>>) {\n    const date = new Date(Number(row.created_at)).toISOString().slice(0, 10);\n    const prev = dayMap.get(date) ?? { cents: 0, calls: 0 };\n    prev.cents += Number(row.cost_cents_x100 ?? 0);\n    prev.calls += 1;\n    dayMap.set(date, prev);\n  }\n  const byDay: DailyBucket[] = [...dayMap.entries()]\n    .map(([date, v]) => ({\n      date,\n      cents: v.cents / 100,\n      calls: v.calls,\n    }))\n    .sort((a, b) => a.date.localeCompare(b.date));\n\n  const recentRows = await client.execute({\n    sql: `SELECT id, created_at, label, app, model,\n        input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,\n        cost_cents_x100\n      FROM token_usage\n      WHERE owner_email = ?\n      ORDER BY created_at DESC\n      LIMIT 50`,\n    args: [options.ownerEmail],\n  });\n  const recent: UsageRecentEntry[] = (\n    recentRows.rows as Array<Record<string, number | string | null>>\n  ).map((row) => ({\n    id: Number(row.id),\n    createdAt: Number(row.created_at),\n    label: String(row.label ?? \"chat\"),\n    app: String(row.app ?? \"\"),\n    model: String(row.model ?? \"\"),\n    inputTokens: Number(row.input_tokens ?? 0),\n    outputTokens: Number(row.output_tokens ?? 0),\n    cacheReadTokens: Number(row.cache_read_tokens ?? 0),\n    cacheWriteTokens: Number(row.cache_write_tokens ?? 0),\n    cents: Number(row.cost_cents_x100 ?? 0) / 100,\n  }));\n\n  return {\n    billing: USD_USAGE_BILLING,\n    totalCents: Number(t.cents ?? 0) / 100,\n    totalCalls: Number(t.calls ?? 0),\n    totalInputTokens: Number(t.in_tok ?? 0),\n    totalOutputTokens: Number(t.out_tok ?? 0),\n    totalCacheReadTokens: Number(t.cr_tok ?? 0),\n    totalCacheWriteTokens: Number(t.cw_tok ?? 0),\n    sinceMs,\n    byLabel: mapBuckets(byLabelR.rows),\n    byModel: mapBuckets(byModelR.rows),\n    byApp: mapBuckets(byAppR.rows),\n    byDay,\n    recent,\n  };\n}\n"]}

package/docs/content/a2a-protocol.mdx

@@ -5,7 +5,13 @@ description: "Agent-to-agent communication via JSON-RPC: discovery, messaging, s
 
 # A2A Protocol
 
-Agent-to-agent communication over HTTP. Agents discover each other, send messages, and receive structured results.
+A2A lets agents talk to each other directly over HTTP: they discover each other's capabilities, send messages, and get back structured results — no shared database or hand-wired API needed.
+
+<Callout tone="info">
+
+**A2A vs MCP.** A2A is for **agent-to-agent** delegation — one agent-native app's agent handing work to another app's agent, which reasons over it with its own LLM loop. [MCP](/docs/mcp-protocol) is for **tool-to-agent** access — an external host like Claude or Cursor calling your app's actions directly as tools, with no extra agent reasoning in between. Use A2A when the receiving side should think; use MCP when it should just execute. See [MCP Server — MCP vs A2A](/docs/mcp-protocol#mcp-vs-a2a) for the full comparison table.
+
+</Callout>
 
 ## Overview {#overview}
 
@@ -159,7 +165,7 @@ All methods are called via `POST /_agent-native/a2a` with JSON-RPC 2.0 format:
 | `tasks/get`      | Fetch a task by ID — used to poll an async task to completion                                                         | `id`                          |
 | `tasks/cancel`   | Cancel a running task                                                                                                 | `id`                          |
 
-<Endpoint id="doc-block-a6g596" title="Primary A2A endpoint" summary="All JSON-RPC methods are POSTed here. message/send shown." method="POST" path="/_agent-native/a2a" summary="Send a message and wait for the completed task" auth="JWT bearer signed with A2A_SECRET (or legacy apiKeyEnv static token)" params={[
+<Endpoint id="doc-block-a6g596" title="Primary A2A endpoint" summary="All JSON-RPC methods are POSTed here. message/send shown." method="POST" path="/_agent-native/a2a" auth="JWT bearer signed with A2A_SECRET (or legacy apiKeyEnv static token)" params={[
   {
     "name": "Authorization",
     "in": "header",
@@ -272,9 +278,11 @@ When `message/send` is called with `async: true`, the JSON-RPC handler enqueues
 
 </Diagram>
 
-> [!IMPORTANT]
-> **Serverless Webhook & Gateway Timeouts:**
-> Hosted environment gateways (such as Netlify, Vercel, or Cloudflare Pages) impose strict execution limits (often 10 to 30 seconds) on public-facing HTTP routes. Because agent loops can take significant time to run queries, fetch context, and execute tools, you **must use `async: true`** when calling A2A endpoints or handling external webhooks. This immediately returns a `working` status to the API gateway, keeping the connection open only for a few milliseconds, while the self-fired `/process-task` POST executes the agent loop in the background. Do not block the primary HTTP request waiting for the agent loop to finish.
+<Callout tone="warning">
+
+**Serverless webhook and gateway timeouts.** Hosted environment gateways (such as Netlify, Vercel, or Cloudflare Pages) impose strict execution limits (often 10 to 30 seconds) on public-facing HTTP routes. Because agent loops can take significant time to run queries, fetch context, and execute tools, you **must use `async: true`** when calling A2A endpoints or handling external webhooks. This immediately returns a `working` status to the API gateway, keeping the connection open only for a few milliseconds, while the self-fired `/process-task` POST executes the agent loop in the background. Do not block the primary HTTP request waiting for the agent loop to finish.
+
+</Callout>
 
 Messages contain typed parts — text, structured data, and files can all travel in one message:
 
@@ -534,3 +542,11 @@ export default defineAction({
 ```
 
 The analytics agent receives the message, runs the query via its handler, and returns the result. The mail action gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.
+
+## What's next {#whats-next}
+
+- [**MCP Server**](/docs/mcp-protocol#mcp-vs-a2a) — the sibling protocol for external tools calling your app directly
+- [**Dispatch**](/docs/dispatch) — the app that routes inbound messages to the right A2A peer
+- [**Messaging**](/docs/messaging) — reaching agents from Slack, email, Telegram, and WhatsApp
+- [**Agent Mentions**](/docs/agent-mentions) — `@`-mentioning a connected agent in chat, which calls A2A under the hood
+- [**Multi-App Workspaces**](/docs/multi-app-workspace) — same-origin workspace A2A with auto-signed credentials