paseo-plugin-zcode-provider 0.1.0 → 0.2.0

package/server/build-info.ts

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

package/server/diagnostics.ts

@@ -62,6 +62,23 @@ const operations = new Set([
   "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",

package/server/discovery/discover.ts

@@ -75,7 +75,7 @@ async function configuredPaths(environment: NodeJS.ProcessEnv): Promise<{
   if (managed === undefined)
     throw new AdapterError(
       "RUNTIME_SETUP_REQUIRED",
-      "ZCode runtime is not set up. Open Settings → Plugins → zcode-provider to set it up.",
+      "ZCode runtime is not set up. Install it in Settings → Plugins → zcode-provider → Settings → Runtime.",
     );
   return { ...managed, source: "managed" };
 }

package/server/discovery/manifest.ts

@@ -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.14.3";
+export const LAST_REVIEWED_ZCODE_RELEASE = "3.14.4";

package/server/host/bridge.ts

@@ -28,6 +28,12 @@ import {
 import type { Logger } from "../logger.js";
 import { PROVIDER_VERSION } from "../build-info.js";
 
+export type SettingsChannel =
+  | "oauth"
+  | "setting"
+  | "provider-settings"
+  | "usage-stats";
+
 export interface HostSubscription {
   readonly id: string;
   dispose(): Promise<void>;
@@ -265,7 +271,7 @@ export class ZCodeHostBridge implements HostBridge {
       }) + "\n",
     );
     const v4 = helloMessageSchema.parse(
-      await this.call("zcode-agent", "helloConversationV4", undefined, 10_000),
+      await this.call("zcode-agent", "helloConversationV4", [], 10_000),
     );
     if (
       v4.clientMode !== "desktop-continuous" ||
@@ -278,18 +284,20 @@ export class ZCodeHostBridge implements HostBridge {
     await this.call(
       "zcode-agent",
       "initializeConversationV4",
-      {
-        kind: "clientHello",
-        protocolVersion: 3,
-        clientId: "paseo-zcode-provider",
-        appVersion: PROVIDER_VERSION,
-      },
+      [
+        {
+          kind: "clientHello",
+          protocolVersion: 3,
+          clientId: "paseo-zcode-provider",
+          appVersion: PROVIDER_VERSION,
+        },
+      ],
       10_000,
     );
     await this.call(
       "zcode-agent",
       "syncAppRuntimePreferences",
-      { askUserQuestionAutoResolutionEnabled: false },
+      [{ askUserQuestionAutoResolutionEnabled: false }],
       10_000,
     );
   }
@@ -314,7 +322,7 @@ export class ZCodeHostBridge implements HostBridge {
   private async call(
     channel: string,
     method: string,
-    params: unknown,
+    args: readonly unknown[],
     timeoutMs: number,
   ): Promise<unknown> {
     if (!this.client)
@@ -323,13 +331,7 @@ export class ZCodeHostBridge implements HostBridge {
     let timer: ReturnType<typeof setTimeout> | undefined;
     try {
       return await Promise.race([
-        this.client
-          .getChannel(channel)
-          .call(
-            method,
-            params === undefined ? [] : [params],
-            cancellation.token,
-          ),
+        this.client.getChannel(channel).call(method, args, cancellation.token),
         new Promise<never>((_, reject) => {
           timer = setTimeout(() => {
             reject(new AdapterError("NATIVE_TIMEOUT", "ZCode RPC timed out"));
@@ -342,6 +344,12 @@ export class ZCodeHostBridge implements HostBridge {
       cancellation.dispose();
     }
   }
+  private async ensureOpen(): Promise<void> {
+    await this.ready;
+    if (this.failure) throw this.failure;
+    if (this.closing)
+      throw new AdapterError("NATIVE_EXITED", "ZCode Server is closing");
+  }
   async request<Schema extends z.ZodType>(
     method: string,
     params: unknown,
@@ -349,14 +357,12 @@ export class ZCodeHostBridge implements HostBridge {
     timeoutMs = 30_000,
   ): Promise<z.output<Schema>> {
     try {
-      await this.ready;
-      if (this.failure) throw this.failure;
-      if (this.closing)
-        throw new AdapterError("NATIVE_EXITED", "ZCode Server is closing");
+      await this.ensureOpen();
+      const args = params === undefined ? [] : [params];
       let result: unknown;
       if (method === "readModelSelection")
         result = projectModelSelection(
-          await this.call("model-selection", "getView", params, timeoutMs),
+          await this.call("model-selection", "getView", args, timeoutMs),
         );
       else
         result = await this.call(
@@ -365,7 +371,7 @@ export class ZCodeHostBridge implements HostBridge {
             ? "usage-stats"
             : "zcode-agent",
           method,
-          params,
+          args,
           timeoutMs,
         );
       return resultSchema.parse(result);
@@ -377,6 +383,27 @@ export class ZCodeHostBridge implements HostBridge {
       });
     }
   }
+  /** Calls an official account or settings service with positional arguments. */
+  async invoke<Schema extends z.ZodType>(
+    channel: SettingsChannel,
+    method: string,
+    args: readonly unknown[],
+    resultSchema: Schema,
+    timeoutMs = 30_000,
+  ): Promise<z.output<Schema>> {
+    try {
+      await this.ensureOpen();
+      return resultSchema.parse(
+        await this.call(channel, method, args, timeoutMs),
+      );
+    } catch (error) {
+      throw diagnosticError(error, {
+        ...this.diagnostic,
+        stage: "request",
+        operation: `${channel}.${method}`,
+      });
+    }
+  }
   async subscribe(
     target: { workspacePath: string; sessionId: string },
     handler: (frame: ConversationTopicWireCandidate) => Promise<void> | void,

package/server/presentation.ts

@@ -8,6 +8,7 @@ import type {
 } from "@getpaseo/plugin/server/provider";
 import type {
   ConversationRow,
+  HookInvocationRow,
   TimelineMarkerPayload,
 } from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.js";
 import type {
@@ -160,13 +161,12 @@ export function rowTimeline(
         message: `${row.displayName} (${row.artifactType}, ${row.sizeBytes} bytes)`,
       };
     case "hookInvocation":
-      return {
-        id,
-        type: "notification",
-        level: "info",
-        message: `${row.hookEventName}: ${row.executions.map((h) => `${h.displayName} (${h.outcome ?? h.state})`).join(", ")}`,
-      };
+      return hookTimeline(id, row);
     case "timelineMarker":
+      // Paseo appends every notification it receives, so a changing row is
+      // reported once, in its final state.
+      if (row.marker.type === "compact" && row.marker.status === "running")
+        return;
       return {
         id,
         type: "notification",
@@ -175,6 +175,48 @@ export function rowTimeline(
       };
   }
 }
+// Like ZCode Desktop, which keeps hooks out of the conversation and lists
+// them on request, successful hooks are not shown. Paseo appends every
+// notification it receives, so an invocation is reported once, after it ends,
+// and only when a hook that ran did not succeed.
+function hookTimeline(
+  id: string,
+  row: HookInvocationRow,
+): ProviderTimelineItem | undefined {
+  if (
+    row.state === "running" ||
+    row.executions.some((h) => h.state === "running")
+  )
+    return;
+  const problems = row.executions.flatMap((hook) => {
+    if (!hook.didExecute) return [];
+    const outcome =
+      hook.outcome && hook.outcome !== "success"
+        ? hook.outcome
+        : hook.state === "failed"
+          ? "failed"
+          : undefined;
+    return outcome ? [{ hook, outcome }] : [];
+  });
+  if (problems.length === 0) return;
+  const outcomes = new Set(problems.map((p) => p.outcome));
+  return {
+    id,
+    type: "notification",
+    level: outcomes.has("failed")
+      ? "error"
+      : outcomes.has("blocked") || outcomes.has("timed_out")
+        ? "warning"
+        : "info",
+    message: `${row.hookEventName} hook ${problems
+      .map(
+        ({ hook, outcome }) =>
+          `${outcome.replace("_", " ")}: ${hook.displayName}${hook.blockReason ? ` (${hook.blockReason})` : ""}`,
+      )
+      .join("; ")}`,
+  };
+}
+
 export function usage(state: ConversationSnapshot): ProviderUsage {
   return {
     inputTokens: state.usage.cumulative.inputTokens,

package/server/provider-status.ts

@@ -0,0 +1,81 @@
+import type {
+  ProviderStatus,
+  ProviderStatusRequest,
+} from "@getpaseo/plugin/server/provider";
+import {
+  assertRuntimeSupported,
+  discoverRuntime,
+} from "./discovery/discover.js";
+import { AdapterError } from "./errors.js";
+import { logger } from "./logger.js";
+
+export interface RuntimeStatusOptions {
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly discover?: typeof discoverRuntime;
+  /** How long a result is reused. Paseo asks on every catalog load and agent start. */
+  readonly ttlMs?: number;
+  readonly now?: () => number;
+}
+
+// Same shape as Paseo's built-in provider diagnostics; the daemon appends the
+// model count and snapshot status as further indented lines.
+const format = (entries: readonly [string, string][]) =>
+  ["ZCode", ...entries.map(([label, value]) => `  ${label}: ${value}`)].join(
+    "\n",
+  );
+
+async function check(
+  environment: NodeJS.ProcessEnv,
+  discover: typeof discoverRuntime,
+): Promise<ProviderStatus> {
+  try {
+    const runtime = await discover({ environment });
+    assertRuntimeSupported(runtime);
+    const { appVersion, cliVersion, nodeVersion, platform } = runtime.identity;
+    return {
+      available: true,
+      diagnostic: format([
+        [
+          "Runtime",
+          `${runtime.source === "managed" ? "managed" : "PASEO_ZCODE_RUNTIME"}, Server ${appVersion}, Agent ${cliVersion}`,
+        ],
+        ["Node.js", nodeVersion],
+        ["Platform", platform],
+      ]),
+    };
+  } catch (error) {
+    // Discovery errors carry fixed messages; anything else stays in the log.
+    if (!(error instanceof AdapterError))
+      logger.error("zcode.provider.status.failed", error);
+    return {
+      available: false,
+      diagnostic: format([
+        [
+          "Error",
+          error instanceof AdapterError
+            ? error.message
+            : "ZCode runtime could not be inspected",
+        ],
+      ]),
+    };
+  }
+}
+
+/**
+ * Availability for Paseo's provider snapshot and diagnostics (Paseo 0.11+;
+ * older daemons ignore it). It inspects the runtime without starting a Server,
+ * so sign-in problems still surface when a session opens.
+ */
+export function createRuntimeStatus(options: RuntimeStatusOptions = {}) {
+  const environment = options.environment ?? process.env;
+  const discover = options.discover ?? discoverRuntime;
+  const ttlMs = options.ttlMs ?? 30_000;
+  const now = options.now ?? Date.now;
+  let cached: { at: number; result: Promise<ProviderStatus> } | undefined;
+  return (_request?: ProviderStatusRequest): Promise<ProviderStatus> => {
+    if (cached && now() - cached.at < ttlMs) return cached.result;
+    const entry = { at: now(), result: check(environment, discover) };
+    cached = entry;
+    return entry.result;
+  };
+}

package/server/provider.ts

@@ -27,6 +27,7 @@ import {
   runRuntimeSmoke,
 } from "./discovery/discover.js";
 import { ZCodeHostBridge, type HostBridge } from "./host/bridge.js";
+import { createRuntimeStatus } from "./provider-status.js";
 import { logger } from "./logger.js";
 import { MINIMUM_ZCODE_VERSION } from "./discovery/manifest.js";
 import {
@@ -68,11 +69,11 @@ export type BridgeFactory = (
   workspace?: string,
 ) => Promise<HostBridge>;
 
-async function createHost(
+export async function createHost(
   environment: Readonly<Record<string, string>>,
   signal: AbortSignal,
   workspace?: string,
-): Promise<HostBridge> {
+): Promise<ZCodeHostBridge> {
   const env = { ...process.env, ...environment };
   const runtime = await discoverRuntime({ environment: env, signal });
   assertRuntimeSupported(runtime);
@@ -114,6 +115,7 @@ interface SessionEntry {
 export function createZCodeProvider(
   bridgeFactory: BridgeFactory = createHost,
   persistenceStore = new SessionPersistenceStore(),
+  status: ProviderRegistration["status"] = createRuntimeStatus(),
 ): ProviderRegistration {
   return {
     id: "zcode",
@@ -121,6 +123,9 @@ export function createZCodeProvider(
     description:
       "ZCode workspace agent with native planning, tools, and model selection",
     icon: "icon.svg",
+    // No `command`: Paseo would look it up on PATH, but the runtime is the
+    // plugin's managed installation or the PASEO_ZCODE_* override.
+    status,
     async connect(request) {
       if (!request.versions.includes(PROVIDER_PROTOCOL_VERSION))
         throw new Error("ZCode requires provider protocol version 1");
@@ -812,7 +817,9 @@ function publicError(error: unknown): ProviderError {
     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.",
+      "ZCode runtime is not set up. Install it in Settings → Plugins → zcode-provider → Settings → Runtime.",
+    AUTH_REQUIRED:
+      "No ZCode model provider is usable. Sign in or add a provider in Settings → Plugins → zcode-provider → Settings → Account.",
     PERSISTENCE_VERSION_UNSUPPORTED:
       "ZCode persistence version is unsupported. Create a new Paseo ZCode session.",
     PERSISTENCE_INVALID:

package/server/runtime-setup.ts

@@ -1,4 +1,3 @@
-import { join } from "node:path";
 import type { RuntimeSetupStatus } from "../shared/runtime-setup.js";
 import { AdapterError } from "./errors.js";
 import {
@@ -14,20 +13,6 @@ const LICENSES = {
     "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,
@@ -63,24 +48,14 @@ export function createRuntimeSetupHandlers(
           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-"),
-              ),
-            }
-          : {}),
+        components: [
+          await component(layout.node),
+          await component(layout.zcode),
+        ],
       };
     },
     install: async () => ({ started: installer.start() }),