@agent-native/core 0.109.0 → 0.109.1

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -23,6 +23,10 @@ import {
   isLoopbackAddress,
   isTrustedLocalRuntime,
 } from "../a2a/auth-policy.js";
+import {
+  sanitizeA2ACorrelationId,
+  sanitizeA2ACorrelationMetadata,
+} from "../a2a/correlation.js";
 import { applyAgentTextEventToBuffer } from "../a2a/response-text.js";
 import {
   createA2AApproval,
@@ -115,6 +119,7 @@ import {
   type ForkThreadSourceSnapshot,
 } from "../chat-threads/store.js";
 import { createDbAdminAgentTools } from "../db-admin/agent-tools.js";
+import { isTransientDatabaseError } from "../db/client.js";
 import {
   verifyInternalToken,
   extractBearerToken,
@@ -185,6 +190,55 @@ import {
 export { handleSharedThreadRequest };
 export type { SharedThreadRouteDependencies };
 
+function withTransientDatabaseFallback(
+  route: string,
+  handler: (event: H3Event) => unknown,
+) {
+  return defineEventHandler(async (event) => {
+    try {
+      return await handler(event);
+    } catch (error) {
+      if (!isTransientDatabaseError(error)) throw error;
+
+      const method = getMethod(event);
+      const retrySafe = method === "GET" || method === "HEAD";
+
+      const databaseError = error as {
+        code?: unknown;
+        cause?: { code?: unknown };
+      };
+      captureError(new Error("Transient database failure in agent chat"), {
+        route,
+        method,
+        tags: {
+          source: "agent-chat",
+          failureClass: "transient-database",
+        },
+        extra: {
+          databaseErrorName: error instanceof Error ? error.name : typeof error,
+          databaseErrorCode:
+            typeof databaseError.code === "string"
+              ? databaseError.code
+              : undefined,
+          databaseCauseCode:
+            typeof databaseError.cause?.code === "string"
+              ? databaseError.cause.code
+              : undefined,
+        },
+      });
+      setResponseStatus(event, 503);
+      if (retrySafe) setResponseHeader(event, "Retry-After", "2");
+      return {
+        error: retrySafe
+          ? "The database is temporarily unavailable. Please retry."
+          : "The database became unavailable while processing this request. Refresh before deciding whether to retry.",
+        code: "database_unavailable",
+        retryable: retrySafe,
+      };
+    }
+  });
+}
+
 // Lazy fs — loaded via dynamic import() on first use.
 // This avoids require() which bundlers convert to createRequire(import.meta.url)
 // that crashes on CF Workers where import.meta.url is undefined.
@@ -1209,6 +1263,7 @@ export function createAgentChatPlugin(
 
       const { mountA2A } = await import("../a2a/server.js");
       mountA2A(nitroApp, {
+        appId: options?.appId,
         name: options?.appId
           ? options.appId.charAt(0).toUpperCase() + options.appId.slice(1)
           : "Agent",
@@ -1217,7 +1272,7 @@ export function createAgentChatPlugin(
         publicSkillsOnly: true,
         streaming: true,
         durableBackgroundRuns: options?.durableBackgroundRuns,
-        executeReadOnlyAction: async ({ action, input }) => {
+        executeReadOnlyAction: async ({ action, input, invocationId }) => {
           const actions = filterDirectA2AActions(
             mcpFullActions ?? allScripts,
             options ?? {},
@@ -1234,10 +1289,12 @@ export function createAgentChatPlugin(
             actions: { [action]: entry },
             name: action,
             input,
-            callId: `a2a-action-${crypto.randomUUID()}`,
+            callId: `a2a-action-${invocationId}`,
             ownerEmail: getRequestUserEmail(),
             orgId: getRequestOrgId() ?? null,
             caller: "a2a",
+            networkProtocol: "a2a",
+            networkId: invocationId,
           });
           if (result.status === "approval_required") {
             return {
@@ -1574,6 +1631,11 @@ export function createAgentChatPlugin(
           const recoverableArtifactStatusWriter =
             createSerializedA2ATaskStatusWriter(context.taskId);
           const controller = new AbortController();
+          const correlation = sanitizeA2ACorrelationMetadata(context.metadata);
+          const telemetryThreadId =
+            sanitizeA2ACorrelationId(context.contextId) ??
+            correlation.callerThreadId ??
+            context.taskId;
 
           console.log(
             `[A2A] Starting agent loop: ${a2aToolSurface.tools.length}/${a2aToolSurface.availableTools.length} initial tools, prompt ${systemPrompt.length} chars`,
@@ -1598,6 +1660,11 @@ export function createAgentChatPlugin(
                 toolCallCacheKey(approved.tool, approved.input),
               ),
               executionMode: "act",
+              runId: context.taskId,
+              networkProtocol: "a2a",
+              networkId: context.taskId,
+              threadId: context.taskId,
+              turnId: context.taskId,
               send: (event) => {
                 a2aEvents.push(event);
                 if (event.type === "tool_start") {
@@ -1658,6 +1725,26 @@ export function createAgentChatPlugin(
                 options?.durableBackgroundRuns === true &&
                 isInBackgroundFunctionRuntime(),
             },
+            {
+              telemetry: {
+                runId: context.taskId,
+                threadId: telemetryThreadId,
+                userId: userEmail,
+                delegation: {
+                  protocol: "a2a",
+                  taskId: context.taskId,
+                  ...(correlation.callerApp
+                    ? { callerApp: correlation.callerApp }
+                    : {}),
+                  ...(correlation.parentRunId
+                    ? { parentRunId: correlation.parentRunId }
+                    : {}),
+                  ...(correlation.parentTurnId
+                    ? { parentTurnId: correlation.parentTurnId }
+                    : {}),
+                },
+              },
+            },
           );
 
           // The continuation can observe terminal output immediately, so make
@@ -1814,6 +1901,7 @@ export function createAgentChatPlugin(
             : {}),
           askAgent: async (message: string) => {
             const ownerEmail = getRequestUserEmail();
+            const mcpRunId = crypto.randomUUID();
             const { getOwnerActiveApiKey } =
               await import("../agent/production-agent.js");
             const ownerApiKey = ownerEmail
@@ -1942,9 +2030,14 @@ export function createAgentChatPlugin(
                   },
                 ],
                 actions: mcpActions,
-                ownerEmail: getRequestUserEmail(),
+                ownerEmail,
                 orgId: getRequestOrgId() ?? null,
                 executionMode: "act",
+                runId: mcpRunId,
+                networkProtocol: "mcp",
+                networkId: mcpRunId,
+                threadId: mcpRunId,
+                turnId: mcpRunId,
                 send: (event) => {
                   accumulatedText = applyAgentTextEventToBuffer(
                     accumulatedText,
@@ -1962,6 +2055,14 @@ export function createAgentChatPlugin(
                   options?.durableBackgroundRuns === true &&
                   isInBackgroundFunctionRuntime(),
               },
+              {
+                telemetry: {
+                  runId: mcpRunId,
+                  threadId: mcpRunId,
+                  userId: ownerEmail ?? null,
+                  delegation: { protocol: "mcp" },
+                },
+              },
             );
 
             return accumulatedText || "(no response)";
@@ -4234,7 +4335,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
       // GET /runs/active?threadId=X — check if there's an active run for a thread
       getH3App(nitroApp).use(
         `${routePath}/runs`,
-        defineEventHandler(async (event) => {
+        withTransientDatabaseFallback(`${routePath}/runs`, async (event) => {
           // Auth check — ensure the user is authenticated
           const owner = await getOwnerFromEvent(event);
 
@@ -4753,7 +4854,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
         `${getOrigin(event)}${routePath}/shared/${encodeURIComponent(token)}`;
       getH3App(nitroApp).use(
         `${routePath}/threads`,
-        defineEventHandler(async (event) => {
+        withTransientDatabaseFallback(`${routePath}/threads`, async (event) => {
           const owner = await getOwnerFromEvent(event);
           const orgId = await getOrgIdFromEvent(event);
           const method = getMethod(event);
@@ -5383,7 +5484,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
       // earlier-mounted handlers (mode, save-key, files, skills, mentions, threads) handle them.
       getH3App(nitroApp).use(
         routePath,
-        defineEventHandler(async (event) => {
+        withTransientDatabaseFallback(routePath, async (event) => {
           // Skip sub-path requests — they're handled by earlier-mounted handlers
           const url = event.node?.req?.url || event.path || "";
           const afterBase = url.slice(

package/corpus/core/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -144,6 +144,27 @@ message delegation for planning, synthesis, multi-step work, or mutations.
 Inside an agent loop, `call-agent` exposes the same path with `action` + `input`;
 omit `message` and `taskId` in that mode.
 
+### Retry safety and trace linkage
+
+`call-agent` automatically derives an owner-scoped idempotency key from the
+originating turn, target, and exact message. If a retry reaches the receiver
+after the caller timed out, asynchronous `message/send` returns the existing
+active or completed task instead of starting a duplicate agent run. Failed and
+canceled tasks release the key for an intentional retry; synchronous calls are
+never deduplicated. Lower-level clients may pass an
+`idempotencyKey` explicitly; keep it stable for the same logical submission and
+change it when the work changes. Dedupe is scoped to the JWT-authenticated
+owner and verified org, and keys are limited to 128 characters.
+
+The caller also forwards bounded correlation metadata (`callerApp`,
+`callerThreadId`, `parentRunId`, `parentTurnId`, and direct-read
+`invocationId`). These fields
+are telemetry hints only. Receivers must continue to derive identity,
+ownership, org scope, access, and approval from the verified request context.
+Delegated model loops emit `$ai_generation` with A2A/MCP lineage, while direct
+reads emit the content-free `$a2a_read_invoke` event; neither event includes
+action arguments or results.
+
 ### Advanced: `A2AClient` (full control)
 
 ```ts

package/corpus/core/src/templates/workspace-core/.agents/skills/observability/SKILL.md

@@ -285,7 +285,13 @@ LLM generation:
 - Agent Native Analytics shape: the same event lands in `analytics_events` with
   mirrored query-friendly properties such as `run_id`, `thread_id`,
   `cost_cents_x100`, `duration_ms`, `tool_calls`, `successful_tools`,
-  `failed_tools`, and `status`.
+  `failed_tools`, and `status`. A content-free `tools` array includes at most
+  50 tool names, start offsets, durations, statuses, and coarse error classes;
+  interrupted calls are finalized as errors, and failed runs still emit with
+  zero or known usage. `tools_truncated` marks longer runs while the rollup counts remain complete.
+  Delegated runs add `delegation_protocol`, `caller_app`, `a2a_task_id`, and
+  `parent_run_id` when available. `parent_turn_id` is separate because one
+  logical turn may span multiple concrete runs.
 
 Do not build a separate LLM-observability ingestion API unless there is a clear
 reason the tracking provider registry cannot express the use case. Keep prompt,

package/corpus/core/src/templates/workspace-core/.agents/skills/tracking/SKILL.md

@@ -141,7 +141,7 @@ Other framework-level baseline events:
 - `signup` from Better Auth user creation, with `auth_provider`, `auth_user_id`, and first-touch referral attribution (`referral_source`, `referrer_user`, `referral_medium`, `referral_campaign`, `utm_*`, `first_touch_path`, `landing_referrer` — see "Referral / viral attribution" above)
 - `builder connect clicked` and `builder connect popup blocked` from browser Connect Builder CTAs
 - `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes, with LLM connection context when resolvable
-- `$ai_generation` from instrumented agent loops, with PostHog AI Observability fields such as `$ai_trace_id`, `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`, `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and mirrored Agent Native query fields such as `run_id`, `thread_id`, `cost_cents_x100`, `duration_ms`, `tool_calls`, and `status`. Prompt, tool argument, and output content is not included by default.
+- `$ai_generation` from instrumented agent loops, with PostHog AI Observability fields such as `$ai_trace_id`, `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`, `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and mirrored Agent Native query fields such as `run_id`, `thread_id`, `cost_cents_x100`, `duration_ms`, `tool_calls`, and `status`. A bounded `tools` array contains names, start offsets, durations, statuses, and coarse error classes only; interrupted tools and failed runs remain visible, and delegated runs include protocol/task/parent-run/parent-turn correlation. Prompt, tool argument, result, and output content is excluded.
 
 For new lifecycle events, call `track()` server-side when the server is the source of truth, and `trackEvent()` client-side only for browser interactions.
 

package/corpus/templates/analytics/actions/query-agent-native-analytics.ts

@@ -15,7 +15,7 @@ function resolveScope() {
 
 export default defineAction({
   description:
-    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events and session_recordings only; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, and error_message/$ai_error. session_recordings columns include id, session_id, user_id, anonymous_id, user_key, started_at, ended_at, duration_ms, chunk_count, event_count, page_count, error_count, rage_click_count, app, template, status, first_url, last_url, path, hostname, referrer, and metadata.",
+    "Query the built-in first-party Analytics source: events recorded through this app's analytics collector endpoint (/track) and session replay summaries recorded through /api/analytics/replay. This source does not require an external provider connection. Use it for questions about app/site traffic, product events, template/app usage, conversions, session recordings, LLM/agent observability, model cost, token volume, latency, and other first-party data collected by this analytics app. Use source-specific actions such as BigQuery, GA4, Mixpanel, PostHog, or Amplitude when the user asks for those sources or the relevant data lives there. SQL may read analytics_events and session_recordings only; session_replay_chunks is intentionally unavailable, and reads are automatically scoped to the current user/org. analytics_events columns include event_name, timestamp, event_date, user_id, anonymous_id, user_key, session_id, app, template, signed_in, url, path, hostname, referrer, properties, and context. LLM observability events use event_name = '$ai_generation'; useful properties include $ai_trace_id/run_id, $ai_session_id/thread_id, $ai_model/model, $ai_provider/provider, $ai_input_tokens/input_tokens, $ai_output_tokens/output_tokens, cache_read_tokens, cache_write_tokens, cost_cents_x100, $ai_total_cost_usd/cost_usd, duration_ms/$ai_latency, status, tool_calls, successful_tools, failed_tools, tools, tools_truncated, delegated, delegation_protocol, caller_app, a2a_task_id, parent_run_id, parent_turn_id, and error_message/$ai_error. The bounded tools array contains names, relative start times, durations, statuses, and coarse error classes only, never args or results; failed runs and interrupted tools remain queryable. session_recordings columns include id, session_id, user_id, anonymous_id, user_key, started_at, ended_at, duration_ms, chunk_count, event_count, page_count, error_count, rage_click_count, app, template, status, first_url, last_url, path, hostname, referrer, and metadata.",
   schema: z.object({
     sql: z
       .string()

package/corpus/templates/analytics/changelog/2026-07-17-analytics-now-includes-a-default-alert-for-spikes-in-stuck-agent-chats.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-17
+---
+
+Analytics now includes a default inbox alert for spikes in agent chats detected as stuck.

package/corpus/templates/analytics/docs/schemas/first-party-analytics.md

@@ -117,20 +117,29 @@ event_name = '$ai_sentiment'
 
 Useful query fields live in `properties`:
 
-| Property                                         | Description                               |
-| ------------------------------------------------ | ----------------------------------------- |
-| `$ai_trace_id`, `run_id`                         | Agent run id                              |
-| `$ai_session_id`, `thread_id`                    | Chat/thread id, when available            |
-| `$ai_model`, `model`                             | Model used                                |
-| `$ai_provider`, `provider`                       | Engine/provider name                      |
-| `$ai_input_tokens`, `input_tokens`               | Input tokens                              |
-| `$ai_output_tokens`, `output_tokens`             | Output tokens                             |
-| `cache_read_tokens`, `cache_write_tokens`        | Prompt-cache token counts                 |
-| `$ai_total_cost_usd`, `cost_usd`                 | Estimated run cost in USD                 |
-| `cost_cents_x100`                                | Estimated run cost in centicents          |
-| `$ai_latency`, `duration_ms`                     | Run duration in seconds / milliseconds    |
-| `tool_calls`, `successful_tools`, `failed_tools` | Tool-call counts                          |
-| `$ai_is_error`, `status`, `$ai_error`            | Error status and message, when applicable |
+| Property                                         | Description                                                                                       |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `$ai_trace_id`, `run_id`                         | Agent run id                                                                                      |
+| `$ai_session_id`, `thread_id`                    | Chat/thread id, when available                                                                    |
+| `$ai_model`, `model`                             | Model used                                                                                        |
+| `$ai_provider`, `provider`                       | Engine/provider name                                                                              |
+| `$ai_input_tokens`, `input_tokens`               | Input tokens                                                                                      |
+| `$ai_output_tokens`, `output_tokens`             | Output tokens                                                                                     |
+| `cache_read_tokens`, `cache_write_tokens`        | Prompt-cache token counts                                                                         |
+| `$ai_total_cost_usd`, `cost_usd`                 | Estimated run cost in USD                                                                         |
+| `cost_cents_x100`                                | Estimated run cost in centicents                                                                  |
+| `$ai_latency`, `duration_ms`                     | Run duration in seconds / milliseconds                                                            |
+| `tool_calls`, `successful_tools`, `failed_tools` | Complete tool-call counts                                                                         |
+| `tools`, `tools_truncated`                       | First 50 tool names, offsets, durations, statuses, and error classes, including interrupted calls |
+| `delegated`, `delegation_protocol`, `caller_app` | Delegated-run attribution                                                                         |
+| `a2a_task_id`, `parent_run_id`, `parent_turn_id` | Cross-app trace linkage, when available                                                           |
+| `$ai_is_error`, `status`, `$ai_error`            | Error status and message, when applicable                                                         |
+
+The `tools` array never includes tool arguments, results, or error messages.
+Use `tools_truncated` with the complete `tool_calls` count when a run exceeds
+the 50-entry detail cap.
+Failed runs still emit a generation row with zero or known usage so delegated
+timeouts and setup failures remain visible.
 
 Explicit thumbs feedback is content-free and uses these `$ai_feedback`
 properties:

package/corpus/templates/analytics/docs/schemas/tracked-events.md

@@ -29,7 +29,11 @@ Events tracked by application instrumentation and stored in the configured appli
   `$ai_model`, `$ai_provider`, `$ai_input_tokens`, `$ai_output_tokens`,
   `$ai_latency`, `$ai_total_cost_usd`, `run_id`, `thread_id`,
   `cost_cents_x100`, `duration_ms`, `tool_calls`, `status`, and error fields.
-  Prompt and response content are excluded by default.
+  A bounded `tools` array records only tool names, relative start times,
+  durations, statuses, and coarse error classes; interrupted tools and failed
+  runs remain visible, and `tools_truncated` marks runs above the 50-entry cap.
+  Delegated runs also include protocol, caller, task, parent-run, and
+  parent-turn linkage. Prompt, argument, result, and response content are excluded.
 
 ### Content Editing
 

package/corpus/templates/analytics/server/jobs/analytics-alerts.ts

@@ -1,6 +1,6 @@
 import {
   claimAnalyticsAlertRuleEvaluation,
-  ensureDefaultHttp5xxSpikeAlertRules,
+  ensureDefaultAnalyticsAlertRules,
   evaluateAndNotifyAnalyticsAlertRule,
   listEnabledAnalyticsAlertRules,
   markAnalyticsAlertRuleError,
@@ -45,8 +45,8 @@ export async function runAnalyticsAlertsOnce(
 
   try {
     const sweepLimit = maxRulesPerSweep(options.limit);
-    await ensureDefaultHttp5xxSpikeAlertRules().catch((err) => {
-      console.error("[analytics-alerts] Default 5xx alert seed failed:", err);
+    await ensureDefaultAnalyticsAlertRules().catch((err) => {
+      console.error("[analytics-alerts] Default alert seed failed:", err);
     });
     let rules: Awaited<ReturnType<typeof listEnabledAnalyticsAlertRules>>;
     try {