@agent-native/core 0.47.1 → 0.48.1

package/dist/workspace-files/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/workspace-files/tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `workspace-files` agent tool.\n *\n * A single tool with an `action` discriminator covering write, append, read,\n * list, delete, and grep. Files persist across conversations; the agent uses\n * them to stage large intermediate results (fetched pages, per-item memos)\n * and then read back selectively for synthesis.\n *\n * Scope is automatically resolved from the active request context:\n *  - org scope when a request orgId is present (shared across users in the org)\n *  - user scope otherwise (personal to the requesting user's email)\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport {\n  getRequestOrgId,\n  getRequestUserEmail,\n} from \"../server/request-context.js\";\nimport {\n  writeWorkspaceFile,\n  appendWorkspaceFile,\n  readWorkspaceFile,\n  listWorkspaceFiles,\n  deleteWorkspaceFile,\n  grepWorkspaceFiles,\n  type WorkspaceFilesScope,\n} from \"./store.js\";\n\nconst MAX_READ_CHARS = 100_000;\nconst DEFAULT_READ_CHARS = 40_000;\n\n/** Resolve scope from the current request context (org-preferred). */\nfunction resolveScope(): WorkspaceFilesScope | null {\n  const orgId = getRequestOrgId();\n  if (orgId) return { scope: \"org\", scopeId: orgId };\n  const email = getRequestUserEmail();\n  if (email) return { scope: \"user\", scopeId: email };\n  return null;\n}\n\nexport function createWorkspaceFilesTool(): Record<string, ActionEntry> {\n  return {\n    \"workspace-files\": {\n      readOnly: false,\n      tool: {\n        description: [\n          \"Durable scratch-file storage for the agent. Files persist across conversations and are scoped to the current org/user.\",\n          \"Use this to stage large intermediate results (fetched pages, per-item analysis memos, API payloads) so they don't consume context window, then read them back selectively for synthesis.\",\n          \"\",\n          \"Typical fusion-style workflow:\",\n          \"  1. Fan out: for each item, fetch data and `write` a per-item memo file.\",\n          \"  2. Synthesize: `list` files, then `read` each memo (with offset/maxChars to page large ones).\",\n          \"  3. Optionally `grep` across all memos to find patterns.\",\n          \"  4. `delete` temp files when no longer needed.\",\n          \"\",\n          \"Actions:\",\n          \"  write   — create or overwrite a file. Max 2 MB per file, 200 MB total.\",\n          \"  append  — append text to a file (or create if absent).\",\n          \"  read    — read content, optionally with offset/maxChars for paging large files.\",\n          \"  list    — list files (with optional path prefix filter) showing name, size, updated.\",\n          \"  delete  — delete a file by path.\",\n          \"  grep    — search content across files for a substring or regex.\",\n        ].join(\"\\n\"),\n        parameters: {\n          type: \"object\",\n          properties: {\n            action: {\n              type: \"string\",\n              enum: [\"write\", \"append\", \"read\", \"list\", \"delete\", \"grep\"],\n              description: \"Operation to perform.\",\n            },\n            path: {\n              type: \"string\",\n              description:\n                'File path relative to the scope root, e.g. \"analysis/q2-memos/acme.md\". Required for write/append/read/delete. Optional for list/grep (acts as prefix filter).',\n            },\n            content: {\n              type: \"string\",\n              description:\n                \"Text content to write or append. Required for write/append.\",\n            },\n            contentType: {\n              type: \"string\",\n              description:\n                'MIME type for new files. Default: \"text/plain\". Use \"application/json\" for JSON, \"text/markdown\" for Markdown.',\n            },\n            offset: {\n              type: \"number\",\n              description:\n                \"Character offset to start reading from (for paging large files). Default: 0.\",\n            },\n            maxChars: {\n              type: \"number\",\n              description: `Maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,\n            },\n            pattern: {\n              type: \"string\",\n              description:\n                \"Search pattern for grep. Required for grep action. A plain substring by default; set useRegex to true for a regex.\",\n            },\n            useRegex: {\n              type: \"boolean\",\n              description:\n                \"When true, treat `pattern` as a JavaScript regex (case-insensitive). Default: false.\",\n            },\n          },\n          required: [\"action\"],\n        },\n      },\n\n      run: async (args: Record<string, unknown>): Promise<string> => {\n        const scope = resolveScope();\n        if (!scope) {\n          return \"Error: workspace-files requires an authenticated request context.\";\n        }\n\n        const action = String(args.action ?? \"\").trim();\n\n        try {\n          switch (action) {\n            case \"write\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for write.\";\n              const content = String(args.content ?? \"\");\n              const contentType = String(args.contentType ?? \"text/plain\");\n              const meta = await writeWorkspaceFile(\n                scope,\n                path,\n                content,\n                contentType,\n              );\n              return JSON.stringify({\n                ok: true,\n                action: \"write\",\n                path: meta.path,\n                sizeBytes: meta.sizeBytes,\n                updatedAt: meta.updatedAt,\n              });\n            }\n\n            case \"append\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for append.\";\n              const content = String(args.content ?? \"\");\n              const contentType = String(args.contentType ?? \"text/plain\");\n              const meta = await appendWorkspaceFile(\n                scope,\n                path,\n                content,\n                contentType,\n              );\n              return JSON.stringify({\n                ok: true,\n                action: \"append\",\n                path: meta.path,\n                sizeBytes: meta.sizeBytes,\n                updatedAt: meta.updatedAt,\n              });\n            }\n\n            case \"read\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for read.\";\n              const rawOffset = Number(args.offset);\n              const offset =\n                Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;\n              const rawMax = Number(args.maxChars);\n              const maxChars =\n                Number.isFinite(rawMax) && rawMax > 0\n                  ? Math.min(rawMax, MAX_READ_CHARS)\n                  : DEFAULT_READ_CHARS;\n\n              const file = await readWorkspaceFile(scope, path, {\n                offset,\n                maxChars,\n              });\n              if (!file) {\n                return JSON.stringify({\n                  ok: false,\n                  error: `File not found: \"${path}\"`,\n                });\n              }\n\n              const totalChars = file.sizeBytes; // approx\n              const truncated = file.content.length >= maxChars;\n              return JSON.stringify({\n                ok: true,\n                path: file.path,\n                contentType: file.contentType,\n                sizeBytes: file.sizeBytes,\n                updatedAt: file.updatedAt,\n                content: file.content,\n                ...(truncated\n                  ? {\n                      truncated: true,\n                      nextOffset: offset + file.content.length,\n                      hint: `File has more content. Call again with offset: ${offset + file.content.length}`,\n                    }\n                  : {}),\n              });\n            }\n\n            case \"list\": {\n              const prefix = args.path ? String(args.path).trim() : undefined;\n              const files = await listWorkspaceFiles(\n                scope,\n                prefix || undefined,\n              );\n              return JSON.stringify({\n                ok: true,\n                count: files.length,\n                files: files.map((f) => ({\n                  path: f.path,\n                  sizeBytes: f.sizeBytes,\n                  contentType: f.contentType,\n                  updatedAt: f.updatedAt,\n                })),\n              });\n            }\n\n            case \"delete\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for delete.\";\n              const deleted = await deleteWorkspaceFile(scope, path);\n              return JSON.stringify({\n                ok: true,\n                deleted,\n                path,\n              });\n            }\n\n            case \"grep\": {\n              const pattern = String(args.pattern ?? \"\").trim();\n              if (!pattern) return \"Error: pattern is required for grep.\";\n              const prefix = args.path ? String(args.path).trim() : undefined;\n              const useRegex =\n                args.useRegex === true || String(args.useRegex) === \"true\";\n              const matches = await grepWorkspaceFiles(scope, pattern, {\n                pathPrefix: prefix || undefined,\n                useRegex,\n                maxMatchesPerFile: 20,\n                maxFiles: 50,\n              });\n              return JSON.stringify({\n                ok: true,\n                pattern,\n                matchCount: matches.length,\n                matches: matches.map((m) => ({\n                  path: m.path,\n                  line: m.lineNumber,\n                  text: m.line,\n                })),\n              });\n            }\n\n            default:\n              return `Error: unknown action \"${action}\". Valid actions: write, append, read, list, delete, grep.`;\n          }\n        } catch (err) {\n          const msg = err instanceof Error ? err.message : String(err);\n          return JSON.stringify({ ok: false, error: msg });\n        }\n      },\n    },\n  };\n}\n"]}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/workspace-files/tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `workspace-files` agent tool.\n *\n * A single tool with an `action` discriminator covering write, append, read,\n * list, delete, and grep. Files persist across conversations; the agent uses\n * them to stage large intermediate results (fetched pages, per-item memos)\n * and then read back selectively for synthesis.\n *\n * Scope is automatically resolved from the active request context:\n *  - org scope when a request orgId is present (shared across users in the org)\n *  - user scope otherwise (personal to the requesting user's email)\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport {\n  getRequestOrgId,\n  getRequestUserEmail,\n} from \"../server/request-context.js\";\nimport {\n  writeWorkspaceFile,\n  appendWorkspaceFile,\n  readWorkspaceFile,\n  listWorkspaceFiles,\n  deleteWorkspaceFile,\n  grepWorkspaceFiles,\n  type WorkspaceFilesScope,\n} from \"./store.js\";\n\nconst MAX_READ_CHARS = 100_000;\nconst DEFAULT_READ_CHARS = 40_000;\n\n/** Resolve scope from the current request context (org-preferred). */\nfunction resolveScope(): WorkspaceFilesScope | null {\n  const orgId = getRequestOrgId();\n  if (orgId) return { scope: \"org\", scopeId: orgId };\n  const email = getRequestUserEmail();\n  if (email) return { scope: \"user\", scopeId: email };\n  return null;\n}\n\nexport function createWorkspaceFilesTool(): Record<string, ActionEntry> {\n  return {\n    \"workspace-files\": {\n      readOnly: false,\n      tool: {\n        description: [\n          \"Durable scratch-file storage for the agent. Files persist across conversations and are scoped to the current org/user.\",\n          \"Use this to stage large intermediate results (fetched pages, per-item analysis memos, API payloads) so they don't consume context window, then read them back selectively for synthesis.\",\n          \"\",\n          \"Typical fusion-style workflow:\",\n          \"  1. Fan out: for each item, fetch data and `write` a per-item memo file.\",\n          \"  2. Synthesize: `list` files, then `read` each memo (with offset/maxChars to page large ones).\",\n          \"  3. Optionally `grep` across all memos to find patterns.\",\n          \"  4. `delete` temp files when no longer needed.\",\n          \"\",\n          \"Actions:\",\n          \"  write   — create or overwrite a file. Max 2 MB per file, 200 MB total.\",\n          \"  append  — append text to a file (or create if absent).\",\n          \"  read    — read content, optionally with offset/maxChars for paging large files.\",\n          \"  list    — list files (with optional path prefix filter) showing name, size, updated.\",\n          \"  delete  — delete a file by path.\",\n          \"  grep    — search content across files for a substring or regex.\",\n        ].join(\"\\n\"),\n        parameters: {\n          type: \"object\",\n          properties: {\n            action: {\n              type: \"string\",\n              enum: [\"write\", \"append\", \"read\", \"list\", \"delete\", \"grep\"],\n              description: \"Operation to perform.\",\n            },\n            path: {\n              type: \"string\",\n              description:\n                'File path relative to the scope root, e.g. \"analysis/q2-memos/acme.md\". Required for write/append/read/delete. Optional for list/grep (acts as prefix filter).',\n            },\n            content: {\n              type: \"string\",\n              description:\n                \"Text content to write or append. Required for write/append.\",\n            },\n            contentType: {\n              type: \"string\",\n              description:\n                'MIME type for new files. Default: \"text/plain\". Use \"application/json\" for JSON, \"text/markdown\" for Markdown.',\n            },\n            offset: {\n              type: \"number\",\n              description:\n                \"Character offset to start reading from (for paging large files). Default: 0.\",\n            },\n            maxChars: {\n              type: \"number\",\n              description: `Maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,\n            },\n            pattern: {\n              type: \"string\",\n              description:\n                \"Search pattern for grep. Required for grep action. A plain substring by default; set useRegex to true for a regex.\",\n            },\n            useRegex: {\n              type: \"boolean\",\n              description:\n                \"When true, treat `pattern` as a JavaScript regex (case-insensitive). Default: false.\",\n            },\n          },\n          required: [\"action\"],\n        },\n      },\n\n      run: async (args: Record<string, unknown>): Promise<string> => {\n        const scope = resolveScope();\n        if (!scope) {\n          return \"Error: workspace-files requires an authenticated request context.\";\n        }\n\n        const action = String(args.action ?? \"\").trim();\n\n        try {\n          switch (action) {\n            case \"write\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for write.\";\n              const content = String(args.content ?? \"\");\n              const contentType = String(args.contentType ?? \"text/plain\");\n              const meta = await writeWorkspaceFile(\n                scope,\n                path,\n                content,\n                contentType,\n              );\n              return JSON.stringify({\n                ok: true,\n                action: \"write\",\n                path: meta.path,\n                sizeBytes: meta.sizeBytes,\n                updatedAt: meta.updatedAt,\n              });\n            }\n\n            case \"append\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for append.\";\n              const content = String(args.content ?? \"\");\n              const contentType = String(args.contentType ?? \"text/plain\");\n              const meta = await appendWorkspaceFile(\n                scope,\n                path,\n                content,\n                contentType,\n              );\n              return JSON.stringify({\n                ok: true,\n                action: \"append\",\n                path: meta.path,\n                sizeBytes: meta.sizeBytes,\n                updatedAt: meta.updatedAt,\n              });\n            }\n\n            case \"read\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for read.\";\n              const rawOffset = Number(args.offset);\n              const offset =\n                Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;\n              const rawMax = Number(args.maxChars);\n              const maxChars =\n                Number.isFinite(rawMax) && rawMax > 0\n                  ? Math.min(rawMax, MAX_READ_CHARS)\n                  : DEFAULT_READ_CHARS;\n\n              const file = await readWorkspaceFile(scope, path, {\n                offset,\n                maxChars,\n              });\n              if (!file) {\n                return JSON.stringify({\n                  ok: false,\n                  error: `File not found: \"${path}\"`,\n                });\n              }\n\n              const truncated = file.content.length >= maxChars;\n              return JSON.stringify({\n                ok: true,\n                path: file.path,\n                contentType: file.contentType,\n                sizeBytes: file.sizeBytes,\n                updatedAt: file.updatedAt,\n                content: file.content,\n                ...(truncated\n                  ? {\n                      truncated: true,\n                      nextOffset: offset + file.content.length,\n                      hint: `File has more content. Call again with offset: ${offset + file.content.length}`,\n                    }\n                  : {}),\n              });\n            }\n\n            case \"list\": {\n              const prefix = args.path ? String(args.path).trim() : undefined;\n              const files = await listWorkspaceFiles(\n                scope,\n                prefix || undefined,\n              );\n              return JSON.stringify({\n                ok: true,\n                count: files.length,\n                files: files.map((f) => ({\n                  path: f.path,\n                  sizeBytes: f.sizeBytes,\n                  contentType: f.contentType,\n                  updatedAt: f.updatedAt,\n                })),\n              });\n            }\n\n            case \"delete\": {\n              const path = String(args.path ?? \"\").trim();\n              if (!path) return \"Error: path is required for delete.\";\n              const deleted = await deleteWorkspaceFile(scope, path);\n              return JSON.stringify({\n                ok: true,\n                deleted,\n                path,\n              });\n            }\n\n            case \"grep\": {\n              const pattern = String(args.pattern ?? \"\").trim();\n              if (!pattern) return \"Error: pattern is required for grep.\";\n              const prefix = args.path ? String(args.path).trim() : undefined;\n              const useRegex =\n                args.useRegex === true || String(args.useRegex) === \"true\";\n              const matches = await grepWorkspaceFiles(scope, pattern, {\n                pathPrefix: prefix || undefined,\n                useRegex,\n                maxMatchesPerFile: 20,\n                maxFiles: 50,\n              });\n              return JSON.stringify({\n                ok: true,\n                pattern,\n                matchCount: matches.length,\n                matches: matches.map((m) => ({\n                  path: m.path,\n                  line: m.lineNumber,\n                  text: m.line,\n                })),\n              });\n            }\n\n            default:\n              return `Error: unknown action \"${action}\". Valid actions: write, append, read, list, delete, grep.`;\n          }\n        } catch (err) {\n          const msg = err instanceof Error ? err.message : String(err);\n          return JSON.stringify({ ok: false, error: msg });\n        }\n      },\n    },\n  };\n}\n"]}

package/docs/content/a2a-protocol.md

@@ -94,6 +94,8 @@ The card endpoint is public, so the framework redacts skills whose IDs reveal pe
 }
 ```
 
+_(Version may differ; fetch your app's live card at `/.well-known/agent-card.json` for the current `protocolVersion`.)_
+
 When `A2A_SECRET` is set (the recommended path), the card advertises a
 `jwtBearer` scheme as above. The `apiKey` scheme is only added when a legacy
 `apiKeyEnv` is also configured, so a card with just `A2A_SECRET` set publishes
@@ -303,18 +305,22 @@ A mail agent needs analytics data. The analytics agent exposes a "run-query" ski
 
 ```ts
 // In the mail agent's actions/get-analytics.ts
+import { defineAction } from "@agent-native/core/server";
 import { callAgent } from "@agent-native/core/a2a";
-
-export default async function (args: string[]) {
-  const response = await callAgent(
-    "https://analytics.example.com",
-    "How many emails were sent last week by category?",
-    { apiKey: process.env.ANALYTICS_API_KEY },
-  );
-
-  console.log(response);
-  // The mail agent can now use this data in its response
-}
+import { z } from "zod";
+
+export default defineAction({
+  description: "Ask the analytics agent a question.",
+  schema: z.object({ question: z.string() }),
+  async run({ question }) {
+    const response = await callAgent(
+      "https://analytics.example.com",
+      question,
+      { apiKey: process.env.ANALYTICS_API_KEY },
+    );
+    return { answer: response };
+  },
+});
 ```
 
-The analytics agent receives the message, runs the query via its handler, and returns the result. The mail agent's script gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.
+The analytics agent receives the message, runs the query via its handler, and returns the result. The mail action gets the text response back. No shared database, no direct API calls — just agent-to-agent communication.

package/docs/content/actions.md

@@ -15,7 +15,7 @@ Actions are the single source of truth for anything your app does. Define an act
 - **An A2A tool** — called by other agent-native apps over A2A.
 - **A CLI command** — `pnpm action <name>` for scripting and dev loops.
 
-One definition, six consumers. This is rung 3 of the [ladder](/docs/what-is-agent-native#the-ladder).
+One definition, seven consumers. This is rung 3 of the [ladder](/docs/what-is-agent-native#the-ladder).
 
 ## Defining an action {#defining}
 
@@ -57,15 +57,17 @@ By default every action is exposed as `POST /_agent-native/actions/<name>`. Over
 export default defineAction({
   description: "Get details for a lead.",
   schema: z.object({ leadId: z.string() }),
-  http: { method: "GET", path: "leads/:leadId" }, // optional override
+  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`.
+
 - **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — default `POST`. `GET` actions are auto-marked `readOnly` so successful calls don't trigger a UI poll-refresh.
-- **`http: { path: "..." }`** — override the route path under `/_agent-native/actions/`. Defaults to the filename.
+- **`http: { path: "..." }`** — override the mounted URL under `/_agent-native/actions/`. Defaults to the filename. **Path overrides change the URL only 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 path overrides only for external HTTP callers. Note also 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`** — disable the HTTP endpoint entirely. Agent + CLI only.
 - **`readOnly: true`** — explicitly skip the poll-refresh even for POST actions that don't mutate.
 - **`parallelSafe: true`** — allow a mutating action to run concurrently with other same-turn tool calls. Only set this when the action is internally concurrency-safe and order-independent; mutating actions serialize by default.
@@ -133,7 +135,7 @@ export default defineAction({
 | `false`     | Explicit deny. The extension bridge returns 403; the action is still callable normally from the UI, agent, CLI, MCP, and A2A.                                                                                                                     |
 | `undefined` | **Default-allow.** Extensions are intra-org and typically authored by trusted teammates, so the default trusts the org-level access controls. Set `false` only for genuinely auth-adjacent operations (account deletion, org membership changes). |
 
-Enforcement: the parent host (`ToolViewer.tsx` / `EmbeddedTool.tsx` — physical class names retained) tags every outbound action call from an extension iframe with the header `X-Agent-Native-Tool-Bridge: 1`. The action route layer reads this header and applies the rule above. Regular UI/agent/CLI/A2A calls do not carry the header and are unaffected. The header is set by the React host; the iframe's user-authored content cannot spoof it because the bridge sanitizes iframe-supplied headers.
+Enforcement: the parent host tags every outbound action call from an extension iframe with the header `X-Agent-Native-Tool-Bridge: 1`. The action route layer reads this header and applies the rule above. Regular UI/agent/CLI/A2A calls do not carry the header and are unaffected. The header is set by the React host; the iframe's user-authored content cannot spoof it because the bridge sanitizes iframe-supplied headers.
 
 Set `toolCallable: false` for actions that:
 
@@ -169,12 +171,13 @@ export default defineAction({
 
 `ActionRunContext` fields:
 
-| Field       | Type                  | Notes                                                                                                                                                           |
-| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `userEmail` | `string \| undefined` | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
-| `orgId`     | `string \| null`      | Resolved org id, or `null` when the request has no org.                                                                                                         |
-| `caller`    | `ActionCaller`        | How the action was invoked (see below).                                                                                                                         |
-| `send`      | `(event) => void`     | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                   |
+| Field         | Type                    | Notes                                                                                                                                                           |
+| ------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `userEmail`   | `string \| undefined`   | Resolved request user. **Never defaulted to a dev identity** — `undefined` when the request has no authenticated user. Apply your own fallback if you need one. |
+| `orgId`       | `string \| null`        | Resolved org id, or `null` when the request has no org.                                                                                                         |
+| `caller`      | `ActionCaller`          | How the action was invoked (see below).                                                                                                                         |
+| `send`        | `(event) => void`       | Optional. Emit an SSE event to the client. Only present inside the agent tool loop (`caller: "tool"`); `undefined` elsewhere.                                   |
+| `attachments` | `AgentChatAttachment[]` | Files, images, and pasted text blocks submitted with the current agent turn. Populated only when `caller: "tool"`; `undefined` on all other surfaces.           |
 
 `caller` is the union `"tool" | "http" | "frontend" | "cli" | "mcp" | "a2a"`:
 
@@ -189,6 +192,35 @@ export default defineAction({
 
 `run` stays backward compatible: existing 1-argument handlers and handlers that only destructure `{ send }` continue to work unchanged.
 
+### Access control in actions {#access-control}
+
+User-owned tables must scope reads through `accessFilter` and writes through `assertAccess` — the same helpers the framework's sharing system uses. Here is a complete, paste-ready example:
+
+```ts
+// actions/create-lead.ts
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+import { getDb } from "../server/db/index.js";
+import * as schema from "../server/db/schema.js";
+
+export default defineAction({
+  description: "Create a lead in the CRM.",
+  schema: z.object({ name: z.string(), company: z.string() }),
+  run: async ({ name, company }, ctx) => {
+    const db = getDb();
+    await db.insert(schema.leads).values({
+      id: crypto.randomUUID(),
+      name,
+      company,
+      ownerEmail: ctx?.userEmail ?? "system",
+    });
+    return { ok: true };
+  },
+});
+```
+
+For list and read actions, use `accessFilter` to scope the query to the current user and org. For actions that update or delete a specific row, use `assertAccess` to confirm the caller is allowed before writing. See [Security](/docs/security#access-guards) and [Sharing](/docs/sharing) for the full helper API.
+
 ## Calling it from the UI {#ui}
 
 Two hooks, both in `@agent-native/core/client`. Types are inferred from your `defineAction` schemas — no manual type declarations.

package/docs/content/agent-mentions.md

@@ -65,23 +65,20 @@ Agents become available for mentioning through several mechanisms:
 
 ### Custom workspace agents
 
-Custom agents are Markdown resources:
+Custom agents are Markdown files stored in the workspace:
 
 ```markdown
 ---
 name: Design
-description: >-
-  Reviews layouts, product UX, and visual direction.
+description: Reviews layouts, product UX, and visual direction.
 model: inherit
-tools: inherit
-delegate-default: false
 ---
 
-# Role
-
 You are a focused design agent.
 ```
 
+See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format (including `tools`, `delegate-default`, and model overrides).
+
 You can create them from the Workspace tab using:
 
 - `Create Agent` -> `Describe It`
@@ -102,7 +99,9 @@ Remote A2A agents still use JSON manifests:
 }
 ```
 
-## Custom mention providers {#custom-mention-providers}
+---
+
+## For developers: extending mentions {#extending-mentions}
 
 Templates can register custom mention providers to add domain-specific mentionable items beyond agents and files. A mention provider implements the `MentionProvider` interface:
 

package/docs/content/agent-teams.md

@@ -9,6 +9,8 @@ The agent chat is an **orchestrator**, not a monolith. When the main agent hits
 
 This keeps the main thread focused, lets sub-agents run in parallel, and gives you a clean audit trail for any delegated work.
 
+Agent Teams runs on the core run-manager: events stream and persist, aborts propagate through SQL, and tasks survive serverless cold starts.
+
 ## The mental model {#mental-model}
 
 - **Main chat** — the orchestrator. Reads your request, delegates. Rarely does heavy work itself.
@@ -18,23 +20,6 @@ This keeps the main thread focused, lets sub-agents run in parallel, and gives y
 
 Sub-agent state is persisted in the `application_state` SQL table (under `agent-task:<taskId>`), so tasks survive serverless cold starts and work across multiple processes.
 
-Agent Teams runs on the same core `run-manager` as hosted
-agent chat: events are streamed and persisted, aborts propagate through SQL,
-heartbeats mark active work, and stale runs can be reaped consistently. New
-background-agent UIs should reuse `run-manager` or `spawnTask()` instead of
-introducing a separate runner with its own lifecycle rules.
-
-Agent-Native Code is the sibling local surface, not a second hosted-agent
-lifecycle. Code currently keeps long-running local sessions in the file-backed
-Code run store and exposes them through the shared background-run foundation.
-The CLI commands (`agent-native`, `agent-native code`, `resume`, `status`,
-`stop`, `ui`), the Desktop Code tab, background sessions, and sub-agent
-sessions should present the same run model even when their persistence layer is
-different. When a new surface needs both hosted sub-agents and local Code
-sessions, adapt those sources into the shared background-run/run-manager
-vocabulary instead of adding another queue, transcript model, or process
-tracker.
-
 ## When to spawn a sub-agent {#when-to-spawn}
 
 Spawn when the task:
@@ -58,7 +43,17 @@ Custom agents live in the workspace at `agents/<slug>.md` — a Markdown file wi
 
 ### 2. The main agent delegates automatically {#auto-delegate}
 
-The framework gives the main agent a `delegate-to-agent` tool. When the model decides a task fits a registered sub-agent profile, it calls the tool. A chip appears; the sub-agent runs. The main agent waits (or moves on in parallel) and incorporates the result when the sub-agent finishes.
+The framework gives the main agent an `agent-teams` tool. When the model decides a task fits a registered sub-agent profile, it calls the tool with `action: "spawn"` and an optional `agent` parameter naming a profile from `agents/*.md`. A chip appears; the sub-agent runs. The main agent waits (or moves on in parallel) and incorporates the result when the sub-agent finishes.
+
+The full `agent-teams` action set is:
+
+| Action        | Purpose                              |
+| ------------- | ------------------------------------ |
+| `spawn`       | Start a new sub-agent task           |
+| `status`      | Check a running sub-agent's progress |
+| `read-result` | Get a finished sub-agent's output    |
+| `send`        | Message a running sub-agent          |
+| `list`        | See all tasks for the current user   |
 
 ### 3. Programmatic spawn {#programmatic-spawn}
 
@@ -73,12 +68,13 @@ const task = await spawnTask({
   ownerEmail: user.email,
   systemPrompt: mailAgentSystemPrompt,
   actions: mailActions,
-  apiKey: process.env.ANTHROPIC_API_KEY!,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
   parentSend: emit, // streaming sender for the parent chat response
 });
 ```
 
-Most app code won't call this directly — the framework does it under the hood for `@mentions` and for the `delegate-to-agent` tool. Reach for `spawnTask()` only when you're wiring a new entry point (e.g., a button that kicks off a background job that runs as a sub-agent).
+Most app code won't call this directly — the framework does it under the hood for `@mentions` and for the `agent-teams` tool. Reach for `spawnTask()` only when you're wiring a new entry point (e.g., a button that kicks off a background job that runs as a sub-agent).
 
 ## Task lifecycle {#lifecycle}
 
@@ -112,7 +108,7 @@ const task = await getTask(taskId); // single task
 const tasks = await listTasks(); // all tasks for the user (sorted newest first)
 ```
 
-`AgentTask` shape:
+`AgentTask` key fields:
 
 ```ts
 interface AgentTask {
@@ -124,36 +120,26 @@ interface AgentTask {
   summary: string; // full summary once completed
   currentStep: string; // latest step label (updated while running)
   createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
 }
 ```
 
 ## Custom agent profiles {#profiles}
 
-A custom agent is a Markdown file in the workspace:
+A custom agent is a Markdown file in the workspace. Minimal example:
 
 ```markdown
 ---
 name: Code Review
-description: >-
-  Reviews TypeScript PRs with a focus on correctness, type safety, and API design.
+description: Reviews TypeScript PRs for correctness and type safety.
 model: inherit
-tools: inherit
-delegate-default: true
 ---
 
-# Role
-
-You are a meticulous code reviewer. Focus on correctness, subtle type errors,
-and the public API surface. Be terse and concrete — cite file:line wherever
-you can.
-
-## Rules
-
-- Prefer "here's the bug" over "here's why this pattern is wrong."
-- Never LGTM silently; always summarize what you checked.
+You are a meticulous code reviewer. Be terse and concrete — cite file:line wherever you can.
 ```
 
-Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format.
+Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format including `tools`, `delegate-default`, and model overrides.
 
 ## What's next
 

package/docs/content/agent-web-surfaces.md

@@ -5,9 +5,9 @@ description: "Make public routes crawlable, readable, citable, and optionally ca
 
 # Agent Web Surfaces
 
-Agent Web surfaces make public Agent-Native routes easy for agents to crawl, read, cite, and eventually call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
+Agent Web surfaces make public Agent-Native routes easy for agents to crawl, read, cite, and call. The goal is not to make every app endpoint public. The goal is to publish a clean public surface for pages that are already public, while keeping private data and tool access behind explicit controls.
 
-The docs site is the reference implementation. It publishes:
+The docs site is the reference implementation. Today it ships:
 
 - `/robots.txt` with a crawler policy that allows retrieval but disallows training by default.
 - `/sitemap.xml` with absolute canonical URLs and `lastmod` when the source file exposes it.
@@ -15,10 +15,13 @@ The docs site is the reference implementation. It publishes:
 - Markdown mirrors such as `/docs/getting-started.md`.
 - `Accept: text/markdown` responses for public docs pages after a production build.
 - JSON-LD for base organization, website, and page metadata.
+- An audit CLI (`agent-native audit-agent-web`) that checks all of the above.
 
-## Configuration
+Setting `publicMcp: true` additionally exposes opted-in actions as a public MCP endpoint, allowing external agents to call them directly (see [MCP Protocol](/docs/mcp-protocol)).
 
-Add `agentWeb` under the existing workspace app config. The public route list is still derived from the app's route access settings; `agentWeb` controls how that public surface is represented to agents.
+## Configuration {#config}
+
+Add `agentWeb` under the existing workspace app config (in your app's `package.json` under the `agent-native` key — or equivalently `workspace.agentWeb`, `agentWeb`, or `root.agentWeb`). The public route list is still derived from the app's route access settings; `agentWeb` controls how that public surface is represented to agents.
 
 ```json
 {
@@ -49,7 +52,7 @@ Add `agentWeb` under the existing workspace app config. The public route list is
 
 For most apps, leave the defaults alone. If an app has any public route, `discoverable` defaults on. The default crawler policy is "discoverable, not trainable": search, user-triggered retrieval, coding agents, and autonomous browsing agents are allowed; training crawlers are disallowed.
 
-## Route Source Of Truth
+## Route source of truth {#route-source}
 
 Agent Web discovery follows the route access model:
 
@@ -60,11 +63,11 @@ Agent Web discovery follows the route access model:
 
 This keeps mixed apps natural. A forms app can expose a public form page and keep submissions private. A content app can expose published posts and keep the editor private. A docs site can expose everything except admin tools.
 
-## Public Pages Are Not Public Tools
+## Public pages are not public tools {#public-tools}
 
 Public page access and public tool access are separate. A route being public only means agents can read that route as HTML, Markdown, sitemap entries, llms entries, and structured data.
 
-To expose an action through a public agent protocol later, the action must opt in:
+To expose an action through a public agent protocol, the action must opt in:
 
 ```ts
 export default defineAction({
@@ -85,7 +88,7 @@ export default defineAction({
 
 `agentWeb.publicMcp` stays `false` by default. When public MCP is enabled, the server should expose only actions with `publicAgent.expose === true`, and should still exclude consequential or write actions unless the action and auth policy explicitly allow them.
 
-## Build-Time Files
+## Build-time files {#build-time}
 
 Framework utilities in `@agent-native/core/agent-web` generate the common files from one page list:
 
@@ -120,7 +123,7 @@ const files = buildAgentWebStaticFiles({
 
 Vite apps can use `createAgentWebVitePlugin` from `@agent-native/core/vite` to write those files into `public`, `dist`, `dist/client`, `dist/server/public`, or `build/client` during production builds.
 
-## Audit A Site
+## Audit a site {#audit}
 
 Use the CLI audit against a deployed site or a local production server:
 
@@ -141,3 +144,9 @@ The audit checks for:
 - No accidental 401/403 blocks for common agent retrieval user agents.
 
 The audit exits non-zero if a required public surface is missing.
+
+## What's next
+
+- [**Actions**](/docs/actions) — how to opt actions into the public agent protocol
+- [**MCP Protocol**](/docs/mcp-protocol) — the MCP surface that `publicMcp: true` enables
+- [**Deployment**](/docs/deployment) — where these static files are written during builds

package/docs/content/authentication.md

@@ -91,15 +91,7 @@ Templates that use `createGoogleAuthPlugin()` show a "Sign in with Google" page.
 
 ### OAuth State Signing {#oauth-state-secret}
 
-OAuth state envelopes (Google, Atlassian, Zoom) are HMAC-signed with `OAUTH_STATE_SECRET`. Set this to a random 32+ char value in production:
-
-```bash
-OAUTH_STATE_SECRET=$(openssl rand -hex 32)
-```
-
-If unset, the framework falls back to `BETTER_AUTH_SECRET`. A dedicated `OAUTH_STATE_SECRET` is recommended so rotating one secret doesn't invalidate the other. Reusing a third-party client secret (e.g. `GOOGLE_CLIENT_SECRET`) for OAuth state signing is **not** supported — a leak of the third-party secret would let attackers forge state envelopes.
-
-`redirect_uri` query parameters on framework OAuth endpoints are validated against an allowlist (same-origin + framework `/_agent-native/...` paths). Custom OAuth flows in templates should use `isAllowedOAuthRedirectUri(candidate, event)` from `@agent-native/core/server` before signing state.
+Set `OAUTH_STATE_SECRET` to a random 32+ char value in production so OAuth state envelopes (Google, Atlassian, Zoom) are HMAC-signed with a dedicated key independent of any third-party secret. See [Security — OAuth State Signing](/docs/security#oauth-state) for the full requirements and threat model.
 
 ## Organizations {#organizations}
 
@@ -205,6 +197,7 @@ interface AuthSession {
   userId?: string; // Better Auth user ID
   token?: string; // Session token
   name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
   orgId?: string; // Active organization ID
   orgRole?: string; // Role in active org (owner/admin/member)
 }
@@ -258,18 +251,15 @@ When an anonymous user navigates directly to a private path like `/dashboard`, t
 
 Both flows (the explicit `/_agent-native/sign-in` entrypoint and the bookmarked-path case) thread the return URL through the OAuth state. The state is HMAC-signed, so it can't be forged in transit. On the callback, the return URL is re-validated as same-origin before the redirect — so a leaked signing key still can't be turned into an open-redirect oracle.
 
-If your template wraps `/_agent-native/google/auth-url` directly (e.g. mail and calendar templates do, to widen scopes), accept a `?return=<path>` query and forward it as the sixth argument to `encodeOAuthState`:
+If your template wraps `/_agent-native/google/auth-url` directly (e.g. mail and calendar templates do, to widen scopes), accept a `?return=<path>` query and forward it via the options-object form of `encodeOAuthState`:
 
 ```typescript
 const returnUrl = getQuery(event).return;
-const state = encodeOAuthState(
+const state = encodeOAuthState({
   redirectUri,
-  undefined,
   desktop,
-  false,
-  undefined,
-  typeof returnUrl === "string" ? returnUrl : undefined,
-);
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
 ```
 
 The default `/_agent-native/google/auth-url` route does this automatically — only override if your template needs custom OAuth handling.
@@ -287,4 +277,3 @@ The default `/_agent-native/google/auth-url` route does this automatically — o
 | `ACCESS_TOKEN`                 | Static bearer fallback for MCP/connect clients; not browser auth                                                                  |
 | `ACCESS_TOKENS`                | Comma-separated static bearer fallbacks for MCP/connect clients; not browser auth                                                 |
 | `A2A_SECRET`                   | Shared secret for JWT-signed A2A cross-app identity verification and, when present, MCP OAuth access-token signing                |
-| `AUTH_DISABLED`                | Set to `true` to skip auth (infrastructure-level auth)                                                                            |

package/docs/content/automations.md

@@ -63,21 +63,21 @@ Each automation is a markdown file with YAML frontmatter and a body containing n
 
 ### Frontmatter fields {#frontmatter}
 
-| Field         | Type                                                   | Default      | Description                                          |
-| ------------- | ------------------------------------------------------ | ------------ | ---------------------------------------------------- |
-| `schedule`    | cron expression                                        | `""`         | Cron expression (required for schedule triggers)     |
-| `enabled`     | boolean                                                | `true`       | Whether the automation is active                     |
-| `triggerType` | `"schedule"` \| `"event"`                              | `"schedule"` | How the automation fires                             |
-| `event`       | string                                                 | _(optional)_ | Event name to subscribe to (event triggers only)     |
-| `condition`   | string                                                 | _(optional)_ | Natural-language condition evaluated before dispatch |
-| `mode`        | `"agentic"` \| `"deterministic"`                       | `"agentic"`  | Full agent loop vs. fixed action set                 |
-| `domain`      | string                                                 | _(optional)_ | Grouping tag (mail, calendar, clips, etc.)           |
-| `createdBy`   | email                                                  | _(auto)_     | Owner email                                          |
-| `orgId`       | string                                                 | _(auto)_     | Org scope; inherited from the creator's active org   |
-| `runAs`       | `"creator"` \| `"shared"`                              | `"creator"`  | Whose API key and permissions to use                 |
-| `lastRun`     | ISO timestamp                                          | _(managed)_  | Written by the dispatcher after each run             |
-| `lastStatus`  | `"success"` \| `"error"` \| `"running"` \| `"skipped"` | _(managed)_  | Latest outcome                                       |
-| `lastError`   | string                                                 | _(managed)_  | Error message if the last run failed                 |
+| Field         | Type                                                   | Default      | Description                                                                                                                                                  |
+| ------------- | ------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `schedule`    | cron expression                                        | `""`         | Cron expression (required for schedule triggers)                                                                                                             |
+| `enabled`     | boolean                                                | `true`       | Whether the automation is active                                                                                                                             |
+| `triggerType` | `"schedule"` \| `"event"`                              | `"schedule"` | How the automation fires                                                                                                                                     |
+| `event`       | string                                                 | _(optional)_ | Event name to subscribe to (event triggers only)                                                                                                             |
+| `condition`   | string                                                 | _(optional)_ | Natural-language condition evaluated before dispatch                                                                                                         |
+| `mode`        | `"agentic"` \| `"deterministic"`                       | `"agentic"`  | Full agent loop. (`"deterministic"` is reserved but not yet implemented — automations that set it are skipped. Use `"agentic"` for all current automations.) |
+| `domain`      | string                                                 | _(optional)_ | Grouping tag (mail, calendar, clips, etc.)                                                                                                                   |
+| `createdBy`   | email                                                  | _(auto)_     | Owner email                                                                                                                                                  |
+| `orgId`       | string                                                 | _(auto)_     | Org scope; inherited from the creator's active org                                                                                                           |
+| `runAs`       | `"creator"` \| `"shared"`                              | `"creator"`  | Whose API key and permissions to use                                                                                                                         |
+| `lastRun`     | ISO timestamp                                          | _(managed)_  | Written by the dispatcher after each run                                                                                                                     |
+| `lastStatus`  | `"success"` \| `"error"` \| `"running"` \| `"skipped"` | _(managed)_  | Latest outcome                                                                                                                                               |
+| `lastError`   | string                                                 | _(managed)_  | Error message if the last run failed                                                                                                                         |
 
 ## The event bus {#event-bus}
 
@@ -235,8 +235,36 @@ Additional tool: `web-request` — outbound HTTP with `${keys.NAME}` substitutio
    - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
 4. The automation is saved as `jobs/slack-on-builder-booking.md` and begins listening immediately.
 
+## More examples {#more-examples}
+
+### Notify via webhook when a plan is commented on
+
+Ask the plan agent: _"When someone adds a human comment on a plan, POST a
+notification to my webhook."_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+Set `NOTIFY_WEBHOOK` to any HTTP endpoint — a Slack incoming webhook, a generic
+notification service, or a custom receiver. The `web-request` tool resolves
+`${keys.NOTIFY_WEBHOOK}` server-side; the raw URL never appears in the agent's
+context. See [Visual Plans — Events and notifications](/docs/template-plan#events)
+for the full `plan.commented` payload reference and all four plan events.
+
 ## What's next
 
 - [**Recurring Jobs**](/docs/recurring-jobs) — schedule-triggered automations reuse the same scheduler
 - [**Actions**](/docs/actions) — automations can call any registered action via the agent loop
 - [**Security**](/docs/security) — input validation and secret handling
+- [**Visual Plans — Events**](/docs/template-plan#events) — plan events reference and automation recipes