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

package/server/mapping.ts

@@ -0,0 +1,270 @@
+import type { NativePromptInput } from "./session-types.js";
+import { realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative } from "node:path";
+import { z } from "zod";
+
+import type {
+  ProviderMode,
+  ProviderModel,
+  ProviderMcpServerConfig,
+} from "@getpaseo/plugin/server/provider";
+import { AdapterError } from "./errors.js";
+import type { ModelOption, ModelSelection } from "./host/schemas.js";
+
+export const ZCODE_PROVIDER_ID = "zcode";
+export const ZCODE_MODES: ProviderMode[] = [
+  {
+    id: "build",
+    label: "Ask Before Changes",
+    description: "Ask before changing files or running tools",
+  },
+  {
+    id: "edit",
+    label: "Edit Automatically",
+    description: "Edit files automatically while keeping other approvals",
+  },
+  {
+    id: "yolo",
+    label: "Full Access",
+    description: "Run tools without approval",
+  },
+];
+
+export function requireMode(mode: string): string {
+  if (
+    mode !== "plan" &&
+    !ZCODE_MODES.some((candidate) => candidate.id === mode)
+  ) {
+    throw new AdapterError(
+      "NATIVE_PROTOCOL_ERROR",
+      `ZCode returned an unknown mode: ${mode}`,
+    );
+  }
+  return mode;
+}
+
+export function encodeModel(model: ModelSelection): string {
+  return JSON.stringify([model.providerId, model.modelId, null]);
+}
+
+export function decodeModel(value: string): ModelSelection {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new AdapterError("INVALID_CONFIGURATION", "Invalid ZCode model ID");
+  }
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length !== 3 ||
+    typeof parsed[0] !== "string" ||
+    parsed[0].length === 0 ||
+    typeof parsed[1] !== "string" ||
+    parsed[1].length === 0 ||
+    parsed[2] !== null
+  ) {
+    throw new AdapterError("INVALID_CONFIGURATION", "Invalid ZCode model ID");
+  }
+  return {
+    providerId: parsed[0],
+    modelId: parsed[1],
+  };
+}
+
+export function catalogModels(
+  available: readonly ModelOption[],
+  selection?: ModelSelection,
+): ProviderModel[] {
+  const ids = new Set<string>();
+  const current = selection && encodeModel(selection);
+  const models = available.map((model) => {
+    const id = encodeModel(model.ref);
+    if (ids.has(id)) {
+      throw new AdapterError(
+        "NATIVE_PROTOCOL_ERROR",
+        `Duplicate ZCode model ID: ${id}`,
+      );
+    }
+    ids.add(id);
+    const levels = model.reasoningLevels;
+    const level =
+      (id === current ? selection?.options?.reasoningLevel : undefined) ??
+      levels?.at(-1);
+    if (levels && new Set(levels).size !== levels.length) {
+      throw new AdapterError(
+        "NATIVE_PROTOCOL_ERROR",
+        "Duplicate ZCode reasoning level",
+      );
+    }
+    return {
+      id,
+      label: model.ref.modelId,
+      ...(model.providerLabel === undefined
+        ? {}
+        : { description: model.providerLabel }),
+      isDefault: id === current,
+      ...(levels === undefined
+        ? {}
+        : {
+            thinkingOptions: levels.map((value) => ({
+              id: value,
+              label: value,
+              isDefault: value === level,
+            })),
+            ...(level === undefined ? {} : { defaultThinkingOptionId: level }),
+          }),
+    };
+  });
+  return models;
+}
+
+export function mapMcpServers(
+  servers: Record<string, ProviderMcpServerConfig> | undefined,
+): Array<Record<string, unknown>> {
+  return Object.entries(servers ?? {}).map(([name, server]) => {
+    if (name.trim() === "") {
+      throw new AdapterError(
+        "INVALID_CONFIGURATION",
+        "MCP server name must not be empty",
+      );
+    }
+    if (server.alwaysLoad !== undefined) {
+      throw new AdapterError(
+        "INVALID_CONFIGURATION",
+        `MCP server '${name}' uses unsupported alwaysLoad`,
+      );
+    }
+    if (server.type === "stdio") {
+      if (!isAbsolute(server.command)) {
+        throw new AdapterError(
+          "INVALID_CONFIGURATION",
+          `MCP server '${name}' command must be absolute`,
+        );
+      }
+      return {
+        name,
+        command: server.command,
+        args: server.args ?? [],
+        env: Object.entries(server.env ?? {}).map(([key, value]) => ({
+          name: key,
+          value,
+        })),
+      };
+    }
+    const headers = Object.entries(server.headers ?? {}).map(
+      ([key, value]) => ({
+        name: key,
+        value,
+      }),
+    );
+    if (server.type === "http" || server.type === "sse") {
+      return { type: server.type, name, url: server.url, headers };
+    }
+    throw new AdapterError(
+      "INVALID_CONFIGURATION",
+      "Unsupported MCP server type",
+    );
+  });
+}
+
+export interface NativePrompt {
+  content: string;
+  attachments: Array<{
+    kind: "image" | "audio" | "file";
+    filename: string;
+    mimeType: string;
+    dataBase64?: string;
+    localPath?: string;
+    sizeBytes?: number;
+  }>;
+}
+
+export async function mapPrompt(
+  prompt: NativePromptInput,
+  workspace: string,
+): Promise<NativePrompt> {
+  if (typeof prompt === "string") return { content: prompt, attachments: [] };
+  const canonicalWorkspace = await realpath(workspace);
+  const content: string[] = [];
+  const attachments: NativePrompt["attachments"] = [];
+  for (const block of prompt) {
+    if (block.type === "text") {
+      content.push(block.text);
+      continue;
+    }
+    if (block.type === "image") {
+      attachments.push({
+        kind: "image",
+        filename: `image.${block.mimeType.split("/")[1]?.split("+")[0] ?? "bin"}`,
+        mimeType: block.mimeType,
+        dataBase64: block.data,
+        sizeBytes: Buffer.from(block.data, "base64").byteLength,
+      });
+      continue;
+    }
+    if (block.type === "uploaded_file") {
+      if (!isAbsolute(block.path)) {
+        throw new AdapterError(
+          "UNSUPPORTED_CONTENT",
+          "Attachment path must be absolute",
+        );
+      }
+      const resolved = await realpath(block.path);
+      const child = relative(canonicalWorkspace, resolved);
+      if (child.startsWith("..") || isAbsolute(child)) {
+        throw new AdapterError(
+          "UNSUPPORTED_CONTENT",
+          "Attachment path must remain inside the workspace",
+        );
+      }
+      const info = await stat(resolved);
+      if (!info.isFile()) {
+        throw new AdapterError(
+          "UNSUPPORTED_CONTENT",
+          "Attachment must be a regular file",
+        );
+      }
+      attachments.push({
+        kind: block.mimeType.startsWith("image/")
+          ? "image"
+          : block.mimeType.startsWith("audio/")
+            ? "audio"
+            : "file",
+        filename: block.fileName || basename(resolved),
+        mimeType: block.mimeType,
+        localPath: resolved,
+        sizeBytes: info.size,
+      });
+      continue;
+    }
+    throw new AdapterError(
+      "UNSUPPORTED_CONTENT",
+      `Unsupported Paseo attachment type: ${block.type}`,
+    );
+  }
+  return { content: content.join("\n\n"), attachments };
+}
+
+export function planMarkdown(input: unknown): string {
+  const plan = record(input).plan;
+  if (typeof plan !== "string" || plan.trim() === "") {
+    throw new AdapterError(
+      "NATIVE_PROTOCOL_ERROR",
+      "ZCode plan approval has no Markdown",
+    );
+  }
+  return plan.trim();
+}
+
+export function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export function jsonValue(value: unknown) {
+  return z.json().parse(value);
+}
+export function jsonObject(value: unknown) {
+  return z.record(z.string(), z.json()).parse(value);
+}

package/server/models.ts

@@ -0,0 +1,68 @@
+import { AdapterError } from "./errors.js";
+import type { HostBridge } from "./host/bridge.js";
+import { catalogModels, encodeModel } from "./mapping.js";
+import {
+  ModelSelectionViewSchema,
+  type ModelSelection,
+  type ModelSelectionView,
+} from "./host/schemas.js";
+
+export async function readModelSelection(
+  bridge: HostBridge,
+  selection?: ModelSelection,
+): Promise<ModelSelectionView> {
+  const view = await bridge.request(
+    "readModelSelection",
+    { selection },
+    ModelSelectionViewSchema,
+    60_000,
+  );
+  catalogModels(view.models, view.preferredSelection);
+  if (view.models.length === 0)
+    throw new AdapterError(
+      "AUTH_REQUIRED",
+      "No usable ZCode model provider is configured",
+    );
+  return view;
+}
+
+export async function resolveModelSelection(
+  bridge: HostBridge,
+  view: ModelSelectionView,
+  selection: ModelSelection,
+): Promise<ModelSelection> {
+  const model = view.models.find(
+    (item) => encodeModel(item.ref) === encodeModel(selection),
+  );
+  if (!model)
+    throw new AdapterError("INVALID_CONFIGURATION", "Unknown ZCode model");
+  // ZCode's projectAppModelOption uses the last advertised level as default.
+  // Model IDs and reasoning controls remain separate in Paseo.
+  const reasoningLevel =
+    selection.options?.reasoningLevel ?? model.reasoningLevels.at(-1)!;
+  if (!model.reasoningLevels.includes(reasoningLevel))
+    throw new AdapterError(
+      "INVALID_CONFIGURATION",
+      "Unknown ZCode thinking option",
+    );
+  const resolved = await readModelSelection(bridge, {
+    ...selection,
+    options: { reasoningLevel },
+  });
+  if (resolved.selectionIssue || !resolved.effectiveSelection)
+    throw new AdapterError(
+      "INVALID_CONFIGURATION",
+      "ZCode model selection is unavailable",
+    );
+  if (encodeModel(resolved.effectiveSelection) !== encodeModel(selection))
+    throw new AdapterError(
+      "INVALID_CONFIGURATION",
+      "ZCode resolved a different model; select it explicitly",
+    );
+  if (resolved.effectiveSelection.options?.reasoningLevel !== reasoningLevel)
+    throw new AdapterError(
+      "INVALID_CONFIGURATION",
+      "ZCode resolved a different reasoning level",
+    );
+  return resolved.effectiveSelection;
+}

package/server/persistence.ts

@@ -0,0 +1,146 @@
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import type { ProviderPersistence } from "@getpaseo/plugin/server/provider";
+import { AdapterError } from "./errors.js";
+
+const workspace = z.string().min(1);
+const dataSchema = z.discriminatedUnion("kind", [
+  z
+    .object({ kind: z.literal("logical"), id: z.uuid(), cwd: workspace })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("native"),
+      sessionId: z.string().min(1),
+      cwd: workspace,
+    })
+    .strict(),
+]);
+const recordSchema = z
+  .object({
+    version: z.literal(1),
+    sessionId: z.string().min(1),
+    cwd: workspace,
+  })
+  .strict();
+export type PersistenceData = z.infer<typeof dataSchema>;
+
+export function parsePersistence(handle: ProviderPersistence): PersistenceData {
+  if (handle.version !== 3)
+    throw new AdapterError(
+      "PERSISTENCE_VERSION_UNSUPPORTED",
+      "Unsupported ZCode persistence version; expected version 3",
+    );
+  try {
+    return dataSchema.parse(handle.data);
+  } catch {
+    throw new AdapterError(
+      "PERSISTENCE_INVALID",
+      "Invalid ZCode persistence handle",
+    );
+  }
+}
+
+export function persistenceHandle(data: PersistenceData): ProviderPersistence {
+  return { version: 3, data };
+}
+
+// Outside the plugin checkout: reinstalling/building the plugin must not erase handles.
+export function defaultSessionDirectory(
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  return join(
+    environment.XDG_STATE_HOME ?? join(homedir(), ".local", "state"),
+    "paseo-plugin-zcode-provider",
+    "sessions-v3",
+  );
+}
+
+export class SessionPersistenceStore {
+  constructor(readonly directory: string = defaultSessionDirectory()) {}
+
+  private filename(id: string): string {
+    return join(this.directory, `${z.uuid().parse(id)}.json`);
+  }
+
+  async resolve(data: PersistenceData): Promise<string | undefined> {
+    if (data.kind === "native") return data.sessionId;
+    let content: string;
+    try {
+      content = await readFile(this.filename(data.id), "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw new AdapterError(
+        "PERSISTENCE_INVALID",
+        "Cannot read ZCode persistence record",
+        {},
+        { cause: error },
+      );
+    }
+    let record: z.infer<typeof recordSchema>;
+    try {
+      record = recordSchema.parse(JSON.parse(content));
+    } catch (error) {
+      throw new AdapterError(
+        "PERSISTENCE_INVALID",
+        "Invalid ZCode persistence record",
+        {},
+        { cause: error },
+      );
+    }
+    if (record.cwd !== data.cwd)
+      throw new AdapterError(
+        "INVALID_WORKSPACE",
+        "ZCode persistence belongs to another workspace",
+      );
+    return record.sessionId;
+  }
+
+  async save(data: PersistenceData, sessionId: string): Promise<void> {
+    if (data.kind === "native") return;
+    const record = recordSchema.parse({ version: 1, sessionId, cwd: data.cwd });
+    try {
+      await mkdir(this.directory, { recursive: true, mode: 0o700 });
+      await this.write(data.id, record);
+    } catch (error) {
+      throw new AdapterError(
+        "PERSISTENCE_WRITE_FAILED",
+        "Cannot save ZCode resume information; prompt was not sent",
+        {},
+        { cause: error },
+      );
+    }
+  }
+
+  private async write(
+    id: string,
+    record: z.infer<typeof recordSchema>,
+  ): Promise<void> {
+    const destination = this.filename(id);
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+      const file = await open(temporary, "wx", 0o600);
+      try {
+        await file.writeFile(JSON.stringify(record));
+        await file.sync();
+      } finally {
+        await file.close();
+      }
+      await rename(temporary, destination);
+      // Windows does not support opening directories for fsync.
+      if (process.platform !== "win32") {
+        const directory = await open(this.directory, "r");
+        try {
+          await directory.sync();
+        } finally {
+          await directory.close();
+        }
+      }
+    } finally {
+      await rm(temporary, { force: true });
+    }
+  }
+}