@agent-native/core 0.144.0 → 0.144.2

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;
     error?: undefined;
     ok: boolean;
+    count?: 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,37 +34,37 @@ 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;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
  * 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;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: 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/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/creating-templates.mdx

@@ -49,7 +49,7 @@ npx @agent-native/core@latest create my-platform
 
 Chat gives you auth, durable chat threads, SQL-backed resources, tools, application state, actions, and polling sync. You add the domain model and product UI.
 
-If you are not building a reusable UI template yet, use the headless on-ramp in [Getting Started](/docs/getting-started#create-your-app): define one action, run it with `pnpm agent`, and add UI later when the workflow needs a durable surface.
+If you are not building a reusable UI template yet, use [Automation-First Apps](/docs/pure-agent-apps): define actions, run them without a browser, and add UI later when the workflow needs a durable surface.
 
 ## Project Structure {#project-structure}