xcoder-dna 0.0.0-stage → 1.3.0

package/dist/config/loadConfig.js

@@ -0,0 +1,240 @@
+// xcoder:version 3 | xcoder:task task-f9cf18 | xcoder:updated 2026-11-02T16:14:36.637Z | xcoder:subtask code-st-077ea2
+// LLM config — per-role provider configuration (design: llm-provider-config)
+import dotenv from "dotenv";
+import fs from "node:fs";
+import path from "node:path";
+import * as yaml from "js-yaml";
+import os from "node:os";
+import { log } from "../util/logger.js";
+import { createXcoderPaths } from "../util/xcoder-paths.js";
+import { getAppDir, resolveSkillsRoot } from "../skills/skills-root.js";
+import { applyUserConfig, getActiveUserConfig } from "./user-config.js";
+// ============================================================================
+// Environment Initialization (Must run before reading process.env)
+// ============================================================================
+// getAppDir now lives in skills-root.ts (the single source of truth for skill
+// discovery) and is re-exported here so existing importers keep working.
+export { getAppDir };
+function loadXcoderEnv() {
+    const envCandidates = [];
+    // 1. App directory (where xcoder.exe / app bundle lives)
+    const appDir = getAppDir();
+    envCandidates.push(path.join(appDir, ".env"));
+    // 2. XCODER_HOME directory (if defined)
+    if (process.env.XCODER_HOME) {
+        envCandidates.push(path.join(process.env.XCODER_HOME, ".env"));
+    }
+    // 3. User's global home directory (~/.xcoder/.env or C:\Users\<user>\.xcoder\.env)
+    const globalXcoderDir = path.join(os.homedir(), ".xcoder");
+    envCandidates.push(path.join(globalXcoderDir, ".env"));
+    // Ensure global ~/.xcoder directory exists for users
+    if (!fs.existsSync(globalXcoderDir)) {
+        fs.mkdirSync(globalXcoderDir, { recursive: true });
+    }
+    // Load global/system candidate .env files first
+    for (const envPath of envCandidates) {
+        if (fs.existsSync(envPath)) {
+            dotenv.config({ path: envPath });
+        }
+    }
+    // 4. Current working directory .env (highest priority local overrides)
+    const cwdEnvPath = path.join(process.cwd(), ".env");
+    if (fs.existsSync(cwdEnvPath)) {
+        dotenv.config({ path: cwdEnvPath, override: true });
+    }
+}
+// Execute environment loader immediately on module load
+loadXcoderEnv();
+// ~/.xcoder/config.json (provider / key / model / base_url / env) — beats .env files, loses to the real shell env.
+applyUserConfig();
+// Back-compat: accept legacy RONIN_* variables from before the rebrand.
+for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("RONIN_")) {
+        const renamed = `XCODER_${key.slice("RONIN_".length)}`;
+        if (process.env[renamed] === undefined)
+            process.env[renamed] = value;
+    }
+}
+export const AGENT_ROLES = [
+    "orchestrator",
+    "sub_agent",
+    "swarm_agent",
+    "instance_agent",
+];
+const RELATIVE_CONFIG_PATH = ".xcoder/config/llm.yaml";
+const RELATIVE_HOME_PATH = path.join("./");
+const RELATIVE_AGENT_PATH = ".xcoder";
+/**
+ * Shared candidate-path resolution used by resolveSkillsPath, resolveConfigPath,
+ * and resolveAgentPath. Checks, in order:
+ *   1. App directory (where this source file/code is running from)
+ *   2. XCODER_HOME env variable (if set)
+ *   3. Current working directory
+ *   4. User's home directory
+ * Returns the first candidate that exists on disk, or the app-directory
+ * candidate as a fallback if none exist (so callers always get a usable
+ * default path even when nothing has been created yet).
+ *
+ * Set XCODER_DEBUG_CONFIG_PATH=1 to log which candidate was selected.
+ */
+function resolveFirstExisting(relativePath) {
+    const appDir = getAppDir();
+    const candidatePaths = [path.join(appDir, relativePath)];
+    if (process.env.XCODER_HOME) {
+        candidatePaths.push(path.join(process.env.XCODER_HOME, relativePath));
+    }
+    candidatePaths.push(path.join(process.cwd(), relativePath));
+    candidatePaths.push(path.join(os.homedir(), relativePath));
+    for (const candidate of candidatePaths) {
+        if (fs.existsSync(candidate)) {
+            if (process.env.XCODER_DEBUG_CONFIG_PATH) {
+                log.dim(`configPath: ${candidate}`);
+            }
+            return candidate;
+        }
+    }
+    // Nothing found anywhere — fall back to the app-directory candidate so
+    // downstream code (e.g. loadLlmConfig) still gets a deterministic path
+    // and applies its own defaults.
+    return candidatePaths[0] ?? path.join(process.cwd(), RELATIVE_CONFIG_PATH);
+}
+/**
+ * Returns a directory D such that `D/skills` is the resolved skills directory.
+ *
+ * @deprecated Use `resolveSkillsRoot()` from `src/skills/skills-root.ts` — it
+ * is the single source of truth and also tells you which candidate won and
+ * how many packs are actually usable. This wrapper is kept only so existing
+ * importers do not break.
+ */
+export function resolveSkillsPath() {
+    return resolveSkillsRoot().root;
+}
+export function resolveConfigPath() {
+    return resolveFirstExisting(RELATIVE_HOME_PATH);
+}
+export function resolveAgentPath() {
+    return resolveFirstExisting(RELATIVE_AGENT_PATH);
+}
+/**
+ * Built-in DeepSeek default — used when no config file exists and as the
+ * fallback for every role. Reads XCODER_MODEL lazily so env changes between
+ * calls are honored.
+ *
+ * Provider `deepseek` is served through DeepSeek's Anthropic-compatible
+ * endpoint (`@anthropic-ai/sdk`, which appends `/v1/messages` to the base
+ * URL), so the canonical root is `https://api.deepseek.com/anthropic` —
+ * NOT the OpenAI-compatible `https://api.deepseek.com/v1`, which would
+ * produce the invalid `.../v1/v1/messages` request path.
+ */
+export function deepseekDefaultConfig() {
+    return {
+        provider: "deepseek",
+        base_url: "https://api.deepseek.com/anthropic",
+        model: process.env.XCODER_MODEL ?? "deepseek-chat",
+        api_key_env: "DEEPSEEK_API_KEY",
+        max_tokens: 16384,
+        temperature: 0.0,
+        thinking: false,
+    };
+}
+/**
+ * Read `.xcoder/config/llm.yaml` and return the raw per-role schema.
+ * Merge happens in `resolveLlmConfig`, not here. A legacy file shaped as a
+ * single provider block is interpreted as the `default` block.
+ */
+export function loadLlmConfigFile(configPath) {
+    const resolved = configPath ?? createXcoderPaths(process.cwd()).llmConfigPath();
+    if (!fs.existsSync(resolved)) {
+        return {};
+    }
+    const raw = yaml.load(fs.readFileSync(resolved, "utf-8"));
+    if (!raw || typeof raw !== "object") {
+        return {};
+    }
+    const obj = raw;
+    // New per-role schema wins even when the file also carries legacy
+    // top-level keys (e.g. a partially migrated file with both a legacy
+    // `provider:` block and `default`/role blocks). Treating such a file as
+    // a single legacy `default` block silently discards every role block.
+    if ("default" in obj ||
+        AGENT_ROLES.some((role) => obj[role] && typeof obj[role] === "object")) {
+        return obj;
+    }
+    if ("provider" in obj || "model" in obj) {
+        return { default: obj };
+    }
+    return obj;
+}
+/**
+ * Resolve the effective LLM config for a role.
+ * Precedence: role block → `default` block → built-in DeepSeek default.
+ * `XCODER_MODEL` is applied as an env override for `model` only.
+ */
+const PROVIDER_DEFAULTS = {
+    deepseek: { base_url: "https://api.deepseek.com/anthropic", model: "deepseek-chat" },
+    anthropic: {},
+    "openai-compatible": {},
+};
+/**
+ * Overlay `~/.xcoder/config.json` (provider / key / model / base_url) on a
+ * resolved block. Switching provider also resets base_url to that provider's
+ * default, so a key is never sent to the previous provider's host.
+ */
+export function applyUserLlmOverrides(cfg) {
+    const uc = getActiveUserConfig();
+    if (!uc.provider && !uc.key && !uc.model && !uc.base_url)
+        return cfg;
+    const out = { ...cfg };
+    if (uc.provider && uc.provider !== cfg.provider) {
+        out.provider = uc.provider;
+        out.base_url = PROVIDER_DEFAULTS[uc.provider].base_url;
+        out.endpoint = undefined;
+        if (!uc.model && PROVIDER_DEFAULTS[uc.provider].model)
+            out.model = PROVIDER_DEFAULTS[uc.provider].model;
+    }
+    if (uc.base_url)
+        out.base_url = uc.base_url;
+    if (uc.model)
+        out.model = uc.model;
+    if (uc.key)
+        out.api_key_env = "XCODER_API_KEY";
+    return out;
+}
+export function resolveLlmConfig(role, file) {
+    const selected = applyUserLlmOverrides((file && (file[role] ?? file.default)) ?? deepseekDefaultConfig());
+    const envModel = process.env.XCODER_MODEL;
+    return {
+        ...selected,
+        provider: selected.provider ?? "deepseek",
+        model: envModel ?? selected.model ?? "deepseek-chat",
+        max_tokens: selected.max_tokens ?? 16384,
+        temperature: selected.temperature ?? 0.0,
+        api_key_env: selected.api_key_env ?? "DEEPSEEK_API_KEY",
+    };
+}
+/**
+ * @deprecated Legacy loader — returns the merged `default` block. New code
+ * should use `loadLlmConfigFile()` + `resolveLlmConfig(role, file)`.
+ */
+export function loadLlmConfig(configPath) {
+    const file = loadLlmConfigFile(configPath);
+    const block = applyUserLlmOverrides(file.default ?? deepseekDefaultConfig());
+    const envModel = process.env.XCODER_MODEL;
+    return {
+        ...block,
+        provider: block.provider ?? "deepseek",
+        model: envModel ?? block.model ?? "deepseek-chat",
+        max_tokens: block.max_tokens ?? 16384,
+        temperature: block.temperature ?? 0.0,
+        api_key_env: block.api_key_env ?? "DEEPSEEK_API_KEY",
+    };
+}
+export function resolveModelForSkill(config, skillName) {
+    const override = skillName ? config.overrides?.[skillName] : undefined;
+    return {
+        model: override?.model ?? config.model,
+        temperature: override?.temperature ?? config.temperature,
+        thinking: override?.thinking ?? config.thinking ?? false,
+        reasoningEffort: override?.reasoning_effort ?? config.reasoning_effort,
+    };
+}

package/dist/config/secure-mode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Single source of truth for secure-mode resolution.
+ *
+ * No CLI, orchestrator or agent may read `process.argv` or `XCODER_SECURE`
+ * directly (CORE-04: one default, one source of truth). Every entry point
+ * resolves the mode here and threads the result inward.
+ *
+ * Resolution order: explicit flag > XCODER_SECURE env > default ("disabled").
+ * Never throws: an unparseable env value falls back to the default and is
+ * reported as `source: "default"` — a bad env var must not brick the CLI.
+ */
+export type SecureMode = "enforced" | "disabled";
+export type SecureModeSource = "flag" | "env" | "default";
+export interface SecureModeResolution {
+    readonly mode: SecureMode;
+    readonly source: SecureModeSource;
+    /** Convenience boolean mirroring `mode === "enforced"`. */
+    readonly enabled: boolean;
+    /** Human-readable, e.g. "secure enforcement: on (flag)". */
+    readonly description: string;
+}
+export declare function resolveSecureMode(input: {
+    readonly secureFlag?: boolean;
+    readonly env?: string | undefined;
+}): SecureModeResolution;
+/** Default mode constant, exported so consumers never re-declare the default. */
+export declare const DEFAULT_SECURE_MODE: SecureMode;
+/** Env var name consumed by every CLI entry point. */
+export declare const SECURE_MODE_ENV_VAR = "XCODER_SECURE";

package/dist/config/secure-mode.js

@@ -0,0 +1,63 @@
+// xcoder:version 1 | xcoder:task task-ebf4f7 | xcoder:updated 2026-10-17T12:16:05.781Z | xcoder:subtask test-st-f454da
+/**
+ * Single source of truth for secure-mode resolution.
+ *
+ * No CLI, orchestrator or agent may read `process.argv` or `XCODER_SECURE`
+ * directly (CORE-04: one default, one source of truth). Every entry point
+ * resolves the mode here and threads the result inward.
+ *
+ * Resolution order: explicit flag > XCODER_SECURE env > default ("disabled").
+ * Never throws: an unparseable env value falls back to the default and is
+ * reported as `source: "default"` — a bad env var must not brick the CLI.
+ */
+const TRUTHY = new Set(["on", "true", "1", "yes", "enabled", "enforce", "enforced"]);
+const FALSY = new Set(["off", "false", "0", "no", "disabled", "disable"]);
+/**
+ * Parses a raw env value into a mode, or `undefined` when it is absent or
+ * unrecognised. Unrecognised values deliberately do NOT throw.
+ */
+function parseEnv(env) {
+    if (typeof env !== "string")
+        return undefined;
+    const normalized = env.trim().toLowerCase();
+    if (normalized.length === 0)
+        return undefined;
+    if (TRUTHY.has(normalized))
+        return "enforced";
+    if (FALSY.has(normalized))
+        return "disabled";
+    return undefined;
+}
+function describe(mode, source) {
+    const state = mode === "enforced" ? "on" : "off";
+    return `secure enforcement: ${state} (${source})`;
+}
+export function resolveSecureMode(input) {
+    const safe = input ?? {};
+    // 1. Explicit flag always wins, in both directions.
+    if (typeof safe.secureFlag === "boolean") {
+        const mode = safe.secureFlag ? "enforced" : "disabled";
+        return { mode, source: "flag", enabled: mode === "enforced", description: describe(mode, "flag") };
+    }
+    // 2. Environment variable, when set to a recognised value.
+    const fromEnv = parseEnv(safe.env);
+    if (fromEnv !== undefined) {
+        return {
+            mode: fromEnv,
+            source: "env",
+            enabled: fromEnv === "enforced",
+            description: describe(fromEnv, "env"),
+        };
+    }
+    // 3. Default — also the landing spot for unparseable env values.
+    return {
+        mode: "disabled",
+        source: "default",
+        enabled: false,
+        description: describe("disabled", "default"),
+    };
+}
+/** Default mode constant, exported so consumers never re-declare the default. */
+export const DEFAULT_SECURE_MODE = "disabled";
+/** Env var name consumed by every CLI entry point. */
+export const SECURE_MODE_ENV_VAR = "XCODER_SECURE";

package/dist/config/user-config.d.ts

@@ -0,0 +1,39 @@
+export type UserProvider = "deepseek" | "anthropic" | "openai-compatible";
+export interface UserConfig {
+    provider?: UserProvider;
+    key?: string;
+    model?: string;
+    base_url?: string;
+    env?: Record<string, string>;
+}
+export declare const PROVIDER_KEY_ENV: Record<UserProvider, string>;
+export declare function userConfigPath(): string;
+export declare function maskSecret(value: string): string;
+/** Clears the memoised config — for tests and long-lived processes that re-read config. */
+export declare function resetUserConfigCache(): void;
+/** Read config.json. Missing file → {}. Corrupt file → throws (never silently overwritten). */
+export declare function readUserConfig(): UserConfig;
+export declare function getActiveUserConfig(): UserConfig;
+/** Push config.json into process.env (without overriding variables exported in the shell). */
+export declare function applyUserConfig(): UserConfig;
+export interface ParsedConfigArg {
+    /** Top-level fields to set ("" = remove). */
+    fields: Partial<Record<"provider" | "key" | "model" | "base_url", string>>;
+    /** Env vars to set ("" = remove). */
+    env: Record<string, string>;
+    errors: string[];
+}
+export declare function parseConfigArg(arg: string): ParsedConfigArg;
+/** Merge parsed updates into config.json (atomic write, owner-only permissions). */
+export declare function saveUserConfig(parsed: ParsedConfigArg): UserConfig;
+/** Human-readable view with secrets masked. */
+export declare function formatUserConfig(cfg: UserConfig): string[];
+/**
+ * Pull `--config <value>` / `--config=<value>` out of argv so it works anywhere
+ * on the command line. Returns the remaining argv.
+ */
+export declare function extractConfigArg(argv: string[]): {
+    value?: string;
+    argv: string[];
+    error?: string;
+};

package/dist/config/user-config.js

@@ -0,0 +1,202 @@
+// xcoder:version 1 | xcoder:task task-c4a64f | xcoder:updated 2026-10-17T03:03:22.008Z | xcoder:subtask test-st-3a3927
+// User-level runtime config: <home>/.xcoder/config.json
+//
+//   xcoder --config "provider=deepseek,key=sk-…,model=deepseek-chat"
+//
+// Holds the LLM provider/key/model/base_url plus any extra environment
+// variables (the old `.env` settings). Precedence at startup:
+//   real shell environment  >  ~/.xcoder/config.json  >  .env files
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** Variables that were really exported in the shell — config.json never overrides these. */
+const shellKeys = new Set(Object.keys(process.env));
+export const PROVIDER_KEY_ENV = {
+    deepseek: "DEEPSEEK_API_KEY",
+    anthropic: "ANTHROPIC_API_KEY",
+    "openai-compatible": "OPENAI_API_KEY",
+};
+const PROVIDER_ALIASES = {
+    deepseek: "deepseek",
+    anthropic: "anthropic",
+    claude: "anthropic",
+    openai: "openai-compatible",
+    "openai-compatible": "openai-compatible",
+};
+/** Env names that could redirect execution or traffic — never settable from config. */
+const BLOCKED_ENV = /^(PATH|PATHEXT|NODE_OPTIONS|NODE_PATH|NODE_EXTRA_CA_CERTS|LD_.*|DYLD_.*|HOME|USERPROFILE|SHELL|COMSPEC|PYTHONPATH|BUN_.*|NPM_CONFIG_.*|(HTTPS?|ALL|NO)_PROXY)$/i;
+const SECRET_NAME = /(KEY|TOKEN|SECRET|PASSWORD)/i;
+export function userConfigPath() {
+    return process.env.XCODER_CONFIG_FILE ?? path.join(os.homedir(), ".xcoder", "config.json");
+}
+export function maskSecret(value) {
+    return value.length > 8 ? `****${value.slice(-4)}` : "****";
+}
+let active = null;
+/** Clears the memoised config — for tests and long-lived processes that re-read config. */
+export function resetUserConfigCache() {
+    active = null;
+}
+/** Read config.json. Missing file → {}. Corrupt file → throws (never silently overwritten). */
+export function readUserConfig() {
+    const file = userConfigPath();
+    if (!fs.existsSync(file))
+        return {};
+    const raw = fs.readFileSync(file, "utf8");
+    if (!raw.trim())
+        return {};
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error(`${file} must contain a JSON object`);
+    return parsed;
+}
+export function getActiveUserConfig() {
+    if (active)
+        return active;
+    try {
+        active = readUserConfig();
+    }
+    catch (err) {
+        process.stderr.write(`[xcoder] ignoring unreadable ${userConfigPath()}: ${err.message}\n`);
+        active = {};
+    }
+    return active;
+}
+/** Push config.json into process.env (without overriding variables exported in the shell). */
+export function applyUserConfig() {
+    active = null;
+    const cfg = getActiveUserConfig();
+    const set = (name, value) => {
+        if (value === undefined || shellKeys.has(name))
+            return;
+        process.env[name] = value;
+    };
+    for (const [name, value] of Object.entries(cfg.env ?? {})) {
+        if (!BLOCKED_ENV.test(name))
+            set(name, String(value));
+    }
+    if (cfg.key) {
+        set("XCODER_API_KEY", cfg.key);
+        set(PROVIDER_KEY_ENV[cfg.provider ?? "deepseek"], cfg.key);
+    }
+    if (cfg.model)
+        set("XCODER_MODEL", cfg.model);
+    return cfg;
+}
+export function parseConfigArg(arg) {
+    const out = { fields: {}, env: {}, errors: [] };
+    const tokens = arg.split(/,(?=\s*[A-Za-z_][A-Za-z0-9_.-]*\s*=)/);
+    for (const token of tokens) {
+        const eq = token.indexOf("=");
+        if (eq < 1) {
+            if (token.trim())
+                out.errors.push(`expected name=value, got "${token.trim()}"`);
+            continue;
+        }
+        const name = token.slice(0, eq).trim();
+        const value = token.slice(eq + 1).trim().replace(/^(["'])(.*)\1$/, "$2");
+        const lower = name.toLowerCase();
+        if (lower === "provider") {
+            if (value === "")
+                out.fields.provider = "";
+            else if (PROVIDER_ALIASES[value.toLowerCase()])
+                out.fields.provider = PROVIDER_ALIASES[value.toLowerCase()];
+            else
+                out.errors.push(`unknown provider "${value}" (use deepseek, anthropic or openai-compatible)`);
+        }
+        else if (lower === "key" || lower === "api_key" || lower === "apikey") {
+            out.fields.key = value;
+        }
+        else if (lower === "model") {
+            out.fields.model = value;
+        }
+        else if (lower === "base_url" || lower === "baseurl" || lower === "url") {
+            if (value !== "" && !/^https?:\/\/[^\s]+$/i.test(value))
+                out.errors.push(`base_url must start with http:// or https:// (got "${value}")`);
+            else
+                out.fields.base_url = value;
+        }
+        else {
+            const envName = lower.startsWith("env.") ? name.slice(4) : name;
+            if (!/^[A-Z][A-Z0-9_]*$/.test(envName))
+                out.errors.push(`unknown setting "${name}" (use provider, key, model, base_url, or an UPPER_CASE env var)`);
+            else if (BLOCKED_ENV.test(envName))
+                out.errors.push(`${envName} cannot be set from config (security)`);
+            else
+                out.env[envName] = value;
+        }
+    }
+    return out;
+}
+/** Merge parsed updates into config.json (atomic write, owner-only permissions). */
+export function saveUserConfig(parsed) {
+    const current = readUserConfig(); // throws on corrupt JSON instead of clobbering it
+    const next = { ...current, env: { ...(current.env ?? {}) } };
+    for (const [k, v] of Object.entries(parsed.fields)) {
+        if (v === "")
+            delete next[k];
+        else
+            next[k] = v;
+    }
+    for (const [k, v] of Object.entries(parsed.env)) {
+        if (v === "")
+            delete next.env[k];
+        else
+            next.env[k] = v;
+    }
+    if (Object.keys(next.env ?? {}).length === 0)
+        delete next.env;
+    const file = userConfigPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        // best-effort (e.g. Windows)
+    }
+    active = null;
+    return next;
+}
+/** Human-readable view with secrets masked. */
+export function formatUserConfig(cfg) {
+    const lines = [];
+    if (cfg.provider)
+        lines.push(`provider = ${cfg.provider}`);
+    if (cfg.key)
+        lines.push(`key      = ${maskSecret(cfg.key)}`);
+    if (cfg.model)
+        lines.push(`model    = ${cfg.model}`);
+    if (cfg.base_url)
+        lines.push(`base_url = ${cfg.base_url}`);
+    for (const [k, v] of Object.entries(cfg.env ?? {}))
+        lines.push(`${k} = ${SECRET_NAME.test(k) ? maskSecret(String(v)) : v}`);
+    return lines.length ? lines : ["(empty)"];
+}
+/**
+ * Pull `--config <value>` / `--config=<value>` out of argv so it works anywhere
+ * on the command line. Returns the remaining argv.
+ */
+export function extractConfigArg(argv) {
+    const rest = argv.slice(0, 2);
+    let value;
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--config") {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--"))
+                return { argv, error: '--config needs a value, e.g. --config "provider=deepseek,key=sk-…" (or --config show)' };
+            value = next;
+            i++;
+        }
+        else if (a.startsWith("--config=")) {
+            value = a.slice("--config=".length);
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { value, argv: rest };
+}

package/dist/engine/reasoning-engine.d.ts

@@ -0,0 +1,21 @@
+import type { DecisionContext, EngineName, OrchestratorAction, ReasoningEngine } from "../types.js";
+/**
+ * The Master Orchestrator's own decision-making engine — distinct from the
+ * per-subtask engine a Sub Agent runs (see `agents/sub-agent.ts`, which
+ * today only implements `react-v1`). This is "Orchestrator ReAct": at every
+ * DAG event, decide the next orchestration action.
+ *
+ * `react-v1` here is fully deterministic on purpose — the decision space
+ * (dispatch the next-ready frontier, retry with a hint, escalate past the
+ * healing cap) doesn't need an LLM call to get right, and keeping it
+ * deterministic means the orchestrator's own behavior is reproducible and
+ * cheap to run at swarm scale. The other three names are registered as
+ * real extension points (e.g. an LLM-driven `plan-execute-v1` that
+ * proactively reshapes the DAG) but are not implemented yet — calling them
+ * throws a clear "not implemented" rather than silently falling back.
+ */
+export declare class ReactOrchestratorEngine implements ReasoningEngine {
+    name: EngineName;
+    decide(context: DecisionContext): Promise<OrchestratorAction>;
+}
+export declare function getOrchestratorEngine(name: EngineName): ReasoningEngine;

package/dist/engine/reasoning-engine.js

@@ -0,0 +1,59 @@
+/**
+ * The Master Orchestrator's own decision-making engine — distinct from the
+ * per-subtask engine a Sub Agent runs (see `agents/sub-agent.ts`, which
+ * today only implements `react-v1`). This is "Orchestrator ReAct": at every
+ * DAG event, decide the next orchestration action.
+ *
+ * `react-v1` here is fully deterministic on purpose — the decision space
+ * (dispatch the next-ready frontier, retry with a hint, escalate past the
+ * healing cap) doesn't need an LLM call to get right, and keeping it
+ * deterministic means the orchestrator's own behavior is reproducible and
+ * cheap to run at swarm scale. The other three names are registered as
+ * real extension points (e.g. an LLM-driven `plan-execute-v1` that
+ * proactively reshapes the DAG) but are not implemented yet — calling them
+ * throws a clear "not implemented" rather than silently falling back.
+ */
+export class ReactOrchestratorEngine {
+    name = "react-v1";
+    async decide(context) {
+        const { triggeringEvent, subtask } = context;
+        if (triggeringEvent === "subtask_done") {
+            const ready = context.dag.filter((n) => n.status === "ready");
+            return ready.length
+                ? { type: "dispatch", subtaskIds: ready.map((n) => n.id) }
+                : { type: "dispatch", subtaskIds: [] };
+        }
+        if (triggeringEvent === "subtask_failed" && subtask) {
+            if (subtask.healing.attempts >= subtask.healing.maxAttempts) {
+                return {
+                    type: "escalate",
+                    subtaskId: subtask.id,
+                    reason: `healing exhausted after ${subtask.healing.attempts}/${subtask.healing.maxAttempts} attempts`,
+                };
+            }
+            const lastReason = subtask.healing.log.at(-1) ?? "validation failed";
+            return {
+                type: "retry",
+                subtaskId: subtask.id,
+                hint: `Previous attempt failed validation: ${lastReason}. Address this specifically before re-checking your own work.`,
+            };
+        }
+        if (triggeringEvent === "budget_warning") {
+            return { type: "halt", reason: "budget ceiling reached" };
+        }
+        if (triggeringEvent === "stuck_timeout" && subtask) {
+            return {
+                type: "escalate",
+                subtaskId: subtask.id,
+                reason: "subtask exceeded its expected runtime with no progress",
+            };
+        }
+        return { type: "halt", reason: `unhandled triggering event: ${triggeringEvent}` };
+    }
+}
+export function getOrchestratorEngine(name) {
+    if (name === "react-v1")
+        return new ReactOrchestratorEngine();
+    throw new Error(`orchestrator engine "${name}" is registered as an extension point but not implemented yet. ` +
+        `Use "react-v1".`);
+}

package/dist/events/bus.d.ts

@@ -0,0 +1,22 @@
+import { EventEmitter } from "node:events";
+export type XcoderEventType = "task:intro" | "task:outro" | "task:dag" | "orchestrator:note" | "footer:update" | "agent:thinking-start" | "agent:thought" | "agent:action" | "agent:observation" | "agent:tokens" | "agent:final" | "agent:crash" | "agent:protocol-error" | "agent:score" | "agent:duplicate" | "agent:exhausted" | "debate:intro" | "debate:turn-start" | "debate:agent-thought" | "debate:agent-action" | "debate:agent-observation" | "debate:agent-final" | "debate:agent-tokens" | "debate:outro";
+export interface XcoderEvent {
+    type: XcoderEventType;
+    taskId: string;
+    subtaskId?: string;
+    ts: string;
+    data?: unknown;
+}
+/**
+ * A single EventEmitter every RAO-producing part of the system emits to —
+ * `agents/sub-agent.ts`, `orchestrator/swarm.ts`, `orchestrator/
+ * sdlc-orchestrator.ts`. Two things consume it today: `util/terminal.ts`
+ * (indirectly — those modules still call `term.*` directly for the CLI's
+ * colored output) and `xcoder observe --json`, which prints every event as
+ * a JSON line. Adding another
+ * consumer (a plain JSON event log, a metrics exporter) means subscribing
+ * here, not threading a new parameter through every function that produces
+ * an event.
+ */
+export declare const xcoderEvents: EventEmitter<[never]>;
+export declare function emitXcoderEvent(ev: Omit<XcoderEvent, "ts">): void;