maqcli 0.2.0

package/dist/core/help-topics.js

@@ -0,0 +1,294 @@
+/**
+ * @module help-topics
+ *
+ * Conceptual help system for `maq help <topic>`.
+ * Provides detailed reference content for core maq concepts
+ * including the pipeline, permissions, routing, board, skills,
+ * providers, safety, and audit subsystems.
+ *
+ * Zero npm dependencies. ESM module.
+ */
+// ── Topic Definitions ───────────────────────────────────────────────
+const WRAP_WIDTH = 78;
+const topics = [
+    {
+        name: "pipeline",
+        title: "The Scout → Plan → Execute → Verify Pipeline",
+        content: [
+            "Every maq task flows through a four-stage pipeline that separates",
+            "reasoning from action.",
+            "",
+            "1. Scout — A lightweight model scans the repository, gathers context,",
+            "   and produces a structured summary of the codebase topology, relevant",
+            "   files, and potential risks. Scout never writes files.",
+            "",
+            "2. Plan — A mid-tier model receives the scout report and the user's",
+            "   intent, then emits an ordered list of concrete steps with expected",
+            "   outcomes. Each step is tagged with the permission tier it requires.",
+            "",
+            "3. Execute — A capable model (or the same planner) carries out each",
+            "   step sequentially. File writes, shell commands, and network calls",
+            "   happen here, gated by the permission tier granted at launch.",
+            "",
+            "4. Verify — An independent model reviews the diff, runs any declared",
+            "   checks (tests, linters, type-checks), and produces a pass/fail",
+            "   verdict. Failed verification triggers an automatic retry loop",
+            "   (up to the configured retry limit).",
+            "",
+            "The pipeline is recorded end-to-end in the audit log, so every",
+            "decision and mutation can be replayed or inspected after the fact.",
+        ].join("\n"),
+    },
+    {
+        name: "permissions",
+        title: "Permission Tiers & Safety Boundary",
+        content: [
+            "Maq enforces a three-tier permission model that limits what each",
+            "pipeline stage is allowed to do.",
+            "",
+            "Tier 1 — Read-only. The agent can read files, list directories,",
+            "and query environment variables. No writes, no shell commands,",
+            "no network calls beyond API routing. Scout always runs at Tier 1.",
+            "",
+            "Tier 2 — Write-local. The agent may create and modify files inside",
+            "the project directory, run allow-listed shell commands (e.g. npm",
+            "test, cargo build), and access localhost services. It cannot touch",
+            "files outside the project root or make arbitrary network requests.",
+            "",
+            "Tier 3 — Full access. The agent may execute arbitrary commands,",
+            "access the network, and modify files anywhere the invoking user",
+            "has OS-level permission. Tier 3 requires explicit --tier=3 flag",
+            "and records every action in a tamper-evident audit log.",
+            "",
+            "The tier is set at invocation time and cannot be escalated during",
+            "a run. Plan steps tagged above the granted tier are skipped with",
+            "a warning, ensuring the user always controls the blast radius.",
+        ].join("\n"),
+    },
+    {
+        name: "routing",
+        title: "Hybrid API Routing",
+        content: [
+            "Maq uses a hybrid routing strategy to balance cost, latency, and",
+            "capability across pipeline stages.",
+            "",
+            "Broker routing (Scout & Plan) — These stages send requests through",
+            "the maq broker, which selects the cheapest model that meets the",
+            "stage's capability floor. The broker tracks per-model cost rates,",
+            "context-window sizes, and historical accuracy to make routing",
+            "decisions. Users can pin a specific model with --model to override.",
+            "",
+            "Native routing (Execute) — Execution-stage calls go directly to",
+            "the provider's API endpoint, bypassing the broker. This avoids",
+            "double-hop latency for the most token-intensive stage and lets",
+            "the agent stream tool-call results in real time.",
+            "",
+            "Provider fallback — If the primary provider returns a 5xx or a",
+            "rate-limit error, the broker automatically retries with the next",
+            "cheapest compatible model. The fallback chain is configurable via",
+            "`maq config set routing.fallback`.",
+            "",
+            "All routing decisions are logged with the model used, token counts,",
+            "and wall-clock latency so you can audit cost after every run.",
+        ].join("\n"),
+    },
+    {
+        name: "board",
+        title: "The Shared Board (.maq/board.jsonl)",
+        content: [
+            "The board is a local append-only JSONL file at .maq/board.jsonl",
+            "that acts as a stigmergy layer between agents and pipeline stages.",
+            "",
+            "Each line is a JSON object with a timestamp, author (stage name",
+            "or agent ID), type tag, and a freeform payload. Common types:",
+            "",
+            "  context   — Scout writes discovered files, symbols, dependencies.",
+            "  step      — Plan writes each planned step with expected outcome.",
+            "  result    — Execute writes the actual outcome of each step.",
+            "  verdict   — Verify writes pass/fail plus evidence.",
+            "  note      — Any stage can leave advisory notes for later stages.",
+            "",
+            "Because the board is append-only, no stage can erase another's",
+            "observations. Downstream stages read the full board to build",
+            "situational awareness without direct inter-process communication.",
+            "",
+            "Use `maq board show` to pretty-print the current board, or",
+            "`maq board tail` to stream new entries in real time. The board",
+            "is reset at the start of each new session unless --resume is set.",
+            "",
+            "The board format is intentionally simple so external tools can",
+            "parse it with any JSON library or even plain grep.",
+        ].join("\n"),
+    },
+    {
+        name: "skills",
+        title: "Skills & Rules Layer",
+        content: [
+            "Skills are reusable instruction sets that teach maq how to handle",
+            "specific tasks — for example, writing tests in a particular style",
+            "or deploying to a specific cloud provider.",
+            "",
+            "A skill is a Markdown file stored under .maq/skills/ with YAML",
+            "front-matter declaring its name, description, and required tier.",
+            "During planning, the planner searches the skills directory for",
+            "skills whose description matches the current intent and injects",
+            "their instructions into the plan context.",
+            "",
+            "Skills are tier-aware: a Tier 1 skill can only contain read",
+            "operations, while a Tier 3 skill may include deployment commands.",
+            "If the current run's tier is lower than the skill's requirement,",
+            "the skill is silently skipped.",
+            "",
+            "Auto-learning: when a verify stage passes, maq can optionally",
+            "distill the successful plan into a new skill and write it to",
+            ".maq/skills/ so future runs benefit automatically. This behavior",
+            "is controlled by `maq config set skills.autoLearn true`.",
+            "",
+            "Rules are simpler: plain text constraints (e.g. \"never delete",
+            "migration files\") stored in .maq/rules.md and prepended to every",
+            "plan context unconditionally.",
+        ].join("\n"),
+    },
+    {
+        name: "providers",
+        title: "Model Providers & Cost Tiers",
+        content: [
+            "Maq supports multiple LLM providers and organizes them into cost",
+            "tiers to help you control spend.",
+            "",
+            "Built-in providers: OpenAI, Anthropic, Google (Gemini), Mistral,",
+            "Groq, and any OpenAI-compatible endpoint via a custom base URL.",
+            "Each provider is configured with an API key stored in your OS",
+            "keychain or in .maq/config.json (encrypted at rest).",
+            "",
+            "Cost tiers:",
+            "  Tier A — Economy models (e.g. gpt-4.1-mini, gemini-2.5-flash).",
+            "           Used by default for Scout and quick Plan tasks.",
+            "  Tier B — Standard models (e.g. gpt-4.1, claude-sonnet-4).",
+            "           Default for Execute when the plan is non-trivial.",
+            "  Tier C — Frontier models (e.g. o3, claude-opus-4).",
+            "           Opt-in only via --model or per-stage config.",
+            "",
+            "The broker picks the cheapest model in the allowed tier that",
+            "satisfies the stage's context-window and tool-use requirements.",
+            "Use `maq models list` to see available models, their tiers, and",
+            "current per-token pricing. Use `maq models cheapest` to find the",
+            "cheapest model that can handle a given context size.",
+        ].join("\n"),
+    },
+    {
+        name: "safety",
+        title: "Safety & Trust Model",
+        content: [
+            "Maq is designed so that the user is always in control and no",
+            "single model failure can cause irreversible damage.",
+            "",
+            "Defense in depth:",
+            "  1. Tier gating prevents Execute from exceeding the permission",
+            "     level the user granted at invocation.",
+            "  2. Plan review — in interactive mode the plan is displayed for",
+            "     approval before execution begins. In CI mode the plan is",
+            "     logged and a --yes flag is required to skip approval.",
+            "  3. Verify independence — the verification model is deliberately",
+            "     a different model (or temperature) than the executor to avoid",
+            "     self-confirming bias.",
+            "  4. Rollback snapshots — before any write, maq snapshots the",
+            "     target file. If verification fails and retries are exhausted,",
+            "     all changes are rolled back automatically.",
+            "",
+            "Network sandboxing: at Tier 1 and Tier 2, outbound network access",
+            "is blocked except for LLM API calls and localhost. Tier 3 lifts",
+            "this restriction but logs every outbound connection.",
+            "",
+            "All safety events (tier violations, rollbacks, blocked commands)",
+            "are written to the audit log with full context for post-hoc review.",
+        ].join("\n"),
+    },
+    {
+        name: "audit",
+        title: "Audit Logs & Replay",
+        content: [
+            "Every maq session produces a structured audit log under",
+            ".maq/sessions/<id>/audit.jsonl. The log captures every decision",
+            "and side-effect so you can understand exactly what happened.",
+            "",
+            "Each audit entry contains:",
+            "  • timestamp (ISO-8601 with milliseconds)",
+            "  • stage (scout, plan, execute, verify)",
+            "  • action type (file_read, file_write, shell_exec, api_call, ...)",
+            "  • input arguments and output summary",
+            "  • model used, token counts, and latency",
+            "  • permission tier at the time of the action",
+            "",
+            "Replay: use `maq audit <session-id>` to pretty-print the log or",
+            "pipe it to jq for ad-hoc queries. The --replay flag re-executes",
+            "the logged plan against the current codebase, which is useful for",
+            "regression testing your skills and rules.",
+            "",
+            "Retention: audit logs are kept for 30 days by default. Change the",
+            "retention window with `maq config set audit.retentionDays <n>`.",
+            "",
+            "Compliance: for regulated environments, enable tamper-evident mode",
+            "with `maq config set audit.signed true`, which appends an HMAC to",
+            "each entry using a key stored in your OS keychain.",
+        ].join("\n"),
+    },
+];
+// ── Public API ──────────────────────────────────────────────────────
+/** Returns a shallow copy of all available help topics. */
+export function listTopics() {
+    return [...topics];
+}
+/** Looks up a topic by name (case-insensitive). Returns `null` if not found. */
+export function getTopic(name) {
+    const lower = name.toLowerCase();
+    return topics.find((t) => t.name === lower) ?? null;
+}
+/**
+ * Renders a topic as a formatted string suitable for terminal output.
+ * The title is displayed with an underline, followed by word-wrapped
+ * paragraphs of the content body.
+ */
+export function renderTopic(topic) {
+    const underline = "─".repeat(topic.title.length);
+    const wrapped = wordWrap(topic.content, WRAP_WIDTH);
+    return `${topic.title}\n${underline}\n\n${wrapped}\n`;
+}
+// ── Internals ───────────────────────────────────────────────────────
+/**
+ * Word-wraps text to `width` columns, preserving existing blank lines
+ * as paragraph breaks and respecting leading whitespace for indented lines.
+ */
+function wordWrap(text, width) {
+    const lines = text.split("\n");
+    const out = [];
+    for (const line of lines) {
+        if (line.trim() === "") {
+            out.push("");
+            continue;
+        }
+        // Detect leading whitespace to preserve indentation.
+        const indent = line.match(/^(\s*)/)?.[1] ?? "";
+        const effectiveWidth = width - indent.length;
+        if (effectiveWidth <= 20) {
+            // Line is too indented to wrap meaningfully; keep as-is.
+            out.push(line);
+            continue;
+        }
+        const words = line.trimStart().split(/\s+/);
+        let current = indent;
+        for (const word of words) {
+            if (current.length > indent.length && current.length + 1 + word.length > width) {
+                out.push(current);
+                current = indent + word;
+            }
+            else {
+                current += (current.length > indent.length ? " " : "") + word;
+            }
+        }
+        if (current.length > 0) {
+            out.push(current);
+        }
+    }
+    return out.join("\n");
+}

package/dist/core/init-wizard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module init-wizard
+ * @description Interactive onboarding wizard for `maq init`.
+ *
+ * Walks the user through first-time setup:
+ *   1. Welcome banner
+ *   2. Agent auto-detection
+ *   3. LLM provider selection
+ *   4. Permission-default selection
+ *   5. Skill scaffolding
+ *   6. `.maq/` directory creation
+ *   7. Config persistence
+ *   8. Summary & next-step tips
+ *
+ * Zero npm dependencies — uses only Node built-ins.
+ */
+/**
+ * Runs the interactive `maq init` wizard.
+ *
+ * @param cwd - The working directory (project root) in which `.maq/` will be created.
+ * @returns An object indicating whether configuration was written and a human-readable summary.
+ */
+export declare function runInit(cwd: string): Promise<{
+    configured: boolean;
+    summary: string[];
+}>;

package/dist/core/init-wizard.js

@@ -0,0 +1,168 @@
+/**
+ * @module init-wizard
+ * @description Interactive onboarding wizard for `maq init`.
+ *
+ * Walks the user through first-time setup:
+ *   1. Welcome banner
+ *   2. Agent auto-detection
+ *   3. LLM provider selection
+ *   4. Permission-default selection
+ *   5. Skill scaffolding
+ *   6. `.maq/` directory creation
+ *   7. Config persistence
+ *   8. Summary & next-step tips
+ *
+ * Zero npm dependencies — uses only Node built-ins.
+ */
+import { createInterface } from "node:readline";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig, saveConfig, configPath } from "./config-store.js";
+import { initSkills } from "./skills.js";
+import { detectAgents } from "./registry.js";
+/* ------------------------------------------------------------------ */
+/*  Constants                                                          */
+/* ------------------------------------------------------------------ */
+const PROVIDERS = [
+    { key: "1", label: "heuristic (offline, $0)" },
+    { key: "2", label: "openai" },
+    { key: "3", label: "anthropic" },
+    { key: "4", label: "ollama" },
+    { key: "5", label: "groq" },
+    { key: "0", label: "skip" },
+];
+const PROVIDER_MAP = {
+    "1": "heuristic",
+    "2": "openai",
+    "3": "anthropic",
+    "4": "ollama",
+    "5": "groq",
+};
+const PERMISSIONS = [
+    { key: "1", label: "strict (read-only preview first)" },
+    { key: "2", label: "standard (scoped writes)" },
+    { key: "0", label: "skip" },
+];
+const PERMISSION_MAP = {
+    "1": "strict",
+    "2": "standard",
+};
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+/**
+ * Prompts the user with a question and resolves with their trimmed answer.
+ */
+function ask(rl, question) {
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            resolve(answer.trim());
+        });
+    });
+}
+/* ------------------------------------------------------------------ */
+/*  Public API                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Runs the interactive `maq init` wizard.
+ *
+ * @param cwd - The working directory (project root) in which `.maq/` will be created.
+ * @returns An object indicating whether configuration was written and a human-readable summary.
+ */
+export async function runInit(cwd) {
+    const summary = [];
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        return await _runWizard(rl, cwd, summary);
+    }
+    finally {
+        rl.close();
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Internal wizard flow                                               */
+/* ------------------------------------------------------------------ */
+async function _runWizard(rl, cwd, summary) {
+    /* ── 1. Welcome ─────────────────────────────────────────────── */
+    console.log("");
+    console.log("  maq init — first-time setup");
+    console.log("  ─────────────────────────────");
+    console.log("");
+    /* ── 2. Auto-detect agents ──────────────────────────────────── */
+    const agents = await detectAgents();
+    if (agents.length > 0) {
+        console.log("  Detected agents:");
+        for (const agent of agents) {
+            console.log(`    • ${agent}`);
+        }
+        summary.push(`Detected ${agents.length} agent(s): ${agents.join(", ")}`);
+    }
+    else {
+        console.log("  No agents detected.");
+        summary.push("No agents detected");
+    }
+    console.log("");
+    /* ── 3. Provider selection ──────────────────────────────────── */
+    console.log("  Choose a default LLM provider:");
+    for (const p of PROVIDERS) {
+        console.log(`    [${p.key}] ${p.label}`);
+    }
+    const providerChoice = await ask(rl, "\n  Provider [1]: ");
+    const providerKey = providerChoice === "" ? "1" : providerChoice;
+    const provider = PROVIDER_MAP[providerKey] ?? null;
+    if (provider) {
+        summary.push(`Provider: ${provider}`);
+    }
+    else {
+        summary.push("Provider: skipped");
+    }
+    console.log("");
+    /* ── 4. Permission default ──────────────────────────────────── */
+    console.log("  Choose a default permission level:");
+    for (const p of PERMISSIONS) {
+        console.log(`    [${p.key}] ${p.label}`);
+    }
+    const permChoice = await ask(rl, "\n  Permission [1]: ");
+    const permKey = permChoice === "" ? "1" : permChoice;
+    const permission = PERMISSION_MAP[permKey] ?? null;
+    if (permission) {
+        summary.push(`Permissions: ${permission}`);
+    }
+    else {
+        summary.push("Permissions: skipped");
+    }
+    console.log("");
+    /* ── 5. Scaffold skills ─────────────────────────────────────── */
+    await initSkills(cwd);
+    summary.push("Skills scaffolded");
+    /* ── 6. Create .maq/ dir ────────────────────────────────────── */
+    const maqDir = join(cwd, ".maq");
+    await mkdir(maqDir, { recursive: true });
+    summary.push(`Directory: ${maqDir}`);
+    /* ── 7. Save config ─────────────────────────────────────────── */
+    const config = loadConfig();
+    if (provider) {
+        config.provider = provider;
+    }
+    if (permission) {
+        config.defaultPermission = permission;
+    }
+    saveConfig(config);
+    summary.push(`Config saved → ${configPath()}`);
+    /* ── 8. Summary & tips ──────────────────────────────────────── */
+    console.log("  ✔ Setup complete!");
+    console.log("");
+    console.log("  Summary:");
+    for (const line of summary) {
+        console.log(`    • ${line}`);
+    }
+    console.log("");
+    console.log("  Next steps:");
+    console.log('    Try: maq doctor');
+    console.log('    Try: maq run "<task>"');
+    console.log("");
+    return { configured: true, summary };
+}

package/dist/core/interactive-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Interactive registry — long-lived interactive agent terminals the app drives.
+ *
+ * The Master edition is multi-panel: panel 1 is the Headroom master (maq
+ * commands via /v1/exec); the other panels are AI worker CLIs the user starts
+ * themselves (for when an agent isn't the auto-detected default, or to run
+ * several at once). Each is an InteractiveWorker (piped stdin steering + live
+ * status) whose events the daemon streams over SSE and whose stdin the app
+ * writes — the same connection method for every agent terminal.
+ */
+import type { MaqEvent } from "./types.js";
+import { InteractiveWorker, type WorkerStatus } from "./interactive.js";
+export interface InteractiveInfo {
+    id: string;
+    target: string;
+    status: WorkerStatus;
+    createdAt: string;
+    /** Whether the resolved agent looked authenticated at start time. */
+    authenticated?: boolean;
+    /** Advisory if the agent is installed but not authenticated (may prompt login). */
+    warning?: string;
+}
+interface Entry {
+    worker: InteractiveWorker;
+    info: InteractiveInfo;
+    events: MaqEvent[];
+}
+export declare class InteractiveRegistry {
+    private entries;
+    private bus;
+    constructor();
+    /** Start an AI CLI as an interactive agent terminal. Throws if unresolved. */
+    start(target: string, opts?: {
+        cwd?: string;
+        task?: string;
+    }): InteractiveInfo;
+    /** Lower-level spawn (also used by tests with an arbitrary bin). */
+    spawnRaw(bin: string, args: string[], meta: {
+        target: string;
+        cwd?: string;
+    }): InteractiveInfo;
+    get(id: string): Entry | undefined;
+    list(): InteractiveInfo[];
+    /** Steer: write a line to the agent's stdin. */
+    input(id: string, text: string): boolean;
+    close(id: string): boolean;
+    subscribe(id: string, listener: (e: MaqEvent) => void): () => void;
+    private push;
+}
+export {};

package/dist/core/interactive-registry.js

@@ -0,0 +1,86 @@
+/**
+ * Interactive registry — long-lived interactive agent terminals the app drives.
+ *
+ * The Master edition is multi-panel: panel 1 is the Headroom master (maq
+ * commands via /v1/exec); the other panels are AI worker CLIs the user starts
+ * themselves (for when an agent isn't the auto-detected default, or to run
+ * several at once). Each is an InteractiveWorker (piped stdin steering + live
+ * status) whose events the daemon streams over SSE and whose stdin the app
+ * writes — the same connection method for every agent terminal.
+ */
+import { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { makeEvent } from "./types.js";
+import { InteractiveWorker } from "./interactive.js";
+import { detectAgents, agentSpec, resolveTarget } from "./registry.js";
+export class InteractiveRegistry {
+    entries = new Map();
+    bus = new EventEmitter();
+    constructor() {
+        this.bus.setMaxListeners(0);
+    }
+    /** Start an AI CLI as an interactive agent terminal. Throws if unresolved. */
+    start(target, opts = {}) {
+        const agents = detectAgents();
+        const { target: resolved } = resolveTarget(target || "auto", agents);
+        const spec = agentSpec(resolved);
+        const binPath = agents.find((a) => a.name === resolved)?.binPath ?? null;
+        if (!spec || !spec.headless || !binPath) {
+            throw new Error(`agent '${resolved}' is not installed/runnable (try 'maq detect')`);
+        }
+        const args = spec.headless.map((a) => (a === "{task}" ? (opts.task ?? "") : a));
+        const authed = agents.find((a) => a.name === resolved)?.authenticated ?? false;
+        const info = this.spawnRaw(binPath, args, { target: resolved, cwd: opts.cwd });
+        info.authenticated = authed;
+        if (!authed) {
+            info.warning = `'${resolved}' is installed but not authenticated — it may prompt you to log in. Complete login in the terminal panel, then retry.`;
+        }
+        return info;
+    }
+    /** Lower-level spawn (also used by tests with an arbitrary bin). */
+    spawnRaw(bin, args, meta) {
+        const id = randomUUID();
+        const info = { id, target: meta.target, status: "starting", createdAt: new Date().toISOString() };
+        const worker = new InteractiveWorker(bin, args, {
+            cwd: meta.cwd,
+            onEvent: (e) => this.push(id, e),
+            onStatus: (s) => {
+                info.status = s;
+                this.push(id, makeEvent("agent.event", { status: s }));
+            },
+        });
+        this.entries.set(id, { worker, info, events: [] });
+        worker.start();
+        return info;
+    }
+    get(id) {
+        return this.entries.get(id);
+    }
+    list() {
+        return [...this.entries.values()].map((e) => e.info);
+    }
+    /** Steer: write a line to the agent's stdin. */
+    input(id, text) {
+        return this.entries.get(id)?.worker.write(text) ?? false;
+    }
+    close(id) {
+        const e = this.entries.get(id);
+        if (!e)
+            return false;
+        e.worker.end();
+        e.worker.kill();
+        return true;
+    }
+    subscribe(id, listener) {
+        const evt = `event:${id}`;
+        this.bus.on(evt, listener);
+        return () => this.bus.off(evt, listener);
+    }
+    push(id, e) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        entry.events.push(e);
+        this.bus.emit(`event:${id}`, e);
+    }
+}

package/dist/core/interactive.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Interactive worker — the "steer a running worker" capability (CAO's live-PTY
+ * value) WITHOUT a mandatory native PTY dependency. It spawns a worker with a
+ * kept-open stdin pipe, streams stdout/stderr line-by-line as normalized
+ * events, infers a live status (starting → processing ⇄ idle → exited), and
+ * lets a caller `write()` follow-up input mid-task (inbox → stdin steering).
+ *
+ * Zero runtime deps (node:child_process). A full terminal-emulation PTY backend
+ * (node-pty) can be added later as an opt-in for CLIs that require a real TTY;
+ * this covers CLIs that read line-based stdin.
+ */
+import { type MaqEvent } from "./types.js";
+export type WorkerStatus = "starting" | "processing" | "idle" | "exited";
+export interface InteractiveOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Quiet period (ms) after which a busy worker is considered idle. */
+    idleMs?: number;
+    onEvent?: (e: MaqEvent) => void;
+    onStatus?: (s: WorkerStatus) => void;
+}
+export declare class InteractiveWorker {
+    private bin;
+    private args;
+    private child;
+    private _status;
+    private idleTimer;
+    private outBuf;
+    private errBuf;
+    private idleMs;
+    private opts;
+    private exitResolve;
+    constructor(bin: string, args?: string[], opts?: InteractiveOptions);
+    get status(): WorkerStatus;
+    start(): void;
+    /** Steer the worker: send a line of input to its stdin. */
+    write(text: string): boolean;
+    /** Signal end-of-input (close stdin). */
+    end(): void;
+    kill(): void;
+    /** Resolve when the process exits. */
+    wait(): Promise<number | null>;
+    private pump;
+    private emitLine;
+    private armIdle;
+    private setStatus;
+    private emit;
+}