maqcli 0.2.0 → 0.5.0

package/dist/core/capabilities.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Capability tiering — the brain behind "pick an EFFICIENT model, not the
+ * cheapest and not the most expensive".
+ *
+ * Every model the launcher discovers (from the static catalog, from a worker
+ * CLI's /models list, or from a live provider) is classified into one of three
+ * tiers. The guided launcher's AUTO choice for the Headroom model is the best
+ * available MID model: enough capability to manage the whole god-level flow
+ * without paying for max power or crippling it with a toy model.
+ *
+ *   light  — triage/summaries/cheap fan-out workers
+ *   mid    — the efficient default: plans, routing, Headroom management
+ *   heavy  — reserved for the hardest single steps (opt-in / manual)
+ */
+export type CapabilityTier = "light" | "mid" | "heavy";
+export interface TieredModel {
+    id: string;
+    provider: string;
+    /** MAQ provider name for getProvider(). */
+    maqProvider: string;
+    tier: CapabilityTier;
+    vision?: boolean;
+    longContext?: boolean;
+    /** Roles this model is suited for (plan|code|review|summarize|fan-out). */
+    goodFor?: string[];
+}
+/**
+ * Heuristic classifier for a raw model id when we have no catalog tag (e.g. a
+ * model name returned by a CLI's `/models`). Pattern-based, deterministic.
+ */
+export declare function classifyModel(id: string): CapabilityTier;
+export declare function tierRank(t: CapabilityTier): number;
+/**
+ * Pick the efficient model from a set of available tiered models.
+ *
+ * Preference: a MID model first; if none, fall back to the strongest LIGHT
+ * (so we never silently jump to an expensive HEAVY as the "auto efficient"
+ * default). If only HEAVY exists, use it but flag it.
+ */
+export declare function pickEfficient(models: TieredModel[]): {
+    model: TieredModel;
+    note: string;
+} | null;
+/** Split a set of models into their tier buckets (for display). */
+export declare function groupByTier(models: TieredModel[]): Record<CapabilityTier, TieredModel[]>;
+/**
+ * The instruction MAQ hands a worker CLI (option 1) so it self-reports its
+ * capabilities in a machine-parseable form. Kept tiny and format-strict so the
+ * reply can be stored directly into the Headroom knowledge doc.
+ */
+export declare const CAPABILITY_PROBE_INSTRUCTION: string;
+/** Parse a capability-probe reply into a partial TieredModel-ish record. */
+export declare function parseCapabilityReply(reply: string): {
+    tier: CapabilityTier;
+    strengths: string[];
+    contextTokens?: number;
+    vision?: boolean;
+    goodFor: string[];
+} | null;

package/dist/core/capabilities.js

@@ -0,0 +1,106 @@
+/**
+ * Capability tiering — the brain behind "pick an EFFICIENT model, not the
+ * cheapest and not the most expensive".
+ *
+ * Every model the launcher discovers (from the static catalog, from a worker
+ * CLI's /models list, or from a live provider) is classified into one of three
+ * tiers. The guided launcher's AUTO choice for the Headroom model is the best
+ * available MID model: enough capability to manage the whole god-level flow
+ * without paying for max power or crippling it with a toy model.
+ *
+ *   light  — triage/summaries/cheap fan-out workers
+ *   mid    — the efficient default: plans, routing, Headroom management
+ *   heavy  — reserved for the hardest single steps (opt-in / manual)
+ */
+/**
+ * Heuristic classifier for a raw model id when we have no catalog tag (e.g. a
+ * model name returned by a CLI's `/models`). Pattern-based, deterministic.
+ */
+export function classifyModel(id) {
+    const s = id.toLowerCase();
+    // Heavy: flagship / reasoning / "pro"/"opus"/"large"/"ultra" families.
+    if (/(opus|-4\.1$|-4\.5|ultra|large|o3\b|reasoner|r1\b|pro\b|405b|grok-4)/.test(s)) {
+        return "heavy";
+    }
+    // Reasoning "mini" models (o1/o3/o4-mini) are efficient MID, not light.
+    if (/\bo[1345]-mini/.test(s)) {
+        return "mid";
+    }
+    // Light: explicitly small / fast / nano / haiku / mini / 8b / flash-lite.
+    // NB: \bmini avoids matching "geMINI".
+    if (/(nano|\bmini|instant|haiku|flash-lite|-8b|-7b|1\.5-flash|3\.2$|small)/.test(s)) {
+        return "light";
+    }
+    // Mid: the efficient middle — flash, sonnet, medium, 70b, coder.
+    if (/(flash|sonnet|medium|70b|coder|grok-3|deepseek-chat)/.test(s)) {
+        return "mid";
+    }
+    // Default unknown to mid so AUTO stays "efficient" rather than risky.
+    return "mid";
+}
+const TIER_ORDER = { light: 0, mid: 1, heavy: 2 };
+export function tierRank(t) {
+    return TIER_ORDER[t];
+}
+/**
+ * Pick the efficient model from a set of available tiered models.
+ *
+ * Preference: a MID model first; if none, fall back to the strongest LIGHT
+ * (so we never silently jump to an expensive HEAVY as the "auto efficient"
+ * default). If only HEAVY exists, use it but flag it.
+ */
+export function pickEfficient(models) {
+    if (models.length === 0)
+        return null;
+    const mids = models.filter((m) => m.tier === "mid");
+    if (mids.length > 0) {
+        // Prefer a mid model with long context (better for Headroom management).
+        const best = mids.find((m) => m.longContext) ?? mids[0];
+        return { model: best, note: "efficient mid-tier: balanced capability vs cost" };
+    }
+    const lights = models.filter((m) => m.tier === "light");
+    if (lights.length > 0) {
+        return { model: lights[0], note: "no mid model available; using the strongest light model" };
+    }
+    return { model: models[0], note: "only heavy models available; consider a mid model to save cost" };
+}
+/** Split a set of models into their tier buckets (for display). */
+export function groupByTier(models) {
+    const out = { light: [], mid: [], heavy: [] };
+    for (const m of models)
+        out[m.tier].push(m);
+    return out;
+}
+/**
+ * The instruction MAQ hands a worker CLI (option 1) so it self-reports its
+ * capabilities in a machine-parseable form. Kept tiny and format-strict so the
+ * reply can be stored directly into the Headroom knowledge doc.
+ */
+export const CAPABILITY_PROBE_INSTRUCTION = [
+    "You are being registered as a worker model inside the MAQ orchestrator.",
+    "Reply with ONLY a compact JSON object, no prose, in exactly this shape:",
+    '{"tier":"light|mid|heavy","strengths":["..."],"context_tokens":<int>,"vision":<bool>,"good_for":["plan"|"code"|"review"|"summarize"|"fan-out"]}',
+    "Base it on your own known capabilities. Do not include markdown fences.",
+].join("\n");
+/** Parse a capability-probe reply into a partial TieredModel-ish record. */
+export function parseCapabilityReply(reply) {
+    const trimmed = reply.trim().replace(/^```(json)?/i, "").replace(/```$/, "").trim();
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return null;
+    try {
+        const j = JSON.parse(trimmed.slice(start, end + 1));
+        const tier = ["light", "mid", "heavy"].includes(j.tier) ? j.tier : "mid";
+        return {
+            tier,
+            strengths: Array.isArray(j.strengths) ? j.strengths.map(String) : [],
+            contextTokens: typeof j.context_tokens === "number" ? j.context_tokens : undefined,
+            vision: Boolean(j.vision),
+            goodFor: Array.isArray(j.good_for) ? j.good_for.map(String) : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/cli-probe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * cli-probe — actually USE the user's own AI CLIs to learn what they can do.
+ *
+ * The launcher's option (1) registers installed CLIs, but a name alone tells us
+ * nothing about capability. Here we hand each authenticated CLI the
+ * CAPABILITY_PROBE_INSTRUCTION (via its headless mode, at $0 marginal cost —
+ * the user's existing subscription pays) and parse its self-reported tier /
+ * strengths / context / good-for. That report is what we store into the
+ * Headroom knowledge doc so the master can route work to the right model.
+ *
+ * The model call is injectable (`complete`) so this is unit-testable offline
+ * without spawning a real CLI.
+ */
+import { type CapabilityTier } from "./capabilities.js";
+export interface CliCapability {
+    name: string;
+    maqProvider: string;
+    tier: CapabilityTier;
+    strengths: string[];
+    goodFor: string[];
+    contextTokens?: number;
+    vision?: boolean;
+    /** Whether the report came from the CLI itself vs a heuristic fallback. */
+    probed: boolean;
+}
+export type CompleteFn = (prompt: string) => Promise<string>;
+/**
+ * Probe a single CLI. `complete` defaults to the cli:<name> provider; pass a
+ * stub in tests. Never throws — on any failure it returns a heuristic default
+ * so onboarding always proceeds.
+ */
+export declare function probeCliCapability(name: string, opts?: {
+    complete?: CompleteFn;
+    timeoutMs?: number;
+}): Promise<CliCapability>;
+/**
+ * Probe every authenticated CLI (or a provided list). Runs in parallel; each
+ * probe is independently best-effort.
+ */
+export declare function probeInstalledClis(opts?: {
+    names?: string[];
+    complete?: CompleteFn;
+    timeoutMs?: number;
+}): Promise<CliCapability[]>;

package/dist/core/cli-probe.js

@@ -0,0 +1,85 @@
+/**
+ * cli-probe — actually USE the user's own AI CLIs to learn what they can do.
+ *
+ * The launcher's option (1) registers installed CLIs, but a name alone tells us
+ * nothing about capability. Here we hand each authenticated CLI the
+ * CAPABILITY_PROBE_INSTRUCTION (via its headless mode, at $0 marginal cost —
+ * the user's existing subscription pays) and parse its self-reported tier /
+ * strengths / context / good-for. That report is what we store into the
+ * Headroom knowledge doc so the master can route work to the right model.
+ *
+ * The model call is injectable (`complete`) so this is unit-testable offline
+ * without spawning a real CLI.
+ */
+import { getProvider } from "./model.js";
+import { detectAgents } from "./registry.js";
+import { CAPABILITY_PROBE_INSTRUCTION, parseCapabilityReply, classifyModel, } from "./capabilities.js";
+/**
+ * Probe a single CLI. `complete` defaults to the cli:<name> provider; pass a
+ * stub in tests. Never throws — on any failure it returns a heuristic default
+ * so onboarding always proceeds.
+ */
+export async function probeCliCapability(name, opts = {}) {
+    const maqProvider = `cli:${name}`;
+    const fallback = {
+        name,
+        maqProvider,
+        tier: classifyModel(name),
+        strengths: [],
+        goodFor: ["code"],
+        probed: false,
+    };
+    const complete = opts.complete ??
+        (async (prompt) => {
+            const provider = getProvider(maqProvider, { strict: true });
+            const res = await provider.complete({
+                model: maqProvider,
+                messages: [{ role: "user", content: prompt }],
+                maxTokens: 300,
+            });
+            return res.text;
+        });
+    try {
+        const timeoutMs = opts.timeoutMs ?? 45000;
+        const reply = await withTimeout(complete(CAPABILITY_PROBE_INSTRUCTION), timeoutMs);
+        const parsed = parseCapabilityReply(reply);
+        if (!parsed)
+            return fallback;
+        return {
+            name,
+            maqProvider,
+            tier: parsed.tier,
+            strengths: parsed.strengths,
+            goodFor: parsed.goodFor.length ? parsed.goodFor : ["code"],
+            contextTokens: parsed.contextTokens,
+            vision: parsed.vision,
+            probed: true,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Probe every authenticated CLI (or a provided list). Runs in parallel; each
+ * probe is independently best-effort.
+ */
+export async function probeInstalledClis(opts = {}) {
+    const names = opts.names ??
+        detectAgents()
+            .filter((a) => a.installed && a.authenticated)
+            .map((a) => a.name);
+    return Promise.all(names.map((n) => probeCliCapability(n, { complete: opts.complete, timeoutMs: opts.timeoutMs })));
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("capability probe timed out")), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }).catch((e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}

package/dist/core/command-catalog.js

@@ -18,6 +18,12 @@ export const maqCommands = [
             { name: "audit", type: "boolean", description: "write hash-chained audit log" },
         ] },
     { name: "scout", category: "pipeline", summary: "Read-only recon; structured findings (0 tokens).", usage: 'maq scout "<task>"', needsInput: "task", args: [] },
+    { name: "orchestrate", category: "pipeline", summary: "Run a goal through the parallel/loop/safe execution engine.", usage: 'maq orchestrate "<goal>" -m parallel|loop|safe', needsInput: "task",
+        args: [
+            { name: "mode", type: "enum", choices: ["parallel", "loop", "safe"], required: true, description: "execution engine" },
+            { name: "target", type: "enum", choices: ["auto", "claude-code", "codex", "gemini", "none"], description: "worker CLI" },
+            { name: "concurrency", type: "string", description: "max parallel sub-tasks" },
+        ] },
     { name: "plan", category: "pipeline", summary: "Verifier-gated candidate plan.", usage: 'maq plan "<task>"', needsInput: "task", args: [] },
     { name: "verify", category: "pipeline", summary: "Run project tests / cross-model review.", usage: "maq verify [--cwd d]", needsInput: "none", args: [] },
     { name: "swarm", category: "pipeline", summary: "Run several tasks across parallel workers, then join.", usage: 'maq swarm "<t1>" "<t2>" … [--target t] [--concurrency N]', needsInput: "none", args: [{ name: "concurrency", type: "string", description: "max parallel workers" }] },

package/dist/core/config-store.d.ts

@@ -23,6 +23,14 @@ export interface MaqConfig {
     projectTargets: Record<string, string>;
     /** Default permission level (strict or standard) */
     defaultPermission: string;
+    /** Guided-launcher posture: "full" (all allowed) | "moderate" (request-box). */
+    permissionMode: string;
+    /** Default execution strategy: "parallel" | "loop" | "safe". */
+    executionMode: string;
+    /** The efficient (mid) model the Headroom master runs on; "" = auto. */
+    headroomModel: string;
+    /** True once the guided launcher has completed first-run setup. */
+    onboarded: boolean;
 }
 export declare const DEFAULT_CONFIG: MaqConfig;
 export declare function configDir(): string;

package/dist/core/config-store.js

@@ -15,6 +15,10 @@ export const DEFAULT_CONFIG = {
     compactionThreshold: 0.6,
     projectTargets: {},
     defaultPermission: "standard",
+    permissionMode: "moderate",
+    executionMode: "loop",
+    headroomModel: "",
+    onboarded: false,
 };
 export function configDir() {
     return process.env.MAQ_CONFIG_DIR ?? join(homedir(), ".maqcli");

package/dist/core/init-wizard.js

@@ -92,13 +92,15 @@ async function _runWizard(rl, cwd, summary) {
     console.log("  ─────────────────────────────");
     console.log("");
     /* ── 2. Auto-detect agents ──────────────────────────────────── */
-    const agents = await detectAgents();
-    if (agents.length > 0) {
+    const agents = detectAgents();
+    const installed = agents.filter((a) => a.installed);
+    if (installed.length > 0) {
         console.log("  Detected agents:");
-        for (const agent of agents) {
-            console.log(`    • ${agent}`);
+        for (const agent of installed) {
+            const status = agent.authenticated ? "authenticated" : "installed (logged out)";
+            console.log(`    • ${agent.name} — ${status}`);
         }
-        summary.push(`Detected ${agents.length} agent(s): ${agents.join(", ")}`);
+        summary.push(`Detected ${installed.length} agent(s): ${installed.map((a) => a.name).join(", ")}`);
     }
     else {
         console.log("  No agents detected.");

package/dist/core/launcher.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { type MaqConfig } from "./config-store.js";
+import { getCatalogProvider } from "./providers-catalog.js";
+import { type TieredModel } from "./capabilities.js";
+import { type ProviderRole } from "./onboarding.js";
+/** A user-facing 9-digit pairing/auth key (100000000–999999999). */
+export declare function generateAuthKey(): string;
+/** OS-specific command to open a URL in the default browser. */
+export declare function browserOpenCommand(url: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+};
+/** Best-effort: open a URL in the default browser (never throws). */
+export declare function openBrowser(url: string): void;
+/** The Megalodon splash. `color=false` yields a plain-text version. */
+export declare function megalodonSplash(color?: boolean): string;
+/**
+ * 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 declare function megalodonFrames(color?: boolean): string[];
+export interface OnboardingChoices {
+    /** Registered worker/master models (already tiered). */
+    models: TieredModel[];
+    /** Chosen Headroom (efficient) model; null lets applyOnboarding auto-pick. */
+    headroom?: {
+        provider: string;
+        model: string;
+    } | null;
+    /** Whether the Headroom model was auto-picked. */
+    headroomAuto: boolean;
+    permissionMode: "full" | "moderate";
+    /** How each model was sourced, for the knowledge doc. */
+    source: ProviderRole["source"];
+}
+export interface OnboardingResult {
+    config: MaqConfig;
+    knowledgePath: string;
+    headroom: {
+        provider: string;
+        model: string;
+    } | null;
+    authKey: string;
+}
+/**
+ * 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 declare function applyOnboarding(choices: OnboardingChoices): OnboardingResult;
+/**
+ * Run the guided launcher. Returns 0 on success. In a non-interactive context
+ * (piped stdin), it prints guidance and returns without blocking.
+ */
+export declare function runLauncher(cwd: string): Promise<number>;
+/** For discoverability from `maq --help` / knowledge. */
+export declare const LAUNCHER_PROVIDERS: string[];
+export { getCatalogProvider };