maqcli 0.2.0 → 0.5.0

package/dist/core/launcher.js

@@ -0,0 +1,381 @@
+/**
+ * Guided launcher — the zero-typing entry point. Running `maq` with no
+ * arguments (or `maq start`) lands here instead of a wall of command help.
+ *
+ * Flow (all keypress-driven, no command memorization):
+ *   Megalodon splash
+ *   → Path A: Connect to Mobile   (start daemon, show pairing + 9-digit key)
+ *   → Path B: AI Mode
+ *        (1) Your installed CLIs      → register as $0 workers/master
+ *        (2) Single model API          → allowed, flagged "limited"
+ *        (3) Multi-provider APIs        → 2026 catalog, list-only ($0)
+ *      → auto-pick the EFFICIENT (mid) model → keep auto or set Headroom model
+ *      → Permissions: Full | Moderate (request-box)
+ *      → build Headroom knowledge, generate 9-digit key, open the browser UI
+ *
+ * Pure helpers (auth key, browser command, onboarding apply, splash) are
+ * exported for testing; the interactive shell is a thin wrapper over them.
+ */
+import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
+import { randomInt } from "node:crypto";
+import { loadConfig, saveConfig } from "./config-store.js";
+import { detectAgents } from "./registry.js";
+import { PROVIDER_CATALOG, detectAvailableProviders, getCatalogProvider, providerGoodFor, } from "./providers-catalog.js";
+import { classifyModel, pickEfficient } from "./capabilities.js";
+import { buildKnowledge, saveKnowledge, roleForModel } from "./onboarding.js";
+import { probeCliCapability } from "./cli-probe.js";
+/* --------------------------- pure, testable ---------------------------- */
+/** A user-facing 9-digit pairing/auth key (100000000–999999999). */
+export function generateAuthKey() {
+    return String(randomInt(100_000_000, 1_000_000_000));
+}
+/** OS-specific command to open a URL in the default browser. */
+export function browserOpenCommand(url, platform = process.platform) {
+    if (platform === "win32")
+        return { cmd: "cmd", args: ["/c", "start", "", url] };
+    if (platform === "darwin")
+        return { cmd: "open", args: [url] };
+    return { cmd: "xdg-open", args: [url] };
+}
+/** Best-effort: open a URL in the default browser (never throws). */
+export function openBrowser(url) {
+    try {
+        const { cmd, args } = browserOpenCommand(url);
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* ignore */
+    }
+}
+const RED = "\x1b[38;5;196m";
+const WHITE = "\x1b[97m";
+const DIM = "\x1b[2m";
+const RST = "\x1b[0m";
+/** The Megalodon splash. `color=false` yields a plain-text version. */
+export function megalodonSplash(color = true) {
+    const r = color ? RED : "";
+    const w = color ? WHITE : "";
+    const d = color ? DIM : "";
+    const x = color ? RST : "";
+    return [
+        "",
+        `${w}                     ,`,
+        `${w}                   ,'|        ${r}▄▄${x}`,
+        `${w}                 ,'  |      ${r}▄█████▄${x}`,
+        `${w}      ${d}~~~~~${x}${w}    ,'    |   ${r}▄█████████▄${x}   ${w}M A Q${x}`,
+        `${w}   ${d}~~${x}${w}        ,'______|${r}████████████▀${x}`,
+        `${r}  ≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈████████▀${x}      ${d}megalodon${x}`,
+        `${w}            \`.      |${r}██████▀${x}`,
+        `${w}              \`.    |${r}████▀${x}`,
+        `${w}                \`.  |${r}▀▀${x}`,
+        `${w}                  \`.|${x}`,
+        "",
+        `${d}   the apex orchestrator — it hunts, it doesn't type.${x}`,
+        "",
+    ].join("\n");
+}
+/**
+ * Frames of the megalodon swimming in from the left (red fin, white body). The
+ * last frame is the settled splash. Used only on a TTY; tests use the pure
+ * megalodonSplash above.
+ */
+export function megalodonFrames(color = true) {
+    const r = color ? RED : "";
+    const w = color ? WHITE : "";
+    const x = color ? RST : "";
+    const shark = (pad) => {
+        const p = " ".repeat(pad);
+        return [
+            "",
+            "",
+            `${p}${w}          ,${x}`,
+            `${p}${w}        ,'|   ${r}▄▄${x}`,
+            `${p}${r}≈≈≈≈≈≈≈${w},'__|${r}████████▀${x}`,
+            `${p}${w}        \`.|${r}████▀${x}`,
+            `${p}${w}          \`.${r}▀${x}`,
+            "",
+            "",
+        ].join("\n");
+    };
+    return [shark(0), shark(6), shark(14), shark(24), megalodonSplash(color)];
+}
+async function animateSplash(color) {
+    if (!process.stdout.isTTY) {
+        line(megalodonSplash(color));
+        return;
+    }
+    const frames = megalodonFrames(color);
+    for (let i = 0; i < frames.length; i++) {
+        process.stdout.write("\x1b[2J\x1b[H"); // clear + home
+        process.stdout.write(frames[i]);
+        if (i < frames.length - 1)
+            await new Promise((res) => setTimeout(res, 110));
+    }
+    process.stdout.write("\n");
+}
+/**
+ * Persist an onboarding outcome: pick the efficient model if none was chosen,
+ * write config (provider/model/tiers/permission/onboarded) and the Headroom
+ * knowledge doc, and mint a 9-digit key. Pure w.r.t. I/O beyond the config +
+ * knowledge files, so it is directly testable.
+ */
+export function applyOnboarding(choices) {
+    const cfg = loadConfig();
+    // Resolve the Headroom (efficient) model.
+    let headroom = choices.headroom ?? null;
+    if (!headroom) {
+        const picked = pickEfficient(choices.models);
+        headroom = picked ? { provider: picked.model.maqProvider, model: picked.model.id } : null;
+    }
+    if (headroom) {
+        cfg.provider = headroom.provider;
+        cfg.masterModel = headroom.model;
+        cfg.cheapModel = headroom.model;
+        cfg.headroomModel = choices.headroomAuto ? "" : headroom.model;
+        // Reserve the strongest available model for the hard "strong" tier.
+        const heavy = choices.models.filter((m) => m.tier === "heavy")[0];
+        const mid = choices.models.filter((m) => m.tier === "mid")[0];
+        cfg.strongModel = (heavy ?? mid)?.id ?? headroom.model;
+    }
+    cfg.permissionMode = choices.permissionMode;
+    cfg.onboarded = true;
+    saveConfig(cfg);
+    // Build + persist the Headroom knowledge doc.
+    const providers = choices.models.map((m) => {
+        const role = headroom && m.id === headroom.model
+            ? "headroom-master"
+            : m.tier === "light"
+                ? "fan-out"
+                : m.tier === "heavy"
+                    ? "reviewer"
+                    : "worker";
+        return roleForModel(m, role, choices.source, m.goodFor ?? []);
+    });
+    const knowledge = buildKnowledge({
+        providers,
+        permissionMode: choices.permissionMode,
+        headroomModel: headroom ? { ...headroom, auto: choices.headroomAuto } : null,
+    });
+    const knowledgePath = saveKnowledge(knowledge);
+    return { config: cfg, knowledgePath, headroom, authKey: generateAuthKey() };
+}
+/* ----------------------------- interactive ----------------------------- */
+function ask(rl, q) {
+    return new Promise((resolve) => rl.question(q, (a) => resolve(a.trim())));
+}
+const useColor = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+function line(s = "") {
+    process.stdout.write(s + "\n");
+}
+/**
+ * Run the guided launcher. Returns 0 on success. In a non-interactive context
+ * (piped stdin), it prints guidance and returns without blocking.
+ */
+export async function runLauncher(cwd) {
+    await animateSplash(useColor());
+    if (!process.stdin.isTTY) {
+        line("maq: guided setup needs an interactive terminal.");
+        line("  • run `maq start` in a real terminal, or");
+        line("  • use commands directly, e.g. `maq run \"<task>\" --target none`  (see `maq --help`).");
+        return 0;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await drive(rl, cwd);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function drive(rl, cwd) {
+    line("How do you want to start?");
+    line("  [1] Connect to Mobile   — pair your phone as a control surface");
+    line("  [2] AI Mode             — set up the intelligence layer");
+    line("  [0] Exit to command help");
+    const path = (await ask(rl, "\n> ")) || "2";
+    if (path === "0")
+        return 1;
+    if (path === "1")
+        return await connectMobile(rl);
+    return await aiMode(rl, cwd);
+}
+async function aiMode(rl, cwd) {
+    line("");
+    line("AI Mode — choose your intelligence source:");
+    line("  [1] Your installed AI CLIs   — $0, reuses your existing subscriptions");
+    line("  [2] A single model API        — one provider/model (limited: no fan-out)");
+    line("  [3] Multi-provider APIs        — the 2026 catalog, pay only when used");
+    const choice = (await ask(rl, "\n> ")) || "1";
+    let models = [];
+    let source = "api";
+    if (choice === "1") {
+        ({ models, source } = await registerClis(rl));
+    }
+    else if (choice === "2") {
+        ({ models, source } = await registerSingleApi(rl));
+    }
+    else {
+        ({ models, source } = await registerMultiApi(rl));
+    }
+    if (models.length === 0) {
+        line("\nNothing registered. Falling back to the offline heuristic master ($0).");
+        models = [{ id: "heuristic-local", provider: "heuristic", maqProvider: "heuristic", tier: "mid" }];
+        source = "local";
+    }
+    // Efficient-mid auto pick, then let the user confirm or override.
+    const picked = pickEfficient(models);
+    let headroom = null;
+    let headroomAuto = true;
+    if (picked) {
+        line(`\nAuto-picked the efficient model: ${picked.model.id}  (${picked.note})`);
+        const keep = (await ask(rl, "Keep this as the Headroom model? [Y/n or number to choose] ")).toLowerCase();
+        if (keep === "" || keep === "y" || keep === "yes") {
+            headroom = { provider: picked.model.maqProvider, model: picked.model.id };
+        }
+        else {
+            models.forEach((m, i) => line(`  [${i + 1}] ${m.id}  (${m.tier})`));
+            const pick = Number(await ask(rl, "Choose a model number: "));
+            const chosen = models[pick - 1] ?? picked.model;
+            headroom = { provider: chosen.maqProvider, model: chosen.id };
+            headroomAuto = false;
+        }
+    }
+    // Permissions.
+    line("");
+    line("Permissions:");
+    line("  [1] Full     — the master (and its workers) may act without stopping");
+    line("  [2] Moderate — major/destructive actions queue to a request-box for approval");
+    const perm = (await ask(rl, "\n> ")) || "2";
+    const permissionMode = perm === "1" ? "full" : "moderate";
+    const result = applyOnboarding({ models, headroom, headroomAuto, permissionMode, source });
+    line("");
+    line("─────────────────────────────────────────────");
+    line(`  Headroom model : ${result.headroom?.model ?? "heuristic-local"} (${headroomAuto ? "auto" : "manual"})`);
+    line(`  Permissions    : ${permissionMode}`);
+    line(`  Knowledge doc  : ${result.knowledgePath}`);
+    line(`  Auth key       : ${result.authKey}`);
+    line("─────────────────────────────────────────────");
+    const open = (await ask(rl, "\nLaunch the browser UI now? [Y/n] ")).toLowerCase();
+    if (open === "" || open === "y" || open === "yes") {
+        return await launchUi(result.authKey);
+    }
+    line("\nReady. Start anytime with:  maq serve   (then open the printed URL)");
+    return 0;
+}
+async function registerClis(rl) {
+    const agents = detectAgents();
+    const ready = agents.filter((a) => a.installed && a.authenticated);
+    if (ready.length === 0) {
+        line("\nNo authenticated AI CLI found. Install/log in to one (claude, codex, gemini, …),");
+        line("or pick option 3 (API providers). Continuing with none for now.");
+        return { models: [], source: "cli" };
+    }
+    line("\nFound these authenticated CLIs. Asking each one to self-report its capabilities (uses your own subscription, $0)…");
+    const models = [];
+    for (const a of ready) {
+        const cap = await probeCliCapability(a.name, { timeoutMs: 45000 });
+        models.push({
+            id: cap.maqProvider,
+            provider: a.name,
+            maqProvider: cap.maqProvider,
+            tier: cap.tier,
+            vision: cap.vision,
+            goodFor: cap.goodFor,
+        });
+        const how = cap.probed ? `self-reported ${cap.tier}` : `${cap.tier} (probe unavailable)`;
+        const gf = cap.goodFor.length ? `  good for: ${cap.goodFor.join(", ")}` : "";
+        line(`  • ${a.name.padEnd(12)} → ${cap.maqProvider}   [${how}]${gf}`);
+    }
+    return { models, source: "cli" };
+}
+async function registerSingleApi(rl) {
+    const available = detectAvailableProviders().filter((p) => p.active && !p.provider.local);
+    if (available.length === 0) {
+        line("\nNo API keys detected in your environment. Set one (e.g. OPENAI_API_KEY) and re-run,");
+        line("or pick option 1 (your CLIs). Continuing with none for now.");
+        return { models: [], source: "api" };
+    }
+    line("\nActive API providers:");
+    available.forEach((p, i) => line(`  [${i + 1}] ${p.provider.label}`));
+    const pick = Number(await ask(rl, "Choose a provider: ")) || 1;
+    const chosen = (available[pick - 1] ?? available[0]).provider;
+    chosen.models.forEach((m, i) => line(`  [${i + 1}] ${m.id}  (${m.tier})`));
+    const mpick = Number(await ask(rl, "Choose a model: ")) || 1;
+    const model = chosen.models[mpick - 1] ?? chosen.models[0];
+    line("\nNote: a single model can't fan out — parallel/safe modes are disabled until you add more.");
+    return {
+        models: [{ id: model.id, provider: chosen.id, maqProvider: chosen.maqProvider, tier: model.tier, goodFor: providerGoodFor(chosen.id) }],
+        source: "api",
+    };
+}
+async function registerMultiApi(rl) {
+    const detected = detectAvailableProviders();
+    line("\n2026 provider catalog (● active, ○ actionable — listing is free):");
+    for (const d of detected) {
+        const mark = d.active ? "●" : "○";
+        line(`  ${mark} ${d.provider.label.padEnd(38)} ${d.reason}`);
+        line(`     ${d.provider.setup}`);
+    }
+    const active = detected.filter((d) => d.active);
+    if (active.length === 0) {
+        line("\nNone active yet. Set an API key from the list above, then re-run `maq start`.");
+        return { models: [], source: "api" };
+    }
+    // Register every model of every active provider (available, not consuming tokens).
+    const models = active.flatMap((d) => d.provider.models.map((m) => ({
+        id: m.id,
+        provider: d.provider.id,
+        maqProvider: d.provider.maqProvider,
+        tier: m.tier ?? classifyModel(m.id),
+        vision: m.vision,
+        longContext: m.longContext,
+        goodFor: providerGoodFor(d.provider.id),
+    })));
+    line(`\nRegistered ${models.length} models across ${active.length} active provider(s).`);
+    return { models, source: "api" };
+}
+async function connectMobile(rl) {
+    const authKey = generateAuthKey();
+    line("\nConnect to Mobile");
+    line("  1. On this machine, MAQ will run its daemon (loopback + a tunnel/tailnet for remote).");
+    line("  2. In the MAQ phone app, pair using the details below.");
+    line("");
+    line(`  Auth key (pairing PIN): ${authKey}`);
+    line("");
+    line("Starting the daemon now with:  maq serve");
+    line("  (the app pairs with host/port + the token the daemon prints)");
+    await ask(rl, "\nPress Enter to continue…");
+    return 0;
+}
+async function launchUi(authKey) {
+    // Reuse the daemon; open its landing page. Import lazily to avoid a cycle.
+    const { createDaemon } = await import("../server/daemon.js");
+    const daemon = createDaemon({ token: authKey, version: "0.5.0" });
+    try {
+        const { host, port } = await daemon.listen();
+        const url = `http://${host}:${port}/`;
+        line(`\nmaq daemon listening on ${url}`);
+        line(`auth key/token: ${authKey}`);
+        openBrowser(url);
+        line("Opened your browser. Press Ctrl-C here to stop the daemon.");
+        await new Promise((resolve) => {
+            const stop = () => {
+                line("\nshutting down…");
+                daemon.close().then(resolve);
+            };
+            process.on("SIGINT", stop);
+            process.on("SIGTERM", stop);
+        });
+        return 0;
+    }
+    catch (e) {
+        line(`could not start daemon: ${e.message}`);
+        return 1;
+    }
+}
+/** For discoverability from `maq --help` / knowledge. */
+export const LAUNCHER_PROVIDERS = PROVIDER_CATALOG.map((p) => p.id);
+export { getCatalogProvider };

package/dist/core/onboarding.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Onboarding knowledge — the JSON "brain dump" the guided launcher hands to
+ * Headroom so the master understands, in one place: what MAQ can do (feature
+ * catalog), what role each configured provider/model plays, the permission
+ * posture, and the available execution strategies.
+ *
+ * This is NOT injected wholesale into every prompt (that would waste tokens).
+ * It is stored at ~/.maqcli/headroom-knowledge.json and surfaced *by query* —
+ * the master pulls only the relevant slice for the user's current goal. Keeping
+ * it as structured JSON is what makes selective retrieval cheap.
+ */
+import type { TieredModel } from "./capabilities.js";
+export interface ProviderRole {
+    provider: string;
+    model: string;
+    tier: string;
+    /** What this model is registered to do in the pipeline. */
+    role: "headroom-master" | "worker" | "fan-out" | "reviewer";
+    goodFor: string[];
+    source: "cli" | "api" | "local";
+}
+export interface HeadroomKnowledge {
+    version: number;
+    generatedAt: string;
+    /** The master's own management/dev skills, surfaced by query not by default. */
+    masterSkills: string[];
+    /** MAQ feature catalog (name + what it does) for capability-aware planning. */
+    features: Array<{
+        name: string;
+        category: string;
+        summary: string;
+    }>;
+    /** Every registered provider/model and the role it plays. */
+    providers: ProviderRole[];
+    permissionMode: "full" | "moderate";
+    executionModes: Array<{
+        id: string;
+        when: string;
+    }>;
+    headroomModel: {
+        provider: string;
+        model: string;
+        auto: boolean;
+    } | null;
+}
+/** Management + latest-development skills the master can draw on, by query. */
+export declare const MASTER_SKILLS: string[];
+export declare const EXECUTION_MODES: {
+    id: string;
+    when: string;
+}[];
+export interface BuildKnowledgeInput {
+    providers: ProviderRole[];
+    permissionMode: "full" | "moderate";
+    headroomModel?: {
+        provider: string;
+        model: string;
+        auto: boolean;
+    } | null;
+}
+/** Build the knowledge document from the current configuration. */
+export declare function buildKnowledge(input: BuildKnowledgeInput): HeadroomKnowledge;
+/** Map a discovered tiered model into a provider-role entry. */
+export declare function roleForModel(m: TieredModel, role: ProviderRole["role"], source: ProviderRole["source"], goodFor?: string[]): ProviderRole;
+export declare function knowledgePath(): string;
+export declare function saveKnowledge(k: HeadroomKnowledge): string;
+export declare function loadKnowledge(): HeadroomKnowledge | null;
+/**
+ * Selective retrieval: return only the knowledge slices relevant to a query,
+ * so the master pays for context proportional to the task, not the whole doc.
+ */
+export declare function queryKnowledge(k: HeadroomKnowledge, query: string): {
+    features: HeadroomKnowledge["features"];
+    skills: string[];
+    providers: ProviderRole[];
+};

package/dist/core/onboarding.js

@@ -0,0 +1,88 @@
+/**
+ * Onboarding knowledge — the JSON "brain dump" the guided launcher hands to
+ * Headroom so the master understands, in one place: what MAQ can do (feature
+ * catalog), what role each configured provider/model plays, the permission
+ * posture, and the available execution strategies.
+ *
+ * This is NOT injected wholesale into every prompt (that would waste tokens).
+ * It is stored at ~/.maqcli/headroom-knowledge.json and surfaced *by query* —
+ * the master pulls only the relevant slice for the user's current goal. Keeping
+ * it as structured JSON is what makes selective retrieval cheap.
+ */
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { configDir } from "./config-store.js";
+import { maqCommands } from "./command-catalog.js";
+/** Management + latest-development skills the master can draw on, by query. */
+export const MASTER_SKILLS = [
+    "decompose a goal into independently-verifiable sub-tasks",
+    "route each sub-task to the cheapest model that can do it (RouteLLM-style)",
+    "compress verbose tool output before it reaches a model (Headroom compress-cache-retrieve)",
+    "run read-only Scout recon before proposing changes",
+    "gate plans behind a verifier; prefer the smallest change set",
+    "verify with the project's own tests, not self-assessment",
+    "record a lesson to AGENTS.md when verification fails (self-learning)",
+    "fan out independent work in parallel, then join results",
+    "keep worker context isolated; the master sees condensed events, not raw transcripts",
+    "ask for permission before destructive or out-of-scope actions when in moderate mode",
+];
+export const EXECUTION_MODES = [
+    { id: "parallel", when: "independent sub-tasks; assign per model, run at once, join by goal" },
+    { id: "loop", when: "one hard deliverable; iterate/refine in a loop until it passes" },
+    { id: "safe", when: "split into mini-parts on light models (no interference), merge via a loop, then parallelize" },
+];
+/** Build the knowledge document from the current configuration. */
+export function buildKnowledge(input) {
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        masterSkills: MASTER_SKILLS,
+        features: maqCommands.map((c) => ({ name: c.name, category: c.category, summary: c.summary })),
+        providers: input.providers,
+        permissionMode: input.permissionMode,
+        executionModes: EXECUTION_MODES,
+        headroomModel: input.headroomModel ?? null,
+    };
+}
+/** Map a discovered tiered model into a provider-role entry. */
+export function roleForModel(m, role, source, goodFor = []) {
+    return { provider: m.maqProvider, model: m.id, tier: m.tier, role, goodFor, source };
+}
+export function knowledgePath() {
+    return join(configDir(), "headroom-knowledge.json");
+}
+export function saveKnowledge(k) {
+    const dir = configDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const p = knowledgePath();
+    writeFileSync(p, JSON.stringify(k, null, 2), "utf8");
+    return p;
+}
+export function loadKnowledge() {
+    const p = knowledgePath();
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Selective retrieval: return only the knowledge slices relevant to a query,
+ * so the master pays for context proportional to the task, not the whole doc.
+ */
+export function queryKnowledge(k, query) {
+    const q = query.toLowerCase();
+    const words = q.split(/\W+/).filter((w) => w.length >= 3);
+    const match = (text) => words.some((w) => text.toLowerCase().includes(w));
+    const features = k.features.filter((f) => match(f.name) || match(f.summary));
+    const skills = k.masterSkills.filter((s) => match(s));
+    return {
+        features: features.length ? features : k.features.slice(0, 6),
+        skills: skills.length ? skills : k.masterSkills.slice(0, 4),
+        providers: k.providers,
+    };
+}

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Orchestrator — the three god-level execution engines that sit ABOVE the
+ * single Scout→Plan→Execute→Verify pipeline. The master (Headroom) never reads
+ * the full codebase; it decomposes a goal, dispatches work, and reasons only
+ * over the condensed sub-results — then decides the next move until the goal is
+ * met.
+ *
+ *   parallel — independent sub-tasks assigned per model, run at once; the
+ *              master joins the replies, thinks the next batch, repeats until
+ *              the goal is satisfied (or maxRounds).
+ *   loop     — one hard deliverable; run, and if it doesn't verify, refine the
+ *              instruction with the failure and retry until it passes (or
+ *              maxIterations). Best for long single tasks.
+ *   safe     — split into mini-parts on LIGHT models in isolation (no
+ *              interference), MERGE the parts via a loop, then a final parallel
+ *              validation pass.
+ *
+ * Every collaborator (decompose / runTask / evaluate / merge) is injectable, so
+ * the engines are fully unit-testable offline with deterministic fakes. The
+ * default collaborators are backed by the real provider + runPipeline.
+ */
+import type { MaqEvent } from "./types.js";
+export type ExecutionMode = "parallel" | "loop" | "safe";
+export interface SubTaskResult {
+    task: string;
+    verified: boolean;
+    status: string;
+    summary: string;
+    tier?: "cheap" | "strong";
+}
+export interface OrchestrationResult {
+    goal: string;
+    mode: ExecutionMode;
+    rounds: number;
+    subtasks: SubTaskResult[];
+    verified: boolean;
+    summary: string;
+}
+export interface EvaluateResult {
+    done: boolean;
+    reason: string;
+    followups: string[];
+}
+export interface RunTaskCtx {
+    tier?: "cheap" | "strong";
+    onEvent?: (e: MaqEvent) => void;
+    signal?: AbortSignal;
+}
+/** Injectable collaborators; defaults are provider/pipeline-backed. */
+export interface OrchestratorDeps {
+    decompose: (goal: string, ctx: {
+        round: number;
+        prior: SubTaskResult[];
+    }) => Promise<string[]>;
+    runTask: (task: string, ctx: RunTaskCtx) => Promise<SubTaskResult>;
+    evaluate: (goal: string, results: SubTaskResult[]) => Promise<EvaluateResult>;
+    merge: (goal: string, results: SubTaskResult[], ctx: RunTaskCtx) => Promise<SubTaskResult>;
+}
+export interface OrchestrationOptions {
+    cwd?: string;
+    target?: string;
+    provider?: string;
+    model?: string;
+    dryRun?: boolean;
+    maxConcurrency?: number;
+    /** parallel/safe: how many decompose→run→evaluate rounds before stopping. */
+    maxRounds?: number;
+    /** loop: how many refine→retry iterations before stopping. */
+    maxIterations?: number;
+    onEvent?: (e: MaqEvent) => void;
+    signal?: AbortSignal;
+    checkpoint?: () => Promise<void>;
+    /**
+     * Permission gate consulted before MAJOR steps (moderate mode). Resolves
+     * true to proceed, false to hold. When absent, everything proceeds.
+     */
+    requestPermission?: (action: string, detail: string, risk: "low" | "major" | "destructive") => Promise<boolean>;
+    /** Override any collaborator (tests inject deterministic ones). */
+    deps?: Partial<OrchestratorDeps>;
+}
+/**
+ * Deterministic, offline goal splitter used as a fallback when a real model
+ * can't (or shouldn't) be asked to decompose. Splits on natural connectors.
+ */
+export declare function heuristicSplit(goal: string): string[];
+/** Refine a failed task with the failure context for the next loop iteration. */
+export declare function refineTask(goal: string, last: SubTaskResult): string;
+/** Bounded-concurrency map (a tiny worker pool). Preserves input order. */
+export declare function pool<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function runOrchestration(goal: string, mode: ExecutionMode, opts?: OrchestrationOptions): Promise<OrchestrationResult>;