maestro-agent-sdk 0.1.0

package/dist/platform/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pluggable logger for the SDK.
+ *
+ * Upstream clawgram used `pino`. The SDK ships with a minimal console-backed
+ * default and exposes `setLogger()` so hosts can plug their own structured
+ * logger (pino, winston, bunyan, …). All SDK call sites import `logger` from
+ * this module and never assume a particular implementation.
+ *
+ * The interface mirrors pino's call shape — `(meta, msg)` or just `(msg)` —
+ * so existing call sites copied from clawgram work unchanged.
+ */
+export interface Logger {
+    trace: LogFn;
+    debug: LogFn;
+    info: LogFn;
+    warn: LogFn;
+    error: LogFn;
+    fatal: LogFn;
+}
+export interface LogFn {
+    (obj: Record<string, unknown>, msg?: string): void;
+    (msg: string): void;
+}
+export declare function setLogger(custom: Logger): void;
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/platform/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/platform/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AA0BD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,eAAO,MAAM,MAAM,EAAE,MAInB,CAAC"}

package/dist/platform/logger.js

@@ -0,0 +1,41 @@
+/**
+ * Pluggable logger for the SDK.
+ *
+ * Upstream clawgram used `pino`. The SDK ships with a minimal console-backed
+ * default and exposes `setLogger()` so hosts can plug their own structured
+ * logger (pino, winston, bunyan, …). All SDK call sites import `logger` from
+ * this module and never assume a particular implementation.
+ *
+ * The interface mirrors pino's call shape — `(meta, msg)` or just `(msg)` —
+ * so existing call sites copied from clawgram work unchanged.
+ */
+function makeConsoleLogger() {
+    const emit = (level) => (objOrMsg, msg) => {
+        if (typeof objOrMsg === "string") {
+            // biome-ignore lint/suspicious/noConsole: SDK default logger
+            console[level](`[${level}] ${objOrMsg}`);
+        }
+        else {
+            // biome-ignore lint/suspicious/noConsole: SDK default logger
+            console[level](`[${level}] ${msg ?? ""}`, objOrMsg);
+        }
+    };
+    return {
+        trace: emit("log"),
+        debug: emit("log"),
+        info: emit("info"),
+        warn: emit("warn"),
+        error: emit("error"),
+        fatal: emit("error"),
+    };
+}
+let _logger = makeConsoleLogger();
+export function setLogger(custom) {
+    _logger = custom;
+}
+export const logger = new Proxy({}, {
+    get(_target, prop) {
+        return _logger[prop];
+    },
+});
+//# sourceMappingURL=logger.js.map

package/dist/platform/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/platform/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgBH,SAAS,iBAAiB;IACxB,MAAM,IAAI,GACR,CAAC,KAAwC,EAAE,EAAE,CAC7C,CAAC,QAA0C,EAAE,GAAY,EAAE,EAAE;QAC3D,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,6DAA6D;YAC7D,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,6DAA6D;YAC7D,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,GAAG,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACtD,CAAC;IACH,CAAC,CAAC;IACJ,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,CAAU;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,CAAU;QAC3B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAU;QAC3B,IAAI,EAAE,IAAI,CAAC,MAAM,CAAU;QAC3B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAU;QAC7B,KAAK,EAAE,IAAI,CAAC,OAAO,CAAU;KAC9B,CAAC;AACJ,CAAC;AAED,IAAI,OAAO,GAAW,iBAAiB,EAAE,CAAC;AAE1C,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAW,IAAI,KAAK,CAAC,EAAY,EAAE;IACpD,GAAG,CAAC,OAAO,EAAE,IAAkB;QAC7B,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;CACF,CAAC,CAAC"}

package/dist/platform/mcp-config.d.ts

@@ -0,0 +1,15 @@
+import type { MaestroMcpServerSpec } from "../mcp/client.js";
+import type { AgentQueryOptions } from "../types.js";
+/**
+ * Host-provided resolver: returns the MCP servers the loop should attach for
+ * a given query, keyed by server name. The SDK's MCP pool spawns them with
+ * the cache key derived from `(userId, session, groupId, agentKind)`.
+ *
+ * The SDK ships **no defaults** — hosts call `setMcpResolver()` to plug in
+ * their own, or skip it and run without MCP.
+ */
+export type McpServerMap = Record<string, MaestroMcpServerSpec>;
+export type McpResolver = (opts: AgentQueryOptions) => McpServerMap;
+export declare function setMcpResolver(resolver: McpResolver): void;
+export declare function getMcpServersForQuery(opts: AgentQueryOptions): McpServerMap;
+//# sourceMappingURL=mcp-config.d.ts.map

package/dist/platform/mcp-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-config.d.ts","sourceRoot":"","sources":["../../src/platform/mcp-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,YAAY,CAAC;AAIpE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAE1D;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,iBAAiB,GAAG,YAAY,CAE3E"}

package/dist/platform/mcp-config.js

@@ -0,0 +1,8 @@
+let _resolver = () => ({});
+export function setMcpResolver(resolver) {
+    _resolver = resolver;
+}
+export function getMcpServersForQuery(opts) {
+    return _resolver(opts);
+}
+//# sourceMappingURL=mcp-config.js.map

package/dist/platform/mcp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-config.js","sourceRoot":"","sources":["../../src/platform/mcp-config.ts"],"names":[],"mappings":"AAcA,IAAI,SAAS,GAAgB,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;AAExC,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,SAAS,GAAG,QAAQ,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAuB;IAC3D,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,81 @@
+import type { Provider } from "./providers/base.js";
+import type { AgentQueryOptions, UnifiedEvent } from "./types.js";
+/**
+ * Maestro SDK provider (TS port of Maestro Agent v0.13.0).
+ *
+ * Multi-turn resume: when `opts.sessionId` is set we hydrate prior messages
+ * from `~/.maestro/sessions/<id>.jsonl` (written by the previous turn's
+ * persistence path or by a cross-agent rollout). Otherwise we mint a fresh
+ * UUIDv4 — matching the contract claude/codex providers expose, so the
+ * router stays agent-agnostic and `{type:"session", sessionId}` always comes
+ * back on the first iteration.
+ *
+ * After the loop drains we write the updated history back to disk so a
+ * subsequent call resumes correctly. Failures here are logged but never
+ * thrown — losing one persistence round is a degraded experience, not a
+ * stream-breaking one.
+ *
+ * MCP integration: every server in `getMcpServersForQuery(opts)` is leased
+ * from the process-wide cache (`mcp/pool-cache.ts`) and its tools are
+ * registered under `mcp__<server>__<tool>` — the same name convention Claude
+ * SDK uses, so the model sees consistent tool names across providers in the
+ * same topic. Unlike claudeProvider / codexProvider — which hand `mcpServers`
+ * to a vendor SDK that owns MCP lifecycle internally — Maestro hits Anthropic's
+ * Messages API via raw fetch, so we own startup + dispatch + cleanup here.
+ * Cache key includes (userId, session, groupId) so two users never share an
+ * MCP client; the cache evicts idle clients via TTL + LRU cap so stale slots
+ * don't accumulate.
+ *
+ * Snapshot pinned to upstream Maestro v0.13.0 (MIT, Nous Research). See
+ * docs/maestro-integration.md for the porting roadmap.
+ */
+export declare function maestroProvider(opts: AgentQueryOptions): AsyncGenerator<UnifiedEvent>;
+/**
+ * Compose the "Tool iterations remaining: N/M — <tone>" line that rides
+ * inside the per-iteration `<system-reminder>` block. Tone shifts with
+ * ABSOLUTE remaining count (not percentage of maxIter) — same threshold
+ * fires the same urgency regardless of effort level, so the model gets a
+ * consistent cue from a `low` run reaching 4-left as from a `xhigh` run
+ * reaching 4-left.
+ *
+ * Why absolute, not relative: at `low` (maxIter=5) the model crosses the
+ * wrap-up line almost immediately; at `xhigh` (maxIter=90) 75% left lasts
+ * ~22 turns. The user-visible behavior the threshold is targeting is "how
+ * many tool calls before I MUST stop" — that's an absolute count, not a
+ * fraction.
+ *
+ * Thresholds:
+ *   - >= 10  → plenty of room. (no urgency)
+ *   - 5..9   → pace yourself.
+ *   - 2..4   → start wrapping up — consolidate, avoid new tool calls.
+ *   - 0..1   → finalize NOW. Stop tooling, write the answer.
+ *
+ * Imperative phrasing matters: passing a bare count ("3 remaining") gets
+ * acknowledged but doesn't change behavior much. Pairing the count with a
+ * verb the model can act on ("start wrapping up", "finalize NOW") is what
+ * shifts the next-token distribution toward "emit final answer" instead
+ * of "call another tool". Exported so sub-agent / tests can share the
+ * exact phrasing if they need parity.
+ */
+export declare function iterationBudgetLine(remaining: number, max: number): string;
+/**
+ * Pick the right provider adapter for a resolved model id. DeepSeek's V4
+ * family uses `deepseek-*` ids; everything else (Anthropic claude-* + future
+ * direct full ids) falls through to the Anthropic adapter. Exported so tests
+ * can lock the dispatch shape independently of `maestroProvider`'s I/O.
+ */
+export declare function providerForModel(resolvedModel: string): Provider;
+/**
+ * Recognize the multiple shapes Node + WHATWG fetch use when a request is
+ * cancelled via `AbortController`:
+ *   - DOMException with name "AbortError" (fetch / EventSource)
+ *   - Error with name "AbortError" (older Node paths)
+ *   - DOMException with code 20 (legacy ABORT_ERR code)
+ *
+ * Catches both so the abort detection isn't tied to a single runtime.
+ *
+ * Exported for unit coverage — used internally by `maestroProvider`'s catch
+ * branch to distinguish a user-initiated abort from a real provider crash.
+ */
+export declare function isAbortError(err: unknown): boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,QAAQ,EAAyC,MAAM,kBAAkB,CAAC;AA0BxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAuB,eAAe,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAAC,YAAY,CAAC,CAsV5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAY1E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,CAKhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMlD"}

package/dist/provider.js

@@ -0,0 +1,444 @@
+import { randomUUID } from "node:crypto";
+import { AIAgent } from "./core/agent.js";
+import { runConversation } from "./core/loop.js";
+import { registerMcpTools, startMcpPool } from "./mcp/pool.js";
+import { buildSystemReminder } from "./memory/reminder.js";
+import { AnthropicProvider, effortToMaxIter, effortToThinkingBudget, } from "./providers/anthropic.js";
+import { DeepseekProvider } from "./providers/deepseek.js";
+import { maestroRegistry } from "./registry.js";
+import { isWellFormedMessage, loadMaestroSession, saveMaestroSession, trimToSafePrefix, } from "./session-store.js";
+import { curateSkills } from "./skills/curator.js";
+import { buildSkillsIndex } from "./skills/index-builder.js";
+import { loadSkillsCached } from "./skills/loader.js";
+import { getTodoStore } from "./state/todos.js";
+import { createAgentTool } from "./tools/builtin/agent.js";
+import { bashTool } from "./tools/builtin/bash.js";
+import { createEditTool } from "./tools/builtin/edit.js";
+import { createReadTool } from "./tools/builtin/read.js";
+import { createSkillViewTool } from "./tools/builtin/skill_view.js";
+import { createTodoWriteTool } from "./tools/builtin/todo_write.js";
+import { webFetchTool } from "./tools/builtin/web_fetch.js";
+import { createWriteTool } from "./tools/builtin/write.js";
+import { getFileStateTracker } from "./tools/file-state.js";
+import { createSandboxFsHook } from "./tools/hooks/sandbox-fs.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { logger } from "./platform/logger.js";
+import { getMcpServersForQuery } from "./platform/mcp-config.js";
+/**
+ * Maestro SDK provider (TS port of Maestro Agent v0.13.0).
+ *
+ * Multi-turn resume: when `opts.sessionId` is set we hydrate prior messages
+ * from `~/.maestro/sessions/<id>.jsonl` (written by the previous turn's
+ * persistence path or by a cross-agent rollout). Otherwise we mint a fresh
+ * UUIDv4 — matching the contract claude/codex providers expose, so the
+ * router stays agent-agnostic and `{type:"session", sessionId}` always comes
+ * back on the first iteration.
+ *
+ * After the loop drains we write the updated history back to disk so a
+ * subsequent call resumes correctly. Failures here are logged but never
+ * thrown — losing one persistence round is a degraded experience, not a
+ * stream-breaking one.
+ *
+ * MCP integration: every server in `getMcpServersForQuery(opts)` is leased
+ * from the process-wide cache (`mcp/pool-cache.ts`) and its tools are
+ * registered under `mcp__<server>__<tool>` — the same name convention Claude
+ * SDK uses, so the model sees consistent tool names across providers in the
+ * same topic. Unlike claudeProvider / codexProvider — which hand `mcpServers`
+ * to a vendor SDK that owns MCP lifecycle internally — Maestro hits Anthropic's
+ * Messages API via raw fetch, so we own startup + dispatch + cleanup here.
+ * Cache key includes (userId, session, groupId) so two users never share an
+ * MCP client; the cache evicts idle clients via TTL + LRU cap so stale slots
+ * don't accumulate.
+ *
+ * Snapshot pinned to upstream Maestro v0.13.0 (MIT, Nous Research). See
+ * docs/maestro-integration.md for the porting roadmap.
+ */
+export async function* maestroProvider(opts) {
+    // Provider instantiation is deferred until after model resolution so the
+    // right adapter (Anthropic / DeepSeek) is chosen based on the resolved
+    // model id. The env-var check happens at fromEnv() time inside each
+    // adapter — we surface its error as a normal `error` UnifiedEvent so the
+    // dispatcher doesn't see a synthetic crash.
+    // Resolve sessionId up-front so per-session resources (file-state tracker,
+    // skill_view) can key off a stable id. Either supplied by the caller
+    // (resume / cross-agent bridge) or minted now for a fresh session.
+    const sessionId = opts.sessionId ?? randomUUID();
+    // Per-session file-state tracker drives the Read-before-Edit gate. Module-
+    // level registry (see tools/file-state.ts) keeps the tracker alive across
+    // turns so a Read in turn N is still recorded when an Edit fires in N+1.
+    const fileTracker = getFileStateTracker(sessionId);
+    // Per-session TodoWrite store. Same module-level cache pattern — the
+    // store hydrates from `~/.maestro/sessions/<sid>.todos.json` on first
+    // access so a multi-turn plan survives across calls.
+    const todoStore = getTodoStore(sessionId);
+    const tools = new ToolRegistry();
+    // Filesystem sandbox runs as a PreToolUse hook so every tool with a
+    // `file_path` argument (Read/Write/Edit + future FS-touching MCP tools)
+    // shares one gate. Registered first so it fires before any caller-added
+    // hook in this turn.
+    tools.use(createSandboxFsHook());
+    tools.register(bashTool);
+    // Read/Write/Edit/WebFetch — claude SDK parity builtins. Same name + schema
+    // so the model's pretrained instinct calls them with the right shape, and
+    // prompt cache keys line up across agents when a topic is bridged.
+    // Read/Write/Edit also gate on the workspace sandbox (inline today; future
+    // Phase 2.1 migrates to a hook) and on the per-session file-state tracker
+    // so Edit can't mutate a path that hasn't been Read in this session.
+    tools.register(createReadTool({ tracker: fileTracker }));
+    tools.register(createWriteTool({ tracker: fileTracker }));
+    tools.register(createEditTool({ tracker: fileTracker }));
+    tools.register(webFetchTool);
+    tools.register(createTodoWriteTool({ store: todoStore }));
+    // --- Skills: load SKILL.md catalog + register `skill_view` ---------------
+    //
+    // Domain accuracy lever (Phase 2). The model gets:
+    //   - A `## Skills (mandatory)` block appended to the system prompt (60-char
+    //     summary per skill) so prefix caching covers the catalog across turns.
+    //   - A `skill_view(name)` builtin so it can pull the full SKILL.md body on
+    //     demand (progressive disclosure — saves the per-turn cost of inlining
+    //     every skill body).
+    //
+    // Source dir is picked from `MAESTRO_SKILL_DIR` first so power users can
+    // point at a Clawgram-local catalog later without code change; the v0.13.0
+    // upstream tree at `~/__KEEP_MAESTRO_AGENT__/skills/` is the current default.
+    //
+    // Failures (rootDir missing, unreadable, every file malformed) reduce to an
+    // empty catalog — the loop still runs with just bash + MCP tools.
+    const skillsDir = process.env.MAESTRO_SKILL_DIR ?? "/Users/maestrobot/__KEEP_MAESTRO_AGENT__/skills";
+    let skillsBlock = "";
+    // Hoisted to outer scope so the Agent tool (registered below, after
+    // model/effort resolve) can pass the same skill catalog to sub-agents.
+    let loadedSkills = [];
+    try {
+        const skills = loadSkillsCached(skillsDir);
+        loadedSkills = skills;
+        if (skills.length > 0) {
+            // Curator filters the catalog: archived skills (agent-created, never
+            // viewed, >60 days old) are dropped from the system-prompt index but
+            // stay reachable via skill_view by exact name. Bundled skills under
+            // the upstream snapshot directory are protected from archival.
+            // skill_view still sees the full set — model can resolve any name
+            // the user explicitly mentions even if it's been archived.
+            const curated = curateSkills(skills);
+            const visibleSkills = curated.map((c) => c.skill);
+            tools.register(createSkillViewTool({ skills, sessionId })); // full set
+            skillsBlock = buildSkillsIndex(visibleSkills);
+            logger.info({
+                agent: "maestro",
+                skillsDir,
+                skillCount: skills.length,
+                visibleCount: visibleSkills.length,
+                archivedCount: skills.length - visibleSkills.length,
+            }, "maestroProvider: skill catalog loaded (curated)");
+        }
+    }
+    catch (e) {
+        logger.warn({ err: e, skillsDir }, "maestroProvider: skill catalog load failed (degraded)");
+    }
+    // --- MCP pool: spawn every configured server, register their tools -------
+    //
+    // Failures here are logged but non-fatal: a turn can still serve from
+    // builtins alone if every server is unhealthy. This mirrors the partial-
+    // availability stance of the existing Playwright exit-propagation path,
+    // where one dead MCP doesn't take out the rest of the toolset.
+    let mcpPool = null;
+    try {
+        const servers = getMcpServersForQuery(opts);
+        // Scope cache to (userId, session, groupId, agentKind) so two users never
+        // share an MCP client (privacy) and so two sessions within one user keep
+        // their own playwright instance (forum/dm scope rules). The cache hashes
+        // the spec on top of this, so a server spec change inside the same scope
+        // also creates a fresh client.
+        mcpPool = await startMcpPool(servers, {
+            userId: opts.userId,
+            session: opts.session,
+            groupId: opts.groupId,
+            agentKind: "maestro",
+        });
+        registerMcpTools(tools, mcpPool, opts.abortController?.signal);
+        logger.info({
+            agent: "maestro",
+            mcpServerCount: mcpPool.clients.length,
+            mcpToolCount: mcpPool.tools.length,
+        }, "maestroProvider: MCP pool ready");
+    }
+    catch (e) {
+        logger.warn({ err: e }, "maestroProvider: MCP pool start failed — continuing without MCP");
+    }
+    const requestedModel = opts.model ?? maestroRegistry.defaultModel;
+    const resolvedModel = maestroRegistry.expandModelAlias(requestedModel);
+    // Resolve effort up-front (was previously deferred until after history
+    // hydration) so we can both build the initial system-reminder with the
+    // correct "iterations remaining: N/N" line and pass `maxIter` into
+    // `AIAgent` below. Default is the registry's `medium`, matching how
+    // claude-provider hands effort to its SDK when the caller doesn't pin one.
+    const resolvedEffort = opts.effort ?? maestroRegistry.defaultEffort;
+    const maxIter = effortToMaxIter(resolvedEffort);
+    // Pick provider by resolved model id prefix. DeepSeek models (`deepseek-*`)
+    // route to DeepseekProvider; anything else falls through to Anthropic. If
+    // the chosen adapter's env var is missing, close the MCP pool we already
+    // started before bailing so we don't leak subprocesses.
+    let provider;
+    try {
+        provider = providerForModel(resolvedModel);
+    }
+    catch (e) {
+        if (mcpPool) {
+            await mcpPool.close().catch((err) => {
+                logger.warn({ err }, "maestroProvider: mcp pool close after provider error failed");
+            });
+        }
+        yield {
+            type: "error",
+            content: e instanceof Error ? e.message : String(e),
+        };
+        return;
+    }
+    // --- Prior history hydration -------------------------------------------
+    //
+    // `sessionId` was already resolved at the top of this function so per-
+    // session resources (file-state tracker, skill_view) could be keyed off
+    // it. Three load cases for the persisted JSONL:
+    //   1. Caller supplied a sessionId AND file exists → resume.
+    //   2. Caller supplied a sessionId but file is missing/empty → keep the
+    //      id (so cross-agent set_agent's pre-registered DB id stays valid)
+    //      and start with empty history.
+    //   3. No sessionId → fresh UUIDv4 was minted above; no file to load.
+    const persisted = opts.sessionId ? loadMaestroSession(opts.sessionId) : null;
+    const priorMessages = (persisted ?? []).filter(isWellFormedMessage);
+    // Attach a `<system-reminder>` text block AFTER the user prompt on every
+    // new turn. Two reasons this lives at push time rather than on-wire:
+    //   1. Anthropic's automatic prompt cache breaks at the first byte
+    //      divergence — past-turn user messages must be stable across future
+    //      calls. Mutating wireMessages would make turn N's message differ
+    //      between turn N's call (with reminder) and turn N+1's call (without
+    //      reminder once canonical re-renders), nuking cache hits.
+    //   2. Compactor preserves the most-recent user message; the reminder
+    //      rides along automatically. Historical turns keep the reminder
+    //      that was true at THAT turn (sandbox could have flipped since) —
+    //      drift across env-var changes is feature, not bug.
+    // Claude Code places `<system-reminder>` at the tail of user content; we
+    // match that order so the model's pretrained intuition treats the
+    // reminder as meta annotation, not as user intent.
+    // The reminder carries the iteration budget so the model can self-pace
+    // ("8 left → wrap up", "90 left → take your time"). Closure shared with
+    // the per-iteration builder below so first-turn and subsequent-turn
+    // reminders render with identical shape — the model sees the same fields
+    // in the same order, only the counts change.
+    const buildIterReminder = (iterationsRemaining) => buildSystemReminder({
+        sessionId,
+        todos: todoStore.list(),
+        extras: [iterationBudgetLine(iterationsRemaining, maxIter)],
+    });
+    const reminderText = buildIterReminder(maxIter);
+    const userBlocks = [
+        { type: "text", text: opts.prompt },
+        { type: "text", text: reminderText },
+    ];
+    const messages = [...priorMessages, { role: "user", content: userBlocks }];
+    // Emit the session event before the first provider call so the router's
+    // recorder captures it in the unified conversation log — same shape as
+    // claude/codex `init` and `thread.started` events.
+    yield { type: "session", sessionId };
+    // Skills index goes into the system prompt (NOT a user message) so
+    // Anthropic's prefix cache covers it across every turn — the catalog only
+    // changes when SKILL.md files on disk change, while user messages roll
+    // every turn. Append, don't prepend: caller-supplied systemPrompt is
+    // identity / instructions that should still anchor the prompt, and the
+    // skills block reads naturally as a final "and also, here's what tools
+    // you have access to" section.
+    const augmentedSystemPrompt = skillsBlock
+        ? `${opts.systemPrompt}\n\n${skillsBlock}`
+        : opts.systemPrompt;
+    // Register the `Agent` tool last — it captures the resolved model,
+    // effort, augmented system prompt (parent base for sub-agents), and the
+    // already-loaded skill catalog. Registered only on the PARENT call;
+    // sub-agents do NOT get an Agent tool because `runSubAgent` builds its
+    // own registry without registering one (advisor: depth=1 cap).
+    tools.register(createAgentTool({
+        parent: {
+            parentSessionId: sessionId,
+            parentSystemPrompt: augmentedSystemPrompt,
+            parentModel: resolvedModel,
+            ...(resolvedEffort ? { parentEffort: resolvedEffort } : {}),
+            ...(opts.abortController?.signal ? { parentAbortSignal: opts.abortController.signal } : {}),
+            skills: loadedSkills,
+        },
+    }));
+    const thinkingBudget = effortToThinkingBudget(resolvedEffort);
+    const agent = new AIAgent(provider, tools, {
+        model: resolvedModel,
+        systemPrompt: augmentedSystemPrompt,
+        // Effort-derived tool-iteration cap. The model sees the same number via
+        // the per-iteration `<system-reminder>` (see `buildIterReminder` above)
+        // so it can self-pace — low effort tells it to wrap up fast, xhigh
+        // gives it room to dig.
+        maxIterations: maxIter,
+        buildIterReminder,
+        ...(thinkingBudget ? { thinkingBudget } : {}),
+        ...(resolvedEffort ? { effort: resolvedEffort } : {}),
+        ...(opts.abortController?.signal ? { abortSignal: opts.abortController.signal } : {}),
+    });
+    // Wire abort → close MCP pool early. Without this, an aborted turn could
+    // leave Playwright / OCR subprocesses spinning until the finally block,
+    // which only runs after the loop's awaited operation completes.
+    const abortSignal = opts.abortController?.signal;
+    const onAbortClosePool = () => {
+        if (mcpPool) {
+            mcpPool.close().catch((err) => {
+                logger.warn({ err }, "maestroProvider: mcp pool close on abort failed");
+            });
+        }
+    };
+    abortSignal?.addEventListener("abort", onAbortClosePool, { once: true });
+    logger.info({
+        agent: "maestro",
+        model: resolvedModel,
+        effort: resolvedEffort,
+        maxIter,
+        thinkingBudget: thinkingBudget ?? null,
+        sessionId,
+        session: opts.session ?? null,
+        resumed: priorMessages.length > 0,
+        priorTurns: priorMessages.length,
+    }, "maestroProvider: starting run_conversation");
+    let drained = false;
+    let aborted = false;
+    try {
+        for await (const event of runConversation(agent, messages)) {
+            yield event;
+        }
+        drained = true;
+    }
+    catch (e) {
+        // Abort is a user-initiated signal, not a provider failure. claude/codex
+        // both silently return on AbortError (claude-provider relies on the SDK
+        // closing the stream, codex-provider catches `err.name === "AbortError"`
+        // and returns without yielding). Match that so the dispatcher doesn't
+        // see a synthetic "maestroProvider crashed: The operation was aborted"
+        // error event after the user simply moved on to a new prompt.
+        if (isAbortError(e) || abortSignal?.aborted) {
+            aborted = true;
+        }
+        else {
+            yield {
+                type: "error",
+                content: `maestroProvider crashed: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+    }
+    finally {
+        abortSignal?.removeEventListener("abort", onAbortClosePool);
+        if (mcpPool) {
+            await mcpPool.close();
+        }
+        // Always persist a safe prefix — even on partial drain (abort mid-tool,
+        // Anthropic API throw, MCP crash). Earlier versions gated on
+        // `drained === true` to avoid persisting half-finished tool rounds, but
+        // in practice that gate dropped the entire turn on every abort and
+        // users saw "maestro forgets everything I just said". The new contract:
+        //   - clean drain → save messages verbatim (no change)
+        //   - partial / crashed turn → `trimToSafePrefix` strips orphan
+        //     user-prompt or assistant-tool_use trailing entries so the next
+        //     resume passes Anthropic's tool_use/tool_result pairing check
+        // If the trim collapses everything (e.g. the only push before the
+        // crash was the new user prompt), we skip the write so the previous
+        // good checkpoint stays intact.
+        try {
+            const safePrefix = drained ? messages : trimToSafePrefix(messages);
+            if (safePrefix.length > 0) {
+                saveMaestroSession(sessionId, safePrefix);
+                if (!drained && safePrefix.length < messages.length) {
+                    logger.info({
+                        sessionId,
+                        fullLength: messages.length,
+                        savedLength: safePrefix.length,
+                        dropped: messages.length - safePrefix.length,
+                        aborted,
+                    }, "maestroProvider: persisted trimmed prefix after partial turn");
+                }
+            }
+        }
+        catch (err) {
+            logger.warn({ err, sessionId, turns: messages.length }, "maestroProvider: persist failed (best-effort)");
+        }
+    }
+}
+/**
+ * Compose the "Tool iterations remaining: N/M — <tone>" line that rides
+ * inside the per-iteration `<system-reminder>` block. Tone shifts with
+ * ABSOLUTE remaining count (not percentage of maxIter) — same threshold
+ * fires the same urgency regardless of effort level, so the model gets a
+ * consistent cue from a `low` run reaching 4-left as from a `xhigh` run
+ * reaching 4-left.
+ *
+ * Why absolute, not relative: at `low` (maxIter=5) the model crosses the
+ * wrap-up line almost immediately; at `xhigh` (maxIter=90) 75% left lasts
+ * ~22 turns. The user-visible behavior the threshold is targeting is "how
+ * many tool calls before I MUST stop" — that's an absolute count, not a
+ * fraction.
+ *
+ * Thresholds:
+ *   - >= 10  → plenty of room. (no urgency)
+ *   - 5..9   → pace yourself.
+ *   - 2..4   → start wrapping up — consolidate, avoid new tool calls.
+ *   - 0..1   → finalize NOW. Stop tooling, write the answer.
+ *
+ * Imperative phrasing matters: passing a bare count ("3 remaining") gets
+ * acknowledged but doesn't change behavior much. Pairing the count with a
+ * verb the model can act on ("start wrapping up", "finalize NOW") is what
+ * shifts the next-token distribution toward "emit final answer" instead
+ * of "call another tool". Exported so sub-agent / tests can share the
+ * exact phrasing if they need parity.
+ */
+export function iterationBudgetLine(remaining, max) {
+    let tone;
+    if (remaining >= 10) {
+        tone = "plenty of room.";
+    }
+    else if (remaining >= 5) {
+        tone = "pace yourself.";
+    }
+    else if (remaining >= 2) {
+        tone = "start wrapping up — consolidate findings, avoid new tool calls unless essential.";
+    }
+    else {
+        tone = "finalize NOW. Stop tooling and write the final answer.";
+    }
+    return `Tool iterations remaining: ${remaining}/${max} — ${tone}`;
+}
+/**
+ * Pick the right provider adapter for a resolved model id. DeepSeek's V4
+ * family uses `deepseek-*` ids; everything else (Anthropic claude-* + future
+ * direct full ids) falls through to the Anthropic adapter. Exported so tests
+ * can lock the dispatch shape independently of `maestroProvider`'s I/O.
+ */
+export function providerForModel(resolvedModel) {
+    if (resolvedModel.startsWith("deepseek-")) {
+        return DeepseekProvider.fromEnv();
+    }
+    return AnthropicProvider.fromEnv();
+}
+/**
+ * Recognize the multiple shapes Node + WHATWG fetch use when a request is
+ * cancelled via `AbortController`:
+ *   - DOMException with name "AbortError" (fetch / EventSource)
+ *   - Error with name "AbortError" (older Node paths)
+ *   - DOMException with code 20 (legacy ABORT_ERR code)
+ *
+ * Catches both so the abort detection isn't tied to a single runtime.
+ *
+ * Exported for unit coverage — used internally by `maestroProvider`'s catch
+ * branch to distinguish a user-initiated abort from a real provider crash.
+ */
+export function isAbortError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (e.name === "AbortError")
+        return true;
+    if (e.code === 20 || e.code === "ABORT_ERR")
+        return true;
+    return false;
+}
+//# sourceMappingURL=provider.js.map