@agent-native/core 0.157.3 → 0.157.5

package/dist/server/identity-sso-store.d.ts

@@ -15,17 +15,22 @@
  * development may initialize these tables lazily; production release
  * migrations own their creation before serverless requests are served.
  */
+export declare const CANONICAL_IDENTITY_SSO_HUB_URL = "https://dispatch.agent-native.com";
 export declare const SSO_STATE_TTL_MS: number;
 export declare const SSO_LOGIN_MAX = 60;
 export declare const SSO_LOGIN_WINDOW_MS = 60000;
 export declare function getIdentityHubUrl(): string | undefined;
+export declare function isIdentitySsoExplicitlyEnabled(): boolean;
 export declare function isIdentitySsoEnabled(): boolean;
 export declare function isDesktopSsoCanaryUserAgent(userAgent: string | undefined): boolean;
 export declare function isCanonicalAgentNativeAppOrigin(origin: string | undefined): boolean;
+export declare function isCanonicalIdentitySsoClientOrigin(origin: string | undefined): boolean;
 export declare function isCanonicalAgentNativeAppRequest(host: string | undefined, forwardedProtocol: string | undefined): boolean;
+export declare function isCanonicalIdentitySsoClientRequest(host: string | undefined, forwardedProtocol: string | undefined): boolean;
 /**
  * The conditional login entry is the only browser UI this feature adds. It
- * stays byte-for-byte absent when the direct web federation env is unset.
+ * stays byte-for-byte absent on self-hosted apps; canonical hosted clients
+ * use their exact registered origin as the implicit opt-in.
  */
 export declare function identitySsoLoginButtonHtml(): string;
 export interface CreateSsoStateInput {

package/dist/server/identity-sso-store.js

@@ -20,6 +20,7 @@ import { getDbExec, intType, isConnectionError, isPostgres, isProductionServerle
 import { ensureTableExists } from "../db/ddl-guard.js";
 let _initPromise;
 const DESKTOP_SSO_CANARY_USER_AGENT = /AgentNativeDesktopSsoCanary\//i;
+export const CANONICAL_IDENTITY_SSO_HUB_URL = "https://dispatch.agent-native.com";
 const CANONICAL_IDENTITY_SSO_APP_ORIGINS = new Set([
     "https://analytics.agent-native.com",
     "https://assets.agent-native.com",
@@ -47,28 +48,61 @@ const CLIENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const CODE_CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
 const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
 const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+const CANONICAL_IDENTITY_SSO_CLIENT_ORIGINS = new Set([...CANONICAL_IDENTITY_SSO_APP_ORIGINS].filter((origin) => origin !== CANONICAL_IDENTITY_SSO_HUB_URL));
 // ---------------------------------------------------------------------------
 // Feature switch — this module is intentionally dependency-light because the
 // auth guard and the route handler both import the same pure switch.
 // ---------------------------------------------------------------------------
+function configuredAppOrigin() {
+    for (const raw of [
+        process.env.APP_URL,
+        process.env.BETTER_AUTH_URL,
+        process.env.VITE_APP_URL,
+        process.env.VITE_BETTER_AUTH_URL,
+        process.env.URL,
+        process.env.DEPLOY_PRIME_URL,
+        process.env.DEPLOY_URL,
+    ]) {
+        const value = raw?.trim();
+        if (!value)
+            continue;
+        try {
+            const url = new URL(value);
+            return `${url.protocol}//${url.host}${url.pathname}`.replace(/\/+$/, "");
+        }
+        catch (error) {
+            void error;
+        }
+    }
+    return undefined;
+}
 export function getIdentityHubUrl() {
     const raw = process.env.AGENT_NATIVE_IDENTITY_HUB_URL?.trim();
-    if (!raw)
-        return undefined;
-    try {
-        const u = new URL(raw);
-        if (u.protocol !== "https:" &&
-            !(u.protocol === "http:" && LOCALHOST_HOSTS.has(u.hostname))) {
-            return undefined;
+    if (raw) {
+        try {
+            const u = new URL(raw);
+            if (u.protocol !== "https:" &&
+                !(u.protocol === "http:" && LOCALHOST_HOSTS.has(u.hostname))) {
+                return undefined;
+            }
+            if (u.username || u.password || u.search || u.hash)
+                return undefined;
+            return `${u.protocol}//${u.host}${u.pathname}`.replace(/\/+$/, "");
         }
-        if (u.username || u.password || u.search || u.hash)
+        catch (error) {
+            void error;
             return undefined;
-        return `${u.protocol}//${u.host}${u.pathname}`.replace(/\/+$/, "");
-    }
-    catch (error) {
-        void error;
-        return undefined;
+        }
     }
+    // Canonical hosted apps are all registered with Dispatch already. Keep
+    // self-hosted deployments opt-in, and never make Dispatch federate to itself.
+    const appOrigin = configuredAppOrigin();
+    return isCanonicalIdentitySsoClientOrigin(appOrigin)
+        ? CANONICAL_IDENTITY_SSO_HUB_URL
+        : undefined;
+}
+export function isIdentitySsoExplicitlyEnabled() {
+    return Boolean(process.env.AGENT_NATIVE_IDENTITY_HUB_URL?.trim() && getIdentityHubUrl());
 }
 export function isIdentitySsoEnabled() {
     return !!getIdentityHubUrl();
@@ -94,14 +128,23 @@ export function isCanonicalAgentNativeAppOrigin(origin) {
         return false;
     }
 }
+export function isCanonicalIdentitySsoClientOrigin(origin) {
+    return Boolean(origin && CANONICAL_IDENTITY_SSO_CLIENT_ORIGINS.has(origin));
+}
 export function isCanonicalAgentNativeAppRequest(host, forwardedProtocol) {
     if (!host || forwardedProtocol !== "https")
         return false;
     return isCanonicalAgentNativeAppOrigin(`https://${host}`);
 }
+export function isCanonicalIdentitySsoClientRequest(host, forwardedProtocol) {
+    if (!host || forwardedProtocol !== "https")
+        return false;
+    return isCanonicalIdentitySsoClientOrigin(`https://${host}`);
+}
 /**
  * The conditional login entry is the only browser UI this feature adds. It
- * stays byte-for-byte absent when the direct web federation env is unset.
+ * stays byte-for-byte absent on self-hosted apps; canonical hosted clients
+ * use their exact registered origin as the implicit opt-in.
  */
 export function identitySsoLoginButtonHtml() {
     if (!isIdentitySsoEnabled())

package/dist/server/identity-sso.d.ts

@@ -7,11 +7,10 @@
  * callback-scoped cookie and redeems the code server-to-server. Only that
  * server-to-server response may contain the signed identity assertion.
  *
- * Direct browser federation remains opt-in through
- * `AGENT_NATIVE_IDENTITY_HUB_URL`. The packaged Desktop Canary may use the
- * canonical Dispatch authority on canonical app origins, as established by
- * the merged feature-flagged Desktop work. This module does not change the
- * Desktop implementation or any ordinary auth surface.
+ * Direct browser federation uses the canonical Dispatch authority for exact
+ * first-party hosted app origins and remains opt-in through
+ * `AGENT_NATIVE_IDENTITY_HUB_URL` for self-hosted deployments. The packaged
+ * Desktop Canary follows the same canonical-origin boundary.
  */
 import type { H3Event } from "h3";
 import { getIdentityHubUrl, identitySsoLoginButtonHtml, isIdentitySsoEnabled } from "./identity-sso-store.js";
@@ -22,9 +21,9 @@ export declare const IDENTITY_SSO_DESKTOP_COMPLETE_PATH = "/_agent-native/identi
 export declare const IDENTITY_SSO_CALLBACK_PATH = "/_agent-native/identity/callback";
 export declare const IDENTITY_SSO_TOKEN_PATH = "/_agent-native/identity/token";
 /**
- * The packaged Desktop SSO Canary may use Dispatch without each canonical app
- * deploying the direct-web hub env. Ordinary browsers and self-hosted apps
- * remain strictly env-gated.
+ * Canonical hosted apps may use Dispatch without per-app hub configuration.
+ * Self-hosted apps remain strictly env-gated. The exact-origin check is kept
+ * request-scoped so a missing deployment URL cannot broaden the trust set.
  */
 export declare function resolveIdentityHubUrl(event: H3Event): string | undefined;
 export declare function handleIdentitySso(event: H3Event, subpath: string): Promise<Response>;

package/dist/server/identity-sso.js

@@ -7,11 +7,10 @@
  * callback-scoped cookie and redeems the code server-to-server. Only that
  * server-to-server response may contain the signed identity assertion.
  *
- * Direct browser federation remains opt-in through
- * `AGENT_NATIVE_IDENTITY_HUB_URL`. The packaged Desktop Canary may use the
- * canonical Dispatch authority on canonical app origins, as established by
- * the merged feature-flagged Desktop work. This module does not change the
- * Desktop implementation or any ordinary auth surface.
+ * Direct browser federation uses the canonical Dispatch authority for exact
+ * first-party hosted app origins and remains opt-in through
+ * `AGENT_NATIVE_IDENTITY_HUB_URL` for self-hosted deployments. The packaged
+ * Desktop Canary follows the same canonical-origin boundary.
  */
 import { createHash, randomBytes } from "node:crypto";
 import { deleteCookie, getCookie, getHeader, getMethod, setCookie } from "h3";
@@ -22,7 +21,7 @@ import { getAppName } from "./app-name.js";
 import { getSession, isExpectedAuthFailure, safeReturnPath } from "./auth.js";
 import { getBetterAuth, getBetterAuthInternalAdapter, } from "./better-auth-instance.js";
 import { createOAuthSession, getOrigin } from "./google-oauth.js";
-import { consumeSsoState, createSsoState, getIdentityHubUrl, identitySsoLoginButtonHtml, isCanonicalAgentNativeAppRequest, isDesktopSsoCanaryUserAgent, isIdentitySsoEnabled, isJtiReplayed, SSO_STATE_TTL_MS, } from "./identity-sso-store.js";
+import { consumeSsoState, createSsoState, CANONICAL_IDENTITY_SSO_HUB_URL, getIdentityHubUrl, identitySsoLoginButtonHtml, isCanonicalAgentNativeAppRequest, isCanonicalIdentitySsoClientRequest, isDesktopSsoCanaryUserAgent, isIdentitySsoExplicitlyEnabled, isIdentitySsoEnabled, isJtiReplayed, SSO_STATE_TTL_MS, } from "./identity-sso-store.js";
 export { getIdentityHubUrl, identitySsoLoginButtonHtml, isIdentitySsoEnabled };
 export const IDENTITY_SSO_PROVIDER_ID = "agent-native";
 export const IDENTITY_SSO_SCOPE = "identity";
@@ -33,7 +32,6 @@ const DESKTOP_COMPLETION_NONCE = /^[A-Za-z0-9_-]{32,128}$/;
 const STATE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
 const CODE = /^[A-Za-z0-9_-]{43}$/;
 const CODE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/;
-const DESKTOP_IDENTITY_HUB_URL = "https://dispatch.agent-native.com";
 const SSO_VERIFIER_COOKIE_PREFIX = "agent_native_sso_verifier_";
 const MAX_ASSERTION_AGE_SECONDS = 5 * 60;
 const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
@@ -153,14 +151,19 @@ function resolveClientBinding(event, hub) {
     return { appId, clientId, redirectUri, authority };
 }
 /**
- * The packaged Desktop SSO Canary may use Dispatch without each canonical app
- * deploying the direct-web hub env. Ordinary browsers and self-hosted apps
- * remain strictly env-gated.
+ * Canonical hosted apps may use Dispatch without per-app hub configuration.
+ * Self-hosted apps remain strictly env-gated. The exact-origin check is kept
+ * request-scoped so a missing deployment URL cannot broaden the trust set.
  */
 export function resolveIdentityHubUrl(event) {
-    const configured = getIdentityHubUrl();
+    const configured = isIdentitySsoExplicitlyEnabled()
+        ? getIdentityHubUrl()
+        : undefined;
     if (configured)
         return configured;
+    if (isCanonicalIdentitySsoClientRequest(getHeader(event, "host"), getHeader(event, "x-forwarded-proto"))) {
+        return CANONICAL_IDENTITY_SSO_HUB_URL;
+    }
     if (!isDesktopSsoCanaryUserAgent(getHeader(event, "user-agent"))) {
         return undefined;
     }
@@ -168,7 +171,7 @@ export function resolveIdentityHubUrl(event) {
         if (!isCanonicalAgentNativeAppRequest(getHeader(event, "host"), getHeader(event, "x-forwarded-proto"))) {
             return undefined;
         }
-        return DESKTOP_IDENTITY_HUB_URL;
+        return CANONICAL_IDENTITY_SSO_HUB_URL;
     }
     catch (error) {
         void error;

package/dist/sharing/actions/list-resource-shares.d.ts

@@ -11,11 +11,13 @@ declare const _default: import("../../action.js").ActionDefinition<{
     };
     orgId?: undefined;
     role?: undefined;
+    agentReadable?: undefined;
 } | {
     ownerEmail: string;
     orgId: string;
     visibility: import("../schema.js").Visibility;
     role: "owner" | import("../schema.js").ShareRole;
+    agentReadable: boolean;
     shares: any;
     policy: {
         allowPublic: boolean;

package/dist/sharing/actions/list-resource-shares.js

@@ -60,6 +60,7 @@ export default defineAction({
             orgId: access.resource.orgId ?? null,
             visibility: access.resource.visibility ?? "private",
             role: access.role,
+            agentReadable: Boolean(reg.agentReadable),
             shares: shares.map((s) => ({
                 id: s.id,
                 principalType: s.principalType,

package/dist/sharing/schema.d.ts

@@ -160,7 +160,7 @@ export declare function createSharesTable(tableName: string): import("drizzle-or
             data: string;
             driverParam: string;
             notNull: true;
-            hasDefault: false;
+            hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;

package/dist/sharing/schema.js

@@ -73,7 +73,10 @@ export function createSharesTable(tableName) {
         })
             .notNull()
             .default("viewer"),
-        createdBy: text("created_by").notNull(),
+        // Older app databases may already contain share rows from before this
+        // audit field existed. A literal default lets additive schema repair add
+        // the column without inventing an actor for those historical rows.
+        createdBy: text("created_by").notNull().default(""),
         createdAt: text("created_at").notNull().default(now()),
     });
 }

package/dist/templates/chat/.agents/skills/agent-native-toolkit/SKILL.md

@@ -182,6 +182,11 @@ in the moment of agent use.
   five-item sidebar preview and a footer row with New chat followed by an
   ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
   actions.
+- **Data grid kit**: provider-agnostic spreadsheet mechanics belong in
+  `@agent-native/toolkit/data-grid`. Apps provide rows, typed columns, editor
+  slots, selection and width state, persistence callbacks, and product-level
+  row/body slots. Keep database models, access checks, grouping, drag/drop,
+  and domain actions in the app adapter.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

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

@@ -184,6 +184,27 @@ import { ShareButton } from "@agent-native/core/client/sharing";
 
 For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
 
+## Standard share surface
+
+All app share popovers should use the same compact surface contract:
+
+- Use the text-only `ShareTrigger` from `@agent-native/toolkit/sharing`.
+- Render ordinary links with `ShareCopyRow`, which exposes a Copy action without
+  printing the raw URL.
+- Keep general access and individual people access in the standard Core sharing
+  flow. The people flow supports email invites, roles, notifications, and
+  removal through the shared share actions.
+- Add `ShareAgentsSection` only when the resource has a real agent-readable
+  link or prompt. Keep it collapsed by default and supply domain-specific
+  content through the shared section shell.
+- App-specific tabs or controls may remain when they represent a real domain
+  action (for example, an embed-code editor), but they should retain the same
+  trigger, copy-row, access, and spacing language.
+
+`ShareDisclosureSection` is the toolkit-owned shell for optional expandable
+share details; use its `ShareAgentsSection` or `SharePeopleSection` wrappers
+instead of creating another collapsible share panel in a template.
+
 ## Actions available everywhere
 
 The framework auto-mounts these actions in every template — no per-template boilerplate:

package/dist/templates/default/.agents/skills/agent-native-toolkit/SKILL.md

@@ -182,6 +182,11 @@ in the moment of agent use.
   five-item sidebar preview and a footer row with New chat followed by an
   ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
   actions.
+- **Data grid kit**: provider-agnostic spreadsheet mechanics belong in
+  `@agent-native/toolkit/data-grid`. Apps provide rows, typed columns, editor
+  slots, selection and width state, persistence callbacks, and product-level
+  row/body slots. Keep database models, access checks, grouping, drag/drop,
+  and domain actions in the app adapter.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

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

@@ -184,6 +184,27 @@ import { ShareButton } from "@agent-native/core/client/sharing";
 
 For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
 
+## Standard share surface
+
+All app share popovers should use the same compact surface contract:
+
+- Use the text-only `ShareTrigger` from `@agent-native/toolkit/sharing`.
+- Render ordinary links with `ShareCopyRow`, which exposes a Copy action without
+  printing the raw URL.
+- Keep general access and individual people access in the standard Core sharing
+  flow. The people flow supports email invites, roles, notifications, and
+  removal through the shared share actions.
+- Add `ShareAgentsSection` only when the resource has a real agent-readable
+  link or prompt. Keep it collapsed by default and supply domain-specific
+  content through the shared section shell.
+- App-specific tabs or controls may remain when they represent a real domain
+  action (for example, an embed-code editor), but they should retain the same
+  trigger, copy-row, access, and spacing language.
+
+`ShareDisclosureSection` is the toolkit-owned shell for optional expandable
+share details; use its `ShareAgentsSection` or `SharePeopleSection` wrappers
+instead of creating another collapsible share panel in a template.
+
 ## Actions available everywhere
 
 The framework auto-mounts these actions in every template — no per-template boilerplate:

package/dist/templates/headless/.agents/skills/agent-native-toolkit/SKILL.md

@@ -182,6 +182,11 @@ in the moment of agent use.
   five-item sidebar preview and a footer row with New chat followed by an
   ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
   actions.
+- **Data grid kit**: provider-agnostic spreadsheet mechanics belong in
+  `@agent-native/toolkit/data-grid`. Apps provide rows, typed columns, editor
+  slots, selection and width state, persistence callbacks, and product-level
+  row/body slots. Keep database models, access checks, grouping, drag/drop,
+  and domain actions in the app adapter.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

package/dist/templates/workspace-core/.agents/skills/agent-native-toolkit/SKILL.md

@@ -182,6 +182,11 @@ in the moment of agent use.
   five-item sidebar preview and a footer row with New chat followed by an
   ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
   actions.
+- **Data grid kit**: provider-agnostic spreadsheet mechanics belong in
+  `@agent-native/toolkit/data-grid`. Apps provide rows, typed columns, editor
+  slots, selection and width state, persistence callbacks, and product-level
+  row/body slots. Keep database models, access checks, grouping, drag/drop,
+  and domain actions in the app adapter.
 - **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
   `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
   Access tabs plus a Personal/Organization scope toggle. The canonical home

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

@@ -184,6 +184,27 @@ import { ShareButton } from "@agent-native/core/client/sharing";
 
 For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
 
+## Standard share surface
+
+All app share popovers should use the same compact surface contract:
+
+- Use the text-only `ShareTrigger` from `@agent-native/toolkit/sharing`.
+- Render ordinary links with `ShareCopyRow`, which exposes a Copy action without
+  printing the raw URL.
+- Keep general access and individual people access in the standard Core sharing
+  flow. The people flow supports email invites, roles, notifications, and
+  removal through the shared share actions.
+- Add `ShareAgentsSection` only when the resource has a real agent-readable
+  link or prompt. Keep it collapsed by default and supply domain-specific
+  content through the shared section shell.
+- App-specific tabs or controls may remain when they represent a real domain
+  action (for example, an embed-code editor), but they should retain the same
+  trigger, copy-row, access, and spacing language.
+
+`ShareDisclosureSection` is the toolkit-owned shell for optional expandable
+share details; use its `ShareAgentsSection` or `SharePeopleSection` wrappers
+instead of creating another collapsible share panel in a template.
+
 ## Actions available everywhere
 
 The framework auto-mounts these actions in every template — no per-template boilerplate:

package/docs/content/actions-access-control.mdx

@@ -0,0 +1,226 @@
+---
+title: "Access & Authorization"
+description: "Who can call an action: exposure flags (agentTool, toolCallable), ctx-based scoping, accessFilter/assertAccess, and the authorize guard."
+---
+
+# Access & Authorization
+
+Five settings decide who can call an action: the agent, the frontend, an extension, an outside API caller, or nobody without a human's approval first. Most actions never need to touch any of these, since the defaults already fit normal UI-and-agent use.
+
+### Exposure flags {#exposure-flags}
+
+All five flags default to the permissive value, so you only set one when you need to tighten a specific surface. The table below is a quick summary. The sections after it add the one detail each flag needs.
+
+| Flag            | Default       | Restrictive value → who can still call                                      | Typical use                                                          |
+| --------------- | ------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `agentTool`     | `true`        | `false` → UI, HTTP, and CLI only (hidden from the model, MCP, and A2A)      | UI-only or programmatic actions that shouldn't take up a tool slot   |
+| `toolCallable`  | `true`        | `false` → everything **except** the sandboxed extension iframe bridge (403) | Sensitive account or org changes (delete account, change membership) |
+| `publicAgent`   | off (private) | `{ expose: true }` → adds the action to **public** MCP/A2A/OpenAPI surfaces | Safe read or ingest tools that don't require authentication          |
+| `needsApproval` | `false`       | `true` → the agent **pauses**, and a human must approve the specific call   | Consequential side effects (send email, charge a card, delete)       |
+| `authorize`     | none          | a guard function → only callers it accepts, on **every** surface            | Operations restricted to a role (per-app RBAC, admin-only ops)       |
+
+These flags are independent, so setting one doesn't change the others. `agentTool` controls what the model sees, see [Hide from the model](#agent-tool) below. `toolCallable` controls only the extension iframe, see [Block extension iframes](#tool-callable) below. `publicAgent` adds an opt-in public surface, and a public web route never implies public tool exposure, see [Expose to public agents](#public-agent) below. `needsApproval` gates execution after the call is already made, see [Require human approval](#needs-approval) below. `authorize` decides whether this caller may run the action at all, on every dispatch path, before `run()` is entered, see [Restrict callers by role](#authorize) below.
+
+## Hide from the model {#agent-tool}
+
+By default, every action is a callable agent tool. Set `agentTool: false` to remove it from every agent tool list, while keeping it behind the framework's auth and action surface. It stays callable from the UI (`useActionMutation()` or `callAction()`), the CLI, and `/_agent-native/actions/<name>`:
+
+```ts
+export default defineAction({
+  description: "Persist the user's sidebar width.",
+  agentTool: false, // UI-only, not a tool in the model's context window
+  schema: z.object({ widthPx: z.number() }),
+  http: { method: "PUT" },
+  run: async ({ widthPx }) => {
+    /* ... */
+  },
+});
+```
+
+Use this when you add a UI-only or purely programmatic action, or when the UI stops using an action that would otherwise stay exposed to the model.
+
+## Block extension iframes {#tool-callable}
+
+Extensions ([Alpine.js mini-apps in sandboxed iframes](/docs/extensions)) call actions through `appAction(name, params)`, running with the viewer's own permissions, secrets, and SQL scope. For sensitive operations, that's too much trust by default. Set `toolCallable: false` to make the extension bridge return a 403, while keeping the action callable from the UI, agent, CLI, MCP, and A2A:
+
+```ts
+export default defineAction({
+  description: "Delete the current user's account.",
+  toolCallable: false, // never callable from an extension iframe
+  schema: z.object({ confirm: z.literal("yes") }),
+  run: async () => {
+    /* ... */
+  },
+});
+```
+
+Use it for actions that delete or transfer an account or org, change auth state, modify org membership, or grant share access. The framework's built-in `share-resource`, `unshare-resource`, and `set-resource-visibility` actions already opt out. The framework enforces this with a header the host sets on iframe calls, one an iframe can't fake. Regular UI, agent, CLI, MCP, and A2A calls are unaffected. See [Security](/docs/security) for details.
+
+## Expose to public agents {#public-agent}
+
+Every action stays off any public protocol surface by default, even one whose web route is public. Making a page crawlable never exposes a tool. Set `publicAgent: { expose: true, readOnly: true, ... }` to opt one safe action into the public MCP, A2A, and OpenAPI surfaces:
+
+```ts
+export default defineAction({
+  description: "Search published docs.",
+  schema: z.object({ query: z.string() }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: {
+    expose: true,
+    readOnly: true,
+    requiresAuth: false,
+  },
+  run: async ({ query }) => {
+    /* ... */
+  },
+});
+```
+
+Use it only for safe, read-only, or ingest-only actions, the kind you'd let a stranger call without signing in. `requiresAuth: false` tells the public surface this action is safe to list before authentication. Leave it `true` for an action that still needs a connected caller's identity, like a per-account ingest tool. See [External Agents](/docs/external-agents) and [MCP Protocol](/docs/mcp-protocol) for the full catalog and auth model this opts into.
+
+## Require human approval {#needs-approval}
+
+A handful of actions are too consequential to let the agent run on its own, like sending an email, charging a card, or deleting an account. Set `needsApproval: true` (or a predicate `(args, ctx) => boolean | Promise<boolean>`) on `defineAction()`, and the loop pauses before `run()`, requiring a human to approve that specific call. The default is **off**, and almost every action should stay that way.
+
+See [Human-in-the-Loop Approvals](/docs/human-approval) for the predicate API, the `approval_required` event, and the full end-to-end flow.
+
+## Restrict callers by role {#authorize}
+
+`authorize` answers one specific question: **may this caller run this operation at all?** Give it a guard function, and it runs before `run()` on every caller: agent tool, HTTP, frontend, MCP, A2A, and CLI.
+
+Declare the role vocabulary once with `defineAppRoles()`:
+
+```ts
+// server/lib/access.ts
+import { defineAppRoles } from "@agent-native/core/org-team";
+
+export const coachAccess = defineAppRoles({
+  appId: "coach",
+  roles: ["member", "coach-admin"] as const,
+  defaultRole: "member", // display only, never satisfies a guard
+});
+```
+
+Then guard the action with an explicit list of accepted roles:
+
+```ts
+// actions/archive-plan.ts
+import { coachAccess } from "../server/lib/access.js";
+
+export default defineAction({
+  description: "Archive a training plan.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async ({ id }) => {
+    /* ... */
+  },
+});
+```
+
+The guard wraps `run()` itself, instead of attaching to some other part of the action. That's because `run()` is the one thing all six dispatch sites go through, so there is no way for a caller to reach the body without passing the check. A guard that throws denies the call with its own error message. A guard that returns `false` denies the call with a generic 403. Anything else, including `undefined`, allows the call. Because the check needs a caller identity, an unattended CLI or cron invocation with no user email is denied rather than let through.
+
+The wrappers compose in this order:
+
+```text
+validate input -> authorize -> run -> validate output -> audit
+```
+
+Authorization sits _inside_ input validation, so a guard that inspects `args` gets the same parsed, type-checked value that `run()` receives, not whatever raw shape the caller sent. Auditing is outermost, so a denial is still recorded.
+
+`requireAny()` fails at definition time, not at request time. Calling it with no roles, or with a role outside the declared list, throws as soon as the module loads. That way a mistake, like `authorize: coachAccess.requireAny()` with a dropped argument, breaks right where it happened, instead of showing up later as an unexplained 403.
+
+### Access control in actions {#access-control}
+
+`authorize` only answers whether the caller may run the operation at all. It says nothing about which rows they may touch, that's a separate, row-level check. A table built with `ownableColumns()` and registered with `registerShareableResource()` (see [Sharing](/docs/sharing#building)) gets two helpers for this: `accessFilter()` scopes a list or read query to the rows the caller may see, and `assertAccess()` throws before a write if the caller doesn't hold the required role on that row.
+
+Use `accessFilter()` inside a list or read action's query:
+
+```ts
+// actions/list-decks.ts
+import { defineAction } from "@agent-native/core/action";
+import { accessFilter } from "@agent-native/core/sharing";
+import { z } from "zod";
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description: "List the decks the current user can see.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const db = getDb();
+    return await db
+      .select()
+      .from(schema.decks)
+      .where(accessFilter(schema.decks, schema.deckShares));
+  },
+});
+```
+
+Use `assertAccess()` before an update or delete, since a `WHERE` clause alone can't stop a write to a row it excludes:
+
+```ts
+// actions/rename-deck.ts
+import { defineAction } from "@agent-native/core/action";
+import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { getDb, schema } from "../server/db/index.js";
+
+export default defineAction({
+  description: "Rename a deck.",
+  schema: z.object({ id: z.string(), title: z.string() }),
+  run: async ({ id, title }) => {
+    await assertAccess("deck", id, "editor");
+    const db = getDb();
+    await db.update(schema.decks).set({ title }).where(eq(schema.decks.id, id));
+    return { ok: true };
+  },
+});
+```
+
+A create action calls neither helper. It only needs to stamp `ownerEmail` (and `orgId`) from the request context when inserting the new row, since there's no existing row yet to check access against. See [Sharing](/docs/sharing#building) for the full registration and create pattern, and [Run Context](/docs/actions-run-context) for the full shape of the `ctx` second argument used above.
+
+The three mechanisms are not interchangeable:
+
+| Mechanism                         | Question it answers                                  | Applies to                       |
+| --------------------------------- | ---------------------------------------------------- | -------------------------------- |
+| `authorize`                       | May this caller perform the operation at all?        | All six dispatch sites           |
+| `needsApproval`                   | Should a human approve this specific permitted call? | The agent loop only              |
+| `accessFilter()`/`assertAccess()` | Which rows may this permitted caller see or write?   | Inside `run()`, per query or row |
+
+A restricted write action typically needs both `authorize` and `assertAccess()`. The first keeps non-coaches out of the operation. The second keeps a coach out of another org's plan. `needsApproval` is a separate axis. It never restricts who may call, only whether the agent may proceed unattended.
+
+`coachAccess` above comes from `defineAppRoles()`, the per-app role overlay on org membership. See [Organizations, Teams & Permissions → App roles](/docs/organizations-teams-permissions#app-roles-per-app-rbac) for the role model and its guarantees.
+
+## Audit logging {#audit}
+
+Every mutating action is audited automatically. The framework records who ran it, when, from which surface, and, when it was the agent, which thread and turn, with credential-redacted inputs. Read-only (`GET`) actions are skipped. You don't write any code for this. It happens automatically inside `defineAction()`.
+
+Add an `audit` block only to fine-tune capture. The most common reason is to declare the resource the action changed, so the change shows up in that resource owner's trail:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({ type: "recording", id: args.id }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+A few other options. `audit: { onRead: true }` audits a sensitive read, like a secret access or bulk export. `audit: { enabled: false }` opts a noisy write out. `audit: { recordInputs: false }` skips capturing arguments. Read the trail back with the built-in `list-audit-events` and `get-audit-event` actions. See [Audit Log](/docs/audit-log) for full details.
+
+## What's next
+
+- [**Overview**](/docs/actions-overview) — what an action is and the hello-world walkthrough
+- [**Defining Actions**](/docs/actions-defining) — `defineAction()` anatomy, schema, and HTTP config
+- [**Run Context**](/docs/actions-run-context) — the `ctx` argument these checks read
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) — the `needsApproval` gate in depth
+- [**Audit Log**](/docs/audit-log) — the automatic who-changed-what trail
+- [**Security**](/docs/security) — `accessFilter`/`assertAccess` and the extension iframe trust boundary
+- [**Sharing**](/docs/sharing) — the framework sharing system these helpers back