maestro-agent-sdk 0.1.0

package/dist/mcp/pool.js

@@ -0,0 +1,86 @@
+import { getOrStartClient, releaseClient } from "../mcp/pool-cache.js";
+import { logger } from "../platform/logger.js";
+/**
+ * Acquire a lease on every MCP server in `servers` from the cache and collect
+ * their tool schemas. On cache miss the server is spawned fresh; on hit the
+ * pre-warmed client is reused (no spawn cost, no handshake cost).
+ *
+ * Failure isolation: one server failing to start does not abort the others,
+ * we log and continue. Partial MCP availability is preferable to losing the
+ * whole toolset for a turn — same stance as the pre-cache implementation and
+ * the Playwright exit-propagation path.
+ *
+ * `ctx` scopes the cache key. Pass userId/session/groupId from `AgentQueryOptions`.
+ * Same spec across two contexts ⇒ two separate cached clients (correct: e.g.
+ * playwright stdio with `--user-data-dir` differs per user-session anyway, but
+ * scoping by context keeps the invariant even when specs happen to match).
+ */
+export async function startMcpPool(servers, ctx = {}) {
+    const clients = [];
+    const tools = [];
+    const entries = Object.entries(servers ?? {});
+    const results = await Promise.allSettled(entries.map(async ([name, spec]) => {
+        const client = await getOrStartClient(ctx, name, spec);
+        const ts = await client.listTools();
+        return { client, tools: ts };
+    }));
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const name = entries[i][0];
+        if (r.status === "rejected") {
+            logger.warn({ err: r.reason, server: name }, "maestro mcp pool: server failed to start, skipping");
+            continue;
+        }
+        clients.push(r.value.client);
+        tools.push(...r.value.tools);
+    }
+    let closed = false;
+    return {
+        clients,
+        tools,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            // Release leases — actual client.close() runs in pool-cache.ts when the
+            // idle TTL elapses or LRU cap is exceeded.
+            for (const c of clients)
+                releaseClient(c);
+        },
+    };
+}
+/**
+ * Register every MCP tool in the pool into the given Maestro ToolRegistry.
+ *
+ * Name collisions (e.g. a builtin already owns the same prefixed name) are
+ * logged and skipped rather than thrown — builtins win because they're more
+ * stable than MCP servers that come and go per turn.
+ *
+ * Optional `abortSignal` is forwarded into every MCP `tools/call` so a
+ * Maestro-level abort cancels in-flight JSON-RPC requests instead of leaving
+ * them blocked on a dead/slow server. The cached client itself stays alive —
+ * only the in-flight RPC is cancelled, so the next turn can reuse it.
+ */
+export function registerMcpTools(registry, pool, abortSignal) {
+    const byName = new Map(pool.clients.map((c) => [c.name, c]));
+    for (const t of pool.tools) {
+        if (registry.has(t.schema.name)) {
+            logger.warn({ name: t.schema.name, server: t.serverName }, "maestro mcp pool: tool name collision — skipping");
+            continue;
+        }
+        const handler = {
+            schema: t.schema,
+            async execute(input) {
+                const client = byName.get(t.serverName);
+                if (!client) {
+                    return JSON.stringify({
+                        error: `mcp client '${t.serverName}' not available`,
+                    });
+                }
+                return client.callTool(t.originalName, input, abortSignal);
+            },
+        };
+        registry.register(handler);
+    }
+}
+//# sourceMappingURL=pool.js.map

package/dist/mcp/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/mcp/pool.ts"],"names":[],"mappings":"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"}

package/dist/media/file-events.d.ts

@@ -0,0 +1,8 @@
+import type { UnifiedEvent } from "../types.js";
+/**
+ * Yield `file` events for every `[FILE:/path]` tag found in `text`.
+ * Providers call this when the host needs to react to file references the
+ * model emits inline (preview, attachment upload, etc).
+ */
+export declare function extractFileEvents(text: string, source: string): Generator<UnifiedEvent>;
+//# sourceMappingURL=file-events.d.ts.map

package/dist/media/file-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-events.d.ts","sourceRoot":"","sources":["../../src/media/file-events.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,wBAAiB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,CAOxF"}

package/dist/media/file-events.js

@@ -0,0 +1,15 @@
+import { FILE_TAG_REGEX } from "../platform/config.js";
+/**
+ * Yield `file` events for every `[FILE:/path]` tag found in `text`.
+ * Providers call this when the host needs to react to file references the
+ * model emits inline (preview, attachment upload, etc).
+ */
+export function* extractFileEvents(text, source) {
+    const tagRegex = new RegExp(FILE_TAG_REGEX.source, "gi");
+    let match = tagRegex.exec(text);
+    while (match !== null) {
+        yield { type: "file", path: match[1], source, origin: "tag" };
+        match = tagRegex.exec(text);
+    }
+}
+//# sourceMappingURL=file-events.js.map

package/dist/media/file-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-events.js","sourceRoot":"","sources":["../../src/media/file-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;;;GAIG;AACH,MAAM,SAAS,CAAC,CAAC,iBAAiB,CAAC,IAAY,EAAE,MAAc;IAC7D,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzD,IAAI,KAAK,GAA2B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,KAAK,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC9D,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/memory/active-task-template.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Active Task template — the system prompt fed to the auxiliary LLM that
+ * compresses prior conversation history into a single structured summary
+ * block.
+ *
+ * Why a structured template rather than a free-form "summarize this"?
+ *   - Free-form summaries drift in shape between turns, which means the
+ *     compressed prefix changes across compactions and breaks Anthropic
+ *     prompt-cache hits on the cached body. Fixed headers stabilize the
+ *     cacheable prefix.
+ *   - The model needs to know not just what happened but **what's still
+ *     pending**. Without an explicit "Pending" section the summary
+ *     degenerates into a recap; the model loses track of the actual task
+ *     it should be working on next.
+ *   - The headers (Active Task / Goal / Pending / Files / Recent context)
+ *     match the structure upstream uses, calibrated against many real
+ *     compaction events on long sessions.
+ *
+ * Upstream reference: `/Users/maestrobot/__KEEP_MAESTRO_AGENT__/agent/context_compressor.py`
+ * (look for the "ACTIVE_TASK_SUMMARY_TEMPLATE" / "compression_system_prompt"
+ * constants). We keep the schema verbatim so summaries between agents stay
+ * mutually intelligible if the topic later switches via set_agent.
+ */
+export declare const ACTIVE_TASK_TEMPLATE = "You are compressing a long agent conversation so the main agent can continue\nwithout losing context. Produce a single concise summary using EXACTLY these\nsection headers, in this order:\n\n## Active Task\nOne sentence: what is the agent currently working on?\n\n## Goal\nOne or two sentences: the user's overall objective in this session.\n\n## Pending\nBulleted list of unresolved items, decisions to make, or work explicitly\ndeferred. Use \"(blocked: <reason>)\" when applicable.\n\n## Files\nBulleted list of `absolute/paths` touched or referenced (read, written,\ninspected). Skip if none.\n\n## Recent context\n3\u20135 bullets capturing the most recent tool calls + their salient outputs.\nPrefer specifics (paths, line numbers, exit codes, key values) over generic\nrecaps. Skip details that have no bearing on the next step.\n\nRULES:\n- Output ONLY the five sections above, with no preamble or postscript.\n- Do NOT echo the user's words verbatim \u2014 paraphrase tightly.\n- Do NOT invent file paths or facts not present in the transcript.\n- Keep the entire summary under 1500 words.";
+/** Header line for the summary user message that the main loop sees in
+ *  place of the compressed history. Surrounded by visible markers so the
+ *  main model recognizes this as a system-injected compaction, not normal
+ *  user input. Matches upstream's fence convention so cross-agent rollouts
+ *  reading our compacted maestro session see a familiar marker. */
+export declare const COMPACTED_MARKER_OPEN = "<compacted-history>";
+export declare const COMPACTED_MARKER_CLOSE = "</compacted-history>";
+/** Wrap a raw summary in the fence the main loop expects on the next turn. */
+export declare function wrapCompactedSummary(summary: string): string;
+//# sourceMappingURL=active-task-template.d.ts.map

package/dist/memory/active-task-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-task-template.d.ts","sourceRoot":"","sources":["../../src/memory/active-task-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,oBAAoB,+kCA2BW,CAAC;AAE7C;;;;mEAImE;AACnE,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAC3D,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/memory/active-task-template.js

@@ -0,0 +1,63 @@
+/**
+ * Active Task template — the system prompt fed to the auxiliary LLM that
+ * compresses prior conversation history into a single structured summary
+ * block.
+ *
+ * Why a structured template rather than a free-form "summarize this"?
+ *   - Free-form summaries drift in shape between turns, which means the
+ *     compressed prefix changes across compactions and breaks Anthropic
+ *     prompt-cache hits on the cached body. Fixed headers stabilize the
+ *     cacheable prefix.
+ *   - The model needs to know not just what happened but **what's still
+ *     pending**. Without an explicit "Pending" section the summary
+ *     degenerates into a recap; the model loses track of the actual task
+ *     it should be working on next.
+ *   - The headers (Active Task / Goal / Pending / Files / Recent context)
+ *     match the structure upstream uses, calibrated against many real
+ *     compaction events on long sessions.
+ *
+ * Upstream reference: `/Users/maestrobot/__KEEP_MAESTRO_AGENT__/agent/context_compressor.py`
+ * (look for the "ACTIVE_TASK_SUMMARY_TEMPLATE" / "compression_system_prompt"
+ * constants). We keep the schema verbatim so summaries between agents stay
+ * mutually intelligible if the topic later switches via set_agent.
+ */
+export const ACTIVE_TASK_TEMPLATE = `You are compressing a long agent conversation so the main agent can continue
+without losing context. Produce a single concise summary using EXACTLY these
+section headers, in this order:
+
+## Active Task
+One sentence: what is the agent currently working on?
+
+## Goal
+One or two sentences: the user's overall objective in this session.
+
+## Pending
+Bulleted list of unresolved items, decisions to make, or work explicitly
+deferred. Use "(blocked: <reason>)" when applicable.
+
+## Files
+Bulleted list of \`absolute/paths\` touched or referenced (read, written,
+inspected). Skip if none.
+
+## Recent context
+3–5 bullets capturing the most recent tool calls + their salient outputs.
+Prefer specifics (paths, line numbers, exit codes, key values) over generic
+recaps. Skip details that have no bearing on the next step.
+
+RULES:
+- Output ONLY the five sections above, with no preamble or postscript.
+- Do NOT echo the user's words verbatim — paraphrase tightly.
+- Do NOT invent file paths or facts not present in the transcript.
+- Keep the entire summary under 1500 words.`;
+/** Header line for the summary user message that the main loop sees in
+ *  place of the compressed history. Surrounded by visible markers so the
+ *  main model recognizes this as a system-injected compaction, not normal
+ *  user input. Matches upstream's fence convention so cross-agent rollouts
+ *  reading our compacted maestro session see a familiar marker. */
+export const COMPACTED_MARKER_OPEN = "<compacted-history>";
+export const COMPACTED_MARKER_CLOSE = "</compacted-history>";
+/** Wrap a raw summary in the fence the main loop expects on the next turn. */
+export function wrapCompactedSummary(summary) {
+    return `${COMPACTED_MARKER_OPEN}\n${summary.trim()}\n${COMPACTED_MARKER_CLOSE}`;
+}
+//# sourceMappingURL=active-task-template.js.map

package/dist/memory/active-task-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-task-template.js","sourceRoot":"","sources":["../../src/memory/active-task-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA2BQ,CAAC;AAE7C;;;;mEAImE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAC3D,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAE7D,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,GAAG,qBAAqB,KAAK,OAAO,CAAC,IAAI,EAAE,KAAK,sBAAsB,EAAE,CAAC;AAClF,CAAC"}

package/dist/memory/compressor.d.ts

@@ -0,0 +1,87 @@
+import type { Provider, ProviderMessage } from "../providers/base.js";
+/**
+ * Maestro context auto-compaction.
+ *
+ * When estimated tokens exceed `triggerRatio` × `contextWindow`, dispatch a
+ * cheap aux LLM (default `claude-haiku-4-5-...`) to summarize the middle
+ * slice of the conversation into the Active Task template, then return a
+ * new message array shaped as:
+ *
+ *   [ ...head_protected, { role: "user", content: "<compacted-history>..." },
+ *     ...tail_protected ]
+ *
+ * Head + tail protection rationale:
+ *   - Head: the first user prompt + first assistant turn anchor the user's
+ *     actual ask. Losing them to summarization makes the next compaction
+ *     produce a recap with no goal, which cascades into hallucination.
+ *   - Tail: the last few turns are the model's working memory; folding them
+ *     into a summary destroys the in-progress reasoning.
+ *
+ * The middle is what gets compressed. We feed the aux LLM the raw
+ * ProviderMessage[] slice (with the Active Task system prompt) and replace
+ * it in the returned array with a single user message containing the fenced
+ * summary. Anthropic's tool_use/tool_result pairing requirement is
+ * preserved by snapping head/tail boundaries to message boundaries (we
+ * never split a user/assistant pair).
+ *
+ * Fallbacks:
+ *   - Already below threshold → return input as-is (no LLM call).
+ *   - Aux LLM call fails → fall back to pruneMessages only and log a
+ *     warning. The turn proceeds; we never throw because that would break
+ *     the user's in-flight conversation over an optimization.
+ *   - Compacted result is *larger* than the input (degenerate aux output)
+ *     → discard compaction and return pruned-only.
+ *
+ * The compactor itself is pure with respect to the caller's array: it
+ * builds and returns a new array. Caller's persistence path keeps the
+ * canonical (uncompacted) history on disk so resume can replay the full
+ * thread if desired.
+ *
+ * Upstream reference: `/Users/maestrobot/__KEEP_MAESTRO_AGENT__/agent/context_compressor.py`
+ * — the `should_compress(real_tokens)` → `compress_messages()` path, minus
+ * the multi-provider tokenizer plumbing (we estimate; see token-estimate.ts).
+ */
+export interface CompressOptions {
+    /** Model context window in tokens. Default reads `MAESTRO_CONTEXT_WINDOW`
+     *  env (Sonnet 4.6 default = 200_000). */
+    contextWindow?: number;
+    /** Compaction triggers when estimated tokens / window ≥ this ratio.
+     *  Default 0.8 — matches upstream and leaves enough headroom for the
+     *  current turn's prompt + response to fit inside the cap. */
+    triggerRatio?: number;
+    /** Number of HEAD messages preserved verbatim. Default 2 (first user
+     *  prompt + first assistant turn). */
+    headProtect?: number;
+    /** Number of TAIL messages preserved verbatim. Default 6 (~ last 3 turns
+     *  of user/assistant alternation). */
+    tailProtect?: number;
+    /** Aux model id for the summarization call. Default `MODEL_HAIKU`. */
+    auxModel?: string;
+    /** Inject a different provider for tests. Defaults to a fresh
+     *  `AnthropicProvider.fromEnv()` reuse-of-the-main-provider via DI. */
+    auxProvider?: Provider;
+    /** Disable pruning fallback when aux LLM fails. Tests use this to verify
+     *  the fallback path exits cleanly without re-pruning. */
+    disablePruneFallback?: boolean;
+    /** Abort signal for the aux summarization request. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Run the auto-compaction pipeline.
+ *
+ * Steps:
+ *   1. Apply `pruneMessages` first — pass 1+2 are cheap and frequently
+ *      bring the wire size below the trigger ratio on their own.
+ *   2. Re-estimate tokens. If below threshold, return the pruned array.
+ *   3. Otherwise slice head + tail and dispatch the aux LLM to summarize
+ *      the middle. Reconstruct as [head, summary user message, tail].
+ *   4. Anti-thrash: if two consecutive compactions on this array saved
+ *      <10%, drop back to prune-only and stop calling the aux LLM until
+ *      the caller hands us a different array reference.
+ *
+ * Returns a new array — caller is responsible for using the returned slice
+ * on the wire and keeping the unmodified canonical history for persistence.
+ */
+export declare function compressIfNeeded(messages: ProviderMessage[], opts?: CompressOptions): Promise<ProviderMessage[]>;
+export declare function __resetCompactorState(messages: ProviderMessage[]): void;
+//# sourceMappingURL=compressor.d.ts.map

package/dist/memory/compressor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compressor.d.ts","sourceRoot":"","sources":["../../src/memory/compressor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAwB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAIxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,MAAM,WAAW,eAAe;IAC9B;8CAC0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;kEAE8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;0CACsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;0CACsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;2EACuE;IACvE,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB;8DAC0D;IAC1D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,sDAAsD;IACtD,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AA0BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,eAAe,EAAE,EAC3B,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC,CA6G5B;AAoCD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,IAAI,CAEvE"}

package/dist/memory/compressor.js

@@ -0,0 +1,164 @@
+import { ACTIVE_TASK_TEMPLATE, wrapCompactedSummary } from "../memory/active-task-template.js";
+import { pruneMessages } from "../memory/prune.js";
+import { estimateTokens } from "../memory/token-estimate.js";
+import { MODEL_HAIKU } from "../platform/config.js";
+import { logger } from "../platform/logger.js";
+const compactorAntiThrash = new WeakMap();
+/** A compaction that doesn't save at least this fraction of tokens is
+ *  considered ineffective and counts toward backoff. */
+const COMPACTOR_MIN_SAVINGS_RATIO = 0.1;
+/** Two consecutive ineffective calls on the same array → bail out and just
+ *  prune. */
+const COMPACTOR_ANTI_THRASH_LIMIT = 2;
+function defaultContextWindow() {
+    const env = process.env.MAESTRO_CONTEXT_WINDOW;
+    if (env) {
+        const n = Number.parseInt(env, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 200_000;
+}
+/**
+ * Run the auto-compaction pipeline.
+ *
+ * Steps:
+ *   1. Apply `pruneMessages` first — pass 1+2 are cheap and frequently
+ *      bring the wire size below the trigger ratio on their own.
+ *   2. Re-estimate tokens. If below threshold, return the pruned array.
+ *   3. Otherwise slice head + tail and dispatch the aux LLM to summarize
+ *      the middle. Reconstruct as [head, summary user message, tail].
+ *   4. Anti-thrash: if two consecutive compactions on this array saved
+ *      <10%, drop back to prune-only and stop calling the aux LLM until
+ *      the caller hands us a different array reference.
+ *
+ * Returns a new array — caller is responsible for using the returned slice
+ * on the wire and keeping the unmodified canonical history for persistence.
+ */
+export async function compressIfNeeded(messages, opts = {}) {
+    const contextWindow = opts.contextWindow ?? defaultContextWindow();
+    const triggerRatio = opts.triggerRatio ?? 0.8;
+    const headProtect = opts.headProtect ?? 2;
+    const tailProtect = opts.tailProtect ?? 6;
+    const auxModel = opts.auxModel ?? MODEL_HAIKU;
+    // Step 1: prune first. Cheap and often enough.
+    const pruned = pruneMessages(messages);
+    const prunedTokens = estimateTokens(pruned);
+    const threshold = contextWindow * triggerRatio;
+    if (prunedTokens < threshold) {
+        return pruned;
+    }
+    // Anti-thrash check — bail if we already tried twice and it didn't help.
+    const state = compactorAntiThrash.get(messages);
+    if (state && state.failedCompactions >= COMPACTOR_ANTI_THRASH_LIMIT) {
+        return pruned;
+    }
+    // Step 2: validate we have something to compress. Need at least
+    // headProtect + 1 + tailProtect messages, otherwise the middle slice is
+    // empty and there's nothing to summarize.
+    const minSize = headProtect + 1 + tailProtect;
+    if (pruned.length < minSize) {
+        return pruned;
+    }
+    // Snap head/tail boundaries to safe split points. Anthropic rejects a
+    // request whose first message after the head isn't a user turn, and
+    // requires every tool_use to be answered by a tool_result on the next
+    // user turn. We never split a user→assistant or assistant→user(tool_result)
+    // pairing.
+    const headEnd = snapHeadEnd(pruned, headProtect);
+    const tailStart = snapTailStart(pruned, pruned.length - tailProtect);
+    if (tailStart <= headEnd) {
+        // Snapping collapsed the middle — nothing left to compress.
+        return pruned;
+    }
+    const head = pruned.slice(0, headEnd);
+    const middle = pruned.slice(headEnd, tailStart);
+    const tail = pruned.slice(tailStart);
+    // Step 3: aux LLM call.
+    if (!opts.auxProvider) {
+        // No provider supplied AND no factory available in production callers
+        // (maestroProvider passes its own AnthropicProvider). Without one we
+        // can't summarize — drop to pruned and log so the operator sees why.
+        logger.warn({ prunedTokens, threshold }, "compressIfNeeded: over threshold but no auxProvider supplied — falling back to prune-only");
+        return pruned;
+    }
+    let summaryText;
+    try {
+        const auxResponse = await opts.auxProvider.complete({
+            model: auxModel,
+            messages: middle,
+            system: ACTIVE_TASK_TEMPLATE,
+            maxTokens: 2048,
+            ...(opts.abortSignal ? { abortSignal: opts.abortSignal } : {}),
+        });
+        summaryText = extractText(auxResponse.content).trim();
+        if (!summaryText) {
+            throw new Error("aux LLM returned empty summary");
+        }
+    }
+    catch (err) {
+        logger.warn({ err, prunedTokens, threshold }, "compressIfNeeded: aux LLM call failed — returning prune-only fallback");
+        if (opts.disablePruneFallback)
+            return messages;
+        return pruned;
+    }
+    const compacted = [
+        ...head,
+        { role: "user", content: wrapCompactedSummary(summaryText) },
+        ...tail,
+    ];
+    const compactedTokens = estimateTokens(compacted);
+    // Degenerate aux output: compaction made things bigger or barely smaller.
+    // Discard and fall back to prune-only.
+    const savings = prunedTokens - compactedTokens;
+    const ratio = savings / prunedTokens;
+    if (ratio < COMPACTOR_MIN_SAVINGS_RATIO) {
+        const next = state ?? { failedCompactions: 0 };
+        next.failedCompactions++;
+        compactorAntiThrash.set(messages, next);
+        logger.info({ prunedTokens, compactedTokens, ratio, failedCompactions: next.failedCompactions }, "compressIfNeeded: low-savings compaction discarded — anti-thrash counter incremented");
+        return pruned;
+    }
+    // Successful compaction resets the anti-thrash counter.
+    if (state)
+        compactorAntiThrash.delete(messages);
+    logger.info({ prunedTokens, compactedTokens, ratio, headProtect, tailProtect, middleSize: middle.length }, "compressIfNeeded: applied aux-LLM compaction");
+    return compacted;
+}
+/**
+ * Walk forward from `idealEnd` to land on the first boundary where the next
+ * message is `role:"user"` (so the post-head slice starts cleanly with a
+ * user turn — Anthropic's pairing rules require it). Caps at `idealEnd + 4`
+ * so a pathological "all assistant" run can't push the head past the tail.
+ */
+function snapHeadEnd(messages, idealEnd) {
+    const cap = Math.min(messages.length, idealEnd + 4);
+    let i = Math.min(idealEnd, messages.length);
+    while (i < cap && messages[i] && messages[i].role !== "user")
+        i++;
+    return i;
+}
+/**
+ * Walk backward from `idealStart` until we land on a user turn — so the
+ * tail slice begins with a user turn (mirror of `snapHeadEnd`). Caps at
+ * `idealStart - 4` so the tail never grows unboundedly.
+ */
+function snapTailStart(messages, idealStart) {
+    const floor = Math.max(0, idealStart - 4);
+    let i = Math.max(idealStart, 0);
+    while (i > floor && messages[i] && messages[i].role !== "user")
+        i--;
+    return i;
+}
+/** Pull the concatenated text out of an aux LLM ProviderResponse. */
+function extractText(blocks) {
+    return blocks
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+}
+// Test-only: reset the WeakMap state for deterministic single-test runs.
+export function __resetCompactorState(messages) {
+    compactorAntiThrash.delete(messages);
+}
+//# sourceMappingURL=compressor.js.map

package/dist/memory/compressor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compressor.js","sourceRoot":"","sources":["../../src/memory/compressor.ts"],"names":[],"mappings":"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"}

package/dist/memory/hash.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Maestro memory hashing — md5 helpers for tool_result deduplication.
+ *
+ * We use md5 (truncated to 12 hex chars) for parity with upstream Maestro
+ * v0.13.0 `context_compressor.py::_prune_old_tool_results`. Collision risk at
+ * 12 hex (48 bits) is ~1e-4 at 65K entries — well above the per-session
+ * tool_result count we ever see in practice (tens, maybe low hundreds).
+ *
+ * Not cryptographic — pure non-malicious dedup. md5 picked over SHA-256
+ * because:
+ *   1. ~3x cheaper to compute on the per-turn hot path
+ *   2. Wire compat with the Python reference makes future cross-runtime
+ *      session-store inspection trivial
+ */
+/** Truncated md5 hex digest of a string. 12 chars = 48 bits — see header. */
+export declare function hashToolContent(content: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/memory/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/memory/hash.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/memory/hash.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+/**
+ * Maestro memory hashing — md5 helpers for tool_result deduplication.
+ *
+ * We use md5 (truncated to 12 hex chars) for parity with upstream Maestro
+ * v0.13.0 `context_compressor.py::_prune_old_tool_results`. Collision risk at
+ * 12 hex (48 bits) is ~1e-4 at 65K entries — well above the per-session
+ * tool_result count we ever see in practice (tens, maybe low hundreds).
+ *
+ * Not cryptographic — pure non-malicious dedup. md5 picked over SHA-256
+ * because:
+ *   1. ~3x cheaper to compute on the per-turn hot path
+ *   2. Wire compat with the Python reference makes future cross-runtime
+ *      session-store inspection trivial
+ */
+/** Truncated md5 hex digest of a string. 12 chars = 48 bits — see header. */
+export function hashToolContent(content) {
+    return createHash("md5").update(content, "utf8").digest("hex").slice(0, 12);
+}
+//# sourceMappingURL=hash.js.map

package/dist/memory/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/memory/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;GAaG;AAEH,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC"}