@hassangameryt/freeflow 0.4.0 → 0.6.0

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

@@ -0,0 +1,226 @@
+import { FreeflowContextRuntime } from "../freeflow-context/runtime.js";
+import { contextRefForEntry, entryIdFromContextRef } from "../freeflow-context/types.js";
+import { focusedWindow } from "./ranking.js";
+import { searchConversationEntries } from "./search.js";
+import { tokenize, unique } from "./passages.js";
+const MAX_QUERY_CHARACTERS = 500;
+const MAX_QUERY_TERMS = 32;
+const MAX_TOOL_NAMES = 8;
+const MAX_TOOL_NAME_CHARACTERS = 128;
+const MAX_REF_CHARACTERS = 256;
+const MAX_FOCUS_CHARACTERS = 500;
+const MAX_RETRIEVE_REFS = 3;
+const MAX_SOURCE_CHARACTERS = 8_000;
+const MAX_TOTAL_RETRIEVED_CHARACTERS = 24_000;
+const VALID_KINDS = new Set(["user", "assistant", "toolResult", "summary"]);
+function normalizedTerms(value) {
+  return unique(tokenize(value));
+}
+function failure(operation, reason, message) {
+  return {
+    status: "rejected",
+    operation,
+    reason: reason.slice(0, 64),
+    ...(message ? { message: message.slice(0, 500) } : {}),
+  };
+}
+function unavailable(operation, reason = "conversation_history_unavailable") {
+  return { status: "unavailable", operation, reason: reason.slice(0, 64) };
+}
+function sourceMetadata(source) {
+  return {
+    ref: source.ref,
+    kind: source.kind,
+    ...(source.toolNames
+      ? {
+          toolNames: source.toolNames.slice(0, MAX_TOOL_NAMES),
+          ...(source.toolNames.length > MAX_TOOL_NAMES ? { toolNamesTruncated: true } : {}),
+        }
+      : {}),
+    ...(source.isError === undefined ? {} : { isError: source.isError }),
+    timestamp: source.timestamp.slice(0, 64),
+  };
+}
+export class ConversationHistoryRuntime {
+  ctx;
+  freeflowContext;
+  isSourceFullyProjected;
+  snapshot;
+  available = true;
+  unavailableReason;
+  constructor(ctx, isSourceFullyProjected = () => true, freeflowContext = new FreeflowContextRuntime(ctx)) {
+    this.ctx = ctx;
+    this.isSourceFullyProjected = isSourceFullyProjected;
+    this.freeflowContext = freeflowContext;
+  }
+  setContext(ctx) {
+    this.ctx = ctx;
+    this.freeflowContext.setContext(ctx);
+  }
+  capture(contextVirtualizationEnabled = false) {
+    try {
+      this.freeflowContext.setContext(this.ctx);
+      this.snapshot = this.freeflowContext.captureSnapshot({
+        contextVirtualizationEnabled,
+        isSourceFullyProjected: this.isSourceFullyProjected,
+      });
+      this.available = true;
+      this.unavailableReason = undefined;
+      return true;
+    } catch (error) {
+      this.snapshot = undefined;
+      this.available = false;
+      this.unavailableReason = error instanceof Error ? error.message : String(error);
+      return false;
+    }
+  }
+  async search(params, signal) {
+    if (signal?.aborted) return unavailable("search", "conversation_history_search_cancelled");
+    if (!this.available || !this.snapshot) return unavailable("search", this.unavailableReason);
+    const validation = this.validateSearch(params);
+    if (validation) return validation;
+    const query = params.query.trim();
+    const hidden = [...this.snapshot.entries.values()].filter(
+      (entry) =>
+        !this.snapshot?.visibleSourceIds.has(entry.source.source.entryId) &&
+        !this.snapshot?.materializedSourceIds.has(entry.source.source.entryId),
+    );
+    if (hidden.length === 0) {
+      if (this.snapshot.skippedEntries === 0) return failure("search", "no_hidden_conversation_history");
+      return {
+        status: "ok",
+        operation: "search",
+        query,
+        coverage: "partial",
+        skippedEntries: this.snapshot.skippedEntries,
+        returned: 0,
+        truncated: false,
+        hits: [],
+      };
+    }
+    let result;
+    try {
+      result = searchConversationEntries(
+        hidden,
+        {
+          query,
+          kinds: params.kinds,
+          toolNames: Array.isArray(params.toolNames)
+            ? params.toolNames.map((name) => (typeof name === "string" ? name.trim() : ""))
+            : undefined,
+          limit: params.limit,
+        },
+        signal,
+      );
+    } catch (error) {
+      if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) {
+        return unavailable("search", "conversation_history_search_cancelled");
+      }
+      return unavailable("search");
+    }
+    return {
+      status: "ok",
+      operation: "search",
+      query,
+      coverage: this.snapshot.skippedEntries > 0 ? "partial" : "complete",
+      ...(this.snapshot.skippedEntries > 0 ? { skippedEntries: this.snapshot.skippedEntries } : {}),
+      returned: result.returned,
+      truncated: result.truncated,
+      hits: result.hits,
+    };
+  }
+  async retrieve(params, signal) {
+    if (signal?.aborted) return unavailable("retrieve", "conversation_history_retrieve_cancelled");
+    if (!this.available || !this.snapshot) return unavailable("retrieve", this.unavailableReason);
+    const refs = params.refs;
+    if (!Array.isArray(refs) || refs.length < 1 || refs.length > MAX_RETRIEVE_REFS) {
+      return failure("retrieve", "refs_count_invalid");
+    }
+    if (refs.some((ref) => typeof ref !== "string" || ref.length > MAX_REF_CHARACTERS)) {
+      return failure("retrieve", "ref_invalid");
+    }
+    const canonicalRefs = refs.map((ref) => {
+      const entryId = entryIdFromContextRef(ref);
+      return entryId ? contextRefForEntry(entryId) : undefined;
+    });
+    if (canonicalRefs.some((ref) => ref === undefined)) return failure("retrieve", "ref_invalid");
+    const uniqueRefs = canonicalRefs;
+    if (new Set(uniqueRefs).size !== uniqueRefs.length) return failure("retrieve", "duplicate_ref");
+    const focus = params.focus;
+    if (
+      focus !== undefined &&
+      (typeof focus !== "string" || focus.trim().length === 0 || focus.length > MAX_FOCUS_CHARACTERS)
+    ) {
+      return failure("retrieve", "focus_invalid");
+    }
+    const items = [];
+    let total = 0;
+    for (const ref of uniqueRefs) {
+      if (signal?.aborted) return unavailable("retrieve", "conversation_history_retrieve_cancelled");
+      const entryId = entryIdFromContextRef(ref);
+      const source = entryId ? this.snapshot.entries.get(contextRefForEntry(entryId)) : undefined;
+      if (!source) return failure("retrieve", "reference_unresolved");
+      if (this.snapshot.visibleSourceIds.has(entryId) || this.snapshot.materializedSourceIds.has(entryId)) {
+        return failure("retrieve", "source_visible");
+      }
+      const sourceCharacters = source.text.length;
+      let content = source.text;
+      let completeness = "complete";
+      if (sourceCharacters > MAX_SOURCE_CHARACTERS) {
+        if (typeof focus !== "string") return failure("retrieve", "focus_required_for_oversized_source");
+        const focused = focusedWindow(source.text, focus.trim(), MAX_SOURCE_CHARACTERS);
+        if (focused === undefined) return failure("retrieve", "focus_no_match");
+        content = focused;
+        completeness = "partial";
+      }
+      if (total + content.length > MAX_TOTAL_RETRIEVED_CHARACTERS)
+        return failure("retrieve", "retrieval_budget_exceeded");
+      total += content.length;
+      items.push({
+        ...sourceMetadata(source),
+        content,
+        completeness,
+        sourceCharacters,
+        returnedCharacters: content.length,
+      });
+    }
+    return {
+      status: "ok",
+      operation: "retrieve",
+      ...(typeof focus === "string" ? { focus: focus.trim() } : {}),
+      items,
+    };
+  }
+  validateSearch(params) {
+    if (typeof params.query !== "string" || params.query.trim().length === 0)
+      return failure("search", "query_required");
+    if (params.query.length > MAX_QUERY_CHARACTERS) return failure("search", "query_too_long");
+    if (normalizedTerms(params.query).length > MAX_QUERY_TERMS) return failure("search", "query_terms_too_many");
+    if (params.kinds !== undefined) {
+      if (!Array.isArray(params.kinds) || params.kinds.length < 1 || params.kinds.length > 4)
+        return failure("search", "kinds_invalid");
+      if (
+        new Set(params.kinds).size !== params.kinds.length ||
+        params.kinds.some((kind) => typeof kind !== "string" || !VALID_KINDS.has(kind))
+      ) {
+        return failure("search", "kinds_invalid");
+      }
+    }
+    if (params.toolNames !== undefined) {
+      if (!Array.isArray(params.toolNames) || params.toolNames.length < 1 || params.toolNames.length > MAX_TOOL_NAMES)
+        return failure("search", "tool_names_invalid");
+      const normalizedNames = params.toolNames.map((name) => (typeof name === "string" ? name.trim() : ""));
+      if (
+        params.toolNames.some((name) => typeof name !== "string") ||
+        new Set(normalizedNames.map((name) => name.toLocaleLowerCase())).size !== normalizedNames.length ||
+        normalizedNames.some((name) => name.length === 0 || name.length > MAX_TOOL_NAME_CHARACTERS)
+      ) {
+        return failure("search", "tool_names_invalid");
+      }
+    }
+    if (params.limit !== undefined && (!Number.isInteger(params.limit) || params.limit < 1 || params.limit > 20)) {
+      return failure("search", "limit_invalid");
+    }
+    return undefined;
+  }
+}

package/pi-extension/dist/conversation-history/search.js

@@ -0,0 +1,56 @@
+import { normalizeText, snippet, throwIfAborted, tokenize, unique } from "./passages.js";
+import { rankMatchingPassages } from "./ranking.js";
+const MAX_DISPLAYED_TOOL_NAMES = 8;
+function matchesFilters(entry, options) {
+  if (options.kinds && !options.kinds.includes(entry.kind)) return false;
+  if (options.toolNames) {
+    const names = new Set((entry.toolNames ?? []).map((name) => name.toLocaleLowerCase()));
+    if (!options.toolNames.some((name) => names.has(name.toLocaleLowerCase()))) return false;
+  }
+  return true;
+}
+export function searchConversationEntries(entries, options, signal) {
+  throwIfAborted(signal);
+  const normalizedQuery = normalizeText(options.query);
+  const terms = unique(tokenize(options.query));
+  const limit = Math.min(20, Math.max(1, Math.trunc(options.limit ?? 8)));
+  if (!normalizedQuery || terms.length === 0) return { returned: 0, truncated: false, hits: [] };
+  const candidates = entries.filter((entry) => matchesFilters(entry, options));
+  const rankedPassages = rankMatchingPassages(candidates, options.query, signal);
+  const byEntry = new Map();
+  for (const passage of rankedPassages) {
+    throwIfAborted(signal);
+    if (!byEntry.has(passage.entry.ref)) byEntry.set(passage.entry.ref, passage);
+  }
+  const ranked = [...byEntry.values()];
+  const hits = ranked.slice(0, limit).map((passage) => {
+    const matchType = passage.exactPhrase
+      ? "exact-phrase"
+      : passage.matchedTerms.length === terms.length
+        ? "all-terms"
+        : "partial-terms";
+    return {
+      ref: passage.entry.ref,
+      kind: passage.entry.kind,
+      ...(passage.entry.toolNames
+        ? {
+            toolNames: passage.entry.toolNames.slice(0, MAX_DISPLAYED_TOOL_NAMES),
+            ...(passage.entry.toolNames.length > MAX_DISPLAYED_TOOL_NAMES ? { toolNamesTruncated: true } : {}),
+          }
+        : {}),
+      ...(passage.entry.isError === undefined ? {} : { isError: passage.entry.isError }),
+      timestamp: passage.entry.timestamp.slice(0, 64),
+      snippet: snippet(passage.passage.text, normalizedQuery, terms),
+      match: {
+        type: matchType,
+        matchedTerms: passage.matchedTerms,
+        queryTermCount: terms.length,
+      },
+    };
+  });
+  return {
+    returned: hits.length,
+    truncated: ranked.length > limit,
+    hits,
+  };
+}

package/pi-extension/dist/conversation-history/types.js

@@ -0,0 +1 @@
+export {};

package/pi-extension/dist/freeflow-context/resolver.js

@@ -0,0 +1,120 @@
+import { entryIdFromContextRef } from "./types.js";
+export function isToolResultEntry(entry) {
+  return entry?.type === "message" && entry?.message?.role === "toolResult";
+}
+export class ContextSourceResolver {
+  ctx;
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  setContext(ctx) {
+    this.ctx = ctx;
+  }
+  sessionId() {
+    const value = this.ctx?.sessionManager?.getSessionId?.() ?? this.ctx?.sessionId ?? this.ctx?.cwd ?? "current";
+    return String(value);
+  }
+  branchLeafId() {
+    try {
+      return this.ctx?.sessionManager?.getLeafId?.();
+    } catch {
+      return undefined;
+    }
+  }
+  branchEntries() {
+    const entries = this.ctx?.sessionManager?.getBranch?.() ?? this.ctx?.sessionManager?.getEntries?.() ?? [];
+    return Array.isArray(entries) ? entries : [];
+  }
+  activeContextEntries() {
+    try {
+      const entries = this.ctx?.sessionManager?.buildContextEntries?.() ?? this.branchEntries();
+      return Array.isArray(entries) ? entries : [];
+    } catch {
+      return this.branchEntries();
+    }
+  }
+  activeContextEntriesStrict() {
+    const manager = this.ctx?.sessionManager;
+    if (typeof manager?.buildContextEntries !== "function") return this.branchEntries();
+    const entries = manager.buildContextEntries();
+    if (!Array.isArray(entries)) throw new Error("active_context_entries_unavailable");
+    return entries;
+  }
+  resolvedEntriesById(entries = this.branchEntries(), sessionId = this.sessionId()) {
+    const result = new Map();
+    for (const entry of entries) {
+      const resolved = this.entryFromSessionEntry(entry, sessionId);
+      if (resolved) result.set(resolved.source.entryId, resolved);
+    }
+    return result;
+  }
+  toolResultSources(entries = this.branchEntries(), sessionId = this.sessionId()) {
+    const grouped = new Map();
+    for (const entry of entries) {
+      const source = this.sourceFromEntry(entry, sessionId);
+      if (!source) continue;
+      const group = grouped.get(source.source.toolCallId) ?? [];
+      group.push(source);
+      grouped.set(source.source.toolCallId, group);
+    }
+    const unique = new Map();
+    for (const [toolCallId, sources] of grouped) {
+      if (sources.length === 1) unique.set(toolCallId, sources[0]);
+    }
+    return unique;
+  }
+  sourcesByEntryId(entries = this.branchEntries(), sessionId = this.sessionId()) {
+    const result = new Map();
+    for (const source of this.toolResultSources(entries, sessionId).values()) {
+      result.set(source.source.entryId, source);
+    }
+    return result;
+  }
+  activeToolResultIds() {
+    const ids = new Set();
+    for (const entry of this.activeContextEntries()) {
+      if (isToolResultEntry(entry) && typeof entry.id === "string") ids.add(entry.id);
+    }
+    return ids;
+  }
+  resolveCurrent(ref) {
+    const entryId = entryIdFromContextRef(ref);
+    if (!entryId) return undefined;
+    const entry = this.branchEntries().find((candidate) => candidate?.id === entryId);
+    return entry ? this.entryFromSessionEntry(entry, this.sessionId()) : undefined;
+  }
+  sourceFromEntry(entry, sessionId) {
+    const resolved = this.entryFromSessionEntry(entry, sessionId);
+    return resolved?.kind === "toolResult" ? resolved : undefined;
+  }
+  entryFromSessionEntry(entry, sessionId) {
+    if (!entry || typeof entry.id !== "string") return undefined;
+    const kind = this.kindForEntry(entry);
+    if (!kind) return undefined;
+    const message = entry.message;
+    const toolCallId =
+      kind === "toolResult" && typeof message?.toolCallId === "string" ? message.toolCallId : undefined;
+    return {
+      kind,
+      entry,
+      ...(message ? { message } : {}),
+      source: {
+        sessionId,
+        entryId: entry.id,
+        ...(toolCallId ? { toolCallId } : {}),
+        ...(typeof message?.toolName === "string" ? { toolName: message.toolName } : {}),
+      },
+    };
+  }
+  kindForEntry(entry) {
+    if (entry.type === "custom") return "custom";
+    if (entry.type === "compaction" || entry.type === "branch_summary") return "summary";
+    if (entry.type !== "message") return undefined;
+    if (entry.message?.role === "user") return "user";
+    if (entry.message?.role === "assistant") return "assistant";
+    if (entry.message?.role === "toolResult") return "toolResult";
+    if (entry.message?.role === "custom") return "custom";
+    if (entry.message?.role === "branchSummary" || entry.message?.role === "compactionSummary") return "summary";
+    return undefined;
+  }
+}

package/pi-extension/dist/freeflow-context/runtime.js

@@ -0,0 +1,80 @@
+import { buildContextVisibility } from "./visibility.js";
+import { ContextSourceResolver } from "./resolver.js";
+import { projectContextSource } from "./source-projector.js";
+export class FreeflowContextRuntime {
+  resolver;
+  ctx;
+  generation = 0;
+  latestRequestSnapshot;
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.resolver = new ContextSourceResolver(ctx);
+  }
+  setContext(ctx) {
+    this.ctx = ctx;
+    this.resolver.setContext(ctx);
+  }
+  sessionId() {
+    return this.resolver.sessionId();
+  }
+  branchLeafId() {
+    return this.resolver.branchLeafId();
+  }
+  branchEntries() {
+    return this.resolver.branchEntries();
+  }
+  resolveCurrent(ref) {
+    return this.resolver.resolveCurrent(ref);
+  }
+  recordRequest(refs) {
+    this.generation += 1;
+    this.latestRequestSnapshot = {
+      generation: this.generation,
+      sessionId: this.sessionId(),
+      branchLeafId: this.branchLeafId(),
+      refs,
+    };
+    return this.latestRequestSnapshot;
+  }
+  clearRequest() {
+    this.latestRequestSnapshot = undefined;
+  }
+  latestRequest() {
+    return this.latestRequestSnapshot;
+  }
+  captureSnapshot(options) {
+    const branchEntries = this.resolver.branchEntries();
+    const activeEntries = this.resolver.activeContextEntriesStrict();
+    const sessionId = this.sessionId();
+    const resolvedByEntryId = this.resolver.resolvedEntriesById(branchEntries, sessionId);
+    const visibility = buildContextVisibility(activeEntries, resolvedByEntryId, options);
+    const entries = new Map();
+    let skippedEntries = 0;
+    for (let position = 0; position < branchEntries.length; position += 1) {
+      const entry = branchEntries[position];
+      if (typeof entry?.id !== "string") continue;
+      const resolved = resolvedByEntryId.get(entry.id);
+      if (!resolved) continue;
+      const outcome = projectContextSource({ ...resolved, entry: { ...resolved.entry, position } });
+      if (outcome.status === "eligible") entries.set(outcome.source.ref, outcome.source);
+      else if (
+        outcome.status === "invalid" &&
+        !visibility.visibleSourceIds.has(entry.id) &&
+        !visibility.materializedSourceIds.has(entry.id)
+      ) {
+        skippedEntries += 1;
+      }
+    }
+    const generation = this.latestRequestSnapshot?.generation ?? ++this.generation;
+    return {
+      generation,
+      sessionId,
+      branchLeafId: this.branchLeafId(),
+      visibleEntryIds: visibility.visibleEntryIds,
+      visibleSourceIds: visibility.visibleSourceIds,
+      materializedSourceIds: visibility.materializedSourceIds,
+      skippedEntries,
+      entries,
+    };
+  }
+}

package/pi-extension/dist/freeflow-context/source-projector.js

@@ -0,0 +1,95 @@
+import { isFreeflowContextToolName } from "./types.js";
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const value = block;
+    if (value.type === "text" && typeof value.text === "string") {
+      parts.push(value.text);
+    } else if (value.type === "image" && typeof value.mimeType === "string") {
+      parts.push(`[image:${value.mimeType}]`);
+    }
+  }
+  return parts.join("\n");
+}
+function timestampFor(source) {
+  const value = source.entry?.timestamp ?? source.message?.timestamp;
+  const timestamp = typeof value === "string" || typeof value === "number" ? new Date(value) : new Date(0);
+  return Number.isNaN(timestamp.getTime()) ? new Date(0).toISOString() : timestamp.toISOString();
+}
+function invalid(reason) {
+  return { status: "invalid", reason };
+}
+function toolCallParts(content) {
+  if (!Array.isArray(content)) return { status: "ok", text: "", names: [] };
+  const parts = [];
+  const names = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const value = block;
+    if (value.type !== "toolCall" && value.type !== "tool_use") continue;
+    const name = typeof value.name === "string" ? value.name.trim() : "";
+    if (!name) return { status: "invalid", reason: "tool_name_missing" };
+    if (name === "freeflow_context") continue;
+    if (name.length > 128) return { status: "invalid", reason: "tool_name_too_long" };
+    const args = value.arguments ?? value.input;
+    let renderedArgs = "";
+    if (args !== undefined) {
+      try {
+        const serialized = JSON.stringify(args);
+        if (serialized === undefined) return { status: "invalid", reason: "tool_arguments_unserializable" };
+        renderedArgs = `\n${serialized}`;
+      } catch {
+        return { status: "invalid", reason: "tool_arguments_unserializable" };
+      }
+    }
+    names.push(name);
+    parts.push(`Tool call: ${name}${renderedArgs}`);
+  }
+  return { status: "ok", text: parts.join("\n"), names };
+}
+export function projectContextSource(source) {
+  if (!source.entry || !source.source.entryId) return invalid("source_id_missing");
+  if (source.source.entryId.length > 256) return invalid("source_id_too_long");
+  if (source.kind === "custom") return { status: "excluded", reason: "custom_source" };
+  const message = source.message;
+  let text = "";
+  let toolNames = [];
+  let isError;
+  if (source.kind === "summary") {
+    text = typeof source.entry.summary === "string" ? source.entry.summary : textFromContent(message?.content);
+  } else if (source.kind === "toolResult") {
+    if (isFreeflowContextToolName(message?.toolName)) {
+      return { status: "excluded", reason: "freeflow_context_source" };
+    }
+    if (typeof message?.toolName !== "string" || message.toolName.trim().length === 0) {
+      return invalid("tool_name_missing");
+    }
+    const toolName = message.toolName.trim();
+    if (toolName.length > 128) return invalid("tool_name_too_long");
+    text = textFromContent(message.content);
+    toolNames = [toolName];
+    if (typeof message.isError === "boolean") isError = message.isError;
+  } else if (source.kind === "assistant") {
+    const calls = toolCallParts(message?.content);
+    if (calls.status === "invalid") return invalid(calls.reason);
+    text = [textFromContent(message?.content), calls.text].filter(Boolean).join("\n");
+    toolNames = calls.names;
+  } else if (source.kind === "user") {
+    text = textFromContent(message?.content);
+  }
+  if (!text.trim()) return { status: "excluded", reason: "empty_source" };
+  const projected = {
+    ref: `ctx:${source.source.entryId}`,
+    kind: source.kind,
+    text,
+    timestamp: timestampFor(source).slice(0, 64),
+    position: typeof source.entry.position === "number" ? source.entry.position : 0,
+    ...(toolNames.length > 0 ? { toolNames: [...new Set(toolNames)] } : {}),
+    ...(isError === undefined ? {} : { isError }),
+    source,
+  };
+  return { status: "eligible", source: projected };
+}