@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/src/runtime/runtime-identity.ts

@@ -1,8 +0,0 @@
-export function isPiFlowHost(hostInfo: unknown): boolean {
-  if (!hostInfo || typeof hostInfo !== "object") return false;
-  const host = hostInfo as {
-    distribution?: { id?: unknown };
-    capabilities?: Record<string, unknown>;
-  };
-  return host.distribution?.id === "piflow" && host.capabilities?.sessionModelStateControl === 1;
-}

package/pi-extension/src/session-sources/events.ts

@@ -1,230 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { activeReadOnlySessionBranch, readOnlySessionSnapshot, ReadOnlySessionError } from "./read-only-session.js";
-import {
-  ROUTING_ENTRY,
-  RoutingError,
-  canonical,
-  eventKey,
-  eventValue,
-  requireCondition as check,
-  type EventData,
-  type NativeEntry,
-  type RoutingEvent,
-} from "../cognitive-routing-v2/types.js";
-import { parseRoutingEvent, reduce, replay } from "../cognitive-routing-v2/state.js";
-
-export interface SessionReader {
-  getSessionId(): string;
-  getSessionFile(): string | undefined;
-  getBranch(): readonly NativeEntry[];
-  getEntries(): readonly NativeEntry[];
-  getLeafId(): string | null;
-}
-export class EventStore {
-  private observed = new Map<string, { value: string; eventId: string; entryId: string }>();
-  private attempted = new Map<string, RoutingEvent>();
-  private fault?: string;
-  private ready = false;
-  private cachedEntries: readonly NativeEntry[] = [];
-  private cachedState = replay([]);
-  constructor(
-    private readonly pi: { appendEntry(type: string, data: unknown): void },
-    readonly reader: SessionReader,
-  ) {}
-  get blocked(): string | undefined {
-    return this.fault ?? (!this.ready ? "acknowledgment_unclassified" : undefined);
-  }
-  state() {
-    const entries = this.reader.getBranch();
-    const prefix =
-      this.cachedEntries.length <= entries.length && this.cachedEntries.every((entry, i) => entry === entries[i]);
-    if (!prefix) {
-      this.cachedState = replay(entries);
-    } else {
-      let state = this.cachedState;
-      for (const entry of entries.slice(this.cachedEntries.length))
-        if (entry.type === "custom" && entry.customType === ROUTING_ENTRY)
-          state = reduce(state, parseRoutingEvent(entry.data));
-      this.cachedState = state;
-    }
-    this.cachedEntries = [...entries];
-    return this.cachedState;
-  }
-  block(reason: string): void {
-    this.fault = reason;
-    this.ready = false;
-  }
-  make(data: EventData, operationId: string = randomUUID(), stepId: string = data.type): RoutingEvent {
-    return parseRoutingEvent({
-      version: 2,
-      eventId: randomUUID(),
-      operationId,
-      stepId,
-      recordedSessionId: this.reader.getSessionId(),
-      data,
-    });
-  }
-  async reconcile(): Promise<void> {
-    const acknowledged = this.ready && !this.fault;
-    this.ready = false;
-    const branch = this.reader.getBranch();
-    const live = branch.filter((e) => e.type === "custom" && e.customType === ROUTING_ENTRY);
-    try {
-      const ids = new Set<string>();
-      let parent: string | null = null;
-      for (const entry of branch) {
-        check(
-          typeof entry.id === "string" && !ids.has(entry.id) && entry.parentId === parent,
-          "invalid_native_ancestry",
-        );
-        ids.add(entry.id);
-        parent = entry.id;
-      }
-      check(parent === this.reader.getLeafId(), "invalid_native_ancestry");
-      if (
-        acknowledged &&
-        live.every((entry) => {
-          const event = parseRoutingEvent(entry.data);
-          const receipt = this.observed.get(eventKey(event));
-          return (
-            receipt?.entryId === entry.id && receipt.eventId === event.eventId && receipt.value === eventValue(event)
-          );
-        })
-      ) {
-        this.ready = true;
-        return;
-      }
-      if (!live.length && !this.attempted.size) {
-        this.observed.clear();
-        this.fault = undefined;
-        this.ready = true;
-        return;
-      }
-      // Pi defers creating a new session file until its first assistant message.
-      // Before that flush boundary, the complete in-memory native session is the
-      // only available source; uncertain appends still require persisted readback.
-      const preFlush =
-        !this.attempted.size &&
-        !this.reader.getEntries().some((entry) => entry.type === "message" && entry.message?.role === "assistant");
-      if (preFlush) {
-        replay(branch);
-        const known = new Map<string, { value: string; eventId: string; entryId: string }>();
-        for (const entry of branch) {
-          if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
-            const event = parseRoutingEvent(entry.data);
-            known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
-          }
-        }
-        this.observed = known;
-        this.fault = undefined;
-        this.ready = true;
-        this.cachedEntries = [];
-        this.cachedState = replay([]);
-        return;
-      }
-      const path = this.reader.getSessionFile();
-      check(path, "persisted_snapshot_unavailable", "Existing or uncertain routing state needs a persisted snapshot.");
-      const snapshot = await readOnlySessionSnapshot(path);
-      check(snapshot.sessionId === this.reader.getSessionId(), "session_identity_changed");
-      const persistedBranch = activeReadOnlySessionBranch(snapshot, this.reader.getLeafId());
-      check(
-        persistedBranch.length === branch.length && persistedBranch.every((e, i) => e.id === branch[i].id),
-        "snapshot_ancestry_mismatch",
-        "Live branch is not the complete persisted ancestry for its claimed leaf.",
-      );
-      replay(persistedBranch as NativeEntry[]);
-      const disk = new Map(persistedBranch.map((e) => [e.id, e]));
-      const known = new Map<string, { value: string; eventId: string; entryId: string }>();
-      // Compare the live selected ancestry, not whichever branch was last written on disk.
-      for (const entry of branch) {
-        const captured = disk.get(entry.id);
-        check(
-          captured && canonical(captured) === canonical(entry),
-          "snapshot_divergence",
-          "Live ancestry is not fully established by the fresh persisted snapshot; reconcile the session before retrying.",
-        );
-        if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
-          const event = parseRoutingEvent(entry.data);
-          known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
-        }
-      }
-      for (const [key, event] of this.attempted)
-        check(
-          known.get(key)?.value === eventValue(event) && known.get(key)?.eventId === event.eventId,
-          "append_acknowledgment_uncertain",
-          "The attempted routing event is not established by persisted readback.",
-        );
-      this.observed = known;
-      this.attempted.clear();
-      this.fault = undefined;
-      this.ready = true;
-      this.cachedEntries = [];
-      this.cachedState = replay([]);
-    } catch (error) {
-      this.block(
-        error instanceof RoutingError
-          ? error.code
-          : error instanceof ReadOnlySessionError
-            ? `${error.code}: ${error.message}`
-            : "snapshot_unavailable",
-      );
-      throw error;
-    }
-  }
-  append(event: RoutingEvent): RoutingEvent {
-    const value = parseRoutingEvent(event),
-      key = eventKey(value),
-      body = eventValue(value);
-    if (this.blocked) throw new RoutingError("acknowledgment_uncertain", this.blocked);
-    const prior = this.state().events.get(key);
-    if (prior) {
-      check(eventValue(prior) === body, "operation_conflict");
-      const occurrence = this.reader
-        .getBranch()
-        .find(
-          (entry) =>
-            entry.type === "custom" &&
-            entry.customType === ROUTING_ENTRY &&
-            (entry.data as any)?.eventId === prior.eventId,
-        );
-      if (
-        this.observed.get(key)?.value !== body ||
-        this.observed.get(key)?.eventId !== prior.eventId ||
-        this.observed.get(key)?.entryId !== occurrence?.id
-      ) {
-        this.block("prior_acknowledgment_unclassified");
-        throw new RoutingError("acknowledgment_uncertain", this.blocked!);
-      }
-      return prior;
-    }
-    // Validate the whole state transition before mutating Pi's session memory.
-    const candidate = reduce(this.state(), value);
-    const baseline = this.cachedEntries;
-    this.attempted.set(key, value);
-    try {
-      this.pi.appendEntry(ROUTING_ENTRY, value);
-      const found = this.reader
-        .getBranch()
-        .find(
-          (e) => e.type === "custom" && e.customType === ROUTING_ENTRY && (e.data as any)?.eventId === value.eventId,
-        );
-      check(found && eventValue(parseRoutingEvent(found.data)) === body, "append_not_observed");
-      this.observed.set(key, { value: body, eventId: value.eventId, entryId: found.id });
-      this.attempted.delete(key);
-      const branch = this.reader.getBranch();
-      const delta = branch.slice(baseline.length).filter((e) => e.type === "custom" && e.customType === ROUTING_ENTRY);
-      if (baseline.every((e, i) => branch[i] === e) && delta.length === 1 && delta[0].id === found!.id) {
-        // Publish the already validated candidate only after acknowledged native append.
-        this.cachedState = candidate;
-        this.cachedEntries = [...branch];
-      }
-      return value;
-    } catch (error) {
-      this.block("append_acknowledgment_uncertain");
-      throw new RoutingError(
-        "acknowledgment_uncertain",
-        error instanceof Error ? error.message : "Pi append/readback did not acknowledge the event.",
-      );
-    }
-  }
-}

package/pi-extension/src/session-sources/provenance.ts

@@ -1,39 +0,0 @@
-import { isWorkerProfile } from "../cognitive-routing-v2/types.js";
-import { isTaskEvidence, textRef, type Sources, type Source } from "./sources.js";
-
-export function annotateSources(
-  messages: any[],
-  renderedSources: Map<any, Source>,
-  full: Set<string>,
-  sources: Sources,
-  instance: string,
-): any[] {
-  const annotated: any[] = [];
-  for (let i = 0; i < messages.length;) {
-    const group = [messages[i++]];
-    while (i < messages.length && messages[i].role === "toolResult") group.push(messages[i++]);
-    const rows = group.flatMap((message) => {
-      const s = renderedSources.get(message);
-      if (!s) return [];
-      const representation = full.has(s.ref) ? "full" : "structural only; omitted result bodies are not evidence";
-      const selection =
-        isWorkerProfile(s.producer) && isTaskEvidence(s) && full.has(s.ref)
-          ? "task evidence; selection checks apply"
-          : "not offered for new evidence selection";
-      return [
-        `${s.ref} | producer: ${s.producer === "common" ? "unknown/common (no observed routing profile)" : s.producer} | ${s.original ? "assistant-text" : s.message.role}${s.message.toolName ? ` | ${s.message.toolName}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}${!s.original && full.has(s.ref) && sources.byRef.has(textRef(s.ref)) ? ` | visible text: ${textRef(s.ref)}` : ""}`,
-      ];
-    });
-    annotated.push(...group);
-    if (rows.length)
-      annotated.push({
-        role: "custom",
-        customType: "freeflow-routing-v2-refs",
-        display: false,
-        content: `Source provenance for the preceding message/exchange:\n${rows.join("\n")}`,
-        details: { routingInstance: instance },
-        timestamp: 0,
-      });
-  }
-  return annotated;
-}

package/pi-extension/src/session-sources/read-only-session.ts

@@ -1,170 +0,0 @@
-import { createHash } from "node:crypto";
-import { open, stat } from "node:fs/promises";
-import { TextDecoder } from "node:util";
-
-export interface ReadOnlySessionEntry {
-  type: string;
-  id: string;
-  parentId?: string | null;
-  [key: string]: unknown;
-}
-export interface ReadOnlySessionSnapshot {
-  path: string;
-  sessionId: string;
-  version: number;
-  hash: string;
-  entries: readonly ReadOnlySessionEntry[];
-}
-export class ReadOnlySessionError extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-    readonly line?: number,
-  ) {
-    super(message);
-    this.name = "ReadOnlySessionError";
-  }
-}
-
-export const SESSION_READ_LIMITS = {
-  maxBytes: 512 * 1024 * 1024,
-  maxEntryBytes: 128 * 1024 * 1024,
-  maxEntries: 250000,
-};
-function decodeEntry(text: string, line: number, seen: Set<string>): ReadOnlySessionEntry {
-  let value: any;
-  try {
-    value = JSON.parse(text);
-  } catch {
-    throw new ReadOnlySessionError("invalid_json", "Incomplete or invalid session JSON.", line);
-  }
-  if (!value || Array.isArray(value) || typeof value !== "object" || typeof value.type !== "string")
-    throw new ReadOnlySessionError("invalid_entry", "Invalid session entry.", line);
-  if (line === 1) {
-    if (
-      value.type !== "session" ||
-      typeof value.id !== "string" ||
-      !value.id ||
-      ![2, 3].includes(value.version) ||
-      typeof value.cwd !== "string"
-    )
-      throw new ReadOnlySessionError("invalid_header", "A supported native session header is required.", line);
-  } else {
-    if (value.type === "session" || typeof value.id !== "string" || !value.id || seen.has(value.id))
-      throw new ReadOnlySessionError("invalid_id", "Missing, duplicate, or misplaced session identity.", line);
-    if (value.parentId !== null && (typeof value.parentId !== "string" || !seen.has(value.parentId)))
-      throw new ReadOnlySessionError("invalid_parent", "Parent is absent or occurs after its child.", line);
-    seen.add(value.id);
-  }
-  return value;
-}
-export function parseReadOnlySessionText(text: string): readonly ReadOnlySessionEntry[] {
-  const lines = text.split("\n");
-  if (lines.at(-1) === "") lines.pop();
-  if (!lines.length || !lines[0]) throw new ReadOnlySessionError("empty", "Session snapshot is empty.");
-  const seen = new Set<string>();
-  return lines.map((line, i) => decodeEntry(line, i + 1, seen));
-}
-export async function readOnlySessionSnapshot(
-  path: string,
-  options: { maxBytes?: number; maxEntryBytes?: number; maxEntries?: number } = {},
-): Promise<ReadOnlySessionSnapshot> {
-  const limits = { ...SESSION_READ_LIMITS, ...options };
-  if (Object.values(limits).some((n) => !Number.isSafeInteger(n) || n <= 0))
-    throw new ReadOnlySessionError("invalid_limit", "Invalid snapshot limit.");
-  let file: Awaited<ReturnType<typeof open>> | undefined;
-  try {
-    file = await open(path, "r");
-    const before = await file.stat({ bigint: true });
-    if (!before.isFile()) throw new ReadOnlySessionError("read_limit", "Session is not a regular file.");
-    if (before.size > BigInt(limits.maxBytes))
-      throw new ReadOnlySessionError(
-        "read_limit",
-        `Session exceeds the supported ${limits.maxBytes} byte snapshot limit.`,
-      );
-    const hash = createHash("sha256"),
-      entries: ReadOnlySessionEntry[] = [],
-      seen = new Set<string>();
-    let total = 0,
-      lineBytes = 0,
-      parts: Buffer[] = [];
-    const append = (part: Buffer) => {
-      lineBytes += part.length;
-      if (lineBytes > limits.maxEntryBytes)
-        throw new ReadOnlySessionError(
-          "entry_limit",
-          `Session entry exceeds ${limits.maxEntryBytes} bytes.`,
-          entries.length + 1,
-        );
-      if (part.length) parts.push(part);
-    };
-    const decode = () => {
-      if (entries.length >= limits.maxEntries)
-        throw new ReadOnlySessionError("entry_count_limit", `Session exceeds ${limits.maxEntries} entries.`);
-      let text: string;
-      try {
-        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(parts, lineBytes));
-      } catch {
-        throw new ReadOnlySessionError("invalid_encoding", "Session is not complete UTF-8.", entries.length + 1);
-      }
-      entries.push(decodeEntry(text, entries.length + 1, seen));
-      parts = [];
-      lineBytes = 0;
-    };
-    for (;;) {
-      const buffer = Buffer.alloc(64 * 1024),
-        { bytesRead } = await file.read(buffer, 0, buffer.length, null);
-      if (!bytesRead) break;
-      total += bytesRead;
-      if (total > limits.maxBytes)
-        throw new ReadOnlySessionError("read_limit", "Session grew beyond the supported snapshot limit.");
-      const bytes = buffer.subarray(0, bytesRead);
-      hash.update(bytes);
-      let start = 0,
-        end: number;
-      while ((end = bytes.indexOf(10, start)) !== -1) {
-        append(bytes.subarray(start, end));
-        decode();
-        start = end + 1;
-      }
-      append(bytes.subarray(start));
-    }
-    if (lineBytes) decode();
-    if (!entries.length) throw new ReadOnlySessionError("empty", "Session snapshot is empty.");
-    const after = await file.stat({ bigint: true }),
-      current = await stat(path, { bigint: true });
-    const signature = (v: typeof before) => [v.dev, v.ino, v.size, v.mtimeNs, v.ctimeNs].join(":");
-    if (
-      signature(before) !== signature(after) ||
-      signature(after) !== signature(current) ||
-      after.size !== BigInt(total)
-    )
-      throw new ReadOnlySessionError("source_changed", "Session changed during snapshot capture.");
-    return { path, sessionId: entries[0].id, version: entries[0].version as number, hash: hash.digest("hex"), entries };
-  } catch (error) {
-    if (error instanceof ReadOnlySessionError) throw error;
-    throw new ReadOnlySessionError("read_failed", error instanceof Error ? error.message : String(error));
-  } finally {
-    await file?.close();
-  }
-}
-
-export function activeReadOnlySessionBranch(
-  snapshot: ReadOnlySessionSnapshot,
-  leafId: string | null,
-): readonly ReadOnlySessionEntry[] {
-  if (leafId === null) return [];
-  const byId = new Map(snapshot.entries.slice(1).map((entry) => [entry.id, entry]));
-  const path: ReadOnlySessionEntry[] = [];
-  const seen = new Set<string>();
-  let cursor: string | null = leafId;
-  while (cursor !== null) {
-    const entry = byId.get(cursor);
-    if (!entry || seen.has(cursor))
-      throw new ReadOnlySessionError("ancestry_unavailable", "Requested native ancestry is unavailable.");
-    seen.add(cursor);
-    path.push(entry);
-    cursor = entry.parentId as string | null;
-  }
-  return path.reverse();
-}