@agent-native/core 0.49.0 → 0.49.2

package/docs/content/deployment.md

@@ -210,13 +210,14 @@ export default defineConfig({
 
 ### Build / Runtime {#env-runtime}
 
-| Variable              | Description                                                                                                                           |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `PORT`                | Server port (Node.js only)                                                                                                            |
-| `NITRO_PRESET`        | Override build preset at build time                                                                                                   |
-| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `npx @agent-native/core@latest deploy`; leave unset for standalone. |
-| `DATABASE_URL`        | Persistent SQL connection string. Required in production. See [Database](/docs/database#production) for adapter and dialect details.  |
-| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL.                                                         |
+| Variable                    | Description                                                                                                                                       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                      | Server port (Node.js only)                                                                                                                        |
+| `NITRO_PRESET`              | Override build preset at build time                                                                                                               |
+| `APP_BASE_PATH`             | Mount the app under a prefix (e.g. `/mail`). Set automatically by `npx @agent-native/core@latest deploy`; leave unset for standalone.             |
+| `DATABASE_URL`              | Persistent SQL connection string. Required in production. See [Database](/docs/database#production) for adapter and dialect details.              |
+| `DATABASE_AUTH_TOKEN`       | Auth token for providers that require a separate token, such as Turso/libSQL.                                                                     |
+| `AGENT_PROD_CODE_EXECUTION` | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](#production-code-execution). |
 
 ### Required in Production {#env-required-prod}
 
@@ -289,11 +290,34 @@ openssl rand -hex 32
 
 Rotate them by replacing the env var on every instance and redeploying — sessions / OAuth state envelopes signed under the old key become invalid, so users may need to sign in again.
 
+## Production Code Execution {#production-code-execution}
+
+By default, production agents run without code-execution tools. They can call app actions, database tools, MCP tools, browser/session tools, and other registered framework tools, but they do not get shell or filesystem access.
+
+Node-compatible deployments can opt into production code execution through the agent chat plugin or an environment override:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+The available modes are:
+
+- `off` — the default. No code-execution tools are registered in production.
+- `sandboxed` — registers `run-code`, an isolated Node.js JavaScript runner with a scrubbed environment, a fresh temp directory, output/time limits, and a localhost bridge to allowlisted registered tools such as `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request`, and `workspace-files`.
+- `trusted` — registers `run-code` plus the full coding tool registry (`bash`, `read`, `edit`, `write`). Use this only for single-tenant or operator-controlled deployments where full shell access to the host is intentional.
+
+Set `AGENT_PROD_CODE_EXECUTION=sandboxed` or `AGENT_PROD_CODE_EXECUTION=trusted` to override the plugin option for a specific deployment without a code change. `AGENT_PROD_CODE_EXECUTION=off` forces code execution off even when the plugin option enables it.
+
+The `run-code` sandbox is process-level isolation, not an OS container. It strips app secrets from the child process environment and uses the Node permission model when available, but outbound network is not blocked by Node itself; authenticated calls should go through the bridge helpers the tool exposes.
+
 ## Updating UI in Production {#updating-ui-in-production}
 
 One of agent-native's core features is that the agent can modify your app's source code — components, routes, styles, actions. During local development this works seamlessly because the agent has full filesystem access.
 
-In a standard production deployment, however, the agent runs in **production mode** with access to app tools (actions, database, MCP) but **not** the filesystem. This means the agent can read and write data, run actions, and interact with external services — but it can't edit your React components or add new routes on a deployed instance.
+In a standard production deployment with [production code execution](#production-code-execution) left off, the agent has access to app tools (actions, database, MCP) but not the filesystem. This means the agent can read and write data, run actions, and interact with external services — but it can't edit your React components or add new routes on a deployed instance.
 
 ### Builder.io: Visual Editing in Production {#builderio}
 

package/docs/content/drop-in-agent.md

@@ -15,24 +15,27 @@ You don't need to build agent-native from scratch. The agent chat, workspace tab
 
 ## The components at a glance {#components}
 
-| Component             | What it is                                                             | Use it when                                                     |
-| --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `<AgentSidebar>`      | Wraps your app, adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
-| `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                  | Pair with `<AgentSidebar>`                                      |
-| `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                     | You want full control over layout, or a dedicated agent page    |
-| `<AgentChatSurface>`  | A pre-wired panel/page chat surface                                    | You want chat without the sidebar wrapper                       |
-| `<AssistantChat>`     | Lower-level chat renderer with composer/history hooks                  | You need custom chrome around the standard conversation UI      |
-| `sendToAgentChat()`   | Programmatically send a message to the chat                            | A button that hands work to the agent instead of running inline |
-| `useActionMutation()` | Typesafe frontend wrapper around an action                             | The UI needs to run the same operation an agent tool would run  |
+| Component             | What it is                                                                            | Use it when                                                     |
+| --------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `<AgentSidebar>`      | Wraps your root app layout and adds a toggleable side panel containing the full agent | You want the agent available alongside your app on every screen |
+| `<AgentToggleButton>` | Opens/closes `<AgentSidebar>` (put it in your header)                                 | Pair with `<AgentSidebar>`                                      |
+| `<AgentPanel>`        | The raw panel itself — chat + CLI + workspace tabs                                    | You want full control over layout, or a dedicated agent page    |
+| `<AgentChatSurface>`  | A pre-wired panel/page chat surface                                                   | You want chat without the sidebar wrapper                       |
+| `<AssistantChat>`     | Lower-level chat renderer with composer/history hooks                                 | You need custom chrome around the standard conversation UI      |
+| `sendToAgentChat()`   | Programmatically send a message to the chat                                           | A button that hands work to the agent instead of running inline |
+| `useActionMutation()` | Typesafe frontend wrapper around an action                                            | The UI needs to run the same operation an agent tool would run  |
 
 All of these are exported from `@agent-native/core/client`.
 
 ## The 80% case: `<AgentSidebar>` {#sidebar}
 
-The most common setup is a sidebar that slides in from the right on any screen. Two pieces — the wrapper and a header button:
+The most common setup is a sidebar that opens from the right on any screen.
+Wrap your existing root layout with `<AgentSidebar>`; whatever you pass as
+children stays in the main app area. The agent chat is the side panel.
 
 ```tsx
 // app/root.tsx
+import { Outlet } from "react-router";
 import { AgentSidebar, AgentToggleButton } from "@agent-native/core/client";
 
 export default function Root() {
@@ -48,20 +51,23 @@ export default function Root() {
       defaultSidebarWidth={420}
       position="right"
     >
-      <YourApp />
+      <header>
+        <AgentToggleButton />
+      </header>
+
+      <main>
+        <Outlet />
+      </main>
     </AgentSidebar>
   );
 }
-
-// somewhere in your header / navbar
-<AgentToggleButton />;
 ```
 
 That's it. The user now has a toggleable agent on every page — with chat history, workspace tab, CLI terminal, voice input, and a fullscreen mode. State persists across reloads via `localStorage`.
 
 ### Props
 
-- **`children`** — your app. Rendered in the main area; the sidebar overlays from the chosen side.
+- **`children`** — your app's normal layout and routes. Rendered in the main area; the agent panel mounts beside it on desktop and over it on mobile/fullscreen.
 - **`emptyStateText`** — greeting shown when the chat has no messages. Default: `"How can I help you?"`.
 - **`suggestions`** — starter prompts rendered as clickable chips when empty.
 - **`dynamicSuggestions`** — context-aware prompt chips merged with `suggestions`. Enabled by default; pass `false` to show only static suggestions, or `{ max, includeStatic, getSuggestions }` to customize.
@@ -188,8 +194,9 @@ first so client code does not learn a second, ad hoc transport.
 
 ### Build your own sidebar from pieces {#build-your-own-sidebar}
 
-The stock sidebar is optional. A custom sidebar can keep your own layout and
-still reuse the framework runtime:
+The stock sidebar is optional. This example builds the agent-side UI itself.
+Render it inside your own shell, drawer, split pane, or route when you want to
+own the layout around the agent runtime:
 
 ```tsx
 import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";

package/docs/content/plan-plugin.md

@@ -42,6 +42,12 @@ This keeps plan content out of the Agent-Native Plan database. Hosted sharing,
 comments, screenshots, and plan history are unavailable until you explicitly
 publish later.
 
+Agent Native Desktop has a separate local-file sync path for hosted plans: the
+Desktop app can mirror a hosted plan to local MDX files and import edits back
+without cloning the Plan app or running a CLI. That workflow keeps the hosted
+Plan database as the source of truth; use local-files privacy mode when the goal
+is no Plan DB writes.
+
 > The plugin (`agent-native-visual-plans`) carries app id `visual-plans`, which is why the Claude Code plugin name and Codex plugin name are both `agent-native-visual-plans`. The Plan app's display name is "Agent-Native Plan".
 
 ## Install routes {#install}

package/docs/content/template-content.md

@@ -24,6 +24,9 @@ When you open the app, you'll see a sidebar tree of pages on the left, the edito
 - **Write rich text** with headings, lists, tables, code blocks, images, and links. Slash commands (`/`) insert blocks; selecting text pops up a formatting toolbar.
 - **Organize pages in a tree** — nest infinitely, drag to reorder, favorite pages you use often.
 - **Search across everything** with full-text search across titles and content.
+- **Sync with local Markdown/MDX files.** Use the `/local-files` view to export
+  your workspace to files, edit them in your own tools, preview changes, and
+  import them back.
 - **Sync with Notion.** Link a local doc to a Notion page and pull or push content in either direction. Comments sync both ways too.
 - **Collaborate in real time.** Multiple people (and the agent) can edit the same doc at the same time.
 - **Share docs** with teammates or make them public — private by default, with viewer / editor / admin roles.
@@ -43,6 +46,24 @@ When you open the app, click **+ New page** in the sidebar, give it a title, and
 
 Select text and hit Cmd+I to focus the agent with that selection pre-loaded — "make this punchier" then operates on exactly what you highlighted.
 
+## Local Markdown files {#local-files}
+
+Content can round-trip documents through local files without cloning or running
+the Content app locally. Open `/local-files`, choose a folder in your browser or
+Agent Native Desktop, and export the current document tree as Markdown/MDX under
+`content/`.
+
+Each exported file contains frontmatter for document metadata (`id`, `title`,
+`parentId`, `position`, favorite/search/visibility flags, and `updatedAt`) plus
+the document body as Markdown. You can edit those files in your normal editor,
+then return to `/local-files` to preview and import changes back into Content.
+
+This workflow is useful when you want content in source control, want to batch
+edit docs with local tools, or want a no-clone path for teams that prefer files
+as the review surface. The hosted app remains the source of truth for sharing,
+comments, permissions, and live collaboration; the local folder is an explicit
+sync surface.
+
 ## Why it's interesting
 
 Three things make Content a good showcase of the framework:
@@ -111,6 +132,21 @@ Documents can be linked to a Notion page and synced in either direction:
 
 Sync state is tracked in the `document_sync_links` table (last synced time, conflict flag, last error). Markdown-to-Notion block conversion lives in `shared/notion-markdown.ts`. Conflict and status UI is in `app/components/editor/NotionConflictBanner.tsx` and `NotionSyncBar.tsx`. See the `notion-integration` skill for the full flow.
 
+### Local file sync
+
+The protected `/local-files` route uses the browser File System Access API (or
+the same Chromium capability inside Agent Native Desktop) to read and write
+Markdown/MDX files from a user-chosen folder. It calls:
+
+- `export-content-source` — reads the accessible document tree and returns a
+  deterministic `content/` file bundle.
+- `import-content-source` — validates files, creates new private documents,
+  updates documents where the caller has editor access, preserves version
+  history, and rejects invalid parent cycles.
+
+The source format lives in `shared/content-source.ts`. Keep that file as the
+single contract for filenames, frontmatter, parsing, and serialization.
+
 ### Comments
 
 Threaded comments on documents with quoted-text anchors, replies, and resolve state. Backed by the `document_comments` table and `app/components/editor/CommentsSidebar.tsx`. Actions: `list-comments`, `add-comment`. Notion comments can sync both ways via `sync-notion-comments`.

package/docs/content/template-plan.md

@@ -208,6 +208,28 @@ and commenting, and returns the hosted URL. It does
 not automatically make your coding agent's LLM local; choose a local or approved
 model if that privacy boundary matters too.
 
+## Desktop local file sync {#desktop-local-sync}
+
+Agent Native Desktop also gives hosted Plans a native local-folder bridge. This
+is different from local-files privacy mode: the hosted Plan database remains the
+source of truth for sharing, comments, history, and live review, while Desktop
+can mirror the current plan's source files to a folder you choose.
+
+Open a plan in Agent Native Desktop, use the plan menu's **Local files** actions,
+then:
+
+- **Link local folder** — choose the folder for that plan's MDX source.
+- **Sync to local folder** — write `plan.mdx`, optional `canvas.mdx`,
+  optional `prototype.mdx`, optional `.plan-state.json`, and image assets.
+- **Import local edits** — read the folder and apply it through
+  `import-visual-plan-source` with the plan's current update timestamp.
+- **Auto-sync changes** — keep exporting the hosted plan's latest source after
+  edits made in the app.
+
+This path does not require cloning the Plan app or running a CLI. It is for
+file-first review/editing around a hosted plan, not for keeping plan content out
+of the hosted database.
+
 ## Useful prompts
 
 - "Use `/visual-plan` before changing the auth flow."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.49.0",
+  "version": "0.49.2",
   "type": "module",
   "engines": {
     "node": ">=22"