@hassangameryt/freeflow 0.3.0 → 0.4.0

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

@@ -0,0 +1,895 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { normalizeFreeflowConfig, normalizeLocalFreeflowConfig } from "../../../router/dist/index.js";
+
+export const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+
+export const WORKFLOW_COMMANDS = [
+  { command: "discuss", skill: "discuss" },
+  { command: "discover", skill: "discuss" },
+  { 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" },
+  { command: "verify-work", skill: "verify-work" },
+  { command: "review-work", skill: "review-work" },
+  { command: "commit-work", skill: "commit-work" },
+  { command: "handoff", skill: "handoff" },
+  { command: "finish-branch", skill: "finish-branch" },
+  { command: "release-work", skill: "release-work" },
+  { command: "launch-work", skill: "launch-work" },
+  { command: "bypass", skill: "bypass" },
+];
+
+export const CONTRIBUTOR_COMMANDS = ["setup-freeflow", "write-skill", "evaluate-skill"];
+
+export const FREEFLOW_MODEL_SKILL_NAMES = [
+  "bypass",
+  "commit-work",
+  "decision-gate",
+  "migration-work",
+  "design-for-depth",
+  "diagnose-failure",
+  "discuss",
+  "evaluate-skill",
+  "execute-work",
+  "finish-branch",
+  "handoff",
+  "mode-contract",
+  "release-work",
+  "review-artifact",
+  "review-work",
+  "setup-freeflow",
+  "launch-work",
+  "simplify-code",
+  "tdd",
+  "track-work",
+  "verify-work",
+  "workflow",
+  "write-plan",
+  "write-skill",
+  "write-spec",
+];
+
+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));
+}
+
+type SessionCoreKey = "enabled" | "interactionContract" | "skillsEnabled";
+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 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 WORKFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-workflow-bootstrap";
+
+let runtimeContextCache = null;
+let currentModeOverride = null;
+let currentSessionOverrides: SessionCoreOverrides = {};
+let lastRouterConfigWarningKey = null;
+async function loadRuntimeContext(capabilityState = undefined) {
+  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([
+    interactionContractEnabled
+      ? readFile(new URL("../../../runtime/interaction-contract.md", import.meta.url), "utf8")
+      : Promise.resolve(null),
+    skillsEnabled
+      ? readFile(new URL("../../../skills/workflow/SKILL.md", import.meta.url), "utf8")
+      : Promise.resolve(null),
+    outputRouterEnabled
+      ? readFile(new URL("../../../skills/output-router/SKILL.md", import.meta.url), "utf8")
+      : Promise.resolve(null),
+  ]);
+
+  return { interactionContract, workflowSkill, outputRouterSkill };
+}
+
+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;
+}
+
+export async function refreshRuntimeContext(capabilityState = undefined) {
+  runtimeContextCache = await loadRuntimeContext(capabilityState);
+  return runtimeContextCache;
+}
+
+export async function getRuntimeContext(capabilityState = undefined) {
+  if (runtimeContextCacheSatisfies(capabilityState)) {
+    return runtimeContextCache;
+  }
+  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 [];
+}
+
+export function workflowBootstrapMessage(freeflowContext, capabilityState, sessionManager) {
+  if (capabilityState?.skills?.effective !== true || !freeflowContext?.workflowSkill) {
+    return undefined;
+  }
+
+  const alreadyLoaded = activeSessionEntries(sessionManager).some(
+    (entry) => entry?.type === "custom_message" && entry?.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
+  );
+  if (alreadyLoaded) {
+    return undefined;
+  }
+
+  return {
+    customType: WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
+    content: `# Freeflow Workflow Bootstrap\n\n${freeflowContext.workflowSkill.trim()}`,
+    display: false,
+    details: { skill: "workflow", source: "first-turn-bootstrap" },
+  };
+}
+
+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";
+  }
+
+  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) {
+  if (!isRecord(value)) {
+    return "config must be a JSON object";
+  }
+
+  const allowedKeys = new Set([
+    "enabled",
+    "defaultMode",
+    "interactionContract",
+    "skills",
+    "outputRouter",
+    "observedRouting",
+    "scriptTransform",
+  ]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      return `unsupported top-level config key: ${key}`;
+    }
+  }
+
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+
+  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
+    if (value[key] !== undefined && !isRecord(value[key])) {
+      return `${key} must be an object`;
+    }
+  }
+
+  return null;
+}
+
+function validateFreeflowLocalConfigShape(value) {
+  if (!isRecord(value)) {
+    return "local config must be a JSON object";
+  }
+
+  const allowedKeys = new Set(["enabled", "defaultMode", "interactionContract", "skills", "processing"]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      return `unsupported top-level local config key: ${key}`;
+    }
+  }
+
+  return validateCoreConfigFields(value);
+}
+
+async function readConfigFileState(path, validate) {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    const validationError = validate(parsed);
+    if (validationError) {
+      return {
+        path,
+        exists: true,
+        valid: false,
+        parsed: {},
+        parseError: validationError,
+      };
+    }
+    return { path, exists: true, valid: true, parsed, parseError: null };
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : undefined;
+    if (code === "ENOENT") {
+      return {
+        path,
+        exists: false,
+        valid: false,
+        parsed: {},
+        parseError: null,
+      };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      path,
+      exists: true,
+      valid: false,
+      parsed: {},
+      parseError: message,
+    };
+  }
+}
+
+export function readFreeflowConfigState(cwd) {
+  return readConfigFileState(join(cwd, ".freeflow/config.json"), validateFreeflowConfigShape);
+}
+
+export function readFreeflowLocalConfigState(cwd) {
+  return readConfigFileState(join(cwd, ".freeflow/local.json"), validateFreeflowLocalConfigShape);
+}
+
+export async function readFreeflowConfig(cwd) {
+  const state = await readFreeflowConfigState(cwd);
+  return state.valid ? state.parsed : {};
+}
+
+export async function readFreeflowLocalConfig(cwd) {
+  const state = await readFreeflowLocalConfigState(cwd);
+  return state.valid ? state.parsed : {};
+}
+
+function resolveLayeredValue(repository, local, key, fallback) {
+  if (Object.hasOwn(local, key)) {
+    return { value: local[key], source: "local" };
+  }
+  if (Object.hasOwn(repository, key)) {
+    return { value: repository[key], source: "repository" };
+  }
+  return { value: fallback, source: "builtin" };
+}
+
+function resolveCoreConfig(repository, local) {
+  const enabled = resolveLayeredValue(repository, local, "enabled", true);
+  const interactionContract = resolveLayeredValue(repository, local, "interactionContract", true);
+  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,
+      skills: { enabled: skillsEnabled.value },
+      defaultMode: defaultMode.value,
+    },
+    sources: {
+      enabled: enabled.source,
+      interactionContract: interactionContract.source,
+      skillsEnabled: skillsEnabled.source,
+      defaultMode: defaultMode.source,
+    },
+  };
+}
+
+function normalizeSessionOverrides(value): SessionCoreOverrides {
+  if (!isRecord(value)) return {};
+  const overrides: SessionCoreOverrides = {};
+  for (const key of SESSION_CORE_KEYS) {
+    if (typeof value[key] === "boolean") {
+      overrides[key] = value[key];
+    }
+  }
+  return overrides;
+}
+
+function resolveSessionCoreConfig(layers) {
+  const configured = layers.coreConfig;
+  const sources = layers.sources;
+  const enabled = currentSessionOverrides.enabled;
+  const interactionContract = currentSessionOverrides.interactionContract;
+  const skillsEnabled = currentSessionOverrides.skillsEnabled;
+
+  return {
+    config: {
+      enabled: typeof enabled === "boolean" ? enabled : configured.enabled,
+      interactionContract:
+        typeof interactionContract === "boolean" ? interactionContract : configured.interactionContract,
+      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,
+      skillsEnabled: typeof skillsEnabled === "boolean" ? "session" : sources.skillsEnabled,
+      defaultMode: sources.defaultMode,
+    },
+  };
+}
+
+export async function readFreeflowConfigLayers(cwd) {
+  const [repository, local] = await Promise.all([readFreeflowConfigState(cwd), readFreeflowLocalConfigState(cwd)]);
+  const repositoryConfig = repository.valid ? repository.parsed : {};
+  const localConfig = local.valid ? local.parsed : {};
+  const core = resolveCoreConfig(repositoryConfig, localConfig);
+  const localValid = !local.exists || local.valid;
+  const configured = repository.valid && localValid;
+  let blockingState = null;
+  if (!repository.valid) {
+    blockingState = repository;
+  } else if (local.exists && !local.valid) {
+    blockingState = local;
+  }
+
+  return {
+    configured,
+    repositoryConfigured: repository.valid,
+    repository,
+    local,
+    coreConfig: core.config,
+    sources: core.sources,
+    blockingConfigPath: blockingState?.path ?? null,
+    parseError: blockingState?.parseError ?? null,
+  };
+}
+
+export async function readCapabilityState(cwd) {
+  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;
+  return {
+    configured: layers.configured,
+    repositoryConfigured: layers.repositoryConfigured,
+    configExists: layers.repository.exists,
+    configValid: layers.configured,
+    configPath: layers.blockingConfigPath ?? layers.repository.path,
+    parseError: layers.parseError,
+    localConfigExists: layers.local.exists,
+    localConfigValid: !layers.local.exists || layers.local.valid,
+    localConfigPath: layers.local.path,
+    localConfigParseError: layers.local.parseError,
+    configuredCoreConfig: layers.coreConfig,
+    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,
+    },
+    outputRouter: {
+      enabled: enabled && outputRouterConfigEnabled,
+      configEnabled: outputRouterConfigEnabled,
+    },
+  };
+}
+
+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 = {};
+  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) {
+      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(ctx, modeState, capabilityState = undefined) {
+  if (capabilityState && !capabilityState.configured) {
+    ctx.ui.setStatus("freeflow", capabilityState.configExists ? "freeflow: config error" : "freeflow: setup needed");
+    return;
+  }
+  if (capabilityState && !capabilityState.enabled) {
+    const source = capabilityState.configSources?.enabled === "session" ? " (session)" : "";
+    ctx.ui.setStatus("freeflow", `freeflow: off${source}`);
+    return;
+  }
+
+  const active: string[] = [];
+  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?.outputRouter.enabled) {
+    active.push("router");
+  }
+  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;
+}
+
+export function skillPrompt(skill, args) {
+  const trimmed = args?.trim();
+  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
+
+- 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\`.
+
+Disabled capabilities are named only for status/config awareness. Capability-specific instructions and tools are active only while that capability is enabled.`;
+}
+
+function hasModelFacingCapability(capabilityState) {
+  return (
+    capabilityState.interactionContract.effective ||
+    capabilityState.skills.effective ||
+    capabilityState.outputRouter.enabled
+  );
+}
+
+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 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.
+
+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)}`;
+}
+
+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\`.`;
+}
+
+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 runtimeContext(modeState, freeflowContext, routerConfigResult, capabilityState) {
+  if (!capabilityState.configured) {
+    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.`;
+  }
+
+  if (!hasModelFacingCapability(capabilityState)) {
+    return controlPlaneContext(modeState, capabilityState);
+  }
+
+  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.`;
+}
+
+export async function setSessionCoreOverride(key: SessionCoreKey, value: boolean | null, ctx, pi) {
+  if (!SESSION_CORE_KEYS.has(key)) {
+    throw new Error(`Invalid Freeflow session override: ${String(key)}`);
+  }
+  if (value !== null && typeof value !== "boolean") {
+    throw new Error(`Invalid Freeflow session override value for ${key}: ${String(value)}`);
+  }
+
+  const hasOverride = Object.hasOwn(currentSessionOverrides, key);
+  if ((value === null && !hasOverride) || (value !== null && hasOverride && currentSessionOverrides[key] === value)) {
+    return { changed: false, sessionOverrides: { ...currentSessionOverrides } };
+  }
+
+  const next = { ...currentSessionOverrides };
+  if (value === null) {
+    delete next[key];
+  } else {
+    next[key] = value;
+  }
+  currentSessionOverrides = next;
+  pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: { ...currentSessionOverrides } });
+  return {
+    changed: true,
+    reloadRequired: key === "enabled" || key === "skillsEnabled",
+    sessionOverrides: { ...currentSessionOverrides },
+    capabilityState: await readCapabilityState(ctx.cwd),
+  };
+}
+
+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);
+
+  if (hadCoreOverrides) {
+    currentSessionOverrides = {};
+    pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: {} });
+  }
+  if (hadModeOverride) {
+    await setSessionMode(null, ctx, pi);
+  }
+
+  return {
+    changed: hadCoreOverrides || hadModeOverride,
+    reloadRequired,
+    sessionOverrides: { ...currentSessionOverrides },
+    modeState: await readModeState(ctx.cwd),
+  };
+}
+
+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);
+  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 };
+}