@hassangameryt/freeflow 0.4.0 → 0.6.0

package/pi-extension/src/runtime/runtime-context.ts

@@ -2,19 +2,19 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { normalizeFreeflowConfig, normalizeLocalFreeflowConfig } from "../../../router/dist/index.js";
+import { resolveCognitiveRoutingState } from "../cognitive-routing/runtime.js";
+import { isPiFlowHost } from "./runtime-identity.js";
 
 export const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
 
 export const WORKFLOW_COMMANDS = [
   { command: "discuss", skill: "discuss" },
-  { command: "discover", skill: "discuss" },
+  { command: "action-selection", skill: "action-selection" },
   { command: "track-work", skill: "track-work" },
   { command: "write-spec", skill: "write-spec" },
   { command: "review-artifact", skill: "review-artifact" },
   { command: "write-plan", skill: "write-plan" },
   { command: "execute-work", skill: "execute-work" },
-  { command: "execute-plan", skill: "execute-work" },
   { command: "simplify-code", skill: "simplify-code" },
   { command: "migration-work", skill: "migration-work" },
   { command: "diagnose-failure", skill: "diagnose-failure" },
@@ -31,6 +31,7 @@ export const WORKFLOW_COMMANDS = [
 export const CONTRIBUTOR_COMMANDS = ["setup-freeflow", "write-skill", "evaluate-skill"];
 
 export const FREEFLOW_MODEL_SKILL_NAMES = [
+  "action-selection",
   "bypass",
   "commit-work",
   "decision-gate",
@@ -58,63 +59,121 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "write-spec",
 ];
 
+export const FREEFLOW_CAPABILITY_SKILL_NAMES = ["cognitive-routing", "context-virtualization", "conversation-history"];
+
 export function freeflowSkillPath(skillName) {
   return fileURLToPath(new URL(`../../../skills/${skillName}/SKILL.md`, import.meta.url));
 }
 
-export function freeflowModelSkillPaths() {
-  return FREEFLOW_MODEL_SKILL_NAMES.map((skillName) => freeflowSkillPath(skillName));
+export function freeflowCapabilitySkillPath(skillName) {
+  return fileURLToPath(new URL(`../../../capabilities/${skillName}/SKILL.md`, import.meta.url));
+}
+
+export function freeflowModelSkillPaths(capabilityState = undefined) {
+  const paths = FREEFLOW_MODEL_SKILL_NAMES.map((skillName) => freeflowSkillPath(skillName));
+  const capabilityStates = {
+    "cognitive-routing": capabilityState?.cognitiveRouting,
+    "context-virtualization": capabilityState?.contextVirtualization,
+    "conversation-history": capabilityState?.conversationHistory,
+  };
+  for (const skillName of FREEFLOW_CAPABILITY_SKILL_NAMES) {
+    if (capabilityStates[skillName]?.effective === true) {
+      paths.push(freeflowCapabilitySkillPath(skillName));
+    }
+  }
+  return paths;
 }
 
-type SessionCoreKey = "enabled" | "interactionContract" | "skillsEnabled";
+type SessionCoreKey =
+  "enabled" | "interactionContract" | "skillsEnabled" | "contextVirtualization" | "conversationHistory";
 type SessionCoreOverrides = Partial<Record<SessionCoreKey, boolean>>;
 
 const MODE_STATE_ENTRY = "freeflow-mode";
 const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
-const SESSION_CORE_KEYS = new Set<SessionCoreKey>(["enabled", "interactionContract", "skillsEnabled"]);
+const SESSION_CORE_KEYS = new Set<SessionCoreKey>([
+  "enabled",
+  "interactionContract",
+  "skillsEnabled",
+  "contextVirtualization",
+  "conversationHistory",
+]);
 const RESET_MODE_ARGS = new Set(["reset"]);
 
-export const FREEFLOW_STATUS_TOOL_NAME = "freeflow_status";
-export const OUTPUT_ROUTER_TOOL_NAMES = ["freeflow_search", "freeflow_run", "freeflow_batch"];
+export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
+export const FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-runtime-state";
+export const COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-cognitive-routing-runtime-state";
 export const WORKFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-workflow-bootstrap";
+export const COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE = "freeflow-cognitive-routing-bootstrap";
+export const FREEFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-bootstrap";
 
 let runtimeContextCache = null;
 let currentModeOverride = null;
 let currentSessionOverrides: SessionCoreOverrides = {};
-let lastRouterConfigWarningKey = null;
+
+async function readPromptFile(url: URL): Promise<string | null> {
+  try {
+    return await readFile(url, "utf8");
+  } catch {
+    return null;
+  }
+}
+
 async function loadRuntimeContext(capabilityState = undefined) {
+  const freeflowEnabled = capabilityState?.enabled === true;
   const interactionContractEnabled = capabilityState?.interactionContract?.effective === true;
   const skillsEnabled = capabilityState?.skills?.effective === true;
-  const outputRouterEnabled = capabilityState?.outputRouter?.enabled === true;
-  const [interactionContract, workflowSkill, outputRouterSkill] = await Promise.all([
+  const contextVirtualizationEnabled = capabilityState?.contextVirtualization?.effective === true;
+  const conversationHistoryEnabled = capabilityState?.conversationHistory?.effective === true;
+  const cognitiveRoutingEnabled = capabilityState?.cognitiveRouting?.effective === true;
+  const [
+    corePrompt,
+    interactionContractPrompt,
+    skillsPrompt,
+    cognitiveRoutingPrompt,
+    contextVirtualizationPrompt,
+    conversationHistoryPrompt,
+  ] = await Promise.all([
+    freeflowEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/core.md", import.meta.url))
+      : Promise.resolve(null),
     interactionContractEnabled
-      ? readFile(new URL("../../../runtime/interaction-contract.md", import.meta.url), "utf8")
+      ? readPromptFile(new URL("../../../runtime/prompts/interaction-contract.md", import.meta.url))
       : Promise.resolve(null),
     skillsEnabled
-      ? readFile(new URL("../../../skills/workflow/SKILL.md", import.meta.url), "utf8")
+      ? readPromptFile(new URL("../../../runtime/prompts/skills.md", import.meta.url))
+      : Promise.resolve(null),
+    cognitiveRoutingEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/cognitive-routing.md", import.meta.url))
       : Promise.resolve(null),
-    outputRouterEnabled
-      ? readFile(new URL("../../../skills/output-router/SKILL.md", import.meta.url), "utf8")
+    contextVirtualizationEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/context-virtualization.md", import.meta.url))
+      : Promise.resolve(null),
+    conversationHistoryEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/conversation-history.md", import.meta.url))
       : Promise.resolve(null),
   ]);
 
-  return { interactionContract, workflowSkill, outputRouterSkill };
+  return {
+    corePrompt,
+    interactionContractPrompt,
+    skillsPrompt,
+    cognitiveRoutingPrompt,
+    contextVirtualizationPrompt,
+    conversationHistoryPrompt,
+  };
 }
 
 function runtimeContextCacheSatisfies(capabilityState) {
-  if (!runtimeContextCache) {
-    return false;
-  }
-  if (capabilityState?.interactionContract?.effective === true && !runtimeContextCache.interactionContract) {
-    return false;
-  }
-  if (capabilityState?.skills?.effective === true && !runtimeContextCache.workflowSkill) {
-    return false;
-  }
-  if (capabilityState?.outputRouter?.enabled === true && !runtimeContextCache.outputRouterSkill) {
-    return false;
-  }
-  return true;
+  if (!runtimeContextCache) return false;
+  const expected = {
+    corePrompt: capabilityState?.enabled === true,
+    interactionContractPrompt: capabilityState?.interactionContract?.effective === true,
+    skillsPrompt: capabilityState?.skills?.effective === true,
+    cognitiveRoutingPrompt: capabilityState?.cognitiveRouting?.effective === true,
+    contextVirtualizationPrompt: capabilityState?.contextVirtualization?.effective === true,
+    conversationHistoryPrompt: capabilityState?.conversationHistory?.effective === true,
+  };
+  return Object.entries(expected).every(([key, required]) => !required || Boolean(runtimeContextCache[key]));
 }
 
 export async function refreshRuntimeContext(capabilityState = undefined) {
@@ -129,44 +188,34 @@ export async function getRuntimeContext(capabilityState = undefined) {
   return refreshRuntimeContext(capabilityState);
 }
 
-function activeSessionEntries(sessionManager) {
-  try {
-    if (typeof sessionManager?.buildContextEntries === "function") {
-      const entries = sessionManager.buildContextEntries();
-      if (Array.isArray(entries)) {
-        return entries;
-      }
-    }
-    if (typeof sessionManager?.getEntries === "function") {
-      const entries = sessionManager.getEntries();
-      if (Array.isArray(entries)) {
-        return entries;
-      }
-    }
-  } catch {
-    // A missing session snapshot should reload useful context rather than suppress it.
-  }
-  return [];
-}
+const BOOTSTRAP_COMPONENTS = Object.freeze({
+  workflow: "workflow",
+  cognitiveRouting: "cognitive-routing",
+});
 
-export function workflowBootstrapMessage(freeflowContext, capabilityState, sessionManager) {
-  if (capabilityState?.skills?.effective !== true || !freeflowContext?.workflowSkill) {
-    return undefined;
+function bootstrapEntryComponents(entry) {
+  const isCustomMessage = entry?.role === "custom" || entry?.type === "custom_message" || entry?.type === "custom";
+  if (!isCustomMessage) return [];
+  if (entry.customType === FREEFLOW_BOOTSTRAP_MESSAGE_TYPE) {
+    if (Array.isArray(entry.details?.components)) return entry.details.components;
+    return [
+      ...(entry.content?.includes("<!-- freeflow-bootstrap:workflow -->") ? [BOOTSTRAP_COMPONENTS.workflow] : []),
+      ...(entry.content?.includes("<!-- freeflow-bootstrap:cognitive-routing -->")
+        ? [BOOTSTRAP_COMPONENTS.cognitiveRouting]
+        : []),
+    ];
   }
-
-  const alreadyLoaded = activeSessionEntries(sessionManager).some(
-    (entry) => entry?.type === "custom_message" && entry?.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
-  );
-  if (alreadyLoaded) {
-    return undefined;
+  if (entry.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE) {
+    return [BOOTSTRAP_COMPONENTS.workflow];
+  }
+  if (entry.customType === COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE) {
+    return [BOOTSTRAP_COMPONENTS.cognitiveRouting];
   }
+  return [];
+}
 
-  return {
-    customType: WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
-    content: `# Freeflow Workflow Bootstrap\n\n${freeflowContext.workflowSkill.trim()}`,
-    display: false,
-    details: { skill: "workflow", source: "first-turn-bootstrap" },
-  };
+export function filterBootstrapMessage(message) {
+  return bootstrapEntryComponents(message).length === 0 ? message : undefined;
 }
 
 function isRecord(value) {
@@ -182,6 +231,14 @@ function validateCoreConfigFields(value) {
     return "enabled must be a boolean";
   }
 
+  if (value.contextVirtualization !== undefined && typeof value.contextVirtualization !== "boolean") {
+    return "contextVirtualization must be a boolean";
+  }
+
+  if (value.conversationHistory !== undefined && typeof value.conversationHistory !== "boolean") {
+    return "conversationHistory must be a boolean";
+  }
+
   if (value.interactionContract !== undefined && typeof value.interactionContract !== "boolean") {
     return "interactionContract must be a boolean";
   }
@@ -208,6 +265,7 @@ function validateFreeflowConfigShape(value) {
     return "config must be a JSON object";
   }
 
+  // Keep retired capability keys shape-tolerated so existing repositories remain activated; runtime behavior ignores them.
   const allowedKeys = new Set([
     "enabled",
     "defaultMode",
@@ -216,6 +274,9 @@ function validateFreeflowConfigShape(value) {
     "outputRouter",
     "observedRouting",
     "scriptTransform",
+    "cognitiveRouting",
+    "contextVirtualization",
+    "conversationHistory",
   ]);
   for (const key of Object.keys(value)) {
     if (!allowedKeys.has(key)) {
@@ -240,7 +301,16 @@ function validateFreeflowLocalConfigShape(value) {
     return "local config must be a JSON object";
   }
 
-  const allowedKeys = new Set(["enabled", "defaultMode", "interactionContract", "skills", "processing"]);
+  const allowedKeys = new Set([
+    "enabled",
+    "defaultMode",
+    "interactionContract",
+    "skills",
+    "processing",
+    "cognitiveRouting",
+    "contextVirtualization",
+    "conversationHistory",
+  ]);
   for (const key of Object.keys(value)) {
     if (!allowedKeys.has(key)) {
       return `unsupported top-level local config key: ${key}`;
@@ -318,6 +388,8 @@ function resolveLayeredValue(repository, local, key, fallback) {
 function resolveCoreConfig(repository, local) {
   const enabled = resolveLayeredValue(repository, local, "enabled", true);
   const interactionContract = resolveLayeredValue(repository, local, "interactionContract", true);
+  const contextVirtualization = resolveLayeredValue(repository, local, "contextVirtualization", false);
+  const conversationHistory = resolveLayeredValue(repository, local, "conversationHistory", false);
   const defaultMode = resolveLayeredValue(repository, local, "defaultMode", "workflow");
   const repositorySkills = isRecord(repository.skills) ? repository.skills : {};
   const localSkills = isRecord(local.skills) ? local.skills : {};
@@ -327,12 +399,16 @@ function resolveCoreConfig(repository, local) {
     config: {
       enabled: enabled.value,
       interactionContract: interactionContract.value,
+      contextVirtualization: contextVirtualization.value,
+      conversationHistory: conversationHistory.value,
       skills: { enabled: skillsEnabled.value },
       defaultMode: defaultMode.value,
     },
     sources: {
       enabled: enabled.source,
       interactionContract: interactionContract.source,
+      contextVirtualization: contextVirtualization.source,
+      conversationHistory: conversationHistory.source,
       skillsEnabled: skillsEnabled.source,
       defaultMode: defaultMode.source,
     },
@@ -355,6 +431,8 @@ function resolveSessionCoreConfig(layers) {
   const sources = layers.sources;
   const enabled = currentSessionOverrides.enabled;
   const interactionContract = currentSessionOverrides.interactionContract;
+  const contextVirtualization = currentSessionOverrides.contextVirtualization;
+  const conversationHistory = currentSessionOverrides.conversationHistory;
   const skillsEnabled = currentSessionOverrides.skillsEnabled;
 
   return {
@@ -362,12 +440,18 @@ function resolveSessionCoreConfig(layers) {
       enabled: typeof enabled === "boolean" ? enabled : configured.enabled,
       interactionContract:
         typeof interactionContract === "boolean" ? interactionContract : configured.interactionContract,
+      contextVirtualization:
+        typeof contextVirtualization === "boolean" ? contextVirtualization : configured.contextVirtualization,
+      conversationHistory:
+        typeof conversationHistory === "boolean" ? conversationHistory : configured.conversationHistory,
       skills: { enabled: typeof skillsEnabled === "boolean" ? skillsEnabled : configured.skills.enabled },
       defaultMode: configured.defaultMode,
     },
     sources: {
       enabled: typeof enabled === "boolean" ? "session" : sources.enabled,
       interactionContract: typeof interactionContract === "boolean" ? "session" : sources.interactionContract,
+      contextVirtualization: typeof contextVirtualization === "boolean" ? "session" : sources.contextVirtualization,
+      conversationHistory: typeof conversationHistory === "boolean" ? "session" : sources.conversationHistory,
       skillsEnabled: typeof skillsEnabled === "boolean" ? "session" : sources.skillsEnabled,
       defaultMode: sources.defaultMode,
     },
@@ -400,15 +484,60 @@ export async function readFreeflowConfigLayers(cwd) {
   };
 }
 
-export async function readCapabilityState(cwd) {
+export async function readCapabilityState(cwd, host = undefined, extensionHost = undefined) {
   const layers = await readFreeflowConfigLayers(cwd);
-  const parsed = layers.repository.valid ? layers.repository.parsed : {};
-  const normalized = normalizeFreeflowConfig(parsed);
   const effectiveCore = resolveSessionCoreConfig(layers);
   const enabled = layers.configured && effectiveCore.config.enabled;
   const interactionContractConfigEnabled = effectiveCore.config.interactionContract;
   const skillsConfigEnabled = effectiveCore.config.skills.enabled;
-  const outputRouterConfigEnabled = normalized.config.outputRouter.enabled;
+  const contextVirtualizationConfigEnabled = effectiveCore.config.contextVirtualization;
+  const conversationHistoryConfigEnabled = effectiveCore.config.conversationHistory;
+  const skillsEffective = enabled && skillsConfigEnabled;
+  const hostSupportsCognitiveRouting = isPiFlowHost(extensionHost);
+  const configuredCognitiveRouting = await resolveCognitiveRoutingState(
+    layers.repository.parsed,
+    layers.local.parsed,
+    hostSupportsCognitiveRouting ? host : undefined,
+  );
+  const disabledReason = enabled
+    ? skillsEffective
+      ? undefined
+      : { code: "disabled" as const, message: "Skills are disabled" }
+    : { code: "disabled" as const, message: "Freeflow is disabled" };
+  const childCapability = (configuredEnabled) => ({
+    enabled: configuredEnabled,
+    effective: skillsEffective && configuredEnabled,
+    ...(disabledReason ? { blockingReason: disabledReason } : {}),
+  });
+  const cognitiveRouting = enabled
+    ? skillsEffective
+      ? !hostSupportsCognitiveRouting && configuredCognitiveRouting.configValid
+        ? {
+            ...configuredCognitiveRouting,
+            effective: false,
+            blockingReason: {
+              code: "runtime_disabled" as const,
+              message: "Cognitive Routing is disabled outside the PiFlow runtime",
+            },
+          }
+        : configuredCognitiveRouting
+      : {
+          ...configuredCognitiveRouting,
+          effective: false,
+          blockingReason: {
+            code: "disabled" as const,
+            message: "Skills are disabled",
+          },
+        }
+    : {
+        ...configuredCognitiveRouting,
+        enabled: false,
+        effective: false,
+        blockingReason: {
+          code: "disabled" as const,
+          message: "Freeflow is disabled",
+        },
+      };
   return {
     configured: layers.configured,
     repositoryConfigured: layers.repositoryConfigured,
@@ -434,69 +563,15 @@ export async function readCapabilityState(cwd) {
       enabled: skillsConfigEnabled,
       effective: enabled && skillsConfigEnabled,
     },
-    outputRouter: {
-      enabled: enabled && outputRouterConfigEnabled,
-      configEnabled: outputRouterConfigEnabled,
-    },
+    contextVirtualization: childCapability(contextVirtualizationConfigEnabled),
+    conversationHistory: childCapability(conversationHistoryConfigEnabled),
+    hostSupportsCognitiveRouting,
+    cognitiveRouting,
   };
 }
 
 export const readRuntimeState = readCapabilityState;
 
-export async function readOutputRouterConfig(cwd) {
-  const layers = await readFreeflowConfigLayers(cwd);
-  const parsed = layers.repository.valid ? layers.repository.parsed : {};
-  const localParsed = layers.local.valid ? layers.local.parsed : {};
-  const normalized = normalizeFreeflowConfig(parsed);
-  const local = normalizeLocalFreeflowConfig(localParsed);
-  const freeflowEnabled = layers.configured && layers.coreConfig.enabled;
-  const effectiveConfig = freeflowEnabled
-    ? normalized.config
-    : {
-        ...normalized.config,
-        outputRouter: { ...normalized.config.outputRouter, enabled: false },
-        observedRouting: {
-          ...normalized.config.observedRouting,
-          enabled: false,
-        },
-        scriptTransform: {
-          ...normalized.config.scriptTransform,
-          enabled: false,
-        },
-      };
-  const configWarnings = [...normalized.warnings];
-  if (layers.repository.exists && !layers.repository.valid) {
-    configWarnings.unshift(
-      `.freeflow/config.json could not be parsed; Freeflow runtime is inactive. ${layers.repository.parseError ?? ""}`.trim(),
-    );
-  }
-  if (layers.local.exists && !layers.local.valid) {
-    configWarnings.unshift(
-      `.freeflow/local.json could not be parsed; Freeflow runtime is inactive. ${layers.local.parseError ?? ""}`.trim(),
-    );
-  }
-  return {
-    config: effectiveConfig.outputRouter,
-    freeflowConfig: effectiveConfig,
-    localConfig: local.config,
-    warnings: [...configWarnings, ...local.warnings],
-  };
-}
-
-export function notifyRouterConfigWarnings(ctx, routerConfigResult) {
-  if (!routerConfigResult.warnings.length) {
-    return;
-  }
-
-  const key = routerConfigResult.warnings.join("\n");
-  if (key === lastRouterConfigWarningKey) {
-    return;
-  }
-
-  lastRouterConfigWarningKey = key;
-  ctx.ui.notify(`Freeflow config warning: ${routerConfigResult.warnings.join(" ")}`, "warning");
-}
-
 export function restoreModeOverride(ctx) {
   currentModeOverride = null;
   currentSessionOverrides = {};
@@ -538,7 +613,13 @@ export async function readModeState(cwd) {
   };
 }
 
-export function setModeStatus(ctx, modeState, capabilityState = undefined) {
+export function setModeStatus(
+  ctx,
+  modeState,
+  capabilityState = undefined,
+  cognitiveRoutingRuntime = undefined,
+  options: { cognitiveRoutingStartupPending?: boolean } = {},
+) {
   if (capabilityState && !capabilityState.configured) {
     ctx.ui.setStatus("freeflow", capabilityState.configExists ? "freeflow: config error" : "freeflow: setup needed");
     return;
@@ -560,8 +641,39 @@ export function setModeStatus(ctx, modeState, capabilityState = undefined) {
   } else if (capabilityState?.configSources?.skillsEnabled === "session") {
     active.push("skills off (session)");
   }
-  if (capabilityState?.outputRouter.enabled) {
-    active.push("router");
+  const cognitiveRouting = capabilityState?.cognitiveRouting;
+  const cognitiveRoutingActive = cognitiveRouting?.effective === true && cognitiveRoutingRuntime?.effective === true;
+  const startupSelectionSuppressesCognitiveRouting =
+    ctx?.modelStateProvenance?.explicitModel === true || ctx?.modelStateProvenance?.explicitThinking === true;
+  if (cognitiveRoutingActive) {
+    const profile = cognitiveRoutingRuntime.activeProfile;
+    const control =
+      cognitiveRoutingRuntime.controlMode === "manual-standard" ||
+      cognitiveRoutingRuntime.controlMode === "manual-reasoning"
+        ? "manual hold"
+        : "automatic";
+    active.push(`${profile} · ${control}`);
+  } else if (cognitiveRouting?.enabled === true) {
+    if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
+      active.push("cognitive disabled · PiFlow only");
+    } else if (
+      cognitiveRouting.effective === true &&
+      cognitiveRoutingRuntime === undefined &&
+      options.cognitiveRoutingStartupPending === true &&
+      !startupSelectionSuppressesCognitiveRouting
+    ) {
+      const startupProfile = cognitiveRouting.sessionStart?.profile ?? "standard";
+      active.push(`${startupProfile} · pending`);
+    } else {
+      const reason =
+        cognitiveRouting?.effective === true
+          ? (cognitiveRoutingRuntime?.blockingReason?.code ?? "runtime_inactive")
+          : (cognitiveRouting.blockingReason?.code ?? "unavailable");
+      active.push(`cognitive blocked · ${reason}`);
+    }
+  }
+  if (capabilityState?.contextVirtualization?.effective || capabilityState?.conversationHistory?.effective) {
+    active.push("context");
   }
   ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "idle"}`);
 }
@@ -585,175 +697,121 @@ export function skillPrompt(skill, args) {
   return trimmed ? `/skill:${skill}\n\n${trimmed}` : `/skill:${skill}`;
 }
 
-function outputRouterModeGuidance(mode, skillsEnabled = true) {
-  if (!skillsEnabled) {
-    return "Freeflow Skills are disabled: no Freeflow workflow mode is active; apply only output-router evidence guidance.";
-  }
-  if (mode === "conversation") {
-    return "conversation mode: keep routed-tool guidance soft; answer questions directly.";
-  }
-  if (mode === "strict-workflow") {
-    return "strict-workflow mode: strongest guidance; prefer exact, recoverable routed evidence for risky work.";
-  }
-  return "workflow mode: prefer routed tools for exploration and likely-large command output.";
-}
-
-function outputRouterContext(modeState, freeflowContext, routerConfigResult, capabilityState) {
-  const safetyNetText =
-    routerConfigResult.config.postToolRouting === "off"
-      ? ""
-      : "\n\nOutput-router config note: large native read/bash outputs may be vaulted and replaced with labeled routed output. Use freeflow_search with the output id to recover exact content.";
-
-  return `## Loaded Output Router Skill
-
-Mode guidance: ${outputRouterModeGuidance(modeState.effectiveMode, capabilityState.skills.effective)}${safetyNetText}
-
-\`\`\`md
-${freeflowContext.outputRouterSkill.trim()}
-\`\`\``;
-}
-
-function capabilityContext(capabilityState) {
-  const sessionSuffix = (source) => (source === "session" ? " (session override)" : "");
-  const interactionContract = `${capabilityState.interactionContract.effective ? "enabled" : "disabled"}${sessionSuffix(
-    capabilityState.configSources.interactionContract,
-  )}`;
-  const skills = `${capabilityState.skills.effective ? "enabled" : "disabled"}${sessionSuffix(
-    capabilityState.configSources.skillsEnabled,
-  )}`;
-  const outputRouter = capabilityState.outputRouter.enabled ? "enabled" : "disabled";
-  return `## Freeflow Capabilities
+type CognitiveRoutingRuntimeSnapshot = {
+  effective?: boolean;
+  activeProfile?: unknown;
+  controlMode?: unknown;
+};
 
-- Interaction contract: ${interactionContract}. Configure with \`/freeflow settings\` or temporarily with \`/freeflow settings session\`; inspect with \`/freeflow status\`.
-- Skills: ${skills}. Configure with \`/freeflow settings\` or temporarily with \`/freeflow settings session\`; inspect with \`/freeflow status\`.
-- Output router: ${outputRouter}. Configure with \`/freeflow settings\` or \`/output-router\`; inspect with \`/output-router status\`.
+type FreeflowContextMessage = {
+  customType?: unknown;
+  [key: string]: unknown;
+};
 
-Disabled capabilities are named only for status/config awareness. Capability-specific instructions and tools are active only while that capability is enabled.`;
+function publicCognitiveRoutingControl(controlMode) {
+  if (controlMode === "automatic") return "automatic";
+  if (controlMode === "manual-standard" || controlMode === "manual-reasoning") return "manual";
+  return "unavailable";
 }
 
-function hasModelFacingCapability(capabilityState) {
-  return (
-    capabilityState.interactionContract.effective ||
-    capabilityState.skills.effective ||
-    capabilityState.outputRouter.enabled
-  );
+function publicCognitiveRoutingProfile(activeProfile, effective) {
+  if (effective !== true) return "unavailable";
+  return activeProfile === "standard" || activeProfile === "reasoning" ? activeProfile : "unavailable";
 }
 
-function modeOverlayContext(mode) {
-  if (mode === "conversation") {
-    return `
-
-## Conversation Mode Boundary
-
-Conversation mode is active and read-only.
-
-Do not call write, edit, or mutating tools. Do not create, delete, commit, push, or change repository, system, external, or durable state.
-
-A mutation request does not switch mode, and an execution skill does not override this boundary. Explain that conversation mode is read-only and ask the user to switch to workflow or strict-workflow.`;
-  }
-
-  if (mode === "strict-workflow") {
-    return `
-
-## Strict Workflow Overlay
-
-Strict Workflow is active. Use the adaptive Workflow, but increase decision, evidence, verification, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
-
-For work affecting security, privacy, billing, data loss, migrations, public interfaces, compatibility, deployment, or architecture:
-
-- stop for any user-owned choice or source conflict;
-- inspect the relevant risk surface before crossing the boundary;
-- select only artifacts, checkpoints, and independent review that materially reduce risk;
-- verify at the affected boundary before claiming success.
-
-Do not manufacture ceremony for low-risk, reversible work. Strict Workflow does not authorize mutation, bypass safety, or make every implementation detail a user decision.`;
-  }
-
-  return "";
+function publicCapabilityStatus(capability) {
+  if (capability?.effective === true) return "active";
+  if (!capability) return "unavailable";
+  const blockingCode = capability.blockingReason?.code;
+  if (blockingCode && blockingCode !== "disabled") return "unavailable";
+  return "inactive";
 }
 
-function activeModeContext(modeState) {
-  return `## Freeflow Mode State
-
-Repository default mode: \`${modeState.repositoryDefaultMode}\` (${modeState.repositoryDefaultModeSource}).
-Personal default override: \`${modeState.personalDefaultMode ?? "none"}\`.
-Configured default mode: \`${modeState.defaultMode}\` (${modeSourceLabel(modeState.defaultModeSource)}).
-Session mode override: \`${modeState.sessionMode ?? "none"}\`.
-Resolved mode: \`${modeState.resolvedMode}\`.
-Effective Freeflow mode: \`${modeState.effectiveMode}\`.
-
-Mode behavior:
-- \`conversation\`: answer, discuss, critique, and inspect read-only; require a mode change before mutating state.
-- \`workflow\`: use the adaptive workflow for consequential or mutating work.
-- \`strict-workflow\`: use the same workflow with stronger decision, evidence, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
+export function freeflowRuntimeStateMessage(
+  modeState,
+  capabilityState,
+  cognitiveRoutingRuntime: CognitiveRoutingRuntimeSnapshot | undefined = undefined,
+) {
+  const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
+  const profile = publicCognitiveRoutingProfile(
+    cognitiveRoutingRuntime?.activeProfile,
+    cognitiveRoutingEffective && cognitiveRoutingRuntime?.effective === true,
+  );
+  const control =
+    profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
+  const defaultMode = modeState?.defaultMode ?? "workflow";
+  const activeMode = modeState?.effectiveMode ?? "inactive";
 
-Task type, risk classification, and direct skill calls do not change mode. Recommend another mode when useful; the user decides.
-Do not announce mode on every reply. Mention it when the user asks, configuration is discussed, or it changes the next action.${modeOverlayContext(modeState.effectiveMode)}`;
+  return {
+    role: "custom",
+    customType: FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE,
+    content: [
+      "# Freeflow Runtime State",
+      "",
+      "This is extension-generated runtime state. Use it to interpret the stable Freeflow guidance.",
+      "",
+      `Default mode: \`${defaultMode}\``,
+      `Active mode: \`${activeMode}\``,
+      "",
+      "Capabilities:",
+      `- Interaction Contract: ${publicCapabilityStatus(capabilityState?.interactionContract)}`,
+      `- Skills: ${publicCapabilityStatus(capabilityState?.skills)}`,
+      `- Context Virtualization: ${publicCapabilityStatus(capabilityState?.contextVirtualization)}`,
+      `- Conversation History: ${publicCapabilityStatus(capabilityState?.conversationHistory)}`,
+      `- Cognitive Routing: ${publicCapabilityStatus(capabilityState?.cognitiveRouting)}`,
+      "",
+      "Cognitive Routing:",
+      `- Control: \`${control}\``,
+      `- Profile: \`${profile}\``,
+    ].join("\n"),
+    display: false,
+    details: { source: "provider-request-runtime-state" },
+  };
 }
 
-function inactiveModeContext(modeState) {
-  return `## Freeflow Mode State
-
-Repository default mode: \`${modeState.repositoryDefaultMode}\` (${modeState.repositoryDefaultModeSource}).
-Personal default override: \`${modeState.personalDefaultMode ?? "none"}\`.
-Configured default mode: \`${modeState.defaultMode}\` (${modeSourceLabel(modeState.defaultModeSource)}).
-Session mode override: \`${modeState.sessionMode ?? "none"}\`.
-Resolved mode: \`${modeState.resolvedMode}\` (inactive because Skills are disabled).
-Effective Freeflow mode: \`none\`.
-
-Freeflow workflow modes are dormant until Skills are enabled with \`/freeflow settings\`.`;
+export function withoutFreeflowRuntimeState(messages: readonly FreeflowContextMessage[] | undefined) {
+  return (Array.isArray(messages) ? messages : []).filter(
+    (message) =>
+      message?.customType !== FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE &&
+      message?.customType !== COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
+  );
 }
 
-function controlPlaneContext(modeState, capabilityState) {
-  return `# Freeflow Control Plane
-
-Freeflow is enabled for this repo, but no model-facing capabilities are enabled.
-These lines are status/config awareness only; do not apply Freeflow workflow or output-router behavior.
-
-${inactiveModeContext(modeState)}
-
-${capabilityContext(capabilityState)}
-
-Use \`/freeflow settings\` to enable the Interaction Contract, Skills, or Output Router. The read-only \`freeflow_status\` diagnostic may be available so the model can answer setup/status questions.`;
+export function withFreeflowRuntimeState(
+  messages: readonly FreeflowContextMessage[] | undefined,
+  modeState,
+  capabilityState,
+  cognitiveRoutingRuntime: CognitiveRoutingRuntimeSnapshot | undefined = undefined,
+) {
+  return [
+    ...withoutFreeflowRuntimeState(messages),
+    freeflowRuntimeStateMessage(modeState, capabilityState, cognitiveRoutingRuntime),
+  ];
 }
 
-export function runtimeContext(modeState, freeflowContext, routerConfigResult, capabilityState) {
-  if (!capabilityState.configured) {
+export function runtimeContext(freeflowContext, capabilityState) {
+  if (capabilityState?.configured !== true || capabilityState?.enabled !== true || !freeflowContext?.corePrompt) {
     return "";
   }
 
-  if (!capabilityState.enabled) {
-    return `# Freeflow Disabled
-
-Freeflow is disabled by \`.freeflow/config.json\` for this repo. Do not apply the Freeflow Interaction Contract, workflow, or output-router behavior unless the user re-enables Freeflow with \`/freeflow enable\` or \`/freeflow settings\`.
-
-These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.`;
+  const blocks = [];
+  if (freeflowContext?.corePrompt) blocks.push(freeflowContext.corePrompt.trim());
+  if (capabilityState.interactionContract?.effective === true && freeflowContext?.interactionContractPrompt) {
+    blocks.push(freeflowContext.interactionContractPrompt.trim());
   }
-
-  if (!hasModelFacingCapability(capabilityState)) {
-    return controlPlaneContext(modeState, capabilityState);
+  if (capabilityState.skills?.effective === true && freeflowContext?.skillsPrompt) {
+    blocks.push(freeflowContext.skillsPrompt.trim());
   }
-
-  const modeText = capabilityState.skills.effective ? activeModeContext(modeState) : inactiveModeContext(modeState);
-  const interactionContractText = capabilityState.interactionContract.effective
-    ? `\n\n${freeflowContext.interactionContract.trim()}`
-    : "";
-  const routerText =
-    capabilityState.outputRouter.enabled && routerConfigResult.config.enabled
-      ? `\n\n${outputRouterContext(modeState, freeflowContext, routerConfigResult, capabilityState)}`
-      : "";
-
-  return `# Freeflow Runtime Context
-
-Freeflow Pi extension loaded this before the agent turn.
-Runtime delivery: confirmed for this Pi \`before_agent_start\` invocation.
-These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.
-
-${modeText}
-
-${capabilityContext(capabilityState)}${interactionContractText}${routerText}
-
-This Pi extension loads enabled runtime context before every agent turn and routes commands only; it does not enforce policy, block tools, grant permissions, or create repo-local hooks.`;
+  if (capabilityState.cognitiveRouting?.effective === true && freeflowContext?.cognitiveRoutingPrompt) {
+    blocks.push(freeflowContext.cognitiveRoutingPrompt.trim());
+  }
+  if (capabilityState.contextVirtualization?.effective === true && freeflowContext?.contextVirtualizationPrompt) {
+    blocks.push(freeflowContext.contextVirtualizationPrompt.trim());
+  }
+  if (capabilityState.conversationHistory?.effective === true && freeflowContext?.conversationHistoryPrompt) {
+    blocks.push(freeflowContext.conversationHistoryPrompt.trim());
+  }
+  return blocks.filter(Boolean).join("\n\n");
 }
 
 export async function setSessionCoreOverride(key: SessionCoreKey, value: boolean | null, ctx, pi) {
@@ -781,7 +839,7 @@ export async function setSessionCoreOverride(key: SessionCoreKey, value: boolean
     changed: true,
     reloadRequired: key === "enabled" || key === "skillsEnabled",
     sessionOverrides: { ...currentSessionOverrides },
-    capabilityState: await readCapabilityState(ctx.cwd),
+    capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
 }
 
@@ -819,7 +877,7 @@ export async function setSessionMode(mode, ctx, pi) {
 
 export async function handleModeCommand(args, ctx, pi) {
   const arg = args?.trim();
-  const capabilityState = await readCapabilityState(ctx.cwd);
+  const capabilityState = await readCapabilityState(ctx.cwd, ctx, pi?.host);
   const inactiveModeState = await readModeState(ctx.cwd);
 
   if (!capabilityState.configured) {