diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5641086..872c84a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,7 +37,7 @@ jobs: uses: actions/checkout@v6 with: repository: zai-org/ZCode - ref: 872ad960de7ec172591f7e1952f7849229f94521 + ref: 29628c9acdb81b703bbd4080c207a0e7ce5e276e path: zcode-source persist-credentials: false - uses: actions/setup-node@v6 @@ -59,48 +59,43 @@ jobs: run: npm run test:upstream -- "$GITHUB_WORKSPACE/paseo" runtime: - name: Official stdio runtime contract - runs-on: ubuntu-24.04 - timeout-minutes: 40 + name: Managed runtime contract (${{ matrix.target }}) + strategy: + fail-fast: false + matrix: + include: + - target: darwin-arm64 + runner: macos-15 + - target: linux-x64 + runner: ubuntu-24.04 + - target: linux-arm64 + runner: ubuntu-24.04-arm + - target: win-x64 + runner: windows-2025 + - target: win-arm64 + runner: windows-11-arm + runs-on: ${{ matrix.runner }} + timeout-minutes: 30 + defaults: + run: + shell: bash steps: - uses: actions/checkout@v6 with: - path: plugin - persist-credentials: false - - uses: actions/checkout@v6 - with: - repository: zai-org/ZCode - ref: 872ad960de7ec172591f7e1952f7849229f94521 - path: zcode-source persist-credentials: false + # The plugin runs on the daemon's Node.js; ZCode uses the managed Node.js. - uses: actions/setup-node@v6 with: - node-version: "24.14.0" - - uses: pnpm/action-setup@v4 - with: - version: "10.33.2" - - name: Build the official integrated CLI - working-directory: zcode-source - run: | - pnpm install --frozen-lockfile - pnpm exec tsc -b packages/shared - node scripts/build-zcode.mjs --base-url https://example.invalid/zcode/ - - name: Extract outside the source checkout - run: | - mkdir "$RUNNER_TEMP/zcode-runtime" - sha256sum zcode-source/dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz - tar -xzf zcode-source/dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz -C "$RUNNER_TEMP/zcode-runtime" - echo "PASEO_ZCODE_RUNTIME=$RUNNER_TEMP/zcode-runtime/zcode" >> "$GITHUB_ENV" - echo "PASEO_ZCODE_NODE=$(command -v node)" >> "$GITHUB_ENV" - - uses: actions/upload-artifact@v4 - with: - name: zcode-runtime-linux-x64 - path: zcode-source/dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz + node-version: "22" + cache: npm - name: Install plugin dependencies - working-directory: plugin run: npm ci --include=dev - - name: Verify Provider behavior on the official runtime - working-directory: plugin + - name: Install the pinned managed runtime (ADR 15) + run: | + data=$(node -p "require('node:path').join(process.env.RUNNER_TEMP, 'zcode-data')") + echo "XDG_DATA_HOME=$data" >> "$GITHUB_ENV" + XDG_DATA_HOME="$data" npm run setup:managed-runtime + - name: Verify Provider behavior on the managed runtime # Resume uses Paseo's saved mode and Plan settings (ADR 14). # The separate test:native-restore tracks unsupported settings-free resume. run: npm run test:stdio-runtime @@ -120,20 +115,14 @@ jobs: persist-credentials: false - uses: actions/setup-node@v6 with: - node-version: "24.14.0" + node-version: "22" cache: npm - - uses: actions/download-artifact@v4 - with: - name: zcode-runtime-linux-x64 - path: runtime-archive - - name: Configure official runtime - run: | - mkdir "$RUNNER_TEMP/zcode-runtime" - tar -xzf runtime-archive/zcode-3.14.0.tar.gz -C "$RUNNER_TEMP/zcode-runtime" - echo "PASEO_ZCODE_RUNTIME=$RUNNER_TEMP/zcode-runtime/zcode" >> "$GITHUB_ENV" - echo "PASEO_ZCODE_NODE=$(command -v node)" >> "$GITHUB_ENV" - name: Install dependencies run: npm ci --include=dev + - name: Install the pinned managed runtime + run: | + echo "XDG_DATA_HOME=$RUNNER_TEMP/zcode-data" >> "$GITHUB_ENV" + XDG_DATA_HOME="$RUNNER_TEMP/zcode-data" npm run setup:managed-runtime - name: Run isolated real-model E2E env: GLM_API_KEY: ${{ secrets.GLM_API_KEY }} diff --git a/.github/workflows/zcode-runtime-release.yml b/.github/workflows/zcode-runtime-release.yml new file mode 100644 index 0000000..1b5f13b --- /dev/null +++ b/.github/workflows/zcode-runtime-release.yml @@ -0,0 +1,179 @@ +name: ZCode Runtime Release + +# Builds the integrated ZCode CLI from the pinned, unmodified public source, +# adds upstream license material, verifies it on every managed platform and +# publishes it only for zcode-runtime-v tags (ADR 15). +on: + push: + tags: ["zcode-runtime-v*"] + pull_request: + paths: + - .github/workflows/zcode-runtime-release.yml + - scripts/package-zcode-runtime.mjs + - scripts/zcode-manifest.mjs + - scripts/check-stdio-runtime.mjs + - server/discovery/manifest.ts + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: zcode-runtime-${{ github.ref }} + cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }} + +env: + # The same Node.js builds the archive and runs Server/Agent in verification. + NODE_VERSION: "24.21.0" + +jobs: + build: + name: Build runtime archive + runs-on: ubuntu-24.04 + timeout-minutes: 30 + outputs: + version: ${{ steps.package.outputs.version }} + commit: ${{ steps.package.outputs.commit }} + asset: ${{ steps.package.outputs.asset }} + sha256: ${{ steps.package.outputs.sha256 }} + size: ${{ steps.package.outputs.size }} + steps: + - uses: actions/checkout@v6 + with: + path: plugin + persist-credentials: false + - uses: actions/setup-node@v6 + with: + node-version: ${{ env.NODE_VERSION }} + - name: Install plugin dependencies + working-directory: plugin + run: npm ci --include=dev + - name: Resolve pinned ZCode source + id: source + working-directory: plugin + run: echo "commit=$(node scripts/package-zcode-runtime.mjs commit)" >> "$GITHUB_OUTPUT" + - uses: actions/checkout@v6 + with: + repository: zai-org/ZCode + ref: ${{ steps.source.outputs.commit }} + path: zcode-source + persist-credentials: false + - uses: pnpm/action-setup@v4 + with: + version: "10.33.2" + - name: Build the official integrated CLI + working-directory: zcode-source + run: | + pnpm install --frozen-lockfile + pnpm exec tsc -b packages/shared + node scripts/build-zcode.mjs --base-url https://example.invalid/zcode/ + - name: Add upstream notices and build provenance + id: package + working-directory: plugin + env: + TAG: ${{ startsWith(github.ref, 'refs/tags/') && github.ref_name || '' }} + run: node scripts/package-zcode-runtime.mjs package --source ../zcode-source --out ../runtime-release ${TAG:+--tag "$TAG"} + - uses: actions/upload-artifact@v4 + with: + name: zcode-runtime + path: runtime-release/ + if-no-files-found: error + + verify: + name: Verify ${{ matrix.target }} + needs: build + strategy: + fail-fast: false + matrix: + include: + - target: darwin-arm64 + runner: macos-15 + - target: linux-x64 + runner: ubuntu-24.04 + - target: linux-arm64 + runner: ubuntu-24.04-arm + - target: win-x64 + runner: windows-2025 + - target: win-arm64 + runner: windows-11-arm + runs-on: ${{ matrix.runner }} + timeout-minutes: 30 + defaults: + run: + shell: bash + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + - uses: actions/setup-node@v6 + with: + node-version: ${{ env.NODE_VERSION }} + cache: npm + - uses: actions/download-artifact@v4 + with: + name: zcode-runtime + path: runtime-archive + - name: Check the archive and extract it outside the checkout + env: + ASSET: ${{ needs.build.outputs.asset }} + SHA256: ${{ needs.build.outputs.sha256 }} + run: | + actual=$(node -e "const c=require('node:crypto').createHash('sha256');c.update(require('node:fs').readFileSync(process.argv[1]));console.log(c.digest('hex'))" "runtime-archive/$ASSET") + test "$actual" = "$SHA256" + mkdir ../zcode-runtime + tar -xzf "runtime-archive/$ASSET" -C ../zcode-runtime + for file in LICENSE NOTICE.md THIRD-PARTY-NOTICES.md BUILD-INFO.json; do + test -f "../zcode-runtime/zcode/$file" + done + echo "PASEO_ZCODE_RUNTIME=$(node -p "require('node:path').resolve('../zcode-runtime/zcode')")" >> "$GITHUB_ENV" + echo "PASEO_ZCODE_NODE=$(node -p process.execPath)" >> "$GITHUB_ENV" + - name: Install plugin dependencies + run: npm ci --include=dev + - name: Verify Provider behavior on the runtime + # Resume uses Paseo's saved mode and Plan settings (ADR 14). + run: npm run test:stdio-runtime + + publish: + name: Publish runtime release + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/zcode-runtime-v') + needs: [build, verify] + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: write + id-token: write + attestations: write + steps: + - uses: actions/download-artifact@v4 + with: + name: zcode-runtime + path: release + - uses: actions/attest-build-provenance@v4 + with: + subject-path: release/${{ needs.build.outputs.asset }} + - name: Create the GitHub release + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.ref_name }} + VERSION: ${{ needs.build.outputs.version }} + COMMIT: ${{ needs.build.outputs.commit }} + ASSET: ${{ needs.build.outputs.asset }} + SHA256: ${{ needs.build.outputs.sha256 }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + cat > notes.md <` release of this repository, both pinned by SHA-256 in `server/runtime/pins.ts` and installed only when the user starts setup. Setup RPCs never accept URLs, paths or versions from clients. `PASEO_ZCODE_RUNTIME` plus ordinary Node.js 24.14.0+ via `PASEO_ZCODE_NODE` override it; one variable alone is an error. Never fall back to Desktop/Electron. +- To ship a new ZCode version, update the source baseline, push a `zcode-runtime-v` tag so `.github/workflows/zcode-runtime-release.yml` builds, verifies on all managed platforms and publishes the archive, then pin the published SHA-256 and size. Never replace an existing release asset. +- `npm run test:stdio-runtime` uses the real runtime (override pair or managed runtime under `XDG_DATA_HOME`) with isolated data and a local model fixture. Resume guarantees require both Paseo's saved `mode` and `settings.plan_mode`; failures of this supported contract block release. Keep source SHA, distribution hashes, runtime versions and actual OS coverage separate. - `npm run test:native-restore` separately checks resume without explicit settings. The pinned upstream fails this unsupported path; retain its nonzero exit and run it when evaluating runtime updates. It is not a required CI or release condition (ADR 14). - Persistence handles use version 3. Do not migrate old Paseo handles or introduce Plan restoration storage. diff --git a/NOTICE.md b/NOTICE.md index 17b1e70..b18adec 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -8,9 +8,15 @@ `server/discovery`、`server/host`、`server/protocol`、マッピングとセッション処理、および対応テストは、同じ所有者の [paseo-zcode-patcher](https://github.com/supermomonga/paseo-zcode-patcher/tree/572100368774df7632728a72568466ac3632d458) の `patches/paseo-v0.7.2-zcode.patch` に含まれる ZCode 実装を基にしています。Paseo の内部 AgentClient 依存を除去し、公開 Provider API、JSON 検証、接続の終了処理を追加・変更しています。 -ZCode の Agent・認証・ツール・保存エンジン、認証情報、モデル設定は同梱しません。利用者が導入した公式統合 CLI の stdio Services Server を実行します。 +プラグイン本体には ZCode の Agent・認証・ツール・保存エンジン、認証情報、モデル設定を同梱しません。統合 CLI の stdio Services Server は、利用者が設定画面でセットアップを開始したときに取得します。 -`server/vendor/zcode` は [zai-org/ZCode](https://github.com/zai-org/ZCode/tree/872ad960de7ec172591f7e1952f7849229f94521) の RPC、V4 契約、wire 組み立てと純粋な差分適用、および必要なスキーマ依存を含みます。第一者コードは [上流 LICENSE](server/vendor/zcode/LICENSE) の Apache-2.0、RPC と wire codec の VS Code 由来部分は [MIT の通知](server/vendor/zcode/THIRD-PARTY-NOTICES.md) の条件を保持します。[上流 NOTICE](server/vendor/zcode/NOTICE.md) は全文を保持しており、上流製品全体の説明です。そこに記載された全機能・依存がプラグインへ同梱されることを意味しません。 +# ZCode ランタイムの配布 + +ZCode は統合 CLI を配布していないため、このリポジトリは `zcode-runtime-v` タグの GitHub Release で、統合 CLI 配布物の非公式ビルドを配布します(ADR 15)。CI が公開タグの無改変ソースを公式 `scripts/build-zcode.mjs` でビルドし、上流の `LICENSE`(Apache-2.0)、`NOTICE.md`、`THIRD-PARTY-NOTICES.md` と、出典・ビルド記録の `BUILD-INFO.json` を配布物に加えます。ソースは改変しません。第三者コンポーネントはそれぞれのライセンスに従い、上流が `third-party/inventory.json` で確認中とする項目もそのまま引き継ぎます。このビルドは ZCode・Z.ai の承認や保守を受けたものではなく、ZCode・Z.ai の商標の使用許諾も含みません。 + +Node.js は利用者のマシンが nodejs.org の公式成果物を直接取得します。このリポジトリは Node.js を再配布しません。 + +`server/vendor/zcode` は [zai-org/ZCode](https://github.com/zai-org/ZCode/tree/29628c9acdb81b703bbd4080c207a0e7ce5e276e) の RPC、V4 契約、wire 組み立てと純粋な差分適用、および必要なスキーマ依存を含みます。第一者コードは [上流 LICENSE](server/vendor/zcode/LICENSE) の Apache-2.0、RPC と wire codec の VS Code 由来部分は [MIT の通知](server/vendor/zcode/THIRD-PARTY-NOTICES.md) の条件を保持します。[上流 NOTICE](server/vendor/zcode/NOTICE.md) は全文を保持しており、上流製品全体の説明です。そこに記載された全機能・依存がプラグインへ同梱されることを意味しません。 ファイルごとの出典・SHA-256、private workspace import の変更、第三者通知の抽出範囲を [provenance.json](server/vendor/zcode/provenance.json) に記録しています。取得・照合は `scripts/sync-zcode-source.mjs` で行います。`npm run build` はこれらのライセンス・通知を `dist/licenses/zcode` にも配置します。 diff --git a/README.md b/README.md index e0ae61c..2048154 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,65 @@ # ZCode Provider for Paseo -Use ZCode models, tools and conversations through Paseo's public Provider API. The plugin launches the **official stdio Services Server from the integrated ZCode CLI distribution**. Authentication, models, tools and conversation storage remain owned by ZCode. ZCode Desktop is not required. +Use ZCode models, tools and conversations through Paseo's public Provider API. The plugin launches the **official stdio Services Server from the integrated ZCode CLI distribution**, which it can set up for you. Authentication, models, tools and conversation storage remain owned by ZCode. ZCode Desktop is not required. > Mode/Plan restoration is guaranteed when Paseo supplies both saved settings on resume. Without them, the pinned ZCode source can restore an older editing mode and drop Plan. That upstream defect remains unresolved and is outside the supported restoration contract. See [verification and remaining checks](docs/verification.md). This is an unofficial plugin. It is not endorsed or maintained by ZCode or Z.ai. The official RPC/V4 implementation is public source, but it is not a stable third-party SDK. -## Requirements and configuration +## Requirements -Configure the machine running the Paseo daemon: +| Setting | Requirement | +| -------------- | ------------------------------------------------------------------------------------------------------------ | +| Paseo | 0.8.0 or later; development SDK 0.9.0-beta.1 | +| Plugin Node.js | 22.12.0 or later (the Paseo daemon's runtime) | +| Managed setup | darwin-arm64, linux-x64, linux-arm64, win-x64, win-arm64 | +| ZCode | Managed: 3.14.3 with Node.js 24.21.0. Overrides: stable Server 3.14.0+ / Agent 0.16.9+ with Node.js 24.14.0+ | -| Setting | Requirement | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Paseo | 0.8.0 or later; development SDK 0.9.0-beta.1 | -| Plugin Node.js | 22.12.0 or later | -| `PASEO_ZCODE_RUNTIME` | Absolute path to an extracted **integrated CLI distribution**, containing `server/remote/zcode-server.cjs`, `agent/zcode.cjs`, its provider configuration, and `package.json` | -| `PASEO_ZCODE_NODE` | Absolute path to **ordinary Node.js 24.14.0 or later**, used for both Server and Agent | -| ZCode | Stable Server 3.14.0+ / Agent 0.16.9+; necessary files and runtime contracts are checked | +## Installation + +Enable **Settings → Plugins → Enable plugins** for the target daemon, then install and inspect: ```bash -export PASEO_ZCODE_RUNTIME=/absolute/path/to/zcode -export PASEO_ZCODE_NODE=/absolute/path/to/node +paseo plugin add supermomonga/paseo-plugin-zcode-provider +paseo plugin ls ``` -Set these in the daemon's environment, then restart the daemon. A terminal export does not change an already running Desktop application. Electron, `process.execPath`, Desktop discovery and `PASEO_ZCODE_INSTALL` are not alternative launch paths. Missing or invalid settings fail explicitly. +Paseo prepares the Git checkout and compiles the plugin. Update with `paseo plugin update zcode-provider`. Plugins execute with the daemon user's permissions. -You install and update the CLI and its Node.js runtime. Set up authentication and models using the official CLI/TUI. The plugin neither decrypts nor copies credentials. Session environment variables are forwarded, subject to ZCode's own proxy, certificate and runtime environment handling. +## Setup -The source baseline is `872ad960de7ec172591f7e1952f7849229f94521`. Its version strings do not prove that a public CLI artifact has been released or verified. [Build and validation instructions](docs/development.md) distinguish source, distribution hashes and actual runtime results. Newer stable versions are allowed, including major versions; passing the minimum check does not certify compatibility. macOS arm64 has been exercised locally; Linux x64 runtime checks ran in CI, with the settings-free restoration failure recorded separately. See the verification record for the exact coverage. Other OS/CPU combinations remain unverified. +Open **Settings → Plugins → zcode-provider → Setup** and choose **Download and install**. The screen lists every download, its SHA-256, size and license before you start. Setup runs on the machine hosting the daemon: -## Installation +- Node.js 24.21.0 from nodejs.org. +- The ZCode runtime 3.14.3 from this repository's [releases](https://github.com/supermomonga/paseo-plugin-zcode-provider/releases/tag/zcode-runtime-v3.14.3). ZCode does not publish its integrated CLI, so this is an **unofficial build** of the unmodified public source, made and verified by CI. It is not endorsed or maintained by ZCode or Z.ai. -Enable **Settings → Plugins → Enable plugins** for the target daemon, then install and inspect: +Both archives are verified against SHA-256 values pinned in the plugin and extracted to the daemon user's data directory: + +| OS | Destination | +| ------------- | ----------------------------------------------------- | +| Windows | `%LOCALAPPDATA%\paseo-plugin-zcode-provider\runtimes` | +| macOS / Linux | `~/.local/share/paseo-plugin-zcode-provider/runtimes` | + +An absolute `XDG_DATA_HOME` replaces the base directory on every OS. `PATH` and other installations are not changed. The plugin never installs anything until you start setup. + +After setup, the screen shows a login command. Run it in a terminal on the daemon machine to sign in through ZCode's browser authorization (`--no-browser` prints the URL). Then choose **ZCode** when creating an agent. The plugin neither decrypts nor copies credentials. + +**Remove** on the same screen deletes the managed runtime; `paseo plugin remove` does not. ZCode settings, logins and conversations are kept. + +### Using your own runtime + +Set both variables in the daemon's environment and restart the daemon to bypass the managed runtime: ```bash -paseo plugin add supermomonga/paseo-plugin-zcode-provider -paseo plugin ls +export PASEO_ZCODE_RUNTIME=/absolute/path/to/zcode # extracted integrated CLI distribution +export PASEO_ZCODE_NODE=/absolute/path/to/node # ordinary Node.js 24.14.0 or later ``` -Paseo prepares the Git checkout and compiles the plugin. Choose **ZCode** when creating an agent. Update with `paseo plugin update zcode-provider`. Plugins execute with the daemon user's permissions. +`PASEO_ZCODE_RUNTIME` must contain `server/remote/zcode-server.cjs`, `agent/zcode.cjs`, its provider configuration, and `package.json`. Setting only one variable is an error. Newer stable versions are allowed, including major versions; passing the minimum check does not certify compatibility. A terminal export does not change an already running Desktop application. Electron, `process.execPath` and Desktop discovery are never used. + +Session environment variables are forwarded, subject to ZCode's own proxy, certificate and runtime environment handling. + +The source baseline is `29628c9acdb81b703bbd4080c207a0e7ce5e276e` (ZCode `v3.14.3`). The managed runtime passed the stdio runtime contract on all five managed platforms in CI. See the [verification record](docs/verification.md) for exact coverage. ## Behavior @@ -61,7 +82,7 @@ New conversations support listing, resume and paged V4 history. Mode/Plan restor ## Diagnostics -**Settings → Plugins → zcode-provider → Diagnostics** shows the configured runtime, explicit Node.js executable/version, Server/Agent versions and hashes, minimum-version assessment and mapping location. The screen is read-only. Its optional version check does not prove that authentication or a model call succeeds. +**Settings → Plugins → zcode-provider → Diagnostics** shows whether the managed runtime or the environment override is in use, the runtime and Node.js paths and versions, Server/Agent versions and hashes, minimum-version assessment and mapping location. The screen is read-only. Its optional version check does not prove that authentication or a model call succeeds. ```bash paseo plugin logs zcode-provider @@ -71,6 +92,6 @@ For failures, report the operation, error code, structured diagnostic and versio ## Development and license -See [development](docs/development.md), [verification](docs/verification.md), [remaining work](docs/todo.md) and [ADR 13](docs/adr/0013-公開ソースの公式stdio-serverとv4会話状態を採用する.md). +See [development](docs/development.md), [verification](docs/verification.md), [remaining work](docs/todo.md), [ADR 13](docs/adr/0013-公開ソースの公式stdio-serverとv4会話状態を採用する.md) and [ADR 15](docs/adr/0015-プラグイン管理のzcodeランタイムとnode-jsを設定画面から導入する.md). -Original code is [MIT](LICENSE). Vendored ZCode RPC/contracts retain their upstream license and provenance. The icon retains Apache-2.0 attribution; the historical screenshot includes third-party UI and branding. See [NOTICE](NOTICE.md). +Original code is [MIT](LICENSE). Vendored ZCode RPC/contracts retain their upstream license and provenance. The ZCode runtime releases are Apache-2.0 builds of unmodified upstream source and include ZCode's LICENSE, NOTICE.md and THIRD-PARTY-NOTICES.md; third-party components keep their own terms. Node.js is downloaded from nodejs.org, not redistributed. The icon retains Apache-2.0 attribution; the historical screenshot includes third-party UI and branding. See [NOTICE](NOTICE.md). diff --git a/client/diagnostics.tsx b/client/diagnostics.tsx index 8781e1b..3b083f2 100644 --- a/client/diagnostics.tsx +++ b/client/diagnostics.tsx @@ -35,7 +35,14 @@ function Installation({ result, theme, compact }: SectionProps) { return ( - + {result.installRoot} @@ -85,7 +92,12 @@ function Compatibility({ result, theme, compact }: SectionProps) { {result.compatibilityReason} - + {`${result.nodeExecutable} (${result.nodeVersion})`} diff --git a/client/setup.tsx b/client/setup.tsx new file mode 100644 index 0000000..df57cc6 --- /dev/null +++ b/client/setup.tsx @@ -0,0 +1,347 @@ +import { useCallback, useEffect, useState } from "react"; +import { Platform, Text, View } from "react-native"; +import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client"; +import { + SettingsAction, + SettingsCard, + SettingsRow, + SettingsSection, +} from "@getpaseo/plugin/client/ui"; +import { + zcodeRuntimeInstall, + zcodeRuntimeRemove, + zcodeRuntimeStatus, + type RuntimeSetupStatus, +} from "../shared/runtime-setup"; + +type Theme = PluginSurfaceProps["theme"]; +type Job = RuntimeSetupStatus["job"]; + +function Value({ + children, + color, + compact, +}: { + children: string; + color: string; + compact: boolean; +}) { + return ( + + {children} + + ); +} + +const megabytes = (bytes: number) => `${(bytes / 1_000_000).toFixed(1)} MB`; + +function jobLabel(job: Job): string { + switch (job.state) { + case "idle": + return "Not started"; + case "succeeded": + return "Completed"; + case "failed": + return `Failed (${job.code})`; + case "running": { + const name = job.component === "node" ? "Node.js" : "ZCode runtime"; + if (job.phase !== "download") return `${name}: ${job.phase}ing`; + const percent = + job.totalBytes > 0 + ? Math.floor((job.receivedBytes / job.totalBytes) * 100) + : 0; + return `${name}: downloading ${percent}% of ${megabytes(job.totalBytes)}`; + } + } +} + +function Components({ + status, + theme, + compact, +}: { + status: RuntimeSetupStatus; + theme: Theme; + compact: boolean; +}) { + return ( + <> + {status.components.map((component) => ( + + + + + {component.installed ? "Installed" : "Not installed"} + + + + + {component.url} + + + + + {component.sha256} + + + + + {component.license} + + + + + ))} + + ); +} + +export function SetupScreen({ theme, layout }: PluginSurfaceProps) { + const fetchStatus = useRpc(zcodeRuntimeStatus); + const install = useRpc(zcodeRuntimeInstall); + const remove = useRpc(zcodeRuntimeRemove); + const [status, setStatus] = useState(null); + const [requestError, setRequestError] = useState(null); + const [removeMessage, setRemoveMessage] = useState(null); + const [confirmRemove, setConfirmRemove] = useState(false); + const [pending, setPending] = useState(false); + const compact = layout.compact; + + const refresh = useCallback(async () => { + try { + setStatus(await fetchStatus({})); + setRequestError(null); + } catch (cause) { + setRequestError( + cause instanceof Error ? cause.message : "The setup request failed.", + ); + } + }, [fetchStatus]); + + useEffect(() => { + void refresh(); + }, [refresh]); + + const running = status?.job.state === "running"; + useEffect(() => { + if (!running) return; + const timer = setInterval(() => void refresh(), 1000); + return () => clearInterval(timer); + }, [running, refresh]); + + const run = useCallback( + async (action: () => Promise) => { + setPending(true); + try { + await action(); + } catch (cause) { + setRequestError( + cause instanceof Error ? cause.message : "The setup request failed.", + ); + } finally { + setPending(false); + await refresh(); + } + }, + [refresh], + ); + + if (status === null) + return ( + + + + + {requestError ?? "Checking the managed runtime…"} + + + + + ); + + const installed = + status.components.length > 0 && + status.components.every((component) => component.installed); + const total = status.components + .filter((component) => !component.installed) + .reduce((sum, component) => sum + component.sizeBytes, 0); + const busy = pending || running; + + return ( + + + + + + nodejs.org and this plugin's GitHub releases + + + + + Unofficial, not endorsed by ZCode or Z.ai + + + + + The daemon user, on the daemon machine + + + + + Only the destination below; PATH is untouched + + + + + {status.directory} + + + + + {status.supported + ? status.platform + : `${status.platform} is not supported. Set PASEO_ZCODE_RUNTIME and PASEO_ZCODE_NODE instead.`} + + + {status.override ? ( + + + PASEO_ZCODE_RUNTIME / PASEO_ZCODE_NODE are set, so sessions use + them instead of this runtime. + + + ) : null} + + + {jobLabel(status.job)} + + + + {status.supported ? ( + void run(() => install({}))} + /> + ) : null} + + + {status.loginCommand === undefined ? null : ( + + + + + In a terminal on the daemon machine + + + + + Opens a browser; add --no-browser to print the URL + + + {/* A full-width block: a row value would squeeze the label column. */} + + + {status.loginCommand} + + + + + )} + + { + if (!confirmRemove) { + setConfirmRemove(true); + return; + } + setConfirmRemove(false); + void run(async () => { + const result = await remove({}); + setRemoveMessage( + result.status === "removed" + ? "Removed." + : `Removal failed: ${result.message}`, + ); + }); + }} + /> + + {requestError === null ? null : ( + + + {requestError} + + + )} + + ); +} diff --git "a/docs/adr/0008-\350\250\255\345\256\232\347\224\273\351\235\242\343\201\257\350\252\255\343\201\277\345\217\226\343\202\212\345\260\202\347\224\250\343\201\256\350\250\272\346\226\255\343\201\253\351\231\220\345\256\232\343\201\227\343\203\233\343\202\271\343\203\210\347\212\266\346\205\213\343\202\222\345\260\202\347\224\250rpc\343\201\247\350\277\224\343\201\231.md" "b/docs/adr/0008-\350\250\255\345\256\232\347\224\273\351\235\242\343\201\257\350\252\255\343\201\277\345\217\226\343\202\212\345\260\202\347\224\250\343\201\256\350\250\272\346\226\255\343\201\253\351\231\220\345\256\232\343\201\227\343\203\233\343\202\271\343\203\210\347\212\266\346\205\213\343\202\222\345\260\202\347\224\250rpc\343\201\247\350\277\224\343\201\231.md" index 2db0abf..f29d6a0 100644 --- "a/docs/adr/0008-\350\250\255\345\256\232\347\224\273\351\235\242\343\201\257\350\252\255\343\201\277\345\217\226\343\202\212\345\260\202\347\224\250\343\201\256\350\250\272\346\226\255\343\201\253\351\231\220\345\256\232\343\201\227\343\203\233\343\202\271\343\203\210\347\212\266\346\205\213\343\202\222\345\260\202\347\224\250rpc\343\201\247\350\277\224\343\201\231.md" +++ "b/docs/adr/0008-\350\250\255\345\256\232\347\224\273\351\235\242\343\201\257\350\252\255\343\201\277\345\217\226\343\202\212\345\260\202\347\224\250\343\201\256\350\250\272\346\226\255\343\201\253\351\231\220\345\256\232\343\201\227\343\203\233\343\202\271\343\203\210\347\212\266\346\205\213\343\202\222\345\260\202\347\224\250rpc\343\201\247\350\277\224\343\201\231.md" @@ -8,6 +8,8 @@ links: kind: amends - target: 10 kind: amendedby + - target: 15 + kind: amendedby --- # 設定画面は読み取り専用の診断に限定しホスト状態を専用RPCで返す diff --git "a/docs/adr/0010-\343\202\265\343\203\274\343\203\220\343\203\274\350\250\255\345\256\232api\343\201\256\350\277\275\345\212\240\345\276\214\343\202\202\350\250\272\346\226\255\345\260\202\347\224\250\347\224\273\351\235\242\343\202\222\347\266\255\346\214\201\343\201\231\343\202\213.md" "b/docs/adr/0010-\343\202\265\343\203\274\343\203\220\343\203\274\350\250\255\345\256\232api\343\201\256\350\277\275\345\212\240\345\276\214\343\202\202\350\250\272\346\226\255\345\260\202\347\224\250\347\224\273\351\235\242\343\202\222\347\266\255\346\214\201\343\201\231\343\202\213.md" index 6489c3e..e4ffdc6 100644 --- "a/docs/adr/0010-\343\202\265\343\203\274\343\203\220\343\203\274\350\250\255\345\256\232api\343\201\256\350\277\275\345\212\240\345\276\214\343\202\202\350\250\272\346\226\255\345\260\202\347\224\250\347\224\273\351\235\242\343\202\222\347\266\255\346\214\201\343\201\231\343\202\213.md" +++ "b/docs/adr/0010-\343\202\265\343\203\274\343\203\220\343\203\274\350\250\255\345\256\232api\343\201\256\350\277\275\345\212\240\345\276\214\343\202\202\350\250\272\346\226\255\345\260\202\347\224\250\347\224\273\351\235\242\343\202\222\347\266\255\346\214\201\343\201\231\343\202\213.md" @@ -1,11 +1,13 @@ --- number: 10 title: サーバー設定APIの追加後も診断専用画面を維持する -status: accepted +status: superseded date: 2026-09-18 links: - target: 8 kind: amends + - target: 15 + kind: supersededby --- # サーバー設定APIの追加後も診断専用画面を維持する diff --git "a/docs/adr/0013-\345\205\254\351\226\213\343\202\275\343\203\274\343\202\271\343\201\256\345\205\254\345\274\217stdio-server\343\201\250v4\344\274\232\350\251\261\347\212\266\346\205\213\343\202\222\346\216\241\347\224\250\343\201\231\343\202\213.md" "b/docs/adr/0013-\345\205\254\351\226\213\343\202\275\343\203\274\343\202\271\343\201\256\345\205\254\345\274\217stdio-server\343\201\250v4\344\274\232\350\251\261\347\212\266\346\205\213\343\202\222\346\216\241\347\224\250\343\201\231\343\202\213.md" index 0a1da24..ae6a41b 100644 --- "a/docs/adr/0013-\345\205\254\351\226\213\343\202\275\343\203\274\343\202\271\343\201\256\345\205\254\345\274\217stdio-server\343\201\250v4\344\274\232\350\251\261\347\212\266\346\205\213\343\202\222\346\216\241\347\224\250\343\201\231\343\202\213.md" +++ "b/docs/adr/0013-\345\205\254\351\226\213\343\202\275\343\203\274\343\202\271\343\201\256\345\205\254\345\274\217stdio-server\343\201\250v4\344\274\232\350\251\261\347\212\266\346\205\213\343\202\222\346\216\241\347\224\250\343\201\231\343\202\213.md" @@ -20,6 +20,8 @@ links: kind: amends - target: 14 kind: amendedby + - target: 15 + kind: amendedby --- # 公開ソースの公式stdio ServerとV4会話状態を採用する diff --git "a/docs/adr/0015-\343\203\227\343\203\251\343\202\260\343\202\244\343\203\263\347\256\241\347\220\206\343\201\256zcode\343\203\251\343\203\263\343\202\277\343\202\244\343\203\240\343\201\250node-js\343\202\222\350\250\255\345\256\232\347\224\273\351\235\242\343\201\213\343\202\211\345\260\216\345\205\245\343\201\231\343\202\213.md" "b/docs/adr/0015-\343\203\227\343\203\251\343\202\260\343\202\244\343\203\263\347\256\241\347\220\206\343\201\256zcode\343\203\251\343\203\263\343\202\277\343\202\244\343\203\240\343\201\250node-js\343\202\222\350\250\255\345\256\232\347\224\273\351\235\242\343\201\213\343\202\211\345\260\216\345\205\245\343\201\231\343\202\213.md" new file mode 100644 index 0000000..e27f3f6 --- /dev/null +++ "b/docs/adr/0015-\343\203\227\343\203\251\343\202\260\343\202\244\343\203\263\347\256\241\347\220\206\343\201\256zcode\343\203\251\343\203\263\343\202\277\343\202\244\343\203\240\343\201\250node-js\343\202\222\350\250\255\345\256\232\347\224\273\351\235\242\343\201\213\343\202\211\345\260\216\345\205\245\343\201\231\343\202\213.md" @@ -0,0 +1,112 @@ +--- +number: 15 +title: プラグイン管理のZCodeランタイムとNode.jsを設定画面から導入する +status: accepted +date: 2026-10-06 +links: + - target: 13 + kind: amends + - target: 8 + kind: amends + - target: 10 + kind: supersedes +--- + +# プラグイン管理のZCodeランタイムとNode.jsを設定画面から導入する + +## Context and Problem Statement + +ADR 13 は統合 CLI 配布物と普通の Node.js 24.14.0+ の導入・更新を利用者に任せ、`PASEO_ZCODE_RUNTIME` と `PASEO_ZCODE_NODE` を必須にした。しかし ZCode は統合 CLI を配布しておらず、利用者は上流ソースのビルドと Node 24 の導入を自分で行う必要があり、導入の難度が高い。 + +2026-10-06 時点で次を確認した。 + +- GitHub Release `v3.14.3` の成果物は Desktop の dmg と exe だけである。公式 CDN の Linux 版 deb には Agent の `glm/zcode.cjs`(0.16.9)があるが、stdio Services Server の `zcode-server.cjs` と Node.js はない。 +- Desktop が SSH 先へ配置する部品の `manifest-.json` は CDN で公開され、`server-bundle` と `node-runtime` を列挙するが、各成果物は 404 で取得できない。 +- 上流は Apache-2.0 で、依存の大半は permissive license である。統合配布物は `agent/THIRD-PARTY-NOTICES.md` だけを含み、ルートの LICENSE・NOTICE を含まない。 +- 統合配布物は `engines: node>=24`、`node:sqlite`、`process.exit` を使う。Paseo のプラグインは Node 22 または Electron の Helper で動くため、同一プロセスでは実行できない。 +- npm 11 は依存の install スクリプトを既定で実行しない。Paseo は GitHub と npm の両方から導入できる。 +- 利用者環境でのビルドは 1,859 パッケージの取得、Electron 本体の取得、node-pty などのネイティブコンパイル(Python と C/C++ ツールチェーン)を必要とする。 + +## Decision Drivers + +- 利用者が Node 24 や ZCode CLI を自分で用意せずに使い始められる。 +- ホストの PATH やグローバル環境を変更しない。 +- 取得物を固定ハッシュで検証し、クライアントから取得先を指定させない。 +- ダウンロードと実行の前に利用者が内容を確認して明示的に開始する。 +- ZCode・Paseo 本体を改変せず、無改変の公式ソースだけを使う。 +- 上流と依存のライセンス条件を満たす。 + +## Considered Options + +- 自前 Release の統合 CLI 配布物と公式 Node.js を、設定画面のボタンで取得する。 +- 利用者による導入を維持する。 +- 公式 Desktop パッケージや CDN 部品から必要なファイルを取り出す。 +- 利用者環境で ZCode をソースからビルドする。 +- npm のライフサイクルスクリプトや Paseo の `build` 手順で取得する。 +- Node を埋め込んだ SEA バイナリを使う、または `zcode.cjs` をプラグインのプロセス内で実行する。 + +## Decision Outcome + +ユーザーの選択に従い、「自前 Release の統合 CLI 配布物と公式 Node.js を、設定画面のボタンで取得する」を採用する。公式の配布物だけでは stdio Server を入手できず、利用者環境のビルドや install スクリプトは前提条件・安全性・確実性で劣るためである。ADR 13 の stdio Server、V4、プロセス所有、保存形式は維持する。 + +**ZCode ランタイム.** このリポジトリの CI が、公開タグの無改変ソースから公式 `build-zcode.mjs` で統合配布物を作る。上流のルート `LICENSE`、`NOTICE.md`、`THIRD-PARTY-NOTICES.md` を配布物に追加し、プラグイン本体とは別のタグの GitHub Release として公開する。同じソースから再ビルドしてもバイト単位で一致する保証がないため、公開済みの成果物の URL と SHA-256 をプラグインのソースに固定する。最初の配布は `v3.14.3`(`29628c9`)とする。成果物は ZCode と Z.ai の非公式ビルドであると明示し、上流の商標を製品名として使わない。 + +**Node.js.** nodejs.org の公式成果物を、固定したバージョンとプラットフォーム別の SHA-256 で取得する。最初の固定は 24.21.0 とし、CI の実行時試験も同じ版を使う。プラグインは Node を再配布しない。 + +**対象.** darwin-arm64、linux-x64、linux-arm64、win-x64、win-arm64 とする。各ターゲットで固定した成果物の実行時契約試験を CI で行い、失敗したターゲットは提供しない。それ以外の環境は従来どおり環境変数で手動設定する。 + +**配置.** 各 OS の利用者別データ領域の慣習に従い、Windows は `%LOCALAPPDATA%\paseo-plugin-zcode-provider\runtimes`、macOS と Linux は `~/.local/share/paseo-plugin-zcode-provider/runtimes` に、版とプラットフォームごとのディレクトリで置く。Windows の既定はローミングされない `%LOCALAPPDATA%` とし、ホーム直下に `.local` を作らない。絶対パスの `XDG_DATA_HOME` は全 OS で基点を上書きする明示的な指定として扱い、CI と試験の隔離に使う。XDG の仕様どおり相対パスは無視する。一時領域への取得、ハッシュ照合、展開、起動確認、rename による確定の順に行い、ロックで同時導入を防ぐ。Git checkout の外に置くため、プラグインの更新では再取得しない。PATH には追加せず、Server と Agent を絶対パスで起動する。 + +**選択.** `PASEO_ZCODE_RUNTIME` と `PASEO_ZCODE_NODE` の両方があれば、従来どおりそれを使う。片方だけの設定はエラーとする。どちらもなければ、プラグインが固定した版の管理下ランタイムを使い、未導入なら設定画面への案内付きのエラーにする。Electron と Desktop へのフォールバックは引き続き行わない。最低版の判定(ADR 7)は環境変数の経路に適用する。 + +**設定画面.** Settings → Plugins → zcode-provider に導入と削除の操作を加える。導入前に取得元、サイズ、配置先、ライセンスを表示する。RPC は入力に URL、パス、版を受け取らず、サーバー側の固定値だけを使う。導入は開始の RPC で受け付けて即時に返し、状態の RPC で進捗と結果を返す。診断情報の項目と秘匿方針(ADR 8)は維持する。導入後は、管理下の Node で公式 TUI を起動するログイン用コマンドをコピーできる形で表示する。プラグインは認証情報を扱わない。 + +### Consequences + +- Good, because 利用者は Node 24、pnpm、コンパイラ、ZCode CLI を用意せずに導入できる。 +- Good, because install スクリプトの有無や導入元(GitHub / npm)に左右されない。 +- Good, because クライアントは固定値の取得しか起動できず、取得物はハッシュで検証される。 +- Bad, because このリポジトリが ZCode 配布物の再配布者になり、ライセンス表示と上流の未解決の通知(`third-party/inventory.json` の `reviewRequired`)を引き継ぐ。 +- Bad, because ZCode のセキュリティ修正を利用者へ届けるには、ランタイムの再公開とプラグインの更新が必要になる。 +- Bad, because `paseo plugin remove` は管理下ディレクトリを削除しないため、削除の操作と手順を別に提供する必要がある。 + +### Confirmation + +リリース用ワークフローの成果物に LICENSE、NOTICE、THIRD-PARTY-NOTICES が含まれることを検査する。固定した ZCode 成果物と Node で、対象の 5 ターゲットの `test:stdio-runtime` を CI で実行する。取得、ハッシュ不一致、展開失敗、中断後の再試行、同時実行、環境変数の優先順位、削除をユニット試験で確認する。実 UI で導入、セッション作成、ログイン用コマンドの表示を確認し、結果を [verification](../verification.md) に記録する。 + +## Pros and Cons of the Options + +### 自前 Release の統合 CLI 配布物と公式 Node.js を、設定画面のボタンで取得する + +- Good, because CI が成果物を作るため、利用者側にビルド用ツールチェーンが要らない。 +- Good, because 取得と実行の開始を利用者が画面で明示的に選べる。 +- Bad, because Release の運用とライセンス表示の責任を負う。 + +### 利用者による導入を維持する + +- Good, because 再配布者にならない。 +- Bad, because 公式 CLI が配布されていない現状では、利用者が上流をビルドして Node 24 を導入する必要がある。 + +### 公式 Desktop パッケージや CDN 部品から必要なファイルを取り出す + +- Good, because 公式の成果物を利用者が直接取得するため、再配布にならない。 +- Bad, because deb には stdio Server がなく、Agent への直接接続は ADR 13 で退けた構成に戻る。CDN 部品は取得できない。 + +### 利用者環境で ZCode をソースからビルドする + +- Good, because 再配布者にならない。 +- Bad, because Python と C/C++ ツールチェーンが必要で、多数の依存の install スクリプトが daemon の権限で実行される。時間とディスクも大きく消費する。 + +### npm のライフサイクルスクリプトや Paseo の `build` 手順で取得する + +- Good, because 導入と同時に自動で準備できる。 +- Bad, because install スクリプトは npm の設定でスキップされうる。利用者が取得を確認する機会もない。 + +### Node を埋め込んだ SEA バイナリを使う、または `zcode.cjs` をプラグインのプロセス内で実行する + +- Good, because SEA は Node を別途必要としない。 +- Bad, because SEA には stdio Server が含まれず、6 ターゲット分の署名と配布が必要になる。プロセス内実行は Node 24 の要件と ZCode のプロセス前提に反する。 + +## More Information + +ADR 13 のうち、導入・更新を利用者に任せる前提と両環境変数の必須化を変更する。ADR 8 の診断項目と秘匿方針を維持し、読み取り専用の制限を変更する。診断専用画面の維持を決めた ADR 10 を置き換える。ZCode が統合 CLI か stdio Server を含む成果物を公式に配布した場合は、公式の成果物を直接取得する方式へ切り替えるかを再評価する。 diff --git a/docs/adr/README.md b/docs/adr/README.md index 6a9e3c0..ea63c5c 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -12,3 +12,4 @@ * [12. 実モデルE2Eを隔離した認証設定でPRのCIに組み込む](0012-実モデルe2eを隔離した認証設定でprのciに組み込む.md) * [13. 公開ソースの公式stdio ServerとV4会話状態を採用する](0013-公開ソースの公式stdio-serverとv4会話状態を採用する.md) * [14. Paseoの保存設定を再適用する復元を保証範囲とする](0014-paseoの保存設定を再適用する復元を保証範囲とする.md) +* [15. プラグイン管理のZCodeランタイムとNode.jsを設定画面から導入する](0015-プラグイン管理のzcodeランタイムとnode-jsを設定画面から導入する.md) diff --git a/docs/development.md b/docs/development.md index b0ba3c6..5f58dde 100644 --- a/docs/development.md +++ b/docs/development.md @@ -16,17 +16,32 @@ npm run test:upstream -- /absolute/path/to/paseo ## Source of truth -Inspect `~/ghq/github.com/zai-org/ZCode`, not extracted Electron/deb bundles. The current baseline is `872ad960de7ec172591f7e1952f7849229f94521`. Record that SHA and source paths in investigations. Source version, release version and artifact identity are separate facts. +Inspect `~/ghq/github.com/zai-org/ZCode`, not extracted Electron/deb bundles. The current baseline is `29628c9acdb81b703bbd4080c207a0e7ce5e276e`. Record that SHA and source paths in investigations. Source version, release version and artifact identity are separate facts. `server/vendor/zcode` contains the needed official RPC modules, V4 contracts, wire assembler and pure delta application with their transitive schema dependencies. It contains no Agent engine, authentication implementation, tools or storage engine. Paseo's compiler requires executable plugin modules to live under `server/`, `client/` or `shared/`, hence this location. `provenance.json` records entrypoints, original/modified hashes and the only import rewrite (a private workspace alias to its relative source). The upstream Apache-2.0 LICENSE and full NOTICE are retained, along with the relevant Visual Studio Code MIT notice extracted from THIRD-PARTY-NOTICES.md. The extraction and full original file hash are recorded. `npm run build` also copies these notices to `dist/licenses/zcode`. Verify the files with `npm run check:zcode-source`. To deliberately resynchronize the fixed SHA, run `node scripts/sync-zcode-source.mjs /absolute/ZCode --write`; changing the SHA requires reviewing contract changes, the minimum versions and runtime evidence together. The sync script reads `git show :`, not possibly modified checkout files. Do not format vendored source. Unexpected vendored files fail verification. -`download:zcodecjs` and deb extraction tests have been removed. Release monitoring still uses the official changelog and its separately recorded last reviewed release (3.12.3), not the source-only 3.14.0 baseline. Associate GitHub tags/releases when available; do not create an Issue for every main commit. +`download:zcodecjs` and deb extraction tests have been removed. Release monitoring still uses the official changelog and its separately recorded last reviewed release (3.14.3), which matches the pinned v3.14.3 source tag. A changelog release without public source (such as 3.14.4) is not a baseline. Associate GitHub tags/releases when available; do not create an Issue for every main commit. + +## Managed runtime and its releases + +Users install the runtime from the Setup screen (ADR 15). `server/runtime/pins.ts` pins Node.js archives from nodejs.org and the `zcode-runtime-v` release of this repository by URL, SHA-256 and size. The installer downloads to a staging directory under `runtimes/`, checks the size limit and SHA-256, extracts with the system `tar` (Windows uses `%SystemRoot%\System32\tar.exe`, which also reads zip), verifies Node's version and the runtime layout, writes a marker and renames the result into place. A lock directory with the owner PID prevents concurrent setup; a lock from a dead process is reclaimed. + +To use it locally without touching your real data directory: + +```bash +XDG_DATA_HOME=/tmp/zcode-data npm run setup:managed-runtime +XDG_DATA_HOME=/tmp/zcode-data npm run test:stdio-runtime +``` + +To pin a new Node.js version, take the five archive checksums from `SHASUMS256.txt`, verify its signature against the [nodejs/release-keys](https://github.com/nodejs/release-keys) active keyring in a temporary `GNUPGHOME`, and record the sizes. + +To publish a ZCode runtime, update the source baseline first, then push an annotated `zcode-runtime-v` tag on a commit containing it. `.github/workflows/zcode-runtime-release.yml` builds the official distribution, adds the upstream notices and `BUILD-INFO.json` with `scripts/package-zcode-runtime.mjs`, runs `test:stdio-runtime` on all five managed platforms, attests the archive and creates a non-latest release. Rebuilds are not byte-identical, so pin the published asset's SHA-256 and size, never a local build. Pull requests that touch the packaging run the same build and verification without publishing. ## Build an isolated integrated CLI -CLI installation is a user responsibility. For development/CI, build the official distribution from an isolated checkout/archive of the pinned source. Do not change the reference clone or a user's installed runtime. +For investigation, build the official distribution from an isolated checkout/archive of the pinned source. Do not change the reference clone or a user's installed runtime. With ordinary Node.js 24.14.0+ and the repository's pnpm version (10.33.2) on PATH, in that isolated ZCode checkout: @@ -38,7 +53,7 @@ node scripts/build-zcode.mjs --base-url https://example.invalid/zcode/ The explicit shared-package TypeScript build supplies `packages/shared/dist`; the packaging script requires it but the baseline does not otherwise generate it. This uses the official tsconfig without patching source. The URL is build metadata for this development artifact, not a download source. -Extract `dist/zcode/releases/3.14.0/zcode-3.14.0.tar.gz` **outside the checkout**, and configure `PASEO_ZCODE_RUNTIME` to the extracted `zcode` directory and `PASEO_ZCODE_NODE` to the explicit Node binary. Record the archive SHA-256, Server/Agent hashes, source SHA, OS/CPU and Node version independently. Do not infer a source SHA from matching version strings. +Extract `dist/zcode/releases/3.14.3/zcode-3.14.3.tar.gz` **outside the checkout**, and configure `PASEO_ZCODE_RUNTIME` to the extracted `zcode` directory and `PASEO_ZCODE_NODE` to the explicit Node binary. Record the archive SHA-256, Server/Agent hashes, source SHA, OS/CPU and Node version independently. Do not infer a source SHA from matching version strings. The baseline's remote terminal service cannot locate the integrated distribution's `node-pty` prebuild. The Agent's Bash tool uses a different path and passes actual execution tests. Do not copy native binaries into guessed paths; see [verification](verification.md). @@ -59,14 +74,14 @@ The baseline's remote terminal service cannot locate the integrated distribution npm run test:e2e ``` -Set both runtime variables first. The runner writes a private, temporary official provider configuration using the existing key, isolates HOME/configuration/SQLite/temp sockets, and passes no unrelated credentials to child processes. It runs model/reasoning, independent Plan transitions and approval/decline, followed by real guidance, attachment queue, stop and resume checks. Its mode/Plan restoration supplies both saved Paseo settings, matching `test:stdio-runtime`. Test data is removed even after failures. +Set both runtime variables, or `XDG_DATA_HOME` containing a managed runtime, first. The runner writes a private, temporary official provider configuration using the existing key, isolates HOME/configuration/SQLite/temp sockets, and passes no unrelated credentials to child processes. It runs model/reasoning, independent Plan transitions and approval/decline, followed by real guidance, attachment queue, stop and resume checks. Its mode/Plan restoration supplies both saved Paseo settings, matching `test:stdio-runtime`. Test data is removed even after failures. -CI runs ordinary non-billable tests, actual Paseo integration and vendored-source verification on Node 22. A separate Node 24 job builds the pinned official distribution and executes the non-billable Provider contract check on that real runtime. Eligible non-fork PRs and pushes additionally run isolated real-model E2E with `GLM_API_KEY`; no Desktop/deb installation is used. Failures of the supported contract or E2E block release. Actual OS coverage is recorded only after execution, not inferred from workflow configuration. +CI runs ordinary non-billable tests, actual Paseo integration and vendored-source verification on Node 22. A matrix job installs the pinned managed runtime with the plugin's installer on darwin-arm64, linux-x64, linux-arm64, win-x64 and win-arm64 runners (plugin on Node 22, ZCode on the managed Node.js) and executes the non-billable Provider contract check. Eligible non-fork PRs and pushes additionally run isolated real-model E2E with `GLM_API_KEY` on the managed runtime; no Desktop/deb installation is used. Failures of the supported contract or E2E block release. Actual OS coverage is recorded only after execution, not inferred from workflow configuration. ## Architecture Paseo and ZCode themselves must remain unmodified. Changes belong to this Provider plugin; a fork, source patch or patched upstream runtime is not an implementation option. Official configuration and protocol operations remain available. For mode/Plan resume, the plugin reapplies both settings when Paseo supplies them and waits for native confirmation before accepting prompts. This is the supported restoration contract. Omitted values use the state returned by ZCode and are not guaranteed to match the state before shutdown. Keep that upstream defect documented and reproducible with `test:native-restore` until an unmodified official version resolves it. -`discovery/` validates the explicitly configured runtime. `host/bridge.ts` owns hello/ack, official binary framing, RPC, process preferences and process shutdown. `conversation.ts` owns one V4 state, wire assembly, sequencing, resync and coherent history paging. `session.ts` coordinates admissions, public execution IDs, stop and native configuration. `presentation.ts` translates rows and interactions to Paseo. `persistence.ts` stores only the pre-send logical/native identity mapping. Authentication remains in Services Host. +`discovery/` validates the environment override or, without one, the installed managed runtime. `runtime/` holds the pins and the installer behind the Setup screen. `host/bridge.ts` owns hello/ack, official binary framing, RPC, process preferences and process shutdown. `conversation.ts` owns one V4 state, wire assembly, sequencing, resync and coherent history paging. `session.ts` coordinates admissions, public execution IDs, stop and native configuration. `presentation.ts` translates rows and interactions to Paseo. `persistence.ts` stores only the pre-send logical/native identity mapping. Authentication remains in Services Host. Model admission is never retried after an unknown outcome. Only a stale conditional control command, which confirms no mutation occurred, may be retried with the returned revision. Recovery must not mix history epochs/revisions or publish a partial recovery window as complete history. Foreground execution and background continuation are distinct. Product turn IDs, row IDs and source command IDs have different meanings. diff --git a/docs/todo.md b/docs/todo.md index 7bde3b4..8d9363f 100644 --- a/docs/todo.md +++ b/docs/todo.md @@ -12,9 +12,11 @@ Paseo・ZCode 本体の改変は禁止。対応範囲はこの Provider に限 ## 検証の残項目 -- 公式アカウントログイン・期限切れ・未認証、公式 TUI と複数 Server の共有データ同時利用。 +- 公式アカウントログイン・期限切れ・未認証、公式 TUI と複数 Server の共有データ同時利用。設定画面に表示する `zcode.mjs login` で取得した認証を管理下の Server が使えることも、実アカウントで未確認。 +- 管理下セットアップの実 UI(Desktop・Web・モバイルからの開始、進捗表示、削除)と、Paseo daemon を Windows / Linux arm64 で動かした場合の導入。CI の 5 プラットフォーム契約試験は daemon を介さない。 +- プロキシや社内ミラーのみの環境での取得。現状は nodejs.org と GitHub への直接接続が必要で、失敗時は環境変数の上書きで回避する。 - Desktop ネイティブ画面とモバイル実機での操作。Electron Helper / 通常 Node の両 daemon 起動と、実 Web UI の入力・質問・承認・停止・再起動復元は確認済み([検証記録](verification.md))。 -- 修正後 CI の Linux x64 での保存設定による復元と実モデル E2E。修正前 CI の非課金 runtime 項目は設定省略時の復元を除き成功。Windows/macOS x64、長時間ツール/MCP 子プロセスを含む異常終了時の回収は未検証。 +- macOS x64(管理下セットアップの対象外)、長時間ツール/MCP 子プロセスを含む異常終了時の回収は未検証。 - native の長い会話・世代変更・background continuation・子エージェントからの権限要求。現在の契約試験の結果と実行確認を混同しない。 - 統合 CLI の remote terminal 用 node-pty 配置。Provider はその terminal API を呼ばず、Agent Bash は検証済みだが、upstream 配布の問題として追跡する。 diff --git a/docs/verification.md b/docs/verification.md index 57dea70..a729a18 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -1,3 +1,47 @@ +# プラグイン管理ランタイムの検証(2026-10-06) + +ADR 15 の管理下セットアップを、公開した成果物そのもので検証した。 + +| 項目 | 実測値 | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ZCode ランタイム | [`zcode-runtime-v3.14.3`](https://github.com/supermomonga/paseo-plugin-zcode-provider/releases/tag/zcode-runtime-v3.14.3)、`zcode-runtime-3.14.3.tar.gz`、79,887,659 bytes | +| 成果物 SHA-256 | `a2af414592362d226f92c105d91211e5c4f138cf985b0c86da0eb9163cb9aee7`。`gh attestation verify` で、タグ `zcode-runtime-v3.14.3`(コミット `2372c9f`)の release ワークフローによる署名を確認 | +| 成果物の Server / Agent | Server `f5b1d561277062ea1158074ca9240f020aa9d274aa32eebd01bcb838a0910187`(下記ローカルビルドと一致)、Agent `93e4555343aacdef7dfc24ca87572eb3a939ae2f1acf52d77d4bfdead9da6d22`(ビルドごとに異なる) | +| Node.js | 24.21.0。`SHASUMS256.txt` の署名を一時 `GNUPGHOME` と nodejs/release-keys の現役鍵で検証(Antoine du Hamel 鍵) | + +- **Release ワークフロー**: [タグの run](https://github.com/supermomonga/paseo-plugin-zcode-provider/actions/runs/37410109547) でビルド、darwin-arm64・linux-x64・linux-arm64・win-x64・win-arm64 の `test:stdio-runtime`、attestation、Release 作成が成功。PR 上の同ワークフローも 5 ターゲットで成功した。 +- **CI**: [run 37410854307](https://github.com/supermomonga/paseo-plugin-zcode-provider/actions/runs/37410854307) で、プラグインのインストーラーが固定 URL・ハッシュから導入した管理下ランタイムに対し、5 ターゲットの `test:stdio-runtime`(プラグインは Node 22、ZCode は Node 24.21.0)と実モデル E2E が成功。同 run の `test` ジョブは `check-upstream.mjs` のスタブが設定画面の後始末関数を返さないため失敗した。Paseo 0.9.0-beta.1 と最新版の `addSettingsScreen` はどちらも後始末関数を返すため、スタブを実装に合わせて修正し、ローカルの実 compiler / adapter 試験で成功を確認した。 +- **macOS arm64 ローカル**: `XDG_DATA_HOME` を一時ディレクトリにして `npm run setup:managed-runtime` が実ダウンロード込みで 12.6 秒で完了。続く `test:stdio-runtime` は `source: "managed"` で exit 0。 +- **実 UI**: Paseo 0.9.0-beta.2 の一時 daemon(一時ホーム、loopback、relay と MCP 注入は無効、plugins と Web UI は有効、HOME・XDG・ZCode データも一時ディレクトリ)に現在の worktree を導入し、ヘッドレス Chrome で確認した。Setup 画面で取得元・サイズ・SHA-256・ライセンスの表示、ボタンからの導入、進捗(ダウンロード率・展開・検証)、完了後のログインコマンド、Diagnostics の「Managed runtime」表示、削除と削除後の未導入表示を確認した。幅 1280px と 420px で表示を確認し、長い値がラベル列を狭める 2 か所を検証中に修正した。 +- **実モデル**: 同 daemon で隔離した provider configuration の既存 Z.ai Coding Plan キーを使い、`paseo run --provider zcode` が管理下ランタイム経由で `MANAGED_RUNTIME_OK` を返した。削除後の新規作成は「ZCode runtime is not set up. Open Settings → Plugins → zcode-provider to set it up.」で失敗し、案内どおりの表示になった。 +- **ログインコマンド**: 表示されたパスで `--version` が `3.14.3` を返し、`login [zai|bigmodel]` サブコマンドがあることを確認した。実アカウントでのブラウザ認証と、その認証を管理下 Server が使えることは未確認。 + +未検証:Windows と Linux arm64 で Paseo daemon を動かした場合の画面からの導入(CI は daemon を介さずインストーラーと契約試験を実行)、プロキシ環境、Desktop とモバイルのクライアント、実アカウントのログイン。検証後に一時 daemon を停止し、プロセスが残っていないことを確認した。 + +# ZCode v3.14.3 へのソース基準更新(2026-10-06) + +公開タグ `v3.14.3` のソースへ基準を更新した。上流の公開タグは `v3.14.3` だけで、変更履歴にある 3.14.4 のソースは未公開のため対象外とした。下記 2026-09-21 の記録は旧基準 `872ad960` の結果として残す。 + +| 項目 | 実測値 | +| -------------------- | --------------------------------------------------------------------------------------------------------------- | +| ZCode source | `29628c9acdb81b703bbd4080c207a0e7ce5e276e`(タグ `v3.14.3`) | +| ビルド | git archive を一時領域へ展開。pnpm 10.33.2、Node 24.20.0、`tsc -b packages/shared` の後に公式 `build-zcode.mjs` | +| OS/CPU | macOS arm64 | +| Server / Agent | 3.14.3 / 0.16.9 | +| 配布 tar.gz SHA-256 | `e13020f331298f1d0af53e1691910bed6e06556031319c28808bf925b7eb4612` | +| Server SHA-256 | `f5b1d561277062ea1158074ca9240f020aa9d274aa32eebd01bcb838a0910187` | +| Agent SHA-256 | `c6abd0cdf4ca1d7aa2089a9bdc71ccdc24b364b7aa548d84dcce070d4e34866a` | +| Plugin runtime / SDK | Node 22.23.2 / `@getpaseo/plugin` 0.9.0-beta.1 | + +vendored ファイルは 91 から 97 に増えた。V4 の変更は後方互換の追加である。Host と clientHello に任意の `workflowRunDeltas` capability が加わり、`workflowRun.updated` / `workflowRun.removed` 差分はクライアントがこの capability を宣言した接続にだけ送られる。Provider は宣言しないため、従来どおり `state.updated` を受け取る。コマンドの `botDeliveryTarget` は Host が注入する任意項目である。 + +- `npm run typecheck`、`npm test`(15 ファイル、128 tests)、`npm run build`、`npm run format:check`、`npm run check:zcode-source`(97 ファイル)が成功。 +- `npm run test:stdio-runtime` は **exit 0**。catalog、draft、Bash、ACK/完了一回、保存設定による cold resume、履歴、質問、承認、停止と再開、slash command、v3 一覧、EOF cleanup、Server SIGKILL 後の Agent 終了を確認した。 +- `npm run test:native-restore` は **exit 1**。期待値 `edit / true` に対して実際は `yolo / false` で、設定省略時の復元不具合は v3.14.3 でも残る。保証対象外(ADR 14)。 +- 確認済みリリースを 3.12.3 から 3.14.3 へ更新した(Issue #23、#25)。3.14.4(#32)はソース公開後に扱う。 + +未実行:Paseo 実 compiler / adapter 結合試験、実モデル E2E、Linux x64 の runtime 試験。いずれも CI で実行する。 + # 公開ソース・stdio / V4 移行の検証(2026-09-21) 接続方式と会話処理を置換し、通常テスト、実モデル E2E、隔離 daemon の実 Web UI 検証は成功した。固定した ZCode ソースには設定省略時の実行状態復元不具合がある。ユーザー承認と ADR 14 により、**mode / Plan の復元保証は Paseo が保存した両設定を再適用する経路に限定**した。設定省略時の不具合は保証対象外として追跡し、その修正自体を公開条件にはしない。以下の成功・失敗・未検証範囲を分けて扱う。 diff --git a/index.client.tsx b/index.client.tsx index ae12dba..baa8996 100644 --- a/index.client.tsx +++ b/index.client.tsx @@ -1,12 +1,22 @@ import type { PluginClientContext } from "@getpaseo/plugin/client"; import { DiagnosticsScreen } from "./client/diagnostics"; +import { SetupScreen } from "./client/setup"; export default function contribute(client: PluginClientContext): () => void { - client.addSettingsScreen({ + const removeSetup = client.addSettingsScreen({ + id: "setup", + title: "Setup", + icon: "Download", + Component: SetupScreen, + }); + const removeDiagnostics = client.addSettingsScreen({ id: "diagnostics", title: "Diagnostics", icon: "Activity", Component: DiagnosticsScreen, }); - return () => {}; + return () => { + removeSetup(); + removeDiagnostics(); + }; } diff --git a/index.server.ts b/index.server.ts index bd3543b..587a5cb 100644 --- a/index.server.ts +++ b/index.server.ts @@ -1,10 +1,21 @@ import type { PluginServerContext } from "@getpaseo/plugin/server"; import { createZCodeProvider } from "./server/provider.js"; +import { ManagedRuntimeInstaller } from "./server/runtime/managed.js"; +import { createRuntimeSetupHandlers } from "./server/runtime-setup.js"; import { createDiagnosticsHandler } from "./server/status.js"; import { zcodeDiagnostics } from "./shared/diagnostics.js"; +import { + zcodeRuntimeInstall, + zcodeRuntimeRemove, + zcodeRuntimeStatus, +} from "./shared/runtime-setup.js"; export default function contribute(server: PluginServerContext): () => void { server.registerProvider(createZCodeProvider()); server.handle(zcodeDiagnostics, createDiagnosticsHandler()); + const setup = createRuntimeSetupHandlers(new ManagedRuntimeInstaller()); + server.handle(zcodeRuntimeStatus, setup.status); + server.handle(zcodeRuntimeInstall, setup.install); + server.handle(zcodeRuntimeRemove, setup.remove); return () => {}; } diff --git a/package.json b/package.json index 64e6cc9..3a76b25 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,8 @@ "test:e2e": "node scripts/check-e2e.mjs", "check:zcode-source": "node scripts/sync-zcode-source.mjs", "test:stdio-runtime": "node scripts/check-stdio-runtime.mjs", - "test:native-restore": "node scripts/check-stdio-runtime.mjs --check-native-restore" + "test:native-restore": "node scripts/check-stdio-runtime.mjs --check-native-restore", + "setup:managed-runtime": "node scripts/install-managed-runtime.mjs" }, "devDependencies": { "@getpaseo/client": "0.9.0-beta.1", diff --git a/scripts/check-e2e.mjs b/scripts/check-e2e.mjs index 531f30f..91b9043 100644 --- a/scripts/check-e2e.mjs +++ b/scripts/check-e2e.mjs @@ -108,6 +108,8 @@ export async function runE2E({ "LC_ALL", "PASEO_ZCODE_RUNTIME", "PASEO_ZCODE_NODE", + // Locates a managed runtime; HOME below is replaced. + "XDG_DATA_HOME", ] .filter((key) => environment[key] !== undefined) .map((key) => [key, environment[key]]), diff --git a/scripts/check-stdio-runtime.mjs b/scripts/check-stdio-runtime.mjs index 511de95..e935284 100644 --- a/scripts/check-stdio-runtime.mjs +++ b/scripts/check-stdio-runtime.mjs @@ -2,6 +2,7 @@ import assert from "node:assert/strict"; import { z } from "zod"; import { createServer } from "node:http"; import { mkdir, mkdtemp, realpath, writeFile, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { pathToFileURL } from "node:url"; import { parseArgs } from "node:util"; @@ -15,9 +16,19 @@ const { values } = parseArgs({ }); const root = resolve(import.meta.dirname, ".."); const runtime = process.env.PASEO_ZCODE_RUNTIME, - node = process.env.PASEO_ZCODE_NODE; -assert.ok(runtime && node, "Set PASEO_ZCODE_RUNTIME and PASEO_ZCODE_NODE"); -const directory = await realpath(await mkdtemp("/tmp/zcode-contract-")); + node = process.env.PASEO_ZCODE_NODE, + data = process.env.XDG_DATA_HOME; +// Either the explicit override pair or a managed runtime under XDG_DATA_HOME. +const override = Boolean(runtime || node); +assert.ok( + override ? runtime && node : data, + "Set PASEO_ZCODE_RUNTIME and PASEO_ZCODE_NODE, or XDG_DATA_HOME with a managed runtime", +); +const windows = process.platform === "win32"; +// POSIX keeps /tmp so ZCode's Unix socket paths stay below the platform length limit. +const directory = await realpath( + await mkdtemp(join(windows ? tmpdir() : "/tmp", "zcode-contract-")), +); let connection, scenario = "bash", modelCalls = 0; @@ -102,7 +113,12 @@ const cleanup = async () => { }; const removeSignalHandlers = cleanupOnSignal(cleanup); try { - for (const part of ["workspace", ".zcode/v2", "tmp"]) + for (const part of [ + "workspace", + ".zcode/v2", + "tmp", + ...(windows ? ["AppData/Roaming", "AppData/Local"] : []), + ]) await mkdir(join(directory, part), { recursive: true }); await new Promise((r) => modelServer.listen(0, "127.0.0.1", r)); const config = e2eProviderConfig("local-fixture-not-a-secret"); @@ -113,20 +129,32 @@ try { { mode: 0o600 }, ); // This script owns its process environment; no real user configuration is read. + // Windows processes also need their system locations; profile paths are isolated below. + const inherited = windows + ? ["PATH", "PATHEXT", "SystemRoot", "SystemDrive", "windir", "ComSpec"] + : ["PATH", "SHELL", "LANG"]; const env = Object.fromEntries( - ["PATH", "SHELL", "LANG"] - .filter((k) => process.env[k]) - .map((k) => [k, process.env[k]]), + inherited.filter((k) => process.env[k]).map((k) => [k, process.env[k]]), ); for (const key of Object.keys(process.env)) delete process.env[key]; Object.assign(process.env, env, { + ...(windows + ? { + USERPROFILE: directory, + APPDATA: join(directory, "AppData", "Roaming"), + LOCALAPPDATA: join(directory, "AppData", "Local"), + TEMP: join(directory, "tmp"), + TMP: join(directory, "tmp"), + } + : {}), HOME: directory, ZCODE_DATA_BASE_DIR: directory, ZCODE_STORAGE_DIR: join(directory, ".zcode"), ZCODE_SESSION_DB_PATH: join(directory, "sessions.db"), TMPDIR: join(directory, "tmp"), - PASEO_ZCODE_RUNTIME: runtime, - PASEO_ZCODE_NODE: node, + ...(override + ? { PASEO_ZCODE_RUNTIME: runtime, PASEO_ZCODE_NODE: node } + : { XDG_DATA_HOME: data }), }); await build({ stdin: { @@ -147,7 +175,7 @@ try { ZCodeHostBridge, logger, } = await import(pathToFileURL(join(directory, "provider.mjs"))); - const identity = (await discoverRuntime()).identity; + const { identity, source } = await discoverRuntime(); const bridges = []; const provider = createZCodeProvider( async (environment, signal, workspace) => { @@ -419,6 +447,7 @@ try { JSON.stringify( { identity, + source, restoration: "Paseo's saved mode and Plan settings", ...(values["check-native-restore"] ? { nativePlanRestore: "passed" } diff --git a/scripts/check-upstream.mjs b/scripts/check-upstream.mjs index ee2c7a2..9b3140f 100644 --- a/scripts/check-upstream.mjs +++ b/scripts/check-upstream.mjs @@ -366,16 +366,20 @@ async function checkGitPreparation({ }; return nodeRequire(name); }); - let screen; + // Like Paseo's client runtime, each registration returns its own cleanup. + const screens = new Map(); const disposeClient = clientContribution.default({ - addSettingsScreen(screen_) { - screen = screen_; + addSettingsScreen(screen) { + screens.set(screen.id, screen); + return () => screens.delete(screen.id); }, }); - assert.equal(screen.id, "diagnostics"); - assert.equal(typeof screen.Component, "function"); + assert.deepEqual([...screens.keys()], ["setup", "diagnostics"]); + for (const screen of screens.values()) + assert.equal(typeof screen.Component, "function"); assert.equal(typeof disposeClient, "function"); await disposeClient(); + assert.equal(screens.size, 0); return { nodeEnv: nodeEnv ?? "unset", compiledBytes: Buffer.byteLength(serverBundle), diff --git a/scripts/check-zcode-releases.mjs b/scripts/check-zcode-releases.mjs index 20eec3c..488ccef 100644 --- a/scripts/check-zcode-releases.mjs +++ b/scripts/check-zcode-releases.mjs @@ -1,6 +1,4 @@ import { load } from "cheerio"; -import { build } from "esbuild"; -import { fileURLToPath } from "node:url"; import { cliOptions, collectRelease, @@ -11,6 +9,7 @@ import { runReleaseCheck, validateVersion, } from "./releases/common.mjs"; +import { loadZCodeManifest } from "./zcode-manifest.mjs"; export const ZCODE_CHANGELOG_URL = "https://zcode.z.ai/en/changelog"; @@ -56,20 +55,7 @@ export async function fetchNewZCodeReleases(currentVersion, fetchImpl = fetch) { } export async function currentZCodeVersion() { - const result = await build({ - entryPoints: [ - fileURLToPath( - new URL("../server/discovery/manifest.ts", import.meta.url), - ), - ], - bundle: true, - platform: "node", - format: "esm", - write: false, - }); - const manifest = await import( - `data:text/javascript;base64,${Buffer.from(result.outputFiles[0].contents).toString("base64")}` - ); + const manifest = await loadZCodeManifest(); return validateVersion(manifest.LAST_REVIEWED_ZCODE_RELEASE); } diff --git a/scripts/install-managed-runtime.mjs b/scripts/install-managed-runtime.mjs new file mode 100644 index 0000000..37a3edf --- /dev/null +++ b/scripts/install-managed-runtime.mjs @@ -0,0 +1,51 @@ +import { build } from "esbuild"; +import { fileURLToPath } from "node:url"; +import { runMain } from "./releases/common.mjs"; + +// Installs the pinned managed runtime with the plugin's own installer, so CI +// and local checks exercise the same downloads and verification as the +// Settings screen. Honors XDG_DATA_HOME for an isolated destination. +async function loadInstaller() { + const result = await build({ + stdin: { + contents: + 'export { ManagedRuntimeInstaller, resolveManagedRuntime } from "./server/runtime/managed.ts";', + resolveDir: fileURLToPath(new URL("..", import.meta.url)), + }, + bundle: true, + platform: "node", + format: "esm", + write: false, + }); + return import( + `data:text/javascript;base64,${Buffer.from(result.outputFiles[0].contents).toString("base64")}` + ); +} + +runMain(import.meta.url, async () => { + const { ManagedRuntimeInstaller, resolveManagedRuntime } = + await loadInstaller(); + const installer = new ManagedRuntimeInstaller(); + installer.start(); + let last = ""; + const timer = setInterval(() => { + const state = installer.state(); + const line = + state.state === "running" + ? `${state.component} ${state.phase} ${Math.floor((state.receivedBytes / Math.max(state.totalBytes, 1)) * 100)}%` + : state.state; + if (line !== last) console.log(line); + last = line; + }, 2000); + try { + await installer.settled(); + } finally { + clearInterval(timer); + } + const state = installer.state(); + if (state.state !== "succeeded") + throw new Error( + `${state.code ?? "RUNTIME_SETUP_FAILED"}: ${state.message}`, + ); + console.log(JSON.stringify(await resolveManagedRuntime(), null, 2)); +}); diff --git a/scripts/package-zcode-runtime.mjs b/scripts/package-zcode-runtime.mjs new file mode 100644 index 0000000..f3ca35c --- /dev/null +++ b/scripts/package-zcode-runtime.mjs @@ -0,0 +1,203 @@ +import { execFileSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { createReadStream } from "node:fs"; +import { + access, + appendFile, + copyFile, + mkdir, + mkdtemp, + readFile, + rm, + stat, + writeFile, +} from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { parseArgs } from "node:util"; +import { runMain, validateVersion } from "./releases/common.mjs"; +import { loadZCodeManifest } from "./zcode-manifest.mjs"; + +// Repackages the official integrated CLI archive built from unmodified source. +// Only upstream license material and build provenance are added. +export const RUNTIME_TAG_PREFIX = "zcode-runtime-v"; +export const REQUIRED_RUNTIME_FILES = [ + "package.json", + "bin/zcode.mjs", + "server/remote/zcode-server.cjs", + "agent/zcode.cjs", + "agent/provider/zcode-builtin.json", + "agent/THIRD-PARTY-NOTICES.md", +]; +export const UPSTREAM_NOTICE_FILES = [ + "LICENSE", + "NOTICE.md", + "THIRD-PARTY-NOTICES.md", +]; + +export function runtimeVersionFromTag(tag) { + if (!tag.startsWith(RUNTIME_TAG_PREFIX)) + throw new Error(`Runtime tags must start with ${RUNTIME_TAG_PREFIX}`); + return validateVersion(tag.slice(RUNTIME_TAG_PREFIX.length)); +} + +export const runtimeAssetName = (version) => + `zcode-runtime-${validateVersion(version)}.tar.gz`; + +export async function assertRuntimeLayout(root, files) { + for (const file of files) + try { + await access(join(root, file)); + } catch { + throw new Error(`Runtime archive is missing ${file}`); + } +} + +export async function sha256File(path) { + const hash = createHash("sha256"); + for await (const chunk of createReadStream(path)) hash.update(chunk); + return hash.digest("hex"); +} + +const git = (source, ...args) => + execFileSync("git", ["-C", source, ...args], { encoding: "utf8" }).trim(); + +function createArchive(staging, output, mtime) { + // GNU tar (CI) gets stable ordering and ownership; bsdtar is enough locally. + const gnu = execFileSync("tar", ["--version"], { encoding: "utf8" }).includes( + "GNU tar", + ); + const options = gnu + ? [ + "--sort=name", + "--owner=0", + "--group=0", + "--numeric-owner", + `--mtime=@${mtime}`, + "--use-compress-program=gzip -n -9", + "-cf", + ] + : ["-czf"]; + execFileSync("tar", [...options, output, "-C", staging, "zcode"]); +} + +export async function packageRuntime({ source, out, tag }) { + const { ZCODE_SOURCE_COMMIT } = await loadZCodeManifest(); + const commit = git(source, "rev-parse", "HEAD"); + if (commit !== ZCODE_SOURCE_COMMIT) + throw new Error( + `ZCode checkout ${commit} does not match pinned ${ZCODE_SOURCE_COMMIT}`, + ); + const version = validateVersion( + JSON.parse(await readFile(join(source, "package.json"), "utf8")).version, + ); + if (tag !== undefined && runtimeVersionFromTag(tag) !== version) + throw new Error(`Tag ${tag} does not match ZCode ${version}`); + const releaseDirectory = join(source, "dist/zcode/releases", version); + const upstreamArchive = join(releaseDirectory, `zcode-${version}.tar.gz`); + const upstreamSha256 = await sha256File(upstreamArchive); + const recorded = ( + await readFile(join(releaseDirectory, "sha256.txt"), "utf8") + ) + .trim() + .split(/\s+/u)[0]; + if (recorded !== upstreamSha256) + throw new Error("Official archive does not match its sha256.txt"); + + const staging = await mkdtemp(join(tmpdir(), "zcode-runtime-package-")); + try { + execFileSync("tar", ["-xzf", upstreamArchive, "-C", staging]); + const root = join(staging, "zcode"); + await assertRuntimeLayout(root, REQUIRED_RUNTIME_FILES); + for (const file of UPSTREAM_NOTICE_FILES) { + try { + await access(join(root, file)); + throw new Error(`Official archive already contains ${file}`); + } catch (error) { + if (error.code !== "ENOENT") throw error; + } + await copyFile(join(source, file), join(root, file)); + } + const run = process.env.GITHUB_RUN_ID + ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` + : null; + await writeFile( + join(root, "BUILD-INFO.json"), + JSON.stringify( + { + description: + "Unofficial build of the ZCode integrated CLI distribution, packaged for paseo-plugin-zcode-provider. It is not endorsed or maintained by ZCode or Z.ai.", + source: { + repository: "https://github.com/zai-org/ZCode", + commit, + version, + modified: false, + }, + build: { + script: "scripts/build-zcode.mjs", + officialArchiveSha256: upstreamSha256, + node: process.version, + workflowRun: run, + }, + license: + "Apache-2.0 for ZCode first-party code. Third-party components keep their own terms; see LICENSE, NOTICE.md and THIRD-PARTY-NOTICES.md.", + }, + null, + 2, + ) + "\n", + ); + await mkdir(out, { recursive: true }); + const asset = runtimeAssetName(version); + const output = resolve(out, asset); + createArchive( + staging, + output, + git(source, "show", "-s", "--format=%ct", "HEAD"), + ); + const sha256 = await sha256File(output); + const { size } = await stat(output); + await writeFile(join(out, "SHA256SUMS"), `${sha256} ${asset}\n`); + const result = { version, commit, asset, sha256, size }; + if (process.env.GITHUB_OUTPUT) + await appendFile( + process.env.GITHUB_OUTPUT, + Object.entries(result) + .map(([key, value]) => `${key}=${value}\n`) + .join(""), + ); + return result; + } finally { + await rm(staging, { recursive: true, force: true }); + } +} + +runMain(import.meta.url, async () => { + const { values, positionals } = parseArgs({ + allowPositionals: true, + options: { + source: { type: "string" }, + out: { type: "string" }, + tag: { type: "string" }, + }, + }); + if (positionals[0] === "commit") { + const { ZCODE_SOURCE_COMMIT } = await loadZCodeManifest(); + console.log(ZCODE_SOURCE_COMMIT); + return; + } + if (positionals[0] !== "package" || !values.source || !values.out) + throw new Error( + "Usage: package-zcode-runtime.mjs commit | package --source --out [--tag zcode-runtime-v]", + ); + console.log( + JSON.stringify( + await packageRuntime({ + source: resolve(values.source), + out: resolve(values.out), + tag: values.tag || undefined, + }), + null, + 2, + ), + ); +}); diff --git a/scripts/sync-zcode-source.mjs b/scripts/sync-zcode-source.mjs index f0e1585..0160a14 100644 --- a/scripts/sync-zcode-source.mjs +++ b/scripts/sync-zcode-source.mjs @@ -4,7 +4,7 @@ import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"; import { dirname, join, posix, resolve } from "node:path"; import ts from "typescript"; -export const ZCODE_SOURCE_COMMIT = "872ad960de7ec172591f7e1952f7849229f94521"; +export const ZCODE_SOURCE_COMMIT = "29628c9acdb81b703bbd4080c207a0e7ce5e276e"; const checkout = resolve( process.argv.slice(2).find((arg) => arg !== "--write") ?? `${process.env.HOME}/ghq/github.com/zai-org/ZCode`, diff --git a/scripts/zcode-manifest.mjs b/scripts/zcode-manifest.mjs new file mode 100644 index 0000000..2a93d0f --- /dev/null +++ b/scripts/zcode-manifest.mjs @@ -0,0 +1,20 @@ +import { build } from "esbuild"; +import { fileURLToPath } from "node:url"; + +// Scripts read the provider's TypeScript manifest instead of duplicating its pins. +export async function loadZCodeManifest() { + const result = await build({ + entryPoints: [ + fileURLToPath( + new URL("../server/discovery/manifest.ts", import.meta.url), + ), + ], + bundle: true, + platform: "node", + format: "esm", + write: false, + }); + return import( + `data:text/javascript;base64,${Buffer.from(result.outputFiles[0].contents).toString("base64")}` + ); +} diff --git a/server/discovery.test.ts b/server/discovery.test.ts index 2548975..f8532df 100644 --- a/server/discovery.test.ts +++ b/server/discovery.test.ts @@ -1,22 +1,32 @@ import { expect, it, vi, afterEach } from "vitest"; -import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises"; +import { cp, mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { discoverRuntime, runtimeEnvironment } from "./discovery/discover.js"; +import { managedLayout } from "./runtime/managed.js"; +import { managedPlatform } from "./runtime/pins.js"; const dirs: string[] = []; afterEach(async () => { vi.restoreAllMocks(); for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }); }); it.each([ - {}, { PASEO_ZCODE_RUNTIME: "relative", PASEO_ZCODE_NODE: "/node" }, { PASEO_ZCODE_RUNTIME: "/runtime", PASEO_ZCODE_NODE: "relative" }, -])("requires both explicit absolute paths", async (environment) => { + { PASEO_ZCODE_RUNTIME: "/runtime" }, + { PASEO_ZCODE_NODE: "/node" }, +])("requires both override paths to be absolute: %j", async (environment) => { await expect(discoverRuntime({ environment })).rejects.toMatchObject({ code: "RUNTIME_DISCOVERY_FAILED", }); }); +it("asks for setup when neither override nor a managed runtime exists", async () => { + const data = await mkdtemp(join(tmpdir(), "zcode-managed-empty-")); + dirs.push(data); + await expect( + discoverRuntime({ environment: { XDG_DATA_HOME: data } }), + ).rejects.toMatchObject({ code: "RUNTIME_SETUP_REQUIRED" }); +}); it("rejects missing files without discovering Desktop", async () => { const root = await mkdtemp(join(tmpdir(), "zcode-discovery-")); dirs.push(root); @@ -79,3 +89,32 @@ it("validates the integrated layout and hashes its Server and Agent independentl await realpath(f.environment.PASEO_ZCODE_NODE), ); }); + +it.runIf(managedPlatform() !== undefined)( + "uses the installed managed runtime when no override is set", + async () => { + const data = await mkdtemp(join(tmpdir(), "zcode-managed-data-")); + dirs.push(data); + const environment = { XDG_DATA_HOME: data }; + const layout = managedLayout(environment)!; + const f = await executableFixture({ node: "24.21.0" }); + await mkdir(layout.root, { recursive: true }); + await cp(f.root, layout.zcode.directory, { recursive: true }); + await mkdir(join(layout.node.executable, ".."), { recursive: true }); + await cp(f.environment.PASEO_ZCODE_NODE, layout.node.executable); + for (const component of [layout.node, layout.zcode]) + await writeFile( + join(component.directory, ".paseo-managed.json"), + JSON.stringify({ + version: component.version, + archiveSha256: component.archive.sha256, + }), + ); + const found = await discoverRuntime({ environment }); + expect(found.source).toBe("managed"); + expect(found.paths.installRoot).toBe( + await realpath(layout.zcode.directory), + ); + expect(found.paths.executable).toBe(await realpath(layout.node.executable)); + }, +); diff --git a/server/discovery/discover.ts b/server/discovery/discover.ts index f513c9e..1a3a3e2 100644 --- a/server/discovery/discover.ts +++ b/server/discovery/discover.ts @@ -5,6 +5,7 @@ import { isAbsolute, join } from "node:path"; import { gte, valid } from "semver"; import { z } from "zod"; import { AdapterError } from "../errors.js"; +import { resolveManagedRuntime } from "../runtime/managed.js"; import { assessCompatibility, MINIMUM_NODE_VERSION } from "./manifest.js"; import type { DiscoveredRuntime, RuntimeSmokeResult } from "./types.js"; @@ -49,21 +50,43 @@ async function run( ); }); } +// Both variables override the managed runtime (ADR 15); setting only one is a +// configuration error rather than a silent fallback. +async function configuredPaths(environment: NodeJS.ProcessEnv): Promise<{ + installRoot: string; + executable: string; + source: DiscoveredRuntime["source"]; +}> { + const names = ["PASEO_ZCODE_RUNTIME", "PASEO_ZCODE_NODE"] as const; + if (names.some((name) => environment[name])) { + for (const name of names) + if (!environment[name] || !isAbsolute(environment[name]!)) + throw new AdapterError( + "RUNTIME_DISCOVERY_FAILED", + `${name} must be an absolute path; set both variables or neither`, + ); + return { + installRoot: environment.PASEO_ZCODE_RUNTIME!, + executable: environment.PASEO_ZCODE_NODE!, + source: "environment", + }; + } + const managed = await resolveManagedRuntime(environment); + if (managed === undefined) + throw new AdapterError( + "RUNTIME_SETUP_REQUIRED", + "ZCode runtime is not set up. Open Settings → Plugins → zcode-provider to set it up.", + ); + return { ...managed, source: "managed" }; +} export async function discoverRuntime({ environment = process.env, signal, }: DiscoveryOptions = {}): Promise { - const configured = ["PASEO_ZCODE_RUNTIME", "PASEO_ZCODE_NODE"] as const; - for (const name of configured) { - if (!environment[name] || !isAbsolute(environment[name]!)) - throw new AdapterError( - "RUNTIME_DISCOVERY_FAILED", - `${name} must be an absolute path`, - ); - } + const configured = await configuredPaths(environment); try { - const installRoot = await realpath(environment.PASEO_ZCODE_RUNTIME!); - const executable = await realpath(environment.PASEO_ZCODE_NODE!); + const installRoot = await realpath(configured.installRoot); + const executable = await realpath(configured.executable); if ( !(await stat(installRoot)).isDirectory() || !(await stat(executable)).isFile() @@ -154,6 +177,7 @@ export async function discoverRuntime({ }; const compatibility = assessCompatibility(identity); return { + source: configured.source, paths, identity, compatibility: compatibility.status, diff --git a/server/discovery/manifest.ts b/server/discovery/manifest.ts index c8211ce..fefcd58 100644 --- a/server/discovery/manifest.ts +++ b/server/discovery/manifest.ts @@ -1,7 +1,7 @@ import { gte, parse } from "semver"; import type { RuntimeIdentity } from "./types.js"; -export const ZCODE_SOURCE_COMMIT = "872ad960de7ec172591f7e1952f7849229f94521"; +export const ZCODE_SOURCE_COMMIT = "29628c9acdb81b703bbd4080c207a0e7ce5e276e"; export const MINIMUM_ZCODE_VERSION = { app: "3.14.0", cli: "0.16.9" } as const; export const MINIMUM_NODE_VERSION = "24.14.0"; @@ -33,4 +33,4 @@ export function assessCompatibility(identity: RuntimeIdentity): { } // Last reviewed public changelog release; source versions are not releases. -export const LAST_REVIEWED_ZCODE_RELEASE = "3.12.3"; +export const LAST_REVIEWED_ZCODE_RELEASE = "3.14.3"; diff --git a/server/discovery/types.ts b/server/discovery/types.ts index 8e2bce6..4e172ca 100644 --- a/server/discovery/types.ts +++ b/server/discovery/types.ts @@ -15,6 +15,8 @@ export interface RuntimeIdentity { readonly serverSha256: string; } export interface DiscoveredRuntime { + /** "managed" is the pinned plugin-installed runtime; "environment" is an override. */ + readonly source: "managed" | "environment"; readonly paths: RuntimePaths; readonly identity: RuntimeIdentity; readonly compatibility: "supported" | "unsupported"; diff --git a/server/errors.ts b/server/errors.ts index e6f8723..9171d86 100644 --- a/server/errors.ts +++ b/server/errors.ts @@ -8,6 +8,8 @@ export type ZCodeErrorCode = | "UNSUPPORTED_ZCODE" | "RUNTIME_DISCOVERY_FAILED" | "RUNTIME_SMOKE_FAILED" + | "RUNTIME_SETUP_REQUIRED" + | "RUNTIME_SETUP_FAILED" | "NATIVE_PROTOCOL_ERROR" | "NATIVE_INPUT_REJECTED" | "NATIVE_TIMEOUT" diff --git a/server/host-bridge.test.ts b/server/host-bridge.test.ts index 16aa6d1..b57c6ed 100644 --- a/server/host-bridge.test.ts +++ b/server/host-bridge.test.ts @@ -38,6 +38,7 @@ beforeAll(async () => { compatibility: "supported", compatibilityReason: "test fixture", writableInstallRoot: true, + source: "environment", }; }); afterAll(async () => { diff --git a/server/provider.ts b/server/provider.ts index 0c5191c..a56461a 100644 --- a/server/provider.ts +++ b/server/provider.ts @@ -811,6 +811,8 @@ function publicError(error: unknown): ProviderError { UNSUPPORTED_ZCODE: `ZCode requires stable app >=${MINIMUM_ZCODE_VERSION.app} and bundled CLI >=${MINIMUM_ZCODE_VERSION.cli}.`, RUNTIME_DISCOVERY_FAILED: "ZCode installation or required host structure could not be inspected. See the diagnostic for the failure stage.", + RUNTIME_SETUP_REQUIRED: + "ZCode runtime is not set up. Open Settings → Plugins → zcode-provider to set it up.", PERSISTENCE_VERSION_UNSUPPORTED: "ZCode persistence version is unsupported. Create a new Paseo ZCode session.", PERSISTENCE_INVALID: diff --git a/server/runtime-setup.test.ts b/server/runtime-setup.test.ts new file mode 100644 index 0000000..1208b01 --- /dev/null +++ b/server/runtime-setup.test.ts @@ -0,0 +1,103 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import { createRuntimeSetupHandlers, loginCommand } from "./runtime-setup.js"; +import { ManagedRuntimeInstaller, managedLayout } from "./runtime/managed.js"; + +const directories: string[] = []; +afterEach(async () => { + for (const directory of directories.splice(0)) + await rm(directory, { recursive: true, force: true }); +}); + +async function dataHome() { + const directory = await mkdtemp(join(tmpdir(), "zcode-setup-status-")); + directories.push(directory); + return directory; +} + +describe("login command", () => { + it("quotes POSIX paths for a shell", () => { + expect(loginCommand("/opt/it's/node", "/data/zcode", false)).toBe( + `'/opt/it'\\''s/node' '/data/zcode/bin/zcode.mjs' login`, + ); + }); + + it("uses the PowerShell call operator on Windows", () => { + expect( + loginCommand("C:\\Users\\O'Neil\\node.exe", "C:\\data\\zcode", true), + ).toMatch(/^& 'C:\\Users\\O''Neil\\node\.exe' '.+zcode\.mjs' login$/u); + }); +}); + +describe("runtime setup status", () => { + it("lists pinned downloads without a login command before setup", async () => { + const environment = { XDG_DATA_HOME: await dataHome() }; + const handlers = createRuntimeSetupHandlers( + new ManagedRuntimeInstaller(environment, "linux-x64"), + environment, + ); + const status = await handlers.status(); + expect(status).toMatchObject({ + supported: true, + override: false, + job: { state: "idle" }, + }); + expect(status.components.map((component) => component.id)).toEqual([ + "node", + "zcode", + ]); + expect(status.components.every((component) => !component.installed)).toBe( + true, + ); + expect(status.loginCommand).toBeUndefined(); + }); + + it("offers the login command once both components are installed", async () => { + const environment = { XDG_DATA_HOME: await dataHome() }; + const layout = managedLayout(environment, "linux-x64")!; + for (const component of [layout.node, layout.zcode]) { + await mkdir(component.directory, { recursive: true }); + await writeFile( + join(component.directory, ".paseo-managed.json"), + JSON.stringify({ + version: component.version, + archiveSha256: component.archive.sha256, + }), + ); + } + const status = await createRuntimeSetupHandlers( + new ManagedRuntimeInstaller(environment, "linux-x64"), + { ...environment, PASEO_ZCODE_NODE: "/custom/node" }, + ).status(); + expect(status.override).toBe(true); + expect(status.loginCommand).toContain( + join(layout.zcode.directory, "bin", "zcode.mjs"), + ); + }); + + it("reports unsupported platforms without components", async () => { + const environment = { XDG_DATA_HOME: await dataHome() }; + const status = await createRuntimeSetupHandlers( + new ManagedRuntimeInstaller(environment, null), + environment, + ).status(); + expect(status).toMatchObject({ supported: false, components: [] }); + }); + + it("returns a removal failure instead of throwing", async () => { + const environment = { XDG_DATA_HOME: await dataHome() }; + // The job must stay offline; it only needs to be running during removal. + const installer = new ManagedRuntimeInstaller(environment, "linux-x64", { + fetch: async () => { + throw new Error("offline"); + }, + }); + const handlers = createRuntimeSetupHandlers(installer, environment); + expect(await handlers.remove()).toEqual({ status: "removed" }); + installer.start(); + expect(await handlers.remove()).toMatchObject({ status: "failed" }); + await installer.settled(); + }); +}); diff --git a/server/runtime-setup.ts b/server/runtime-setup.ts new file mode 100644 index 0000000..a505e42 --- /dev/null +++ b/server/runtime-setup.ts @@ -0,0 +1,102 @@ +import { join } from "node:path"; +import type { RuntimeSetupStatus } from "../shared/runtime-setup.js"; +import { AdapterError } from "./errors.js"; +import { + isInstalled, + managedRuntimeRoot, + ManagedRuntimeInstaller, + type ManagedComponent, +} from "./runtime/managed.js"; + +const LICENSES = { + node: "Node.js license (MIT) with bundled third-party notices", + zcode: + "Unofficial build of ZCode (Apache-2.0); third-party terms in THIRD-PARTY-NOTICES.md", +} as const; + +// Quoted for the shell a user is most likely to paste into on that OS. +export function loginCommand( + executable: string, + installRoot: string, + windows = process.platform === "win32", +): string { + const script = join(installRoot, "bin", "zcode.mjs"); + return windows + ? `& ${powershellQuote(executable)} ${powershellQuote(script)} login` + : `${posixQuote(executable)} ${posixQuote(script)} login`; +} +const posixQuote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`; +const powershellQuote = (value: string) => `'${value.replaceAll("'", "''")}'`; + +export function createRuntimeSetupHandlers( + installer: ManagedRuntimeInstaller, + environment: NodeJS.ProcessEnv = process.env, +) { + const component = async ( + entry: ManagedComponent, + ): Promise => ({ + id: entry.id, + name: entry.id === "node" ? "Node.js" : "ZCode runtime", + version: entry.version, + url: entry.archive.url, + sha256: entry.archive.sha256, + sizeBytes: entry.archive.size, + license: LICENSES[entry.id], + installed: await isInstalled(entry), + }); + + return { + async status(): Promise { + const layout = installer.layout(); + const override = Boolean( + environment.PASEO_ZCODE_RUNTIME || environment.PASEO_ZCODE_NODE, + ); + const base = { + platform: `${process.platform}-${process.arch}`, + override, + job: installer.state(), + }; + if (layout === undefined) + return { + ...base, + supported: false, + directory: managedRuntimeRoot(environment), + components: [], + }; + const components = [ + await component(layout.node), + await component(layout.zcode), + ]; + return { + ...base, + supported: true, + directory: layout.root, + components, + ...(components.every((entry) => entry.installed) + ? { + loginCommand: loginCommand( + layout.node.executable, + layout.zcode.directory, + layout.platform.startsWith("win-"), + ), + } + : {}), + }; + }, + install: async () => ({ started: installer.start() }), + async remove() { + try { + await installer.remove(); + return { status: "removed" as const }; + } catch (error) { + return { + status: "failed" as const, + message: + error instanceof AdapterError + ? error.message + : "The managed runtime could not be removed", + }; + } + }, + }; +} diff --git a/server/runtime/managed.test.ts b/server/runtime/managed.test.ts new file mode 100644 index 0000000..e9c3e45 --- /dev/null +++ b/server/runtime/managed.test.ts @@ -0,0 +1,274 @@ +import { execFileSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { + mkdir, + mkdtemp, + readFile, + readdir, + rm, + stat, + writeFile, +} from "node:fs/promises"; +import { homedir, tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { + MANAGED_ZCODE_FILES, + ManagedRuntimeInstaller, + isInstalled, + managedLayout, + managedRuntimeRoot, + resolveManagedRuntime, + type ManagedLayout, +} from "./managed.js"; +import { + MANAGED_NODE_ARCHIVES, + MANAGED_ZCODE_ARCHIVE, + managedPlatform, +} from "./pins.js"; + +const directories: string[] = []; +afterEach(async () => { + vi.restoreAllMocks(); + for (const directory of directories.splice(0)) + await rm(directory, { recursive: true, force: true }); +}); + +async function temporary(prefix: string): Promise { + const directory = await mkdtemp(join(tmpdir(), prefix)); + directories.push(directory); + return directory; +} + +// Builds a .tar.gz with one top-level directory, like the real archives. +async function archive(top: string, files: readonly string[]) { + const source = await temporary("zcode-archive-source-"); + for (const file of files) { + await mkdir(join(source, top, file, ".."), { recursive: true }); + await writeFile(join(source, top, file), `${top}/${file}`); + } + const output = join(await temporary("zcode-archive-"), "archive.tgz"); + execFileSync("tar", ["-czf", output, "-C", source, top]); + const bytes = await readFile(output); + return { + bytes, + sha256: createHash("sha256").update(bytes).digest("hex"), + size: bytes.length, + }; +} + +async function fixture() { + const data = await temporary("zcode-managed-"); + const base = managedLayout({ XDG_DATA_HOME: data }, "linux-x64")!; + const node = await archive("node-fixture", ["bin/node"]); + const zcode = await archive("zcode", MANAGED_ZCODE_FILES); + const layout: ManagedLayout = { + ...base, + node: { + ...base.node, + archive: { url: "https://example.test/node.tgz", ...node }, + }, + zcode: { + ...base.zcode, + archive: { url: "https://example.test/zcode.tgz", ...zcode }, + }, + }; + const bodies = new Map([ + [layout.node.archive.url, node.bytes], + [layout.zcode.archive.url, zcode.bytes], + ]); + const fetch = vi.fn(async (url: string | URL | Request) => { + const body = bodies.get(String(url)); + return body === undefined + ? new Response("missing", { status: 404 }) + : new Response(body); + }); + const nodeVersion = vi.fn(async () => `v${layout.node.version}`); + const installer = new ManagedRuntimeInstaller({}, "linux-x64", { + layout, + fetch: fetch as typeof globalThis.fetch, + nodeVersion, + }); + return { data, layout, bodies, fetch, nodeVersion, installer }; +} + +async function finish(installer: ManagedRuntimeInstaller) { + expect(installer.start()).toBe(true); + await installer.settled(); + return installer.state(); +} + +describe("pins", () => { + it("pins every managed Node.js archive by SHA-256 and size", () => { + for (const archive of Object.values(MANAGED_NODE_ARCHIVES)) { + expect(archive.url).toMatch(/^https:\/\/nodejs\.org\/dist\//u); + expect(archive.sha256).toMatch(/^[0-9a-f]{64}$/u); + expect(archive.size).toBeGreaterThan(0); + } + }); + + it("pins the published ZCode runtime archive", () => { + expect(MANAGED_ZCODE_ARCHIVE.url).toMatch( + /^https:\/\/github\.com\/supermomonga\/paseo-plugin-zcode-provider\/releases\/download\/zcode-runtime-v/u, + ); + expect(MANAGED_ZCODE_ARCHIVE.sha256).toMatch(/^[0-9a-f]{64}$/u); + expect(MANAGED_ZCODE_ARCHIVE.size).toBeGreaterThan(0); + }); + + it("maps only the five managed platforms", () => { + expect(managedPlatform("darwin", "arm64")).toBe("darwin-arm64"); + expect(managedPlatform("win32", "x64")).toBe("win-x64"); + expect(managedPlatform("linux", "arm64")).toBe("linux-arm64"); + expect(managedPlatform("darwin", "x64")).toBeUndefined(); + expect(managedPlatform("freebsd", "x64")).toBeUndefined(); + }); +}); + +describe("managed runtime location", () => { + const suffix = join("paseo-plugin-zcode-provider", "runtimes"); + + it("uses %LOCALAPPDATA% on Windows and ~/.local/share elsewhere", () => { + const local = join(tmpdir(), "AppData", "Local"); + expect(managedRuntimeRoot({ LOCALAPPDATA: local }, "win32")).toBe( + join(local, suffix), + ); + expect(managedRuntimeRoot({}, "win32")).toBe( + join(homedir(), "AppData", "Local", suffix), + ); + for (const platform of ["darwin", "linux"] as const) + expect(managedRuntimeRoot({ LOCALAPPDATA: local }, platform)).toBe( + join(homedir(), ".local", "share", suffix), + ); + }); + + it("honors only an absolute XDG_DATA_HOME, on every OS", () => { + const data = join(tmpdir(), "xdg-data"); + for (const platform of ["win32", "darwin", "linux"] as const) + expect(managedRuntimeRoot({ XDG_DATA_HOME: data }, platform)).toBe( + join(data, suffix), + ); + expect(managedRuntimeRoot({ XDG_DATA_HOME: "relative" }, "linux")).toBe( + join(homedir(), ".local", "share", suffix), + ); + expect(managedRuntimeRoot({ XDG_DATA_HOME: "" }, "darwin")).toBe( + join(homedir(), ".local", "share", suffix), + ); + }); +}); + +describe("ManagedRuntimeInstaller", () => { + it("installs verified archives atomically and skips them afterwards", async () => { + const f = await fixture(); + expect(await finish(f.installer)).toEqual({ state: "succeeded" }); + expect(await isInstalled(f.layout.node)).toBe(true); + expect(await isInstalled(f.layout.zcode)).toBe(true); + expect( + (await stat(join(f.layout.zcode.directory, "agent/zcode.cjs"))).isFile(), + ).toBe(true); + expect(f.nodeVersion).toHaveBeenCalledWith( + expect.stringMatching(/[\\/]bin[\\/]node$/u), + ); + expect(await readdir(f.layout.root)).not.toContain(".lock"); + expect(f.fetch).toHaveBeenCalledTimes(2); + + expect(await finish(f.installer)).toEqual({ state: "succeeded" }); + expect(f.fetch).toHaveBeenCalledTimes(2); + }); + + it("rejects an archive whose SHA-256 differs and leaves no install", async () => { + const f = await fixture(); + f.bodies.set( + f.layout.zcode.archive.url, + Buffer.alloc(f.layout.zcode.archive.size), + ); + expect(await finish(f.installer)).toMatchObject({ + state: "failed", + code: "RUNTIME_SETUP_FAILED", + message: expect.stringContaining("SHA-256"), + }); + expect(await isInstalled(f.layout.zcode)).toBe(false); + expect(await readdir(join(f.layout.root, ".staging"))).toEqual([]); + }); + + it("stops downloads larger than the pinned size", async () => { + const f = await fixture(); + f.bodies.set( + f.layout.node.archive.url, + Buffer.alloc(f.layout.node.archive.size + 1), + ); + expect(await finish(f.installer)).toMatchObject({ + state: "failed", + message: expect.stringContaining("larger than the pinned size"), + }); + }); + + it("reports HTTP failures without installing anything", async () => { + const f = await fixture(); + f.bodies.delete(f.layout.node.archive.url); + expect(await finish(f.installer)).toMatchObject({ + state: "failed", + message: expect.stringContaining("HTTP 404"), + }); + expect(await resolveManagedRuntime({ XDG_DATA_HOME: f.data })).toBe( + undefined, + ); + }); + + it("rejects a Node.js archive that reports another version", async () => { + const f = await fixture(); + f.nodeVersion.mockResolvedValue("v22.0.0"); + expect(await finish(f.installer)).toMatchObject({ + state: "failed", + message: expect.stringContaining("version check"), + }); + expect(await isInstalled(f.layout.node)).toBe(false); + }); + + it("runs one job at a time and refuses removal meanwhile", async () => { + const f = await fixture(); + expect(f.installer.start()).toBe(true); + expect(f.installer.start()).toBe(false); + expect(f.installer.state()).toMatchObject({ state: "running" }); + await expect(f.installer.remove()).rejects.toMatchObject({ + code: "RUNTIME_SETUP_FAILED", + }); + await f.installer.settled(); + }); + + it("reclaims a lock left by a dead process but not by a live one", async () => { + const f = await fixture(); + const lock = join(f.layout.root, ".lock"); + await mkdir(lock, { recursive: true }); + await writeFile(join(lock, "owner"), String(process.pid)); + expect(await finish(f.installer)).toMatchObject({ + state: "failed", + message: "Another ZCode runtime setup is running", + }); + vi.spyOn(process, "kill").mockImplementation(() => { + throw Object.assign(new Error("gone"), { code: "ESRCH" }); + }); + expect(await finish(f.installer)).toEqual({ state: "succeeded" }); + }); + + it("removes stale versions after setup and everything on removal", async () => { + const f = await fixture(); + const stale = join(f.layout.root, "zcode-0.0.1-000000000000"); + await mkdir(stale, { recursive: true }); + expect(await finish(f.installer)).toEqual({ state: "succeeded" }); + await expect(stat(stale)).rejects.toMatchObject({ code: "ENOENT" }); + await f.installer.remove(); + await expect(stat(f.layout.root)).rejects.toMatchObject({ code: "ENOENT" }); + expect(f.installer.state()).toEqual({ state: "idle" }); + }); + + it("fails clearly on platforms without managed archives", async () => { + const installer = new ManagedRuntimeInstaller( + { XDG_DATA_HOME: await temporary("zcode-unsupported-") }, + null, + ); + expect(await finish(installer)).toMatchObject({ + state: "failed", + code: "UNSUPPORTED_PLATFORM", + }); + }); +}); diff --git a/server/runtime/managed.ts b/server/runtime/managed.ts new file mode 100644 index 0000000..6632b0a --- /dev/null +++ b/server/runtime/managed.ts @@ -0,0 +1,501 @@ +import { execFile } from "node:child_process"; +import { createHash } from "node:crypto"; +import { createWriteStream } from "node:fs"; +import { + access, + mkdir, + mkdtemp, + readFile, + readdir, + rename, + rm, + stat, + writeFile, +} from "node:fs/promises"; +import { homedir } from "node:os"; +import { isAbsolute, join, relative } from "node:path"; +import { Readable, Transform } from "node:stream"; +import { pipeline } from "node:stream/promises"; +import { z } from "zod"; +import { AdapterError } from "../errors.js"; +import { + MANAGED_NODE_ARCHIVES, + MANAGED_NODE_VERSION, + MANAGED_ZCODE_ARCHIVE, + MANAGED_ZCODE_VERSION, + managedPlatform, + type ManagedPlatform, + type PinnedArchive, +} from "./pins.js"; + +export type ManagedComponentId = "node" | "zcode"; + +export interface ManagedComponent { + readonly id: ManagedComponentId; + readonly version: string; + readonly archive: PinnedArchive; + /** Final directory; it exists only after a verified, complete install. */ + readonly directory: string; +} + +export interface ManagedLayout { + readonly root: string; + readonly platform: ManagedPlatform; + readonly node: ManagedComponent & { readonly executable: string }; + readonly zcode: ManagedComponent; +} + +// Files the provider launches or must ship with the redistributed runtime. +export const MANAGED_ZCODE_FILES = [ + "package.json", + "bin/zcode.mjs", + "server/remote/zcode-server.cjs", + "agent/zcode.cjs", + "agent/provider/zcode-builtin.json", + "LICENSE", + "NOTICE.md", + "THIRD-PARTY-NOTICES.md", +] as const; + +const MARKER = ".paseo-managed.json"; +const markerSchema = z + .object({ version: z.string(), archiveSha256: z.string() }) + .strict(); + +// Outside the plugin checkout so plugin updates do not download the runtime +// again. Each OS uses its per-user data convention: Windows' non-roaming +// %LOCALAPPDATA%, otherwise ~/.local/share. An absolute XDG_DATA_HOME is an +// explicit override everywhere (CI isolates with it); relative values are +// ignored as the XDG specification requires. +export function managedRuntimeRoot( + environment: NodeJS.ProcessEnv = process.env, + platform: NodeJS.Platform = process.platform, +): string { + const absolute = (value: string | undefined) => + value !== undefined && isAbsolute(value) ? value : undefined; + const base = + absolute(environment.XDG_DATA_HOME) ?? + (platform === "win32" + ? (absolute(environment.LOCALAPPDATA) ?? + join(homedir(), "AppData", "Local")) + : join(homedir(), ".local", "share")); + return join(base, "paseo-plugin-zcode-provider", "runtimes"); +} + +export function managedLayout( + environment: NodeJS.ProcessEnv = process.env, + platform: ManagedPlatform | undefined = managedPlatform(), +): ManagedLayout | undefined { + if (platform === undefined) return undefined; + const root = managedRuntimeRoot(environment); + const nodeDirectory = join(root, `node-v${MANAGED_NODE_VERSION}-${platform}`); + return { + root, + platform, + node: { + id: "node", + version: MANAGED_NODE_VERSION, + archive: MANAGED_NODE_ARCHIVES[platform], + directory: nodeDirectory, + executable: platform.startsWith("win-") + ? join(nodeDirectory, "node.exe") + : join(nodeDirectory, "bin", "node"), + }, + zcode: { + id: "zcode", + version: MANAGED_ZCODE_VERSION, + archive: MANAGED_ZCODE_ARCHIVE, + directory: join( + root, + `zcode-${MANAGED_ZCODE_VERSION}-${MANAGED_ZCODE_ARCHIVE.sha256.slice(0, 12)}`, + ), + }, + }; +} + +export async function isInstalled( + component: ManagedComponent, +): Promise { + try { + const marker = markerSchema.parse( + JSON.parse(await readFile(join(component.directory, MARKER), "utf8")), + ); + return ( + marker.version === component.version && + marker.archiveSha256 === component.archive.sha256 + ); + } catch { + return false; + } +} + +/** Paths for discovery when both pinned components are installed. */ +export async function resolveManagedRuntime( + environment: NodeJS.ProcessEnv = process.env, +): Promise<{ installRoot: string; executable: string } | undefined> { + const layout = managedLayout(environment); + if ( + layout === undefined || + !(await isInstalled(layout.node)) || + !(await isInstalled(layout.zcode)) + ) + return undefined; + return { + installRoot: layout.zcode.directory, + executable: layout.node.executable, + }; +} + +export interface SetupProgress { + readonly component: ManagedComponentId; + readonly phase: "download" | "extract" | "verify"; + readonly receivedBytes: number; + readonly totalBytes: number; +} + +export type SetupState = + | { readonly state: "idle" } + | ({ readonly state: "running" } & SetupProgress) + | { readonly state: "succeeded" } + | { + readonly state: "failed"; + readonly code: string; + readonly message: string; + }; + +export interface InstallerDependencies { + /** Replaces the pinned layout; tests use it to install local archives. */ + readonly layout?: ManagedLayout; + readonly fetch?: typeof fetch; + readonly extract?: (archive: string, destination: string) => Promise; + readonly nodeVersion?: (executable: string) => Promise; +} + +function execute(file: string, args: string[]): Promise { + return new Promise((resolve, reject) => + execFile( + file, + args, + { timeout: 300_000, maxBuffer: 1024 * 1024, windowsHide: true }, + (error, stdout) => (error ? reject(error) : resolve(stdout.trim())), + ), + ); +} + +// System tar reads .tar.gz everywhere and .zip on Windows. Windows uses its own +// bsdtar by path: a Git-for-Windows GNU tar on PATH cannot read zip archives. +export function extractWithSystemTar( + archive: string, + destination: string, +): Promise { + const tar = + process.platform === "win32" + ? join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe") + : "tar"; + return execute(tar, ["-xf", archive, "-C", destination]).then(() => {}); +} + +const setupFailure = (message: string, cause?: unknown) => + new AdapterError("RUNTIME_SETUP_FAILED", message, {}, { cause }); + +/** + * Installs the pinned Node.js and ZCode runtime. One job runs at a time per + * plugin process; a lock directory also guards other processes sharing the root. + */ +export class ManagedRuntimeInstaller { + private current: SetupState = { state: "idle" }; + private job: Promise | undefined; + private readonly fetchImpl: typeof fetch; + private readonly extract: ( + archive: string, + destination: string, + ) => Promise; + private readonly nodeVersion: (executable: string) => Promise; + private readonly fixedLayout: ManagedLayout | undefined; + + constructor( + private readonly environment: NodeJS.ProcessEnv = process.env, + // null disables managed setup; tests use it for unsupported hosts. + private readonly platform: ManagedPlatform | null = managedPlatform() ?? + null, + dependencies: InstallerDependencies = {}, + ) { + this.fixedLayout = dependencies.layout; + this.fetchImpl = dependencies.fetch ?? fetch; + this.extract = dependencies.extract ?? extractWithSystemTar; + this.nodeVersion = + dependencies.nodeVersion ?? + ((executable) => execute(executable, ["--version"])); + } + + layout(): ManagedLayout | undefined { + if (this.fixedLayout !== undefined) return this.fixedLayout; + return this.platform === null + ? undefined + : managedLayout(this.environment, this.platform); + } + + state(): SetupState { + return this.current; + } + + /** Starts setup unless it is already running; returns whether it started. */ + start(): boolean { + if (this.job !== undefined) return false; + this.current = { + state: "running", + component: "node", + phase: "download", + receivedBytes: 0, + totalBytes: this.layout()?.node.archive.size ?? 0, + }; + this.job = this.install() + .then( + () => { + this.current = { state: "succeeded" }; + }, + (error: unknown) => { + this.current = { + state: "failed", + code: + error instanceof AdapterError + ? error.code + : "RUNTIME_SETUP_FAILED", + message: + error instanceof AdapterError + ? error.message + : "ZCode runtime setup failed", + }; + }, + ) + .finally(() => { + this.job = undefined; + }); + return true; + } + + /** Resolves when the current job, if any, has finished. */ + async settled(): Promise { + await this.job; + } + + async remove(): Promise { + const layout = this.layout(); + if (this.job !== undefined) + throw setupFailure("ZCode runtime setup is still running"); + const root = layout?.root ?? managedRuntimeRoot(this.environment); + try { + await rm(root, { recursive: true, force: true }); + } catch (error) { + throw setupFailure( + "The managed runtime could not be removed. Stop running ZCode sessions and try again.", + error, + ); + } + this.current = { state: "idle" }; + } + + private async install(): Promise { + const layout = this.layout(); + if (layout === undefined) + throw new AdapterError( + "UNSUPPORTED_PLATFORM", + "Managed ZCode setup is not available on this platform", + ); + if (!/^[0-9a-f]{64}$/u.test(layout.zcode.archive.sha256)) + throw setupFailure("This plugin build has no pinned ZCode runtime"); + await mkdir(layout.root, { recursive: true }); + const lock = await acquireLock(join(layout.root, ".lock")); + try { + await this.installComponent(layout, layout.node, async (directory) => { + const executable = join( + directory, + relative(layout.node.directory, layout.node.executable), + ); + if ((await this.nodeVersion(executable)) !== `v${layout.node.version}`) + throw setupFailure("The downloaded Node.js failed its version check"); + }); + await this.installComponent(layout, layout.zcode, async (directory) => { + for (const file of MANAGED_ZCODE_FILES) + await access(join(directory, file)).catch((error) => { + throw setupFailure( + `The ZCode runtime archive is missing ${file}`, + error, + ); + }); + }); + await this.removeStaleVersions(layout); + } finally { + await rm(lock, { recursive: true, force: true }); + } + } + + private async installComponent( + layout: ManagedLayout, + component: ManagedComponent, + verify: (directory: string) => Promise, + ): Promise { + if (await isInstalled(component)) return; + const stagingRoot = join(layout.root, ".staging"); + await mkdir(stagingRoot, { recursive: true }); + const staging = await mkdtemp(join(stagingRoot, `${component.id}-`)); + try { + const archive = join( + staging, + component.archive.url.endsWith(".zip") ? "archive.zip" : "archive.tgz", + ); + await this.download(component, archive); + this.progress(component, "extract"); + const extracted = join(staging, "extracted"); + await mkdir(extracted); + await this.extract(archive, extracted).catch((error) => { + throw setupFailure( + `The ${label(component)} archive could not be extracted`, + error, + ); + }); + const entries = await readdir(extracted); + if (entries.length !== 1) + throw setupFailure( + `The ${label(component)} archive has an unexpected layout`, + ); + const top = join(extracted, entries[0]!); + if (!(await stat(top)).isDirectory()) + throw setupFailure( + `The ${label(component)} archive has an unexpected layout`, + ); + this.progress(component, "verify"); + await verify(top); + await writeFile( + join(top, MARKER), + JSON.stringify({ + version: component.version, + archiveSha256: component.archive.sha256, + }), + ); + // A directory without a valid marker is an interrupted earlier attempt. + await rm(component.directory, { recursive: true, force: true }); + await rename(top, component.directory); + } finally { + await rm(staging, { recursive: true, force: true }); + } + } + + private async download( + component: ManagedComponent, + destination: string, + ): Promise { + const { url, sha256, size } = component.archive; + let response: Response; + try { + response = await this.fetchImpl(url, { redirect: "follow" }); + } catch (error) { + throw setupFailure( + `Cannot download ${label(component)} from ${url}`, + error, + ); + } + if (!response.ok || response.body === null) + throw setupFailure( + `Download of ${label(component)} failed with HTTP ${response.status}`, + ); + const hash = createHash("sha256"); + let received = 0; + this.progress(component, "download", received); + const meter = new Transform({ + transform: (chunk: Buffer, _encoding, callback) => { + hash.update(chunk); + received += chunk.length; + if (received > size) + return callback( + setupFailure(`${label(component)} is larger than the pinned size`), + ); + this.progress(component, "download", received); + callback(null, chunk); + }, + }); + try { + await pipeline( + Readable.fromWeb( + response.body as import("node:stream/web").ReadableStream, + ), + meter, + createWriteStream(destination, { flags: "wx" }), + ); + } catch (error) { + if (error instanceof AdapterError) throw error; + throw setupFailure( + `Download of ${label(component)} was interrupted`, + error, + ); + } + if (hash.digest("hex") !== sha256) + throw setupFailure( + `${label(component)} does not match its pinned SHA-256`, + ); + } + + private progress( + component: ManagedComponent, + phase: SetupProgress["phase"], + receivedBytes = component.archive.size, + ): void { + this.current = { + state: "running", + component: component.id, + phase, + receivedBytes, + totalBytes: component.archive.size, + }; + } + + private async removeStaleVersions(layout: ManagedLayout): Promise { + const keep = new Set([layout.node.directory, layout.zcode.directory]); + for (const entry of await readdir(layout.root)) { + const path = join(layout.root, entry); + if ( + !keep.has(path) && + (entry === ".staging" || /^(node-v|zcode-)/u.test(entry)) + ) + await rm(path, { recursive: true, force: true }).catch(() => {}); + } + } +} + +// A crashed setup leaves its lock behind; reclaim it only when its owner is gone. +async function acquireLock(lock: string): Promise { + for (let attempt = 0; attempt < 2; attempt++) { + try { + await mkdir(lock); + await writeFile(join(lock, "owner"), String(process.pid)); + return lock; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EEXIST") + throw setupFailure( + "Cannot create the managed runtime directory", + error, + ); + } + const owner = Number( + await readFile(join(lock, "owner"), "utf8").catch(() => ""), + ); + if (Number.isSafeInteger(owner) && owner > 0 && processExists(owner)) + throw setupFailure("Another ZCode runtime setup is running"); + await rm(lock, { recursive: true, force: true }); + } + throw setupFailure("Another ZCode runtime setup is running"); +} + +function processExists(pid: number): boolean { + try { + process.kill(pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === "EPERM"; + } +} + +const label = (component: ManagedComponent) => + component.id === "node" + ? `Node.js ${component.version}` + : `ZCode runtime ${component.version}`; diff --git a/server/runtime/pins.ts b/server/runtime/pins.ts new file mode 100644 index 0000000..45012b6 --- /dev/null +++ b/server/runtime/pins.ts @@ -0,0 +1,72 @@ +// Fixed downloads for the managed runtime (ADR 15). Clients can only ask the +// server to install these exact artifacts; they never supply URLs or versions. +export type ManagedPlatform = + | "darwin-arm64" + | "linux-x64" + | "linux-arm64" + | "win-x64" + | "win-arm64"; + +export interface PinnedArchive { + readonly url: string; + readonly sha256: string; + readonly size: number; +} + +export const MANAGED_NODE_VERSION = "24.21.0"; + +// Checksums come from nodejs.org SHASUMS256.txt, whose signature was verified +// against the nodejs/release-keys active keyring when the version was pinned. +const nodeArchive = (file: string, sha256: string, size: number) => ({ + url: `https://nodejs.org/dist/v${MANAGED_NODE_VERSION}/${file}`, + sha256, + size, +}); +export const MANAGED_NODE_ARCHIVES: Readonly< + Record +> = { + "darwin-arm64": nodeArchive( + `node-v${MANAGED_NODE_VERSION}-darwin-arm64.tar.gz`, + "bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057", + 52_909_993, + ), + "linux-x64": nodeArchive( + `node-v${MANAGED_NODE_VERSION}-linux-x64.tar.gz`, + "6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff", + 58_088_022, + ), + "linux-arm64": nodeArchive( + `node-v${MANAGED_NODE_VERSION}-linux-arm64.tar.gz`, + "724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5", + 57_824_078, + ), + "win-x64": nodeArchive( + `node-v${MANAGED_NODE_VERSION}-win-x64.zip`, + "158f7685b44de51f6c0df1d153526cbcd3e1bc739a8dfc607721cef75de9e541", + 37_618_919, + ), + "win-arm64": nodeArchive( + `node-v${MANAGED_NODE_VERSION}-win-arm64.zip`, + "8779b1bde1d39f8d420e3b57aa657b39891af434d3de44a919044cec06785921", + 33_679_608, + ), +}; + +// Published by .github/workflows/zcode-runtime-release.yml from the pinned +// unmodified source. The same archive serves every managed platform. +export const MANAGED_ZCODE_VERSION = "3.14.3"; +export const MANAGED_ZCODE_ARCHIVE: PinnedArchive = { + url: `https://github.com/supermomonga/paseo-plugin-zcode-provider/releases/download/zcode-runtime-v${MANAGED_ZCODE_VERSION}/zcode-runtime-${MANAGED_ZCODE_VERSION}.tar.gz`, + sha256: "a2af414592362d226f92c105d91211e5c4f138cf985b0c86da0eb9163cb9aee7", + size: 79_887_659, +}; + +export function managedPlatform( + platform: NodeJS.Platform = process.platform, + arch: string = process.arch, +): ManagedPlatform | undefined { + const key = `${platform === "win32" ? "win" : platform}-${arch}`; + return Object.hasOwn(MANAGED_NODE_ARCHIVES, key) + ? (key as ManagedPlatform) + : undefined; +} diff --git a/server/status.test.ts b/server/status.test.ts index dd4a7ce..5607390 100644 --- a/server/status.test.ts +++ b/server/status.test.ts @@ -22,6 +22,7 @@ const runtime: DiscoveredRuntime = { compatibility: "supported", compatibilityReason: "Minimum version met; runtime checked during use", writableInstallRoot: false, + source: "environment", }; it("reports explicit paths and hashes separately without claiming source equality", async () => { const smoke = vi.fn(); diff --git a/server/status.ts b/server/status.ts index 3ce4cbe..0e8b21b 100644 --- a/server/status.ts +++ b/server/status.ts @@ -31,7 +31,7 @@ function smokeResult(result: RuntimeSmokeResult) { }; } -// Read-only report for the Settings screen. Detection runs on demand; the +// Read-only report for the Diagnostics screen. Detection runs on demand; the // optional smoke check spawns the bundled CLI. Nothing here is persisted. export function createDiagnosticsHandler( dependencies: DiagnosticsDependencies = {}, @@ -54,6 +54,7 @@ export function createDiagnosticsHandler( return { status: "ready", providerVersion, + source: runtime.source, installRoot: runtime.paths.installRoot, nodeExecutable: runtime.paths.executable, nodeVersion: runtime.identity.nodeVersion, diff --git a/server/vendor/zcode/packages/shared/src/bots.ts b/server/vendor/zcode/packages/shared/src/bots.ts new file mode 100644 index 0000000..e7a585b --- /dev/null +++ b/server/vendor/zcode/packages/shared/src/bots.ts @@ -0,0 +1,558 @@ +/* oxlint-disable eslint(max-lines) -- Bot 共享合约集中维护 provider、状态和 schema,保持类型与校验就近。 */ +import { z } from "zod"; +import { modelSelectionSchema, type ModelSelection } from "./model-selection.js"; +import { ZCODE_AGENT_PROVIDER, ZCODE_AGENT_PROVIDER_LABEL } from "./zcode-agent-policy.js"; +import type { + ZCodeConfigOption, + ZCodeElicitationRequest, + ZCodeElicitationQuestion, + ZCodePermissionRequest, + ZCodePromptAttachment, + ZCodeProvider, + ZCodeStreamEvent, + ZCodeTaskMeta, + ZCodeTaskRuntimeStatus, +} from "./zcode-task-types-core.js"; +import { + zcodeInteractionRequestOriginSchema, + zcodePermissionResponseSchema, + type ZCodeInteractionRequestOrigin, + type ZCodePermissionResponse, +} from "./zcode-protocol-legacy-types.js"; +import type { Locale } from "./protocol.js"; + +export const botProviders = [ + "telegram", + "webhook", + "feishu", + "lark", + "weixin", + "discord", + "wecom", +] as const; + +export type BotProvider = (typeof botProviders)[number]; +export type FeishuBotProvider = Extract; + +/** + * 定时任务完成后的 Bot 回推目标。只保留未来仍稳定的会话地址;当前消息 id/context token + * 属于一次入站交互,不能持久化后复用。该字段由 Host 注入,模型工具参数不直接暴露。 + */ +export const zcodeAutomationBotDeliveryTargetSchema = z + .object({ + provider: z.enum(["feishu", "lark", "weixin"]), + botId: z.string().trim().min(1), + providerUserId: z.string().trim().min(1), + chatType: z.enum(["private", "group"]), + }) + .strict(); + +export type ZCodeAutomationBotDeliveryTarget = z.infer< + typeof zcodeAutomationBotDeliveryTargetSchema +>; + +export function isFeishuBotProvider(provider: BotProvider): provider is FeishuBotProvider { + return provider === "feishu" || provider === "lark"; +} +export type BotContextMode = "draft" | "task"; +export type BotReplyGranularity = + | "assistant_changes" + | "assistant_toolcalls_changes" + | "summary_changes" + | "streaming_card"; + +export const BOT_REPLY_GRANULARITIES = [ + "assistant_changes", + "assistant_toolcalls_changes", + "summary_changes", + "streaming_card", +] as const satisfies readonly BotReplyGranularity[]; + +export const ALL_BOT_WORKSPACES = "*"; +export const BOT_BIND_CODE_TTL_MS = 30_000; + +export interface BotWorkspaceRef { + id: string; + label: string; + workspacePath: string; + workspaceIdentity?: string; +} + +export interface BotAllowedCommands { + status: boolean; + new: boolean; + workspace: boolean; + model: boolean; + mode?: boolean; + thoughtLevel: boolean; + sandboxMode?: boolean; + approvalPolicy?: boolean; + reply: boolean; +} + +export type BotCommandPolicy = BotAllowedCommands; + +export interface BotCurrentOptions { + modelSelection?: ModelSelection; + mode?: string; + sandboxMode?: string; + approvalPolicy?: string; +} + +export type BotReplyMode = BotReplyGranularity; + +export interface BotConfig { + id: string; + name: string; + provider: BotProvider; + enabled: boolean; + credentialRef?: string; + webhookSecretRef?: string; + webhookUrl?: string; + webhookAuthHeaderName?: string; + feishuAppId?: string; + providerUserId?: string; + displayName?: string; + allowedWorkspaces: string[]; + allowedCommands: BotAllowedCommands; + currentOptions: BotCurrentOptions; + replyMode: BotReplyMode; +} + +export interface BotPendingPermissionOption { + requestId: string; + optionId: string; + command: "approve" | "deny"; + label: string; + response: ZCodePermissionResponse; + handledAt?: number; +} + +export interface BotPendingElicitation { + taskId: string; + requestId: string; + runId: string; + origin?: ZCodeInteractionRequestOrigin; + actorKey?: string; + currentQuestionIndex: number; + questions: ZCodeElicitationQuestion[]; + answers: Record; + renderContext?: { + kind: "plan_approval"; + plan: string; + }; + expandedCustomAnswerQuestionIndexes?: number[]; + handledAt?: number; +} + +export interface BotStructuredElicitationResponse { + requestId: string; + action: "accept" | "decline" | "cancel"; + content?: Record; +} + +export interface BotOutboundElicitationRequest { + requestId: string; + taskId: string; + runId: string; + currentQuestionIndex: number; + questions: ZCodeElicitationQuestion[]; + answers?: Record; + status?: "pending" | "completed" | "cancelled"; + expandedCustomAnswerQuestionIndexes?: number[]; + schema?: unknown; +} + +export interface BotDraftOptions { + provider: ZCodeProvider; + modelSelection?: ModelSelection; + mode?: string; +} + +export interface BotsConfigFile { + version: 3; + bots: BotConfig[]; +} + +export interface BotState { + botId: string; + workspacePath: string; + workspaceIdentity?: string; + workspaceId?: string; + mode: BotContextMode; + activeTaskId: string | null; + draftOptions?: BotDraftOptions; + pendingPermissionOptions?: BotPendingPermissionOption[]; + pendingElicitation?: BotPendingElicitation; + telegramOffset?: number; + weixinGetUpdatesBuf?: string; + weixinActivatedAt?: number; + updatedAt: number; +} + +export type BotContextState = BotState; + +export interface BotsStateFile { + version: 3; + bots: Record; +} + +export interface BotRuntimeInfo { + /** 最近一次消息投递错误;独立于长连接状态,成功投递后清除。 */ + deliveryError?: string; + botId: string; + provider: BotProvider; + status: "disabled" | "idle" | "polling" | "connected" | "error"; + messageId?: string; + message?: string; + lastUpdateAt?: number; + offset?: number; +} + +export interface BotActor { + provider: BotProvider; + botId: string; + providerUserId: string; + displayName?: string; + chatType: "private" | "group"; + chatId?: string; + providerMessageId?: string; + providerContextToken?: string; +} + +export type BotInboundAttachmentKind = "image" | "audio" | "video" | "file"; + +export interface BotInboundAttachment { + id: string; + kind: BotInboundAttachmentKind; + filename: string; + mimeType: string; + sizeBytes?: number; + providerFileId?: string; + downloadUrl?: string; + dataBase64?: string; + localPath?: string; + providerMetadata?: Record; +} + +export type BotCommand = + | { type: "bind"; code: string } + | { type: "help" } + | { type: "status" } + | { type: "new" } + | { type: "reconnect" } + | { type: "workspace.list" } + | { type: "workspace.set"; value: string } + | { type: "model.list" } + | { type: "model.provider.set"; value: string } + | { type: "model.set"; value: string } + | { type: "mode.list" } + | { type: "mode.set"; value: string } + | { type: "thoughtLevel.list" } + | { type: "thoughtLevel.set"; value: string } + | { type: "task.list" } + | { type: "task.set"; value: string } + | { type: "reply.list" } + | { type: "reply.set"; value: string } + | { type: "stop" } + | { type: "permission.respond"; value: string } + | { type: "elicitation.respond"; value: string } + | { type: "elicitation.submit" } + | { type: "approve"; requestId: string; optionId: string } + | { type: "deny"; requestId: string } + | { type: "unknown"; name: string; raw: string } + | { type: "selection.cancel" } + | { type: "message"; text: string }; + +export interface SelectionPrompt { + id: string; + token?: string; + title: string; + currentId?: string; + cancelLabel?: string; + showCancel?: boolean; + action: + | "workspace.set" + | "model.provider.set" + | "model.set" + | "mode.set" + | "thoughtLevel.set" + | "task.set" + | "reply.set" + | "permission.respond" + | "elicitation.respond"; + options: Array<{ + id: string; + label: string; + description?: string; + }>; +} + +export interface BotInboundMessage { + botId: string; + actor: BotActor; + text: string; + attachments?: BotInboundAttachment[]; + elicitationResponse?: BotStructuredElicitationResponse; + receivedAt?: number; +} + +export interface BotOutboundMessage { + botId: string; + provider: BotProvider; + providerUserId: string; + text: string; + locale?: Locale; + selection?: SelectionPrompt; + elicitation?: BotOutboundElicitationRequest; + providerContextToken?: string; +} + +export interface BotTaskSummary { + taskId: string; + title: string; + status: ZCodeTaskRuntimeStatus | "persisted-completed" | "persisted-error" | "unknown"; + workspacePath: string; + workspaceIdentity?: string; + provider?: ZCodeProvider; + model?: string; +} + +export const BOT_TASK_BROADCAST_CHANNEL = "bots:task"; +export const BOT_TASK_STREAM_BROADCAST_CHANNEL = "bots:task-stream"; + +export type BotTaskBroadcastEvent = + | "created" + | "prompt_sent" + | "resumed" + | "streaming" + | "permission_request" + | "permission_resolved" + | "elicitation_request" + | "elicitation_resolved" + | "updated" + | "completed" + | "error"; + +export interface BotTaskBroadcastPayload { + workspacePath: string; + workspaceIdentity?: string; + taskId: string; + event: BotTaskBroadcastEvent; + updatedAt: number; + task?: ZCodeTaskMeta; + provider?: ZCodeProvider; + configOptions?: ZCodeConfigOption[]; + prompt?: { + content: string; + attachments?: ZCodePromptAttachment[]; + messageId: string; + sentAt: number; + }; + permissionRequest?: ZCodePermissionRequest; + elicitationRequest?: ZCodeElicitationRequest; + requestId?: string; + error?: string; +} + +export interface BotTaskStreamBroadcastPayload { + workspacePath: string; + workspaceIdentity?: string; + taskId: string; + event: ZCodeStreamEvent; + updatedAt: number; +} + +export interface BotServiceStatus { + botsCount: number; + enabledBotsCount: number; + contextsCount: number; + botRuntime: BotRuntimeInfo[]; +} + +export interface BotProviderCallbackResult { + ok: boolean; + replies: BotOutboundMessage[]; + responseBody?: unknown; + status?: number; +} + +export const botAllowedCommandsSchema = z + .object({ + status: z.boolean(), + new: z.boolean(), + workspace: z.boolean(), + model: z.boolean(), + mode: z.boolean().optional(), + thoughtLevel: z.boolean(), + sandboxMode: z.boolean().optional(), + approvalPolicy: z.boolean().optional(), + // 兼容旧 bot-config.json;/cli 命令已移除,新配置不会再写入这个字段。 + cli: z.boolean().optional(), + reply: z.boolean(), + }) + .strict(); + +export const botCommandPolicySchema = botAllowedCommandsSchema; + +export const botCurrentOptionsSchema = z + .object({ + modelSelection: modelSelectionSchema.optional(), + mode: z.string().min(1).optional(), + sandboxMode: z.string().min(1).optional(), + approvalPolicy: z.string().min(1).optional(), + // 兼容旧 bot-config.json;CLI provider 现在统一由 ZCode Protocol 侧配置决定。 + cli: z.literal(ZCODE_AGENT_PROVIDER).optional(), + }) + .strict(); + +export const botDraftOptionsSchema = z + .object({ + provider: z.literal(ZCODE_AGENT_PROVIDER), + modelSelection: modelSelectionSchema.optional(), + mode: z.string().min(1).optional(), + }) + .strict(); + +const botElicitationOptionSchema = z + .object({ + value: z.string(), + label: z.string(), + description: z.string().optional(), + }) + .strict(); + +const botElicitationQuestionSchema = z + .object({ + question: z.string(), + header: z.string(), + options: z.array(botElicitationOptionSchema), + multiSelect: z.boolean().optional(), + }) + .strict(); + +const botPendingElicitationSchema = z + .object({ + taskId: z.string().min(1), + requestId: z.string().min(1), + runId: z.string().min(1), + origin: zcodeInteractionRequestOriginSchema.optional(), + actorKey: z.string().min(1).optional(), + currentQuestionIndex: z.number().int().min(0), + questions: z.array(botElicitationQuestionSchema), + answers: z.record(z.string(), z.array(z.string())), + renderContext: z + .object({ + kind: z.literal("plan_approval"), + plan: z.string().min(1), + }) + .strict() + .optional(), + expandedCustomAnswerQuestionIndexes: z.array(z.number().int().min(0)).optional(), + handledAt: z.number().optional(), + }) + .strict(); + +export const botConfigSchema = z + .object({ + id: z.string().min(1), + name: z.string(), + provider: z.enum(botProviders), + enabled: z.boolean(), + credentialRef: z.string().min(1).optional(), + webhookSecretRef: z.string().min(1).optional(), + webhookUrl: z.string().url().optional(), + webhookAuthHeaderName: z.string().min(1).optional(), + feishuAppId: z.string().min(1).optional(), + providerUserId: z.string().min(1).optional(), + displayName: z.string().optional(), + allowedWorkspaces: z.array(z.string().min(1)), + allowedCommands: botAllowedCommandsSchema, + currentOptions: botCurrentOptionsSchema, + replyMode: z.enum([ + "assistant_changes", + "assistant_toolcalls_changes", + "summary_changes", + "streaming_card", + ]), + }) + .strict(); + +export const botsConfigFileSchema = z + .object({ + version: z.literal(3), + bots: z.array(botConfigSchema), + }) + .strict(); + +export const botsStateFileSchema = z + .object({ + version: z.literal(3), + bots: z.record( + z.string(), + z.object({ + botId: z.string().min(1), + workspacePath: z.string().min(1), + workspaceIdentity: z.string().min(1).optional(), + workspaceId: z.string().min(1).optional(), + mode: z.enum(["draft", "task"]), + activeTaskId: z.string().min(1).nullable(), + draftOptions: botDraftOptionsSchema.optional(), + pendingPermissionOptions: z + .array( + z.object({ + requestId: z.string().min(1), + optionId: z.string().min(1), + command: z.enum(["approve", "deny"]), + label: z.string().min(1), + response: zcodePermissionResponseSchema, + handledAt: z.number().optional(), + }), + ) + .optional(), + pendingElicitation: botPendingElicitationSchema.optional(), + telegramOffset: z.number().optional(), + weixinGetUpdatesBuf: z.string().optional(), + weixinActivatedAt: z.number().optional(), + updatedAt: z.number(), + }), + ), + }) + .strict(); + +export const DEFAULT_BOT_COMMANDS: BotAllowedCommands = { + status: true, + new: true, + workspace: true, + model: true, + mode: true, + thoughtLevel: true, + reply: true, +}; + +export const DEFAULT_BOT_REPLY_GRANULARITY: BotReplyGranularity = "assistant_changes"; + +export function getSupportedBotReplyGranularities( + provider: BotProvider, +): readonly BotReplyGranularity[] { + return isFeishuBotProvider(provider) + ? (["streaming_card"] as const) + : BOT_REPLY_GRANULARITIES.filter( + // Bugfix: streaming card 依赖 Feishu/Lark Card JSON 2.0,其他 channel 无法渲染或更新该消息形态。 + (granularity) => granularity !== "streaming_card", + ); +} + +export function normalizeBotReplyGranularity( + provider: BotProvider, + replyMode: BotReplyGranularity | undefined, +): BotReplyGranularity { + const supported = getSupportedBotReplyGranularities(provider); + const candidate = replyMode ?? DEFAULT_BOT_REPLY_GRANULARITY; + return supported.includes(candidate) ? candidate : supported[0]!; +} + +export const BOT_ZCODE_PROVIDER_OPTIONS: Array<{ + id: ZCodeProvider; + label: string; +}> = [{ id: ZCODE_AGENT_PROVIDER, label: ZCODE_AGENT_PROVIDER_LABEL }]; diff --git a/server/vendor/zcode/packages/shared/src/command-types.ts b/server/vendor/zcode/packages/shared/src/command-types.ts new file mode 100644 index 0000000..09d66ec --- /dev/null +++ b/server/vendor/zcode/packages/shared/src/command-types.ts @@ -0,0 +1,96 @@ +// Command 相关类型定义 +import type { SettingsDirectoryLocation } from "./settings-source.js"; + +export type CommandSource = "user" | "plugin"; +export type CommandAgentSource = "zcodeAgent"; + +export interface CommandInfo { + name: string; + prompt: string; + content: string; + filePath: string; + description?: string; + argumentHint?: string; +} + +export interface UserCommand extends CommandInfo { + id: string; + source: "user"; + agentSource: CommandAgentSource; + location: SettingsDirectoryLocation; + enabled: boolean; + scope: "global" | "project"; + projectPath?: string; +} + +export interface PluginCommand extends Omit { + id: string; + source: "plugin"; + enabled: boolean; + pluginName: string; + pluginMarketplace: string; + pluginEnabled: boolean; + scope: "global"; + filePath: string; +} + +export type ZCodeCommand = UserCommand | PluginCommand; + +export function isUserCommand(command: ZCodeCommand): command is UserCommand { + return command.source === "user"; +} + +export function isPluginCommand(command: ZCodeCommand): command is PluginCommand { + return command.source === "plugin"; +} + +export interface CommandConfig { + name: string; + prompt: string; + description?: string; + argumentHint?: string; + filePath?: string; +} + +export type CommandStorageLevel = "user" | "project"; + +export interface CommandsCapability { + userScopeAvailable: boolean; + userScopeReason?: "desktop_only"; +} + +export interface CommandsListResult { + commands: ZCodeCommand[]; + userCommands: UserCommand[]; + pluginCommands: PluginCommand[]; + capability: CommandsCapability; +} + +export interface CommandCreateParams { + config: CommandConfig; + agentSource?: CommandAgentSource; + storageLevel?: CommandStorageLevel; + workspacePath?: string; +} + +export interface CommandUpdateParams { + commandId: string; + config: CommandConfig; + agentSource?: CommandAgentSource; + oldFilePath?: string; + storageLevel?: CommandStorageLevel; + workspacePath?: string; +} + +export interface CommandDeleteParams { + commandId: string; + filePath: string; + agentSource?: CommandAgentSource; +} + +export interface CommandSetEnabledParams { + commandId: string; + filePath: string; + enabled: boolean; + agentSource?: CommandAgentSource; +} diff --git a/server/vendor/zcode/packages/shared/src/settings-source.ts b/server/vendor/zcode/packages/shared/src/settings-source.ts new file mode 100644 index 0000000..6ff55fd --- /dev/null +++ b/server/vendor/zcode/packages/shared/src/settings-source.ts @@ -0,0 +1,10 @@ +export type SettingsDirectorySource = "zcode" | "agents" | "claude"; + +export type SettingsDirectoryScope = "user" | "project"; + +export interface SettingsDirectoryLocation { + source: SettingsDirectorySource; + scope: SettingsDirectoryScope; + directoryPath: string; + projectPath?: string; +} diff --git a/server/vendor/zcode/packages/shared/src/zcode-agent-policy.ts b/server/vendor/zcode/packages/shared/src/zcode-agent-policy.ts new file mode 100644 index 0000000..9a222d7 --- /dev/null +++ b/server/vendor/zcode/packages/shared/src/zcode-agent-policy.ts @@ -0,0 +1,25 @@ +import { z } from "zod"; +import type { CommandAgentSource } from "./command-types.js"; +import type { ZCodeProvider } from "./zcode-task-types-core.js"; + +export const ZCODE_AGENT_PROVIDER = "glm" satisfies ZCodeProvider; +export const ZCODE_AGENT_PROVIDER_LABEL = "ZCode Agent"; +export const ZCODE_COMMAND_AGENT_SOURCE = "zcodeAgent" satisfies CommandAgentSource; + +export const zcodeAgentProviderSchema = z.literal(ZCODE_AGENT_PROVIDER); + +export const ZCODE_COMMAND_AGENT_SOURCES = [ + ZCODE_COMMAND_AGENT_SOURCE, +] as const satisfies readonly CommandAgentSource[]; + +export function normalizeAgentProviderToZCodeAgent( + _provider?: ZCodeProvider | null, +): ZCodeProvider { + return ZCODE_AGENT_PROVIDER; +} + +export function isZCodeAgentProvider( + provider: ZCodeProvider | null | undefined, +): provider is typeof ZCODE_AGENT_PROVIDER { + return provider === ZCODE_AGENT_PROVIDER; +} diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.ts index 9702889..740d1df 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.ts @@ -6,6 +6,7 @@ import type { ConversationDelta } from "./delta.js"; import type { ConversationSnapshot } from "./snapshot.js"; import type { ConversationRow } from "./rows.js"; import type { StreamablePath } from "./core.js"; +import { applyWorkflowRunRemoved, applyWorkflowRunUpdated } from "./workflow-runs-delta.js"; /** * 仅供服务端在未发布的候选快照内批量归约使用。 @@ -118,6 +119,18 @@ export function applyConversationDelta( case "state.updated": // 键级整体替换:patch 中在场的键覆盖,绝不深合并。 return { ...snapshot, ...delta.patch }; + // workflowRuns 是唯一开了增量口子的状态键(delta.ts 的注释讲了为什么)。规则整份住在 + // workflow-runs-delta.ts:两个 twin 都只转调它,两边的语义因此没有走散的余地。 + case "workflowRun.updated": + return { + ...snapshot, + workflowRuns: applyWorkflowRunUpdated(snapshot.workflowRuns, delta), + }; + case "workflowRun.removed": + return { + ...snapshot, + workflowRuns: applyWorkflowRunRemoved(snapshot.workflowRuns, delta), + }; } } @@ -185,6 +198,14 @@ export function applyConversationDeltaMutable( case "state.updated": // 与不可变实现相同:patch 在场键整体替换,不能深合并。 Object.assign(snapshot, delta.patch); + return; + // 与不可变实现调同一个纯函数:workflowRuns 是状态键不是 rows 窗口,没有「原地追加」可优化, + // 而 accumulator.snapshot 本来就是候选快照自己的对象,赋一个新容器不会碰到已发布的快照。 + case "workflowRun.updated": + snapshot.workflowRuns = applyWorkflowRunUpdated(snapshot.workflowRuns, delta); + return; + case "workflowRun.removed": + snapshot.workflowRuns = applyWorkflowRunRemoved(snapshot.workflowRuns, delta); } } diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/command.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/command.ts index 5730428..cdd6d95 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/command.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/command.ts @@ -9,6 +9,7 @@ import { v4ConversationFileRewindPreviewResultSchema } from "./transport.js"; import { modelSelectionSchema } from "../model-selection.js"; import { modelExecutionSchema } from "../model-execution.js"; import { submissionModeSchema } from "./submission.js"; +import { zcodeAutomationBotDeliveryTargetSchema } from "../bots.js"; import { amendWorkflowRunSettingsPayloadSchema, amendWorkflowRunSettingsResultSchema, @@ -103,6 +104,8 @@ export const commandPayloadSchemas = { automationId: z.string().min(1).optional(), offPeakTaskId: z.string().min(1).optional(), offPeakRunType: z.enum(["init", "resume"]).optional(), + // Bot 来源只由 Host 注入,用于 CronCreate 在当前 turn 内读取并持久化回推地址。 + botDeliveryTarget: zcodeAutomationBotDeliveryTargetSchema.optional(), // 定时任务会话的后续用户输入也必须保持 turn-scoped 工具面隔离;不能借用 // automationId,否则会把普通用户输入误标成一次 automation 派发。 toolDisallowlist: z.array(z.string().min(1)).optional(), diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/delta.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/delta.ts index b93e9e1..29ceb49 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/delta.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/delta.ts @@ -1,6 +1,11 @@ -// ConversationDelta:五个操作,封闭集合。 +// ConversationDelta:七个操作,封闭集合。 // 没有 row.inserted(中间插入)、没有 row.moved、没有字段级 JSON patch—— // 凡此模型表达不了的结构变化,服务端一律发 snapshot resync,刻意压缩客户端错误面。 +// +// 唯一的例外是最后两条 `workflowRun.*`:`workflowRuns` 是一个高频状态键,键级整体替换让 +// 每条引擎事件都要重发整张表(O(N) 字节/事件、O(N²)/run)。它们**只**给这一个键开了一道 +// 按 (runId, siteId, ordinal) 的增量口子,语义仍是「键内整体替换,只是下探了两级」: +// header 键整键替换、条目整条替换,没有任何字段级深合并。规则在 workflow-runs-delta.ts。 import { z } from "zod"; import { streamablePathSchema } from "./core.js"; import { conversationRowSchema } from "./rows.js"; @@ -22,7 +27,13 @@ import { subagentProjectionStateSchema, workspaceHookAdmissionStateSchema, } from "./snapshot.js"; -import { workflowRunsStateSchema } from "./workflow-runs.js"; +import { + WORKFLOW_RUNS_LIMITS, + workflowRunActorSchema, + workflowRunNodeSchema, + workflowRunSchema, + workflowRunsStateSchema, +} from "./workflow-runs.js"; // StatePatch:键级整体替换(Object.assign),键集合封闭。键内绝不深合并。 export const statePatchSchema = z.object({ @@ -50,6 +61,36 @@ export const statePatchSchema = z.object({ }); export type StatePatch = z.infer; +/** + * run 的 **header** = `workflowRunSchema` 减去 actors / nodes 两张按实例增量同步的表。 + * + * 使用 `.omit` 从同一 schema 派生,避免独立维护的字段表不一致导致订阅解析失败。小集合(reports / artifacts / phases / pendingQuestions…)留在 header 里整键替换—— + * 它们的上界都是几十条,为它们再开一套增量语法只会多一套能写错的东西。 + */ +export const workflowRunHeaderSchema = workflowRunSchema.omit({ actors: true, nodes: true }); +export type WorkflowRunHeader = z.infer; + +/** header 的部分更新:在场的键整键替换,缺席的键保持不动(绝不深合并)。 */ +export const workflowRunHeaderPatchSchema = workflowRunHeaderSchema.partial(); +export type WorkflowRunHeaderPatch = z.infer; + +/** 变成**缺席**的 header 键。「零条 ⇒ 键缺席」是 reports / pendingQuestions 等键的协议约定,所以增量必须说得出它。 */ +export const workflowRunHeaderKeySchema = workflowRunHeaderSchema.keyof(); +export type WorkflowRunHeaderKey = z.infer; + +/** + * 一条被淘汰条目的**身份**(两张表共用的去重键)。从 actor schema 上 `.pick` 而不是手写 + * 两个字段:这两个字段的界只该有一处定义,理由与 `workflowRunHeaderSchema` 的 `.omit` 逐字相同。 + * + * 刻意**只有身份**:淘汰要说的全部内容就是「这条走了」,带上条目本身只会让消费者以为这是一次 + * upsert。 + */ +export const workflowRunEntryRefSchema = workflowRunActorSchema.pick({ + siteId: true, + ordinal: true, +}); +export type WorkflowRunEntryRef = z.infer; + export const conversationDeltaSchema = z.discriminatedUnion("op", [ // 追加到尾部(99%)。 z.object({ op: z.literal("row.appended"), row: conversationRowSchema }), @@ -65,5 +106,42 @@ export const conversationDeltaSchema = z.discriminatedUnion("op", [ append: z.string(), }), z.object({ op: z.literal("state.updated"), patch: statePatchSchema }), + /** + * 一条 dwf run 的键级增量。`revision` 是**这次变化之后**的 `workflowRuns.revision`(绝对值); + * 一条引擎事件最多产生一条本 op(节点相位、派生的 actor 状态、用量、水位一起落地,原子)。 + * + * 六个载荷各有各的语义:`run` 按键整体替换、`cleared` 说哪些键变成了缺席、 + * `removedActors` / `removedNodes` 按 (siteId, ordinal) 删条目、`actors` / `nodes` 按同一个键 + * 整条 upsert。四张表的界与状态键同值——增量不该能拼出一个非法的状态。 + * + * **施加序是 header → 删除 → upsert**,写在这里也写在字段序上:同一个键在一条 op 里被删又被加 + * (溢出过的 run 在 resume 时清表重开,或一个条目被淘汰后又回来)必须落在表尾,才与顺序施加 + * 两条 op 的结果一致。 + */ + z.object({ + op: z.literal("workflowRun.updated"), + runId: workflowRunSchema.shape.runId, + revision: workflowRunsStateSchema.shape.revision, + run: workflowRunHeaderPatchSchema.optional(), + cleared: z + .array(workflowRunHeaderKeySchema) + .max(workflowRunHeaderKeySchema.options.length) + .optional(), + removedActors: z + .array(workflowRunEntryRefSchema) + .max(WORKFLOW_RUNS_LIMITS.maxActors) + .optional(), + removedNodes: z.array(workflowRunEntryRefSchema).max(WORKFLOW_RUNS_LIMITS.maxNodes).optional(), + actors: z.array(workflowRunActorSchema).max(WORKFLOW_RUNS_LIMITS.maxActors).optional(), + nodes: z.array(workflowRunNodeSchema).max(WORKFLOW_RUNS_LIMITS.maxNodes).optional(), + }), + /** 这条 run 被生产者淘汰了(只有生产者淘汰,而且必须说出来——客户端永远不自行施加上界)。 */ + z.object({ + op: z.literal("workflowRun.removed"), + runId: workflowRunSchema.shape.runId, + revision: workflowRunsStateSchema.shape.revision, + }), ]); export type ConversationDelta = z.infer; +export type WorkflowRunUpdatedDelta = Extract; +export type WorkflowRunRemovedDelta = Extract; diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts index efcb4b9..d1753ef 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts @@ -200,7 +200,9 @@ export const toolCallRowSchema = z.object({ input: z.unknown().optional(), cuaApp: cuaAppIdentitySchema.optional(), output: toolOutputSchema.optional(), - display: toolCallDisplaySchema.optional(), + // display 解析失败只丢这张卡的载荷,不拒整条 row(理由见 toolDisplay.ts 的 toolOutputSchema + // 注释:装饰载荷不得决定 row/帧/订阅的生死)。 + display: toolCallDisplaySchema.optional().catch(undefined), // status=error 时必带。 error: z.object({ code: z.string(), message: z.string() }).optional(), // 仅 replayable 档运行中出现,终态清除。 diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts index cdef58b..099b66c 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts @@ -244,7 +244,8 @@ export const permissionRequestPayloadSchema = z.object({ freeText: z.boolean().optional(), origin: zcodeInteractionRequestOriginSchema.optional(), // 工具自报的确认预览,复用 row 的 display 投影(同一有界形状)。缺省 = 纯文本 ask。 - display: toolCallDisplaySchema.optional(), + // 同样不设门:预览解析失败退化成纯文本 ask,不拒整份 snapshot(见 toolDisplay.ts 注释)。 + display: toolCallDisplaySchema.optional().catch(undefined), // 独立 additive 能力:旧 UI 忽略此字段,仍只显示原 options,不出现半实现授权入口。 fullAccessOption: permissionOptionSchema .extend({ diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/toolDisplay.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/toolDisplay.ts index de1074a..b7e971a 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/toolDisplay.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/toolDisplay.ts @@ -151,9 +151,10 @@ const toolResultDisplaySchema = z.discriminatedUnion("kind", [ export type ToolResultDisplay = z.infer; // toolCall。终态 output 全档统一 head+tail 截断,超出走 truncated.ref 按需拉。 +// display 是展示载荷;版本不兼容时降级为无卡片,避免同一内容导致整条订阅反复恢复失败。 export const toolOutputSchema = z.object({ text: z.string(), - display: toolResultDisplaySchema.optional(), + display: toolResultDisplaySchema.optional().catch(undefined), truncated: z .object({ totalBytes: z.number(), diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts index 28f8ec3..4d1d53b 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts @@ -29,6 +29,12 @@ export const hostCapabilitiesSchema = z.object({ // Wire-compatible:旧 Host 缺失等价于 false;调用方必须用 === true 判断。 workspaceHookReview: z.boolean().optional(), independentPlanState: z.boolean().optional(), + /** + * 本 Host 会发 `workflowRun.*` 键级增量(delta.ts 的两条 op),因而 `workflowRuns` 的 + * actors / nodes 可以到 1024 而不是旧界的 256。没有这个位的消费者收到的仍是整键 + * `state.updated`,并且先经 `clampWorkflowRunsForLegacy` 裁到旧界。 + */ + workflowRunDeltas: z.boolean().optional(), }); export type HostCapabilities = z.infer; @@ -67,7 +73,18 @@ export const clientHelloSchema = z clientKind: z.enum(["desktop", "web", "mobileRemote", "mobileApp"]).optional(), appVersion: z.string(), // 缺失代表旧客户端,不具备 Settings-centered review UI。 - capabilities: z.object({ workspaceHookReviewUi: z.boolean().optional() }).strict().optional(), + capabilities: z + .object({ + workspaceHookReviewUi: z.boolean().optional(), + /** + * 本客户端认得 `workflowRun.*` 增量。⚠ 声明规则是**单向**的:客户端只有在 Host 的 + * hello 里见到 `workflowRunDeltas === true` 时才能带上这个键——这个 capabilities 对象 + * 是 `.strict()` 的,老 Host 见到不认识的键会整条 clientHello 解析失败、连接握不上手。 + */ + workflowRunDeltas: z.boolean().optional(), + }) + .strict() + .optional(), }) .strict(); export type ClientHello = z.infer; @@ -80,7 +97,15 @@ export function clientSupportsWorkspaceHookReview(clientHello: ClientHello): boo return clientHello.capabilities?.workspaceHookReviewUi === true; } -// ── 订阅 ── +export function hostSupportsWorkflowRunDeltas(capabilities: HostCapabilities): boolean { + return capabilities.workflowRunDeltas === true; +} + +export function clientSupportsWorkflowRunDeltas(clientHello: ClientHello): boolean { + return clientHello.capabilities?.workflowRunDeltas === true; +} + +// ── §3.1 订阅 ── export const subscribeParamsSchema = z .object({ // "conversation/" | "sessions-index/" | ... @@ -403,6 +428,12 @@ export const v4ConversationSubscribeParamsSchema = subscribeParamsSchema.extend( legacyTaskIds: z.array(z.string().min(1)).max(MAX_LEGACY_TASK_IDS_PER_SUBSCRIBE).optional(), // 仅供 host→CLI cold resume 使用;live conversation 不消费该 hint。 resumeThoughtLevel: z.string().trim().min(1).optional(), + /** + * 这条订阅收不收 `workflowRun.*` 键级增量。与 `clientMode` 同族:由**可信 host** 从该连接的 + * clientHello 注入,面向 UI 的 subscribe 选不了它——一个客户端能不能认得增量是连接的事实, + * 不是某一次订阅可以自选的口味。缺席 = 按旧消费者处理(整键 patch + 旧界裁剪)。 + */ + workflowRunDeltas: z.boolean().optional(), }); export type V4ConversationSubscribeParams = z.infer; diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-assembler.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-assembler.ts index c10c9a1..cdca361 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-assembler.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-assembler.ts @@ -6,6 +6,7 @@ import { PROTOCOL_V4_LIMITS } from "./core.js"; import { crc32WireBytes, decodeWireBase64 } from "./wire-binary.js"; import { measureTopicNotificationEnvelopeBytes } from "./wire-codec.js"; import type { TopicFrameDeliveryKind, TopicWireFrameCandidate } from "./wire.js"; +import { WIRE_FAULT_INVALID_PAYLOAD } from "./wire-fault.js"; export interface TopicWireAssemblyFault { /** 缺失/伪值本身也必须成为 owned typed fault,此时不能伪造用途。 */ @@ -289,7 +290,7 @@ export class TopicWireFrameAssembler { const parsed = this.frameSchema.safeParse(wire.frame); if (!parsed.success) { this.settle(key, wire); - events.push(this.fault(wire, "proto.frameAssemblyInvalidPayload")); + events.push(this.fault(wire, WIRE_FAULT_INVALID_PAYLOAD)); return events; } this.settle(key, wire); @@ -460,7 +461,7 @@ export class TopicWireFrameAssembler { const parsed = this.frameSchema.safeParse(value); if (!parsed.success) { this.settle(key, assembly); - events.push(this.fault(assembly, "proto.frameAssemblyInvalidPayload")); + events.push(this.fault(assembly, WIRE_FAULT_INVALID_PAYLOAD)); return events; } this.settle(key, assembly); diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-fault.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-fault.ts new file mode 100644 index 0000000..a843eff --- /dev/null +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-fault.ts @@ -0,0 +1,39 @@ +// V4 physical assembly fault 的分类:**内容确定性失败** vs 瞬态失败。 +// +// 恢复阶梯默认把 fault 当瞬态处理:先 same-sub resync(服务端可能回 resume),再断档则升级 +// forceSnapshot,仍不成则 fail closed。这套升级对丢片、超时、校验和不符是对的——重投一次很可能 +// 就好了。对 **schema 拒收** 却是错的:字节已经过了 length/checksum/UTF-8/JSON 四道关,被拒说明 +// 本端读不懂对端发来的**内容**,而 resume 档只会把同一批 delta 再投一遍,必然同样被拒。 +// +// 工具卡载荷出现不兼容字段时,重投相同内容无法恢复;应尝试快照后明确报告内容不兼容。 +// +// 本模块只回答「这个 reason code 是不是确定性内容失败」,不决定怎么处置——处置在两个 store 里 +// (conversationProjectionStore / sessionsIndexStore)。 + +/** + * 帧内容通过了 checksum/JSON,却没过 zod schema 的 reason code。 + * + * 常量化而不是各处写字面量:判定这一侧与产出这一侧(wire-assembler、wire-reassembly)必须永远 + * 是同一个词——两处分叉的症状正是本模块要修的那类静默失配。 + */ +export const WIRE_FAULT_INVALID_PAYLOAD = "proto.frameAssemblyInvalidPayload"; + +/** + * 这个 fault 是不是「同一份内容再投一次必然再被拒」的确定性失败。 + * + * 目前只有 schema 拒收一个。刻意**不**把 `proto.frameAssemblyInvalidJson` 也算进来:JSON 不合法 + * 也可能来自组装路径本身(分片拼接、编码边界),重投确实可能不同;把瞬态误判成确定性会让本该 + * 自愈的 gap 停在原地,那是比多一次无用重试更坏的失败。按证据逐个加,不按猜测扩大。 + */ +export function isDeterministicContentFault(reasonCode: string | undefined): boolean { + return reasonCode === WIRE_FAULT_INVALID_PAYLOAD; +} + +/** + * 内容确定性失败走到底的客户端终态 code(`fault.subscription.*` 是 04-sync 的词表)。 + * + * 与 `fault.subscription.recoveryFailed` 分开是有用的区分,不是命名洁癖:后者是「链路没恢复 + * 过来」,重连有意义;本 code 是「本端读不懂对端发来的内容」,重连必然得到同样结果。遥测按 + * code 聚合,两者混在一起会把一次版本失配读成一片网络抖动。 + */ +export const SUBSCRIPTION_CONTENT_REJECTED = "fault.subscription.contentRejected"; diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-row-meta.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-row-meta.ts index b04cf17..01d45a8 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-row-meta.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-row-meta.ts @@ -104,7 +104,11 @@ const workflowSubagentModelTextSchema = z // 这一块说**改了什么**:只有改动过的设置在场;每一项的 from / to 缺一端即那一端是默认 // (模型 = 会话模型,上限 = 本机上限)。`ceiling` 是本机上限,供「13 → 4」这种读法。 export const workflowSettingsAmendMetaSchema = z.object({ - predecessorRunId: z.string().min(1).max(128), + // 修订自哪个 run。**缺席 = 就地生效**:只改并发上限、run + // 又在飞时,那次「配置」不停这次 run、也不另起一次,于是没有前驱可指——`runId` 指的就是被调整的 + // 那一个。渲染端据此只出那一行、不再出卡(同一条 run 画两张卡会读成两次运行)。 + // 此字段为可选;生产者和消费者需使用一致的 schema 才能解析就地调整的设置记录。 + predecessorRunId: z.string().min(1).max(128).optional(), subagentModel: z .object({ from: workflowSubagentModelTextSchema.optional(), @@ -148,7 +152,8 @@ export const workflowLaunchMetaSchema = z.object({ description: z.string().max(500).optional(), // 启动前编译得到的 create_workflow display(有界因果图 + 诊断):run 详情侧板按 toolCallId 找 // 「发起行」取图,直接启动没有工具行,图从这里取。与工具行 display 同一 schema。 - display: toolCallCreateWorkflowDisplaySchema.optional(), + // 同样不设门:图解析失败只是这一行没有图,不拒整帧(见 toolDisplay.ts 注释)。 + display: toolCallCreateWorkflowDisplaySchema.optional().catch(undefined), // 本次 run 实际执行的脚本原文(侧板 Script 区),对应工具行的 input.script;上界与 contracts // WORKFLOW_LAUNCH_SCRIPT_MAX_CHARS 同值。 script: z.string().max(256_000).optional(), diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs-delta.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs-delta.ts new file mode 100644 index 0000000..8e1d764 --- /dev/null +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs-delta.ts @@ -0,0 +1,517 @@ +// ============================================================ +// workflowRuns 的键级增量:diff(生产侧)、apply(消费侧)与规范键序 +// ============================================================ +// 为什么存在:`workflowRuns` 是一个**高频**状态键,而 `state.updated` 的语义是键级整体替换。 +// 一条引擎事件只改一个节点,却要把整张表重发一遍——每事件 O(N) 字节、一条 run 全程 O(N²)。 +// 节点/子代理被压在 256 上、宽 fan-out 一撞界就静默丢实例,根子都在这里。本模块把「这一步 +// 改了什么」算出来,让线上的字节数与**改动量**成正比,而不是与状态大小成正比。 +// +// 三条结构性事实,读下面的代码前先知道,否则几处会像兜底: +// 1. reducer 只在表满时**淘汰**终态条目,绝不重排(workflow-runs-eviction.ts)。所以 diff 的 +// 快路径仍然是按下标对齐比较,只在对不齐时才退到键化路径算出「哪些走了」;真遇到重排 +// 它认不出来,只能整键重发(见 RESYNC)。 +// 2. reducer 只给**变化的那条 run** 造新对象,其余 run 与未改动的条目保持引用不变。所以 +// diff 的第一道闸是引用比较,深比较只发生在真正动过的那条 run 上。 +// 3. 正确性绝不依赖引用:引用相等只是快路径,不等时一律退回结构比较。 +// +// 契约:对任意一对 reducer 产出的 (prior, next), +// `JSON.stringify(applyAll(带 prior 的快照, diff(prior, next)).workflowRuns) === JSON.stringify(next)` +// ——**逐字节**,不只是深相等。键序因此是本模块的一等公民,见 {@link canonicalWorkflowRun}。 + +import type { + ConversationDelta, + WorkflowRunEntryRef, + WorkflowRunHeaderKey, + WorkflowRunRemovedDelta, + WorkflowRunUpdatedDelta, +} from "./delta.js"; +import { + WORKFLOW_RUNS_LIMITS, + workflowRunSchema, + type WorkflowRunActor, + type WorkflowRunNode, + type WorkflowRunState, + type WorkflowRunsState, +} from "./workflow-runs.js"; + +/** + * run 对象的**规范键序** = `workflowRunSchema` 的声明序。 + * + * 逐字节一致里唯一不靠「值相等」保证的一环就是键序:reducer 用 `{...run, 新键: v}` 推进状态, + * 新出现的可选键(reports / phases / concurrency…)因此按**到达顺序**缀在对象尾部,而 apply + * 重建 run 时没有那段历史。两边各自按这张表重排一次,序就对齐了——这也是为什么 reducer 的 + * 出口同样要走一遍本函数(那是一处,不是两处)。 + * + * 键序从 schema 派生,避免独立维护字段表导致生产者和消费者使用不同的 run 结构。 + */ +const WORKFLOW_RUN_KEYS = Object.keys(workflowRunSchema.shape) as (keyof WorkflowRunState)[]; +const WORKFLOW_RUN_KEY_SET: ReadonlySet = new Set(WORKFLOW_RUN_KEYS); + +/** header = run 减去两张按 (siteId, ordinal) 增量同步的表。顺序仍是 schema 声明序。 */ +export const WORKFLOW_RUN_HEADER_KEYS: readonly WorkflowRunHeaderKey[] = WORKFLOW_RUN_KEYS.filter( + (key): key is WorkflowRunHeaderKey => key !== "actors" && key !== "nodes", +); + +/** + * header 里的**必填**键,同样从 schema 派生(`safeParse(undefined)` 通过 = 可缺省)。 + * 它只用在一处:判一条 `workflowRun.updated` 的 header 够不够格让一条未知 run **出生**。 + */ +const runShape = workflowRunSchema.shape as unknown as Record< + string, + { safeParse: (value: unknown) => { success: boolean } } +>; +const WORKFLOW_RUN_REQUIRED_HEADER_KEYS: readonly WorkflowRunHeaderKey[] = + WORKFLOW_RUN_HEADER_KEYS.filter((key) => !runShape[key]!.safeParse(undefined).success); + +/** 两张实例表的去重键。`\0` 分隔的理由与 reducer 的派生 actor 状态逐字相同:("a",12) 与 ("a1",2) 不能撞车。 */ +export function workflowRunEntryKey(entry: { siteId: string; ordinal: number }): string { + return `${entry.siteId}\0${entry.ordinal}`; +} + +/** + * 按规范键序重建一个 run 对象(浅重建:嵌套值原样搬运引用,它们本来就来自同一份事实)。 + * + * `undefined` 值的键按缺席处理,与 `JSON.stringify` 的语义对齐——协议线上只有「键在场」与 + * 「键缺席」两态,没有第三态。schema 之外的键按原序缀在尾部:本模块没有资格替调用方丢数据。 + */ +export function canonicalWorkflowRun(run: WorkflowRunState): WorkflowRunState { + const source = run as unknown as Record; + const canonical: Record = {}; + for (const key of WORKFLOW_RUN_KEYS) { + const value = source[key]; + if (value !== undefined) canonical[key] = value; + } + for (const key of Object.keys(source)) { + if (WORKFLOW_RUN_KEY_SET.has(key)) continue; + const value = source[key]; + if (value !== undefined) canonical[key] = value; + } + return canonical as unknown as WorkflowRunState; +} + +/** + * JSON 值的结构相等。reducer 的幂等判据(原来是整条 run 的 `JSON.stringify` 比对,每事件 + * O(N) 字节)与 diff 的「这个键/条目变了吗」共用这一份,两处判据不会再各说各话。 + * + * 与 `JSON.stringify` 的差别只有两处,两处都是**更**准确:键序不参与判定;`undefined` 值的键 + * 与缺席等同(stringify 也会丢掉它们)。 + */ +export function jsonValueEqual(a: unknown, b: unknown): boolean { + if (a === b) return true; + if (Array.isArray(a) || Array.isArray(b)) { + if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false; + return a.every((item, index) => jsonValueEqual(item, b[index])); + } + if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false; + const left = a as Record; + const right = b as Record; + let present = 0; + for (const key of Object.keys(left)) { + const value = left[key]; + if (value === undefined) continue; + present += 1; + if (!jsonValueEqual(value, right[key])) return false; + } + let expected = 0; + for (const key of Object.keys(right)) if (right[key] !== undefined) expected += 1; + return present === expected; +} + +/** reducer 的幂等判据:同一条事件重放后内容无变化即不产 delta、不抬 revision。 */ +export function workflowRunUnchanged(previous: WorkflowRunState, next: WorkflowRunState): boolean { + return jsonValueEqual(previous, next); +} + +/** + * 一条 header 够不够格让**未知 run 出生**:必填键一个不缺。 + * + * 只有 diff 的「诞生」分支会造出完整 header——已有 run 的增量里 `runId` 永远不变、因此永远不在 + * patch 里,于是若干条增量合并(coalesce 规则 6)也**拼不出**一条完整 header。这条不变量是 + * 合并规则得以成立的支点:合并不会把两条对未知 run 的 no-op 变成一次凭空出生。 + */ +export function isCompleteWorkflowRunHeader(header: unknown): boolean { + if (typeof header !== "object" || header === null) return false; + const record = header as Record; + return WORKFLOW_RUN_REQUIRED_HEADER_KEYS.every((key) => record[key] !== undefined); +} + +/** + * 两个 workflowRuns 状态之间的键级增量。 + * + * 退路只有一条:认不出的结构变化(条目被删或被重排,见文件头第 1 条)或「没有任何 op 却 + * revision 动了」时,整键重发一条 `state.updated`。它在协议上完全合法(键级整体替换), + * 在 coalesce 里是一道屏障,代价只是退回改造前的字节数。 + */ +export function diffWorkflowRunsState( + prior: WorkflowRunsState | undefined, + next: WorkflowRunsState, +): ConversationDelta[] { + const priorRuns = prior?.runs ?? []; + const nextIds = new Set(next.runs.map((run) => run.runId)); + const ops: ConversationDelta[] = []; + // 淘汰先发、按 prior 序:客户端先把走了的 run 摘掉,剩下的增量都作用在活着的表上。 + for (const run of priorRuns) { + if (nextIds.has(run.runId)) continue; + ops.push({ op: "workflowRun.removed", runId: run.runId, revision: next.revision }); + } + const priorById = new Map(priorRuns.map((run) => [run.runId, run])); + for (const run of next.runs) { + const before = priorById.get(run.runId); + if (before === run) continue; + const op = diffWorkflowRun(before, run, next.revision); + if (op === null) return [{ op: "state.updated", patch: { workflowRuns: next } }]; + if (op !== undefined) ops.push(op); + } + // 一条 op 都没有却 revision 变了:容器版本没有自己的载体,只能整键重发。 + // reducer 不产生这种输入(无变化时它返回 null),所以这条在生产上不会走到。 + if (ops.length === 0 && (prior?.revision ?? -1) !== next.revision) { + return [{ op: "state.updated", patch: { workflowRuns: next } }]; + } + return ops; +} + +/** 单条 run 的增量:`undefined` = 无变化,`null` = 认不出的结构变化(整键重发)。 */ +function diffWorkflowRun( + before: WorkflowRunState | undefined, + run: WorkflowRunState, + revision: number, +): WorkflowRunUpdatedDelta | undefined | null { + const source = run as unknown as Record; + // key 是 header 键的联合,逐键写回时 TS 会把值收窄成 never;这里按记录装配、出口处再定型。 + const patch: Record = {}; + const cleared: WorkflowRunHeaderKey[] = []; + if (before === undefined) { + // 诞生:整条 header(含 runId,客户端据它判断这条 op 够不够格建表)+ 全部条目。 + for (const key of WORKFLOW_RUN_HEADER_KEYS) { + const value = source[key]; + if (value !== undefined) patch[key] = value; + } + return { + op: "workflowRun.updated", + runId: run.runId, + revision, + run: patch as WorkflowRunUpdatedDelta["run"], + ...(run.actors.length > 0 ? { actors: [...run.actors] } : {}), + ...(run.nodes.length > 0 ? { nodes: [...run.nodes] } : {}), + }; + } + const previous = before as unknown as Record; + for (const key of WORKFLOW_RUN_HEADER_KEYS) { + const left = previous[key]; + const right = source[key]; + if (left === right) continue; + if (right === undefined) { + cleared.push(key); + continue; + } + if (left !== undefined && jsonValueEqual(left, right)) continue; + patch[key] = right; + } + const actors = diffWorkflowRunEntries(before.actors, run.actors); + const nodes = diffWorkflowRunEntries(before.nodes, run.nodes); + if (actors === null || nodes === null) return null; + const changedHeader = Object.keys(patch).length > 0 || cleared.length > 0; + if (!changedHeader && actors === undefined && nodes === undefined) return undefined; + // 键序 = 施加序(header → 删除 → upsert):同一个键被删又被加时它落在表尾,与顺序施加 + // 两条 op 一致。 + return { + op: "workflowRun.updated", + runId: run.runId, + revision, + ...(Object.keys(patch).length > 0 ? { run: patch as WorkflowRunUpdatedDelta["run"] } : {}), + ...(cleared.length > 0 ? { cleared } : {}), + ...(actors?.removed.length ? { removedActors: actors.removed } : {}), + ...(nodes?.removed.length ? { removedNodes: nodes.removed } : {}), + ...(actors?.changed.length ? { actors: actors.changed } : {}), + ...(nodes?.changed.length ? { nodes: nodes.changed } : {}), + }; +} + +/** 一张实例表这一步的变化:走掉的条目(只带身份)+ 变了的条目(整条,按 next 的顺序)。 */ +interface EntryDiff { + removed: WorkflowRunEntryRef[]; + changed: T[]; +} + +/** + * 两张实例表之间的变化。`undefined` = 无变化,`null` = 认不出的结构变化(整键重发)。 + * + * 快路径按**下标对齐**比较:reducer 的常态是追加与原地更新,这条路径上未改动的条目只做一次 + * 指针比较。第一次对不齐(下标处身份不同,或 prior 比 next 长)说明有条目走了——那是腾位 + * (workflow-runs-eviction.ts),于是退到键化路径把「哪些走了」算出来。 + * + * 键化路径仍然要求**幸存者按下标对齐**:删除之外的顺序变化这个模型表达不了(协议里没有 + * 条目移动语法),只能整键重发。 + */ +function diffWorkflowRunEntries( + before: readonly T[], + after: readonly T[], +): EntryDiff | undefined | null { + if (before === after) return undefined; + if (before.length <= after.length) { + const changed: T[] = []; + let aligned = true; + for (let index = 0; index < after.length && aligned; index += 1) { + const entry = after[index]!; + const previous = before[index]; + if (previous === undefined) { + changed.push(entry); + continue; + } + if (previous === entry) continue; + if (previous.siteId !== entry.siteId || previous.ordinal !== entry.ordinal) aligned = false; + else if (!jsonValueEqual(previous, entry)) changed.push(entry); + } + if (aligned) return changed.length > 0 ? { removed: [], changed } : undefined; + } + return diffWorkflowRunEntriesByKey(before, after); +} + +function diffWorkflowRunEntriesByKey( + before: readonly T[], + after: readonly T[], +): EntryDiff | undefined | null { + const survives = new Set(after.map(workflowRunEntryKey)); + const removed: WorkflowRunEntryRef[] = []; + const survivors: T[] = []; + for (const entry of before) { + if (survives.has(workflowRunEntryKey(entry))) survivors.push(entry); + else removed.push({ siteId: entry.siteId, ordinal: entry.ordinal }); + } + if (survivors.length > after.length) return null; + const changed: T[] = []; + for (let index = 0; index < after.length; index += 1) { + const entry = after[index]!; + const previous = survivors[index]; + if (previous === undefined) { + changed.push(entry); + continue; + } + // 幸存者必须仍按原序坐在 next 的前缀上,否则就是重排——退回整键重发。 + if (previous.siteId !== entry.siteId || previous.ordinal !== entry.ordinal) return null; + if (previous === entry || jsonValueEqual(previous, entry)) continue; + changed.push(entry); + } + if (removed.length === 0 && changed.length === 0) return undefined; + return { removed, changed }; +} + +/** + * `workflowRun.updated` 的应用。 + * + * 容器 revision 取 **max**:coalesce 允许把靠后的 op 合并到靠前的位置上(规则 6),于是输出序列 + * 的最后一条不一定携带最高 revision。revision 按契约单调,max 让「合并前后终态逐字节一致」这条 + * 定律不依赖 op 的位置。 + * + * 身份:未改动的 run 与未改动的条目保持引用不变,变化的那条 run 与容器是新对象——GUI 正是按 + * 这两级引用做 memo。 + */ +export function applyWorkflowRunUpdated( + state: WorkflowRunsState | undefined, + delta: WorkflowRunUpdatedDelta, +): WorkflowRunsState { + const runs = state?.runs ?? []; + const revision = Math.max(state?.revision ?? 0, delta.revision); + const index = runs.findIndex((run) => run.runId === delta.runId); + if (index < 0) { + // 未知 run + 完整 header = 诞生;未知 run + 残缺 header = 这条 op 说的不是客户端手上的事实, + // 按 no-op 处理(与 row.upserted 命中未加载行同一条裁决),只让容器 revision 跟上。 + if (!isCompleteWorkflowRunHeader(delta.run)) { + return state !== undefined && state.revision === revision ? state : { revision, runs }; + } + const born = canonicalWorkflowRun({ + ...(delta.run as Partial), + actors: delta.actors === undefined ? [] : [...delta.actors], + nodes: delta.nodes === undefined ? [] : [...delta.nodes], + } as WorkflowRunState); + return { revision, runs: [...runs, born] }; + } + const existing = runs[index]!; + const merged: Record = { ...existing, ...delta.run }; + // 「零条 ⇒ 键缺席」是好几个键的协议约定,所以增量必须说得出「这个键没了」。 + for (const key of delta.cleared ?? []) delete merged[key]; + // 施加序:header → 删除 → upsert。同一个键在一条 op 里被删又被加时它落在表尾,与顺序施加 + // 两条 op 的结果一致;反过来(先加后删)会把一条刚回来的条目又摘掉。 + const actors = removeWorkflowRunEntries(existing.actors, delta.removedActors); + const nodes = removeWorkflowRunEntries(existing.nodes, delta.removedNodes); + if (actors !== existing.actors) merged.actors = actors; + if (nodes !== existing.nodes) merged.nodes = nodes; + if (delta.actors !== undefined && delta.actors.length > 0) { + merged.actors = upsertWorkflowRunEntries(actors, delta.actors); + } + if (delta.nodes !== undefined && delta.nodes.length > 0) { + merged.nodes = upsertWorkflowRunEntries(nodes, delta.nodes); + } + const next = [...runs]; + next[index] = canonicalWorkflowRun(merged as unknown as WorkflowRunState); + return { revision, runs: next }; +} + +/** `workflowRun.removed` 的应用:把这条 run 摘掉。未知 runId 只让 revision 跟上。 */ +export function applyWorkflowRunRemoved( + state: WorkflowRunsState | undefined, + delta: WorkflowRunRemovedDelta, +): WorkflowRunsState { + const runs = state?.runs ?? []; + const revision = Math.max(state?.revision ?? 0, delta.revision); + const remaining = runs.filter((run) => run.runId !== delta.runId); + if (remaining.length === runs.length) { + return state !== undefined && state.revision === revision ? state : { revision, runs }; + } + return { revision, runs: remaining }; +} + +/** + * 按 (siteId, ordinal) 摘掉条目;一条都没命中时返回**同一个数组**(未提到的表要保住引用)。 + * 未命中的键是定义明确的 no-op:合并把两条 op 的删除取了并集,其中一些在这个客户端手上 + * 根本没到过。 + */ +function removeWorkflowRunEntries( + current: readonly T[], + removed: readonly { siteId: string; ordinal: number }[] | undefined, +): T[] { + if (removed === undefined || removed.length === 0) return current as T[]; + const dropped = new Set(removed.map(workflowRunEntryKey)); + const next = current.filter((entry) => !dropped.has(workflowRunEntryKey(entry))); + return next.length === current.length ? (current as T[]) : next; +} + +/** + * 按 (siteId, ordinal) upsert:已有键原地替换、新键追加到尾部。 + * + * 客户端**绝不**施加任何上界(maxNodes / maxActors / maxRuns):只有生产者有资格淘汰,而且 + * 淘汰必须说出来(`workflowRun.removed` / `removedActors` / `removedNodes`)。客户端自行裁剪 + * 只会让两侧悄悄分叉。 + */ +function upsertWorkflowRunEntries( + current: readonly T[], + incoming: readonly T[], +): T[] { + const next = [...current]; + const indexByKey = new Map(); + next.forEach((entry, index) => indexByKey.set(workflowRunEntryKey(entry), index)); + for (const entry of incoming) { + const key = workflowRunEntryKey(entry); + const index = indexByKey.get(key); + if (index === undefined) { + indexByKey.set(key, next.length); + next.push(entry); + continue; + } + next[index] = entry; + } + return next; +} + +/** + * 一条 `workflowRun.updated` 的四张条目表都在线上界之内吗。 + * + * 真正会超界的是**两张删除表**。合并出来的 upsert 表自己就有界:按合并规则,先者 upsert 的键 + * 凡被后者删掉的都已去掉,所以留下的每一个键在这条 op 施加完之后都还在表里,而表本身 ≤ 界。 + * 删除表没有这条护栏——合并分不出「窗口里刚出生又被淘汰的键」和「客户端早就拿着的键」, + * 每次淘汰都让出一个位子,一个够宽的 flush 窗口里被删掉的不同键因此可以多于 1024 条。 + * 淘汰之前这不可能:表只增不减,一世之内被碰过的不同键最多就是表界那么多。 + * + * 超界载荷会让整个 patch 解析失败、整帧被丢;publisher 的两道限制(500 op / 1 MiB)在这个 + * 量级上都不会响。四张表都查是因为这道闸很便宜,而且不该依赖上面那条论证一直成立。 + * + * 合并是**优化**,所以拒绝合并永远是安全的:两条 op 各自都在界内,逐条投递的终态一个字节都不差。 + */ +export function workflowRunUpdateWithinWireBounds( + delta: WorkflowRunUpdatedDelta, + limits: WorkflowRunWireBounds = WORKFLOW_RUNS_LIMITS, +): boolean { + return ( + (delta.actors?.length ?? 0) <= limits.maxActors && + (delta.removedActors?.length ?? 0) <= limits.maxActors && + (delta.nodes?.length ?? 0) <= limits.maxNodes && + (delta.removedNodes?.length ?? 0) <= limits.maxNodes + ); +} + +/** + * 条目表的容量上限,默认使用 {@link WORKFLOW_RUNS_LIMITS}。 + * 增量应用和合并必须使用一致的上限。 + */ +export interface WorkflowRunWireBounds { + readonly maxActors: number; + readonly maxNodes: number; +} + +/** 合并两条同 run 的 `workflowRun.updated`(coalesce 规则 6 的载荷部分,规则本身在 coalesce.ts)。 */ +export function mergeWorkflowRunUpdates( + earlier: WorkflowRunUpdatedDelta, + later: WorkflowRunUpdatedDelta, +): WorkflowRunUpdatedDelta { + const run: Record = { ...earlier.run, ...later.run }; + // header 键与 `cleared` 互为反面,合并时必须彼此对消:后设值的键不再是"被清掉的", + // 后清掉的键也不再有值。留一半会让 apply 先写后删(或先删后写),结果取决于键序。 + const laterCleared = new Set(later.cleared ?? []); + for (const key of laterCleared) delete run[key]; + const cleared: WorkflowRunHeaderKey[] = []; + for (const key of earlier.cleared ?? []) { + if (run[key] === undefined && !cleared.includes(key)) cleared.push(key); + } + for (const key of later.cleared ?? []) { + if (!cleared.includes(key)) cleared.push(key); + } + const removedActors = mergeRemovedRefs(earlier.removedActors, later.removedActors); + const removedNodes = mergeRemovedRefs(earlier.removedNodes, later.removedNodes); + const actors = mergeEntryLists( + earlier.actors, + later.actors, + later.removedActors, + ); + const nodes = mergeEntryLists(earlier.nodes, later.nodes, later.removedNodes); + return { + op: "workflowRun.updated", + runId: later.runId, + // 取最高水位:合并后的 op 坐在靠前的位置上,靠 apply 的 max 让容器版本仍然收在最高 revision。 + revision: Math.max(earlier.revision, later.revision), + ...(Object.keys(run).length > 0 ? { run: run as WorkflowRunUpdatedDelta["run"] } : {}), + ...(cleared.length > 0 ? { cleared } : {}), + ...(removedActors === undefined ? {} : { removedActors }), + ...(removedNodes === undefined ? {} : { removedNodes }), + ...(actors === undefined ? {} : { actors }), + ...(nodes === undefined ? {} : { nodes }), + }; +} + +/** 两侧的删除取并集,按首次出现去重(删除是按键过滤,顺序不影响结果,只影响字节)。 */ +function mergeRemovedRefs( + earlier: readonly WorkflowRunEntryRef[] | undefined, + later: readonly WorkflowRunEntryRef[] | undefined, +): WorkflowRunEntryRef[] | undefined { + if (earlier === undefined && later === undefined) return undefined; + const merged: WorkflowRunEntryRef[] = []; + const seen = new Set(); + for (const ref of [...(earlier ?? []), ...(later ?? [])]) { + const key = workflowRunEntryKey(ref); + if (seen.has(key)) continue; + seen.add(key); + merged.push(ref); + } + return merged.length > 0 ? merged : undefined; +} + +/** + * 条目表按键后来者覆盖、按首次出现保序;两侧都没有条目时返回 undefined(键不建)。 + * + * **先者 upsert 的键凡是被后者删掉的一律去掉**:顺序施加时它先进表、再被后者摘走,所以合并后 + * 的 op 里根本不该有它。若后者又把同一个键加了回来,它只在后者的表里出现一次,于是落在表尾 + * ——顺序施加得到的正是这个位置。 + */ +function mergeEntryLists( + earlier: readonly T[] | undefined, + later: readonly T[] | undefined, + laterRemoved: readonly WorkflowRunEntryRef[] | undefined, +): T[] | undefined { + if (earlier === undefined && later === undefined) return undefined; + const dropped = new Set((laterRemoved ?? []).map(workflowRunEntryKey)); + const kept = + dropped.size === 0 + ? (earlier ?? []) + : (earlier ?? []).filter((entry) => !dropped.has(workflowRunEntryKey(entry))); + const merged = upsertWorkflowRunEntries(kept, later ?? []); + return merged.length > 0 ? merged : undefined; +} diff --git a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs.ts b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs.ts index 6a4c249..cd27ebe 100644 --- a/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs.ts +++ b/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-runs.ts @@ -15,14 +15,22 @@ export const WORKFLOW_RUNS_LIMITS = { /** 最近若干个 run;超出按最旧淘汰。 */ maxRuns: 8, /** - * actors 与 nodes **同界**。每个节点都属于某个 actor,所以 nodes 的界已经隐含了 actor - * 数的量级;把 actors 压得更低(曾是 32)只会让一个平常的 50 路 fan-out 在检视器里 - * 静默少掉 18 个子代理,而节点表、引擎、图三层都装得下。这条界的唯一职责是挡住 - * 「疯掉的脚本在循环里 `agent()`」——状态键按事件整体重发,无界会是 O(N²) 字节—— - * 不是产品意义上的子代理上限。 + * actors 与 nodes 使用相同的容量上限,避免节点可展示而所属子代理提前被截断。 + * 键级增量使每个事件只传输改动部分;容量上限用于限制单条 run 的投影大小, + * 并限制异常脚本持续创建条目带来的资源消耗。跨 run 的总量由 {@link maxTotalEntries} 控制。 + * 这是展示状态的容量限制,不限制引擎实际运行的子代理数量。 */ - maxActors: 256, - maxNodes: 256, + maxActors: 1_024, + maxNodes: 1_024, + /** + * 整个状态键的条目预算:所有 run 的 `nodes.length + actors.length` 之和。 + * + * 单条 run 的界乘以 {@link maxRuns} 是 16384 条,按每条约 150 字节算就是 ~2.5 MB —— + * 离 16 MiB 的快照上限不远,而快照是要整份序列化的。预算把最坏情形压回 ~1 MB, + * 代价是**最旧的终态 run** 会提前离场(它的完整事实仍在 journal 里,详情页照样查得到)。 + * 归约在超预算时只淘汰终态 run,绝不动在跑的 run,也绝不动事件所属的那条。 + */ + maxTotalEntries: 6_144, /** * 详情页 Results 区的**展示**预算,刻意远小于引擎的 run 级 report 上限(256 条): * 协议线上的界是展示预算,引擎的界才是契约,两者不必相等。超出这个界的条目仍在 @@ -89,6 +97,20 @@ export const WORKFLOW_RUNS_LIMITS = { maxLastToolTargetLength: 120, } as const; +/** + * **旧消费者**(没有 `workflowRunDeltas` 能力的那一代)编译进去的 actors / nodes 界。 + * + * ⚠ 这两个数**永远不能改**:它们不是我们的界,是别人二进制里的校验界。超界的载荷不会被 + * 剥掉一个键——它会让整个 `state.updated` patch 解析失败、整帧被丢,那条订阅从此静默。所以给这类订阅者 + * 发帧前必须先过 `clampWorkflowRunsForLegacy`。 + * + * 「前 256 条」不是随手取的:旧归约触界时是**拒新**,它产出的恰好就是最早的那 256 条。 + */ +export const WORKFLOW_RUNS_LEGACY_LIMITS = { + maxActors: 256, + maxNodes: 256, +} as const; + /** * 一个被控制流进入过的阶段(`phase("…")` 标记)。`name` 是作者原词(时间线按它关联 display 的 `phases[].name`);`rounds` 是进入 * 次数——单调(reducer 取 max),所以 resume 重放的前缀不会把它加倍。 @@ -99,6 +121,28 @@ export const workflowRunPhaseSchema = z.object({ }); export type WorkflowRunPhase = z.infer; +/** + * 界在某个**出生阶段**上花掉了多少。 + * + * 两个计数器({@link workflowRunUsageSchema} 的 `nodesUnlisted` / `nodesUnlistedSettled`)说得出 + * 一条 run 总共少列了多少,说不出少在**哪一站**——而读面是按站画的:一个站点的花名册、计数环和 + * 「N more」都得把自己那格的表外条目加回去,否则宽 fan-out 的站点会显示成一个小数字。 + * + * `phaseName` 缺席 = 无阶段那一格(出生在任何 `phase()` 标记之前,或旧 CLI 没打戳)。`actors` 是 + * 这个阶段**此刻不在 actor 表上**的子代理数(被拒的、被淘汰的、按孤儿规则摘掉的都算), + * `actorsSettled` 是其中已知已经结束的、`actorsFailed` 又是其中失败的,`settled` 是记在这一格上的 + * 表外已结算节点数。`actors` 可加可减:一个被淘汰的子代理在下次被派活时会回到表上。 + * 零值的可选子键缺席,四个数全零的格子整个不在(与本文件其余「无则缺席」同规)。 + */ +export const workflowRunUnlistedPhaseSchema = z.object({ + phaseName: z.string().min(1).max(WORKFLOW_RUNS_LIMITS.maxPhaseNameLength).optional(), + actors: z.number().int().nonnegative(), + actorsSettled: z.number().int().nonnegative().optional(), + actorsFailed: z.number().int().nonnegative().optional(), + settled: z.number().int().nonnegative(), +}); +export type WorkflowRunUnlistedPhase = z.infer; + /** * run 级用量:观察面,不是控制面。`spentTokens` 直接取 * 引擎 `usage-updated` 事件携带的已花总量(与 `dwf_run.spent_tokens` 同一同步步骤写入, @@ -108,6 +152,16 @@ export type WorkflowRunPhase = z.infer; export const workflowRunUsageSchema = z.object({ spentTokens: z.number().int().nonnegative(), nodesUsed: z.number().int().nonnegative(), + /** + * 撞上 {@link WORKFLOW_RUNS_LIMITS.maxNodes} 被**拒之表外**的实例数,以及其中已结算的条数。`truncated` 只说得出「有东西没进来」,说不出 + * 有多少——于是一个 3000 路 fan-out 的 run 在读面上会显示成「1024 步」,那是一句假话。 + * + * 两条都是**加出来**的计数(被拒实例根本不在表里,没有可去重的身份),所以归约只在事件 + * **抬过水位**时才计,重传的队尾事件不会把它们越推越高。`run-started` 连同整个 usage 一起 + * 清零:resume 会把脚本前缀重发一遍,不清零等于把两世的步数加在一起。零时整个键缺席。 + */ + nodesUnlisted: z.number().int().nonnegative().optional(), + nodesUnlistedSettled: z.number().int().nonnegative().optional(), }); export type WorkflowRunUsage = z.infer; @@ -161,7 +215,8 @@ export type WorkflowRunNodeLastTool = z.infer; -// Read-only status report for the Settings screen. The handler sanitizes every +// Status report for the Diagnostics screen. The handler sanitizes every // field; no credentials, conversation text, or raw native output cross this RPC. export const zcodeDiagnostics = defineRpc({ name: "zcode.diagnostics", diff --git a/shared/runtime-setup.ts b/shared/runtime-setup.ts new file mode 100644 index 0000000..332c9c9 --- /dev/null +++ b/shared/runtime-setup.ts @@ -0,0 +1,75 @@ +import { defineRpc } from "@getpaseo/plugin"; +import { z } from "zod"; + +export const runtimeComponentSchema = z + .object({ + id: z.enum(["node", "zcode"]), + name: z.string(), + version: z.string(), + url: z.string(), + sha256: z.string(), + sizeBytes: z.number().int().nonnegative(), + license: z.string(), + installed: z.boolean(), + }) + .strict(); + +export const setupJobSchema = z.discriminatedUnion("state", [ + z.object({ state: z.literal("idle") }).strict(), + z + .object({ + state: z.literal("running"), + component: z.enum(["node", "zcode"]), + phase: z.enum(["download", "extract", "verify"]), + receivedBytes: z.number().int().nonnegative(), + totalBytes: z.number().int().nonnegative(), + }) + .strict(), + z.object({ state: z.literal("succeeded") }).strict(), + z + .object({ + state: z.literal("failed"), + code: z.string(), + message: z.string(), + }) + .strict(), +]); + +export const runtimeSetupStatusSchema = z + .object({ + platform: z.string(), + /** Managed setup exists for this daemon's OS/CPU. */ + supported: z.boolean(), + /** PASEO_ZCODE_RUNTIME / PASEO_ZCODE_NODE take precedence when set. */ + override: z.boolean(), + directory: z.string(), + components: z.array(runtimeComponentSchema), + job: setupJobSchema, + /** Present once both components are installed; run it on the daemon machine. */ + loginCommand: z.string().optional(), + }) + .strict(); + +export type RuntimeSetupStatus = z.output; + +// Inputs are empty on purpose: the server installs only its pinned artifacts. +export const zcodeRuntimeStatus = defineRpc({ + name: "zcode.runtime.status", + input: z.object({}).strict(), + output: runtimeSetupStatusSchema, +}); + +export const zcodeRuntimeInstall = defineRpc({ + name: "zcode.runtime.install", + input: z.object({}).strict(), + output: z.object({ started: z.boolean() }).strict(), +}); + +export const zcodeRuntimeRemove = defineRpc({ + name: "zcode.runtime.remove", + input: z.object({}).strict(), + output: z.discriminatedUnion("status", [ + z.object({ status: z.literal("removed") }).strict(), + z.object({ status: z.literal("failed"), message: z.string() }).strict(), + ]), +}); diff --git a/test/package-zcode-runtime.test.mjs b/test/package-zcode-runtime.test.mjs new file mode 100644 index 0000000..4128afa --- /dev/null +++ b/test/package-zcode-runtime.test.mjs @@ -0,0 +1,52 @@ +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, test } from "vitest"; +import { + REQUIRED_RUNTIME_FILES, + assertRuntimeLayout, + runtimeAssetName, + runtimeVersionFromTag, +} from "../scripts/package-zcode-runtime.mjs"; + +const directories = []; +afterEach(async () => { + for (const directory of directories.splice(0)) + await rm(directory, { recursive: true, force: true }); +}); + +describe("runtime release naming", () => { + test("accepts only exact stable or prerelease versions after the prefix", () => { + expect(runtimeVersionFromTag("zcode-runtime-v3.14.3")).toBe("3.14.3"); + for (const tag of [ + "v3.14.3", + "zcode-runtime-3.14.3", + "zcode-runtime-v3.14", + "zcode-runtime-v3.14.3 ", + ]) + expect(() => runtimeVersionFromTag(tag)).toThrow(); + }); + + test("derives the asset name from the version", () => { + expect(runtimeAssetName("3.14.3")).toBe("zcode-runtime-3.14.3.tar.gz"); + expect(() => runtimeAssetName("../3.14.3")).toThrow(); + }); +}); + +describe("runtime archive layout", () => { + test("requires the Server, Agent, provider configuration and launcher", async () => { + const root = await mkdtemp(join(tmpdir(), "zcode-layout-")); + directories.push(root); + for (const file of REQUIRED_RUNTIME_FILES) { + await mkdir(join(root, file, ".."), { recursive: true }); + await writeFile(join(root, file), ""); + } + await expect( + assertRuntimeLayout(root, REQUIRED_RUNTIME_FILES), + ).resolves.toBeUndefined(); + await rm(join(root, "server/remote/zcode-server.cjs")); + await expect( + assertRuntimeLayout(root, REQUIRED_RUNTIME_FILES), + ).rejects.toThrow("server/remote/zcode-server.cjs"); + }); +});