@agent-native/core 0.152.0 → 0.153.0

package/corpus/templates/content/docs/solutions/evidence/content-text-selector/README.md

@@ -0,0 +1,26 @@
+# Content text selector visual evidence
+
+Matched desktop captures for the compact Text/H1-H4 selector in the Content editor.
+
+## Before
+
+- Source revision: `dcc028cb7d67a0f9279f9235cdc4c16710ce5689`
+- Route: `http://127.0.0.1:3317/page/j4a5KAEDBHXY`
+- Viewport: `1496 x 846`, desktop Chrome
+- Fixture account: disposable local account `toolbar-demo@example.com`
+- Fixture page: `Toolbar comparison`
+- Fixture paragraph: `Select this sentence to compare the formatting toolbar.`
+- UI state: Personal workspace expanded, agent panel closed, full paragraph selected, formatting bubble open, text-style submenu closed
+
+![Before: separate H1-H4 toolbar buttons](./before.png)
+
+## After
+
+- Source: this pull request's production build
+- Route: `http://127.0.0.1:3317/page/vDisteHisXMq`
+- Viewport: `1496 x 846`, desktop Chrome
+- Fixture account, page title, paragraph, sidebar state, and agent-panel state match the before capture
+- UI state: full paragraph selected, formatting bubble open, Text selector expanded, Text checked, H1-H4 visible
+- The route differs because the isolated worktree uses its own disposable local fixture database; the rendered fixture and viewport are matched
+
+![After: compact Text selector with H1-H4 menu](./after.png)

package/corpus/templates/content/shared/api.ts

@@ -6,7 +6,12 @@ import type {
   DocumentPropertyVisibility,
 } from "./properties";
 
-export type DocumentAccessRole = "owner" | "viewer" | "editor" | "admin";
+export type DocumentAccessRole =
+  | "owner"
+  | "viewer"
+  | "commenter"
+  | "editor"
+  | "admin";
 
 export interface ContentContextPathEntry {
   id: string;
@@ -30,6 +35,7 @@ export interface Document {
   visibility?: "private" | "org" | "public";
   accessRole?: DocumentAccessRole;
   canView?: boolean;
+  canComment?: boolean;
   canEdit?: boolean;
   canManage?: boolean;
   source?: DocumentSourceInfo;

package/corpus/templates/crm/.agents/skills/actions/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: actions
+description: >-
+  How to create and run agent actions. Actions are the single source of truth
+  for app operations — the agent calls them as tools and frontend code calls
+  them through client hooks. Use when creating a new action, adding an API
+  integration, or wiring up frontend data fetching.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Actions
+
+## Rule
+
+Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, the frontend calls them through `useActionQuery` / `useActionMutation`, and the framework owns the HTTP transport behind those hooks — no duplicate `/api/` routes.
+
+Before creating any custom route for app data, check `actions/` and the action table in `AGENTS.md`. An action already exists? Call it directly. Missing? Create or update a `defineAction`. **Stop trigger:** about to add a file under `server/routes/api/` (or middleware to guard one)? Check it against the exception list in *Custom `/api/` Routes* below first — even if you already started the route.
+
+## Keep Actions Deterministic
+
+An action may call a provider API, validate data, and persist records without being an AI feature — keep it deterministic, focused, and independently useful to the agent. Don't put LLM calls or a second model runtime in ordinary actions (`completeText()` in `delegate-to-agent` is the one narrow exception).
+
+When a workflow is research, analysis, generation, recommendation, or synthesis — or spans several provider calls and writes — route it to the AgentSidebar via `sendToAgentChat({ openSidebar: true })` and let the agent orchestrate focused actions instead of hiding an AI-shaped workflow behind one opaque `generate-*`/`create-*` action just because its implementation happens to be deterministic.
+
+## How to Create an Action
+
+```ts
+// actions/list-meals.ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+import { getDb } from "../server/db/index.js";
+import { meals } from "../server/db/schema.js";
+
+export default defineAction({
+  description: "List all meals",
+  schema: z.object({
+    date: z.string().describe("Filter by date (YYYY-MM-DD)"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    // args is fully typed: { date: string }
+    const db = getDb();
+    const rows = await db.select().from(meals);
+    return rows; // Return objects/arrays, NOT JSON.stringify()
+  },
+});
+```
+
+`schema` (Zod or Standard Schema-compatible) gives runtime validation, TS inference for `run()` args, and an auto-generated JSON Schema for the tool. `.describe()` each param, `.optional()` for optional ones, `z.enum([...])` for constrained values, `z.coerce.number()` for numeric HTTP params — but write an explicit boolean parser instead of `z.coerce.boolean()`, which treats `"false"` as truthy.
+
+Use Drizzle's query builder, not raw SQL/`getDbExec()`/dialect-specific imports, unless Drizzle can't express the query. Never hardcode API keys/tokens/secrets — read via `readAppSecret` / `resolveCredential` / OAuth helpers; `process.env` is deploy-level config only.
+
+**Decision order:** existing action → extend/create a `defineAction` → custom route as last resort (*Custom `/api/` Routes* below). Actions are already callable by agents, CLIs, hooks, HTTP, and MCP/A2A — don't wrap them in an umbrella REST API.
+
+## Keep the Action Surface Small and Orthogonal
+
+Every agent-exposed action is a tool in the model's context window; more tools degrades tool-selection quality. Add the fewest, most orthogonal actions that cover the capability.
+
+- **One orthogonal `update` per resource**, not one per field — `update-<thing>` taking an optional-fields patch, not `update-<thing>-name` + `update-<thing>-order` + …
+- **Reach for a generic escape hatch before minting a new read action** — the `provider-api-catalog`/`docs`/`request` trio for provider data (`references/provider-apis.md`), `db-query` for ad hoc app-data reads in dev.
+- **`agentTool: false`** hides a UI-only/programmatic action from the model while keeping it frontend/HTTP-callable — not `toolCallable: false`, which only blocks the sandboxed extension bridge and leaves the action visible everywhere else; reserve that one for high-blast-radius operations.
+- **Delete or hide stale actions** once the UI stops using them; `pnpm actions:audit` advisory-flags likely-dead/redundant ones (`references/examples.md`).
+
+## The `http` Option
+
+Controls HTTP exposure:
+
+| Value | Behavior | Use for |
+| --- | --- | --- |
+| _(omitted)_ | `POST /_agent-native/actions/:name` | Write operations (default) |
+| `{ method: "GET" }` | `GET /_agent-native/actions/:name` | Read-only queries |
+| `{ method: "PUT"/"DELETE" }` | matching verb | Update / delete |
+| `{ method: "GET", path: "x" }` | custom route path | Non-default path |
+| `false` | never exposed as HTTP | `navigate`, `view-screen`, internal |
+
+Mutating actions (anything but `GET`) auto-refresh the UI on success — don't call `refresh-screen` after a normal action. Overrides (`readOnly`, `parallelSafe`) and exact trigger rules: `references/action-fields.md`.
+
+## Return Values
+
+Return **structured data** (objects, arrays), never `JSON.stringify()` — the framework serializes the response and only tries to parse a returned string as JSON, which isn't the same contract.
+
+```ts
+run: async (args) => await fetchEvents(args.from, args.to); // good
+run: async (args) => JSON.stringify(await fetchEvents(...)); // bad
+```
+
+Reach for `outputSchema` (validate the return), `_agentImages` (attach images the agent can see), `authorize` (gate who may call it), or `needsApproval` (require human sign-off per call) only when the action needs that guarantee — examples in `references/action-fields.md`.
+
+## Frontend Hooks
+
+Use hooks from `@agent-native/core/client`, not hand-written `fetch("/_agent-native/actions/...")`.
+
+```ts
+import { useActionQuery, useActionMutation, callAction } from "@agent-native/core/client/hooks";
+
+const { data: meals } = useActionQuery("list-meals", { date: "2025-01-01" }); // GET, types auto-inferred
+const { mutate } = useActionMutation("log-meal");                             // POST/PUT/DELETE
+mutate({ name: "Salad", calories: 350 });
+const people = await callAction("search-people", { query }, { method: "GET" }); // imperative (debounce, prefetch)
+```
+
+Don't add manual generics like `useActionQuery<Meal[]>(...)` — types come from `.generated/action-types.d.ts`. Mutations auto-invalidate all `["action"]` query keys, so GET queries refetch.
+
+## How to Run (Agent)
+
+```bash
+pnpm action my-action --input data/source.json --output data/result.json
+```
+
+The default template dispatches through core's `runScript()` in `actions/run.ts`. Action names are lowercase-with-hyphens (`pnpm action my-action` → `actions/my-action.ts`).
+
+## Custom `/api/` Routes
+
+Complete exception list — justified only when the caller isn't your own UI/agent, or the payload isn't JSON: **file uploads** (actions take JSON, not multipart), **streaming** (SSE/chunked needing direct H3 control), **webhooks**, **OAuth callbacks** (fixed redirect URL patterns), **public unauthenticated endpoints** (SEO/OG images, share links), **binary/non-JSON responses**.
+
+Everything else — CRUD, settings, search, list/detail reads, auth state, anything the UI fetches as JSON — is an action. Needing middleware to scope a route to the current user is itself a signal it should be an action. First-party templates still carry a shrinking, grandfathered set of older `/api/*` CRUD routes (`guard:no-action-twin-routes` ratchets it down) — not license to add new ones.
+
+## Do / Don't
+
+- **Do** keep one action, one job; document a reusable action (when to use it, key args, return fields to preserve) in `AGENTS.md` once it's called from outside one narrow screen; promote workflow-heavy actions (provider-backed, cross-app, MCP/A2A, multi-step) into a skill.
+- **Do** use `fail()` for user-friendly errors and import primitives from `@agent-native/core`(`/action`) instead of redefining them; use the core `upload-image` action or `uploadFile()` for durable images/files — never base64 into SQL, markdown, or action results.
+- **Don't** re-export actions as REST — `/_agent-native/actions/:name` is already the REST surface; duplicating it under `/api/*` hides the operation from agents.
+- **Don't** reach for provider integrations, `outputSchema`, `authorize`, `needsApproval`, or `_agentImages` without checking `references/` first — each has sharp edges covered there, not here.
+
+## Troubleshooting
+
+- **Action not found** — filename must match the command (`pnpm action foo-bar` → `actions/foo-bar.ts`).
+- **Args not parsing** — use `--key value` / `--key=value`; boolean flags are `--flag` (sets `"true"`).
+- **Frontend 405** — `http.method` doesn't match the hook (`useActionQuery` for GET, `useActionMutation` for POST/PUT/DELETE).
+- **Frontend gets undefined** — action must return structured data, not `JSON.stringify()`.
+
+## References
+
+- `references/provider-apis.md` — wiring a credentialed provider (HubSpot, Gong, Slack, …) for querying, reporting, or cross-source research.
+- `references/action-fields.md` — `outputSchema`, `authorize`, `needsApproval`, `_agentImages`, and exact auto-refresh rules.
+- `references/examples.md` — a second worked example, the legacy `parameters`/bare-export patterns, and `pnpm actions:audit`.
+
+## Related Skills
+
+- **storing-data** — Actions read/write data in SQL
+- **delegate-to-agent** — The agent invokes actions via `pnpm action <name>`
+- **real-time-sync** — Database writes from actions trigger change events to update the UI
+- **adding-a-feature** — Actions are area 2 of the four-area checklist
+- **client-methods** — Client code uses named helpers/hooks instead of raw REST calls

package/corpus/templates/crm/.agents/skills/actions/references/action-fields.md

@@ -0,0 +1,136 @@
+# Action Field Reference
+
+Full detail on the less-common `defineAction` fields and automatic behaviors.
+Read this when you need output validation, authorization, human approval,
+image results, or the exact rules for the auto-refresh behavior — the happy
+path in SKILL.md doesn't need any of these.
+
+## Screen Refresh (automatic)
+
+The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the framework emits a change event with `source: "action"` that the client's `useDbSync` picks up and uses to invalidate `["action"]` React Query keys — so `list-*` / `get-*` hooks refetch without a full page reload. In-process calls emit directly; dev-mode `pnpm action ...` calls also write a durable marker so the web server sees child-process action changes.
+
+Rules:
+
+- `http: { method: "GET" }` → read-only, does NOT trigger a refresh (inferred automatically).
+- Any other action (default `POST`, `PUT`, `DELETE`, or `http: false`) → treated as mutating, triggers a refresh on success.
+- To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
+- To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
+
+Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
+
+## Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
+## Validating Return Values (`outputSchema`)
+
+`schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.
+
+```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; "strict" | "fallback"
+  // outputFallback: { summary: "", messageCount: 0 }, // used only by "fallback"
+  run: async ({ threadId }) => {
+    /* ... */
+  },
+});
+```
+
+- `"warn"` (default) — `console.warn` the issues and return the **original** result unchanged. Non-breaking.
+- `"strict"` — throw a clear error so a buggy action surfaces loudly.
+- `"fallback"` — return `outputFallback` in place of the invalid result.
+
+On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
+
+## Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
+## Human-in-the-Loop Approval (`needsApproval`)
+
+For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:
+
+```ts
+export default defineAction({
+  description: "Send an email via Gmail.",
+  schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+  needsApproval: true, // boolean, or (args, ctx) => boolean | Promise<boolean>
+  run: async (args) => {
+    /* ...actually send... */
+  },
+});
+```
+
+When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
+
+**Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/crm/.agents/skills/actions/references/examples.md

@@ -0,0 +1,94 @@
+# Extra Examples, Legacy Pattern, and the Audit Script
+
+Read this for a second worked example beyond the one in SKILL.md, for the
+older bare-export action format you may find in existing code, or for the
+advisory dead-action audit tool.
+
+## Common Patterns
+
+**Read action (GET):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "List calendar events",
+  schema: z.object({
+    from: z.string().describe("Start date"),
+    to: z.string().describe("End date"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return await fetchEvents(args.from, args.to);
+  },
+});
+```
+
+**Write action (POST, default):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Log a meal",
+  schema: z.object({
+    name: z.string().describe("Meal name"),
+    calories: z.coerce.number().describe("Calorie count"),
+  }),
+  run: async (args) => {
+    // args.calories is a number — z.coerce.number() handles string-to-number conversion from HTTP
+    const meal = await insertMeal(args);
+    return meal;
+  },
+});
+```
+
+**Agent-only action:**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Navigate the UI to a view",
+  schema: z.object({
+    view: z.string().describe("Target view"),
+  }),
+  http: false,
+  run: async (args) => {
+    await writeAppState("navigate", { command: "go", view: args.view });
+    return "Navigated";
+  },
+});
+```
+
+## Legacy `parameters` Field
+
+Before Standard Schema support, `defineAction` took a plain JSON Schema object via `parameters` instead of a Zod `schema`. It still works — the action is still callable — but skips runtime validation and TypeScript inference. Migrate to `schema: z.object({...})` when you touch one of these.
+
+## Legacy Pattern (bare export)
+
+Older actions use a bare async function export with `parseArgs`:
+
+```ts
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  // ...
+}
+```
+
+This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all new actions.
+
+## Audit Script (Advisory)
+
+`pnpm actions:audit [template ...]` (or `node scripts/audit-template-actions.mjs`) statically scans a template's `actions/` and prints two kinds of suggestions:
+
+1. **Likely UI-dead** — HTTP-exposed mutating actions whose name is never referenced under `app/` (candidates to delete or mark `agentTool: false`).
+2. **Likely redundant clusters** — groups like `update-foo-name` / `update-foo-order` that could collapse into one orthogonal `update-foo`.
+
+It is **advisory only**: it always exits 0, never fails CI, and uses conservative heuristics, so expect some false positives (e.g. an action the agent calls but the UI doesn't). Use it as a prompt to review, not a gate.

package/corpus/templates/crm/.agents/skills/actions/references/provider-apis.md

@@ -0,0 +1,95 @@
+# Provider API Integrations
+
+Read this when an action needs to call an external provider API — HubSpot,
+Gong, Slack, any credentialed third-party service — for ad hoc analysis,
+querying, reporting, or cross-source research.
+
+For provider integrations used in ad hoc analysis, querying, reporting, or
+cross-source research, do not hardcode every provider endpoint as a separate
+rigid action and do not encode one lookback window, filter shape, or pagination
+strategy as the only path the agent can take. Expose the shared provider API
+action trio instead:
+
+- `provider-api-catalog`: lists provider base URLs, auth style, credential keys,
+  docs/spec URLs, placeholders, and examples without exposing secrets.
+- `provider-api-docs`: fetches public provider docs/spec/changelog URLs when
+  the exact endpoint, filter operator, payload shape, or pagination contract is
+  uncertain. Registered docs URLs are curated starting points. Use
+  `responseMode: "markdown"` for clean readable docs, or
+  `responseMode: "matches"` with `search: { query | terms | regex }` for
+  compact snippets instead of flooding context with raw HTML.
+- `provider-api-request`: makes a constrained authenticated HTTP request to the
+  provider host, injects configured credentials, blocks private/internal URLs,
+  and redacts secrets.
+
+Use `@agent-native/core/provider-api` as the shared substrate, and build these
+actions as thin factory imports rather than copying `defineAction` schemas and
+handlers into each template:
+
+```ts
+import {
+  createProviderApiCatalogAction,
+  createProviderApiDocsAction,
+  createProviderApiRequestAction,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import {
+  createDeleteStagedDatasetAction,
+  createListStagedDatasetsAction,
+  createQueryStagedDatasetAction,
+} from "@agent-native/core/provider-api/actions/staged-datasets";
+```
+
+Pass the app's existing provider runtime to the provider factories, and pass
+its app id to the staged-dataset factories. Keep app-specific descriptions,
+provider allow-lists, HTTP/tool-callability settings, and credential adapters
+as factory options. Only add a thin credential adapter when the app has
+app-specific credential lookup rules. If the app stores a built-in provider's
+OAuth grant under a narrower local provider id, use the runtime's
+`oauthProviderOverrides` instead of duplicating provider config. If credentials
+are stored on shareable/resource rows rather than in the shared credential or
+OAuth-token stores, build a resolver that enforces those access checks before
+exposing raw provider requests. Keep `provider-api-request` `http: false`
+unless a separate UI permission model authorizes arbitrary provider writes.
+Specific actions such as `search-records`, `search-emails`, or `sync-source`
+are convenience shortcuts, not capability limits; agents should fall back to
+the provider API trio when a question requires an endpoint or filter that the
+shortcut does not model.
+
+This is a framework tenet. The safety boundary should be provider host
+allow-listing, credential scoping, auth injection, private-network blocking,
+secret redaction, and user/org access checks, not an artificially small set of
+hand-authored read actions. If the upstream provider API supports a capability,
+the agent should normally be able to reach it through `provider-api-request`
+with the user's configured credentials. For large responses, expose staging
+(`stageAs`, `itemsPath`, pagination, and `query-staged-dataset`) or sandboxed
+code execution so the agent can reduce data without flooding context.
+
+For broad provider questions, cross-source joins, corpus-wide mention/search
+work, classification, or any answer where absence matters, design the action
+surface for full coverage instead of convenience-only samples. The agent should
+be able to fetch every relevant page or an explicitly bounded cohort, stage or
+save the raw provider response outside chat, and then use
+`query-staged-dataset`, `run-code`, or provider-side search to count, join,
+grep, classify, and aggregate. Tool descriptions and AGENTS.md guidance should
+teach agents to report source, filters, time window, row/record counts,
+pagination status, truncation, failed pages, and uncovered gaps. They must not
+turn default limits, sampled rows, truncated excerpts, or aborted calls into a
+confident "none found", "all records", or exhaustive conclusion.
+
+For public web pages and docs, prefer the token-efficient path: `web-search`
+to find likely URLs, `web-request` or `provider-api-docs` with clean
+`responseMode` output to read a page, and `run-code` with `webRead()` /
+`webFetch()` when you need to grep, aggregate, or compare many pages before
+returning a small result.
+
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.