@hassangameryt/freeflow 0.7.3 → 0.8.0

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?.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,58 @@ 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?.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 &&
+          !(reader.getHeader?.()?.parentSession && !ids.has(frame.basis) && !newIds.has(frame.basis))) ||
         byId.has(frame.id)
       )
         throw new Error("Context frame anchor differs");
@@ -131,13 +191,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 +225,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 +263,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 +281,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/runtime-state.js

@@ -0,0 +1,189 @@
+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(controlMode)) return "manual";
+  return "unavailable";
+}
+function publicCognitiveRoutingProfile(activeProfile, effective) {
+  if (effective !== true) return "unavailable";
+  return ["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";
+  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}`,
+      "",
+      "Capabilities:",
+      `- Cognitive Routing: ${publicCognitiveRoutingStatus(capabilityState?.cognitiveRouting, cognitiveRoutingRuntime)}`,
+      `- Tool Execution: ${publicCapabilityStatus(capabilityState?.toolExecution)}`,
+      "",
+      "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}\``,
+    ].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,
+  });
+  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)];
+}