@hassangameryt/freeflow 0.7.3 → 0.8.0

package/pi-extension/dist/provider-support/cache/anchor.js

@@ -0,0 +1,21 @@
+/**
+ * Keep a remembered cache entry reachable. A provider only reads an entry that lies within its
+ * lookback window of some breakpoint, so when a request extends an earlier one by more than that
+ * window (for example after another model's turns were inserted), the earlier entry is lost even
+ * though the prefix is unchanged. Placing a breakpoint on the earlier request's final entry lets
+ * the request read it, and only the new tail is written.
+ */
+export function planAnchor(prior, current, limits) {
+  let entry;
+  for (const layout of prior) {
+    const end = layout.breakpoints.at(-1);
+    if (end === undefined || end >= current.chain.length || layout.chain[end] !== current.chain[end]) continue;
+    if (entry === undefined || end > entry) entry = end;
+  }
+  if (entry === undefined || current.breakpoints.includes(entry)) return;
+  const reach = current.breakpoints.find((position) => position > entry);
+  if (reach === undefined || reach - entry <= limits.lookback - limits.margin) return;
+  if (current.breakpoints.length < limits.maxBreakpoints) return { add: entry };
+  const remove = current.yieldable.find((position) => position < entry && current.breakpoints.includes(position));
+  return remove === undefined ? undefined : { add: entry, remove };
+}

package/pi-extension/dist/provider-support/cache/anthropic.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+/** Anthropic Messages: four explicit breakpoints, each reading entries up to 20 positions back. */
+export const ANTHROPIC_LIMITS = { maxBreakpoints: 4, lookback: 20, margin: 5 };
+// Consecutive tool_use blocks, and consecutive tool_result blocks, form one lookback position.
+const RUN_TYPES = new Set(["tool_use", "tool_result"]);
+// Thinking blocks cannot carry cache_control.
+const UNMARKABLE = new Set(["thinking", "redacted_thinking"]);
+const withoutMarkers = (value) => JSON.stringify(value, (key, v) => (key === "cache_control" ? undefined : v));
+export function anthropicLayout(payload) {
+  if (!payload || !Array.isArray(payload.messages)) return;
+  const chain = [],
+    handles = [],
+    breakpoints = [];
+  let hash = "",
+    pending = "";
+  const push = (fingerprint, handle, marked) => {
+    hash = createHash("sha256").update(hash).update(pending).update(fingerprint).digest("hex");
+    pending = "";
+    if (marked) breakpoints.push(chain.length);
+    chain.push(hash);
+    handles.push(handle);
+  };
+  if (Array.isArray(payload.tools) && payload.tools.length)
+    push(
+      `tools:${withoutMarkers(payload.tools)}`,
+      { kind: "tools" },
+      payload.tools.some((t) => t?.cache_control),
+    );
+  const system = typeof payload.system === "string" ? [{ type: "text", text: payload.system }] : (payload.system ?? []);
+  system.forEach((block, index) =>
+    push(
+      `system:${withoutMarkers(block)}`,
+      typeof payload.system === "string" ? undefined : { kind: "system", index },
+      !!block?.cache_control,
+    ),
+  );
+  payload.messages.forEach((message, m) => {
+    const start = `message:${message.role}:`;
+    if (!Array.isArray(message.content)) {
+      // Unmarkable without reshaping the message, but still part of the prefix.
+      push(`${start}${withoutMarkers(message.content)}`, undefined, false);
+      return;
+    }
+    if (!message.content.length) {
+      // Content-less messages (such as per-message effort) change the prefix without adding a position.
+      pending += `${start}${withoutMarkers(message)}`;
+      return;
+    }
+    // Mid-conversation role:"system" updates carry markers too; Pi puts the final one there when an update ends the request.
+    const markable = message.role === "user" || message.role === "assistant" || message.role === "system";
+    let b = 0;
+    while (b < message.content.length) {
+      const type = message.content[b]?.type;
+      let end = b;
+      if (RUN_TYPES.has(type)) while (message.content[end + 1]?.type === type) end++;
+      const run = message.content.slice(b, end + 1);
+      push(
+        `${b === 0 ? start : ""}${withoutMarkers(run)}`,
+        markable && !UNMARKABLE.has(message.content[end]?.type) ? { kind: "block", message: m, block: end } : undefined,
+        run.some((block) => block?.cache_control),
+      );
+      b = end + 1;
+    }
+  });
+  if (pending) push("", undefined, false);
+  const systemMarks = breakpoints.filter((p) => handles[p]?.kind === "system");
+  const yieldable = [
+    ...breakpoints.filter((p) => handles[p]?.kind === "tools"),
+    // The last system breakpoint covers every earlier one while the system prompt is unchanged.
+    ...systemMarks.slice(0, -1),
+  ];
+  return { layout: { chain, breakpoints, yieldable }, handles };
+}
+function markerAt(payload, handle) {
+  if (handle?.kind === "tools") return payload.tools.findLast((t) => t.cache_control)?.cache_control;
+  if (handle?.kind === "system") return payload.system[handle.index].cache_control;
+  if (handle?.kind === "block") return payload.messages[handle.message].content[handle.block].cache_control;
+}
+/** Apply a plan without mutating the host payload: only the touched containers are copied. */
+export function applyAnthropicAnchor(payload, { layout, handles }, plan) {
+  const add = handles[plan.add];
+  // Reuse the final breakpoint's marker so TTL ordering (longer lifetimes first) is preserved.
+  const marker = markerAt(payload, handles[layout.breakpoints.at(-1)]);
+  if (add?.kind !== "block" || !marker) return payload;
+  const next = { ...payload, messages: [...payload.messages] };
+  const message = { ...next.messages[add.message], content: [...next.messages[add.message].content] };
+  message.content[add.block] = { ...message.content[add.block], cache_control: marker };
+  next.messages[add.message] = message;
+  const remove = plan.remove === undefined ? undefined : handles[plan.remove];
+  if (remove?.kind === "tools")
+    next.tools = payload.tools.map((tool) => {
+      if (!tool?.cache_control) return tool;
+      const { cache_control: _marker, ...rest } = tool;
+      return rest;
+    });
+  else if (remove?.kind === "system") {
+    next.system = [...payload.system];
+    const { cache_control: _marker, ...rest } = next.system[remove.index];
+    next.system[remove.index] = rest;
+  }
+  return next;
+}

package/pi-extension/dist/provider-support/cache/health.js

@@ -0,0 +1,73 @@
+const WINDOW = 8;
+const MISSES = 4;
+const GAP_MS = 5 * 60_000;
+const MIN_PROMPT = 8_000;
+const HIT_SHARE = 0.5;
+const tokens = (n) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : `${Math.round(n / 1e3)}k`);
+/**
+ * Detects prompt-cache regressions: back-to-back requests to the same model and effort, with nothing in between
+ * that legitimately invalidates the cache, should reuse the previous prompt. Provider-side misses are uncommon
+ * (about 2-4% of Codex requests in September 2026 sessions, with or without Freeflow), so repeated misses in that
+ * situation mean something is rewriting the start of the prompt.
+ * A routing profile that hands off and later resumes on the same model should likewise reuse its own
+ * previous prompt while that prompt's cache entry lives.
+ */
+export class CacheHealth {
+  previous;
+  lanes = new Map();
+  windows = new Map();
+  warned = new Map();
+  /** Compaction, navigation, or reload legitimately invalidates every cached prompt. */
+  noteBreak() {
+    this.previous = undefined;
+    this.lanes.clear();
+  }
+  /** A model or effort change starts a new back-to-back run; a routing lane keeps its own prompt. */
+  noteSwitch() {
+    this.previous = undefined;
+  }
+  reset() {
+    this.previous = undefined;
+    this.lanes.clear();
+    this.windows.clear();
+    this.warned.clear();
+  }
+  /** Returns a warning the first time a model's recent comparable requests cross the miss threshold. */
+  observe(observation) {
+    const key = `${observation.provider ?? "unknown"}/${observation.model ?? "unknown"}/${observation.thinking ?? "unknown"}`;
+    const prompt = observation.input + observation.cacheRead + (observation.cacheWrite ?? 0);
+    const previous = this.previous;
+    this.previous = { key, lane: observation.lane, at: observation.at, prompt };
+    let basis;
+    // Routing profiles see different views of the conversation, so one never reuses another's prompt.
+    if (
+      previous &&
+      previous.key === key &&
+      previous.lane === observation.lane &&
+      observation.at - previous.at <= GAP_MS
+    )
+      basis = previous;
+    else if (observation.lane) {
+      const own = this.lanes.get(`${key}/${observation.lane}`);
+      if (own && observation.at - own.at <= (observation.ttlMs ?? GAP_MS)) basis = own;
+    }
+    if (observation.lane) this.lanes.set(`${key}/${observation.lane}`, { at: observation.at, prompt });
+    if (!basis || basis.prompt < MIN_PROMPT) return;
+    const miss = observation.cacheRead < HIT_SHARE * basis.prompt;
+    const window = [
+      ...(this.windows.get(key) ?? []),
+      { miss, lost: miss ? basis.prompt - observation.cacheRead : 0 },
+    ].slice(-WINDOW);
+    this.windows.set(key, window);
+    const misses = window.filter((entry) => entry.miss).length;
+    if (misses <= 1) this.warned.delete(key);
+    if (misses < MISSES || this.warned.has(key)) return;
+    const lost = window.reduce((sum, entry) => sum + entry.lost, 0);
+    const message = `Freeflow: the prompt cache for ${observation.model} (${observation.thinking}) missed on ${misses} of the last ${window.length} requests that should have reused it (~${tokens(lost)} tokens re-read). Something is rewriting the start of the prompt or placing it out of the provider's reach; check recently changed extensions or Freeflow settings.`;
+    this.warned.set(key, message);
+    return message;
+  }
+  status() {
+    return [...this.warned.values()];
+  }
+}

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

@@ -0,0 +1,58 @@
+import { isChatGPTSignIn } from "../routes.js";
+import { planAnchor } from "./anchor.js";
+import { ANTHROPIC_LIMITS, anthropicLayout, applyAnthropicAnchor } from "./anthropic.js";
+import {
+  OPENAI_RESPONSES_LIMITS,
+  applyResponsesAnchor,
+  responsesLayout,
+  supportsExplicitBreakpoints,
+} from "./openai-responses.js";
+export { planAnchor } from "./anchor.js";
+const responses = {
+  limits: OPENAI_RESPONSES_LIMITS,
+  applies: supportsExplicitBreakpoints,
+  layout: responsesLayout,
+  apply: applyResponsesAnchor,
+};
+// APIs with unbounded prefix lookup need no entry: every prefix they wrote stays reachable. The ChatGPT
+// Codex backend is one: live probes found full prefix reuse after 60 appended message endings, and it
+// rejects prompt_cache_breakpoint, so it must never be adapted. Sign in with ChatGPT on the openai provider
+// reaches the same backend (full reuse after 25 endings, breakpoints rejected) and is skipped in adapt().
+const PROTOCOLS = {
+  "anthropic-messages": { limits: ANTHROPIC_LIMITS, layout: anthropicLayout, apply: applyAnthropicAnchor },
+  "openai-responses": responses,
+  "azure-openai-responses": responses,
+};
+/** Recent requests per session and model; enough to find the requester's own earlier entry. */
+const REMEMBERED = 8;
+export class CacheAnchorAdapter {
+  enabled;
+  lanes = new Map();
+  constructor(enabled = () => true) {
+    this.enabled = enabled;
+  }
+  reset() {
+    this.lanes.clear();
+  }
+  adapt(payload, ctx) {
+    const model = ctx?.model;
+    const protocol = model && PROTOCOLS[model.api];
+    if (!protocol || (protocol.applies && !protocol.applies(model)) || !this.enabled()) return payload;
+    if (isChatGPTSignIn(model, ctx)) return payload;
+    try {
+      const session = ctx.sessionManager?.getSessionId?.() ?? "memory";
+      const lane = JSON.stringify([session, model.provider, model.api, model.id, model.baseUrl ?? ""]);
+      const mapped = protocol.layout(payload);
+      if (!mapped) return payload;
+      const prior = this.lanes.get(lane) ?? [];
+      const plan = planAnchor(prior, mapped.layout, protocol.limits);
+      const sent = plan ? protocol.apply(payload, mapped, plan) : payload;
+      const remembered = sent === payload ? mapped.layout : protocol.layout(sent).layout;
+      this.lanes.set(lane, [remembered, ...prior].slice(0, REMEMBERED));
+      return sent;
+    } catch {
+      // Cache placement is an optimization; never turn it into a failed request.
+      return payload;
+    }
+  }
+}

package/pi-extension/dist/provider-support/cache/keepalive.js

@@ -0,0 +1,210 @@
+import { isChatGPTSignIn } from "../routes.js";
+const responses = {
+  cap: (payload) => ({ ...payload, max_output_tokens: 16 }),
+  retention: (payload) =>
+    payload?.prompt_cache_retention === "24h" || payload?.prompt_cache_options?.ttl ? "long" : undefined,
+};
+const PROTOCOLS = {
+  "anthropic-messages": {
+    cap: (payload) => ({ ...payload, max_tokens: 1 }),
+    retention: (payload) => (JSON.stringify(payload).includes('"ttl":"1h"') ? "long" : "short"),
+    // Budget-based thinking must stay below max_tokens and is part of the cache key, so a one-token replay is
+    // rejected or writes a different entry. Adaptive thinking has no budget. Pi's own warmer skips these too.
+    replayable: (payload) => payload?.thinking?.type !== "enabled",
+  },
+  "openai-responses": responses,
+  "azure-openai-responses": responses,
+};
+/** Continuation is near-certain while a delegated worker runs: the requester resumes on its return. */
+const CONTINUATION = 0.9;
+/** Same threshold as Pi's own warmer: a refresh must be expected to save at least this much. */
+const MINIMUM_SAVINGS = 0.05;
+/** A refresh counts as reuse only when it reads nearly all of the prompt. */
+const REUSE = 0.9;
+const EXPIRY_MARGIN_MS = 10_000;
+/**
+ * Keeps a suspended requester's prompt cache warm while it is certain to resume, such as a Coordinator
+ * whose delegated worker is still running. Pi's own warmer only keeps the latest request warm, which
+ * during a worker run belongs to the worker. Eligibility and economics come from the model's declared
+ * cache lifetime and prices, so any provider that declares them is handled the same way.
+ */
+export class CacheKeepAlive {
+  options;
+  lanes = new Map();
+  holdSource = () => undefined;
+  requester = () => undefined;
+  active;
+  lastStop;
+  now;
+  setTimer;
+  clearTimer;
+  send;
+  constructor(options = {}) {
+    this.options = options;
+    this.now = options.now ?? Date.now;
+    this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms).unref?.());
+    this.clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer));
+    this.send = options.send ?? sendThroughHost;
+  }
+  setHoldSource(source) {
+    this.holdSource = source;
+  }
+  /** Names who is sending the current request, so requesters sharing a model keep separate lanes. */
+  setRequesterSource(source) {
+    this.requester = () => {
+      try {
+        return source();
+      } catch {
+        return undefined;
+      }
+    };
+  }
+  reset() {
+    this.stop("reset");
+    this.lanes.clear();
+  }
+  status() {
+    if (this.active)
+      return `Keeping ${this.lanes.get(this.active.lane)?.model?.id} cache warm while its worker runs · $${this.active.spent.toFixed(3)} spent`;
+    return this.lastStop;
+  }
+  /** Remember the request just sent on its model; a hold keeps the latest one warm. */
+  record(payload, ctx) {
+    const key = laneKey(ctx, undefined, this.requester());
+    // Sign in with ChatGPT rejects max_output_tokens (live, 400), so a replay cannot be capped and is never sent.
+    const protocol = isChatGPTSignIn(ctx.model, ctx) ? undefined : PROTOCOLS[ctx.model?.api];
+    if (!key || !protocol) return;
+    if (protocol.replayable?.(payload) === false) {
+      this.lanes.delete(key);
+      if (this.active?.lane === key) this.stop("this request cannot be replayed with a capped output");
+      return;
+    }
+    const prior = this.lanes.get(key);
+    this.lanes.set(key, { key, model: ctx.model, payload, sentAt: this.now(), prompt: prior?.prompt });
+    if (this.active?.lane === key) this.schedule();
+  }
+  /** Provider-reported usage of the latest request on a model gives the prompt size to price. */
+  observe(ctx, usage, producer) {
+    const lane = this.lanes.get(laneKey(ctx, producer, this.requester()) ?? "");
+    if (lane && usage) lane.prompt = usage.input + usage.cacheRead + usage.cacheWrite;
+  }
+  /** Start or stop holding according to the current run and hold source. */
+  evaluate(ctx) {
+    const hold = this.currentHold(ctx);
+    const key = hold && laneKey(ctx, hold, hold.requester);
+    if (this.active && this.active.lane === key) {
+      this.active.ctx = ctx;
+      return;
+    }
+    this.stop(hold ? "hold changed" : "no suspended requester");
+    if (!key || !this.lanes.has(key)) return;
+    this.active = { lane: key, since: this.now(), spent: 0, ctx };
+    this.schedule();
+  }
+  currentHold(ctx) {
+    if (!(this.options.enabled?.() ?? true) || ctx?.isIdle?.() !== false) return;
+    try {
+      return this.holdSource();
+    } catch {
+      return;
+    }
+  }
+  stop(reason) {
+    if (this.active?.timer !== undefined) this.clearTimer(this.active.timer);
+    if (this.active) this.lastStop = `Cache keep-alive stopped: ${reason}`;
+    this.active = undefined;
+  }
+  ttlMs(lane) {
+    const protocol = PROTOCOLS[lane.model.api];
+    const env = this.options.env ?? process.env;
+    const retention = protocol?.retention(lane.payload) ?? (env.PI_CACHE_RETENTION === "long" ? "long" : "short");
+    const seconds = lane.model.promptCache?.[retention];
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1000 : undefined;
+  }
+  schedule() {
+    const active = this.active;
+    if (!active) return;
+    if (active.timer !== undefined) this.clearTimer(active.timer);
+    active.timer = undefined;
+    const lane = this.lanes.get(active.lane);
+    const ttl = this.ttlMs(lane);
+    if (!ttl || ttl <= EXPIRY_MARGIN_MS) return this.stop("model declares no cache lifetime");
+    const at = lane.sentAt + refreshDelay(ttl);
+    active.timer = this.setTimer(() => this.refresh(active), Math.max(0, at - this.now()));
+  }
+  async refresh(active) {
+    if (this.active !== active) return;
+    active.timer = undefined;
+    const lane = this.lanes.get(active.lane);
+    const hold = this.currentHold(active.ctx);
+    if (!hold || laneKey(active.ctx, hold, hold.requester) !== active.lane)
+      return this.stop("requester resumed or run ended");
+    const now = this.now();
+    // Like Pi's warmer, a refresh later than halfway from its slot to expiry is likely a full rewrite.
+    const ttl = this.ttlMs(lane),
+      delay = refreshDelay(ttl);
+    if (now > lane.sentAt + delay + (ttl - delay) / 2) return this.stop("cache entry already expired");
+    if (now - active.since > (this.options.maxHoldMs ?? 6 * 3_600_000)) return this.stop("hold duration limit");
+    const economics = price(lane);
+    if (!economics) return this.stop("prompt size or prices unknown");
+    if (CONTINUATION * economics.miss - economics.warm < MINIMUM_SAVINGS)
+      return this.stop("refresh would not save money");
+    if (active.spent + economics.warm > (this.options.maxHoldCost ?? 2)) return this.stop("hold spend limit");
+    let usage;
+    try {
+      usage = await this.send(lane.model, PROTOCOLS[lane.model.api].cap(lane.payload), active.ctx);
+    } catch {
+      usage = undefined;
+    }
+    if (this.active !== active) return;
+    if (!usage) return this.stop("refresh failed");
+    const spent = cost(lane.model, usage);
+    active.spent += spent;
+    try {
+      this.options.onRefresh?.({ provider: lane.model.provider, model: lane.model.id, usage, cost: spent });
+    } catch {
+      // Attribution is diagnostic and never changes warming.
+    }
+    if (usage.cacheRead < REUSE * lane.prompt || usage.cacheWrite > (1 - REUSE) * lane.prompt)
+      return this.stop("refresh did not reuse the cache");
+    lane.sentAt = now;
+    this.schedule();
+  }
+}
+/** Pi's refresh point: 90% of the lifetime, keeping at least ten seconds of margin. */
+const refreshDelay = (ttl) => Math.min(ttl * 0.9, ttl - EXPIRY_MARGIN_MS);
+function laneKey(ctx, hold, requester) {
+  const provider = hold?.provider ?? ctx?.model?.provider,
+    model = hold?.modelId ?? ctx?.model?.id;
+  if (!provider || !model) return;
+  return JSON.stringify([ctx?.sessionManager?.getSessionId?.() ?? "memory", provider, model, requester ?? ""]);
+}
+const perToken = (value) => (typeof value === "number" ? value / 1_000_000 : undefined);
+function price(lane) {
+  const c = lane.model.cost ?? {};
+  const read = perToken(c.cacheRead),
+    input = perToken(c.input),
+    output = perToken(c.output) ?? 0;
+  const write = perToken(c.cacheWrite) || input;
+  if (!lane.prompt || read === undefined || write === undefined) return;
+  return { warm: lane.prompt * read + output, miss: Math.max(0, lane.prompt * (write - read)) };
+}
+function cost(model, usage) {
+  const c = model.cost ?? {};
+  return (
+    usage.input * (perToken(c.input) ?? 0) +
+    usage.output * (perToken(c.output) ?? 0) +
+    usage.cacheRead * (perToken(c.cacheRead) ?? 0) +
+    usage.cacheWrite * (perToken(c.cacheWrite) ?? 0)
+  );
+}
+/** Replay through the host's own transport so provider auth and request shaping apply as usual. */
+async function sendThroughHost(model, payload, ctx) {
+  const stream = ctx.modelRegistry.streamSimple(
+    model,
+    { systemPrompt: "", messages: [{ role: "user", content: "cache keep-alive", timestamp: Date.now() }] },
+    { onPayload: () => payload, maxRetries: 0, maxTokens: 1 },
+  );
+  const message = await stream.result();
+  return message.stopReason === "error" || message.stopReason === "aborted" ? undefined : message.usage;
+}

package/pi-extension/dist/provider-support/cache/monitor.js

@@ -0,0 +1,17 @@
+/**
+ * Prompt-cache diagnostics for /freeflow status. The footer only shows current Freeflow settings, so
+ * cache mechanics (keep-alive, context replay, effort baselines) report here instead.
+ */
+export class CacheMonitor {
+  entries = new Map();
+  set(key, text) {
+    if (text) this.entries.set(key, text);
+    else this.entries.delete(key);
+  }
+  lines() {
+    return [...this.entries.values()];
+  }
+  reset() {
+    this.entries.clear();
+  }
+}

package/pi-extension/dist/provider-support/cache/openai-responses.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/**
+ * OpenAI Responses on GPT-5.6+: the implicit breakpoint sits at the latest eligible message, and a
+ * lookup checks it, up to 20 earlier eligible message endings, and the latest explicit breakpoints.
+ * A position here is an eligible message ending: a user message, or the last tool output of a group.
+ */
+export const OPENAI_RESPONSES_LIMITS = { maxBreakpoints: 50, lookback: 20, margin: 5 };
+const OUTPUTS = new Set(["function_call_output", "custom_tool_call_output"]);
+const withoutMarkers = (value) =>
+  JSON.stringify(value, (key, v) => (key === "prompt_cache_breakpoint" ? undefined : v));
+/** Only routes whose documented cache protocol includes explicit breakpoints are adapted. */
+export const supportsExplicitBreakpoints = (model) => model?.compat?.supportsExplicitPromptCacheMode === true;
+export function responsesLayout(payload) {
+  if (!payload || !Array.isArray(payload.input)) return;
+  const chain = [],
+    handles = [],
+    breakpoints = [];
+  let hash = createHash("sha256")
+    .update(withoutMarkers([payload.instructions ?? null, payload.tools ?? null]))
+    .digest("hex");
+  let pending = "";
+  const input = payload.input;
+  input.forEach((item, i) => {
+    pending += withoutMarkers(item);
+    const user = item?.role === "user";
+    const lastOutput = OUTPUTS.has(item?.type) && !OUTPUTS.has(input[i + 1]?.type);
+    if (!user && !lastOutput) return;
+    hash = createHash("sha256").update(hash).update(pending).digest("hex");
+    pending = "";
+    const content = Array.isArray(item.content) ? item.content : undefined;
+    if (content?.some((block) => block?.prompt_cache_breakpoint)) breakpoints.push(chain.length);
+    chain.push(hash);
+    // Breakpoints go on message content blocks; tool outputs have no documented place for one.
+    handles.push(user && content?.length ? { item: i, block: content.length - 1 } : undefined);
+  });
+  // The implicit breakpoint: the latest eligible message ending.
+  if (chain.length && breakpoints.at(-1) !== chain.length - 1) breakpoints.push(chain.length - 1);
+  return { layout: { chain, breakpoints, yieldable: [] }, handles };
+}
+export function applyResponsesAnchor(payload, { handles }, plan) {
+  const handle = handles[plan.add];
+  if (!handle) return payload;
+  const input = [...payload.input];
+  const item = { ...input[handle.item], content: [...input[handle.item].content] };
+  item.content[handle.block] = { ...item.content[handle.block], prompt_cache_breakpoint: { mode: "explicit" } };
+  input[handle.item] = item;
+  return { ...payload, input };
+}

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

@@ -0,0 +1,13 @@
+import { effortHistoryRoute } from "./openai/adapter.js";
+import { isChatGPTSignIn } from "./routes.js";
+/**
+ * Whether changing effort on this route keeps its prompt cache. Freeflow's effort history keeps it on qualified
+ * GPT-6 routes; Pi keeps it natively on Claude models that take per-message effort, where a request-level
+ * effort change would otherwise invalidate every cached message.
+ */
+export function keepsCacheAcrossEffort(model, ctx) {
+  // Sign in with ChatGPT rejects effort-history items, and a plain effort change rereads the context (live, S-006).
+  if (isChatGPTSignIn(model, ctx)) return false;
+  if (effortHistoryRoute(model) !== undefined) return true;
+  return model?.api === "anthropic-messages" && model.compat?.supportsMidConvoEffort === true;
+}

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

@@ -1,4 +1,45 @@
-import { registerAstraSupport } from "./astra/index.js";
-export function registerProviderSupport(pi) {
-  registerAstraSupport(pi);
+import { CacheAnchorAdapter } from "./cache/index.js";
+import { CacheKeepAlive } from "./cache/keepalive.js";
+import { registerOpenAIEffortSupport } from "./openai/index.js";
+export function registerProviderSupport(pi, enabled, monitor) {
+  registerOpenAIEffortSupport(pi, enabled, monitor);
+  const anchor = new CacheAnchorAdapter(enabled);
+  const report = () => monitor?.set("keep-alive", keepAlive.status());
+  const keepAlive = new CacheKeepAlive({
+    enabled,
+    onRefresh: (record) => {
+      try {
+        // Pi's session usage totals are host-owned; keep-alive spend is recorded for Freeflow attribution.
+        pi.appendEntry?.("freeflow-cache-keepalive-v1", { ...record, at: Date.now() });
+      } catch {}
+      report();
+    },
+  });
+  const evaluate = (ctx) => {
+    keepAlive.evaluate(ctx);
+    report();
+  };
+  pi.on("session_shutdown", () => {
+    anchor.reset();
+    keepAlive.reset();
+    report();
+  });
+  pi.on("before_provider_request", (event, ctx) => {
+    const sent = anchor.adapt(event.payload, ctx);
+    try {
+      keepAlive.record(sent, ctx);
+      evaluate(ctx);
+    } catch {
+      // Keep-alive bookkeeping never affects the request being sent.
+    }
+    return sent;
+  });
+  pi.on("message_end", (event, ctx) => {
+    const message = event?.message;
+    if (message?.role === "assistant" && message.provider && message.model)
+      keepAlive.observe(ctx, message.usage, { provider: message.provider, modelId: message.model });
+  });
+  pi.on("agent_start", (_event, ctx) => evaluate(ctx));
+  pi.on("agent_end", (_event, ctx) => evaluate(ctx));
+  return { keepAlive };
 }