mixdog 0.8.0 → 0.9.0

package/src/runtime/agent/orchestrator/{smart-bridge → agent-runtime}/cache-strategy.mjs

@@ -1,25 +1,31 @@
 /**
- * Smart Bridge — Cache Strategy
+ * Agent Runtime — 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.
+ * breakpoints (up to 4 per request) — we spend them on the stable system /
+ * session prefix plus the reusable message tail. Non-breakpoint providers
+ * rely on provider-managed prefix routing or provider-local cache objects.
  *
- * Anthropic 4-BP layout (public/CLI):
- *   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   (1h)  — last message only; sliding extends prefix loss-free
+ * Anthropic 4-BP layout:
+ *   BP_1  system#1  (1h)  — shared tool policy + compact skill manifest
+ *   BP_2  system#2  (1h)  — role/system rules (Lead / agent / hidden role)
+ *   BP_3  system#3  (1h)  — stable memory/meta marker (sessionMarker system block; tier3)
+ *   BP_4  messages  (1h/5m) — sliding tool_result / prior user-text tail
  *
- * 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.
+ * Tool schemas still sit before system in the provider prompt prefix. We do
+ * not spend a separate cache_control slot on tools; the first system BP covers
+ * the preceding tool prefix via Anthropic prefix caching semantics. Keeping
+ * agent worker tool schemas byte-stable is therefore still load-bearing.
+ *
+ * Tier 3 gets its own BP because memory/meta context is stable within the
+ * session. The sliding messages BP handles tool_result accumulation and
+ * per-call task/event data without pinning volatile text into the 1h tier.
  *
  * 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.
+ *   - OpenAI OAuth: prompt_cache_key only (server in-memory 5-10min)
+ *   - Gemini: provider-managed explicit cachedContents with 1h TTL, plus
+ *     implicit caching as a fallback when the prefix is below cache minimums.
  *   - xAI: x-grok-conv-id (server routing pin) + prompt_cache_key on
  *     Responses API. Treat as key-prefix, not implicit.
  *   - DeepSeek / OpenCode Go: automatic KV/prefix cache; observe provider
@@ -34,7 +40,7 @@ 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.
+ * closed (agent-dispatch.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
@@ -60,7 +66,7 @@ function isOneShotMaintenanceRole(role) {
  *   '5m'   → ephemeral 5m TTL  (1.25x write premium, 0.1x read)
  *   'none' → no breakpoint written on this layer
  *
- * Public bridge agents stay resumable for up to 1h (the terminal-reap window)
+ * Public agents stay resumable for up to 1h (the terminal-reap window)
  * for same-task reuse, so their message tail uses 1h too. 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
@@ -80,10 +86,10 @@ export function resolveCacheStrategy(role) {
         return { tools: 'none', system: 'none', tier3: 'none', messages: 'none' };
     }
     if (getHiddenRole(role)) {
-        return { tools: '1h', system: '1h', tier3: '1h', messages: '5m' };
+        return { tools: 'none', system: '1h', tier3: '1h', messages: '5m' };
     }
-    // Public bridge agents: resumable up to 1h for same-task reuse → 1h tail.
-    return { tools: '1h', system: '1h', tier3: '1h', messages: '1h' };
+    // Public agents: resumable up to 1h for same-task reuse -> 1h tail.
+    return { tools: 'none', system: '1h', tier3: '1h', messages: '1h' };
 }
 
 /**
@@ -98,6 +104,7 @@ export function resolveCacheStrategy(role) {
 // Provider cache capability kinds:
 //   'explicit-breakpoint' — explicit provider-side cache_control writes
 //   'key-prefix'          — provider-managed shard keyed by cache key/session
+//   'managed-explicit'    — provider object creates/attaches explicit caches
 //   'implicit-observed'   — cache hits are observable but not guaranteed warm
 //   'none'                — no API-level cache knob/metric
 const PROVIDER_CACHE_CAPABILITY = Object.freeze({
@@ -107,7 +114,7 @@ const PROVIDER_CACHE_CAPABILITY = Object.freeze({
     'openai-oauth':    'key-prefix',
     'xai':             'key-prefix',
     'grok-oauth':      'key-prefix',
-    'gemini':          'implicit-observed',
+    'gemini':          'managed-explicit',
     'deepseek':        'implicit-observed',
     'opencode-go':     'implicit-observed',
 });
@@ -118,7 +125,9 @@ export function cacheCapabilityForProvider(provider) {
 
 export function shouldMarkWarmForProvider(provider) {
     const capability = cacheCapabilityForProvider(provider);
-    return capability === 'explicit-breakpoint' || capability === 'key-prefix';
+    return capability === 'explicit-breakpoint'
+        || capability === 'key-prefix'
+        || capability === 'managed-explicit';
 }
 
 export function shouldRecordObservedForProvider(provider) {
@@ -183,7 +192,7 @@ function cleanString(value) {
 
 function normalizePromptCacheNamespace(value) {
     const s = String(value || '').trim() || 'mixdog-shared';
-    // Keep the key boring for OpenAI/Codex's 64-char prompt_cache_key cap while
+    // Keep the key boring for OpenAI OAuth's 64-char prompt_cache_key cap while
     // preserving user overrides as much as possible.
     return s.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'mixdog-shared';
 }
@@ -358,7 +367,7 @@ export function buildProviderCacheOpts(provider, sessionId, role) {
     }
     if (provider === 'openai') {
         // Public OpenAI API: prompt_cache_retention extends prefix retention.
-        // openai-oauth (Codex) rejects the header — falls through to default.
+        // openai-oauth rejects the header — falls through to default.
         return { cacheRetention: '24h' };
     }
     return {};

package/src/runtime/agent/orchestrator/{smart-bridge → agent-runtime}/session-builder.mjs

@@ -1,28 +1,26 @@
 /**
- * Smart Bridge — shared session builder.
+ * Agent Runtime — shared session builder.
  *
- * Single source of truth for bridge session creation + role/preset
+ * Single source of truth for agent session creation + role/preset
  * telemetry. Both entry points route through this helper:
  *
- *   - `smart-bridge/bridge-llm.mjs` — internal callers
+ *   - `agent-runtime/agent-dispatch.mjs` — internal callers
  *     (memory-cycle, scheduler, webhook) dispatching via
- *     `makeBridgeLlm`.
- *   - `src/agent/index.mjs` `case 'bridge'` — Lead-originated MCP
- *     bridge dispatches into user-workflow roles.
+ *     `makeAgentDispatch`.
+ *   - Lead-originated agent dispatches into configured workflow agents.
  *
  * Before this helper, the two paths carried separate `createSession` +
- * `traceBridgePreset` blocks. Lead-direct dispatches silently skipped
- * the trace so cache-hit analysis missed every user-workflow role call.
+ * `traceAgentPreset` blocks. Lead-direct dispatches silently skipped
+ * the trace so cache-hit analysis missed every public agent call.
  *
  * Preset resolution stays with each caller since they read from
- * different sources (MCP: user-workflow.json only; Smart Bridge:
- * hidden-role map first, then user-workflow.json). The helper takes
- * already-resolved primitives.
+ * different sources. The helper takes already-resolved primitives.
  */
 
 import { createSession } from '../session/manager.mjs';
-import { traceBridgePreset } from '../bridge-trace.mjs';
-import { resolveBridgeSessionPermission } from '../internal-roles.mjs';
+import { traceAgentPreset } from '../agent-trace.mjs';
+import { resolveAgentSessionPermission } from '../internal-roles.mjs';
+import { loadConfig } from '../config.mjs';
 
 /**
  * @param {object} opts
@@ -30,10 +28,10 @@ import { resolveBridgeSessionPermission } from '../internal-roles.mjs';
  * @param {string}  opts.presetName    — resolved preset identifier
  * @param {object}  opts.preset        — resolved preset object from agent-config
  * @param {object}  opts.runtimeSpec   — resolveRuntimeSpec output; must carry .scopeKey / .lane
- * @param {string}  [opts.permission]  — 'read' | 'read-write' | null (preset/full default when unset)
- * @param {string|null} [opts.cwd]     — absolute working dir; null is the fixed bridge sentinel meaning "no caller workspace context"
- * @param {string}  [opts.owner='bridge']
- * @param {string}  [opts.permissionMode] — Claude Code permissionMode forwarded from the MCP payload ('bypassPermissions', 'acceptEdits', 'plan', 'dontAsk', 'default')
+ * @param {string}  [opts.permission]  — 'none' | 'read' | 'read-write' | 'mcp' | 'full' | null
+ * @param {string|null} [opts.cwd]     — absolute working dir; null is the fixed agent sentinel meaning "no caller workspace context"
+ * @param {string}  [opts.owner='agent']
+ * @param {string}  [opts.permissionMode] — permissionMode forwarded from the MCP payload ('bypassPermissions', 'acceptEdits', 'plan', 'dontAsk', 'default')
  * @param {string[]} [opts.schemaAllowedTools] — schema-level allowlist from a hidden-role toolSchemaProfile
  * @param {string}  [opts.sourceType]
  * @param {string}  [opts.sourceName]
@@ -41,17 +39,16 @@ import { resolveBridgeSessionPermission } from '../internal-roles.mjs';
  * @param {number}  [opts.maxLoopIterations]
  * @param {string}  [opts.parentSessionId]
  * @param {string|null} [opts.ownerSessionId] - owning Mixdog MCP instance id for statusline isolation
- * @param {boolean} [opts.skipRoleReminder=false] — Pool C suppresses Tier 3 reminder
  * @returns {{ session: object, effectiveCwd: string|null }}
  */
-export function prepareBridgeSession({
+export function prepareAgentSession({
     role,
     presetName,
     preset,
     runtimeSpec,
     permission,
     cwd,
-    owner = 'bridge',
+    owner = 'agent',
     permissionMode,
     sourceType,
     sourceName,
@@ -60,13 +57,12 @@ export function prepareBridgeSession({
     parentSessionId,
     ownerSessionId,
     clientHostPid,
-    bridgeTag,
-    skipRoleReminder = false,
+    agentTag,
     cacheKeyOverride,
     schemaAllowedTools,
 }) {
-    const effectivePermission = resolveBridgeSessionPermission(role, permission);
-    // Pass cwd through verbatim — null is the fixed bridge sentinel meaning
+    const effectivePermission = resolveAgentSessionPermission(role, permission);
+    // Pass cwd through verbatim — null is the fixed agent sentinel meaning
     // "no caller workspace context" (cycle1-agent shards, etc). Upgrading
     // null → process.cwd() here would defeat cache-shard fork suppression.
     // Downstream collectors (collect.mjs) handle null as "no project cwd".
@@ -74,6 +70,16 @@ export function prepareBridgeSession({
     const effectiveOwnerSessionId = ownerSessionId === undefined
         ? (process.env.MIXDOG_OWNER_SESSION_ID || null)
         : ownerSessionId;
+    let compaction = null;
+    try {
+        const cfg = loadConfig({ secrets: false });
+        // Agent worker sessions should keep the higher-quality semantic compact
+        // path even when the Lead session uses recall-fasttrack for cheap
+        // auto-clear/auto-compact. Cycle maintenance prompts are small enough
+        // that this normally only matters for long-lived worker conversations.
+        const base = cfg?.compaction && typeof cfg.compaction === 'object' ? cfg.compaction : {};
+        compaction = { ...base, type: '1', compactType: '1' };
+    } catch { /* config is best-effort for agent compaction policy */ }
     const sessionOpts = {
         preset,
         owner,
@@ -87,18 +93,18 @@ export function prepareBridgeSession({
         sourceName: sourceName || undefined,
         ownerSessionId: effectiveOwnerSessionId || null,
         clientHostPid: clientHostPid || null,
+        compaction: compaction || undefined,
     };
-    if (bridgeTag) sessionOpts.bridgeTag = bridgeTag;
+    if (agentTag) sessionOpts.agentTag = agentTag;
     if (effectivePermission) sessionOpts.permission = effectivePermission;
     if (permissionMode) sessionOpts.permissionMode = permissionMode;
-    if (skipRoleReminder) sessionOpts.skipRoleReminder = true;
     if (cacheKeyOverride) sessionOpts.cacheKeyOverride = cacheKeyOverride;
     if (Array.isArray(schemaAllowedTools)) {
         sessionOpts.schemaAllowedTools = schemaAllowedTools;
     }
     const session = createSession(sessionOpts);
     try {
-        traceBridgePreset({
+        traceAgentPreset({
             sessionId: session.id,
             role: role || null,
             presetName: presetName || null,