paseo-plugin-zcode-provider 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 supermomonga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,29 @@
+# ライセンスの適用範囲
+
+本プロジェクトのオリジナルコードは [MIT License](LICENSE)（Copyright (c) 2026 supermomonga）で提供します。移植元の `paseo-zcode-patcher` と `zcode-acp` の該当コードも同じ著作者のオリジナルコードです。
+
+第三者素材のライセンスや権利は変更しません。`icon.svg` には以下の Apache-2.0 の条件が適用されます。`images/zcode-conversation.png` は著作者提供のスクリーンショットで、含まれる第三者アプリの画面・ロゴ・商標への権利を本プロジェクトの MIT License で許諾するものではありません。
+
+# ソースの由来
+
+`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 ランタイムの配布
+
+ZCode は統合 CLI を配布していないため、このリポジトリは `zcode-runtime-v<version>` タグの 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` にも配置します。
+
+開発 SDK は `@getpaseo/plugin@0.9.0-beta.1` です。ビルドは `@getpaseo/plugin/server/provider` と `zod` を外部モジュールとして維持し、Paseo に解決させます。
+
+`icon.svg` は [Paseo main c424f829 の glm-acp-agent.svg](https://github.com/getpaseo/paseo/blob/c424f82922fcd36aa9cc9e473644bca04417b420/packages/app/src/assets/acp-provider-icons/glm-acp-agent.svg) のコピーです。この SVG は [ACP Registry の glm-acp-agent/icon.svg](https://github.com/agentclientprotocol/registry/blob/f3826ddd6e35951ea9b7fd0cf43c35a30c3c64cd/glm-acp-agent/icon.svg) とバイト単位で一致します。ACP Registry は Apache-2.0 で配布されており、その [LICENSE](vendor/acp-registry/LICENSE) を保持しています。アイコンは変更していません。商標への権利や公式の承認を示すものではありません。
+
+アイコンの出典に対応する上流ライセンスを [vendor/paseo/LICENSE](vendor/paseo/LICENSE) に保持しています。Copyright (c) 2025-present Mohamed Boudra。
+
+リリース監視スクリプトとワークフローは、[zcode-acp commit 7b3af187d7ee732e9043aed873a863fc855625c2](https://github.com/supermomonga/zcode-acp/tree/7b3af187d7ee732e9043aed873a863fc855625c2) の `scripts/check-zcode-releases.ts`、対応テスト、`.github/workflows/zcode-release-check.yml` を参考にしています。対応バージョンより新しいリリースの取得、変更履歴付きIssue作成、クローズ済みを含む重複防止をNode.js向けに実装し、Paseoのプレリリース・正式版にも適用しています。

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# ZCode Provider for Paseo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+| 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+ |
+
+## Installation
+
+Enable **Settings → Plugins → Enable plugins** for the target daemon, then install the [npm package](https://www.npmjs.com/package/paseo-plugin-zcode-provider) and inspect:
+
+```bash
+paseo plugin add npm:paseo-plugin-zcode-provider
+paseo plugin ls
+```
+
+You can also paste `npm:paseo-plugin-zcode-provider` into **Settings → Plugins → Plugin source**. npm packages require Paseo 0.9.0 or later and npm on the daemon host. Paseo installs the released version and compiles the plugin. Update with `paseo plugin update zcode-provider`. Plugins execute with the daemon user's permissions.
+
+To follow the `main` branch instead, install the Git repository with `paseo plugin add supermomonga/paseo-plugin-zcode-provider`. Paseo prepares the checkout with `npm ci`.
+
+## Setup
+
+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:
+
+- 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.
+
+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
+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_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
+
+- Models and reasoning options come from ZCode. Editing modes are `build`, `edit`, and `yolo`; `settings.plan_mode` is independent.
+- Text, thoughts, tools, subagent progress, usage and history use V4 snapshots and deltas. Tool output is marked when ZCode truncates it. Usage is cumulative; repeated snapshots do not add it again.
+- Text submitted during generation uses native guidance. Attachments use the native queue. Paseo reports one run across these native turns and completes it only after all accepted input has been consumed and foreground work has ended.
+- Acceptance is reported once, after the native acknowledgement. Unknown delivery results are never automatically resent. Stop identifies the current native execution, disables automatic queue execution and removes pending input. A new explicit run enables the queue again.
+- Native permission IDs, option values, questions and Plan approval retain their meanings. Question auto-resolution is disabled for each owned Server. Workspace hook trust is reviewed through the official CLI; it is not represented as “allow once.”
+- Each session owns its Server process and environment. Metadata requests use temporary Servers. Closing stdin gives ZCode time to clean up before process termination.
+
+The plugin uses ZCode's own skills, MCP configuration and tools. Browser/Computer Use, generic rewind, independent Paseo child agents, hook-review UI and Goal/Workflow controls are outside this migration. `prompt.output_schema`, custom system prompts and `persist:false` are unsupported. MCP `alwaysLoad` is unsupported; stdio MCP commands must be absolute paths. Standard Paseo quota and initial usage UI limitations are not filled with substitute displays.
+
+## Persistence
+
+New handles use **version 3**. Versions 1 and 2 are rejected without migration or replacement. Old Paseo sessions are outside this migration.
+
+Unsent conversations are deferred drafts. Before the first prompt, the plugin atomically saves the logical-to-native ID mapping under `$XDG_STATE_HOME/paseo-plugin-zcode-provider/sessions-v3`, or `~/.local/state/paseo-plugin-zcode-provider/sessions-v3`. It stores identifiers and workspace paths, not message bodies. Preserve this directory for backup. A mapping write failure prevents sending. Corrupt mappings and missing native conversations fail explicitly; no replacement conversation is created.
+
+New conversations support listing, resume and paged V4 history. Mode/Plan restoration requires both `mode` and `settings.plan_mode` saved by Paseo. The plugin applies them after native restore and confirms the resulting state before reporting the session ready. Omitted settings retain whatever ZCode returns, which can be stale on the pinned source; restoration of those values is not guaranteed. There is no private Plan restoration store. [ADR 14](docs/adr/0014-paseoの保存設定を再適用する復元を保証範囲とする.md) limits the guarantee to this supported path; settings-free restoration is checked separately with `npm run test:native-restore`. Existing ZCode databases may be migrated by ZCode itself on startup; the native tests isolate the home, configuration and database.
+
+## Diagnostics
+
+**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
+```
+
+For failures, report the operation, error code, structured diagnostic and versions/hashes. Native stderr, raw errors, credentials and conversation bodies are excluded from diagnostics. Review any additional material before sharing. Reports are not sent automatically.
+
+## Development and license
+
+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 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).

package/client/diagnostics.tsx

@@ -0,0 +1,397 @@
+import { useCallback, useEffect, useState } from "react";
+import { Text, View } from "react-native";
+import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client";
+import {
+  SettingsAction,
+  SettingsCard,
+  SettingsRow,
+  SettingsSection,
+} from "@getpaseo/plugin/client/ui";
+import {
+  zcodeDiagnostics,
+  type DiagnosticsResult,
+} from "../shared/diagnostics";
+
+function Value({
+  children,
+  color,
+  compact,
+}: {
+  children: string;
+  color: string;
+  compact: boolean;
+}) {
+  return (
+    <Text
+      selectable
+      style={{ color, fontSize: compact ? 13 : 14, lineHeight: 20 }}
+    >
+      {children}
+    </Text>
+  );
+}
+
+function Installation({ result, theme, compact }: SectionProps) {
+  return (
+    <SettingsSection title="ZCode installation">
+      <SettingsCard>
+        <SettingsRow
+          label="Install root"
+          hint={
+            result.source === "managed"
+              ? "Managed runtime installed from the Setup screen"
+              : "PASEO_ZCODE_RUNTIME"
+          }
+        >
+          <Value color={theme.colors.foreground} compact={compact}>
+            {result.installRoot}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Platform">
+          <Value color={theme.colors.foreground} compact={compact}>
+            {result.platform}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="ZCode Server version">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.appVersion ?? "Not reported"}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Agent version">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.cliVersion ?? "Not reported"}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Provider plugin version">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.providerVersion}
+          </Value>
+        </SettingsRow>
+      </SettingsCard>
+    </SettingsSection>
+  );
+}
+
+function Compatibility({ result, theme, compact }: SectionProps) {
+  const supported = result.compatibility === "supported";
+  return (
+    <SettingsSection title="Compatibility">
+      <SettingsCard>
+        <SettingsRow label="Status">
+          <Value
+            color={
+              supported ? theme.colors.statusSuccess : theme.colors.statusDanger
+            }
+            compact={compact}
+          >
+            {supported ? "Supported" : "Unsupported"}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Reason">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.compatibilityReason}
+          </Value>
+        </SettingsRow>
+        <SettingsRow
+          label="Node.js"
+          hint={
+            result.source === "managed" ? "Managed Node.js" : "PASEO_ZCODE_NODE"
+          }
+        >
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {`${result.nodeExecutable} (${result.nodeVersion})`}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Server SHA-256">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.serverSha256}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Agent SHA-256">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.agentSha256}
+          </Value>
+        </SettingsRow>
+        <SettingsRow label="Install root permissions">
+          <Value color={theme.colors.foregroundMuted} compact={compact}>
+            {result.writableInstallRoot ? "Writable" : "Read-only"}
+          </Value>
+        </SettingsRow>
+      </SettingsCard>
+    </SettingsSection>
+  );
+}
+
+function HostCheck({
+  result,
+  busy,
+  onRun,
+  theme,
+  compact,
+}: SectionProps & { busy: boolean; onRun(): void }) {
+  const smoke = result.smoke;
+  return (
+    <SettingsSection title="Host check">
+      <SettingsCard>
+        <SettingsRow
+          label="Result"
+          hint="Checks the configured Node.js and Server versions. No prompt is sent."
+        >
+          <Value
+            color={
+              smoke === undefined
+                ? theme.colors.foregroundMuted
+                : smoke.passed
+                  ? theme.colors.statusSuccess
+                  : theme.colors.statusDanger
+            }
+            compact={compact}
+          >
+            {smoke === undefined
+              ? "Not run"
+              : smoke.passed
+                ? "Passed"
+                : "Failed"}
+          </Value>
+        </SettingsRow>
+        {smoke === undefined ? null : (
+          <>
+            {smoke.error === undefined ? null : (
+              <SettingsRow label="Error">
+                <Value color={theme.colors.statusDanger} compact={compact}>
+                  {smoke.error}
+                </Value>
+              </SettingsRow>
+            )}
+          </>
+        )}
+      </SettingsCard>
+      <SettingsAction
+        label="stdio Server"
+        actionLabel={busy ? "Checking…" : "Run host check"}
+        disabled={busy}
+        onPress={onRun}
+      />
+    </SettingsSection>
+  );
+}
+
+function SessionStorage({ result, theme, compact }: SectionProps) {
+  return (
+    <SettingsSection title="Session storage">
+      <SettingsCard>
+        <SettingsRow
+          label="Resume mapping directory"
+          hint="Stores identifiers and workspace paths, not message contents."
+        >
+          <Value color={theme.colors.foreground} compact={compact}>
+            {result.sessionsDirectory}
+          </Value>
+        </SettingsRow>
+      </SettingsCard>
+    </SettingsSection>
+  );
+}
+
+interface SectionProps {
+  result: Extract<DiagnosticsResult, { status: "ready" }>;
+  theme: PluginSurfaceProps["theme"];
+  compact: boolean;
+}
+
+function ReadyView({
+  result,
+  busy,
+  onCheck,
+  onSmoke,
+  theme,
+  compact,
+}: {
+  result: Extract<DiagnosticsResult, { status: "ready" }>;
+  busy: boolean;
+  onCheck(): void;
+  onSmoke(): void;
+  theme: PluginSurfaceProps["theme"];
+  compact: boolean;
+}) {
+  return (
+    <View style={{ gap: compact ? 16 : 24 }}>
+      <Installation result={result} theme={theme} compact={compact} />
+      <Compatibility result={result} theme={theme} compact={compact} />
+      <HostCheck
+        result={result}
+        busy={busy}
+        onRun={onSmoke}
+        theme={theme}
+        compact={compact}
+      />
+      <SessionStorage result={result} theme={theme} compact={compact} />
+      <SettingsSection title="Detection">
+        <SettingsAction
+          label="Installed ZCode"
+          actionLabel={busy ? "Checking…" : "Check again"}
+          disabled={busy}
+          onPress={onCheck}
+        />
+      </SettingsSection>
+    </View>
+  );
+}
+
+function FailedView({
+  result,
+  busy,
+  onCheck,
+  theme,
+  compact,
+}: {
+  result: Extract<DiagnosticsResult, { status: "failed" }>;
+  busy: boolean;
+  onCheck(): void;
+  theme: PluginSurfaceProps["theme"];
+  compact: boolean;
+}) {
+  return (
+    <View style={{ gap: compact ? 16 : 24 }}>
+      <SettingsSection title="ZCode diagnostics">
+        <SettingsCard>
+          <SettingsRow label="Result">
+            <Value color={theme.colors.statusDanger} compact={compact}>
+              Failed
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Error code">
+            <Value color={theme.colors.foreground} compact={compact}>
+              {result.code}
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Message">
+            <Value color={theme.colors.foregroundMuted} compact={compact}>
+              {result.message}
+            </Value>
+          </SettingsRow>
+          <SettingsRow
+            label="Diagnostic report"
+            hint="Safe to attach to a GitHub issue; credentials, prompts, and raw native errors are excluded."
+          >
+            <Value color={theme.colors.foregroundMuted} compact={compact}>
+              {result.diagnostic}
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Provider plugin version">
+            <Value color={theme.colors.foregroundMuted} compact={compact}>
+              {result.providerVersion}
+            </Value>
+          </SettingsRow>
+        </SettingsCard>
+        <SettingsAction
+          label="Installed ZCode"
+          actionLabel={busy ? "Checking…" : "Check again"}
+          disabled={busy}
+          onPress={onCheck}
+        />
+      </SettingsSection>
+    </View>
+  );
+}
+
+export function DiagnosticsScreen({ theme, layout }: PluginSurfaceProps) {
+  const run = useRpc(zcodeDiagnostics);
+  const [result, setResult] = useState<DiagnosticsResult | null>(null);
+  const [requestError, setRequestError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(true);
+
+  const check = useCallback(
+    async (smoke: boolean) => {
+      setBusy(true);
+      try {
+        setResult(await run({ smoke }));
+        setRequestError(null);
+      } catch (cause) {
+        setRequestError(
+          cause instanceof Error
+            ? cause.message
+            : "The diagnostics request failed.",
+        );
+      } finally {
+        setBusy(false);
+      }
+    },
+    [run],
+  );
+
+  useEffect(() => {
+    void check(false);
+  }, [check]);
+
+  if (result === null) {
+    return (
+      <SettingsSection title="ZCode diagnostics">
+        <SettingsCard>
+          <SettingsRow label="Status">
+            <Value
+              color={theme.colors.foregroundMuted}
+              compact={layout.compact}
+            >
+              {requestError ?? "Checking the ZCode installation…"}
+            </Value>
+          </SettingsRow>
+        </SettingsCard>
+        {requestError === null ? null : (
+          <SettingsAction
+            label="Diagnostics request"
+            actionLabel={busy ? "Checking…" : "Try again"}
+            disabled={busy}
+            onPress={() => void check(false)}
+          />
+        )}
+      </SettingsSection>
+    );
+  }
+
+  const props = {
+    busy,
+    onCheck: () => void check(false),
+    onSmoke: () => void check(true),
+    theme,
+    compact: layout.compact,
+  };
+  return result.status === "ready" ? (
+    <>
+      <ReadyView result={result} {...props} />
+      {requestError === null ? null : (
+        <RequestError
+          message={requestError}
+          theme={theme}
+          compact={layout.compact}
+        />
+      )}
+    </>
+  ) : (
+    <FailedView result={result} {...props} />
+  );
+}
+
+function RequestError({
+  message,
+  theme,
+  compact,
+}: {
+  message: string;
+  theme: PluginSurfaceProps["theme"];
+  compact: boolean;
+}) {
+  return (
+    <SettingsSection title="Last request">
+      <Text
+        accessibilityRole="alert"
+        style={{
+          color: theme.colors.statusDanger,
+          fontSize: compact ? 13 : 14,
+        }}
+      >
+        {message}
+      </Text>
+    </SettingsSection>
+  );
+}