mixdog 0.7.18 → 0.8.1

package/src/agent/orchestrator/session/trim.mjs

@@ -1,491 +0,0 @@
-import { isOffloadedToolResultText } from './tool-result-offload.mjs';
-import { createHash } from 'node:crypto';
-
-// Rough token estimate: ~4 chars per token
-function estimateTokens(text) {
-    return Math.ceil(String(text ?? '').length / 4);
-}
-function messageEstimateText(m) {
-    if (!m || typeof m !== 'object') return '';
-    let text = typeof m.content === 'string' ? m.content : JSON.stringify(m.content ?? '');
-    if (m.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length) {
-        try { text += `\n${JSON.stringify(m.toolCalls)}`; }
-        catch { text += `\n[${m.toolCalls.length} tool calls]`; }
-    }
-    if (m.role === 'tool' && m.toolCallId) text += `\n${m.toolCallId}`;
-    return text;
-}
-function estimateMessageTokens(m) {
-    return estimateTokens(messageEstimateText(m)) + 4;
-}
-export function estimateMessagesTokens(messages) {
-    return messages.reduce((sum, m) => sum + estimateMessageTokens(m), 0);
-}
-
-// Per-request overhead the provider injects that never appears in the
-// `messages` array: function-calling preamble + system-prompt framing the
-// provider wraps around the request. The chars/4 message estimate misses all
-// of it, so a "fits" verdict computed from messages alone is optimistic.
-const REQUEST_OVERHEAD_TOKENS = 512;
-
-/**
- * Estimate the token cost of the tool/function schemas a provider appends to
- * the request body. These are NOT part of `messages` (they're a separate
- * argument to provider.send), so estimateMessagesTokens() ignores them
- * entirely — a transcript that "fits" by message tokens can still overflow
- * once N tool schemas are serialized into the same request. Best-effort
- * chars/4 over the JSON-serialized definitions.
- */
-export function estimateToolSchemaTokens(tools) {
-    if (!Array.isArray(tools) || tools.length === 0) return 0;
-    let text = '';
-    try { text = JSON.stringify(tools); }
-    catch { text = tools.map(t => String(t?.name ?? '')).join(''); }
-    return estimateTokens(text);
-}
-
-/**
- * Total headroom the caller should reserve out of the context window before
- * trimming: tool-schema bytes + fixed request framing overhead. Pass the
- * result as `opts.reserveTokens` to trimMessages so the working budget
- * accounts for request-side bytes the message estimate cannot see.
- */
-export function estimateRequestReserveTokens(tools) {
-    return estimateToolSchemaTokens(tools) + REQUEST_OVERHEAD_TOKENS;
-}
-const TOOL_MISSING_STUB = '[Older tool result dropped to fit the context window]';
-/**
- * Walk backward from `idx` past consecutive tool messages to the parent
- * assistant message that emitted the tool_calls. Returns an index that points
- * at (or before) that assistant so a byte-budget cut drops the group as a
- * unit rather than leaving orphan tool results. Returns `idx` unchanged if
- * we didn't land inside a group.
- */
-export function alignBoundaryBackward(messages, idx) {
-    if (!Array.isArray(messages) || idx <= 0 || idx >= messages.length) return idx;
-    let i = idx;
-    while (i > 0 && messages[i]?.role === 'tool') i--;
-    if (i === idx) return idx;
-    const anchor = messages[i];
-    if (anchor?.role === 'assistant' && Array.isArray(anchor.toolCalls) && anchor.toolCalls.length) {
-        return i;
-    }
-    return idx;
-}
-/**
- * Post-trim sanitization (Hermes `_sanitize_tool_pairs`):
- *   - Drop `tool` messages whose toolCallId has no surviving assistant tool_call.
- *   - For surviving assistant tool_calls whose results got trimmed, insert a
- *     stub tool message so the provider doesn't reject the request for
- *     unmatched tool_use_id.
- * Messages ordering is preserved; stubs are inserted immediately after the
- * assistant message so the tool pair sits adjacent.
- */
-export function sanitizeToolPairs(messages) {
-    if (!Array.isArray(messages) || messages.length === 0) return messages;
-    const assistantCallIds = new Set();
-    for (const m of messages) {
-        if (m.role === 'assistant' && Array.isArray(m.toolCalls)) {
-            for (const tc of m.toolCalls) {
-                if (tc && tc.id) assistantCallIds.add(tc.id);
-            }
-        }
-    }
-    const toolById = new Map();
-    for (const m of messages) {
-        if (m.role === 'tool' && m.toolCallId) toolById.set(m.toolCallId, m);
-    }
-    const filtered = messages.filter(m => {
-        if (m.role !== 'tool') return true;
-        if (!m.toolCallId) return true;
-        return assistantCallIds.has(m.toolCallId);
-    });
-    const result = [];
-    for (const m of filtered) {
-        result.push(m);
-        if (m.role !== 'assistant' || !Array.isArray(m.toolCalls)) continue;
-        for (const tc of m.toolCalls) {
-            if (!tc?.id) continue;
-            const existing = toolById.get(tc.id);
-            if (existing && filtered.includes(existing)) continue;
-            const preserved = existing?.content;
-            result.push({
-                role: 'tool',
-                content: isOffloadedToolResultText(preserved) ? preserved : TOOL_MISSING_STUB,
-                toolCallId: tc.id,
-            });
-        }
-    }
-    return result;
-}
-
-// Minimum body size to consider for hash-based dedup. Small results are
-// cheap to re-deliver and short strings often collide on trivial content
-// like "ok" or "done", so deduplicate only non-trivial bodies.
-const DEDUP_MIN_BYTES = 512;
-
-/**
- * Replace duplicate tool-result bodies (2nd+ occurrence of the same content
- * hash) with a compact reference stub. Hash-based dedup avoids re-delivering
- * large identical results (e.g. the same grep output called twice) while
- * keeping the first occurrence intact so the model still has the body.
- *
- * Skip conditions (structural — not heuristic prefix sniffing):
- *   - m.toolKind !== 'normal' (and defined): cache-hit / error / ref messages
- *     carry a structured kind annotation set by loop.mjs; skip them.
- *   - No toolKind (undefined): legacy or intra-turn-dedup stubs — apply dedup
- *     (backward compatible; the dedup body IS the meaningful result).
- *   - content.length < DEDUP_MIN_BYTES: structural cost optimization.
- *   - isOffloadedToolResultText(content): body is on disk, not inline.
- */
-export function dedupToolResultBodies(messages) {
-    if (!Array.isArray(messages) || messages.length === 0) return messages;
-    const seenHash = new Map(); // hash -> first toolCallId
-    return messages.map((m) => {
-        if (m?.role !== 'tool' || typeof m.content !== 'string') return m;
-        const content = m.content;
-        if (content.length < DEDUP_MIN_BYTES) return m;
-        if (isOffloadedToolResultText(content)) return m;
-        // Structural kind-based skip: non-normal kinds are already stubs/refs —
-        // deduping them would nest stubs inside stubs and confuse the model.
-        if (m.toolKind !== undefined && m.toolKind !== 'normal') return m;
-        const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
-        const first = seenHash.get(hash);
-        if (!first) {
-            seenHash.set(hash, m.toolCallId || '?');
-            return m;
-        }
-        const stub = `[duplicate-of tool_use_id=${first}] body identical to result of ${first} (sha256 prefix matches; ${content.length} bytes elided).`;
-        return { ...m, content: stub };
-    });
-}
-
-// Match the head of dedupToolResultBodies' stub body so we can detect whether
-// the referenced first-occurrence tool_use_id is still present after later
-// drop passes (safety loop, sanitize). Any stub pointing at an id no longer
-// in the message stream is reconciled back to TOOL_MISSING_STUB so the model
-// never sees `[duplicate-of call_X]` with no call_X.
-const DEDUP_STUB_HEAD_RE = /^\[duplicate-of tool_use_id=([^\]]+)\]/;
-export function reconcileDedupStubs(messages) {
-    if (!Array.isArray(messages) || messages.length === 0) return messages;
-    const presentIds = new Set();
-    for (const m of messages) {
-        if (m?.role === 'tool' && m.toolCallId) presentIds.add(m.toolCallId);
-    }
-    return messages.map((m) => {
-        if (m?.role !== 'tool' || typeof m.content !== 'string') return m;
-        const match = DEDUP_STUB_HEAD_RE.exec(m.content);
-        if (!match) return m;
-        if (presentIds.has(match[1])) return m;
-        return { ...m, content: TOOL_MISSING_STUB };
-    });
-}
-
-/**
- * Final-mile pairing for Anthropic API content arrays. Operates on the
- * already-converted format (role: assistant|user|system, content: block[])
- * — the mixdog-internal sanitizeToolPairs only sees toolCalls/toolCallId
- * fields and misses cases where tool_use blocks were pushed directly into
- * content (streaming chunk inserts, salvage paths, etc.). Without this
- * pass, an unmatched tool_use can reach the provider and trigger
- * `messages.N: tool_use ids were found without tool_result blocks
- * immediately after`.
- */
-export function sanitizeAnthropicContentPairs(messages) {
-    if (!Array.isArray(messages)) return messages;
-    const work = messages.slice();
-    const out = [];
-    for (let i = 0; i < work.length; i++) {
-        let m = work[i];
-        // Drop tool_use blocks without an id from assistant messages — these
-        // come from partial streaming chunks that never finalised, and the
-        // provider rejects them as `tool_use ids were found without
-        // tool_result blocks` even though no id was actually emitted.
-        if (m?.role === 'assistant' && Array.isArray(m.content)) {
-            const cleaned = m.content.filter(
-                (b) => !(b?.type === 'tool_use' && !b.id),
-            );
-            if (cleaned.length !== m.content.length) {
-                m = { ...m, content: cleaned };
-                work[i] = m;
-            }
-        }
-        out.push(m);
-        if (m?.role !== 'assistant' || !Array.isArray(m.content)) continue;
-        const toolUseIds = m.content
-            .filter((b) => b?.type === 'tool_use' && b.id)
-            .map((b) => b.id);
-        if (toolUseIds.length === 0) continue;
-        const next = work[i + 1];
-        const nextResultIds = (next?.role === 'user' && Array.isArray(next.content))
-            ? new Set(
-                next.content
-                    .filter((b) => b?.type === 'tool_result' && b.tool_use_id)
-                    .map((b) => b.tool_use_id),
-            )
-            : new Set();
-        const missing = toolUseIds.filter((id) => !nextResultIds.has(id));
-        const stubs = missing.map((id) => ({
-            type: 'tool_result',
-            tool_use_id: id,
-            content: '[tool_result missing — recovered by sanitizeAnthropicContentPairs]',
-            is_error: true,
-        }));
-        if (next?.role === 'user' && Array.isArray(next.content)) {
-            // Anthropic requires tool_result blocks to lead the user message
-            // when responding to a prior tool_use. Reorder even when no stub
-            // was needed; a matching tool_result after text still triggers the
-            // same `tool_use ids ... without tool_result blocks immediately
-            // after` rejection.
-            const existingResults = next.content.filter((b) => b?.type === 'tool_result');
-            const nonResults = next.content.filter((b) => b?.type !== 'tool_result');
-            const reordered = [...stubs, ...existingResults, ...nonResults];
-            const changed = missing.length > 0 || reordered.some((b, idx) => b !== next.content[idx]);
-            if (changed) work[i + 1] = { ...next, content: reordered };
-        } else {
-            if (missing.length === 0) continue;
-            out.push({ role: 'user', content: stubs });
-        }
-    }
-    return out;
-}
-
-/**
- * Trim messages to fit within a token budget.
- *
- * Single linear path — no fallback chain:
- *   1. Sanitize tool pairs on entry.
- *   2. Dedup repeated large tool-result bodies (hash-based; first occurrence kept).
- *   3. Return deduped messages if already within budget.
- *   4. Drop tool result messages oldest-first; also drop paired assistant
- *      once all its tool calls are gone.
- *   5. If still over budget, drop oldest non-system messages respecting
- *      tool-call group boundaries.
- *   6. Final sanitize + safety loop absorbs stub-insertion overshoot.
- *
- * budgetTokens MUST be derived from the model's context window by the
- * caller (session.contextWindow * safetyFactor). Passing 0 or a negative
- * value is a caller error and throws immediately.
- *
- * opts.reserveTokens (optional) subtracts request-side bytes the message
- * estimate cannot see (tool schemas + provider framing — see
- * estimateRequestReserveTokens). The reserve is clamped so it can never
- * drive the effective budget to <= 0; at most it leaves 1 token of working
- * room so callers that over-estimate the reserve still get a usable budget
- * rather than an immediate throw.
- */
-export function trimMessages(messages, budgetTokens, opts = {}) {
-    if (!(budgetTokens > 0)) throw new Error();
-    const reserve = Number(opts?.reserveTokens) || 0;
-    if (reserve > 0) {
-        // Cap the reserve so it can never consume more than half the budget.
-        // An over-estimated reserve (large tool schemas relative to a small
-        // context window) would otherwise collapse the effective budget toward
-        // 1, making system+latest baseCost exceed it and forcing trimMessages
-        // to throw — which defeats the overflow-resilience goal. Half-budget
-        // is the floor: the reserve still accounts for tool schemas but can
-        // never starve the mandatory system+latest content.
-        const effectiveReserve = Math.min(reserve, Math.floor(budgetTokens * 0.5));
-        budgetTokens = Math.max(1, budgetTokens - effectiveReserve);
-    }
-
-    const sanitized = sanitizeToolPairs(messages);
-    // Cache-anchor invariant: when sanitized messages already fit the budget,
-    // return them WITHOUT running dedupToolResultBodies. Dedup creates new
-    // object refs on every duplicate hit (sha256 match on ≥512B tool result
-    // bodies); messagesArrayChanged in loop.mjs detects those new refs as
-    // mutation and drops providerState, which kills the server-side
-    // previous_response_id chain that xAI Responses / Codex WS rely on for
-    // prefix cache reuse. Skip the payload optimization when it would cost
-    // a fresh cache cold-start for no token-budget benefit.
-    if (estimateMessagesTokens(sanitized) <= budgetTokens) return reconcileDedupStubs(sanitized);
-    // Over budget: dedup-then-fit before drop. If post-dedup body fits the
-    // budget, return the deduped result without dropping. Both stub and
-    // original are still in the message stream so the stub reference is safe.
-    // Survivors-only dedup (Pass 1/2 below) still applies when drop is required.
-    const deduped = dedupToolResultBodies(sanitized);
-    if (estimateMessagesTokens(deduped) <= budgetTokens) return reconcileDedupStubs(deduped);
-
-    const system = sanitized.filter(m => m.role === 'system');
-    const rest = sanitized.filter(m => m.role !== 'system');
-    if (rest.length === 0) return reconcileDedupStubs(system);
-
-    // The most-recent turn must survive intact. When the last message is a tool
-    // result, its owning assistant (and that assistant's sibling tool results)
-    // form one atomic "last group" — we keep the whole group, never a bare
-    // orphan tool result. The boundary is determined strictly by toolCallId
-    // ownership (invariant), not by position.
-    const lastMsg = rest[rest.length - 1];
-    let lastGroupStart = rest.length - 1;
-    if (lastMsg && lastMsg.role === 'tool' && lastMsg.toolCallId) {
-        const ownerIdx = rest.findIndex(m =>
-            m.role === 'assistant' && Array.isArray(m.toolCalls) &&
-            m.toolCalls.some(tc => tc.id === lastMsg.toolCallId)
-        );
-        if (ownerIdx !== -1) lastGroupStart = ownerIdx;
-    }
-    const lastGroup = rest.slice(lastGroupStart);
-    let middle = rest.slice(0, lastGroupStart);
-    const baseCost = estimateMessagesTokens(system) + estimateMessagesTokens(lastGroup);
-
-    // Exact fit (baseCost === budget) must be allowed — only a true overshoot throws.
-    if (baseCost > budgetTokens) throw new Error(`trimMessages: cannot fit even system+last group within budget=${budgetTokens} (base=${baseCost})`);
-
-    // Pass 1: drop tool results oldest-first; drop paired assistant when all its calls are gone.
-    let total = estimateMessagesTokens(middle);
-    while (total + baseCost > budgetTokens) {
-        const toolIdx = middle.findIndex(m => m.role === 'tool');
-        if (toolIdx === -1) break;
-        const toolCallId = middle[toolIdx].toolCallId;
-        total -= estimateMessageTokens(middle[toolIdx]);
-        middle.splice(toolIdx, 1);
-        if (toolCallId) {
-            const assistantIdx = middle.findIndex(m =>
-                m.role === 'assistant' && Array.isArray(m.toolCalls) &&
-                m.toolCalls.some(tc => tc.id === toolCallId)
-            );
-            if (assistantIdx !== -1) {
-                const assistantMsg = middle[assistantIdx];
-                const remainingCalls = assistantMsg.toolCalls.filter(tc =>
-                    middle.some(m => m.role === 'tool' && m.toolCallId === tc.id)
-                );
-                if (remainingCalls.length === 0) {
-                    total -= estimateMessageTokens(assistantMsg);
-                    middle.splice(assistantIdx, 1);
-                }
-            }
-        }
-    }
-
-    if (total + baseCost <= budgetTokens) {
-        const s = sanitizeToolPairs([...system, ...middle, ...lastGroup]);
-        if (estimateMessagesTokens(s) <= budgetTokens) return reconcileDedupStubs(dedupToolResultBodies(s));
-        // sanitizeToolPairs stub inserts pushed back over budget — fall through to Pass 2.
-        // Recompute the last-group span on the POST-sanitize sequence: stubs may have
-        // been inserted adjacent to the last group, so using the original lastGroup.length
-        // as a tail offset is off-by-N. Locate by matching the lastGroup subsequence
-        // from the END of s — indexOf(lastGroup[0]) is wrong when the same object
-        // reference repeats earlier in middle (a duplicate would promote part of
-        // middle into the locked last group).
-        let anchorIdx = -1;
-        let lgMatchIdx = lastGroup.length - 1;
-        for (let si = s.length - 1; si >= 0 && lgMatchIdx >= 0; si--) {
-            if (s[si] === lastGroup[lgMatchIdx]) {
-                if (lgMatchIdx === 0) { anchorIdx = si; break; }
-                lgMatchIdx--;
-            }
-        }
-        const postSanitizeLastGroup = anchorIdx === -1 ? lastGroup : s.slice(anchorIdx);
-        const nonSystem = s.slice(0, anchorIdx === -1 ? s.length : anchorIdx)
-            .filter(m => m.role !== 'system');
-        middle = nonSystem;
-        // Replace lastGroup binding so downstream baseCost/safety bounds reflect
-        // the sanitize-grown tail (stubs inserted around the last group).
-        lastGroup.length = 0;
-        for (const m of postSanitizeLastGroup) lastGroup.push(m);
-    }
-
-    // Pass 2: drop oldest non-system messages, respecting tool-call group boundaries.
-    // Recompute baseCost against the (possibly grown) lastGroup so we don't underflow
-    // remaining by the original tail-cost estimate.
-    const baseCostP2 = estimateMessagesTokens(system) + estimateMessagesTokens(lastGroup);
-    let remaining = budgetTokens - baseCostP2;
-    const kept = [];
-    // Track which middle messages have already had their cost subtracted from
-    // `remaining`. Without this, a paired-assistant charged via the tool→owner
-    // lookup gets charged again when the outer loop reaches its own index,
-    // double-counting its cost and underflowing `remaining` -> premature break
-    // that drops content which still fits.
-    const charged = new Set();
-    const startIdx = alignBoundaryBackward(middle, middle.length - 1);
-    for (let i = startIdx; i >= 0; i--) {
-        const m = middle[i];
-        const cost = charged.has(m) ? 0 : estimateMessageTokens(m);
-        if (remaining - cost < 0) break;
-        if (m.role === 'tool' && m.toolCallId) {
-            const pairedIdx = middle.findIndex((a, idx) =>
-                idx < i && a.role === 'assistant' && Array.isArray(a.toolCalls) &&
-                a.toolCalls.some(tc => tc.id === m.toolCallId)
-            );
-            if (pairedIdx !== -1 && !kept.includes(middle[pairedIdx])) {
-                const paired = middle[pairedIdx];
-                const pairedCost = charged.has(paired) ? 0 : estimateMessageTokens(paired);
-                if (remaining - cost - pairedCost < 0) break;
-                remaining -= pairedCost;
-                charged.add(paired);
-                kept.unshift(paired);
-            }
-        }
-        if (m.role === 'assistant' && Array.isArray(m.toolCalls)) {
-            const toolResultCosts = m.toolCalls.reduce((sum, tc) => {
-                const toolMsg = middle.find(t =>
-                    t.role === 'tool' && t.toolCallId === tc.id && !kept.includes(t)
-                );
-                return sum + (toolMsg && !charged.has(toolMsg) ? estimateMessageTokens(toolMsg) : 0);
-            }, 0);
-            if (remaining - cost - toolResultCosts < 0) break;
-            for (const tc of m.toolCalls) {
-                const toolMsg = middle.find(t =>
-                    t.role === 'tool' && t.toolCallId === tc.id && !kept.includes(t)
-                );
-                if (toolMsg) {
-                    if (!charged.has(toolMsg)) {
-                        remaining -= estimateMessageTokens(toolMsg);
-                        charged.add(toolMsg);
-                    }
-                    kept.push(toolMsg);
-                }
-            }
-        }
-        if (!charged.has(m)) {
-            remaining -= cost;
-            charged.add(m);
-        }
-        if (!kept.includes(m)) kept.unshift(m);
-    }
-
-    const middleOrder = new Map(middle.map((m, idx) => [m, idx]));
-    kept.sort((a, b) => (middleOrder.get(a) ?? 0) - (middleOrder.get(b) ?? 0));
-
-    // Run sanitizeToolPairs before the safety loop; defer dedupToolResultBodies until after
-    // so stubs are never left referencing content that the safety loop subsequently drops.
-    let result = sanitizeToolPairs([...system, ...kept, ...lastGroup]);
-    let safety = 16;
-    while (
-        safety-- > 0
-        && result.length > system.length + lastGroup.length
-        && estimateMessagesTokens(result) > budgetTokens
-    ) {
-        // Drop a whole aligned tool-group from the head of the non-system region,
-        // not a single arbitrary line. Splicing one line at a time can sever an
-        // assistant from its tool results (orphaned pair) — sanitizeToolPairs
-        // then re-inserts a stub for the dangling tool_use, the byte count drops
-        // by less than expected, and the loop oscillates without progress.
-        const head = system.length;
-        if (head >= result.length) break;
-        let dropEnd = head + 1;
-        const first = result[head];
-        if (first?.role === 'assistant' && Array.isArray(first.toolCalls) && first.toolCalls.length) {
-            const callIds = new Set(first.toolCalls.map(tc => tc.id).filter(Boolean));
-            while (
-                dropEnd < result.length
-                && result[dropEnd]?.role === 'tool'
-                && callIds.has(result[dropEnd].toolCallId)
-            ) dropEnd++;
-        }
-        // Refuse to cross into the locked last group.
-        const lastGroupStartIdx = result.length - lastGroup.length;
-        if (dropEnd > lastGroupStartIdx) break;
-        result.splice(head, dropEnd - head);
-        result = sanitizeToolPairs(result);
-    }
-    result = dedupToolResultBodies(result);
-    // Final stub-vs-survivor reconciliation: any [duplicate-of tool_use_id=X]
-    // pointing at an X no longer present in `result` (carried over from a
-    // prior trim and orphaned by this trim's drops) is rewritten to the
-    // generic missing-stub so the model never sees a reference to an absent id.
-    result = reconcileDedupStubs(result);
-    const finalTokens = estimateMessagesTokens(result);
-    if (finalTokens > budgetTokens) throw new Error(`trimMessages: exhausted drop strategy, result=${finalTokens} > budget=${budgetTokens}`);
-    return result;
-}

package/src/agent/orchestrator/smart-bridge/CACHE-SHARD.md

@@ -1,115 +0,0 @@
-# Bridge Cache-Shard Policy
-
-Authoritative policy for prefix-cache shard construction across all bridge sessions. The implementation must satisfy every rule below; reviewers should reject changes that turn stable shared layers into per-call fragments.
-
-## Design philosophy
-
-Maximize cross-role / cross-call cache reuse by packing every role's policy into a SHARED monolithic prefix. Bridge sessions across all roles see bit-identical BP1 + BP2. User-defined customizations (roles / schedules / webhooks) are baked into BP1 as a fixed-value block — a user edit invalidates BP1 once and the new prefix re-warms across every role together.
-
-The only per-call variance lives in BP4 (5m tail). Lead-only fields (e.g. memory recap) never enter bridge sessions.
-
-## 4-Block Layout
-
-| Block | Role | Cache TTL | Hashed by registry | Content | Variability |
-|---|---|---|---|---|---|
-| BP1 baseRules | system | 1h | YES | bridge common rules + tool/memory/search/explore guidance + DATA_DIR roles/schedules/webhooks (monolithic) | Stable across all bridge calls. Invalidated only when a user edits roles/schedules/webhooks or plugin upgrades. |
-| BP2 roleCatalog | system | 1h | YES | scoped role catalog + project context | Stable for a given provider/project. Project context changes re-hash this block. |
-| BP3 sessionMarker | user (`<system-reminder>` with `<!-- bp3-sentinel -->` marker) | 1h | NO | role-specific task instructions, when present | Stable for that bridge session/task. Empty when no role-specific body is present. |
-| BP4 volatileTail | user (`<system-reminder>`, no sentinel) | 5m | NO | role / permission / task-brief | May vary per call. |
-
-**Note on tool schemas (Anthropic):** Anthropic's `cache_control` caches every block from the marked block back through the prefix (order: tools → system → messages). The system block's `cache_control` therefore covers the tool-schema array implicitly, so a separate dedicated tools breakpoint slot is not needed. This frees one of the 4 slots for the messages tail. See `anthropic.mjs:211-214` and `anthropic-oauth.mjs` for the layout decision.
-
-**Provider cache classes:** Anthropic uses explicit breakpoints and can be marked warm. OpenAI uses a provider cache key/session prefix and can be tracked as a reusable shard. Gemini uses implicit prompt caching only; hits are observed via `cachedContentTokenCount`, but the registry must not treat that as a guaranteed warm shard.
-
-## Hash inputs
-
-`registry.markWarm` / `checkWarm` hash exactly two things:
-
-1. `JSON.stringify(systemMessages)` — array of leading system-role messages from `session.messages` (BP1 + BP2 only)
-2. `tools.map(t => ({ name, description, inputSchema }))` — the bridge tool array (sorted alphabetically by name for bridge sessions)
-
-Anything outside these two inputs MUST NOT influence the registry hash. cwd, role, permission, task-brief, memory recap, files, prompt text, tool results, provider/model/effort/fast — all excluded. Project context is part of BP2 when present, so it is included via the leading system-message hash.
-
-## cwd policy
-
-- `cwd: null` is a fixed sentinel meaning "no caller workspace context". Internal callers (memory-cycle, scheduler, webhook) pass null deliberately to share one shard.
-- Never upgrade `null` to `process.cwd()` — that defeats fork suppression. The public bridge entry at `src/agent/index.mjs` MUST honor null.
-- Tilde (`~`) and relative paths must be normalized at the entry point. Once inside `prepareBridgeSession`, cwd is either an absolute path or null.
-- cwd does NOT enter the registry hash. cwd-aware tools receive cwd via tool args at call time, not via prompt injection.
-
-## What goes where (must / must-not)
-
-**baseRules (BP1) MUST contain (monolithic, fixed value):**
-- `lib/rules-builder.cjs` static bridge injection (tool/memory/search/explore guidance)
-- `rules/bridge/00-common.md`
-- `DATA_DIR/roles/*.md` — every role definition aggregated
-- `DATA_DIR/schedules/*/instructions.md` — every schedule aggregated
-- `DATA_DIR/webhooks/*/instructions.md` — every webhook aggregated
-
-User edits to roles/schedules/webhooks invalidate BP1 once. This is acceptable because: (a) edits are infrequent, (b) every role re-warms together to the new prefix, (c) keeping all role policies in BP1 maximizes cross-role hit rate compared to per-call branching.
-
-**baseRules (BP1) MUST NOT contain:**
-- per-call values (role identity, permission, task brief, memory recap)
-- cwd, project context, file references
-
-**roleCatalog (BP2) MUST contain only:**
-- the scoped role catalog selected by `loadScopedRoleCatalog`
-- `# project-context` when project context is present
-
-**roleCatalog (BP2) MUST NOT contain:**
-- role / permission / task-brief markers
-- volatile tool results or user task text
-
-**sessionMarker (BP3) MUST contain only:**
-- `<!-- bp3-sentinel -->\n<roleSpecific>` when role-specific instructions are present
-- nothing when role-specific instructions are absent — emit no `<system-reminder>` at all in that case
-
-**volatileTail (BP4) MUST contain (any subset):**
-- `# role`, `# permission`, `# task-brief`
-
-**Lead-only fields — MUST NOT enter bridge sessions:**
-- `# memory-context` — recap / history context. Reserved for Lead session prompt only. Bridge `composeSystemPrompt` callers must not pass `opts.memoryContext` for `opts.owner === 'bridge'`.
-
-## Provider Tier3 selection
-
-Anthropic provider wrapper auto-marks the first user `<system-reminder>` as BP3 (1h). To prevent volatileTail from being mistaken for BP3:
-
-- `sessionMarker` MUST carry the explicit BP3 sentinel `<!-- bp3-sentinel -->` at the head.
-- The provider wrapper MUST mark only sentinel-bearing reminders as 1h. Non-sentinel reminders ride 5m default.
-- When sessionMarker is empty, no BP3 mark is emitted; volatileTail stays at 5m.
-
-## Tool list canonicalization
-
-Bridge sessions (`opts.owner === 'bridge'`) receive a tool array sorted alphabetically by `tool.name` after the deny-list filter. This eliminates incidental fragmentation from MCP/internal registration order changes.
-
-## Entry-point checklist (cwd handling)
-
-Every external entry point that constructs a bridge session must satisfy:
-
-1. `args.cwd` provided → `normalizeInputPath(args.cwd)` (expand `~`, resolve relative)
-2. `args.cwd` absent and `callerCwd` available → use `callerCwd`
-3. Both absent → `cwd: null`. NEVER fall back to `process.cwd()`.
-
-Current entry points (must remain compliant):
-- `src/agent/index.mjs` `case 'bridge'` (Lead-originated MCP dispatch; the unified `bridge` handler routes type=spawn/send/close/list)
-- `src/agent/orchestrator/smart-bridge/bridge-llm.mjs` `makeBridgeLlm` (internal callers)
-
-## Trigger map (when prefix transitions)
-
-Single transition cause → effect:
-
-- Edit `lib/rules-builder.cjs` static block, `agents/*.md`, `rules/bridge/*.md`, or any `DATA_DIR/{roles,schedules,webhooks}/*.md` → BP1 or BP2 hash changes once → all roles/presets re-warm together (acceptable, infrequent)
-- Add/remove an MCP or internal tool → tool_schema_hash changes → all bridge sessions re-warm
-- Project switch → project context may change BP2 → provider shard re-warm/observe under a new prefix hash
-- Per-call (role / permission / task-brief change) → only BP4 5m tail differs; BP1/BP2/BP3 untouched
-
-If a single per-call change invalidates more than BP4, the policy has been violated.
-
-## Forbidden patterns
-
-- per-role tool narrowing in bridge sessions (`opts.allowedTools` whitelist) — fragments BP2 by role group
-- `process.cwd()` fallback in any bridge entry point — breaks the null sentinel
-- emitting cwd or other variant data inside `<system-reminder>` blocks intended for BP3
-- mid-pipeline cwd normalization (do it once at entry)
-- routing memory-context into bridge sessions — Lead-only field
-- changing the registry hash inputs (additions or removals) without updating this document in the same change