docs(providers): document the provider installation contract

Plugin authors get the contract in the provider guide, with a worked
example that reports a version, checks for an update and runs the CLI's
own updater, and every field, deadline and cache in the reference.
The internal provider and plugin docs record why the three callbacks are
separate, that versions are opaque, that Paseo adds no verification to
an update, and how the plugin bridge carries and cancels each request.
This commit is contained in:
Mohamed Boudra
2026-11-14 09:39:40 +01:00
parent 59ab8b8c1f
commit fa8dcb372a
6 changed files with 365 additions and 0 deletions
+12
View File
@@ -510,6 +510,18 @@ before calling status; it exposes your diagnostic through the normal provider di
A command-backed provider without status is available when its executable resolves. Providers with
neither command nor status retain connection-based availability.
Implement optional `installation` to fill the **Installation** section of provider settings. The
bridge sends each callback as a `provider.installation.*` request carrying the launch `status`
receives plus `resolved`. `resolved: false` means the executable was not found and `command` is
the configured name, so answer `not_installed` instead of spawning it. Inspect and update-check
requests use the 30 s plugin request timeout; the daemon's 25 s update-check deadline sits below
it, so a slow check reports that deadline. `update` has no request timeout and streams output
through `provider.installation.report`. When the daemon stops waiting on any of the three, it
sends `provider.installation.cancel`, which aborts the callback's `signal`.
The rules shared with built-ins are in [providers.md](providers.md#installation-and-updates); the
author contract is in the
[public provider guide](../public-docs/plugins/providers.md#report-installation-and-updates).
A same-ID config entry without `extends` overrides the plugin's `enabled`, `command`, `env`, label,
description, and model configuration through the normal provider registry. `enabled: false` disables
selection and discovery. An entry with `extends` defines the user's own provider, shadows the plugin,
+41
View File
@@ -263,6 +263,47 @@ promise for completion: equal results, including equal discovery timestamps, emi
---
## Installation and updates
The **Installation** section of provider settings reads `AgentClient.installation`. Built-ins set
it on the client; plugins set `ProviderRegistration.installation`, which the plugin bridge maps to
the same interface. `ProviderInstallations` in `packages/server/src/server/agent/provider-installation/`
owns deadlines, caching and the one running update per provider, so a provider only answers.
Declare only what the vendor offers:
- `installUrl` and `updateUrl` link the vendor's own install and update docs.
- `inspect` reports the version the CLI prints. Versions are opaque: Paseo shows them as written
and never parses or compares them.
- `checkForUpdates` asks the source the CLI's own updater reads, such as the vendor's release
endpoint or the CLI's `update --check`. Leave it out when that source is inside the binary or
depends on how the CLI was installed, which is why Copilot and OpenCode have no check. Do not
build a release lookup of your own.
- `update` runs the CLI's own update command and passes its output through, using
`runUpdateCommand`. Paseo adds no verification, signature check or rollback, so the update does
exactly what the same command does in a terminal.
The three calls are separate because they cost differently. `inspect` runs whenever someone opens
provider settings, with a 20 s deadline and a 30 s cache. `checkForUpdates` usually reaches the
network, so the app asks only after `inspect` reports the CLI installed, and a conclusive answer
holds for an hour. `update` runs for minutes, streams output, and is aborted only when the daemon
stops.
The app shows **Update** only when a check answers `available` and the provider declares `update`.
A provider with `update` and no check, such as Copilot or OpenCode, never shows the button, and
users follow `updateUrl` instead.
Write the success message for the provider's process model. A CLI that Paseo starts once per agent
uses `updatedForNewAgents()`. OpenCode agents share one server that keeps the old binary running,
so its message asks the user to restart the daemon.
`createCliInstallation()` covers a CLI that prints `--version` and updates with a subcommand. It
resolves the configured command, so a profile that extends a built-in reports and updates the CLI
that profile launches. Clients for `extends: "acp"` providers declare no installation.
Test with fake executables, as `providers/provider-update-checks.test.ts` does. Running a real
updater during development replaces the CLI on your machine.
## Usage sources
See the [public usage source reference](../public-docs/plugins/reference.md#usage-sources) for the
+117
View File
@@ -427,6 +427,123 @@ export default function contribute(client: PluginClientContext) {
The same renderer can display items emitted by a provider, a client timeline transformer, or a
daemon timeline append. A renderer does not require a provider implementation.
## Report installation and updates
Add `installation` to your registration and the provider's settings show an **Installation**
section. Users see whether your CLI is installed and which version, whether an update is
available, and an **Update** button that runs your updater and shows its output. Every member is
optional, so declare only what your CLI supports:
| Member | Users see | Declare it when |
| ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
| `installUrl` | **Install instructions**, and **Install** while not installed | Users install a CLI |
| `updateUrl` | **Update instructions** | Your docs say how to update |
| `inspect` | **Version**, or **Not installed** | The CLI reports its version |
| `checkForUpdates` | **Up to date**, **Update available**, or **Couldn't check for updates** | You can ask the release source your CLI's updater uses |
| `update` | **Update** while an update is available, then the updater's output | The CLI updates itself with a command |
This `example-agent` prints its version, checks for a release with
`self-update --check --json`, and updates with `self-update`:
```ts
import { execCommand, spawnProcess, terminateProcess } from "@getpaseo/plugin/server";
import type {
ProviderInstallation,
ProviderInstallationLaunch,
} from "@getpaseo/plugin/server/provider";
async function run(launch: ProviderInstallationLaunch, args: string[], signal: AbortSignal) {
const { stdout } = await execCommand(launch.command, [...launch.args, ...args], {
env: launch.env,
timeout: 20_000,
signal,
});
return stdout.trim();
}
export const installation: ProviderInstallation = {
installUrl: "https://example.com/docs/install",
updateUrl: "https://example.com/docs/update",
async inspect({ launch, signal }) {
if (!launch?.resolved) return { status: "not_installed" };
// `example-agent --version` prints `1.4.2`.
return { status: "installed", version: await run(launch, ["--version"], signal) };
},
async checkForUpdates({ launch, signal }) {
if (!launch?.resolved) return { status: "unknown", message: "example-agent is not installed" };
// Asks the release source `example-agent self-update` installs from.
const answer = JSON.parse(await run(launch, ["self-update", "--check", "--json"], signal)) as {
latest: string;
updateAvailable: boolean;
};
return answer.updateAvailable
? { status: "available", versions: [answer.latest] }
: { status: "current" };
},
async update({ launch, signal, report }) {
if (!launch?.resolved) return { status: "failed", message: "example-agent is not installed" };
const child = spawnProcess(launch.command, [...launch.args, "self-update"], {
env: launch.env,
stdio: "pipe",
});
child.stdin.end();
child.stdout.on("data", (chunk: Buffer) => report({ type: "stdout", text: chunk.toString() }));
child.stderr.on("data", (chunk: Buffer) => report({ type: "stderr", text: chunk.toString() }));
const stop = () => void terminateProcess(child);
signal.addEventListener("abort", stop, { once: true });
const code = await new Promise<number | null>((resolve, reject) => {
child.once("error", reject);
child.once("close", resolve);
}).finally(() => signal.removeEventListener("abort", stop));
if (code !== 0) return { status: "failed", message: `self-update exited with code ${code}` };
return { status: "succeeded", message: "New sessions use the new version." };
},
};
```
Add it to the registration next to `command`:
```ts
export function createProvider(): ProviderRegistration {
return {
id: "example-agent",
label: "Example Agent",
command: ["example-agent"],
installation,
async connect(request) {
// ...
},
};
}
```
Each callback receives the launch a session would use. When `launch.resolved` is `false`, Paseo did
not find the executable and `command` is the configured name, so report `not_installed` without
running it. `launch` is absent when the registration declares no `command`. For an ACP provider,
spread `runAcpProvider()` into the registration and add `installation` beside it. Run version and
update probes with the launch's arguments before your session subcommand, such as `hoplite
--version` for a provider that runs `hoplite acp`.
Paseo treats versions as text. It shows `version` and `versions` as written and never compares
them, so your check decides what counts as newer. Ask the source your CLI's own updater asks, and
leave `checkForUpdates` out when you cannot. A check that returns `unknown`, throws, or misses its
deadline shows **Couldn't check for updates** with your message and never shows **Up to date**.
`update` runs only when a user selects **Update**, and Paseo runs one update per provider at a
time. Pass the updater's output to `report` unchanged; Paseo keeps the last 65,536 characters. Paseo adds no
verification of its own, so the update does what your command does in a terminal. Return
`succeeded` with a message that says when the new version takes effect, or `failed` with the reason.
Without `update`, an available update shows **Update instructions** when you declare `updateUrl`.
Paseo calls `inspect` when the settings open and keeps the answer for 30 seconds. It calls
`checkForUpdates` after `inspect` reports the CLI installed and keeps a `current` or `available`
answer for an hour. `inspect` must answer within 20 seconds and `checkForUpdates` within 25.
`update` has no deadline. `signal` aborts when Paseo stops waiting or the daemon stops.
See the [`installation` reference](/docs/plugins/reference#provider-installation) for every field.
## Adapt an ACP agent
Use the ACP shim when the agent already speaks ACP:
+97
View File
@@ -351,6 +351,103 @@ export default function contribute(client: PluginClientContext) {
同一个渲染器可以显示由 Provider、客户端时间线转换器或 daemon 时间线追加发出的条目。渲染器并不需要 Provider 实现。
## 报告安装与更新 {#report-installation-and-updates}
在注册中添加 `installation`,Provider 的设置中就会出现 **安装** 部分。用户可以看到你的 CLI 是否已安装、是哪个版本、是否有可用更新,以及一个 **更新** 按钮,它会运行你的更新程序并显示其输出。每个成员都是可选的,只声明你的 CLI 支持的部分:
| 成员 | 用户看到的内容 | 何时声明 |
| ----------------- | ------------------------------------------------- | --------------------------------------- |
| `installUrl` | **安装说明**,未安装时还有 **安装** | 用户需要安装 CLI |
| `updateUrl` | **更新说明** | 你的文档说明了如何更新 |
| `inspect` | **版本**,或 **未安装** | CLI 会报告自己的版本 |
| `checkForUpdates` | **已是最新**、**有可用更新** 或 **无法检查更新** | 你能询问 CLI 自带更新程序所用的发布来源 |
| `update` | 有可用更新时显示 **更新**,随后显示更新程序的输出 | CLI 能用一条命令更新自己 |
这个 `example-agent` 会打印自己的版本,用 `self-update --check --json` 检查发布,并用 `self-update` 更新:
```ts
import { execCommand, spawnProcess, terminateProcess } from "@getpaseo/plugin/server";
import type {
ProviderInstallation,
ProviderInstallationLaunch,
} from "@getpaseo/plugin/server/provider";
async function run(launch: ProviderInstallationLaunch, args: string[], signal: AbortSignal) {
const { stdout } = await execCommand(launch.command, [...launch.args, ...args], {
env: launch.env,
timeout: 20_000,
signal,
});
return stdout.trim();
}
export const installation: ProviderInstallation = {
installUrl: "https://example.com/docs/install",
updateUrl: "https://example.com/docs/update",
async inspect({ launch, signal }) {
if (!launch?.resolved) return { status: "not_installed" };
// `example-agent --version` prints `1.4.2`.
return { status: "installed", version: await run(launch, ["--version"], signal) };
},
async checkForUpdates({ launch, signal }) {
if (!launch?.resolved) return { status: "unknown", message: "example-agent is not installed" };
// Asks the release source `example-agent self-update` installs from.
const answer = JSON.parse(await run(launch, ["self-update", "--check", "--json"], signal)) as {
latest: string;
updateAvailable: boolean;
};
return answer.updateAvailable
? { status: "available", versions: [answer.latest] }
: { status: "current" };
},
async update({ launch, signal, report }) {
if (!launch?.resolved) return { status: "failed", message: "example-agent is not installed" };
const child = spawnProcess(launch.command, [...launch.args, "self-update"], {
env: launch.env,
stdio: "pipe",
});
child.stdin.end();
child.stdout.on("data", (chunk: Buffer) => report({ type: "stdout", text: chunk.toString() }));
child.stderr.on("data", (chunk: Buffer) => report({ type: "stderr", text: chunk.toString() }));
const stop = () => void terminateProcess(child);
signal.addEventListener("abort", stop, { once: true });
const code = await new Promise<number | null>((resolve, reject) => {
child.once("error", reject);
child.once("close", resolve);
}).finally(() => signal.removeEventListener("abort", stop));
if (code !== 0) return { status: "failed", message: `self-update exited with code ${code}` };
return { status: "succeeded", message: "New sessions use the new version." };
},
};
```
把它添加到注册中 `command` 的旁边:
```ts
export function createProvider(): ProviderRegistration {
return {
id: "example-agent",
label: "Example Agent",
command: ["example-agent"],
installation,
async connect(request) {
// ...
},
};
}
```
每个回调都会收到会话将使用的启动配置。当 `launch.resolved` 为 `false` 时,Paseo 没有找到可执行文件,`command` 是配置中写的名称,因此直接报告 `not_installed`,不要运行它。注册没有声明 `command` 时,`launch` 不存在。对于 ACP Provider,把 `runAcpProvider()` 展开到注册中,并在旁边添加 `installation`。版本和更新探测使用会话子命令之前的启动参数,例如对运行 `hoplite acp` 的 Provider 使用 `hoplite --version`。
Paseo 把版本当作文本。它按原样显示 `version` 和 `versions`,从不比较它们,因此由你的检查决定什么算更新。询问 CLI 自带更新程序所询问的来源;做不到时就不要声明 `checkForUpdates`。返回 `unknown`、抛出异常或超过期限的检查会显示 **无法检查更新** 和你的消息,绝不会显示 **已是最新**。
`update` 只在用户选择 **更新** 时运行,并且每个 Provider 同一时间只运行一个更新。把更新程序的输出原样传给 `report`;Paseo 保留最后 65,536 个字符。Paseo 不会额外做任何校验,所以更新的效果与在终端中运行你的命令相同。返回 `succeeded` 并用消息说明新版本何时生效,或返回 `failed` 并说明原因。没有 `update` 时,如果你声明了 `updateUrl`,可用更新会显示 **更新说明**。
Paseo 在设置打开时调用 `inspect`,并把结果保留 30 秒。它在 `inspect` 报告 CLI 已安装后调用 `checkForUpdates`,并把 `current` 或 `available` 结果保留一小时。`inspect` 必须在 20 秒内回答,`checkForUpdates` 必须在 25 秒内回答。`update` 没有期限。当 Paseo 停止等待或 daemon 停止时,`signal` 会中止。每个字段见 [`installation` 参考](/docs/plugins/reference#provider-installation)。
## 适配 ACP Agent {#adapt-an-acp-agent}
当 Agent 已经支持 ACP 时,使用 ACP 适配层:
+54
View File
@@ -440,6 +440,60 @@ It must resolve inside that directory to a regular file that follows the
[SVG icon rules](#svg-rules). Paseo reads and validates the file when the plugin starts; the string
is never inline SVG or a URL.
#### Provider installation
`ProviderRegistration.installation` fills the **Installation** section of the provider's settings.
Every member is optional. Paseo hides the section when you declare neither `inspect` nor
`installUrl`. [Report installation and updates](/docs/plugins/providers#report-installation-and-updates)
has a complete example. Import the types from `@getpaseo/plugin/server/provider`.
```ts
interface ProviderInstallation {
installUrl?: string;
updateUrl?: string;
inspect?(context: ProviderInstallationContext): Promise<ProviderInspection>;
checkForUpdates?(context: ProviderInstallationContext): Promise<ProviderUpdateCheck>;
update?(context: ProviderUpdateContext): Promise<ProviderUpdateResult>;
}
```
| Member | Called | Deadline | Answer kept |
| ----------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------ |
| `inspect` | When provider settings open | 20 s | 30 s |
| `checkForUpdates` | After `inspect` answers `installed` | 25 s | 1 hour for `current` or `available`, else 30 s |
| `update` | When the user selects **Update**, one at a time per provider | None | Paseo reads both answers again after `succeeded` |
**Refresh** in the provider's settings skips the kept answers. Paseo never calls these members
before a session or on a schedule. A deadline or a throw becomes an error that shows the message.
`installUrl` and `updateUrl` are `http` or `https` pages that Paseo opens in the browser. The
plugin fails to start when either is another kind of URL.
The context:
| Field | Type | Meaning |
| -------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `launch` | `ProviderInstallationLaunch \| undefined` | The launch a session would use, with `resolved`. Absent when the registration declares no `command`. |
| `signal` | `AbortSignal` | Aborts when Paseo stops waiting or the daemon stops. |
| `report` | `(event: ProviderUpdateReport) => void` | `update` only. Shows `{ type: "stdout" \| "stderr" \| "message", text }` to the user in order. |
`ProviderInstallationLaunch` is `{ command, args, env, resolved }`. With `resolved: true`, `command`
is the executable's path. With `resolved: false`, Paseo did not find the executable and `command`
is the configured name.
Answers:
| Type | Values |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ProviderInspection` | `{ status: "installed", version?: string }` or `{ status: "not_installed" }` |
| `ProviderUpdateCheck` | `{ status: "current" }`, `{ status: "available", versions?: string[], message?: string }`, or `{ status: "unknown", message?: string }` |
| `ProviderUpdateResult` | `{ status: "succeeded", message?: string }` or `{ status: "failed", message: string }` |
Paseo shows `version`, `versions` and `message` as written and does not parse, sort or compare
them. It keeps the last 65,536 characters of `report` output. An answer that does not match these
shapes is an error. **Update** appears only when `checkForUpdates` answers `available` and you
declare `update`; without `update`, Paseo offers `updateUrl` instead.
### Usage sources
**Requires Paseo 0.11.** Register a source from your server entry with
+44
View File
@@ -367,6 +367,50 @@ Paseo 刷新 Agent 的方式是关闭它当前的 Provider 会话,再用当前
`ProviderRegistration.icon` 是相对于插件目录的文件路径,例如 `icon.svg`。它必须解析到该目录内一个遵循 [SVG 图标规则](#svg-rules)的普通文件。Paseo 在插件启动时读取并校验该文件;这个字符串从不是内联 SVG 或 URL。
#### Provider 安装 {#provider-installation}
`ProviderRegistration.installation` 填充 Provider 设置中的 **安装** 部分。每个成员都是可选的。`inspect` 和 `installUrl` 都没有声明时,Paseo 会隐藏这个部分。完整示例见[报告安装与更新](/docs/plugins/providers#report-installation-and-updates)。类型从 `@getpaseo/plugin/server/provider` 导入。
```ts
interface ProviderInstallation {
installUrl?: string;
updateUrl?: string;
inspect?(context: ProviderInstallationContext): Promise<ProviderInspection>;
checkForUpdates?(context: ProviderInstallationContext): Promise<ProviderUpdateCheck>;
update?(context: ProviderUpdateContext): Promise<ProviderUpdateResult>;
}
```
| 成员 | 调用时机 | 期限 | 结果保留时间 |
| ----------------- | ------------------------------------------------ | ----- | ----------------------------------------------- |
| `inspect` | 打开 Provider 设置时 | 20 秒 | 30 秒 |
| `checkForUpdates` | `inspect` 回答 `installed` 之后 | 25 秒 | `current` 或 `available` 为一小时,其他为 30 秒 |
| `update` | 用户选择 **更新** 时,每个 Provider 同一时间一个 | 无 | `succeeded` 之后 Paseo 重新读取两个结果 |
Provider 设置中的 **刷新** 会跳过保留的结果。Paseo 从不在会话开始前或按计划调用这些成员。超过期限或抛出异常会变成显示该消息的错误。
`installUrl` 和 `updateUrl` 是 Paseo 在浏览器中打开的 `http` 或 `https` 页面。其中任何一个是其他类型的 URL 时,插件无法启动。
上下文:
| 字段 | 类型 | 含义 |
| -------- | ----------------------------------------- | --------------------------------------------------------------------------------------- |
| `launch` | `ProviderInstallationLaunch \| undefined` | 会话将使用的启动配置,带有 `resolved`。注册没有声明 `command` 时不存在。 |
| `signal` | `AbortSignal` | 当 Paseo 停止等待或 daemon 停止时中止。 |
| `report` | `(event: ProviderUpdateReport) => void` | 仅用于 `update`。按顺序向用户显示 `{ type: "stdout" \| "stderr" \| "message", text }`。 |
`ProviderInstallationLaunch` 是 `{ command, args, env, resolved }`。`resolved: true` 时,`command` 是可执行文件的路径。`resolved: false` 时,Paseo 没有找到可执行文件,`command` 是配置中写的名称。
结果:
| 类型 | 取值 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `ProviderInspection` | `{ status: "installed", version?: string }` 或 `{ status: "not_installed" }` |
| `ProviderUpdateCheck` | `{ status: "current" }`、`{ status: "available", versions?: string[], message?: string }` 或 `{ status: "unknown", message?: string }` |
| `ProviderUpdateResult` | `{ status: "succeeded", message?: string }` 或 `{ status: "failed", message: string }` |
Paseo 按原样显示 `version`、`versions` 和 `message`,不解析、排序或比较它们。它保留 `report` 输出的最后 65,536 个字符。不符合这些结构的结果是错误。只有当 `checkForUpdates` 回答 `available` 且你声明了 `update` 时才会出现 **更新**;没有 `update` 时,Paseo 改为提供 `updateUrl`。
### 用量来源 {#usage-sources}
**需要 Paseo 0.11**。在服务端入口中用 `server.registerUsageSource()` 注册一个来源。从 `@getpaseo/plugin/server/usage` 导入它的契约和辅助函数。