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

package/server/conversation.ts

@@ -0,0 +1,319 @@
+import { randomUUID } from "node:crypto";
+import { applyConversationDeltas } from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/apply.js";
+import { TopicWireFrameAssembler } from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-assembler.js";
+import {
+  commandAckSchema,
+  parseCommandEnvelope,
+} from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/command.js";
+import {
+  conversationTopicFrameSchema,
+  v4ConversationResyncResultSchema,
+  v4ConversationRowsRangeResultSchema,
+  type ConversationTopicFrame,
+  type ConversationTopicWireCandidate,
+} from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.js";
+import type { ConversationSnapshot } from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.js";
+import type { ConversationRow } from "./vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.js";
+import type { HostBridge, HostSubscription } from "./host/bridge.js";
+import { AdapterError } from "./errors.js";
+export type ConversationState = ConversationSnapshot;
+
+/** One authoritative V4 state. No legacy session events participate in it. */
+export class Conversation {
+  state?: ConversationSnapshot;
+  private subscription?: HostSubscription;
+  private readonly assembler = new TopicWireFrameAssembler(
+    conversationTopicFrameSchema,
+  );
+  private expiry?: ReturnType<typeof setTimeout>;
+  private recovery?: Promise<void>;
+  private recovering = false;
+  private hydrating = false;
+  private readonly waiters = new Set<() => void>();
+  private closed = false;
+  private readonly listeners = new Set<() => void>();
+  private failure?: unknown;
+  constructor(
+    private readonly bridge: HostBridge,
+    private readonly workspacePath: string,
+    private readonly sessionId: string,
+    private readonly onFailure: (error: unknown) => void,
+  ) {}
+  async open(): Promise<void> {
+    const early: ConversationTopicWireCandidate[] = [];
+    this.subscription = await this.bridge.subscribe(
+      { workspacePath: this.workspacePath, sessionId: this.sessionId },
+      (frame) => {
+        if (this.subscription) this.accept(frame);
+        else early.push(frame);
+      },
+    );
+    for (const frame of early) this.accept(frame);
+    await this.waitFor(() => this.state !== undefined && !this.recovering);
+    await this.loadHistory();
+  }
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  private changed(): void {
+    for (const waiter of this.waiters) waiter();
+    if (!this.hydrating) for (const listener of this.listeners) listener();
+  }
+  private fail(error: unknown): void {
+    if (this.failure || this.closed) return;
+    this.failure = error;
+    this.changed();
+    this.onFailure(error);
+  }
+  accept(wire: ConversationTopicWireCandidate): void {
+    if (
+      this.closed ||
+      wire.subscriptionId !== this.subscription?.id ||
+      wire.topic !== `conversation/${this.sessionId}`
+    )
+      return;
+    for (const event of this.assembler.accept(wire)) {
+      if (event.kind === "fault") {
+        if (event.fault.deliveryKind === "recovery")
+          this.fail(
+            new AdapterError(
+              "NATIVE_PROTOCOL_ERROR",
+              "ZCode recovery frame is invalid",
+            ),
+          );
+        else this.resync();
+        continue;
+      }
+      if (this.recovering && event.deliveryKind !== "recovery") continue;
+      this.apply(event.frame, event.deliveryKind === "recovery");
+    }
+    this.scheduleExpiry();
+  }
+  private apply(frame: ConversationTopicFrame, recovery: boolean): void {
+    if (frame.payload.kind === "snapshot") {
+      const snapshot = frame.payload.snapshot;
+      if (
+        snapshot.sessionId !== this.sessionId ||
+        snapshot.seq !== frame.toSeq ||
+        frame.fromSeq !== 0
+      ) {
+        this.resync();
+        return;
+      }
+      if (
+        this.state &&
+        !recovery &&
+        (snapshot.logEpoch !== this.state.logEpoch ||
+          snapshot.seq < this.state.seq)
+      ) {
+        this.resync();
+        return;
+      }
+      this.state = snapshot;
+      this.recovering = false;
+    } else {
+      if (!this.state || frame.fromSeq !== this.state.seq) {
+        this.resync();
+        return;
+      }
+      if (frame.toSeq < frame.fromSeq) {
+        this.resync();
+        return;
+      }
+      this.state = {
+        ...applyConversationDeltas(this.state, frame.payload.deltas),
+        seq: frame.toSeq,
+      };
+    }
+    this.changed();
+  }
+  private scheduleExpiry(): void {
+    clearTimeout(this.expiry);
+    const expiry = this.assembler.nextExpiryAt;
+    if (expiry === null) return;
+    this.expiry = setTimeout(
+      () => {
+        if (this.assembler.expire().length) this.resync();
+        this.scheduleExpiry();
+      },
+      Math.max(1, expiry - Date.now()),
+    );
+    this.expiry.unref();
+  }
+  private resync(): void {
+    if (this.closed || this.recovery) return;
+    this.recovering = true;
+    this.hydrating = true;
+    this.recovery = (async () => {
+      await this.bridge.request(
+        "resyncConversationV4",
+        {
+          workspacePath: this.workspacePath,
+          subscriptionId: this.subscription!.id,
+          base: null,
+          forceSnapshot: true,
+        },
+        v4ConversationResyncResultSchema,
+      );
+      await this.waitFor(() => !this.recovering);
+      await this.loadHistory();
+    })()
+      .catch((error) => this.fail(error))
+      .finally(() => {
+        this.recovery = undefined;
+        this.hydrating = false;
+        this.changed();
+      });
+  }
+  async loadHistory(): Promise<void> {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const base = this.state!;
+      let beforeRowId: number | undefined;
+      const rows = new Map<number, ConversationRow>();
+      let consistent = true;
+      do {
+        const page = await this.bridge.request(
+          "conversationRowsRangeV4",
+          {
+            workspacePath: this.workspacePath,
+            sessionId: this.sessionId,
+            limit: 200,
+            ...(beforeRowId === undefined ? {} : { beforeRowId }),
+          },
+          v4ConversationRowsRangeResultSchema,
+        );
+        if (
+          page.atLogEpoch !== base.logEpoch ||
+          page.atRevision !== base.revision ||
+          page.atSeq !== base.seq ||
+          this.state?.logEpoch !== base.logEpoch ||
+          this.state?.seq !== base.seq
+        ) {
+          consistent = false;
+          break;
+        }
+        for (const row of page.rows) rows.set(row.rowId, row);
+        if (!page.hasMore) break;
+        const next = page.rows[0]?.rowId;
+        if (
+          next === undefined ||
+          (beforeRowId !== undefined && next >= beforeRowId)
+        )
+          throw new AdapterError(
+            "NATIVE_PROTOCOL_ERROR",
+            "ZCode history cursor did not advance",
+          );
+        beforeRowId = next;
+      } while (!this.closed);
+      if (this.closed) return;
+      if (consistent) {
+        this.state = {
+          ...base,
+          rows: {
+            ...base.rows,
+            window: [...rows.values()].sort((a, b) => a.rowId - b.rowId),
+          },
+        };
+        this.changed();
+        return;
+      }
+    }
+    throw new AdapterError(
+      "NATIVE_PROTOCOL_ERROR",
+      "ZCode history changed during pagination; no mixed history was published",
+    );
+  }
+  get idle(): boolean {
+    const c = this.state?.control;
+    return (
+      !!c &&
+      !this.recovering &&
+      !this.hydrating &&
+      !c.canStop &&
+      c.activeWorks.length === 0 &&
+      c.phase !== "running" &&
+      c.phase !== "prewarming" &&
+      this.state!.queue.items.length === 0
+    );
+  }
+  waitFor(predicate: () => boolean): Promise<void> {
+    if (this.failure) return Promise.reject(this.failure);
+    if (predicate()) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(
+          new AdapterError(
+            "NATIVE_TIMEOUT",
+            "ZCode did not confirm the requested state",
+          ),
+        );
+      }, 30_000);
+      const off = () => this.waiters.delete(check);
+      const check = () => {
+        if (this.failure || this.closed || predicate()) {
+          clearTimeout(timer);
+          off();
+          this.failure
+            ? reject(this.failure)
+            : this.closed
+              ? reject(new AdapterError("NATIVE_EXITED", "Conversation closed"))
+              : resolve();
+        }
+      };
+      this.waiters.add(check);
+      check();
+    });
+  }
+  async close(): Promise<void> {
+    this.closed = true;
+    clearTimeout(this.expiry);
+    this.assembler.clear();
+    this.changed();
+    await this.subscription?.dispose();
+    this.listeners.clear();
+  }
+}
+export async function conversationCommand(
+  bridge: HostBridge,
+  workspacePath: string,
+  sessionId: string,
+  type: string,
+  payload: unknown,
+  options: { commandId?: string; revision?: number } = {},
+) {
+  const commandId = options.commandId ?? randomUUID();
+  const envelope = {
+    commandId,
+    clientId: "paseo-zcode-provider",
+    sessionId,
+    type,
+    payload,
+    issuedAt: Date.now(),
+    ...(options.revision === undefined
+      ? {}
+      : { baseRevision: options.revision }),
+  };
+  const validated = parseCommandEnvelope(envelope);
+  if (!validated.ok)
+    throw new AdapterError(
+      "NATIVE_PROTOCOL_ERROR",
+      "Invalid ZCode command",
+      {},
+      { cause: validated.error },
+    );
+  const ack = await bridge.request(
+    "sendConversationCommandV4",
+    { workspacePath, envelope },
+    commandAckSchema,
+    60_000,
+    { sessionId, inputId: commandId },
+  );
+  if (ack.commandId !== commandId)
+    throw new AdapterError(
+      "NATIVE_PROTOCOL_ERROR",
+      "ZCode acknowledged a different command",
+    );
+  return ack;
+}

package/server/diagnostics.ts

@@ -0,0 +1,235 @@
+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",
+  "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);
+}