@hassangameryt/freeflow 0.6.0 → 0.7.1

package/pi-extension/dist/runtime/runtime-context.js

@@ -2,8 +2,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveCognitiveRoutingState } from "../cognitive-routing/runtime.js";
-import { isPiFlowHost } from "./runtime-identity.js";
-export const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing/host.js";
 export const WORKFLOW_COMMANDS = [
   { command: "discuss", skill: "discuss" },
   { command: "action-selection", skill: "action-selection" },
@@ -38,7 +37,6 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "execute-work",
   "finish-branch",
   "handoff",
-  "mode-contract",
   "release-work",
   "review-artifact",
   "review-work",
@@ -74,16 +72,8 @@ export function freeflowModelSkillPaths(capabilityState = undefined) {
   }
   return paths;
 }
-const MODE_STATE_ENTRY = "freeflow-mode";
 const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
-const SESSION_CORE_KEYS = new Set([
-  "enabled",
-  "interactionContract",
-  "skillsEnabled",
-  "contextVirtualization",
-  "conversationHistory",
-]);
-const RESET_MODE_ARGS = new Set(["reset"]);
+const SESSION_CORE_KEYS = new Set(["enabled", "contextVirtualization", "conversationHistory"]);
 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";
@@ -91,26 +81,31 @@ 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 = {};
+export function isPromptAvailable(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+export function hasUsableMandatoryPrompts(freeflowContext) {
+  return (
+    isPromptAvailable(freeflowContext?.corePrompt) && isPromptAvailable(freeflowContext?.interactionContractPrompt)
+  );
+}
 async function readPromptFile(url) {
   try {
-    return await readFile(url, "utf8");
+    const prompt = await readFile(url, "utf8");
+    return isPromptAvailable(prompt) ? prompt.trim() : null;
   } 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 contextVirtualizationEnabled = capabilityState?.contextVirtualization?.effective === true;
   const conversationHistoryEnabled = capabilityState?.conversationHistory?.effective === true;
   const cognitiveRoutingEnabled = capabilityState?.cognitiveRouting?.effective === true;
   const [
     corePrompt,
     interactionContractPrompt,
-    skillsPrompt,
     cognitiveRoutingPrompt,
     contextVirtualizationPrompt,
     conversationHistoryPrompt,
@@ -118,12 +113,9 @@ async function loadRuntimeContext(capabilityState = undefined) {
     freeflowEnabled
       ? readPromptFile(new URL("../../../runtime/prompts/core.md", import.meta.url))
       : Promise.resolve(null),
-    interactionContractEnabled
+    freeflowEnabled
       ? readPromptFile(new URL("../../../runtime/prompts/interaction-contract.md", import.meta.url))
       : Promise.resolve(null),
-    skillsEnabled
-      ? 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),
@@ -137,7 +129,6 @@ async function loadRuntimeContext(capabilityState = undefined) {
   return {
     corePrompt,
     interactionContractPrompt,
-    skillsPrompt,
     cognitiveRoutingPrompt,
     contextVirtualizationPrompt,
     conversationHistoryPrompt,
@@ -147,13 +138,12 @@ function runtimeContextCacheSatisfies(capabilityState) {
   if (!runtimeContextCache) return false;
   const expected = {
     corePrompt: capabilityState?.enabled === true,
-    interactionContractPrompt: capabilityState?.interactionContract?.effective === true,
-    skillsPrompt: capabilityState?.skills?.effective === true,
+    interactionContractPrompt: capabilityState?.enabled === 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]));
+  return Object.entries(expected).every(([key, required]) => !required || isPromptAvailable(runtimeContextCache[key]));
 }
 export async function refreshRuntimeContext(capabilityState = undefined) {
   runtimeContextCache = await loadRuntimeContext(capabilityState);
@@ -196,9 +186,6 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function validateCoreConfigFields(value) {
-  if (value.defaultMode !== undefined && !VALID_MODES.has(value.defaultMode)) {
-    return `invalid defaultMode: ${JSON.stringify(value.defaultMode)}`;
-  }
   if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
     return "enabled must be a boolean";
   }
@@ -208,22 +195,6 @@ function validateCoreConfigFields(value) {
   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";
-  }
-  if (value.skills !== undefined) {
-    if (!isRecord(value.skills)) {
-      return "skills must be an object";
-    }
-    for (const key of Object.keys(value.skills)) {
-      if (key !== "enabled") {
-        return `unsupported skills config key: ${key}`;
-      }
-    }
-    if (value.skills.enabled !== undefined && typeof value.skills.enabled !== "boolean") {
-      return "skills.enabled must be a boolean";
-    }
-  }
   return null;
 }
 function validateFreeflowConfigShape(value) {
@@ -233,9 +204,6 @@ function validateFreeflowConfigShape(value) {
   // Keep retired capability keys shape-tolerated so existing repositories remain activated; runtime behavior ignores them.
   const allowedKeys = new Set([
     "enabled",
-    "defaultMode",
-    "interactionContract",
-    "skills",
     "outputRouter",
     "observedRouting",
     "scriptTransform",
@@ -263,9 +231,6 @@ function validateFreeflowLocalConfigShape(value) {
   }
   const allowedKeys = new Set([
     "enabled",
-    "defaultMode",
-    "interactionContract",
-    "skills",
     "processing",
     "cognitiveRouting",
     "contextVirtualization",
@@ -339,29 +304,18 @@ 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 : {};
-  const skillsEnabled = resolveLayeredValue(repositorySkills, localSkills, "enabled", true);
   return {
     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,
     },
   };
 }
@@ -379,29 +333,20 @@ function resolveSessionCoreConfig(layers) {
   const configured = layers.coreConfig;
   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 {
     config: {
       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,
     },
   };
 }
@@ -433,55 +378,27 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
   const layers = await readFreeflowConfigLayers(cwd);
   const effectiveCore = resolveSessionCoreConfig(layers);
   const enabled = layers.configured && effectiveCore.config.enabled;
-  const interactionContractConfigEnabled = effectiveCore.config.interactionContract;
-  const skillsConfigEnabled = effectiveCore.config.skills.enabled;
   const contextVirtualizationConfigEnabled = effectiveCore.config.contextVirtualization;
   const conversationHistoryConfigEnabled = effectiveCore.config.conversationHistory;
-  const skillsEffective = enabled && skillsConfigEnabled;
-  const hostSupportsCognitiveRouting = isPiFlowHost(extensionHost);
+  const hostSupportsCognitiveRouting = supportsCognitiveRoutingModelRegistry(host);
   const configuredCognitiveRouting = await resolveCognitiveRoutingState(
     layers.repository.parsed,
     layers.local.parsed,
     hostSupportsCognitiveRouting ? host : undefined,
   );
-  const disabledReason = enabled
-    ? skillsEffective
-      ? undefined
-      : { code: "disabled", message: "Skills are disabled" }
-    : { code: "disabled", message: "Freeflow is disabled" };
+  const disabledReason = enabled ? undefined : { code: "disabled", message: "Freeflow is disabled" };
   const childCapability = (configuredEnabled) => ({
     enabled: configuredEnabled,
-    effective: skillsEffective && configuredEnabled,
+    effective: enabled && configuredEnabled,
     ...(disabledReason ? { blockingReason: disabledReason } : {}),
   });
   const cognitiveRouting = enabled
-    ? skillsEffective
-      ? !hostSupportsCognitiveRouting && configuredCognitiveRouting.configValid
-        ? {
-            ...configuredCognitiveRouting,
-            effective: false,
-            blockingReason: {
-              code: "runtime_disabled",
-              message: "Cognitive Routing is disabled outside the PiFlow runtime",
-            },
-          }
-        : configuredCognitiveRouting
-      : {
-          ...configuredCognitiveRouting,
-          effective: false,
-          blockingReason: {
-            code: "disabled",
-            message: "Skills are disabled",
-          },
-        }
+    ? configuredCognitiveRouting
     : {
         ...configuredCognitiveRouting,
         enabled: false,
         effective: false,
-        blockingReason: {
-          code: "disabled",
-          message: "Freeflow is disabled",
-        },
+        blockingReason: disabledReason,
       };
   return {
     configured: layers.configured,
@@ -498,16 +415,7 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
     configuredSources: layers.sources,
     sessionOverrides: { ...currentSessionOverrides },
     configSources: effectiveCore.sources,
-    defaultMode: effectiveCore.config.defaultMode,
     enabled,
-    interactionContract: {
-      enabled: interactionContractConfigEnabled,
-      effective: enabled && interactionContractConfigEnabled,
-    },
-    skills: {
-      enabled: skillsConfigEnabled,
-      effective: enabled && skillsConfigEnabled,
-    },
     contextVirtualization: childCapability(contextVirtualizationConfigEnabled),
     conversationHistory: childCapability(conversationHistoryConfigEnabled),
     hostSupportsCognitiveRouting,
@@ -515,48 +423,20 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
   };
 }
 export const readRuntimeState = readCapabilityState;
-export function restoreModeOverride(ctx) {
-  currentModeOverride = null;
+export function restoreSessionOverrides(ctx) {
   currentSessionOverrides = {};
   const entries = ctx.sessionManager?.getBranch?.() ?? ctx.sessionManager?.getEntries?.() ?? [];
   for (const entry of entries) {
-    if (entry.type !== "custom") continue;
-    if (entry.customType === MODE_STATE_ENTRY) {
-      const mode = entry.data?.currentMode;
-      currentModeOverride = VALID_MODES.has(mode) ? mode : null;
-    } else if (entry.customType === SESSION_OVERRIDES_ENTRY) {
+    if (entry.type === "custom" && entry.customType === SESSION_OVERRIDES_ENTRY) {
       currentSessionOverrides = normalizeSessionOverrides(entry.data?.overrides);
     }
   }
 }
-export async function readModeState(cwd) {
-  const layers = await readFreeflowConfigLayers(cwd);
-  const effectiveCore = resolveSessionCoreConfig(layers);
-  const repositoryDefaultMode = VALID_MODES.has(layers.repository.parsed.defaultMode)
-    ? layers.repository.parsed.defaultMode
-    : "workflow";
-  const personalDefaultMode = VALID_MODES.has(layers.local.parsed.defaultMode) ? layers.local.parsed.defaultMode : null;
-  const sessionMode = VALID_MODES.has(currentModeOverride) ? currentModeOverride : null;
-  const resolvedMode = sessionMode ?? effectiveCore.config.defaultMode;
-  const active = layers.configured && effectiveCore.config.enabled && effectiveCore.config.skills.enabled;
-  return {
-    repositoryDefaultMode,
-    repositoryDefaultModeSource: VALID_MODES.has(layers.repository.parsed.defaultMode) ? "repository" : "builtin",
-    personalDefaultMode,
-    defaultMode: effectiveCore.config.defaultMode,
-    defaultModeSource: effectiveCore.sources.defaultMode,
-    currentMode: sessionMode,
-    sessionMode,
-    resolvedMode,
-    active,
-    effectiveMode: active ? resolvedMode : null,
-  };
-}
-export function setModeStatus(
+export function setFreeflowStatus(
   ctx,
-  modeState,
   capabilityState = undefined,
   cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
   options = {},
 ) {
   if (capabilityState && !capabilityState.configured) {
@@ -568,22 +448,25 @@ export function setModeStatus(
     ctx.ui.setStatus("freeflow", `freeflow: off${source}`);
     return;
   }
-  const active = [];
-  if (capabilityState?.interactionContract.effective) {
-    active.push("interaction");
-  } else if (capabilityState?.configSources?.interactionContract === "session") {
-    active.push("interaction off (session)");
-  }
-  if (capabilityState?.skills.effective) {
-    active.push(`${modeState.effectiveMode}${modeState.currentMode ? " (session)" : ""}`);
-  } else if (capabilityState?.configSources?.skillsEnabled === "session") {
-    active.push("skills off (session)");
+  if (capabilityState?.enabled === true && !hasUsableMandatoryPrompts(freeflowContext)) {
+    ctx.ui.setStatus("freeflow", "freeflow: unavailable");
+    return;
   }
+  const active = [];
   const cognitiveRouting = capabilityState?.cognitiveRouting;
+  const cognitiveRoutingInactive =
+    cognitiveRouting?.enabled === true && cognitiveRoutingRuntime?.runtimeStatus === "inactive";
+  const cognitiveRoutingBlocked =
+    cognitiveRouting?.enabled === true &&
+    (cognitiveRouting?.blockingReason?.code === "runtime_blocked" ||
+      cognitiveRoutingRuntime?.runtimeStatus === "blocked");
   const cognitiveRoutingActive = cognitiveRouting?.effective === true && cognitiveRoutingRuntime?.effective === true;
-  const startupSelectionSuppressesCognitiveRouting =
-    ctx?.modelStateProvenance?.explicitModel === true || ctx?.modelStateProvenance?.explicitThinking === true;
-  if (cognitiveRoutingActive) {
+  const startupSelectionSuppressesCognitiveRouting = options.startupSelectionSuppressed === true;
+  if (cognitiveRoutingInactive) {
+    active.push("cognitive inactive");
+  } else if (cognitiveRoutingBlocked) {
+    active.push(`cognitive blocked · ${cognitiveRoutingRuntime?.runtimeReason ?? "runtime_blocked"}`);
+  } else if (cognitiveRoutingActive) {
     const profile = cognitiveRoutingRuntime.activeProfile;
     const control =
       cognitiveRoutingRuntime.controlMode === "manual-standard" ||
@@ -593,18 +476,21 @@ export function setModeStatus(
     active.push(`${profile} · ${control}`);
   } else if (cognitiveRouting?.enabled === true) {
     if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
-      active.push("cognitive disabled · PiFlow only");
+      active.push("cognitive blocked · runtime_disabled");
     } else if (
       cognitiveRouting.effective === true &&
       cognitiveRoutingRuntime === undefined &&
       options.cognitiveRoutingStartupPending === true &&
       !startupSelectionSuppressesCognitiveRouting
     ) {
-      const startupProfile = cognitiveRouting.sessionStart?.profile ?? "standard";
+      const startupProfile =
+        cognitiveRouting.sessionStart?.control === "manual"
+          ? (cognitiveRouting.sessionStart.profile ?? "reasoning")
+          : "reasoning";
       active.push(`${startupProfile} · pending`);
     } else {
       const reason =
-        cognitiveRouting?.effective === true
+        cognitiveRouting.effective === true
           ? (cognitiveRoutingRuntime?.blockingReason?.code ?? "runtime_inactive")
           : (cognitiveRouting.blockingReason?.code ?? "unavailable");
       active.push(`cognitive blocked · ${reason}`);
@@ -613,19 +499,7 @@ export function setModeStatus(
   if (capabilityState?.contextVirtualization?.effective || capabilityState?.conversationHistory?.effective) {
     active.push("context");
   }
-  ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "idle"}`);
-}
-function modeSourceLabel(source) {
-  if (source === "local") return "personal override";
-  if (source === "repository") return "repository default";
-  return "built-in default";
-}
-function describeModeState(modeState) {
-  const configuredDefault = `configured default ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)})`;
-  if (modeState.sessionMode) {
-    return `session ${modeState.sessionMode}; ${configuredDefault}`;
-  }
-  return configuredDefault;
+  ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "active"}`);
 }
 export function skillPrompt(skill, args) {
   const trimmed = args?.trim();
@@ -647,7 +521,15 @@ function publicCapabilityStatus(capability) {
   if (blockingCode && blockingCode !== "disabled") return "unavailable";
   return "inactive";
 }
-export function freeflowRuntimeStateMessage(modeState, capabilityState, cognitiveRoutingRuntime = undefined) {
+function publicCognitiveRoutingStatus(capability, runtime) {
+  if (runtime?.runtimeStatus === "inactive") return "inactive";
+  return publicCapabilityStatus(capability);
+}
+export function freeflowRuntimeStateMessage(
+  capabilityState,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+) {
   const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
   const profile = publicCognitiveRoutingProfile(
     cognitiveRoutingRuntime?.activeProfile,
@@ -655,8 +537,16 @@ export function freeflowRuntimeStateMessage(modeState, capabilityState, cognitiv
   );
   const control =
     profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
-  const defaultMode = modeState?.defaultMode ?? "workflow";
-  const activeMode = modeState?.effectiveMode ?? "inactive";
+  const mandatoryPromptAvailable = capabilityState?.enabled !== true || hasUsableMandatoryPrompts(freeflowContext);
+  const freeflowStatus = capabilityState?.configured
+    ? capabilityState.enabled
+      ? mandatoryPromptAvailable
+        ? "active"
+        : "unavailable"
+      : "inactive"
+    : capabilityState?.configExists
+      ? "config error"
+      : "setup needed";
   return {
     role: "custom",
     customType: FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE,
@@ -665,15 +555,12 @@ export function freeflowRuntimeStateMessage(modeState, capabilityState, cognitiv
       "",
       "This is extension-generated runtime state. Use it to interpret the stable Freeflow guidance.",
       "",
-      `Default mode: \`${defaultMode}\``,
-      `Active mode: \`${activeMode}\``,
+      `Freeflow: ${freeflowStatus}`,
       "",
       "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: ${publicCognitiveRoutingStatus(capabilityState?.cognitiveRouting, cognitiveRoutingRuntime)}`,
       "",
       "Cognitive Routing:",
       `- Control: \`${control}\``,
@@ -690,31 +577,68 @@ export function withoutFreeflowRuntimeState(messages) {
       message?.customType !== COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
   );
 }
-export function withFreeflowRuntimeState(messages, modeState, capabilityState, cognitiveRoutingRuntime = undefined) {
-  return [
-    ...withoutFreeflowRuntimeState(messages),
-    freeflowRuntimeStateMessage(modeState, capabilityState, cognitiveRoutingRuntime),
-  ];
+function lastUserMessageIndex(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+function insertRuntimeStateBeforeLatestUser(messages, runtimeState) {
+  const latestUserIndex = lastUserMessageIndex(messages);
+  if (latestUserIndex < 0) return [...messages, runtimeState];
+  return [...messages.slice(0, latestUserIndex), runtimeState, ...messages.slice(latestUserIndex)];
+}
+export function withFreeflowRuntimeState(
+  messages,
+  capabilityState,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+  options = {},
+) {
+  const source = Array.isArray(messages) ? messages : [];
+  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext);
+  const runtimeStateMessages = source.filter(
+    (message) =>
+      message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE ||
+      message?.customType === COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
+  );
+  const withoutRuntimeState = withoutFreeflowRuntimeState(source);
+  const expectedRuntimeStateIndex = lastUserMessageIndex(withoutRuntimeState);
+  const runtimeStateIndex = source.findIndex((message) => message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE);
+  const unchanged =
+    options.force !== true &&
+    runtimeStateMessages.length === 1 &&
+    runtimeStateMessages[0]?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE &&
+    runtimeStateMessages[0]?.content === runtimeState.content &&
+    runtimeStateIndex === (expectedRuntimeStateIndex < 0 ? withoutRuntimeState.length : expectedRuntimeStateIndex);
+  if (unchanged) return source;
+  return insertRuntimeStateBeforeLatestUser(withoutRuntimeState, runtimeState);
 }
 export function runtimeContext(freeflowContext, capabilityState) {
-  if (capabilityState?.configured !== true || capabilityState?.enabled !== true || !freeflowContext?.corePrompt) {
+  if (
+    capabilityState?.configured !== true ||
+    capabilityState?.enabled !== true ||
+    !hasUsableMandatoryPrompts(freeflowContext)
+  ) {
     return "";
   }
-  const blocks = [];
-  if (freeflowContext?.corePrompt) blocks.push(freeflowContext.corePrompt.trim());
-  if (capabilityState.interactionContract?.effective === true && freeflowContext?.interactionContractPrompt) {
-    blocks.push(freeflowContext.interactionContractPrompt.trim());
-  }
-  if (capabilityState.skills?.effective === true && freeflowContext?.skillsPrompt) {
-    blocks.push(freeflowContext.skillsPrompt.trim());
-  }
-  if (capabilityState.cognitiveRouting?.effective === true && freeflowContext?.cognitiveRoutingPrompt) {
+  const blocks = [freeflowContext.corePrompt.trim(), freeflowContext.interactionContractPrompt.trim()];
+  if (
+    capabilityState.cognitiveRouting?.effective === true &&
+    isPromptAvailable(freeflowContext.cognitiveRoutingPrompt)
+  ) {
     blocks.push(freeflowContext.cognitiveRoutingPrompt.trim());
   }
-  if (capabilityState.contextVirtualization?.effective === true && freeflowContext?.contextVirtualizationPrompt) {
+  if (
+    capabilityState.contextVirtualization?.effective === true &&
+    isPromptAvailable(freeflowContext.contextVirtualizationPrompt)
+  ) {
     blocks.push(freeflowContext.contextVirtualizationPrompt.trim());
   }
-  if (capabilityState.conversationHistory?.effective === true && freeflowContext?.conversationHistoryPrompt) {
+  if (
+    capabilityState.conversationHistory?.effective === true &&
+    isPromptAvailable(freeflowContext.conversationHistoryPrompt)
+  ) {
     blocks.push(freeflowContext.conversationHistoryPrompt.trim());
   }
   return blocks.filter(Boolean).join("\n\n");
@@ -740,106 +664,22 @@ export async function setSessionCoreOverride(key, value, ctx, pi) {
   pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: { ...currentSessionOverrides } });
   return {
     changed: true,
-    reloadRequired: key === "enabled" || key === "skillsEnabled",
+    reloadRequired: key === "enabled",
     sessionOverrides: { ...currentSessionOverrides },
     capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
 }
 export async function resetSessionOverrides(ctx, pi) {
   const hadCoreOverrides = Object.keys(currentSessionOverrides).length > 0;
-  const reloadRequired =
-    Object.hasOwn(currentSessionOverrides, "enabled") || Object.hasOwn(currentSessionOverrides, "skillsEnabled");
-  const hadModeOverride = VALID_MODES.has(currentModeOverride);
+  const reloadRequired = Object.hasOwn(currentSessionOverrides, "enabled");
   if (hadCoreOverrides) {
     currentSessionOverrides = {};
     pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: {} });
   }
-  if (hadModeOverride) {
-    await setSessionMode(null, ctx, pi);
-  }
   return {
-    changed: hadCoreOverrides || hadModeOverride,
+    changed: hadCoreOverrides,
     reloadRequired,
     sessionOverrides: { ...currentSessionOverrides },
-    modeState: await readModeState(ctx.cwd),
+    capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
 }
-export async function setSessionMode(mode, ctx, pi) {
-  const nextMode = mode === "default" || mode === "reset" || mode === null ? null : mode;
-  if (nextMode !== null && !VALID_MODES.has(nextMode)) {
-    throw new Error(`Invalid Freeflow mode: ${String(mode)}`);
-  }
-  currentModeOverride = nextMode;
-  pi?.appendEntry?.(MODE_STATE_ENTRY, { currentMode: nextMode });
-  return readModeState(ctx.cwd);
-}
-export async function handleModeCommand(args, ctx, pi) {
-  const arg = args?.trim();
-  const capabilityState = await readCapabilityState(ctx.cwd, ctx, pi?.host);
-  const inactiveModeState = await readModeState(ctx.cwd);
-  if (!capabilityState.configured) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      "Freeflow is installed but this repo is not set up. Run /setup-freeflow before changing mode.",
-      "warning",
-    );
-    return { changed: false, error: "not_configured" };
-  }
-  if (!capabilityState.enabled) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      "Freeflow is disabled for this repo. Use /freeflow enable or /freeflow settings to re-enable it.",
-      "warning",
-    );
-    return { changed: false, error: "freeflow_disabled" };
-  }
-  if (!capabilityState.skills.effective) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow modes are inactive because Skills are disabled. Configured default mode: ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}). Enable Skills in /freeflow settings before changing mode.`,
-      "warning",
-    );
-    return { changed: false, error: "skills_disabled" };
-  }
-  if (VALID_MODES.has(arg)) {
-    if (inactiveModeState.effectiveMode === arg) {
-      setModeStatus(ctx, inactiveModeState, capabilityState);
-      const message = inactiveModeState.sessionMode
-        ? `Freeflow is already in ${arg} mode for this Pi session. No session entry was added. Configured default remains ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}).`
-        : `Freeflow is already in ${arg} mode from the configured default (${modeSourceLabel(inactiveModeState.defaultModeSource)}). No session override was created.`;
-      ctx.ui.notify(message, "info");
-      return { changed: false, modeState: inactiveModeState };
-    }
-    const modeState = await setSessionMode(arg, ctx, pi);
-    setModeStatus(ctx, modeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow mode is now ${modeState.effectiveMode} for this Pi session. Stored in Pi session history; .freeflow/local.json and .freeflow/config.json were not changed. Configured default remains ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)}).`,
-      "info",
-    );
-    return { changed: true, modeState };
-  }
-  if (RESET_MODE_ARGS.has(arg) || arg === "default") {
-    if (!inactiveModeState.sessionMode) {
-      setModeStatus(ctx, inactiveModeState, capabilityState);
-      ctx.ui.notify(
-        `Freeflow is already using the configured default: ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}). No session override is active.`,
-        "info",
-      );
-      return { changed: false, modeState: inactiveModeState };
-    }
-    const modeState = await setSessionMode(null, ctx, pi);
-    setModeStatus(ctx, modeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow mode reset to configured default: ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)}). Session override cleared; .freeflow/local.json and .freeflow/config.json were not changed.`,
-      "info",
-    );
-    return { changed: true, modeState };
-  }
-  const modeState = await readModeState(ctx.cwd);
-  setModeStatus(ctx, modeState, capabilityState);
-  ctx.ui.notify(
-    `Freeflow mode is ${modeState.effectiveMode} (${describeModeState(modeState)}). Use /freeflow mode conversation, /freeflow mode workflow, /freeflow mode strict-workflow, or /freeflow mode reset.`,
-    "info",
-  );
-  return { changed: false, modeState, error: arg ? "invalid_mode" : undefined };
-}