@hassangameryt/freeflow 0.7.1 → 0.7.3

package/pi-extension/dist/provider-support/astra/adapter.js

@@ -0,0 +1,110 @@
+import { assemble, EFFORTS } from "./history.js";
+import { SessionState } from "./session-state.js";
+export function requestKey(payload, model) {
+  if (
+    !payload ||
+    payload.model !== "gpt-6-astra" ||
+    model?.id !== payload.model ||
+    payload.store !== false ||
+    !Array.isArray(payload.input) ||
+    !EFFORTS.includes(payload.reasoning?.effort) ||
+    payload.previous_response_id ||
+    payload.conversation ||
+    payload.context_management ||
+    (payload.truncation && payload.truncation !== "disabled") ||
+    (payload.reasoning.mode && payload.reasoning.mode !== "standard") ||
+    payload.agents ||
+    payload.input.some((x) => x?.type === "configuration_update" || x?.type === "compaction_trigger")
+  )
+    return;
+  const codex = model.provider === "openai-codex" && model.api === "openai-codex-responses";
+  const api = model.provider === "openai" && model.api === "openai-responses";
+  if (!codex && !api) return;
+  if (model.baseUrl !== undefined && typeof model.baseUrl !== "string") return;
+  const base = (model.baseUrl ?? (codex ? "https://chatgpt.com/backend-api" : "https://api.openai.com/v1")).replace(
+    /\/+$/,
+    "",
+  );
+  const allowed = codex
+    ? [
+        "https://chatgpt.com/backend-api",
+        "https://chatgpt.com/backend-api/codex",
+        "https://chatgpt.com/backend-api/codex/responses",
+      ]
+    : ["https://api.openai.com/v1"];
+  if (!allowed.includes(base)) return;
+  return `${model.provider}/${model.api}/${model.id}`;
+}
+export class AstraAdapter {
+  pi;
+  session;
+  generation = 0;
+  compacting = false;
+  queue = Promise.resolve();
+  statusSignature;
+  constructor(pi) {
+    this.pi = pi;
+  }
+  reset(ctx) {
+    this.generation++;
+    this.session = undefined;
+    this.compacting = false;
+    this.status(ctx, undefined);
+  }
+  setCompacting(value) {
+    this.compacting = value;
+  }
+  status(ctx, label) {
+    if (this.statusSignature === label) return;
+    this.statusSignature = label;
+    // Diagnostics must never turn a completed payload transformation into an exception.
+    try {
+      ctx.ui?.setStatus?.("freeflow-astra-effort", label);
+    } catch {}
+  }
+  async adapt(payload, ctx) {
+    const generation = this.generation;
+    const operation = this.queue.then(async () => {
+      const key = requestKey(payload, ctx.model);
+      if (generation !== this.generation || this.compacting || !key) {
+        this.status(ctx, undefined);
+        return payload;
+      }
+      try {
+        const reader = ctx.sessionManager;
+        if (
+          typeof this.pi.appendEntry !== "function" ||
+          !reader?.getLeafId ||
+          !reader.getSessionId ||
+          !reader.getSessionFile
+        )
+          throw new Error("Native session persistence unavailable");
+        const id = reader.getSessionId(),
+          file = reader.getSessionFile();
+        if (!this.session || this.session.id !== id || this.session.file !== file)
+          this.session = { id, file, store: new SessionState(this.pi, reader) };
+        const store = this.session.store,
+          basis = reader.getLeafId();
+        const records = await store.records();
+        if (
+          generation !== this.generation ||
+          reader.getLeafId() !== basis ||
+          this.session?.store !== store ||
+          key !== requestKey(payload, ctx.model)
+        )
+          throw new Error("Astra request changed during preparation");
+        const result = assemble(payload, key, store.generation(), basis, records);
+        if (result.record) store.append(result.record);
+        this.status(ctx, `Astra ${result.effective} · cache baseline ${result.baseline}`);
+        return result.payload;
+      } catch {
+        // Pi swallows hook exceptions. Return the untouched full-history request,
+        // including its requested effort, instead of a partially pinned request.
+        this.status(ctx, "Astra cache adaptation unavailable · native effort");
+        return payload;
+      }
+    });
+    this.queue = operation.catch(() => {});
+    return operation;
+  }
+}

package/pi-extension/dist/provider-support/astra/history.js

@@ -0,0 +1,125 @@
+import { createHash, randomUUID } from "node:crypto";
+export const ENTRY_TYPE = "freeflow-astra-effort-v1";
+export const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+export const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const digest = (x) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
+const effort = (x) => EFFORTS.includes(x);
+const identity = (x) => typeof x === "string" && x.length > 0 && x.length <= 1024;
+export function parseAttempt(value) {
+  if (
+    !value ||
+    value.version !== 1 ||
+    !identity(value.id) ||
+    !(value.basis === null || identity(value.basis)) ||
+    !identity(value.key) ||
+    !identity(value.generation) ||
+    !digest(value.envelope) ||
+    !digest(value.inputHash) ||
+    !effort(value.baseline) ||
+    !effort(value.effective) ||
+    !(value.parent === null || identity(value.parent)) ||
+    !Number.isSafeInteger(value.length) ||
+    value.length < 0 ||
+    (value.update !== undefined &&
+      (!value.update ||
+        !Number.isSafeInteger(value.update.at) ||
+        value.update.at < 0 ||
+        value.update.at > value.length ||
+        !digest(value.update.prefixHash) ||
+        !effort(value.update.effort))) ||
+    Object.keys(value).some(
+      (k) =>
+        ![
+          "version",
+          "id",
+          "basis",
+          "key",
+          "generation",
+          "envelope",
+          "baseline",
+          "effective",
+          "parent",
+          "length",
+          "inputHash",
+          "update",
+        ].includes(k),
+    )
+  )
+    throw new Error("Invalid Astra effort history");
+  return value;
+}
+// Hash complete serialized items, including opaque reasoning; never persist their bodies.
+export function prefixHashes(input) {
+  const result = [hash([])];
+  for (const item of input) result.push(hash([result.at(-1), item]));
+  return result;
+}
+export function envelopeHash(payload) {
+  const { input: _input, prompt_cache_key: _key, max_output_tokens: _max, stream: _stream, ...rest } = payload;
+  const { effort: _effort, ...reasoning } = rest.reasoning;
+  return hash({ ...rest, reasoning });
+}
+export function assemble(payload, key, generation, basis, records) {
+  const hashes = prefixHashes(payload.input),
+    envelope = envelopeHash(payload);
+  const applicable = records.filter((r) => r.key === key && r.generation === generation);
+  const compatible = applicable.filter((r) => r.envelope === envelope && hashes[r.length] === r.inputHash);
+  const prior = compatible.reduce((best, r) => (!best || r.length >= best.length ? r : best), undefined);
+  const baseline = prior?.baseline ?? applicable[0]?.baseline ?? payload.reasoning.effort;
+  const desired = payload.reasoning.effort;
+  const byId = new Map(records.map((r) => [r.id, r]));
+  const updates = [];
+  const seen = new Set();
+  let cursor = prior;
+  while (cursor) {
+    if (seen.has(cursor.id)) throw new Error("Cyclic Astra history");
+    seen.add(cursor.id);
+    if (cursor.update) {
+      if (hashes[cursor.update.at] !== cursor.update.prefixHash) throw new Error("Astra anchor changed");
+      updates.unshift(cursor.update);
+    }
+    if (cursor.parent === null) break;
+    const parent = byId.get(cursor.parent);
+    if (!parent || parent.key !== key || parent.generation !== generation || parent.baseline !== baseline)
+      throw new Error("Astra history parent unavailable");
+    cursor = parent;
+  }
+  let update;
+  if (desired !== (prior?.effective ?? baseline)) {
+    // Only insert before a new user item. Within a tool loop, append after all completed exchanges.
+    const last = payload.input.length - 1;
+    const at = payload.input[last]?.role === "user" && last >= (prior?.length ?? 0) ? last : payload.input.length;
+    update = { at, prefixHash: hashes[at], effort: desired };
+    if (updates.at(-1)?.at === at) throw new Error("Adjacent Astra effort updates");
+    updates.push(update);
+  }
+  if (updates.some((u, i) => i > 0 && u.at <= updates[i - 1].at)) throw new Error("Invalid Astra update order");
+  const output = structuredClone(payload);
+  output.input = [];
+  let nextUpdate = 0;
+  for (let i = 0; i <= payload.input.length; i++) {
+    if (updates[nextUpdate]?.at === i) {
+      output.input.push({ type: "configuration_update", reasoning: { effort: updates[nextUpdate++].effort } });
+    }
+    if (i < payload.input.length) output.input.push(structuredClone(payload.input[i]));
+  }
+  output.reasoning.effort = baseline;
+  const identical = prior?.length === payload.input.length && prior.effective === desired;
+  const record = identical
+    ? undefined
+    : {
+        version: 1,
+        id: randomUUID(),
+        basis,
+        key,
+        generation,
+        envelope,
+        baseline,
+        effective: desired,
+        parent: prior?.id ?? null,
+        length: payload.input.length,
+        inputHash: hashes.at(-1),
+        ...(update ? { update } : {}),
+      };
+  return { payload: output, record, baseline, effective: desired, rebased: !prior && applicable.length > 0 };
+}

package/pi-extension/dist/provider-support/astra/index.js

@@ -0,0 +1,11 @@
+import { AstraAdapter } from "./adapter.js";
+export function registerAstraSupport(pi) {
+  const adapter = new AstraAdapter(pi);
+  pi.on("session_start", (_event, ctx) => adapter.reset(ctx));
+  pi.on("session_shutdown", (_event, ctx) => adapter.reset(ctx));
+  pi.on("session_tree", (_event, ctx) => adapter.reset(ctx));
+  pi.on("session_before_compact", () => adapter.setCompacting(true));
+  pi.on("session_compact", (_event, ctx) => adapter.reset(ctx));
+  pi.on("session_compact_failed", () => adapter.setCompacting(false));
+  pi.on("before_provider_request", (event, ctx) => adapter.adapt(event.payload, ctx));
+}

package/pi-extension/dist/provider-support/astra/session-state.js

@@ -0,0 +1,114 @@
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot } from "../../session-sources/read-only-session.js";
+import { ENTRY_TYPE, parseAttempt } from "./history.js";
+export class SessionState {
+  pi;
+  reader;
+  acknowledged = new Map();
+  fault;
+  constructor(pi, reader) {
+    this.pi = pi;
+    this.reader = reader;
+  }
+  branch() {
+    const entries = this.reader.getBranch();
+    let parent = null;
+    const seen = new Set();
+    for (const entry of entries) {
+      if (!entry.id || seen.has(entry.id) || entry.parentId !== parent)
+        throw new Error("Invalid Astra session ancestry");
+      seen.add(entry.id);
+      parent = entry.id;
+    }
+    if (parent !== this.reader.getLeafId()) throw new Error("Astra session leaf changed");
+    return entries;
+  }
+  async records() {
+    if (this.fault) throw new Error(this.fault);
+    const branch = this.branch();
+    // Model visits are not history replacement. Derive both identities from the
+    // selected native ancestry so old v1 records remain readable without rewriting them.
+    const boundaries = new Map();
+    let epoch = "root",
+      legacy = "root",
+      model;
+    for (const entry of branch) {
+      if (entry.type === "compaction" || entry.type === "branch_summary") epoch = legacy = entry.id;
+      if (entry.type === "model_change") {
+        const next = `${entry.provider}/${entry.modelId}`;
+        if (model !== next) legacy = entry.id;
+        model = next;
+      }
+      boundaries.set(entry.id, { epoch, legacy });
+    }
+    const entries = branch.filter((e) => e.type === "custom" && e.customType === ENTRY_TYPE);
+    const records = entries.map((e) => {
+      const record = parseAttempt(e.data);
+      if (
+        record.basis !== e.parentId &&
+        !(this.reader.getHeader?.()?.parentSession && !branch.some((entry) => entry.id === record.basis))
+      )
+        throw new Error("Astra attempt anchor mismatch");
+      const boundary = boundaries.get(e.id);
+      if (record.generation !== boundary.epoch && record.generation !== boundary.legacy)
+        throw new Error("Astra history generation unavailable");
+      return { ...record, generation: boundary.epoch };
+    });
+    if (new Set(records.map((r) => r.id)).size !== records.length) throw new Error("Duplicate Astra attempt");
+    const parents = new Map();
+    for (const record of records) {
+      const parent = record.parent === null ? undefined : parents.get(record.parent);
+      if (
+        record.parent !== null &&
+        (!parent ||
+          parent.key !== record.key ||
+          parent.generation !== record.generation ||
+          parent.envelope !== record.envelope ||
+          parent.baseline !== record.baseline ||
+          parent.length > record.length)
+      )
+        throw new Error("Invalid Astra history parent");
+      const expected = record.update?.effort ?? parent?.effective ?? record.baseline;
+      if (record.effective !== expected || (record.update && record.update.at < (parent?.length ?? 0)))
+        throw new Error("Invalid Astra effective effort");
+      parents.set(record.id, record);
+    }
+    const unknown = entries.some((e) => this.acknowledged.get(e.id) !== JSON.stringify(e));
+    const file = this.reader.getSessionFile();
+    if (unknown && file && branch.some((e) => e.type === "message" && e.message?.role === "assistant")) {
+      const sessionId = this.reader.getSessionId(),
+        leaf = this.reader.getLeafId();
+      const snapshot = await readOnlySessionSnapshot(file);
+      const persisted = activeReadOnlySessionBranch(snapshot, leaf);
+      if (
+        snapshot.sessionId !== sessionId ||
+        this.reader.getLeafId() !== leaf ||
+        JSON.stringify(persisted) !== JSON.stringify(branch)
+      )
+        throw new Error("Astra persisted ancestry differs");
+    }
+    for (const entry of entries) this.acknowledged.set(entry.id, JSON.stringify(entry));
+    return records;
+  }
+  generation() {
+    let generation = "root";
+    for (const entry of this.branch()) {
+      if (entry.type === "compaction" || entry.type === "branch_summary") generation = entry.id;
+    }
+    return generation;
+  }
+  append(record) {
+    try {
+      if (this.reader.getLeafId() !== record.basis) throw new Error("Astra request ancestry changed");
+      this.pi.appendEntry(ENTRY_TYPE, record);
+      const entry = this.branch().find(
+        (e) => e.type === "custom" && e.customType === ENTRY_TYPE && e.data?.id === record.id,
+      );
+      if (!entry || entry.parentId !== record.basis || JSON.stringify(entry.data) !== JSON.stringify(record))
+        throw new Error("Astra append not acknowledged");
+      this.acknowledged.set(entry.id, JSON.stringify(entry));
+    } catch (error) {
+      this.fault = "Astra append uncertain; native effort retained until session recovery";
+      throw error;
+    }
+  }
+}

package/pi-extension/dist/provider-support/index.js

@@ -0,0 +1,4 @@
+import { registerAstraSupport } from "./astra/index.js";
+export function registerProviderSupport(pi) {
+  registerAstraSupport(pi);
+}

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

@@ -0,0 +1,216 @@
+import { createHash, randomUUID } from "node:crypto";
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot } from "../session-sources/read-only-session.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-budget",
+  "freeflow-routing-communication",
+]);
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+function fingerprint(message) {
+  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);
+}
+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;
+  acknowledged = new Map();
+  identity;
+  fault = false;
+  serial = Promise.resolve();
+  revision = 0;
+  constructor(pi) {
+    this.pi = pi;
+  }
+  reset() {
+    this.revision++;
+    this.acknowledged.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 {
+        try {
+          ctx.ui?.setStatus?.("freeflow-cache", "Freeflow context replay unavailable · current view retained");
+        } catch {}
+        // 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.fault = false;
+      this.identity = identity;
+    }
+    if (this.fault) throw new Error("Uncertain Freeflow context append");
+    const branch = reader.getBranch(),
+      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");
+      parent = entry.id;
+      ids.add(entry.id);
+      if (entry.type === "compaction" || entry.type === "branch_summary") generation = entry.id;
+    }
+    if (parent !== leaf) throw new Error("Context leaf changed");
+    const entries = branch.filter((e) => e.type === "custom" && e.customType === ENTRY);
+    if (
+      entries.some((e) => this.acknowledged.get(e.id) !== hash(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 (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);
+      if (
+        (frame.basis !== entry.parentId && !(reader.getHeader?.()?.parentSession && !ids.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);
+      this.acknowledged.set(entry.id, hash(entry));
+    }
+    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 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 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);
+        }
+      }
+    }
+    if (!prior || prior.length !== base.length || additions.length) {
+      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 = reader.getBranch().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));
+      } catch (error) {
+        this.fault = true;
+        throw error;
+      }
+    }
+    try {
+      ctx.ui?.setStatus?.("freeflow-cache", undefined);
+    } catch {}
+    return result;
+  }
+}