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

package/server/diagnostics.ts

@@ -0,0 +1,252 @@
+import { z } from "zod";
+import { valid } from "semver";
+import { PROVIDER_VERSION as providerVersion } from "./build-info.js";
+import { AdapterError, type ZCodeErrorCode } from "./errors.js";
+import type { DiscoveredRuntime } from "./discovery/types.js";
+
+const stages = [
+  "discovery",
+  "version",
+  "host-inspection",
+  "smoke",
+  "host-start",
+  "request",
+  "response",
+  "notification",
+  "transport",
+  "session",
+] as const;
+const checks = [
+  "bundle-metadata",
+  "minimum-version",
+  "host-entry",
+  "host-imports",
+  "host-path",
+  "rpc-module-load",
+  "rpc-missing",
+  "rpc-ambiguous",
+  "host-inspection-result",
+  "cli-smoke",
+  "native-envelope",
+  "native-result",
+  "native-event",
+  "native-error",
+  "native-exit",
+  "request-timeout",
+  "request-write",
+] as const;
+const operations = new Set([
+  "initialize",
+  "readWorkspacePresentation",
+  "readModelSelection",
+  "createSession",
+  "resumeSession",
+  "listSessions",
+  "readSession",
+  "closeSession",
+  "disposeWorkspace",
+  "cancelGeneration",
+  "respondStructuredInput",
+  "respondPermission",
+  "getEntitlementSnapshot",
+  "getCodingPlanResetStatus",
+  "helloConversationV4",
+  "initializeConversationV4",
+  "syncAppRuntimePreferences",
+  "sendConversationCommandV4",
+  "subscribeConversationV4",
+  "unsubscribeConversationV4",
+  "resyncConversationV4",
+  "conversationRowsRangeV4",
+  "attachmentBeginV4",
+  "attachmentChunkV4",
+  "attachmentCommitV4",
+  "attachmentAbortV4",
+  "oauth.restoreCachedSessionState",
+  "oauth.getActiveProvider",
+  "oauth.startOAuthWithPolling",
+  "oauth.pollPendingOAuth",
+  "oauth.cancelPending",
+  "oauth.logout",
+  "setting.get",
+  "setting.update",
+  "provider-settings.getView",
+  "provider-settings.refresh",
+  "provider-settings.createPersonalProvider",
+  "provider-settings.savePersonalProviderOverlay",
+  "provider-settings.deletePersonalProvider",
+  "provider-settings.addPersonalModel",
+  "provider-settings.deletePersonalModel",
+  "provider-settings.setPersonalModelEnabled",
+  "usage-stats.getEntitlementSnapshot",
+  "event",
+  "catalog",
+  "session.create",
+  "session.resume",
+  "session.list",
+  "session.prompt",
+  "session.configure",
+  "session.close",
+  "session.cancel",
+  "session.permission.respond",
+  "session.open",
+  "session.interrupt",
+  "session.permission",
+]);
+// Paths from record/map keys can contain user data. Only fixed schema field names are reportable.
+const schemaFields = new Set([
+  "id",
+  "type",
+  "method",
+  "params",
+  "result",
+  "error",
+  "code",
+  "message",
+  "subscriptionId",
+  "event",
+  "sessionId",
+  "turnId",
+  "seq",
+  "payload",
+  "kind",
+  "delta",
+  "status",
+  "models",
+  "settings",
+  "mode",
+  "current",
+  "thoughtLevel",
+  "model",
+  "provider",
+  "providers",
+  "options",
+  "request",
+  "workspacePath",
+  "sessions",
+  "items",
+  "usage",
+  "data",
+  "name",
+  "role",
+  "content",
+  "requestId",
+  "toolCallId",
+]);
+
+export interface RuntimeDiagnostic {
+  readonly appVersion?: string;
+  readonly cliVersion?: string;
+  readonly platform?: string;
+  readonly stage?: (typeof stages)[number];
+  readonly operation?: string;
+  readonly check?: (typeof checks)[number];
+  readonly serverSha256?: string;
+  readonly cliSha256?: string;
+  readonly nativeCode?: number;
+  readonly exitCode?: number;
+  readonly validation?: readonly { path: string; code: string }[];
+}
+
+export function runtimeDiagnostic(
+  runtime: DiscoveredRuntime,
+): RuntimeDiagnostic {
+  return {
+    appVersion: runtime.identity.appVersion,
+    cliVersion: runtime.identity.cliVersion,
+    platform: runtime.identity.platform,
+    serverSha256: runtime.identity.serverSha256,
+    cliSha256: runtime.identity.cliSha256,
+  };
+}
+
+export function diagnosticError(
+  error: unknown,
+  context: RuntimeDiagnostic,
+  defaultCode: ZCodeErrorCode = "NATIVE_PROTOCOL_ERROR",
+): AdapterError {
+  const diagnostic = {
+    ...context,
+    ...(error instanceof AdapterError ? error.diagnostic : {}),
+  };
+  const cause = error instanceof AdapterError ? error.cause : error;
+  if (cause instanceof z.ZodError) {
+    diagnostic.validation = cause.issues.slice(0, 10).map((issue) => ({
+      path: issue.path
+        .map((part) =>
+          typeof part === "number"
+            ? "[]"
+            : schemaFields.has(String(part))
+              ? String(part)
+              : "*",
+        )
+        .join("."),
+      code: issue.code,
+    }));
+  }
+  return new AdapterError(
+    error instanceof AdapterError ? error.code : defaultCode,
+    error instanceof AdapterError ? error.message : "ZCode operation failed",
+    error instanceof AdapterError ? error.details : {},
+    { cause: error },
+    diagnostic,
+  );
+}
+
+export function formatDiagnostic(error: unknown): string {
+  const context = error instanceof AdapterError ? error.diagnostic : undefined;
+  const result: Record<string, unknown> = {
+    providerVersion,
+    code: error instanceof AdapterError ? error.code : "NATIVE_PROTOCOL_ERROR",
+  };
+  if (context) {
+    for (const key of ["appVersion", "cliVersion"] as const) {
+      const value = context[key];
+      if (value && valid(value)) result[key] = valid(value);
+    }
+    if (
+      context.platform &&
+      /^(darwin|linux|win32)-(arm64|x64|ia32)$/u.test(context.platform)
+    )
+      result.platform = context.platform;
+    if (context.stage && stages.includes(context.stage))
+      result.stage = context.stage;
+    if (context.check && checks.includes(context.check))
+      result.check = context.check;
+    if (context.operation && operations.has(context.operation))
+      result.operation = context.operation;
+    for (const key of ["serverSha256", "cliSha256"] as const) {
+      if (/^[a-f0-9]{64}$/u.test(context[key] ?? ""))
+        result[key] = context[key];
+    }
+    for (const key of ["nativeCode", "exitCode"] as const) {
+      if (Number.isSafeInteger(context[key])) result[key] = context[key];
+    }
+    if (context.validation)
+      result.validation = context.validation.slice(0, 10).map((issue) => ({
+        path: issue.path
+          .split(".")
+          .slice(0, 20)
+          .map((part) =>
+            schemaFields.has(part) || part === "[]" || part === "" ? part : "*",
+          )
+          .join("."),
+        code: [
+          "invalid_type",
+          "too_big",
+          "too_small",
+          "invalid_format",
+          "not_multiple_of",
+          "unrecognized_keys",
+          "invalid_union",
+          "invalid_key",
+          "invalid_element",
+          "invalid_value",
+          "custom",
+        ].includes(issue.code)
+          ? issue.code
+          : "custom",
+      }));
+  }
+  return JSON.stringify(result, null, 2);
+}

package/server/discovery/discover.ts

@@ -0,0 +1,225 @@
+import { execFile } from "node:child_process";
+import { access, constants, readFile, realpath, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+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";
+
+export interface DiscoveryOptions {
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+}
+export function runtimeEnvironment(
+  environment: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+  const result = { ...environment };
+  delete result.ELECTRON_RUN_AS_NODE;
+  return result;
+}
+async function run(
+  executable: string,
+  args: string[],
+  environment: NodeJS.ProcessEnv,
+  signal?: AbortSignal,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      executable,
+      args,
+      {
+        env: environment,
+        signal,
+        timeout: 15_000,
+        maxBuffer: 64 * 1024,
+        windowsHide: true,
+      },
+      (error, stdout) => {
+        if (error)
+          reject(
+            new AdapterError(
+              "RUNTIME_SMOKE_FAILED",
+              "Configured ZCode executable failed its runtime check",
+            ),
+          );
+        else resolve(stdout.trim());
+      },
+    );
+  });
+}
+// 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. Install it in Settings → Plugins → zcode-provider → Settings → Runtime.",
+    );
+  return { ...managed, source: "managed" };
+}
+export async function discoverRuntime({
+  environment = process.env,
+  signal,
+}: DiscoveryOptions = {}): Promise<DiscoveredRuntime> {
+  const configured = await configuredPaths(environment);
+  try {
+    const installRoot = await realpath(configured.installRoot);
+    const executable = await realpath(configured.executable);
+    if (
+      !(await stat(installRoot)).isDirectory() ||
+      !(await stat(executable)).isFile()
+    )
+      throw new Error("Invalid runtime path");
+    await access(executable, constants.X_OK);
+    const paths = {
+      installRoot,
+      executable,
+      serverEntry: join(installRoot, "server/remote/zcode-server.cjs"),
+      cliEntry: join(installRoot, "agent/zcode.cjs"),
+      appPackage: join(installRoot, "package.json"),
+      builtinProviderConfig: join(
+        installRoot,
+        "agent/provider/zcode-builtin.json",
+      ),
+    };
+    for (const file of [
+      paths.serverEntry,
+      paths.cliEntry,
+      paths.appPackage,
+      paths.builtinProviderConfig,
+    ])
+      if (!(await stat(file)).isFile()) throw new Error("Missing runtime file");
+    // Run Electron in Node mode only during identification, so a mistaken path
+    // cannot launch its desktop UI. It is rejected before any Server starts.
+    const node = z
+      .object({
+        node: z.string(),
+        electron: z.string().optional(),
+        platform: z.string(),
+        arch: z.string(),
+      })
+      .parse(
+        JSON.parse(
+          await run(
+            executable,
+            [
+              "-e",
+              "console.log(JSON.stringify({node:process.versions.node,electron:process.versions.electron,platform:process.platform,arch:process.arch}))",
+            ],
+            { ...environment, ELECTRON_RUN_AS_NODE: "1" },
+            signal,
+          ),
+        ),
+      );
+    if (
+      node.electron ||
+      !valid(node.node) ||
+      !gte(node.node, MINIMUM_NODE_VERSION)
+    )
+      throw new AdapterError(
+        "UNSUPPORTED_ZCODE",
+        `PASEO_ZCODE_NODE requires ordinary Node.js >=${MINIMUM_NODE_VERSION}; Electron is unsupported`,
+      );
+    const pkg = z
+      .object({ name: z.literal("zcode-runtime"), version: z.string() })
+      .parse(JSON.parse(await readFile(paths.appPackage, "utf8")));
+    const env = runtimeEnvironment(environment);
+    const [serverVersion, cliOutput, serverBytes, cliBytes] = await Promise.all(
+      [
+        run(executable, [paths.serverEntry, "--version"], env, signal),
+        run(executable, [paths.cliEntry, "--version"], env, signal),
+        readFile(paths.serverEntry),
+        readFile(paths.cliEntry),
+      ],
+    );
+    if (serverVersion !== pkg.version)
+      throw new AdapterError(
+        "UNSUPPORTED_ZCODE",
+        "ZCode runtime package and Server versions differ",
+      );
+    const cliVersion = cliOutput.match(
+      /^(?:zcode\s+)?v?(\d+\.\d+\.\d+(?:-[\w.-]+)?)$/i,
+    )?.[1];
+    if (!cliVersion)
+      throw new AdapterError(
+        "UNSUPPORTED_ZCODE",
+        "ZCode Agent returned an invalid version",
+      );
+    const identity = {
+      platform: `${node.platform}-${node.arch}`,
+      appVersion: serverVersion,
+      cliVersion,
+      nodeVersion: node.node,
+      cliSha256: createHash("sha256").update(cliBytes).digest("hex"),
+      serverSha256: createHash("sha256").update(serverBytes).digest("hex"),
+    };
+    const compatibility = assessCompatibility(identity);
+    return {
+      source: configured.source,
+      paths,
+      identity,
+      compatibility: compatibility.status,
+      compatibilityReason: compatibility.reason,
+      writableInstallRoot: await access(installRoot, constants.W_OK).then(
+        () => true,
+        () => false,
+      ),
+    };
+  } catch (error) {
+    if (error instanceof AdapterError || signal?.aborted) throw error;
+    throw new AdapterError(
+      "RUNTIME_DISCOVERY_FAILED",
+      "Configured ZCode runtime is missing required files or has invalid metadata",
+    );
+  }
+}
+export function assertRuntimeSupported(runtime: DiscoveredRuntime): void {
+  if (runtime.compatibility !== "supported")
+    throw new AdapterError("UNSUPPORTED_ZCODE", runtime.compatibilityReason);
+}
+export async function runRuntimeSmoke(
+  runtime: DiscoveredRuntime,
+  environment: NodeJS.ProcessEnv = process.env,
+  signal?: AbortSignal,
+): Promise<RuntimeSmokeResult> {
+  // Discovery checks both executable versions. Protocol and V4 are checked by
+  // the real Server connection, without inspecting an embedded bundle export.
+  try {
+    assertRuntimeSupported(runtime);
+    const version = await run(
+      runtime.paths.executable,
+      [runtime.paths.serverEntry, "--version"],
+      runtimeEnvironment(environment),
+      signal,
+    );
+    return {
+      passed: version === runtime.identity.appVersion,
+      cliVersion: runtime.identity.cliVersion,
+    };
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return { passed: false, error: "ZCode runtime check failed" };
+  }
+}

package/server/discovery/manifest.ts

@@ -0,0 +1,36 @@
+import { gte, parse } from "semver";
+import type { RuntimeIdentity } from "./types.js";
+
+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";
+
+export function assessCompatibility(identity: RuntimeIdentity): {
+  status: "supported" | "unsupported";
+  reason: string;
+} {
+  for (const [component, version, minimum] of [
+    ["app", identity.appVersion, MINIMUM_ZCODE_VERSION.app],
+    ["CLI", identity.cliVersion, MINIMUM_ZCODE_VERSION.cli],
+  ] as const) {
+    const parsed = version === undefined ? null : parse(version);
+    if (
+      parsed === null ||
+      parsed.prerelease.length !== 0 ||
+      !gte(parsed, minimum)
+    ) {
+      return {
+        status: "unsupported",
+        reason: `ZCode ${component} requires a stable version >=${minimum}`,
+      };
+    }
+  }
+  return {
+    status: "supported",
+    reason:
+      "ZCode Server and Agent meet the minimum stable versions; runtime compatibility is checked during use",
+  };
+}
+
+// Last reviewed public changelog release; source versions are not releases.
+export const LAST_REVIEWED_ZCODE_RELEASE = "3.14.4";

package/server/discovery/types.ts

@@ -0,0 +1,30 @@
+export interface RuntimePaths {
+  readonly installRoot: string;
+  readonly executable: string;
+  readonly cliEntry: string;
+  readonly serverEntry: string;
+  readonly appPackage: string;
+  readonly builtinProviderConfig: string;
+}
+export interface RuntimeIdentity {
+  readonly platform: string;
+  readonly appVersion: string;
+  readonly cliVersion: string;
+  readonly nodeVersion: string;
+  readonly cliSha256: string;
+  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";
+  readonly compatibilityReason: string;
+  readonly writableInstallRoot: boolean;
+}
+export interface RuntimeSmokeResult {
+  readonly passed: boolean;
+  readonly cliVersion?: string;
+  readonly error?: string;
+}

package/server/errors.ts

@@ -0,0 +1,36 @@
+export type ZCodeErrorCode =
+  | "PERSISTENCE_INVALID"
+  | "PERSISTENCE_WRITE_FAILED"
+  | "PERSISTENCE_VERSION_UNSUPPORTED"
+  | "INVALID_CONFIGURATION"
+  | "INVALID_WORKSPACE"
+  | "UNSUPPORTED_PLATFORM"
+  | "UNSUPPORTED_ZCODE"
+  | "RUNTIME_DISCOVERY_FAILED"
+  | "RUNTIME_SMOKE_FAILED"
+  | "RUNTIME_SETUP_REQUIRED"
+  | "RUNTIME_SETUP_FAILED"
+  | "NATIVE_PROTOCOL_ERROR"
+  | "NATIVE_INPUT_REJECTED"
+  | "NATIVE_TIMEOUT"
+  | "NATIVE_EXITED"
+  | "AUTH_REQUIRED"
+  | "UNSUPPORTED_CONTENT"
+  | "SESSION_NOT_FOUND"
+  | "SESSION_BUSY"
+  | "INTERACTION_UNSUPPORTED";
+
+export class AdapterError extends Error {
+  override readonly name = "ZCodeProviderError";
+
+  constructor(
+    readonly code: ZCodeErrorCode,
+    message: string,
+    readonly details: Record<string, unknown> = {},
+    options?: ErrorOptions,
+    readonly diagnostic?: RuntimeDiagnostic,
+  ) {
+    super(message, options);
+  }
+}
+import type { RuntimeDiagnostic } from "./diagnostics.js";