mixdog 0.9.166 → 0.9.167

package/src/runtime/agent/orchestrator/context/deferred-tools.mjs

@@ -0,0 +1,272 @@
+// Deferred-pool and MCP-instruction manifests injected into BP2.
+// Extracted from collect.mjs so skill discovery and prompt composition
+// no longer share a god-file with session-surface mutation.
+
+export function compactPromptManifestText(value, max = 250) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    const limit = Math.max(1, Math.floor(max));
+    if (text.length <= limit) return text;
+    const head = text.slice(0, Math.max(1, limit - 1));
+    const space = head.lastIndexOf(' ');
+    const cut = space >= Math.floor(limit * 0.6) ? head.slice(0, space) : head;
+    return `${cut.replace(/[\s,.;:!?/\-]+$/, '')}...`;
+}
+
+const DEFERRED_TOOLS_BLOCK_RE = /(\n\n---\n*)?<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>\s*/gi;
+const MCP_INSTRUCTIONS_BLOCK_RE = /(\n\n---\n*)?<mcp-instructions>[\s\S]*?<\/mcp-instructions>\s*/gi;
+const DEFERRED_TOOL_NAME_SAFE_RE = /^[A-Za-z0-9_.:-]+$/;
+const MCP_SERVER_NAME_SAFE_RE = /^[A-Za-z0-9_.:-]+$/;
+const MCP_INSTRUCTION_MAX_CHARS = 600;
+
+function sanitizeDeferredToolManifestName(name) {
+    const text = String(name || '').trim();
+    if (!text || text.includes('<') || text.includes('>')) return '';
+    if (!DEFERRED_TOOL_NAME_SAFE_RE.test(text)) return '';
+    return text;
+}
+
+function skillRoutedToolNames(messages) {
+    const names = new Set();
+    for (const message of Array.isArray(messages) ? messages : []) {
+        if (message?.role !== 'system' || typeof message.content !== 'string') continue;
+        for (const block of message.content.matchAll(/<available_skills>([\s\S]*?)<\/available_skills>/g)) {
+            // Use only routes actually visible to this session, not the global
+            // skill catalog (which may include disabled or omitted skills).
+            for (const route of block[1].matchAll(/^- [^:\r\n]+:\s+\S[^\r\n]* \[tools: ([^\]\r\n]+)\]$/gm)) {
+                for (const name of route[1].split(',').map((value) => value.trim())) {
+                    // MCP dependencies name servers, not individual tools.
+                    if (/^[A-Za-z0-9_]+$/.test(name) && !name.startsWith('mcp__')) names.add(name);
+                }
+            }
+        }
+    }
+    return names;
+}
+
+function hasDeferredToolManifestBlock(text) {
+    const raw = String(text || '');
+    return /<available-deferred-tools>[\s\S]*?<\/available-deferred-tools>/i.test(raw)
+        || /<mcp-instructions>[\s\S]*?<\/mcp-instructions>/i.test(raw);
+}
+
+/**
+ * Skill-style manifest for tools in the deferred pool (catalog minus active
+ * wire tools). Each entry is either a bare name string or `{ name, description }`;
+ * output lines are `- name: description` (description omitted when absent),
+ * mirroring the available-skills manifest so the model calls deferred tools
+ * directly. Descriptions are compacted and stripped of `<`/`>`.
+ * Empty pool → '' (caller omits the block).
+ */
+export function buildDeferredToolManifest(entries) {
+    const list = [];
+    const seen = new Set();
+    for (const entry of Array.isArray(entries) ? entries : []) {
+        const rawName = typeof entry === 'string' ? entry : entry?.name;
+        const name = sanitizeDeferredToolManifestName(rawName);
+        if (!name || seen.has(name)) continue;
+        seen.add(name);
+        const description = typeof entry === 'string'
+            ? ''
+            : compactPromptManifestText(String(entry?.description || '').replace(/[<>]/g, ''), 100);
+        list.push({ name, description });
+    }
+    if (!list.length) return '';
+    list.sort((a, b) => a.name.localeCompare(b.name));
+    return [
+        '<available-deferred-tools>',
+        'Deferred tool names and purposes; schemas load on demand.',
+        ...list.map((entry) => (entry.description ? `- ${entry.name}: ${entry.description}` : `- ${entry.name}`)),
+        '</available-deferred-tools>',
+    ].join('\n');
+}
+
+function sanitizeMcpManifestServerName(name) {
+    const text = String(name || '').trim();
+    if (!text || text.includes('<') || text.includes('>')) return '';
+    if (!MCP_SERVER_NAME_SAFE_RE.test(text)) return '';
+    return text;
+}
+
+function sanitizeMcpInstructionText(text, max = MCP_INSTRUCTION_MAX_CHARS) {
+    const stripped = String(text || '').replace(/[<>]/g, '').trim();
+    if (!stripped) return '';
+    const cap = Math.max(1, Number(max) || MCP_INSTRUCTION_MAX_CHARS);
+    return stripped.length > cap ? `${stripped.slice(0, Math.max(1, cap - 3))}...` : stripped;
+}
+
+/**
+ * Per-server MCP initialize instructions for deferred-pool tools only.
+ * Empty when no instructions or no matching deferred MCP tools → omit block.
+ * Emits ONLY the server heading + instruction body: the per-server tool names
+ * are deliberately NOT repeated here — every pool tool is already listed once
+ * (with its description) in <available-deferred-tools>, and re-listing ~30
+ * names per server doubled the MCP share of the BP2 prefix (2026-08-05 audit).
+ * Server membership stays evident from the mcp__<server>__ name prefix.
+ */
+function buildMcpInstructionsManifest(mcpServerInstructions, poolNames) {
+    const map = mcpServerInstructions && typeof mcpServerInstructions === 'object'
+        ? mcpServerInstructions
+        : {};
+    const pool = [...new Set((Array.isArray(poolNames) ? poolNames : [])
+        .map((name) => sanitizeDeferredToolManifestName(name))
+        .filter(Boolean))];
+    const toolsByServer = new Map();
+    for (const name of pool) {
+        const match = name.match(/^mcp__(.+?)__(.+)$/);
+        if (!match) continue;
+        const server = match[1];
+        if (!toolsByServer.has(server)) toolsByServer.set(server, []);
+        toolsByServer.get(server).push(name);
+    }
+    const servers = [...toolsByServer.keys()]
+        .filter((server) => sanitizeMcpManifestServerName(server)
+            && sanitizeMcpInstructionText(map[server])
+            && toolsByServer.get(server).length)
+        .sort((a, b) => a.localeCompare(b));
+    if (!servers.length) return '';
+    const lines = ['<mcp-instructions>'];
+    for (const server of servers) {
+        const safeServer = sanitizeMcpManifestServerName(server);
+        const body = sanitizeMcpInstructionText(map[server]);
+        lines.push(`## ${safeServer}`, body);
+    }
+    lines.push('</mcp-instructions>');
+    return lines.join('\n');
+}
+
+export function stripDeferredToolManifestBlock(text) {
+    return String(text || '')
+        .replace(DEFERRED_TOOLS_BLOCK_RE, '')
+        .replace(MCP_INSTRUCTIONS_BLOCK_RE, '')
+        .replace(/\n\n---\n*$/,'')
+        .trimEnd();
+}
+
+// Rebuild path: replace the FIRST previously-injected <available-deferred-tools>
+// block (with its leading `---` separator) with the fresh manifest IN PLACE, so
+// the block keeps its original position and no sibling BP2 block (skills
+// manifest, agent rules, …) is reordered or dropped. The fresh manifest already
+// carries the mcp-instructions companion, so any pre-existing standalone one is
+// removed first to avoid duplication.
+function rebuildDeferredToolManifestBlock(text, manifest) {
+    let out = String(text || '').replace(MCP_INSTRUCTIONS_BLOCK_RE, '');
+    let replaced = false;
+    out = out.replace(DEFERRED_TOOLS_BLOCK_RE, (match, sep) => {
+        if (replaced) return '';
+        replaced = true;
+        return `${sep || ''}${manifest}`;
+    });
+    if (!replaced) {
+        const base = out.trimEnd();
+        out = base ? `${base}\n\n---\n\n${manifest}` : manifest;
+    }
+    return out;
+}
+
+function deferredManifestEntries(session, pool) {
+    const descByName = new Map();
+    for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
+        const name = String(tool?.name || '').trim();
+        if (name && !descByName.has(name)) descByName.set(name, String(tool?.description || ''));
+    }
+    const skillRoutedNames = skillRoutedToolNames(session.messages);
+    return pool.map((name) => ({
+        name,
+        description: skillRoutedNames.has(String(name).trim())
+            ? ''
+            : descByName.get(String(name).trim()) || '',
+    }));
+}
+
+function composeDeferredBp2Manifest(session, pool) {
+    const parts = [];
+    const deferredManifest = buildDeferredToolManifest(deferredManifestEntries(session, pool));
+    if (deferredManifest) parts.push(deferredManifest);
+    const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool);
+    if (mcpManifest) parts.push(mcpManifest);
+    return parts.join('\n\n');
+}
+
+function markDeferredBp2Applied(session) {
+    session.deferredToolBp2Applied = true;
+    delete session.deferredToolBp1Applied;
+}
+
+function clearDeferredManifestBlocks(session) {
+    for (const message of session.messages) {
+        if (message?.role === 'system' && typeof message.content === 'string') {
+            message.content = stripDeferredToolManifestBlock(message.content);
+        }
+    }
+    session.messages = session.messages.filter((message) => (
+        message?.role !== 'system' || String(message.content || '').trim()
+    ));
+}
+
+function resolveDeferredBp2Index(session) {
+    const systemIndexes = session.messages
+        .map((message, index) => (message?.role === 'system' ? index : -1))
+        .filter((index) => index >= 0);
+    if (!systemIndexes.length) return -1;
+    const tier3Index = systemIndexes.find((index) => session.messages[index]?.cacheTier === 'tier3');
+    let idx = systemIndexes.length >= 2 && systemIndexes[1] !== tier3Index
+        ? systemIndexes[1]
+        : -1;
+    if (idx >= 0) return idx;
+    idx = tier3Index >= 0 ? tier3Index : systemIndexes[0] + 1;
+    session.messages.splice(idx, 0, { role: 'system', content: '' });
+    return idx;
+}
+
+function writeDeferredManifestAt(session, idx, manifest, rebuild) {
+    for (let i = 0; i < session.messages.length; i++) {
+        if (i === idx || session.messages[i]?.role !== 'system' || typeof session.messages[i].content !== 'string') continue;
+        session.messages[i].content = stripDeferredToolManifestBlock(session.messages[i].content);
+    }
+    const raw = typeof session.messages[idx].content === 'string' ? session.messages[idx].content : '';
+    if (rebuild && hasDeferredToolManifestBlock(raw)) {
+        session.messages[idx].content = rebuildDeferredToolManifestBlock(raw, manifest);
+        return;
+    }
+    const base = stripDeferredToolManifestBlock(raw);
+    session.messages[idx].content = base
+        ? `${base}\n\n---\n\n${manifest}`
+        : manifest;
+}
+
+/**
+ * Inject the skill-style deferred pool (name + description) into BP2 at session
+ * start. Normally once; with `{ rebuild: true }` it strips any existing
+ * <available-deferred-tools>/<mcp-instructions> block and re-injects the fresh
+ * pool in place (used by the first-turn MCP refresh, before the prompt renders,
+ * so late-connected MCP tools land in the INITIAL manifest — never duplicated).
+ */
+export function applyInitialDeferredToolManifestToBp2(session, poolNames, options = {}) {
+    const rebuild = options?.rebuild === true;
+    if (!session || !Array.isArray(session.messages)) return false;
+    if (session.deferredToolBp2Applied && !rebuild) return false;
+    const pool = Array.isArray(poolNames) ? poolNames : [];
+    const manifest = composeDeferredBp2Manifest(session, pool);
+    if (!manifest) {
+        clearDeferredManifestBlocks(session);
+        markDeferredBp2Applied(session);
+        session.updatedAt = Date.now();
+        return true;
+    }
+
+    const existingMessage = session.messages.find((message) => (
+        message?.role === 'system'
+        && typeof message.content === 'string'
+        && hasDeferredToolManifestBlock(message.content)
+    ));
+    const idx = resolveDeferredBp2Index(session);
+    if (idx < 0) return false;
+    if (existingMessage === session.messages[idx] && !rebuild) {
+        markDeferredBp2Applied(session);
+        return true;
+    }
+    writeDeferredManifestAt(session, idx, manifest, rebuild);
+    markDeferredBp2Applied(session);
+    session.updatedAt = Date.now();
+    return true;
+}

package/src/runtime/agent/orchestrator/context/role-instructions.mjs

@@ -0,0 +1,296 @@
+// Agent-scoped role markdown and 4-BP system prompt composition.
+// Extracted from collect.mjs so skill catalog loading is not mixed into
+// role-specific prompt assembly.
+
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { mixdogRoot } from '../../../shared/plugin-paths.mjs';
+import { readMarkdownDocument } from '../../../shared/markdown-frontmatter.mjs';
+import { listHiddenAgentsByKind, getAgentCatalogShareAgents } from '../internal-agents.mjs';
+import { mixdogGlobalDir, mtimeWithTtl, readSafe } from './skill-catalog.mjs';
+
+// --- Agent-scoped instruction loader ---
+// Emits a BP2 agent/system block scoped to the calling agent:
+//   - Public/custom agents: their own agents/<agent>.md when present,
+//     plus the public agent-worker contract.
+//   - Hidden agents: their own rules/agent/<agent>.md section only.
+//   - Null agent: falls back to the full all-in-one block
+//     (explicit-cache unified-shard path).
+//
+// Agent-specific markdown intentionally rides BP2, behind the shared BP1 tool
+// and skill manifest prefix, so agent changes do not disturb the common layer.
+//
+// Classification is dynamic — hidden retrieval/maintenance sets come from the
+// `kind` field in internal-agents.mjs. Any other non-null agent is public/custom.
+
+function loadAgentClassification() {
+    // Not cached — called only on instruction rebuild (mtime-busted), and
+    // listHiddenAgentsByKind now reads from the mtime-aware cache inside
+    // internal-agents.mjs so the classification always reflects the current
+    // agents.json on disk.
+    return {
+        retrieval: new Set(listHiddenAgentsByKind('retrieval')),
+        maintenance: new Set(listHiddenAgentsByKind('maintenance')),
+    };
+}
+
+const _scopedRoleInstructionsCache = new Map();
+// Short-TTL gate for the role-instruction freshness stat. loadScopedRoleInstructions() ran
+// maxMtimeRecursive() over agents/ + rules/agent/ on EVERY call (many per
+// turn across roles), so even a warm cache paid dozens of statSync per turn.
+// Mirror collectSkillsCached(): only re-stat after _ROLE_INSTRUCTIONS_MTIME_TTL_MS, and
+// trust the cached mtime within that window. Edits still propagate within ~1
+// stat interval, which is well under human-perceptible latency.
+const _scopedRoleInstructionsMtimeCache = new Map();
+const _ROLE_INSTRUCTIONS_MTIME_TTL_MS = 2000;
+
+function loadHiddenAgentSnippets(pluginRoot) {
+    try {
+        const agentRulesDir = join(pluginRoot, 'rules', 'agent');
+        if (!existsSync(agentRulesDir)) return [];
+        const files = readdirSync(agentRulesDir)
+            .filter(f => f.endsWith('.md') && f !== '00-common.md' && f !== '00-core.md')
+            .sort();
+        const pairs = [];
+        for (const f of files) {
+            const raw = readSafe(join(agentRulesDir, f));
+            if (!raw) continue;
+            const { body } = readMarkdownDocument(raw);
+            if (!body) continue;
+            const name = f.replace(/^\d+-/, '').replace(/\.md$/, '');
+            pairs.push({ name, body });
+        }
+        return pairs;
+    } catch {
+        return [];
+    }
+}
+
+// Role-markdown roots, in precedence order (later wins on the same name):
+// the shipped agents/ tree, then the user data dir. User-authored roles and
+// built-in overrides written by the Workflows editor live in the data dir —
+// reading only the install root left a custom agent with an EMPTY role
+// catalog while Lead already saw the edited AGENT.md.
+function agentSectionDirs(pluginRoot) {
+    const dirs = [];
+    if (pluginRoot) dirs.push(join(pluginRoot, 'agents'));
+    try {
+        const userDir = mixdogGlobalDir('agents');
+        if (userDir && !dirs.includes(userDir)) dirs.push(userDir);
+    } catch { /* unresolvable data dir — built-in roles still load */ }
+    return dirs;
+}
+
+function loadAgentSections(pluginRoot) {
+    // agents/ accepts both the compatibility flat layout and the current
+    // nested agents/<agent>/AGENT.md layout.
+    // The previous flat-only readdir silently dropped every nested agent, so a
+    // public agent like heavy-worker produced an EMPTY scoped instruction block
+    // (BP2) — the model lost its agent contract and the tool smoke's
+    // "heavy-worker AGENT.md must be included" assertion failed. Walk both.
+    const byName = new Map();
+    for (const agentsDir of agentSectionDirs(pluginRoot)) {
+        if (!existsSync(agentsDir)) continue;
+        let entries;
+        try {
+            entries = readdirSync(agentsDir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            let name = '';
+            let raw = null;
+            if (entry.isDirectory()) {
+                name = entry.name;
+                raw = readSafe(join(agentsDir, entry.name, 'AGENT.md'));
+            } else if (entry.isFile() && entry.name.endsWith('.md')) {
+                name = entry.name.replace(/\.md$/, '');
+                raw = readSafe(join(agentsDir, entry.name));
+            }
+            if (!name || !raw) continue;
+            const { body } = readMarkdownDocument(raw);
+            if (!body) continue;
+            byName.set(name, `## ${name}\n\n${body}`);
+        }
+    }
+    return [...byName.entries()]
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .map(([, text]) => text);
+}
+
+// Empty by design: scoped agent markdown already rides BP2 for every provider.
+// Keeping the set in place preserves the old branch point for a future
+// provider-specific experiment without changing today's cache layout.
+const EXPLICIT_CACHE_PROVIDERS = new Set();
+
+function hiddenRuleSections(hiddenPairs) {
+    return hiddenPairs.map((p) => `## ${p.name}\n\n${p.body}`);
+}
+
+function selfHiddenRuleSection(hiddenPairs, agent) {
+    const self = hiddenPairs.find((p) => p.name === agent);
+    return self ? [`## ${self.name}\n\n${self.body}`] : [];
+}
+
+function selectRoleInstructionSections({
+    useUnified,
+    agent,
+    classification,
+    agentSharesCatalog,
+    agentSections,
+    hiddenPairs,
+}) {
+    if (useUnified || !agent) {
+        return {
+            agentRuleSectionsToEmit: hiddenRuleSections(hiddenPairs),
+            agentSectionsToEmit: agentSections,
+        };
+    }
+    if (classification.retrieval.has(agent)) {
+        return {
+            agentRuleSectionsToEmit: selfHiddenRuleSection(hiddenPairs, agent),
+            agentSectionsToEmit: agentSections.filter((s) =>
+                [...agentSharesCatalog].some((name) => s.startsWith(`## ${name}\n`))),
+        };
+    }
+    if (classification.maintenance.has(agent)) {
+        const selfRules = selfHiddenRuleSection(hiddenPairs, agent);
+        const fromAgent = agentSections.find((s) => s.startsWith(`## ${agent}\n`));
+        return {
+            agentRuleSectionsToEmit: selfRules.length ? selfRules : (fromAgent ? [fromAgent] : []),
+            agentSectionsToEmit: [],
+        };
+    }
+    return {
+        agentRuleSectionsToEmit: [],
+        agentSectionsToEmit: agentSections.filter((s) => s.startsWith(`## ${agent}\n`)),
+    };
+}
+
+export function loadScopedRoleInstructions(agent, provider = null) {
+    const useUnified = !!(provider && EXPLICIT_CACHE_PROVIDERS.has(provider));
+    const cacheKey = useUnified ? '__unified__' : (agent || '__all__');
+    const cached = _scopedRoleInstructionsCache.get(cacheKey);
+    const pluginRoot = mixdogRoot();
+    // Use maxMtimeRecursive so edits to .md files inside agents/ and
+    // rules/agent/ propagate — parent dir mtime is unchanged on
+    // Linux/macOS when only a nested file's content changes. Gate the stat
+    // behind a short TTL so repeated same-turn calls reuse the last mtime
+    // instead of re-walking the trees on every invocation.
+    const mtime = pluginRoot
+        ? mtimeWithTtl(_scopedRoleInstructionsMtimeCache, cacheKey, [
+            ...agentSectionDirs(pluginRoot),
+            join(pluginRoot, 'rules', 'agent'),
+            join(pluginRoot, 'defaults', 'agents.json'),
+        ], _ROLE_INSTRUCTIONS_MTIME_TTL_MS)
+        : 0;
+    if (cached && mtime <= cached.mtime) {
+        return cached.value;
+    }
+    // Compute classification before file loading — internal-agents metadata
+    // failures (malformed/missing agents.json) must propagate, not be
+    // silently swallowed by the file-IO catch below.
+    const classification = loadAgentClassification();
+    const agentSharesCatalog = agent && classification.retrieval.has(agent)
+        ? new Set(getAgentCatalogShareAgents(agent))
+        : new Set();
+    try {
+        const agentSections = loadAgentSections(pluginRoot);
+        const hiddenPairs = loadHiddenAgentSnippets(pluginRoot);
+
+        const { agentRuleSectionsToEmit, agentSectionsToEmit } = selectRoleInstructionSections({
+            useUnified,
+            agent,
+            classification,
+            agentSharesCatalog,
+            agentSections,
+            hiddenPairs,
+        });
+
+        const blocks = [];
+        if (agentSectionsToEmit.length) {
+            blocks.push(`# Agent Role Catalog\n\n${agentSectionsToEmit.join('\n\n---\n\n')}`);
+        }
+        if (agentRuleSectionsToEmit.length) {
+            blocks.push(`# Agent Role Rules\n\n${agentRuleSectionsToEmit.join('\n\n---\n\n')}`);
+        }
+        const value = blocks.join('\n\n---\n\n');
+        _scopedRoleInstructionsCache.set(cacheKey, { mtime, value });
+        return value;
+    } catch {
+        return '';
+    }
+}
+
+// --- Compose system prompt — 4-BP cache layout ---
+// Returns the three stable system blocks and the BP3 core used for refreshes.
+// directly to the breakpoint plan:
+//   BP1 (1h, system block #1) = baseRules — shared tool policy
+//   BP2 (1h, system block #2) = stableSystemContext — profile, skills, deferred/MCP
+//   BP3 (1h, system block #3) = sessionMarker — workflow/role, memory, session/project environment
+//   BP4 (5m/1h, messages tail) = live user/task/tool message tail
+//
+// Dynamic schedule/webhook/task payloads stay in normal user messages so
+// changing one event does not rewrite the stable memory layer.
+//
+// `profile.skip` still filters specific buckets (claudemd, skills, memory)
+// for backward compatibility with existing profiles.
+function trimmedPromptSlice(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : '';
+}
+
+function joinPromptSlices(parts) {
+    return parts.filter(Boolean).join('\n\n---\n\n');
+}
+
+export function composeSystemPrompt(opts) {
+    const skip = opts.profile?.skip || {};
+
+    // ── BP1: globally shared tool policy ────────────────────────────────
+    const baseParts = [];
+    if (opts.agentRules) baseParts.push(opts.agentRules);
+    const baseRules = baseParts.join('\n\n---\n\n');
+
+    // ── BP2: persistent profile/tool catalog layer ──────────────────────
+    // deferredToolManifest: optional BP2 slice; production path is
+    // applyInitialDeferredToolManifestToBp2 once after applyDeferredToolSurface.
+    const stableSystemContext = joinPromptSlices([
+        trimmedPromptSlice(opts.metaContext),
+        skip.skills ? '' : trimmedPromptSlice(opts.skillManifest),
+        trimmedPromptSlice(opts.deferredToolManifest),
+    ]);
+
+    // ── BP3: workflow/role + session environment layer ─────────────────
+    const roleInstructionContext = opts.skipRoleCatalog
+        ? ''
+        : loadScopedRoleInstructions(opts.agent || null, opts.provider || null);
+    // Keep the active workflow first within BP3 so it leads the role and
+    // environment material that varies with the session.
+    const coreMemory = skip.memory ? '' : trimmedPromptSlice(opts.coreMemoryContext);
+    const sessionMarkerCore = joinPromptSlices([
+        trimmedPromptSlice(opts.workflowContext),
+        opts.roleRules || '',
+        opts.userPrompt || '',
+        roleInstructionContext,
+        coreMemory ? `# Core Memory\n${coreMemory}` : '',
+    ]);
+    // Response language is the LAST system text before the conversation. It
+    // rides the environment block (not the tier3 core) because the `# Session`
+    // / shell / git lines are English and would otherwise trail it, pulling the
+    // pre-tool preamble toward English.
+    const environmentParts = [
+        opts.sessionStartContext,
+        opts.projectInstructionsContext,
+        opts.environmentContext,
+        opts.languageContext,
+    ].map(trimmedPromptSlice);
+    // Volatile session/project environment. Kept OUT of sessionMarkerCore so
+    // Anthropic providers can leave it as an UNMARKED system block (covered by
+    // the messages-tail breakpoint) while prefix-order providers still see it
+    // after the stable context. sessionMarker keeps the combined legacy shape
+    // for callers that consume a single BP3 string.
+    const sessionEnvironment = joinPromptSlices(environmentParts);
+    const sessionMarker = joinPromptSlices([sessionMarkerCore, sessionEnvironment]);
+
+    return { baseRules, stableSystemContext, sessionMarkerCore, sessionEnvironment, sessionMarker };
+}