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

package/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<boolean> {
+  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<void>;
+  readonly nodeVersion?: (executable: string) => Promise<string>;
+}
+
+function execute(file: string, args: string[]): Promise<string> {
+  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<void> {
+  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<void> | undefined;
+  private readonly fetchImpl: typeof fetch;
+  private readonly extract: (
+    archive: string,
+    destination: string,
+  ) => Promise<void>;
+  private readonly nodeVersion: (executable: string) => Promise<string>;
+  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<void> {
+    await this.job;
+  }
+
+  async remove(): Promise<void> {
+    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<void> {
+    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<void>,
+  ): Promise<void> {
+    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<void> {
+    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<void> {
+    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<string> {
+  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}`;

package/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<ManagedPlatform, PinnedArchive>
+> = {
+  "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;
+}

package/server/runtime-setup.ts

@@ -0,0 +1,77 @@
+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;
+
+export function createRuntimeSetupHandlers(
+  installer: ManagedRuntimeInstaller,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const component = async (
+    entry: ManagedComponent,
+  ): Promise<RuntimeSetupStatus["components"][number]> => ({
+    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<RuntimeSetupStatus> {
+      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: [],
+        };
+      return {
+        ...base,
+        supported: true,
+        directory: layout.root,
+        components: [
+          await component(layout.node),
+          await component(layout.zcode),
+        ],
+      };
+    },
+    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",
+        };
+      }
+    },
+  };
+}

package/server/session-types.ts

@@ -0,0 +1,49 @@
+import type {
+  ProviderContent,
+  ProviderPermissionRequest,
+  ProviderPermissionResponse,
+  ProviderTimelineItem,
+  ProviderUsage,
+} from "@getpaseo/plugin/server/provider";
+
+export type NativePromptInput = string | ProviderContent[];
+export type NativeTimelineItem = ProviderTimelineItem;
+export interface NativeTimelineEntry {
+  item: NativeTimelineItem;
+  timestamp?: string;
+}
+
+export type NativeSessionEvent =
+  | {
+      type: "prompt_accepted";
+      clientMessageId: string;
+      turnId: string;
+      delivery: "turn" | "steer";
+    }
+  | ({ type: "timeline"; turnId?: string } & NativeTimelineEntry)
+  | { type: "usage_updated"; usage: ProviderUsage; turnId?: string }
+  | {
+      type: "turn_started" | "turn_completed" | "turn_canceled";
+      turnId: string;
+      usage?: ProviderUsage;
+      reason?: string;
+    }
+  | {
+      type: "turn_failed" | "runtime_failed";
+      turnId?: string;
+      error: string;
+      code?: string;
+      diagnostic?: string;
+    }
+  | {
+      type: "permission_requested";
+      request: ProviderPermissionRequest;
+      turnId?: string;
+    }
+  | {
+      type: "permission_resolved";
+      requestId: string;
+      resolution: ProviderPermissionResponse;
+      turnId?: string;
+    }
+  | { type: "config_changed" };