@agent-native/core 0.157.4 → 0.157.6

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

package/docs/content/actions-advanced.mdx

@@ -0,0 +1,152 @@
+---
+title: "Advanced & Legacy"
+description: "Feature-flag gating for actions still rolling out, and the older CLI-only action style (export default async function(args) plus parseArgs) kept for one-off dev scripts."
+---
+
+# Advanced & Legacy
+
+## Guarding staged features {#feature-flags}
+
+Feature flags exist for one specific situation: an action is safe to deploy, but you want to turn it on for a few accounts before everyone gets it. Getting there takes three required steps, plus an optional fourth for the UI.
+
+<Steps>
+
+### Declare the flag
+
+Declare the flag in a module both the server and the client can import, since the same flag key has to reach both sides:
+
+```ts
+// shared/feature-flags.ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+`key` is the only field every other piece of code will reference, so it needs to be stable. `displayName` and `description` only show up later, in the operator UI where someone actually turns the flag on. Declaring the flag here doesn't enable anything. Every flag starts out off for every account.
+
+### Register it at startup
+
+Register the flag with a Nitro plugin so the running server knows it exists:
+
+```ts
+// server/plugins/feature-flags.ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+An unregistered flag always evaluates to `false`, no matter what an operator later sets. This step is what makes the flag real to the server. It still doesn't turn the flag on for anyone. That happens through the operator actions described at the end of this section.
+
+### Guard the action
+
+This is the check that actually matters, since every caller, whether that's the agent, the frontend, or a script, has to go through it:
+
+```ts
+// actions/create-fusion-app.ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // Perform the guarded operation.
+};
+```
+
+`isFeatureFlagEnabled()` reads the caller's identity off `ctx` (see [the ctx argument](/docs/actions-run-context#ctx)) and evaluates the flag for that specific user and org. If the flag isn't on for them, the action throws before doing anything else. This check has to live inside `run()`, because `run()` is the one place every dispatch path is guaranteed to pass through.
+
+### Hide it in the UI (optional)
+
+Use the same flag on the client to hide the feature from people who can't call it anyway:
+
+```tsx
+// app/routes/fusion.tsx
+import { Button } from "@/components/ui/button";
+import { useFeatureFlag } from "@agent-native/core/client";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export function CreateFusionAppButton() {
+  const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+  if (!enabled) return null;
+  return <Button onClick={createFusionApp}>Create Fusion app</Button>;
+}
+```
+
+`useFeatureFlag()` returns a plain boolean, evaluated for the signed-in user the same way the server-side check is. Hiding the button when it's `false` keeps someone from clicking into a feature they can't use yet, but it's presentation only. Nothing about it stops a direct call to the action. That's exactly why the check in `run()` from the previous step still has to be there, regardless of what the UI shows.
+
+</Steps>
+
+Once a flag is declared and registered, turning it on for real accounts goes through three mounted actions. `get-feature-flags` is the one `useFeatureFlag()` itself calls: it's open to any signed-in caller, since every user needs to check their own flags. `list-feature-flags` and `set-feature-flag` are the two management actions. Both are restricted to an organization's owners and admins (or the no-org administrator), and both are audited.
+
+`set-feature-flag` is how an operator actually changes who the flag is on for:
+
+| Operation                                         | What it does                                          | Example args                                                                                                    |
+| ------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `enable-for-current-user`                         | Turns the flag on for your own account only.          | `{ key: "full-app-building", operation: "enable-for-current-user" }`                                            |
+| `off`                                             | Turns the flag off for everyone, resetting any rules. | `{ key: "full-app-building", operation: "off" }`                                                                |
+| `replace-rules`, mode `"on"`                      | Turns the flag on for everyone.                       | `{ key: "full-app-building", operation: "replace-rules", rules: { mode: "on" } }`                               |
+| `replace-rules`, mode `"rules"` with `emails`     | Turns it on for a specific list of accounts.          | `{ key: "full-app-building", operation: "replace-rules", rules: { mode: "rules", emails: ["a@example.com"] } }` |
+| `replace-rules`, mode `"rules"` with `orgIds`     | Turns it on for specific organizations.               | `{ key: "full-app-building", operation: "replace-rules", rules: { mode: "rules", orgIds: ["org_123"] } }`       |
+| `replace-rules`, mode `"rules"` with `percentage` | Turns it on for a percentage rollout.                 | `{ key: "full-app-building", operation: "replace-rules", rules: { mode: "rules", percentage: 10 } }`            |
+
+Fleet operator UIs call these same actions through narrowly scoped A2A delegation instead of a shared login, and Analytics is the sole operator UI for them. Apps should not build their own flag settings panel, and flag writes should never route through generic settings endpoints or raw SQL.
+
+<Callout id="doc-block-actions-advanced-1" tone="warning">
+
+Never put authentication, authorization, audit, secrets, or SSR cache behavior behind a runtime flag. Those need to be correct unconditionally, not toggled.
+
+</Callout>
+
+## Legacy CLI-style actions {#legacy-cli-actions}
+
+The framework still supports older `export default async function(args)` actions that aren't wrapped in `defineAction()`. These are useful for one-off dev scripts that don't need agent or HTTP exposure. They're CLI-only: they don't appear as agent tools, don't mount HTTP endpoints, and don't get typesafe frontend hooks.
+
+```ts
+// actions/debug-dump.ts (CLI-only)
+import { parseArgs } from "@agent-native/core";
+
+export default async function main(args: string[]) {
+  const { table } = parseArgs(args);
+  // one-off script you wouldn't want the agent to call
+}
+```
+
+New code should prefer `defineAction()`. Reach for this pattern only when you deliberately don't want the action exposed to agents or the UI.
+
+### `parseArgs(args)` {#parseargs}
+
+Helper for legacy-style actions. Parses CLI arguments in `--key value` or `--key=value` format:
+
+```ts
+import { parseArgs } from "@agent-native/core";
+
+const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
+// { name: "Steve", verbose: "true", count: "3" }
+```
+
+## Utility functions {#utility-functions}
+
+These are small helpers for writing scripts, from the same `@agent-native/core` import `parseArgs()` above comes from. They aren't tied to the legacy CLI-style action style specifically. Reach for them in any one-off dev script: loading environment variables, validating a path argument, or aborting with a clear error.
+
+| Function                | Returns                  | Description                                                                                                                                                       |
+| ----------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loadEnv(path?)`        | `void`                   | Load `.env` (and `.env.local`) from the project root or a custom path. Falls back to the workspace root's `.env` in an enterprise workspace.                      |
+| `camelCaseArgs(args)`   | `Record<string, string>` | Convert kebab-case keys to camelCase.                                                                                                                             |
+| `isValidPath(p)`        | `boolean`                | Validate a relative path (no traversal, no absolute).                                                                                                             |
+| `isValidProjectPath(p)` | `boolean`                | Validate a project slug (e.g. `my-project` or `group/my-project`).                                                                                                |
+| `ensureDir(dir)`        | `void`                   | `mkdir -p` helper.                                                                                                                                                |
+| `fail(message)`         | `never`                  | Throw an error to abort a script. The CLI runner catches it and exits with code 1. In-server callers (agent tools, A2A) get it back as a tool-call error instead. |
+
+## What's next
+
+- [**Defining Actions**](/docs/actions-defining) — the `defineAction()` pattern this legacy style predates
+- [**Overview**](/docs/actions-overview) — what an action is and the hello-world walkthrough
+- [**Other Surfaces**](/docs/actions-other-surfaces) — the CLI runner these utilities and legacy actions support
+- [**Feature Flags**](/docs/feature-flags) — the full flag lifecycle beyond gating a single action

package/docs/content/actions-defining.mdx

@@ -0,0 +1,275 @@
+---
+title: "Defining Actions"
+description: "The defineAction() anatomy: schema, run, and HTTP config, plus how to keep the action surface small."
+---
+
+# Defining Actions
+
+Every action starts with a call to `defineAction()`. It bundles a description for the agent, a schema that validates input, and a `run` function that does the work, so the UI and the agent call the exact same code.
+
+<AnnotatedCode
+  id="doc-block-actions-defining-1"
+  title="Anatomy of an action"
+  filename="actions/reply-to-email.ts"
+  language="ts"
+  code={
+    'import { defineAction } from "@agent-native/core/action";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\n\nexport default defineAction({\n  description: "Reply to an email thread in the user\'s voice.",\n  schema: z.object({\n    emailId: z.string().describe("The id of the email to reply to."),\n    body: z.string().describe("The reply body, in markdown."),\n  }),\n  run: async ({ emailId, body }) => {\n    const db = getDb();\n    await db.insert(schema.replies).values({ emailId, body });\n    return { ok: true, emailId };\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "Tool surface",
+      note: "`description` is what the agent reads to decide when to call this. The per-field `.describe()` calls flow into the JSON Schema too.",
+    },
+    {
+      lines: "8-11",
+      label: "Typed contract",
+      note: "One schema validates input from **every** surface and is converted to JSON Schema for the model. Invalid inputs never reach `run`.",
+    },
+    {
+      lines: "12-16",
+      label: "One implementation",
+      note: "The `run` body is the single source of truth. The UI button and the agent tool both execute exactly this. `getDb()` and `schema` come from your app's `server/db/index.ts`. See [Database](/docs/database).",
+    },
+  ]}
+/>
+
+The framework auto-discovers every file in `actions/` and mounts it on startup. There's nothing else to register by hand.
+
+<Signature
+  id="doc-block-actions-defining-2"
+  name="defineAction"
+  params={[
+    {
+      name: "config",
+      type: "DefineActionConfig<TSchema, TReturn, TOutputSchema>",
+      description:
+        "Everything below is one config object. Only description, schema, and run are required.",
+      fields: [
+        {
+          name: "description",
+          type: "string",
+          description:
+            "What the agent reads to decide when to call this action.",
+        },
+        {
+          name: "schema",
+          type: "StandardSchemaV1",
+          description:
+            "Validates input on every surface. See Schema options below.",
+        },
+        {
+          name: "run",
+          type: "(args, ctx?) => Promise<TReturn> | TReturn",
+          description:
+            "The single implementation every surface calls. See Run Context for the ctx argument.",
+        },
+        {
+          name: "http",
+          type: "ActionHttpConfig | false",
+          optional: true,
+          description:
+            "Overrides the mounted method/path, or disables the HTTP endpoint entirely. See HTTP config below.",
+        },
+        {
+          name: "readOnly",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Auto-true when http.method is GET. Skips the UI poll-refresh and write-auditing. Not access control.",
+        },
+        {
+          name: "outputSchema",
+          type: "StandardSchemaV1",
+          optional: true,
+          description:
+            "Validates what run() returns. See Validating the return value below.",
+        },
+        {
+          name: "outputErrorStrategy",
+          type: '"warn" | "strict" | "fallback"',
+          optional: true,
+          default: '"warn"',
+          description: "What happens on an output mismatch.",
+        },
+        {
+          name: "outputFallback",
+          type: "TReturn",
+          optional: true,
+          description:
+            'Returned in place of an invalid result when outputErrorStrategy is "fallback".',
+        },
+        {
+          name: "parallelSafe",
+          type: "boolean",
+          optional: true,
+          description:
+            "Allows a mutating action to run concurrently with other same-turn tool calls.",
+        },
+        {
+          name: "agentTool",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            "Set false to hide from every agent tool list. See Access & Authorization.",
+        },
+        {
+          name: "toolCallable",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            "Set false to block the sandboxed extension iframe bridge. See Access & Authorization.",
+        },
+        {
+          name: "publicAgent",
+          type: "PublicAgentActionConfig",
+          optional: true,
+          description:
+            "{ expose: true } adds the action to public MCP/A2A/OpenAPI surfaces. See Access & Authorization.",
+        },
+        {
+          name: "needsApproval",
+          type: "boolean | ((args, ctx?) => boolean | Promise<boolean>)",
+          optional: true,
+          default: "false",
+          description:
+            "Pauses the agent loop for human approval before run(). See Human-in-the-Loop Approvals.",
+        },
+        {
+          name: "authorize",
+          type: "ActionAuthorize<TInput>",
+          optional: true,
+          description:
+            "Guard function deciding whether this caller may run the action at all. See Access & Authorization.",
+        },
+        {
+          name: "audit",
+          type: "ActionAuditConfig",
+          optional: true,
+          description:
+            "Tunes the automatic audit capture every mutating action already gets. See Audit Log.",
+        },
+        {
+          name: "chatUI",
+          type: "ActionChatUIConfig",
+          optional: true,
+          description:
+            "Declares a native chat UI renderer for the action's result. See Other Surfaces.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "ActionDefinition<TInput, TReturn>",
+    description:
+      "The typed action definition. Export it as the file's default export.",
+  }}
+/>
+
+## Schema options {#schemas}
+
+`schema` accepts any [Standard Schema](https://standardschema.dev)-compatible library:
+
+- **Zod** (v4): the most common choice, with the best type inference and automatic conversion to JSON Schema.
+- **Valibot**: a good pick when bundle size matters.
+- **ArkType**: a good pick if you prefer its syntax.
+
+The schema does two jobs. It converts to JSON Schema for the Claude API tool definition, and it validates input at runtime before `run()` fires. Invalid input never reaches your handler.
+
+## Validating the return value {#output-schema}
+
+`schema` validates _inputs_. To also validate what an action **returns**, pass an `outputSchema` (any Standard Schema-compatible schema: Zod, Valibot, ArkType, the same surface as `schema`). The framework validates input before `run()` and validates the result after `run()` resolves.
+
+```ts
+export default defineAction({
+  description: "Summarize a thread.",
+  schema: z.object({ threadId: z.string() }),
+  outputSchema: z.object({
+    summary: z.string(),
+    messageCount: z.number(),
+  }),
+  outputErrorStrategy: "warn", // default
+  run: async ({ threadId }) => {
+    /* ...returns { summary, messageCount } ... */
+  },
+});
+```
+
+`outputErrorStrategy` controls what happens on a mismatch:
+
+| Strategy     | Behavior on mismatch                                                                               |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| `"warn"`     | **Default.** `console.warn` the issues and return the **original** result unchanged. Non-breaking. |
+| `"strict"`   | Throw a clear error, so a bug in the action is easy to notice.                                     |
+| `"fallback"` | Return the provided `outputFallback` value in place of the invalid result.                         |
+
+When `run()` succeeds, the framework returns the validated value, so any defaults or coercions on `outputSchema` take effect, the same way they do for input. When you don't pass an `outputSchema`, the return value is unchanged.
+
+## HTTP config {#http}
+
+By default every action is exposed as `POST /_agent-native/actions/<name>`. Override with the `http` option:
+
+```ts
+export default defineAction({
+  description: "Get details for a lead.",
+  schema: z.object({ leadId: z.string() }),
+  http: { method: "GET" },
+  run: async ({ leadId }) => {
+    return await db.select().from(leads).where(eq(leads.id, leadId));
+  },
+});
+```
+
+For a `GET` action, `leadId` is passed as a query param: `/_agent-native/actions/get-lead?leadId=abc`.
+
+<Endpoint id="doc-block-actions-defining-3" title="The auto-mounted action endpoint" method="GET" path="/_agent-native/actions/get-lead" summary={"Every action is mounted here automatically. The filename is the action name."} auth={"Session cookie (frontend calls carry `X-Agent-Native-Frontend: 1`), or `Authorization: Bearer <token>` for external callers"} params={[
+  {
+    "name": "leadId",
+    "in": "query",
+    "type": "string",
+    "required": true,
+    "description": "GET args arrive as query params. POST args arrive in the JSON body."
+  }
+]} responses={[
+  {
+    "status": "200",
+    "description": "The action's return value as JSON."
+  },
+  {
+    "status": "400",
+    "description": "Input failed schema validation before run() fired."
+  }
+]}>
+
+POST is the default, and `http: { method: "GET" }` makes it a GET. The React hooks and `callAction()` always call this path by name, regardless of any `http.path` override. External systems can call the same route with a long-lived bearer token. See [HTTP API](/docs/http-api).
+
+</Endpoint>
+
+- **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`**: defaults to `POST`. `GET` actions are auto-marked `readOnly`, so a successful call doesn't trigger a UI poll-refresh.
+- **`http: { path: "..." }`**: overrides the mounted URL under `/_agent-native/actions/`. It defaults to the filename. This override only changes the URL for direct HTTP callers. `useActionQuery()`, `useActionMutation()`, and `callAction()` always call `/_agent-native/actions/<name>`, regardless of this override, so overriding the path makes those hooks 404. Use a path override only for external HTTP callers. Also note that `:param` route segments in the override path are not parsed into `run()` args. Only query-string params and JSON body fields are.
+- **`http: false`**: disables the HTTP endpoint entirely. Only the agent and CLI can call the action.
+- **`readOnly: true`**: explicitly skips the poll-refresh, even for POST actions that don't mutate anything. This is not access control. It doesn't restrict who may call the action, and it doesn't affect `useActionQuery()`, `useActionMutation()`, or any client hook. Its only effects are suppressing the post-call refresh event and opting the action out of write-auditing. To hide an action from the model, use `agentTool: false`. To gate who can call it, use the auth and access options on [Access & Authorization](/docs/actions-access-control).
+- **`parallelSafe: true`**: allows a mutating action to run at the same time as other tool calls in the same turn. Only set this when the action is safe to run concurrently and doesn't depend on order. Mutating actions serialize by default.
+
+## Keep the action surface small {#small-surface}
+
+Every action the agent can see takes up a slot in the model's tool list, and a long, overlapping list makes it harder for the model to pick the right tool. Design the action surface like an API you maintain, not one action per button in the UI:
+
+- Prefer **one CRUD-style `update` action** that takes a patch of optional fields, over many per-field actions like `update-name`, `update-order`, and `update-color`. The caller only sends the fields that changed.
+- Before adding a new read action for every query or filter, consider a more general option first: the [provider API trio](/docs/template-dispatch-vault-integrations#provider-api) (`provider-api-catalog`, `provider-api-docs`, and `provider-api-request`) for provider data, or the dev `db-query` tool for app data.
+- Mark UI-only or programmatic actions [`agentTool: false`](/docs/actions-access-control#agent-tool). They stay callable from the frontend or over HTTP, without taking a slot in the model's tool list.
+- Delete or hide actions the UI no longer uses, instead of leaving them exposed to the model.
+
+The repo includes an advisory helper, `node scripts/audit-template-actions.mjs [template ...]` (alias `pnpm actions:audit`). It scans a template's `actions/` folder and flags actions the UI may no longer use, along with groups of per-field actions that could be combined into one. It always exits with code 0 and never fails CI, and its heuristics are conservative, so treat its output as a suggestion, not an error.
+
+## What's next
+
+- [**Overview**](/docs/actions-overview) — what an action is and the hello-world walkthrough
+- [**Access & Authorization**](/docs/actions-access-control) — `agentTool`, `toolCallable`, `authorize`, and `ctx` scoping
+- [**Run Context**](/docs/actions-run-context) — the full `ctx` field table
+- [**Other Surfaces**](/docs/actions-other-surfaces) — native chat UI, CLI, A2A, MCP, and standard actions
+- [**Database**](/docs/database) — `getDb()`/`schema` used inside `run()`
+- [**Data & Sync**](/docs/client-data) — calling this action from the UI