@agent-native/core 0.111.4 → 0.113.0

package/dist/templates/default/.agents/skills/integration-webhooks/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: integration-webhooks
+description: >-
+  Cross-platform pattern for handling messaging integration webhooks (Slack,
+  Telegram, WhatsApp, email, etc.) on serverless hosts. Use when adding a new
+  integration adapter, debugging dropped messages, or wiring long-running agent
+  work into a webhook handler.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Integration Webhooks
+
+## Rule
+
+Integration webhooks (Slack, Telegram, WhatsApp, email, Google Docs, etc.) must
+**enqueue work to SQL and return 200 immediately**, then process the work in a
+**separate fresh function execution** kicked off by a self-fired HTTP POST. A
+recurring retry job sweeps anything that gets stuck. This pattern works on every
+serverless host (Netlify, Vercel, Cloudflare Workers, Fly, Render, Node) without
+relying on platform-specific background-execution features.
+
+Do not run agent loops inside the webhook handler itself. Do not rely on
+fire-and-forget `Promise`s after `return`ing from a serverless handler — they get
+killed when the function freezes.
+
+## Why
+
+Messaging platforms expect a 200 response within a tight window — Slack will
+retry after 3 seconds, and a retried event triggers duplicate agent runs. At the
+same time, an agent loop replying to the message can take 30–60+ seconds because
+it may make multiple LLM calls and tool calls.
+
+Past attempts that don't work cross-host:
+
+- **Fire-and-forget `Promise.then(...)` after returning** — Lambda/Vercel/CF
+  freeze the execution context the moment the response goes out. The promise
+  is silently killed, the user gets no reply, and there's no error in the
+  logs.
+- **Netlify Background Functions** — Netlify-only, requires a `-background`
+  filename suffix, breaks on every other host.
+- **Cloudflare `event.waitUntil()`** — CF Workers only, not portable.
+- **Vercel Fluid / `after()`** — Vercel-only, gated behind specific runtimes.
+- **A long-lived in-process queue** — fine on a single Node box, but on
+  serverless every cold start gets a fresh queue and any pending work is
+  lost.
+
+The only universal answer: **persist the work, then trigger a brand new
+function execution to do it.** SQL is the queue, a self-webhook is the trigger,
+and a recurring job is the safety net.
+
+## The Flow
+
+```
+┌──────────┐    1. POST /integrations/:platform/webhook
+│ Platform │────────────────────────────────────────────►┌──────────────────┐
+└──────────┘                                             │ Webhook handler  │
+                                                         │ (function exec 1)│
+                                                         └──────────────────┘
+                                                                  │
+                            2. INSERT INTO integration_pending_tasks
+                                 (status='pending', payload=...)
+                                                                  │
+                            3. fetch(POST /integrations/_process-task)
+                                 — fire-and-forget, NO await on body
+                                                                  │
+                            4. return 200 to platform ◄───────────┘
+
+                                                         ┌──────────────────┐
+                          5. POST arrives at processor   │ Processor        │
+                             (separate fresh function)   │ (function exec 2)│
+                                                         └──────────────────┘
+                                                                  │
+                            6. claimPendingTask(id) → status='processing'
+                            7. runAgentLoop(...) — full timeout budget here
+                            8. adapter.sendResponse(...) back to platform
+                            9. markTaskCompleted(id)
+
+
+                          ┌──────────────────────────────────────────────┐
+                          │  Recurring job (every 60s) — safety net      │
+                          │  Re-fires processor for tasks stuck in       │
+                          │  'pending' or 'processing' beyond timeout.   │
+                          │  Caps retries at 3 then marks 'failed'.      │
+                          └──────────────────────────────────────────────┘
+```
+
+The webhook handler does as little as possible. The fresh function execution
+that handles `_process-task` gets its own full timeout budget for the agent
+loop.
+
+## Key Files
+
+| File                                                                    | Purpose                                                                |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `packages/core/src/integrations/plugin.ts`                              | Mounts `/_agent-native/integrations/*` routes                          |
+| `packages/core/src/integrations/webhook-handler.ts`                     | Verifies signature, parses, enqueues task, fires processor             |
+| `packages/core/src/integrations/pending-tasks-store.ts`                 | SQL queue: `insertPendingTask`, `claimPendingTask`, `markTaskCompleted`, `markTaskFailed` |
+| `packages/core/src/integrations/pending-tasks-retry-job.ts`             | Recurring retry sweep (`startPendingTasksRetryJob`, `retryStuckPendingTasks`) |
+| `packages/core/src/integrations/types.ts`                               | `PlatformAdapter`, `IncomingMessage`, `OutgoingMessage`                |
+| `packages/core/src/integrations/adapters/{slack,telegram,whatsapp,email,google-docs}.ts` | One adapter per platform                                               |
+
+## Routes
+
+All under `/_agent-native/integrations/`:
+
+| Method | Path                       | Purpose                                                       |
+| ------ | -------------------------- | ------------------------------------------------------------- |
+| POST   | `/:platform/webhook`       | Platform pings this. Verifies, enqueues, returns 200 quickly. |
+| POST   | `/_process-task`           | Self-webhook target. Claims a task and runs the agent loop.   |
+| GET    | `/status`                  | All integrations status (settings UI).                        |
+| GET    | `/:platform/status`        | One platform's status.                                        |
+| POST   | `/:platform/enable`        | Enable an integration.                                        |
+| POST   | `/:platform/disable`       | Disable an integration.                                       |
+| POST   | `/:platform/setup`         | Platform-specific setup (e.g. Telegram webhook registration). |
+
+## SQL Schema
+
+The pending-task queue lives in `integration_pending_tasks`:
+
+```sql
+CREATE TABLE IF NOT EXISTS integration_pending_tasks (
+  id                 TEXT    PRIMARY KEY,
+  platform           TEXT    NOT NULL,
+  external_thread_id TEXT    NOT NULL,
+  payload            TEXT    NOT NULL,   -- JSON-serialized IncomingMessage
+  owner_email        TEXT    NOT NULL,
+  org_id             TEXT,
+  status             TEXT    NOT NULL,   -- pending | processing | completed | failed
+  attempts           INTEGER NOT NULL DEFAULT 0,
+  error_message      TEXT,
+  created_at         INTEGER NOT NULL,
+  updated_at         INTEGER NOT NULL,
+  completed_at       INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_pending_tasks_status_created
+  ON integration_pending_tasks(status, created_at);
+```
+
+The store layer creates this lazily on first use via `ensureTable()` and uses
+`intType()` from `db/client.ts` so it works on both SQLite and Postgres.
+
+`claimPendingTask` is the critical concurrency primitive: it atomically flips
+`pending` → `processing` and increments `attempts`, returning `null` if another
+worker beat us to it. Both the initial fire-and-forget call and the retry job
+funnel through the same processor endpoint, and `claimPendingTask` is what
+prevents the same task from being processed twice.
+
+## Adding a New Platform Adapter
+
+1. **Implement `PlatformAdapter`** in `packages/core/src/integrations/adapters/<platform>.ts`:
+
+   ```ts
+   export function myPlatformAdapter(): PlatformAdapter {
+     return {
+       platform: "myplatform",
+       label: "MyPlatform",
+       getRequiredEnvKeys: () => [
+         { name: "MYPLATFORM_TOKEN", label: "MyPlatform Bot Token", scope: "global" },
+         { name: "MYPLATFORM_SIGNING_SECRET", label: "MyPlatform Signing Secret", scope: "global" },
+       ],
+       async handleVerification(event) {
+         // Platform-specific challenge response, if any
+         return { handled: false };
+       },
+       async verifyWebhook(event) {
+         // Verify HMAC/signature with a server-side secret and constant-time comparison.
+         // Never leave this as a permissive stub in production.
+         return verifyMyPlatformSignature(event);
+       },
+       async parseIncomingMessage(event) {
+         // Map raw payload → IncomingMessage, or null to ignore
+         return null;
+       },
+       async sendResponse(message, context) {
+         // POST back to the platform's API
+       },
+       formatAgentResponse(text) {
+         return { text, platformContext: {} };
+       },
+       async getStatus(baseUrl) {
+         return { platform: "myplatform", label: "MyPlatform", enabled: false, configured: false };
+       },
+     };
+   }
+   ```
+
+2. **Register it** in `getDefaultAdapters()` inside `plugin.ts`. The webhook,
+   queue, processor, and retry job are shared infrastructure — you do not
+   write any of that per-adapter.
+
+3. **Declare required env keys** so the secrets/onboarding UI surfaces them.
+   See `secrets` and `onboarding` skills.
+
+4. **Update the platform's webhook URL** to point at
+   `${baseUrl}/_agent-native/integrations/<platform>/webhook`. For platforms
+   with a registration API (Telegram), implement `POST /:platform/setup`.
+
+Never hardcode bot tokens, signing secrets, verification tokens, webhook URLs,
+channel/customer identifiers, or copied platform payloads with real private data
+inside the adapter, tests, docs, prompts, or fixtures. `getRequiredEnvKeys()`
+declares credential names only. Values come from deployment configuration,
+registered secrets, OAuth, or scoped credential stores, and tests should use
+obvious fake placeholders.
+
+The adapter is **only** responsible for:
+
+- platform-specific verification (signatures, challenges)
+- payload → `IncomingMessage` mapping
+- agent text → platform format
+- delivering the response back to the platform
+
+It does **not** know about the queue, the processor, retries, or the agent
+loop. Those are handled by the shared webhook handler.
+
+### Slack non-message events
+
+Slack's Events API also sends events that are not agent messages, such as
+`link_shared` for app unfurls. Do not map those into `IncomingMessage` unless
+they should actually run the agent. Handle them as short, provider-specific
+webhook work: verify the Slack signature, return `200 OK` quickly, and call the
+provider API needed for the event (`chat.unfurl` for link previews). If a single
+Slack app must handle both agent chat and app unfurls, put a dispatcher in front
+of the one Slack Events Request URL and route message events to the integration
+webhook flow while routing `link_shared` to the app-specific unfurl handler.
+
+## Long-Running Agent Work
+
+The processor endpoint runs in a fresh function execution with its own full
+timeout (typically 30–60s on Netlify/Vercel, longer on background-friendly
+hosts). That budget is dedicated entirely to the agent loop — there is no
+platform-side timer racing it.
+
+If a single agent run might exceed the function timeout (large multi-step
+plans, deep delegation chains), the agent should:
+
+1. Send an interim acknowledgement back to the platform so the user knows the
+   request landed (`adapter.sendResponse({ text: "Working on it..." })`).
+2. Persist intermediate state in chat-thread data, application state, or a
+   recurring job so the next invocation can pick up where this one left off.
+
+The retry job will only re-fire tasks stuck in `processing` for over 5 minutes,
+so a normal long-running reply is safe.
+
+## Cross-Platform Considerations
+
+- **No platform-specific background APIs.** No `waitUntil`, no
+  `-background.ts` filenames, no Vercel `after()`. The pattern works
+  identically on every host because it only uses `fetch()` and SQL.
+- **No assumed runtime.** The processor endpoint is a normal H3 handler under
+  `/_agent-native/`. It runs wherever the rest of the framework runs.
+- **No persistent in-memory state.** The dedup map in the webhook handler is
+  best-effort only; the SQL queue is the source of truth. Any cold start
+  loses the dedup map but the queue stays consistent.
+- **Postgres + SQLite both supported.** `claimPendingTask` uses `RETURNING` on
+  Postgres and a re-read on SQLite. No platform-specific SQL.
+- **Self-webhook URL resolution.** The processor URL is built from
+  `WEBHOOK_BASE_URL`, `APP_URL`, or `URL` env vars (with `localhost:3000` as
+  the dev fallback). Templates that change their public URL must keep one of
+  these set.
+
+## Why Fire-and-Forget on Serverless Is Unreliable
+
+Even though the webhook handler does `fetch(processorUrl, ...)` without
+awaiting the response body, that initial dispatch is **not** guaranteed to
+complete before the function freezes. In practice it usually does — the TCP
+connect + write happens quickly — but the recurring retry job is the safety
+net for the cases where:
+
+- The serverless platform froze the handler before the outbound `fetch`
+  flushed its bytes.
+- The processor function 502'd or cold-started slow enough to time out.
+- The processor itself was killed mid-agent-loop (function timeout, container
+  shutdown, deploy mid-run).
+
+Tasks stuck in `pending` for >90s or `processing` for >5min get re-fired up to
+3 times. After 3 attempts they're marked `failed` permanently so we stop
+spamming the processor.
+
+**Never assume the initial fire-and-forget succeeded.** Always rely on the
+queue + retry job for at-least-once delivery.
+
+## Debugging Checklist
+
+1. **Platform sent the webhook?** Check the platform's delivery logs (Slack
+   admin, Telegram `getWebhookInfo`).
+2. **Webhook handler returned 200?** If not, the platform retries — look for
+   duplicate task rows. Signature failures return 401.
+3. **Task in the queue?** `SELECT * FROM integration_pending_tasks WHERE
+   external_thread_id = '...' ORDER BY created_at DESC LIMIT 5`.
+4. **Status?** `pending` means the processor never picked it up — check that
+   `_process-task` is reachable from the box itself (the self-fetch must work
+   over the public URL). `processing` for over 5 minutes means the processor
+   died mid-run — the retry job will pick it up.
+5. **Failed?** Check `error_message` and `attempts`. After 3 attempts the row
+   is parked at `failed` and won't be retried.
+6. **Reply not delivered?** The processor likely succeeded but
+   `adapter.sendResponse` failed — check the adapter's outbound logs.
+
+## Automation connectors
+
+Workflow systems such as n8n and Zapier are not messaging channels. Do not add
+them as `PlatformAdapter`s or route them through `provider-api`.
+
+For n8n-style workflow invocation and callbacks, use
+`@agent-native/core/automation` with static workflow IDs and allow-listed
+origins. Agents provide structured input, never a target URL or credential.
+Callbacks must verify a configured secret/signature, claim a durable event ID,
+enqueue work through the established queue, and acknowledge quickly.
+
+Zapier is blueprint-only unless the app implements Zapier's explicit REST Hook
+subscribe/unsubscribe contract or configures a separate Zapier MCP connection.
+Do not imply a generic Zapier workflow-execution API exists.
+
+## Related Skills
+
+- `server-plugins` — How `/_agent-native/` routes get mounted
+- `recurring-jobs` — Pattern the retry job follows
+- `actions` — When to use an action vs a webhook
+- `secrets` — Registering platform tokens
+- `onboarding` — Surfacing setup steps for each platform
+- `delegate-to-agent` — How the processor invokes the agent loop

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

@@ -0,0 +1,56 @@
+---
+name: onboarding
+description: >-
+  How to register user-facing setup steps (API keys, OAuth, connecting
+  third-party services) for the sidebar setup checklist. Use when adding a
+  feature that needs initial user configuration.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Onboarding Steps
+
+## Rule
+
+If a feature requires user-facing setup (API keys, OAuth, connecting a third-party service), register an onboarding step so it appears in the agent sidebar's setup checklist.
+
+Onboarding must point users to a secure credential path; it must never encode
+the credential value in source, docs, fixtures, prompts, or generated content.
+For API keys and service tokens, prefer `registerRequiredSecret()` from the
+`secrets` skill so the settings UI, encrypted storage, validation, and
+onboarding checklist stay in one place. For OAuth, check the scoped OAuth token
+store. Use deployment env vars only for deploy-level configuration, not
+per-user credentials.
+
+## Registering a Step
+
+```ts
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+import { hasOAuthTokens } from "@agent-native/core/oauth-tokens";
+
+registerOnboardingStep({
+  id: "gmail",
+  order: 100,
+  title: "Connect Gmail",
+  description: "Grant read/send access.",
+  methods: [
+    {
+      id: "oauth",
+      kind: "link",
+      primary: true,
+      label: "Sign in with Google",
+      payload: { url: "/_agent-native/google/auth-url" },
+    },
+  ],
+  isComplete: async (ctx) =>
+    ctx?.userEmail ? hasOAuthTokens("google", ctx.userEmail) : false,
+});
+```
+
+See `packages/core/docs/content/onboarding.md` for method kinds and built-in steps.
+
+## Related Skills
+
+- `adding-a-feature` — The four-area checklist; onboarding is often part of a new integration
+- `authentication` — Most onboarding steps involve OAuth or credentials

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

@@ -0,0 +1,273 @@
+---
+name: secrets
+description: >-
+  Declaratively register API keys and service credentials a template needs so
+  they appear in the agent sidebar settings UI and the onboarding checklist.
+  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
+  surfacing OAuth connections in the unified settings UI.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Secrets Registry
+
+## Non-negotiable rule
+
+Never hardcode credential values. Source, docs, tests, fixtures, prompts, seed
+data, and generated extension/app content may mention credential **names** such
+as `OPENAI_API_KEY`, but must not contain real API keys, tokens, webhook URLs,
+signing secrets, OAuth refresh tokens, or private Builder/customer data.
+
+Secret values are supplied at runtime through deployment configuration, the
+encrypted `app_secrets` vault, `saveCredential` / `resolveCredential`, OAuth, or
+`${keys.NAME}` substitution. Examples must use obvious placeholders such as
+`<OPENAI_API_KEY>` or `${keys.SLACK_WEBHOOK}`, not real-looking copied values.
+
+## When to use
+
+Use this for any external credential your template needs: API keys, service
+tokens, webhook secrets. It gives you:
+
+- A sidebar UI entry for each credential (masked input, rotate, test, delete).
+- Automatic onboarding-checklist items for `required: true` secrets.
+- A stable server-side read API (`readAppSecret`) that decrypts values on
+  demand.
+- Validator hooks for health-checking keys before save and from a Test button.
+
+## When NOT to use
+
+- OAuth flows that need to run the full authorization code exchange — use
+  `@agent-native/core/oauth-tokens` directly to save/refresh tokens. The
+  registry can still surface the OAuth connection in the sidebar by
+  registering a secret with `kind: "oauth"` — that just delegates status
+  lookup to oauth-tokens and renders a Connect button, no `app_secrets` row
+  is written.
+- Purely process-level env vars that are never user-facing (e.g. `NODE_ENV`,
+  deployment flags). Those belong in the onboarding `form` method or the
+  `envKeys` list in `core-routes-plugin`.
+
+## Registering a secret
+
+```ts
+// server/plugins/register-secrets.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerRequiredSecret } from "@agent-native/core/secrets";
+
+export default defineNitroPlugin(() => {
+  registerRequiredSecret({
+    key: "OPENAI_API_KEY",
+    label: "OpenAI API Key",
+    description: "Used for Whisper transcription of your recordings.",
+    docsUrl: "https://platform.openai.com/api-keys",
+    scope: "user",
+    kind: "api-key",
+    required: true,
+    validator: async (value) => {
+      const res = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${value}` },
+      });
+      return res.ok
+        ? { ok: true }
+        : { ok: false, error: `OpenAI rejected the key (HTTP ${res.status})` };
+    },
+  });
+});
+```
+
+### OAuth in the unified UI
+
+```ts
+registerRequiredSecret({
+  key: "GOOGLE_CONNECTED",
+  label: "Google account",
+  description: "Grants access to Gmail / Calendar APIs.",
+  scope: "user",
+  kind: "oauth",
+  required: true,
+  oauthProvider: "google", // must match the provider id in oauth-tokens
+  oauthConnectUrl: "/_agent-native/google/auth-url",
+});
+```
+
+The sidebar shows a Connect button instead of a text input; no `app_secrets`
+row is written — status is derived from `hasOAuthTokens("google")`.
+
+## Registered options
+
+| Field              | Type                                    | Purpose                                                                  |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
+| `key`              | `string`                                | Env-var style name (`OPENAI_API_KEY`). Also the storage key.             |
+| `label`            | `string`                                | Human-readable title in the sidebar.                                     |
+| `description`      | `string?`                               | Subtitle under the label.                                                |
+| `docsUrl`          | `string?`                               | "Get key" link rendered on the card.                                     |
+| `scope`            | `"user" \| "workspace"`                 | Per-user or shared across the active org.                                |
+| `kind`             | `"api-key" \| "oauth"`                  | Drives UI and storage behavior.                                          |
+| `required`         | `boolean?`                              | When true, an onboarding step is auto-injected.                          |
+| `validator`        | `(v) => Promise<boolean \| {ok,error}>` | Runs on save and from the Test button. Never log `v`.                    |
+| `oauthProvider`    | `string?` (oauth-kind only)             | Provider id in `oauth-tokens` that backs this entry.                     |
+| `oauthConnectUrl`  | `string?` (oauth-kind only)             | URL the Connect button points at.                                        |
+
+## Reading a secret from an action
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+import { readAppSecret } from "@agent-native/core/secrets";
+import { getRequestUserEmail } from "@agent-native/core/server";
+
+export default defineAction({
+  description: "Transcribe an audio file with Whisper",
+  schema: z.object({ fileUrl: z.string() }),
+  run: async ({ fileUrl }) => {
+    const email = await getRequestUserEmail();
+    if (!email) throw new Error("Not signed in");
+
+    const stored = await readAppSecret({
+      key: "OPENAI_API_KEY",
+      scope: "user",
+      scopeId: email,
+    });
+    const apiKey = stored?.value;
+    if (!apiKey) {
+      throw new Error(
+        "OPENAI_API_KEY is not set. Configure it in the sidebar settings.",
+      );
+    }
+
+    // …call OpenAI. NEVER log the key or include it in error messages.
+  },
+});
+```
+
+Rules:
+
+- **Never log the value.** The read layer enforces this server-side; your
+  code must do the same.
+- **Use env vars only for deploy-level secrets.** If a credential is
+  user-scoped, org-scoped, or workspace-scoped, read the scoped vault/credential
+  store. Do not add a `process.env` fallback that makes every user inherit one
+  deployment's key.
+- **Scope matches the registration.** `scope: "user"` → pass the user email.
+  `scope: "workspace"` → pass the active `orgId` from
+  `getOrgContext(event).orgId`.
+
+## HTTP routes
+
+Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
+
+- `GET /_agent-native/secrets` — list registered secrets with status (`set`
+  / `unset` / `invalid`), metadata, and — for set api-keys — the last 4
+  characters. Values are never returned.
+- `POST /_agent-native/secrets/:key` — body `{ value, scope?, scopeId? }`.
+  Runs the registered validator; returns 400 with the error on failure.
+- `DELETE /_agent-native/secrets/:key` — remove the stored value.
+- `POST /_agent-native/secrets/:key/test` — re-run the validator against the
+  currently stored value.
+
+## Storage & encryption
+
+- Values are stored in `app_secrets` (created on-demand; no migration
+  needed).
+- Encrypted at rest with AES-256-GCM. Key material is derived from
+  `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set (for example,
+  `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
+  `BETTER_AUTH_SECRET`. App-scoped keys are useful when a local multi-app
+  workspace connects one app to its production database without replacing the
+  shared local authentication secret. If none is set, the framework uses a
+  machine-local fallback and logs a one-time warning — set stable key material
+  in production and in every runtime that reads the same encrypted data.
+
+## Ad-hoc Keys
+
+Ad-hoc keys are user-created secrets that are not declared by the template.
+Users create them through the settings UI or the agent chat to use with
+automations and the `web-request` tool. They support `${keys.NAME}`
+substitution in outbound HTTP requests.
+
+### Ad-hoc API
+
+Core routes plugin mounts these under `/_agent-native/secrets/adhoc`:
+
+- `GET /_agent-native/secrets/adhoc` — list all ad-hoc keys (name, last 4
+  chars, URL allowlist). Values are never returned.
+- `POST /_agent-native/secrets/adhoc` — body `{ name, value, urlAllowlist? }`.
+  Creates or updates an ad-hoc key.
+- `DELETE /_agent-native/secrets/adhoc/:name` — remove an ad-hoc key.
+
+### URL Allowlists
+
+Each ad-hoc key can have a URL allowlist — an array of origin URLs that
+restrict where the key's value can be sent. The check is origin-level
+(scheme + host + port). If no allowlist is configured, the key can be used
+with any URL.
+
+```ts
+// Creating a key with an allowlist
+POST /_agent-native/secrets/adhoc
+{
+  "name": "SLACK_WEBHOOK",
+  "value": "<SLACK_WEBHOOK_URL_FROM_SETTINGS>",
+  "urlAllowlist": ["https://hooks.slack.com"]
+}
+```
+
+### `${keys.NAME}` Substitution
+
+The `web-request` tool supports `${keys.NAME}` placeholders in the URL,
+headers, and body. Substitution happens server-side after the agent emits
+the tool call — the raw secret value never enters the agent's context.
+
+```ts
+import {
+  resolveKeyReferences,
+  validateUrlAllowlist,
+} from "@agent-native/core/secrets/substitution";
+
+// Resolve all ${keys.NAME} references in a string
+const { resolved, usedKeys } = await resolveKeyReferences(
+  "Bearer ${keys.API_TOKEN}",
+  "user",
+  "user@example.com",
+);
+
+// Validate a URL against a key's allowlist
+const allowed = validateUrlAllowlist(
+  "https://hooks.slack.com/services/<WORKSPACE>/<CHANNEL>/<SECRET>",
+  ["https://hooks.slack.com"],
+);
+```
+
+Key resolution falls back from user scope to workspace scope, so users can
+override shared keys without breaking automations that reference workspace
+defaults.
+
+## Dispatch Vault Access
+
+Dispatch workspaces have a vault access policy for workspace app credentials:
+
+- `all-apps` is the default. Every saved Dispatch vault key is available to
+  every workspace app; `sync-vault-to-app` pushes all vault keys to the target
+  app.
+- `manual` requires explicit per-app grants. Use
+  `create-vault-grant` / `grant-vault-secrets-to-app`, then
+  `sync-vault-to-app`.
+
+Use `get-vault-access-settings` before deciding whether to create grants, and
+use `set-vault-access-settings` only when the user asks to change the policy.
+
+### Key Files (ad-hoc)
+
+| File                                           | Purpose                                     |
+| ---------------------------------------------- | ------------------------------------------- |
+| `packages/core/src/secrets/substitution.ts`    | `resolveKeyReferences()`, `validateUrlAllowlist()` |
+| `packages/core/src/tools/fetch-tool.ts`        | `web-request` tool consuming key references |
+
+## Related skills
+
+- `onboarding` — the setup checklist that required secrets show up in.
+- `actions` — where you'll read secrets when calling third-party APIs.
+- `authentication` — session scoping; `scope: "user"` uses the session
+  email.
+- `security` — input validation and never logging secrets.
+- `automations` — ad-hoc keys power `${keys.NAME}` in automation web requests.