# Plugin API

What a plugin with code is made of, and every call it can make: its server code's `fx`, and its page code's `app` and `@fxbot/app`. fxbot calls such a plugin, a folder with `plugin.json`, a package. A guide to writing one: [Write a plugin](/sdk/how-to/write-a-plugin/).

## The folder

```text
my-plugin/
├── plugin.json
├── fxbot/
│   ├── server.ts           server code: plain JavaScript, or TypeScript that Node runs as it is
│   ├── page.js             page code: one CommonJS bundle
│   ├── page.css            optional
│   └── migrations/         optional: its tables
├── skills/<name>/SKILL.md  optional: skills, as Agent Skills lays them out
└── mcp.json                optional: MCP servers
```

Only `plugin.json` is required, and only the paths it names count.

## plugin.json

| Field | What it is |
| --- | --- |
| `name` | Required. Up to 40 lowercase letters, digits, and dashes. Its tools are `<name>_<tool>`, its routes are under `/api/plugins/<name>/`, its page paths under `/<name>/`, and its schema is `plugin_<name>`, with `_` for `-`. It can't be `chat`, `memory`, `library`, or `skill`, or an MCP server's prefix, nor a name fxbot uses itself: `preview`, `search`, `addons`, `plugins`, `settings`, `profiles`, or 12 hex characters, which is a plugin's id. It and the repository's owner make the plugin's icon. |
| `version` | Shown on its row. Default `0.0.0` |
| `description` | Shown whole on its page. Its rows in **Plugins** show its first sentence, up to 100 characters and two lines, so write one sentence that fits. |
| `extensions["sh.fxbot"].minFxbot` | The oldest fxbot it runs on, as `x.y.z`. See [Which fxbot it runs on](#which-fxbot-it-runs-on). Since 0.7.0. |
| `extensions["sh.fxbot"].server` | Its server code, a path inside the folder |
| `extensions["sh.fxbot"].page` | Its page code |
| `extensions["sh.fxbot"].css` | Its CSS |
| `extensions["sh.fxbot"].migrations` | A folder of `.sql` files |
| `extensions["sh.fxbot"].settings` | A list of settings, each with `name`, `description`, and optionally `default`, `isRequired`, and `isSecret` |
| `extensions["sh.fxbot"].commands` | Commands for the `/` list in a bot's message box, each with `name` (up to 40 lowercase letters, digits, and dashes) and `description` (up to 200 characters). Listing one runs nothing: the plugin's `message` hook sees `/name` as text. Since 0.5.0. |
| `extensions["sh.fxbot"].needs` | The plugins it needs, each name mapped to an object for that plugin, up to 16 KiB in all. See [Plugins that need others](#plugins-that-need-others). |

## Which fxbot it runs on

`minFxbot` is the oldest fxbot a plugin runs on. The rows on this page say `Since 0.6.0` where a call is newer than the rest, so set it to the newest of those that the plugin uses. It's a version and not a range: nothing says the newest fxbot a plugin runs on, since nobody can know that ahead of time.

A plugin with code on a fxbot older than its `minFxbot` can't be added, or updated to. On a start, it doesn't run, and says what it needs. fxbot before 0.7.0 doesn't read `minFxbot`, so a plugin that wants to refuse those can check for a call it needs, and throw.

What a release breaks is in fxbot's [`plugin-breaks.json`](https://fxbot.sh/plugin-breaks.json), which installs read every hour:

```json
{
  "breaks": [
    { "since": "0.8.0", "uses": ["fx.models.ask"], "says": "Use fx.models.run." },
    { "since": "0.9.0", "says": "Hooks changed shape, so every plugin needs a new version." },
    { "plugin": "computer", "below": "0.4.0", "says": "It can lose a bot's files on this version." }
  ]
}
```

| A line | It fits a plugin when |
| --- | --- |
| `since` and `uses` | Its `minFxbot` is below `since`, and its server or page code names one of `uses`, as a whole word |
| `since` alone | Its `minFxbot` is below `since` |
| `plugin` and `below` | It's that plugin, at a version below `below` |

A line applies on a fxbot at `since` or later. A plugin it fits is **Unsupported** there: it doesn't run, its files, settings, and tables stay, and it can't be added. To say a plugin has moved on from a break, raise its `minFxbot` to `since`. A plugin that needs one that's **Unsupported** gets `null` from `fx.need`, as it does for any plugin that isn't running.

The check reads names in code, so it can miss a call reached another way, and a name in a comment counts. A plugin from `FXBOT_PLUGIN_DIRS` runs whatever the check says, with a line in its log, since its author is at the keyboard.

## Server code

The server module's default export is called once when the plugin loads, with `fx`. It may be async, and may return a cleanup function, which runs when the plugin is turned off, updated, or removed, and when fxbot stops.

```ts
import type { PluginApi } from "@fxbot/sdk";

export default async function setup(fx: PluginApi) {
  const timer = setInterval(() => fx.log("still here"), 60_000);
  return () => clearInterval(timer);
}
```

| Member | What it is |
| --- | --- |
| `fx.name` | The plugin's name |
| `fx.on(event, handler)` | A hook. See [Hooks](#hooks). |
| `fx.tool(tool)` | A tool for bots. See [Tools](#tools). |
| `fx.route(method, path, handler)` | A route. See [Routes](#routes). |
| `fx.socket(path, handler)` | A WebSocket. See [Sockets](#sockets). |
| `fx.sql` | A [postgres](https://github.com/porsager/postgres) client in the plugin's own schema, with two connections at most |
| `fx.settings` | Its settings, with defaults, and secrets opened. The same object, kept up to date. |
| `fx.secrets.get(name)`, `fx.secrets.set(name, value)` | Values the plugin makes itself, such as keys of its own, sealed beside its settings and never shown in them. `get` answers `null` for a name it never set, and `set` with `null` removes one. A name is up to 64 letters, digits, `.`, `_`, or `-`, and a value up to 64 KiB of text. Since 0.8.0. |
| `fx.bots.list()`, `fx.bots.get(id)` | The bots, as [the fxbot object](/sdk/reference/server-api/) lists them |
| `fx.bots.on(id)` | Whether this plugin is on for the bot. Since 0.6.0. |
| `fx.localUrl` | The server's own address on its machine, such as `http://127.0.0.1:8787`, for requests to fxbot's own API. Since 0.8.0. |
| `fx.timeZone()` | The owner's time zone, such as `Europe/Berlin`: **Settings** › **General**'s, or the machine's. Read it at each use. Since 0.6.0. |
| `fx.compaction()` | Idle compaction's setting, from **Settings** › **General**: `{ idleMinutes, provider, model }`. `idleMinutes` is how long a chat sits idle before it's compacted, 0 when it's off, and `provider` and `model` the model that writes a summary, or `""` for each bot's own. Chat rooms compacts its rooms by it. Read it at each use. Since 0.10.0. |
| `fx.chats` | Sessions and turns of its own. See [Turns](#turns). |
| `fx.dependents()` | The added plugins that need this one: `{ name, version, needs, api }` each, where `needs` is its object for this plugin, and `api` what it provides, or null while it isn't running |
| `fx.provide(api)` | Offers an object to the plugins that need this one, which get it with `fx.need`. Since 0.5.0. See [Plugins that need others](#plugins-that-need-others). |
| `fx.need(name)` | What a plugin this one names under `needs` provides, or null while it isn't running. It throws for a plugin `needs` doesn't name. Since 0.5.0. |
| `fx.library.read(bot, id)` | A library item's `name`, `type`, and `bytes`, if it's tagged for the bot; otherwise it throws |
| `fx.library.save({ bot, session, name, type, bytes })` | Saves an image, UTF-8 text, or since 0.10.0 a PDF, whose text fxbot reads, to the bot's library, tagged for the chat, through the library's checks. It answers the item. |
| `fx.library.replace({ bot, session, id, name, type, bytes })` | Changes a document a bot made, in place: its id and tags stay, the chat gets a tag, and it comes to the top of the library. It refuses an image, an upload, an item not tagged for the bot, one another bot holds too, since one item serves every bot that saved the same text, and text another item holds. When the owner sends a bot's document in a chat, it becomes an upload. It answers the item. Since 0.7.0. |
| `fx.library.list(bot, session)` | The items saved in one chat of the bot, newest first. Since 0.6.0. |
| `fx.skills.files(bot, name)` | The files besides `SKILL.md` of the skill the bot sees by that name, as `{ path, text }`. None when it has no such skill. |
| `fx.skills.set(bot, skills)` | The skills the plugin gives one bot, in place of those it gave before, each `{ name, description, instructions }`, as a `SKILL.md`'s name, description, and body. They join the bot's catalog, its `skill` tool, and its `/` list while the plugin is on for it, and go when the plugin unloads, so a plugin keeps them and sets them again in its setup. It throws with status 400 for a bad name, a description over 1,024 characters, a name twice, or instructions over 64 KiB. Since 0.5.0. |
| `fx.memories.get(bot, id)` | One of the bot's memories, with `savedBy`, `bot` or `owner`, or null when the bot has none by that id. Since 0.5.0. `fx.memories` reaches only a bot's own memories, never the team's. |
| `fx.memories.save(bot, { text, replaces? })` | Saves a memory as the bot's, as `memory_save` does, or with `replaces`, changes that one's text. It answers `{ memory, existed, merged }`: `existed` when the same text was saved already, and `merged` when the changed memory now said what another did, and went into that one. It throws with status 400 for text over 1,000 characters, and 404 for a `replaces` the bot doesn't have. Since 0.5.0. |
| `fx.models.ask(bot, { instructions, text, provider?, model?, timeoutMs? })` | One tool-free request, on the bot's provider and model unless `provider` and `model` name others. It answers the text, and throws on a failure or after `timeoutMs`, 60 seconds by default. Keys stay on the server. Since 0.6.0. |
| `fx.memories.remove(bot, id)` | Deletes one of the bot's memories. A missing one throws with status 404. Since 0.5.0. |
| `fx.machine` | In an install made by `setup.sh`, the machine's `fxbot` command, for a job only root can do; `null` in a checkout. `ask("computer")` asks it to set up the computer plugin's engine, and `status("computer")` says how that went: `{ state, error? }`, with `state` `asked`, `working`, `done`, or `failed`, or `null` when nothing asked. `computer` is its only job. |
| `fx.log(...parts)` | A line in its log, which its tab in **Settings** shows |
| `fx.signal` | An `AbortSignal` that aborts when the plugin unloads |

Setup gets 10 seconds. A setup that throws or runs late leaves the plugin added but off, with its error on its row. fxbot starts either way. Turns can start only after fxbot has: not from setup itself.

## Hooks

Handlers run in the order the plugins were added, and change the event's fields in place, so each sees what the last one changed. A plugin's hooks reach only the bots it's on for.

| Event | When | Fields | Can |
| --- | --- | --- | --- |
| `message` | Before a message runs, after the chat is known | `bot`, `session`, `text`, `files`, `from`, `asked` | Change `text` and `files`; answer `{ handled: true }`, and no turn runs; or answer `{ startOver: { ask } }`, and the message goes to a new chat |
| `instructions` | Each time a chat opens | `bot`, `session`, `instructions`, a list | Add, change, or remove entries |
| `tool.before` | Before every tool call: fxbot's, MCP servers', skills', and plugins' | `bot`, `session`, and since 0.9.0 `label`, the session's from `newSession`, or null, `messageId`, the message whose turn it's in, since 0.6.0, and since 0.6.0, `callId`, which holds across a restart, `tool`, `description`, `input`, and `safe`, the tool's own word that it only reads or writes the bot's own notes | Change `input`, answer `{ block: reason }`, which the model gets as a failed call, or since 0.6.0 answer `{ wait }`: a function core calls after every hook, with `{ input }`, the final one, and no time limit but the call's own. It answers `{ block: reason }`, or nothing, and the call runs. Since 0.7.0, the bot's `waiting` is true while a `wait` holds one of its calls |
| `tool.after` | After it | the same, with `result`, or `error` when it failed | Change `result` |
| `turn.start` | Once libfx stores the prompt, or since 0.6.0, in a bot's own chat, when the turn it waited behind ends | `bot`, `session`, `messageId`, `text`, `from`, `asked` | Observe |
| `turn.end` | When the turn ends | the same, with `reply`, `error` when it failed, as when the provider answered with an error, and `cancelled` when it was stopped, since 0.6.0 | Observe |
| `library.removed` | An item left the library, for every bot. It reaches every running plugin, whichever bots it's on for. Since 0.7.0. | `id` | Observe |
| `settings` | The owner changed its settings | `settings` | Observe |
| `dependents` | A plugin that needs this one was added, updated, or removed | `dependents`, as `fx.dependents()` gives them | Observe |

- `message`, `instructions`, `tool.before`, and `tool.after` handlers get 5 seconds each. One that throws or runs late is logged and skipped, except `tool.before`, where it blocks the call.
- `turn.start` and `turn.end` run beside the turn, and never hold it up.
- `from` is the plugin that sent the message, when one did.
- `asked`, since 0.7.0, is the owner's words a plugin's message carried on, as `send` was given them, when it had any. The plugin that sent them vouches they're the owner's.
- A message that joins a running turn runs the `message` hook as ever, and has no `turn.start` or `turn.end` of its own: those are the running turn's. See [Turns](#turns).
- A message that a `message` hook handled answers `send` with `{ messageId, sessionId, handled: true }`.
- `{ startOver: { ask } }`, since 0.5.0, starts the bot's own chat over before the message runs: the bot's model summarizes the chat, answering `ask`, up to 16 KiB of text, and the bot starts a new chat from that summary, as a provider switch does. The message then goes to the new chat as the owner's. It applies only to the bot's own chat, only to a chat with messages, and only once for a message: a retry of one that went through doesn't start over again. The other plugins' hooks still run, and the first `startOver` counts. A message left with no text and no files answers `handled: true`. A summary that fails fails the send, with 502, and nothing moves. fxbot's own `/fresh` takes the same path since 0.10.0, before the hooks run, and a hook's `startOver` then doesn't count.

## Tools

```ts
fx.tool({
  name: "greet",
  description: "Greet someone by name",
  inputSchema: { type: "object", properties: { name: { type: "string" } } },
  idempotent: true,
  execute: async (input, { bot, session, signal }) => `Hello, ${input.name}!`,
});
```

| Field | What it is |
| --- | --- |
| `name` | Lowercase letters, digits, and `_`. Bots see `<plugin>_<name>`, up to 64 characters. |
| `description` | What the model reads |
| `inputSchema` | A JSON Schema object for the input |
| `idempotent` | Whether running a call twice is harmless, so a call cut off by a crash runs again |
| `safe` | Optional: it only reads, or writes the bot's own notes, and reaches nothing outside. A hook sees this on `tool.before`. Since 0.6.0. |
| `execute(input, call)` | Runs one call. `call` has the `bot` and `session` of the chat, the session's `label` from `newSession`, or null in the bot's own chat, since 0.9.0, the `messageId` of the message whose turn it's in, since 0.6.0, and a `signal` that aborts with the turn. A string goes to the model as it is, and anything else as JSON, but for `{ type: "libfx.tool-result", text, images }`, whose images, up to 8, the model sees. |

Adding a tool makes fxbot's agents again. A call from a bot the plugin isn't on for fails, and so does a result over 64 KiB.

## Routes

```ts
fx.route("GET", "/rooms/:id", async (request, { id }) => Response.json({ id }));
```

- A route answers `/api/plugins/<name>/<path>`, with a web `Request` and `Response`. `:name` parts come in `params`.
- A `Response` with a stream for its body streams to the caller. The request's `signal` aborts when the caller goes.
- fxbot's server checks first: a write from another site's page gets 403, and a body over 12 MiB 413.
- A handler that throws answers 500, `{ "error": "<message>" }`, and the error goes in the log.
- `/api/plugins/<name>/files/` serves its page code and CSS, and no route there is reached.

## Sockets

```ts
fx.socket("/desktop/:bot", (socket, request, { bot }) => {
  socket.onmessage = (data) => socket.send(data);
  socket.onclose = () => {};
});
```

- A socket is a WebSocket at `/api/plugins/<name>/<path>`, for a two-way stream that a route's request and response can't carry. The page opens one with `ws:` or `wss:`, matching its own address.
- `socket` has `send(data)`, `close(code?, reason?)`, `bufferedAmount`, and two handlers to set: `onmessage`, which gets a binary message as a `Buffer` and text as a string, and `onclose`.
- fxbot's server checks first: a socket opened from another site's page gets 403, since a WebSocket opens with a GET, which the write check doesn't cover. A path no socket has gets 404.
- A handler that throws closes its socket with code 1011, and the error goes in the log. Turning the plugin off, removing it, or stopping fxbot closes its open sockets.

## Data

- Adding the plugin makes the schema `plugin_<name>`, then runs each file in its migrations folder, in name order, each in a transaction. The names run are kept in the schema's `_migrations`.
- An update runs only the files that are new. Never change a file that has shipped.
- `fx.sql` reaches the schema's tables by name, without the schema.
- Removing the plugin drops the schema.

## Settings

- The owner sets them on the plugin's tab in **Settings**. Each is text, up to 8 KiB. Clearing one brings back its default.
- They're sealed together in Postgres. A secret one is never shown again, and its row says only that it's set.
- `fx.settings` has them. `fx.on("settings", …)` hears a change.

## Turns

A plugin's turns run as the owner's do, with the same hooks, history, library, and `busy`.

| Call | What it does |
| --- | --- |
| `fx.chats.newSession(bot, { label?, effort? })` | A session of the plugin's own for the bot, on the bot's provider now. Keep its id. `label`, since 0.9.0, names it, up to 80 characters, such as a subagent's name: each of its tool calls gets it, so a plugin such as the computer can tell the bot's sessions apart. `effort`, since 0.10.0, is the thinking level its turns ask for, such as `high`, in place of the bot's: the model's nearest lower level when it doesn't offer that one. |
| `fx.chats.send(bot, { text, shown?, label?, steer?, files?, session?, messageId?, asked? })` | A message. `shown`, since 0.6.0, is what the chat shows of it, when that isn't `text`, which the model gets. Without `session`, it goes to the bot's own chat, which shows it as "From <plugin>". With one, it stays out of the bot's chat, its earlier chats, and its preview, and `chat_history` still finds it. `messageId` defaults to a new UUID. `asked`, since 0.7.0, is the owner's own words the message carries on, up to 8,000 characters, which the plugin quotes from a chat of theirs, such as what they asked the bot it's from. Hooks get it with the message and its turn. |
| `fx.chats.stream(bot, session, cursor?)` | That session's lines, as NDJSON, from `cursor` on, then each new one. The same lines as [`fxbot.stream`](/sdk/how-to/stream-replies/). |
| `fx.chats.ownerSaid(bot, limit)` | The owner's newest messages in the bot's own chat, oldest first, with no plugin's or other bot's. Since 0.6.0. |
| `fx.chats.cancel(bot, session?)` | Stops the turn running in one of the plugin's own sessions, if one runs. It ends `cancelled`, and the session's stream says so. Since 0.4.1. With no `session`, since 0.6.0, it stops the turn running in the bot's own chat, if this plugin started it. Any other turn there throws with `status` 409, and with nothing running it does nothing. |

In a bot's own chat, since 0.6.0, and in a session of the plugin's own, since 0.9.0, `send` also takes these, and its answer has `joined`:

| Field | What it does |
| --- | --- |
| `label` | Who the chat says the message is from, in place of the plugin's name. Hooks still get the plugin in `from`. |
| `steer` | `true` lets the message join a turn that's running, instead of waiting behind it, when that turn takes messages: the owner's turns, and plugin turns sent with `steer`. The turn this message starts takes messages the same way. A message with an image never joins, since that would end the running turn. Since 0.9.0, it works the same in a session of the plugin's own: a turn there sent with `steer` takes the plugin's later messages sent with `steer`. |
| `joined` | In the answer: the `messageId` of the turn the message joined, when it did. Its text reaches that turn, and the turn's hooks stay that turn's. A message that came just too late runs as a turn of its own, under its own `messageId`, with `turn.start` and `turn.end`. |

A session belongs to the provider it started on. After the bot moves to another provider, `send` and `stream` for it fail with `status` 409: make a new one.

## Plugins that need others

A plugin names the plugins it needs, and what it asks of each, under `needs`:

```json
"needs": { "computer": { "setup": ["apt-get update && apt-get install -y --no-install-recommends chromium"] } }
```

- Its page says what it needs. Adding it is refused until those are added, and they can't be removed while it is.
- It loads after the plugins it needs.
- **`"optional": true`** in a need's object, since 0.10.0, makes it a plugin it works with: it loads and runs without it, Add doesn't wait for it, and it can be removed. `fx.need` answers null while it isn't running. Its page lists it under **Works with**. An older fxbot reads it as needed, so a plugin that uses it sets `minFxbot` to 0.10.0. The computer marks chat rooms so, for a room's computer.
- What each object holds is up to the plugin it names, which reads them with `fx.dependents()` and hears a change with the `dependents` event.
- A plugin with no code, only `needs` and skills, is a plugin too.

Since 0.5.0, plugins call each other through objects they provide. A plugin offers one with `fx.provide`, and a plugin that needs it gets it with `fx.need`. The plugin needed reads its dependents' objects as `api` in `fx.dependents()`:

```ts
// rooms: what other plugins may ask it.
fx.provide({ roomOf: async (session: string) => rooms.get(session) ?? null });

// room-notes, with "needs": { "rooms": {} }: asks rooms, at each use.
fx.route("GET", "/notes/:session", async (_request, { session }) => {
  const room = await fx.need<{ roomOf(session: string): Promise<{ id: number } | null> }>("rooms")?.roomOf(session);
  return Response.json({ room });
});
```

- **Read it at each use.** An update or a reload of the plugin replaces its object, and one turned off, failed, or unloading provides null.
- **It's the provider's own object,** not a copy: its functions run the provider's code, with no time limit, and their errors reach the caller.
- **On the page,** a plugin leaves a place with `Slot`, from `@fxbot/app`, and another fills it with `app.slot`. Name a place for the plugin that leaves it, such as `chat-rooms.room-header`.

The computer and chat rooms provide objects of their own: see [the computer's](/docs/reference/computer/#a-computer-for-another-plugin) and chat rooms' README.

## Page code

`page` is one CommonJS bundle that leaves `react`, `react/jsx-runtime`, and `@fxbot/app` out. The page runs it with a `require` that gives those three, its own copies, and nothing else. Its default export is called with `app`, which has the plugin's `name` and `version`, and these:

| Call | Where it shows |
| --- | --- |
| `app.route(path, Component)` | The screen at `/<plugin><path>`. `path` may have `:name` parts, which `Component` gets as `params`. |
| `app.sidebar(Component)` | A group in the sidebar, after the bots |
| `app.nav({ label, path, icon? })` | A button in the sidebar's footer row, to `/<plugin><path>`. `icon` is a component; without one, the button shows the plugin's icon. |
| `app.chat(Component)` | Above the message box in a bot's chat. It gets `bot`, and `reload()`, which reads the bot again, so the chat follows a session the plugin started, such as with `fx.chats.send` to a bot that had no chat. Since 0.6.0; `reload` since 0.10.0. |
| `app.botPanel(Component)` | Above the tabs of a bot's panel, beside its chat. It gets `bot`. |
| `app.libraryItem(Component)` | Beside **Download** in an item's preview, from the library or a bot's panel. It gets `item`. Since 0.7.0. |
| `app.composer(Component)` | A control beside the attach button. It gets `bot`, `setDraft(text)`, and `attach(files)`. `setDraft` also takes a function from the draft to the new text. |
| `app.box(Component)` | Replaces the textarea in a bot's chat, for the first plugin that sets one. It gets `bot` and a textarea's props, and acts as one: `value` is the text, `onChange` gets `{ target: { value, selectionStart } }`, and its `ref` has `selectionStart` and `setSelectionRange`. One that throws falls back to the textarea. Since 0.6.0. |
| `app.fold({ message, tool })` | Folds messages in a bot's chat into a pill, which counts what was received and sent, shows each bot's face, and opens to show them. `message(id)` gets a message's id, and answers `{ fold, bot }`, or nothing: `fold` is `"turn"` to fold it with the turn it starts, or `"message"` to fold it alone, and `bot` is the id of who it's from. `tool(call)` gets a tool call, and answers `{ bot, name }` when it sent a message, or nothing, and its card goes in a pill. A run of them makes one pill, until something that doesn't fold. A turn the owner wrote into stays in view. Since 0.6.0. |
| `app.codeBlock(language, Component)` | Draws each fenced code block of `language`, such as ```` ```mermaid ````, wherever the app shows Markdown: a bot's replies, Markdown pages, rooms, and the library's preview. `Component` gets `code`, `language`, `meta` (what follows the language on the fence), and `incomplete`, true while the block is still streaming in: in a bot's reply as it arrives, and in `ui.Streamdown` when the plugin passes it `isAnimating`. The first plugin to claim a language draws it, and one that throws leaves the plain code. Since 0.9.0. |
| `app.said(pattern, Component)` | Draws each match of `pattern`, a global regex, in what the owner or a plugin said in a bot's chat. `Component` gets `match`. Since 0.6.0. |
| `app.toolView(tool, Component, { open? })` | How a call of `<plugin>_<tool>` shows in a reply. With `open`, since 0.6.0, it stays in sight below the folded steps, for what the owner shouldn't miss. It gets `call`: `name`, `input`, `output`, `error`, and `done`. |
| `app.settings(Component)` | A part of the plugin's tab in Settings, at `/settings/plugins/<plugin>`, above its bots and settings. Every plugin has that tab, and several calls stack in it. Before 0.6.0, only a plugin that called this had a tab, and before 0.5.0, it was a section of Settings' one page. |
| `app.botSettings(Component)` | A section in a bot's settings. It gets `bot`. |
| `app.slot(name, Component)` | A part in a place another plugin's page leaves with `Slot`, which gets that `Slot`'s `props`. Several stack in order. Since 0.5.0. |

Each part sits in its own error boundary: one that throws shows a short card in its place, and the rest of the app goes on. A plugin's page parts are for everyone, whichever bots it's on for. The page reads the list of plugins again after a change in **Plugins**, and keeps code it already ran until it reloads.

`@fxbot/app`:

| Export | What it is |
| --- | --- |
| `api(path, init?)` | `fetch` for the plugin's own routes |
| `client` | The app's client, as [The client](/sdk/reference/client/) describes |
| `applyLine` | Folds a stream line into turns |
| `go(path)` | Opens a path in the app |
| `useBots()` | The app's list of bots, or `null` while it loads |
| `createPortal(children, node)` | React's, from `react-dom`, for drawing a component into DOM the plugin doesn't render with React, such as an editor's node. Since 0.4.1. |
| `Slot` | `<Slot name="<plugin>.<place>" props={…} />` leaves a place other plugins fill with `app.slot`, each part in its own error boundary. One nobody fills draws nothing. Since 0.5.0. |
| `ui` | The app's components: Button, Input, Textarea, Badge, Switch, Checkbox, the Dialog, Empty, Sidebar (with `useSidebar`), Attachment, Message, Bubble, and MessageScroller parts, `Streamdown` for Markdown, with the code blocks plugins draw since 0.9.0, `Header` for a screen's top bar, `Blob` for a bot's look, given a whole bot, as in `<ui.Blob {...bot} size={24} />`, `NativeSelect`, `ModelField` for the app's model picker, since 0.6.0, `Reply` for a turn's reply, and since 0.7.0, `useReorder(onMove, axis?)`, the app's drag to reorder a list, by mouse or finger: the list's element takes its `list` ref, each item `item(id)`'s props, with `data-lifted` on the one held, `onMove` gets the ids in their new order, `dragging` is true while an item is held, and `cancel()` ends a drag, as when the item's menu opens |

The page's styles hold only the classes the app uses. A plugin brings its own CSS for anything else.

## Where plugins come from

| Source | How |
| --- | --- |
| GitHub | **Plugins**, on **Browse**, under **From GitHub**, with unvetted plugins on: `owner/repo`, or `owner/repo/folder`. Its page pins the repository's newest commit, and shows its code. **Add** writes its files to `FXBOT_DATA/plugins/<name>/<commit>/`. |
| fxbot's list | `plugins-registry.json` on fxbot's site, read hourly, tagged **fxbot** |
| A folder | `FXBOT_PLUGIN_DIRS`, in a checkout. Added on first sight, loaded at start, and loaded again a moment after its files change |

- From GitHub, files are text only, up to 2 MiB each and 20 MB in all.
- The hourly check marks **Update available** when a plugin's files change in its repository. **Update** moves it to the commit its page showed, and keeps the old version running when the new one doesn't load.
- Its skills join the catalog of the bots it's on for. Each remote server in its `mcp.json` is added with it, under the usual rules for addresses: a record of its own, which shows in the package's settings, follows the package's switch and bots, and is removed with it. A server that runs a command isn't used yet.
- In a release, fxbot runs in its container, and a plugin reaches what the container does.

## In your own app

Plugins load inside [`createFxbot`](/sdk/reference/create-fxbot/), so an app built on the SDK runs them as fxbot does, with some parts left to the app:
- **Server code runs as it is:** hooks, tools, tables, settings, turns, skills, and MCP servers. [`fxbot.plugins`](/sdk/reference/server-api/#plugins) adds, updates, and removes plugins, and `pluginDirs` loads folders.
- **Routes and sockets need your server.** Pass requests under `/api/plugins/<name>/` to `fxbot.plugins.handle(name, request, path)`, its page code and CSS under `files/` to `fxbot.plugins.file`, and WebSocket upgrades there to `fxbot.plugins.socket`, as fxbot's server does (`packages/server/src/index.ts`). A plugin's page calls that path.
- **Page code needs fxbot's page.** `fxbot.plugins.pages()` lists each plugin's bundle, but what runs one, the `app` places and `@fxbot/app`, is part of fxbot's own app (`packages/ui/src/plugins.tsx`), not `@fxbot/sdk/client`. An app with a page of its own shows none of a plugin's screens, panels, or buttons, unless it gives the bundle that `require` and `app` itself.
- **`fx.machine` is `null`** unless you pass `machine`. The computer plugin then sets up its engine by itself only when the app runs as root, and otherwise shows the command to run.