extensions

# Extensions > **Terminology note.** This skill is about **extensions** — the framework's > user-authored mini-app primitive (sandboxed Alpine.js HTML rendered in an > iframe). It is NOT the same thing as **LLM "tools"**, which are the > function-calling primitives the AI agent uses (actions, MCP tools, etc.). > Other skills still talk about "the agent calls actions as tools" — that's > the LLM concept and stays as-is. When this doc says "tool" without > qualification, it means LLM tool. When it says "extension", it means the > sandboxed mini-app. > > Historical naming: extensions were previously called "tools". The physical > SQL table names (`tools`, `tool_data`, `tool_shares`) and a few legacy > in-iframe globals (`toolFetch`, `toolData`) are kept for back-compat — see > the back-compat table in `references/api.md`. ## References - **`references/api.md`** — the exhaustive helper/global tables (`appAction`, `appFetch`, `dbQuery`, `dbExec`, `extensionFetch`, `extensionData`), secrets, Tailwind classes, sharing, navigation, routes, and the full back-compat naming table. Read this when you need the precise signature, scope option, or route for any helper. - **`references/examples.md`** — five worked HTML extensions (API status dashboard, weather widget, todo list with `extensionData`, quick notes). Read this when you want a complete copy-pasteable starting point. ## CRITICAL: What Extensions Are (and Are Not) An Extension is a **self-contained Alpine.js HTML snippet** stored in the SQL `tools` table (table name kept for back-compat; the Drizzle export is `extensions`). It runs inside a sandboxed iframe with its own Tailwind CSS and Alpine.js runtime. **Extensions are NOT:** - React components - New source code files - Database schema changes - Action files in `actions/` - Routes ## When the Request Needs Code Instead Route by the user's exact outcome, not by whether they called it an "extension." Extensions render only on their own page or inside an existing named `ExtensionSlot`; they cannot inject UI into arbitrary native components, replace built-in views, or appear at a location where the host app has no slot. If the requested placement or behavior requires changing native components, host layout/styles/routes/business logic, or adding a new slot: 1. Briefly explain the extension boundary. 2. Do **not** stop at "an extension cannot do that," and do not silently move the UI to a less useful slot. 3. Continue through the normal source-code customization flow: - In hosted/app-rendered chat, call `connect-builder`. When its `builderEnabled` result is true, offer the Builder.io Cloud Agent handoff; when false, say the change can be made with local code editing, Agent Native Desktop, or Builder.io cloud editing. - In a local development or outer code-editing surface, follow the `self-modifying-code` skill and edit the app source directly. Full source-code customization is a core Agent-Native capability. Extensions are an optional, sandboxed, no-deploy patch layer—not the limit of what the app can become. Most apps keep extension creation disabled; do not offer or create one unless the host app has explicitly opted in. Use this decision rule when either path could solve the request: - Start with native app behavior or app code. Use an extension only when the app opted in, the user explicitly wants a bespoke one-off block, and an existing extension surface fits the requested placement. - Use app code for a core template feature, native UI/layout/routes/business logic, a new slot, or behavior that should be reused across dashboards or users. - Treat an extension as an agent-authored patch. Make that provenance clear, preserve it while promoting, and use **Promote to app code** when the behavior becomes durable. Do not imply that promotion is a lossless mechanical conversion. As a rule of thumb, default to app code. In Analytics, an explicitly requested one-off custom visualization can be a Custom Block; a new chart type that should be available across dashboards belongs in the template code. **When a user asks to "make an extension", "create an extension", or "build a ... extension" (or the older phrasings "make a tool" / "create a tool"):** 1. Write the Alpine.js HTML 2. Call `create-extension` with the HTML as `content` 3. That's it — no files to create, no schema changes, no actions Extensions have full access to app data via helpers injected into the iframe (full signatures in `references/api.md`): - `appAction(name, params)` — call any app action - `agentNative.mcp.listTools(serverId?)` and `agentNative.mcp.callTool(serverId, toolName, arguments)` — inspect and call connected remote MCP tools through the host app's authenticated, scoped action surface. The iframe never receives MCP credentials. - `agentNative.providerApi.catalog(params)` and `agentNative.providerApi.docs(params)` — discover provider APIs and their contracts using existing OAuth workspace connections. Arbitrary `providerApi.request` is intentionally not exposed to extensions because it could turn a shared extension into an authenticated write proxy; use `agentNative.mcp.callTool` or an explicit app action instead. - `appFetch(path, options)` — call allowed framework endpoints under `/_agent-native/*` - `dbQuery(sql, args)` — read from SQL - `dbExec(sql, args)` — write to SQL - `extensionFetch(url, options)` — call external APIs via proxy. Legacy alias: `toolFetch` — kept for back-compat with extension bodies authored before the rename; both names refer to the same helper. - `extensionData.set/list/get/remove(collection, ...)` — persist custom data per-extension (supports `{ scope: 'user' | 'org' | 'all' }` option). Legacy alias: `toolData` — kept for back-compat; both names refer to the same store. - `agentNative.ui.output(value, opts?)` — when an extension is rendered inline in chat, record passive control/selection output at `inline-ui:<extensionId>:output` in application state so the agent can read it later with `readAppState`. - `agentNative.chat.send(message, opts?)` - send a visible prompt or selected value back into the current agent chat. The extension bridge keeps messages draft-only unless `opts.submit === true`; pass `{ submit: true }` only from a user-triggered Apply or Submit action. Never call it from polling, refresh, or error handlers; use application state or `agentNative.ui.output` for passive results. For transient inline generative UI, `extensionData` is host-browser `localStorage`: the agent cannot read it, it does not sync across devices, it does not migrate when the UI is saved later, and the server does not garbage collect it. Use it only for throwaway local UI state. Use application state, `agentNative.ui.output`, `appAction`, or `agentNative.chat.send` for anything the agent or app must observe. ## Data Persistence is Built In **Every extension has `extensionData` — a per-extension key-value store. NO source code changes, NO Builder, NO new tables needed.** When a user asks to "add persistence", "save data", "remember state", or "store settings" in an extension, use `extensionData`. It handles table creation, scoping, and upserts automatically. Data is organized into collections per-extension: ```javascript // Save a private item (default — only the current user can see it) await extensionData.set('notes', 'note-1', { title: 'My Note', body: 'Hello' }); // Save an org-shared item (visible to everyone in the org) await extensionData.set('notes', 'note-1', { title: 'Team Note', body: 'Hello' }, { scope: 'org' }); // List items by scope const myNotes = await extensionData.list('notes'); // user-scoped (default) const orgNotes = await extensionData.list('notes', { scope: 'org' }); // org-scoped only const allNotes = await extensionData.list('notes', { scope: 'all' }); // both user + org ``` > The legacy global `toolData` is still injected and points at the same > store — older extension bodies that reference `toolData.set(...)` continue > to work without changes. Prefer `extensionData` in new code. **Prefer `extensionData` over raw `dbExec` for extension-specific persistence** — it handles everything automatically. Only use `dbQuery`/`dbExec` when querying the app's existing tables. See `references/api.md` for the full `get`/`remove`/scope reference. ### Agent-side extension data access The agent can read and write `extensionData` directly using two dedicated actions — no need to go through the iframe bridge or raw SQL: | Action | Purpose | | --------------------- | ------------------------------------------------- | | `extension-data-set` | Upsert an item in an extension's data store | | `extension-data-get` | Read items from an extension's data store | Use `extension-data-set` when the agent needs to seed, refresh, or update data that an extension reads at render time via `extensionData.get()`. This is the correct path for agent-driven dashboard refreshes — the agent fetches fresh data from providers, then writes the merged result with `extension-data-set`, and the extension picks it up on next load. Use `extension-data-get` to inspect what data an extension currently stores, or to verify a write succeeded. ## What extensions are Extensions are mini Alpine.js apps that run inside sandboxed iframes. They can call external APIs via `extensionFetch()`, which routes through a server-side proxy that injects secret values. Extensions share the main app's Tailwind v4 theme automatically. ## Creating an extension Call the `create-extension` action: ```bash pnpm action create-extension \ --name "GitHub PR Dashboard" \ --description "Shows open PRs for the repo" \ --content '<div x-data="...">...</div>' ``` Or via the HTTP API: ``` POST /_agent-native/extensions { "name": "GitHub PR Dashboard", "description": "Shows open PRs", "content": "<div ...>...</div>" } ``` HTTP creation is disabled by default. The host app must set `extensionTools: true` on `createCoreRoutesPlugin()` as well as `frameworkTools: { extensions: true }` on `createAgentChatPlugin()`; otherwise authenticated collection `POST` requests return `403` while existing extension runtime, read, edit, and deep-link routes remain available for compatibility. (`extensionTools` on the agent-chat plugin is the deprecated spelling of `frameworkTools.extensions`; the core-routes option keeps its own name because it gates route mounting rather than agent tools.) The action accepts: | Field | Type | Required | Purpose | | ---------------------- | -------- | -------- | -------------------------------------------------- | | `name` | `string` | yes | Display name of the extension | | `description` | `string` | no | Short summary | | `content` | `string` | yes\* | Alpine.js HTML body (\*unless `contentFromAttachment`) | | `contentFromAttachment`| `string` | no | Host a pasted/attached file verbatim, by reference | | `icon` | `string` | no | Icon name or short label | See `references/examples.md` for full, runnable `content` bodies. ### Hosting a pasted file (by reference) When the user **pastes a large file** (e.g. a finished HTML/Alpine app) and asks you to host it as an extension, do NOT copy that file into the `content` argument. A big paste shows up in your context as a `<attachment name="pasted-text-…">` block; re-typing it as a tool argument burns thousands of output tokens and frequently gets cut off mid-stream, stalling the turn. Instead, leave `content` empty and pass `contentFromAttachment` set to that attachment's `name` — or the literal string `"latest"` for the most recent pasted block. The server reads the attachment verbatim and stores it as the extension content: ```json { "name": "My Dashboard", "contentFromAttachment": "latest" } ``` `update-extension` accepts the same `contentFromAttachment` inside its compact `payloadJson` string for a full-body replacement. Use `operation: "replace"`; that explicit operation is the safety acknowledgement for a broad rewrite. Inline `content` still works inside `payloadJson` for everything you author yourself — use `contentFromAttachment` only to avoid regurgitating something the user already pasted. ## Editing an extension Use the `update-extension` action with exactly `id`, `operation`, and `payloadJson`. The payload is encoded as a JSON string so model gateways cannot fill every optional field with empty placeholders. Prefer `operation: "edit"` with granular `edits` inside `payloadJson` for surgical changes instead of regenerating the full HTML. For medium/large extensions, add stable section comments around major blocks so future agents can target them without touching unrelated indentation: For data-only repairs, preserve the existing layout, CSS, copy, and interactions. Do not reconstruct and submit the entire body. The action and store reject implicit full-body replacement; choose `operation: "replace"` only for a user-requested visual rewrite or complete replacement body. If a focused edit fails, inspect the current body and adjust its target; do not retry unchanged arguments. ```html <!-- agent-native:section npm-daily-chart --> <section>...</section> <!-- /agent-native:section npm-daily-chart --> ``` Then update just that section: ```json { "id": "EXTENSION_ID", "operation": "edit", "payloadJson": "{\"edits\":[{\"op\":\"replace-section\",\"section\":\"npm-daily-chart\",\"content\":\"<section>...</section>\"}],\"format\":true}" } ``` Supported `edits` operations: | Operation | Use for | | ----------------- | -------------------------------------------- | | `replace` | Literal find/replace; defaults to one match | | `insert-before` | Insert content before an exact marker | | `insert-after` | Insert content after an exact marker | | `replace-between` | Replace content between two exact markers | | `replace-section` | Replace a named comment section | | `wrap-section` | Add a wrapper around a named section | | `remove-section` | Remove a named section | | `regex-replace` | Carefully scoped regex replacement | Use `expectedMatches` when ambiguity would be dangerous. Missing required targets fail instead of silently doing nothing. Pass `format: true` to run Prettier on the final HTML after the patch. Full `content` replacement remains available for broad rewrites through `operation: "replace"`. Legacy `patches` still work for simple literal replacements: ``` PUT /_agent-native/extensions/:id { "patches": [ { "find": "old HTML fragment", "replace": "new HTML fragment" } ] } ``` Each patch does a string find-and-replace on the current content. Use this to change a single element, fix a URL, or update a class without rewriting everything. To replace the full content instead: ``` PUT /_agent-native/extensions/:id { "content": "full new HTML", "allowFullReplacement": true } ``` For the agent action, use the compact form instead: ```json { "id": "EXTENSION_ID", "operation": "replace", "payloadJson": "{\"content\":\"full new HTML\"}" } ``` ## History and rollback Extensions keep a snapshot history in SQL. A version is recorded when an extension is created, when metadata or HTML content changes, and when a prior version is restored. Existing extensions that predate history get their current state saved as a baseline the first time they are edited. Use these actions when the user asks what changed, wants a changelog/diff, or wants to go back in time: