faberun 0.26.3 → 0.28.0

package/src/harnesses/fx/index.mjs

@@ -0,0 +1,137 @@
+/**
+ * The fx harness adapter: capabilities, the command that starts Faberun's own
+ * fx client (`runner.mjs`), and the envelope folded from its transcript. The
+ * client, not the `fx` binary, is what the gate spawns.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseVersion } from "../protocol.mjs";
+import { normalizeRunnerTranscript, runnerEnvironmentOverlay, withSchema } from "../runner-transcript.mjs";
+
+/**
+ * The environment names this adapter reads outside the base set and the
+ * runtime's own `*.env_key` names: the provider key the client falls back to
+ * when a runtime names none, and the binary override `executable()` honours.
+ * Values never travel here.
+ *
+ * @type {readonly string[]}
+ */
+export const declaredEnvironment = Object.freeze([
+  "DEEPSEEK_API_KEY",
+  "FABERUN_FX_BIN",
+]);
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * fx has no one-shot surface that streams a turn or reports its cache split,
+ * so the adapter's real provider is this client: it speaks `fx acp`, answers
+ * fx's permission requests, and relays the provider traffic through a
+ * loopback meter. The `fx` binary named by `executable()` is the harness the
+ * client drives, and probing it is what preflight means by "the provider
+ * binary exists".
+ */
+const RUNNER = join(HERE, "runner.mjs");
+
+/**
+ * The same client in Zig (`native/`), built by `zig build` in that directory.
+ * Measured 2026-09-24 over three parseDuration turns: 15-16 MB resident
+ * against 83 MB for `runner.mjs`, with the same transcript. Until a release
+ * ships the binary, a checkout that has not built it runs `runner.mjs`.
+ */
+const NATIVE_RUNNER = join(HERE, "native", "zig-out", "bin", process.platform === "win32" ? "faberun-fx-runner.exe" : "faberun-fx-runner");
+
+/**
+ * Measured 2026-09-24 on the parseDuration fixture on one macOS machine: this
+ * runner peaked at 83 MB resident and `fx acp` at 9 MB, against 310-370 MB for
+ * `dsh --profile headless` alone, with the same model and a passing suite. The
+ * harness exists for parallel campaigns on DeepSeek, where that difference is
+ * the worker count a machine can hold.
+ *
+ * @type {import("../index.mjs").HarnessAdapter}
+ */
+export const fxHarness = {
+  capabilities: {
+    // The schema rides in the prompt and the verdict is extracted from the
+    // final message, as dsh does; nothing in the wire enforces it.
+    structuredOutput: true,
+    promptTransport: "stdin",
+    // `runtime.sandbox` is decided per ACP permission request by
+    // `permissions.mjs`: file mutations by path, shell commands allowed.
+    sandbox: true,
+    permissions: false,
+    // `fx acp` can resume a session, but the runner builds a throwaway HOME
+    // per turn and fx stores sessions there; no id outlives the turn.
+    continuation: false,
+    tokenBudget: false,
+    costBudget: false,
+    usage: true,
+    cost: false,
+    toolPolicy: false,
+    // Measured 2026-09-24: one parseDuration turn streamed 7 `tool_call`
+    // updates as they happened; the runner forwards each as `fx.tool`.
+    streamsOutput: true,
+    // Not measured for fx.
+    signalsProcesses: null,
+  },
+
+  permissionExecution: {
+    field: "sandbox",
+    executingModes: ["read-only", "workspace-write", "danger-full-access"],
+    defaultMode: "workspace-write",
+    readOnlyModes: ["read-only"],
+  },
+
+  /** @param {import("../index.mjs").HarnessRuntime} runtime @returns {string} */
+  executable(runtime) {
+    return process.env.FABERUN_FX_BIN ?? runtime.executable ?? "fx";
+  },
+
+  /** @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 args = ["--fx", this.executable(runtime), "--model", runtime.model];
+    if (runtime.sandbox) args.push("--sandbox", runtime.sandbox);
+    const config = runtime.config ?? {};
+    if (config.provider === "codex") args.push("--provider", "codex");
+    if (typeof config.base_url === "string" && config.base_url) args.push("--base-url", config.base_url);
+    if (typeof config["api_key.env_key"] === "string" && config["api_key.env_key"]) args.push("--key-env", config["api_key.env_key"]);
+    if (typeof config.context_window === "number") args.push("--context-window", String(config.context_window));
+    if (typeof config.max_output_tokens === "number") args.push("--max-output-tokens", String(config.max_output_tokens));
+    const native = existsSync(NATIVE_RUNNER);
+    return {
+      executable: native ? NATIVE_RUNNER : process.execPath,
+      args: native ? args : [RUNNER, ...args],
+      promptTransport: "stdin",
+      input: withSchema(prompt, options.schema),
+      env: runnerEnvironmentOverlay(process.env),
+    };
+  },
+
+  /**
+   * @param {string} stdout
+   * @param {number|null} exitCode
+   * @param {string|null} signal
+   * @param {import("../index.mjs").NormalizeOptions} [options]
+   * @returns {import("../index.mjs").ProviderEnvelope}
+   */
+  normalize(stdout, exitCode, signal, options = {}) {
+    return normalizeRunnerTranscript("fx", stdout, exitCode, signal, options);
+  },
+};
+
+export const harness = fxHarness;
+export default fxHarness;

package/src/harnesses/fx/native/build.zig

@@ -0,0 +1,20 @@
+//! Builds `faberun-fx-runner`, the native fx client the fx adapter spawns.
+//! `zig build` installs it to `zig-out/bin/`; `zig build test` runs the unit
+//! tests of every module.
+
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    // ReleaseSafe unless told otherwise: the runner ships to operators, and
+    // Debug is 4x the binary for no runtime check ReleaseSafe drops.
+    const optimize = b.option(std.builtin.OptimizeMode, "optimize", "Optimization mode (default ReleaseSafe)") orelse .ReleaseSafe;
+    const module = b.createModule(.{
+        .root_source_file = b.path("main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    b.installArtifact(b.addExecutable(.{ .name = "faberun-fx-runner", .root_module = module }));
+    const tests = b.addTest(.{ .root_module = module });
+    b.step("test", "Run the runner's unit tests").dependOn(&b.addRunArtifact(tests).step);
+}

package/src/harnesses/fx/native/build.zig.zon

@@ -0,0 +1,7 @@
+.{
+    .name = .faberun_fx_runner,
+    .version = "0.1.0",
+    .fingerprint = 0x899586834bb2a4a8,
+    .minimum_zig_version = "0.16.0",
+    .paths = .{ "build.zig", "build.zig.zon", "main.zig", "home.zig", "permissions.zig", "relay.zig", "usage.zig" },
+}

package/src/harnesses/fx/native/home.zig

@@ -0,0 +1,85 @@
+//! The HOME an fx worker runs under. fx reads provider connections only from
+//! `$HOME/.fx/settings.json` and has no flag or variable that names another
+//! settings file, so pointing a worker at its own usage relay means giving it
+//! its own HOME. The same boundary closes the packet: fx loads every skill it
+//! finds under `~/.fx`, `~/.claude`, `~/.codex`, `~/.agents` and
+//! `~/.config/opencode` (fx 0.0.11 `skill_runtime.zig`), none of which a closed
+//! task packet asked for.
+//!
+//! Everything else in the operator's HOME is linked in, because the worker's
+//! shell inherits this HOME: git identity, npm and toolchain caches, and
+//! version managers keep resolving to the real files.
+
+const std = @import("std");
+const Io = std.Io;
+
+/// Top-level HOME entries fx scans for skills or reads as its own profile.
+const withheld = [_][]const u8{ ".fx", ".claude", ".codex", ".agents" };
+/// Entries under `~/.config` fx scans for skills.
+const withheld_config = [_][]const u8{"opencode"};
+
+fn isWithheld(name: []const u8, list: []const []const u8) bool {
+    for (list) |entry| if (std.mem.eql(u8, entry, name)) return true;
+    return false;
+}
+
+/// Links every entry of `from` into `to` except `list` and `rebuilt`.
+fn linkEntries(arena: std.mem.Allocator, io: Io, from: []const u8, to: []const u8, list: []const []const u8, rebuilt: ?[]const u8) !void {
+    var dir = Io.Dir.openDirAbsolute(io, from, .{ .iterate = true }) catch |err| switch (err) {
+        // An operator without `~/.config` has nothing to link from it.
+        error.FileNotFound => return,
+        else => return err,
+    };
+    defer dir.close(io);
+    var entries = dir.iterate();
+    while (try entries.next(io)) |entry| {
+        if (isWithheld(entry.name, list)) continue;
+        if (rebuilt) |name| if (std.mem.eql(u8, entry.name, name)) continue;
+        const target = try std.fs.path.join(arena, &.{ from, entry.name });
+        const link = try std.fs.path.join(arena, &.{ to, entry.name });
+        try Io.Dir.symLinkAbsolute(io, target, link, .{});
+    }
+}
+
+/// Fill `home`, an empty directory the caller owns and removes, with links to
+/// `real_home` and the fx settings document `settings`.
+pub fn prepare(arena: std.mem.Allocator, io: Io, real_home: []const u8, home: []const u8, settings: []const u8) !void {
+    try linkEntries(arena, io, real_home, home, &withheld, ".config");
+    const config = try std.fs.path.join(arena, &.{ home, ".config" });
+    try Io.Dir.cwd().createDirPath(io, config);
+    try linkEntries(arena, io, try std.fs.path.join(arena, &.{ real_home, ".config" }), config, &withheld_config, null);
+    // fx on Linux refuses a profile directory others can read
+    // (`private_state_permissions_unsupported`); macOS did not check.
+    const fx_dir = try std.fs.path.join(arena, &.{ home, ".fx" });
+    _ = try Io.Dir.cwd().createDirPathStatus(io, fx_dir, .fromMode(0o700));
+    var dir = try Io.Dir.openDirAbsolute(io, fx_dir, .{});
+    defer dir.close(io);
+    try dir.writeFile(io, .{ .sub_path = "settings.json", .data = settings, .flags = .{ .permissions = .fromMode(0o600) } });
+}
+
+test "the worker HOME withholds every skill root and links the rest" {
+    const io = std.testing.io;
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    var root_buf: [4096]u8 = undefined;
+    const root = root_buf[0..try tmp.dir.realPath(io, &root_buf)];
+    for ([_][]const u8{ "real/.fx", "real/.claude", "real/.codex", "real/.agents", "real/.npm", "real/.config/opencode", "real/.config/git", "home" }) |sub| {
+        try tmp.dir.createDirPath(io, sub);
+    }
+    const real = try std.fs.path.join(arena, &.{ root, "real" });
+    const home = try std.fs.path.join(arena, &.{ root, "home" });
+    try prepare(arena, io, real, home, "{\"provider\":\"faberun\"}\n");
+    for ([_][]const u8{ "home/.claude", "home/.codex", "home/.agents", "home/.config/opencode" }) |sub| {
+        try std.testing.expectError(error.FileNotFound, tmp.dir.access(io, sub, .{}));
+    }
+    var link_buf: [4096]u8 = undefined;
+    const npm = link_buf[0..try tmp.dir.readLink(io, "home/.npm", &link_buf)];
+    try std.testing.expectEqualStrings(try std.fs.path.join(arena, &.{ real, ".npm" }), npm);
+    const git = link_buf[0..try tmp.dir.readLink(io, "home/.config/git", &link_buf)];
+    try std.testing.expectEqualStrings(try std.fs.path.join(arena, &.{ real, ".config", "git" }), git);
+    const settings = try tmp.dir.readFileAlloc(io, "home/.fx/settings.json", arena, .unlimited);
+    try std.testing.expectEqualStrings("{\"provider\":\"faberun\"}\n", settings);
+}