maqcli 0.2.0 → 0.5.0

package/dist/core/orchestrator.js

@@ -0,0 +1,228 @@
+/**
+ * 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 { makeEvent } from "./types.js";
+import { runPipeline } from "./pipeline.js";
+import { loadConfig } from "./config-store.js";
+import { getProvider } from "./model.js";
+/* --------------------------- pure helpers ------------------------------ */
+/**
+ * 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 function heuristicSplit(goal) {
+    const parts = goal
+        .split(/\s*(?:,?\s+and\s+then\s+|;|\n|\bthen\b|,\s+and\s+|\band also\b)\s*/i)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 2);
+    const uniq = [...new Set(parts)];
+    return uniq.length >= 2 ? uniq : [goal.trim()];
+}
+/** Refine a failed task with the failure context for the next loop iteration. */
+export function refineTask(goal, last) {
+    return `${goal}\n\nThe previous attempt did not pass verification (status=${last.status}: ${last.summary}). Diagnose the root cause and fix it; do not repeat the same approach.`;
+}
+/** Bounded-concurrency map (a tiny worker pool). Preserves input order. */
+export async function pool(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const n = Math.max(1, Math.min(limit, items.length || 1));
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: n }, () => worker()));
+    return results;
+}
+/* ------------------------- default collaborators ----------------------- */
+function makeDefaultDeps(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const cfg = loadConfig();
+    const providerName = opts.provider ?? cfg.provider;
+    const runTask = async (task, ctx) => {
+        const model = opts.model ?? (ctx.tier === "strong" ? cfg.strongModel : cfg.cheapModel);
+        const res = await runPipeline(task, {
+            cwd,
+            target: opts.target,
+            provider: providerName,
+            model,
+            dryRun: opts.dryRun,
+            onEvent: ctx.onEvent,
+            signal: ctx.signal,
+        });
+        return {
+            task,
+            verified: res.verify.verified,
+            status: res.execute.status,
+            summary: res.plan?.winner.summary ?? res.verify.details ?? task,
+            tier: ctx.tier,
+        };
+    };
+    const decompose = async (goal, ctx) => {
+        // Follow-up rounds re-run only the unfinished work.
+        if (ctx.round > 1 && ctx.prior.some((p) => !p.verified)) {
+            return ctx.prior.filter((p) => !p.verified).map((p) => refineTask(goal, p));
+        }
+        // Ask the model for a JSON array of subtasks; fall back to the splitter.
+        try {
+            const provider = getProvider(providerName);
+            const resp = await provider.complete({
+                model: opts.model ?? cfg.cheapModel,
+                messages: [
+                    { role: "system", content: "Decompose the user's goal into 2-5 independent sub-tasks. Reply with ONLY a JSON array of short strings, no prose." },
+                    { role: "user", content: goal },
+                ],
+                maxTokens: 300,
+            });
+            const arr = JSON.parse(resp.text.trim().replace(/^```(json)?/i, "").replace(/```$/, "").trim());
+            if (Array.isArray(arr) && arr.length >= 2)
+                return arr.map(String).slice(0, 6);
+        }
+        catch {
+            /* fall through */
+        }
+        return heuristicSplit(goal);
+    };
+    const evaluate = async (goal, results) => {
+        const failed = results.filter((r) => !r.verified);
+        return {
+            done: failed.length === 0,
+            reason: failed.length ? `${failed.length} of ${results.length} sub-task(s) unverified` : "all sub-tasks verified against the goal",
+            followups: failed.map((r) => refineTask(goal, r)),
+        };
+    };
+    const merge = async (goal, results, ctx) => {
+        const task = `Integrate the following completed sub-results into one coherent solution for the goal "${goal}". Resolve overlaps and ensure the whole passes verification.\n` +
+            results.map((r) => `- ${r.task} → ${r.status} (${r.summary})`).join("\n");
+        return runTask(task, { ...ctx, tier: "strong" });
+    };
+    return { decompose, runTask, evaluate, merge };
+}
+/* ------------------------------- engines ------------------------------- */
+export async function runOrchestration(goal, mode, opts = {}) {
+    const deps = { ...makeDefaultDeps(opts), ...opts.deps };
+    const emit = (e) => opts.onEvent?.(e);
+    emit(makeEvent("task.started", { goal, mode, engine: "orchestrator" }));
+    let result;
+    try {
+        if (mode === "loop")
+            result = await engineLoop(goal, deps, opts, emit);
+        else if (mode === "safe")
+            result = await engineSafe(goal, deps, opts, emit);
+        else
+            result = await engineParallel(goal, deps, opts, emit);
+    }
+    catch (err) {
+        emit(makeEvent("task.error", { message: err instanceof Error ? err.message : String(err), mode }));
+        throw err;
+    }
+    emit(makeEvent("task.done", { verified: result.verified, mode, rounds: result.rounds, subtasks: result.subtasks.length, summary: result.summary }));
+    return result;
+}
+async function engineParallel(goal, deps, opts, emit) {
+    const maxRounds = Math.max(1, opts.maxRounds ?? 3);
+    const concurrency = opts.maxConcurrency ?? 4;
+    const all = []; // full history (what actually ran)
+    const completed = []; // verified results carried forward
+    let outstanding = []; // last round's failures (fed to the next decompose)
+    let round = 0;
+    let evaluated = { done: false, reason: "", followups: [] };
+    while (round < maxRounds) {
+        await opts.checkpoint?.();
+        round++;
+        const phase = `parallel-round-${round}`;
+        emit(makeEvent("phase.started", { phase, mode: "parallel" }));
+        const tasks = await deps.decompose(goal, { round, prior: outstanding });
+        emit(makeEvent("agent.event", { note: "decomposed", round, subtasks: tasks }));
+        const results = await pool(tasks, concurrency, (task) => deps.runTask(task, { tier: "cheap", onEvent: emit, signal: opts.signal }));
+        all.push(...results);
+        // A follow-up round addresses the previous round's failures, so only THIS
+        // round's failures count as outstanding — old ones are superseded.
+        completed.push(...results.filter((r) => r.verified));
+        outstanding = results.filter((r) => !r.verified);
+        evaluated = await deps.evaluate(goal, [...completed, ...outstanding]);
+        emit(makeEvent("phase.done", { phase, done: evaluated.done, reason: evaluated.reason, verifiedThisRound: results.filter((r) => r.verified).length }));
+        if (evaluated.done || outstanding.length === 0)
+            break;
+    }
+    return { goal, mode: "parallel", rounds: round, subtasks: all, verified: evaluated.done, summary: evaluated.reason };
+}
+async function engineLoop(goal, deps, opts, emit) {
+    const maxIterations = Math.max(1, opts.maxIterations ?? 4);
+    const attempts = [];
+    let task = goal;
+    let iter = 0;
+    let last = null;
+    while (iter < maxIterations) {
+        await opts.checkpoint?.();
+        iter++;
+        const phase = `loop-iteration-${iter}`;
+        emit(makeEvent("phase.started", { phase, mode: "loop" }));
+        last = await deps.runTask(task, { tier: "strong", onEvent: emit, signal: opts.signal });
+        attempts.push(last);
+        emit(makeEvent("phase.done", { phase, verified: last.verified, status: last.status }));
+        if (last.verified)
+            break;
+        task = refineTask(goal, last);
+        emit(makeEvent("agent.event", { note: "refining after failed verification", iteration: iter }));
+    }
+    return {
+        goal,
+        mode: "loop",
+        rounds: iter,
+        subtasks: attempts,
+        verified: last?.verified ?? false,
+        summary: last?.verified ? `verified after ${iter} iteration(s)` : `not verified after ${iter} iteration(s)`,
+    };
+}
+async function engineSafe(goal, deps, opts, emit) {
+    const concurrency = opts.maxConcurrency ?? 4;
+    // 1. Split into mini-parts and run them ISOLATED on light models.
+    await opts.checkpoint?.();
+    emit(makeEvent("phase.started", { phase: "safe-split", mode: "safe" }));
+    const parts = await deps.decompose(goal, { round: 1, prior: [] });
+    emit(makeEvent("agent.event", { note: "split into isolated mini-parts", parts }));
+    const partResults = await pool(parts, concurrency, (task) => deps.runTask(task, { tier: "cheap", onEvent: emit, signal: opts.signal }));
+    emit(makeEvent("phase.done", { phase: "safe-split", parts: partResults.length, verified: partResults.filter((r) => r.verified).length }));
+    // 2. MERGE the parts via a (single) integration step on a strong model.
+    await opts.checkpoint?.();
+    emit(makeEvent("phase.started", { phase: "safe-merge", mode: "safe" }));
+    // Merging integrates everyone's work — a MAJOR action, so it passes through
+    // the permission gate (moderate mode may hold it for approval).
+    const allowMerge = opts.requestPermission ? await opts.requestPermission("merge", "integrate all sub-results into the final solution", "major") : true;
+    if (!allowMerge) {
+        emit(makeEvent("agent.event", { note: "merge held by permission policy (request-box)", phase: "safe-merge" }));
+        emit(makeEvent("phase.done", { phase: "safe-merge", held: true }));
+        return { goal, mode: "safe", rounds: 1, subtasks: partResults, verified: false, summary: "merge held pending approval" };
+    }
+    const merged = await deps.merge(goal, partResults, { onEvent: emit, signal: opts.signal });
+    emit(makeEvent("phase.done", { phase: "safe-merge", verified: merged.verified, status: merged.status }));
+    // 3. Final validation pass over everything.
+    await opts.checkpoint?.();
+    const all = [...partResults, merged];
+    const evaluated = await deps.evaluate(goal, all);
+    emit(makeEvent("phase.done", { phase: "safe-validate", done: evaluated.done, reason: evaluated.reason }));
+    return { goal, mode: "safe", rounds: 1, subtasks: all, verified: evaluated.done && merged.verified, summary: evaluated.reason };
+}

package/dist/core/permissions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * permissions — the "request box" the spec describes.
+ *
+ * A single Headroom master controls everything, but it never performs work
+ * itself; its ants (workers) do. So permission is about gating the ants' major
+ * actions, not the master. Two postures:
+ *
+ *   full     — everything is allowed; the box stays empty.
+ *   moderate — every MAJOR or DESTRUCTIVE action stops and is filed as a
+ *              request. A goal-aware policy (the Headroom check) auto-approves
+ *              actions that clearly serve the stated goal and holds the rest for
+ *              an explicit approve/deny (by the master or a human via the UI).
+ *
+ * Requests are held in an in-memory box; each pending request exposes a promise
+ * (`await`) that resolves when it is decided. Low-risk actions never queue.
+ */
+export type PermissionMode = "full" | "moderate";
+export type Risk = "low" | "major" | "destructive";
+export type RequestStatus = "pending" | "approved" | "denied";
+export interface PermissionRequest {
+    id: string;
+    action: string;
+    detail: string;
+    risk: Risk;
+    goal?: string;
+    status: RequestStatus;
+    reason: string;
+    ts: string;
+    decidedBy?: string;
+}
+/** Classify an action string into a risk level (deterministic, pattern-based). */
+export declare function classifyRisk(action: string, detail?: string): Risk;
+export interface Policy {
+    (req: Pick<PermissionRequest, "action" | "detail" | "risk" | "goal">): {
+        allow: boolean;
+        reason: string;
+    };
+}
+/**
+ * The Headroom check: allow when the action plainly serves the goal.
+ *  - low risk           → always allow
+ *  - destructive        → never auto-allow (must be approved explicitly)
+ *  - major              → allow only if it aligns with the goal (keyword overlap)
+ */
+export declare function goalAwarePolicy(req: Pick<PermissionRequest, "action" | "detail" | "risk" | "goal">): {
+    allow: boolean;
+    reason: string;
+};
+export declare class PermissionBroker {
+    private mode;
+    private policy;
+    private box;
+    private waiters;
+    constructor(mode?: PermissionMode, opts?: {
+        policy?: Policy;
+    });
+    getMode(): PermissionMode;
+    /**
+     * File a request. Returns the (possibly already-decided) request. In `full`
+     * mode everything is approved immediately; in `moderate` mode the policy runs
+     * and only holds what it cannot justify.
+     */
+    request(action: string, detail: string, ctx?: {
+        risk?: Risk;
+        goal?: string;
+    }): PermissionRequest;
+    /** Resolve once the request is decided. Already-decided requests resolve now. */
+    await(id: string): Promise<boolean>;
+    /** Convenience: file + await in one call. */
+    gate(action: string, detail: string, ctx?: {
+        risk?: Risk;
+        goal?: string;
+    }): Promise<boolean>;
+    approve(id: string, by?: string): boolean;
+    deny(id: string, by?: string): boolean;
+    private decide;
+    pending(): PermissionRequest[];
+    list(): PermissionRequest[];
+    get(id: string): PermissionRequest | undefined;
+}

package/dist/core/permissions.js

@@ -0,0 +1,147 @@
+/**
+ * permissions — the "request box" the spec describes.
+ *
+ * A single Headroom master controls everything, but it never performs work
+ * itself; its ants (workers) do. So permission is about gating the ants' major
+ * actions, not the master. Two postures:
+ *
+ *   full     — everything is allowed; the box stays empty.
+ *   moderate — every MAJOR or DESTRUCTIVE action stops and is filed as a
+ *              request. A goal-aware policy (the Headroom check) auto-approves
+ *              actions that clearly serve the stated goal and holds the rest for
+ *              an explicit approve/deny (by the master or a human via the UI).
+ *
+ * Requests are held in an in-memory box; each pending request exposes a promise
+ * (`await`) that resolves when it is decided. Low-risk actions never queue.
+ */
+import { randomUUID } from "node:crypto";
+/** Classify an action string into a risk level (deterministic, pattern-based). */
+export function classifyRisk(action, detail = "") {
+    const s = `${action} ${detail}`.toLowerCase();
+    if (/(rm\s+-rf|rmdir\s+\/s|drop\s+(table|database)|truncate|del\s+\/|format\s|mkfs|:\s*>\s|force[-\s]?push|--force\b|\bpush\b.*\s-f\b|reset\s+--hard|git\s+clean\s+-|delete\s+from|shutdown|reboot)/.test(s)) {
+        return "destructive";
+    }
+    if (/(write|create|modify|edit|install|npm\s+i|pip\s+install|deploy|publish|push|commit|merge|migrate|chmod|chown|mv\s|move|rename|apply|patch)/.test(s)) {
+        return "major";
+    }
+    return "low";
+}
+/**
+ * The Headroom check: allow when the action plainly serves the goal.
+ *  - low risk           → always allow
+ *  - destructive        → never auto-allow (must be approved explicitly)
+ *  - major              → allow only if it aligns with the goal (keyword overlap)
+ */
+export function goalAwarePolicy(req) {
+    if (req.risk === "low")
+        return { allow: true, reason: "low-risk action" };
+    if (req.risk === "destructive")
+        return { allow: false, reason: "destructive action requires explicit approval" };
+    // major: align against the goal.
+    const goal = (req.goal ?? "").toLowerCase();
+    if (!goal)
+        return { allow: false, reason: "no goal context to justify a major action" };
+    const words = new Set((req.action + " " + req.detail).toLowerCase().split(/\W+/).filter((w) => w.length >= 4));
+    const goalWords = new Set(goal.split(/\W+/).filter((w) => w.length >= 4));
+    let overlap = 0;
+    for (const w of words)
+        if (goalWords.has(w))
+            overlap++;
+    return overlap > 0
+        ? { allow: true, reason: `major action aligns with the goal (${overlap} matching term(s))` }
+        : { allow: false, reason: "major action does not clearly serve the stated goal" };
+}
+export class PermissionBroker {
+    mode;
+    policy;
+    box = new Map();
+    waiters = new Map();
+    constructor(mode = "moderate", opts = {}) {
+        this.mode = mode;
+        this.policy = opts.policy ?? goalAwarePolicy;
+    }
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * File a request. Returns the (possibly already-decided) request. In `full`
+     * mode everything is approved immediately; in `moderate` mode the policy runs
+     * and only holds what it cannot justify.
+     */
+    request(action, detail, ctx = {}) {
+        const risk = ctx.risk ?? classifyRisk(action, detail);
+        const req = {
+            id: randomUUID(),
+            action,
+            detail,
+            risk,
+            goal: ctx.goal,
+            status: "pending",
+            reason: "",
+            ts: new Date().toISOString(),
+        };
+        if (this.mode === "full") {
+            req.status = "approved";
+            req.reason = "full-permission mode";
+            this.box.set(req.id, req);
+            return req;
+        }
+        const verdict = this.policy({ action, detail, risk, goal: ctx.goal });
+        if (verdict.allow) {
+            req.status = "approved";
+            req.reason = verdict.reason;
+        }
+        else {
+            req.status = "pending";
+            req.reason = verdict.reason;
+        }
+        this.box.set(req.id, req);
+        return req;
+    }
+    /** Resolve once the request is decided. Already-decided requests resolve now. */
+    await(id) {
+        const req = this.box.get(id);
+        if (!req)
+            return Promise.resolve(false);
+        if (req.status !== "pending")
+            return Promise.resolve(req.status === "approved");
+        return new Promise((resolve) => {
+            const list = this.waiters.get(id) ?? [];
+            list.push({ resolve });
+            this.waiters.set(id, list);
+        });
+    }
+    /** Convenience: file + await in one call. */
+    async gate(action, detail, ctx = {}) {
+        const req = this.request(action, detail, ctx);
+        return this.await(req.id);
+    }
+    approve(id, by = "user") {
+        return this.decide(id, "approved", by);
+    }
+    deny(id, by = "user") {
+        return this.decide(id, "denied", by);
+    }
+    decide(id, status, by) {
+        const req = this.box.get(id);
+        if (!req || req.status !== "pending")
+            return false;
+        req.status = status;
+        req.decidedBy = by;
+        req.reason = `${status} by ${by}`;
+        const waiters = this.waiters.get(id) ?? [];
+        for (const w of waiters)
+            w.resolve(status === "approved");
+        this.waiters.delete(id);
+        return true;
+    }
+    pending() {
+        return [...this.box.values()].filter((r) => r.status === "pending");
+    }
+    list() {
+        return [...this.box.values()];
+    }
+    get(id) {
+        return this.box.get(id);
+    }
+}

package/dist/core/providers-catalog.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Provider catalog — the 2026 "menu" the guided launcher shows for AI mode
+ * option (3): every kind of AI API provider, its setup format, docs link, and
+ * a known model list. Listing is FREE — it consumes zero tokens and makes zero
+ * network calls. A provider only becomes "active" the moment a task actually
+ * uses it.
+ *
+ * This is deliberately static + dependency-free: it is the vocabulary the
+ * launcher and Headroom knowledge doc are built from. Model lists are the
+ * publicly-known families as of 2026-07; the live `/models`-style discovery for
+ * a specific key is a separate, opt-in step (see capabilities.ts).
+ */
+import type { CapabilityTier } from "./capabilities.js";
+/** How a provider's HTTP API is shaped (drives which ModelProvider we use). */
+export type ApiFormat = "openai" | "anthropic" | "gemini" | "ollama";
+export interface CatalogModel {
+    id: string;
+    /** Rough capability class used for the efficient-"mid" auto pick. */
+    tier: CapabilityTier;
+    /** Multimodal / vision capable. */
+    vision?: boolean;
+    /** Very large context (>= 200k tokens). */
+    longContext?: boolean;
+}
+export interface CatalogProvider {
+    /** Stable id used in config (`provider`). */
+    id: string;
+    label: string;
+    /** OpenAI-compatible? anthropic-native? etc. */
+    format: ApiFormat;
+    /** The MAQ provider name getProvider() understands. */
+    maqProvider: string;
+    /** Env var that holds the API key (empty for keyless/local). */
+    envVar: string;
+    /** Default REST base URL. */
+    baseUrl: string;
+    /** Where the user gets a key / reads setup docs. */
+    docsUrl: string;
+    /** True for local/self-hosted providers (no key, no cost). */
+    local?: boolean;
+    /** Known model families (list-only; not fetched). */
+    models: CatalogModel[];
+    /** One-line setup hint shown in the launcher. */
+    setup: string;
+}
+/**
+ * The registry. Ordered roughly by how commonly it is the user's daily driver.
+ * Model ids are the well-known 2026 families; keep them representative rather
+ * than exhaustive — the point is a browsable, $0 menu.
+ */
+export declare const PROVIDER_CATALOG: CatalogProvider[];
+export declare function getCatalogProvider(id: string): CatalogProvider | undefined;
+export declare function providerGoodFor(id: string): string[];
+/**
+ * Detect which catalog providers are usable RIGHT NOW from the environment
+ * only — no network, no tokens. Local providers (Ollama) are reported as
+ * "actionable" (installed/reachable is confirmed later, on first use).
+ */
+export declare function detectAvailableProviders(env?: NodeJS.ProcessEnv): Array<{
+    provider: CatalogProvider;
+    active: boolean;
+    reason: string;
+}>;
+/** Flat list of every catalog model tagged with its provider (for tiering). */
+export declare function allCatalogModels(): Array<CatalogModel & {
+    provider: string;
+    maqProvider: string;
+}>;