faberun 0.3.0

package/src/harnesses/zcode/index.mjs

@@ -0,0 +1,276 @@
+import { accessSync, chmodSync, constants, existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { normalizeZcodeResult, parseVersion } from "../protocol.mjs";
+
+/** Default Z.ai Anthropic-compatible endpoint serving GLM models. */
+const ZCODE_DEFAULT_BASE_URL = "https://api.z.ai/api/anthropic";
+
+/** The command name the adapter resolves and the shim is installed under. */
+const ZCODE_BIN_NAME = "zcode";
+
+/**
+ * macOS install layout: ZCode ships as an Electron app with the CLI bundled
+ * inside it (`zcode.cjs`) and no CLI installer of its own, so a machine can run
+ * the desktop app for months without ever having a runnable `zcode` command.
+ * The `glm` directory name is the app's own, not this skill's provider id.
+ */
+const ZCODE_MACOS_BUNDLE = Object.freeze({
+  electron: "/Applications/ZCode.app/Contents/MacOS/ZCode",
+  cli: "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
+});
+
+/** Provider id in the ZCODE_MODEL target; it also derives the auth env var name. */
+const ZCODE_DEFAULT_PROVIDER = "glm";
+
+/** Default environment variable holding the Z.ai API token. */
+const ZCODE_DEFAULT_AUTH_TOKEN_ENV = "ZAI_API_KEY";
+
+/**
+ * ZCode harness: drives Z.ai's own harness CLI headlessly (`--prompt --json`),
+ * so a contract can route GLM 5.x nodes through the native ZCode protocol
+ * instead of a Claude-Code-compatible shim. The CLI 0.16.5 headless surface is
+ * `--prompt`, `--json`, `--mode`, `--resume`, and `--no-color`; model and
+ * endpoint travel as `ZCODE_MODEL` (`provider/model`) and `ZCODE_BASE_URL`,
+ * and the token is read at invocation time from the environment variable named
+ * by `config["auth_token.env_key"]` (default `ZAI_API_KEY`, falling back to
+ * `ANTHROPIC_AUTH_TOKEN`) into the provider-derived `${PROVIDER}_API_KEY`
+ * variable the CLI resolves. Values never travel in the contract.
+ *
+ * The harness has no schema flag, and this harness sends no tool policy, so
+ * `structuredOutput` and `toolPolicy` stay `false`: a judge's schema travels
+ * inside the prompt text (enforcement remains parseJudge at the review
+ * boundary), and the CLI's `--settings`/hooks surface stays unwired.
+ *
+ * The vendor's own CLI reference is checked in at
+ * `docs/faberun/ZCODE-CLI.md`; it is the authority this adapter is
+ * written against, and the place to look before trusting any of the surface
+ * facts above. `ensureZcodeAvailable` below implements what that document
+ * describes as the install story: the CLI lives inside the app bundle and has
+ * to be reached through a shim on PATH.
+ *
+ * @type {import("../index.mjs").HarnessAdapter}
+ */
+export const zcodeHarness = {
+  capabilities: {
+    structuredOutput: false,
+    promptTransport: "argv",
+    maxArgvPromptBytes: 128 * 1024,
+    sandbox: false,
+    permissions: false,
+    continuation: true,
+    tokenBudget: false,
+    costBudget: false,
+    usage: true,
+    cost: false,
+    toolPolicy: false,
+    // `--json` (no streaming flag exists) buffers the whole turn and dumps it
+    // once at exit: a live worker node was killed at 420s stall_timeout with
+    // its stdout/stderr at zero bytes, while a completed 1m26s invocation's
+    // log held its full 26 lines only once the process exited. Stall
+    // detection must not watch this harness's stdout/stderr mtime.
+    streamsOutput: false,
+  },
+
+  // build/edit/plan do not execute commands; command() defaults to yolo.
+  permissionExecution: { field: "permissionMode", executingModes: ["yolo"], defaultMode: "yolo" },
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @returns {string} */
+  executable(runtime) {
+    const declared = process.env.FABERUN_ZCODE_BIN ?? runtime.executable;
+    if (declared) return declared;
+    // Repair the host, then keep naming the command `zcode`. The name is part
+    // of the runtime fingerprint (node.mjs hashes `{runtime, executable}`) and
+    // is compared against snapshots persisted by an earlier process, where a
+    // mismatch silently rotates the session and drops `--resume`. An absolute
+    // path would make that identity depend on whichever PATH the process
+    // happened to inherit.
+    ensureZcodeAvailable();
+    return ZCODE_BIN_NAME;
+  },
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @returns {string[]} */
+  versionArgs(runtime) {
+    return runtime.versionArgs ?? ["--version"];
+  },
+
+  parseVersion,
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @param {string} prompt @param {import("../index.mjs").CommandOptions} options @returns {import("../index.mjs").HarnessCommand} */
+  command(runtime, prompt, options) {
+    const continuationId = options.continuationId ?? null;
+    const provider = typeof runtime.config?.provider === "string" && runtime.config.provider
+      ? runtime.config.provider
+      : ZCODE_DEFAULT_PROVIDER;
+    // No schema flag exists, so the schema travels inside the prompt: the
+    // judge prompt names "the output schema" but only carries its text when
+    // the harness puts it there.
+    const fullPrompt = options.schema
+      ? `${prompt}\n\nThe output schema (return exactly one JSON object matching it, as the only content of your final message):\n${JSON.stringify(options.schema)}`
+      : prompt;
+    const args = [
+      "--json",
+      "--no-color",
+      "--mode",
+      runtime.permissionMode ?? "yolo",
+      ...(continuationId ? ["--resume", continuationId] : []),
+      "--prompt",
+      fullPrompt,
+    ];
+    const model = runtime.model.replace(/\[1m\]$/iu, "");
+    /** @type {Record<string, string|null>} */
+    const env = {
+      ZCODE_MODEL: `${provider}/${model}`,
+      ZCODE_BASE_URL: /** @type {string} */ (runtime.config?.base_url) ?? ZCODE_DEFAULT_BASE_URL,
+      // An ambient Anthropic key must not shadow the provider-derived token:
+      // the CLI checks it first for anthropic-kind providers.
+      ANTHROPIC_API_KEY: null,
+    };
+    const token = authToken(runtime);
+    // The token travels under the provider-derived variable name the CLI
+    // resolves (e.g. GLM_API_KEY); an unresolved token is omitted, not blanked.
+    const apiKeyVar = providerApiKeyVar(provider);
+    if (token !== null && apiKeyVar !== null) env[apiKeyVar] = token;
+    return { executable: this.executable(runtime), args, promptTransport: "argv", input: null, env };
+  },
+
+  normalize: normalizeZcodeResult,
+};
+
+/**
+ * The variable the harness reads a provider's token from: the CLI folds every
+ * run of non-alphanumerics in the provider id into `_` before appending
+ * `_API_KEY` (`z-ai` → `Z_AI_API_KEY`), so the id carried verbatim in
+ * `ZCODE_MODEL` has to be folded the same way. An id with no alphanumerics
+ * names no variable at all.
+ *
+ * @param {string} provider
+ * @returns {string|null}
+ */
+function providerApiKeyVar(provider) {
+  const stem = provider.trim().replace(/[^a-zA-Z0-9]+/gu, "_").replace(/^_+|_+$/gu, "").toUpperCase();
+  return stem ? `${stem}_API_KEY` : null;
+}
+
+/**
+ * @param {import("../index.mjs").HarnessRuntime} runtime
+ * @returns {string|null}
+ */
+function authToken(runtime) {
+  const declared = /** @type {unknown} */ (runtime.config?.["auth_token.env_key"]);
+  const name = typeof declared === "string" && declared ? declared : ZCODE_DEFAULT_AUTH_TOKEN_ENV;
+  const resolved = process.env[name] ?? process.env.ANTHROPIC_AUTH_TOKEN;
+  return typeof resolved === "string" && resolved ? resolved : null;
+}
+
+/**
+ * Make the ZCode CLI reachable as `zcode`, for this process and every later
+ * shell: when the name resolves to nothing on PATH and the app bundle is
+ * installed, write the shim that reaches the bundled CLI through Electron's own
+ * node. The install dir has to be on PATH already — a shim somewhere the shell
+ * does not look would fix the harness and not the user, which is the half of the
+ * request that matters here.
+ *
+ * Total by design: `executable()` is called by surfaces that have no error path
+ * around it (`models` reports every registered harness, runtime discovery probes
+ * each one, `doctor` checks binaries), so a permissions or disk failure has to
+ * degrade into "not found" — never into an aborted run or a crashed report.
+ *
+ * @param {{env?: Record<string, string|undefined>, pathDirs?: string[], home?: string, bundle?: {electron: string, cli: string}}} [options]
+ * @returns {void}
+ */
+export function ensureZcodeAvailable(options = {}) {
+  try {
+    const env = options.env ?? process.env;
+    const pathDirs = options.pathDirs ?? (env.PATH ?? "").split(delimiter).filter(Boolean);
+    if (resolvesOnPath(pathDirs, ZCODE_BIN_NAME)) return;
+    const bundle = options.bundle ?? ZCODE_MACOS_BUNDLE;
+    if (!existsSync(bundle.electron) || !existsSync(bundle.cli)) return;
+    const body = zcodeShim(bundle);
+    for (const dir of shimDirs(options.home ?? homedir())) {
+      if (!pathDirs.includes(dir)) continue;
+      if (settleShim(join(dir, ZCODE_BIN_NAME), body)) return;
+    }
+  } catch {
+    // Unreachable host: the spawn fails and the adapter classifies `not_found`,
+    // which is the same answer a machine without the app gets.
+  }
+}
+
+/**
+ * The shim body. It runs the bundle through the app's own Electron binary as
+ * node because the CLI mis-handles its response path under a system node
+ * (detached ArrayBuffer on node 24 x64), and it `exec`s so no wrapper process
+ * outlives it.
+ *
+ * @param {{electron: string, cli: string}} bundle
+ * @returns {string}
+ */
+function zcodeShim(bundle) {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+# Written by the faberun zcode harness; the ZCode app owns both paths.
+ELECTRON_RUN_AS_NODE=1 exec ${bundle.electron} \\
+  ${bundle.cli} "$@"
+`;
+}
+
+/**
+ * Install dirs, in preference order. `~/.local/bin` is the convention this
+ * machine already uses for provider CLIs, `~/bin` is the older habit, and
+ * `/usr/local/bin` is the last resort — all three are only eligible while they
+ * are on PATH (see the caller).
+ *
+ * @param {string} home
+ * @returns {string[]}
+ */
+function shimDirs(home) {
+  return [join(home, ".local", "bin"), join(home, "bin"), "/usr/local/bin"];
+}
+
+/**
+ * @param {string[]} pathDirs
+ * @param {string} name
+ * @returns {boolean} whether `name` is a runnable command on this PATH.
+ */
+function resolvesOnPath(pathDirs, name) {
+  return pathDirs.some((dir) => {
+    try {
+      accessSync(join(dir, name), constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Write the shim into `target`, or decide it is already settled. Returns false
+ * only to let the caller try the next install dir.
+ *
+ * The symlink refusal is the important one: writing a path that is a symlink
+ * writes through it, onto whatever it points at — and on a machine where the
+ * user already hand-installed `zcode -> zcode-shim`, that would be their file.
+ *
+ * @param {string} target
+ * @param {string} body
+ * @returns {boolean}
+ */
+function settleShim(target, body) {
+  const existing = lstatSync(target, { throwIfNoEntry: false });
+  if (existing?.isSymbolicLink()) return true;
+  if (existing?.isFile() && readFileSync(target, "utf8") === body) return true;
+  const temporary = `${target}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, body);
+    // A created file's mode is masked by umask, and the shim has to be runnable.
+    chmodSync(temporary, 0o755);
+    renameSync(temporary, target);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+  return true;
+}
+
+export const harness = zcodeHarness;
+export default zcodeHarness;

package/src/host/config.mjs

@@ -0,0 +1,87 @@
+/**
+ * The user config at `$FABERUN_HOME/config.json`: which harnesses `setup`
+ * enabled and which runtime is the default worker and judge.
+ *
+ * It is separate from `host/home.mjs`, which owns the path, because reading a
+ * config is a validation problem and writing it is an atomic-write problem;
+ * neither belongs in the path table. `engine/runtime-discovery.mjs` types its
+ * `options.config` against this module and `cli/setup.mjs` writes it.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { configPath, faberunHome } from "./home.mjs";
+
+/** @typedef {{schemaVersion: 1, harnesses: string[], worker?: string, judge?: string, updatedAt: string}} UserConfig */
+
+/** Paths already reported malformed, so a process that reads twice warns once. */
+const warned = new Set();
+
+/**
+ * The user config, or null when the file is absent or malformed. A malformed
+ * file is written off as a single `[warn]` line on stderr and then ignored:
+ * the run falls back to the discovery law rather than refusing to start.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {UserConfig|null}
+ */
+export function readUserConfig(env = process.env) {
+  const path = configPath(faberunHome(env));
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    // An unreadable file is indistinguishable from an absent one here; there
+    // is nothing to act on either way.
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return warnMalformed(path);
+  }
+  return isUserConfig(parsed) ? parsed : warnMalformed(path);
+}
+
+/**
+ * Write the config atomically: a sibling temporary file then a rename, so a
+ * concurrent reader never observes a half-written record. The home directory
+ * is created on the way.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {UserConfig} config
+ * @returns {void}
+ */
+export function writeUserConfig(env, config) {
+  const path = configPath(faberunHome(env));
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(config)}\n`);
+  renameSync(temporary, path);
+}
+
+/**
+ * @param {string} path
+ * @returns {null}
+ */
+function warnMalformed(path) {
+  if (!warned.has(path)) {
+    warned.add(path);
+    process.stderr.write(`[warn] config · ${path} is not valid; ignoring it\n`);
+  }
+  return null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is UserConfig}
+ */
+function isUserConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  if (record.schemaVersion !== 1) return false;
+  if (!Array.isArray(record.harnesses) || !record.harnesses.every((harness) => typeof harness === "string")) return false;
+  if (record.worker !== undefined && typeof record.worker !== "string") return false;
+  if (record.judge !== undefined && typeof record.judge !== "string") return false;
+  return typeof record.updatedAt === "string";
+}

package/src/host/home.mjs

@@ -0,0 +1,149 @@
+/**
+ * The install layout under `$FABERUN_HOME` (default `~/.faberun`).
+ *
+ * One module owns every path the installer, the self-updater and the banner
+ * must agree on: `versions/<v>/`, the `current` symlink, `config.json`,
+ * `update-check.json` and `tmp/`. install.sh is owned by another node; if it
+ * and the updater each spelled the layout out, they would drift until
+ * `current` pointed at a directory one of them did not mean.
+ */
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** @typedef {{checkedAt: string, current: string, latest: string}} UpdateCheck */
+
+/**
+ * The install root: `$FABERUN_HOME`, or `~/.faberun` when it is unset or empty.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function faberunHome(env = process.env) {
+  const configured = env.FABERUN_HOME;
+  if (typeof configured === "string" && configured) return configured;
+  return join(homedir(), ".faberun");
+}
+
+/** @param {string} home @returns {string} */
+export function versionsDir(home) {
+  return join(home, "versions");
+}
+
+/** @param {string} home @returns {string} */
+export function currentLink(home) {
+  return join(home, "current");
+}
+
+/** @param {string} home @returns {string} */
+export function configPath(home) {
+  return join(home, "config.json");
+}
+
+/** @param {string} home @returns {string} */
+export function updateCheckPath(home) {
+  return join(home, "update-check.json");
+}
+
+/** @param {string} home @returns {string} */
+export function tmpDir(home) {
+  return join(home, "tmp");
+}
+
+/**
+ * The version directory an entry path was launched from, or null when the path
+ * does not name a location inside `versions/`.
+ *
+ * Containment is judged on the literal path first: a `bin/faberun.mjs` that is
+ * itself a symlink still counts because its *location* is what identifies the
+ * installed version. When the literal path does not match, the path is resolved
+ * so an entry reached through the install's `current` link (or a `$FABERUN_BIN_DIR`
+ * symlink to it) reports the version it ultimately points at.
+ *
+ * @param {string|undefined} entryPath
+ * @param {string} home
+ * @returns {string|null}
+ */
+export function installedVersionDir(entryPath, home) {
+  if (typeof entryPath !== "string" || !entryPath) return null;
+  const root = resolve(versionsDir(home));
+  /** @type {string[]} */
+  const candidates = [resolve(entryPath)];
+  try {
+    candidates.push(realpathSync(entryPath));
+  } catch {
+    // The path does not exist: only its literal location can identify a version.
+  }
+  for (const candidate of candidates) {
+    const within = relative(root, candidate);
+    if (!within || within.startsWith("..") || isAbsolute(within)) continue;
+    const [name] = within.split(sep);
+    if (name) return join(root, name);
+  }
+  return null;
+}
+
+/**
+ * The cached update check, or null when it is missing or malformed. The banner
+ * reads this and nothing else: it never reaches the network.
+ *
+ * @param {string} home
+ * @returns {UpdateCheck|null}
+ */
+export function readUpdateCheck(home) {
+  try {
+    const parsed = JSON.parse(readFileSync(updateCheckPath(home), "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    if (typeof parsed.checkedAt !== "string" || typeof parsed.current !== "string" || typeof parsed.latest !== "string") return null;
+    return { checkedAt: parsed.checkedAt, current: parsed.current, latest: parsed.latest };
+  } catch {
+    // No readable cache is simply no cached fact, not an error.
+    return null;
+  }
+}
+
+/**
+ * Write the cache atomically: a sibling temporary file then a rename, so a
+ * reader never observes a half-written record.
+ *
+ * @param {string} home
+ * @param {UpdateCheck} record
+ * @returns {void}
+ */
+export function writeUpdateCheck(home, record) {
+  const path = updateCheckPath(home);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(record)}\n`);
+  renameSync(temporary, path);
+}
+
+/**
+ * Compare two `X.Y.Z` versions numerically on their three parts. Prerelease
+ * suffixes are out of scope for this command: a version that does not match the
+ * three-part grammar compares equal to nothing, so no hint is shown.
+ *
+ * @param {string} left
+ * @param {string} right
+ * @returns {-1|0|1}
+ */
+export function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {string} text
+ * @returns {number[]|null}
+ */
+function parseVersion(text) {
+  if (typeof text !== "string") return null;
+  const match = /^(\d+)\.(\d+)\.(\d+)$/u.exec(text);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}

package/src/host/package.mjs

@@ -0,0 +1,23 @@
+/**
+ * The installed package's own name and version, read once from `package.json`.
+ *
+ * It is separate from the contract protocol version: `CONTRACT_VERSION` is the
+ * schema `src/` evolves on its own, while this is the release number
+ * release-please moves. `--version` and the banner both need the latter from
+ * one place, so no source file hard-codes a number the package can outgrow.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** @type {{name: string, version: string}} */
+const PACKAGE = JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf8"));
+
+/** @returns {string} */
+export function packageName() {
+  return PACKAGE.name;
+}
+
+/** @returns {string} */
+export function packageVersion() {
+  return PACKAGE.version;
+}