@agent-native/core 0.214.0 → 0.217.0

package/dist/server/first-touch-route.js

@@ -0,0 +1,115 @@
+import { appendResponseHeader, defineEventHandler, getHeader, getMethod, setResponseHeader, setResponseStatus, } from "h3";
+import { FIRST_TOUCH_SERVER_COOKIE_NAME, firstTouchServerExpiry, preferFirstTouch, } from "../shared/first-touch-persistence.js";
+import { FIRST_TOUCH_COOKIE_NAME, LAST_TOUCH_COOKIE_NAME, decodeFirstTouchServerValue, decodeFirstTouchValue, decodeLastTouchValue, encodeFirstTouchServerCookieValue, parseCookieHeader, } from "./attribution.js";
+import { requestAllowsConsentCategory } from "./consent-route.js";
+import { readBodyWithSizeLimit } from "./h3-helpers.js";
+import { getForwardedRequestOrigin, isSameOriginPost, } from "./request-origin.js";
+const MAX_BODY_BYTES = 8 * 1024;
+/** How long the browser's own `an_ft` and `an_lt` copies last. */
+const BROWSER_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+const BROWSER_COOKIES = [
+    { name: FIRST_TOUCH_COOKIE_NAME, decode: decodeFirstTouchValue },
+    { name: LAST_TOUCH_COOKIE_NAME, decode: decodeLastTouchValue },
+];
+// What `encodeURIComponent` emits, so a value echoed into Set-Cookie can't
+// carry an attribute or a header break.
+const ENCODED_COOKIE_VALUE = /^[A-Za-z0-9\-_.!~*'()%]{1,1500}$/;
+function cookieAttributes(event) {
+    const secure = getForwardedRequestOrigin(event).startsWith("https:");
+    return `Path=/; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+function clearAttributionCookies(event) {
+    for (const name of [
+        FIRST_TOUCH_SERVER_COOKIE_NAME,
+        FIRST_TOUCH_COOKIE_NAME,
+        LAST_TOUCH_COOKIE_NAME,
+    ]) {
+        appendResponseHeader(event, "set-cookie", `${name}=; Max-Age=0; ${cookieAttributes(event)}`);
+    }
+}
+/**
+ * Safari keeps a cookie page JavaScript wrote for seven days at most, so write
+ * the browser's own `an_ft` and `an_lt` again from here, for their full 30
+ * days. Only values that decode as touches are echoed back.
+ */
+function resetBrowserCookies(event) {
+    const cookies = parseCookieHeader(getHeader(event, "cookie"));
+    for (const { name, decode } of BROWSER_COOKIES) {
+        const value = cookies[name];
+        if (!value || !ENCODED_COOKIE_VALUE.test(value) || !decode(value)) {
+            continue;
+        }
+        appendResponseHeader(event, "set-cookie", `${name}=${value}; Max-Age=${BROWSER_COOKIE_MAX_AGE_SECONDS}; ${cookieAttributes(event)}`);
+    }
+}
+function readCandidate(body) {
+    const firstTouch = body?.firstTouch;
+    if (!firstTouch || typeof firstTouch !== "object")
+        return null;
+    return decodeFirstTouchValue(encodeURIComponent(JSON.stringify(firstTouch)));
+}
+/** A touch more than a year old can't be kept, or win against one that can. */
+function unexpired(touch) {
+    return touch && firstTouchServerExpiry(touch) ? touch : null;
+}
+/**
+ * `POST /_agent-native/auth/attribution` with `{ firstTouch }`: keep the
+ * browser's first touch in the year-long `an_fts` cookie. Anyone may call it,
+ * signed in or not, but only from this origin. The value already in the
+ * cookie wins unless `preferFirstTouch` picks the new one, so a slow request
+ * from another tab can't replace a better first touch it never saw. Where the
+ * banner applies and the visitor hasn't accepted targeting cookies, it stores
+ * nothing and clears every attribution cookie. Elsewhere it also writes the
+ * browser's `an_ft` and `an_lt` again, so Safari keeps them their 30 days.
+ */
+export function createFirstTouchHandler() {
+    return defineEventHandler(async (event) => {
+        setResponseHeader(event, "cache-control", "no-store");
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        if (!isSameOriginPost(event)) {
+            setResponseStatus(event, 403);
+            return { error: "Cross-origin request" };
+        }
+        let body;
+        try {
+            body = await readBodyWithSizeLimit(event, MAX_BODY_BYTES);
+        }
+        catch (error) {
+            if (error.statusCode === 413) {
+                return { error: "Body too large" };
+            }
+            setResponseStatus(event, 400);
+            return { error: "Invalid JSON" };
+        }
+        if (!requestAllowsConsentCategory(event, "targeting")) {
+            clearAttributionCookies(event);
+            return {
+                stored: false,
+                reason: "consent_required",
+            };
+        }
+        const candidate = readCandidate(body);
+        if (!candidate) {
+            setResponseStatus(event, 400);
+            return { error: "Missing firstTouch" };
+        }
+        resetBrowserCookies(event);
+        const existing = decodeFirstTouchServerValue(parseCookieHeader(getHeader(event, "cookie"))[FIRST_TOUCH_SERVER_COOKIE_NAME]);
+        const firstTouch = preferFirstTouch(unexpired(existing), unexpired(candidate));
+        const expires = firstTouch && firstTouchServerExpiry(firstTouch);
+        if (!firstTouch || !expires) {
+            return {
+                stored: false,
+                reason: "expired",
+            };
+        }
+        if (firstTouch !== existing) {
+            appendResponseHeader(event, "set-cookie", `${FIRST_TOUCH_SERVER_COOKIE_NAME}=${encodeFirstTouchServerCookieValue(firstTouch)}; ` +
+                `Expires=${expires.toUTCString()}; ${cookieAttributes(event)}`);
+        }
+        return { stored: true, firstTouch };
+    });
+}

package/dist/server/index.d.ts

@@ -104,7 +104,7 @@ export { resolveDeployPlatform, type DeployPlatform, } from "./deploy-environmen
 export { isServerlessRuntime } from "../db/client.js";
 export { BUILDER_PUBLISH_MCP_RESOURCE, canAuthorizeBuilderApiRequest, hasBuilderApiCredentialCustody, resolveBuilderApiAuthorization, resolveBuilderLegacyRequestAuthorization, resolveBuilderRequestAuthorization, type BuilderLegacyCredentialKey, type BuilderRequestAuthorization, } from "./builder-api-auth.js";
 export { createFusionAgentFeed, fusionStepToAgentChatEvents, type FusionAgentFeedSummary, } from "./fusion-agent-feed.js";
-export { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_OAUTH_SCOPE, type BuilderOAuthPermissionScope, } from "./builder-oauth.js";
+export { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_CONTENT_READ_SCOPE, BUILDER_CONTENT_WRITE_SCOPE, BUILDER_OAUTH_RESOURCE, BUILDER_OAUTH_SCOPE, type BuilderOAuthPermissionScope, } from "./builder-oauth.js";
 export { assertBuilderDesignSystemCodeIndexingAllowed, builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, designSystemTierUpgradeUrl, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, fetchBuilderDesignSystemDocumentCount, fetchBuilderDesignSystemRecord, fetchBuilderDesignSystemTierLimit, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, isBuilderDesignSystemReadyByCount, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemDocumentCountResult, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemRecord, type BuilderDesignSystemStatus, type BuilderDesignSystemTierLimit, type BuilderDesignSystemGitHubFile, type BuilderDesignSystemGitHubFileCollection, type BuilderDesignSystemGitHubSource, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
 export { cdnSafeOriginStatus, createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, normalizeBuilderAgentAttachments, runBuilderAgent, type BuilderAgentAttachment, type BuilderAgentUploadAttachment, type BuilderAgentUrlAttachment, type BuilderProjectResult, type RunBuilderAgentResult, } from "./builder-browser.js";
 export { BuilderBranchError, getBuilderBranchStatus, sendBuilderBranchMessage, type BuilderBranchAgentState, type BuilderBranchErrorCode, type BuilderBranchOperation, type BuilderBranchPrStatus, type BuilderBranchRef, type BuilderBranchState, type BuilderBranchStatus, type GetBuilderBranchStatusOptions, type SendBuilderBranchMessageOptions, type SendBuilderBranchMessageResult, } from "./builder-branch.js";
@@ -127,3 +127,4 @@ export { AGENT_READABLE_RESOURCE_PAYLOAD_TYPE, AGENT_READABLE_RESOURCE_SCRIPT_TY
 export { registerObservabilityProvider, type ObservabilityMeterProvider, type ObservabilityProvider, type ObservabilityTracerProvider, } from "../observability/otel-provider.js";
 export type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 export declare function defineNitroPlugin(def: NitroPluginDef): NitroPluginDef;
+export { appStateListKeysByKeySuffixPrefix } from "./application-state-maintenance.js";

package/dist/server/index.js

@@ -98,7 +98,7 @@ export { resolveDeployPlatform, } from "./deploy-environment.js";
 export { isServerlessRuntime } from "../db/client.js";
 export { BUILDER_PUBLISH_MCP_RESOURCE, canAuthorizeBuilderApiRequest, hasBuilderApiCredentialCustody, resolveBuilderApiAuthorization, resolveBuilderLegacyRequestAuthorization, resolveBuilderRequestAuthorization, } from "./builder-api-auth.js";
 export { createFusionAgentFeed, fusionStepToAgentChatEvents, } from "./fusion-agent-feed.js";
-export { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_OAUTH_SCOPE, } from "./builder-oauth.js";
+export { BUILDER_ASSETS_WRITE_SCOPE, BUILDER_CONTENT_READ_SCOPE, BUILDER_CONTENT_WRITE_SCOPE, BUILDER_OAUTH_RESOURCE, BUILDER_OAUTH_SCOPE, } from "./builder-oauth.js";
 export { assertBuilderDesignSystemCodeIndexingAllowed, builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, designSystemTierUpgradeUrl, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, fetchBuilderDesignSystemDocumentCount, fetchBuilderDesignSystemRecord, fetchBuilderDesignSystemTierLimit, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, isBuilderDesignSystemReadyByCount, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
 export { cdnSafeOriginStatus, createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, normalizeBuilderAgentAttachments, runBuilderAgent, } from "./builder-browser.js";
 export { BuilderBranchError, getBuilderBranchStatus, sendBuilderBranchMessage, } from "./builder-branch.js";
@@ -122,3 +122,4 @@ export { registerObservabilityProvider, } from "../observability/otel-provider.j
 export function defineNitroPlugin(def) {
     return def;
 }
+export { appStateListKeysByKeySuffixPrefix } from "./application-state-maintenance.js";

package/dist/server/queued-submission-inbox-drain.d.ts

@@ -0,0 +1,9 @@
+export declare function scheduleQueuedSubmissionInboxDrain(input: {
+    threadId: string;
+    turnContinues: boolean;
+    waitUntil?: (promise: Promise<unknown>) => void;
+    drain: (input: {
+        threadId: string;
+    }) => Promise<unknown>;
+    onError: (error: unknown) => void;
+}): void;

package/dist/server/queued-submission-inbox-drain.js

@@ -0,0 +1,12 @@
+import { runWithoutExecutionFence } from "../agent/execution-fence.js";
+export function scheduleQueuedSubmissionInboxDrain(input) {
+    if (input.turnContinues)
+        return;
+    const drain = Promise.resolve()
+        .then(() => runWithoutExecutionFence(() => input.drain({ threadId: input.threadId })))
+        .catch(input.onError);
+    if (input.waitUntil)
+        input.waitUntil(drain);
+    else
+        void drain;
+}

package/dist/server/request-origin.d.ts

@@ -4,4 +4,10 @@ export declare function getForwardedRequestOrigin(event: H3Event): string;
 export declare function getForwardedRequestURL(event: H3Event): URL;
 export declare function getForwardedRequestHostname(event: H3Event): string;
 export declare function getForwardedRequestHostnameFromHeaders(headers: Headers | IncomingHttpHeaders, remoteAddress?: string): string;
+/**
+ * Stricter than `isSameOriginRequest`, for a POST that writes cookies: a
+ * request with neither header, a navigation, or a desktop shell's origin
+ * can't prove it came from this site's pages.
+ */
+export declare function isSameOriginPost(event: H3Event): boolean;
 export declare function isSameOriginRequest(event: H3Event): boolean;

package/dist/server/request-origin.js

@@ -95,6 +95,18 @@ export function getForwardedRequestHostnameFromHeaders(headers, remoteAddress) {
 function isLoopbackHost(host) {
     return host.startsWith("localhost:") || host.startsWith("127.0.0.1:");
 }
+/**
+ * Stricter than `isSameOriginRequest`, for a POST that writes cookies: a
+ * request with neither header, a navigation, or a desktop shell's origin
+ * can't prove it came from this site's pages.
+ */
+export function isSameOriginPost(event) {
+    const fetchSite = getRequestHeader(event, "sec-fetch-site");
+    if (fetchSite)
+        return fetchSite === "same-origin";
+    const origin = getRequestHeader(event, "origin");
+    return !!origin && origin === getForwardedRequestOrigin(event);
+}
 export function isSameOriginRequest(event) {
     const fetchSite = getRequestHeader(event, "sec-fetch-site");
     if (fetchSite)

package/dist/settings/org-settings.d.ts

@@ -1,5 +1,6 @@
-import { type StoreWriteOptions, type StoreReadOptions } from "./store.js";
+import { type SettingEntry, type StoreWriteOptions, type StoreReadOptions } from "./store.js";
 export declare function getOrgSetting(orgId: string, key: string, options?: StoreReadOptions): Promise<Record<string, unknown> | null>;
+export declare function getOrgSettingEntry(orgId: string, key: string, options?: StoreReadOptions): Promise<SettingEntry>;
 export declare function putOrgSetting(orgId: string, key: string, value: Record<string, unknown>, options?: StoreWriteOptions): Promise<void>;
 export declare function mutateOrgSetting(orgId: string, key: string, updater: (current: Record<string, unknown> | null) => Record<string, unknown> | Promise<Record<string, unknown>>, options?: StoreWriteOptions): Promise<Record<string, unknown>>;
 export declare function deleteOrgSetting(orgId: string, key: string, options?: StoreWriteOptions): Promise<boolean>;

package/dist/settings/org-settings.js

@@ -1,4 +1,4 @@
-import { getSetting, mutateSetting, putSetting, deleteSetting, deleteSettingsByPrefix, listSettingsByPrefix, } from "./store.js";
+import { getSetting, getSettingEntry, mutateSetting, putSetting, deleteSetting, deleteSettingsByPrefix, listSettingsByPrefix, } from "./store.js";
 function orgKey(orgId, key) {
     return `o:${orgId}:${key}`;
 }
@@ -6,6 +6,9 @@ const ORG_PREFIX_RE = /^o:([^:]+):(.+)$/;
 export async function getOrgSetting(orgId, key, options) {
     return getSetting(orgKey(orgId, key), options);
 }
+export async function getOrgSettingEntry(orgId, key, options) {
+    return getSettingEntry(orgKey(orgId, key), options);
+}
 export async function putOrgSetting(orgId, key, value, options) {
     return putSetting(orgKey(orgId, key), value, options);
 }

package/dist/settings/store.d.ts

@@ -9,6 +9,14 @@ export interface StoreReadOptions {
     transaction?: DbExec;
 }
 export declare function getSetting(key: string, options?: StoreReadOptions): Promise<Record<string, unknown> | null>;
+export type SettingEntry = {
+    found: false;
+} | {
+    found: true;
+    value: unknown;
+};
+/** Like `getSetting`, but a stored JSON `null` is found, not missing. */
+export declare function getSettingEntry(key: string, options?: StoreReadOptions): Promise<SettingEntry>;
 export declare function getSettings(keys: readonly string[], options?: StoreReadOptions): Promise<Map<string, Record<string, unknown> | null>>;
 export interface StoreWriteOptions {
     requestSource?: string;

package/dist/settings/store.js

@@ -63,12 +63,10 @@ export const settingsStore = defineStore({
 export function ensureTable() {
     return settingsStore.ready();
 }
-export async function getSetting(key, options) {
+async function readSettingRaw(key, options) {
     const cache = options?.transaction ? null : requestSettingsCache();
-    if (!options?.bypassCache && cache?.has(key)) {
-        const cached = cache.get(key);
-        return cached == null ? null : JSON.parse(cached);
-    }
+    if (!options?.bypassCache && cache?.has(key))
+        return cache.get(key) ?? null;
     if (!options?.transaction)
         await ensureTable();
     const client = options?.transaction ?? getDbExec();
@@ -80,8 +78,19 @@ export async function getSetting(key, options) {
     const raw = rows.length === 0 ? null : rows[0].value;
     if (!options?.bypassCache)
         cache?.set(key, raw);
+    return raw;
+}
+export async function getSetting(key, options) {
+    const raw = await readSettingRaw(key, options);
     return raw == null ? null : JSON.parse(raw);
 }
+/** Like `getSetting`, but a stored JSON `null` is found, not missing. */
+export async function getSettingEntry(key, options) {
+    const raw = await readSettingRaw(key, options);
+    return raw == null
+        ? { found: false }
+        : { found: true, value: JSON.parse(raw) };
+}
 const SETTINGS_IN_LIST_CHUNK_SIZE = 500;
 function parseSettingValue(key, raw) {
     try {

package/dist/shared/consent.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cookie consent for the regions that need it. The regions and categories
+ * follow builder.io's consent banner: visitors in these countries opt in, and
+ * every other visitor is tracked as before, with no banner.
+ */
+/** For the inline bootstrap the server writes into each page. */
+export declare const CONSENT_REGION_TIME_ZONE_LIST: readonly string[];
+export declare function isConsentRegionCountry(code: string | null | undefined): boolean;
+export declare function isConsentRegionTimeZone(timeZone: string | null | undefined): boolean;
+/**
+ * What the banner asks about. `performance` covers analytics (Google
+ * Analytics, Amplitude); `targeting` covers advertising and attribution (Tag
+ * Manager's ad tags, the referral attribution cookies). Strictly necessary
+ * cookies need no consent.
+ */
+export type ConsentCategory = "performance" | "targeting";
+export type ConsentChoice = Record<ConsentCategory, boolean>;
+/** `consent` shows the banner; `none` tracks as before. */
+export type ConsentRegion = "consent" | "none";
+export declare const CONSENT_COOKIE_NAME = "an_consent";
+/** Asked again a year later, like builder.io. */
+export declare const CONSENT_COOKIE_LIFETIME_SECONDS: number;
+export declare const CONSENT_REGION_PATH = "/_agent-native/auth/consent-region";
+export declare const CONSENT_PATH = "/_agent-native/auth/consent";
+/**
+ * One choice covers the site and every app on agent-native.com. The browser
+ * and the server must agree, or the two copies become two cookies.
+ */
+export declare function consentCookieDomain(hostname: string): string | null;
+/** `1.p1.t0`: version, then one flag per category. */
+export declare function serializeConsent(choice: ConsentChoice): string;
+/** The stored choice, or `null` when there is none this version can read. */
+export declare function parseConsent(value: string | null | undefined): ConsentChoice | null;

package/dist/shared/consent.js

@@ -0,0 +1,149 @@
+/**
+ * Cookie consent for the regions that need it. The regions and categories
+ * follow builder.io's consent banner: visitors in these countries opt in, and
+ * every other visitor is tracked as before, with no banner.
+ */
+/**
+ * Countries that see the banner: builder.io's "GDPR" rule, i.e. the EU, the
+ * rest of the EEA, Monaco, San Marino, Åland and France's overseas regions.
+ * The UK and Switzerland are not on it, matching builder.io.
+ */
+const CONSENT_REGION_COUNTRY_CODES = new Set([
+    "AT",
+    "AX",
+    "BE",
+    "BG",
+    "CY",
+    "CZ",
+    "DE",
+    "DK",
+    "EE",
+    "ES",
+    "FI",
+    "FR",
+    "GF",
+    "GP",
+    "GR",
+    "HR",
+    "HU",
+    "IE",
+    "IS",
+    "IT",
+    "LI",
+    "LT",
+    "LU",
+    "LV",
+    "MC",
+    "MF",
+    "MQ",
+    "MT",
+    "NL",
+    "NO",
+    "PL",
+    "PT",
+    "RE",
+    "RO",
+    "SE",
+    "SI",
+    "SK",
+    "SM",
+    "YT",
+]);
+/** The IANA zones of those countries, for a request with no country header. */
+const CONSENT_REGION_TIME_ZONES = new Set([
+    "Africa/Ceuta",
+    "America/Cayenne",
+    "America/Guadeloupe",
+    "America/Marigot",
+    "America/Martinique",
+    "Asia/Famagusta",
+    "Asia/Nicosia",
+    "Atlantic/Azores",
+    "Atlantic/Canary",
+    "Atlantic/Madeira",
+    "Atlantic/Reykjavik",
+    "Europe/Amsterdam",
+    "Europe/Athens",
+    "Europe/Berlin",
+    "Europe/Bratislava",
+    "Europe/Brussels",
+    "Europe/Bucharest",
+    "Europe/Budapest",
+    "Europe/Busingen",
+    "Europe/Copenhagen",
+    "Europe/Dublin",
+    "Europe/Helsinki",
+    "Europe/Lisbon",
+    "Europe/Ljubljana",
+    "Europe/Luxembourg",
+    "Europe/Madrid",
+    "Europe/Malta",
+    "Europe/Mariehamn",
+    "Europe/Monaco",
+    "Europe/Nicosia",
+    "Europe/Oslo",
+    "Europe/Paris",
+    "Europe/Prague",
+    "Europe/Riga",
+    "Europe/Rome",
+    "Europe/San_Marino",
+    "Europe/Sofia",
+    "Europe/Stockholm",
+    "Europe/Tallinn",
+    "Europe/Vaduz",
+    "Europe/Vienna",
+    "Europe/Vilnius",
+    "Europe/Warsaw",
+    "Europe/Zagreb",
+    "Indian/Mayotte",
+    "Indian/Reunion",
+    "CET",
+    "EET",
+    "Eire",
+    "Iceland",
+    "MET",
+    "Poland",
+    "Portugal",
+    "WET",
+]);
+/** For the inline bootstrap the server writes into each page. */
+export const CONSENT_REGION_TIME_ZONE_LIST = [
+    ...CONSENT_REGION_TIME_ZONES,
+];
+export function isConsentRegionCountry(code) {
+    return CONSENT_REGION_COUNTRY_CODES.has(code?.trim().toUpperCase() ?? "");
+}
+export function isConsentRegionTimeZone(timeZone) {
+    return !!timeZone && CONSENT_REGION_TIME_ZONES.has(timeZone);
+}
+export const CONSENT_COOKIE_NAME = "an_consent";
+/** Asked again a year later, like builder.io. */
+export const CONSENT_COOKIE_LIFETIME_SECONDS = 365 * 24 * 60 * 60;
+export const CONSENT_REGION_PATH = "/_agent-native/auth/consent-region";
+export const CONSENT_PATH = "/_agent-native/auth/consent";
+/**
+ * One choice covers the site and every app on agent-native.com. The browser
+ * and the server must agree, or the two copies become two cookies.
+ */
+export function consentCookieDomain(hostname) {
+    const host = hostname.toLowerCase();
+    return host === "agent-native.com" || host.endsWith(".agent-native.com")
+        ? "agent-native.com"
+        : null;
+}
+const CONSENT_COOKIE_VERSION = "1";
+/** `1.p1.t0`: version, then one flag per category. */
+export function serializeConsent(choice) {
+    return [
+        CONSENT_COOKIE_VERSION,
+        `p${choice.performance ? 1 : 0}`,
+        `t${choice.targeting ? 1 : 0}`,
+    ].join(".");
+}
+/** The stored choice, or `null` when there is none this version can read. */
+export function parseConsent(value) {
+    const match = /^1\.p([01])\.t([01])$/.exec(value?.trim() ?? "");
+    if (!match)
+        return null;
+    return { performance: match[1] === "1", targeting: match[2] === "1" };
+}

package/dist/shared/first-touch-persistence.d.ts

@@ -0,0 +1,31 @@
+import { type AttributionTouch } from "./attribution-source.js";
+/**
+ * The durable copy of first touch. Our server sets it, because Safari caps
+ * cookies written by page JavaScript at seven days; the browser's own `an_ft`
+ * cookie and localStorage copy stay the immediate, 30-day copies. Signup and
+ * the browser both pick between the copies with `preferFirstTouch`, so they
+ * agree on which visit is first touch.
+ */
+export declare const FIRST_TOUCH_SERVER_COOKIE_NAME = "an_fts";
+export declare const FIRST_TOUCH_SERVER_COOKIE_VERSION = "1";
+export declare const FIRST_TOUCH_SERVER_PATH = "/_agent-native/auth/attribution";
+/** Counted from the first visit, never extended by later ones. */
+export declare const FIRST_TOUCH_SERVER_LIFETIME_SECONDS: number;
+/** `name=value` budget, so this and the browser's cookies fit one header. */
+export declare const FIRST_TOUCH_SERVER_COOKIE_MAX_BYTES = 1500;
+export interface TimedFirstTouch extends AttributionTouch {
+    landed_at?: string;
+}
+/**
+ * Which of two records is first touch: the first visit that had a source,
+ * else the first visit. `incumbent` wins a tie, so a copy never displaces the
+ * value it came from.
+ */
+export declare function preferFirstTouch<T extends TimedFirstTouch>(incumbent: T | null | undefined, challenger: T | null | undefined): T | null;
+/** Whether two records are the same visit, however each copy was trimmed. */
+export declare function isSameFirstTouch(a: TimedFirstTouch | null | undefined, b: TimedFirstTouch | null | undefined): boolean;
+/**
+ * When the durable copy expires: a year after the visit, or `null` once that
+ * year is over. A missing or future visit time counts from now.
+ */
+export declare function firstTouchServerExpiry(touch: TimedFirstTouch, now?: number): Date | null;

package/dist/shared/first-touch-persistence.js

@@ -0,0 +1,53 @@
+import { hasAttributionSource, } from "./attribution-source.js";
+/**
+ * The durable copy of first touch. Our server sets it, because Safari caps
+ * cookies written by page JavaScript at seven days; the browser's own `an_ft`
+ * cookie and localStorage copy stay the immediate, 30-day copies. Signup and
+ * the browser both pick between the copies with `preferFirstTouch`, so they
+ * agree on which visit is first touch.
+ */
+export const FIRST_TOUCH_SERVER_COOKIE_NAME = "an_fts";
+export const FIRST_TOUCH_SERVER_COOKIE_VERSION = "1";
+export const FIRST_TOUCH_SERVER_PATH = "/_agent-native/auth/attribution";
+/** Counted from the first visit, never extended by later ones. */
+export const FIRST_TOUCH_SERVER_LIFETIME_SECONDS = 365 * 24 * 60 * 60;
+/** `name=value` budget, so this and the browser's cookies fit one header. */
+export const FIRST_TOUCH_SERVER_COOKIE_MAX_BYTES = 1500;
+// A record with no readable visit time was trimmed to fit its cookie, so it
+// was stored before any dated record it is compared with.
+function landedAtMs(touch) {
+    const time = Date.parse(touch.landed_at ?? "");
+    return Number.isFinite(time) ? time : Number.NEGATIVE_INFINITY;
+}
+/**
+ * Which of two records is first touch: the first visit that had a source,
+ * else the first visit. `incumbent` wins a tie, so a copy never displaces the
+ * value it came from.
+ */
+export function preferFirstTouch(incumbent, challenger) {
+    if (!incumbent)
+        return challenger ?? null;
+    if (!challenger)
+        return incumbent;
+    const incumbentSourced = hasAttributionSource(incumbent);
+    if (incumbentSourced !== hasAttributionSource(challenger)) {
+        return incumbentSourced ? incumbent : challenger;
+    }
+    return landedAtMs(challenger) < landedAtMs(incumbent)
+        ? challenger
+        : incumbent;
+}
+/** Whether two records are the same visit, however each copy was trimmed. */
+export function isSameFirstTouch(a, b) {
+    return !!a?.landed_at && a.landed_at === b?.landed_at;
+}
+/**
+ * When the durable copy expires: a year after the visit, or `null` once that
+ * year is over. A missing or future visit time counts from now.
+ */
+export function firstTouchServerExpiry(touch, now = Date.now()) {
+    const landed = Date.parse(touch.landed_at ?? "");
+    const start = Number.isFinite(landed) && landed <= now ? landed : now;
+    const expires = start + FIRST_TOUCH_SERVER_LIFETIME_SECONDS * 1000;
+    return expires > now ? new Date(expires) : null;
+}

package/dist/sharing/actions/set-resource-visibility.js

@@ -29,6 +29,11 @@ export default defineAction({
         const access = await assertAccess(args.resourceType, args.resourceId, "admin", undefined, { skipResourceBody: true });
         return access.resource.visibility !== "public";
     },
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: true,
+    },
     run: async (args, ctx) => {
         assertWidgetShareWriteGrant(ctx, "set-resource-visibility", args);
         const reg = requireShareableResource(args.resourceType);

package/dist/sharing/actions/share-resource.js

@@ -124,6 +124,11 @@ export default defineAction({
             .describe("Optional short note included in the notification email to an individual recipient."),
     }),
     needsApproval: needsExternalShareApproval,
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: true,
+    },
     run: async (args, ctx) => {
         assertWidgetShareWriteGrant(ctx, "share-resource", args);
         const reg = requireShareableResource(args.resourceType);

package/dist/sharing/actions/unshare-resource.js

@@ -26,6 +26,11 @@ export default defineAction({
         principalType: z.enum(["user", "group", "org"]),
         principalId: z.string(),
     }),
+    mcpAnnotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
     run: async (args, ctx) => {
         assertWidgetShareWriteGrant(ctx, "unshare-resource", args);
         const reg = requireShareableResource(args.resourceType);

package/dist/templates/chat/.agents/skills/actions/references/action-fields.md

@@ -140,6 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
-Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other direct HTTP caller (bearer or API key, MCP OAuth token, org service token, extension iframe, or mobile app) gets `409 approval_required`, and a service identity can never approve. A2A tasks use their separate approval flow. The task pauses until its owner approves, then replays the approved tool call under its approval lease. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. The agent loop, plan mode registry, HTTP action route, generated Workers entry, and MCP dispatch evaluate the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat it as a local development tool, not an approval boundary. A caller that must run unattended needs a different action, never a bypass of the gate.
 
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/dist/templates/default/.agents/skills/actions/references/action-fields.md

@@ -140,6 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
-Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other direct HTTP caller (bearer or API key, MCP OAuth token, org service token, extension iframe, or mobile app) gets `409 approval_required`, and a service identity can never approve. A2A tasks use their separate approval flow. The task pauses until its owner approves, then replays the approved tool call under its approval lease. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. The agent loop, plan mode registry, HTTP action route, generated Workers entry, and MCP dispatch evaluate the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat it as a local development tool, not an approval boundary. A caller that must run unattended needs a different action, never a bypass of the gate.
 
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.