From 20ecdee72d7dcdaedb7959842e6bf7f5332217e1 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Wed, 2 Sep 2026 23:45:23 +0200 Subject: [PATCH] docs(plugins): version breaking API guides (#4245) Keep stable v0.7 guidance available while the client-entry layout is previewed for v0.8. Existing reference and migration URLs redirect to the release that owns their content. --- docs/plugins.md | 6 +- packages/plugin/src/migration-doc.test.ts | 2 +- .../src/server/plugins/runtime.posix.test.ts | 2 +- packages/server/src/server/plugins/runtime.ts | 2 +- packages/website/src/docs.ts | 11 + .../src/plugin-docs-navigation.test.ts | 43 + packages/website/src/server-entry.ts | 8 +- public-docs/cli.md | 2 +- public-docs/plugins/index.md | 271 +---- public-docs/plugins/v0.7/index.md | 204 ++++ public-docs/plugins/v0.7/reference.md | 1019 +++++++++++++++++ public-docs/plugins/v0.8/index.md | 271 +++++ public-docs/plugins/{ => v0.8}/migration.md | 4 +- public-docs/plugins/{ => v0.8}/reference.md | 10 +- skills/paseo-plugin/SKILL.md | 4 +- 15 files changed, 1585 insertions(+), 274 deletions(-) create mode 100644 packages/website/src/plugin-docs-navigation.test.ts create mode 100644 public-docs/plugins/v0.7/index.md create mode 100644 public-docs/plugins/v0.7/reference.md create mode 100644 public-docs/plugins/v0.8/index.md rename public-docs/plugins/{ => v0.8}/migration.md (99%) rename public-docs/plugins/{ => v0.8}/reference.md (99%) diff --git a/docs/plugins.md b/docs/plugins.md index 5f5a65dcba..b1051c3a7f 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -158,7 +158,7 @@ Its controlled modal keeps presentation metadata on ``. Plugin UI runs on desktop and mobile across multiple themes: color every `Text` from `theme.colors.foreground` or `theme.colors.foregroundMuted`, and size layout from `layout.compact`. -See `public-docs/plugins/reference.md`. +See `public-docs/plugins/v0.8/reference.md`. | Module | Use it for | | ------------------------------- | ----------------------------------------------------------------------------------------- | @@ -176,7 +176,7 @@ The scaffold omits `"DOM"` from `tsconfig.json` and does not use `/// { 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)), + fileURLToPath(new URL("../../../public-docs/plugins/v0.8/migration.md", import.meta.url)), "utf8", ); const table = migration.slice( diff --git a/packages/server/src/server/plugins/runtime.posix.test.ts b/packages/server/src/server/plugins/runtime.posix.test.ts index 9b285687d7..6980a6f7e3 100644 --- a/packages/server/src/server/plugins/runtime.posix.test.ts +++ b/packages/server/src/server/plugins/runtime.posix.test.ts @@ -507,7 +507,7 @@ export default function contribute(plugin: unknown) { "Plugin entry split is required", ); await expect(runtime.startPlugin("legacy", directory)).rejects.toThrow( - "https://paseo.sh/docs/plugins/migration", + "https://paseo.sh/docs/plugins/v0.8/migration", ); }); diff --git a/packages/server/src/server/plugins/runtime.ts b/packages/server/src/server/plugins/runtime.ts index 63593d9199..11951ecad3 100644 --- a/packages/server/src/server/plugins/runtime.ts +++ b/packages/server/src/server/plugins/runtime.ts @@ -207,7 +207,7 @@ async function resolveEntryPaths(directory: string): Promise<{ const legacyEntry = await findEntry(directory, ["index.ts", "index.tsx"]); if (legacyEntry) { throw new Error( - "Plugin entry split is required: migrate index.ts to index.client.tsx and/or index.server.ts. See https://paseo.sh/docs/plugins/migration", + "Plugin entry split is required: migrate index.ts to index.client.tsx and/or index.server.ts. See https://paseo.sh/docs/plugins/v0.8/migration", ); } throw new Error( diff --git a/packages/website/src/docs.ts b/packages/website/src/docs.ts index aa89c2315a..c9211c4064 100644 --- a/packages/website/src/docs.ts +++ b/packages/website/src/docs.ts @@ -157,6 +157,17 @@ export function getDoc(slug: string): Doc | undefined { return getDocs().find((d) => d.slug === slug); } +const legacyPluginDocRedirects: Readonly> = { + "/docs/plugins/reference": "/docs/plugins/v0.7/reference", + "/docs/plugins/reference.md": "/docs/plugins/v0.7/reference.md", + "/docs/plugins/migration": "/docs/plugins/v0.8/migration", + "/docs/plugins/migration.md": "/docs/plugins/v0.8/migration.md", +}; + +export function getLegacyDocsRedirect(pathname: string): string | undefined { + return legacyPluginDocRedirects[pathname]; +} + function formatLabel(segment: string): string { return segment.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()); } diff --git a/packages/website/src/plugin-docs-navigation.test.ts b/packages/website/src/plugin-docs-navigation.test.ts new file mode 100644 index 0000000000..1d44644b46 --- /dev/null +++ b/packages/website/src/plugin-docs-navigation.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from "vitest"; +import { buildDocsNavTree, getDocs, getLegacyDocsRedirect } from "./docs"; + +describe("versioned plugin documentation", () => { + it("keeps current and preview releases together in the Plugins navigation", () => { + const plugins = buildDocsNavTree(getDocs()).find( + (node) => node.type === "category" && node.label === "Plugins", + ); + + expect(plugins).toMatchObject({ + type: "category", + children: [ + { type: "page", label: "Versions", href: "/docs/plugins" }, + { + type: "group", + label: "Paseo v0.7 — Current", + href: "/docs/plugins/v0.7", + children: [{ type: "page", label: "Reference", href: "/docs/plugins/v0.7/reference" }], + }, + { + type: "group", + label: "Paseo v0.8 — Preview", + href: "/docs/plugins/v0.8", + children: [ + { type: "page", label: "Reference", href: "/docs/plugins/v0.8/reference" }, + { type: "page", label: "Migration", href: "/docs/plugins/v0.8/migration" }, + ], + }, + ], + }); + }); + + it("keeps existing plugin documentation URLs working", () => { + expect(getLegacyDocsRedirect("/docs/plugins/reference")).toBe("/docs/plugins/v0.7/reference"); + expect(getLegacyDocsRedirect("/docs/plugins/reference.md")).toBe( + "/docs/plugins/v0.7/reference.md", + ); + expect(getLegacyDocsRedirect("/docs/plugins/migration")).toBe("/docs/plugins/v0.8/migration"); + expect(getLegacyDocsRedirect("/docs/plugins/migration.md")).toBe( + "/docs/plugins/v0.8/migration.md", + ); + }); +}); diff --git a/packages/website/src/server-entry.ts b/packages/website/src/server-entry.ts index 75f46e2450..9fb921833a 100644 --- a/packages/website/src/server-entry.ts +++ b/packages/website/src/server-entry.ts @@ -1,7 +1,7 @@ import startEntry from "@tanstack/react-start/server-entry"; import { getAndroidVersionCode } from "~/android-version"; import { getCanonicalRedirect } from "~/canonical-url"; -import { getDoc } from "~/docs"; +import { getDoc, getLegacyDocsRedirect } from "~/docs"; import { getLatestAndroidVersion } from "~/latest-release"; import { buildLlmsTxt } from "~/llms"; @@ -80,6 +80,12 @@ export default { return Response.redirect(url.toString(), 301); } + const legacyDocsRedirect = getLegacyDocsRedirect(url.pathname); + if (legacyDocsRedirect) { + url.pathname = legacyDocsRedirect; + return Response.redirect(url.toString(), 301); + } + if (url.pathname === "/llms.txt") { return markdownResponse(buildLlmsTxt()); } diff --git a/public-docs/cli.md b/public-docs/cli.md index 9f8f5f7d8e..e0ec925bfe 100644 --- a/public-docs/cli.md +++ b/public-docs/cli.md @@ -168,7 +168,7 @@ paseo plugin remove my-plugin GitHub shorthand checks an existing host directory first. Append `:` for a plugin in a monorepo. `paseo plugin logs ` returns the plugin's recent daemon-side stdout and stderr. Add `--json` for structured entries, or run `paseo --host plugin logs ` for another daemon. See the -[Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention +[Plugin reference](/docs/plugins/v0.7/reference) for installation, trust, lifecycle, and log-retention behavior. ## Listing agents diff --git a/public-docs/plugins/index.md b/public-docs/plugins/index.md index d25961218a..552a0476e0 100644 --- a/public-docs/plugins/index.md +++ b/public-docs/plugins/index.md @@ -1,268 +1,21 @@ --- -title: Plugin quickstart -description: Build, install, share, and update a trusted Paseo plugin. -nav: Quickstart -order: 45 +title: Paseo plugin documentation +description: Choose the plugin API documentation for your Paseo release. +nav: Versions +order: 44 category: Plugins --- -# Plugin quickstart +# Paseo plugin documentation -> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to -> your plugins as Paseo evolves. See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins) -> for planned contribution surfaces. +Choose the documentation that matches your Paseo release. The plugin API is experimental and can +change between releases. -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 v0.7 — Current](/docs/plugins/v0.7) -This guide scaffolds a plugin, runs it, and adds a workspace panel to it. +Build and maintain plugins for the latest stable Paseo release. -## Create a plugin +## [Paseo v0.8 — Preview](/docs/plugins/v0.8) -Use an absolute path on the daemon machine: - -```bash -paseo plugin init /absolute/path/to/workspace-plugin -cd /absolute/path/to/workspace-plugin -npm install -``` - -`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. - -The scaffold is a working plugin: a sidebar surface with a button that asks the daemon for a -greeting through an RPC. - -```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"; -import { useMemo } from "react"; -import { Text, View } from "react-native"; - -export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) { - const workspace = useWorkspace(workspaceId, ({ name, directory }) => ({ - name, - directory, - })); - const styles = useMemo( - () => ({ - screen: { - flex: 1, - padding: layout.compact ? 16 : 24, - gap: layout.compact ? 8 : 12, - backgroundColor: theme.colors.surface0, - }, - title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 }, - label: { color: theme.colors.foregroundMuted }, - detail: { color: theme.colors.foreground }, - }), - [theme, layout.compact], - ); - - return ( - - {workspace?.name} - Directory - {workspace?.directory} - - ); -} -``` - -`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. - -Register the panel and a Command Center item that opens it by adding to `index.client.tsx`: - -```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"); - }, -}); -``` - -`icon` is a [Lucide](https://lucide.dev/icons/) icon name. - -## Edit and reload - -Source changes take effect only when you reload the plugin: - -```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 error in `paseo plugin ls`; fix the source and reload -again. - -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 owner/monorepo:plugins/workspace -paseo plugin add owner/repository --ref main -``` - -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 -paseo plugin update workspace-plugin -paseo plugin update --all -``` - -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. - -## Read backend logs - -Daemon-side handlers and cleanup can use normal Node logging: - -```ts -console.log("Refreshing issues"); -console.error("Issue refresh failed", error); -``` - -Read the recent output from **Settings → Plugins → Logs** or the CLI: - -```bash -paseo plugin logs workspace-plugin -paseo plugin logs workspace-plugin --json -``` - -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): 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. +Prepare plugins for the upcoming client and server entry layout. Existing plugin authors should +follow the [v0.8 migration guide](/docs/plugins/v0.8/migration). diff --git a/public-docs/plugins/v0.7/index.md b/public-docs/plugins/v0.7/index.md new file mode 100644 index 0000000000..dafe44620a --- /dev/null +++ b/public-docs/plugins/v0.7/index.md @@ -0,0 +1,204 @@ +--- +title: Plugin quickstart +description: Build, install, share, and update a trusted Paseo plugin. +nav: Paseo v0.7 — Current +order: 45 +category: Plugins +--- + +# Plugin quickstart + +> **For Paseo v0.7.x.** This is the current stable plugin API. + +> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to +> your plugins as Paseo evolves. + +See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins) for planned contribution +surfaces and their current status. + +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`. + +## Create a plugin + +Use an absolute path on the daemon machine: + +```bash +paseo plugin init /absolute/path/to/workspace-plugin +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. + +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. + +Replace `main.client.tsx` with: + +```tsx +import { type PluginWorkspacePanelProps, useWorkspace } from "@getpaseo/plugin"; +import { useMemo } from "react"; +import { Text, View } from "react-native"; + +export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) { + const workspace = useWorkspace(workspaceId, ({ name, directory }) => ({ + name, + directory, + })); + const styles = useMemo( + () => ({ + screen: { + flex: 1, + padding: layout.compact ? 16 : 24, + gap: layout.compact ? 8 : 12, + backgroundColor: theme.colors.surface0, + }, + title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 }, + label: { color: theme.colors.foregroundMuted }, + detail: { color: theme.colors.foreground }, + }), + [theme, layout.compact], + ); + + return ( + + {workspace?.name} + Directory + {workspace?.directory} + + ); +} +``` + +Replace `index.ts` with: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; +import { WorkspaceOverview } from "./main.client"; + +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 () => {}; +} +``` + +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/v0.7/reference#theme-and-layout) for the required tokens. + +## Check and install it + +```bash +npm run typecheck +paseo plugin install /absolute/path/to/workspace-plugin +paseo plugin ls +``` + +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. + +To install a plugin published through GitHub or another Git host: + +```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: + +```bash +paseo plugin status +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: + +```json +{ + "id": "workspace-plugin", + "build": [ + ["npm", "ci"], + ["npm", "run", "build"] + ] +} +``` + +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: + +```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 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/v0.7/reference#debug-backend-output) for retention and +security behavior. + +## Next + +- [Plugin reference](/docs/plugins/v0.7/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. diff --git a/public-docs/plugins/v0.7/reference.md b/public-docs/plugins/v0.7/reference.md new file mode 100644 index 0000000000..1ff7511fda --- /dev/null +++ b/public-docs/plugins/v0.7/reference.md @@ -0,0 +1,1019 @@ +--- +title: Plugin reference +description: Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands. +nav: Reference +order: 46 +category: Plugins +--- + +# Plugin reference + +> **For Paseo v0.7.x.** Return to the [v0.7 quickstart](/docs/plugins/v0.7). + +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; +- transformed and daemon-pushed agent timeline rows; +- 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. + +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.ts + main.client.tsx + package.json + tsconfig.json +``` + +The required root manifest is `paseo-plugin.json`. It contains the default plugin ID: + +```json +{ "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. + +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: + +```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. | + +## 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. + +### 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 | + +These exact module specifiers use the host's runtime instances. A client bundle that requests another host module fails with `Module "" 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. + +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. + +## 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: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; +import { Main } from "./main.client"; + +export default function contribute(plugin: PluginContext) { + plugin.addSurface("main", Main); + return () => {}; +} +``` + +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: + +`main.client.tsx`: + +```tsx +import type { PluginSurfaceProps } from "@getpaseo/plugin"; +import { useMemo } from "react"; +import { Text, View } from "react-native"; + +export function Main({ theme, host, layout }: PluginSurfaceProps) { + const styles = useMemo( + () => ({ + screen: { + flex: 1, + padding: layout.compact ? 16 : 24, + backgroundColor: theme.colors.surface0, + }, + title: { color: theme.colors.foreground }, + detail: { color: theme.colors.foregroundMuted }, + }), + [theme, layout.compact], + ); + return ( + + {host.label} + {layout.platform} + + ); +} +``` + +`index.ts`: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; +import { Main } from "./main.client"; + +export default function contribute(plugin: PluginContext) { + plugin.addSurface("main", Main); + plugin.addSidebarItem({ + id: "main", + title: "My plugin", + icon: "Blocks", + surface: "main", + }); + return () => {}; +} +``` + +`PluginSurfaceProps` contains: + +| Field | Meaning | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| `theme` | Typed `PluginTheme` color tokens for the active Paseo theme. | +| `host` | Selected host `id` and display `label`. | +| `layout` | `compact` and the `ios`, `android`, or `web` platform. | +| `navigation` | Optional client navigation. `openAgent({ agentId })` and `openWorkspace({ workspaceId })` open targets on the selected host. | + +Paseo owns the route, header, close action, host picker, error boundary, and query client. The plugin owns the surface body. + +## Host UI + +Import Paseo-owned UI from `@getpaseo/plugin/react-native` in `*.client.tsx` files. This example +opens a controlled modal, renders a host icon, and confirms the action with a toast: + +```tsx +import type { PluginSurfaceProps } from "@getpaseo/plugin"; +import { Icon, Modal, useToast } from "@getpaseo/plugin/react-native"; +import { useState } from "react"; +import { Pressable, Text, View } from "react-native"; + +export function IssueActions({ theme }: PluginSurfaceProps) { + const [open, setOpen] = useState(false); + const toast = useToast(); + + function saveIssue() { + toast.show("Issue saved", { variant: "success" }); + setOpen(false); + } + + return ( + + setOpen(true)}> + + + Edit issue + + + + } + open={open} + onOpenChange={setOpen} + > + + + Save + + + + + ); +} +``` + +### Modal + +`Modal` uses a bottom sheet on compact layouts and a centered dialog otherwise. The plugin owns +the `open` state. + +| Prop | Type | Required | Behavior | +| -------------- | ------------------------- | -------- | -------------------------------------------- | +| `title` | `string` | Yes | Labels the modal and its visible header. | +| `icon` | `ReactNode` | No | Renders before the title in the header. | +| `open` | `boolean` | Yes | Shows the modal content when `true`. | +| `onOpenChange` | `(open: boolean) => void` | Yes | Receives `false` when the user dismisses it. | +| `children` | `ReactNode` | Yes | Contains `Modal.Content`. | + +`Modal.Content` owns the body below the host-rendered header: + +| Prop | Type | Required | Behavior | +| ---------- | ----------- | -------- | --------------------------------------------- | +| `children` | `ReactNode` | Yes | Renders the plugin's React Native UI content. | + +The close button, backdrop, platform back action, web Escape key, and compact sheet gesture dismiss +the modal. Dismissal calls `onOpenChange(false)`; the plugin must update `open` to close it. + +Modal children keep the plugin runtime context. `usePaseo`, `useRpc`, `useWorkspace`, and +`useAgent` work inside them. + +### Toasts + +`useToast()` returns two methods: + +| Method | Behavior | +| ------------------------- | ----------------------------------------------------------- | +| `show(message, options?)` | Shows a toast for 2,200 ms unless `durationMs` is supplied. | +| `error(message)` | Shows an error toast for 3,200 ms. | + +`show` accepts these options: + +| Option | Type | Default | +| ------------ | ---------------------------------------------------------- | ----------- | +| `variant` | `"default" \| "info" \| "success" \| "warning" \| "error"` | `"default"` | +| `durationMs` | `number` | `2200` | + +Showing another toast replaces the currently visible toast. An empty message is ignored. + +### Icons + +`Icon` renders a [Lucide icon](https://lucide.dev/icons/) from Paseo's installed icon set. Plugin bundles do not import +`lucide-react-native` or `react-native-svg`. + +| Prop | Type | Required | Behavior | +| ------- | -------- | -------- | ----------------------------------------------- | +| `name` | `string` | Yes | Lucide icon name. Unknown names render nothing. | +| `size` | `number` | No | Icon width and height. | +| `color` | `string` | No | Icon color. Use a plugin theme token. | + +## Timeline items + +A plugin can replace an agent timeline entry with its own data and React Native renderer. Both +registrations are client contributions. Paseo applies the transformer while building the render +model, including every live streaming update. + +```tsx +import type { PluginContext, PluginTimelineItemProps } from "@getpaseo/plugin"; +import { Text } from "react-native"; +import { z } from "zod"; + +const schema = z.object({ label: z.string() }); + +function Card({ item, theme }: PluginTimelineItemProps>) { + return {item.data.label}; +} + +export default function contribute(plugin: PluginContext) { + plugin.addTimelineTransformer({ + id: "command-card", + query: { itemType: "tool_call" }, + transform({ item, phase }) { + return { + items: [ + { + type: "plugin", + kind: "command-card", + version: 1, + data: { label: item.name, phase }, + }, + ], + }; + }, + }); + plugin.addTimelineRenderer({ + kind: "command-card", + version: 1, + schema, + Component: Card, + }); + return () => {}; +} +``` + +`query.itemType` is the stable, coarse selector. Inspect the selected item inside `transform` for +provider- or tool-specific recognition. Returning `undefined` keeps the original entry. Returning +`items` replaces it; an empty array removes it. Item `data` must be JSON-compatible. The `phase` +input is `"streaming"` for running tool calls and loading reasoning, and `"complete"` otherwise. +Each replacement may set an optional plugin-local `id`; otherwise Paseo uses its index within that +source item's output. + +Renderers receive `agentId`, `item`, `timestamp`, `theme`, `host`, and `layout`. Paseo validates +`item.data` with the registered schema before rendering. Keep transformers synchronous and +deterministic. Paseo memoizes results by source-item reference and derives replacement identity from +the source row, so updates to one streaming item do not remount its renderer. Use the exported +`useRevealedText(text, phase)` hook when a renderer should pace streaming text like Paseo's built-in +assistant rows. + +### Append a timeline row from the daemon + +A server handler can add a plugin-owned row to canonical history: + +```ts +import type { PluginHandlerContext } from "@getpaseo/plugin"; + +async function publishReview(agentId: string, { paseo }: PluginHandlerContext) { + await paseo.agents.ref(agentId).timeline.append({ + type: "plugin", + id: "review", + kind: "review-result", + version: 1, + data: { verdict: "ready" }, + }); +} +``` + +| Field | Type | Required | Behavior | +| --------- | ---------------- | -------- | -------------------------------------------------------------- | +| `type` | `"plugin"` | Yes | Selects the plugin timeline variant. | +| `id` | `string` | Yes | Stable plugin-local identity. Reusing it replaces the old row. | +| `kind` | `string` | Yes | Selects the registered renderer. | +| `version` | positive integer | Yes | Selects the renderer contract version. | +| `data` | JSON-compatible | Yes | Renderer payload, at most 64 KiB after JSON serialization. | + +The daemon stamps `pluginId` from the calling plugin session and rejects this RPC from non-plugin +sessions. The row appears live, survives timeline refetches, and keeps only the latest value for the +same plugin and `id`. If its renderer is missing, Paseo shows the existing unavailable row. Daemons +reject `data` over the limit rather than truncating it. Daemons that support this operation +advertise `server_info.features.pluginTimelineItems`. + +## Theme and layout + +Plugin UI runs on desktop, browser, iOS, and Android, across every Paseo theme. `theme` is a typed `PluginTheme` mapped from the active host theme. Color and spacing must come from those props. Hardcoded colors and unstyled `Text` break when the host theme changes. + +Recreate styles when `theme` or `layout.compact` changes. + +| Key | Required for | Use it for | +| ------------------------------- | -------------------------- | ----------------------------------- | +| `theme.colors.foreground` | Every primary `Text` | Titles and body copy | +| `theme.colors.foregroundMuted` | Secondary `Text` | Labels and supporting copy | +| `theme.colors.surface0` | Root view | Panel background | +| `theme.colors.surface1` | Raised surfaces | Cards and panels | +| `theme.colors.surface2` | Control surfaces | Inputs and secondary controls | +| `theme.colors.border` | Surface boundaries | Borders and dividers | +| `theme.colors.accent` | Primary action fills | Buttons and selected states | +| `theme.colors.accentForeground` | Text on an accent fill | Button labels | +| `theme.colors.statusSuccess` | Success feedback | Success messages and indicators | +| `theme.colors.statusWarning` | Warning feedback | Warning messages and indicators | +| `theme.colors.statusDanger` | Failure copy | Error messages and destructive text | +| `layout.compact` | Padding and stacking | `true` on mobile and narrow windows | +| `layout.platform` | Platform-specific behavior | `ios`, `android`, or `web` | + +Do not hardcode `#000`, `#fff`, or React Native's default text color. Primary copy uses `foreground`. Labels use `foregroundMuted`. Tighten padding when `layout.compact` is true. + +Workspace and agent panels receive the same `theme`, `layout`, and optional `navigation` fields. + +## 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: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; + +export default function contribute(plugin: PluginContext) { + plugin.addTheme({ + id: "mocha", + name: "Catppuccin Mocha", + appearance: "dark", + colors: { + background: "#1e1e2e", + foreground: "#cdd6f4", + raised: "#313244", + control: "#45475a", + border: "#45475a", + accent: "#cba6f7", + mutedForeground: "#a6adc8", + ring: "#6c7086", + }, + }); + return () => {}; +} +``` + +Every color is a hex string; anything else fails to load. Paseo expands the palette into the full +token set the built-in dark themes use, so a contributed theme covers panels, menus, diffs, status +colors, and the terminal without listing them. + +| Color | Becomes | +| ----------------- | ----------------------------------------------------------------- | +| `background` | App, workspace, and terminal background | +| `foreground` | Primary text, terminal foreground and cursor | +| `raised` | Cards, popovers, and hovered rows | +| `control` | Inputs, secondary fills, and the light-theme sidebar | +| `border` | Borders and the highest raised-surface tint | +| `accent` | Buttons, selection, and focus. Optional; `foreground` if omitted. | +| `mutedForeground` | Secondary text | +| `ring` | Focus rings, scrollbars, and terminal bright black | + +`appearance` is `"light"` or `"dark"`. Paseo uses it to select the matching surface, status, +diff, syntax, terminal, and shadow derivation. + +Only one contributed theme is active at a time. Selecting one persists the choice; if the plugin is +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. + +## Workspace panels + +Register one panel for workspace or agent context: + +`review.client.tsx`: + +```tsx +import { type PluginAgentPanelProps, useAgent, useWorkspace } from "@getpaseo/plugin"; +import { useMemo } from "react"; +import { Text, View } from "react-native"; + +export function ReviewPanel({ theme, layout, workspaceId, agentId }: PluginAgentPanelProps) { + const workspaceName = useWorkspace(workspaceId, (workspace) => workspace.name); + const agent = useAgent(agentId, ({ id, title }) => ({ id, title })); + const styles = useMemo( + () => ({ + screen: { + flex: 1, + padding: layout.compact ? 16 : 24, + backgroundColor: theme.colors.surface0, + }, + title: { color: theme.colors.foreground }, + detail: { color: theme.colors.foregroundMuted }, + }), + [theme, layout.compact], + ); + return ( + + {workspaceName} + {agent?.title ?? agent?.id} + + ); +} +``` + +`index.ts`: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; +import { ReviewPanel } from "./review.client"; + +export default function contribute(plugin: PluginContext) { + plugin.addWorkspacePanel({ + id: "review", + title: "Review", + icon: "Scan", + context: "agent", + locations: ["workspace", "explorer"], + Component: ReviewPanel, + }); + return () => {}; +} +``` + +`addWorkspacePanel` fields: + +| Field | Required | Meaning | +| ----------- | -------- | ------------------------------------------------------------- | +| `id` | Yes | Plugin-local panel ID. | +| `title` | Yes | Workspace-tab title. | +| `icon` | Yes | Lucide icon name. | +| `context` | Yes | `workspace` or `agent`. | +| `locations` | No | `workspace` and/or `explorer`. Defaults to `workspace`. | +| `Component` | Yes | React Native component matching the selected context's props. | + +A workspace panel receives `PluginWorkspacePanelProps`: `context: "workspace"`, `theme`, `host`, `layout`, and `workspaceId`. An agent panel receives `PluginAgentPanelProps`: `context: "agent"`, the same common fields and `workspaceId`, plus `agentId`. + +Read cached state with `useWorkspace(workspaceId, selector)` and `useAgent(agentId, selector)`. A selector is required. Paseo compares its result shallowly, so selecting `{ name, status }` does not re-render when unrelated fields change. Select every field the component renders in one call; do not select the whole snapshot. + +Both hooks return `null` when the record is unavailable. Otherwise they run synchronously against normalized client state. Snapshot DTOs and their nested values are deeply readonly and frozen at runtime. Do not call plugin RPC to discover the current workspace or agent. Fetch optional or vendor-specific enrichment after the component renders. + +Workspace snapshot fields: + +| Field | Type | +| -------------------- | ----------------------------------------------------------------- | +| `id` | `string` | +| `projectId` | `string` | +| `projectDisplayName` | `string` | +| `projectRootPath` | `string` | +| `directory` | `string` | +| `projectKind` | `"git" \| "non_git" \| "directory"` | +| `kind` | `"directory" \| "local_checkout" \| "checkout" \| "worktree"` | +| `name` | `string` | +| `title` | `string \| null` | +| `status` | `"needs_input" \| "failed" \| "running" \| "attention" \| "done"` | +| `statusEnteredAt` | ISO timestamp or `null` | +| `archivingAt` | ISO timestamp or `null` | +| `diffStat` | `{ additions: number; deletions: number } \| null` | + +Agent snapshot fields: + +| Field | Type | +| ------------------- | -------------------------------------------------------------- | +| `id` | `string` | +| `workspaceId` | `string` | +| `provider` | `string` | +| `status` | `"initializing" \| "idle" \| "running" \| "error" \| "closed"` | +| `createdAt` | ISO timestamp | +| `updatedAt` | ISO timestamp | +| `lastActivityAt` | ISO timestamp | +| `title` | `string \| null` | +| `cwd` | `string` | +| `model` | `string \| null` | +| `currentModeId` | `string \| null` | +| `thinkingOptionId` | `string \| null` | +| `requiresAttention` | `boolean` | +| `attentionReason` | `"finished" \| "error" \| "permission" \| null` | +| `parentAgentId` | `string \| null` | +| `labels` | `Record` | + +Paseo owns tab focus, splitting, closing, persistence, query state, the API/RPC providers, and the render error boundary. A restored tab whose plugin, panel, context, workspace, or agent is unavailable stays open with an unavailable message instead of crashing the workspace. + +## Command Center items + +Open the Command Center with **⌘K** on macOS or **Ctrl+K** on Windows and Linux, then search for the item title. + +Register an action and open a panel from the callback: + +```tsx +import { defineRpc } from "@getpaseo/plugin/server"; +import { z } from "zod"; + +const refreshReview = defineRpc({ + name: "review.refresh", + input: z.object({ agentId: z.string() }), + output: z.object({ refreshed: z.boolean() }), +}); + +plugin.addCommandCenterItem({ + id: "open-review", + title: "Open review", + icon: "Scan", + keywords: ["inspect"], + context: "agent", + async onSelect({ paseo, rpc, workspace, agent, openPanel }) { + await paseo.workspaces.ref(workspace.id).setTitle(`Review ${agent.id}`); + await rpc(refreshReview, { agentId: agent.id }); + openPanel("review"); + }, +}); +``` + +`addCommandCenterItem` fields: + +| Field | Required | Meaning | +| ---------- | -------- | ---------------------------------------------- | +| `id` | Yes | Plugin-local item ID. | +| `title` | Yes | Search result title. | +| `icon` | Yes | Lucide icon name. | +| `keywords` | No | Additional Command Center search terms. | +| `context` | Yes | `global`, `workspace`, or `agent`. | +| `onSelect` | Yes | Client-side callback for the matching context. | + +Global items appear on the installation's selected host. Workspace items appear only when that host has an active cached workspace. Agent items appear only when the focused workspace tab is an agent or an agent-context plugin panel whose cached record belongs to that workspace. Missing context removes the item rather than calling the plugin to discover it. + +Every callback receives: + +| Field | Context | Meaning | +| ------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- | +| `context` | All | Matching discriminator. | +| `paseo` | All | Selected host's existing `PaseoApi`. | +| `rpc(contract, input)` | All | Typed call to this installation's daemon-side plugin handler. | +| `openSurface(id)` | All | Opens one of this plugin's registered global surfaces. | +| `workspace` | Workspace and agent | Synchronous workspace snapshot. | +| `agent` | Agent | Synchronous matching agent snapshot. | +| `openPanel(id, options?)` | Workspace and agent | Opens a registered panel in the callback's current context. Pass `{ location: "explorer" }` to target Explorer. | + +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 + +Register a command that runs entirely in the Paseo client when the user submits it from the message +composer: + +```ts +plugin.addClientSlashCommand({ + name: "review", + description: "Run the review bot", + argumentHint: "[scope]", + context: "agent", + async onSubmit({ args, agent, rpc, openPanel }) { + await rpc(refreshReview, { agentId: agent.id, scope: args }); + openPanel("review"); + }, +}); +``` + +| Field | Required | Meaning | +| -------------- | -------- | ---------------------------------------------- | +| `name` | Yes | Command name without the leading slash. | +| `description` | Yes | Composer autocomplete description. | +| `argumentHint` | Yes | Short usage hint shown after the command name. | +| `context` | Yes | `"workspace"` or `"agent"`. | +| `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. + +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 +order wins a collision between plugins. Commands do not run while the composer has attachments. + +## 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: + +```tsx +import { + Icon, + type PluginClientContext, + type PluginComposerPillProps, + useAgent, +} from "@getpaseo/plugin"; +import { Text } from "react-native"; + +function ReviewPill({ theme, agentId }: PluginComposerPillProps) { + const agent = useAgent(agentId, ({ title }) => ({ title })); + return ( + <> + + + {agent?.title ?? "Review"} + + + ); +} + +export function contributeClient(client: PluginClientContext) { + const pills = new Map void>(); + const unsubscribe = client.paseo.agents.subscribe((update) => { + if (update.kind !== "upsert" || !update.agent.workspaceId) return; + const { id: agentId, workspaceId } = update.agent; + pills.get(agentId)?.(); + pills.set( + agentId, + client.addComposerPill({ + id: "review", + title: "Open review", + workspaceId, + agentId, + Component: ReviewPill, + async onPress() { + await client.rpc(refreshReview, { agentId }); + client.openPanel("review", { workspaceId, agentId }); + }, + }), + ); + }); + return () => { + unsubscribe(); + for (const remove of pills.values()) remove(); + }; +} +``` + +`addComposerPill` fields: + +| Field | Required | Meaning | +| ------------- | -------- | ---------------------------------------------------------- | +| `id` | Yes | Plugin-local ID within the target agent. | +| `title` | Yes | Accessible button label. | +| `workspaceId` | Yes | Workspace whose composer track owns the pill. | +| `agentId` | Yes | Agent whose composer track owns the pill. | +| `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`. +`addComposerPill` returns an idempotent removal function. Paseo also removes every outstanding pill +when the client entrypoint, 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 +current values with `useWorkspace` and `useAgent`. The plugin owns when the pill exists, its icon +and text, and the callback. `openPanel(id, { workspaceId, agentId? })` opens or focuses a panel +registered by the same plugin. + +## 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 "@getpaseo/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 ( + void createReviewWorkspace()}> + Create review workspace + + ); +} +``` + +The returned API covers projects, 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: + +`greeting.shared.ts`: + +```ts +import { defineRpc } from "@getpaseo/plugin/server"; +import { z } from "zod"; + +export const greeting = defineRpc({ + name: "greeting.create", + input: z.object({ name: z.string() }), + output: z.object({ message: z.string() }), +}); +``` + +`greeting.client.tsx`: + +```tsx +import { useRpc } from "@getpaseo/plugin"; +import { greeting } from "./greeting.shared"; + +export function GreetingButton() { + const createGreeting = useRpc(greeting); + // Call createGreeting({ name: "Ada" }) from an event or query. + return null; +} +``` + +`greeting.server.ts`: + +```ts +import type { output as ZodOutput } from "zod"; +import { greeting } from "./greeting.shared"; + +export function createGreeting({ name }: ZodOutput) { + return { message: `Hello, ${name}` }; +} +``` + +`index.ts`: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; +import { GreetingButton } from "./greeting.client"; +import { createGreeting } from "./greeting.server"; +import { greeting } from "./greeting.shared"; + +export default function contribute(plugin: PluginContext) { + plugin.handle(greeting, createGreeting); + plugin.addSurface("main", GreetingButton); + return () => {}; +} +``` + +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 adds `[paseo]` entries when the plugin starts loading, becomes ready, starts stopping, and has +stopped. It records compilation and load failures as stderr entries, including failures that happen +before the plugin subprocess starts. Paseo also 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 +``` + +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, compilation failure, 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. + +`issues.shared.ts`: + +```ts +import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin/server"; +import { z } from "zod"; + +export 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(), + }), + ), + }), +}); + +export const issues = defineAttachmentSource({ + id: "issues", + title: "Acme issue", + icon: "CircleDot", + pickerTitle: "Attach Acme issue", + searchPlaceholder: "Search by identifier or title", + search: searchIssues, +}); +``` + +`issues.server.ts`: + +```ts +import type { output as ZodOutput } from "zod"; +import { searchIssues } from "./issues.shared"; + +export function search({ query }: ZodOutput) { + return searchAcmeIssues(query); +} +``` + +`index.ts`: + +```ts +import type { PluginContext } from "@getpaseo/plugin"; +import { search } from "./issues.server"; +import { issues, searchIssues } from "./issues.shared"; + +export default function contribute(plugin: PluginContext) { + plugin.handle(searchIssues, search); + plugin.addAttachmentSource(issues); + return () => {}; +} +``` + +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. + +Workspace panels and Command Center items stay scoped to the active host and exact cached context. +Reload replaces their registrations. Disable, removal, host disconnect, and evaluation failure +remove Command Center items and clear the installation's query state. An already-restored panel tab +remains as unavailable until its matching contribution returns or the user closes it. Panel render +failures stay inside the plugin error boundary. + +## 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 add owner/repository +paseo plugin add https://git.example.com/owner/repository.git --ref main +paseo plugin add owner/monorepo:plugins/review +paseo plugin status [id] +paseo plugin update +paseo plugin update --all +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 ` to management commands when the target is not the CLI's default daemon. `remove` +never deletes a directory source; it deletes the managed checkout for a Git source. The install-time +`--id` is the runtime ID and allows the same directory or repository to be installed more than once. + +> **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. + +An existing directory wins over `owner/repository` GitHub shorthand. Append `:relative/path` when +the plugin lives below the repository root. Omit `--ref` to track the default branch. Explicit +branches track updates; tags and commits stay pinned. + +Most plugins should omit `build`. Use it only when the staged checkout must install a dependency +that Paseo does not provide, generate source or assets, or perform another required preparation +step: + +```json +{ + "id": "review", + "build": [ + ["npm", "ci"], + ["npm", "run", "build"] + ] +} +``` + +`build` is a list of non-empty argv arrays. Paseo runs each executable directly, without a shell, +from the staged plugin directory after resolving the exact commit and manifest. It never infers a +package manager or commands from lockfiles. Install and update both run `build` before validation, +compilation, activation, or replacement. A failing command reports its output, discards the +candidate, and leaves the installed/running version intact. The daemon log records each command and +output; with `--host`, execution is on that daemon host. + +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 `. | +| Reload fails | Read `paseo plugin ls` and `paseo plugin logs `, fix the source error, then reload; Paseo does not restore the previous bundle. | +| Plugin exits unexpectedly | Read `paseo plugin logs ` for retained initialization, cleanup, stderr, and final crash output. | diff --git a/public-docs/plugins/v0.8/index.md b/public-docs/plugins/v0.8/index.md new file mode 100644 index 0000000000..8a167bfbac --- /dev/null +++ b/public-docs/plugins/v0.8/index.md @@ -0,0 +1,271 @@ +--- +title: Plugin quickstart +description: Build, install, share, and update a trusted Paseo plugin. +nav: Paseo v0.8 — Preview +order: 46 +category: Plugins +--- + +# Plugin quickstart + +> **For the upcoming Paseo v0.8 release.** Use the [current v0.7 docs](/docs/plugins/v0.7) +> unless you are preparing a plugin for v0.8. + +> **Experimental:** The plugin API is still evolving, so expect breaking changes and updates to +> your plugins as Paseo evolves. See the [plugin roadmap](https://github.com/getpaseo/paseo/labels/plugins) +> for planned contribution surfaces. + +A plugin is a TypeScript project installed into one Paseo daemon. It can add +[surfaces and sidebar items](/docs/plugins/v0.8/reference#surfaces-and-sidebar-items), +[workspace panels](/docs/plugins/v0.8/reference#workspace-panels), +[Command Center items](/docs/plugins/v0.8/reference#command-center-items), +[slash commands](/docs/plugins/v0.8/reference#slash-commands), +[composer pills](/docs/plugins/v0.8/reference#composer-pills), +[timeline items](/docs/plugins/v0.8/reference#timeline-items), +[themes](/docs/plugins/v0.8/reference#contribute-a-theme), +[attachment sources](/docs/plugins/v0.8/reference#add-a-composer-attachment-source), and +[daemon-side RPCs](/docs/plugins/v0.8/reference#add-plugin-specific-backend-behavior). Client +contributions run on every Paseo client connected to that daemon, including mobile. + +This guide scaffolds a plugin, runs it, and adds a workspace panel to it. + +## Create a plugin + +Use an absolute path on the daemon machine: + +```bash +paseo plugin init /absolute/path/to/workspace-plugin +cd /absolute/path/to/workspace-plugin +npm install +``` + +`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. + +The scaffold is a working plugin: a sidebar surface with a button that asks the daemon for a +greeting through an RPC. + +```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/v0.8/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"; +import { useMemo } from "react"; +import { Text, View } from "react-native"; + +export function WorkspaceOverview({ theme, layout, workspaceId }: PluginWorkspacePanelProps) { + const workspace = useWorkspace(workspaceId, ({ name, directory }) => ({ + name, + directory, + })); + const styles = useMemo( + () => ({ + screen: { + flex: 1, + padding: layout.compact ? 16 : 24, + gap: layout.compact ? 8 : 12, + backgroundColor: theme.colors.surface0, + }, + title: { color: theme.colors.foreground, fontSize: layout.compact ? 20 : 24 }, + label: { color: theme.colors.foregroundMuted }, + detail: { color: theme.colors.foreground }, + }), + [theme, layout.compact], + ); + + return ( + + {workspace?.name} + Directory + {workspace?.directory} + + ); +} +``` + +`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/v0.8/reference#theme-and-layout) for the token list. + +Register the panel and a Command Center item that opens it by adding to `index.client.tsx`: + +```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"); + }, +}); +``` + +`icon` is a [Lucide](https://lucide.dev/icons/) icon name. + +## Edit and reload + +Source changes take effect only when you reload the plugin: + +```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 error in `paseo plugin ls`; fix the source and reload +again. + +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 owner/monorepo:plugins/workspace +paseo plugin add owner/repository --ref main +``` + +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 +paseo plugin update workspace-plugin +paseo plugin update --all +``` + +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/v0.8/reference#cli-reference) in its manifest. + +## Read backend logs + +Daemon-side handlers and cleanup can use normal Node logging: + +```ts +console.log("Refreshing issues"); +console.error("Issue refresh failed", error); +``` + +Read the recent output from **Settings → Plugins → Logs** or the CLI: + +```bash +paseo plugin logs workspace-plugin +paseo plugin logs workspace-plugin --json +``` + +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/v0.8/reference#debug-backend-output) for retention and what not to +log. + +## Next + +- [Plugin reference](/docs/plugins/v0.8/reference): every contribution type, its fields, the runtime + modules, hosts, and the CLI. +- [Migrate a plugin to runtime entries](/docs/plugins/v0.8/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. diff --git a/public-docs/plugins/migration.md b/public-docs/plugins/v0.8/migration.md similarity index 99% rename from public-docs/plugins/migration.md rename to public-docs/plugins/v0.8/migration.md index cae6bc9c7c..9cb7ea98c7 100644 --- a/public-docs/plugins/migration.md +++ b/public-docs/plugins/v0.8/migration.md @@ -2,12 +2,14 @@ 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 +order: 48 category: Plugins --- # Migrate a plugin to runtime entries +> **For the upcoming Paseo v0.8 release.** This migration is not required for Paseo v0.7. + 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. diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/v0.8/reference.md similarity index 99% rename from public-docs/plugins/reference.md rename to public-docs/plugins/v0.8/reference.md index bf3417018e..963968166b 100644 --- a/public-docs/plugins/reference.md +++ b/public-docs/plugins/v0.8/reference.md @@ -2,13 +2,15 @@ title: Plugin reference description: Local plugin files, client and server runtimes, platform limits, contributions, RPCs, lifecycle, hosts, and CLI commands. nav: Reference -order: 46 +order: 47 category: Plugins --- # Plugin reference -Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/migration). +> **For the upcoming Paseo v0.8 release.** Return to the [v0.8 quickstart](/docs/plugins/v0.8). + +Migrating an existing plugin? Follow the standalone [runtime-entry migration guide](/docs/plugins/v0.8/migration). Local plugins are directory sources installed into one Paseo daemon. A plugin can contribute: @@ -52,7 +54,7 @@ The required root manifest is `paseo-plugin.json`. It contains the default plugi | `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). +old `index.ts` fails to load and points at the [migration guide](/docs/plugins/v0.8/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. @@ -1068,7 +1070,7 @@ Use `paseo plugin ls` to read the current status and error. | Symptom | Check | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -| `Plugin entry split is required` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/migration). | +| `Plugin entry split is required` | The directory has only an `index.ts` entry. Follow the [migration guide](/docs/plugins/v0.8/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. | diff --git a/skills/paseo-plugin/SKILL.md b/skills/paseo-plugin/SKILL.md index eefe83339a..53110b8103 100644 --- a/skills/paseo-plugin/SKILL.md +++ b/skills/paseo-plugin/SKILL.md @@ -14,7 +14,7 @@ Build or manage the requested plugin directly. Use the current public docs to ca Fetch [https://paseo.sh/llms.txt](https://paseo.sh/llms.txt) first. Select and fetch the current plugin Markdown pages from that index before changing a plugin: - [Plugin quickstart](https://paseo.sh/docs/plugins.md) ([browser page](https://paseo.sh/docs/plugins)) -- [Plugin reference](https://paseo.sh/docs/plugins/reference.md) ([browser page](https://paseo.sh/docs/plugins/reference)) +- [Plugin reference](https://paseo.sh/docs/plugins/v0.8/reference.md) ([browser page](https://paseo.sh/docs/plugins/v0.8/reference)) Use the deployed docs when they disagree with this skill. Do not send the user away to read them instead of completing the work. @@ -598,7 +598,7 @@ Use `--host ` 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. +For an old mixed entry, follow the standalone [v0.8 runtime-entry migration guide](https://paseo.sh/docs/plugins/v0.8/migration) mechanically. ## Verify the outcome