diff --git a/docs/plugins.md b/docs/plugins.md index d6c2228d69..e764ef61b7 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -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, diff --git a/docs/providers.md b/docs/providers.md index 6d9ea2a6ac..e0c313edab 100644 --- a/docs/providers.md +++ b/docs/providers.md @@ -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 diff --git a/public-docs/plugins/providers.md b/public-docs/plugins/providers.md index 5495405bfd..017827f49a 100644 --- a/public-docs/plugins/providers.md +++ b/public-docs/plugins/providers.md @@ -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((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: diff --git a/public-docs/plugins/providers.zh-CN.md b/public-docs/plugins/providers.zh-CN.md index e917ba0538..bc53dda773 100644 --- a/public-docs/plugins/providers.zh-CN.md +++ b/public-docs/plugins/providers.zh-CN.md @@ -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((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 适配层: diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/reference.md index 7e9247d452..9fa457ed5b 100644 --- a/public-docs/plugins/reference.md +++ b/public-docs/plugins/reference.md @@ -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; + checkForUpdates?(context: ProviderInstallationContext): Promise; + update?(context: ProviderUpdateContext): Promise; +} +``` + +| 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 diff --git a/public-docs/plugins/reference.zh-CN.md b/public-docs/plugins/reference.zh-CN.md index 05d34ac07c..45ca7142b3 100644 --- a/public-docs/plugins/reference.zh-CN.md +++ b/public-docs/plugins/reference.zh-CN.md @@ -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; + checkForUpdates?(context: ProviderInstallationContext): Promise; + update?(context: ProviderUpdateContext): Promise; +} +``` + +| 成员 | 调用时机 | 期限 | 结果保留时间 | +| ----------------- | ------------------------------------------------ | ----- | ----------------------------------------------- | +| `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` 导入它的契约和辅助函数。