mixdog 0.7.1

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

@@ -0,0 +1,327 @@
+/**
+ * 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', …)
+    const hidden = getHiddenRole(role);
+    if (hidden) {
+        try {
+            const config = cfgIn || loadConfig();
+            const maint = config?.maintenance || {};
+            return maint[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

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