Make local plugins manageable and debuggable (#3446)
* feat(plugins): expose Paseo API to local plugins Plugin surfaces borrow the selected host connection while subprocess handlers receive an exclusively owned IPC session, so plugins can use normal workspace and agent operations without inventing another transport. * feat(plugins): reload global enablement safely Treat the global plugin switch as a live daemon setting and teach plugin automation to inspect it before acting. Enabling remains permission-gated because plugin backend code can access the daemon machine and client contributions execute inside the app. * feat(plugins): expose plugin logs Capture plugin stdout and stderr separately from IPC so authors can debug initialization, RPC, cleanup, and crash behavior from the app or CLI. Keep a bounded tail across lifecycle recovery while preserving structured output in the daemon log. * fix(build): order plugin dependency builds * test(plugins): align startup and CLI expectations
This commit is contained in:
Mohamed Boudra
@@ -0,0 +1,120 @@
|
||||
---
|
||||
title: Plugin quickstart
|
||||
description: Build, install, and reload a trusted local Paseo plugin with a native sidebar surface.
|
||||
nav: Quickstart
|
||||
order: 45
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin quickstart
|
||||
|
||||
Paseo plugins add native surfaces, sidebar items, daemon behavior, and composer attachment sources. They run on every Paseo client connected to the host, including mobile.
|
||||
|
||||
Plugins are trusted local code. Install only code you trust: backend code runs unsandboxed with access to the daemon machine, and client contributions run inside the Paseo app.
|
||||
|
||||
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`.
|
||||
|
||||
## Create a plugin
|
||||
|
||||
Use an absolute path on the daemon machine:
|
||||
|
||||
```bash
|
||||
paseo plugin init /absolute/path/to/counter-plugin
|
||||
cd /absolute/path/to/counter-plugin
|
||||
npm install
|
||||
```
|
||||
|
||||
`init` creates a strict TSX project. It does not run the package manager.
|
||||
|
||||
Replace `index.tsx` with:
|
||||
|
||||
```tsx
|
||||
import type { PluginContext } from "@paseo/plugin";
|
||||
import React, { useState } from "react";
|
||||
import { Pressable, Text, View } from "react-native";
|
||||
|
||||
function Counter() {
|
||||
const [count, setCount] = useState(0);
|
||||
|
||||
return (
|
||||
<View style={{ flex: 1, padding: 24, gap: 16 }}>
|
||||
<Text style={{ fontSize: 48 }}>{count}</Text>
|
||||
<Pressable
|
||||
accessibilityRole="button"
|
||||
accessibilityLabel={`Increment counter, currently ${count}`}
|
||||
onPress={() => setCount((value) => value + 1)}
|
||||
style={{ padding: 16, borderRadius: 12, backgroundColor: "#238253" }}
|
||||
>
|
||||
<Text style={{ color: "white", textAlign: "center" }}>Count me in</Text>
|
||||
</Pressable>
|
||||
</View>
|
||||
);
|
||||
}
|
||||
|
||||
export default function contribute(plugin: PluginContext) {
|
||||
plugin.addSurface("main", Counter);
|
||||
plugin.addSidebarItem({
|
||||
id: "main",
|
||||
title: "Counter",
|
||||
icon: "ListPlus",
|
||||
surface: "main",
|
||||
});
|
||||
return () => undefined;
|
||||
}
|
||||
```
|
||||
|
||||
The icon is a [Lucide](https://lucide.dev/icons/) icon name. The surface uses React Native primitives, so the same contribution works in the desktop, browser, iOS, and Android clients.
|
||||
|
||||
## Check and install it
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin install /absolute/path/to/counter-plugin
|
||||
paseo plugin ls
|
||||
```
|
||||
|
||||
Open **Counter** in the Paseo sidebar. 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.
|
||||
|
||||
## Edit and reload
|
||||
|
||||
Source changes are explicit:
|
||||
|
||||
```bash
|
||||
npm run typecheck
|
||||
paseo plugin reload counter-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:
|
||||
|
||||
```ts
|
||||
console.log("Refreshing issues");
|
||||
console.error("Issue refresh failed", error);
|
||||
```
|
||||
|
||||
Read recent stdout and stderr from **Settings → Plugins → Logs** or the CLI:
|
||||
|
||||
```bash
|
||||
paseo plugin logs counter-plugin
|
||||
paseo plugin logs counter-plugin --json
|
||||
```
|
||||
|
||||
The log tail survives reloads and crashes, so 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.
|
||||
|
||||
## Next
|
||||
|
||||
- [Plugin reference](/docs/plugins/reference), add daemon behavior, use the Paseo SDK, contribute attachments, and manage lifecycle.
|
||||
- [TypeScript SDK](/docs/sdk), the workspace, agent, provider, and config API exposed inside plugins.
|
||||
@@ -0,0 +1,284 @@
|
||||
---
|
||||
title: Plugin reference
|
||||
description: Local plugin files, contributions, Paseo SDK access, RPCs, attachments, logs, lifecycle, hosts, and CLI commands.
|
||||
nav: Reference
|
||||
order: 46
|
||||
category: Plugins
|
||||
---
|
||||
|
||||
# Plugin reference
|
||||
|
||||
Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute:
|
||||
|
||||
- React Native surfaces and sidebar items to Paseo clients;
|
||||
- schema-validated RPC handlers running beside the daemon;
|
||||
- normal Paseo operations through the TypeScript SDK;
|
||||
- searchable external resources in the message composer.
|
||||
|
||||
Plugin code is trusted and unsandboxed. Client surfaces run in the Paseo app. Backend contributions run in a subprocess with access to the daemon machine, including its files, processes, credentials, and network.
|
||||
|
||||
## Project files
|
||||
|
||||
`paseo plugin init /absolute/path/to/my-plugin` creates:
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
paseo-plugin.json
|
||||
index.tsx
|
||||
paseo-plugin.d.ts
|
||||
package.json
|
||||
tsconfig.json
|
||||
```
|
||||
|
||||
The manifest contains the default plugin ID:
|
||||
|
||||
```json
|
||||
{ "id": "my-plugin" }
|
||||
```
|
||||
|
||||
Plugin, surface, sidebar-item, and attachment-source IDs start with a lowercase letter and contain lowercase letters, numbers, or hyphens.
|
||||
|
||||
The generated declaration file supplies `@paseo/plugin` types for local typechecking. Paseo supplies the runtime modules. Regenerate a fresh project with the matching CLI when the plugin contract changes.
|
||||
|
||||
## Entry point and cleanup
|
||||
|
||||
`index.tsx` default-exports one contribution function. It must return cleanup, even when it has nothing to clean:
|
||||
|
||||
```tsx
|
||||
import type { PluginContext } from "@paseo/plugin";
|
||||
|
||||
export default function contribute(plugin: PluginContext) {
|
||||
// Register contributions here.
|
||||
return () => undefined;
|
||||
}
|
||||
```
|
||||
|
||||
Cleanup can be async. Release timers, watchers, sockets, and other resources created by the plugin. Paseo also removes registrations, unmounts surfaces, rejects pending RPCs, closes the plugin's daemon session, and stops its subprocess on reload, disable, removal, disconnect, or daemon shutdown.
|
||||
|
||||
## Surfaces and sidebar items
|
||||
|
||||
Register a component, then point a sidebar item at its surface ID:
|
||||
|
||||
```tsx
|
||||
import type { PluginContext, PluginSurfaceProps } from "@paseo/plugin";
|
||||
import { Text } from "react-native";
|
||||
|
||||
function Main({ host, layout }: PluginSurfaceProps) {
|
||||
return <Text>{`${host.label} · ${layout.platform}`}</Text>;
|
||||
}
|
||||
|
||||
export default function contribute(plugin: PluginContext) {
|
||||
plugin.addSurface("main", Main);
|
||||
plugin.addSidebarItem({
|
||||
id: "main",
|
||||
title: "My plugin",
|
||||
icon: "Blocks",
|
||||
surface: "main",
|
||||
});
|
||||
return () => undefined;
|
||||
}
|
||||
```
|
||||
|
||||
`PluginSurfaceProps` contains:
|
||||
|
||||
| Field | Meaning |
|
||||
| -------- | --------------------------------------------------------- |
|
||||
| `theme` | Paseo theme values. Validate the keys your surface reads. |
|
||||
| `host` | Selected host `id` and display `label`. |
|
||||
| `layout` | `compact` and the `ios`, `android`, or `web` platform. |
|
||||
|
||||
Paseo owns the route, header, close action, host picker, error boundary, and query client. The plugin owns the surface body. Icons use [Lucide](https://lucide.dev/icons/) names.
|
||||
|
||||
Client code can import `react`, `react-native`, `@tanstack/react-query`, `zod`, and `@paseo/plugin`. Install them locally for typechecking; Paseo provides the client runtime instances.
|
||||
|
||||
## Use the Paseo SDK
|
||||
|
||||
Use `usePaseo()` for ordinary Paseo operations from a surface. It borrows the selected host's existing connection; do not create another client.
|
||||
|
||||
```tsx
|
||||
import { usePaseo } from "@paseo/plugin";
|
||||
import { Pressable, Text } from "react-native";
|
||||
|
||||
function PullRequestAction() {
|
||||
const paseo = usePaseo();
|
||||
|
||||
async function createReviewWorkspace() {
|
||||
const workspace = await paseo.workspaces.create({
|
||||
title: "Review PR 42",
|
||||
source: {
|
||||
kind: "worktree",
|
||||
cwd: "/absolute/path/to/repository",
|
||||
action: "checkout",
|
||||
checkoutSource: { kind: "change_request", forge: "github", number: 42 },
|
||||
},
|
||||
});
|
||||
await workspace.agents.create({
|
||||
config: { provider: "codex/gpt-5.5" },
|
||||
prompt: "Review PR #42.",
|
||||
});
|
||||
}
|
||||
|
||||
return (
|
||||
<Pressable accessibilityRole="button" onPress={() => void createReviewWorkspace()}>
|
||||
<Text>Create review workspace</Text>
|
||||
</Pressable>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
The returned API covers workspaces, agents, providers, and daemon config. See the [SDK API reference](/docs/sdk/reference) for its methods. Connection lifecycle methods are intentionally absent because Paseo owns the connection.
|
||||
|
||||
## Add plugin-specific backend behavior
|
||||
|
||||
Use plugin RPC only for work that is not a normal Paseo operation: reading a vendor API, accessing daemon-local resources, or keeping credentials off the client.
|
||||
|
||||
Define one contract with Zod, handle it in the subprocess, and call it from the surface:
|
||||
|
||||
```tsx
|
||||
import { defineRpc, type PluginContext, useRpc } from "@paseo/plugin";
|
||||
import { z } from "zod";
|
||||
|
||||
const greeting = defineRpc({
|
||||
name: "greeting.create",
|
||||
input: z.object({ name: z.string() }),
|
||||
output: z.object({ message: z.string() }),
|
||||
});
|
||||
|
||||
function GreetingButton() {
|
||||
const createGreeting = useRpc(greeting);
|
||||
// Call createGreeting({ name: "Ada" }) from an event or query.
|
||||
return null;
|
||||
}
|
||||
|
||||
export default function contribute(plugin: PluginContext) {
|
||||
plugin.handle(greeting, async ({ name }, { paseo }) => {
|
||||
const { config } = await paseo.config.get();
|
||||
return { message: `${name}: plugins are ${config.pluginsEnabled ? "on" : "off"}` };
|
||||
});
|
||||
plugin.addSurface("main", GreetingButton);
|
||||
return () => undefined;
|
||||
}
|
||||
```
|
||||
|
||||
Inputs and outputs are validated on both sides. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. `useRpc()` returns a typed async function. Use TanStack Query for request state, caching, and mutations.
|
||||
|
||||
Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. Backend code can use Node APIs and dependencies installed in the plugin directory.
|
||||
|
||||
## Debug backend output
|
||||
|
||||
Backend contributions can write to stdout and stderr with normal Node logging:
|
||||
|
||||
```ts
|
||||
console.log("Refreshing issues");
|
||||
console.error("Issue refresh failed", error);
|
||||
```
|
||||
|
||||
Paseo captures output emitted during initialization, RPC handlers, cleanup, and process failure.
|
||||
Protocol traffic uses a separate channel, so `console.log()` cannot corrupt plugin RPCs.
|
||||
|
||||
Open **Settings → Plugins → Logs** for the plugin, or inspect the same recent tail from the daemon
|
||||
CLI:
|
||||
|
||||
```bash
|
||||
paseo plugin logs my-plugin
|
||||
paseo plugin logs my-plugin --json
|
||||
paseo plugin logs my-plugin --host <url>
|
||||
```
|
||||
|
||||
The command returns a snapshot rather than following live output. Refresh the settings view or run
|
||||
the command again for newer entries. Each entry includes its timestamp, stdout or stderr stream,
|
||||
sequence, and message.
|
||||
|
||||
Paseo retains up to 500 entries and 256 KiB per plugin in memory. Individual lines are capped at
|
||||
16 KiB. Reload, disable, initialization failure, and process failure retain the tail. Removing the
|
||||
plugin clears it, and a daemon restart starts a new tail. Structured copies are also written to the
|
||||
daemon log at `$PASEO_HOME/daemon.log`.
|
||||
|
||||
Only daemon-side output is captured. Logs from client surfaces remain in the app runtime. Do not log
|
||||
credentials, access tokens, or other secrets: connected users can read the retained tail, and the
|
||||
daemon log persists it.
|
||||
|
||||
## Add a composer attachment source
|
||||
|
||||
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.
|
||||
|
||||
```tsx
|
||||
import { defineAttachmentSource, defineRpc, type PluginContext } from "@paseo/plugin";
|
||||
import { z } from "zod";
|
||||
|
||||
const searchIssues = defineRpc({
|
||||
name: "issues.search",
|
||||
input: z.object({ query: z.string() }),
|
||||
output: z.object({
|
||||
items: z.array(
|
||||
z.object({
|
||||
id: z.string(),
|
||||
identifier: z.string(),
|
||||
title: z.string(),
|
||||
subtitle: z.string().optional(),
|
||||
url: z.string().url(),
|
||||
text: z.string(),
|
||||
resourceType: z.string(),
|
||||
}),
|
||||
),
|
||||
}),
|
||||
});
|
||||
|
||||
const issues = defineAttachmentSource({
|
||||
id: "issues",
|
||||
title: "Acme issue",
|
||||
icon: "CircleDot",
|
||||
pickerTitle: "Attach Acme issue",
|
||||
searchPlaceholder: "Search by identifier or title",
|
||||
search: searchIssues,
|
||||
});
|
||||
|
||||
export default function contribute(plugin: PluginContext) {
|
||||
plugin.handle(searchIssues, ({ query }) => searchAcmeIssues(query));
|
||||
plugin.addAttachmentSource(issues);
|
||||
return () => undefined;
|
||||
}
|
||||
```
|
||||
|
||||
Paseo owns the composer menu, search picker, selected pill, draft state, and submission. The `text` value is the complete snapshot sent to the agent.
|
||||
|
||||
## Hosts and lifecycle
|
||||
|
||||
Plugins are installed per daemon. When the same contribution exists on several connected hosts, Paseo shows one sidebar item and adds a host picker. The selected host supplies the bundle, Paseo API, RPC transport, and query cache. Calls never fall through to another host when the selected host is offline.
|
||||
|
||||
Attachment sources remain scoped to each composer's host.
|
||||
|
||||
## CLI reference
|
||||
|
||||
```bash
|
||||
paseo plugin init /absolute/path/to/plugin
|
||||
paseo plugin install /absolute/path/to/plugin
|
||||
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
|
||||
paseo plugin ls
|
||||
paseo plugin reload my-plugin
|
||||
paseo plugin logs my-plugin
|
||||
paseo plugin disable my-plugin
|
||||
paseo plugin enable my-plugin
|
||||
paseo plugin remove my-plugin
|
||||
```
|
||||
|
||||
Pass `--host <url>` to management commands when the target is not the CLI's default daemon. `remove` deletes only the daemon configuration; it never deletes the source directory. The install-time `--id` is the runtime ID and allows the same directory to be installed more than once.
|
||||
|
||||
Run `npm run typecheck` before install or reload. Never edit the daemon config directly.
|
||||
|
||||
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.
|
||||
|
||||
## 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. |
|
||||
Reference in New Issue
Block a user