mixdog 0.7.18 → 0.8.0

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

@@ -1,228 +0,0 @@
-/**
- * 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

@@ -1,215 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/**
- * 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,
-    };
-}