Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

20.1 KB
Raw Blame
import { existsSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve } from "node:path";
import { ZCODE_MODELS } from "../config/providers/registry/zcode/index.ts";
import {
  BaseExecutor,
  type ExecuteInput,
  type ExecutorExecuteResult,
  type ProviderCredentials,
} from "./base.ts";
import { ZcodeAppServerClient, type ZcodeClientLike } from "./zcodeProtocol.ts";
import { errorResponse, sanitizeErrorMessage } from "../utils/error.ts";
import { MAX_CURSOR_IMAGES, resolveCursorImages } from "../utils/cursorImages.ts";

const ZCODE_URL = "zcode://app-server/stdio";
const DEFAULT_PROVIDER_ID = "builtin:zai-coding-plan";
const ACCOUNT_PROVIDER_ID = "account:zai-individual-coding-plan";
const DEFAULT_TURN_TIMEOUT_MS = 600_000;
const ZCODE_MODEL_ALLOWLIST = new Set(ZCODE_MODELS.map((model) => model.id));
const DEFAULT_ZCODE_MODEL = ZCODE_MODELS[0]?.id || "glm-5.2";
type JsonRecord = Record<string, unknown>;
type ZcodeCommand = { command: string; args: string[] };
type ZcodeModelResolution = { ok: true; model: string } | { ok: false; error: string };
export interface ZcodeExecutorOptions {
  command?: string;
  args?: string[];
  cwd?: string;
  providerId?: string;
  startupTimeoutMs?: number;
  requestTimeoutMs?: number;
  turnTimeoutMs?: number;
  clientFactory?: () => ZcodeClientLike;
}
function asRecord(value: unknown): JsonRecord {
  return value && typeof value === "object" && !Array.isArray(value) ? (value as JsonRecord) : {};
}
/**
 * Native generateWorkspaceText selection payload. The native schema rejects
 * unknown keys anywhere inside `selection`, so no runtime option bound may be
 * shipped here — it is resolved separately.
 */
export interface ZcodeTurnSelection {
  providerId: string;
  modelId: string;
  options?: { reasoningLevel?: string };
}

type NativeModelEntry = { record: JsonRecord; providerId: string };

function findNativeModelEntry(
  view: unknown,
  model: string,
  providerId?: string
): NativeModelEntry | null {
  const providers = asRecord(view).providers;
  const allowed = providerId ? [providerId] : [ACCOUNT_PROVIDER_ID, DEFAULT_PROVIDER_ID];
  for (const id of allowed) {
    const provider = (Array.isArray(providers) ? providers : [])
      .map(asRecord)
      .find((entry) => entry.providerId === id);
    const models = provider?.models;
    const entry = (Array.isArray(models) ? models : [])
      .map(asRecord)
      .find(
        (candidate) =>
          typeof candidate.modelId === "string" &&
          candidate.modelId.toLowerCase() === model.toLowerCase() &&
          asRecord(candidate.config).enabled !== false
      );
    if (entry) return { record: entry, providerId: id };
  }
  return null;
}

/** Use the native registry's exact, case-sensitive IDs without changing providers. */
export function resolveZcodeSelection(
  view: unknown,
  model: string,
  providerId?: string
): ZcodeTurnSelection {
  const found = findNativeModelEntry(view, model, providerId);
  if (!found) {
    throw new Error(
      `ZCode Coding Plan model "${model}" is not enabled in the native provider registry.`
    );
  }
  const optionSpecs = asRecord(asRecord(found.record.config).optionSpecs);
  const spec = asRecord(optionSpecs.reasoningLevel);
  const levels = Array.isArray(spec.values)
    ? spec.values.filter((value): value is string => typeof value === "string")
    : [];
  const reasoningLevel = levels.includes("high") ? "high" : levels[0];
  return {
    providerId: found.providerId,
    modelId: found.record.modelId as string,
    ...(reasoningLevel ? { options: { reasoningLevel } } : {}),
  };
}

/**
 * Native maxOutputTokens bound from the model option spec, or undefined when
 * the registry does not publish one. The upstream runtime refuses turns whose
 * maxOutputTokens is missing or outside this bound.
 */
export function resolveZcodeMaxTokens(
  view: unknown,
  model: string,
  providerId?: string
): number | undefined {
  const found = findNativeModelEntry(view, model, providerId);
  if (!found) return undefined;
  const optionSpecs = asRecord(asRecord(found.record.config).optionSpecs);
  const tokensSpec = asRecord(optionSpecs.maxOutputTokens);
  return typeof tokensSpec.max === "number" && tokensSpec.max >= 1
    ? Math.floor(tokensSpec.max)
    : undefined;
}

function textContent(content: unknown): string {
  if (content == null) return "";
  if (typeof content === "string") return content;
  if (!Array.isArray(content)) throw new Error("ZCode model messages require text content");
  return content
    .map((part) => {
      const item = asRecord(part);
      if (typeof part === "string") return part;
      if (
        ["text", "input_text", "output_text"].includes(String(item.type)) &&
        typeof item.text === "string"
      )
        return item.text;
      throw new Error("ZCode model transport currently supports text input only");
    })
    .join("");
}

function userContent(content: unknown): string | JsonRecord[] {
  if (!Array.isArray(content)) return textContent(content);
  const blocks = content.map((part) => {
    const item = asRecord(part);
    if (item.type === "image_url") {
      const url = asRecord(item.image_url).url;
      if (typeof url !== "string" || !url) throw new Error("ZCode image URL is missing");
      return {
        type: "image",
        dataUrl: url,
        mediaType: /^data:([^;,]+)/i.exec(url)?.[1]?.toLowerCase() || "image/unknown",
      };
    }
    return { type: "text", text: textContent([part]) };
  });
  return blocks.some((part) => part.type === "image")
    ? blocks
    : blocks.map((part) => part.text).join("");
}

/** Reuse bounded public-URL fetching; retain original image bytes without JPEG prep. */
async function resolveRequestImages(request: JsonRecord, signal?: AbortSignal | null) {
  const blocks = (request.messages as JsonRecord[])
    .flatMap((message) => (Array.isArray(message.content) ? message.content.map(asRecord) : []))
    .filter((block) => block.type === "image");
  if (blocks.length > MAX_CURSOR_IMAGES)
    throw new Error(`Too many ZCode images (max ${MAX_CURSOR_IMAGES})`);
  for (const block of blocks) {
    const [image] = await withAbort(
      resolveCursorImages([String(block.dataUrl)], { prepareForWire: false }),
      signal
    );
    if (
      !["image/png", "image/jpeg", "image/jpg", "image/gif", "image/webp"].includes(image.mimeType)
    )
      throw new Error("Unsupported ZCode image media type");
    block.mediaType = image.mimeType === "image/jpg" ? "image/jpeg" : image.mimeType;
    block.dataUrl = `data:${block.mediaType};base64,${image.data.toString("base64")}`;
  }
}

/** Preserve caller tool calls/results; the native text API never runs a coding agent. */
export function buildZcodeModelRequest(body: JsonRecord): JsonRecord {
  const names = new Map<string, string>();
  const messages = (Array.isArray(body.messages) ? body.messages : []).map((value) => {
    const message = asRecord(value);
    const content =
      message.role === "user" ? userContent(message.content) : textContent(message.content);
    if (message.role === "assistant") {
      const toolCalls = (Array.isArray(message.tool_calls) ? message.tool_calls : []).map(
        (value) => {
          const call = asRecord(value),
            fn = asRecord(call.function);
          if (typeof call.id !== "string" || typeof fn.name !== "string")
            throw new Error("Invalid assistant tool call");
          names.set(call.id, fn.name);
          return {
            id: call.id,
            name: fn.name,
            input:
              typeof fn.arguments === "string" ? JSON.parse(fn.arguments) : (fn.arguments ?? {}),
          };
        }
      );
      return { role: "assistant", content, ...(toolCalls.length ? { toolCalls } : {}) };
    }
    if (message.role === "tool") {
      const toolCallId = message.tool_call_id;
      const toolName = message.name || names.get(String(toolCallId));
      if (typeof toolCallId !== "string" || typeof toolName !== "string")
        throw new Error("Tool result has no matching assistant call/name");
      return { role: "tool", content, toolCallId, toolName };
    }
    if (!["system", "developer", "user"].includes(String(message.role)))
      throw new Error("Unsupported ZCode message role");
    return { role: message.role === "developer" ? "system" : message.role, content };
  });
  if (!messages.length) throw new Error("ZCode model request requires messages");
  if (body.tool_choice != null && !["auto", "none"].includes(String(body.tool_choice))) {
    throw new Error("ZCode model transport supports automatic tool selection or tool_choice=none");
  }
  const tools =
    body.tool_choice === "none"
      ? []
      : (Array.isArray(body.tools) ? body.tools : []).map((value) => {
          const item = asRecord(value),
            fn = asRecord(item.function);
          if (item.type !== "function" || typeof fn.name !== "string")
            throw new Error("ZCode model transport requires function tools");
          return {
            name: fn.name,
            ...(typeof fn.description === "string" ? { description: fn.description } : {}),
            inputSchema: asRecord(fn.parameters),
          };
        });
  const maxTokens = body.max_completion_tokens ?? body.max_tokens;
  return {
    messages,
    tools,
    ...(typeof maxTokens === "number" && maxTokens > 0
      ? { maxOutputTokens: Math.floor(maxTokens) }
      : {}),
  };
}

export function resolveZcodeModel(model: unknown): ZcodeModelResolution {
  const requested = typeof model === "string" ? model.trim() : "";
  if (!requested) return { ok: true, model: DEFAULT_ZCODE_MODEL };
  if (requested.startsWith("-")) {
    return {
      ok: false,
      error: `Invalid ZCode model \"${requested}\": model must not start with \"-\".`,
    };
  }
  const normalized = requested.startsWith("zcode/") ? requested.slice("zcode/".length) : requested;
  if (!ZCODE_MODEL_ALLOWLIST.has(normalized)) {
    return {
      ok: false,
      error: `Unknown ZCode model \"${requested}\". Supported models: ${[...ZCODE_MODEL_ALLOWLIST].join(", ")}.`,
    };
  }
  return { ok: true, model: normalized };
}

function parseArgs(raw: string | undefined): string[] {
  if (!raw) return ["app-server"];
  const parsed: unknown = JSON.parse(raw);
  if (
    !Array.isArray(parsed) ||
    parsed.length > 16 ||
    !parsed.every((arg) => typeof arg === "string" && arg.length <= 4096)
  ) {
    throw new Error("ZCODE_ARGS must be a JSON array of at most 16 strings");
  }
  return parsed as string[];
}

function defaultCommand(): ZcodeCommand {
  const runtimeRoot = process.env.ZCODE_SERVER_RUNTIME_ROOT || join(homedir(), ".zcode", "server");
  const serverNode = process.env.ZCODE_SERVER_NODE || join(runtimeRoot, "node");
  const serverEntry = process.env.ZCODE_SERVER_ENTRY || join(runtimeRoot, "zcode-server.cjs");
  if (existsSync(serverNode) && existsSync(serverEntry)) {
    return { command: serverNode, args: [serverEntry] };
  }
  return { command: process.env.ZCODE_BIN || "zcode", args: parseArgs(process.env.ZCODE_ARGS) };
}

function completion(model: string, result: JsonRecord): JsonRecord {
  const toolCalls = (Array.isArray(result.toolCalls) ? result.toolCalls : []).map((value) => {
    const call = asRecord(value);
    if (typeof call.id !== "string" || typeof call.name !== "string")
      throw new Error("ZCode returned an invalid tool call");
    return {
      id: call.id,
      type: "function",
      function: { name: call.name, arguments: JSON.stringify(call.input ?? {}) },
    };
  });
  const nativeUsage = asRecord(result.usage);
  const promptTokens = Number(nativeUsage.inputTokens || 0),
    completionTokens = Number(nativeUsage.outputTokens || 0);
  const finishReason = toolCalls.length
    ? "tool_calls"
    : ["length", "max-tokens"].includes(String(result.finishReason))
      ? "length"
      : "stop";
  return {
    id: `chatcmpl-zcode-${Date.now()}`,
    object: "chat.completion",
    created: Math.floor(Date.now() / 1000),
    model,
    choices: [
      {
        index: 0,
        message: {
          role: "assistant",
          content: typeof result.text === "string" ? result.text : "",
          ...(toolCalls.length ? { tool_calls: toolCalls } : {}),
        },
        finish_reason: finishReason,
      },
    ],
    usage: {
      prompt_tokens: promptTokens,
      completion_tokens: completionTokens,
      total_tokens: Number(nativeUsage.totalTokens ?? promptTokens + completionTokens),
      prompt_tokens_details: { cached_tokens: Number(nativeUsage.cacheReadTokens || 0) },
      completion_tokens_details: { reasoning_tokens: Number(nativeUsage.reasoningTokens || 0) },
    },
  };
}

function modelResponse(model: string, result: JsonRecord, stream: boolean): Response {
  const body = completion(model, result);
  if (!stream) return Response.json(body);
  const choice = (body.choices as JsonRecord[])[0],
    message = asRecord(choice.message);
  const base = { id: body.id, object: "chat.completion.chunk", created: body.created, model };
  const toolCalls = Array.isArray(message.tool_calls)
    ? message.tool_calls.map((value, index) => ({ ...asRecord(value), index }))
    : undefined;
  const chunks = [
    {
      ...base,
      choices: [
        {
          index: 0,
          delta: {
            role: "assistant",
            content: message.content,
            ...(toolCalls ? { tool_calls: toolCalls } : {}),
          },
          finish_reason: null,
        },
      ],
    },
    {
      ...base,
      choices: [{ index: 0, delta: {}, finish_reason: choice.finish_reason }],
      usage: body.usage,
    },
  ];
  return new Response(
    chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("") + "data: [DONE]\n\n",
    {
      headers: {
        "Content-Type": "text/event-stream",
        "Cache-Control": "no-cache",
        Connection: "keep-alive",
      },
    }
  );
}

async function withAbort<T>(promise: Promise<T>, signal?: AbortSignal | null): Promise<T> {
  if (!signal) return promise;
  let listener: () => void;
  const aborted = new Promise<never>((_, reject) => {
    listener = () => reject(new Error("ZCode model request aborted"));
    if (signal.aborted) listener();
    else signal.addEventListener("abort", listener, { once: true });
  });
  try {
    return await Promise.race([promise, aborted]);
  } finally {
    signal.removeEventListener("abort", listener!);
  }
}

function errorText(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

async function prepareZcodeRequest(
  body: unknown,
  model: string,
  signal?: AbortSignal | null
): Promise<JsonRecord> {
  const request = buildZcodeModelRequest(asRecord(body));
  const hasImages = (request.messages as JsonRecord[]).some(
    (message) =>
      Array.isArray(message.content) &&
      message.content.some((block) => asRecord(block).type === "image")
  );
  if (hasImages && !ZCODE_MODELS.find((entry) => entry.id === model)?.supportsVision)
    throw new Error(`ZCode model "${model}" does not support image input`);
  await resolveRequestImages(request, signal);
  return request;
}

// The native runtime validates that maxOutputTokens is a positive integer
// inside the model's option range on every turn, while the RPC selection
// payload must stay schema-clean. Bound a caller-provided limit into the
// registry range; otherwise use the bound.
function boundMaxOutputTokens(request: JsonRecord, nativeMaxTokens: number | undefined): void {
  if (typeof nativeMaxTokens !== "number") return;
  const callerMax =
    typeof request.maxOutputTokens === "number" && request.maxOutputTokens >= 1
      ? Math.floor(request.maxOutputTokens)
      : undefined;
  request.maxOutputTokens = Math.min(callerMax ?? nativeMaxTokens, nativeMaxTokens);
}

export class ZcodeExecutor extends BaseExecutor {
  constructor(private readonly options: ZcodeExecutorOptions = {}) {
    super("zcode", { id: "zcode", baseUrl: ZCODE_URL, format: "openai" });
  }
  buildUrl(): string {
    return ZCODE_URL;
  }
  transformRequest(): null {
    return null;
  }
  async execute(input: ExecuteInput): Promise<ExecutorExecuteResult> {
    const resolution = resolveZcodeModel(input.model);
    if (!resolution.ok)
      return errorResponse(400, "error" in resolution ? resolution.error : "Invalid ZCode model");
    let request: JsonRecord;
    try {
      request = await prepareZcodeRequest(input.body, resolution.model, input.signal);
    } catch (error) {
      return errorResponse(400, sanitizeErrorMessage(errorText(error)));
    }
    const client = this.createClient();
    try {
      const cwd = resolve(this.workingDirectory());
      const workspace = { workspacePath: cwd, workspaceIdentity: cwd };
      await withAbort(client.start(), input.signal);
      const initialized = asRecord(
        await withAbort(client.call("zcode-agent", "initialize", [workspace]), input.signal)
      );
      if (initialized.available !== true) throw new Error("ZCode model runtime is unavailable");
      const { selection, nativeMaxTokens } = await this.waitForSelection(
        client,
        resolution.model,
        input.signal
      );
      input.log?.info?.("ZCODE", `native model request model=${resolution.model}`);
      boundMaxOutputTokens(request, nativeMaxTokens);
      const result = asRecord(
        await withAbort(
          client.call("zcode-agent", "generateWorkspaceText", [
            {
              ...workspace,
              selection,
              ...request,
              querySource: "omniroute",
              requestTimeoutMs: this.turnTimeoutMs(),
            },
          ]),
          input.signal
        )
      );
      return {
        response: modelResponse(resolution.model, result, Boolean(input.stream)),
        url: ZCODE_URL,
        headers: {},
        transformedBody: {
          model: resolution.model,
          buffered: true,
          tools: (request.tools as unknown[]).length,
        },
        transport: "local-zcode-model",
      };
    } catch (error) {
      const message = sanitizeErrorMessage(errorText(error));
      input.log?.warn?.("ZCODE", message);
      // No stream has started: retain a real HTTP error, not a 200 error-only SSE
      // that the readiness guard rewrites into STREAM_EARLY_EOF.
      return errorResponse(input.signal?.aborted ? 499 : 502, message);
    } finally {
      await client.close().catch(() => undefined);
    }
  }
  // The signed-in account can hydrate after initialize while custom providers
  // are already ready. Wait for the exact model; never substitute a provider.
  private async waitForSelection(
    client: ZcodeClientLike,
    model: string,
    signal?: AbortSignal | null
  ): Promise<{ selection: ZcodeTurnSelection; nativeMaxTokens: number | undefined }> {
    const providerId = this.options.providerId || process.env.ZCODE_PROVIDER_ID;
    const readyDeadline = Date.now() + (this.options.startupTimeoutMs ?? 10_000);
    for (;;) {
      const registry = await withAbort(client.call("model-selection", "getView", []), signal);
      try {
        return {
          selection: resolveZcodeSelection(registry, model, providerId),
          nativeMaxTokens: resolveZcodeMaxTokens(registry, model, providerId),
        };
      } catch (error) {
        if (Date.now() >= readyDeadline) throw error;
        await withAbort(
          new Promise((resolve) => setTimeout(resolve, Math.min(250, readyDeadline - Date.now()))),
          signal
        );
      }
    }
  }
  private workingDirectory(): string {
    return this.options.cwd || process.env.ZCODE_CWD || process.cwd();
  }
  private turnTimeoutMs(): number {
    return (
      this.options.turnTimeoutMs ??
      Number(process.env.ZCODE_TURN_TIMEOUT_MS || DEFAULT_TURN_TIMEOUT_MS)
    );
  }
  private createClient(): ZcodeClientLike {
    if (this.options.clientFactory) return this.options.clientFactory();
    const selected = defaultCommand();
    return new ZcodeAppServerClient({
      command: this.options.command || selected.command,
      args: this.options.args || selected.args,
      cwd: this.options.cwd || process.env.ZCODE_CWD || process.cwd(),
      startupTimeoutMs:
        this.options.startupTimeoutMs ?? Number(process.env.ZCODE_STARTUP_TIMEOUT_MS || 10_000),
      requestTimeoutMs: this.options.requestTimeoutMs ?? this.turnTimeoutMs() + 10_000,
    });
  }
  override buildHeaders(_credentials: ProviderCredentials): Record<string, string> {
    return {};
  }
}