@agent-native/core 0.52.0 → 0.54.0

package/README.md

@@ -1,6 +1,6 @@
 # Agent-Native
 
-### Agentic applications you own.
+### Open-source framework for agentic applications you own.
 
 Don't choose between rich user interfaces and autonomous agents. Every Agent-Native app is both.
 
@@ -20,15 +20,40 @@ The agent and the UI are equal citizens of the same system. Every action works b
 - **Any database, any host** — Any SQL database Drizzle supports. Any hosting target Nitro supports. No lock-in.
 - **Any AI agent** — Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, or Builder.io. Use whichever agent you prefer.
 
+## The framework for agent-native apps
+
+Agent-Native is an open-source framework for building robust agents that can act inside real apps, not just chat next to them.
+
+It gives you primitives for product-grade agentic software: shared actions, SQL-backed state, identity, tools, skills, jobs, observability, and UI surfaces that all work together.
+
+Backend agnostic: bring your own database, hosting provider, model stack, and app code.
+
+```ts
+// One action powers UI, agent, HTTP, MCP, A2A, and CLI.
+export default defineAction({
+  schema: z.object({
+    emailId: z.string(),
+    body: z.string(),
+  }),
+  run: async ({ emailId, body }) => {
+    await db.insert(replies).values({ emailId, body });
+  },
+});
+```
+
+- **Actions** — Define work once. Use it from UI, agent, API, MCP, A2A, and CLI.
+- **Agent runtime** — Chat, tools, skills, memory, jobs, observability, and handoffs ship together.
+- **Backend agnostic** — Plug in any Drizzle-supported SQL database and Nitro-compatible host.
+
 ## Try it with a skill
 
-Don't want to scaffold a whole app yet? Add agent-native superpowers to a coding agent you already use — Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, and similar agents — with one command:
+Don't want to scaffold a whole app yet? Add visual planning and PR recaps to Claude Code, Codex, Cursor, Pi, OpenCode, GitHub Copilot / VS Code, and similar agents with one command:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
 ```
 
-It installs the skills, writes shared `.agents` skill folders for agents that support them, registers the hosted MCP connector for supported local clients, and signs in the selected client(s) in one step. You get two slash commands that upgrade how your agent plans and reports its work:
+You get two slash commands that upgrade how your agent plans and reports its work:
 
 - **`/visual-plan`** — before the agent writes code, it opens a structured, reviewable plan document instead of a wall of text: inline diagrams, UI wireframes and prototypes, file-by-file implementation maps, and annotations you can comment on and approve.
 - **`/visual-recap`** — after changes land, it turns a PR or git diff into a high-altitude visual recap: schema, API, and file changes rendered as grounded before/after blocks with a shareable review link, instead of scrolling a raw diff.
@@ -37,30 +62,30 @@ See the **[Skills Guide](https://agent-native.com/docs/skills-guide#app-backed-s
 
 ## Templates
 
-Start from a complete, production-grade SaaS app — cloneable, not scaffolded. Each one replaces tools you're paying for, except you own everything and can customize it however you want. Not demos; products.
+Start with a full featured template. Each one is a complete, 100% free and open-source SaaS app — cloneable, not scaffolded — except you own the code and can customize everything.
 
 <table>
 <tr>
 <td width="33%" align="center" valign="top">
 
-**Mail**
+**Calendar**
 
-<a href="https://agent-native.com/templates/mail"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F6f49a81c404d4242b33317491eac7575?format=webp&width=800" alt="Mail template" width="100%" /></a>
+<a href="https://agent-native.com/templates/calendar"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Ffb6c3b483ca24ab3b6c3a758aeceef4c?format=webp&width=800" alt="Calendar template" width="100%" /></a>
 
-**Agent-Native Mail, Superhuman**
+**Agent-Native Google Calendar, Calendly**
 
-Superhuman-style email client with keyboard shortcuts, AI triage, and a fully customizable inbox you own.
+Manage events, sync with Google Calendar, and share a public booking page with AI scheduling.
 
 </td>
 <td width="33%" align="center" valign="top">
 
-**Calendar**
+**Content**
 
-<a href="https://agent-native.com/templates/calendar"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Ffb6c3b483ca24ab3b6c3a758aeceef4c?format=webp&width=800" alt="Calendar template" width="100%" /></a>
+<a href="https://agent-native.com/templates/content"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F89bcfc6106304bfbaf8ec8a7ccd721eb?format=webp&width=800" alt="Content template" width="100%" /></a>
 
-**Agent-Native Google Calendar, Calendly**
+**Open-source Obsidian for MDX**
 
-Manage events, sync with Google Calendar, and share a public booking page with AI scheduling.
+Edit local Markdown/MDX files, generate rich interactive custom blocks, and draft, rewrite, or publish with an agent.
 
 </td>
 <td width="33%" align="center" valign="top">
@@ -78,17 +103,6 @@ Install `/visual-plan` and `/visual-recap` so your coding agent can plan before
 <tr>
 <td width="33%" align="center" valign="top">
 
-**Content**
-
-<a href="https://agent-native.com/templates/content"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F89bcfc6106304bfbaf8ec8a7ccd721eb?format=webp&width=800" alt="Content template" width="100%" /></a>
-
-**Agent-Native Notion, Google Docs**
-
-Write and organize content with an agent that knows your brand and publishing workflow.
-
-</td>
-<td width="33%" align="center" valign="top">
-
 **Slides**
 
 <a href="https://agent-native.com/templates/slides"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F2c09b451d40c4a74a89a38d69170c2d8?format=webp&width=800" alt="Slides template" width="100%" /></a>
@@ -100,19 +114,6 @@ Generate and edit React-based presentations via prompt or point-and-click.
 </td>
 <td width="33%" align="center" valign="top">
 
-**Video**
-
-<a href="https://agent-native.com/templates/video"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F6b8bfcc18a1d4c47a491da3b2d4148a4?format=webp&width=800" alt="Video template" width="100%" /></a>
-
-**Agent-Native video editing**
-
-Create and edit Remotion video compositions with agent assistance.
-
-</td>
-</tr>
-<tr>
-<td width="33%" align="center" valign="top">
-
 **Analytics**
 
 <a href="https://agent-native.com/templates/analytics"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F4933a80cc3134d7e874631f688be828a?format=webp&width=800" alt="Analytics template" width="100%" /></a>
@@ -132,73 +133,18 @@ Connect analytics data sources, prompt for real charts, and build reusable dashb
 
 Record your screen with auto-transcripts, shareable links, and an agent that summarizes, captions, and edits clips on demand.
 
-</td>
-<td width="33%" align="center" valign="top">
-
-**Design**
-
-<a href="https://agent-native.com/templates/design"><img src="https://cdn.builder.io/api/v1/image/assets%2F348da13fcd8b414c87de9066196f7266%2F961bedb713a94463b834c1f2f4643bcf?format=webp&width=800" alt="Design template" width="100%" /></a>
-
-**Agent-Native Figma, Canva**
-
-Create and edit visual designs by prompt or by hand, with the agent as your co-designer.
-
-</td>
-</tr>
-<tr>
-<td width="33%" align="center" valign="top">
-
-**Dispatch**
-
-<a href="https://agent-native.com/templates/dispatch"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F104b3ad8d1dc461aa33ab9bff37a4482?format=webp&width=800" alt="Dispatch template" width="100%" /></a>
-
-**Mission control for agent-native apps**
-
-Message, manage, and delegate to agents from Slack, Telegram, or the web. Dispatch is also the control plane for vault secrets, reusable provider connections, app grants, routing, memory, and approvals.
-
-</td>
-<td width="33%" align="center" valign="top">
-
-**Forms**
-
-<a href="https://agent-native.com/templates/forms"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F190c3fabd51f4c1bba5aa4e091ad4e9b?format=webp&width=800" alt="Forms template" width="100%" /></a>
-
-**Agent-Native Typeform**
-
-Generate forms from a prompt, branch logic with the agent, and own every response in your own database.
-
-</td>
-<td width="33%" align="center" valign="top">
-
-**Brain**
-
-<a href="https://agent-native.com/templates/brain"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F9c9fe3b5b9494e33803cd3f494cba356?format=webp&width=800" alt="Brain template" width="100%" /></a>
-
-**Agent-Native company memory**
-
-Ask questions over cited company knowledge from approved Slack, meetings, transcripts, GitHub, and decisions.
-
-</td>
-</tr>
-<tr>
-<td width="33%" align="center" valign="top">
-
-**Assets**
-
-<a href="https://agent-native.com/templates/assets"><img src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F769092170a14474f998cbca47384f891?format=webp&width=800" alt="Assets template" width="100%" /></a>
-
-**Agent-Native asset library**
-
-Upload, organize, search, and generate on-brand image and video assets that other apps can reuse.
-
 </td>
 </tr>
 </table>
 
 Every template is a complete cloneable SaaS — fork it, customize it with the agent, own it. Try them with example data before connecting your own sources.
 
+View the full template gallery at **[agent-native.com/templates](https://agent-native.com/templates)**.
+
 ## Quick Start
 
+One command to fork a template and start building locally.
+
 ```bash
 npx @agent-native/core@latest create my-platform
 cd my-platform

package/blueprints/action/crud.md

@@ -0,0 +1,98 @@
+# Blueprint: add a new multi-surface action
+
+You are a coding agent working inside an **agent-native** app (a repo built on
+`@agent-native/core`). Apply this blueprint as real source changes on the
+current branch. Do not just describe the work — do it, then verify.
+
+## Goal
+
+Add a new app operation as a single `defineAction` so it is callable from **all
+surfaces at once**: the agent uses it as a tool, the frontend calls it through
+`useActionQuery` / `useActionMutation`, and HTTP/MCP/A2A get it for free. One
+implementation, every consumer — no duplicate `/api/*` route.
+
+Use this for a real capability your app is missing (e.g. `create-note`,
+`update-task`, `list-orders`). Replace `<thing>` below with the actual resource.
+
+## Read first
+
+Read the `actions` skill. The rules that matter most here:
+
+- Actions in `actions/` are the **single source of truth**. Before adding one,
+  grep `actions/` and `AGENTS.md` — extend an existing action if it already
+  covers the operation.
+- **Keep the surface small and orthogonal.** Prefer one CRUD-style
+  `update-<thing>` taking a patch of optional fields over N per-field actions.
+  One `create` / one `update` / one `delete` per resource.
+- Reach for a generic query / the provider-api trio before minting another read
+  action.
+
+## Files to touch
+
+1. **`actions/<verb>-<thing>.ts`** — one file, default-exporting a
+   `defineAction` with a **Zod** schema:
+
+   ```ts
+   import { z } from "zod";
+   import { defineAction } from "@agent-native/core";
+   import { getDb } from "../server/db/index.js";
+   import { things } from "../server/db/schema.js";
+
+   export default defineAction({
+     description: "Create a <thing>",
+     schema: z.object({
+       title: z.string().describe("Human-readable title"),
+       notes: z.string().optional(),
+     }),
+     // Omit `http` for the default POST; use { method: "GET" } for reads.
+     run: async (args, ctx) => {
+       const db = getDb();
+       // Return plain objects/arrays — never JSON.stringify().
+       return await db
+         .insert(things)
+         .values({ ...args })
+         .returning();
+     },
+   });
+   ```
+
+   - Use Drizzle's query builder and portable `drizzle-orm` operators — no raw
+     SQL, no dialect-specific imports, no `getDbExec()` for normal actions.
+   - Use `z.coerce.number()` for numeric HTTP params; for booleans use an
+     explicit string parser (not `z.coerce.boolean()`).
+   - If only the UI/HTTP needs it (not the model), set `agentTool: false` to
+     keep the model's tool list lean — it stays callable from the UI and HTTP.
+
+2. **If the resource is user-authored and shareable**, make its table ownable
+   and scope reads/writes. Read the `sharing` and `security` skills: tables with
+   `ownableColumns()` require `accessFilter` / `resolveAccess` / `assertAccess`
+   in the action, never an unscoped `select`/`update`.
+
+3. **Wire the UI** to the shared action surface with `useActionQuery`
+   (reads) / `useActionMutation` (writes). Do **not** hand-write `fetch` to a
+   framework or `/api/*` route — import the client hooks. Keep the UI optimistic:
+   update cache / navigate immediately and roll back on error.
+
+4. **Register the action** in whatever index the app uses (`actions/index.ts`
+   or the auto-discovery glob) and add it to the `AGENTS.md` action table if the
+   app maintains one.
+
+## Framework rules to honor
+
+- No `/api/*` or Nitro pass-through route whose job is to call/repackage this
+  action — that violates the Architecture Contract.
+- Never hardcode secrets/credentials; read them from the secret store at call
+  time. Use placeholders in any example.
+- Validate and scope all input; ownable tables fail closed without access
+  checks.
+- If this edits a publishable package's source, add a `.changeset/*.md`.
+
+## Verify
+
+1. `agent-native typecheck` (or `tsc --noEmit`) passes.
+2. From the agent chat, invoke the new action and confirm structured
+   input/output.
+3. From the UI, confirm the `useActionQuery` / `useActionMutation` path works and
+   stays optimistic.
+4. For ownable resources, confirm a non-owner cannot read or mutate another
+   user's row (access check fails closed).

package/blueprints/channel/discord.md

@@ -0,0 +1,74 @@
+# Blueprint: add a Discord inbound channel adapter
+
+You are a coding agent working inside an **agent-native** app (a repo built on
+`@agent-native/core`). Apply this blueprint as real source changes on the
+current branch. Do not just describe the work — do it, then verify.
+
+## Goal
+
+Let users talk to the agent from Discord: a Discord message hits a webhook, the
+framework enqueues the work, returns `200` fast, and a fresh function execution
+runs the full agent loop and posts the reply back. You implement a
+`PlatformAdapter` for Discord that slots into the existing integration-webhooks
+pipeline — you do **not** invent a new transport.
+
+## Read first
+
+Read the `integration-webhooks` skill end to end. The non-negotiable shape: the
+webhook handler **enqueues to SQL and returns 200 immediately**, then a
+self-fired POST runs the agent loop in a separate execution. Never run the agent
+loop inside the webhook handler; never rely on fire-and-forget `Promise`s after
+returning (serverless freezes the context).
+
+Study the existing adapters as the pattern to copy:
+
+- `packages/core/src/integrations/types.ts` — the `PlatformAdapter`,
+  `IncomingMessage`, `OutgoingMessage` contracts.
+- `packages/core/src/integrations/adapters/slack.ts` — the closest analog
+  (signature verification, parsing, response delivery).
+- `packages/core/src/integrations/adapters/telegram.ts` — a simpler reference.
+- `packages/core/src/integrations/plugin.ts` → `getDefaultAdapters()` — where
+  built-in adapters are registered into the route pipeline.
+
+## Files to touch
+
+1. **`packages/core/src/integrations/adapters/discord.ts`** — implement
+   `discordAdapter(): PlatformAdapter`:
+   - `platform = "discord"`, `label = "Discord"`.
+   - `getRequiredEnvKeys()` — declare `DISCORD_PUBLIC_KEY` (signature
+     verification) and `DISCORD_BOT_TOKEN` (sending), with UI hints so the
+     settings form renders them. Use obviously-fake placeholders in any docs.
+   - `handleVerification(event)` — answer Discord's `PING` interaction
+     (`type: 1`) with a `PONG` (`type: 1`).
+   - `verifyWebhook(event)` — verify the Ed25519 `X-Signature-Ed25519` /
+     `X-Signature-Timestamp` headers against `DISCORD_PUBLIC_KEY`. Fail closed.
+   - `parseMessage(event)` — map the interaction/message payload into a
+     normalized `IncomingMessage` (set `externalThreadId` to the channel/thread
+     id, `text`, `senderName`, `platformContext` with what you need to reply).
+     Return `null` to ignore bot messages and non-message events.
+   - `sendResponse(...)` — POST the agent reply back via the Discord API using
+     `DISCORD_BOT_TOKEN`, read at send time from the secret store.
+2. **Register it** in `getDefaultAdapters()` in
+   `packages/core/src/integrations/plugin.ts` alongside `slackAdapter()` etc.
+3. **Add `discord.spec.ts`** next to the adapter mirroring `slack.spec.ts`:
+   cover signature verification (valid + tampered), the PING/PONG verification
+   path, message parsing, and bot-message filtering.
+
+## Framework rules to honor
+
+- Do the minimum in the webhook handler; the agent loop runs in the
+  `_process-task` execution with its own timeout budget. Don't change that flow.
+- `senderVerified` must reflect real cryptographic sender authentication. Never
+  derive a privileged acting identity from an unverified sender — fail closed.
+- Never hardcode the bot token, public key, or signing secret in source, tests,
+  or fixtures. Use placeholders and read real values from the secret store.
+- This is a publishable `packages/core` source change → add a `.changeset/*.md`.
+
+## Verify
+
+1. `tsc --noEmit` for `@agent-native/core` passes.
+2. `discord.spec.ts` passes (`vitest --run src/integrations/adapters/discord`).
+3. End-to-end smoke: send a signed test interaction to
+   `/_agent-native/integrations/discord/webhook`; confirm a `200` returns
+   immediately, a task is enqueued, the processor runs the agent loop, and a
+   reply is delivered. A tampered signature must be rejected.

package/blueprints/provider/stripe.md

@@ -0,0 +1,87 @@
+# Blueprint: integrate the Stripe API
+
+You are a coding agent working inside an **agent-native** app (a repo built on
+`@agent-native/core`). Apply this blueprint as real source changes on the
+current branch. Do not just describe the work — do it, then verify.
+
+## Goal
+
+Let the agent (and the UI) talk to the Stripe API for ad-hoc reads — list
+charges, look up a customer, summarize subscriptions — **without minting one
+rigid action per endpoint**. Wire Stripe into the shared **provider-api
+substrate** so any endpoint/filter is reachable through a single, safe surface.
+
+## Why the provider-api substrate (read this first)
+
+The framework tenet (see `CLAUDE.md` → Architecture Contract and the `actions`
+skill): first-class actions are ergonomic shortcuts, **not** capability limits.
+Do not hardcode `list-stripe-charges`, `get-stripe-customer`,
+`list-stripe-subscriptions`, … Instead expose the provider-api trio so the agent
+can hit any Stripe endpoint with the user's configured credentials, behind host
+allow-listing, credential injection, private-network blocking, and secret
+redaction.
+
+The substrate lives in `@agent-native/core/provider-api`:
+
+- `provider-api-catalog` — lists provider base URLs, auth style, credential
+  keys, docs/spec URLs, placeholders, and examples (never secrets).
+- `provider-api-docs` — fetches the registered public docs/spec URLs when the
+  exact endpoint, filter, or payload is uncertain.
+- `provider-api-request` — makes one constrained authenticated request to the
+  provider host, injects the configured credential, blocks internal URLs, and
+  redacts secrets.
+
+## Files to touch
+
+1. **Register the Stripe provider config** wherever this app assembles its
+   provider catalog (grep for `providerApi`, `provider-api`, or `defineProvider`
+   under `actions/`, `server/`, or look at `templates/dispatch/actions/` for the
+   canonical wiring). Add an entry like:
+
+   ```ts
+   {
+     id: "stripe",
+     label: "Stripe",
+     baseUrl: "https://api.stripe.com",
+     auth: { type: "bearer", credentialKey: "STRIPE_SECRET_KEY" },
+     docsUrls: ["https://docs.stripe.com/api"],
+     // Obviously-fake placeholder only — never a real key.
+     placeholders: { STRIPE_SECRET_KEY: "sk_test_PLACEHOLDER_xxx" },
+     examples: [
+       "GET /v1/charges?limit=10",
+       "GET /v1/customers/{id}",
+       "GET /v1/subscriptions?status=active",
+     ],
+   }
+   ```
+
+2. **Expose the three provider-api actions** if the app does not already export
+   them. Re-use `@agent-native/core/provider-api`; do **not** re-implement the
+   request/redaction logic. Keep `provider-api-request` `http: false` unless this
+   app has a separate UI permission model for arbitrary provider writes.
+
+3. **Register the credential** so it shows in the agent settings/onboarding UI.
+   Read the `secrets` and `onboarding` skills. The Stripe secret key is read at
+   request time via `readAppSecret` / the provider credential adapter — never
+   `process.env` for per-user/org secrets, never a literal in source.
+
+## Framework rules to honor
+
+- No `/api/*` or Nitro pass-through routes that just call Stripe — that violates
+  the Architecture Contract. The provider-api actions are already callable from
+  the agent, the UI (`useActionMutation`), HTTP, and MCP.
+- Never hardcode the Stripe key, a webhook signing secret, or any
+  credential-looking literal in source, tests, fixtures, or docs. Use
+  `sk_test_PLACEHOLDER_xxx`-style fakes.
+- If you add a publishable-package source change, add a `.changeset/*.md`.
+- Keep the action surface small and orthogonal — the trio replaces a dozen
+  per-endpoint actions.
+
+## Verify
+
+1. `agent-native typecheck` (or `tsc --noEmit`) passes.
+2. With a placeholder `STRIPE_SECRET_KEY` set, ask the agent: "list my 5 most
+   recent Stripe charges." Confirm it calls `provider-api-catalog` →
+   (optionally) `provider-api-docs` → `provider-api-request` against
+   `api.stripe.com`, and that the response redacts secrets.
+3. Confirm the Stripe credential appears in the settings/onboarding checklist.

package/blueprints/sandbox/docker.md

@@ -0,0 +1,78 @@
+# Blueprint: implement a Docker sandbox adapter
+
+You are a coding agent working inside an **agent-native** app (a repo built on
+`@agent-native/core`). Apply this blueprint as real source changes on the
+current branch. Do not just describe the work — do it, then verify.
+
+## Goal
+
+Run the `run-code` tool's agent-supplied JavaScript inside a **Docker
+container** instead of a local child process, without touching the agent loop,
+`run-code.ts`, the localhost bridge, the env scrub, or the output formatting.
+You implement the `SandboxAdapter` seam and select it via
+`AGENT_NATIVE_SANDBOX` / `registerSandboxAdapter()`.
+
+## Read first
+
+Read these three files — they ARE the contract:
+
+- `packages/core/src/coding-tools/sandbox/adapter.ts` — the `SandboxAdapter`
+  interface plus `SandboxRunRequest` / `SandboxRunResult` / `SandboxEnv`.
+- `packages/core/src/coding-tools/sandbox/index.ts` — `getSandboxAdapter()`
+  resolution order (registered → `AGENT_NATIVE_SANDBOX` built-in → local
+  default) and `registerSandboxAdapter()`. Note the `// TODO: remote/durable
+adapter` block — that is exactly this work.
+- `packages/core/src/coding-tools/sandbox/local-child-process-adapter.ts` — the
+  reference implementation to mirror for timeout enforcement and stdout/stderr
+  capture.
+
+Key invariant: the adapter receives an **already-prepared, non-secret**
+`moduleSource` (it already embeds the loopback bridge URL/token and wraps the
+user's code) plus a scrubbed `env`. The adapter only **runs** it. It must never
+augment `env` with the parent's environment and never see app secrets.
+
+## Files to touch
+
+1. **`packages/core/src/coding-tools/sandbox/docker-adapter.ts`** — implement
+   `class DockerSandboxAdapter implements SandboxAdapter`:
+   - `readonly id = "docker"`.
+   - `run(request)`:
+     - Write `request.moduleSource` to a temp ESM file (or pass via stdin).
+     - Spawn `docker run --rm` with a minimal Node image, the file mounted
+       read-only, `--network` configured so the sandbox can still reach the
+       parent's loopback bridge on `request.bridgePort` (use
+       `--add-host=host.docker.internal:host-gateway` and rewrite/allow the
+       bridge host, or `--network=host` where acceptable — document the
+       trade-off in a comment). Pass `request.env` explicitly; do NOT inherit
+       the host env. Apply CPU/memory limits.
+     - Enforce `request.timeoutMs` as a hard wall-clock kill (`docker kill`),
+       and set `timedOut: true` when you kill for timeout.
+     - Capture stdout/stderr and the container exit code into
+       `SandboxRunResult` (`exitCode: null` when terminated by signal).
+2. **Wire selection** in
+   `packages/core/src/coding-tools/sandbox/index.ts` by adding `docker` to the
+   `BUILT_IN_ADAPTERS` map (`docker: () => new DockerSandboxAdapter()`), so
+   `AGENT_NATIVE_SANDBOX=docker` selects it. A host process can also call
+   `registerSandboxAdapter(new DockerSandboxAdapter())` to force it everywhere.
+3. **Add `docker-adapter.spec.ts`** mirroring the existing sandbox
+   `index.spec.ts`: assert `getSandboxAdapter()` returns the Docker adapter when
+   `AGENT_NATIVE_SANDBOX=docker`, that a registered adapter wins over the env
+   var, and that timeout produces `timedOut: true`. Skip the real-`docker`
+   integration path when the Docker daemon is unavailable (guard on a probe).
+
+## Framework rules to honor
+
+- Do not change `run-code.ts`, the agent loop, the bridge, the env scrub, or the
+  output formatting — the whole point of the seam is that they stay untouched.
+- Preserve the security posture: the adapter sees only scrubbed env + prepared
+  module source. Never re-inject the parent env or app secrets.
+- This is a publishable `packages/core` source change → add a `.changeset/*.md`.
+
+## Verify
+
+1. `tsc --noEmit` for `@agent-native/core` passes.
+2. `docker-adapter.spec.ts` passes.
+3. With Docker available, set `AGENT_NATIVE_SANDBOX=docker` and run a `run-code`
+   task that uses `appAction`/`providerFetch` through the loopback bridge;
+   confirm it executes in a container and the bridge round-trips. Confirm a
+   long-running task is killed at `timeoutMs` with `timedOut: true`.

package/dist/action.d.ts

@@ -213,7 +213,19 @@ export interface ParameterSchema {
 type InferParams<T extends Record<string, ParameterSchema> | undefined> = T extends Record<string, ParameterSchema> ? {
     [K in keyof T]?: string;
 } : Record<string, string>;
-interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any> {
+/**
+ * What to do when an action's RETURN value fails `outputSchema` validation.
+ *
+ * - `"strict"` — throw a clear error so a buggy action surfaces loudly.
+ * - `"warn"` (default) — `console.warn` the issues and return the ORIGINAL
+ *   result unchanged. Non-breaking: behavior never changes unless the dev
+ *   opts into `"strict"` or `"fallback"`.
+ * - `"fallback"` — return `outputFallback` in place of the invalid result.
+ *
+ * Mirrors Mastra/Flue structured-output handling, kept on the action layer.
+ */
+export type ActionOutputErrorStrategy = "strict" | "warn" | "fallback";
+interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any, TOutputSchema extends StandardSchemaV1 | undefined = undefined> {
     description: string;
     /** Standard Schema-compatible schema (Zod, Valibot, ArkType). Provides runtime
      *  validation and full TypeScript type inference for `run()` args. The schema is
@@ -221,6 +233,16 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
     schema: TSchema;
     /** Legacy parameters — ignored when `schema` is provided. */
     parameters?: never;
+    /** Optional Standard Schema-compatible schema (Zod, Valibot, ArkType) the
+     *  action's RETURN value is validated against AFTER `run()` resolves. Borrowed
+     *  from Mastra/Flue structured-output. When omitted, behavior is byte-for-byte
+     *  unchanged. The mismatch handling is governed by `outputErrorStrategy`. */
+    outputSchema?: TOutputSchema;
+    /** What to do when the result fails `outputSchema`. Default: `"warn"`. */
+    outputErrorStrategy?: ActionOutputErrorStrategy;
+    /** Value returned in place of an invalid result when `outputErrorStrategy` is
+     *  `"fallback"`. Ignored for the other strategies. */
+    outputFallback?: TReturn;
     run: (args: StandardSchemaV1.InferOutput<TSchema>, ctx?: ActionRunContext) => Promise<TReturn> | TReturn;
     http?: ActionHttpConfig | false;
     /** Whether the HTTP/frontend action route must have an authenticated owner.
@@ -272,6 +294,23 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
      *  interactive app iframes. Text/deep-link tool results remain the fallback
      *  for CLI and non-UI hosts. */
     mcpApp?: ActionMcpAppConfig;
+    /**
+     * Opt-in human-in-the-loop approval gate. **Default off** — the framework
+     * intentionally keeps HITL approvals rare; almost every action should run
+     * without one. Set this only for high-consequence, outward-facing,
+     * hard-to-undo operations (the canonical example is actually sending an
+     * email). When `needsApproval` resolves truthy and the agent calls this
+     * action, the loop does NOT execute `run()`: it emits an `approval_required`
+     * event and stops the turn, waiting for a human to approve. The action runs
+     * only once the human re-issues the turn approving this specific call.
+     *
+     * - `true` — always require approval.
+     * - `(args, ctx) => boolean | Promise<boolean>` — require approval only when
+     *   the predicate returns true (e.g. only for external recipients, only
+     *   above a dollar threshold). Keep it pure + fast; thrown errors are treated
+     *   as "approval required" (fail closed).
+     */
+    needsApproval?: boolean | ((args: StandardSchemaV1.InferOutput<TSchema>, ctx?: ActionRunContext) => boolean | Promise<boolean>);
 }
 interface DefineActionWithParams<TParams extends Record<string, ParameterSchema> | undefined = Record<string, ParameterSchema> | undefined, TReturn = any> {
     description: string;
@@ -280,6 +319,15 @@ interface DefineActionWithParams<TParams extends Record<string, ParameterSchema>
     parameters?: TParams;
     /** Standard Schema — not used in this overload. */
     schema?: never;
+    /** Optional Standard Schema-compatible schema the action's RETURN value is
+     *  validated against AFTER `run()` resolves. See the schema overload above.
+     *  When omitted, behavior is byte-for-byte unchanged. */
+    outputSchema?: StandardSchemaV1;
+    /** What to do when the result fails `outputSchema`. Default: `"warn"`. */
+    outputErrorStrategy?: ActionOutputErrorStrategy;
+    /** Value returned in place of an invalid result when `outputErrorStrategy` is
+     *  `"fallback"`. Ignored for the other strategies. */
+    outputFallback?: TReturn;
     run: (args: InferParams<TParams>, ctx?: ActionRunContext) => Promise<TReturn> | TReturn;
     http?: ActionHttpConfig | false;
     /** Whether the HTTP/frontend action route must have an authenticated owner.
@@ -305,6 +353,9 @@ interface DefineActionWithParams<TParams extends Record<string, ParameterSchema>
     link?: ActionLinkBuilder;
     /** Optional MCP Apps UI resource. See schema overload above. */
     mcpApp?: ActionMcpAppConfig;
+    /** Opt-in human-in-the-loop approval gate (default off). See the schema
+     *  overload above for full semantics. */
+    needsApproval?: boolean | ((args: InferParams<TParams>, ctx?: ActionRunContext) => boolean | Promise<boolean>);
 }
 /**
  * Opaque typed wrapper returned by `defineAction`. The type parameters carry
@@ -336,6 +387,18 @@ export interface ActionDefinition<TInput, TReturn> {
     readonly publicAgent?: PublicAgentActionConfig;
     readonly link?: ActionLinkBuilder;
     readonly mcpApp?: ActionMcpAppConfig;
+    /** Standard Schema the action's RETURN value is validated against after
+     *  `run()` resolves. Present only when the caller passed `outputSchema`. */
+    readonly outputSchema?: StandardSchemaV1;
+    /** Resolved output-mismatch strategy. Present only when `outputSchema` is
+     *  set; defaults to `"warn"`. */
+    readonly outputErrorStrategy?: ActionOutputErrorStrategy;
+    /** Value substituted for an invalid result under the `"fallback"` strategy. */
+    readonly outputFallback?: TReturn;
+    /** Opt-in human-in-the-loop approval gate (default off). When truthy, the
+     *  agent loop emits `approval_required` and pauses instead of executing this
+     *  action until a human approves the specific call. */
+    readonly needsApproval?: boolean | ((args: TInput, ctx?: ActionRunContext) => boolean | Promise<boolean>);
 }
 /**
  * Define an agent action. Place in `actions/` directory — auto-discovered by the framework.