maqcli 0.4.0 → 0.6.0

package/dist/core/capabilities.d.ts

@@ -21,6 +21,8 @@ export interface TieredModel {
     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

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

@@ -41,6 +41,7 @@ export const maqCommands = [
     { name: "memory", category: "memory", summary: "Recall memory store (injected into planning).", usage: "maq memory [store|recall|list]", needsInput: "query", args: [] },
     { name: "flow", category: "control", summary: "Scheduled agent sessions (run under the daemon).", usage: "maq flow [list|add|remove]", needsInput: "none", args: [] },
     { name: "audit", category: "control", summary: "Verify a run's hash-chained audit log.", usage: "maq audit verify <run-dir>", needsInput: "none", args: [] },
+    { name: "security", category: "system", summary: "Enforced security rules (protected paths, egress allowlist, injection scanning) + recent findings.", usage: "maq security [report|rules|scan <path>]", needsInput: "none", args: [] },
 ];
 /** Catalog of AI worker CLIs' own commands/flags (verified 2026-07-01). */
 export const aiCliCatalog = [

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

@@ -31,6 +31,10 @@ export interface MaqConfig {
     headroomModel: string;
     /** True once the guided launcher has completed first-run setup. */
     onboarded: boolean;
+    /** Project-specific additions to the protected-path denylist (base list is never removable). */
+    extraProtectedPaths: string[];
+    /** Additional hosts allowed for network egress (default allowlist is always applied on top). */
+    extraNetAllowlist: string[];
 }
 export declare const DEFAULT_CONFIG: MaqConfig;
 export declare function configDir(): string;
@@ -39,3 +43,7 @@ export declare function loadConfig(): MaqConfig;
 export declare function saveConfig(cfg: MaqConfig): void;
 /** Set a single top-level scalar key by string, coercing to the existing type. */
 export declare function setConfigKey(key: string, value: string): MaqConfig;
+/** Append a value to an array-valued config key (e.g. security allowlists). */
+export declare function addConfigListItem(key: string, value: string): MaqConfig;
+/** Remove a value from an array-valued config key. */
+export declare function removeConfigListItem(key: string, value: string): MaqConfig;

package/dist/core/config-store.js

@@ -19,6 +19,8 @@ export const DEFAULT_CONFIG = {
     executionMode: "loop",
     headroomModel: "",
     onboarded: false,
+    extraProtectedPaths: [],
+    extraNetAllowlist: [],
 };
 export function configDir() {
     return process.env.MAQ_CONFIG_DIR ?? join(homedir(), ".maqcli");
@@ -57,9 +59,34 @@ export function setConfigKey(key, value) {
     if (typeof current === "boolean")
         coerced = value === "true";
     if (typeof current === "object") {
-        throw new Error(`Cannot set object key '${key}' from the CLI`);
+        throw new Error(`Cannot set object key '${key}' from the CLI; use addConfigListItem/removeConfigListItem`);
     }
     cfg[key] = coerced;
     saveConfig(cfg);
     return cfg;
 }
+/** Array-valued config keys that may be extended/trimmed from the CLI. */
+const LIST_KEYS = new Set(["extraProtectedPaths", "extraNetAllowlist"]);
+/** Append a value to an array-valued config key (e.g. security allowlists). */
+export function addConfigListItem(key, value) {
+    if (!LIST_KEYS.has(key))
+        throw new Error(`'${key}' is not a list config key`);
+    const cfg = loadConfig();
+    const list = cfg[key];
+    if (!list.includes(value))
+        list.push(value);
+    saveConfig(cfg);
+    return cfg;
+}
+/** Remove a value from an array-valued config key. */
+export function removeConfigListItem(key, value) {
+    if (!LIST_KEYS.has(key))
+        throw new Error(`'${key}' is not a list config key`);
+    const cfg = loadConfig();
+    const list = cfg[key];
+    const idx = list.indexOf(value);
+    if (idx >= 0)
+        list.splice(idx, 1);
+    saveConfig(cfg);
+    return cfg;
+}

package/dist/core/exec.d.ts

@@ -14,6 +14,15 @@ export interface ExecOptions {
     maxBuffer?: number;
     /** Abort signal; kills the child when aborted. */
     signal?: AbortSignal;
+    /**
+     * Secret hygiene for the spawned process (NVIDIA: "secret injection, not
+     * inheritance"). Defaults to scrubbing secret-shaped env vars from the
+     * inherited environment. Set to false to opt out (e.g. a trusted local
+     * tool that legitimately needs a key); pass `secretAllowlist` to re-admit
+     * specific names the task actually needs.
+     */
+    scrubSecrets?: boolean;
+    secretAllowlist?: string[];
 }
 export interface ExecOutcome {
     code: number | null;

package/dist/core/exec.js

@@ -6,6 +6,7 @@
  * chokepoint for running worker CLIs and raw commands.
  */
 import { spawn } from "node:child_process";
+import { scrubEnv } from "./security.js";
 /**
  * Run a command safely. `cmd` is the binary, `args` are passed verbatim.
  * Never pass a full command string here — that is what enables injection.
@@ -13,9 +14,11 @@ import { spawn } from "node:child_process";
 export function execSafe(cmd, args = [], opts = {}) {
     const maxBuffer = opts.maxBuffer ?? 10 * 1024 * 1024;
     return new Promise((resolve) => {
+        const baseEnv = opts.env ?? process.env;
+        const env = opts.scrubSecrets === false ? baseEnv : scrubEnv(baseEnv, opts.secretAllowlist);
         const child = spawn(cmd, args, {
             cwd: opts.cwd ?? process.cwd(),
-            env: opts.env ?? process.env,
+            env,
             shell: false,
             windowsHide: true,
         });
@@ -78,9 +81,11 @@ export function execSafe(cmd, args = [], opts = {}) {
 export function execStream(cmd, args = [], opts = {}) {
     const maxBuffer = opts.maxBuffer ?? 20 * 1024 * 1024;
     return new Promise((resolve) => {
+        const baseEnv = opts.env ?? process.env;
+        const env = opts.scrubSecrets === false ? baseEnv : scrubEnv(baseEnv, opts.secretAllowlist);
         const child = spawn(cmd, args, {
             cwd: opts.cwd ?? process.cwd(),
-            env: opts.env ?? process.env,
+            env,
             shell: false,
             windowsHide: true,
         });

package/dist/core/launcher.d.ts

@@ -31,6 +31,12 @@ export declare function browserOpenCommand(url: string, platform?: NodeJS.Platfo
 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[];

package/dist/core/launcher.js

@@ -21,18 +21,10 @@ 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, } from "./providers-catalog.js";
+import { PROVIDER_CATALOG, detectAvailableProviders, getCatalogProvider, providerGoodFor, } from "./providers-catalog.js";
 import { classifyModel, pickEfficient } from "./capabilities.js";
 import { buildKnowledge, saveKnowledge, roleForModel } from "./onboarding.js";
-/** Preferred lightest master invocation per detected CLI agent ($0 marginal). */
-const CLI_MASTER_HINT = {
-    gemini: "cli:gemini",
-    "claude-code": "cli:claude-code",
-    codex: "cli:codex",
-    opencode: "cli:opencode",
-    "amazon-q": "cli:amazon-q",
-    aider: "cli:aider",
-};
+import { probeCliCapability } from "./cli-probe.js";
 /* --------------------------- pure, testable ---------------------------- */
 /** A user-facing 9-digit pairing/auth key (100000000–999999999). */
 export function generateAuthKey() {
@@ -85,6 +77,45 @@ export function megalodonSplash(color = true) {
         "",
     ].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
@@ -121,7 +152,7 @@ export function applyOnboarding(choices) {
                 : m.tier === "heavy"
                     ? "reviewer"
                     : "worker";
-        return roleForModel(m, role, choices.source);
+        return roleForModel(m, role, choices.source, m.goodFor ?? []);
     });
     const knowledge = buildKnowledge({
         providers,
@@ -144,7 +175,7 @@ function line(s = "") {
  * (piped stdin), it prints guidance and returns without blocking.
  */
 export async function runLauncher(cwd) {
-    line(megalodonSplash(useColor()));
+    await animateSplash(useColor());
     if (!process.stdin.isTTY) {
         line("maq: guided setup needs an interactive terminal.");
         line("  • run `maq start` in a real terminal, or");
@@ -242,15 +273,22 @@ async function registerClis(rl) {
         line("or pick option 3 (API providers). Continuing with none for now.");
         return { models: [], source: "cli" };
     }
-    line("\nFound these authenticated CLIs (registered as $0 workers):");
+    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 masterModel = CLI_MASTER_HINT[a.name] ?? `cli:${a.name}`;
-        // A CLI reused as a master is treated as a mid-tier worker for tiering.
-        models.push({ id: masterModel, provider: a.name, maqProvider: masterModel, tier: "mid" });
-        line(`  • ${a.name}  → ${masterModel}`);
+        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}`);
     }
-    line(`\n(To register each CLI's own model list, MAQ will ask it "/models" on first use.)`);
     return { models, source: "cli" };
 }
 async function registerSingleApi(rl) {
@@ -269,7 +307,7 @@ async function registerSingleApi(rl) {
     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 }],
+        models: [{ id: model.id, provider: chosen.id, maqProvider: chosen.maqProvider, tier: model.tier, goodFor: providerGoodFor(chosen.id) }],
         source: "api",
     };
 }
@@ -292,6 +330,9 @@ async function registerMultiApi(rl) {
         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" };
@@ -312,7 +353,7 @@ async function connectMobile(rl) {
 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.4.0" });
+    const daemon = createDaemon({ token: authKey, version: "0.6.0" });
     try {
         const { host, port } = await daemon.listen();
         const url = `http://${host}:${port}/`;

package/dist/core/orchestrator.d.ts

@@ -70,6 +70,11 @@ export interface OrchestrationOptions {
     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>;
 }

package/dist/core/orchestrator.js

@@ -209,6 +209,14 @@ async function engineSafe(goal, deps, opts, emit) {
     // 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.

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;
+}