@agent-native/core 0.144.1 → 0.144.3

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

@@ -38,7 +38,16 @@ function setTimer(t) {
 function enqueue(url, body, headers, options) {
     const queue = getQueue();
     queue.push({ url, body, headers });
-    if (options?.flushImmediately || queue.length >= MAX_BATCH_SIZE) {
+    // The batch timer is unref'd so it never keeps a long-lived server alive —
+    // but on Netlify/Vercel/Lambda the execution environment can freeze the
+    // moment the event loop looks empty, which is exactly when an unref'd timer
+    // doesn't count. Without a signal, a warm container freezing between
+    // invocations never fires that timer, silently dropping every provider's
+    // queued events for a request that ends in a crash. Default to flushing
+    // synchronously with the response in that environment; a caller (e.g.
+    // Agent Native Analytics' flush-mode override) can still force either way.
+    const flushImmediately = options?.flushImmediately ?? isServerlessRuntime();
+    if (flushImmediately || queue.length >= MAX_BATCH_SIZE) {
         void drainQueue();
     }
     else if (!getTimer()) {
@@ -134,6 +143,7 @@ function createPostHogProvider(apiKey, host, errorTracking) {
             properties: {
                 distinct_id: distinctId,
                 ...properties,
+                ...(event.sessionId ? { $session_id: event.sessionId } : {}),
                 timestamp: event.timestamp,
             },
         }));
@@ -168,6 +178,7 @@ function createPostHogProvider(apiKey, host, errorTracking) {
                 distinct_id: distinctId,
                 properties: {
                     ...event.properties,
+                    ...(event.sessionId ? { $session_id: event.sessionId } : {}),
                     timestamp: event.timestamp,
                 },
             }));
@@ -225,6 +236,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 +267,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 +308,7 @@ function createWebhookProvider(url, authHeader) {
                 event: event.name,
                 properties: event.properties,
                 userId: event.userId,
+                sessionId: event.sessionId,
                 timestamp: event.timestamp,
             }), extra);
         },
@@ -318,6 +337,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.3",
   "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": {
@@ -72,6 +72,7 @@
     "./server/request-context": "./dist/server/request-context.js",
     "./server/design-token-utils": "./dist/server/design-token-utils.js",
     "./server/poll": "./dist/server/poll.js",
+    "./server/interval-job": "./dist/server/interval-job.js",
     "./server/sse": "./dist/server/sse.js",
     "./server/short-lived-token": "./dist/server/short-lived-token.js",
     "./integrations": "./dist/integrations/index.js",
@@ -411,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.3"
+    "@agent-native/toolkit": "^0.13.3",
+    "@agent-native/recap-cli": "0.5.3"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/default/.agents/skills/internationalization/SKILL.md

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

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

@@ -29,6 +29,11 @@ Templates use `app/i18n/`:
 Use BCP-47 filenames from the supported set: `en-US`, `zh-CN`, `es-ES`,
 `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN`, `ar-SA`.
 
+If an app only ships translations for a subset of that set, set
+`supportedLocales` on the `AgentNativeI18nCatalog` to that subset. Without it,
+`<LanguagePicker />` lists every framework-supported locale regardless of
+whether `loadMessages` can actually resolve it.
+
 ## UI Pattern
 
 - Wrap apps with `AppProviders i18n={{ catalog: i18nCatalog }}`.

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.