mixdog 0.7.1

package/src/agent/orchestrator/smart-bridge/cache-strategy.mjs

@@ -0,0 +1,228 @@
+/**
+ * Smart Bridge — Cache Strategy
+ *
+ * Provider-level cache policy. Anthropic supports explicit cache_control
+ * breakpoints (up to 4 per request) — we use all 4 slots. Non-breakpoint
+ * providers rely on server-side automatic prefix matching or observation.
+ *
+ * Anthropic 4-BP layout (bridge/agent use case — no interactive idle):
+ *   BP_1  tools      (1h)  — tool schemas, stable per schema profile
+ *   BP_2  system     (1h)  — Tier 2 shared rules
+ *   BP_3  tier3      (1h)  — role/permission meta (messages[1] system-reminder)
+ *   BP_4  messages   (5m)  — last message only; sliding extends prefix loss-free
+ *
+ * Tier 3 gets its own BP because role meta is stable per dispatch, so a
+ * dedicated slot gives a reliable hit across the entire tool loop while
+ * the sliding messages BP handles volatile tool_result accumulation.
+ *
+ * Non-breakpoint providers:
+ *   - OpenAI (public): prompt_cache_key + prompt_cache_retention=24h
+ *   - OpenAI OAuth (Codex): prompt_cache_key only (server in-memory 5-10min)
+ *   - Gemini: implicit caching does NOT report cachedContentTokenCount on
+ *     3.5+. Explicit cachedContents API required for measurable cache hits.
+ *   - xAI: x-grok-conv-id (server routing pin) + prompt_cache_key on
+ *     Responses API. Treat as key-prefix, not implicit.
+ *   - DeepSeek: automatic KV prompt cache; observe prompt_cache_hit_tokens
+ *   - Groq: auto 50% cache (gpt-oss-120b) — no knob
+ *   - Copilot / Ollama / LMStudio: no API-level cache
+ */
+
+import { getHiddenRole } from '../internal-roles.mjs';
+
+/**
+ * One-shot, LLM-only maintenance hidden roles (cycle1/cycle2/cycle3-agent):
+ * a fresh stateless session is created per call, asked exactly once, and
+ * closed (bridge-llm.mjs) — the per-batch user prompt can NEVER be reused.
+ * Writing a message-tail cache breakpoint on it just pays the 1.25x write
+ * premium for content read back 0 times. Identified by the declarative
+ * (kind:'maintenance' + toolSchemaProfile:'llm-only') pair rather than
+ * hardcoded names, so new roles sharing the pattern are covered for free.
+ * Multi-turn maintenance roles (scheduler-task / webhook-handler) are
+ * 'unified' and therefore excluded — they run a tool loop whose tail caches
+ * legitimately reuse across iterations.
+ */
+function isOneShotMaintenanceRole(role) {
+    const hidden = getHiddenRole(role);
+    return Boolean(
+        hidden
+        && hidden.kind === 'maintenance'
+        && hidden.toolSchemaProfile === 'llm-only',
+    );
+}
+
+/**
+ * Return the layered cache policy for Anthropic-family providers.
+ *
+ * Values:
+ *   '1h'   → ephemeral 1h TTL  (2x write premium, 0.1x read)
+ *   '5m'   → ephemeral 5m TTL  (1.25x write premium, 0.1x read)
+ *   'none' → no breakpoint written on this layer
+ *
+ * Public bridge workers (any user-workflow.json role) stay resumable for up to
+ * 1h (the terminal-reap window) for same-task reuse, so their message tail uses
+ * 1h too — a resume within that window reads the conversation from cache instead
+ * of re-writing it. Hidden multi-turn roles (explorer / scheduler / webhook) run
+ * a single fan-out or entry-driven session that is not resumed for same-task
+ * reuse, so their volatile tail stays at the cheaper 5m TTL. (Tail TTL only
+ * affects explicit-breakpoint providers — Anthropic; no-op elsewhere.)
+ *
+ * Exception: one-shot LLM-only maintenance roles are asked once on a fresh
+ * session and closed, so their volatile per-call message tail is never read
+ * back — and trace data (2026-06) shows the 1h system/tools prefix never
+ * gets read back either: cycle1's prompt sits below Anthropic's minimum
+ * cacheable length (0 writes), and cycle2's 1h run interval lands at/after
+ * the 1h TTL expiry (writes every run, 0 reads). All layers go 'none' for
+ * these roles — single-iteration calls pay the write premium with no reuse.
+ */
+export function resolveCacheStrategy(role) {
+    if (isOneShotMaintenanceRole(role)) {
+        return { tools: 'none', system: 'none', tier3: 'none', messages: 'none' };
+    }
+    // Hidden multi-turn roles (explorer / scheduler / webhook): single-use
+    // session, not resumed for same-task reuse → keep the cheaper 5m tail.
+    if (getHiddenRole(role)) {
+        return { tools: '1h', system: '1h', tier3: '1h', messages: '5m' };
+    }
+    // Public bridge workers: resumable up to 1h for same-task reuse → 1h tail.
+    return { tools: '1h', system: '1h', tier3: '1h', messages: '1h' };
+}
+
+/**
+ * Build provider-specific sendOpts.
+ *
+ * @param {string} provider
+ * @param {string} [sessionId]
+ * @param {string} [role]
+ * @returns {object} partial sendOpts — spread into provider.send call
+ */
+
+// Provider cache capability kinds:
+//   'explicit-breakpoint' — explicit provider-side cache_control writes
+//   'key-prefix'          — provider-managed shard keyed by cache key/session
+//   'implicit-observed'   — cache hits are observable but not guaranteed warm
+//   'none'                — no API-level cache knob/metric
+const PROVIDER_CACHE_CAPABILITY = Object.freeze({
+    'anthropic':       'explicit-breakpoint',
+    'anthropic-oauth': 'explicit-breakpoint',
+    'openai':          'key-prefix',
+    'openai-oauth':    'key-prefix',
+    'xai':             'key-prefix',
+    'grok-oauth':      'key-prefix',
+    'gemini':          'implicit-observed',
+    'deepseek':        'implicit-observed',
+});
+
+export function cacheCapabilityForProvider(provider) {
+    return PROVIDER_CACHE_CAPABILITY[provider] || 'none';
+}
+
+export function shouldMarkWarmForProvider(provider) {
+    const capability = cacheCapabilityForProvider(provider);
+    return capability === 'explicit-breakpoint' || capability === 'key-prefix';
+}
+
+export function shouldRecordObservedForProvider(provider) {
+    return cacheCapabilityForProvider(provider) === 'implicit-observed';
+}
+
+// Stable per-provider shared prompt-cache key. key-prefix providers MUST land on
+// a cross-session shard, so the resolver below NEVER falls back to sessionId
+// (which isolates each session into its own bucket and forces a cold start).
+// Generalizes the xai pattern ('mixdog-xai') that already defaulted to a shared
+// key. Anthropic/Gemini use content-keyed cache_control / explicit CachedContent
+// and do not consult this map.
+const PROVIDER_CACHE_KEY_DEFAULT = Object.freeze({
+    'openai':       'mixdog-openai',
+    'openai-oauth': 'mixdog-codex',
+    'xai':          'mixdog-xai',
+    'grok-oauth':   'mixdog-xai',
+});
+
+/**
+ * Resolve the server-side prompt-cache grouping key (prompt_cache_key) for a
+ * key-prefix provider. Precedence: explicit provider key > prompt key >
+ * session-scoped prompt key > stable shared default. Invariant: always returns a
+ * non-empty stable key, and deliberately EXCLUDES sessionId so a fresh session
+ * reuses the warm shard instead of cold-starting its own bucket.
+ *
+ * This is the CACHE key only. The socket poolKey stays sessionId-scoped at each
+ * call site to avoid cross-session socket/delta-state reuse.
+ */
+export function resolveProviderCacheKey(opts, provider) {
+    return opts?.providerCacheKey
+        || opts?.promptCacheKey
+        || opts?.session?.promptCacheKey
+        || PROVIDER_CACHE_KEY_DEFAULT[provider]
+        || 'mixdog-shared';
+}
+
+export function buildProviderCacheOpts(provider, sessionId, role) {
+    const ttls = resolveCacheStrategy(role);
+    const capability = cacheCapabilityForProvider(provider);
+    if (capability === 'explicit-breakpoint') {
+        // 2026-03-06 Anthropic dropped default TTL 1h→5m. We send
+        // extended-cache-ttl-2025-04-11 header to retain 1h.
+        // Verified 2026-04-17 (ephemeral_1h_input_tokens=4722).
+        return { cacheStrategy: ttls };
+    }
+    if (provider === 'openai') {
+        // Public OpenAI API: prompt_cache_retention extends prefix retention.
+        // openai-oauth (Codex) rejects the header — falls through to default.
+        return { cacheRetention: '24h' };
+    }
+    return {};
+}
+
+/**
+ * Prefix content used to derive the cache hash for registry tracking.
+ * Excludes the volatile user message — only the stable prefix (tools,
+ * system) determines whether our cache is "still warm". The Pool B prefix
+ * is workspace-wide, so a single hash represents every Pool B caller.
+ *
+ * `systemPrompt` is an array of system-role message contents in their send
+ * order (BP1 / BP2 / ...), serialized deterministically as a JSON array.
+ * Invariant: callers must pass an array.
+ */
+export function computePrefixContent(systemPrompt, tools) {
+    const systemMessages = Array.isArray(systemPrompt)
+        ? systemPrompt.map(s => s == null ? '' : String(s))
+        : [systemPrompt == null ? '' : String(systemPrompt)];
+    return {
+        systemPrompt: JSON.stringify(systemMessages),
+        tools: (tools || []).map(t => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    };
+}
+
+/**
+ * Longest-lived layer TTL (seconds) for registry expiry tracking.
+ */
+export function ttlSecondsForCache(role) {
+    const ttls = resolveCacheStrategy(role);
+    if (
+        ttls.tools === 'none'
+        && ttls.system === 'none'
+        && ttls.tier3 === 'none'
+        && ttls.messages === 'none'
+    ) {
+        return 0;
+    }
+    return Math.max(
+        ttlToSeconds(ttls.tools),
+        ttlToSeconds(ttls.system),
+        ttlToSeconds(ttls.tier3),
+        ttlToSeconds(ttls.messages),
+    );
+}
+
+// --- Helpers ---
+
+function ttlToSeconds(v) {
+    if (v === '24h') return 86400;
+    if (v === '1h') return 3600;
+    if (v === '5m') return 300;
+    return 0;
+}

package/src/agent/orchestrator/smart-bridge/index.mjs

@@ -0,0 +1,215 @@
+/**
+ * Smart Bridge — public API
+ *
+ * Resolution flow:
+ *   request.role   →  getRoleConfig(role)         (user-workflow.json)
+ *   request.preset →  presets[preset]             (mixdog-config.json agent.presets)
+ *
+ * Missing role → preset comes from `request.preset` →
+ * userRoles[request.role] → default preset.
+ */
+
+import { buildVirtualProfile } from './profiles.mjs';
+import { CacheRegistry } from './registry.mjs';
+import {
+    buildProviderCacheOpts,
+    computePrefixContent,
+    shouldMarkWarmForProvider,
+    shouldRecordObservedForProvider,
+    ttlSecondsForCache,
+} from './cache-strategy.mjs';
+import { getHiddenRole } from '../internal-roles.mjs';
+
+let _sharedInstance = null;
+
+// Plugin-managed hidden roles live in internal-roles.mjs, not
+// user-workflow.json. The resolver normalises them into the same RoleConfig
+// shape user-defined roles produce so every caller lands in the cache
+// registry with a stable profileId — no per-call branching, no fallback
+// chain in downstream code.
+function _hiddenRoleConfig(role) {
+    const hidden = getHiddenRole(role);
+    if (!hidden) return null;
+    return {
+        name: role,
+        preset: null,
+        desc_path: hidden.description || null,
+    };
+}
+
+// Unified role resolver. Defaults to the hidden-role registry so SmartBridge
+// is usable standalone before agent/init() runs; setRoleResolver() layers the
+// user-workflow.json lookup on top once available. One function, one shape —
+// downstream code never checks for null or picks a branch.
+let _resolveRole = _hiddenRoleConfig;
+
+/**
+ * Install the user-workflow role lookup. Called once by agent/index.mjs after
+ * the user-workflow.json cache is populated. The resulting resolver returns
+ * user-defined roles when present and hidden-role metadata otherwise.
+ */
+export function setRoleResolver(fn) {
+    const userResolver = typeof fn === 'function' ? fn : null;
+    _resolveRole = userResolver
+        ? (role) => userResolver(role) || _hiddenRoleConfig(role)
+        : _hiddenRoleConfig;
+}
+
+async function _lazyGetRoleConfig(role) {
+    // User-workflow resolver already installed — synchronous lookup is fine.
+    if (_resolveRole !== _hiddenRoleConfig) return _resolveRole(role);
+    // Pre-init: dynamic import so standalone tests / scripts still see the
+    // user-workflow roles without requiring agent/init() to have run.
+    try {
+        const mod = await import('../../index.mjs');
+        if (typeof mod.getRoleConfig === 'function') {
+            setRoleResolver(mod.getRoleConfig);
+            return _resolveRole(role);
+        }
+    } catch { /* ignore */ }
+    return _hiddenRoleConfig(role);
+}
+
+function _syncGetRoleConfig(role) {
+    return _resolveRole(role);
+}
+
+export class SmartBridge {
+    constructor(opts = {}) {
+        this.userRoles = opts.userRoles || {};
+        this.presets = Array.isArray(opts.presets) ? opts.presets : [];
+        this.llmCall = opts.llmCall || null;
+        this.registry = opts.registry || CacheRegistry.shared();
+    }
+
+    /**
+     * Async resolution — used by bridge-llm and any caller that can await.
+     * Returns the same shape as resolveSync but falls back to the default
+     * preset when no role config is found.
+     */
+    async resolve(request) {
+        const role = request?.role || request?.taskType || null;
+        const roleConfig = role ? await _lazyGetRoleConfig(role) : null;
+        return this._finalize(roleConfig, request || {});
+    }
+
+    /**
+     * Sync variant — used by createSession and the bridge tool entry point.
+     * Returns null only when called before agent init has populated the
+     * role-config cache. Callers fall back to classic preset behaviour.
+     */
+    resolveSync(request) {
+        if (!request) return null;
+        const role = request.role || request.taskType || null;
+        const roleConfig = role ? _syncGetRoleConfig(role) : null;
+        return this._finalize(roleConfig, request);
+    }
+
+    _finalize(roleConfig, request) {
+        const profile = buildVirtualProfile(roleConfig);
+
+        let presetName = request.preset
+            || (request.role ? this.userRoles[request.role] : null)
+            || (roleConfig?.preset || null)
+            || null;
+
+        let preset = this._findPreset(presetName);
+
+        const provider = request.provider || preset?.provider || null;
+        const model = request.model || preset?.model || null;
+        const effort = preset?.effort || null;
+        const fast = preset?.fast === true;
+
+        const cacheOpts = buildProviderCacheOpts(provider, request.sessionId, request.role);
+
+        return {
+            profile,
+            preset: preset || (presetName ? { name: presetName, id: presetName } : null),
+            presetName,
+            provider,
+            model,
+            effort,
+            fast,
+            source: roleConfig ? 'role-config' : 'default',
+            reasoning: null,
+            providerCacheOpts: cacheOpts,
+        };
+    }
+
+    _findPreset(name) {
+        if (!name || !this.presets.length) return null;
+        return this.presets.find(p => p.id === name || p.name === name) || null;
+    }
+
+    /**
+     * Called after a successful send to update the cache registry. Explicit
+     * and key-prefix providers can mark a reusable warm shard; implicit-only
+     * providers record observed hit/miss metrics without reporting warm=true.
+     * The registry keys on the profile id (which is the role name post-refactor).
+     */
+    recordCall(profile, provider, { systemPrompt, tools, usage }) {
+        if (!profile) return;
+        const prefixContent = computePrefixContent(systemPrompt, tools);
+        const ttlSeconds = ttlSecondsForCache(profile.id);
+        const cachedTokens = usage?.cachedTokens ?? 0;
+        const inputTokens = usage?.inputTokens ?? usage?.promptTokens ?? 0;
+        if (ttlSeconds > 0 && shouldMarkWarmForProvider(provider)) {
+            this.registry.markWarm(profile.id, provider, prefixContent, ttlSeconds);
+        } else if (
+            ttlSeconds > 0
+            && shouldRecordObservedForProvider(provider)
+            && (cachedTokens > 0 || inputTokens > 0)
+        ) {
+            this.registry.markObserved(profile.id, provider, prefixContent, ttlSeconds);
+        }
+        if (cachedTokens > 0) {
+            this.registry.recordHit(profile.id, provider);
+        } else if (inputTokens > 0) {
+            this.registry.recordMiss(profile.id, provider);
+        }
+        if (this.registry.dirty) this.registry.save();
+    }
+
+    /**
+     * Called when user changes preset mapping for a role.
+     */
+    updateUserRoles(userRoles) {
+        this.userRoles = userRoles || {};
+    }
+
+    /**
+     * Update preset catalog — call when mixdog-config.json's agent.presets change.
+     */
+    updatePresets(presets) {
+        this.presets = Array.isArray(presets) ? presets : [];
+    }
+
+    /**
+     * Returns a virtual profile for a role id. Used by session manager to
+     * rehydrate the profile object after session reload.
+     */
+    getProfile(id) {
+        if (!id) return null;
+        const roleConfig = _syncGetRoleConfig(id);
+        return buildVirtualProfile(roleConfig);
+    }
+
+    getStats() {
+        return this.registry.getStats();
+    }
+}
+
+/**
+ * Singleton accessor.
+ */
+export function initSmartBridge(opts = {}) {
+    _sharedInstance = new SmartBridge(opts);
+    return _sharedInstance;
+}
+
+export function getSmartBridge() {
+    if (!_sharedInstance) {
+        _sharedInstance = new SmartBridge();
+    }
+    return _sharedInstance;
+}

package/src/agent/orchestrator/smart-bridge/profiles.mjs

@@ -0,0 +1,37 @@
+/**
+ * Smart Bridge — Virtual Profile Helpers
+ *
+ * Single source of truth for role metadata is `user-workflow.json`, loaded
+ * via `getRoleConfig(role)` in agent/index.mjs. This module keeps a small
+ * helper used by callers that still think in terms of "profiles":
+ *
+ *   • buildVirtualProfile(roleConfig)
+ *       Turn a user-workflow.json role into the shape older code expected
+ *       (`{id, taskType, permission, description}`).
+ *
+ *   • ROLE_TOOLS_UNIFIED
+ *       Every bridge caller ships the same tool surface at the cached
+ *       prefix so the tools breakpoint stays bit-identical across roles.
+ *       Per-role narrowing happens in the role.md injected into the first
+ *       user turn.
+ */
+
+export const ROLE_TOOLS_UNIFIED = ['full'];
+
+/**
+ * Build a minimal profile-shaped object from a user-workflow.json role.
+ * Used by the session manager + bridge-llm to keep the existing
+ * `session.profileId` code paths working without introducing a second
+ * registry.
+ */
+export function buildVirtualProfile(roleConfig) {
+    if (!roleConfig || !roleConfig.name) return null;
+    return {
+        id: roleConfig.name,
+        taskType: roleConfig.name,
+        tools: ROLE_TOOLS_UNIFIED,
+        permission: roleConfig.permission && roleConfig.permission !== 'full' ? roleConfig.permission : null,
+        fallbackPreset: roleConfig.preset || null,
+        description: roleConfig.desc_path || null,
+    };
+}