@agent-native/core 0.144.1 → 0.144.2

package/dist/client/analytics/index.d.ts

@@ -1,2 +1,2 @@
-export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, type AgentChatLifecycleEvent, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "../analytics.js";
+export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, clearAnalyticsSessionId, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setAnalyticsSessionId, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, type AgentChatLifecycleEvent, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "../analytics.js";
 export { track } from "../track.js";

package/dist/client/analytics/index.js

@@ -1,2 +1,2 @@
-export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, } from "../analytics.js";
+export { AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureClientException, captureError, captureException, captureMessage, clearAnalyticsSessionId, configureTracking, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, getSessionReplayContext, getSessionReplayUrl, isErrorCaptureInstalled, maybeStartSessionReplay, setAnalyticsSessionId, setSentryUser, setTrackingContentCaptureEnabled, setTrackingIdentity, startSessionReplay, stopSessionReplay, trackAgentChatLifecycle, trackEvent, trackSessionStatus, } from "../analytics.js";
 export { track } from "../track.js";

package/dist/client/analytics-session.d.ts

@@ -1,2 +1,15 @@
 export declare function getOrCreateAnalyticsAnonymousId(): string | undefined;
+/**
+ * Pin the browser session id an app wants every analytics event, agent run, and
+ * action request in this tab to carry. Returns the stored id, or `undefined`
+ * when there is no browser storage to pin it in (SSR) — the caller can tell
+ * those apart.
+ *
+ * Throws on an id the transport cannot carry rather than storing it.
+ */
+export declare function setAnalyticsSessionId(sessionId: string): string | undefined;
+/**
+ * Drop a pinned id and let the next read start a fresh rotating session.
+ */
+export declare function clearAnalyticsSessionId(): void;
 export declare function getOrCreateAnalyticsSessionId(): string | undefined;

package/dist/client/analytics-session.js

@@ -1,10 +1,17 @@
 import { serializeAnalyticsAnonymousIdCookie } from "../shared/analytics-anonymous-id.js";
 const ANONYMOUS_ID_STORAGE_KEY = "agent-native.anonymous_id";
 const SESSION_ID_STORAGE_KEY = "agent-native.session_id";
+const SESSION_ID_PIN_STORAGE_KEY = "agent-native.session_id_pin";
 const SESSION_LAST_ACTIVITY_STORAGE_KEY = "agent-native.session_last_activity";
 // 30-minute idle timeout matches GA4 / Mixpanel defaults: a tab left open
 // overnight starts a new session in the morning instead of stretching one visit.
 const SESSION_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+// The server drops the session header at 128 characters
+// (`readBrowserSessionIdHeader`), and `fetch` throws on a header value with
+// non-ASCII or newline bytes. Both are rejected at the point the id is set so a
+// bad id fails once, loudly, instead of silently unlinking every later request.
+const MAX_SESSION_ID_LENGTH = 127;
+const SAFE_SESSION_ID = /^[!-~]+$/;
 function generateVisitorId() {
     try {
         if (typeof crypto !== "undefined" &&
@@ -35,6 +42,15 @@ function safeStorageSet(key, value) {
         // private browsing / storage disabled -- best-effort
     }
 }
+function safeStorageRemove(key) {
+    try {
+        window.localStorage.removeItem(key);
+        // coercion-ok: storage that refuses writes holds no key to clear, so the caller's end state already holds
+    }
+    catch {
+        // private browsing / storage disabled -- best-effort
+    }
+}
 function syncAnalyticsAnonymousIdCookie(id) {
     try {
         const cookie = serializeAnalyticsAnonymousIdCookie(id);
@@ -57,10 +73,51 @@ export function getOrCreateAnalyticsAnonymousId() {
     syncAnalyticsAnonymousIdCookie(id);
     return id;
 }
+/**
+ * Pin the browser session id an app wants every analytics event, agent run, and
+ * action request in this tab to carry. Returns the stored id, or `undefined`
+ * when there is no browser storage to pin it in (SSR) — the caller can tell
+ * those apart.
+ *
+ * Throws on an id the transport cannot carry rather than storing it.
+ */
+export function setAnalyticsSessionId(sessionId) {
+    const trimmed = typeof sessionId === "string" ? sessionId.trim() : "";
+    if (!trimmed ||
+        trimmed.length > MAX_SESSION_ID_LENGTH ||
+        !SAFE_SESSION_ID.test(trimmed)) {
+        throw new Error(`Invalid analytics session id: expected 1-${MAX_SESSION_ID_LENGTH} printable ASCII characters with no whitespace`);
+    }
+    if (typeof window === "undefined")
+        return undefined;
+    safeStorageSet(SESSION_ID_PIN_STORAGE_KEY, trimmed);
+    safeStorageSet(SESSION_ID_STORAGE_KEY, trimmed);
+    safeStorageSet(SESSION_LAST_ACTIVITY_STORAGE_KEY, String(Date.now()));
+    return trimmed;
+}
+/**
+ * Drop a pinned id and let the next read start a fresh rotating session.
+ */
+export function clearAnalyticsSessionId() {
+    if (typeof window === "undefined")
+        return;
+    safeStorageRemove(SESSION_ID_PIN_STORAGE_KEY);
+    safeStorageRemove(SESSION_ID_STORAGE_KEY);
+    safeStorageRemove(SESSION_LAST_ACTIVITY_STORAGE_KEY);
+}
 export function getOrCreateAnalyticsSessionId() {
     if (typeof window === "undefined")
         return undefined;
     const now = Date.now();
+    // A pinned id opts out of idle rotation: the app chose it to correlate its
+    // own runs, so expiring it mid-workflow would split one correlated session
+    // into two that nothing can join back together.
+    const pinned = safeStorageGet(SESSION_ID_PIN_STORAGE_KEY);
+    if (pinned) {
+        safeStorageSet(SESSION_ID_STORAGE_KEY, pinned);
+        safeStorageSet(SESSION_LAST_ACTIVITY_STORAGE_KEY, String(now));
+        return pinned;
+    }
     const lastActivityRaw = safeStorageGet(SESSION_LAST_ACTIVITY_STORAGE_KEY);
     const lastActivity = lastActivityRaw
         ? Number.parseInt(lastActivityRaw, 10)

package/dist/client/analytics.d.ts

@@ -1,3 +1,4 @@
+export { clearAnalyticsSessionId, setAnalyticsSessionId, } from "./analytics-session.js";
 import type { SessionReplayOptions, SessionReplayStartResult } from "./session-replay.js";
 export { scrubUrl } from "./url-scrub.js";
 export { addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, type CaptureExceptionContext, type CapturedExceptionEvent, type ExceptionBreadcrumb, type ExceptionLevel, } from "./error-capture.js";

package/dist/client/analytics.js

@@ -1,6 +1,7 @@
 import { llmConnectionTrackingProperties, } from "../shared/llm-connection.js";
 import { toPostHogExceptionProperties } from "../tracking/posthog-exception.js";
 import { getOrCreateAnalyticsAnonymousId, getOrCreateAnalyticsSessionId, } from "./analytics-session.js";
+export { clearAnalyticsSessionId, setAnalyticsSessionId, } from "./analytics-session.js";
 import { fetchAgentEngineStatus, fetchAuthSessionStatus, } from "./client-status-requests.js";
 import { installErrorCapture, } from "./error-capture.js";
 import { isDynamicImportFailureMessage } from "./route-chunk-recovery.js";

package/dist/client/index.d.ts

@@ -18,7 +18,7 @@ export { DevDatabaseLink, type DevDatabaseLinkProps, } from "./db-admin/DevDatab
 export { DbAdminPage } from "./db-admin/DbAdminPage.js";
 export { installRouteChunkRecovery, reloadForStaleChunk, recoverFromStaleChunkError, } from "./route-chunk-recovery.js";
 export { AgentTerminal, type AgentTerminalProps } from "./terminal/index.js";
-export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type AgentChatLifecycleEvent, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayOptions, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "./analytics.js";
+export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, setAnalyticsSessionId, clearAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, type CaptureExceptionContext, type CapturedExceptionEvent, type ClientCaptureContext, type AgentChatLifecycleEvent, type ConfigureTrackingOptions, type ErrorCaptureConfigOptions, type ExceptionBreadcrumb, type ExceptionLevel, type FirstTouchAttribution, type SessionReplayOptions, type SessionReplayContext, type SessionReplayLinkOptions, type SessionReplayStartResult, type SessionReplayUrlMatcher, type TrackingIdentityUser, } from "./analytics.js";
 export { track } from "./track.js";
 export { useCollaborativeDoc, isReconcileLeadClient, emailToColor, emailToName, dedupeCollabUsersByEmail, type UseCollaborativeDocOptions, type UseCollaborativeDocResult, type CollabUser, } from "../collab/client.js";
 export { AGENT_CLIENT_ID } from "../collab/agent-identity.js";

package/dist/client/index.js

@@ -18,7 +18,7 @@ export { DevDatabaseLink, } from "./db-admin/DevDatabaseLink.js";
 export { DbAdminPage } from "./db-admin/DbAdminPage.js";
 export { installRouteChunkRecovery, reloadForStaleChunk, recoverFromStaleChunkError, } from "./route-chunk-recovery.js";
 export { AgentTerminal } from "./terminal/index.js";
-export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, 
+export { trackEvent, trackAgentChatLifecycle, trackSessionStatus, configureTracking, setTrackingContentCaptureEnabled, maybeStartSessionReplay, startSessionReplay, stopSessionReplay, getAnalyticsAnonymousId, getAnalyticsSessionId, setAnalyticsSessionId, clearAnalyticsSessionId, getFirstTouchAttribution, setSentryUser, setTrackingIdentity, getSessionReplayContext, getSessionReplayUrl, captureError, captureClientException, 
 // First-party, Sentry-style error capture (auto + manual API).
 AGENT_NATIVE_EXCEPTION_EVENT_NAME, addErrorBreadcrumb, captureException, captureMessage, isErrorCaptureInstalled, } from "./analytics.js";
 export { track } from "./track.js";

package/dist/client/track.js

@@ -1,3 +1,4 @@
+import { getOrCreateAnalyticsSessionId } from "./analytics-session.js";
 import { agentNativePath } from "./api-path.js";
 /**
  * Fire an analytics event from browser/app code. This is the client-side twin
@@ -35,6 +36,7 @@ export function track(name, properties) {
         // Non-serializable properties — drop rather than throw into the caller.
         return Promise.resolve();
     }
+    const browserSessionId = getOrCreateAnalyticsSessionId();
     return fetch(agentNativePath("/_agent-native/track"), {
         method: "POST",
         headers: {
@@ -43,6 +45,11 @@ export function track(name, properties) {
             // middleware trusts it as a first-party marker. Matches the convention
             // used by other client writes (application-state, guided-questions).
             "X-Agent-Native-CSRF": "1",
+            // Same session the action client and agent chat send, so a client event
+            // and the server events from the same visit share one session.
+            ...(browserSessionId
+                ? { "X-Agent-Native-Session-Id": browserSessionId }
+                : {}),
         },
         body,
         keepalive: true,

package/dist/client/use-action.js

@@ -22,6 +22,7 @@
  * compatibility.
  */
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { getOrCreateAnalyticsSessionId } from "./analytics-session.js";
 import { trackEvent } from "./analytics.js";
 import { agentNativePath } from "./api-path.js";
 import { getBrowserTabId } from "./browser-tab-id.js";
@@ -192,8 +193,16 @@ async function performActionFetch(name, method, params, options) {
     if (buildId)
         headers["X-Agent-Native-Build-Id"] = buildId;
     const tz = resolveUserTimezone();
-    if (tz)
+    if (tz) {
         headers["x-user-timezone"] = tz;
+    }
+    // Same browser session the agent chat sends on an agent run, so an action
+    // called from the UI and an action the agent calls during that visit land on
+    // one `$session_id` in traces and session replay.
+    const browserSessionId = getOrCreateAnalyticsSessionId();
+    if (browserSessionId) {
+        headers["X-Agent-Native-Session-Id"] = browserSessionId;
+    }
     const init = {
         method,
         headers,

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/file-upload/actions/upload-image.d.ts

@@ -17,11 +17,11 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
-    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
+    error?: undefined;
 }>;
 export default _default;

package/dist/mcp/screen-memory-stdio.d.ts

@@ -137,13 +137,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -159,7 +159,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -175,6 +174,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -190,7 +190,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
     inputSchema: {
         type: string;
         properties: {
-            count?: undefined;
             minutes: {
                 type: string;
                 description: string;
@@ -200,6 +199,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -216,7 +216,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query: {
                 type: string;
                 description: string;
@@ -235,6 +234,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
             };
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;
@@ -250,7 +250,6 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
@@ -264,6 +263,7 @@ export declare function screenMemoryMcpToolDefinitions(): ({
                 description: string;
             };
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             includeMicrophone?: undefined;
@@ -314,13 +314,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt: {
                 type: string;
                 description: string;
@@ -349,13 +349,13 @@ export declare function screenMemoryMcpToolDefinitions(): ({
         type: string;
         required: string[];
         properties: {
-            count?: undefined;
             query?: undefined;
             minutes?: undefined;
             limit?: undefined;
             clientHint?: undefined;
             timestamp?: undefined;
             chapterId?: undefined;
+            count?: undefined;
             startAt?: undefined;
             endAt?: undefined;
             reason?: undefined;

package/dist/notifications/routes.d.ts

@@ -16,18 +16,18 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error?: undefined;
     ok?: undefined;
 } | {
-    count?: undefined;
     updated: number;
     error?: undefined;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     error: string;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
+    count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -42,22 +42,22 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     avgEvalScore: number;
 } | {
     error?: undefined;
-    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
+    ok?: undefined;
 } | {
     error?: undefined;
-    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
     error?: undefined;
     summary?: undefined;

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,8 +75,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    id?: undefined;
     deleted?: undefined;
+    id?: undefined;
     providers: {
         id: string;
         label: string;
@@ -93,9 +93,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
-    id?: undefined;
     deleted?: undefined;
     count?: undefined;
+    id?: undefined;
     providers?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/action-routes.js

@@ -7,7 +7,7 @@ import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
 import { actionCallIsReadOnly, notifyActionChange } from "./action-change.js";
-import { seedAgentRunOwnerContext, } from "./agent-run-context.js";
+import { readBrowserSessionIdHeader, seedAgentRunOwnerContext, } from "./agent-run-context.js";
 import { captureError } from "./capture-error.js";
 import { getAllowedCorsOrigin as resolveAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { resolveEmbedSessionFromRequest, resolvedEmbedCapabilityScope, } from "./embed-session.js";
@@ -158,7 +158,7 @@ function handleOptionsRequest(event) {
         }
         setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
         setResponseHeader(event, "Access-Control-Allow-Headers", cors.credentials
-            ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,${EMBED_TARGET_HEADER}`
+            ? `Content-Type,Authorization,X-Requested-With,X-Request-Source,X-Agent-Native-CSRF,X-User-Timezone,X-Agent-Native-Session-Id,X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id,${EMBED_TARGET_HEADER}`
             : `${MCP_EMBED_CORS_ALLOW_HEADERS},X-Agent-Native-Tool-Bridge,X-Agent-Native-Tool-Id,X-Agent-Native-Frontend,X-Agent-Native-Client-Compatibility,X-Agent-Native-Build-Id`);
     }
     setResponseStatus(event, 204);
@@ -350,12 +350,14 @@ export function mountActionRoutes(nitroApp, actions, options) {
                     : undefined;
             }
             const timezone = readTimezoneHeader(event);
+            const browserSessionId = readBrowserSessionIdHeader(event);
             return runWithRequestContext({
                 userEmail,
                 userName,
                 orgId,
                 authCapability,
                 timezone,
+                browserSessionId,
                 requestOrigin: getRequestURL(event).origin,
                 // Captured here because this is the last layer that still holds
                 // the h3 event; everything below reads it off the request store.

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,10 +27,10 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
+    error?: undefined;
 }>>;
 export {};

package/dist/server/agent-run-context.d.ts

@@ -14,9 +14,11 @@ export declare function readAgentRunTimezone(event: H3Event): string | undefined
  *
  * Emitted as PostHog's `$session_id` on the run's `$ai_*` events so an agent
  * trace joins to the session replay it happened in. Distinct from
- * `$ai_session_id`, which is the conversation thread.
+ * `$ai_session_id`, which is the conversation thread. Read by both the agent
+ * run path and the HTTP action route, so one visit correlates across the UI's
+ * action calls and the agent's.
  */
-export declare function readAgentRunBrowserSessionId(event: H3Event): string | undefined;
+export declare function readBrowserSessionIdHeader(event: H3Event): string | undefined;
 export declare function seedAgentRunOwnerContext(event: H3Event, ownerContext: AgentRunOwnerContext): AgentRunOwnerContext;
 export declare function seedBackgroundAgentRunOwnerContext(event: H3Event, runId: string): Promise<AgentRunOwnerContext | null>;
 export declare function resolveAgentRunOwnerContext(event: H3Event, options?: {

package/dist/server/agent-run-context.js

@@ -49,9 +49,11 @@ export function readAgentRunTimezone(event) {
  *
  * Emitted as PostHog's `$session_id` on the run's `$ai_*` events so an agent
  * trace joins to the session replay it happened in. Distinct from
- * `$ai_session_id`, which is the conversation thread.
+ * `$ai_session_id`, which is the conversation thread. Read by both the agent
+ * run path and the HTTP action route, so one visit correlates across the UI's
+ * action calls and the agent's.
  */
-export function readAgentRunBrowserSessionId(event) {
+export function readBrowserSessionIdHeader(event) {
     const raw = readHeaderValue(event, "x-agent-native-session-id");
     const value = Array.isArray(raw) ? raw[0] : raw;
     return typeof value === "string" &&
@@ -140,7 +142,7 @@ export async function resolveAgentRunOrgId(options) {
 export async function resolveAgentRunRequestContext(options) {
     const orgId = await resolveAgentRunOrgId(options);
     const timezone = readAgentRunTimezone(options.event);
-    const browserSessionId = readAgentRunBrowserSessionId(options.event);
+    const browserSessionId = readBrowserSessionIdHeader(options.event);
     const waitUntil = requestWaitUntil(options.event);
     const run = {
         ...(options.isBackgroundWorker ? { isBackgroundWorker: true } : {}),

package/dist/server/core-routes-plugin.js

@@ -33,6 +33,7 @@ import { registerBuiltinProviders } from "../tracking/providers.js";
 import { validateTrackPayload } from "../tracking/route.js";
 import { createAutomationsHandler } from "../triggers/routes.js";
 import { createAgentEngineApiKeyHandler } from "./agent-engine-api-key-route.js";
+import { readBrowserSessionIdHeader } from "./agent-run-context.js";
 import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
 import { getAppName } from "./app-name.js";
 import { getSession } from "./auth.js";
@@ -2544,6 +2545,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 try {
                     track(validation.name, properties, {
                         userId: userEmail,
+                        sessionId: readBrowserSessionIdHeader(event),
                     });
                 }
                 catch {

package/dist/server/realtime-token.d.ts

@@ -26,8 +26,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
-    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
+    error?: undefined;
 }>>;

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

@@ -283,7 +283,11 @@ same best-effort fan-out as other tracking events.
   upward through `$ai_parent_id` so a backend can rebuild the tree.
   `$ai_session_id` is the thread; the browser session is separate and ships as
   `$session_id`, read from `X-Agent-Native-Session-Id` via
-  `RequestContext.browserSessionId`. Emission lives in `posthog-ai.ts`.
+  `RequestContext.browserSessionId`. The agent chat and the action client both
+  send that header, so a UI action call and the agent's own call during one
+  visit share a session. `setAnalyticsSessionId()` from
+  `@agent-native/core/client/analytics` pins a custom id and opts it out of the
+  30-minute idle rotation. Emission lives in `posthog-ai.ts`.
 - 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`,

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

@@ -18,19 +18,26 @@ The tracking system provides a single `track()` call that fans out to all regist
 ## How It Works
 
 1. At server startup, `registerBuiltinProviders()` checks env vars and registers any configured providers.
-2. Application code calls `track(eventName, properties, meta)` from actions, plugins, or server routes.
+2. Application code calls `track(eventName, properties, source)` from actions, plugins, or server routes.
 3. The registry fans out the event to every registered provider. Errors are caught and logged -- a failing provider never crashes the caller.
 4. Built-in providers batch HTTP calls (flush every 10 seconds or 50 events, whichever comes first).
 
 ## API
 
-### `track(name, properties?, meta?)`
+### `track(name, properties?, source?)`
 
-Fire an analytics event.
+Fire an analytics event. `source` is either a `{ userId, anonymousId, sessionId }`
+meta object or an action's `ctx` passed straight through.
 
 ```ts
 import { track } from "@agent-native/core/tracking";
 
+// From an action — pass ctx; userId comes from ctx.userEmail.
+run: async ({ name }, ctx) => {
+  track("meal.logged", { mealName: name, calories: 350 }, ctx);
+};
+
+// From a plugin or route with no ctx.
 track(
   "meal.logged",
   { mealName: "Salad", calories: 350 },
@@ -38,6 +45,16 @@ track(
 );
 ```
 
+The caller's browser session comes from the ambient request context
+(`RequestContext.browserSessionId`, set from the `X-Agent-Native-Session-Id`
+header), so it resolves the same whether the UI called the action or the agent
+did. Pass `sessionId` in the meta object to override it — routes that run
+outside a request context, such as `/_agent-native/track`, do exactly that.
+Providers map it to their own session field: `$session_id` for PostHog (which
+joins the event to session replay), `session_id` as a property for Mixpanel and
+Amplitude, a top-level `sessionId` for webhooks and Agent Native Analytics. It
+is absent for callers with no browser — cron, CLI, MCP, A2A.
+
 ### `identify(userId, traits?)`
 
 Identify a user with traits. Forwarded to providers that support it.

package/dist/tracking/index.d.ts

@@ -1,4 +1,4 @@
-export { track, identify, flushTracking, registerTrackingProvider, unregisterTrackingProvider, listTrackingProviders, } from "./registry.js";
+export { track, identify, flushTracking, registerTrackingProvider, unregisterTrackingProvider, listTrackingProviders, type TrackingMeta, type TrackingSource, } from "./registry.js";
 export { registerBuiltinProviders } from "./providers.js";
 export { captureException, type TrackingExceptionContext, type TrackingExceptionLevel, } from "./error-capture.js";
 export { errorToPostHogExceptionProperties, parseStackFrames, reshapeTrackedExceptionProperties, toPostHogExceptionProperties, type PostHogExceptionEntry, type PostHogExceptionInput, type PostHogExceptionLevel, type PostHogExceptionProperties, type PostHogStackFrame, } from "./posthog-exception.js";

package/dist/tracking/providers.js

@@ -134,6 +134,7 @@ function createPostHogProvider(apiKey, host, errorTracking) {
             properties: {
                 distinct_id: distinctId,
                 ...properties,
+                ...(event.sessionId ? { $session_id: event.sessionId } : {}),
                 timestamp: event.timestamp,
             },
         }));
@@ -168,6 +169,7 @@ function createPostHogProvider(apiKey, host, errorTracking) {
                 distinct_id: distinctId,
                 properties: {
                     ...event.properties,
+                    ...(event.sessionId ? { $session_id: event.sessionId } : {}),
                     timestamp: event.timestamp,
                 },
             }));
@@ -225,6 +227,9 @@ function createMixpanelProvider(token) {
                         ? new Date(event.timestamp).getTime() / 1000
                         : undefined,
                     ...event.properties,
+                    // Mixpanel's own `$session_id` is numeric and assigned by its SDK, so
+                    // the browser session lands as a plain property here.
+                    ...(event.sessionId ? { session_id: event.sessionId } : {}),
                 },
             };
             enqueue("https://api.mixpanel.com/track", JSON.stringify([data]));
@@ -253,7 +258,11 @@ function createAmplitudeProvider(apiKey) {
                     {
                         event_type: event.name,
                         user_id: event.userId || "anonymous",
-                        event_properties: event.properties,
+                        // Amplitude's top-level `session_id` must be a numeric epoch, so
+                        // the browser session ships as an event property instead.
+                        event_properties: event.sessionId
+                            ? { ...event.properties, session_id: event.sessionId }
+                            : event.properties,
                         time: event.timestamp
                             ? new Date(event.timestamp).getTime()
                             : undefined,
@@ -290,6 +299,7 @@ function createWebhookProvider(url, authHeader) {
                 event: event.name,
                 properties: event.properties,
                 userId: event.userId,
+                sessionId: event.sessionId,
                 timestamp: event.timestamp,
             }), extra);
         },
@@ -318,6 +328,7 @@ function createAgentNativeAnalyticsProvider(publicKey, endpoint) {
                 properties: event.properties ?? {},
                 userId: event.userId,
                 anonymousId: event.anonymousId,
+                sessionId: event.sessionId,
                 timestamp: event.timestamp,
             }), undefined, { flushImmediately });
         },

package/dist/tracking/registry.d.ts

@@ -1,10 +1,20 @@
+import type { ActionRunContext } from "../action.js";
 import type { TrackingProvider } from "./types.js";
 export declare function registerTrackingProvider(provider: TrackingProvider): void;
 export declare function unregisterTrackingProvider(name: string): boolean;
 export declare function listTrackingProviders(): string[];
-export declare function track(name: string, properties?: Record<string, unknown>, meta?: {
+export interface TrackingMeta {
     userId?: string;
     anonymousId?: string;
-}): void;
+    /** Overrides the ambient request's browser session. */
+    sessionId?: string;
+}
+/**
+ * Who an event is attributed to. Pass an action's `ctx` straight through —
+ * `track("project_created", { template }, ctx)` — instead of restating
+ * `{ userId: ctx.userEmail }` at every call site.
+ */
+export type TrackingSource = TrackingMeta | ActionRunContext;
+export declare function track(name: string, properties?: Record<string, unknown>, source?: TrackingSource): void;
 export declare function identify(userId: string, traits?: Record<string, unknown>): void;
 export declare function flushTracking(): Promise<void[]>;

package/dist/tracking/registry.js

@@ -1,3 +1,4 @@
+import { getRequestContext } from "../server/request-context.js";
 const REGISTRY_KEY = Symbol.for("@agent-native/core/tracking.registry");
 function getRegistry() {
     const g = globalThis;
@@ -20,13 +21,36 @@ export function unregisterTrackingProvider(name) {
 export function listTrackingProviders() {
     return Array.from(getRegistry().keys());
 }
-export function track(name, properties, meta) {
+// `caller` is required on ActionRunContext and absent from TrackingMeta, so it
+// is the one field that tells the two apart without the caller declaring which
+// shape it passed.
+function isActionRunContext(source) {
+    return typeof source.caller === "string";
+}
+function resolveTrackingSource(source) {
+    // The browser session rides the request, not the caller's arguments, so it
+    // resolves the same way whether the UI called the action or the agent did.
+    const ambientSessionId = getRequestContext()?.browserSessionId;
+    if (!source)
+        return { sessionId: ambientSessionId };
+    if (isActionRunContext(source)) {
+        return { userId: source.userEmail, sessionId: ambientSessionId };
+    }
+    return {
+        userId: source.userId,
+        anonymousId: source.anonymousId,
+        sessionId: source.sessionId ?? ambientSessionId,
+    };
+}
+export function track(name, properties, source) {
+    const { userId, anonymousId, sessionId } = resolveTrackingSource(source);
     const event = {
         name,
         properties,
         timestamp: new Date().toISOString(),
-        userId: meta?.userId,
-        anonymousId: meta?.anonymousId,
+        userId,
+        anonymousId,
+        sessionId,
     };
     for (const provider of getRegistry().values()) {
         try {

package/dist/tracking/types.d.ts

@@ -4,6 +4,14 @@ export interface TrackingEvent {
     timestamp?: string;
     userId?: string;
     anonymousId?: string;
+    /**
+     * Browser session the event belongs to, so a server-side event joins the
+     * visit that caused it. Carried as a typed field rather than a property so
+     * each provider maps it to its own session concept instead of every backend
+     * receiving another backend's reserved key. `undefined` for callers with no
+     * browser — cron, CLI, MCP, A2A — which is a real distinction, not a gap.
+     */
+    sessionId?: string;
 }
 export interface TrackingProvider {
     name: string;

package/docs/content/observability.mdx

@@ -307,6 +307,22 @@ Nodes share the run id as `$ai_trace_id`, so PostHog renders one tree per run.
 `$ai_session_id` is the conversation thread; the browser session is sent
 separately as `$session_id` so a trace links to its session replay.
 
+The browser session id travels on the `X-Agent-Native-Session-Id` header. Both
+the agent chat and the action client (`useActionQuery` / `useActionMutation` /
+`callAction`) send it, and the server exposes it to actions and agent runs alike
+as `RequestContext.browserSessionId` — so an action the UI calls and an action
+the agent calls during the same visit correlate. The id rotates after 30 idle
+minutes by default; to correlate a workflow under an id of your own, pin it once
+at startup:
+
+```ts
+import { setAnalyticsSessionId } from "@agent-native/core/client/analytics";
+
+// Pinned ids opt out of idle rotation. Call clearAnalyticsSessionId() to
+// return to the rotating default.
+setAnalyticsSessionId(myWorkflowId);
+```
+
 Tool calls always appear (PostHog derives its tool tags from them), but their
 **arguments** require `captureToolArgs` and message content requires
 `capturePrompts`. When those are off the fields are omitted entirely rather than

package/docs/content/tracking.mdx

@@ -116,7 +116,7 @@ used as a fallback for it.
 
 ## API {#api}
 
-### `track(name, properties?, meta?)` {#track}
+### `track(name, properties?, source?)` {#track}
 
 Fire an analytics event. Fans out to all registered providers.
 
@@ -130,6 +130,19 @@ track(
 );
 ```
 
+`source` is either an action's `ctx`, passed straight through, or a
+`{ userId, anonymousId, sessionId }` meta object for callers that have no `ctx`.
+
+The browser session is not something the caller has to supply: it comes from the
+ambient request context (`RequestContext.browserSessionId`, set from the
+`X-Agent-Native-Session-Id` header the action client, chat, and client `track()`
+all send), so the same visit correlates whether the UI or the agent triggered the
+event. Each provider maps it to its own session field — `$session_id` for
+PostHog, which joins the event to session replay; a `session_id` property for
+Mixpanel and Amplitude; a top-level `sessionId` for webhooks and Agent Native
+Analytics. It is absent for callers with no browser (cron, CLI, MCP, A2A), and a
+`sessionId` in the meta object overrides it.
+
 ### `identify(userId, traits?)` {#identify}
 
 Identify a user with traits. Forwarded to providers that support it (PostHog, Mixpanel, Amplitude, webhook).
@@ -166,7 +179,9 @@ export default defineAction({
       .values({ name, template })
       .returning();
 
-    track("project.created", { name, template }, { userId: ctx?.userEmail });
+    // Pass ctx straight through: the event is attributed to ctx.userEmail and
+    // joins the browser session the call came from.
+    track("project.created", { name, template }, ctx);
 
     return { ok: true, projectId: project.id };
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.144.1",
+  "version": "0.144.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

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

@@ -283,7 +283,11 @@ same best-effort fan-out as other tracking events.
   upward through `$ai_parent_id` so a backend can rebuild the tree.
   `$ai_session_id` is the thread; the browser session is separate and ships as
   `$session_id`, read from `X-Agent-Native-Session-Id` via
-  `RequestContext.browserSessionId`. Emission lives in `posthog-ai.ts`.
+  `RequestContext.browserSessionId`. The agent chat and the action client both
+  send that header, so a UI action call and the agent's own call during one
+  visit share a session. `setAnalyticsSessionId()` from
+  `@agent-native/core/client/analytics` pins a custom id and opts it out of the
+  30-minute idle rotation. Emission lives in `posthog-ai.ts`.
 - 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`,

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

@@ -18,19 +18,26 @@ The tracking system provides a single `track()` call that fans out to all regist
 ## How It Works
 
 1. At server startup, `registerBuiltinProviders()` checks env vars and registers any configured providers.
-2. Application code calls `track(eventName, properties, meta)` from actions, plugins, or server routes.
+2. Application code calls `track(eventName, properties, source)` from actions, plugins, or server routes.
 3. The registry fans out the event to every registered provider. Errors are caught and logged -- a failing provider never crashes the caller.
 4. Built-in providers batch HTTP calls (flush every 10 seconds or 50 events, whichever comes first).
 
 ## API
 
-### `track(name, properties?, meta?)`
+### `track(name, properties?, source?)`
 
-Fire an analytics event.
+Fire an analytics event. `source` is either a `{ userId, anonymousId, sessionId }`
+meta object or an action's `ctx` passed straight through.
 
 ```ts
 import { track } from "@agent-native/core/tracking";
 
+// From an action — pass ctx; userId comes from ctx.userEmail.
+run: async ({ name }, ctx) => {
+  track("meal.logged", { mealName: name, calories: 350 }, ctx);
+};
+
+// From a plugin or route with no ctx.
 track(
   "meal.logged",
   { mealName: "Salad", calories: 350 },
@@ -38,6 +45,16 @@ track(
 );
 ```
 
+The caller's browser session comes from the ambient request context
+(`RequestContext.browserSessionId`, set from the `X-Agent-Native-Session-Id`
+header), so it resolves the same whether the UI called the action or the agent
+did. Pass `sessionId` in the meta object to override it — routes that run
+outside a request context, such as `/_agent-native/track`, do exactly that.
+Providers map it to their own session field: `$session_id` for PostHog (which
+joins the event to session replay), `session_id` as a property for Mixpanel and
+Amplitude, a top-level `sessionId` for webhooks and Agent Native Analytics. It
+is absent for callers with no browser — cron, CLI, MCP, A2A.
+
 ### `identify(userId, traits?)`
 
 Identify a user with traits. Forwarded to providers that support it.