mixdog 0.7.1

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

@@ -0,0 +1,491 @@
+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;
+}
+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

@@ -0,0 +1,115 @@
+# 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