maqcli 0.2.0

package/dist/core/providers.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Real model providers (LiteLLM-style single interface, dependency-free).
+ *
+ * Uses Node's global `fetch` (Node >= 18/20) — no SDKs, no runtime deps. Every
+ * provider implements the same `ModelProvider.complete()` surface used by the
+ * offline `HeuristicProvider`, so Scout/Plan/Verify never care which backend
+ * runs. API keys come from environment variables only (never config files),
+ * calls have hard timeouts (AbortController) and bounded retries with backoff,
+ * and real usage is used for token/cost accounting when the API returns it.
+ *
+ * Providers:
+ *  - OpenAICompatibleProvider — OpenAI, LiteLLM proxy, Groq, Together, Ollama's
+ *    OpenAI-compatible endpoint, or any `/v1/chat/completions` server.
+ *  - AnthropicProvider — Anthropic Messages API (`/v1/messages`).
+ *  - OllamaProvider — Ollama native `/api/chat` (no key, localhost by default).
+ */
+import type { CompletionRequest, CompletionResponse, ModelProvider } from "./model.js";
+export interface HttpProviderOptions {
+    /** Base URL, e.g. https://api.openai.com/v1 (no trailing slash needed). */
+    baseUrl: string;
+    /** API key (already resolved from env by the factory). */
+    apiKey?: string;
+    /** Per-call timeout in ms. */
+    timeoutMs?: number;
+    /** Max attempts (>=1). Retries apply to network errors and 429/5xx. */
+    maxRetries?: number;
+    /** Extra headers. */
+    headers?: Record<string, string>;
+}
+export declare class ProviderError extends Error {
+    readonly status?: number | undefined;
+    readonly retryable: boolean;
+    constructor(message: string, status?: number | undefined, retryable?: boolean);
+}
+/**
+ * OpenAI-compatible chat completions. Works with OpenAI, a LiteLLM proxy, and
+ * any server exposing POST {baseUrl}/chat/completions.
+ */
+export declare class OpenAICompatibleProvider implements ModelProvider {
+    readonly name: string;
+    private opts;
+    constructor(name: string, options: HttpProviderOptions);
+    complete(req: CompletionRequest): Promise<CompletionResponse>;
+}
+/** Anthropic Messages API provider (`/v1/messages`). */
+export declare class AnthropicProvider implements ModelProvider {
+    readonly name = "anthropic";
+    private opts;
+    constructor(options: HttpProviderOptions);
+    complete(req: CompletionRequest): Promise<CompletionResponse>;
+}
+/** Ollama native `/api/chat` provider (local, no API key). */
+export declare class OllamaProvider implements ModelProvider {
+    readonly name = "ollama";
+    private baseUrl;
+    private timeoutMs;
+    private maxRetries;
+    constructor(options?: Partial<HttpProviderOptions>);
+    complete(req: CompletionRequest): Promise<CompletionResponse>;
+}
+/**
+ * CLI-as-provider — reuse an already-authenticated worker CLI (Claude Code,
+ * Gemini CLI, Codex, ...) as the master's OWN thinking model, at $0 marginal
+ * cost (the user's existing subscription pays for it). This is the "prefer the
+ * detected AI as Headroom's light model" strategy: the master's Scout/Plan/
+ * Verify prompts are answered by piping them to the CLI's headless mode.
+ *
+ * The command runner is injectable for testing; by default it uses execSafe
+ * (shell:false, argument array — the prompt is never shell-interpreted).
+ */
+export type CliRunner = (bin: string, args: string[], input: string) => Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+export declare class CliProvider implements ModelProvider {
+    private binPath;
+    private headless;
+    private runner;
+    private timeoutMs;
+    readonly name: string;
+    constructor(agentName: string, binPath: string, headless: string[], runner: CliRunner, timeoutMs?: number);
+    complete(req: CompletionRequest): Promise<CompletionResponse>;
+}

package/dist/core/providers.js

@@ -0,0 +1,275 @@
+/**
+ * Real model providers (LiteLLM-style single interface, dependency-free).
+ *
+ * Uses Node's global `fetch` (Node >= 18/20) — no SDKs, no runtime deps. Every
+ * provider implements the same `ModelProvider.complete()` surface used by the
+ * offline `HeuristicProvider`, so Scout/Plan/Verify never care which backend
+ * runs. API keys come from environment variables only (never config files),
+ * calls have hard timeouts (AbortController) and bounded retries with backoff,
+ * and real usage is used for token/cost accounting when the API returns it.
+ *
+ * Providers:
+ *  - OpenAICompatibleProvider — OpenAI, LiteLLM proxy, Groq, Together, Ollama's
+ *    OpenAI-compatible endpoint, or any `/v1/chat/completions` server.
+ *  - AnthropicProvider — Anthropic Messages API (`/v1/messages`).
+ *  - OllamaProvider — Ollama native `/api/chat` (no key, localhost by default).
+ */
+import { costUsd } from "./cost.js";
+function estTokens(s) {
+    return Math.ceil(s.length / 4);
+}
+export class ProviderError extends Error {
+    status;
+    retryable;
+    constructor(message, status, retryable = false) {
+        super(message);
+        this.status = status;
+        this.retryable = retryable;
+        this.name = "ProviderError";
+    }
+}
+async function fetchWithRetry(url, init, timeoutMs, maxRetries) {
+    let lastErr;
+    for (let attempt = 0; attempt < Math.max(1, maxRetries); attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(url, { ...init, signal: controller.signal });
+            clearTimeout(timer);
+            if (res.status === 429 || (res.status >= 500 && res.status <= 599)) {
+                lastErr = new ProviderError(`upstream ${res.status}`, res.status, true);
+                if (attempt < maxRetries - 1) {
+                    await sleep(backoffMs(attempt, res.headers.get("retry-after")));
+                    continue;
+                }
+                return res;
+            }
+            return res;
+        }
+        catch (e) {
+            clearTimeout(timer);
+            lastErr = e;
+            const aborted = e instanceof Error && e.name === "AbortError";
+            if (attempt < maxRetries - 1) {
+                await sleep(backoffMs(attempt, null));
+                continue;
+            }
+            throw new ProviderError(aborted ? `request timed out after ${timeoutMs}ms` : `network error: ${e.message}`, undefined, true);
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new ProviderError(String(lastErr));
+}
+function backoffMs(attempt, retryAfter) {
+    if (retryAfter) {
+        const secs = Number(retryAfter);
+        if (!Number.isNaN(secs))
+            return Math.min(secs * 1000, 20000);
+    }
+    const base = 300 * 2 ** attempt;
+    return Math.min(base + Math.random() * 250, 10000);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** Split a message list into an Anthropic-style {system, messages}. */
+function splitSystem(messages) {
+    const system = messages
+        .filter((m) => m.role === "system")
+        .map((m) => m.content)
+        .join("\n\n");
+    const rest = messages.filter((m) => m.role !== "system");
+    return { system, rest };
+}
+/**
+ * OpenAI-compatible chat completions. Works with OpenAI, a LiteLLM proxy, and
+ * any server exposing POST {baseUrl}/chat/completions.
+ */
+export class OpenAICompatibleProvider {
+    name;
+    opts;
+    constructor(name, options) {
+        this.name = name;
+        this.opts = {
+            baseUrl: options.baseUrl.replace(/\/$/, ""),
+            apiKey: options.apiKey,
+            timeoutMs: options.timeoutMs ?? 60000,
+            maxRetries: options.maxRetries ?? 3,
+            headers: options.headers ?? {},
+        };
+    }
+    async complete(req) {
+        const url = `${this.opts.baseUrl}/chat/completions`;
+        const body = {
+            model: req.model,
+            messages: req.messages,
+            ...(req.maxTokens ? { max_tokens: req.maxTokens } : {}),
+        };
+        const headers = {
+            "content-type": "application/json",
+            ...this.opts.headers,
+        };
+        if (this.opts.apiKey)
+            headers.authorization = `Bearer ${this.opts.apiKey}`;
+        const res = await fetchWithRetry(url, { method: "POST", headers, body: JSON.stringify(body) }, this.opts.timeoutMs, this.opts.maxRetries);
+        const raw = await res.text();
+        if (!res.ok) {
+            throw new ProviderError(`${this.name} ${res.status}: ${raw.slice(0, 300)}`, res.status, res.status >= 500);
+        }
+        const data = safeJson(raw);
+        const text = data?.choices?.[0]?.message?.content ?? "";
+        const promptTokens = data?.usage?.prompt_tokens ?? estTokens(JSON.stringify(req.messages));
+        const completionTokens = data?.usage?.completion_tokens ?? estTokens(text);
+        return {
+            text,
+            model: data?.model ?? req.model,
+            provider: this.name,
+            promptTokensEst: promptTokens,
+            completionTokensEst: completionTokens,
+            costUsd: costUsd(req.model, promptTokens, completionTokens),
+        };
+    }
+}
+/** Anthropic Messages API provider (`/v1/messages`). */
+export class AnthropicProvider {
+    name = "anthropic";
+    opts;
+    constructor(options) {
+        this.opts = {
+            baseUrl: (options.baseUrl || "https://api.anthropic.com/v1").replace(/\/$/, ""),
+            apiKey: options.apiKey ?? "",
+            timeoutMs: options.timeoutMs ?? 60000,
+            maxRetries: options.maxRetries ?? 3,
+            headers: options.headers ?? {},
+        };
+    }
+    async complete(req) {
+        const url = `${this.opts.baseUrl}/messages`;
+        const { system, rest } = splitSystem(req.messages);
+        const body = {
+            model: req.model,
+            max_tokens: req.maxTokens ?? 1024,
+            ...(system ? { system } : {}),
+            messages: rest.map((m) => ({ role: m.role === "assistant" ? "assistant" : "user", content: m.content })),
+        };
+        const headers = {
+            "content-type": "application/json",
+            "x-api-key": this.opts.apiKey,
+            "anthropic-version": "2023-06-01",
+            ...this.opts.headers,
+        };
+        const res = await fetchWithRetry(url, { method: "POST", headers, body: JSON.stringify(body) }, this.opts.timeoutMs, this.opts.maxRetries);
+        const raw = await res.text();
+        if (!res.ok) {
+            throw new ProviderError(`anthropic ${res.status}: ${raw.slice(0, 300)}`, res.status, res.status >= 500);
+        }
+        const data = safeJson(raw);
+        const text = Array.isArray(data?.content)
+            ? data.content.filter((b) => b?.type === "text").map((b) => b.text ?? "").join("")
+            : "";
+        const promptTokens = data?.usage?.input_tokens ?? estTokens(JSON.stringify(req.messages));
+        const completionTokens = data?.usage?.output_tokens ?? estTokens(text);
+        return {
+            text,
+            model: data?.model ?? req.model,
+            provider: this.name,
+            promptTokensEst: promptTokens,
+            completionTokensEst: completionTokens,
+            costUsd: costUsd(req.model, promptTokens, completionTokens),
+        };
+    }
+}
+/** Ollama native `/api/chat` provider (local, no API key). */
+export class OllamaProvider {
+    name = "ollama";
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl || process.env.OLLAMA_HOST || "http://127.0.0.1:11434").replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? 120000;
+        this.maxRetries = options.maxRetries ?? 2;
+    }
+    async complete(req) {
+        const url = `${this.baseUrl}/api/chat`;
+        const body = {
+            model: req.model,
+            messages: req.messages,
+            stream: false,
+            ...(req.maxTokens ? { options: { num_predict: req.maxTokens } } : {}),
+        };
+        const res = await fetchWithRetry(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, this.timeoutMs, this.maxRetries);
+        const raw = await res.text();
+        if (!res.ok) {
+            throw new ProviderError(`ollama ${res.status}: ${raw.slice(0, 300)}`, res.status, res.status >= 500);
+        }
+        const data = safeJson(raw);
+        const text = data?.message?.content ?? "";
+        const promptTokens = data?.prompt_eval_count ?? estTokens(JSON.stringify(req.messages));
+        const completionTokens = data?.eval_count ?? estTokens(text);
+        return {
+            text,
+            model: data?.model ?? req.model,
+            provider: this.name,
+            promptTokensEst: promptTokens,
+            completionTokensEst: completionTokens,
+            costUsd: 0, // local inference is free
+        };
+    }
+}
+function safeJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+export class CliProvider {
+    binPath;
+    headless;
+    runner;
+    timeoutMs;
+    name;
+    constructor(agentName, binPath, headless, runner, timeoutMs = 120000) {
+        this.binPath = binPath;
+        this.headless = headless;
+        this.runner = runner;
+        this.timeoutMs = timeoutMs;
+        this.name = `cli:${agentName}`;
+    }
+    async complete(req) {
+        const prompt = req.messages.map((m) => `${m.role.toUpperCase()}: ${m.content}`).join("\n\n");
+        const args = this.headless.map((a) => (a === "{task}" ? prompt : a));
+        const outcome = await this.runner(this.binPath, args, prompt);
+        if (outcome.code !== 0 && !outcome.stdout) {
+            throw new ProviderError(`${this.name} exited ${outcome.code}: ${outcome.stderr.slice(0, 300)}`, undefined, false);
+        }
+        const text = extractCliText(outcome.stdout);
+        return {
+            text,
+            model: this.name,
+            provider: this.name,
+            promptTokensEst: estTokens(prompt),
+            completionTokensEst: estTokens(text),
+            costUsd: 0, // covered by the user's existing CLI subscription
+        };
+    }
+}
+/** Some CLIs emit JSON ({result|text|content}); fall back to raw stdout. */
+function extractCliText(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        const j = safeJson(trimmed);
+        if (j) {
+            if (typeof j.result === "string")
+                return j.result;
+            if (typeof j.text === "string")
+                return j.text;
+            if (typeof j.content === "string")
+                return j.content;
+            if (Array.isArray(j.content))
+                return j.content.map((b) => b?.text ?? "").join("");
+        }
+    }
+    return trimmed;
+}

package/dist/core/recall.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Recall memory (CAO memory_store / memory_recall analogue).
+ *
+ * A durable, per-project note store the master can write to and read from, so
+ * knowledge survives across sessions and is injected as context at the start of
+ * a run. Distinct from `memory.ts` (which only appends failure lessons to
+ * AGENTS.md): this is a general, queryable key/text store.
+ *
+ * Storage: append-only JSONL at `<cwd>/.maq/memory/notes.jsonl` (dependency-free,
+ * human-inspectable). Recall is a cheap keyword/overlap score — good enough to
+ * surface relevant notes; a vector index can slot in behind `recall()` later.
+ */
+export interface MemoryNote {
+    ts: string;
+    key: string;
+    text: string;
+    tags: string[];
+}
+export declare class RecallMemory {
+    private dir;
+    private path;
+    constructor(cwd: string);
+    store(key: string, text: string, tags?: string[]): MemoryNote;
+    all(): MemoryNote[];
+    /** Rank notes by keyword overlap with the query; newest breaks ties. */
+    recall(query: string, limit?: number): MemoryNote[];
+    /** A compact context block of the most relevant notes for a task. */
+    contextBlock(query: string, limit?: number): string;
+}

package/dist/core/recall.js

@@ -0,0 +1,83 @@
+/**
+ * Recall memory (CAO memory_store / memory_recall analogue).
+ *
+ * A durable, per-project note store the master can write to and read from, so
+ * knowledge survives across sessions and is injected as context at the start of
+ * a run. Distinct from `memory.ts` (which only appends failure lessons to
+ * AGENTS.md): this is a general, queryable key/text store.
+ *
+ * Storage: append-only JSONL at `<cwd>/.maq/memory/notes.jsonl` (dependency-free,
+ * human-inspectable). Recall is a cheap keyword/overlap score — good enough to
+ * surface relevant notes; a vector index can slot in behind `recall()` later.
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export class RecallMemory {
+    dir;
+    path;
+    constructor(cwd) {
+        this.dir = join(cwd, ".maq", "memory");
+        this.path = join(this.dir, "notes.jsonl");
+    }
+    store(key, text, tags = []) {
+        mkdirSync(this.dir, { recursive: true });
+        const note = { ts: new Date().toISOString(), key: key.trim(), text: text.trim(), tags };
+        appendFileSync(this.path, JSON.stringify(note) + "\n", "utf8");
+        return note;
+    }
+    all() {
+        if (!existsSync(this.path))
+            return [];
+        return readFileSync(this.path, "utf8")
+            .split(/\r?\n/)
+            .filter(Boolean)
+            .map((l) => {
+            try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((n) => n !== null);
+    }
+    /** Rank notes by keyword overlap with the query; newest breaks ties. */
+    recall(query, limit = 5) {
+        const terms = [...tokenize(query)];
+        if (terms.length === 0)
+            return this.all().slice(-limit).reverse();
+        const scored = this.all().map((n) => {
+            const hay = tokenize(`${n.key} ${n.text} ${n.tags.join(" ")}`);
+            const prefixes = new Set([...hay].map((w) => w.slice(0, 4)));
+            let score = 0;
+            for (const t of terms) {
+                // Exact token, or shared 4-char prefix (so token≈tokens, validate≈validation).
+                if (hay.has(t) || prefixes.has(t.slice(0, 4)))
+                    score++;
+            }
+            return { n, score };
+        });
+        return scored
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score || (a.n.ts < b.n.ts ? 1 : -1))
+            .slice(0, limit)
+            .map((s) => s.n);
+    }
+    /** A compact context block of the most relevant notes for a task. */
+    contextBlock(query, limit = 5) {
+        const notes = this.recall(query, limit);
+        if (notes.length === 0)
+            return "";
+        return ["Relevant recalled notes:", ...notes.map((n) => `- (${n.key}) ${clip(n.text, 200)}`)].join("\n");
+    }
+}
+function tokenize(s) {
+    return new Set((s || "")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length > 2));
+}
+function clip(s, n) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > n ? t.slice(0, n) + "…" : t;
+}

package/dist/core/registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Agent registry + detection.
+ *
+ * Scans PATH for known worker-CLI binaries and inspects each tool's own
+ * config/auth directory to report installed/authenticated status. Detection is
+ * pure filesystem work — no network, no token cost.
+ */
+import type { DetectedAgent } from "./types.js";
+interface AgentSpec {
+    name: string;
+    /** Binary base names to search for on PATH. */
+    bins: string[];
+    /** Files/dirs whose existence implies auth/config for this tool. */
+    authPaths: string[];
+    stableJsonStream: boolean;
+    /** Headless invocation template; "{task}" is replaced at run time. */
+    headless: string[] | null;
+}
+export declare const KNOWN_AGENTS: AgentSpec[];
+/** Resolve a binary base name against PATH; returns absolute path or null. */
+export declare function whichBin(base: string, pathEnv?: string): string | null;
+/** Detect all known agents on the host. */
+export declare function detectAgents(pathEnv?: string): DetectedAgent[];
+/** Look up the headless template for a given agent name. */
+export declare function agentSpec(name: string): AgentSpec | undefined;
+/**
+ * Advisory when no AI worker CLI is installed+authenticated. AI CLIs manage
+ * their own login/logout on the device, so this is re-evaluated on every scan;
+ * a user logging out is reflected on the next detect. Returns null when at
+ * least one agent is ready.
+ */
+export declare function authAdvisory(agents?: DetectedAgent[]): string | null;
+/**
+ * Resolve which target to use given a requested target and detection results.
+ * Returns the chosen agent name, "none", or throws if ambiguous.
+ */
+export declare function resolveTarget(requested: string, agents: DetectedAgent[]): {
+    target: string;
+    ambiguous: string[];
+};
+export {};

package/dist/core/registry.js

@@ -0,0 +1,162 @@
+/**
+ * Agent registry + detection.
+ *
+ * Scans PATH for known worker-CLI binaries and inspects each tool's own
+ * config/auth directory to report installed/authenticated status. Detection is
+ * pure filesystem work — no network, no token cost.
+ */
+import { homedir } from "node:os";
+import { join, delimiter } from "node:path";
+import { existsSync, statSync } from "node:fs";
+const HOME = homedir();
+export const KNOWN_AGENTS = [
+    {
+        name: "claude-code",
+        bins: ["claude"],
+        authPaths: [join(HOME, ".claude"), join(HOME, ".claude.json")],
+        stableJsonStream: true,
+        headless: ["-p", "{task}", "--output-format", "json"],
+    },
+    {
+        name: "codex",
+        bins: ["codex"],
+        authPaths: [join(HOME, ".codex", "auth.json"), join(HOME, ".codex")],
+        // Codex lacks a stable JSON event stream for orchestration -> needs stdout parsing.
+        stableJsonStream: false,
+        headless: ["exec", "--json", "{task}"],
+    },
+    {
+        name: "gemini",
+        bins: ["gemini"],
+        authPaths: [join(HOME, ".gemini")],
+        stableJsonStream: false,
+        headless: ["-p", "{task}"],
+    },
+    {
+        name: "opencode",
+        bins: ["opencode"],
+        authPaths: [join(HOME, ".config", "opencode"), join(HOME, ".opencode")],
+        stableJsonStream: false,
+        headless: ["run", "{task}"],
+    },
+    {
+        name: "aider",
+        bins: ["aider"],
+        authPaths: [join(HOME, ".aider.conf.yml")],
+        stableJsonStream: false,
+        headless: ["--message", "{task}"],
+    },
+    {
+        name: "amazon-q",
+        bins: ["q"],
+        authPaths: [join(HOME, ".aws", "amazonq"), join(HOME, ".local", "share", "amazon-q")],
+        stableJsonStream: false,
+        headless: ["chat", "{task}"],
+    },
+];
+const IS_WIN = process.platform === "win32";
+const WIN_EXTS = ((process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";"));
+/** Resolve a binary base name against PATH; returns absolute path or null. */
+export function whichBin(base, pathEnv = process.env.PATH ?? "") {
+    const dirs = pathEnv.split(delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        if (IS_WIN) {
+            for (const ext of WIN_EXTS) {
+                const cand = join(dir, base + ext);
+                if (isExecutableFile(cand))
+                    return cand;
+            }
+            const bare = join(dir, base);
+            if (isExecutableFile(bare))
+                return bare;
+        }
+        else {
+            const cand = join(dir, base);
+            if (isExecutableFile(cand))
+                return cand;
+        }
+    }
+    return null;
+}
+function isExecutableFile(p) {
+    try {
+        return existsSync(p) && statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function anyExists(paths) {
+    return paths.some((p) => {
+        try {
+            return existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Detect all known agents on the host. */
+export function detectAgents(pathEnv = process.env.PATH ?? "") {
+    return KNOWN_AGENTS.map((spec) => {
+        let binPath = null;
+        for (const b of spec.bins) {
+            binPath = whichBin(b, pathEnv);
+            if (binPath)
+                break;
+        }
+        return {
+            name: spec.name,
+            binPath,
+            installed: binPath !== null,
+            authenticated: anyExists(spec.authPaths),
+            stableJsonStream: spec.stableJsonStream,
+            headless: spec.headless,
+        };
+    });
+}
+/** Look up the headless template for a given agent name. */
+export function agentSpec(name) {
+    return KNOWN_AGENTS.find((a) => a.name === name || a.bins.includes(name));
+}
+/**
+ * Advisory when no AI worker CLI is installed+authenticated. AI CLIs manage
+ * their own login/logout on the device, so this is re-evaluated on every scan;
+ * a user logging out is reflected on the next detect. Returns null when at
+ * least one agent is ready.
+ */
+export function authAdvisory(agents = detectAgents()) {
+    const ready = agents.filter((a) => a.installed && a.authenticated);
+    if (ready.length > 0)
+        return null;
+    const installedButLoggedOut = agents.filter((a) => a.installed && !a.authenticated).map((a) => a.name);
+    if (installedButLoggedOut.length > 0) {
+        return `No authenticated AI CLI detected (installed but logged out: ${installedButLoggedOut.join(", ")}). Log in to one in a terminal to enable AI mode; until then MAQ uses the offline master and --target none.`;
+    }
+    return "No AI CLI detected. Install/log in to one (claude, codex, gemini, …) to enable AI mode; MAQ works without AI via --target none.";
+}
+/**
+ * Resolve which target to use given a requested target and detection results.
+ * Returns the chosen agent name, "none", or throws if ambiguous.
+ */
+export function resolveTarget(requested, agents) {
+    if (requested === "none")
+        return { target: "none", ambiguous: [] };
+    if (requested !== "auto") {
+        const found = agents.find((a) => a.name === requested || agentSpec(requested)?.name === a.name);
+        if (found && found.installed)
+            return { target: found.name, ambiguous: [] };
+        return { target: requested, ambiguous: [] };
+    }
+    // auto: pick the single authenticated+installed agent, else surface ambiguity.
+    const ready = agents.filter((a) => a.installed && a.authenticated);
+    if (ready.length === 1)
+        return { target: ready[0].name, ambiguous: [] };
+    if (ready.length === 0) {
+        const installed = agents.filter((a) => a.installed);
+        if (installed.length === 1)
+            return { target: installed[0].name, ambiguous: [] };
+        return { target: "none", ambiguous: [] };
+    }
+    return { target: ready[0].name, ambiguous: ready.map((a) => a.name) };
+}