mixdog 0.7.18 → 0.8.0

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

@@ -1,331 +0,0 @@
-/**
- * Smart Bridge — Internal LLM Helper (session-based).
- *
- * Every one-shot LLM dispatch from internal callers (memory-cycle,
- * scheduler, webhook) now flows through the SAME session pipeline as the
- * MCP `bridge` tool. No more parallel `provider.send()` helper — one code
- * path = one message shape = one usage log = "bridge single path".
- *
- * The returned function uses the existing caller signature, so call sites
- * do not need changes:
- *
- *   const llm = makeBridgeLlm({ role: 'maintenance', preset: 'haiku' });
- *   const text = await llm({ prompt });
- *
- * Internally it:
- *   1. Resolves the preset (explicit arg > opts.preset > user-workflow.json[role])
- *   2. Creates or reuses a session via the session manager
- *   3. Applies stateless-reset for stateless profiles so the prefix handle
- *      stays warm while per-dispatch transcripts never leak
- *   4. Calls `askSession` → provider.send() → usage logged via
- *      `session/manager.mjs` (mode='active')
- */
-
-import { readFileSync } from 'fs';
-import { join } from 'path';
-import { loadConfig } from '../config.mjs';
-import { resolveRuntimeSpec } from '../config.mjs';
-import { getHiddenRole, resolveBridgeSessionPermission } from '../internal-roles.mjs';
-import { DEFAULT_PLUGIN, DEFAULT_MARKETPLACE } from '../../../shared/plugin-paths.mjs';
-import { prepareBridgeSession } from './session-builder.mjs';
-import {
-    askSession,
-    updateSessionStatus,
-    closeSession,
-} from '../session/manager.mjs';
-
-// Cap bridge role synthesis to ~3000 tokens (~12 KB at the 4 B/tok
-// working average). Pool B explore/recall/search answers occasionally land
-// 8-10k-token walls that then ride in the Lead context for the rest of the
-// turn; the cap keeps those outliers bounded without touching the 95%+ of
-// answers already under the threshold.
-const BRIEF_CAP_BYTES = 12 * 1024;
-function applyBriefCap(text) {
-    if (typeof text !== 'string') return text;
-    if (text.length <= BRIEF_CAP_BYTES) return text;
-    const head = text.slice(0, BRIEF_CAP_BYTES);
-    const approxTokens = Math.round(text.length / 4);
-    return `${head}\n\n... [TRUNCATED — full answer was ~${approxTokens} tokens / ${Math.round(text.length / 1024)} KB. Re-run with brief:false for the complete synthesis]`;
-}
-
-function pluginRoot() {
-    return process.env.CLAUDE_PLUGIN_ROOT
-        || join(process.env.HOME || process.env.USERPROFILE || '', '.claude', 'plugins', 'marketplaces', DEFAULT_MARKETPLACE, 'external_plugins', DEFAULT_PLUGIN);
-}
-
-// Unified-shard policy — most bridge sessions (Pool B + Pool C) share the
-// same tool schema so BP_1 is bit-identical across roles and one provider-side
-// cache shard serves every caller. Per-role behaviour is steered by:
-//   1. rules/bridge/*.md concatenated into BP2 roleCatalog (via
-//      loadScopedRoleCatalog — every bridge session carries the full
-//      hidden-role catalog so the shard stays bit-identical across roles)
-//   2. call-time guards (loop.mjs write-block + ai-wrapped-dispatch
-//      recursion break)
-// Hidden-role exceptions are declarative: defaults/hidden-roles.json may set
-// toolSchemaProfile when first-turn routing quality is worth a separate tool
-// prefix. Keep "unified" as the default; new profiles must justify the cache
-// shard split.
-// See manager.mjs resolveSessionTools for the single source of truth;
-// bridge visibility is declared via annotations.bridgeHidden on each tool def.
-const HIDDEN_ROLE_TOOL_SCHEMA_PROFILES = Object.freeze({
-    unified: null,
-    'llm-only': Object.freeze([]),
-    'filesystem-read': Object.freeze([
-        'code_graph',
-        'glob',
-        'list',
-        'grep',
-        'read',
-    ]),
-});
-
-export function resolveHiddenRoleSchemaAllowedTools(hidden) {
-    if (!hidden) return null;
-    if (Array.isArray(hidden.schemaAllowedTools)) {
-        return hidden.schemaAllowedTools.map((name) => String(name || '').trim()).filter(Boolean);
-    }
-    const profile = String(hidden.toolSchemaProfile || 'unified').trim() || 'unified';
-    if (Object.prototype.hasOwnProperty.call(HIDDEN_ROLE_TOOL_SCHEMA_PROFILES, profile)) {
-        return HIDDEN_ROLE_TOOL_SCHEMA_PROFILES[profile];
-    }
-    process.stderr.write(`[bridge-llm] unknown hidden-role toolSchemaProfile="${profile}" role="${hidden.name || 'unknown'}"; using unified schema\n`);
-    return null;
-}
-
-function buildUnifiedHeader({ permission, role }) {
-    const lines = [];
-    if (permission) lines.push(`Permission: ${permission}`);
-    if (role) lines.push(`Role: ${role}`);
-    if (lines.length === 0) return '';
-    lines.push('');
-    lines.push('---');
-    lines.push('');
-    return lines.join('\n');
-}
-
-/**
- * Resolve a preset name from (preset arg | opts.preset | hidden-role | user-workflow).
- *
- * Hidden roles (explorer, cycle1/cycle2, scheduler-task, etc.) are
- * plugin-managed and take precedence over user-workflow.json — users cannot
- * override them by redefining the same name.
- */
-export function resolvePresetName({ preset, optsPreset, role, config: cfgIn = null }) {
-    if (preset) return preset;
-    if (optsPreset) return optsPreset;
-    if (!role) return null;
-    // Hidden roles resolve their maintenance preset by SLOT. Every slot carries
-    // a concrete default in DEFAULT_MAINTENANCE, so `maint[slot]` resolves
-    // directly; the Setup panel can still tune each slot independently.
-    // (explorer.slot = 'explore', cycle1-agent.slot = 'cycle1', …). A hidden
-    // role may override which maintenance key it reads via `maintKey`
-    // (e.g. the cycle1/2/3 agents all read `maint.memory` instead of their
-    // own slot) so several agents can share one model knob while keeping
-    // distinct slots/identity.
-    const hidden = getHiddenRole(role);
-    if (hidden) {
-        try {
-            const config = cfgIn || loadConfig();
-            const maint = config?.maintenance || {};
-            return maint[hidden.maintKey || hidden.slot] || null;
-        } catch { return null; }
-    }
-    try {
-        const pluginData = process.env.CLAUDE_PLUGIN_DATA;
-        if (!pluginData) return null;
-        const wf = JSON.parse(readFileSync(join(pluginData, 'user-workflow.json'), 'utf8'));
-        if (!Array.isArray(wf.roles)) return null;
-        const entry = wf.roles.find((r) => r.name === role);
-        return entry ? entry.preset : null;
-    } catch {
-        return null;
-    }
-}
-
-/**
- * Build a bridge-backed LLM callback.
- *
- * @param {object} opts
- * @param {string} opts.role        — REQUIRED; canonical role name (worker, cycle1-agent, scheduler-task, ...)
- * @param {string} [opts.taskType]  — optional internal classification stamped on the session
- * @param {string} [opts.preset]    — explicit preset override (bypasses role → preset lookup)
- * @param {string} [opts.parentSessionId] — parent bridge session for trace aggregation
- * @param {AbortSignal} [opts.parentSignal] — optional AbortSignal from the fan-out coordinator;
- *   when aborted the bridge role session's own controller is also aborted so the
- *   provider call tears down promptly (parent→child cascade).
- * @returns {(args: { prompt, preset?, sourceName? }) => Promise<string>}
- */
-export function makeBridgeLlm(opts = {}) {
-    if (!opts.role || typeof opts.role !== 'string') {
-        throw new Error('[bridge-llm] opts.role is required');
-    }
-    const role = opts.role;
-
-    return async function bridgeLlm({ prompt, preset: presetArg, sourceName: sourceNameArg, parentSignal: callParentSignal, idleTimeoutMs: callIdleTimeoutMs }) {
-        if (typeof prompt !== 'string' || !prompt) {
-            throw new Error(`[bridge-llm] prompt required for role "${role}"`);
-        }
-
-        const config = opts.config || loadConfig();
-        const presetName = resolvePresetName({
-            preset: presetArg,
-            optsPreset: opts.preset,
-            role,
-            config,
-        });
-        if (!presetName) {
-            throw new Error(
-                `[bridge-llm] preset unresolved for role "${role}" `
-                + `(preset="${presetArg || opts.preset || ''}")`,
-            );
-        }
-
-        const preset = config.presets?.find((p) => p.id === presetName || p.name === presetName);
-        if (!preset) {
-            throw new Error(`[bridge-llm] preset "${presetName}" not found in mixdog-config.json`);
-        }
-
-        const runtimeSpec = resolveRuntimeSpec(preset, {
-            lane: 'bridge',
-            agentId: role,
-        });
-
-        // Callers (e.g. aiWrapped explore dispatch) may pass an explicit
-        // `cwd` to scope the agent's filesystem view. Absolute path expected
-        // (aiWrapped already expands `~` and resolves relatives). When unset
-        // we pass `null` through instead of falling back to `process.cwd()`
-        // — the MCP server's launch dir is not deterministic across callers,
-        // and the downstream skill-discovery path tolerates null. Combined
-        // with the frozen bridge skill meta-tools (collect.mjs) this keeps
-        // every caller on the same provider cache shard.
-        const cwd = (typeof opts.cwd === 'string' && opts.cwd) ? opts.cwd : null;
-
-        // Unified dispatch: Pool B/C share bit-identical tools + system prompt
-        // unless a hidden role declares a narrow toolSchemaProfile. Per-role
-        // differentiation rides in the user-message header (permission + role
-        // line) plus an optional short Pool C snippet. The read-only contract
-        // is still enforced at call time via loop.mjs's READ_BLOCKED_TOOLS
-        // guard; schema profiles are a routing-efficiency layer, not safety.
-        const hidden = getHiddenRole(role);
-        const isPoolC = Boolean(hidden);
-        // Permission: read-declared hidden roles are locked in
-        // resolveBridgeSessionPermission (prepareBridgeSession applies the same).
-        const permission = resolveBridgeSessionPermission(
-            role,
-            opts.permission ?? (isPoolC ? (hidden?.permission || 'read') : null),
-        );
-        // Pool C hidden-role instructions live in BP2 roleCatalog (loaded
-        // by loadScopedRoleCatalog from rules/bridge/*.md) — the Tier 3
-        // reminder is suppressed so the shard stays bit-identical across
-        // every bridge role.
-        //
-        // User message = pure query. Permission / role ride in BP3
-        // sessionMarker (composeSystemPrompt) — only the query varies per
-        // call, so provider cache reuses the shared prefix.
-        //
-        // Stateless ephemeral session — created fresh per call, never
-        // pooled or resumed. Cache prefix matching happens at the provider
-        // layer (account-level), not the session level.
-        const finalPrompt = prompt;
-        const { session } = prepareBridgeSession({
-            role,
-            presetName,
-            preset,
-            runtimeSpec,
-            permission,
-            cwd,
-            sourceType: opts.sourceType,
-            sourceName: sourceNameArg || opts.sourceName,
-            parentSessionId: opts.parentSessionId || null,
-            clientHostPid: opts.clientHostPid,
-            skipRoleReminder: isPoolC,
-            schemaAllowedTools: resolveHiddenRoleSchemaAllowedTools(hidden),
-            taskType: opts.taskType,
-            maxLoopIterations: opts.maxLoopIterations,
-        });
-        // Diagnostic — dump the actual tool names exposed to this LLM call,
-        // visible from the worker log instead of being hidden behind a
-        // count-only "tools=N" line.
-        try {
-            const _toolNames = (session.tools || []).map((t) => t?.name).filter(Boolean);
-            process.stderr.write(`[bridge-llm] role=${role} tool-list (${_toolNames.length}): ${_toolNames.join(',')}\n`);
-        } catch { /* best-effort diagnostic */ }
-
-        await updateSessionStatus(session.id, 'running');
-        // Parent→child abort cascade: when opts.parentSignal (factory) or
-        // callParentSignal (per-call) fires, abort the sub-session's own
-        // controller so the provider call tears down promptly. Best-effort:
-        // if the session/manager import is unavailable we fall back silently.
-        const _managerMod = await import('../session/manager.mjs').catch(() => null);
-        const _linkSignal = _managerMod?.linkParentSignalToSession;
-        const _getLastProgressAt = _managerMod?.getSessionLastProgressAt;
-        if (_linkSignal) {
-            if (opts.parentSignal instanceof AbortSignal) {
-                try { _linkSignal(session.id, opts.parentSignal); } catch { /* ignore */ }
-            }
-            if (callParentSignal instanceof AbortSignal) {
-                try { _linkSignal(session.id, callParentSignal); } catch { /* ignore */ }
-            }
-        }
-        // Idle-progress watchdog. A "session that's actually doing work"
-        // refreshes one of three runtime fields every chunk/tool-call.
-        // If none of those advance for `idleMs`, we treat the provider call
-        // as stuck (network black-hole, nested-spawn deadlock, etc.) and
-        // abort the sub-session controller. Routine long runs — multi-tool
-        // chains, slow streams — stay untouched because at least one of
-        // the three fields keeps ticking. `0` or negative disables the
-        // watchdog entirely; default is 120s.
-        const _idleMs = Number.isFinite(callIdleTimeoutMs)
-            ? callIdleTimeoutMs
-            : (Number.isFinite(opts.idleTimeoutMs) ? opts.idleTimeoutMs : 120_000);
-        const _idleController = (_idleMs > 0 && _linkSignal) ? new AbortController() : null;
-        if (_idleController) {
-            try { _linkSignal(session.id, _idleController.signal); } catch { /* ignore */ }
-        }
-        const _idleTimer = (_idleController && typeof _getLastProgressAt === 'function')
-            ? setInterval(() => {
-                const last = _getLastProgressAt(session.id);
-                if (!last) return; // ask hasn't started writing progress yet
-                if (Date.now() - last > _idleMs) {
-                    try {
-                        _idleController.abort(new Error(`idle timeout exceeded (${_idleMs}ms)`));
-                    } catch { /* ignore */ }
-                }
-            }, 1000)
-            : null;
-        if (_idleTimer && typeof _idleTimer.unref === 'function') _idleTimer.unref();
-        let terminalStatus = 'idle';
-        process.stderr.write(`[bridge-llm] role=${role} preset=${presetName} model=${preset.model} provider=${preset.provider} session=${session.id}\n`);
-        const _bridgeT0 = Date.now();
-        try {
-            const result = await askSession(session.id, finalPrompt, null, null, cwd);
-            process.stderr.write(`[bridge-llm] role=${role} session=${session.id} elapsed=${Date.now() - _bridgeT0}ms\n`);
-            const raw = result?.content || '';
-            // Brief cap. Bridge role answers (explore/recall/search)
-            // occasionally balloon to 8-10k token walls that then ride in the
-            // parent Lead's context for the rest of the turn. A 3000-token
-            // (~12 KB) ceiling trims the long tail while leaving the vast
-            // majority of answers untouched. Opt-out via `brief:false` when
-            // the caller explicitly wants the full synthesis.
-            if (opts.brief === false) {
-                try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
-                return raw;
-            }
-            const out = applyBriefCap(raw);
-            try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
-            return out;
-        } catch (err) {
-            terminalStatus = 'error';
-            try { closeSession(session.id, 'ephemeral-error'); } catch { /* ignore */ }
-            throw err;
-        } finally {
-            if (_idleTimer) {
-                try { clearInterval(_idleTimer); } catch { /* ignore */ }
-            }
-            // Always flip out of 'running' before returning so the sweep never
-            // leaves a stateless Pool C session stuck in 'running' when the
-            // try/catch falls through in unexpected ways.
-            try { await updateSessionStatus(session.id, terminalStatus); } catch { /* ignore */ }
-        }
-    };
-}

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

@@ -1,150 +0,0 @@
-/**
- * Smart Bridge — Cache Observability
- *
- * Normalizes raw provider usage objects into a unified CacheObservation
- * for cross-provider cache performance comparison.
- *
- * @typedef {Object} CacheObservation
- * @property {string}  provider           — provider name
- * @property {number}  cache_hit_tokens   — tokens read from cache
- * @property {number}  cache_write_tokens — tokens written to cache
- * @property {string|null} cache_ttl_tier — '5m' | '1h' | null
- * @property {number|null} cache_hit_ratio — 0.0–1.0, null if not computable
- * @property {boolean} cache_observable   — whether the provider reports cache metrics
- */
-
-/**
- * Normalize raw provider usage into a CacheObservation.
- *
- * @param {string} provider — one of the 10 supported providers
- * @param {object} rawUsage — raw usage object from provider response
- * @returns {CacheObservation}
- */
-export function normalizeUsage(provider, rawUsage) {
-    if (!rawUsage) {
-        return _empty(provider, false);
-    }
-
-    switch (provider) {
-        case 'anthropic':
-        case 'anthropic-oauth':
-            return _normalizeAnthropic(provider, rawUsage);
-
-        case 'openai':
-        case 'openai-oauth':
-        case 'xai':
-        case 'grok-oauth':
-            // xAI Responses usage mirrors OpenAI's shape:
-            // input_tokens_details.cached_tokens for prefix cache hits.
-            return _normalizeOpenai(provider, rawUsage);
-
-        case 'gemini':
-            return _normalizeGemini(provider, rawUsage);
-
-        case 'deepseek':
-            return _normalizeOpenai(provider, rawUsage);
-
-        case 'ollama':
-        case 'lmstudio':
-            return _empty(provider, false);
-
-        default:
-            return _empty(provider, false);
-    }
-}
-
-// --- Per-provider extractors ---
-
-function _normalizeAnthropic(provider, u) {
-    const hit = _num(u.cache_read_input_tokens);
-    const write = _num(u.cache_creation_input_tokens);
-    const input = _num(u.input_tokens);
-
-    // TTL tier: pick from cache_creation breakdown
-    let ttlTier = null;
-    if (u.cache_creation) {
-        if (_num(u.cache_creation.ephemeral_1h_input_tokens) > 0) ttlTier = '1h';
-        else if (_num(u.cache_creation.ephemeral_5m_input_tokens) > 0) ttlTier = '5m';
-    }
-
-    const total = hit + input + write;
-    const ratio = total > 0 ? hit / total : null;
-
-    return {
-        provider,
-        cache_hit_tokens: hit,
-        cache_write_tokens: write,
-        cache_ttl_tier: ttlTier,
-        cache_hit_ratio: ratio,
-        cache_observable: true,
-    };
-}
-
-function _normalizeOpenai(provider, u) {
-    // OpenAI: cached_tokens in prompt_tokens_details or input_tokens_details
-    const hit = _num(u.prompt_tokens_details?.cached_tokens)
-             || _num(u.input_tokens_details?.cached_tokens)
-             || 0;
-    const input = _num(u.prompt_tokens) || _num(u.input_tokens) || 0;
-    const ratio = input > 0 ? hit / input : null;
-
-    return {
-        provider,
-        cache_hit_tokens: hit,
-        cache_write_tokens: 0,
-        cache_ttl_tier: null,
-        cache_hit_ratio: ratio,
-        cache_observable: true,
-    };
-}
-
-function _normalizeGemini(provider, u) {
-    // Gemini: provider-normalized usage may already include fallback-adjusted
-    // cachedTokens. Raw SDK/REST usage reports cachedContentTokenCount.
-    const meta = u.usageMetadata || u;
-    const hit = _num(meta.cachedTokens)
-             || _num(meta.cached_tokens)
-             || _num(meta.effectiveCachedTokens)
-             || _num(meta.cachedContentTokenCount)
-             || _num(meta.cachedFallbackTokens)
-             || 0;
-    const observable = 'cachedTokens' in (meta || {})
-        || 'cached_tokens' in (meta || {})
-        || 'effectiveCachedTokens' in (meta || {})
-        || 'cachedContentTokenCount' in (meta || {})
-        || 'cachedFallbackTokens' in (meta || {});
-    const input = _num(meta.promptTokens)
-               || _num(meta.inputTokens)
-               || _num(meta.input_tokens)
-               || _num(meta.promptTokenCount)
-               || _num(meta.totalTokenCount)
-               || 0;
-    const ratio = input > 0 ? hit / input : null;
-
-    return {
-        provider,
-        cache_hit_tokens: hit,
-        cache_write_tokens: 0,
-        cache_ttl_tier: null,
-        cache_hit_ratio: ratio,
-        cache_observable: observable,
-    };
-}
-
-// --- Helpers ---
-
-function _empty(provider, observable) {
-    return {
-        provider,
-        cache_hit_tokens: 0,
-        cache_write_tokens: 0,
-        cache_ttl_tier: null,
-        cache_hit_ratio: null,
-        cache_observable: observable,
-    };
-}
-
-function _num(v) {
-    const n = Number(v);
-    return Number.isFinite(n) ? n : 0;
-}