@hassangameryt/freeflow 0.7.2 → 0.8.0

package/pi-extension/dist/host/request-history.js

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from "node:crypto";
+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 owned(message) {
+  return message?.role === "custom" && TRANSIENT.has(message.customType);
+}
+function parse(value) {
+  if (
+    !value ||
+    value.version !== 1 ||
+    typeof value.id !== "string" ||
+    typeof value.view !== "string" ||
+    typeof value.generation !== "string" ||
+    !(value.basis === null || typeof value.basis === "string") ||
+    !Number.isSafeInteger(value.length) ||
+    value.length < 0 ||
+    !/^[a-f0-9]{64}$/.test(value.prefix) ||
+    !(value.parent === null || typeof value.parent === "string") ||
+    !value.states ||
+    typeof value.states !== "object" ||
+    Array.isArray(value.states) ||
+    !Object.entries(value.states).every(
+      ([key, val]) => TRANSIENT.has(key) && typeof val === "string" && /^[a-f0-9]{64}$/.test(val),
+    ) ||
+    !Array.isArray(value.retained) ||
+    !value.retained.every((x) => typeof x === "string") ||
+    !Array.isArray(value.additions) ||
+    !value.additions.every((x) => Number.isSafeInteger(x.at) && x.at >= 0 && x.at <= value.length && owned(x.message))
+  )
+    throw new Error("Invalid Freeflow context history");
+  return 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, 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;
+  }
+  async assemble(messages, view, ctx, notice) {
+    const revision = this.revision;
+    const operation = this.serial.then(async () => {
+      if (revision !== this.revision) return messages;
+      try {
+        return await this.prepare(messages, view, ctx, revision, notice);
+      } 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;
+      }
+    });
+    this.serial = operation.catch(() => {});
+    return operation;
+  }
+  async prepare(messages, view, ctx, revision, notice) {
+    const reader = ctx.sessionManager;
+    if (!reader?.getBranch || !reader.getLeafId || !reader.getSessionId || !this.pi.appendEntry) return messages;
+    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 = activeBranch(reader),
+      leaf = reader.getLeafId();
+    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;
+      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 newEntries = branch.slice(start).filter((e) => e.type === "custom" && e.customType === ENTRY);
+    if (
+      newEntries.some((e) => this.acknowledged.get(e.id) !== this.frameHash(e)) &&
+      reader.getSessionFile?.() &&
+      branch.some((e) => e.message?.role === "assistant")
+    ) {
+      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 = 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) && !newIds.has(frame.basis))) ||
+        byId.has(frame.id)
+      )
+        throw new Error("Context frame anchor differs");
+      const previous = frame.parent ? byId.get(frame.parent) : undefined;
+      if (frame.parent && (!previous || previous.generation !== frame.generation || previous.length > frame.length))
+        throw new Error("Context frame parent missing");
+      frames.push(frame);
+      byId.set(frame.id, frame);
+      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 = 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 },
+      additions = [];
+    const seenRetained = new Set(prior?.retained ?? []);
+    for (const message of current) {
+      const signature = fingerprint(message),
+        kind = message.customType;
+      if (kind === "freeflow-routing-communication" ? seenRetained.has(signature) : states[kind] === signature)
+        continue;
+      additions.push({ at: base.length, message: structuredClone(message) });
+      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)
+      chain.unshift(cursor);
+    for (const frame of chain) injections.push(...frame.additions);
+    injections.push(...additions);
+    const result = [];
+    let next = 0;
+    for (let i = 0; i <= base.length; i++) {
+      while (injections[next]?.at === i) result.push(structuredClone(injections[next++].message));
+      if (i < base.length) result.push(base[i]);
+    }
+    if (next !== injections.length) throw new Error("Context anchor ordering differs");
+    if (notice) {
+      const warning = notice(result);
+      if (warning || states["freeflow-routing-budget"]) {
+        const message = warning ?? {
+          role: "custom",
+          customType: "freeflow-routing-budget",
+          display: false,
+          content: "Routing budget warning cleared for the current request.",
+          timestamp: 0,
+        };
+        const signature = fingerprint(message);
+        if (states[message.customType] !== signature) {
+          states[message.customType] = signature;
+          additions.push({ at: base.length, message });
+          result.push(message);
+        }
+      }
+    }
+    // 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(),
+        basis: leaf,
+        view,
+        generation,
+        length: base.length,
+        prefix: hashes.at(-1),
+        parent: prior?.id ?? null,
+        states,
+        retained: [...seenRetained],
+        additions,
+      };
+      try {
+        this.pi.appendEntry(ENTRY, frame);
+        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");
+        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;
+      }
+    }
+    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)];
+}