@agent-native/core 0.169.1 → 0.170.0

package/dist/server/workspace-provider-oauth.js

@@ -13,7 +13,12 @@ import { decodeOAuthState, encodeOAuthState, getAppUrl, resolveOAuthRedirectUri,
 import { runWithRequestContext } from "./request-context.js";
 const SUPPORTED_PROVIDERS = new Set([
     "figma",
+    "gmail",
+    "google_calendar",
+    "google_docs",
     "google_drive",
+    "google_sheets",
+    "google_slides",
     "github",
     "hubspot",
     "salesforce",
@@ -26,7 +31,22 @@ const PROVIDER_REQUEST_TIMEOUT_MS = 10_000;
 const PROVIDER_RESPONSE_MAX_BYTES = 256 * 1024;
 const SALESFORCE_PRODUCTION_LOGIN_URL = "https://login.salesforce.com";
 const SALESFORCE_SANDBOX_LOGIN_URL = "https://test.salesforce.com";
-const WORKSPACE_OAUTH_ADMIN_ERROR = "Only organization admins or the relevant app admin can connect shared OAuth accounts.";
+const WORKSPACE_OAUTH_ADMIN_ERROR = "This shared connection requires organization or app-admin access. Personal connections can be connected by any workspace member.";
+export function isWorkspaceProviderOAuthScope(value) {
+    return value === "user" || value === "organization" || value === "app";
+}
+export function isGoogleWorkspaceOAuthProvider(provider) {
+    return (provider === "gmail" ||
+        provider === "google_calendar" ||
+        provider === "google_docs" ||
+        provider === "google_drive" ||
+        provider === "google_sheets" ||
+        provider === "google_slides");
+}
+export async function hasWorkspaceProviderOAuthCredentials(provider) {
+    const [clientId, clientSecret] = await resolveProviderClientCredentials(provider);
+    return Boolean(clientId && clientSecret);
+}
 export function workspaceProviderOAuthPath(provider, phase) {
     return `/_agent-native/connections/oauth/${provider}/${phase}`;
 }
@@ -46,7 +66,14 @@ export async function handleWorkspaceProviderOAuthStart(event, providerId) {
         return unauthorized(event);
     const query = getQuery(event);
     const appId = normalizeAppId(text(query.appId) ?? getAppConfig().app.workspaceId ?? "creative-context");
-    const orgContext = await requireWorkspaceProviderOAuthAdmin(event, appId);
+    const requestedScope = parseWorkspaceProviderOAuthScope(text(query.scope));
+    if (!requestedScope) {
+        setResponseStatus(event, 400);
+        return {
+            error: "OAuth connection scope must be user, organization, or app.",
+        };
+    }
+    const orgContext = await requireWorkspaceProviderOAuthAccess(event, appId, requestedScope);
     if (!orgContext) {
         return { error: WORKSPACE_OAUTH_ADMIN_ERROR };
     }
@@ -91,6 +118,7 @@ export async function handleWorkspaceProviderOAuthStart(event, providerId) {
             owner: session.email,
             orgId,
             app: appId,
+            scope: orgContext.oauthScope,
             returnUrl,
             flowId,
         });
@@ -102,6 +130,7 @@ export async function handleWorkspaceProviderOAuthStart(event, providerId) {
             owner: session.email,
             orgId,
             appId,
+            scope: orgContext.oauthScope,
             ...(salesforceLoginUrl ? { salesforceLoginUrl } : {}),
             expiresAt: Date.now() + FLOW_TTL_SECONDS * 1_000,
         };
@@ -134,7 +163,11 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
     if (!session?.email)
         return unauthorized(event);
     const flow = readStoredFlow(event, providerId);
-    const orgContext = await requireWorkspaceProviderOAuthAdmin(event, flow?.appId);
+    if (!flow || !isWorkspaceProviderOAuthScope(flow.scope)) {
+        setResponseStatus(event, 400);
+        return { error: "OAuth state is invalid or expired." };
+    }
+    const orgContext = await requireWorkspaceProviderOAuthAccess(event, flow.appId, flow.scope);
     if (!orgContext) {
         return { error: WORKSPACE_OAUTH_ADMIN_ERROR };
     }
@@ -204,8 +237,12 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
             await saveOAuthTokens(provider.oauth.provider, accountId, tokens, session.email);
             await setOAuthDisplayName(provider.oauth.provider, accountId, identity.label);
             const existing = existingConnections.find((connection) => connection.accountId === accountId &&
-                (orgContext.oauthScope === "organization" ||
-                    connection.allowedApps.some((allowedApp) => allowedApp.toLowerCase() === flow.appId.toLowerCase())));
+                (flow.scope === "user"
+                    ? connection.allowedUsers.some((allowedUser) => allowedUser.toLowerCase() === session.email.toLowerCase())
+                    : flow.scope === "organization"
+                        ? connection.allowedUsers.length === 0 &&
+                            (connection.allowedUserGroups?.length ?? 0) === 0
+                        : connection.allowedApps.some((allowedApp) => allowedApp.toLowerCase() === flow.appId.toLowerCase())));
             const scopes = mergeWorkspaceOAuthValues(existing?.scopes ?? [], identity.scopes ?? tokenScopes(tokens, provider.oauth.scopes));
             const connectionConfig = {
                 credentialMode: "oauth",
@@ -229,8 +266,10 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
                 accountLabel: identity.label,
                 status: "connected",
                 scopes,
-                allowedApps: existing?.allowedApps ??
-                    (orgContext.oauthScope === "app" ? [flow.appId] : []),
+                allowedApps: existing?.allowedApps ?? (flow.scope === "app" ? [flow.appId] : []),
+                allowedUsers: flow.scope === "user"
+                    ? [session.email]
+                    : (existing?.allowedUsers ?? []),
                 config: connectionConfig,
                 lastCheckedAt: new Date(),
                 lastError: null,
@@ -267,7 +306,7 @@ export function buildWorkspaceProviderAuthorizationUrl(input) {
         url.searchParams.set("audience", "api.atlassian.com");
         url.searchParams.set("prompt", "consent");
     }
-    if (input.provider.id === "google_drive") {
+    if (isGoogleWorkspaceOAuthProvider(input.provider.id)) {
         url.searchParams.set("access_type", "offline");
         url.searchParams.set("include_granted_scopes", "true");
         url.searchParams.set("prompt", "consent");
@@ -393,7 +432,7 @@ export async function exchangeWorkspaceProviderOAuthCode(input) {
         ...(input.providerId === "sentry"
             ? { client_id: input.clientId, client_secret: input.clientSecret }
             : {}),
-        ...(input.providerId === "google_drive"
+        ...(isGoogleWorkspaceOAuthProvider(input.providerId)
             ? { client_id: input.clientId, client_secret: input.clientSecret }
             : {}),
     };
@@ -566,19 +605,16 @@ async function resolveWorkspaceProviderIdentitySingle(providerId, tokens) {
             label: text(user?.email) ?? text(user?.name) ?? "Sentry account",
         };
     }
-    if (providerId === "google_drive") {
+    if (isGoogleWorkspaceOAuthProvider(providerId)) {
         const accessToken = text(tokens.access_token);
-        const { response, body } = await fetchBoundedProviderJson("https://www.googleapis.com/drive/v3/about?fields=user(displayName,emailAddress,permissionId)", { headers: { Authorization: `Bearer ${accessToken}` } }, "Google Drive");
-        const user = record(body.user);
-        const accountId = text(user?.permissionId) ?? text(user?.emailAddress);
+        const { response, body } = await fetchBoundedProviderJson("https://openidconnect.googleapis.com/v1/userinfo", { headers: { Authorization: `Bearer ${accessToken}` } }, "Google Workspace");
+        const accountId = text(body.email) ?? text(body.sub);
         if (!response.ok || !accountId) {
-            throw new Error("Google Drive OAuth response did not identify the connected account.");
+            throw new Error("Google OAuth response did not identify the connected account.");
         }
         return {
             accountId,
-            label: text(user?.emailAddress) ??
-                text(user?.displayName) ??
-                "Google Drive account",
+            label: text(body.email) ?? text(body.name) ?? "Google account",
         };
     }
     const accessToken = text(tokens.access_token);
@@ -615,6 +651,7 @@ export function isWorkspaceProviderOAuthFlowValid(input) {
         input.state.flowId === input.flow.flowId &&
         input.state.redirectUri === input.flow.redirectUri &&
         input.state.owner === input.flow.owner &&
+        input.state.scope === input.flow.scope &&
         input.sessionEmail === input.flow.owner &&
         input.state.orgId === input.flow.orgId &&
         input.sessionOrgId === input.flow.orgId &&
@@ -697,7 +734,9 @@ export function mergeWorkspaceOAuthValues(existing, incoming) {
     return [...new Set([...existing, ...incoming])];
 }
 function clientCredentialKeys(provider, field) {
-    const prefix = provider === "google_drive" ? "GOOGLE" : provider.toUpperCase();
+    const prefix = isGoogleWorkspaceOAuthProvider(provider)
+        ? "GOOGLE"
+        : provider.toUpperCase();
     const suffix = field === "id" ? "ID" : "SECRET";
     if (provider === "github") {
         const integrationPrefix = `GITHUB_INTEGRATION_CLIENT_${suffix}`;
@@ -799,6 +838,11 @@ function normalizeAppId(value) {
 function text(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+function parseWorkspaceProviderOAuthScope(value) {
+    if (value === undefined)
+        return "organization";
+    return isWorkspaceProviderOAuthScope(value) ? value : null;
+}
 function scalarText(value) {
     if (typeof value === "number" && Number.isFinite(value))
         return String(value);
@@ -817,15 +861,23 @@ function unauthorized(event) {
     setResponseStatus(event, 401);
     return { error: "Authentication required" };
 }
-async function requireWorkspaceProviderOAuthAdmin(event, appId) {
+async function requireWorkspaceProviderOAuthAccess(event, appId, requestedScope = "organization") {
     const context = await getOrgContext(event).catch(() => null);
     if (!context || !context.orgId) {
         setResponseStatus(event, 403);
         return null;
     }
-    if (canConnectWorkspaceProviderOAuth(context.orgId, context.role)) {
+    if (requestedScope === "user") {
+        return { ...context, oauthScope: "user" };
+    }
+    if (requestedScope === "organization" &&
+        canConnectWorkspaceProviderOAuth(context.orgId, context.role)) {
         return { ...context, oauthScope: "organization" };
     }
+    if (requestedScope === "app" &&
+        canConnectWorkspaceProviderOAuth(context.orgId, context.role)) {
+        return { ...context, oauthScope: "app" };
+    }
     if (appId) {
         const descriptor = getRegisteredAppRoles(appId);
         if (descriptor?.roles.some((role) => role === "admin")) {

package/dist/shared/agent-sidebar-url.d.ts

@@ -1,5 +1,6 @@
 export declare const AGENT_NATIVE_OPEN_PATH = "/_agent-native/open";
 export declare const AGENT_SIDEBAR_QUERY_PARAM = "agentSidebar";
 export declare const AGENT_SIDEBAR_QUERY_VALUE_CLOSED = "closed";
+export declare const AGENT_SIDEBAR_QUERY_VALUE_OPEN = "open";
 export declare function isAgentNativeOpenDeepLink(urlOrPath: string): boolean;
 export declare function withCollapsedAgentSidebarParam(urlOrPath: string): string;

package/dist/shared/agent-sidebar-url.js

@@ -1,6 +1,7 @@
 export const AGENT_NATIVE_OPEN_PATH = "/_agent-native/open";
 export const AGENT_SIDEBAR_QUERY_PARAM = "agentSidebar";
 export const AGENT_SIDEBAR_QUERY_VALUE_CLOSED = "closed";
+export const AGENT_SIDEBAR_QUERY_VALUE_OPEN = "open";
 const RELATIVE_URL_BASE = "http://agent-native.invalid";
 function hasUrlScheme(urlOrPath) {
     return /^[a-z][a-z0-9+.-]*:/i.test(urlOrPath);

package/dist/shared/environment-lanes.d.ts

@@ -1,6 +1,8 @@
 export declare const BETA_OPT_OUT_QUERY_PARAM = "agentNativeBetaOptOut";
 export declare const BETA_OPT_OUT_DURATION_MS: number;
 export declare const BETA_OPT_OUT_STORAGE_KEY = "agent-native:beta-opt-out-until";
+export declare const BETA_FORCE_QUERY_PARAM = "force";
+export declare const BETA_FORCE_SESSION_STORAGE_KEY = "agent-native:force-production";
 export declare const ENVIRONMENT_BETA_HOSTS: {
     readonly "agent-workspace.builder.io": "beta.agent-workspace.builder.io";
     readonly "analytics.agent-native.com": "beta.analytics.agent-native.com";

package/dist/shared/environment-lanes.js

@@ -1,6 +1,8 @@
 export const BETA_OPT_OUT_QUERY_PARAM = "agentNativeBetaOptOut";
-export const BETA_OPT_OUT_DURATION_MS = 24 * 60 * 60 * 1000;
+export const BETA_OPT_OUT_DURATION_MS = 8 * 60 * 60 * 1000;
 export const BETA_OPT_OUT_STORAGE_KEY = "agent-native:beta-opt-out-until";
+export const BETA_FORCE_QUERY_PARAM = "force";
+export const BETA_FORCE_SESSION_STORAGE_KEY = "agent-native:force-production";
 export const ENVIRONMENT_BETA_HOSTS = {
     "agent-workspace.builder.io": "beta.agent-workspace.builder.io",
     "analytics.agent-native.com": "beta.analytics.agent-native.com",

package/dist/shared/index.d.ts

@@ -6,13 +6,15 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { BETA_FORCE_QUERY_PARAM, BETA_FORCE_SESSION_STORAGE_KEY, BETA_OPT_OUT_DURATION_MS, BETA_OPT_OUT_QUERY_PARAM, BETA_OPT_OUT_STORAGE_KEY, ENVIRONMENT_BETA_HOSTS, resolveEnvironmentTargets, type EnvironmentBadgeTargets, } from "./environment-lanes.js";
 export { SSR_HTML_CONTENT_TYPE, SSR_QUERY_CACHE_KEY_HEADER, type SsrHtmlContentTypeOptions, withSsrHtmlContentType, } from "./cache-control.js";
+export { SURFACE_HIDDEN_FLAG, SURFACE_VISIBILITY_EVENT, addSurfaceVisibilityListener, buildSurfaceVisibilityScript, isHostSurfaceHidden, isSurfaceHidden, } from "./surface-visibility.js";
 export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, type DocsUrlOptions, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, type RuntimeConfigEnvironment, type RuntimeConfigIssue, type RuntimeConfigIssueCode, type RuntimeConfigIssueSeverity, type RuntimeConfigPhase, type RuntimeConfigReport, type RuntimeConfigRequirements, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, type LlmConnectionStatus, } from "./llm-connection.js";
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, normalizeWorkspaceAppId, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, type WorkspaceAppRouteAccess, type WorkspaceAppRouteAccessFromConfig, type WorkspaceAppAudience, } from "./workspace-app-audience.js";
-export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, AGENT_SIDEBAR_QUERY_VALUE_OPEN, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
 export { buildChatFirstAppCreationPrompt, titleFromChatFirstAppPrompt, type ChatFirstAppCreationPromptInput, type ChatFirstAppCreationResource, type ChatFirstAppCreationVaultAccessMode, } from "./chat-first-app-creation.js";
 export { NATIVE_AUTH_COPY, resolveNativeAuthCopy, type NativeAuthCopy, } from "./auth-copy.js";
 export { createPollEngine, type PollEngineOptions, type PollEngineHandle, } from "./poll-engine.js";

package/dist/shared/index.js

@@ -6,13 +6,15 @@ export { truncate } from "./truncate.js";
 export { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "./document-title.js";
 export { injectDocumentMarkup } from "./html-document.js";
 export { withBuilderUtmTrackingParams } from "./builder-link-tracking.js";
+export { BETA_FORCE_QUERY_PARAM, BETA_FORCE_SESSION_STORAGE_KEY, BETA_OPT_OUT_DURATION_MS, BETA_OPT_OUT_QUERY_PARAM, BETA_OPT_OUT_STORAGE_KEY, ENVIRONMENT_BETA_HOSTS, resolveEnvironmentTargets, } from "./environment-lanes.js";
 export { SSR_HTML_CONTENT_TYPE, SSR_QUERY_CACHE_KEY_HEADER, withSsrHtmlContentType, } from "./cache-control.js";
+export { SURFACE_HIDDEN_FLAG, SURFACE_VISIBILITY_EVENT, addSurfaceVisibilityListener, buildSurfaceVisibilityScript, isHostSurfaceHidden, isSurfaceHidden, } from "./surface-visibility.js";
 export { AGENT_NATIVE_DOCS_ORIGIN, docsUrl, } from "./docs-url.js";
 export { buildRuntimeConfigPrompt, formatRuntimeConfigReport, getRuntimeConfigReport, parseRuntimeConfigReport, runtimeConfigRequirementsFromSearchParams, } from "./runtime-config.js";
 export { llmConnectionTrackingProperties, normalizeLlmConnection, } from "./llm-connection.js";
 export { DISPATCH_WORKSPACE_ROOT_REDIRECTS, RESERVED_WORKSPACE_APP_IDS, assertValidWorkspaceAppId, getWorkspaceAppIdValidationError, isValidWorkspaceAppIdFormat, normalizeWorkspaceAppId, } from "./workspace-app-id.js";
 export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromEnv, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromEnv, workspaceAppRouteAccessFromPackageJson, } from "./workspace-app-audience.js";
-export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
+export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, AGENT_SIDEBAR_QUERY_VALUE_OPEN, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
 export { buildChatFirstAppCreationPrompt, titleFromChatFirstAppPrompt, } from "./chat-first-app-creation.js";
 export { NATIVE_AUTH_COPY, resolveNativeAuthCopy, } from "./auth-copy.js";
 export { createPollEngine, } from "./poll-engine.js";

package/dist/shared/surface-visibility.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Host-declared surface visibility.
+ *
+ * An Electron `<webview>` guest never reports itself hidden: hiding the element
+ * or any ancestor leaves `document.visibilityState === "visible"` and never
+ * fires `visibilitychange`, so every visibility-based pause in this package is
+ * inert inside the desktop shell. A backgrounded app tab there keeps polling at
+ * its full foreground cadence and holds its event stream open for as long as
+ * the shell is running. The host therefore has to say so explicitly, and this
+ * flag is what background work must consult instead of the document alone.
+ */
+export declare const SURFACE_HIDDEN_FLAG = "__agentNativeSurfaceHidden";
+/** Dispatched on `window` whenever the host flips the flag. */
+export declare const SURFACE_VISIBILITY_EVENT = "agentnative:surfacevisibilitychange";
+/** Whether an embedding host has declared this surface off screen. */
+export declare function isHostSurfaceHidden(): boolean;
+/**
+ * Whether this surface is off screen by either signal. A host that has stashed
+ * the surface entirely is a stronger statement than a backgrounded browser tab,
+ * so callers that keep working while merely backgrounded should still stop on
+ * `isHostSurfaceHidden()`.
+ */
+export declare function isSurfaceHidden(): boolean;
+/** Subscribe to both visibility signals. Returns an unsubscribe function. */
+export declare function addSurfaceVisibilityListener(handler: () => void): () => void;
+/**
+ * Script a host embedder evaluates inside the guest to declare whether the
+ * surface it is hosting is on screen. Kept here so the flag name, the event
+ * name, and the write that sets them cannot drift apart across packages.
+ */
+export declare function buildSurfaceVisibilityScript(hidden: boolean): string;

package/dist/shared/surface-visibility.js

@@ -0,0 +1,57 @@
+/**
+ * Host-declared surface visibility.
+ *
+ * An Electron `<webview>` guest never reports itself hidden: hiding the element
+ * or any ancestor leaves `document.visibilityState === "visible"` and never
+ * fires `visibilitychange`, so every visibility-based pause in this package is
+ * inert inside the desktop shell. A backgrounded app tab there keeps polling at
+ * its full foreground cadence and holds its event stream open for as long as
+ * the shell is running. The host therefore has to say so explicitly, and this
+ * flag is what background work must consult instead of the document alone.
+ */
+export const SURFACE_HIDDEN_FLAG = "__agentNativeSurfaceHidden";
+/** Dispatched on `window` whenever the host flips the flag. */
+export const SURFACE_VISIBILITY_EVENT = "agentnative:surfacevisibilitychange";
+/** Whether an embedding host has declared this surface off screen. */
+export function isHostSurfaceHidden() {
+    if (typeof window === "undefined")
+        return false;
+    return (window[SURFACE_HIDDEN_FLAG] === true);
+}
+/**
+ * Whether this surface is off screen by either signal. A host that has stashed
+ * the surface entirely is a stronger statement than a backgrounded browser tab,
+ * so callers that keep working while merely backgrounded should still stop on
+ * `isHostSurfaceHidden()`.
+ */
+export function isSurfaceHidden() {
+    if (isHostSurfaceHidden())
+        return true;
+    return (typeof document !== "undefined" && document.visibilityState === "hidden");
+}
+/** Subscribe to both visibility signals. Returns an unsubscribe function. */
+export function addSurfaceVisibilityListener(handler) {
+    if (typeof document === "undefined" || typeof window === "undefined") {
+        return () => { };
+    }
+    document.addEventListener("visibilitychange", handler);
+    window.addEventListener(SURFACE_VISIBILITY_EVENT, handler);
+    return () => {
+        document.removeEventListener("visibilitychange", handler);
+        window.removeEventListener(SURFACE_VISIBILITY_EVENT, handler);
+    };
+}
+/**
+ * Script a host embedder evaluates inside the guest to declare whether the
+ * surface it is hosting is on screen. Kept here so the flag name, the event
+ * name, and the write that sets them cannot drift apart across packages.
+ */
+export function buildSurfaceVisibilityScript(hidden) {
+    return `(() => {
+  const next = ${hidden ? "true" : "false"};
+  if (window[${JSON.stringify(SURFACE_HIDDEN_FLAG)}] === next) return next;
+  window[${JSON.stringify(SURFACE_HIDDEN_FLAG)}] = next;
+  window.dispatchEvent(new Event(${JSON.stringify(SURFACE_VISIBILITY_EVENT)}));
+  return next;
+})()`;
+}

package/dist/templates/chat/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/templates/chat/app/routes.ts

@@ -1,4 +1,6 @@
 import { type RouteConfig } from "@react-router/dev/routes";
 import { flatRoutes } from "@react-router/fs-routes";
 
-export default flatRoutes() satisfies RouteConfig;
+export default flatRoutes({
+  ignoredRouteFiles: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+}) satisfies RouteConfig;

package/dist/templates/chat/vitest.config.ts

@@ -11,4 +11,12 @@ export default defineConfig({
       "@shared": path.resolve(__dirname, "./shared"),
     },
   },
+  test: {
+    exclude: [
+      "**/node_modules/**",
+      "**/.git/**",
+      "**/dist/**",
+      "**/.react-router/**",
+    ],
+  },
 });

package/dist/templates/default/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/templates/default/app/routes.ts

@@ -1,4 +1,6 @@
 import { type RouteConfig } from "@react-router/dev/routes";
 import { flatRoutes } from "@react-router/fs-routes";
 
-export default flatRoutes() satisfies RouteConfig;
+export default flatRoutes({
+  ignoredRouteFiles: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+}) satisfies RouteConfig;

package/dist/templates/headless/.agents/skills/secrets/SKILL.md

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

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

@@ -19,10 +19,17 @@ data, and generated extension/app content may mention credential **names** such
 as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
 signing secrets, OAuth refresh tokens, or private Builder/customer data.
 
-Secret values are supplied at runtime through deployment configuration, the
-encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
-`${keys.NAME}` substitution. Examples must use obvious placeholders such as
-`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+Provider secret values are supplied at runtime through the encrypted
+`app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Deployment configuration is reserved for
+deploy-level secrets and non-provider configuration. Examples must use obvious
+placeholders such as `<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not
+real-looking copied values.
+
+Provider credentials and provider account identifiers are workspace data. Use
+standard workspace connections and org/workspace vault scopes; never put them
+in `.env` or deployment environment variables, and never add a provider-specific
+action or startup bootstrap just to write a credential for one organization.
 
 ## Credential Modeling Preflight
 

package/dist/tracking/registry.d.ts

@@ -8,6 +8,17 @@ export interface TrackingMeta {
     anonymousId?: string;
     /** Overrides the ambient request's browser session. */
     sessionId?: string;
+    /**
+     * When the event actually happened, in epoch ms. Defaults to now.
+     *
+     * Needed by callers that buffer and flush a batch of events at the end of a
+     * unit of work — an agent run emits its trace, generation, and tool spans in
+     * one burst, and stamping all of them with the flush time collapses a
+     * multi-second waterfall into a single instant. PostHog orders an LLM trace
+     * tree by event timestamp, so without this the tree renders with a synthetic
+     * timeline.
+     */
+    occurredAt?: number;
 }
 /**
  * Who an event is attributed to. Pass an action's `ctx` straight through —

package/dist/tracking/registry.js

@@ -42,10 +42,11 @@ function resolveTrackingSource(source) {
         userId: source.userId,
         anonymousId: source.anonymousId,
         sessionId: source.sessionId ?? ambientSessionId,
+        occurredAt: source.occurredAt,
     };
 }
 export function track(name, properties, source) {
-    const { userId, anonymousId, sessionId } = resolveTrackingSource(source);
+    const { userId, anonymousId, sessionId, occurredAt } = resolveTrackingSource(source);
     const clientPlatform = getRequestContext()?.clientPlatform;
     const trackedProperties = {
         ...(properties ?? {}),
@@ -57,7 +58,9 @@ export function track(name, properties, source) {
     const event = {
         name,
         properties: trackedProperties,
-        timestamp: new Date().toISOString(),
+        // A caller-supplied `occurredAt` of 0 is not a real event time, so `||`
+        // rather than `??` is deliberate here.
+        timestamp: new Date(occurredAt || Date.now()).toISOString(),
         userId,
         anonymousId,
         sessionId,

package/dist/triggers/actions.js

@@ -301,12 +301,15 @@ async function handleRunNow(args, getCurrentUser, appId, context) {
         return "Error: an automation cannot run another automation.";
     }
     try {
+        const path = typeof args.path === "string" ? args.path.trim() : "";
+        const name = typeof args.name === "string" ? args.name : "";
         const result = await queueAutomationRunNow({
             userEmail: getCurrentUser(),
             orgId: getRequestOrgId(),
             appId,
             scope: automationScope(args.scope),
-            name: typeof args.name === "string" ? args.name : "",
+            ...(path ? { path } : { name }),
+            requestHeaders: context?.requestHeaders,
         });
         return JSON.stringify(result);
     }
@@ -340,7 +343,7 @@ export function createAutomationToolEntries(getCurrentUser, appId) {
 - **update**: Update an existing automation's settings without changing its creator (enabled, schedule, timezone, condition, body, policy, model, execution host, MCP allowlist). Required param: name. Use the same scope it was created in.
 - **delete**: Delete an automation. Always confirm with the user first. Required param: name.
 - **fire-test**: Fire a test event to validate automations. Emits a test.event.fired event. Optional param: data (JSON string).
-- **run-now**: Run one automation immediately using its real actions and side effects. This is an explicit user-authorized run and returns a durable run id; it does not change the automation's next scheduled run. Required params: name; optional scope.`,
+- **run-now**: Run one automation immediately using its real actions and side effects. This is an explicit user-authorized run and returns a durable run id; it does not change the automation's next scheduled run. Required params: name or path (not both); optional scope. Use path for automations nested under jobs/ (for example jobs/factories/<id>/factory-slack-feedback.md); those names contain a slash and cannot round-trip through name.`,
                 parameters: {
                     type: "object",
                     properties: {
@@ -351,7 +354,11 @@ export function createAutomationToolEntries(getCurrentUser, appId) {
                         },
                         name: {
                             type: "string",
-                            description: "Slug name for the automation (lowercase, hyphens). Used by define, update, delete, and run-now.",
+                            description: "Slug name for the automation (lowercase, hyphens). Used by define, update, delete, and run-now for flat automations. For nested automations, pass path to run-now instead.",
+                        },
+                        path: {
+                            type: "string",
+                            description: "Full jobs resource path (jobs/...md) for a nested automation. Use with run-now instead of name when the automation name contains a slash.",
                         },
                         scope: {
                             type: "string",

package/dist/usage/store.js

@@ -207,6 +207,17 @@ export async function ensureUsageTable() {
                 // Probe pg_indexes first (no lock) and skip the SHARE-locking CREATE
                 // INDEX when the index is already present.
                 await ensureIndexExists("idx_token_usage_owner_created", `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`);
+                // `owner_email` is written as the caller supplied it, so the metrics
+                // queries scope with `LOWER(owner_email) IN (…)`. A plain btree cannot
+                // serve a function-wrapped predicate: without this expression index the
+                // usage panel scans the whole table, which is the highest-row-count one
+                // in the system (a row per LLM call, every app and org).
+                // NOT built CONCURRENTLY. This runs at release over the pooled Neon
+                // endpoint, and a transaction-pooled connection cannot carry
+                // `CREATE INDEX CONCURRENTLY` to completion — it returns without
+                // creating the index, which then fails the verifying probe and blocks
+                // the whole release. The SHARE lock is the cost of a build that lands.
+                await ensureIndexExists("idx_token_usage_lower_owner_created", `CREATE INDEX IF NOT EXISTS idx_token_usage_lower_owner_created ON token_usage (LOWER(owner_email), created_at)`);
                 return;
             }
             // SQLite (local dev): no lock problem — keep the original behaviour.
@@ -226,10 +237,19 @@ export async function ensureUsageTable() {
             // the `Date.now()` written per run by recordUsage() overflows int4. Widen
             // it in place (no-op once done / on fresh BIGINT databases).
             await widenIntColumnsToBigInt("token_usage", ["created_at"]);
-            try {
-                await client.execute(`CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`);
+            for (const ddl of [
+                `CREATE INDEX IF NOT EXISTS idx_token_usage_owner_created ON token_usage (owner_email, created_at)`,
+                `CREATE INDEX IF NOT EXISTS idx_token_usage_lower_owner_created ON token_usage (LOWER(owner_email), created_at)`,
+            ]) {
+                try {
+                    await client.execute(ddl);
+                }
+                catch {
+                    // coercion-ok: index already exists, or this dialect rejected the
+                    // duplicate. Local-dev SQLite only — the hosted path creates these
+                    // through the Postgres branch above, which probes before creating.
+                }
             }
-            catch { }
         })().catch((err) => {
             // Retry init on the next call after a failed startup.
             _initPromise = undefined;