@numairbaseer/scifcode 0.1.2

package/LICENSE

@@ -0,0 +1,5 @@
+Proprietary
+
+Copyright (c) 2026.
+
+All rights reserved.

package/README.md

@@ -0,0 +1,147 @@
+# Scifcode
+
+Scifcode is the user-facing configuration wrapper for the Scifcode coding agent powered by Poolside Laguna.
+
+This v0.1 is intentionally small: it installs one global `scifcode` command, configures the Scifcode runtime to use Laguna, and launches the coding agent with Scifcode defaults.
+
+## Install
+
+Scifcode requires Node.js `>=22.19.0`. It depends on `@numairbaseer/scifcode-runtime`,
+which installs the compiled runtime for the current operating system and CPU.
+Users do not need Bun or a source checkout.
+
+```bash
+npm install -g @numairbaseer/scifcode
+```
+
+Supported runtime packages cover:
+
+- macOS: arm64 and x64
+- Linux: arm64 and x64, with glibc and musl variants
+- Windows: arm64 and x64
+- baseline x64 builds for CPUs without AVX2
+
+## Configure
+
+Scifcode does not store API keys in the repo. Set the API key or bearer token
+for your configured endpoint in the current shell:
+
+```bash
+export SCIFCODE_API_KEY="endpoint_or_modal_bearer_token"
+```
+
+Scifcode uses the project's fixed Modal endpoint:
+
+```bash
+https://danishshaik--reservoir-vllm-serve.modal.run/v1
+```
+
+You usually only need to set `SCIFCODE_API_KEY`. The provider and model are
+fixed to the Scifcode Modal deployment.
+
+## Run
+
+```bash
+cd your-repo
+scifcode
+```
+
+## One-shot prompt
+
+```bash
+scifcode -p "Review the current diff for correctness and missing tests."
+```
+
+## Check your installation
+
+```bash
+scifcode doctor
+```
+
+`doctor` creates or updates Scifcode's provider config, checks whether the runtime can be resolved, and verifies that an API key is present.
+
+## Initialize config explicitly
+
+```bash
+scifcode init
+```
+
+`init` creates or updates:
+
+```text
+~/.config/scifcode/scifcode.json
+```
+
+Normal `scifcode` and `scifcode doctor` commands also ensure this config exists so the first Laguna smoke test stays short.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+| --- | ---: | --- | --- |
+| `SCIFCODE_API_KEY` | yes | none | API key or bearer token for the configured endpoint |
+| `SCIFCODE_CONTEXT_WINDOW` | no | `32768` | Context window reported for `scifcode-1.0` |
+| `SCIFCODE_MAX_TOKENS` | no | `8192` | Maximum output tokens reported for `scifcode-1.0` |
+| `SCIFCODE_RUNTIME_BIN` | no | installed platform package | Override path to a compiled Scifcode runtime binary |
+| `SCIFCODE_SOURCE_DIR` | no | adjacent `../scifcode` | Development-only path to the Scifcode source fork |
+| `SCIFCODE_BUN_BIN` | no | auto-detected | Development-only Bun executable used to run the fork from source |
+
+Scifcode also loads private env defaults from:
+
+```text
+~/.scifcode/env
+./.scifcode.env
+```
+
+Shell environment variables win over these files. Keep API keys in the global
+file or an ignored project `.scifcode.env`, not in committed source.
+
+## Troubleshooting
+
+### `Scifcode requires SCIFCODE_API_KEY`
+
+Set your key:
+
+```bash
+export SCIFCODE_API_KEY="endpoint_or_modal_bearer_token"
+```
+
+Then retry:
+
+```bash
+scifcode doctor
+scifcode
+```
+
+### Invalid Scifcode config
+
+Scifcode writes to:
+
+```text
+~/.config/scifcode/scifcode.json
+```
+
+If this file contains invalid JSON, fix it or move it aside and rerun:
+
+```bash
+scifcode init
+```
+
+### Modal A100 endpoint
+
+Scifcode can also point at an OpenAI Chat Completions-compatible endpoint
+served from Modal. See `docs/modal-a100.md` for a Laguna XS.2 vLLM scaffold.
+
+## Security
+
+Scifcode v0.1 does not store API keys in the repo. It writes an environment
+variable reference such as `{env:SCIFCODE_API_KEY}` into its runtime config and
+passes the current process environment to the agent process. `LAGUNA_API_KEY` is
+still accepted as a legacy fallback.
+
+Scifcode launches the installed platform runtime directly with argument arrays
+and does not use shell string execution. Bun/source execution remains available
+only as a local-development fallback.
+
+## Third-party notices
+
+Scifcode uses third-party open-source software internally. See `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-Party Notices
+
+Scifcode uses third-party open-source software.
+
+## Agent Runtime
+
+Scifcode is based on a fork of the OpenCode agent runtime, which is licensed
+under the MIT License.
+
+See https://github.com/anomalyco/opencode for the upstream project and license.
+
+## Poolside Laguna
+
+Scifcode is configured to use Poolside Laguna models through an API-compatible provider configuration.
+
+Use of Laguna models is subject to the applicable Poolside, OpenRouter, or customer API-provider terms, depending on how the customer obtains access.

package/assets/AGENTS.md

@@ -0,0 +1,16 @@
+# Scifcode Agent Instructions
+
+You are Scifcode, a software engineering assistant optimized for safe, validated code changes.
+
+Default workflow:
+1. Inspect the repository before editing.
+2. Prefer small, reviewable changes.
+3. Before modifying files, explain the intended change.
+4. After editing, run the most relevant tests or checks.
+5. If tests cannot be run, explain exactly why.
+6. Summarize changed files and risks.
+
+Safety rules:
+- Do not run destructive shell commands without asking.
+- Do not modify secrets, credentials, lockfiles, or deployment config unless directly requested.
+- Do not invent APIs. Inspect existing code first.

package/bin/scifcode.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+main();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@numairbaseer/scifcode",
+  "version": "0.1.2",
+  "description": "Scifcode: a coding CLI agent powered by Poolside Laguna.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/numairbaseer/reservoir.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "bin": {
+    "scifcode": "./bin/scifcode.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "lint": "node --check bin/scifcode.js && node --check src/cli.js && node --check src/constants.js && node --check src/env-config.js && node --check src/ensure-scifcode-config.js && node --check src/paths.js && node --check src/run-runtime.js",
+    "prepack": "npm test && npm run lint"
+  },
+  "dependencies": {
+    "@numairbaseer/scifcode-runtime": "0.1.2"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "Proprietary"
+}

package/src/cli.js

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureScifcodeConfig } from "./ensure-scifcode-config.js";
+import { loadScifcodeEnv } from "./env-config.js";
+import { resolveRuntimeBin, runRuntime } from "./run-runtime.js";
+import {
+  API_KEY_ENV_NAME,
+  DEFAULT_BASE_URL,
+  DEFAULT_MODEL,
+  DEFAULT_PROVIDER_NAME,
+  LEGACY_API_KEY_ENV_NAME
+} from "./constants.js";
+
+export function printHelp(stdout = console.log) {
+  stdout(`Scifcode - coding CLI agent powered by Poolside Laguna
+
+Usage:
+  scifcode                 Start interactive coding agent
+  scifcode -p "prompt"     Run one-shot prompt
+  scifcode init            Initialize local Scifcode runtime config
+  scifcode doctor          Check installation and configuration
+
+Required environment:
+  SCIFCODE_API_KEY        API key or bearer token for the configured endpoint
+
+Optional environment:
+  SCIFCODE_RUNTIME_BIN     Path to a compiled Scifcode runtime binary
+  SCIFCODE_SOURCE_DIR      Path to the Scifcode OpenCode fork
+  SCIFCODE_BUN_BIN         Path to Bun when launching the fork from source
+
+Private config files:
+  ~/.scifcode/env          Default environment loaded before shell env
+  ./.scifcode.env          Project override loaded before shell env
+`);
+}
+
+export function getPackageVersion() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const srcDir = path.dirname(currentFile);
+  const packagePath = path.join(srcDir, "..", "package.json");
+  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  return pkg.version;
+}
+
+function createConsoleWriters(stdout, stderr) {
+  return {
+    log(message = "") {
+      stdout(String(message));
+    },
+    error(message = "") {
+      stderr(String(message));
+    }
+  };
+}
+
+function printInitResult(result, log) {
+  log("Scifcode config initialized.");
+  log(`Scifcode config path: ${result.configPath}`);
+  log(`Provider: ${result.providerName}`);
+  log(`Base URL: ${result.baseUrl}`);
+}
+
+function printDoctorHeader(configResult, hasApiKey, runtimeResolved, env, log) {
+  log("Scifcode doctor");
+  log(`${API_KEY_ENV_NAME} configured: ${hasApiKey ? "yes" : "no"}`);
+  log(`Base URL: ${configResult.baseUrl}`);
+  log(`Scifcode runtime resolved: ${runtimeResolved ? "yes" : "no"}`);
+  log(`Scifcode config path: ${configResult.configPath}`);
+  log(`Scifcode provider configured: yes`);
+  log(`Provider: ${configResult.providerName}`);
+  log(`Default model: ${DEFAULT_MODEL}`);
+}
+
+export function main(options = {}) {
+  const args = options.args || process.argv.slice(2);
+  const command = args[0];
+  const baseEnv = options.env || process.env;
+  const shouldLoadEnv = options.loadEnvFile ?? !options.env;
+  const env = shouldLoadEnv
+    ? loadScifcodeEnv({
+        env: baseEnv,
+        cwd: options.cwd,
+        homeDir: options.homeDir
+      })
+    : baseEnv;
+  const exit = options.exit || process.exit;
+  const ensureScifcodeConfigFn =
+    options.ensureScifcodeConfigFn || ensureScifcodeConfig;
+  const resolveRuntimeBinFn = options.resolveRuntimeBinFn || resolveRuntimeBin;
+  const runRuntimeFn = options.runRuntimeFn || runRuntime;
+  const writers = createConsoleWriters(
+    options.stdout || console.log,
+    options.stderr || console.error
+  );
+
+  if (command === "--help" || command === "-h") {
+    printHelp(writers.log);
+    exit(0);
+    return;
+  }
+
+  if (command === "--version" || command === "-v") {
+    writers.log(getPackageVersion());
+    exit(0);
+    return;
+  }
+
+  if (command === "init") {
+    try {
+      const result = ensureScifcodeConfigFn({ env });
+      printInitResult(result, writers.log);
+      exit(0);
+    } catch (error) {
+      writers.error(error.message);
+      exit(1);
+    }
+    return;
+  }
+
+  if (command === "doctor") {
+    let configResult;
+    let runtimeResolved = false;
+    let runtimeError = null;
+
+    try {
+      configResult = ensureScifcodeConfigFn({ env });
+    } catch (error) {
+      writers.error("Scifcode doctor");
+      writers.error("Scifcode config: error");
+      writers.error(error.message);
+      exit(1);
+      return;
+    }
+
+    try {
+      resolveRuntimeBinFn({ env });
+      runtimeResolved = true;
+    } catch (error) {
+      runtimeError = error;
+    }
+
+    const hasApiKey = Boolean(env[API_KEY_ENV_NAME] || env[LEGACY_API_KEY_ENV_NAME]);
+    printDoctorHeader(configResult, hasApiKey, runtimeResolved, env, writers.log);
+
+    if (!runtimeResolved) {
+      writers.log("Status: Scifcode runtime resolution failed");
+      writers.error(runtimeError.message);
+      exit(1);
+      return;
+    }
+
+    if (!hasApiKey) {
+      writers.log(`Status: missing ${API_KEY_ENV_NAME}`);
+      writers.log("");
+      writers.log("Set it with:");
+      writers.log(`  export ${API_KEY_ENV_NAME}="endpoint_or_modal_bearer_token"`);
+      exit(1);
+      return;
+    }
+
+    writers.log("Status: ok");
+    exit(0);
+    return;
+  }
+
+  try {
+    ensureScifcodeConfigFn({ env });
+  } catch (error) {
+    writers.error(error.message);
+    exit(1);
+    return;
+  }
+
+  runRuntimeFn(args, { env, exit, stderr: writers.error });
+}

package/src/constants.js

@@ -0,0 +1,8 @@
+export const DEFAULT_PROVIDER_NAME = "scifcode";
+export const DEFAULT_BASE_URL = "https://danishshaik--reservoir-vllm-serve.modal.run/v1";
+export const DEFAULT_MODEL = "reservoir-modal";
+export const DEFAULT_MODEL_NAME = "scifcode-1.0";
+export const DEFAULT_CONTEXT_WINDOW = 32768;
+export const DEFAULT_MAX_TOKENS = 8192;
+export const API_KEY_ENV_NAME = "SCIFCODE_API_KEY";
+export const LEGACY_API_KEY_ENV_NAME = "LAGUNA_API_KEY";

package/src/ensure-scifcode-config.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import { API_KEY_ENV_NAME, DEFAULT_BASE_URL, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_MODEL, DEFAULT_MODEL_NAME, DEFAULT_PROVIDER_NAME, LEGACY_API_KEY_ENV_NAME } from "./constants.js";
+import { getScifcodeConfigDir, getScifcodeConfigPath } from "./paths.js";
+
+function positiveInteger(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function buildScifcodeModels(env = process.env) {
+  return {
+    [DEFAULT_MODEL]: {
+    name: DEFAULT_MODEL_NAME,
+    limit: {
+      context: positiveInteger(env.SCIFCODE_CONTEXT_WINDOW, DEFAULT_CONTEXT_WINDOW),
+      output: positiveInteger(env.SCIFCODE_MAX_TOKENS, DEFAULT_MAX_TOKENS)
+    }
+    }
+  };
+}
+
+export function getApiKeyReference(env = process.env) {
+  return env[LEGACY_API_KEY_ENV_NAME] && !env[API_KEY_ENV_NAME]
+    ? `{env:${LEGACY_API_KEY_ENV_NAME}}`
+    : `{env:${API_KEY_ENV_NAME}}`;
+}
+
+export function buildScifcodeProvider(env = process.env) {
+  return {
+    npm: "@ai-sdk/openai-compatible",
+    name: "Scifcode",
+    options: {
+      baseURL: DEFAULT_BASE_URL,
+      apiKey: getApiKeyReference(env)
+    },
+    models: buildScifcodeModels(env)
+  };
+}
+
+function readConfig(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch (error) { throw new Error(`Scifcode could not parse ${filePath}. Fix the JSON and retry.\n${error.message}`); }
+}
+
+export function ensureScifcodeConfig(options = {}) {
+  const env = options.env || process.env;
+  const configDir = getScifcodeConfigDir(options.homeDir);
+  const configPath = getScifcodeConfigPath(options.homeDir);
+  const providerName = DEFAULT_PROVIDER_NAME;
+  const existing = readConfig(configPath);
+  const provider = buildScifcodeProvider(env);
+  const merged = {
+    ...existing,
+    $schema: existing.$schema || "https://opencode.ai/config.json",
+    enabled_providers: [providerName],
+    model: `${providerName}/${DEFAULT_MODEL}`,
+    permission: {
+      ...(existing.permission && typeof existing.permission === "object" ? existing.permission : {}),
+      edit: "ask",
+      bash: "ask"
+    },
+    provider: {
+      ...(existing.provider && typeof existing.provider === "object" ? existing.provider : {}),
+      [providerName]: provider
+    }
+  };
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(merged, null, 2)}\n`);
+  return { configPath, providerName, baseUrl: provider.options.baseURL };
+}

package/src/env-config.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import {
+  getProjectScifcodeEnvPath,
+  getScifcodeEnvPath
+} from "./paths.js";
+
+function unquoteValue(value) {
+  const trimmed = value.trim();
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+
+  if (
+    trimmed.length >= 2 &&
+    ((first === '"' && last === '"') || (first === "'" && last === "'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+
+  return trimmed;
+}
+
+export function parseEnvContent(content) {
+  const parsed = {};
+
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const exportPrefix = "export ";
+    const normalized = trimmed.startsWith(exportPrefix)
+      ? trimmed.slice(exportPrefix.length).trim()
+      : trimmed;
+    const equalsIndex = normalized.indexOf("=");
+
+    if (equalsIndex <= 0) {
+      continue;
+    }
+
+    const key = normalized.slice(0, equalsIndex).trim();
+    const value = normalized.slice(equalsIndex + 1);
+
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      parsed[key] = unquoteValue(value);
+    }
+  }
+
+  return parsed;
+}
+
+function readEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+
+  return parseEnvContent(fs.readFileSync(filePath, "utf8"));
+}
+
+export function loadScifcodeEnv(options = {}) {
+  const env = options.env || process.env;
+  const globalEnv = readEnvFile(getScifcodeEnvPath(options.homeDir));
+  const projectEnv = readEnvFile(getProjectScifcodeEnvPath(options.cwd));
+
+  return {
+    ...globalEnv,
+    ...projectEnv,
+    ...env
+  };
+}

package/src/paths.js

@@ -0,0 +1,8 @@
+import os from "node:os";
+import path from "node:path";
+
+export function getScifcodeHomeDir(homeDir = os.homedir()) { return path.join(homeDir, ".scifcode"); }
+export function getScifcodeEnvPath(homeDir = os.homedir()) { return path.join(getScifcodeHomeDir(homeDir), "env"); }
+export function getProjectScifcodeEnvPath(cwd = process.cwd()) { return path.join(cwd, ".scifcode.env"); }
+export function getScifcodeConfigDir(homeDir = os.homedir()) { return path.join(homeDir, ".config", "scifcode"); }
+export function getScifcodeConfigPath(homeDir = os.homedir()) { return path.join(getScifcodeConfigDir(homeDir), "scifcode.json"); }

package/src/run-runtime.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { API_KEY_ENV_NAME, DEFAULT_MODEL, DEFAULT_PROVIDER_NAME, LEGACY_API_KEY_ENV_NAME } from "./constants.js";
+
+function executableOnPath(name, env = process.env) {
+  return String(env.PATH || "").split(path.delimiter).map(dir => path.join(dir, name)).find(fs.existsSync);
+}
+
+function defaultSourceDir() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "scifcode");
+}
+
+function findInstalledRuntime(options = {}) {
+  let current = options.searchDir || path.dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    const candidate = path.join(current, "node_modules", "@numairbaseer", "scifcode-runtime", "bin", "scifcode.exe");
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return;
+    current = parent;
+  }
+}
+
+export function resolveRuntime(options = {}) {
+  const env = options.env || process.env;
+  if (env.SCIFCODE_RUNTIME_BIN) {
+    if (!fs.existsSync(env.SCIFCODE_RUNTIME_BIN)) throw new Error(`SCIFCODE_RUNTIME_BIN does not exist: ${env.SCIFCODE_RUNTIME_BIN}`);
+    return { command: env.SCIFCODE_RUNTIME_BIN, argsPrefix: [], source: "binary" };
+  }
+  const installedBin = findInstalledRuntime(options);
+  if (installedBin) return { command: installedBin, argsPrefix: [], source: "package" };
+  const sourceDir = env.SCIFCODE_SOURCE_DIR || defaultSourceDir();
+  const runtimePlatform = options.platform || process.platform;
+  const platform = runtimePlatform === "win32" ? "windows" : runtimePlatform;
+  const arch = options.arch || process.arch;
+  const binaryName = runtimePlatform === "win32" ? "scifcode.exe" : "scifcode";
+  const builtBin = path.join(sourceDir, "packages", "opencode", "dist", `scifcode-${platform}-${arch}`, "bin", binaryName);
+  if (fs.existsSync(builtBin)) return { command: builtBin, argsPrefix: [], source: "binary" };
+  const packageDir = path.join(sourceDir, "packages", "opencode");
+  const entrypoint = path.join(packageDir, "src", "index.ts");
+  const bunName = process.platform === "win32" ? "bun.exe" : "bun";
+  const bunInstall = env.BUN_INSTALL && path.join(env.BUN_INSTALL, "bin", bunName);
+  const standardBun = path.join(options.homeDir || os.homedir(), ".bun", "bin", bunName);
+  const bun = env.SCIFCODE_BUN_BIN
+    || executableOnPath("bun", env)
+    || (bunInstall && fs.existsSync(bunInstall) ? bunInstall : undefined)
+    || (fs.existsSync(standardBun) ? standardBun : undefined);
+  if (bun && fs.existsSync(entrypoint)) {
+    return {
+      command: bun,
+      argsPrefix: ["run", "--conditions=browser", entrypoint],
+      source: "source",
+      cwd: packageDir
+    };
+  }
+  throw new Error("Could not resolve the Scifcode runtime package. Install dependencies or set SCIFCODE_RUNTIME_BIN.");
+}
+
+export function resolveRuntimeBin(options = {}) { return resolveRuntime(options).command; }
+
+export function buildRuntimeArgs(userArgs = [], env = process.env, runtime = resolveRuntime({ env }), projectDir = process.cwd()) {
+  const model = `${DEFAULT_PROVIDER_NAME}/${DEFAULT_MODEL}`;
+  const args = [...userArgs];
+  const promptIndex = args.findIndex(arg => arg === "-p" || arg === "--prompt");
+  const translated = promptIndex >= 0 ? ["run", args[promptIndex + 1] || "", ...args.slice(0, promptIndex), ...args.slice(promptIndex + 2)] : args;
+  const scoped = runtime.source !== "source"
+    ? translated
+    : translated[0] === "run"
+      ? [...translated, "--dir", projectDir]
+      : translated.length === 0
+        ? [projectDir]
+        : translated;
+  const withoutModelOverrides = scoped.filter((arg, index) => {
+    if (arg.startsWith("--model=")) return false;
+    if (arg === "--model" || arg === "-m") return false;
+    return scoped[index - 1] !== "--model" && scoped[index - 1] !== "-m";
+  });
+  return [...runtime.argsPrefix, "--model", model, ...withoutModelOverrides];
+}
+
+export function buildRuntimeEnv(env = process.env) {
+  const runtimeEnv = { ...env };
+  if (!runtimeEnv[API_KEY_ENV_NAME] && env[LEGACY_API_KEY_ENV_NAME]) runtimeEnv[API_KEY_ENV_NAME] = env[LEGACY_API_KEY_ENV_NAME];
+  return runtimeEnv;
+}
+
+export function validateLagunaApiKey(env = process.env) { return Boolean(env[API_KEY_ENV_NAME] || env[LEGACY_API_KEY_ENV_NAME]); }
+export function printMissingApiKey(stderr = console.error) {
+  stderr(`Scifcode requires ${API_KEY_ENV_NAME}.`);
+  stderr("");
+  stderr(`Run:\n  export ${API_KEY_ENV_NAME}="endpoint_or_modal_bearer_token"\n  scifcode`);
+}
+
+export function runRuntime(userArgs = [], options = {}) {
+  const env = options.env || process.env;
+  const stderr = options.stderr || console.error;
+  const exit = options.exit || process.exit;
+  if (!validateLagunaApiKey(env)) { printMissingApiKey(stderr); exit(1); return null; }
+  let runtime;
+  try { runtime = (options.resolveRuntimeFn || resolveRuntime)({ env }); }
+  catch (error) { stderr("Failed to resolve the Scifcode agent runtime."); stderr(error.message); exit(1); return null; }
+  const runtimeEnv = buildRuntimeEnv(env);
+  const projectDir = options.cwd || process.cwd();
+  const child = (options.spawnFn || spawn)(runtime.command, buildRuntimeArgs(userArgs, runtimeEnv, runtime, projectDir), {
+    stdio: "inherit",
+    env: runtimeEnv,
+    cwd: runtime.cwd || projectDir
+  });
+  child.on("exit", code => exit(code ?? 0));
+  child.on("error", error => { stderr("Failed to launch Scifcode."); stderr(error.message); exit(1); });
+  return child;
+}