skills/getpaseo__paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-09-14 20:36:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(plugins): publish client entry guides

Browse Source 
Restore the public client-entry reference, migration guide, links, and migration-table drift test when the feature is ready to launch.
This commit is contained in:
Mohamed Boudra
2026-09-02 23:08:09 +02:00
parent 2250148e3a
commit ad67c7030c
6 changed files with 615 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins.md
+2
View File
@@ -417,6 +417,8 @@ stable rather than arrival-ordered. The app resolves that id
against the installed catalog on every change; an id nothing contributes falls back to the default
preference instead of painting the reserved slot's placeholder colors.
Existing plugin authors should follow the standalone [runtime-entry migration guide](../public-docs/plugins/migration.md).
See `plugin-examples/local-plugin` for a native surface, `plugin-examples/linear` for a complete
attachment-source example, `plugin-examples/timeline-items` for timeline projection, and
`plugin-examples/catppuccin` for a theme.
packages/plugin/src/migration-doc.test.ts
+23
View File
@@ -0,0 +1,23 @@
import { readFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
describe("plugin runtime-entry migration guide", () => {
it("maps every client registration method", async () => {
const contracts = await readFile(new URL("./contracts.ts", import.meta.url), "utf8");
const context = /export interface PluginClientContext[^{]*{([\s\S]*?)\n}/.exec(contracts)?.[1];
if (!context) throw new Error("PluginClientContext was not found");
const methods = [...context.matchAll(/^\s+(add[A-Z]\w*)\(/gm)].map((match) => match[1]);
const migration = await readFile(
fileURLToPath(new URL("../../../public-docs/plugins/migration.md", import.meta.url)),
"utf8",
);
const table = migration.slice(
migration.indexOf("| Old registration and location"),
migration.indexOf("## 4. Separate imports"),
);
expect(methods).not.toEqual([]);
for (const method of methods) expect(table).toContain(`client.${method}(`);
});
});
public-docs/plugins/index.md
+163 -97
View File
@@ -9,24 +9,22 @@ category: Plugins
# Plugin quickstart
> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to
> your plugins as Paseo evolves.
> your plugins as Paseo evolves. See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins)
> for planned contribution surfaces.
See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins) for planned contribution
surfaces and their current status.
A plugin is a TypeScript project installed into one Paseo daemon. It can add
[surfaces and sidebar items](/docs/plugins/reference#surfaces-and-sidebar-items),
[workspace panels](/docs/plugins/reference#workspace-panels),
[Command Center items](/docs/plugins/reference#command-center-items),
[slash commands](/docs/plugins/reference#slash-commands),
[composer pills](/docs/plugins/reference#composer-pills),
[timeline items](/docs/plugins/reference#timeline-items),
[themes](/docs/plugins/reference#contribute-a-theme),
[attachment sources](/docs/plugins/reference#add-a-composer-attachment-source), and
[daemon-side RPCs](/docs/plugins/reference#add-plugin-specific-backend-behavior). Client
contributions run on every Paseo client connected to that daemon, including mobile.
Paseo plugins add native workspace panels, composer pills, Command Center items, global surfaces, app themes, daemon behavior, and composer attachment sources. They run on every Paseo client connected to the host, including mobile.
> **Trust every plugin you add.** `paseo plugin add` and `paseo plugin install` mean “I trust this codebase.” Server code and Git preparation commands run unsandboxed with the daemon user's access on the daemon host; client contributions run inside Paseo. Dependencies and future updates are part of that decision. With `--host`, commands run on the remote daemon host.
On the target host, open **Settings → Plugins** and turn on **Enable plugins**. This is the global switch for every configured plugin on that daemon.
You can also change the root `pluginsEnabled` field in the daemon's `config.json`, then apply it without restarting:
```bash
paseo reload --json
```
Enabling starts configured plugins; disabling tears them down. Automation must inspect the current value first and obtain your explicit permission before changing a disabled or omitted value to `true`.
This guide scaffolds a plugin, runs it, and adds a workspace panel to it.
## Create a plugin
@@ -38,14 +36,99 @@ cd /absolute/path/to/workspace-plugin
npm install
```
`init` creates a strict TypeScript project. It does not run the package manager. `npm install`
installs development dependencies for local typechecking and tests. Paseo supplies the plugin SDK,
React, React Native, TanStack Query, and Zod at runtime; plugins do not need a `build` hook for these
modules. `index.ts` registers contributions; client UI lives in `*.client.tsx` files.
`init` writes a strict TypeScript project and does not run the package manager. `npm install` adds
development dependencies for typechecking and tests only; Paseo supplies the plugin SDK, React,
React Native, TanStack Query, and Zod at runtime.
Plugins run on desktop, browser, iOS, and Android. Paseo ships several themes. Color every `Text` from `theme.colors.foreground` or `theme.colors.foregroundMuted`, and size layout from `layout.compact`. Hardcoded black text fails in dark themes.
The scaffold is a working plugin: a sidebar surface with a button that asks the daemon for a
greeting through an RPC.
Replace `main.client.tsx` with:
```text
workspace-plugin/
paseo-plugin.json # { "id": "workspace-plugin" }
index.client.tsx # runs in the Paseo app
index.server.ts # runs in a daemon subprocess
client/greeting.tsx # the surface component
client/web.ts # the only file allowed to touch browser APIs
server/greeting.ts # the RPC handler
shared/greeting.ts # the RPC contract, imported by both
package.json
tsconfig.json
```
Each entry default-exports one function that registers contributions and returns a cleanup
function. `index.client.tsx` registers the surface and the sidebar item that opens it:
```tsx
import type { PluginClientContext } from "@getpaseo/plugin";
import { GreetingSurface } from "./client/greeting";
export default function contribute(client: PluginClientContext) {
client.addSurface("greeting", GreetingSurface);
client.addSidebarItem({
id: "greeting",
title: "Greeting",
icon: "MessageCircle",
surface: "greeting",
});
return () => {};
}
```
`index.server.ts` registers the handler for the contract in `shared/greeting.ts`:
```ts
import type { PluginServerContext } from "@getpaseo/plugin";
import { createGreeting } from "./server/greeting";
import { greetingRpc } from "./shared/greeting";
export default function contribute(server: PluginServerContext) {
server.handle(greetingRpc, createGreeting);
return () => {};
}
```
The directory is the boundary. Code under `client/` compiles only into the app bundle, code under
`server/` only into the daemon bundle, and `shared/` into both. Importing across that line, adding
a code file at the root, or importing a `node:` module from client code is a compile error. A
plugin with no daemon-side work can omit `index.server.ts`; a plugin with no UI can omit
`index.client.tsx`.
Client code runs on phones as well as in browsers. The project typechecks without the DOM library,
so `document` and `window` are errors outside `client/web.ts`, which shows how to gate a browser
API behind `Platform.OS` with a native fallback. See
[Cross-platform rules](/docs/plugins/reference#cross-platform-rules) before writing UI.
## Install and try it
Plugins are trusted, unsandboxed code: server code and Git preparation commands run with the daemon
user's access on the daemon machine, and client code runs inside the Paseo app. Installing a plugin
means you trust that codebase, its dependencies, and its future updates.
Turn on **Enable plugins** under **Settings → Plugins** on the daemon you are installing into. It is
the global switch for every plugin on that daemon. It is also the root `pluginsEnabled` field in the
daemon's `config.json`; after editing the file, apply it with `paseo reload --json`. An automated
tool must read the current value and get your explicit permission before turning it on.
Then typecheck and install:
```bash
npm run typecheck
paseo plugin install /absolute/path/to/workspace-plugin
paseo plugin ls
```
`paseo plugin ls` should report the plugin as `running`. Open Paseo, choose **Greeting** in the
sidebar, and press **Create greeting**. The message comes back from the daemon subprocess through
the RPC.
If the sidebar item is missing, check that **Enable plugins** is on, the plugin is `running`, and
the client is viewing the host you installed into. `paseo plugin logs workspace-plugin` shows the
daemon-side output, including load errors.
## Add a workspace panel
A workspace panel opens as a tab next to agents, terminals, and files. Create `client/overview.tsx`:
```tsx
import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin";
@@ -82,60 +165,67 @@ export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspac
}
```
Replace `index.ts` with:
`useWorkspace` reads the fields the panel renders from the app's cached state, without an RPC and
without re-rendering when unrelated fields change. Every `Text` takes its color from
`theme.colors`, and `layout.compact` drives spacing, so the panel works in every Paseo theme and on
phones. See [Theme and layout](/docs/plugins/reference#theme-and-layout) for the token list.
```ts
import type { PluginContext } from "@getpaseo/plugin";
import { WorkspaceOverview } from "./main.client";
Register the panel and a Command Center item that opens it by adding to `index.client.tsx`:
export default function contribute(plugin: PluginContext) {
plugin.addWorkspacePanel({
id: "overview",
title: "Workspace overview",
icon: "PanelsTopLeft",
context: "workspace",
locations: ["workspace", "explorer"],
Component: WorkspaceOverview,
});
plugin.addCommandCenterItem({
id: "open-overview",
title: "Open workspace overview",
icon: "PanelsTopLeft",
context: "workspace",
onSelect({ openPanel }) {
openPanel("overview");
},
});
return () => {};
}
```tsx
import { WorkspaceOverview } from "./client/overview";
// Inside contribute(client), after the existing registrations:
client.addWorkspacePanel({
id: "overview",
title: "Workspace overview",
icon: "PanelsTopLeft",
context: "workspace",
locations: ["workspace", "explorer"],
Component: WorkspaceOverview,
});
client.addCommandCenterItem({
id: "open-overview",
title: "Open workspace overview",
icon: "PanelsTopLeft",
context: "workspace",
onSelect({ openPanel }) {
openPanel("overview");
},
});
```
The icon is a [Lucide](https://lucide.dev/icons/) icon name. `*.client.tsx` files can use React Native runtime APIs; Paseo excludes them from the daemon bundle. Panel props contain stable IDs; `useWorkspace` selects the cached fields the component needs without fetching through RPC or re-rendering for unrelated workspace changes. See [Theme and layout](/docs/plugins/reference#theme-and-layout) for the required tokens.
`icon` is a [Lucide](https://lucide.dev/icons/) icon name.
## Check and install it
## Edit and reload
Source changes take effect only when you reload the plugin:
```bash
npm run typecheck
paseo plugin install /absolute/path/to/workspace-plugin
paseo plugin ls
paseo plugin reload workspace-plugin
```
Open a workspace, press **⌘K** on macOS or **Ctrl+K** on Windows and Linux, and choose **Open workspace overview**. It opens as a normal workspace tab. If the item does not appear, confirm that **Enable plugins** is on, the plugin status is `running` in `paseo plugin ls`, and the client is viewing the host where you installed it.
A reload stops the old plugin, runs its cleanup, compiles the current source, and starts it again.
A failed reload stays failed and reports its error in `paseo plugin ls`; fix the source and reload
again.
To install a plugin published through GitHub or another Git host:
Open a workspace, press **⌘K** on macOS or **Ctrl+K** on Windows and Linux, and choose **Open
workspace overview**. The panel opens as a workspace tab.
## Install a published plugin
Plugins published in a Git repository install by shorthand or URL:
```bash
paseo plugin add owner/repository
paseo plugin add https://gitlab.com/group/repository.git
paseo plugin add https://git.example.com/owner/repository.git
paseo plugin add owner/monorepo:plugins/workspace
paseo plugin add owner/repository --ref main
```
Append `:relative/path` to the source when the plugin lives below the repository root.
An omitted `--ref` tracks the default branch. Explicit branches track updates; tags and commits are
pinned. Check and apply updates with:
Append `:relative/path` when the plugin lives below the repository root. Without `--ref`, the
default branch is tracked; a branch tracks updates, while a tag or commit stays pinned.
```bash
paseo plugin status
@@ -143,60 +233,36 @@ paseo plugin update workspace-plugin
paseo plugin update --all
```
Most plugins should omit `build`. Paseo compiles TypeScript and TSX and supplies its runtime modules.
Declare preparation only when the staged checkout must install another dependency, generate source,
or perform another required build step:
Paseo compiles TypeScript itself, so most plugins need no build step. A repository that must
install a dependency Paseo does not provide, or generate files, declares
[`build` commands](/docs/plugins/reference#cli-reference) in its manifest.
```json
{
"id": "workspace-plugin",
"build": [
["npm", "ci"],
["npm", "run", "build"]
]
}
```
## Read backend logs
Each `build` entry is a non-empty argv array, executed directly without a shell from the staged
plugin directory. Paseo never chooses a package manager or infers commands from lockfiles. On
install and update it resolves the exact commit, runs these commands, then validates, compiles, and
activates the candidate. A failed command discards the candidate and keeps the installed/running
version. The daemon log records the exact argv and output; `--host` runs them on the remote daemon
host.
## Edit and reload
Source changes are explicit:
```bash
npm run typecheck
paseo plugin reload workspace-plugin
```
A reload stops the old plugin, runs its cleanup, compiles the current source, and starts it again. A failed reload stays failed and reports its load error; fix the source and reload again.
## Debug backend output
Use normal Node logging in daemon-side handlers and cleanup:
Daemon-side handlers and cleanup can use normal Node logging:
```ts
console.log("Refreshing issues");
console.error("Issue refresh failed", error);
```
Read recent stdout and stderr from **Settings → Plugins → Logs** or the CLI:
Read the recent output from **Settings → Plugins → Logs** or the CLI:
```bash
paseo plugin logs workspace-plugin
paseo plugin logs workspace-plugin --json
```
The log tail includes `[paseo]` loading, ready, stopping, and stopped entries, plus compilation and
load failures. It survives reloads and crashes. Inspect it when a plugin fails to start or an RPC
rejects. See [Debug backend output](/docs/plugins/reference#debug-backend-output) for retention and
security behavior.
The tail includes `[paseo]` loading, ready, stopping, and stopped entries, plus compilation and load
failures, and it survives reloads and crashes. Client-side output stays in the app. See
[Debug backend output](/docs/plugins/reference#debug-backend-output) for retention and what not to
log.
## Next
- [Plugin reference](/docs/plugins/reference), add daemon behavior, use the Paseo SDK, contribute themes and attachments, and manage lifecycle.
- [TypeScript SDK](/docs/sdk), the workspace, agent, provider, and config API exposed inside plugins.
- [Plugin reference](/docs/plugins/reference): every contribution type, its fields, the runtime
modules, hosts, and the CLI.
- [Migrate a plugin to runtime entries](/docs/plugins/migration): move a plugin written against the
single `index.ts` entry, step by step.
- [TypeScript SDK](/docs/sdk): the workspace, agent, provider, and config API available as `paseo`
in client and server code.
public-docs/plugins/migration.md
+233
View File
@@ -0,0 +1,233 @@
---
title: Migrate a plugin to runtime entries
description: Mechanical migration from a mixed plugin entry to explicit client and server entries.
nav: Migration
order: 47
category: Plugins
---
# Migrate a plugin to runtime entries
Give this page to a coding agent with the plugin directory as its working directory. Execute the
steps in order. Do not keep a compatibility entry.
## 1. Classify the existing code
Start from the old shape:
```text
my-plugin/
paseo-plugin.json
package.json
tsconfig.json
index.ts
greeting.client.tsx
greeting.server.ts
greeting.shared.ts
```
The finished shape is:
```text
my-plugin/
paseo-plugin.json
package.json
tsconfig.json
index.client.tsx
index.server.ts
client/greeting.tsx
server/greeting.ts
shared/greeting.ts
```
Create only the entries the plugin needs. At least one is required. Components and client callbacks
need the client entry. RPC handlers and Node APIs need the server entry.
## 2. Rename files and directories
Apply these rules exactly:
1. Replace the mixed root entry with `index.client.tsx`, `index.server.ts`, or both.
2. Move every `name.client.ts` or `name.client.tsx` to `client/name.ts` or `client/name.tsx`.
3. Move every `name.server.ts` or `name.server.tsx` to `server/name.ts` or `server/name.tsx`.
4. Move every `name.shared.ts` or `name.shared.tsx` to `shared/name.ts` or `shared/name.tsx`.
5. Preserve nested feature directories under the matching runtime directory.
6. Update relative imports after every move.
7. Keep `paseo-plugin.json`, `package.json`, and `tsconfig.json` at the root.
8. Delete the old root entry. Paseo does not load it.
The directories are the compiler boundaries. A file beneath `client/` compiles only into the app
bundle, a file beneath `server/` only into the daemon bundle, and `shared/` into both. Filename
suffixes such as `*.client.tsx` no longer mean anything, and a code module left at the plugin root
is a compile error.
## 3. Move every registration
Use this table as the complete registration checklist.
| Old registration and location | New registration and location |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `plugin.handle(contract, handler)` in the old root entry | `server.handle(contract, handler)` in `index.server.ts` |
| `plugin.addSurface(id, Component)` in the old root entry | `client.addSurface(id, Component)` in `index.client.tsx` |
| `plugin.addSidebarItem(item)` in the old root entry | `client.addSidebarItem(item)` in `index.client.tsx` |
| `plugin.addWorkspacePanel(panel)` in the old root entry | `client.addWorkspacePanel(panel)` in `index.client.tsx` |
| `plugin.addCommandCenterItem(item)` in the old root entry | `client.addCommandCenterItem(item)` in `index.client.tsx` |
| `plugin.addClientSlashCommand(command)` in the old root entry | `client.addSlashCommand(command)` in `index.client.tsx` |
| `plugin.addClientSide(fn)` in the old root entry | Delete the wrapper and move the body of `fn` into the default client entry function |
| `client.addComposerPill(pill)` inside the old client callback | `client.addComposerPill(pill)` inside `index.client.tsx` or an imported `client/` function |
| `plugin.addAttachmentSource(source)` in the old root entry | `client.addAttachmentSource(source)` in `index.client.tsx` |
| `plugin.addTheme(theme)` in the old root entry | `client.addTheme(theme)` in `index.client.tsx` |
| `plugin.addTimelineTransformer(transformer)` in the old root entry | `client.addTimelineTransformer(transformer)` in `index.client.tsx` |
| `plugin.addTimelineRenderer(renderer)` in the old root entry | `client.addTimelineRenderer(renderer)` in `index.client.tsx` |
| `import { defineRpc, defineAttachmentSource } from "@getpaseo/plugin/server"` in shared files | `import { defineRpc, defineAttachmentSource } from "@getpaseo/plugin"` |
| `ZodOutput<typeof contract.input>` handler parameter types | `RpcInput<typeof contract>` from `@getpaseo/plugin`; `RpcOutput` for return types |
Import `PluginClientContext` in the client entry and `PluginServerContext` in the server entry.
Remove imports of the old context type. `@getpaseo/plugin/server` now exports only handler-side
types such as `PluginHandlerContext`. Every client `add*` now returns an idempotent removal
function. Preserve any remover the plugin calls before teardown; Paseo removes outstanding
registrations after the entry cleanup runs.
## 4. Separate imports
The client entry imports only `client/`, `shared/`, and client-safe packages. The server entry imports
only `server/`, `shared/`, and server-safe packages. A `node:` import in the client entry or anything
reachable from it is a compile error. Never import a component into the server entry merely to wire
its registration; that registration belongs in the client entry.
## 5. Recognize half-migration errors
| Compiler or load error | Meaning and fix |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Plugin entry split is required` | The directory still has only the old root entry. Create a runtime entry, move registrations, then delete the old file. |
| `Plugin entry points are missing: expected index.client.ts or index.client.tsx and/or index.server.ts or index.server.tsx` | No supported entry exists. Add at least one exact filename. |
| `server-only module cannot be imported into the plugin client bundle: <file>` | A client import reaches `server/`. Move the call behind an RPC and import its contract from `shared/`. |
| `client-only module cannot be imported into the plugin server bundle: <file>` | A server import reaches `client/`. Move that registration and import to the client entry. |
| `Plugin modules belong in client/, server/, or shared/: <file>` | A code module is still at the plugin root. Move it into the matching directory and fix its imports. |
| `Node module cannot be imported into the plugin client bundle: node:<name> imported by <file>` | Client code imports a Node API. Move the operation to `server/`, expose an RPC in `shared/`, and call it from the client. |
| TypeScript reports that `PluginContext`, `addClientSide`, or `addClientSlashCommand` does not exist | Replace the old context types and registrations using the table above. |
## 6. Worked example: `plugin-examples/local-plugin`
Only the entry files and import paths change. Component and handler bodies move without edits.
Before:
```text
local-plugin/
index.ts
main.client.tsx
increment.server.ts
increment.shared.ts
```
```ts
// index.ts
import type { PluginContext } from "@getpaseo/plugin";
import { contributeClient, ExamplePanel } from "./main.client";
import { increment } from "./increment.server";
import { incrementRpc } from "./increment.shared";
export default function contribute(plugin: PluginContext) {
plugin.handle(incrementRpc, increment);
plugin.addWorkspacePanel({
id: "counter",
title: "Plugin counter",
icon: "Blocks",
context: "workspace",
locations: ["workspace", "explorer"],
Component: ExamplePanel,
});
plugin.addCommandCenterItem({
id: "open-counter",
title: "Open plugin counter",
icon: "Blocks",
context: "workspace",
onSelect({ openPanel }) {
openPanel("counter");
},
});
plugin.addClientSide(contributeClient);
return () => {};
}
```
After:
```text
local-plugin/
index.client.tsx
index.server.ts
client/main.tsx # was main.client.tsx
server/increment.ts # was increment.server.ts
shared/increment.ts # was increment.shared.ts
```
```tsx
// index.client.tsx
import type { PluginClientContext } from "@getpaseo/plugin";
import { contributeClient, ExamplePanel } from "./client/main";
export default function contribute(client: PluginClientContext) {
client.addWorkspacePanel({
id: "counter",
title: "Plugin counter",
icon: "Blocks",
context: "workspace",
locations: ["workspace", "explorer"],
Component: ExamplePanel,
});
client.addCommandCenterItem({
id: "open-counter",
title: "Open plugin counter",
icon: "Blocks",
context: "workspace",
onSelect({ openPanel }) {
openPanel("counter");
},
});
return contributeClient(client);
}
```
```ts
// index.server.ts
import type { PluginServerContext } from "@getpaseo/plugin";
import { increment } from "./server/increment";
import { incrementRpc } from "./shared/increment";
export default function contribute(server: PluginServerContext) {
server.handle(incrementRpc, increment);
return () => {};
}
```
Import path changes inside the moved files:
```diff
// client/main.tsx
-import { incrementRpc } from "./increment.shared";
+import { incrementRpc } from "../shared/increment";
// server/increment.ts
-import { incrementRpc } from "./increment.shared";
+import { incrementRpc } from "../shared/increment";
```
`contributeClient` already took a `PluginClientContext` and returned cleanup, so the client entry
calls it directly and returns its cleanup. A plugin whose `addClientSide` callback also registered
pills or subscriptions keeps that code; only the wrapper goes away.
## 7. Verify the migration
Run:
```bash
npm run typecheck
paseo plugin reload <plugin-id>
paseo plugin ls
```
Require `running` with no error. Exercise every contribution. For plugins with RPCs, call the client
action and verify the server result. For client-only plugins, confirm the contribution loads without
a server process. Call any stored registration remover twice and verify the second call is a no-op.
public-docs/plugins/reference.md
+192 -128
View File
@@ -8,14 +8,16 @@ category: Plugins
# Plugin reference
Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/migration).
Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute:
- React Native surfaces and sidebar items to Paseo clients;
- workspace and agent panels opened as workspace tabs;
- global, workspace, and agent actions in the Command Center;
- client slash commands in the message composer;
- slash commands in the message composer;
- transformed and daemon-pushed agent timeline rows;
- dark themes in Settings → Appearance;
- light and dark themes in Settings → Appearance;
- schema-validated RPC handlers running beside the daemon;
- normal Paseo operations through the TypeScript SDK;
- searchable external resources in the message composer.
@@ -29,8 +31,11 @@ Plugin code is trusted and unsandboxed. Client surfaces run in the Paseo app. Ba
```text
my-plugin/
paseo-plugin.json
index.ts
main.client.tsx
index.client.tsx
index.server.ts
client/greeting.tsx
server/greeting.ts
shared/greeting.ts
package.json
tsconfig.json
```
@@ -41,70 +46,114 @@ The required root manifest is `paseo-plugin.json`. It contains the default plugi
{ "id": "my-plugin" }
```
The entry point is `index.ts` at the plugin root. Plugin, surface, sidebar-item, workspace-panel,
Command Center item, and attachment-source IDs start with a lowercase letter and contain lowercase
letters, numbers, or hyphens. Client slash-command names follow the same rule.
| Entry | Runtime | Receives | Required |
| ------------------ | --------------------- | --------------------- | ----------------------------------------------------------------- |
| `index.client.tsx` | Paseo app, per client | `PluginClientContext` | When the plugin has any UI, callback, theme, or attachment source |
| `index.server.ts` | Daemon subprocess | `PluginServerContext` | When the plugin handles RPCs |
At least one entry is required; both accept `.ts` or `.tsx`. A directory that still has only the
old `index.ts` fails to load and points at the [migration guide](/docs/plugins/migration).
Plugin, surface, sidebar-item, workspace-panel, Command Center item, attachment-source, and
slash-command IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.
The generated `package.json` installs `@getpaseo/plugin` and the other host modules as development
dependencies for local typechecking and tests. Paseo supplies their runtime instances. Consumers do
not install them when adding the plugin.
Add runtime-specific files as the plugin grows:
Every other module lives in one of three directories. Nesting inside them is fine; a module at the
plugin root is a compile error.
```text
my-plugin/
action.shared.ts
action.server.ts
panel.client.tsx
```
| Suffix | Use it for |
| -------------- | -------------------------------------------------------------------- |
| `*.client.tsx` | React, React Native, hooks, styles, surfaces, panels, and callbacks. |
| `*.server.ts` | Node APIs, local resources, credentials, and RPC handlers. |
| `*.shared.ts` | Zod RPC contracts and plain values imported by both runtimes. |
| Directory | Compiled into | Use it for |
| --------- | ------------------ | -------------------------------------------------------------------- |
| `client/` | App bundle only | React, React Native, hooks, styles, surfaces, panels, and callbacks. |
| `server/` | Daemon bundle only | Node APIs, local resources, credentials, and RPC handlers. |
| `shared/` | Both | Zod RPC contracts and plain values imported by both runtimes. |
## Runtime modules
Paseo builds separate client and server bundles from `index.ts`. It rejects imports from `*.server` files into client modules and imports from `*.client` files into server modules. Keep shared modules free of Node and React Native runtime code.
Paseo builds each bundle from its matching entry. An import from `client/` into the daemon bundle,
from `server/` into the app bundle, or of a `node:` module anywhere in the app bundle is a compile
error. Keep `shared/` free of Node and React Native runtime code.
### Client runtime
Paseo provides these modules to client code:
| Module | Use it for |
| ------------------------------- | ------------------------------------- |
| `@getpaseo/plugin` | Contribution contracts and data hooks |
| `@getpaseo/plugin/react-native` | Paseo UI components and UI hooks |
| `@getpaseo/plugin/server` | Shared RPC and attachment contracts |
| `@tanstack/react-query` | Request state and caching |
| `react` | Components and hooks |
| `react/jsx-runtime` | Compiled JSX |
| `react-native` | Cross-platform UI |
| `zod` | Shared schemas |
| Module | Use it for |
| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `@getpaseo/plugin` | Contribution contracts, `defineRpc`, `defineAttachmentSource`, `RpcInput`, `RpcOutput`, and data hooks |
| `@getpaseo/plugin/react-native` | Paseo UI components and UI hooks |
| `@getpaseo/plugin/server` | Handler-only types such as `PluginHandlerContext` |
| `@tanstack/react-query` | Request state and caching |
| `react` | Components and hooks |
| `react/jsx-runtime` | Compiled JSX |
| `react-native` | Cross-platform UI |
| `zod` | Shared schemas |
These exact module specifiers use the host's runtime instances. A client bundle that requests another host module fails with `Module "<name>" is not available in plugin client code`.
Do not import `lucide-react-native`, `react-native-svg`, or DOM libraries. Set contribution `icon` fields to a [Lucide icon name](https://lucide.dev/icons/); Paseo validates the name and renders the icon.
Client components are React Native components rendered by Paseo. Web clients render them through React Native Web. Browser globals such as `localStorage` and `location` exist only when `layout.platform === "web"`; iOS and Android have no equivalent. Gate any use on that field.
### Cross-platform rules
There is no plugin storage API. Browser storage does not persist settings across Paseo clients. There is also no general host navigation API: plugin code cannot open native Paseo routes. Command Center callbacks can only open surfaces and panels registered by the same plugin.
Client code runs on iOS, Android, and in browsers through React Native Web. A component that works
in your browser and crashes on a phone is the most common plugin bug. The rules:
| Do | Do not |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `View`, `Text`, `Pressable`, `ScrollView`, `TextInput` from `react-native` | `<div>`, `<span>`, `<button>`, or any HTML element |
| `style` objects built from `theme.colors` and `layout.compact` | `className`, CSS strings, or hardcoded colors |
| `onPress` | `onClick`, `onMouseEnter`, or other DOM handlers |
| `Linking`, `Clipboard`-style React Native APIs | `window`, `document`, `localStorage`, `navigator`, `location` in components |
The scaffold's `tsconfig.json` omits the DOM library, so `document` and `window` are type errors
everywhere by default. The one place browser APIs are allowed is `client/web.ts`. It declares the
narrow shape of each global it uses, gates every export on `Platform.OS`, and gives native the
alternative:
`client/web.ts`:
```ts
import { Linking, Platform } from "react-native";
// This plugin typechecks without the DOM library. Declare only what this module uses.
declare const window: { open(url: string, target: string, features: string): unknown };
export async function openExternal(url: string): Promise<void> {
if (Platform.OS === "web") {
window.open(url, "_blank", "noopener,noreferrer");
return;
}
await Linking.openURL(url);
}
```
Do not add `/// <reference lib="dom" />` or `"DOM"` to `lib`; either one turns DOM types back on
for the whole project and hides the next mistake. Components import `openExternal` and never touch
`window` themselves. `layout.platform` on surface and panel props carries the same value as
`Platform.OS` for rendering decisions.
There is no plugin storage API. Browser storage does not persist settings across Paseo clients.
There is also no general host navigation API: plugin code cannot open native Paseo routes. Command
Center callbacks can only open surfaces and panels registered by the same plugin.
### Server runtime
Paseo provides `@getpaseo/plugin`, `@getpaseo/plugin/server`, and `zod` to server code. Backend contributions run in a daemon subprocess with Node access to the host machine. Keep filesystem, process, credential, and other machine-local work in `*.server.ts` files.
Paseo provides `@getpaseo/plugin`, `@getpaseo/plugin/server`, and `zod` to server code. Backend contributions run in a daemon subprocess with Node access to the host machine. Keep filesystem, process, credential, and other machine-local work under `server/`. A plugin without `index.server.ts` starts no subprocess.
## Entry point and cleanup
`index.ts` wires contributions together and default-exports one contribution function. It must return cleanup, even when it has nothing to clean:
Each present entry default-exports one contribution function and returns cleanup. Client entries
receive `PluginClientContext`; server entries receive `PluginServerContext`. Every client `add*`
returns an idempotent remover. The entry cleanup runs before Paseo removes remaining registrations.
```ts
import type { PluginContext } from "@getpaseo/plugin";
import { Main } from "./main.client";
import type { PluginClientContext } from "@getpaseo/plugin";
import { Main } from "./client/main";
export default function contribute(plugin: PluginContext) {
plugin.addSurface("main", Main);
export default function contribute(client: PluginClientContext) {
client.addSurface("main", Main);
return () => {};
}
```
@@ -115,7 +164,7 @@ Cleanup can be async. Release timers, watchers, sockets, and other resources cre
Register a component, then point a sidebar item at its surface ID:
`main.client.tsx`:
`client/main.tsx`:
```tsx
import type { PluginSurfaceProps } from "@getpaseo/plugin";
@@ -144,15 +193,15 @@ export function Main({ theme, host, layout }: PluginSurfaceProps) {
}
```
`index.ts`:
`index.client.tsx`:
```ts
import type { PluginContext } from "@getpaseo/plugin";
import { Main } from "./main.client";
import type { PluginClientContext } from "@getpaseo/plugin";
import { Main } from "./client/main";
export default function contribute(plugin: PluginContext) {
plugin.addSurface("main", Main);
plugin.addSidebarItem({
export default function contribute(client: PluginClientContext) {
client.addSurface("main", Main);
client.addSidebarItem({
id: "main",
title: "My plugin",
icon: "Blocks",
@@ -175,7 +224,7 @@ Paseo owns the route, header, close action, host picker, error boundary, and que
## Host UI
Import Paseo-owned UI from `@getpaseo/plugin/react-native` in `*.client.tsx` files. This example
Import Paseo-owned UI from `@getpaseo/plugin/react-native` in client code. This example
opens a controlled modal, renders a host icon, and confirms the action with a toast:
```tsx
@@ -280,7 +329,7 @@ registrations are client contributions. Paseo applies the transformer while buil
model, including every live streaming update.
```tsx
import type { PluginContext, PluginTimelineItemProps } from "@getpaseo/plugin";
import type { PluginClientContext, PluginTimelineItemProps } from "@getpaseo/plugin";
import { Text } from "react-native";
import { z } from "zod";
@@ -290,8 +339,8 @@ function Card({ item, theme }: PluginTimelineItemProps<z.output<typeof schema>>)
return <Text style={{ color: theme.colors.foreground }}>{item.data.label}</Text>;
}
export default function contribute(plugin: PluginContext) {
plugin.addTimelineTransformer({
export default function contribute(client: PluginClientContext) {
client.addTimelineTransformer({
id: "command-card",
query: { itemType: "tool_call" },
transform({ item, phase }) {
@@ -307,7 +356,7 @@ export default function contribute(plugin: PluginContext) {
};
},
});
plugin.addTimelineRenderer({
client.addTimelineRenderer({
kind: "command-card",
version: 1,
schema,
@@ -391,14 +440,14 @@ Workspace and agent panels receive the same `theme`, `layout`, and optional `nav
## Contribute a theme
`addTheme` adds a light or dark theme to Settings → Appearance, listed under the built-ins by its `name`. A
theme is data, so it needs no client file:
`addTheme` adds a light or dark theme to Settings → Appearance, listed under the built-ins by its
`name`. A theme is data, so it needs no component file:
```ts
import type { PluginContext } from "@getpaseo/plugin";
import type { PluginClientContext } from "@getpaseo/plugin";
export default function contribute(plugin: PluginContext) {
plugin.addTheme({
export default function contribute(client: PluginClientContext) {
client.addTheme({
id: "mocha",
name: "Catppuccin Mocha",
appearance: "dark",
@@ -439,15 +488,14 @@ Only one contributed theme is active at a time. Selecting one persists the choic
later disabled or removed, Paseo falls back to the default theme rather than leaving the app
unpainted.
Themes need a host that supports them. A daemon released before `addTheme` compiles the call into
the plugin's backend bundle, where it does not exist, and the plugin fails to start with
`plugin.addTheme is not a function`. Update the host.
Themes need a host that supports them. A client released before `addTheme` cannot evaluate that client entry and reports
`client.addTheme is not a function`. Update the client.
## Workspace panels
Register one panel for workspace or agent context:
`review.client.tsx`:
`client/review.tsx`:
```tsx
import { type PluginAgentPanelProps, useAgent, useWorkspace } from "@getpaseo/plugin";
@@ -478,14 +526,14 @@ export function ReviewPanel({ theme, layout, workspaceId, agentId }: PluginAgent
}
```
`index.ts`:
`index.client.tsx`:
```ts
import type { PluginContext } from "@getpaseo/plugin";
import { ReviewPanel } from "./review.client";
import type { PluginClientContext } from "@getpaseo/plugin";
import { ReviewPanel } from "./client/review";
export default function contribute(plugin: PluginContext) {
plugin.addWorkspacePanel({
export default function contribute(client: PluginClientContext) {
client.addWorkspacePanel({
id: "review",
title: "Review",
icon: "Scan",
@@ -562,7 +610,7 @@ Open the Command Center with **⌘K** on macOS or **Ctrl+K** on Windows and Linu
Register an action and open a panel from the callback:
```tsx
import { defineRpc } from "@getpaseo/plugin/server";
import { defineRpc } from "@getpaseo/plugin";
import { z } from "zod";
const refreshReview = defineRpc({
@@ -571,7 +619,7 @@ const refreshReview = defineRpc({
output: z.object({ refreshed: z.boolean() }),
});
plugin.addCommandCenterItem({
client.addCommandCenterItem({
id: "open-review",
title: "Open review",
icon: "Scan",
@@ -612,13 +660,13 @@ Every callback receives:
An agent callback may open either an agent panel or a workspace panel. A workspace callback may open only a workspace panel. Unknown surface and panel IDs fail visibly. Use `paseo` for normal workspace, agent, provider, and daemon-config operations. Use `rpc` for plugin-specific filesystem, credential, vendor, or daemon-local work.
## Client slash commands
## Slash commands
Register a command that runs entirely in the Paseo client when the user submits it from the message
composer:
Register a command that runs in the Paseo client when the user submits `/name args` from the
message composer. The text is never sent to the agent:
```ts
plugin.addClientSlashCommand({
client.addSlashCommand({
name: "review",
description: "Run the review bot",
argumentHint: "[scope]",
@@ -639,9 +687,9 @@ plugin.addClientSlashCommand({
| `onSubmit` | Yes | Client callback for the matching context. |
`onSubmit` receives the matching Command Center callback context plus `args`. For `/review src`,
`args` is `"src"`; Paseo trims only the remainder's leading and trailing whitespace. Paseo owns the
autocomplete row, input clearing, and error toast. A handled command is never sent to the agent.
The compiler removes this registration from the plugin's server bundle.
`args` is `"src"`; Paseo trims only the remainder's leading and trailing whitespace and leaves
parsing to the plugin. Paseo owns the autocomplete row, input clearing, and the error toast. It
does not wait for `onSubmit` or show a pending state; use a composer pill or panel for that.
Precedence is built-in client commands, plugin commands, then provider commands. A lower-precedence
collision is omitted. Built-in aliases also reserve their names. The first plugin in stable catalog
@@ -649,18 +697,8 @@ order wins a collision between plugins. Commands do not run while the composer h
## Composer pills
Register a headless client entrypoint from `index.ts`:
```ts
import { contributeClient } from "./review.client";
export default function contribute(plugin: PluginContext) {
plugin.addClientSide(contributeClient);
return () => {};
}
```
The client entrypoint owns pill creation and removal:
The client entry owns pill creation and removal. This can live directly in `index.client.tsx` or in
a function it imports from `client/`:
```tsx
import {
@@ -683,7 +721,7 @@ function ReviewPill({ theme, agentId }: PluginComposerPillProps) {
);
}
export function contributeClient(client: PluginClientContext) {
export default function contribute(client: PluginClientContext) {
const pills = new Map<string, () => void>();
const unsubscribe = client.paseo.agents.subscribe((update) => {
if (update.kind !== "upsert" || !update.agent.workspaceId) return;
@@ -722,10 +760,10 @@ export function contributeClient(client: PluginClientContext) {
| `Component` | Yes | React Native component rendering the pill's icon and text. |
| `onPress` | Yes | Client-side callback. |
`addClientSide` runs once per plugin installation in each connected app. Its context exposes
`paseo`, typed `rpc`, `openSurface`, explicit-context `openPanel`, and `addComposerPill`.
The client entry runs once per plugin installation in each connected app. Its context exposes
`paseo`, typed `rpc`, `openSurface`, explicit-context `openPanel`, and every client registration.
`addComposerPill` returns an idempotent removal function. Paseo also removes every outstanding pill
when the client entrypoint, plugin installation, or host connection is torn down.
when the plugin installation or host connection is torn down.
Paseo owns the pressable, shared pill chrome, pending state, error reporting, and track-bar
placement. The component receives `theme`, `host`, `layout`, `workspaceId`, and `agentId`. Read
@@ -776,10 +814,10 @@ Use plugin RPC only for work that is not a normal Paseo operation: reading a ven
Define one contract with Zod, handle it in the subprocess, and call it from the surface:
`greeting.shared.ts`:
`shared/greeting.ts`:
```ts
import { defineRpc } from "@getpaseo/plugin/server";
import { defineRpc } from "@getpaseo/plugin";
import { z } from "zod";
export const greeting = defineRpc({
@@ -789,11 +827,11 @@ export const greeting = defineRpc({
});
```
`greeting.client.tsx`:
`client/greeting.tsx`:
```tsx
import { useRpc } from "@getpaseo/plugin";
import { greeting } from "./greeting.shared";
import { greeting } from "../shared/greeting";
export function GreetingButton() {
const createGreeting = useRpc(greeting);
@@ -802,28 +840,38 @@ export function GreetingButton() {
}
```
`greeting.server.ts`:
`server/greeting.ts`:
```ts
import type { output as ZodOutput } from "zod";
import { greeting } from "./greeting.shared";
import type { RpcInput } from "@getpaseo/plugin";
import { greeting } from "../shared/greeting";
export function createGreeting({ name }: ZodOutput<typeof greeting.input>) {
export function createGreeting({ name }: RpcInput<typeof greeting>) {
return { message: `Hello, ${name}` };
}
```
`index.ts`:
`index.client.tsx`:
```ts
import type { PluginContext } from "@getpaseo/plugin";
import { GreetingButton } from "./greeting.client";
import { createGreeting } from "./greeting.server";
import { greeting } from "./greeting.shared";
import type { PluginClientContext } from "@getpaseo/plugin";
import { GreetingButton } from "./client/greeting";
export default function contribute(plugin: PluginContext) {
plugin.handle(greeting, createGreeting);
plugin.addSurface("main", GreetingButton);
export default function contribute(client: PluginClientContext) {
client.addSurface("main", GreetingButton);
return () => {};
}
```
`index.server.ts`:
```ts
import type { PluginServerContext } from "@getpaseo/plugin";
import { createGreeting } from "./server/greeting";
import { greeting } from "./shared/greeting";
export default function contribute(server: PluginServerContext) {
server.handle(greeting, createGreeting);
return () => {};
}
```
@@ -873,10 +921,10 @@ daemon log persists it.
An attachment source searches external resources and returns a stable text snapshot for an agent prompt. Keep credentials and vendor calls in the backend handler.
`issues.shared.ts`:
`shared/issues.ts`:
```ts
import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin/server";
import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin";
import { z } from "zod";
export const searchIssues = defineRpc({
@@ -907,27 +955,38 @@ export const issues = defineAttachmentSource({
});
```
`issues.server.ts`:
`server/issues.ts`:
```ts
import type { output as ZodOutput } from "zod";
import { searchIssues } from "./issues.shared";
import type { RpcInput } from "@getpaseo/plugin";
import { searchIssues } from "../shared/issues";
export function search({ query }: ZodOutput<typeof searchIssues.input>) {
export function search({ query }: RpcInput<typeof searchIssues>) {
return searchAcmeIssues(query);
}
```
`index.ts`:
`index.client.tsx`:
```ts
import type { PluginContext } from "@getpaseo/plugin";
import { search } from "./issues.server";
import { issues, searchIssues } from "./issues.shared";
import type { PluginClientContext } from "@getpaseo/plugin";
import { issues } from "./shared/issues";
export default function contribute(plugin: PluginContext) {
plugin.handle(searchIssues, search);
plugin.addAttachmentSource(issues);
export default function contribute(client: PluginClientContext) {
client.addAttachmentSource(issues);
return () => {};
}
```
`index.server.ts`:
```ts
import type { PluginServerContext } from "@getpaseo/plugin";
import { search } from "./server/issues";
import { searchIssues } from "./shared/issues";
export default function contribute(server: PluginServerContext) {
server.handle(searchIssues, search);
return () => {};
}
```
@@ -1001,17 +1060,22 @@ Run `npm run typecheck` before install or reload. Never edit the daemon config d
The daemon-wide **Enable plugins** switch lives under **Settings → Plugins**. A configured plugin remains `disabled` until that switch and the plugin's own enabled state are both on.
The switch is the root `pluginsEnabled` field in `config.json`. After changing it, run `paseo reload --json`. Enabling starts every configured plugin whose own `enabled` value is not `false`; disabling tears down all plugins. No daemon restart is required. Manual edits to plugin source entries are not reloaded—use the plugin lifecycle commands for those.
The switch is the root `pluginsEnabled` field in `config.json`. After changing it, run `paseo reload --json`. Enabling starts every configured plugin whose own `enabled` value is not `false`; disabling tears down all plugins. No daemon restart is required. Manual edits to plugin source entries are not reloaded; use the plugin lifecycle commands for those.
## Load failures
Use `paseo plugin ls` to read the current status and error.
| Symptom | Check |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Sidebar item is missing | The plugin is `running`, the item references an existing surface, the icon name is valid, and the client is on the installation's host. |
| Client module is unavailable | Import only the host-provided client modules listed above. |
| RPC rejects | Check both Zod schemas and the daemon-side handler error. |
| Edited code does not appear | Run `npm run typecheck`, then `paseo plugin reload <id>`. |
| Reload fails | Read `paseo plugin ls` and `paseo plugin logs <id>`, fix the source error, then reload; Paseo does not restore the previous bundle. |
| Plugin exits unexpectedly | Read `paseo plugin logs <id>` for retained initialization, cleanup, stderr, and final crash output. |
| Symptom | Check |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Plugin entry split is required` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/migration). |
| `Plugin entry points are missing` | Neither `index.client.tsx` nor `index.server.ts` exists with that exact name. |
| `server-only module cannot be imported into the plugin client bundle` | Client code imports `server/` or a `*.server.*` file. Move the work behind an RPC and import its contract from `shared/`. |
| `client-only module cannot be imported into the plugin server bundle` | Server code imports `client/` or a `*.client.*` file. Register that contribution from `index.client.tsx` instead. |
| `Node module cannot be imported into the plugin client bundle` | Client code imports `node:*`. Move the operation to `server/` and call it through an RPC. |
| Sidebar item is missing | The plugin is `running`, the item references an existing surface, the icon name is valid, and the client is on the installation's host. |
| Client module is unavailable | Import only the host-provided client modules listed above. |
| RPC rejects | Check both Zod schemas and the daemon-side handler error. |
| Edited code does not appear | Run `npm run typecheck`, then `paseo plugin reload <id>`. |
| Reload fails | Read `paseo plugin ls` and `paseo plugin logs <id>`, fix the source error, then reload; Paseo does not restore the previous bundle. |
| Plugin exits unexpectedly | Read `paseo plugin logs <id>` for retained initialization, cleanup, stderr, and final crash output. |
skills/paseo-plugin/SKILL.md
+2
View File
@@ -598,6 +598,8 @@ Use `--host <url>` when managing a daemon other than the CLI default. A Git sour
Do not restart the daemon to load source changes. Restarting it can kill the agent performing the work.
For an old mixed entry, follow the standalone [runtime-entry migration guide](https://paseo.sh/docs/plugins/migration.md) mechanically.
## Verify the outcome
After a change: