@agent-native/core 0.167.1 → 0.168.0

package/dist/server/agent-chat/recurring-jobs-runtime.js

@@ -30,20 +30,27 @@ function isLoopbackAppUrl(value) {
     }
     return false;
 }
-export function shouldDisableRecurringJobsRuntime(env = process.env) {
-    if (isTruthyEnv(env.AGENT_NATIVE_DISABLE_RECURRING_JOBS))
-        return true;
-    // A serverless isolate is not a durable scheduler. Keep this check separate
-    // from the platform-specific scheduler branch below so a new sweep cannot
-    // accidentally start an in-process timer before its platform trigger exists.
-    const isServerlessRuntime = env.NETLIFY_LOCAL !== "true" &&
+/**
+ * A serverless isolate is not a durable scheduler. Shared so
+ * `shouldDisableRecurringJobsRuntime` and `scheduledTriggerAvailability` cannot
+ * drift on what counts as serverless.
+ */
+function isServerlessRecurringJobsRuntime(env) {
+    return (env.NETLIFY_LOCAL !== "true" &&
         (isTruthyEnv(env.NETLIFY) ||
             env.NITRO_PRESET === "netlify" ||
             Boolean(env.AWS_LAMBDA_FUNCTION_NAME) ||
             env.AWS_EXECUTION_ENV?.startsWith("AWS_Lambda") === true ||
             isTruthyEnv(env.CF_PAGES) ||
-            isTruthyEnv(env.VERCEL));
-    if (isServerlessRuntime)
+            isTruthyEnv(env.VERCEL)));
+}
+export function shouldDisableRecurringJobsRuntime(env = process.env) {
+    if (isTruthyEnv(env.AGENT_NATIVE_DISABLE_RECURRING_JOBS))
+        return true;
+    // Keep this check separate from the platform-specific scheduler branch below
+    // so a new sweep cannot accidentally start an in-process timer before its
+    // platform trigger exists.
+    if (isServerlessRecurringJobsRuntime(env))
         return true;
     const isLocalRuntime = env.NODE_ENV === "development" ||
         env.NODE_ENV === "test" ||
@@ -74,3 +81,89 @@ export function isNetlifyRecurringJobsRuntime(env = process.env) {
         return false;
     return Boolean((env.NETLIFY && env.NETLIFY !== "false") || env.SITE_ID);
 }
+/**
+ * Env name the build embeds its recurring-jobs decision under.
+ *
+ * Netlify's scheduled function is emitted — or omitted — while the build runs,
+ * and a deployed serverless runtime never sees the build environment. So the
+ * build has to hand the decision over explicitly; nothing observable at runtime
+ * can reconstruct it. Consumed below as a LITERAL `process.env.<name>` member
+ * expression because that is the only form Vite's `define` and Nitro's
+ * `replace` inline at build time.
+ */
+export const RECURRING_JOBS_BUILD_MARKER_ENV_VAR = "AGENT_NATIVE_BUILD_RECURRING_JOBS";
+/**
+ * Build-side resolver: what the build environment decided. Shared with
+ * `isRecurringJobsDeployEnabled` in the deploy build so the gate that emits the
+ * scheduled function and the marker that reports it cannot disagree.
+ */
+export function resolveRecurringJobsBuildMarker(env = process.env) {
+    return isTruthyEnv(env.AGENT_NATIVE_DISABLE_RECURRING_JOBS)
+        ? "disabled"
+        : "enabled";
+}
+function readRecurringJobsBuildMarker(env) {
+    const raw = env.AGENT_NATIVE_BUILD_RECURRING_JOBS ??
+        // config-ok: this value is INLINED at build time by Vite's `define` /
+        // Nitro's `replace`, which rewrite the literal `process.env.<NAME>` member
+        // expression and nothing else. A declared app-config field is read at
+        // runtime from the deployed environment, which is precisely the scope that
+        // cannot see the build's decision — the bug this marker exists to fix.
+        // Reading through the aliased `env` parameter would also survive the build
+        // unreplaced, so the literal form is load-bearing.
+        process.env.AGENT_NATIVE_BUILD_RECURRING_JOBS;
+    const value = raw?.trim();
+    return value === "enabled" || value === "disabled" ? value : undefined;
+}
+/**
+ * Whether ANY driver will actually fire a schedule-triggered automation in this
+ * deploy. Distinct from `shouldDisableRecurringJobsRuntime`, which answers the
+ * narrower "should THIS process run an in-process timer" and is therefore `true`
+ * on hosted Netlify even though schedules do fire there via the emitted
+ * scheduled function — reporting that value to a user would call the one
+ * working production runtime broken.
+ *
+ * Each branch reads the scope that actually decides its driver. The Netlify
+ * driver is a BUILD artifact, so it is answered by the build marker; every other
+ * driver is an in-process timer started from the RUNTIME env, so it is answered
+ * by the runtime flag. Reading runtime-only platform markers for the Netlify
+ * branch would report `available` off a build that emitted no trigger at all.
+ */
+export function scheduledTriggerAvailability(env = process.env) {
+    const buildMarker = readRecurringJobsBuildMarker(env);
+    // Netlify: the driver IS the emitted scheduled function. It fires on the
+    // platform's clock without consulting the deployed env, and no runtime value
+    // can conjure it back once the build omitted it — so the build marker is the
+    // only honest input here, in both directions.
+    if (isNetlifyRecurringJobsRuntime(env)) {
+        if (buildMarker === "disabled") {
+            return { available: false, reason: "disabled-by-env" };
+        }
+        if (buildMarker === "enabled") {
+            return { available: true, driver: "netlify-scheduled-function" };
+        }
+        // No marker: a build predating it, or a caller passing a synthetic env.
+        // Fall back to the runtime flag, which only agrees with the build when the
+        // pipeline sets the same value in both scopes.
+        return isTruthyEnv(env.AGENT_NATIVE_DISABLE_RECURRING_JOBS)
+            ? { available: false, reason: "disabled-by-env" }
+            : { available: true, driver: "netlify-scheduled-function" };
+    }
+    // Everything below is driven by an in-process timer, and the runtime flag is
+    // what `shouldDisableRecurringJobsRuntime` reads before starting it. A build
+    // marker cannot speak for this branch: a build with recurring jobs turned off
+    // still starts the timer if the deployed env does not repeat the switch.
+    if (isTruthyEnv(env.AGENT_NATIVE_DISABLE_RECURRING_JOBS)) {
+        return { available: false, reason: "disabled-by-env" };
+    }
+    // Every other serverless host: the build emits a scheduled trigger only for
+    // Netlify, and a frozen isolate cannot hold a timer.
+    if (isServerlessRecurringJobsRuntime(env)) {
+        return { available: false, reason: "no-platform-scheduler" };
+    }
+    // Long-lived host. Whatever is left of the runtime gate here is the
+    // local/loopback branch, which needs AGENT_NATIVE_ENABLE_LOCAL_RECURRING_JOBS.
+    return shouldDisableRecurringJobsRuntime(env)
+        ? { available: false, reason: "local-development" }
+        : { available: true, driver: "in-process" };
+}

package/dist/server/agent-chat-plugin.d.ts

@@ -9,7 +9,7 @@ import { _agentChatPromptSectionsForTests } from "./agent-chat/framework-prompts
 import { type AgentChatPluginOptions, type NitroPluginDef } from "./agent-chat/plugin-options.js";
 import { finalizeClaimedAgentChatProcessRunFailure } from "./agent-chat/process-run-failure.js";
 import { loadResourcesForPrompt } from "./agent-chat/prompt-resources.js";
-import { isNetlifyRecurringJobsRuntime, shouldDisableRecurringJobsRuntime } from "./agent-chat/recurring-jobs-runtime.js";
+import { isNetlifyRecurringJobsRuntime, resolveRecurringJobsBuildMarker, scheduledTriggerAvailability, shouldDisableRecurringJobsRuntime } from "./agent-chat/recurring-jobs-runtime.js";
 import { shouldBlockInProductCodeEditingSurface } from "./agent-chat/request-surface.js";
 import { loadRunCodeToolEntries } from "./agent-chat/run-code-tools.js";
 export { loadResourcesForPrompt };
@@ -34,6 +34,8 @@ export { DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKEN
 export { shouldBlockInProductCodeEditingSurface };
 export { loadRunCodeToolEntries };
 export { isNetlifyRecurringJobsRuntime };
+export { resolveRecurringJobsBuildMarker };
+export { scheduledTriggerAvailability };
 export { shouldDisableRecurringJobsRuntime };
 export { finalizeClaimedAgentChatProcessRunFailure };
 export declare function resolveInteractiveAgentRunOptions(options?: Pick<AgentChatPluginOptions, "runSoftTimeoutMs" | "runNoProgressTimeoutMs" | "durableBackgroundRuns">): {

package/dist/server/agent-chat-plugin.js

@@ -23,7 +23,7 @@ import { attachToolSearch } from "../agent/tool-search.js";
 import { getAppConfig } from "../app-config/index.js";
 import { readAppStateForCurrentTab } from "../application-state/script-helpers.js";
 import { runChatThreadDataMigrations } from "../chat-threads/migrations.js";
-import { adoptThreadScopeIfUnscoped, createThread, forkThread, getThread, registerChatThreadsShareable, resolveRunThreadScope, resolveThreadAccess, listThreads, searchThreads, renameThread, createThreadShareLink, getThreadByShareToken, getThreadShareState, revokeThreadShareLink, setThreadArchived, setThreadPinned, setThreadScope, updateThreadData, withThreadDataLock, deleteThread, setThreadQueuedMessages, setThreadSourceIfMissing, } from "../chat-threads/store.js";
+import { adoptThreadScopeIfUnscoped, createThread, forkThread, getThread, registerChatThreadsShareable, resolveRunThreadScope, resolveThreadAccess, listThreads, searchThreads, renameThread, createThreadShareLink, getThreadByShareToken, getThreadShareState, revokeThreadShareLink, setThreadArchived, setThreadPinned, setThreadScope, updateThreadData, withThreadDataLock, deleteThread, setThreadQueuedMessages, setThreadSourceIfMissing, isAppOwnedChatScope, threadScopeMismatch, } from "../chat-threads/store.js";
 import { isCheckpointRestorePath } from "../checkpoints/route-match.js";
 import { createDbAdminAgentTools } from "../db-admin/agent-tools.js";
 import { isProductionServerlessFunctionRuntime, isTransientDatabaseError, } from "../db/client.js";
@@ -120,7 +120,7 @@ import { resolveAgentChatMcpOptions } from "./agent-chat/mcp-options.js";
 import { resolveA2AAgentDelegationEnabled, } from "./agent-chat/plugin-options.js";
 import { finalizeClaimedAgentChatProcessRunFailure } from "./agent-chat/process-run-failure.js";
 import { loadResourcesForPrompt, promptResourceManifestSections, resourceScopeForOwner, } from "./agent-chat/prompt-resources.js";
-import { isNetlifyRecurringJobsRuntime, shouldDisableRecurringJobsRuntime, } from "./agent-chat/recurring-jobs-runtime.js";
+import { isNetlifyRecurringJobsRuntime, resolveRecurringJobsBuildMarker, scheduledTriggerAvailability, shouldDisableRecurringJobsRuntime, } from "./agent-chat/recurring-jobs-runtime.js";
 import { isLocalhost, shouldBlockInProductCodeEditingSurface, } from "./agent-chat/request-surface.js";
 import { loadRunCodeToolEntries } from "./agent-chat/run-code-tools.js";
 import { createAgentEngineScriptEntries, createAgentLoopSettingsScriptEntries, createCallAgentScriptEntry, createChatScriptEntries, createDbScriptEntries, createDocsScriptEntries, createResourceScriptEntries, } from "./agent-chat/script-entries.js";
@@ -147,6 +147,8 @@ export { DEFAULT_DELEGATED_MAX_ITERATIONS, DEFAULT_DELEGATED_MAX_RUN_INPUT_TOKEN
 export { shouldBlockInProductCodeEditingSurface };
 export { loadRunCodeToolEntries };
 export { isNetlifyRecurringJobsRuntime };
+export { resolveRecurringJobsBuildMarker };
+export { scheduledTriggerAvailability };
 export { shouldDisableRecurringJobsRuntime };
 export { finalizeClaimedAgentChatProcessRunFailure };
 export function resolveInteractiveAgentRunOptions(options) {
@@ -2288,17 +2290,23 @@ export function createAgentChatPlugin(options) {
                             thread = await getThread(threadId);
                         }
                     }
-                    if (options?.appId) {
-                        await setThreadSourceIfMissing(threadId, {
-                            appId: options.appId,
+                    if (!thread) {
+                        throw createError({
+                            statusCode: 404,
+                            statusMessage: "Thread not found",
                         });
                     }
-                    if (!thread) {
+                    if (threadScopeMismatch(thread.scope, runScope)) {
                         throw createError({
                             statusCode: 404,
                             statusMessage: "Thread not found",
                         });
                     }
+                    if (options?.appId) {
+                        await setThreadSourceIfMissing(threadId, {
+                            appId: options.appId,
+                        });
+                    }
                     const access = await resolveThreadAccess(ownerEmail, threadId, "editor", { orgId: getRequestOrgId() });
                     if (!access) {
                         throw createError({
@@ -2818,6 +2826,12 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     if (details.threadId && details.ownerEmail) {
                         const existingThread = await getThread(details.threadId);
                         if (existingThread) {
+                            if (threadScopeMismatch(existingThread.scope, getRequestRunContext()?.chatScope)) {
+                                throw createError({
+                                    statusCode: 404,
+                                    statusMessage: "Thread not found",
+                                });
+                            }
                             const access = await resolveThreadAccess(details.ownerEmail, details.threadId, "editor", { orgId: await getOrgIdFromEvent(details.event) });
                             if (!access) {
                                 throw createError({
@@ -3094,6 +3108,12 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         if (details.threadId && details.ownerEmail) {
                             const existingThread = await getThread(details.threadId);
                             if (existingThread) {
+                                if (threadScopeMismatch(existingThread.scope, getRequestRunContext()?.chatScope)) {
+                                    throw createError({
+                                        statusCode: 404,
+                                        statusMessage: "Thread not found",
+                                    });
+                                }
                                 const access = await resolveThreadAccess(details.ownerEmail, details.threadId, "editor", { orgId: await getOrgIdFromEvent(details.event) });
                                 if (!access) {
                                     throw createError({
@@ -4471,11 +4491,16 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 const method = getMethod(event);
                 const { threadId, tail: threadTail } = parseThreadRoute(event);
                 const isThreadSubroute = (subroute) => threadTail[0] === subroute;
+                const requestedScope = parseScopeFromQuery(getQuery(event));
+                const scopesMatch = (left, right) => Boolean(left && right && left.type === right.type && left.id === right.id);
+                const threadMatchesRequestedScope = (thread, incomingScope) => !requestedScope ||
+                    scopesMatch(thread.scope, requestedScope) ||
+                    (!thread.scope && scopesMatch(incomingScope, requestedScope));
                 // ── Specific thread: GET/PUT/DELETE /threads/:id ──
                 if (threadId) {
                     if (method === "GET") {
                         const thread = await resolveThreadAccess(owner, threadId, "viewer", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4489,12 +4514,33 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         // run could clobber the assistant message the server just
                         // appended (and vice versa).
                         return await withThreadDataLock(threadId, async () => {
+                            const body = await readBody(event);
+                            const bodyIncludesScope = Boolean(body &&
+                                typeof body === "object" &&
+                                Object.prototype.hasOwnProperty.call(body, "scope"));
+                            const incomingScope = bodyIncludesScope
+                                ? parseScopeFromBody(body.scope)
+                                : undefined;
                             const thread = await resolveThreadAccess(owner, threadId, "editor", { orgId });
-                            if (!thread) {
+                            if (!thread ||
+                                !threadMatchesRequestedScope(thread, incomingScope)) {
+                                setResponseStatus(event, 404);
+                                return { error: "Thread not found" };
+                            }
+                            const bodyScopeMatchesRequestedScope = !requestedScope ||
+                                !incomingScope ||
+                                scopesMatch(incomingScope, requestedScope);
+                            const unauthorizedScopeChange = bodyIncludesScope &&
+                                ((incomingScope !== null &&
+                                    (threadScopeMismatch(thread.scope, incomingScope) ||
+                                        !bodyScopeMatchesRequestedScope)) ||
+                                    (incomingScope === null &&
+                                        isAppOwnedChatScope(thread.scope) &&
+                                        !requestedScope));
+                            if (unauthorizedScopeChange) {
                                 setResponseStatus(event, 404);
                                 return { error: "Thread not found" };
                             }
-                            const body = await readBody(event);
                             let newThreadData = body.threadData || thread.threadData;
                             let newMessageCount = body.messageCount ?? thread.messageCount;
                             let nextTitle = typeof body.title === "string" ? body.title : thread.title;
@@ -4541,9 +4587,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                             }
                             await updateThreadData(threadId, newThreadData, nextTitle, nextPreview, newMessageCount, { ignoreConflicts: true });
                             // Scope updates piggyback on the PUT — the client uses this
-                            // path for both "detach" (scope: null) and "retag" flows.
-                            // Send the field as `scope: undefined` (or omit it) when
-                            // you don't want to touch the existing scope.
+                            // path for detach and for claiming a legacy unscoped thread.
+                            // A scoped thread cannot be retagged across resources here.
                             if (Object.prototype.hasOwnProperty.call(body, "scope")) {
                                 const incomingScope = parseScopeFromBody(body.scope);
                                 await setThreadScope(threadId, incomingScope);
@@ -4557,7 +4602,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     // on full-thread saves.
                     if (method === "POST" && isThreadSubroute("queued")) {
                         const thread = await resolveThreadAccess(owner, threadId, "editor", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4574,7 +4619,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     }
                     if (method === "POST" && isThreadSubroute("rename")) {
                         const thread = await resolveThreadAccess(owner, threadId, "editor", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4595,7 +4640,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     }
                     if (method === "POST" && isThreadSubroute("pin")) {
                         const thread = await resolveThreadAccess(owner, threadId, "editor", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4613,7 +4658,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     }
                     if (method === "POST" && isThreadSubroute("archive")) {
                         const thread = await resolveThreadAccess(owner, threadId, "editor", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4632,7 +4677,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     // POST /threads/:id/fork — duplicate a thread with all its messages
                     if (method === "POST" && isThreadSubroute("fork")) {
                         const thread = await resolveThreadAccess(owner, threadId, "viewer", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4650,7 +4695,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     }
                     if (isThreadSubroute("share")) {
                         const thread = await resolveThreadAccess(owner, threadId, "admin", { orgId });
-                        if (!thread) {
+                        if (!thread || !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4684,7 +4729,9 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     }
                     if (method === "DELETE") {
                         const thread = await getThread(threadId);
-                        if (!thread || thread.ownerEmail !== owner) {
+                        if (!thread ||
+                            thread.ownerEmail !== owner ||
+                            !threadMatchesRequestedScope(thread)) {
                             setResponseStatus(event, 404);
                             return { error: "Thread not found" };
                         }
@@ -4725,6 +4772,46 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 }
                 if (method === "POST") {
                     const body = await readBody(event);
+                    const requestedScope = parseScopeFromQuery(getQuery(event));
+                    const bodyIncludesScope = Boolean(body &&
+                        typeof body === "object" &&
+                        Object.prototype.hasOwnProperty.call(body, "scope"));
+                    const bodyScope = bodyIncludesScope
+                        ? parseScopeFromBody(body.scope)
+                        : undefined;
+                    const bodyScopeMatchesRequestedScope = !requestedScope ||
+                        !bodyIncludesScope ||
+                        (bodyScope !== null && scopesMatch(bodyScope, requestedScope));
+                    if (!bodyScopeMatchesRequestedScope) {
+                        setResponseStatus(event, 404);
+                        return { error: "Thread not found" };
+                    }
+                    const resolveExistingOwnedThread = async (existing) => {
+                        if ((requestedScope &&
+                            threadScopeMismatch(existing.scope, requestedScope)) ||
+                            (bodyIncludesScope &&
+                                threadScopeMismatch(existing.scope, bodyScope))) {
+                            setResponseStatus(event, 404);
+                            return null;
+                        }
+                        const scopeToAdopt = bodyIncludesScope
+                            ? bodyScope
+                            : requestedScope;
+                        if (!existing.scope && scopeToAdopt) {
+                            const adoptedScope = await adoptThreadScopeIfUnscoped(existing.id, scopeToAdopt);
+                            if (!scopesMatch(adoptedScope, scopeToAdopt)) {
+                                setResponseStatus(event, 404);
+                                return null;
+                            }
+                            const adopted = await getThread(existing.id);
+                            if (!adopted) {
+                                setResponseStatus(event, 404);
+                                return null;
+                            }
+                            return adopted;
+                        }
+                        return existing;
+                    };
                     // Idempotent: when the caller supplies an id and a thread with
                     // that id already exists for this owner, return it instead of
                     // 500'ing on the UNIQUE constraint. The client can race with
@@ -4735,8 +4822,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     if (body?.id) {
                         const existing = await getThread(body.id);
                         if (existing) {
-                            if (existing.ownerEmail === owner)
-                                return existing;
+                            if (existing.ownerEmail === owner) {
+                                const resolved = await resolveExistingOwnedThread(existing);
+                                return resolved ?? { error: "Thread not found" };
+                            }
                             setResponseStatus(event, 409);
                             return { error: "Thread id already in use" };
                         }
@@ -4745,7 +4834,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         const thread = await createThread(owner, {
                             id: body?.id,
                             title: body?.title ?? "",
-                            scope: parseScopeFromBody(body?.scope),
+                            scope: bodyIncludesScope ? bodyScope : requestedScope,
                             source: options?.appId ? { appId: options.appId } : null,
                         });
                         return thread;
@@ -4756,8 +4845,10 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         // return the row that actually landed.
                         if (body?.id) {
                             const existing = await getThread(body.id);
-                            if (existing && existing.ownerEmail === owner)
-                                return existing;
+                            if (existing && existing.ownerEmail === owner) {
+                                const resolved = await resolveExistingOwnedThread(existing);
+                                return resolved ?? { error: "Thread not found" };
+                            }
                         }
                         throw err;
                     }

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/attribution.d.ts

@@ -35,6 +35,18 @@ export interface FirstTouchAttribution {
     /** ISO timestamp of when the visitor first landed. */
     landed_at?: string;
 }
+/**
+ * Request-scoped browser attribution captured at the signup boundary.
+ * Better Auth may create the user in a later async callback where the
+ * original request headers are no longer available, so the values must be
+ * carried explicitly through that boundary.
+ */
+export interface SignupAttributionContext {
+    attribution: Record<string, string>;
+    anonymousId?: string;
+}
+/** Internal Better Auth handoff header; attribution is analytics-only. */
+export declare const SIGNUP_ATTRIBUTION_HEADER_NAME = "x-agent-native-signup-attribution";
 /** Cookie name written by the client (non-HttpOnly; non-sensitive). */
 export declare const FIRST_TOUCH_COOKIE_NAME = "an_ft";
 /**
@@ -87,3 +99,20 @@ export declare function deriveSignupAttribution(ft: FirstTouchAttribution | null
  * error.
  */
 export declare function signupAttributionFromCookieHeader(cookieHeader: string | null | undefined): Record<string, string>;
+/**
+ * Capture all browser attribution needed by the server-side signup event.
+ * Keep this as one boundary helper so every signup entry point carries the
+ * same values into Better Auth's user-create hook.
+ */
+export declare function signupAttributionContextFromCookieHeader(cookieHeader: string | null | undefined): SignupAttributionContext;
+/** Serialize the bounded attribution handoff for a Better Auth request. */
+export declare function encodeSignupAttributionContext(context: SignupAttributionContext): string;
+/**
+ * Decode the internal handoff header. Invalid input is absent, not a direct
+ * attribution, so the caller can safely fall back to the request cookie.
+ */
+export declare function decodeSignupAttributionContext(value: string | null | undefined): SignupAttributionContext | undefined;
+/** Add the explicit handoff to a Better Auth request/API header set. */
+export declare function addSignupAttributionHeader(headers: HeadersInit | undefined, context: SignupAttributionContext): Headers;
+/** Read the explicit handoff from Better Auth's request context headers. */
+export declare function signupAttributionContextFromHeaders(headers: Headers | null | undefined): SignupAttributionContext | undefined;

package/dist/server/attribution.js

@@ -1,4 +1,7 @@
 import { ANALYTICS_ANONYMOUS_ID_COOKIE_NAME, normalizeAnalyticsAnonymousId, } from "../shared/analytics-anonymous-id.js";
+/** Internal Better Auth handoff header; attribution is analytics-only. */
+export const SIGNUP_ATTRIBUTION_HEADER_NAME = "x-agent-native-signup-attribution";
+const SIGNUP_ATTRIBUTION_HEADER_MAX_LENGTH = 4096;
 /** Cookie name written by the client (non-HttpOnly; non-sensitive). */
 export const FIRST_TOUCH_COOKIE_NAME = "an_ft";
 const STRING_FIELDS = [
@@ -178,3 +181,68 @@ export function signupAttributionFromCookieHeader(cookieHeader) {
         return { referral_source: "direct" };
     }
 }
+/**
+ * Capture all browser attribution needed by the server-side signup event.
+ * Keep this as one boundary helper so every signup entry point carries the
+ * same values into Better Auth's user-create hook.
+ */
+export function signupAttributionContextFromCookieHeader(cookieHeader) {
+    const anonymousId = readAnalyticsAnonymousId(cookieHeader);
+    return {
+        attribution: signupAttributionFromCookieHeader(cookieHeader),
+        ...(anonymousId ? { anonymousId } : {}),
+    };
+}
+/** Serialize the bounded attribution handoff for a Better Auth request. */
+export function encodeSignupAttributionContext(context) {
+    return encodeURIComponent(JSON.stringify(context));
+}
+/**
+ * Decode the internal handoff header. Invalid input is absent, not a direct
+ * attribution, so the caller can safely fall back to the request cookie.
+ */
+export function decodeSignupAttributionContext(value) {
+    if (!value || value.length > SIGNUP_ATTRIBUTION_HEADER_MAX_LENGTH) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(decodeURIComponent(value));
+        const rawAttribution = parsed?.attribution;
+        if (!rawAttribution ||
+            typeof rawAttribution !== "object" ||
+            Array.isArray(rawAttribution)) {
+            return undefined;
+        }
+        const attribution = {};
+        for (const [key, rawValue] of Object.entries(rawAttribution)) {
+            if (/^[A-Za-z0-9_]+$/.test(key) &&
+                key.length <= 64 &&
+                typeof rawValue === "string" &&
+                rawValue.length > 0) {
+                attribution[key] = rawValue.slice(0, 120);
+            }
+        }
+        if (Object.keys(attribution).length === 0)
+            return undefined;
+        const anonymousId = normalizeAnalyticsAnonymousId(parsed?.anonymousId);
+        return {
+            attribution,
+            ...(anonymousId ? { anonymousId } : {}),
+        };
+    }
+    catch (error) {
+        // `undefined` distinguishes an unreadable handoff from direct attribution.
+        void error;
+        return undefined;
+    }
+}
+/** Add the explicit handoff to a Better Auth request/API header set. */
+export function addSignupAttributionHeader(headers, context) {
+    const result = new Headers(headers);
+    result.set(SIGNUP_ATTRIBUTION_HEADER_NAME, encodeSignupAttributionContext(context));
+    return result;
+}
+/** Read the explicit handoff from Better Auth's request context headers. */
+export function signupAttributionContextFromHeaders(headers) {
+    return decodeSignupAttributionContext(headers?.get(SIGNUP_ATTRIBUTION_HEADER_NAME));
+}