ExtensionsBLOCK

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: extensions
description: >-
  Creating, editing, and managing extensions — sandboxed Alpine.js mini-apps
  that run inside iframes. Use only when the host app explicitly enables
  extensions and the user asks for a one-off custom block or mini-app. Distinct
  from LLM "tools" (function calls) — see note below.
metadata:
  internal: true
---

# 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.
- `extension

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (7)

server-side proxy that injects secret values. Extensions share the main

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Extensions have full access to app data via helpers injected into the iframe

Gates applied: critical_finding, no_behavioural_pass, undeclared_transfer.

[![ModelsAtlas audit: Extensions](https://modelsatlas.com/skills/builderio/extensions/badge.svg)](https://modelsatlas.com/skills/builderio/extensions/)

Not your listing, or something out of date? Claim or update your listing.