maqcli 0.2.0

package/dist/core/router.d.ts

@@ -0,0 +1,33 @@
+/**
+ * RouteLLM-style routing: pick a model tier for a sub-task, then resolve that
+ * tier to a concrete (provider, model) from config.
+ *
+ * The classifier here is deterministic and rule-based (task complexity ->
+ * tier), which is the cheap, zero-token version of RouteLLM's trained router.
+ * A trained classifier can slot in behind `tierFor` later without changing any
+ * caller. Routing cheap work to a cheap model and escalating only hard work is
+ * the documented lever for large cost reduction while holding quality.
+ */
+import type { Complexity } from "./types.js";
+import type { MaqConfig } from "./config-store.js";
+import type { ModelProvider } from "./model.js";
+export type Tier = "cheap" | "strong";
+export interface Route {
+    tier: Tier;
+    provider: ModelProvider;
+    providerName: string;
+    model: string;
+}
+/** Map task complexity to a model tier. */
+export declare function tierFor(complexity: Complexity): Tier;
+/**
+ * Resolve a tier to a concrete provider+model using config. Both tiers use the
+ * same configured `provider`; only the model name differs (cheap vs strong).
+ * Falls back to `masterModel` when a tier model is unset.
+ */
+export declare class Router {
+    private cfg;
+    constructor(cfg: MaqConfig);
+    route(tier: Tier): Route;
+    routeByComplexity(complexity: Complexity): Route;
+}

package/dist/core/router.js

@@ -0,0 +1,40 @@
+/**
+ * RouteLLM-style routing: pick a model tier for a sub-task, then resolve that
+ * tier to a concrete (provider, model) from config.
+ *
+ * The classifier here is deterministic and rule-based (task complexity ->
+ * tier), which is the cheap, zero-token version of RouteLLM's trained router.
+ * A trained classifier can slot in behind `tierFor` later without changing any
+ * caller. Routing cheap work to a cheap model and escalating only hard work is
+ * the documented lever for large cost reduction while holding quality.
+ */
+import { getProvider } from "./model.js";
+/** Map task complexity to a model tier. */
+export function tierFor(complexity) {
+    return complexity === "complex" ? "strong" : "cheap";
+}
+/**
+ * Resolve a tier to a concrete provider+model using config. Both tiers use the
+ * same configured `provider`; only the model name differs (cheap vs strong).
+ * Falls back to `masterModel` when a tier model is unset.
+ */
+export class Router {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    route(tier) {
+        const model = tier === "strong"
+            ? this.cfg.strongModel || this.cfg.masterModel
+            : this.cfg.cheapModel || this.cfg.masterModel;
+        return {
+            tier,
+            provider: getProvider(this.cfg.provider),
+            providerName: this.cfg.provider,
+            model,
+        };
+    }
+    routeByComplexity(complexity) {
+        return this.route(tierFor(complexity));
+    }
+}

package/dist/core/sandbox.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module sandbox
+ * @description Permission tier / safety boundary system for maqcli.
+ *
+ * Enforces a three-level permission model:
+ *   Tier 1 (Scout)   — read-only access
+ *   Tier 2 (Execute) — scoped writes within allowed paths
+ *   Tier 3 (Destructive) — all writes allowed, destructive ops flagged for confirmation
+ *
+ * Zero npm dependencies — Node built-ins only.
+ */
+export type PermissionTier = 1 | 2 | 3;
+export interface SandboxPolicy {
+    tier: PermissionTier;
+    allowedPaths: string[];
+    denyCommands: string[];
+    readOnlyCommands: string[];
+}
+export interface SandboxCheck {
+    allowed: boolean;
+    tier: PermissionTier;
+    reason: string;
+}
+/** Sentinel exit code returned when a sandbox violation terminates a phase. */
+export declare const EXIT_SANDBOX = 4;
+/**
+ * Create a {@link SandboxPolicy} anchored at `cwd`.
+ *
+ * @param cwd  - Working directory that becomes the default allowed-path root.
+ * @param tier - Permission tier (defaults to **2** — scoped-write).
+ */
+export declare function createPolicy(cwd: string, tier?: PermissionTier): SandboxPolicy;
+/**
+ * Determine whether a **read** of `filePath` is permitted under `policy`.
+ *
+ * Reads are allowed at every tier — the check exists so callers get a
+ * uniform {@link SandboxCheck} shape.
+ */
+export declare function checkRead(filePath: string, policy: SandboxPolicy): SandboxCheck;
+/**
+ * Determine whether a **write** to `filePath` is permitted under `policy`.
+ *
+ * - Tier 1 — always denied (read-only).
+ * - Tier 2 — allowed only inside `allowedPaths` and outside system dirs.
+ * - Tier 3 — allowed everywhere, but destructive flag raised.
+ */
+export declare function checkWrite(filePath: string, policy: SandboxPolicy): SandboxCheck;
+/**
+ * Determine whether `command` is permitted under `policy`.
+ *
+ * Evaluation order:
+ * 1. Deny-list — unconditionally blocked regardless of tier.
+ * 2. Tier 1 — only read-only commands allowed.
+ * 3. Tier 2 — all non-denied commands allowed.
+ * 4. Tier 3 — all non-denied commands allowed, destructive ones flagged.
+ */
+export declare function checkCommand(command: string | string[], policy: SandboxPolicy): SandboxCheck;
+/**
+ * Returns `true` when `command` matches a known destructive pattern.
+ *
+ * Destructive patterns include `rm -rf`, `git push --force`,
+ * `git reset --hard`, `DROP TABLE`, `DROP DATABASE`, `format`,
+ * `shutdown`, and `reboot`.
+ */
+export declare function isDestructive(command: string | string[]): boolean;
+/**
+ * Map a pipeline phase name to its appropriate {@link PermissionTier}.
+ *
+ * | Phase     | Tier |
+ * |-----------|------|
+ * | scout     | 1    |
+ * | plan      | 1    |
+ * | execute   | 2    |
+ * | verify    | 1    |
+ *
+ * Unknown phases default to tier **1** (safest).
+ */
+export declare function tierForPhase(phase: string): PermissionTier;

package/dist/core/sandbox.js

@@ -0,0 +1,268 @@
+/**
+ * @module sandbox
+ * @description Permission tier / safety boundary system for maqcli.
+ *
+ * Enforces a three-level permission model:
+ *   Tier 1 (Scout)   — read-only access
+ *   Tier 2 (Execute) — scoped writes within allowed paths
+ *   Tier 3 (Destructive) — all writes allowed, destructive ops flagged for confirmation
+ *
+ * Zero npm dependencies — Node built-ins only.
+ */
+import { resolve, normalize } from "node:path";
+import { platform } from "node:os";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Sentinel exit code returned when a sandbox violation terminates a phase. */
+export const EXIT_SANDBOX = 4;
+const DENY_COMMANDS = [
+    "rm -rf /",
+    "mkfs",
+    "dd if=",
+    ":(){",
+    "chmod -R 777 /",
+    "eval",
+];
+const READ_ONLY_COMMANDS = [
+    "cat",
+    "head",
+    "tail",
+    "less",
+    "ls",
+    "dir",
+    "find",
+    "grep",
+    "rg",
+    "tree",
+    "wc",
+    "file",
+    "stat",
+    "git log",
+    "git diff",
+    "git status",
+    "git show",
+    "git blame",
+    "type",
+    "Get-Content",
+    "Select-String",
+];
+const DESTRUCTIVE_PATTERNS = [
+    "rm -rf",
+    "git push --force",
+    "git reset --hard",
+    "DROP TABLE",
+    "DROP DATABASE",
+    "format",
+    "shutdown",
+    "reboot",
+];
+const SYSTEM_PATHS_POSIX = ["/usr", "/etc", "/bin"];
+const SYSTEM_PATHS_WIN = ["C:\\Windows", "C:\\Program Files"];
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Normalise a command input (string or argv array) into a single string
+ * for pattern matching.
+ */
+function normalizeCommand(command) {
+    return Array.isArray(command) ? command.join(" ") : command;
+}
+/**
+ * Returns the set of system paths that must never be written to,
+ * chosen based on the current platform.
+ */
+function systemPaths() {
+    return platform() === "win32" ? SYSTEM_PATHS_WIN : SYSTEM_PATHS_POSIX;
+}
+/**
+ * Check whether `filePath` falls within at least one of the `allowed` roots.
+ */
+function isWithinAllowed(filePath, allowed) {
+    const resolved = normalize(resolve(filePath));
+    return allowed.some((root) => {
+        const normalizedRoot = normalize(resolve(root));
+        return (resolved === normalizedRoot || resolved.startsWith(normalizedRoot + (platform() === "win32" ? "\\" : "/")));
+    });
+}
+/**
+ * Check whether `filePath` falls within a protected system directory.
+ */
+function isSystemPath(filePath) {
+    const resolved = normalize(resolve(filePath)).toLowerCase();
+    return systemPaths().some((sp) => {
+        const normalizedSp = normalize(sp).toLowerCase();
+        return (resolved === normalizedSp || resolved.startsWith(normalizedSp + (platform() === "win32" ? "\\" : "/")));
+    });
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Create a {@link SandboxPolicy} anchored at `cwd`.
+ *
+ * @param cwd  - Working directory that becomes the default allowed-path root.
+ * @param tier - Permission tier (defaults to **2** — scoped-write).
+ */
+export function createPolicy(cwd, tier = 2) {
+    return {
+        tier,
+        allowedPaths: [resolve(cwd)],
+        denyCommands: [...DENY_COMMANDS],
+        readOnlyCommands: [...READ_ONLY_COMMANDS],
+    };
+}
+/**
+ * Determine whether a **read** of `filePath` is permitted under `policy`.
+ *
+ * Reads are allowed at every tier — the check exists so callers get a
+ * uniform {@link SandboxCheck} shape.
+ */
+export function checkRead(filePath, policy) {
+    // Reads are universally permitted across all tiers.
+    return {
+        allowed: true,
+        tier: policy.tier,
+        reason: `Read access granted at tier ${policy.tier}`,
+    };
+}
+/**
+ * Determine whether a **write** to `filePath` is permitted under `policy`.
+ *
+ * - Tier 1 — always denied (read-only).
+ * - Tier 2 — allowed only inside `allowedPaths` and outside system dirs.
+ * - Tier 3 — allowed everywhere, but destructive flag raised.
+ */
+export function checkWrite(filePath, policy) {
+    const resolved = normalize(resolve(filePath));
+    // Tier 1: read-only — no writes ever.
+    if (policy.tier === 1) {
+        return {
+            allowed: false,
+            tier: policy.tier,
+            reason: `Write denied: tier 1 (Scout) is read-only — ${resolved}`,
+        };
+    }
+    // Tier 2: scoped writes — within allowed paths, outside system dirs.
+    if (policy.tier === 2) {
+        if (isSystemPath(resolved)) {
+            return {
+                allowed: false,
+                tier: policy.tier,
+                reason: `Write denied: system path is protected — ${resolved}`,
+            };
+        }
+        if (!isWithinAllowed(resolved, policy.allowedPaths)) {
+            return {
+                allowed: false,
+                tier: policy.tier,
+                reason: `Write denied: path outside allowed roots — ${resolved}`,
+            };
+        }
+        return {
+            allowed: true,
+            tier: policy.tier,
+            reason: `Write allowed within scoped path — ${resolved}`,
+        };
+    }
+    // Tier 3: destructive — allow but flag.
+    return {
+        allowed: true,
+        tier: policy.tier,
+        reason: `Write allowed at tier 3 (destructive) — confirm before proceeding — ${resolved}`,
+    };
+}
+/**
+ * Determine whether `command` is permitted under `policy`.
+ *
+ * Evaluation order:
+ * 1. Deny-list — unconditionally blocked regardless of tier.
+ * 2. Tier 1 — only read-only commands allowed.
+ * 3. Tier 2 — all non-denied commands allowed.
+ * 4. Tier 3 — all non-denied commands allowed, destructive ones flagged.
+ */
+export function checkCommand(command, policy) {
+    const cmd = normalizeCommand(command);
+    // 1. Deny-list — always blocked.
+    for (const denied of policy.denyCommands) {
+        if (cmd.includes(denied)) {
+            return {
+                allowed: false,
+                tier: policy.tier,
+                reason: `Command denied: matches deny-list entry "${denied}"`,
+            };
+        }
+    }
+    // 2. Tier 1 — read-only commands only.
+    if (policy.tier === 1) {
+        const isReadOnly = policy.readOnlyCommands.some((ro) => {
+            const trimmed = cmd.trimStart();
+            return trimmed === ro || trimmed.startsWith(ro + " ");
+        });
+        if (!isReadOnly) {
+            return {
+                allowed: false,
+                tier: policy.tier,
+                reason: `Command denied: tier 1 (Scout) permits only read-only commands`,
+            };
+        }
+        return {
+            allowed: true,
+            tier: policy.tier,
+            reason: `Command allowed: recognised read-only command at tier 1`,
+        };
+    }
+    // 3. Tier 2 — scoped-write, non-denied commands pass.
+    if (policy.tier === 2) {
+        return {
+            allowed: true,
+            tier: policy.tier,
+            reason: `Command allowed at tier 2 (Execute)`,
+        };
+    }
+    // 4. Tier 3 — allow, flag destructive.
+    if (isDestructive(cmd)) {
+        return {
+            allowed: true,
+            tier: policy.tier,
+            reason: `Command allowed at tier 3 (destructive) — confirm before proceeding`,
+        };
+    }
+    return {
+        allowed: true,
+        tier: policy.tier,
+        reason: `Command allowed at tier 3`,
+    };
+}
+/**
+ * Returns `true` when `command` matches a known destructive pattern.
+ *
+ * Destructive patterns include `rm -rf`, `git push --force`,
+ * `git reset --hard`, `DROP TABLE`, `DROP DATABASE`, `format`,
+ * `shutdown`, and `reboot`.
+ */
+export function isDestructive(command) {
+    const cmd = normalizeCommand(command).toLowerCase();
+    return DESTRUCTIVE_PATTERNS.some((p) => cmd.includes(p.toLowerCase()));
+}
+/**
+ * Map a pipeline phase name to its appropriate {@link PermissionTier}.
+ *
+ * | Phase     | Tier |
+ * |-----------|------|
+ * | scout     | 1    |
+ * | plan      | 1    |
+ * | execute   | 2    |
+ * | verify    | 1    |
+ *
+ * Unknown phases default to tier **1** (safest).
+ */
+export function tierForPhase(phase) {
+    switch (phase.toLowerCase()) {
+        case "scout":
+            return 1;
+        case "plan":
+            return 1;
+        case "execute":
+            return 2;
+        case "verify":
+            return 1;
+        default:
+            return 1;
+    }
+}

package/dist/core/session.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Session registry + multi-agent management.
+ *
+ * Each session is one orchestrated task run (Scout->Plan->Execute->Verify)
+ * against one worker target. The registry runs many concurrently, keeps each
+ * session's normalized event history for replay, and exposes a live subscribe
+ * hook that the daemon turns into an SSE stream for the app.
+ *
+ * Coordination vocabulary borrowed from CAO (the vocabulary, not the tmux +
+ * Bedrock runtime):
+ *   - assign(task)        -> async, fire-and-forget; returns the session id now
+ *   - handoff(task)       -> sync, wait-for-completion; resolves with the result
+ *   - sendMessage(id, m)  -> deliver a message into a session's inbox
+ * Worker context stays isolated per session; the supervisor sees condensed
+ * events, never a raw shared transcript.
+ */
+import type { MaqEvent, PipelineResult } from "./types.js";
+export type SessionStatus = "running" | "paused" | "cancelled" | "done" | "error";
+export interface InboxMessage {
+    ts: string;
+    from: string;
+    text: string;
+}
+export interface Session {
+    id: string;
+    task: string;
+    status: SessionStatus;
+    target?: string;
+    cwd: string;
+    createdAt: string;
+    updatedAt: string;
+    events: MaqEvent[];
+    inbox: InboxMessage[];
+    result?: PipelineResult;
+    error?: string;
+}
+export interface SessionSummary {
+    id: string;
+    task: string;
+    status: SessionStatus;
+    target?: string;
+    cwd: string;
+    createdAt: string;
+    updatedAt: string;
+    verified?: boolean;
+    eventCount: number;
+}
+export interface CreateOptions {
+    cwd?: string;
+    target?: string;
+    dryRun?: boolean;
+    timeoutMs?: number;
+    /** Named agent profile — resolves target/provider/model. */
+    profile?: string;
+    /** Provider override (else config). */
+    provider?: string;
+    /** Model override (else config tier models). */
+    model?: string;
+}
+type Listener = (e: MaqEvent) => void;
+/** Thrown through the pipeline checkpoint when a session is cancelled. */
+export declare class CancelError extends Error {
+    constructor();
+}
+export declare class SessionRegistry {
+    private sessions;
+    private controls;
+    private bus;
+    private maxSessions;
+    private maxEventsPerSession;
+    constructor(maxSessions?: number, maxEventsPerSession?: number);
+    /** Fire-and-forget: start a session and return its id immediately. */
+    assign(task: string, opts?: CreateOptions): Session;
+    /** Synchronous handoff: start a session and await its completion. */
+    handoff(task: string, opts?: CreateOptions): Promise<Session>;
+    /** Deliver a message into a session's inbox (records a normalized event). */
+    sendMessage(id: string, text: string, from?: string): boolean;
+    get(id: string): Session | undefined;
+    list(): SessionSummary[];
+    summarize(s: Session): SessionSummary;
+    /** Subscribe to live events for a session. Returns an unsubscribe fn. */
+    subscribe(id: string, listener: Listener): () => void;
+    /** Subscribe to ALL sessions' events (for plugins/webhooks). */
+    onAny(listener: (p: {
+        sessionId: string;
+        event: MaqEvent;
+    }) => void): void;
+    offAny(listener: (p: {
+        sessionId: string;
+        event: MaqEvent;
+    }) => void): void;
+    /** Remove finished sessions (housekeeping). */
+    prune(): number;
+    private spawn;
+    /** Pause a running session at its next phase boundary. */
+    pause(id: string): boolean;
+    /** Resume a paused session. */
+    resume(id: string): boolean;
+    /** Cancel a session; kills in-flight worker processes and aborts the run. */
+    cancel(id: string): boolean;
+    private push;
+    private waitFor;
+    private evictOldestDone;
+}
+export {};