mixdog 0.9.2 → 0.9.4

package/src/runtime/agent/orchestrator/session/manager/context-meta.mjs

@@ -0,0 +1,230 @@
+// Context-window sizing, compaction target math, and session context-meta
+// resolution. Extracted verbatim from manager.mjs (behavior-preserving).
+import { getModelMetadataSync } from '../../providers/model-catalog.mjs';
+import { resolveCompactTriggerTokens } from '../context-utils.mjs';
+import { normalizeCompactType, DEFAULT_COMPACT_TYPE } from '../compact.mjs';
+
+// Known context windows for the current-generation models this plugin
+// routes to. Anything not listed falls through to guessContextWindow() —
+// local llama/mistral/phi default to 8192, everything else 128000. Keep
+// this map trimmed to live models; older generations slow down reads
+// without buying anything.
+const CONTEXT_WINDOWS = {
+    // OpenAI GPT-5.x family (openai / openai-oauth)
+    'gpt-5.5': 272000,
+    'gpt-5.4': 272000,
+    'gpt-5.4-mini': 272000,
+    'gpt-5.4-nano': 272000,
+    // Anthropic Claude 4.x
+    'claude-opus-4-8': 1000000,
+    'claude-opus-4-7': 1000000,
+    'claude-sonnet-4-6': 1000000,
+    'claude-haiku-4-5-20251001': 200000,
+    // Google Gemini 3.x
+    'gemini-3.1-pro': 1000000,
+    'gemini-3-pro': 1000000,
+    'gemini-3.5-flash': 1000000,
+    'gemini-3-flash': 1000000,
+    // xAI Grok (catalog polyfill mirror — model-catalog PRICING_OVERRIDES)
+    'grok-build-0.1': 256000,
+    'grok-4.20': 1000000,
+};
+// Family-pattern fallback used only when both the provider catalog and the
+// exact-id table miss (cold metadata, before the LiteLLM/models.dev catalog
+// warms). Keep these aligned with the catalog so /context, gateway, and the
+// runtime agree on the boundary the first time a model is routed. Local models
+// (llama/mistral/phi/qwen/gemma) stay small so an unknown local id never claims
+// a giant window.
+const LOCAL_PROVIDERS = new Set(['ollama', 'lmstudio', 'llamacpp', 'llama.cpp', 'local', '']);
+export function guessContextWindow(model, provider = null) {
+    if (CONTEXT_WINDOWS[model])
+        return CONTEXT_WINDOWS[model];
+    const m = String(model || '').toLowerCase();
+    const p = String(provider || '').toLowerCase();
+    const isLocalProvider = LOCAL_PROVIDERS.has(p);
+    // Local/self-hosted families — never inflate an unknown local id.
+    if (isLocalProvider && (m.includes('llama') || m.includes('mistral') || m.includes('mixtral')
+        || m.includes('phi') || m.includes('qwen') || m.includes('gemma')
+        || m.includes('deepseek-r1') || m.includes('codellama')))
+        return 8192;
+    // Current hosted families by name pattern.
+    if (m.startsWith('claude-opus') || m.startsWith('claude-sonnet')) return 1000000;
+    if (m.startsWith('claude-haiku') || m.startsWith('claude-')) return 200000;
+    if (m.startsWith('gemini-3') || m.startsWith('gemini-2')) return 1000000;
+    if (m.startsWith('gpt-5')) return 272000;
+    if (m.startsWith('grok-build')) return 256000;
+    if (m.startsWith('grok-')) return 1000000;
+    if (m.startsWith('deepseek-v')) return 1000000;
+    return 128000;
+}
+export function positiveContextWindow(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+export function envFlag(name, fallback = false) {
+    const v = process.env[name];
+    if (v === undefined) return fallback;
+    return !['0', 'false', 'off', 'no'].includes(String(v).trim().toLowerCase());
+}
+function boundedPercent(value, fallback = null) {
+    const n = Number(value);
+    if (Number.isFinite(n) && n > 0 && n <= 100) return n;
+    return fallback;
+}
+function providerNameOf(provider) {
+    if (typeof provider === 'string') return provider.toLowerCase();
+    return String(provider?.name || provider?.id || '').toLowerCase();
+}
+// Carry the percent/ratio-named buffer config from a compaction config object
+// onto session.compaction so the shared compact-policy parser honors configured
+// buffer
+// percent/ratio. Only finite positive values are copied; absent fields stay
+// undefined so the default-ratio fallback still applies.
+export function preserveBufferConfigFields(cfg = {}) {
+    const out = {};
+    for (const key of ['bufferPercent', 'bufferPct', 'bufferRatio', 'bufferFraction']) {
+        const n = Number(cfg?.[key]);
+        if (Number.isFinite(n) && n > 0) out[key] = n;
+    }
+    return out;
+}
+const COMPACT_TARGET_RATIO = 0.02;
+const COMPACT_TARGET_MIN_TOKENS = 4_000;
+const COMPACT_TARGET_MAX_TOKENS = 16_000;
+function compactTargetRatio() {
+    const raw = process.env.MIXDOG_AGENT_COMPACT_TARGET_PERCENT
+        ?? process.env.MIXDOG_COMPACT_TARGET_PERCENT
+        ?? COMPACT_TARGET_RATIO;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) return COMPACT_TARGET_RATIO;
+    return n > 1 ? n / 100 : n;
+}
+function compactTargetTokensForBoundary(boundaryTokens) {
+    const boundary = positiveContextWindow(boundaryTokens);
+    if (!boundary) return null;
+    const explicit = positiveContextWindow(
+        process.env.MIXDOG_AGENT_COMPACT_TARGET_TOKENS
+            ?? process.env.MIXDOG_COMPACT_TARGET_TOKENS,
+    );
+    if (explicit) return Math.max(1, Math.min(boundary, explicit));
+    const minTarget = Math.min(boundary, positiveContextWindow(process.env.MIXDOG_COMPACT_TARGET_MIN_TOKENS) || COMPACT_TARGET_MIN_TOKENS);
+    const maxTarget = Math.min(boundary, positiveContextWindow(process.env.MIXDOG_COMPACT_TARGET_MAX_TOKENS) || COMPACT_TARGET_MAX_TOKENS);
+    const byRatio = Math.max(1, Math.floor(boundary * compactTargetRatio()));
+    return Math.max(1, Math.min(boundary, maxTarget, Math.max(minTarget, byRatio)));
+}
+function defaultEffectiveContextWindowPercent(provider) {
+    // Gateway/statusline route metadata reserves a universal 10% headroom from
+    // the raw catalog window. Keep session compaction on the same effective
+    // capacity so /context, the TUI statusline, and gateway telemetry agree.
+    return 90;
+}
+const PROVIDER_SYNTHETIC_CONTEXT_DEFAULT = 1_000_000;
+function providerRawContextWindow(info, catalogInfo) {
+    if (!info || typeof info !== 'object') return null;
+    const fromApiFields = positiveContextWindow(info.context_window)
+        || positiveContextWindow(info.max_context_window);
+    if (fromApiFields) return fromApiFields;
+    const fromCache = positiveContextWindow(info.contextWindow)
+        || positiveContextWindow(info.maxContextWindow);
+    if (!fromCache) return null;
+    const catalogWindow = positiveContextWindow(catalogInfo?.contextWindow)
+        || positiveContextWindow(catalogInfo?.maxContextWindow)
+        || positiveContextWindow(catalogInfo?.context_window)
+        || positiveContextWindow(catalogInfo?.max_context_window);
+    if (fromCache === PROVIDER_SYNTHETIC_CONTEXT_DEFAULT
+        && catalogWindow
+        && fromCache !== catalogWindow) {
+        return null;
+    }
+    return fromCache;
+}
+export function resolveSessionContextMeta(provider, model, seed = {}) {
+    const info = typeof provider?.getCachedModelInfo === 'function'
+        ? provider.getCachedModelInfo(model)
+        : null;
+    const catalogInfo = getModelMetadataSync(model, providerNameOf(provider));
+    const rawContextWindow = providerRawContextWindow(info, catalogInfo)
+        || positiveContextWindow(catalogInfo?.contextWindow)
+        || positiveContextWindow(catalogInfo?.maxContextWindow)
+        || positiveContextWindow(catalogInfo?.context_window)
+        || positiveContextWindow(catalogInfo?.max_context_window)
+        || positiveContextWindow(seed.rawContextWindow)
+        || positiveContextWindow(seed.raw_context_window)
+        || positiveContextWindow(seed.contextWindow)
+        || guessContextWindow(model, providerNameOf(provider));
+    const effectiveContextWindowPercent = boundedPercent(
+        seed.effectiveContextWindowPercent
+            ?? seed.effective_context_window_percent
+            ?? info?.effectiveContextWindowPercent
+            ?? info?.effective_context_window_percent
+            ?? catalogInfo?.effectiveContextWindowPercent
+            ?? catalogInfo?.effective_context_window_percent,
+        defaultEffectiveContextWindowPercent(provider),
+    );
+    const pct = boundedPercent(effectiveContextWindowPercent, 100);
+    const contextWindow = Math.max(1, Math.floor(rawContextWindow * pct / 100));
+    const compactBoundaryTokens = contextWindow;
+    const rawCompactLimit = positiveContextWindow(
+        seed.autoCompactTokenLimit
+            ?? seed.auto_compact_token_limit
+            ?? info?.autoCompactTokenLimit
+            ?? info?.auto_compact_token_limit
+            ?? catalogInfo?.autoCompactTokenLimit
+            ?? catalogInfo?.auto_compact_token_limit,
+    );
+    // Legacy-data migration: old implementations derived autoCompactTokenLimit
+    // from the full effective/raw window and persisted it onto the session.
+    // A resumed session therefore re-seeds autoCompactTokenLimit == boundary
+    // (or the raw window), which compactTriggerForSession / loop policy used to
+    // honor as an explicit trigger, collapsing the compaction buffer to 0. Only
+    // accept an explicit limit that is STRICTLY BELOW the boundary; a value at
+    // or above the boundary is a derived full-window artifact and is dropped to
+    // null so the trigger falls back to the default boundary trigger.
+    const explicitCompactLimit = rawCompactLimit && rawCompactLimit < compactBoundaryTokens
+        ? rawCompactLimit
+        : null;
+    // Do NOT derive the auto-compact limit from the full effective window.
+    // Setting it to contextWindow makes autoTriggerTokens == boundary and the
+    // compaction buffer collapse to 0 (loop.mjs:708-713 / compactTriggerForSession),
+    // so auto-compact only fires when the context is already at the limit —
+    // at which point semantic compact fails ("result exceeds budget" /
+    // "summary cannot fit") and the turn can no longer be resumed.
+    // Leave it null unless the provider/catalog/seed supplies an explicit
+    // limit; the downstream buffer logic (default 10%, capped 25%) then
+    // triggers compaction with headroom, matching the reference auto-compact threshold.
+    const autoCompactTokenLimit = explicitCompactLimit || null;
+    return {
+        contextWindow,
+        rawContextWindow,
+        effectiveContextWindowPercent,
+        autoCompactTokenLimit: autoCompactTokenLimit || null,
+        compactBoundaryTokens,
+    };
+}
+export function compactTriggerForSession(session, boundaryTokens) {
+    return resolveCompactTriggerTokens(session, boundaryTokens);
+}
+export function compactTargetBudget(boundaryTokens, reserveTokens, _sourceTokens = null, _ratio = null) {
+    const boundary = positiveContextWindow(boundaryTokens);
+    if (!boundary) return null;
+    const reserve = Math.max(0, Number(reserveTokens) || 0);
+    const targetEffective = compactTargetTokensForBoundary(boundary) || boundary;
+    return Math.max(1, Math.min(boundary, targetEffective + reserve));
+}
+export function semanticCompactionEnabledForSession(session) {
+    const cfg = session?.compaction || {};
+    if (process.env.MIXDOG_AGENT_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_AGENT_COMPACT_SEMANTIC', true);
+    if (process.env.MIXDOG_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_COMPACT_SEMANTIC', true);
+    if (cfg.semantic === false || cfg.semantic === 'false' || cfg.semantic === 'off') return false;
+    if (cfg.semantic === true || cfg.semantic === 'true' || cfg.semantic === 'on' || cfg.semantic === 'auto') return true;
+    return true;
+}
+export function compactTypeForSession(session) {
+    const cfg = session?.compaction || {};
+    const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
+        ?? process.env.MIXDOG_COMPACT_TYPE
+        ?? cfg.type
+        ?? cfg.compactType
+        ?? cfg.compact_type;
+    return normalizeCompactType(configured, DEFAULT_COMPACT_TYPE);
+}

package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs

@@ -0,0 +1,235 @@
+// Steering / pending-message queue with sync buffered + atomic-file persistence.
+// Extracted verbatim from manager.mjs (behavior-preserving).
+import { join } from 'path';
+import { resolvePluginData } from '../../../../shared/plugin-paths.mjs';
+import { updateJsonAtomicSync } from '../../../../shared/atomic-file.mjs';
+import { promptContentText, isInternalRuntimeNotificationText } from './prompt-utils.mjs';
+
+const _sessionPendingMessages = new Map();
+const PENDING_MESSAGES_FILE = 'session-pending-messages.json';
+const PENDING_MESSAGES_MODE = 0o600;
+const _pendingPersistBuffers = new Map();
+let _pendingPersistImmediate = null;
+
+function pendingMessagesPath() {
+    return join(resolvePluginData(), PENDING_MESSAGES_FILE);
+}
+
+function isValidPendingSessionId(sessionId) {
+    return typeof sessionId === 'string' && /^[A-Za-z0-9_-]+$/.test(sessionId);
+}
+
+function normalizePendingStore(raw) {
+    const sessions = raw && typeof raw === 'object' && raw.sessions && typeof raw.sessions === 'object'
+        ? raw.sessions
+        : {};
+    const out = { version: 1, updatedAt: Date.now(), sessions: {} };
+    for (const [sid, value] of Object.entries(sessions)) {
+        if (!isValidPendingSessionId(sid) || !Array.isArray(value)) continue;
+        const q = value
+            .map((entry) => {
+                if (typeof entry === 'string') return entry;
+                if (entry && typeof entry === 'object' && typeof entry.message === 'string') return entry.message;
+                return '';
+            })
+            .filter(Boolean);
+        if (q.length > 0) out.sessions[sid] = q;
+    }
+    return out;
+}
+
+function normalizePendingMessageEntry(entry) {
+    if (typeof entry === 'string') {
+        const text = entry.trim();
+        return text ? { content: text, text } : null;
+    }
+    if (Array.isArray(entry)) {
+        if (entry.length === 0) return null;
+        const text = promptContentText(entry).trim();
+        return { content: entry, text };
+    }
+    if (!entry || typeof entry !== 'object') return null;
+    const content = Object.prototype.hasOwnProperty.call(entry, 'content') ? entry.content : null;
+    if (content == null) return null;
+    const text = typeof entry.text === 'string' ? entry.text.trim() : promptContentText(content).trim();
+    if (Array.isArray(content)) return content.length > 0 ? { content, text } : null;
+    if (typeof content === 'string') {
+        const value = content.trim();
+        return value ? { content: value, text: text || value } : null;
+    }
+    const fallback = promptContentText(content).trim();
+    return fallback ? { content: fallback, text: text || fallback } : null;
+}
+
+function pendingMessageText(entry) {
+    const normalized = normalizePendingMessageEntry(entry);
+    return normalized ? String(normalized.text || promptContentText(normalized.content) || '').trim() : '';
+}
+
+function pendingMessageQueueEntry(entry) {
+    const normalized = normalizePendingMessageEntry(entry);
+    if (!normalized) return null;
+    if (typeof normalized.content === 'string' && normalized.content === normalized.text) return normalized.content;
+    return { content: normalized.content, text: normalized.text || promptContentText(normalized.content).trim() };
+}
+
+function persistPendingMessages(sessionId, messages) {
+    if (!isValidPendingSessionId(sessionId)) return 0;
+    const persistedMessages = (Array.isArray(messages) ? messages : [messages])
+        .map(pendingMessageText)
+        .filter(Boolean);
+    if (persistedMessages.length === 0) return 0;
+    let depth = 0;
+    try {
+        updateJsonAtomicSync(pendingMessagesPath(), (raw) => {
+            const next = normalizePendingStore(raw);
+            const q = Array.isArray(next.sessions[sessionId]) ? next.sessions[sessionId] : [];
+            q.push(...persistedMessages);
+            next.sessions[sessionId] = q;
+            next.updatedAt = Date.now();
+            depth = q.length;
+            return next;
+        }, { compact: true, lock: true, mode: PENDING_MESSAGES_MODE, fsync: false });
+    } catch (err) {
+        try { process.stderr.write(`[session] pending-message persist failed sessionId=${sessionId}: ${err?.message || err}\n`); } catch {}
+    }
+    return depth;
+}
+
+function flushPendingMessagePersistsSync() {
+    if (_pendingPersistImmediate) {
+        try { clearImmediate(_pendingPersistImmediate); } catch {}
+        _pendingPersistImmediate = null;
+    }
+    if (_pendingPersistBuffers.size === 0) return;
+    const batches = [..._pendingPersistBuffers.entries()];
+    _pendingPersistBuffers.clear();
+    for (const [sid, messages] of batches) {
+        persistPendingMessages(sid, messages);
+    }
+}
+
+function schedulePendingMessagePersist(sessionId, message) {
+    if (!isValidPendingSessionId(sessionId)) return 0;
+    const persistedMessage = pendingMessageText(message);
+    if (!persistedMessage) return 0;
+    const q = _pendingPersistBuffers.get(sessionId) || [];
+    q.push(persistedMessage);
+    _pendingPersistBuffers.set(sessionId, q);
+    if (!_pendingPersistImmediate) {
+        _pendingPersistImmediate = setImmediate(() => {
+            _pendingPersistImmediate = null;
+            flushPendingMessagePersistsSync();
+        });
+    }
+    return q.length;
+}
+
+function takeBufferedPendingMessages(sessionId) {
+    if (!isValidPendingSessionId(sessionId)) return [];
+    const buffered = _pendingPersistBuffers.get(sessionId);
+    if (!buffered || buffered.length === 0) return [];
+    _pendingPersistBuffers.delete(sessionId);
+    return buffered.slice();
+}
+
+function drainPersistedPendingMessages(sessionId) {
+    if (!isValidPendingSessionId(sessionId)) return [];
+    let drained = [];
+    try {
+        updateJsonAtomicSync(pendingMessagesPath(), (raw) => {
+            const next = normalizePendingStore(raw);
+            const q = Array.isArray(next.sessions[sessionId]) ? next.sessions[sessionId] : [];
+            drained = q.filter((m) => typeof m === 'string' && m.length > 0);
+            if (drained.length === 0) return undefined;
+            delete next.sessions[sessionId];
+            next.updatedAt = Date.now();
+            return next;
+        }, { compact: true, lock: true, mode: PENDING_MESSAGES_MODE, fsync: false });
+    } catch (err) {
+        try { process.stderr.write(`[session] pending-message drain failed sessionId=${sessionId}: ${err?.message || err}\n`); } catch {}
+    }
+    return drained;
+}
+
+function modelVisiblePendingMessages(messages) {
+    return (Array.isArray(messages) ? messages : [])
+        .map(pendingMessageQueueEntry)
+        .filter(Boolean)
+        .filter((message) => !isInternalRuntimeNotificationText(
+            message && typeof message === 'object' && Object.prototype.hasOwnProperty.call(message, 'content')
+                ? message.content
+                : message,
+        ));
+}
+
+export function _mergePendingMessageEntries(entries) {
+    const normalized = (Array.isArray(entries) ? entries : [])
+        .map(normalizePendingMessageEntry)
+        .filter(Boolean);
+    if (normalized.length === 0) return null;
+    const displayText = normalized.map((entry) => entry.text || promptContentText(entry.content))
+        .filter((text) => String(text || '').trim())
+        .join('\n');
+    if (normalized.every((entry) => typeof entry.content === 'string')) {
+        return {
+            content: normalized.map((entry) => entry.content).filter(Boolean).join('\n'),
+            text: displayText,
+            count: normalized.length,
+        };
+    }
+    const parts = [];
+    for (const entry of normalized) {
+        if (typeof entry.content === 'string') {
+            if (entry.content.trim()) parts.push({ type: 'text', text: entry.content });
+        } else if (Array.isArray(entry.content)) {
+            parts.push(...entry.content);
+        } else {
+            const text = promptContentText(entry.content);
+            if (text.trim()) parts.push({ type: 'text', text });
+        }
+        parts.push({ type: 'text', text: '\n' });
+    }
+    while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
+    return { content: parts, text: displayText || promptContentText(parts), count: normalized.length };
+}
+
+export function enqueuePendingMessage(sessionId, message) {
+    const entry = pendingMessageQueueEntry(message);
+    if (!sessionId || !entry) return 0;
+    let q = _sessionPendingMessages.get(sessionId);
+    if (!q) { q = []; _sessionPendingMessages.set(sessionId, q); }
+    q.push(entry);
+    const bufferedDepth = schedulePendingMessagePersist(sessionId, entry);
+    return Math.max(q.length, bufferedDepth || 0);
+}
+
+export function drainPendingMessages(sessionId) {
+    const q = _sessionPendingMessages.get(sessionId);
+    const memory = q && q.length > 0 ? q.slice() : [];
+    _sessionPendingMessages.delete(sessionId);
+    const persisted = [...takeBufferedPendingMessages(sessionId), ...drainPersistedPendingMessages(sessionId)];
+    const memoryVisible = modelVisiblePendingMessages(memory);
+    const persistedVisible = modelVisiblePendingMessages(persisted);
+    if (memoryVisible.length === 0) return persistedVisible;
+    if (persistedVisible.length === 0) return memoryVisible;
+    const persistedTexts = persistedVisible.map(pendingMessageText);
+    const prefixMatches = memoryVisible.every((m, i) => persistedTexts[i] === pendingMessageText(m));
+    if (prefixMatches) return [...memoryVisible, ...persistedVisible.slice(memoryVisible.length)];
+    const out = persistedVisible.slice();
+    const seen = new Set(persistedTexts);
+    for (const m of memoryVisible) {
+        const text = pendingMessageText(m);
+        if (!text || seen.has(text)) continue;
+        out.push(m);
+        seen.add(text);
+    }
+    return out;
+}
+
+// Cleanup hook for closeSession — drop the in-memory queue and buffered-persist
+// entry so both Maps do not accumulate one entry per closed session.
+export function _dropPendingMessageState(id) {
+    try { _sessionPendingMessages.delete(id); } catch { /* ignore */ }
+    try { _pendingPersistBuffers.delete(id); } catch { /* ignore */ }
+}

package/src/runtime/agent/orchestrator/session/manager/prompt-utils.mjs

@@ -0,0 +1,149 @@
+// Prompt content + temporal helpers, extracted verbatim from manager.mjs
+// (behavior-preserving). Pure string/date utilities with no session state.
+import { isInternalRuntimeNotificationText as contractIsInternalRuntimeNotificationText } from '../../../../shared/tool-execution-contract.mjs';
+import { SUMMARY_PREFIX } from '../compact.mjs';
+
+export function promptContentText(content) {
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+        return content.map((part) => {
+            if (typeof part === 'string') return part;
+            if (part?.type === 'text') return part.text || '';
+            if (part?.type === 'image') return '[Image]';
+            return part?.text || '';
+        }).filter(Boolean).join('\n');
+    }
+    return String(content ?? '');
+}
+
+export function hasModelVisiblePromptContent(prompt) {
+    return !!promptContentText(prompt).trim();
+}
+
+export function promptContentBytes(content) {
+    try {
+        if (typeof content === 'string') return Buffer.byteLength(content, 'utf8');
+        return Buffer.byteLength(JSON.stringify(content), 'utf8');
+    } catch {
+        return Buffer.byteLength(promptContentText(content), 'utf8');
+    }
+}
+
+export function prefixUserTurnContent(content, contextBlock) {
+    if (!contextBlock) return content;
+    if (Array.isArray(content)) {
+        return [{ type: 'text', text: `${contextBlock}# Task\n` }, ...content];
+    }
+    return `${contextBlock}# Task\n${content}`;
+}
+
+export function prefixSessionStartContent(content, sessionBlock) {
+    if (!sessionBlock) return content;
+    if (Array.isArray(content)) {
+        return [{ type: 'text', text: `${sessionBlock}\n\n` }, ...content];
+    }
+    return `${sessionBlock}\n\n${content}`;
+}
+
+function localIsoDate(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+
+function localDateTimeWithZone(date = new Date()) {
+    const datePart = localIsoDate(date);
+    const hh = String(date.getHours()).padStart(2, '0');
+    const mm = String(date.getMinutes()).padStart(2, '0');
+    const ss = String(date.getSeconds()).padStart(2, '0');
+    let zone = '';
+    try { zone = Intl.DateTimeFormat().resolvedOptions().timeZone || ''; } catch {}
+    return zone ? `${datePart} ${hh}:${mm}:${ss} ${zone}` : `${datePart} ${hh}:${mm}:${ss}`;
+}
+
+function temporalPromptText(content) {
+    const text = promptContentText(content)
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+    return text;
+}
+
+function promptNeedsDateReminder(content) {
+    const text = temporalPromptText(content);
+    if (!text) return false;
+    return /(?:오늘|내일|어제|모레|그저께|요즘|최근|방금|아까|현재\s*(?:날짜|시간|시각)|지금\s*(?:몇\s*시|시간|날짜|요일)|몇\s*월\s*몇\s*일|몇\s*시|무슨\s*요일|요일|날짜|이번\s*(?:주|달|월|년)|지난\s*(?:주|달|월|년)|다음\s*(?:주|달|월|년)|올해|작년|내년|today|tomorrow|yesterday|recently|current\s+(?:date|time)|what\s+(?:date|time)|which\s+day|weekday|this\s+(?:week|month|year)|last\s+(?:week|month|year)|next\s+(?:week|month|year))/i.test(text);
+}
+
+function promptNeedsTimeReminder(content) {
+    const text = temporalPromptText(content);
+    if (!text) return false;
+    return /(?:현재\s*(?:시간|시각)|지금\s*(?:몇\s*시|시간)|몇\s*시|시각|시간|current\s+time|what\s+time|time\s+is\s+it)/i.test(text);
+}
+
+export function buildCurrentTimeBlock(content) {
+    const needsTime = promptNeedsTimeReminder(content);
+    if (!needsTime && !promptNeedsDateReminder(content)) return '';
+    return localDateTimeWithZone(new Date());
+}
+
+function sessionModelDisplay(model) {
+    const text = String(model || '').trim();
+    if (!text) return '';
+    return text
+        .replace(/-\d{4}-\d{2}-\d{2}$/, '')
+        .replace(/^gpt-/i, 'GPT-')
+        .replace(/(?:^|-)([a-z])/g, (m) => m.toUpperCase());
+}
+
+export function buildSessionStartBlock(session, cwd) {
+    if (!session || session.owner === 'agent') return '';
+    const lines = ['# Session'];
+    const effectiveCwd = String(cwd || session.cwd || '').trim();
+    if (effectiveCwd) lines.push(`Cwd: ${effectiveCwd}`);
+    const modelBits = [
+        sessionModelDisplay(session.model),
+        session.effort ? String(session.effort).trim().toUpperCase() : '',
+        session.fast === true ? 'FAST' : '',
+    ].filter(Boolean);
+    if (modelBits.length) lines.push(`Model: ${modelBits.join(' · ')}`);
+    const workflowName = String(session.workflow?.name || session.workflow?.id || '').trim();
+    if (workflowName) lines.push(`Workflow: ${workflowName}`);
+    return lines.length > 1 ? lines.join('\n') : '';
+}
+
+export function isReferenceFilesMessage(message) {
+    return message?.role === 'user'
+        && typeof message.content === 'string'
+        && /^Reference files:\s*/i.test(message.content.trimStart());
+}
+
+export function isProtectedContextUserMessage(message) {
+    return message?.role === 'user'
+        && typeof message.content === 'string'
+        && message.content.trimStart().startsWith('<system-reminder>');
+}
+
+// Compact summary messages (role:'user', content startsWith SUMMARY_PREFIX)
+// are synthetic anchors, not a real human turn — they must not count as
+// "user conversation" or the post-clear/post-compact session-start block
+// would be wrongly suppressed on the next real user turn.
+function isSummaryAnchorMessage(message) {
+    return message?.role === 'user'
+        && typeof message.content === 'string'
+        && message.content.startsWith(SUMMARY_PREFIX);
+}
+
+export function hasUserConversationMessage(messages) {
+    return (Array.isArray(messages) ? messages : []).some((message) => (
+        message?.role === 'user'
+        && !isProtectedContextUserMessage(message)
+        && !isReferenceFilesMessage(message)
+        && !isSummaryAnchorMessage(message)
+    ));
+}
+
+export function isInternalRuntimeNotificationText(content) {
+    return contractIsInternalRuntimeNotificationText(promptContentText(content));
+}