maqcli 0.2.0

package/dist/server/daemon.js

@@ -0,0 +1,377 @@
+/**
+ * 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 { createServer as httpCreateServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { SessionRegistry } from "../core/session.js";
+import { detectAgents, authAdvisory } from "../core/registry.js";
+import { probeConnectivity } from "../core/probe.js";
+import { execSafe } from "../core/exec.js";
+import { commandCatalog, maqCommands } from "../core/command-catalog.js";
+import { InteractiveRegistry } from "../core/interactive-registry.js";
+/** Generate a URL-safe token. */
+export function generateToken() {
+    return randomBytes(24).toString("base64url");
+}
+function constantTimeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+export function createDaemon(opts = {}) {
+    const host = opts.host ?? process.env.MAQ_HOST ?? "127.0.0.1";
+    const port = opts.port ?? Number(process.env.MAQ_PORT ?? 7717);
+    const token = opts.token ?? process.env.MAQ_TOKEN ?? generateToken();
+    const version = opts.version ?? "0.2.0";
+    const corsOrigin = opts.corsOrigin ?? process.env.MAQ_CORS_ORIGIN;
+    const registry = opts.registry ?? new SessionRegistry();
+    const interactive = new InteractiveRegistry();
+    const startedAt = Date.now();
+    // Track live SSE responses so shutdown can end them deterministically.
+    // Without this, server.close() blocks forever on the long-lived event
+    // streams (they only emit a keep-alive ping every 15s and never end on their
+    // own), so SIGINT/SIGTERM would hang the daemon.
+    const sseClients = new Set();
+    const server = httpCreateServer((req, res) => handle(req, res).catch((err) => {
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }));
+    function setCors(res) {
+        if (!corsOrigin)
+            return;
+        res.setHeader("access-control-allow-origin", corsOrigin);
+        res.setHeader("access-control-allow-headers", "authorization, content-type");
+        res.setHeader("access-control-allow-methods", "GET, POST, OPTIONS");
+    }
+    function authorized(req) {
+        const header = req.headers["authorization"];
+        if (!header || Array.isArray(header))
+            return false;
+        const m = /^Bearer\s+(.+)$/i.exec(header);
+        if (!m)
+            return false;
+        return constantTimeEqual(m[1], token);
+    }
+    async function handle(req, res) {
+        setCors(res);
+        const url = new URL(req.url ?? "/", `http://${host}:${port}`);
+        const path = url.pathname;
+        const method = req.method ?? "GET";
+        if (method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Liveness needs no auth.
+        if (path === "/health" && method === "GET") {
+            sendJson(res, 200, {
+                ok: true,
+                version,
+                sessions: registry.list().length,
+                startedAt: new Date(startedAt).toISOString(),
+                uptimeMs: Date.now() - startedAt,
+            });
+            return;
+        }
+        if (!authorized(req)) {
+            sendJson(res, 401, { error: "unauthorized: send Authorization: Bearer <token>" });
+            return;
+        }
+        if (path === "/v1/agents" && method === "GET") {
+            const agents = detectAgents();
+            sendJson(res, 200, { agents, advisory: authAdvisory(agents) });
+            return;
+        }
+        if (path === "/v1/connectivity" && method === "GET") {
+            sendJson(res, 200, await probeConnectivity());
+            return;
+        }
+        if (path === "/v1/commands" && method === "GET") {
+            sendJson(res, 200, commandCatalog());
+            return;
+        }
+        // Whitelisted CLI runner — powers the app's Master (terminal) edition.
+        // Only known `maq` subcommands run; never arbitrary shell.
+        if (path === "/v1/exec" && method === "POST") {
+            const body = await readJson(req);
+            const argv = Array.isArray(body.argv) ? body.argv.map(String) : [];
+            const cmd = argv[0];
+            const allowed = new Set([...maqCommands.map((c) => c.name), "help", "version", "-h", "--help"]);
+            if (!cmd || !allowed.has(cmd)) {
+                sendJson(res, 400, { error: `command not allowed: ${cmd ?? "(empty)"}. Allowed: ${[...allowed].join(", ")}` });
+                return;
+            }
+            const entry = join(dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+            const outcome = await execSafe(process.execPath, [entry, ...argv], {
+                cwd: typeof body.cwd === "string" ? body.cwd : process.cwd(),
+                timeoutMs: 120000,
+            });
+            sendJson(res, 200, { argv, code: outcome.code, stdout: outcome.stdout, stderr: outcome.stderr });
+            return;
+        }
+        if (path === "/v1/interactive" && method === "GET") {
+            sendJson(res, 200, { terminals: interactive.list() });
+            return;
+        }
+        if (path === "/v1/interactive" && method === "POST") {
+            const body = await readJson(req);
+            const target = typeof body.target === "string" ? body.target : "auto";
+            try {
+                const info = interactive.start(target, {
+                    cwd: typeof body.cwd === "string" ? body.cwd : undefined,
+                    task: typeof body.task === "string" ? body.task : undefined,
+                });
+                sendJson(res, 201, info);
+            }
+            catch (e) {
+                sendJson(res, 400, { error: e.message });
+            }
+            return;
+        }
+        const interMatch = /^\/v1\/interactive\/([^/]+)(\/events|\/input|\/close)?$/.exec(path);
+        if (interMatch) {
+            const id = decodeURIComponent(interMatch[1]);
+            const sub = interMatch[2];
+            const entry = interactive.get(id);
+            if (!entry) {
+                sendJson(res, 404, { error: "no such terminal" });
+                return;
+            }
+            if (!sub && method === "GET") {
+                sendJson(res, 200, { ...entry.info, events: entry.events });
+                return;
+            }
+            if (sub === "/events" && method === "GET") {
+                streamInteractive(res, id);
+                return;
+            }
+            if (sub === "/input" && method === "POST") {
+                const body = await readJson(req);
+                const text = typeof body.text === "string" ? body.text : "";
+                sendJson(res, 202, { delivered: interactive.input(id, text) });
+                return;
+            }
+            if (sub === "/close" && method === "POST") {
+                sendJson(res, 202, { closed: interactive.close(id) });
+                return;
+            }
+        }
+        if (path === "/v1/sessions" && method === "GET") {
+            sendJson(res, 200, { sessions: registry.list() });
+            return;
+        }
+        if (path === "/v1/sessions" && method === "POST") {
+            const body = await readJson(req);
+            const task = typeof body.task === "string" ? body.task.trim() : "";
+            if (!task) {
+                sendJson(res, 400, { error: "missing 'task'" });
+                return;
+            }
+            const s = registry.assign(task, {
+                target: typeof body.target === "string" ? body.target : undefined,
+                cwd: typeof body.cwd === "string" ? body.cwd : undefined,
+                dryRun: Boolean(body.dryRun),
+                timeoutMs: typeof body.timeoutMs === "number" ? body.timeoutMs : undefined,
+            });
+            sendJson(res, 201, registry.summarize(s));
+            return;
+        }
+        const sessionMatch = /^\/v1\/sessions\/([^/]+)(\/events|\/message|\/control)?$/.exec(path);
+        if (sessionMatch) {
+            const id = decodeURIComponent(sessionMatch[1]);
+            const sub = sessionMatch[2];
+            const session = registry.get(id);
+            if (!session) {
+                sendJson(res, 404, { error: "no such session" });
+                return;
+            }
+            if (!sub && method === "GET") {
+                sendJson(res, 200, { ...registry.summarize(session), events: session.events, error: session.error });
+                return;
+            }
+            if (sub === "/events" && method === "GET") {
+                streamEvents(res, session.id);
+                return;
+            }
+            if (sub === "/message" && method === "POST") {
+                const body = await readJson(req);
+                const text = typeof body.text === "string" ? body.text : "";
+                if (!text) {
+                    sendJson(res, 400, { error: "missing 'text'" });
+                    return;
+                }
+                registry.sendMessage(id, text, typeof body.from === "string" ? body.from : "user");
+                sendJson(res, 202, { delivered: true });
+                return;
+            }
+            if (sub === "/control" && method === "POST") {
+                const body = await readJson(req);
+                const action = String(body.action ?? "");
+                let ok = false;
+                if (action === "pause")
+                    ok = registry.pause(id);
+                else if (action === "resume")
+                    ok = registry.resume(id);
+                else if (action === "cancel")
+                    ok = registry.cancel(id);
+                else {
+                    sendJson(res, 400, { error: "action must be pause|resume|cancel" });
+                    return;
+                }
+                sendJson(res, ok ? 202 : 409, { action, ok, status: registry.get(id)?.status });
+                return;
+            }
+        }
+        sendJson(res, 404, { error: "not found" });
+    }
+    function streamEvents(res, id) {
+        res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+        });
+        sseClients.add(res);
+        const session = registry.get(id);
+        // Replay history so a late subscriber is not missing context.
+        for (const e of session?.events ?? [])
+            writeSse(res, e);
+        if (session && session.status !== "running") {
+            writeSse(res, { type: "stream.end", ts: new Date().toISOString(), data: { status: session.status } });
+            sseClients.delete(res);
+            res.end();
+            return;
+        }
+        const unsub = registry.subscribe(id, (e) => {
+            writeSse(res, e);
+            if (e.type === "task.done" || e.type === "task.error" || e.type === "task.cancelled") {
+                writeSse(res, { type: "stream.end", ts: new Date().toISOString(), data: { status: "closed" } });
+                cleanup();
+                res.end();
+            }
+        });
+        const keepAlive = setInterval(() => res.write(": ping\n\n"), 15000);
+        const cleanup = () => {
+            clearInterval(keepAlive);
+            unsub();
+            sseClients.delete(res);
+        };
+        res.on("close", cleanup);
+    }
+    function streamInteractive(res, id) {
+        res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+        });
+        sseClients.add(res);
+        const entry = interactive.get(id);
+        for (const e of entry?.events ?? [])
+            writeSse(res, e);
+        const unsub = interactive.subscribe(id, (e) => {
+            writeSse(res, e);
+            const status = e.data.status;
+            if (status === "exited") {
+                writeSse(res, { type: "stream.end", ts: new Date().toISOString(), data: { status: "exited" } });
+                cleanup();
+                res.end();
+            }
+        });
+        const keepAlive = setInterval(() => res.write(": ping\n\n"), 15000);
+        const cleanup = () => {
+            clearInterval(keepAlive);
+            unsub();
+            sseClients.delete(res);
+        };
+        res.on("close", cleanup);
+    }
+    return {
+        server,
+        registry,
+        token,
+        host,
+        port,
+        listen() {
+            return new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(port, host, () => {
+                    const addr = server.address();
+                    const boundPort = typeof addr === "object" && addr ? addr.port : port;
+                    resolve({ host, port: boundPort });
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve) => {
+                // Deterministically end long-lived SSE streams first, otherwise
+                // server.close() waits on them indefinitely.
+                for (const client of sseClients) {
+                    try {
+                        writeSse(client, { type: "stream.end", ts: new Date().toISOString(), data: { status: "shutdown" } });
+                        client.end();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+                sseClients.clear();
+                server.close(() => resolve());
+                // Safety net: drop any lingering keep-alive/active sockets so the
+                // process can exit promptly (Node >= 18.2).
+                server.closeAllConnections?.();
+            });
+        },
+    };
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(payload);
+}
+function writeSse(res, event) {
+    res.write(`event: ${event.type}\n`);
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    const MAX = 1024 * 1024;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX)
+            throw new Error("request body too large");
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}

package/dist/server/relay-bridge.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Relay bridge — lets the daemon be reached through the outbound-only relay
+ * (Tier 2) with NO inbound ports. The daemon dials OUT to the relay as the
+ * `agent` for a deviceId; the phone app connects as the `controller`. Controller
+ * requests (tunnelled as `{t:"msg", data:{op:...}}`) are executed against the
+ * local SessionRegistry and answers/events are streamed back the same way.
+ *
+ * App ⇄ relay protocol (data payloads):
+ *   → {op:"sessions", reqId}                     ← {kind:"sessions", sessions, reqId}
+ *   → {op:"agents", reqId}                        ← {kind:"agents", agents, advisory, reqId}
+ *   → {op:"connectivity", reqId}                  ← {kind:"connectivity", connectivity, reqId}
+ *   → {op:"create", task,target,cwd,dryRun,reqId} ← {kind:"created", session, reqId}
+ *   → {op:"subscribe", id}                        ← {kind:"event", id, event}  (stream)
+ *   → {op:"control", id, action}                  ← {kind:"ok"|"error", ...}
+ *   → {op:"message", id, text}                    ← {kind:"ok"}
+ *
+ * Uses Node's global WebSocket client (Node >= 22) — zero dependencies.
+ */
+import type { SessionRegistry } from "../core/session.js";
+export interface RelayBridgeOptions {
+    url: string;
+    deviceId: string;
+    token?: string;
+    registry: SessionRegistry;
+    /** Reconnect backoff base in ms. */
+    reconnectMs?: number;
+    log?: (msg: string) => void;
+}
+export declare class RelayBridge {
+    private opts;
+    private ws;
+    private closed;
+    private subscribed;
+    private unsubs;
+    constructor(opts: RelayBridgeOptions);
+    start(): void;
+    stop(): void;
+    private connect;
+    private handleOp;
+    private subscribe;
+    private reply;
+    private send;
+    private log;
+}

package/dist/server/relay-bridge.js

@@ -0,0 +1,175 @@
+/**
+ * Relay bridge — lets the daemon be reached through the outbound-only relay
+ * (Tier 2) with NO inbound ports. The daemon dials OUT to the relay as the
+ * `agent` for a deviceId; the phone app connects as the `controller`. Controller
+ * requests (tunnelled as `{t:"msg", data:{op:...}}`) are executed against the
+ * local SessionRegistry and answers/events are streamed back the same way.
+ *
+ * App ⇄ relay protocol (data payloads):
+ *   → {op:"sessions", reqId}                     ← {kind:"sessions", sessions, reqId}
+ *   → {op:"agents", reqId}                        ← {kind:"agents", agents, advisory, reqId}
+ *   → {op:"connectivity", reqId}                  ← {kind:"connectivity", connectivity, reqId}
+ *   → {op:"create", task,target,cwd,dryRun,reqId} ← {kind:"created", session, reqId}
+ *   → {op:"subscribe", id}                        ← {kind:"event", id, event}  (stream)
+ *   → {op:"control", id, action}                  ← {kind:"ok"|"error", ...}
+ *   → {op:"message", id, text}                    ← {kind:"ok"}
+ *
+ * Uses Node's global WebSocket client (Node >= 22) — zero dependencies.
+ */
+import { detectAgents, authAdvisory } from "../core/registry.js";
+import { probeConnectivity } from "../core/probe.js";
+export class RelayBridge {
+    opts;
+    ws = null;
+    closed = false;
+    subscribed = new Set();
+    unsubs = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    start() {
+        this.connect();
+    }
+    stop() {
+        this.closed = true;
+        for (const u of this.unsubs)
+            u();
+        this.unsubs = [];
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    connect() {
+        if (this.closed)
+            return;
+        const WsCtor = globalThis.WebSocket;
+        if (!WsCtor) {
+            this.log("relay bridge requires a global WebSocket (Node >= 22); skipping");
+            return;
+        }
+        const ws = new WsCtor(this.opts.url);
+        this.ws = ws;
+        ws.addEventListener("open", () => {
+            this.log(`relay bridge connected: ${this.opts.url} (device ${this.opts.deviceId})`);
+            this.send({ t: "hello", role: "agent", deviceId: this.opts.deviceId, token: this.opts.token ?? "" });
+        });
+        ws.addEventListener("message", (ev) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            if (msg.t === "msg" && msg.data && typeof msg.data === "object") {
+                this.handleOp(msg.data);
+            }
+        });
+        ws.addEventListener("close", () => {
+            if (this.closed)
+                return;
+            const delay = this.opts.reconnectMs ?? 2000;
+            this.log(`relay bridge disconnected; reconnecting in ${delay}ms`);
+            setTimeout(() => this.connect(), delay);
+        });
+        ws.addEventListener("error", () => {
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        });
+    }
+    handleOp(op) {
+        const reqId = op.reqId;
+        const reg = this.opts.registry;
+        switch (op.op) {
+            case "sessions":
+                this.reply({ kind: "sessions", sessions: reg.list(), reqId });
+                break;
+            case "agents": {
+                const agents = detectAgents();
+                this.reply({ kind: "agents", agents, advisory: authAdvisory(agents), reqId });
+                break;
+            }
+            case "connectivity":
+                probeConnectivity()
+                    .then((connectivity) => this.reply({ kind: "connectivity", connectivity, reqId }))
+                    .catch((e) => this.reply({ kind: "error", message: e.message, reqId }));
+                break;
+            case "create": {
+                const task = typeof op.task === "string" ? op.task.trim() : "";
+                if (!task) {
+                    this.reply({ kind: "error", message: "missing task", reqId });
+                    return;
+                }
+                const s = reg.assign(task, {
+                    target: typeof op.target === "string" ? op.target : undefined,
+                    cwd: typeof op.cwd === "string" ? op.cwd : undefined,
+                    dryRun: Boolean(op.dryRun),
+                });
+                this.reply({ kind: "created", session: reg.summarize(s), reqId });
+                this.subscribe(s.id);
+                break;
+            }
+            case "subscribe":
+                if (typeof op.id === "string")
+                    this.subscribe(op.id);
+                break;
+            case "control": {
+                const id = String(op.id ?? "");
+                const action = String(op.action ?? "");
+                let ok = false;
+                if (action === "pause")
+                    ok = reg.pause(id);
+                else if (action === "resume")
+                    ok = reg.resume(id);
+                else if (action === "cancel")
+                    ok = reg.cancel(id);
+                this.reply({ kind: ok ? "ok" : "error", action, id, reqId });
+                break;
+            }
+            case "message":
+                if (typeof op.id === "string" && typeof op.text === "string") {
+                    reg.sendMessage(op.id, op.text);
+                    this.reply({ kind: "ok", reqId });
+                }
+                break;
+            default:
+                this.reply({ kind: "error", message: `unknown op: ${String(op.op)}`, reqId });
+        }
+    }
+    subscribe(id) {
+        const session = this.opts.registry.get(id);
+        if (!session) {
+            this.reply({ kind: "error", message: "no such session" });
+            return;
+        }
+        // Replay history so a late controller sees full context.
+        for (const e of session.events)
+            this.reply({ kind: "event", id, event: e });
+        if (this.subscribed.has(id))
+            return;
+        this.subscribed.add(id);
+        const unsub = this.opts.registry.subscribe(id, (e) => this.reply({ kind: "event", id, event: e }));
+        this.unsubs.push(unsub);
+    }
+    reply(data) {
+        this.send({ t: "msg", data });
+    }
+    send(obj) {
+        try {
+            this.ws?.send(JSON.stringify(obj));
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    log(msg) {
+        this.opts.log?.(msg);
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "maqcli",
+  "version": "0.2.0",
+  "description": "MAQ master orchestrator — a token-efficient, agent-agnostic supervisor CLI that sits on top of any worker CLI (AI or not) via a Scout -> Plan -> Execute -> Verify pipeline.",
+  "type": "module",
+  "bin": {
+    "maqcli": "dist/index.js",
+    "maq": "dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "cli",
+    "orchestrator",
+    "ai-agents",
+    "token-efficiency",
+    "scout-plan-execute-verify",
+    "supervisor"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}