maqcli 0.2.0

package/dist/core/supervisor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Supervisor → multi-worker graph. A supervisor fans a job out to several
+ * worker sessions (parallel `assign`), waits for them all (`join`), and returns
+ * their condensed results — building on the SessionRegistry + subagent-style
+ * containment. Cross-provider by design: each worker task may pin its own
+ * target / provider / model / profile, so one swarm can mix Claude + Codex +
+ * raw workers. Unlike CAO this runs on MAQ's efficient, verified pipeline
+ * (each worker is a full Scout→Plan→Execute→Verify run).
+ */
+import type { SessionRegistry } from "./session.js";
+export interface WorkerTask {
+    task: string;
+    target?: string;
+    provider?: string;
+    model?: string;
+    profile?: string;
+    cwd?: string;
+    dryRun?: boolean;
+}
+export interface SwarmResult {
+    count: number;
+    workers: Array<{
+        id: string;
+        task: string;
+        status: string;
+        verified?: boolean;
+        target?: string;
+    }>;
+    allVerified: boolean;
+}
+/**
+ * Run tasks concurrently and join. Each is a full session; the supervisor sees
+ * only the summaries (containment), never raw worker transcripts.
+ */
+export declare function runSwarm(registry: SessionRegistry, tasks: WorkerTask[], opts?: {
+    maxConcurrency?: number;
+}): Promise<SwarmResult>;

package/dist/core/supervisor.js

@@ -0,0 +1,40 @@
+/**
+ * Supervisor → multi-worker graph. A supervisor fans a job out to several
+ * worker sessions (parallel `assign`), waits for them all (`join`), and returns
+ * their condensed results — building on the SessionRegistry + subagent-style
+ * containment. Cross-provider by design: each worker task may pin its own
+ * target / provider / model / profile, so one swarm can mix Claude + Codex +
+ * raw workers. Unlike CAO this runs on MAQ's efficient, verified pipeline
+ * (each worker is a full Scout→Plan→Execute→Verify run).
+ */
+/**
+ * Run tasks concurrently and join. Each is a full session; the supervisor sees
+ * only the summaries (containment), never raw worker transcripts.
+ */
+export async function runSwarm(registry, tasks, opts = {}) {
+    const limit = Math.max(1, opts.maxConcurrency ?? tasks.length);
+    const queue = [...tasks];
+    const done = [];
+    async function worker() {
+        for (;;) {
+            const t = queue.shift();
+            if (!t)
+                return;
+            const s = await registry.handoff(t.task, {
+                target: t.target,
+                provider: t.provider,
+                model: t.model,
+                profile: t.profile,
+                cwd: t.cwd,
+                dryRun: t.dryRun,
+            });
+            done.push(registry.summarize(s));
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, () => worker()));
+    return {
+        count: done.length,
+        workers: done.map((w) => ({ id: w.id, task: w.task, status: w.status, verified: w.verified, target: w.target })),
+        allVerified: done.every((w) => w.verified !== false),
+    };
+}

package/dist/core/tools.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tool registry — a small, SAFE set of tools the master can offer a model
+ * (tool-use) or run itself. Safety first: file tools are sandboxed to the
+ * working directory (path-traversal guarded), outputs are size-capped, and
+ * network access is OFF unless explicitly enabled (MAQ_ALLOW_NET=1).
+ *
+ * Each tool exposes a JSON-schema-ish descriptor so it can be advertised to an
+ * OpenAI/Anthropic-style tool-use API, plus a `run` that executes locally.
+ * Prefer these native tools over MCP servers where both exist — they add no
+ * per-tool listing overhead to the model's context.
+ */
+import type { Headroom } from "./headroom.js";
+export interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, {
+        type: string;
+        description: string;
+        required?: boolean;
+    }>;
+}
+export interface Tool extends ToolSchema {
+    run(args: Record<string, unknown>): Promise<unknown> | unknown;
+}
+export interface ToolContext {
+    cwd: string;
+    headroom?: Headroom;
+    allowNet?: boolean;
+}
+export declare function createToolRegistry(ctx: ToolContext): ToolRegistry;
+export declare class ToolRegistry {
+    private tools;
+    readonly netEnabled: boolean;
+    constructor(tools: Tool[], netEnabled: boolean);
+    /** Advertise schemas (for model tool-use, or `maq tools`). */
+    schemas(): ToolSchema[];
+    names(): string[];
+    run(name: string, args?: Record<string, unknown>): Promise<unknown>;
+}

package/dist/core/tools.js

@@ -0,0 +1,159 @@
+/**
+ * Tool registry — a small, SAFE set of tools the master can offer a model
+ * (tool-use) or run itself. Safety first: file tools are sandboxed to the
+ * working directory (path-traversal guarded), outputs are size-capped, and
+ * network access is OFF unless explicitly enabled (MAQ_ALLOW_NET=1).
+ *
+ * Each tool exposes a JSON-schema-ish descriptor so it can be advertised to an
+ * OpenAI/Anthropic-style tool-use API, plus a `run` that executes locally.
+ * Prefer these native tools over MCP servers where both exist — they add no
+ * per-tool listing overhead to the model's context.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { resolve, join, relative, isAbsolute } from "node:path";
+const MAX_OUT = 64 * 1024;
+/** Resolve a user path safely inside cwd; throws on traversal escape. */
+function safePath(cwd, p) {
+    const base = resolve(cwd);
+    const target = isAbsolute(p) ? resolve(p) : resolve(base, p);
+    const rel = relative(base, target);
+    if (rel !== "" && (rel.startsWith("..") || isAbsolute(rel))) {
+        throw new Error(`path escapes working directory: ${p}`);
+    }
+    return target;
+}
+export function createToolRegistry(ctx) {
+    const allowNet = ctx.allowNet ?? process.env.MAQ_ALLOW_NET === "1";
+    const tools = [
+        {
+            name: "read_file",
+            description: "Read a UTF-8 text file within the working directory.",
+            parameters: { path: { type: "string", description: "relative path", required: true } },
+            run: (args) => {
+                const p = safePath(ctx.cwd, String(args.path ?? ""));
+                return readFileSync(p, "utf8").slice(0, MAX_OUT);
+            },
+        },
+        {
+            name: "list_dir",
+            description: "List entries of a directory within the working directory.",
+            parameters: { path: { type: "string", description: "relative path (default '.')" } },
+            run: (args) => {
+                const p = safePath(ctx.cwd, String(args.path ?? "."));
+                return readdirSync(p).map((name) => {
+                    const full = join(p, name);
+                    let kind = "other";
+                    try {
+                        kind = statSync(full).isDirectory() ? "dir" : "file";
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    return { name, kind };
+                });
+            },
+        },
+        {
+            name: "grep_text",
+            description: "Search files under a directory for a substring (case-insensitive).",
+            parameters: {
+                query: { type: "string", description: "substring to find", required: true },
+                path: { type: "string", description: "relative dir (default '.')" },
+            },
+            run: (args) => {
+                const q = String(args.query ?? "").toLowerCase();
+                if (!q)
+                    return [];
+                const root = safePath(ctx.cwd, String(args.path ?? "."));
+                const hits = [];
+                const stack = [root];
+                const IGNORE = new Set(["node_modules", ".git", "dist", "build", "target"]);
+                while (stack.length && hits.length < 200) {
+                    const dir = stack.pop();
+                    let entries = [];
+                    try {
+                        entries = readdirSync(dir);
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const e of entries) {
+                        if (IGNORE.has(e))
+                            continue;
+                        const full = join(dir, e);
+                        let st;
+                        try {
+                            st = statSync(full);
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (st.isDirectory())
+                            stack.push(full);
+                        else if (st.isFile() && st.size < 512 * 1024) {
+                            let content = "";
+                            try {
+                                content = readFileSync(full, "utf8");
+                            }
+                            catch {
+                                continue;
+                            }
+                            const lines = content.split(/\r?\n/);
+                            for (let i = 0; i < lines.length && hits.length < 200; i++) {
+                                if (lines[i].toLowerCase().includes(q)) {
+                                    hits.push({ file: relative(ctx.cwd, full), line: i + 1, text: lines[i].slice(0, 300) });
+                                }
+                            }
+                        }
+                    }
+                }
+                return hits;
+            },
+        },
+    ];
+    if (ctx.headroom) {
+        tools.push({
+            name: "headroom_retrieve",
+            description: "Retrieve the original, uncompressed content for a Headroom reference (hr_...).",
+            parameters: { ref: { type: "string", description: "headroom reference id", required: true } },
+            run: (args) => ctx.headroom.retrieve(String(args.ref ?? "")) ?? null,
+        });
+    }
+    if (allowNet) {
+        tools.push({
+            name: "http_get",
+            description: "HTTP GET a URL and return up to 64KB of text (network access is enabled).",
+            parameters: { url: { type: "string", description: "http(s) URL", required: true } },
+            run: async (args) => {
+                const url = String(args.url ?? "");
+                if (!/^https?:\/\//i.test(url))
+                    throw new Error("only http(s) URLs allowed");
+                const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
+                const text = await res.text();
+                return { status: res.status, body: text.slice(0, MAX_OUT) };
+            },
+        });
+    }
+    return new ToolRegistry(tools, allowNet);
+}
+export class ToolRegistry {
+    tools;
+    netEnabled;
+    constructor(tools, netEnabled) {
+        this.tools = tools;
+        this.netEnabled = netEnabled;
+    }
+    /** Advertise schemas (for model tool-use, or `maq tools`). */
+    schemas() {
+        return this.tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters }));
+    }
+    names() {
+        return this.tools.map((t) => t.name);
+    }
+    async run(name, args = {}) {
+        const tool = this.tools.find((t) => t.name === name);
+        if (!tool)
+            throw new Error(`no such tool: ${name}`);
+        return tool.run(args);
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared types and the normalized event schema for maqcli.
+ *
+ * Every worker CLI (Claude Code, Codex, Gemini, raw bash, ...) has its output
+ * normalized into these event shapes so the UI / consumers never need
+ * per-vendor logic.
+ */
+export type EventType = "task.started" | "phase.started" | "phase.done" | "agent.event" | "agent.stdout" | "agent.stderr" | "tool.call" | "task.paused" | "task.resumed" | "task.cancelled" | "task.done" | "task.error";
+export interface MaqEvent {
+    type: EventType;
+    /** ISO timestamp */
+    ts: string;
+    /** Free-form structured payload. */
+    data: Record<string, unknown>;
+}
+export declare function makeEvent(type: EventType, data?: Record<string, unknown>): MaqEvent;
+/** A detected worker CLI on the host. */
+export interface DetectedAgent {
+    name: string;
+    /** Absolute path to the resolved binary, if found. */
+    binPath: string | null;
+    installed: boolean;
+    /** Whether the tool's auth/config dir suggests it is authenticated. */
+    authenticated: boolean;
+    /** Whether the tool exposes a stable machine-readable (JSON) event stream. */
+    stableJsonStream: boolean;
+    /** Headless invocation template; {task} is substituted at run time. */
+    headless: string[] | null;
+}
+export type Complexity = "trivial" | "standard" | "complex";
+export interface ScoutFindings {
+    task: string;
+    cwd: string;
+    files: string[];
+    readme: string | null;
+    manifestSnippet: string | null;
+    recentCommits: string[];
+    uncommittedChanges: string;
+    complexity: Complexity;
+    notes: string[];
+}
+export interface PlanCandidate {
+    summary: string;
+    steps: string[];
+    score: number;
+    pass: boolean;
+    reason: string;
+}
+export interface Plan {
+    winner: PlanCandidate;
+    allEvaluated: PlanCandidate[];
+    candidatesGenerated: number;
+    earlyExit: boolean;
+}
+export interface ExecuteResult {
+    status: "success" | "failed" | "skipped";
+    target: string;
+    command: string[] | null;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    filesChanged: string[];
+    errors: string[];
+}
+export interface VerifyResult {
+    verified: boolean;
+    method: string;
+    details: string;
+}
+export interface PipelineResult {
+    task: string;
+    scout: ScoutFindings;
+    plan: Plan | null;
+    execute: ExecuteResult;
+    verify: VerifyResult;
+    events: MaqEvent[];
+    /** Token/cost accounting for the master's own calls. */
+    cost?: {
+        calls: number;
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        usd: number;
+    };
+    /** Run id when audit artifacts were written. */
+    runId?: string;
+}

package/dist/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared types and the normalized event schema for maqcli.
+ *
+ * Every worker CLI (Claude Code, Codex, Gemini, raw bash, ...) has its output
+ * normalized into these event shapes so the UI / consumers never need
+ * per-vendor logic.
+ */
+export function makeEvent(type, data = {}) {
+    return { type, ts: new Date().toISOString(), data };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * maqcli entry point.
+ *
+ * MAQ master orchestrator: a token-efficient, agent-agnostic supervisor that
+ * sits on top of any worker CLI (AI or not) via a Scout -> Plan -> Execute ->
+ * Verify pipeline. Zero runtime dependencies; uses only Node built-ins.
+ *
+ * Commands: detect | config | scout | plan | run | verify | help | version
+ */
+export {};