maqcli 0.2.0

package/dist/phases/execute.d.ts

@@ -0,0 +1,39 @@
+/**
+ * EXECUTE phase: dispatch the winning plan to the resolved worker.
+ *
+ * - target = an AI CLI  -> invoke it headless with the plan as the task,
+ *   wrapping its stdout/stderr through Headroom compression before it would
+ *   reach any downstream model.
+ * - target = "none"     -> run the plan's steps as raw commands (the non-AI
+ *   device-control / bash path), still via safe array-arg execution.
+ *
+ * All execution goes through execSafe (shell:false, argument arrays) so
+ * model/user-provided values can never be shell-interpreted.
+ */
+import type { ExecuteResult, Plan, MaqEvent } from "../core/types.js";
+import { type StreamLine } from "../core/exec.js";
+import { Headroom } from "../core/headroom.js";
+export interface ExecuteOptions {
+    cwd: string;
+    target: string;
+    binPath: string | null;
+    /** When true, do not actually run anything (plan-only dry run). */
+    dryRun?: boolean;
+    timeoutMs?: number;
+    headroom?: Headroom;
+    /** Real-time normalized event sink (agent.stdout/stderr, tool.call, ...). */
+    onEvent?: (e: MaqEvent) => void;
+    /** Whether the worker emits a stable JSON-lines stream (parse structurally). */
+    jsonStream?: boolean;
+    /** Abort signal; kills the worker/raw child process when aborted. */
+    signal?: AbortSignal;
+}
+/**
+ * Normalize one worker output line into a MaqEvent. JSON lines from stable
+ * streams (e.g. Claude Code) become structured `agent.event`/`tool.call`;
+ * everything else is passthrough `agent.stdout`/`agent.stderr`.
+ */
+export declare function normalizeLine(l: StreamLine): MaqEvent;
+/** Split a raw command string into argv without invoking a shell. */
+export declare function tokenizeCommand(cmd: string): string[];
+export declare function runExecute(plan: Plan, opts: ExecuteOptions): Promise<ExecuteResult>;

package/dist/phases/execute.js

@@ -0,0 +1,166 @@
+/**
+ * EXECUTE phase: dispatch the winning plan to the resolved worker.
+ *
+ * - target = an AI CLI  -> invoke it headless with the plan as the task,
+ *   wrapping its stdout/stderr through Headroom compression before it would
+ *   reach any downstream model.
+ * - target = "none"     -> run the plan's steps as raw commands (the non-AI
+ *   device-control / bash path), still via safe array-arg execution.
+ *
+ * All execution goes through execSafe (shell:false, argument arrays) so
+ * model/user-provided values can never be shell-interpreted.
+ */
+import { makeEvent } from "../core/types.js";
+import { execStream } from "../core/exec.js";
+import { agentSpec } from "../core/registry.js";
+import { Headroom } from "../core/headroom.js";
+/**
+ * Normalize one worker output line into a MaqEvent. JSON lines from stable
+ * streams (e.g. Claude Code) become structured `agent.event`/`tool.call`;
+ * everything else is passthrough `agent.stdout`/`agent.stderr`.
+ */
+export function normalizeLine(l) {
+    if (l.stream === "stderr") {
+        return makeEvent("agent.stderr", { text: l.line });
+    }
+    const trimmed = l.line.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+        try {
+            const obj = JSON.parse(trimmed);
+            const type = String(obj.type ?? obj.event ?? "");
+            if (/tool/i.test(type) || obj.tool_use || obj.tool_name || obj.name) {
+                return makeEvent("tool.call", { raw: obj, tool: obj.tool_name ?? obj.name ?? obj.tool });
+            }
+            return makeEvent("agent.event", { raw: obj });
+        }
+        catch {
+            /* not JSON after all */
+        }
+    }
+    return makeEvent("agent.stdout", { text: l.line });
+}
+/** Split a raw command string into argv without invoking a shell. */
+export function tokenizeCommand(cmd) {
+    const out = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let m;
+    while ((m = re.exec(cmd)) !== null) {
+        out.push(m[1] ?? m[2] ?? m[3] ?? "");
+    }
+    return out;
+}
+export async function runExecute(plan, opts) {
+    const headroom = opts.headroom ?? new Headroom();
+    if (opts.target === "none") {
+        return runRaw(plan, opts, headroom);
+    }
+    return runAgent(plan, opts, headroom);
+}
+async function runAgent(plan, opts, headroom) {
+    const spec = agentSpec(opts.target);
+    if (!spec || !spec.headless || !opts.binPath) {
+        return {
+            status: "skipped",
+            target: opts.target,
+            command: null,
+            exitCode: null,
+            stdout: "",
+            stderr: `agent '${opts.target}' not runnable (no binary or headless template)`,
+            filesChanged: [],
+            errors: [`agent '${opts.target}' not runnable`],
+        };
+    }
+    const taskText = [plan.winner.summary, ...plan.winner.steps.map((s) => `- ${s}`)].join("\n");
+    const args = spec.headless.map((a) => (a === "{task}" ? taskText : a));
+    const command = [opts.binPath, ...args];
+    if (opts.dryRun) {
+        return dry(opts.target, command);
+    }
+    const outcome = await execStream(opts.binPath, args, {
+        cwd: opts.cwd,
+        timeoutMs: opts.timeoutMs ?? 120000,
+        signal: opts.signal,
+        onLine: (l) => opts.onEvent?.(normalizeLine(l)),
+    });
+    // Compress worker output through Headroom (this is where token savings land
+    // when the output is fed back to a model for verification/summarization).
+    const compressed = headroom.compress(outcome.stdout);
+    return {
+        status: outcome.code === 0 ? "success" : "failed",
+        target: opts.target,
+        command,
+        exitCode: outcome.code,
+        stdout: compressed.compressed,
+        stderr: outcome.stderr,
+        filesChanged: [],
+        errors: outcome.code === 0 ? [] : [outcome.stderr.slice(0, 500)],
+    };
+}
+async function runRaw(plan, opts, headroom) {
+    const commands = plan.winner.steps
+        .map((s) => extractShellCommand(s))
+        .filter((c) => c !== null);
+    if (commands.length === 0) {
+        return {
+            status: "skipped",
+            target: "none",
+            command: null,
+            exitCode: null,
+            stdout: "",
+            stderr: "no runnable commands found in plan steps (target=none)",
+            filesChanged: [],
+            errors: [],
+        };
+    }
+    if (opts.dryRun) {
+        return dry("none", commands.flatMap(tokenizeCommand));
+    }
+    let stdout = "";
+    let stderr = "";
+    let lastCode = 0;
+    for (const cmd of commands) {
+        const argv = tokenizeCommand(cmd);
+        if (argv.length === 0)
+            continue;
+        opts.onEvent?.(makeEvent("tool.call", { command: argv }));
+        const outcome = await execStream(argv[0], argv.slice(1), {
+            cwd: opts.cwd,
+            timeoutMs: opts.timeoutMs ?? 60000,
+            signal: opts.signal,
+            onLine: (l) => opts.onEvent?.(normalizeLine(l)),
+        });
+        stdout += headroom.compress(outcome.stdout).compressed + "\n";
+        stderr += outcome.stderr;
+        lastCode = outcome.code;
+        if (outcome.code !== 0)
+            break;
+    }
+    return {
+        status: lastCode === 0 ? "success" : "failed",
+        target: "none",
+        command: commands.flatMap(tokenizeCommand),
+        exitCode: lastCode,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        filesChanged: [],
+        errors: lastCode === 0 ? [] : [stderr.slice(0, 500)],
+    };
+}
+/** Steps prefixed with "$ " or "run: " are treated as literal shell commands. */
+function extractShellCommand(step) {
+    const t = step.trim();
+    const m = t.match(/^(?:\$\s+|run:\s*)(.+)$/i);
+    return m ? m[1].trim() : null;
+}
+function dry(target, command) {
+    return {
+        status: "skipped",
+        target,
+        command,
+        exitCode: null,
+        stdout: "[dry-run] would execute the above command",
+        stderr: "",
+        filesChanged: [],
+        errors: [],
+    };
+}

package/dist/phases/plan.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PLAN phase: branch -> filter -> commit (verifier-gated Best-of-N).
+ *
+ * Generates a small set of short candidate approaches via the master model,
+ * scores each with a cheap verifier, and early-exits as soon as one clearly
+ * passes. This is the efficient variant of test-time search: we do NOT execute
+ * every branch; only the winner gets the full execution budget.
+ */
+import type { Plan, ScoutFindings } from "../core/types.js";
+import type { ModelProvider } from "../core/model.js";
+export declare function runPlan(findings: ScoutFindings, provider: ModelProvider, model: string, skills?: string): Promise<Plan>;

package/dist/phases/plan.js

@@ -0,0 +1,118 @@
+/**
+ * PLAN phase: branch -> filter -> commit (verifier-gated Best-of-N).
+ *
+ * Generates a small set of short candidate approaches via the master model,
+ * scores each with a cheap verifier, and early-exits as soon as one clearly
+ * passes. This is the efficient variant of test-time search: we do NOT execute
+ * every branch; only the winner gets the full execution budget.
+ */
+const PLAN_SYSTEM = "MODE:plan You are a planning assistant. Return 2-3 short candidate approaches " +
+    "as a JSON array of objects with 'summary' and 'steps' fields. Be concise.";
+export async function runPlan(findings, provider, model, skills) {
+    const userPrompt = buildPlanPrompt(findings, skills);
+    const res = await provider.complete({
+        model,
+        tier: findings.complexity === "complex" ? "strong" : "cheap",
+        maxTokens: 512,
+        messages: [
+            { role: "system", content: PLAN_SYSTEM },
+            { role: "user", content: userPrompt },
+        ],
+    });
+    const raw = parseCandidates(res.text);
+    const evaluated = [];
+    let earlyExit = false;
+    for (const c of raw) {
+        const scored = scoreCandidate(c, findings);
+        evaluated.push(scored);
+        // Early exit: first clearly-passing candidate wins; stop spending tokens.
+        if (scored.pass && scored.score >= 0.7) {
+            earlyExit = true;
+            break;
+        }
+    }
+    const winner = pickWinner(evaluated);
+    return {
+        winner,
+        allEvaluated: evaluated,
+        candidatesGenerated: raw.length,
+        earlyExit,
+    };
+}
+function buildPlanPrompt(f, skills) {
+    return [
+        skills ? skills + "\n" : "",
+        `Task: ${f.task}`,
+        `Working dir: ${f.cwd}`,
+        `Complexity: ${f.complexity}`,
+        `Relevant files: ${f.files.slice(0, 20).join(", ") || "(none identified)"}`,
+        f.manifestSnippet ? `Manifest present: yes` : `Manifest present: no`,
+        `Constraints: keep the change set minimal; do not break existing tests.`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function parseCandidates(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed)) {
+            return parsed
+                .filter((c) => c && typeof c.summary === "string")
+                .map((c) => ({
+                summary: String(c.summary),
+                steps: Array.isArray(c.steps) ? c.steps.map(String) : [],
+            }));
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    // Fallback: single candidate from raw text.
+    return [{ summary: text.slice(0, 200).trim() || "proceed with the task", steps: [] }];
+}
+/**
+ * Cheap, grounded verifier. Rewards candidates that reference scoped files and
+ * concrete, testable steps; penalizes vague or empty plans. Grounding the
+ * score in checkable structure (not vibes) avoids the self-consistency bias trap.
+ */
+function scoreCandidate(c, f) {
+    let score = 0.5;
+    const reasons = [];
+    if (c.steps.length >= 2) {
+        score += 0.2;
+        reasons.push("has concrete steps");
+    }
+    else {
+        score -= 0.2;
+        reasons.push("too few steps");
+    }
+    const mentionsTest = /test|lint|verify|typecheck/i.test(c.steps.join(" ") + c.summary);
+    if (mentionsTest) {
+        score += 0.2;
+        reasons.push("includes a verification step");
+    }
+    const mentionsScopedFile = f.files.some((file) => (c.steps.join(" ") + c.summary).toLowerCase().includes(baseName(file).toLowerCase()));
+    if (mentionsScopedFile) {
+        score += 0.1;
+        reasons.push("references scoped file");
+    }
+    score = Math.max(0, Math.min(1, score));
+    return {
+        summary: c.summary,
+        steps: c.steps,
+        score,
+        pass: score >= 0.6,
+        reason: reasons.join("; "),
+    };
+}
+function pickWinner(cands) {
+    if (cands.length === 0) {
+        return { summary: "proceed with the task", steps: [], score: 0.5, pass: true, reason: "no candidates; default" };
+    }
+    return [...cands].sort((a, b) => b.score - a.score)[0];
+}
+function baseName(p) {
+    const parts = p.split(/[\\/]/);
+    const name = parts[parts.length - 1] ?? p;
+    return name.replace(/\.[^.]+$/, "");
+}

package/dist/phases/scout.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SCOUT phase: deterministic, read-only recon. Zero token cost by default.
+ *
+ * Explores the working directory (capped), reads README + manifest, gathers
+ * recent git history and uncommitted change stats, classifies complexity, and
+ * writes a structured findings object. Model-assisted deep research is an
+ * explicit opt-in layered on top; the base pass never calls a model.
+ */
+import type { ScoutFindings } from "../core/types.js";
+export declare function runScout(task: string, cwd: string, fileCap?: number): Promise<ScoutFindings>;

package/dist/phases/scout.js

@@ -0,0 +1,113 @@
+/**
+ * SCOUT phase: deterministic, read-only recon. Zero token cost by default.
+ *
+ * Explores the working directory (capped), reads README + manifest, gathers
+ * recent git history and uncommitted change stats, classifies complexity, and
+ * writes a structured findings object. Model-assisted deep research is an
+ * explicit opt-in layered on top; the base pass never calls a model.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { classifyComplexity } from "../core/complexity.js";
+import { execSafe } from "../core/exec.js";
+const IGNORE = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    ".cache",
+    "target",
+    ".next",
+    "coverage",
+]);
+const MANIFESTS = [
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "go.mod",
+    "pom.xml",
+    "build.gradle",
+    "pubspec.yaml",
+];
+function walk(root, cap) {
+    const found = [];
+    const stack = [root];
+    while (stack.length && found.length < cap) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (IGNORE.has(entry))
+                continue;
+            const full = join(dir, entry);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                stack.push(full);
+            }
+            else if (st.isFile()) {
+                found.push(relative(root, full));
+                if (found.length >= cap)
+                    break;
+            }
+        }
+    }
+    return found.sort();
+}
+function readIfExists(path, maxLen) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf8").slice(0, maxLen);
+    }
+    catch {
+        return null;
+    }
+}
+export async function runScout(task, cwd, fileCap = 400) {
+    const files = walk(cwd, fileCap);
+    const readmePath = ["README.md", "readme.md", "README"].map((f) => join(cwd, f)).find(existsSync);
+    const readme = readmePath ? readIfExists(readmePath, 2000) : null;
+    const manifestName = MANIFESTS.find((m) => existsSync(join(cwd, m)));
+    const manifestSnippet = manifestName ? readIfExists(join(cwd, manifestName), 1500) : null;
+    // Git context is best-effort; missing git is fine.
+    const log = await execSafe("git", ["log", "--oneline", "-n", "10"], { cwd, timeoutMs: 5000 });
+    const recentCommits = log.code === 0 ? log.stdout.split(/\r?\n/).filter(Boolean) : [];
+    const diff = await execSafe("git", ["diff", "--stat"], { cwd, timeoutMs: 5000 });
+    const uncommittedChanges = diff.code === 0 ? diff.stdout.trim() : "";
+    const relevant = files.filter((f) => task.toLowerCase().includes(baseName(f).toLowerCase()));
+    const { complexity, reasons } = classifyComplexity(task, relevant);
+    const notes = [];
+    if (!manifestName)
+        notes.push("no recognized build manifest found");
+    if (recentCommits.length === 0)
+        notes.push("no git history (or git unavailable)");
+    notes.push(`complexity=${complexity}: ${reasons.join("; ") || "no strong signals"}`);
+    return {
+        task,
+        cwd,
+        files: relevant.length ? relevant : files.slice(0, 50),
+        readme,
+        manifestSnippet,
+        recentCommits,
+        uncommittedChanges,
+        complexity,
+        notes,
+    };
+}
+function baseName(p) {
+    const parts = p.split(/[\\/]/);
+    const name = parts[parts.length - 1] ?? p;
+    return name.replace(/\.[^.]+$/, "");
+}

package/dist/phases/verify.d.ts

@@ -0,0 +1,22 @@
+/**
+ * VERIFY phase: never trust "the agent stopped talking = done".
+ *
+ * Order of preference:
+ *   1. Run the project's own test command (tests as ground truth).
+ *   2. If no test command exists, fall back to a cheap cross-model review of
+ *      the execution output (the master model judging pass/fail).
+ * A hard execution failure (non-zero exit) short-circuits to "not verified".
+ */
+import type { ExecuteResult, VerifyResult } from "../core/types.js";
+import type { ModelProvider } from "../core/model.js";
+export interface VerifyOptions {
+    cwd: string;
+    provider: ModelProvider;
+    model: string;
+    /** Skip running tests (e.g. for dry runs). */
+    skipTests?: boolean;
+    timeoutMs?: number;
+}
+/** Detect a test command from the project manifest. Returns argv or null. */
+export declare function detectTestCommand(cwd: string): string[] | null;
+export declare function runVerify(exec: ExecuteResult, opts: VerifyOptions): Promise<VerifyResult>;

package/dist/phases/verify.js

@@ -0,0 +1,81 @@
+/**
+ * VERIFY phase: never trust "the agent stopped talking = done".
+ *
+ * Order of preference:
+ *   1. Run the project's own test command (tests as ground truth).
+ *   2. If no test command exists, fall back to a cheap cross-model review of
+ *      the execution output (the master model judging pass/fail).
+ * A hard execution failure (non-zero exit) short-circuits to "not verified".
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSafe } from "../core/exec.js";
+const VERIFY_SYSTEM = "MODE:verify You are a strict verifier. Given execution output, return JSON " +
+    "{\"pass\": boolean, \"reason\": string}. Fail on any error or incomplete signal.";
+/** Detect a test command from the project manifest. Returns argv or null. */
+export function detectTestCommand(cwd) {
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if (pkg.scripts && typeof pkg.scripts.test === "string") {
+                const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+                return [npm, "test", "--silent"];
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (existsSync(join(cwd, "Cargo.toml")))
+        return ["cargo", "test"];
+    if (existsSync(join(cwd, "pyproject.toml")) || existsSync(join(cwd, "pytest.ini"))) {
+        return ["pytest", "-q"];
+    }
+    if (existsSync(join(cwd, "go.mod")))
+        return ["go", "test", "./..."];
+    return null;
+}
+export async function runVerify(exec, opts) {
+    if (exec.status === "failed") {
+        return { verified: false, method: "execution-status", details: "execution failed (non-zero exit)" };
+    }
+    if (exec.status === "skipped") {
+        return { verified: true, method: "skipped", details: "execution was skipped (dry run or no-op)" };
+    }
+    const testCmd = opts.skipTests ? null : detectTestCommand(opts.cwd);
+    if (testCmd) {
+        const outcome = await execSafe(testCmd[0], testCmd.slice(1), {
+            cwd: opts.cwd,
+            timeoutMs: opts.timeoutMs ?? 300000,
+        });
+        return {
+            verified: outcome.code === 0,
+            method: `tests:${testCmd.join(" ")}`,
+            details: outcome.code === 0
+                ? "test suite passed"
+                : `test suite failed (exit ${outcome.code}): ${outcome.stderr.slice(0, 300)}`,
+        };
+    }
+    // No tests -> cross-model review of the output as a fallback signal.
+    const res = await opts.provider.complete({
+        model: opts.model,
+        tier: "cheap",
+        maxTokens: 128,
+        messages: [
+            { role: "system", content: VERIFY_SYSTEM },
+            { role: "user", content: (exec.stdout + "\n" + exec.stderr).slice(0, 4000) },
+        ],
+    });
+    try {
+        const verdict = JSON.parse(res.text);
+        return {
+            verified: Boolean(verdict.pass),
+            method: "cross-model-review",
+            details: verdict.reason ?? "",
+        };
+    }
+    catch {
+        return { verified: true, method: "cross-model-review", details: "no failure signals parsed" };
+    }
+}

package/dist/server/daemon.d.ts

@@ -0,0 +1,50 @@
+/**
+ * MAQ daemon — a small, dependency-free HTTP + SSE server (Node built-in
+ * `http`) that exposes the orchestrator to the app track over one normalized
+ * seam. This is the concrete "master <-> app" contract from the product docs:
+ * the app never speaks any worker CLI's dialect, only MAQ's normalized events.
+ *
+ * SECURITY:
+ *  - Binds to 127.0.0.1 by default (loopback only). Binding to 0.0.0.0 is
+ *    allowed but logged loudly, because that exposes device control to the LAN.
+ *  - Every route except /health requires `Authorization: Bearer <token>`.
+ *    The token comes from MAQ_TOKEN, else config, else a freshly generated one
+ *    that is printed once on startup. There is no unauthenticated path to run
+ *    commands. Auth comparison is constant-time.
+ *  - CORS is opt-in (MAQ_CORS_ORIGIN); off by default.
+ *
+ * Endpoints (all JSON unless noted):
+ *   GET  /health                     -> liveness (no auth)
+ *   GET  /v1/agents                  -> detected worker CLIs
+ *   GET  /v1/connectivity            -> connectivity tier probe
+ *   GET  /v1/sessions                -> list session summaries
+ *   POST /v1/sessions                -> start a session {task,target?,cwd?,dryRun?}
+ *   GET  /v1/sessions/:id            -> one session (summary + events)
+ *   GET  /v1/sessions/:id/events     -> SSE stream (replay history, then live)
+ *   POST /v1/sessions/:id/message    -> deliver a message to a session {text}
+ */
+import { type Server } from "node:http";
+import { SessionRegistry } from "../core/session.js";
+export interface DaemonOptions {
+    host?: string;
+    port?: number;
+    token?: string;
+    version?: string;
+    corsOrigin?: string;
+    registry?: SessionRegistry;
+}
+export interface Daemon {
+    server: Server;
+    registry: SessionRegistry;
+    token: string;
+    host: string;
+    port: number;
+    listen(): Promise<{
+        host: string;
+        port: number;
+    }>;
+    close(): Promise<void>;
+}
+/** Generate a URL-safe token. */
+export declare function generateToken(): string;
+export declare function createDaemon(opts?: DaemonOptions): Daemon;