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

package/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 (
+    <Text
+      selectable
+      style={{ color, fontSize: compact ? 13 : 14, lineHeight: 20 }}
+    >
+      {children}
+    </Text>
+  );
+}
+
+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) => (
+        <SettingsSection
+          key={component.id}
+          title={`${component.name} ${component.version}`}
+        >
+          <SettingsCard>
+            <SettingsRow label="Status">
+              <Value
+                color={
+                  component.installed
+                    ? theme.colors.statusSuccess
+                    : theme.colors.foregroundMuted
+                }
+                compact={compact}
+              >
+                {component.installed ? "Installed" : "Not installed"}
+              </Value>
+            </SettingsRow>
+            <SettingsRow label="Source" hint={megabytes(component.sizeBytes)}>
+              <Value color={theme.colors.foregroundMuted} compact={compact}>
+                {component.url}
+              </Value>
+            </SettingsRow>
+            <SettingsRow label="SHA-256" hint="Checked before extraction">
+              <Value color={theme.colors.foregroundMuted} compact={compact}>
+                {component.sha256}
+              </Value>
+            </SettingsRow>
+            <SettingsRow label="License">
+              <Value color={theme.colors.foregroundMuted} compact={compact}>
+                {component.license}
+              </Value>
+            </SettingsRow>
+          </SettingsCard>
+        </SettingsSection>
+      ))}
+    </>
+  );
+}
+
+export function SetupScreen({ theme, layout }: PluginSurfaceProps) {
+  const fetchStatus = useRpc(zcodeRuntimeStatus);
+  const install = useRpc(zcodeRuntimeInstall);
+  const remove = useRpc(zcodeRuntimeRemove);
+  const [status, setStatus] = useState<RuntimeSetupStatus | null>(null);
+  const [requestError, setRequestError] = useState<string | null>(null);
+  const [removeMessage, setRemoveMessage] = useState<string | null>(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<unknown>) => {
+      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 (
+      <SettingsSection title="ZCode runtime setup">
+        <SettingsCard>
+          <SettingsRow label="Status">
+            <Value color={theme.colors.foregroundMuted} compact={compact}>
+              {requestError ?? "Checking the managed runtime…"}
+            </Value>
+          </SettingsRow>
+        </SettingsCard>
+      </SettingsSection>
+    );
+
+  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 (
+    <View style={{ gap: compact ? 16 : 24 }}>
+      <SettingsSection title="ZCode runtime setup">
+        <SettingsCard>
+          <SettingsRow label="Downloads from">
+            <Value color={theme.colors.foreground} compact={compact}>
+              nodejs.org and this plugin's GitHub releases
+            </Value>
+          </SettingsRow>
+          <SettingsRow
+            label="ZCode build"
+            hint="ZCode does not publish its CLI; CI builds the unmodified source."
+          >
+            <Value color={theme.colors.foreground} compact={compact}>
+              Unofficial, not endorsed by ZCode or Z.ai
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Runs as">
+            <Value color={theme.colors.foreground} compact={compact}>
+              The daemon user, on the daemon machine
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Changes">
+            <Value color={theme.colors.foreground} compact={compact}>
+              Only the destination below; PATH is untouched
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Destination">
+            <Value color={theme.colors.foregroundMuted} compact={compact}>
+              {status.directory}
+            </Value>
+          </SettingsRow>
+          <SettingsRow label="Platform">
+            <Value
+              color={
+                status.supported
+                  ? theme.colors.foregroundMuted
+                  : theme.colors.statusDanger
+              }
+              compact={compact}
+            >
+              {status.supported
+                ? status.platform
+                : `${status.platform} is not supported. Set PASEO_ZCODE_RUNTIME and PASEO_ZCODE_NODE instead.`}
+            </Value>
+          </SettingsRow>
+          {status.override ? (
+            <SettingsRow
+              label="Environment override"
+              hint="Unset both variables and restart the daemon to use the managed runtime."
+            >
+              <Value color={theme.colors.statusWarning} compact={compact}>
+                PASEO_ZCODE_RUNTIME / PASEO_ZCODE_NODE are set, so sessions use
+                them instead of this runtime.
+              </Value>
+            </SettingsRow>
+          ) : null}
+          <SettingsRow
+            label="Progress"
+            error={status.job.state === "failed" ? status.job.message : null}
+          >
+            <Value
+              color={
+                status.job.state === "failed"
+                  ? theme.colors.statusDanger
+                  : theme.colors.foregroundMuted
+              }
+              compact={compact}
+            >
+              {jobLabel(status.job)}
+            </Value>
+          </SettingsRow>
+        </SettingsCard>
+        {status.supported ? (
+          <SettingsAction
+            label={installed ? "Runtime installed" : "Install runtime"}
+            hint={installed ? undefined : `Downloads ${megabytes(total)}`}
+            actionLabel={
+              running
+                ? "Installing…"
+                : installed
+                  ? "Installed"
+                  : "Download and install"
+            }
+            disabled={busy || installed}
+            onPress={() => void run(() => install({}))}
+          />
+        ) : null}
+      </SettingsSection>
+      <Components status={status} theme={theme} compact={compact} />
+      {status.loginCommand === undefined ? null : (
+        <SettingsSection title="Sign in to ZCode">
+          <SettingsCard>
+            <SettingsRow label="Run it">
+              <Value color={theme.colors.foreground} compact={compact}>
+                In a terminal on the daemon machine
+              </Value>
+            </SettingsRow>
+            <SettingsRow label="Authorization">
+              <Value color={theme.colors.foreground} compact={compact}>
+                Opens a browser; add --no-browser to print the URL
+              </Value>
+            </SettingsRow>
+            {/* A full-width block: a row value would squeeze the label column. */}
+            <View style={{ padding: compact ? 12 : 16 }}>
+              <Text
+                selectable
+                style={{
+                  color: theme.colors.foreground,
+                  fontFamily: Platform.select({
+                    ios: "Menlo",
+                    default: "monospace",
+                  }),
+                  fontSize: compact ? 12 : 13,
+                  lineHeight: 20,
+                }}
+              >
+                {status.loginCommand}
+              </Text>
+            </View>
+          </SettingsCard>
+        </SettingsSection>
+      )}
+      <SettingsSection title="Remove">
+        <SettingsAction
+          label="Managed runtime"
+          hint={
+            removeMessage ??
+            "Deletes the destination directory. Stop ZCode sessions first. ZCode settings, logins and conversations are kept."
+          }
+          actionLabel={confirmRemove ? "Confirm removal" : "Remove"}
+          disabled={busy}
+          onPress={() => {
+            if (!confirmRemove) {
+              setConfirmRemove(true);
+              return;
+            }
+            setConfirmRemove(false);
+            void run(async () => {
+              const result = await remove({});
+              setRemoveMessage(
+                result.status === "removed"
+                  ? "Removed."
+                  : `Removal failed: ${result.message}`,
+              );
+            });
+          }}
+        />
+      </SettingsSection>
+      {requestError === null ? null : (
+        <SettingsSection title="Last request">
+          <Text
+            accessibilityRole="alert"
+            style={{
+              color: theme.colors.statusDanger,
+              fontSize: compact ? 13 : 14,
+            }}
+          >
+            {requestError}
+          </Text>
+        </SettingsSection>
+      )}
+    </View>
+  );
+}

package/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" fill="currentColor" fill-rule="evenodd"><title>Z.ai</title><path d="M8.07 1.333L6.618 3.302H.435L1.887 1.333h6.184zM15.503 12.699L14.052 14.667h-6.161l1.449-1.968h6.163zM16 1.333L6.176 14.667H0L9.824 1.333H16z"/></svg>

package/index.client.tsx

@@ -0,0 +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 {
+  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 () => {
+    removeSetup();
+    removeDiagnostics();
+  };
+}

package/index.server.ts

@@ -0,0 +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 () => {};
+}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "paseo-plugin-zcode-provider",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Unofficial Paseo provider plugin for ZCode, using the official stdio Services Server of the integrated ZCode CLI.",
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "zcode",
+    "z.ai",
+    "glm"
+  ],
+  "homepage": "https://github.com/supermomonga/paseo-plugin-zcode-provider#readme",
+  "bugs": "https://github.com/supermomonga/paseo-plugin-zcode-provider/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/supermomonga/paseo-plugin-zcode-provider.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "paseo-plugin.json",
+    "index.client.tsx",
+    "index.server.ts",
+    "icon.svg",
+    "client/",
+    "server/",
+    "shared/",
+    "NOTICE.md",
+    "vendor/",
+    "!**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "test": "vitest run",
+    "test:upstream": "node scripts/check-upstream.mjs",
+    "test:runtime": "node scripts/check-runtime.mjs",
+    "test:steering-runtime": "node scripts/check-steering-runtime.mjs",
+    "build": "node scripts/build.mjs",
+    "format": "prettier --write index.client.tsx index.server.ts client server shared scripts test docs README.md NOTICE.md package.json tsconfig.json tsconfig.client.json vitest.config.ts paseo-plugin.json .github/workflows",
+    "format:check": "prettier --check index.client.tsx index.server.ts client server shared scripts test docs README.md NOTICE.md package.json tsconfig.json tsconfig.client.json vitest.config.ts paseo-plugin.json .github/workflows",
+    "check:zcode-releases": "node scripts/check-zcode-releases.mjs",
+    "check:paseo-releases": "node scripts/check-paseo-releases.mjs",
+    "prepare": "node scripts/generate-build-info.mjs",
+    "prebuild": "node scripts/generate-build-info.mjs",
+    "test:model-plan-runtime": "node scripts/check-model-plan-runtime.mjs",
+    "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",
+    "setup:managed-runtime": "node scripts/install-managed-runtime.mjs",
+    "prepack": "node scripts/pack-manifest.mjs prepack",
+    "postpack": "node scripts/pack-manifest.mjs postpack"
+  },
+  "dependencies": {
+    "semver": "7.8.5"
+  },
+  "devDependencies": {
+    "@getpaseo/client": "0.9.0-beta.1",
+    "@getpaseo/plugin": "0.9.0-beta.1",
+    "@getpaseo/protocol": "0.9.0-beta.1",
+    "@types/node": "22.18.3",
+    "@types/react": "~19.2.0",
+    "@types/semver": "7.8.0",
+    "cheerio": "1.2.0",
+    "esbuild": "0.25.12",
+    "prettier": "3.6.2",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "turndown": "7.2.4",
+    "typescript": "5.9.2",
+    "vitest": "3.2.7",
+    "zod": "4.4.3"
+  }
+}

package/paseo-plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "zcode-provider",
+  "requirements": {
+    "paseo": ">=0.8.0"
+  }
+}

package/server/attachments.ts

@@ -0,0 +1,150 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import type { HostBridge } from "./host/bridge.js";
+import type { NativePrompt } from "./mapping.js";
+import { AdapterError } from "./errors.js";
+
+const progress = z.object({
+  uploadId: z.string(),
+  nextChunkIndex: z.number().int().nonnegative(),
+});
+const begun = z.discriminatedUnion("state", [
+  progress.extend({ state: z.literal("staging") }),
+  progress.extend({ state: z.literal("committed"), ref: z.string().min(1) }),
+]);
+const reference = z.object({ ref: z.string().min(1) }).strict();
+const metadata = z.object({
+  fileName: z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(/^[^\0\r\n]+$/),
+  mime: z
+    .string()
+    .min(3)
+    .max(255)
+    .regex(
+      /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/,
+    ),
+  bytes: z
+    .number()
+    .int()
+    .min(0)
+    .max(20 * 1024 * 1024),
+});
+const chunkBytes = 512 * 1024;
+
+/** Transfer validated input to ZCode's persisted attachment store before admission. */
+export async function uploadAttachments(
+  bridge: HostBridge,
+  workspacePath: string,
+  sessionId: string,
+  attachments: NativePrompt["attachments"],
+  assertSending: () => void,
+) {
+  const refs: Array<z.infer<typeof metadata> & { ref: string }> = [];
+  for (const attachment of attachments) {
+    assertSending();
+    const info = metadata.safeParse({
+      fileName: attachment.filename,
+      mime: attachment.mimeType,
+      bytes: attachment.sizeBytes,
+    });
+    if (!info.success)
+      throw new AdapterError(
+        "UNSUPPORTED_CONTENT",
+        "Attachment exceeds ZCode's size limit or has invalid metadata",
+      );
+    if (
+      !attachment.localPath &&
+      (attachment.dataBase64 === undefined ||
+        !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+          attachment.dataBase64,
+        ))
+    )
+      throw new AdapterError(
+        "UNSUPPORTED_CONTENT",
+        "Attachment has invalid base64 data",
+      );
+    const data = attachment.localPath
+      ? await readFile(attachment.localPath)
+      : Buffer.from(attachment.dataBase64!, "base64");
+    if (data.length !== info.data.bytes)
+      throw new AdapterError(
+        "UNSUPPORTED_CONTENT",
+        "Attachment changed after validation",
+      );
+    const uploadId = randomUUID();
+    const target = { workspacePath, sessionId, uploadId };
+    try {
+      const start = await bridge.request(
+        "attachmentBeginV4",
+        {
+          ...target,
+          fileName: info.data.fileName,
+          mime: info.data.mime,
+          totalBytes: data.length,
+          totalChunks: Math.ceil(data.length / chunkBytes),
+          checksum: `sha256:${createHash("sha256").update(data).digest("hex")}`,
+        },
+        begun,
+      );
+      if (
+        start.uploadId !== uploadId ||
+        start.state !== "staging" ||
+        start.nextChunkIndex !== 0
+      )
+        throw new AdapterError(
+          "NATIVE_PROTOCOL_ERROR",
+          "Unexpected attachment upload acknowledgement",
+        );
+      for (
+        let offset = 0, chunkIndex = 0;
+        offset < data.length;
+        offset += chunkBytes, chunkIndex++
+      ) {
+        assertSending();
+        const chunk = await bridge.request(
+          "attachmentChunkV4",
+          {
+            ...target,
+            chunkIndex,
+            dataBase64: data
+              .subarray(offset, offset + chunkBytes)
+              .toString("base64"),
+          },
+          progress,
+        );
+        if (
+          chunk.uploadId !== uploadId ||
+          chunk.nextChunkIndex !== chunkIndex + 1
+        )
+          throw new AdapterError(
+            "NATIVE_PROTOCOL_ERROR",
+            "Unexpected attachment chunk acknowledgement",
+          );
+      }
+      assertSending();
+      const committed = await bridge.request(
+        "attachmentCommitV4",
+        target,
+        reference,
+      );
+      refs.push({ ...info.data, ref: committed.ref });
+    } catch (error) {
+      // Abort staged bytes; never retry a command whose result is unknown.
+      try {
+        await bridge.request(
+          "attachmentAbortV4",
+          target,
+          z.object({}).strict(),
+        );
+      } catch {
+        /* The host expires staging storage after disconnection. */
+      }
+      throw error;
+    }
+  }
+  return refs;
+}

package/server/build-info.ts

@@ -0,0 +1,2 @@
+// Generated from package.json by npm prepare / prebuild.
+export const PROVIDER_VERSION = "0.1.0";