@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/{session-sources → host}/read-only-session.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { open, stat } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { lstat, open, stat } from "node:fs/promises";
 import { TextDecoder } from "node:util";
 export class ReadOnlySessionError extends Error {
   code;
@@ -50,7 +51,10 @@ export function parseReadOnlySessionText(text) {
   const seen = new Set();
   return lines.map((line, i) => decodeEntry(line, i + 1, seen));
 }
+/** Whole-file snapshots read so far; tests check that a verified startup reads none. */
+export const readOnlySessionCounters = { snapshots: 0 };
 export async function readOnlySessionSnapshot(path, options = {}) {
+  readOnlySessionCounters.snapshots++;
   const limits = { ...SESSION_READ_LIMITS, ...options };
   if (Object.values(limits).some((n) => !Number.isSafeInteger(n) || n <= 0))
     throw new ReadOnlySessionError("invalid_limit", "Invalid snapshot limit.");
@@ -146,3 +150,115 @@ export function activeReadOnlySessionBranch(snapshot, leafId) {
   }
   return path.reverse();
 }
+// Byte offset and entry count up to which a session file is known to equal Pi's in-memory entries.
+const verified = new Map();
+/** Pi just parsed this file into memory, so its current bytes are the verified prefix. */
+export function trustLoadedSession(reader) {
+  const path = reader.getSessionFile?.();
+  if (!path) return;
+  try {
+    verified.set(path, { size: statSync(path).size, count: reader.getEntries().length });
+  } catch {
+    verified.delete(path);
+  }
+}
+/**
+ * At `session_start`, trust the file only when Pi just parsed it. A reload keeps Pi's session in memory without
+ * re-reading the file, so it establishes nothing: after a failed write, memory could hold an entry the file lacks.
+ * The previous trust point, or a full check, still applies after a reload.
+ */
+export function trustStartedSession(reason, reader) {
+  if (reason !== "reload") trustLoadedSession(reader);
+}
+async function tailMatches(path, reader) {
+  const point = verified.get(path);
+  if (!point) return false;
+  const entries = reader.getEntries();
+  let file;
+  try {
+    file = await open(path, "r");
+    const { size } = await file.stat();
+    if (size < point.size || entries.length < point.count) return false;
+    const buffer = Buffer.alloc(size - point.size);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, point.size);
+    if (bytesRead !== buffer.length) return false;
+    const lines = new TextDecoder("utf-8", { fatal: true }).decode(buffer).split("\n");
+    if (lines.pop() !== "") return false;
+    const appended = entries.slice(point.count);
+    // Pi appends each entry as its JSON serialization, in memory order.
+    if (lines.length !== appended.length || lines.some((line, i) => line !== JSON.stringify(appended[i]))) return false;
+    verified.set(path, { size, count: entries.length });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    await file?.close();
+  }
+}
+/**
+ * Whether every entry Pi holds is persisted, judged only by the bytes appended since the trust point: true when the
+ * file grew by exactly those entries. False when there is no trust point or anything differs; callers then fall back
+ * to a full snapshot.
+ */
+export async function persistedTailMatches(reader) {
+  const path = reader.getSessionFile?.();
+  return !!path && (await tailMatches(path, reader));
+}
+/** Verify one newly appended native anchor without re-reading the historical session. */
+export async function persistedLastEntryMatches(path, entry) {
+  if (!path) return false;
+  let file;
+  try {
+    const expected = Buffer.from(`${JSON.stringify(entry)}\n`, "utf8");
+    if (!expected.length || expected.length > 1024 * 1024) return false;
+    const named = await lstat(path, { bigint: true });
+    if (!named.isFile() || named.isSymbolicLink() || named.size < BigInt(expected.length)) return false;
+    file = await open(path, "r");
+    const before = await file.stat({ bigint: true });
+    if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) return false;
+    const actual = Buffer.alloc(expected.length);
+    let offset = 0;
+    while (offset < actual.length) {
+      const read = await file.read(
+        actual,
+        offset,
+        actual.length - offset,
+        Number(before.size) - actual.length + offset,
+      );
+      if (!read.bytesRead) return false;
+      offset += read.bytesRead;
+    }
+    const after = await file.stat({ bigint: true });
+    const current = await lstat(path, { bigint: true });
+    const signature = (value) => [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs].join(":");
+    return (
+      before.isFile() &&
+      signature(named) === signature(before) &&
+      signature(before) === signature(after) &&
+      signature(after) === signature(current) &&
+      actual.equals(expected)
+    );
+  } catch {
+    return false;
+  } finally {
+    await file?.close();
+  }
+}
+/** Whether the persisted session holds exactly this branch: tail-only after a trust point, else a full comparison. */
+export async function persistedBranchMatches(reader, leaf, branch) {
+  const path = reader.getSessionFile?.();
+  if (!path) return false;
+  if (await tailMatches(path, reader)) return true;
+  const snapshot = await readOnlySessionSnapshot(path);
+  const matches =
+    snapshot.sessionId === reader.getSessionId() &&
+    JSON.stringify(activeReadOnlySessionBranch(snapshot, leaf)) === JSON.stringify(branch);
+  // The trust point covers every entry Pi holds, so it is set only when the file holds them all: a match on this
+  // branch says nothing of an entry on another branch that was never written.
+  const onDisk = new Set(snapshot.entries.slice(1).map((entry) => entry.id));
+  const inMemory = reader.getEntries();
+  const complete = inMemory.length === onDisk.size && inMemory.every((entry) => onDisk.has(entry.id));
+  if (matches && complete) trustLoadedSession(reader);
+  else verified.delete(path);
+  return matches;
+}

package/pi-extension/dist/{runtime → host}/request-history.js

@@ -1,23 +1,26 @@
 import { createHash, randomUUID } from "node:crypto";
-import { activeReadOnlySessionBranch, readOnlySessionSnapshot } from "../session-sources/read-only-session.js";
+import { persistedBranchMatches } from "./read-only-session.js";
+import { occurrenceIdentity } from "./projection-tags.js";
+import { cachedBranch as activeBranch } from "./branch.js";
 const ENTRY = "freeflow-request-history-v1";
 const TRANSIENT = new Set([
   "freeflow-runtime-state",
   "freeflow-cognitive-routing-runtime-state",
   "freeflow-routing-v2-state",
+  "freeflow-routing-attention",
   "freeflow-routing-budget",
   "freeflow-routing-communication",
 ]);
+// Situational notices describe a condition, not standing state; once absent, the next occurrence is new.
+const SITUATIONAL = new Set(["freeflow-routing-attention"]);
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+/** Whole-message fingerprints computed so far; the request-path budget test counts them per request. */
+export const requestHistoryCounters = { fingerprints: 0 };
 function fingerprint(message) {
+  requestHistoryCounters.fingerprints++;
   const { usage: _usage, timestamp: _timestamp, details: _details, ...body } = message;
   return hash(body);
 }
-function prefixes(messages) {
-  const result = [hash([])];
-  for (const message of messages) result.push(hash([result.at(-1), fingerprint(message)]));
-  return result;
-}
 function owned(message) {
   return message?.role === "custom" && TRANSIENT.has(message.customType);
 }
@@ -50,17 +53,60 @@ function parse(value) {
 /** Preserve only Freeflow-generated occurrences. Native content remains owned by Pi and its projectors. */
 export class RequestHistory {
   pi;
+  monitor;
   acknowledged = new Map();
+  // Pi reuses immutable native entry objects across requests. A replacement object with the
+  // same ID must be validated again; a known entry need not be rehashed and reparsed.
+  validatedFrames = new Map();
+  prefixCache;
+  branchCache;
+  frameHash = (entry) => {
+    const cached = this.validatedFrames.get(entry.id);
+    return cached !== undefined && cached.entry === entry ? cached.hash : hash(entry);
+  };
+  // Unedited native entries and Freeflow's renderings of them never change under their identity, so their
+  // fingerprints are computed once per session.
+  fingerprints = new Map();
+  fingerprintOf = (message) => {
+    const id = occurrenceIdentity(message);
+    if (id === undefined) return fingerprint(message);
+    let value = this.fingerprints.get(id);
+    if (value === undefined) this.fingerprints.set(id, (value = fingerprint(message)));
+    return value;
+  };
+  prefixes(messages) {
+    const previous = this.prefixCache;
+    const identities = [];
+    const values = [hash([])];
+    let samePrefix = true;
+    for (let i = 0; i < messages.length; i++) {
+      const message = messages[i];
+      const entryId = occurrenceIdentity(message);
+      // Generated and host-edited messages have no stable identity and must be hashed anew.
+      const body = entryId === undefined ? fingerprint(message) : undefined;
+      const identity = entryId === undefined ? `body:${body}` : `entry:${entryId}`;
+      identities.push(identity);
+      samePrefix = samePrefix && previous?.identities[i] === identity;
+      values.push(samePrefix ? previous.values[i + 1] : hash([values[i], body ?? this.fingerprintOf(message)]));
+    }
+    this.prefixCache = { identities, values };
+    return values;
+  }
   identity;
   fault = false;
   serial = Promise.resolve();
   revision = 0;
-  constructor(pi) {
+  constructor(pi, monitor) {
     this.pi = pi;
+    this.monitor = monitor;
   }
   reset() {
     this.revision++;
     this.acknowledged.clear();
+    this.validatedFrames.clear();
+    this.prefixCache = undefined;
+    this.branchCache = undefined;
+    this.fingerprints.clear();
     this.identity = undefined;
     this.fault = false;
   }
@@ -71,9 +117,7 @@ export class RequestHistory {
       try {
         return await this.prepare(messages, view, ctx, revision, notice);
       } catch {
-        try {
-          ctx.ui?.setStatus?.("freeflow-cache", "Freeflow context replay unavailable · current view retained");
-        } catch {}
+        this.monitor?.set("context-replay", "Freeflow context replay unavailable · current view retained");
         // Keep the already-qualified projected view on failure, never raw hidden history.
         return messages;
       }
@@ -87,42 +131,62 @@ export class RequestHistory {
     const identity = `${reader.getSessionId()}:${reader.getSessionFile?.() ?? "memory"}`;
     if (this.identity !== identity) {
       this.acknowledged.clear();
+      this.validatedFrames.clear();
+      this.prefixCache = undefined;
+      this.branchCache = undefined;
+      this.fingerprints.clear();
       this.fault = false;
       this.identity = identity;
     }
     if (this.fault) throw new Error("Uncertain Freeflow context append");
-    const branch = reader.getBranch(),
+    const branch = activeBranch(reader),
       leaf = reader.getLeafId();
-    let parent = null,
-      generation = "root";
-    const ids = new Set();
-    for (const entry of branch) {
-      if (entry.parentId !== parent || ids.has(entry.id)) throw new Error("Invalid context ancestry");
+    const cachedBranch = this.branchCache;
+    // Pi appends immutable native entry objects. A sibling/edited branch breaks this exact prefix.
+    const extendsCache =
+      !!cachedBranch &&
+      cachedBranch.length <= branch.length &&
+      (cachedBranch.length === 0 ||
+        (branch[0] === cachedBranch.first && branch[cachedBranch.length - 1] === cachedBranch.last));
+    const start = extendsCache ? cachedBranch.length : 0;
+    let parent = extendsCache ? cachedBranch.leaf : null;
+    let generation = extendsCache ? cachedBranch.generation : "root";
+    const ids = extendsCache ? cachedBranch.ids : new Set();
+    const newIds = new Set();
+    for (let i = start; i < branch.length; i++) {
+      const entry = branch[i];
+      if (entry.parentId !== parent || ids.has(entry.id) || newIds.has(entry.id))
+        throw new Error("Invalid context ancestry");
       parent = entry.id;
-      ids.add(entry.id);
-      if (entry.type === "compaction" || entry.type === "branch_summary") generation = entry.id;
+      newIds.add(entry.id);
+      // Compaction replaces earlier history. A branch summary follows its branch point and keeps the path
+      // before it intact, so generated state there keeps its positions (frames on the abandoned path are
+      // not ancestors and drop out on their own).
+      if (entry.type === "compaction") generation = entry.id;
     }
     if (parent !== leaf) throw new Error("Context leaf changed");
-    const entries = branch.filter((e) => e.type === "custom" && e.customType === ENTRY);
+    const newEntries = branch.slice(start).filter((e) => e.type === "custom" && e.customType === ENTRY);
     if (
-      entries.some((e) => this.acknowledged.get(e.id) !== hash(e)) &&
+      newEntries.some((e) => this.acknowledged.get(e.id) !== this.frameHash(e)) &&
       reader.getSessionFile?.() &&
       branch.some((e) => e.message?.role === "assistant")
     ) {
-      const snapshot = await readOnlySessionSnapshot(reader.getSessionFile());
-      if (
-        snapshot.sessionId !== reader.getSessionId() ||
-        JSON.stringify(activeReadOnlySessionBranch(snapshot, leaf)) !== JSON.stringify(branch)
-      )
-        throw new Error("Context history readback differs");
+      if (!(await persistedBranchMatches(reader, leaf, branch))) throw new Error("Context history readback differs");
     }
     if (revision !== this.revision || reader.getLeafId() !== leaf) throw new Error("Context changed while preparing");
-    const frames = [],
-      byId = new Map();
-    for (const entry of entries) {
-      const frame = parse(entry.data);
+    const frames = extendsCache ? (newEntries.length ? [...cachedBranch.frames] : cachedBranch.frames) : [];
+    const byId = extendsCache ? (newEntries.length ? new Map(cachedBranch.byId) : cachedBranch.byId) : new Map();
+    for (const entry of newEntries) {
+      const cached = this.validatedFrames.get(entry.id);
+      const same = cached !== undefined && cached.entry === entry;
+      const frame = same ? cached.frame : parse(entry.data);
       if (
-        (frame.basis !== entry.parentId && !(reader.getHeader?.()?.parentSession && !ids.has(frame.basis))) ||
+        (frame.basis !== entry.parentId &&
+          // A null basis is in neither set, so it counts as outside the parent session's branch.
+          !(
+            reader.getHeader?.()?.parentSession &&
+            (frame.basis === null || (!ids.has(frame.basis) && !newIds.has(frame.basis)))
+          )) ||
         byId.has(frame.id)
       )
         throw new Error("Context frame anchor differs");
@@ -131,13 +195,26 @@ export class RequestHistory {
         throw new Error("Context frame parent missing");
       frames.push(frame);
       byId.set(frame.id, frame);
-      this.acknowledged.set(entry.id, hash(entry));
+      const entryHash = same ? cached.hash : hash(entry);
+      this.acknowledged.set(entry.id, entryHash);
+      if (!same) this.validatedFrames.set(entry.id, { entry, hash: entryHash, frame });
     }
+    for (const id of newIds) ids.add(id);
+    this.branchCache = {
+      first: branch[0],
+      last: branch.at(-1),
+      length: branch.length,
+      leaf,
+      generation,
+      ids,
+      frames,
+      byId,
+    };
     const base = messages.filter((m) => !owned(m));
     const current = messages
       .filter(owned)
       .filter((message) => !notice || message.customType !== "freeflow-routing-budget");
-    const hashes = prefixes(base);
+    const hashes = this.prefixes(base);
     const candidates = frames.filter((f) => f.generation === generation && hashes[f.length] === f.prefix);
     const prior = candidates.reduce((best, f) => (!best || f.length >= best.length ? f : best), undefined);
     const states = { ...prior?.states },
@@ -152,6 +229,13 @@ export class RequestHistory {
       if (kind === "freeflow-routing-communication") seenRetained.add(signature);
       else states[kind] = signature;
     }
+    const present = new Set(current.map((message) => message.customType));
+    let cleared = false;
+    for (const kind of SITUATIONAL)
+      if (states[kind] && !present.has(kind)) {
+        delete states[kind];
+        cleared = true;
+      }
     const injections = [];
     const chain = [];
     for (let cursor = prior; cursor; cursor = cursor.parent ? byId.get(cursor.parent) : undefined)
@@ -183,7 +267,9 @@ export class RequestHistory {
         }
       }
     }
-    if (!prior || prior.length !== base.length || additions.length) {
+    // A frame that only advances the length adds no injection its parent lacks and matches no
+    // branch its parent does not, so frames are written only when generated state changes.
+    if (!prior || additions.length || cleared) {
       const frame = {
         version: 1,
         id: randomUUID(),
@@ -199,18 +285,18 @@ export class RequestHistory {
       };
       try {
         this.pi.appendEntry(ENTRY, frame);
-        const entry = reader.getBranch().find((e) => e.customType === ENTRY && e.data?.id === frame.id);
+        const entry = activeBranch(reader).find((e) => e.customType === ENTRY && e.data?.id === frame.id);
         if (!entry || entry.parentId !== leaf || JSON.stringify(entry.data) !== JSON.stringify(frame))
           throw new Error("Context append not acknowledged");
-        this.acknowledged.set(entry.id, hash(entry));
+        const entryHash = hash(entry);
+        this.acknowledged.set(entry.id, entryHash);
+        this.validatedFrames.set(entry.id, { entry, hash: entryHash, frame });
       } catch (error) {
         this.fault = true;
         throw error;
       }
     }
-    try {
-      ctx.ui?.setStatus?.("freeflow-cache", undefined);
-    } catch {}
+    this.monitor?.set("context-replay", undefined);
     return result;
   }
 }

package/pi-extension/dist/host/rows.js

@@ -0,0 +1,25 @@
+import { Text } from "@earendil-works/pi-tui";
+/**
+ * A transcript row the way Pi draws its own: a one-line head, then the body. A short body (a few lines) shows in both
+ * views; a long one shows only when the row is expanded (ctrl+o), with a count of what is hidden.
+ */
+export const SHORT_LINES = 4;
+const SHORT_CHARS = 400;
+export function paint(theme, color, text) {
+  return theme?.fg ? theme.fg(color, text) : text;
+}
+export function firstLine(text, max = 100) {
+  const line =
+    String(text ?? "")
+      .split("\n")
+      .find((each) => each.trim()) ?? "";
+  const clean = line.trim();
+  return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+export function foldRow(head, body, expanded, theme) {
+  const lines = body.flatMap((each) => String(each).split("\n"));
+  const short = lines.length <= SHORT_LINES && lines.join("\n").length <= SHORT_CHARS;
+  if (!lines.length) return new Text(head, 0, 0);
+  if (expanded || short) return new Text(`${head}\n${lines.map((line) => `  ${line}`).join("\n")}`, 0, 0);
+  return new Text(`${head} ${paint(theme, "dim", `(${lines.length} lines, ctrl+o to expand)`)}`, 0, 0);
+}

package/pi-extension/dist/host/runtime-state.js

@@ -0,0 +1,204 @@
+import { reviewStateLine, skillsStateLine } from "./config-validation.js";
+import { hasUsableMandatoryPrompts } from "./prompts.js";
+/**
+ * The Freeflow Runtime State message: what is active this request, placed so unchanged state keeps its cached
+ * position and changed state never rewrites earlier input. Also drops bootstrap messages that older Freeflow
+ * versions saved in sessions.
+ */
+const FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-runtime-state";
+const COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-cognitive-routing-runtime-state";
+const WORKFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-workflow-bootstrap";
+const COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE = "freeflow-cognitive-routing-bootstrap";
+const FREEFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-bootstrap";
+const BOOTSTRAP_COMPONENTS = Object.freeze({
+  workflow: "workflow",
+  cognitiveRouting: "cognitive-routing",
+});
+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]
+        : []),
+    ];
+  }
+  if (entry.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE) {
+    return [BOOTSTRAP_COMPONENTS.workflow];
+  }
+  if (entry.customType === COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE) {
+    return [BOOTSTRAP_COMPONENTS.cognitiveRouting];
+  }
+  return [];
+}
+export function filterBootstrapMessage(message) {
+  return bootstrapEntryComponents(message).length === 0 ? message : undefined;
+}
+function publicCognitiveRoutingControl(controlMode) {
+  if (controlMode === "automatic") return "automatic";
+  if (["manual-helper", "manual-executor", "manual-coordinator"].includes(String(controlMode))) return "manual";
+  return "unavailable";
+}
+function publicCognitiveRoutingProfile(activeProfile, effective) {
+  if (effective !== true) return "unavailable";
+  return typeof activeProfile === "string" && ["helper", "executor", "coordinator"].includes(activeProfile)
+    ? activeProfile
+    : "unavailable";
+}
+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 publicCognitiveRoutingStatus(capability, runtime) {
+  if (runtime?.runtimeStatus === "inactive") return "inactive";
+  return publicCapabilityStatus(capability);
+}
+function publicCognitiveRoutingProjectionMode(capability, runtime, projectionFailure) {
+  if (capability?.projection !== true) return "disabled";
+  if (capability?.effective !== true) return "unavailable";
+  if (String(runtime?.controlMode).startsWith("manual-")) return "manual-bypass";
+  if (projectionFailure) return "blocked";
+  if (runtime?.runtimeStatus === "inactive" || runtime?.runtimeStatus === "blocked") return "unavailable";
+  if (runtime?.effective === true && runtime.controlMode === "automatic") return "enabled";
+  return "pending";
+}
+export function freeflowRuntimeStateMessage(
+  capabilityState,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+  options = {},
+) {
+  const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
+  const profile = publicCognitiveRoutingProfile(
+    cognitiveRoutingRuntime?.activeProfile,
+    cognitiveRoutingEffective && cognitiveRoutingRuntime?.effective === true,
+  );
+  const control =
+    profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
+  const projectionMode = publicCognitiveRoutingProjectionMode(
+    capabilityState?.cognitiveRouting,
+    cognitiveRoutingRuntime,
+    options.projectionFailure,
+  );
+  const mandatoryPromptAvailable = capabilityState?.enabled !== true || hasUsableMandatoryPrompts(freeflowContext);
+  const freeflowStatus = capabilityState?.configured
+    ? capabilityState.enabled
+      ? mandatoryPromptAvailable
+        ? "active"
+        : "unavailable"
+      : "inactive"
+    : capabilityState?.configExists
+      ? "config error"
+      : "setup needed";
+  // Only a choice the user made: the default adds nothing, so most users' state stays as it was.
+  const review = freeflowStatus === "active" ? reviewStateLine(capabilityState?.review) : null;
+  const skillsOff = freeflowStatus === "active" ? skillsStateLine(capabilityState?.skills?.off) : null;
+  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.",
+      "",
+      `Freeflow: ${freeflowStatus}`,
+      ...(review ? [review] : []),
+      ...(skillsOff ? [skillsOff] : []),
+      "",
+      "Capabilities:",
+      `- Cognitive Routing: ${publicCognitiveRoutingStatus(capabilityState?.cognitiveRouting, cognitiveRoutingRuntime)}`,
+      `- Tool Execution: ${publicCapabilityStatus(capabilityState?.toolExecution)}`,
+      ...(capabilityState?.messaging?.enabled
+        ? [`- Messaging: ${publicCapabilityStatus(capabilityState.messaging)}`]
+        : []),
+      "",
+      "Cognitive Routing:",
+      `- Control: \`${control}\``,
+      // Under Automatic control the routing Runtime State owns the active profile, so switches do not churn this state.
+      ...(control === "automatic" ? [] : [`- Profile: \`${profile}\``]),
+      `- Delegation: \`${cognitiveRoutingRuntime?.delegation ?? capabilityState?.cognitiveRouting?.delegation ?? "executor"}\``,
+      `- Projection: \`${projectionMode}\``,
+      ...(options.skills?.length ? ["", `Freeflow skills read in this context: ${options.skills.join(", ")}`] : []),
+      ...(options.taskMemory?.length ? ["", ...options.taskMemory] : []),
+    ].join("\n"),
+    display: false,
+    details: { source: "provider-request-runtime-state" },
+  };
+}
+function withoutFreeflowRuntimeState(messages) {
+  return (Array.isArray(messages) ? messages : []).filter(
+    (message) =>
+      message?.customType !== FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE &&
+      message?.customType !== COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
+  );
+}
+function firstUserMessageIndex(messages) {
+  for (let index = 0; index < messages.length; index += 1) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+function insertRuntimeStateBeforeFirstUser(messages, runtimeState) {
+  const firstUserIndex = firstUserMessageIndex(messages);
+  if (firstUserIndex < 0) return [...messages, runtimeState];
+  return [...messages.slice(0, firstUserIndex), runtimeState, ...messages.slice(firstUserIndex)];
+}
+export function withFreeflowRuntimeState(
+  messages,
+  capabilityState,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+  options = {},
+) {
+  const source = Array.isArray(messages) ? messages : [];
+  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext, {
+    projectionFailure: options.projectionFailure,
+    taskMemory: options.taskMemory,
+    skills: options.skills,
+  });
+  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 = firstUserMessageIndex(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;
+  if (options.anchor) return insertAnchoredRuntimeState(withoutRuntimeState, runtimeState, options.anchor);
+  return insertRuntimeStateBeforeFirstUser(withoutRuntimeState, runtimeState);
+}
+// Unchanged state keeps its position so the cached prefix survives; changed state is placed before the
+// latest user message so earlier input is not rewritten, and then stays at that position.
+function insertAnchoredRuntimeState(messages, runtimeState, anchor) {
+  let index;
+  if (anchor.content === runtimeState.content && anchor.index !== undefined && anchor.index <= messages.length)
+    index = anchor.index;
+  else if (anchor.content === undefined) {
+    const first = firstUserMessageIndex(messages);
+    index = first < 0 ? messages.length : first;
+  } else {
+    let latest = messages.length;
+    for (let i = messages.length - 1; i >= 0; i -= 1)
+      if (messages[i]?.role === "user") {
+        latest = i;
+        break;
+      }
+    index = latest;
+  }
+  anchor.content = runtimeState.content;
+  anchor.index = index;
+  return [...messages.slice(0, index), runtimeState, ...messages.slice(index)];
+}