maqcli 0.2.0 → 0.4.0

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,85 @@
+/**
+ * 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>;
+    /** 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>;

package/dist/core/orchestrator.js

@@ -0,0 +1,220 @@
+/**
+ * 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" }));
+    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/providers-catalog.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;
+/**
+ * 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;
+}>;