open-managed-agents 0.1.0

package/bin/oma.mjs

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const compiledRoot = join(root, "dist");
+const usesCompiledRuntime = existsSync(join(compiledRoot, "src", "main.js"));
+const runtimeRoot = usesCompiledRuntime ? compiledRoot : root;
+const runtimeExtension = usesCompiledRuntime ? ".js" : ".ts";
+const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const args = process.argv.slice(2);
+
+const { resolveOmaUpEgressEnvironment } = await import(
+  pathToFileURL(runtimeFile("src", "control-plane", "egress", "image")).href,
+);
+
+checkNode();
+
+const command = args[0];
+if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+  if (command === "help" && args.length > 1) {
+    printCommandHelp(args.slice(1));
+    process.exit(0);
+  }
+  printHelp();
+  process.exit(0);
+}
+if ((command === "version" && args.length === 1) || command === "--version" || command === "-v") {
+  console.log(`oma ${packageJson.version}`);
+  process.exit(0);
+}
+const commandArgs = args.slice(1);
+const helpIndex = commandArgs.findIndex((arg) => arg === "--help" || arg === "-h");
+if (helpIndex !== -1) {
+  if (helpIndex !== commandArgs.length - 1) fail(`Help must be the last argument. Run \`oma help ${[command, ...commandArgs.slice(0, helpIndex)].join(" ")}\`.`);
+  printCommandHelp([command, ...commandArgs.slice(0, helpIndex)]);
+  process.exit(0);
+}
+
+if (command === "up") {
+  await runUp(args.slice(1));
+} else if (command === "smoke") {
+  await runSmoke(args.slice(1));
+} else if (command === "keys") {
+  await runKeys(args.slice(1));
+} else if (command === "workspaces") {
+  await runWorkspaces(args.slice(1));
+} else if (command === "admin") {
+  runAdmin(args.slice(1));
+} else if (command === "providers") {
+  await runProviders(args.slice(1));
+} else if (command === "models") {
+  await runModels(args.slice(1));
+} else if (command === "auth") {
+  await runAuth(args.slice(1));
+} else if (command === "doctor") {
+  await runDoctor(args.slice(1));
+} else if (command === "down" || command === "logs" || command === "status") {
+  fail(`${command} is not implemented yet. Run \`oma up\` in the foreground and use Ctrl-C to stop it.`);
+} else {
+  fail(`Unknown command: ${command}\n\nRun \`oma --help\` for usage.`);
+}
+
+async function runDoctor(commandArgs) {
+  await runChild(
+    process.execPath,
+    [
+      ...runtimeNodeFlags(),
+      runtimeFile("scripts", "oma-doctor"),
+      ...commandArgs,
+    ],
+    process.env,
+  );
+}
+
+async function runUp(commandArgs) {
+  let sandbox = "docker-local";
+  for (let index = 0; index < commandArgs.length; index += 1) {
+    const arg = commandArgs[index];
+    if (arg === "--sandbox") {
+      const value = commandArgs[index + 1];
+      if (value === undefined) fail("--sandbox requires docker or microsandbox");
+      sandbox = normalizeSandbox(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--detach" || arg === "-d") {
+      fail("Detached mode is not implemented yet. Run `oma up` in the foreground for now.");
+    }
+    fail(`Unknown option for oma up: ${arg}\nRun \`oma help up\` for usage.`);
+  }
+
+  checkSandbox(sandbox);
+  let runtimeEnv;
+  try {
+    runtimeEnv = resolveOmaUpEgressEnvironment(process.env, sandbox);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  const sandboxEnv = sandbox === "docker-local"
+    ? { OMA_SANDBOX_PROVIDER: sandbox, OMA_ALLOW_DOCKER_LOCAL: "true" }
+    : { OMA_SANDBOX_PROVIDER: sandbox, OMA_ALLOW_MICROSANDBOX_LOCAL: "true" };
+
+  const adminEnv = resolveAdminEnvironment();
+  console.log(`Starting OMA with ${sandbox}`);
+  if (runtimeEnv.OMA_ENABLE_EGRESS === "true") {
+    console.log(`Approved HTTPS egress: ${runtimeEnv.OMA_EGRESS_SIDECAR_IMAGE}`);
+  } else {
+    console.log("Approved HTTPS egress: unavailable (offline environments only)");
+  }
+  if (adminEnv.OMA_ADMIN_KEY_FILE !== undefined) {
+    console.log(`Admin mode: ${adminEnv.OMA_ADMIN_KEY_FILE}`);
+  } else if (process.env.OMA_ADMIN_KEY !== undefined) {
+    console.log("Admin mode: OMA_ADMIN_KEY environment variable");
+  }
+  console.log("Press Ctrl-C to stop. Durable data defaults to ~/.oma.\n");
+  await runChild(
+    process.execPath,
+    [
+      ...runtimeNodeFlags(),
+      runtimeFile("src", "main"),
+    ],
+    { ...runtimeEnv, ...sandboxEnv, ...adminEnv },
+  );
+}
+
+function runAdmin(commandArgs) {
+  const [action, ...rest] = commandArgs;
+  if (action === "init") {
+    let path = defaultAdminKeyPath();
+    for (let index = 0; index < rest.length; index += 1) {
+      const arg = rest[index];
+      if (arg === "--file") {
+        path = requiredOption(rest, ++index, arg);
+      } else {
+        fail(`Unknown option for oma admin init: ${arg}\nRun \`oma help admin init\` for usage.`);
+      }
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const key = randomBytes(32).toString("base64");
+    try {
+      writeFileSync(path, `${key}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+      chmodSync(path, 0o600);
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        fail(`Admin key file already exists at ${path}. Refusing to overwrite it.`);
+      }
+      throw error;
+    }
+    console.log(`Admin key initialized at ${path}`);
+    console.log(`Admin key: ${key}`);
+    console.log("This key grants appliance-wide administration. Store it securely.");
+    console.log("Restart `oma up` to enable console admin mode.");
+    return;
+  }
+  if (action === "status") {
+    if (rest.length !== 0) fail("Usage: oma admin status");
+    if (process.env.OMA_ADMIN_KEY !== undefined && process.env.OMA_ADMIN_KEY !== "") {
+      console.log("Admin mode is configured through OMA_ADMIN_KEY.");
+      return;
+    }
+    const path = defaultAdminKeyPath();
+    if (!existsSync(path)) {
+      console.log(`Admin mode is not configured. Run \`oma admin init\` to create ${path}.`);
+      return;
+    }
+    const mode = statSync(path).mode & 0o777;
+    console.log(`Admin key file: ${path}`);
+    console.log(`Permissions: ${mode.toString(8).padStart(3, "0")}`);
+    console.log("Admin mode will be enabled the next time `oma up` starts.");
+    return;
+  }
+  if (action === "rotate") {
+    fail("Admin key rotation is not implemented yet. Preserve the existing key file.");
+  }
+  fail("Usage: oma admin <init|status>");
+}
+
+async function runKeys(commandArgs) {
+  const [action, ...rest] = commandArgs;
+  if (action !== "mint" && action !== "list") {
+    fail("Usage: oma keys <mint|list> [--workspace id] [--label label] [--db path]");
+  }
+  let workspace = "wrk_default";
+  let label = "oma-cli";
+  let db = defaultDatabasePath();
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === "--workspace") {
+      workspace = requiredOption(rest, ++index, arg);
+    } else if (arg === "--label" && action === "mint") {
+      label = requiredOption(rest, ++index, arg);
+    } else if (arg === "--db") {
+      db = requiredOption(rest, ++index, arg);
+    } else {
+      fail(`Unknown option for oma keys ${action}: ${arg}\nRun \`oma help keys ${action}\` for usage.`);
+    }
+  }
+  const provisioningArgs = action === "mint"
+    ? ["mint-key", workspace, label, "--db", db]
+    : ["list-keys", workspace, "--db", db];
+  await runProvisioning(provisioningArgs);
+}
+
+async function runWorkspaces(commandArgs) {
+  const [action, ...rest] = commandArgs;
+  if (action !== "list") fail("Usage: oma workspaces list [--db path]");
+  let db = defaultDatabasePath();
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === "--db") {
+      db = requiredOption(rest, ++index, arg);
+    } else {
+      fail(`Unknown option for oma workspaces list: ${arg}\nRun \`oma help workspaces list\` for usage.`);
+    }
+  }
+  await runProvisioning(["list-workspaces", "--db", db]);
+}
+
+async function runProviders(commandArgs) {
+  const [action, ...rest] = commandArgs;
+  if (action !== "status") fail("Usage: oma providers status");
+  if (rest.length !== 0) fail("Usage: oma providers status");
+  await runModelProvisioning(["providers-status"]);
+}
+
+async function runModels(commandArgs) {
+  const [action, ...rest] = commandArgs;
+  if (action === "list") {
+    await runModelProvisioning(["models-list", ...rest]);
+    return;
+  }
+  if (action === "validate") {
+    await runModelProvisioning(["models-validate", ...rest]);
+    return;
+  }
+  fail("Usage: oma models <list|validate>");
+}
+
+async function runAuth(commandArgs) {
+  const [action, ...rest] = commandArgs;
+  if (action === "set") {
+    await runModelProvisioning(["auth-set", ...rest]);
+    return;
+  }
+  if (action === "remove") {
+    await runModelProvisioning(["auth-remove", ...rest]);
+    return;
+  }
+  if (action === "status") {
+    await runModelProvisioning(["auth-status", ...rest]);
+    return;
+  }
+  fail("Usage: oma auth <set|remove|status>");
+}
+
+async function runProvisioning(provisioningArgs) {
+  await runChild(
+    process.execPath,
+    [
+      ...runtimeNodeFlags(),
+      runtimeFile("scripts", "oma-workspaces"),
+      ...provisioningArgs,
+    ],
+    process.env,
+  );
+}
+
+async function runModelProvisioning(provisioningArgs) {
+  await runChild(
+    process.execPath,
+    [
+      ...runtimeNodeFlags(),
+      runtimeFile("scripts", "oma-models"),
+      ...provisioningArgs,
+    ],
+    process.env,
+  );
+}
+
+async function runSmoke(commandArgs) {
+  let sandbox;
+  let localCompatible = false;
+  let egress = false;
+  for (let index = 0; index < commandArgs.length; index += 1) {
+    const arg = commandArgs[index];
+    if (arg === "--sandbox") {
+      const value = commandArgs[index + 1];
+      if (value === undefined) fail("--sandbox requires docker or microsandbox");
+      sandbox = normalizeSandbox(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--local-compatible") {
+      localCompatible = true;
+      continue;
+    }
+    if (arg === "--egress") {
+      egress = true;
+      localCompatible = true;
+      continue;
+    }
+    fail(`Unknown option for oma smoke: ${arg}\nRun \`oma help smoke\` for usage.`);
+  }
+  await runChild(
+    process.execPath,
+    [join(runtimeRoot, "scripts", "alpha-smoke.mjs")],
+    {
+      ...process.env,
+      ...(sandbox === undefined ? {} : { OMA_ALPHA_SANDBOX_PROVIDER: sandbox }),
+      ...(localCompatible ? { OMA_ALPHA_LOCAL_COMPATIBLE: "1" } : {}),
+      ...(egress ? { OMA_ALPHA_EGRESS_SMOKE: "1" } : {}),
+    },
+  );
+}
+
+function runtimeFile(...segments) {
+  const stem = join(runtimeRoot, ...segments);
+  return `${stem}${runtimeExtension}`;
+}
+
+function runtimeNodeFlags() {
+  return usesCompiledRuntime ? [] : ["--experimental-transform-types", "--disable-warning=ExperimentalWarning"];
+}
+
+function requiredOption(args, index, option) {
+  const value = args[index];
+  if (value === undefined || value.startsWith("--")) fail(`${option} requires a value`);
+  return value;
+}
+
+function defaultDatabasePath() {
+  return process.env.OMA_SQLITE_PATH ?? join(defaultOmaHome(), "oma.sqlite");
+}
+
+function defaultOmaHome() {
+  return process.env.OMA_HOME ?? join(homedir(), ".oma");
+}
+
+function defaultAdminKeyPath() {
+  return process.env.OMA_ADMIN_KEY_FILE ?? join(defaultOmaHome(), "admin.key");
+}
+
+function resolveAdminEnvironment() {
+  if (process.env.OMA_ADMIN_KEY !== undefined || process.env.OMA_ADMIN_KEY_FILE !== undefined) return {};
+  const path = defaultAdminKeyPath();
+  return existsSync(path) ? { OMA_ADMIN_KEY_FILE: path } : {};
+}
+
+function normalizeSandbox(value) {
+  if (value === "docker" || value === "docker-local") return "docker-local";
+  if (value === "microsandbox" || value === "microsandbox-local") return "microsandbox-local";
+  fail(`Unsupported sandbox ${JSON.stringify(value)}. Use docker or microsandbox.`);
+}
+
+function checkSandbox(sandbox) {
+  if (sandbox === "docker-local") {
+    const result = spawnSync("docker", ["info"], { encoding: "utf8" });
+    if (result.status !== 0) {
+      const detail = (result.stderr || result.stdout || "docker info failed").trim();
+      fail(`Docker is required for \`oma up\`. Start Docker and retry.\n${detail}`);
+    }
+    return;
+  }
+  const command = process.env.OMA_MICROSANDBOX_COMMAND ?? "msb";
+  const result = spawnSync(command, ["--version"], { encoding: "utf8" });
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || `${command} --version failed`).trim();
+    fail(`Microsandbox is required for \`oma up --sandbox microsandbox\`.\n${detail}`);
+  }
+}
+
+function runChild(command, childArgs, env) {
+  return new Promise((resolve) => {
+    const child = spawn(command, childArgs, { cwd: root, env, stdio: "inherit" });
+    const onSigint = () => child.exitCode === null && child.kill("SIGINT");
+    const onSigterm = () => child.exitCode === null && child.kill("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    child.on("exit", (code, signal) => {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+      if (signal !== null) {
+        process.exit(signal === "SIGINT" ? 130 : 143);
+      }
+      if ((code ?? 0) !== 0) process.exit(code ?? 1);
+      resolve();
+    });
+  });
+}
+
+function checkNode() {
+  const [major = 0, minor = 0] = process.versions.node.split(".").map((part) => Number.parseInt(part, 10));
+  if (major < 22 || (major === 22 && minor < 19)) {
+    fail(`oma requires Node >= 22.19.0 (found ${process.versions.node})`);
+  }
+}
+
+function printHelp() {
+  console.log(`Open Managed Agents CLI
+
+Usage:
+  oma up [--sandbox docker|microsandbox]
+  oma smoke [--sandbox docker|microsandbox] [--local-compatible] [--egress]
+  oma keys mint [--workspace id] [--label label]
+  oma keys list [--workspace id]
+  oma workspaces list
+  oma providers status
+  oma models list [--provider name] [--available]
+  oma models validate [--file path]
+  oma auth set <provider> [--stdin]
+  oma auth status [provider]
+  oma auth remove <provider>
+  oma doctor [--sandbox docker|microsandbox] [--json]
+  oma admin init
+  oma admin status
+  oma version
+  oma help
+
+Commands:
+  up       Start the durable local appliance in the foreground. Docker is the default.
+  smoke      Run the disposable end-to-end alpha smoke test.
+  keys       Mint or list workspace API keys in the local appliance database.
+  workspaces  List local appliance workspaces.
+  providers   Inspect enabled Pi model providers and credential readiness.
+  models      List or validate enabled Pi models.
+  auth        Store, remove, or inspect model provider API-key credentials.
+  doctor      Run secret-safe, read-only local readiness diagnostics.
+  admin       Initialize or inspect local appliance admin mode.
+  version     Print the installed OMA version.
+
+Environment:
+  ANTHROPIC_API_KEY       Anthropic model credential used by the control plane.
+  OMA_MODEL_PROVIDERS     Enabled provider allowlist (default: anthropic,openai,openrouter).
+  OMA_DEFAULT_MODEL_PROVIDER / OMA_DEFAULT_MODEL
+                           Default exact model pair.
+  OMA_ALPHA_MODEL_PROVIDER / OMA_ALPHA_MODEL
+                           Exact provider/model used by oma smoke.
+  OMA_PI_AUTH_FILE        Pi auth storage path (default: $OMA_HOME/pi/auth.json).
+  OMA_PI_MODELS_FILE      Pi models.json path (default: $OMA_HOME/pi/models.json).
+  OMA_HOME                Durable data directory (default: ~/.oma).
+  OMA_HOST                Bind address (default: 127.0.0.1).
+  OMA_PORT                Listen port (default: 4180).
+
+Exit status:
+  0   Command or help completed successfully.
+  1   A readiness or runtime verification failed.
+  2   The invocation or local configuration was invalid.
+  130/143  Interrupted by SIGINT/SIGTERM.
+
+Planned, not implemented yet:
+  oma up --detach
+  oma status
+  oma logs
+  oma down
+  oma admin rotate`);
+}
+
+function commandHelpFor(key) {
+  return ({
+  up: ["Usage: oma up [--sandbox docker|microsandbox]", "Start OMA in the foreground. Docker is the default and includes the pinned HTTPS egress sidecar capability; environments remain default-deny.", "Examples: oma up; OMA_ENABLE_EGRESS=false oma up; oma up --sandbox microsandbox"],
+  smoke: ["Usage: oma smoke [--sandbox docker|microsandbox] [--local-compatible] [--egress]", "Run the disposable end-to-end alpha proof. --egress uses Docker plus the deterministic local-compatible model fixture to verify npm, PyPI/uv, GitHub, denial, and cleanup.", "Examples: oma smoke --local-compatible; oma smoke --egress"],
+  keys: ["Usage: oma keys <mint|list> [options]", "Manage workspace API keys in the local SQLite database.", "Examples: oma keys mint --workspace wrk_default; oma keys list --workspace wrk_default"],
+  "keys mint": ["Usage: oma keys mint [--workspace id] [--label label] [--db path]", "Mint a workspace key and print its plaintext once.", "Example: oma keys mint --workspace wrk_default --label console"],
+  "keys list": ["Usage: oma keys list [--workspace id] [--db path]", "List workspace key metadata without plaintext secrets.", "Example: oma keys list --workspace wrk_default"],
+  workspaces: ["Usage: oma workspaces list [--db path]", "List local workspaces.", "Example: oma workspaces list"],
+  "workspaces list": ["Usage: oma workspaces list [--db path]", "List local workspaces.", "Example: oma workspaces list --db ~/.oma/oma.sqlite"],
+  providers: ["Usage: oma providers status", "Inspect enabled Pi providers and credential readiness.", "Example: oma providers status"],
+  "providers status": ["Usage: oma providers status", "Inspect enabled Pi providers and credential readiness.", "Example: oma providers status"],
+  models: ["Usage: oma models <list|validate>", "Discover enabled models or validate models.json.", "Examples: oma models list --available; oma models validate"],
+  "models list": ["Usage: oma models list [--provider name] [--available]", "List enabled Pi models without exposing credentials.", "Example: oma models list --provider openai --available"],
+  "models validate": ["Usage: oma models validate [--file path]", "Validate deployment policy and Pi models.json without calling a provider.", "Example: oma models validate --file ~/.oma/pi/models.json"],
+  auth: ["Usage: oma auth <set|status|remove>", "Manage provider API-key credentials.", "Examples: printf '%s\\n' \"$OPENAI_API_KEY\" | oma auth set openai --stdin; oma auth status"],
+  "auth set": ["Usage: oma auth set <provider> [--stdin]", "Store a provider key without accepting it as a command-line argument.", "Example: printf '%s\\n' \"$OPENAI_API_KEY\" | oma auth set openai --stdin"],
+  "auth status": ["Usage: oma auth status [provider]", "Show credential readiness without secret values.", "Example: oma auth status openai"],
+  "auth remove": ["Usage: oma auth remove <provider>", "Remove a stored provider credential idempotently.", "Example: oma auth remove openai"],
+  admin: ["Usage: oma admin <init|status>", "Initialize or inspect appliance-wide admin mode.", "Examples: oma admin init; oma admin status"],
+  "admin init": ["Usage: oma admin init [--file path]", "Create a new owner-only admin key file; existing files are never overwritten.", "Example: oma admin init"],
+  "admin status": ["Usage: oma admin status", "Inspect admin configuration without printing the key.", "Example: oma admin status"],
+  doctor: ["Usage: oma doctor [--sandbox docker|microsandbox] [--json]", "Run read-only readiness checks. This command creates no OMA files and downloads no images.", "Examples: oma doctor; oma doctor --json", "Exit codes: 0 ready (warnings allowed), 1 readiness failures, 2 invalid invocation or internal diagnostic failure."],
+  version: ["Usage: oma version", "Print the installed OMA package version.", "Example: oma version"],
+  })[key];
+}
+
+function printCommandHelp(parts) {
+  const key = parts.join(" ");
+  const lines = commandHelpFor(key);
+  if (lines === undefined) fail(`Unknown help topic: ${key}\n\nRun \`oma --help\` for available commands.`);
+  console.log(`${lines.join("\n\n")}\n\nExit status: 0 success/help, 1 readiness or runtime failure, 2 invalid invocation/configuration, 130/143 interruption.\n\nAll command help exits 0 and performs no storage or network mutation.`);
+}
+
+function fail(message) {
+  console.error(`oma: ${message}`);
+  process.exit(2);
+}

package/dist/scripts/alpha-openai-compatible-fixture.mjs

@@ -0,0 +1,134 @@
+import { createServer } from "node:http";
+
+const MAX_REQUEST_BYTES = 1024 * 1024;
+
+export async function startAlphaOpenAICompatibleFixture(options) {
+  const requests = [];
+  const server = createServer(async (req, res) => {
+    try {
+      if (req.method !== "POST" || req.url !== "/v1/chat/completions") {
+        sendJson(res, 404, { error: { message: "not found" } });
+        return;
+      }
+      const body = JSON.parse(await readBody(req));
+      const authorization = req.headers.authorization;
+      requests.push({ body, authorization });
+      if (authorization !== `Bearer ${options.apiKey}`) {
+        sendJson(res, 401, { error: { message: "fixture rejected authorization" } });
+        return;
+      }
+      if (body.model !== options.modelId || body.stream !== true) {
+        sendJson(res, 400, { error: { message: "fixture received unexpected model request" } });
+        return;
+      }
+
+      const messages = Array.isArray(body.messages) ? body.messages : [];
+      const hasToolResult = messages.some((message) => message?.role === "tool");
+      if (!hasToolResult) {
+        const bash = Array.isArray(body.tools)
+          && body.tools.some((tool) => tool?.type === "function" && tool.function?.name === "bash");
+        if (!bash) {
+          sendJson(res, 400, { error: { message: "fixture expected the bash tool" } });
+          return;
+        }
+        sendSse(res, [
+          chunk(options.modelId, {
+            role: "assistant",
+            tool_calls: [{
+              index: 0,
+              id: "call_oma_alpha_smoke",
+              type: "function",
+              function: {
+                name: "bash",
+                arguments: JSON.stringify({ command: options.command ?? `printf ${options.token}` }),
+              },
+            }],
+          }),
+          chunk(options.modelId, {}, "tool_calls", usage()),
+        ]);
+        return;
+      }
+
+      if (!JSON.stringify(messages).includes(options.token)) {
+        sendJson(res, 400, { error: { message: "fixture did not receive the expected tool result" } });
+        return;
+      }
+      sendSse(res, [
+        chunk(options.modelId, { role: "assistant", content: options.token }),
+        chunk(options.modelId, {}, "stop", usage()),
+      ]);
+    } catch (error) {
+      sendJson(res, 500, { error: { message: error instanceof Error ? error.message : String(error) } });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Could not resolve fixture address");
+
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}`,
+    assertComplete() {
+      if (requests.length !== 2) {
+        throw new Error(`Compatible-provider fixture expected 2 model requests, observed ${requests.length}`);
+      }
+      if (!requests[1]?.body?.messages?.some((message) => message?.role === "tool")) {
+        throw new Error("Compatible-provider fixture did not observe the sandbox tool result round trip");
+      }
+    },
+    requestSummary() {
+      return requests.map(({ body }) => ({ model: body.model, stream: body.stream }));
+    },
+    async close() {
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}
+
+function chunk(model, delta, finishReason = null, chunkUsage) {
+  return {
+    id: "chatcmpl-oma-alpha",
+    object: "chat.completion.chunk",
+    created: 1,
+    model,
+    choices: [{ index: 0, delta, finish_reason: finishReason }],
+    ...(chunkUsage === undefined ? {} : { usage: chunkUsage }),
+  };
+}
+
+function usage() {
+  return { prompt_tokens: 10, completion_tokens: 3, total_tokens: 13 };
+}
+
+function sendSse(res, chunks) {
+  res.writeHead(200, {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+  });
+  for (const value of chunks) res.write(`data: ${JSON.stringify(value)}\n\n`);
+  res.end("data: [DONE]\n\n");
+}
+
+function sendJson(res, status, body) {
+  if (res.headersSent) return;
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+async function readBody(req) {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > MAX_REQUEST_BYTES) throw new Error("fixture request exceeded 1 MiB");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}