@agent-native/core 0.152.0 → 0.153.0

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

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import { deleteCookie, defineEventHandler, getCookie, getMethod, getQuery, setCookie, setResponseStatus, } from "h3";
 import { getWorkspaceConnectionProvider, } from "../connections/catalog.js";
 import { saveOAuthTokens, setOAuthDisplayName } from "../oauth-tokens/store.js";
+import { getRegisteredAppRoles, resolveAppRole } from "../org/app-roles.js";
 import { getOrgContext } from "../org/context.js";
 import { decryptSecretValue, encryptSecretValue } from "../secrets/crypto.js";
 import { listWorkspaceConnections, upsertWorkspaceConnection, upsertWorkspaceConnectionGrant, } from "../workspace-connections/store.js";
@@ -24,6 +25,7 @@ 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.";
 export function workspaceProviderOAuthPath(provider, phase) {
     return `/_agent-native/connections/oauth/${provider}/${phase}`;
 }
@@ -41,21 +43,21 @@ export async function handleWorkspaceProviderOAuthStart(event, providerId) {
     const session = await getSession(event).catch(() => null);
     if (!session?.email)
         return unauthorized(event);
-    const orgContext = await requireWorkspaceProviderOAuthAdmin(event);
+    const query = getQuery(event);
+    const appId = normalizeAppId(text(query.appId) ??
+        process.env.AGENT_NATIVE_WORKSPACE_APP_ID ??
+        process.env.VITE_AGENT_NATIVE_WORKSPACE_APP_ID ??
+        "creative-context");
+    const orgContext = await requireWorkspaceProviderOAuthAdmin(event, appId);
     if (!orgContext) {
-        return {
-            error: "Only organization owners and admins can connect shared OAuth accounts.",
-        };
+        return { error: WORKSPACE_OAUTH_ADMIN_ERROR };
     }
     const orgId = orgContext.orgId;
     if (!orgId) {
         setResponseStatus(event, 403);
-        return {
-            error: "Only organization owners and admins can connect shared OAuth accounts.",
-        };
+        return { error: WORKSPACE_OAUTH_ADMIN_ERROR };
     }
     const provider = requiredProvider(providerId);
-    const query = getQuery(event);
     const salesforceLoginUrl = providerId === "salesforce"
         ? resolveSalesforceOAuthLoginUrl(text(query.environment))
         : undefined;
@@ -63,10 +65,6 @@ export async function handleWorkspaceProviderOAuthStart(event, providerId) {
         setResponseStatus(event, 400);
         return { error: "Salesforce environment must be production or sandbox." };
     }
-    const appId = normalizeAppId(text(query.appId) ??
-        process.env.AGENT_NATIVE_WORKSPACE_APP_ID ??
-        process.env.VITE_AGENT_NATIVE_WORKSPACE_APP_ID ??
-        "creative-context");
     const redirectUri = resolveOAuthRedirectUri(event, workspaceProviderOAuthPath(providerId, "callback"));
     if (!redirectUri) {
         setResponseStatus(event, 400);
@@ -137,18 +135,15 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
     const session = await getSession(event).catch(() => null);
     if (!session?.email)
         return unauthorized(event);
-    const orgContext = await requireWorkspaceProviderOAuthAdmin(event);
+    const flow = readStoredFlow(event, providerId);
+    const orgContext = await requireWorkspaceProviderOAuthAdmin(event, flow?.appId);
     if (!orgContext) {
-        return {
-            error: "Only organization owners and admins can connect shared OAuth accounts.",
-        };
+        return { error: WORKSPACE_OAUTH_ADMIN_ERROR };
     }
     const orgId = orgContext.orgId;
     if (!orgId) {
         setResponseStatus(event, 403);
-        return {
-            error: "Only organization owners and admins can connect shared OAuth accounts.",
-        };
+        return { error: WORKSPACE_OAUTH_ADMIN_ERROR };
     }
     const query = getQuery(event);
     const code = text(query.code);
@@ -162,7 +157,6 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
         setResponseStatus(event, 400);
         return { error: "OAuth callback is missing code or state." };
     }
-    const flow = readStoredFlow(event, providerId);
     deleteCookie(event, flowCookieName(providerId), { path: "/" });
     const state = decodeOAuthState(stateParam, "");
     if (!flow ||
@@ -211,7 +205,9 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
             const accountId = scopedOAuthAccountId(providerId, session.email, identity.accountId);
             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);
+            const existing = existingConnections.find((connection) => connection.accountId === accountId &&
+                (orgContext.oauthScope === "organization" ||
+                    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",
@@ -235,7 +231,8 @@ export async function handleWorkspaceProviderOAuthCallback(event, providerId) {
                 accountLabel: identity.label,
                 status: "connected",
                 scopes,
-                allowedApps: existing?.allowedApps ?? [],
+                allowedApps: existing?.allowedApps ??
+                    (orgContext.oauthScope === "app" ? [flow.appId] : []),
                 config: connectionConfig,
                 lastCheckedAt: new Date(),
                 lastError: null,
@@ -822,12 +819,27 @@ function unauthorized(event) {
     setResponseStatus(event, 401);
     return { error: "Authentication required" };
 }
-async function requireWorkspaceProviderOAuthAdmin(event) {
+async function requireWorkspaceProviderOAuthAdmin(event, appId) {
     const context = await getOrgContext(event).catch(() => null);
-    if (!context ||
-        !canConnectWorkspaceProviderOAuth(context.orgId, context.role)) {
+    if (!context || !context.orgId) {
         setResponseStatus(event, 403);
         return null;
     }
-    return context;
+    if (canConnectWorkspaceProviderOAuth(context.orgId, context.role)) {
+        return { ...context, oauthScope: "organization" };
+    }
+    if (appId) {
+        const descriptor = getRegisteredAppRoles(appId);
+        if (descriptor?.roles.some((role) => role === "admin")) {
+            const role = await resolveAppRole(descriptor, {
+                userEmail: context.email,
+                orgId: context.orgId,
+            });
+            if (role.status === "assigned" && role.role === "admin") {
+                return { ...context, oauthScope: "app" };
+            }
+        }
+    }
+    setResponseStatus(event, 403);
+    return null;
 }

package/dist/setup-connections/index.d.ts

@@ -1,5 +1,5 @@
 export { registerOnboardingStep, listOnboardingSteps, createOnboardingPlugin, defaultOnboardingPlugin, registerDefaultOnboardingSteps, type OnboardingFormField, type OnboardingMethod, type OnboardingMethodBadge, type OnboardingPluginOptions, type OnboardingStep, type OnboardingStepStatus, } from "../onboarding/index.js";
 export { deleteAppSecret, getAppSecretMeta, getRequiredSecret, last4, listAppSecretsForScope, listRequiredSecrets, maybeRegisterSecretOnboardingStep, readAppSecret, readAppSecretMeta, registerRequiredSecret, resolveKeyReferences, validateUrlAllowlist, writeAppSecret, type ReadSecretResult, type RegisteredSecret, type SecretKind, type SecretMeta, type SecretRef, type SecretScope, type SecretValidator, type ValidatorResult, type WriteSecretArgs, } from "../secrets/index.js";
 export { WORKSPACE_CONNECTION_PROVIDERS, defineWorkspaceConnectionProvider, getWorkspaceConnectionProvider, isWorkspaceConnectionProviderId, listWorkspaceConnectionProviders, listWorkspaceConnectionProvidersForCapability, listWorkspaceConnectionProvidersForTemplate, mergeWorkspaceConnectionProviders, workspaceConnectionProviderSupports, type ListWorkspaceConnectionProvidersOptions, type WorkspaceConnectionCapability, type WorkspaceConnectionCredentialKey, type WorkspaceConnectionProvider, type WorkspaceConnectionProviderId, type WorkspaceConnectionTemplateUse, } from "../connections/index.js";
-export { deleteWorkspaceConnection, getWorkspaceConnection, listWorkspaceConnectionProviderCatalogForApp, listWorkspaceConnectionGrants, listWorkspaceConnections, listWorkspaceConnectionsForApp, markWorkspaceConnectionUsed, resolveWorkspaceConnectionCredentialForApp, resolveWorkspaceConnectionCredentialsForApp, resolveWorkspaceConnectionForApp, revokeWorkspaceConnectionGrant, summarizeWorkspaceConnectionProviderForApp, summarizeWorkspaceConnectionProviderReadiness, upsertWorkspaceConnection, upsertWorkspaceConnectionGrant, type ListWorkspaceConnectionProviderCatalogForAppOptions, type ResolvedWorkspaceConnectionForApp, type ResolveWorkspaceConnectionForAppOptions, type SerializedWorkspaceConnection, type SerializedWorkspaceConnectionGrant, type SummarizeWorkspaceConnectionProviderReadinessOptions, type UpsertWorkspaceConnectionGrantInput, type UpsertWorkspaceConnectionInput, type WorkspaceConnection, type WorkspaceConnectionForAppSummary, type WorkspaceConnectionGrant, type WorkspaceConnectionProviderCatalogForApp, type WorkspaceConnectionProviderCatalogForAppItem, type WorkspaceConnectionProviderReadiness, type WorkspaceConnectionProviderReadinessStatus, } from "../workspace-connections/index.js";
+export { deleteWorkspaceConnection, getWorkspaceConnection, listWorkspaceConnectionProviderCatalogForApp, listWorkspaceConnectionGrants, listWorkspaceConnections, listWorkspaceConnectionsForApp, markWorkspaceConnectionUsed, normalizeWorkspaceConnectionAllowedUsers, resolveWorkspaceConnectionCredentialForApp, resolveWorkspaceConnectionCredentialsForApp, resolveWorkspaceConnectionForApp, revokeWorkspaceConnectionGrant, summarizeWorkspaceConnectionProviderForApp, summarizeWorkspaceConnectionProviderReadiness, upsertWorkspaceConnection, upsertWorkspaceConnectionGrant, type ListWorkspaceConnectionProviderCatalogForAppOptions, type ResolvedWorkspaceConnectionForApp, type ResolveWorkspaceConnectionForAppOptions, type SerializedWorkspaceConnection, type SerializedWorkspaceConnectionGrant, type SummarizeWorkspaceConnectionProviderReadinessOptions, type UpsertWorkspaceConnectionGrantInput, type UpsertWorkspaceConnectionInput, type WorkspaceConnection, type WorkspaceConnectionForAppSummary, type WorkspaceConnectionGrant, type WorkspaceConnectionProviderCatalogForApp, type WorkspaceConnectionProviderCatalogForAppItem, type WorkspaceConnectionProviderReadiness, type WorkspaceConnectionProviderReadinessStatus, } from "../workspace-connections/index.js";
 export { registerWorkspaceConnectionOnboardingStep, type RegisterWorkspaceConnectionOnboardingStepOptions, } from "./onboarding.js";

package/dist/setup-connections/index.js

@@ -1,5 +1,5 @@
 export { registerOnboardingStep, listOnboardingSteps, createOnboardingPlugin, defaultOnboardingPlugin, registerDefaultOnboardingSteps, } from "../onboarding/index.js";
 export { deleteAppSecret, getAppSecretMeta, getRequiredSecret, last4, listAppSecretsForScope, listRequiredSecrets, maybeRegisterSecretOnboardingStep, readAppSecret, readAppSecretMeta, registerRequiredSecret, resolveKeyReferences, validateUrlAllowlist, writeAppSecret, } from "../secrets/index.js";
 export { WORKSPACE_CONNECTION_PROVIDERS, defineWorkspaceConnectionProvider, getWorkspaceConnectionProvider, isWorkspaceConnectionProviderId, listWorkspaceConnectionProviders, listWorkspaceConnectionProvidersForCapability, listWorkspaceConnectionProvidersForTemplate, mergeWorkspaceConnectionProviders, workspaceConnectionProviderSupports, } from "../connections/index.js";
-export { deleteWorkspaceConnection, getWorkspaceConnection, listWorkspaceConnectionProviderCatalogForApp, listWorkspaceConnectionGrants, listWorkspaceConnections, listWorkspaceConnectionsForApp, markWorkspaceConnectionUsed, resolveWorkspaceConnectionCredentialForApp, resolveWorkspaceConnectionCredentialsForApp, resolveWorkspaceConnectionForApp, revokeWorkspaceConnectionGrant, summarizeWorkspaceConnectionProviderForApp, summarizeWorkspaceConnectionProviderReadiness, upsertWorkspaceConnection, upsertWorkspaceConnectionGrant, } from "../workspace-connections/index.js";
+export { deleteWorkspaceConnection, getWorkspaceConnection, listWorkspaceConnectionProviderCatalogForApp, listWorkspaceConnectionGrants, listWorkspaceConnections, listWorkspaceConnectionsForApp, markWorkspaceConnectionUsed, normalizeWorkspaceConnectionAllowedUsers, resolveWorkspaceConnectionCredentialForApp, resolveWorkspaceConnectionCredentialsForApp, resolveWorkspaceConnectionForApp, revokeWorkspaceConnectionGrant, summarizeWorkspaceConnectionProviderForApp, summarizeWorkspaceConnectionProviderReadiness, upsertWorkspaceConnection, upsertWorkspaceConnectionGrant, } from "../workspace-connections/index.js";
 export { registerWorkspaceConnectionOnboardingStep, } from "./onboarding.js";

package/dist/shared/first-run-onboarding.d.ts

@@ -1,3 +1,9 @@
 export declare const FIRST_RUN_ONBOARDING_COOKIE = "agent-native-first-run";
 export declare const FIRST_RUN_ONBOARDING_MAX_AGE: number;
 export declare const FIRST_RUN_ONBOARDING_COMPLETED_KEY = "onboarding:first-run-completed";
+/**
+ * Set only when the framework provisions the user's first default
+ * organization. Membership in an existing organization must never qualify a
+ * user for the first-run flow, even if an old signup cookie is still present.
+ */
+export declare const FIRST_RUN_ONBOARDING_ELIGIBLE_KEY = "onboarding:first-run-eligible";

package/dist/shared/first-run-onboarding.js

@@ -1,3 +1,9 @@
 export const FIRST_RUN_ONBOARDING_COOKIE = "agent-native-first-run";
 export const FIRST_RUN_ONBOARDING_MAX_AGE = 24 * 60 * 60;
 export const FIRST_RUN_ONBOARDING_COMPLETED_KEY = "onboarding:first-run-completed";
+/**
+ * Set only when the framework provisions the user's first default
+ * organization. Membership in an existing organization must never qualify a
+ * user for the first-run flow, even if an old signup cookie is still present.
+ */
+export const FIRST_RUN_ONBOARDING_ELIGIBLE_KEY = "onboarding:first-run-eligible";

package/dist/sharing/access.d.ts

@@ -6,7 +6,7 @@
  * 2. Visibility — `'private' | 'org' | 'public'`. `org` grants read to anyone
  *    in the same org; `public` grants read to any authenticated user.
  * 3. Share rows — per-user or per-org grants in the `{type}_shares` table
- *    with a role (`viewer | editor | admin`).
+ *    with a role (`viewer | commenter | editor | admin`).
  *
  * Use `applyAccessFilter()` on list/read queries to filter rows the current
  * user can see. Use `assertAccess()` at the top of write actions to reject

package/dist/sharing/access.js

@@ -6,7 +6,7 @@
  * 2. Visibility — `'private' | 'org' | 'public'`. `org` grants read to anyone
  *    in the same org; `public` grants read to any authenticated user.
  * 3. Share rows — per-user or per-org grants in the `{type}_shares` table
- *    with a role (`viewer | editor | admin`).
+ *    with a role (`viewer | commenter | editor | admin`).
  *
  * Use `applyAccessFilter()` on list/read queries to filter rows the current
  * user can see. Use `assertAccess()` at the top of write actions to reject
@@ -166,6 +166,9 @@ function minRoleSql(minRole) {
         // any role satisfies viewer
         return sql `1=1`;
     }
+    if (minRole === "commenter") {
+        return sql `role in ('commenter','editor','admin')`;
+    }
     if (minRole === "editor") {
         return sql `role in ('editor','admin')`;
     }

package/dist/sharing/actions/share-resource.d.ts

@@ -5,7 +5,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     resourceId: string;
     principalType: "org" | "user";
     principalId: string;
-    role?: "admin" | "editor" | "viewer";
+    role?: "admin" | "commenter" | "editor" | "viewer";
     notify?: boolean;
     resourceUrl?: string;
     message?: string;

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

@@ -140,9 +140,9 @@ export default defineAction({
             .string()
             .describe("Email (user) or org id (org) of the principal."),
         role: z
-            .enum(["viewer", "editor", "admin"])
+            .enum(["viewer", "commenter", "editor", "admin"])
             .default("viewer")
-            .describe("Role to grant."),
+            .describe("Role to grant: viewer can only read; commenter can read and add comments; editor can edit; admin can edit and manage access."),
         notify: z
             .boolean()
             .default(true)

package/dist/sharing/registry.d.ts

@@ -151,11 +151,11 @@ export interface ShareableResourceRegistration {
      * registration and always loads the full row instead — a fixed role string
      * has no such requirement and is compatible with the projection.
      */
-    publicAccessRole?: "viewer" | "editor" | "admin" | ((resource: any, ctx: {
+    publicAccessRole?: "viewer" | "commenter" | "editor" | "admin" | ((resource: any, ctx: {
         userEmail?: string;
         orgId?: string;
         authCapability?: string;
-    }) => "viewer" | "editor" | "admin" | Promise<"viewer" | "editor" | "admin">);
+    }) => "viewer" | "commenter" | "editor" | "admin" | Promise<"viewer" | "commenter" | "editor" | "admin">);
     /**
      * When `true`, individual user shares (`principalType: "user"`) must target
      * an email that is already a member of the same org as the resource, OR has

package/dist/sharing/schema.d.ts

@@ -19,7 +19,7 @@
  *
  *   export const deckShares = createSharesTable("deck_shares");
  *
- * The share row `role` supports `viewer | editor | admin`. `admin` is a
+ * The share row `role` supports `viewer | commenter | editor | admin`. `admin` is a
  * share-level capability — it lets non-owners manage shares. The single
  * `owner_email` column on the resource remains the ground truth for ownership.
  */
@@ -44,7 +44,7 @@ export declare function ownableColumns(): {
  * - `resourceId`      — id of the parent resource
  * - `principalType`   — `'user' | 'org'`
  * - `principalId`     — email (for user) or org id (for org)
- * - `role`            — `'viewer' | 'editor' | 'admin'`
+ * - `role`            — `'viewer' | 'commenter' | 'editor' | 'admin'`
  * - `createdBy`       — email of the user who created the share
  * - `createdAt`       — ISO timestamp
  *
@@ -138,14 +138,14 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             tableName: string;
             dataType: "string";
             columnType: "SQLiteText";
-            data: "admin" | "editor" | "viewer";
+            data: "admin" | "commenter" | "editor" | "viewer";
             driverParam: string;
             notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["viewer", "editor", "admin"];
+            enumValues: ["viewer", "commenter", "editor", "admin"];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
@@ -194,7 +194,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
     dialect: 'sqlite';
 }>;
 export type Visibility = "private" | "org" | "public";
-export type ShareRole = "viewer" | "editor" | "admin";
+export type ShareRole = "viewer" | "commenter" | "editor" | "admin";
 export type PrincipalType = "user" | "org";
 /** Role precedence — higher number = stronger capability. */
 export declare const ROLE_RANK: Record<ShareRole | "owner", number>;

package/dist/sharing/schema.js

@@ -19,7 +19,7 @@
  *
  *   export const deckShares = createSharesTable("deck_shares");
  *
- * The share row `role` supports `viewer | editor | admin`. `admin` is a
+ * The share row `role` supports `viewer | commenter | editor | admin`. `admin` is a
  * share-level capability — it lets non-owners manage shares. The single
  * `owner_email` column on the resource remains the ground truth for ownership.
  */
@@ -51,7 +51,7 @@ export function ownableColumns() {
  * - `resourceId`      — id of the parent resource
  * - `principalType`   — `'user' | 'org'`
  * - `principalId`     — email (for user) or org id (for org)
- * - `role`            — `'viewer' | 'editor' | 'admin'`
+ * - `role`            — `'viewer' | 'commenter' | 'editor' | 'admin'`
  * - `createdBy`       — email of the user who created the share
  * - `createdAt`       — ISO timestamp
  *
@@ -68,7 +68,9 @@ export function createSharesTable(tableName) {
             enum: ["user", "org"],
         }).notNull(),
         principalId: text("principal_id").notNull(),
-        role: text("role", { enum: ["viewer", "editor", "admin"] })
+        role: text("role", {
+            enum: ["viewer", "commenter", "editor", "admin"],
+        })
             .notNull()
             .default("viewer"),
         createdBy: text("created_by").notNull(),
@@ -78,9 +80,10 @@ export function createSharesTable(tableName) {
 /** Role precedence — higher number = stronger capability. */
 export const ROLE_RANK = {
     viewer: 1,
-    editor: 2,
-    admin: 3,
-    owner: 4,
+    commenter: 2,
+    editor: 3,
+    admin: 4,
+    owner: 5,
 };
 export function roleSatisfies(actual, minimum) {
     return ROLE_RANK[actual] >= ROLE_RANK[minimum];

package/dist/styles/agent-native.css

@@ -497,6 +497,27 @@
       transform: translateY(0);
     }
   }
+  /* Indeterminate: a route load has no percentage to report, so the bar
+     sweeps rather than pretending to know how far along it is. */
+  @keyframes route-transition-sweep {
+    0% {
+      transform: translateX(-100%);
+    }
+    100% {
+      transform: translateX(100%);
+    }
+  }
+}
+
+.route-transition-indicator-bar {
+  animation: route-transition-sweep 1.1s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .route-transition-indicator-bar {
+    animation: none;
+    opacity: 0.6;
+  }
 }
 
 /* Border-color compatibility shim:

package/dist/styles/chat-history-list.css

@@ -13,5 +13,5 @@ section[data-chat-first-chat-history]
   .an-chat-history-row__button {
   min-height: 28px;
   padding-block: 4px;
-  padding-inline: 8px 32px;
+  padding-inline: 8px;
 }

package/dist/templates/chat/.agents/skills/adding-a-feature/SKILL.md

@@ -101,8 +101,9 @@ placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
 real keys, internal data, or customer data into instructions as examples.
 
 If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
-states, or formatting, read `internationalization` and update the app's i18n
-catalogs in the same change.
+states, or formatting, update the English source copy. Read the optional
+`internationalization` skill and update additional catalogs only when
+`translations.locales` in `agent-native.config.ts` includes them.
 
 For app-backed skills, declare skill visibility in the app-skill manifest:
 

package/dist/templates/chat/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate actions, wiring navigation
+  state, or debugging agent context issues.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Core Patterns
+
+### 1. Navigation State (`navigation` key)
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent the semantic screen state: view, open IDs, active tab, and focused object.
+
+**UI side** — `useNavigationState`, an app-owned hook (not a framework import) that every template ships at `app/hooks/use-navigation-state.ts`. It is a thin wrapper around the framework primitive `useAgentRouteState`, handling both directions: writing `navigation` on route change and consuming the agent's `navigate` command.
+
+```tsx
+// app/hooks/use-navigation-state.ts
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are already exposed in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
+- Any durable selection — focused item, selected text range, active tab
+
+Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
+
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
+### 2. Current URL (`__url__` key)
+
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
+
+Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.
+
+### 3. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state,
+the current URL if filters matter, and selection state. It fetches the relevant
+data from existing domain actions, shared data helpers, or Drizzle queries, and
+returns a snapshot of what the user sees. Do not add REST wrappers just so
+`view-screen` can read app data. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const url = (await readAppState("__url__")) as {
+    searchParams?: Record<string, string>;
+  } | null;
+  const screen: Record<string, unknown> = { navigation };
+
+  if (url?.searchParams) {
+    screen.activeFilters = url.searchParams;
+  }
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const emails = await fetchEmailList(navigation.label);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
+
+### 4. The `navigate` Script
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
+
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
+
+Client code can use `useAgentRouteState`, `useSemanticNavigationState`, `setClientAppState`, `writeClientAppState`, `readClientAppState`, and `deleteClientAppState` from `@agent-native/core/client` instead of hand-written `fetch` calls. Pass `{ requestSource: TAB_ID }` on UI writes when pairing with `useDbSync({ ignoreSource: TAB_ID })`; pass `{ keepalive: true }` for short-lived writes such as selection cleanup during unload.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When processing sync events, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates these patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Reads `__url__` if URL query filters matter
+- Fetches email list matching current view/filter state
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+- For pure query-filter changes, use `set-search-params`
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include semantic route state in the `navigation` key (view, item IDs, active tab, focused row)
+- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
+- Update `view-screen` when adding new features — it should return data for every view
+- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
+- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How `useDbSync` delivers app-state changes to the UI
+- **actions** — How to create the `view-screen` and `navigate` actions
+- **storing-data** — Application-state is one of the core SQL stores