maqcli 0.2.0

package/dist/core/session.js

@@ -0,0 +1,252 @@
+/**
+ * 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 { EventEmitter } from "node:events";
+import { randomUUID } from "node:crypto";
+import { makeEvent } from "./types.js";
+import { runPipeline } from "./pipeline.js";
+import { ProfileManager } from "./profiles.js";
+/** Thrown through the pipeline checkpoint when a session is cancelled. */
+export class CancelError extends Error {
+    constructor() {
+        super("cancelled");
+        this.name = "CancelError";
+    }
+}
+export class SessionRegistry {
+    sessions = new Map();
+    controls = new Map();
+    bus = new EventEmitter();
+    maxSessions;
+    maxEventsPerSession;
+    constructor(maxSessions = 100, maxEventsPerSession = 2000) {
+        this.maxSessions = maxSessions;
+        this.maxEventsPerSession = maxEventsPerSession;
+        this.bus.setMaxListeners(0);
+    }
+    /** Fire-and-forget: start a session and return its id immediately. */
+    assign(task, opts = {}) {
+        const session = this.spawn(task, opts);
+        return session;
+    }
+    /** Synchronous handoff: start a session and await its completion. */
+    async handoff(task, opts = {}) {
+        const session = this.spawn(task, opts);
+        await this.waitFor(session.id);
+        return this.sessions.get(session.id);
+    }
+    /** Deliver a message into a session's inbox (records a normalized event). */
+    sendMessage(id, text, from = "user") {
+        const s = this.sessions.get(id);
+        if (!s)
+            return false;
+        const msg = { ts: new Date().toISOString(), from, text };
+        s.inbox.push(msg);
+        this.push(s, makeEvent("agent.event", { note: "message received", from, text }));
+        return true;
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    list() {
+        return [...this.sessions.values()].map((s) => this.summarize(s));
+    }
+    summarize(s) {
+        return {
+            id: s.id,
+            task: s.task,
+            status: s.status,
+            target: s.target,
+            cwd: s.cwd,
+            createdAt: s.createdAt,
+            updatedAt: s.updatedAt,
+            verified: s.result?.verify.verified,
+            eventCount: s.events.length,
+        };
+    }
+    /** Subscribe to live events for a session. Returns an unsubscribe fn. */
+    subscribe(id, listener) {
+        const evt = `event:${id}`;
+        this.bus.on(evt, listener);
+        return () => this.bus.off(evt, listener);
+    }
+    /** Subscribe to ALL sessions' events (for plugins/webhooks). */
+    onAny(listener) {
+        this.bus.on("event", listener);
+    }
+    offAny(listener) {
+        this.bus.off("event", listener);
+    }
+    /** Remove finished sessions (housekeeping). */
+    prune() {
+        let removed = 0;
+        for (const [id, s] of this.sessions) {
+            if (s.status !== "running") {
+                this.sessions.delete(id);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    spawn(task, opts) {
+        if (this.sessions.size >= this.maxSessions)
+            this.evictOldestDone();
+        const id = randomUUID();
+        const now = new Date().toISOString();
+        // Resolve an agent profile (if any) into concrete overrides.
+        let target = opts.target;
+        let provider = opts.provider;
+        let model = opts.model;
+        if (opts.profile) {
+            const prof = new ProfileManager(opts.cwd ?? process.cwd()).get(opts.profile);
+            if (prof) {
+                target = target ?? prof.target;
+                provider = provider ?? prof.provider;
+                model = model ?? prof.model;
+            }
+        }
+        const session = {
+            id,
+            task,
+            status: "running",
+            target,
+            cwd: opts.cwd ?? process.cwd(),
+            createdAt: now,
+            updatedAt: now,
+            events: [],
+            inbox: [],
+        };
+        this.sessions.set(id, session);
+        const control = { paused: false, cancelled: false, abort: new AbortController(), resumeWaiters: [] };
+        this.controls.set(id, control);
+        const checkpoint = () => {
+            const c = this.controls.get(id);
+            if (!c || c.cancelled)
+                return Promise.reject(new CancelError());
+            if (!c.paused)
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                c.resumeWaiters.push(() => (this.controls.get(id)?.cancelled ? reject(new CancelError()) : resolve()));
+            });
+        };
+        const pipelineOpts = {
+            cwd: session.cwd,
+            target,
+            provider,
+            model,
+            dryRun: opts.dryRun,
+            timeoutMs: opts.timeoutMs,
+            onEvent: (e) => this.push(session, e),
+            signal: control.abort.signal,
+            checkpoint,
+        };
+        // Run asynchronously; never throw out of assign/handoff spawn.
+        runPipeline(task, pipelineOpts)
+            .then((result) => {
+            if (session.status === "cancelled")
+                return;
+            session.result = result;
+            session.status = "done";
+            session.updatedAt = new Date().toISOString();
+            this.bus.emit(`done:${id}`);
+        })
+            .catch((err) => {
+            if (err instanceof CancelError || this.controls.get(id)?.cancelled) {
+                session.status = "cancelled";
+                session.updatedAt = new Date().toISOString();
+                this.push(session, makeEvent("task.cancelled", {}));
+            }
+            else {
+                session.error = err instanceof Error ? err.message : String(err);
+                session.status = "error";
+                session.updatedAt = new Date().toISOString();
+                this.push(session, makeEvent("task.error", { message: session.error }));
+            }
+            this.bus.emit(`done:${id}`);
+        });
+        return session;
+    }
+    /** Pause a running session at its next phase boundary. */
+    pause(id) {
+        const c = this.controls.get(id);
+        const s = this.sessions.get(id);
+        if (!c || !s || c.cancelled || s.status !== "running")
+            return false;
+        c.paused = true;
+        s.status = "paused";
+        this.push(s, makeEvent("task.paused", {}));
+        return true;
+    }
+    /** Resume a paused session. */
+    resume(id) {
+        const c = this.controls.get(id);
+        const s = this.sessions.get(id);
+        if (!c || !s || !c.paused)
+            return false;
+        c.paused = false;
+        s.status = "running";
+        const waiters = c.resumeWaiters.splice(0);
+        for (const w of waiters)
+            w();
+        this.push(s, makeEvent("task.resumed", {}));
+        return true;
+    }
+    /** Cancel a session; kills in-flight worker processes and aborts the run. */
+    cancel(id) {
+        const c = this.controls.get(id);
+        const s = this.sessions.get(id);
+        if (!c || !s || s.status === "done" || s.status === "error" || s.status === "cancelled")
+            return false;
+        c.cancelled = true;
+        c.paused = false;
+        try {
+            c.abort.abort();
+        }
+        catch {
+            /* ignore */
+        }
+        const waiters = c.resumeWaiters.splice(0);
+        for (const w of waiters)
+            w();
+        return true;
+    }
+    push(session, e) {
+        session.events.push(e);
+        // Bound per-session history so a long-lived or chatty session cannot grow
+        // memory without limit. SSE replay still gets recent context; the terminal
+        // task.started/… bookkeeping stays intact because we only drop the oldest.
+        if (session.events.length > this.maxEventsPerSession) {
+            session.events.splice(0, session.events.length - this.maxEventsPerSession);
+        }
+        session.updatedAt = e.ts;
+        this.bus.emit(`event:${session.id}`, e);
+        this.bus.emit("event", { sessionId: session.id, event: e });
+    }
+    waitFor(id) {
+        const s = this.sessions.get(id);
+        if (!s || s.status !== "running")
+            return Promise.resolve();
+        return new Promise((resolve) => this.bus.once(`done:${id}`, () => resolve()));
+    }
+    evictOldestDone() {
+        for (const [id, s] of this.sessions) {
+            if (s.status !== "running") {
+                this.sessions.delete(id);
+                return;
+            }
+        }
+    }
+}

package/dist/core/skills.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Skills / rules layer — standing instructions injected into the master's own
+ * prompts (Plan, Verify), the way `CLAUDE.md` / `AGENTS.md` / skill files lift a
+ * model's behavior.
+ *
+ * Key nuance (from field reports on strong models): rules written to scaffold a
+ * WEAK model can HOLD BACK a strong one — guardrails for failure modes it no
+ * longer has just eat context. So skills are TIER-AWARE: a file can declare the
+ * tier it applies to, and the strong tier receives a trimmed, high-signal set.
+ *
+ * Sources of skills (later ones win on name collision):
+ *   1. built-in defaults (below)
+ *   2. ~/.maqcli/skills/*.md          (global)
+ *   3. <cwd>/<skillsDir>/*.md         (project; default ".maq/skills")
+ *   4. <cwd>/AGENTS.md, <cwd>/CLAUDE.md, <cwd>/MAQ.md   (project standing files)
+ *
+ * A skill file may begin with light front-matter lines:
+ *   maq-tier: cheap | strong | all      (default: all)
+ *   maq-kind: constraint | scaffolding | context   (default: context)
+ * `scaffolding` skills are dropped for the strong tier.
+ */
+import type { Tier } from "./router.js";
+export type SkillTier = "cheap" | "strong" | "all";
+export type SkillKind = "constraint" | "scaffolding" | "context";
+export interface Skill {
+    name: string;
+    path: string | null;
+    tier: SkillTier;
+    kind: SkillKind;
+    content: string;
+}
+export interface SkillsOptions {
+    skillsDir?: string;
+    /** Hard cap on the assembled context block (chars). */
+    maxChars?: number;
+}
+export declare class SkillsManager {
+    private cwd;
+    private skillsDir;
+    private maxChars;
+    constructor(cwd: string, opts?: SkillsOptions);
+    /** Load all skills from every source, de-duplicated by name (later wins). */
+    load(): Skill[];
+    /** Skills that apply to a given tier (strong drops `scaffolding`). */
+    forTier(tier: Tier): Skill[];
+    /** Assemble a compact standing-instructions block for a tier (capped). */
+    contextBlock(tier: Tier): string;
+    private readDir;
+    private readFile;
+}
+/**
+ * Scaffold starter skill files (and an AGENTS.md if absent) into a project so
+ * teams can extend the built-in pack. Never overwrites existing files.
+ * Returns the list of files written.
+ */
+export declare function initSkills(cwd: string, skillsDir?: string): string[];

package/dist/core/skills.js

@@ -0,0 +1,289 @@
+/**
+ * Skills / rules layer — standing instructions injected into the master's own
+ * prompts (Plan, Verify), the way `CLAUDE.md` / `AGENTS.md` / skill files lift a
+ * model's behavior.
+ *
+ * Key nuance (from field reports on strong models): rules written to scaffold a
+ * WEAK model can HOLD BACK a strong one — guardrails for failure modes it no
+ * longer has just eat context. So skills are TIER-AWARE: a file can declare the
+ * tier it applies to, and the strong tier receives a trimmed, high-signal set.
+ *
+ * Sources of skills (later ones win on name collision):
+ *   1. built-in defaults (below)
+ *   2. ~/.maqcli/skills/*.md          (global)
+ *   3. <cwd>/<skillsDir>/*.md         (project; default ".maq/skills")
+ *   4. <cwd>/AGENTS.md, <cwd>/CLAUDE.md, <cwd>/MAQ.md   (project standing files)
+ *
+ * A skill file may begin with light front-matter lines:
+ *   maq-tier: cheap | strong | all      (default: all)
+ *   maq-kind: constraint | scaffolding | context   (default: context)
+ * `scaffolding` skills are dropped for the strong tier.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync } from "node:fs";
+/**
+ * Curated default skills. Grounded in 2026 agent-instruction best practice:
+ * frontier models reliably follow ~150–200 instructions before adherence
+ * degrades, so this set is deliberately small and high-signal (constraints that
+ * matter + scaffolding only weak tiers need). `scaffolding` skills are dropped
+ * for the strong tier because rules written for a weak model hold a strong one
+ * back. Projects extend/override these via .maq/skills, AGENTS.md, CLAUDE.md.
+ */
+const DEFAULT_SKILLS = [
+    // --- constraints (apply to every tier) ---
+    {
+        name: "verify-before-done",
+        path: null,
+        tier: "all",
+        kind: "constraint",
+        content: "Never treat 'the agent stopped' as done. Prove completion with tests, a build, or a concrete check. State what you verified and what you could not.",
+    },
+    {
+        name: "tests-are-truth",
+        path: null,
+        tier: "all",
+        kind: "constraint",
+        content: "Run the project's own tests/build as the completion signal. When fixing a bug, add or adjust a test that would have caught it.",
+    },
+    {
+        name: "minimal-diff",
+        path: null,
+        tier: "all",
+        kind: "constraint",
+        content: "Make the smallest change that satisfies the task. Do not refactor or reformat unrelated code. Match the project's existing style, conventions, and libraries.",
+    },
+    {
+        name: "safe-exec",
+        path: null,
+        tier: "all",
+        kind: "constraint",
+        content: "Run commands via argument arrays, never string-interpolate untrusted values into a shell. Validate inputs. Quote/escape anything user- or model-provided.",
+    },
+    {
+        name: "confirm-destructive",
+        path: null,
+        tier: "all",
+        kind: "constraint",
+        content: "Pause and confirm before irreversible or high-blast-radius actions: force push, hard reset, recursive delete, dropping data, or touching production.",
+    },
+    {
+        name: "no-secrets",
+        path: null,
+        tier: "all",
+        kind: "constraint",
+        content: "Never print or commit secrets. Reference credentials by key name, not value. Flag files that likely hold secrets before reading or committing them.",
+    },
+    {
+        name: "cite-what-you-checked",
+        path: null,
+        tier: "all",
+        kind: "context",
+        content: "Distinguish what you verified (ran/read/confirmed) from what you assumed. Do not present assumptions as facts; do not over-qualify confirmed results.",
+    },
+    {
+        name: "keep-rules-fresh",
+        path: null,
+        tier: "all",
+        kind: "context",
+        content: "Standing rules can go stale. If an instruction contradicts what you observe in the repo or is a guardrail you no longer need, flag it instead of blindly following it.",
+    },
+    // --- scaffolding (cheap tier only; dropped for strong models) ---
+    {
+        name: "scope-tight",
+        path: null,
+        tier: "cheap",
+        kind: "scaffolding",
+        content: "Work only on the files in scope. Do not re-explore the whole repo. Prefer the smallest change that satisfies the task and keeps existing tests green.",
+    },
+    {
+        name: "read-before-write",
+        path: null,
+        tier: "cheap",
+        kind: "scaffolding",
+        content: "Read the relevant file(s) fully before editing them. Understand the surrounding pattern first, then change the minimum.",
+    },
+    {
+        name: "plan-then-act",
+        path: null,
+        tier: "cheap",
+        kind: "scaffolding",
+        content: "For non-trivial tasks, outline a short plan (files to touch, steps, how you'll verify) before editing. Commit to one approach.",
+    },
+    {
+        name: "structured-handoff",
+        path: null,
+        tier: "cheap",
+        kind: "scaffolding",
+        content: "When delegating a sub-step, pass a minimal context package and expect back a concise summary (findings, decisions, artifacts) — not a raw transcript.",
+    },
+];
+const STANDING_FILES = ["AGENTS.md", "CLAUDE.md", "MAQ.md"];
+const MAX_FILE_CHARS = 8000;
+export class SkillsManager {
+    cwd;
+    skillsDir;
+    maxChars;
+    constructor(cwd, opts = {}) {
+        this.cwd = cwd;
+        this.skillsDir = opts.skillsDir ?? ".maq/skills";
+        this.maxChars = opts.maxChars ?? 6000;
+    }
+    /** Load all skills from every source, de-duplicated by name (later wins). */
+    load() {
+        const byName = new Map();
+        for (const s of DEFAULT_SKILLS)
+            byName.set(s.name, s);
+        for (const dir of [join(homedir(), ".maqcli", "skills"), join(this.cwd, this.skillsDir)]) {
+            for (const s of this.readDir(dir))
+                byName.set(s.name, s);
+        }
+        for (const f of STANDING_FILES) {
+            const p = join(this.cwd, f);
+            const s = this.readFile(p, f.replace(/\.md$/i, "").toLowerCase());
+            if (s)
+                byName.set(s.name, s);
+        }
+        return [...byName.values()];
+    }
+    /** Skills that apply to a given tier (strong drops `scaffolding`). */
+    forTier(tier) {
+        return this.load().filter((s) => {
+            if (s.tier !== "all" && s.tier !== tier)
+                return false;
+            if (tier === "strong" && s.kind === "scaffolding")
+                return false;
+            return true;
+        });
+    }
+    /** Assemble a compact standing-instructions block for a tier (capped). */
+    contextBlock(tier) {
+        const skills = this.forTier(tier);
+        if (skills.length === 0)
+            return "";
+        const parts = ["Standing instructions (skills):"];
+        let budget = this.maxChars;
+        for (const s of skills) {
+            const line = `- [${s.kind}] ${s.name}: ${s.content.trim()}`;
+            if (line.length > budget) {
+                parts.push(line.slice(0, Math.max(0, budget)) + "…");
+                break;
+            }
+            parts.push(line);
+            budget -= line.length;
+        }
+        return parts.join("\n");
+    }
+    readDir(dir) {
+        if (!existsSync(dir))
+            return [];
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const e of entries) {
+            if (!e.toLowerCase().endsWith(".md"))
+                continue;
+            const s = this.readFile(join(dir, e), e.replace(/\.md$/i, ""));
+            if (s)
+                out.push(s);
+        }
+        return out;
+    }
+    readFile(path, name) {
+        if (!existsSync(path))
+            return null;
+        try {
+            if (!statSync(path).isFile())
+                return null;
+            const raw = readFileSync(path, "utf8").slice(0, MAX_FILE_CHARS);
+            const { tier, kind, body } = parseFrontMatter(raw);
+            return { name, path, tier, kind, content: body };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function parseFrontMatter(raw) {
+    let tier = "all";
+    let kind = "context";
+    const lines = raw.split(/\r?\n/);
+    let consumed = 0;
+    for (let i = 0; i < Math.min(lines.length, 6); i++) {
+        const m = /^\s*maq-(tier|kind)\s*:\s*(\w+)/i.exec(lines[i]);
+        if (!m)
+            break;
+        const key = m[1].toLowerCase();
+        const val = m[2].toLowerCase();
+        if (key === "tier" && (val === "cheap" || val === "strong" || val === "all"))
+            tier = val;
+        if (key === "kind" && (val === "constraint" || val === "scaffolding" || val === "context"))
+            kind = val;
+        consumed = i + 1;
+    }
+    return { tier, kind, body: lines.slice(consumed).join("\n").trim() };
+}
+/**
+ * Scaffold starter skill files (and an AGENTS.md if absent) into a project so
+ * teams can extend the built-in pack. Never overwrites existing files.
+ * Returns the list of files written.
+ */
+export function initSkills(cwd, skillsDir = ".maq/skills") {
+    const written = [];
+    const dir = join(cwd, skillsDir);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch {
+        /* ignore */
+    }
+    const example = join(dir, "example-skill.md");
+    if (!existsSync(example)) {
+        writeFileSync(example, [
+            "maq-tier: all",
+            "maq-kind: constraint",
+            "",
+            "# Example project skill",
+            "",
+            "Replace this with a real, single-purpose rule specific to THIS project —",
+            "something an agent cannot infer from the code (a convention, a boundary, a",
+            "gotcha). Keep it concise; stale or contradictory rules corrupt decisions.",
+            "",
+            "Front-matter options (first lines): `maq-tier: cheap|strong|all`,",
+            "`maq-kind: constraint|scaffolding|context`. `scaffolding` skills are",
+            "dropped for the strong model tier.",
+        ].join("\n"), "utf8");
+        written.push(example);
+    }
+    const agents = join(cwd, "AGENTS.md");
+    if (!existsSync(agents)) {
+        writeFileSync(agents, [
+            "# AGENTS.md",
+            "",
+            "Standing instructions for coding agents working in this repo. Keep it tight —",
+            "models reliably follow ~150–200 instructions before adherence degrades, so",
+            "write only what an agent cannot discover from the code itself.",
+            "",
+            "## Commands",
+            "- build: (fill in)",
+            "- test: (fill in)",
+            "- lint: (fill in)",
+            "",
+            "## Conventions",
+            "- (language/style/library conventions specific to this repo)",
+            "",
+            "## Boundaries",
+            "- (directories or actions that are off-limits)",
+            "",
+            "## MAQ — lessons from verification failures",
+            "(MAQ appends lessons here automatically when a run fails verification.)",
+        ].join("\n"), "utf8");
+        written.push(agents);
+    }
+    return written;
+}

package/dist/core/subagent.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Sub-agent isolation (containment over delegation).
+ *
+ * The lead/orchestrator should NOT inherit a sub-agent's full working set. A
+ * sub-agent runs in a FRESH, minimal context (task + only the explicitly passed
+ * artifacts) and returns a CONCISE summary — findings, decisions, artifacts —
+ * not a raw transcript. This is what makes multi-step work cheap: you pay for
+ * isolation only if you get the token savings of a summary back.
+ *
+ * This mirrors the mechanism a long-horizon model does internally (plan →
+ * delegate to sub-agents → synthesize), supplied externally so any model gets it.
+ */
+import type { ModelProvider } from "./model.js";
+import { CostMeter } from "./cost.js";
+export interface SubagentInput {
+    /** The scoped sub-task. */
+    task: string;
+    /** Minimal, explicitly-selected context package (NOT the parent's whole state). */
+    context?: string;
+    /** Target summary size hint, in tokens. */
+    summaryTokens?: number;
+}
+export interface SubagentResult {
+    summary: string;
+    model: string;
+    provider: string;
+    promptTokensEst: number;
+    completionTokensEst: number;
+    costUsd: number;
+}
+/**
+ * Run one isolated sub-agent. Returns a condensed summary plus accounting.
+ * The parent should merge only the `summary` into its context.
+ */
+export declare function runSubagent(input: SubagentInput, provider: ModelProvider, model: string, meter?: CostMeter): Promise<SubagentResult>;
+/**
+ * Fan out several scoped sub-tasks in parallel and collect their summaries.
+ * Each runs in its own isolated context; the orchestrator sees only summaries.
+ */
+export declare function runSubagents(inputs: SubagentInput[], provider: ModelProvider, model: string, meter?: CostMeter): Promise<SubagentResult[]>;

package/dist/core/subagent.js

@@ -0,0 +1,55 @@
+/**
+ * Sub-agent isolation (containment over delegation).
+ *
+ * The lead/orchestrator should NOT inherit a sub-agent's full working set. A
+ * sub-agent runs in a FRESH, minimal context (task + only the explicitly passed
+ * artifacts) and returns a CONCISE summary — findings, decisions, artifacts —
+ * not a raw transcript. This is what makes multi-step work cheap: you pay for
+ * isolation only if you get the token savings of a summary back.
+ *
+ * This mirrors the mechanism a long-horizon model does internally (plan →
+ * delegate to sub-agents → synthesize), supplied externally so any model gets it.
+ */
+const SYSTEM = "You are an isolated sub-agent invoked by an orchestrator. You have a single scoped task. " +
+    "Explore/answer it using only the context provided. Return a CONCISE structured summary " +
+    "(findings, decisions, artifacts, open questions) — never a raw transcript or full data dump. " +
+    "Containment rule: hand back a concise answer, not everything you looked at.";
+/**
+ * Run one isolated sub-agent. Returns a condensed summary plus accounting.
+ * The parent should merge only the `summary` into its context.
+ */
+export async function runSubagent(input, provider, model, meter) {
+    const summaryTokens = input.summaryTokens ?? 1500;
+    const user = [
+        `Sub-task: ${input.task}`,
+        input.context ? `\nContext package (only what you were given):\n${input.context}` : "",
+        `\nReturn at most ~${summaryTokens} tokens. Structure: Findings / Decisions / Artifacts / Open questions.`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const res = await provider.complete({
+        model,
+        tier: "cheap",
+        maxTokens: summaryTokens,
+        messages: [
+            { role: "system", content: SYSTEM },
+            { role: "user", content: user },
+        ],
+    });
+    meter?.record(res.model, res.promptTokensEst, res.completionTokensEst);
+    return {
+        summary: res.text.trim(),
+        model: res.model,
+        provider: res.provider,
+        promptTokensEst: res.promptTokensEst,
+        completionTokensEst: res.completionTokensEst,
+        costUsd: res.costUsd ?? 0,
+    };
+}
+/**
+ * Fan out several scoped sub-tasks in parallel and collect their summaries.
+ * Each runs in its own isolated context; the orchestrator sees only summaries.
+ */
+export async function runSubagents(inputs, provider, model, meter) {
+    return Promise.all(inputs.map((i) => runSubagent(i, provider, model, meter)));
+}