@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/cognitive-routing/session.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { Sources } from "./sources.js";
+import { ViewCache } from "./projection.js";
+import { pairFromProfile } from "./config.js";
+import { initialState } from "./state.js";
+import { RoutingError, isWorkerProfile, requireCondition as check, samePair, workersForDelegation } from "./types.js";
+import { cachedBranch } from "../host/branch.js";
+const STAGED_CONTROL = new Set(["control", "profile-overrides", "delegation-override"]);
+export const ROUTING_RECOVERY_HINT =
+  "Run /freeflow profile auto to reconcile routing, or /freeflow resume to continue saved work.";
+/**
+ * State and identity shared by every part of routing for one bound session: the event journal, the host
+ * context, the current turn, blocking errors, control mode, and the queue that orders control changes.
+ */
+export class RoutingSession {
+  store;
+  ctx;
+  capability;
+  token = randomUUID();
+  turn;
+  /** The packaged routing skill and role references the bootstrap read must cover; undefined when the skill cannot be read. */
+  routingSkill;
+  messages = [];
+  error;
+  projectionError;
+  suppressed = false;
+  operations = Promise.resolve();
+  revision = 0;
+  manualHold;
+  automaticControl = false;
+  sourceCache;
+  /** Rendered view messages reused across requests (see ViewCache); rebuilt after a rebind or ancestry change. */
+  viewCache = new ViewCache();
+  /** Replayed tool results for the current turn, keyed by operation id. */
+  receipts = new Map();
+  /** Recently served inspection pages, keyed by request; at most eight are kept. */
+  pages = new Map();
+  get projectionEnabled() {
+    return this.supported() && this.capability?.projection === true && this.stateData().control === "automatic";
+  }
+  /** Forgets everything derived for the current turn: its context view, sources, replay receipts, and pages. */
+  resetTurn() {
+    this.turn = undefined;
+    this.messages = [];
+    this.sourceCache = undefined;
+    this.viewCache = new ViewCache();
+    this.receipts.clear();
+    this.pages.clear();
+  }
+  subject() {
+    const branch = cachedBranch(this.store?.reader) ?? [];
+    return {
+      token: this.token,
+      revision: this.revision,
+      store: this.store,
+      leafId: branch.at(-1)?.id ?? null,
+      userId: branch.filter((e) => e.message?.role === "user").at(-1)?.id ?? null,
+    };
+  }
+  current(s) {
+    if (s.token !== this.token || s.revision !== this.revision || s.store !== this.store) return false;
+    const branch = cachedBranch(this.store?.reader) ?? [];
+    return (
+      (!s.leafId || branch.some((e) => e.id === s.leafId)) &&
+      (branch.filter((e) => e.message?.role === "user").at(-1)?.id ?? null) === s.userId
+    );
+  }
+  guard(s) {
+    check(
+      this.current(s),
+      "stale_operation",
+      "Routing state changed while the operation was waiting; no further effects applied.",
+    );
+  }
+  taskBasis(state, assignmentId) {
+    return state.resumeBasis.has(assignmentId)
+      ? state.resumeBasis.get(assignmentId)
+      : state.assignments.get(assignmentId)?.basisUserEntryId;
+  }
+  delegation(state = this.stateData()) {
+    return state.delegationOverride ?? this.capability?.delegation ?? "executor";
+  }
+  enabledWorkers(state = this.stateData()) {
+    return workersForDelegation(this.delegation(state));
+  }
+  assignedWorker(state, assignmentId = state.assignmentId) {
+    const assignment = assignmentId ? state.assignments.get(assignmentId) : undefined;
+    const handoff = assignment ? state.handoffs.get(assignment.delegateHandoffId) : undefined;
+    check(
+      handoff?.kind === "delegate" && handoff.assignmentId === assignment?.id && isWorkerProfile(handoff.to),
+      "assignment_worker_missing",
+      "The current assignment has no valid recorded worker.",
+    );
+    return handoff.to;
+  }
+  requiredProfiles(state = this.stateData(), delegation = this.delegation(state)) {
+    const profiles = new Set(["coordinator", ...workersForDelegation(delegation)]);
+    if (state.profile) profiles.add(state.profile);
+    if (this.manualHold) profiles.add(this.manualHold);
+    const assignment = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+    if (assignment?.state === "outstanding" || state.recoveryId) profiles.add(this.assignedWorker(state));
+    const pending = state.pendingId ? state.handoffs.get(state.pendingId) : undefined;
+    if (pending && isWorkerProfile(pending.to)) profiles.add(pending.to);
+    return [...profiles];
+  }
+  retireUnbound(reason) {
+    for (const execution of this.stateData().executions.values()) {
+      if (!execution.assistantEntryId && !execution.interrupted)
+        this.append({ type: "execution-interrupted", executionId: execution.id, reason });
+    }
+    this.turn = undefined;
+  }
+  openTurn() {
+    if (!this.turn || this.turn.opened) return;
+    const t = this.turn;
+    this.append({
+      type: "execution-opened",
+      execution: {
+        id: t.id,
+        profile: t.profile,
+        assignmentId: t.assignmentId,
+        recoveryId: t.recoveryId,
+        basisUserEntryId: t.basisUserEntryId,
+        pair: t.pair,
+        resultEntryIds: [],
+      },
+    });
+    t.opened = true;
+  }
+  stateData() {
+    return this.store?.state() ?? initialState();
+  }
+  sources(state = this.stateData()) {
+    const branch = cachedBranch(this.ctx.sessionManager);
+    const cache = this.sourceCache;
+    // The cached branch is the same array until the leaf moves, so an unchanged branch needs no filtering.
+    if (cache && cache.branch === branch && cache.authors === state.authors.size) return cache.source;
+    const entries = branch.filter((e) =>
+      ["message", "custom_message", "compaction", "branch_summary"].includes(e.type),
+    );
+    if (
+      cache &&
+      cache.authors === state.authors.size &&
+      entries.length === cache.entries.length &&
+      entries.every((e, i) => e === cache.entries[i])
+    ) {
+      cache.branch = branch;
+      return cache.source;
+    }
+    const active = this.ctx.sessionManager.buildContextEntries?.();
+    const activeIds = active ? new Set(active.map((e) => e.id)) : undefined;
+    const source = cache?.source ?? new Sources([], state);
+    source.refresh(entries, state, activeIds);
+    this.sourceCache = { branch, entries, authors: state.authors.size, source };
+    return source;
+  }
+  observed(ctx = this.ctx) {
+    return ctx?.model?.provider && ctx?.model?.id && ctx?.thinkingLevel
+      ? { provider: ctx.model.provider, modelId: ctx.model.id, thinking: ctx.thinkingLevel }
+      : undefined;
+  }
+  supported() {
+    return !!this.capability?.effective && !this.suppressed;
+  }
+  append(data, op, step) {
+    check(this.store, "routing_unavailable");
+    // Control changes made while no run is active affect no request until the next prompt; stage them there.
+    const stage = STAGED_CONTROL.has(data.type) && this.ctx?.isIdle?.() !== false;
+    return this.store.append(this.store.make(data, op, step), stage);
+  }
+  enqueue(action) {
+    const token = this.token;
+    const result = this.operations.then(() => {
+      check(token === this.token, "stale_instance");
+      return action();
+    });
+    this.operations = result.catch(() => {});
+    return result;
+  }
+  mark(error) {
+    if (this.error && error instanceof RoutingError && error.code === "routing_blocked") return;
+    this.error =
+      error instanceof RoutingError
+        ? `${error.code}: ${error.message}`
+        : error instanceof Error
+          ? error.message
+          : String(error);
+  }
+  announced;
+  // Tell the user once per distinct block; routing stays blocked until an explicit control clears it.
+  announceBlock(ctx) {
+    if (!this.error || this.announced === this.error) return;
+    this.announced = this.error;
+    ctx?.ui?.notify?.(`Cognitive Routing blocked: ${this.error}. ${ROUTING_RECOVERY_HINT}`, "warning");
+  }
+  assertAvailable(profile) {
+    check(
+      this.supported() && this.store && !this.error && !this.store.blocked,
+      "routing_unavailable",
+      this.error ?? this.store?.blocked ?? "Routing is inactive.",
+    );
+    const state = this.stateData();
+    check(state.control === "automatic", "manual_control");
+    if (profile) check(state.profile === profile && this.turn?.profile === profile, "wrong_profile");
+    if (state.profile) check(samePair(this.observed(), this.profilePair(state.profile)), "configuration_mismatch");
+  }
+  configuredProfilePair(profile) {
+    const configured = this.capability?.profiles[profile];
+    check(configured, "profile_missing");
+    return pairFromProfile(configured);
+  }
+  profilePair(profile) {
+    return this.stateData().profileOverrides.get(profile) ?? this.configuredProfilePair(profile);
+  }
+  profilePairs(profiles = this.requiredProfiles()) {
+    return Object.fromEntries(profiles.map((profile) => [profile, this.profilePair(profile)]));
+  }
+  workerBasis(state, assignmentId) {
+    const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
+    if (recovery?.state === "reading") return state.handoffs.get(recovery.requestHandoffId)?.basisUserEntryId ?? null;
+    return this.taskBasis(state, assignmentId) ?? null;
+  }
+}

package/pi-extension/dist/{session-sources → cognitive-routing}/sources.js

@@ -1,19 +1,25 @@
 import { createHash } from "node:crypto";
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
-import { canonical, idFor, isWorkerProfile, refFor } from "../cognitive-routing-v2/types.js";
+import { canonical, idFor, isWorkerProfile, refFor, ROUTING_TOOLS, routingToolName } from "./types.js";
+import { isHostEdited, isProjected, projectedEntryId } from "../host/projection-tags.js";
 export const bodyHash = (value) => createHash("sha256").update(canonical(value)).digest("hex");
-export const textRef = (ref) => `${ref}#text`;
-const routingTools = new Set(["freeflow_delegate", "freeflow_return", "freeflow_project", "freeflow_unit"]);
-// Discovery and new selections share this policy. Existing saved selections keep
-// their original delivery semantics; mixed assistant messages offer visible text.
+/** Define a memoized hash so history is hashed only when a consumer needs it. */
+function lazyHash(target, compute) {
+  let value;
+  return Object.defineProperty(target, "hash", {
+    enumerable: true,
+    get: () => (value ??= compute()),
+  });
+}
+const routingTools = new Set(ROUTING_TOOLS);
+// Discovery, new selections, and delivery share this policy: evidence is what tools produced. What a worker
+// says belongs in its report, so its assistant messages are never evidence.
 export function isTaskEvidence(source) {
-  if (source.original) return true;
-  if (source.message.role === "toolResult") return !routingTools.has(source.message.toolName);
-  return (
-    source.message.role === "assistant" &&
-    !source.message.content?.some((b) => b.type === "toolCall" && routingTools.has(b.name)) &&
-    source.message.content?.some((b) => b.type === "text" && b.text?.trim())
-  );
+  return source.message.role === "toolResult" && !routingTools.has(routingToolName(source.message.toolName));
+}
+/** Saved selections keep their delivery, except assistant messages (whole or `#text`), which are never evidence. */
+export function deliveredSelection(sources, ref) {
+  return !ref.endsWith("#text") && sources.byRef.get(ref)?.message.role !== "assistant";
 }
 const callKey = (id, name) => JSON.stringify([id, name]);
 const locatorLimit = 160;
@@ -39,11 +45,15 @@ export class Sources {
   byRef = new Map();
   ambiguous = new Set();
   byBody = new Map();
+  // Sources not yet placed in byBody; the content index is only needed for unprojected association.
+  unindexed = [];
   exchanges = new Map();
   owners = new Map();
   tail;
   associated;
   entries = [];
+  ranks;
+  nonWorker;
   activeIds;
   locatorProvider;
   constructor(entries, state, activeIds, locatorProvider) {
@@ -54,9 +64,12 @@ export class Sources {
     const prefix = this.entries.length <= entries.length && this.entries.every((e, i) => e === entries[i]);
     const start = prefix ? this.entries.length : 0;
     this.associated = undefined;
+    this.ranks = undefined;
+    this.nonWorker = undefined;
     if (!prefix) {
       this.byRef.clear();
       this.byBody.clear();
+      this.unindexed = [];
       this.exchanges.clear();
       this.owners.clear();
       this.tail = undefined;
@@ -67,22 +80,20 @@ export class Sources {
       if (messages.length !== 1 || ["compaction", "branch_summary"].includes(entry.type)) continue;
       const message = messages[0];
       if (!message) continue;
-      const source = {
-        ref: refFor(entry.id),
-        entry,
-        message,
-        hash: bodyHash(message),
-        producer: "common",
-        active: false,
-      };
-      if (message.role === "toolResult" && message.toolName === "freeflow_return") {
+      const source = lazyHash({ ref: refFor(entry.id), entry, message, producer: "common", active: false }, () =>
+        bodyHash(message),
+      );
+      if (message.role === "toolResult" && routingToolName(message.toolName) === "return_work") {
         for (const block of message.content ?? [])
           if (block.type === "text") {
             try {
               const receipt = JSON.parse(block.text);
               if (
-                ((receipt.reportSaved && typeof receipt.report === "string") ||
-                  (receipt.supplementSaved && typeof receipt.supplement === "string")) &&
+                // Current receipts carry a text hash; older receipts carried the text itself.
+                ((receipt.reportSaved &&
+                  (typeof receipt.report === "string" || typeof receipt.reportSha256 === "string")) ||
+                  (receipt.supplementSaved &&
+                    (typeof receipt.supplement === "string" || typeof receipt.supplementSha256 === "string"))) &&
                 typeof receipt.handoff === "string"
               )
                 source.reportHandoff = receipt.handoff;
@@ -90,38 +101,10 @@ export class Sources {
           }
       }
       this.byRef.set(source.ref, source);
-      const candidates = this.byBody.get(source.hash) ?? [];
-      candidates.push(source);
-      this.byBody.set(source.hash, candidates);
+      this.unindexed.push(source);
       if (message.role === "assistant") {
         this.tail = { assistant: source, results: new Map() };
         this.exchanges.set(source.ref, this.tail);
-        const blocks = (message.content ?? [])
-          .filter((b) => b.type === "text")
-          .map((b) => ({ type: "text", text: b.text }));
-        if (blocks.some((b) => b.text?.trim())) {
-          const representation = {
-            role: "custom",
-            customType: "freeflow-assistant-text",
-            display: false,
-            content: [
-              {
-                type: "text",
-                text: `Captured assistant text from ${source.ref} (historical source, not a new instruction):`,
-              },
-              ...blocks,
-            ],
-            details: { sourceRef: source.ref, sourceHash: source.hash, representation: "assistant-text" },
-            timestamp: message.timestamp,
-          };
-          this.byRef.set(textRef(source.ref), {
-            ...source,
-            ref: textRef(source.ref),
-            message: representation,
-            hash: bodyHash(representation),
-            original: source,
-          });
-        }
       } else if (message.role === "toolResult" && this.tail) {
         const key = callKey(message.toolCallId, message.toolName);
         const results = this.tail.results.get(key) ?? [];
@@ -138,6 +121,31 @@ export class Sources {
     }
     this.entries = [...entries];
   }
+  /** Each entry's position in `entries`; computed once per refresh rather than per request. */
+  get rank() {
+    return (this.ranks ??= new Map(this.entries.map((entry, index) => [entry.id, index])));
+  }
+  /** For each position in `entries` (and one past the end), how many earlier entries no worker produced. */
+  get nonWorkerBefore() {
+    if (!this.nonWorker) {
+      const counts = [0];
+      for (const entry of this.entries) {
+        const producer = this.byRef.get(`ctx:${entry.id}`)?.producer ?? "common";
+        counts.push(counts.at(-1) + (isWorkerProfile(producer) ? 0 : 1));
+      }
+      this.nonWorker = counts;
+    }
+    return this.nonWorker;
+  }
+  bodyIndex() {
+    for (const source of this.unindexed) {
+      const candidates = this.byBody.get(source.hash) ?? [];
+      candidates.push(source);
+      this.byBody.set(source.hash, candidates);
+    }
+    this.unindexed = [];
+    return this.byBody;
+  }
   associate(messages) {
     if (
       this.associated &&
@@ -147,38 +155,42 @@ export class Sources {
       return this.associated.items;
     this.ambiguous.clear();
     for (const source of this.byRef.values()) source.active = false;
-    const used = new Set(),
-      hashes = messages.map((message) => {
-        const direct = bodyHash(message);
-        if (this.byBody.has(direct) || message?.role !== "toolResult" || !Array.isArray(message.content)) return direct;
-        const last = message.content.at(-1);
-        if (last?.type !== "text") return direct;
-        const original = bodyHash({ ...message, content: message.content.slice(0, -1) });
-        // Freeflow's stable reference decoration does not change the native evidence body.
-        return this.byBody.get(original)?.some((s) => last.text === `[context-ref: ${s.ref}]`) ? original : direct;
-      }),
+    const projected = messages.some(isProjected);
+    // After an aligned projection, only host-edited messages can match a source by content: the others are
+    // tagged, sourceless (summaries, multi-message entries), or generated after the projection.
+    const contentOnly = (message) => !projected || isHostEdited(message);
+    const direct = messages.map((message) => {
+      const id = projectedEntryId(message);
+      const source = id === undefined ? undefined : this.byRef.get(refFor(id));
+      return source && (!this.activeIds || this.activeIds.has(source.entry.id)) ? source : undefined;
+    });
+    const used = new Set(direct.flatMap((source) => (source ? [source.ref] : []))),
+      hashes = messages.map((message, index) =>
+        direct[index] || !contentOnly(message) ? undefined : bodyHash(message),
+      ),
       remaining = new Map();
-    for (const hash of hashes) remaining.set(hash, (remaining.get(hash) ?? 0) + 1);
+    for (const hash of hashes) if (hash) remaining.set(hash, (remaining.get(hash) ?? 0) + 1);
     const items = messages.map((message, index) => {
+      if (direct[index]) {
+        const source = direct[index];
+        source.active = true;
+        return { message, source };
+      }
+      if (hashes[index] === undefined) return { message };
       const hash = hashes[index],
         count = remaining.get(hash);
       remaining.set(hash, count - 1);
-      const candidates = (this.byBody.get(hash) ?? []).filter(
+      const candidates = (this.bodyIndex().get(hash) ?? []).filter(
         (s) => !used.has(s.ref) && (!this.activeIds || this.activeIds.has(s.entry.id)),
       );
       const exact = candidates.find((s) => s.message === message);
       const source = exact ?? (candidates.length === 1 || candidates.length === count ? candidates[0] : undefined);
       if (!source) {
-        for (const candidate of candidates) {
-          this.ambiguous.add(candidate.ref);
-          this.ambiguous.add(textRef(candidate.ref));
-        }
+        for (const candidate of candidates) this.ambiguous.add(candidate.ref);
         return { message };
       }
       used.add(source.ref);
       source.active = true;
-      const text = this.byRef.get(textRef(source.ref));
-      if (text) text.active = true;
       return { message, source };
     });
     this.associated = { messages: [...messages], items };
@@ -188,8 +200,7 @@ export class Sources {
     const source = this.byRef.get(ref);
     if (!idFor(ref) || !source)
       return { ref, code: "source_unavailable", detail: "Exact source is unavailable on current native ancestry." };
-    const original = source.original ?? source;
-    if (bodyHash(original.message) !== original.hash || bodyHash(source.message) !== source.hash)
+    if (bodyHash(source.message) !== source.hash)
       return {
         ref,
         code: "source_changed",
@@ -197,7 +208,7 @@ export class Sources {
       };
     if (!isWorkerProfile(source.producer))
       return { ref, code: "source_origin", detail: "Selection requires observed worker attribution." };
-    if (state.exposure.get(original.ref) !== original.hash && state.exposure.get(source.ref) !== source.hash)
+    if (state.exposure.get(source.ref) !== source.hash)
       return {
         ref,
         code: "source_unexposed",
@@ -210,17 +221,21 @@ export class Sources {
     if (problem) return problem;
     const source = this.byRef.get(ref);
     if (!isTaskEvidence(source))
-      return {
-        ref,
-        code: "routing_source",
-        detail: this.byRef.has(textRef(ref))
-          ? `Routing control messages are not task evidence. Use ${textRef(ref)} if its visible assistant text is the intended evidence.`
-          : "Routing control receipts are not task evidence; saved communication is delivered separately.",
-      };
+      return source.message.role === "assistant"
+        ? {
+            ref,
+            code: "assistant_message",
+            detail:
+              "Assistant messages are not task evidence; say it in the report and select the tool results it rests on.",
+          }
+        : {
+            ref,
+            code: "routing_source",
+            detail: "Routing control receipts are not task evidence; saved communication is delivered separately.",
+          };
     return undefined;
   }
   exchange(source) {
-    if (source.original) return { sources: [source], problems: [] };
     if (!["assistant", "toolResult"].includes(source.message.role)) return { sources: [source], problems: [] };
     const group = source.message.role === "assistant" ? this.exchanges.get(source.ref) : this.owners.get(source.ref);
     const calls = group?.assistant.message.content?.filter((b) => b.type === "toolCall") ?? [];
@@ -257,7 +272,7 @@ export class Sources {
   }
   locator(ref) {
     const source = this.byRef.get(ref);
-    if (!source || source.original || source.message.role !== "toolResult") return undefined;
+    if (!source || source.message.role !== "toolResult") return undefined;
     const group = this.owners.get(source.ref);
     if (!group) return undefined;
     const calls = group.assistant.message.content?.filter((b) => b.type === "toolCall") ?? [];
@@ -266,12 +281,36 @@ export class Sources {
     );
     return matches.length === 1 ? locatorForCall(group.assistant, matches[0], this.locatorProvider) : undefined;
   }
+  /**
+   * What a tool result's call did, in a few words: its path, command or first short string argument. Coordinator
+   * matches a selected ref to the result in its view by this label (Task 004 S-005); undefined when unknown.
+   */
+  callLabel(ref) {
+    const source = this.byRef.get(ref);
+    if (!source || source.message.role !== "toolResult") return undefined;
+    const call = (this.owners.get(source.ref)?.assistant.message.content ?? []).find(
+      (block) =>
+        block.type === "toolCall" && block.id === source.message.toolCallId && block.name === source.message.toolName,
+    );
+    const args = call?.arguments;
+    if (!args || typeof args !== "object") return undefined;
+    // A path keeps its end, where the file name is; anything else keeps its start.
+    const path = typeof args.path === "string" ? args.path.trim() : "";
+    if (path) return path.length > 100 ? `...${path.slice(-97)}` : path;
+    const chosen =
+      ["command", "pattern", "query", "url"]
+        .map((key) => args[key])
+        .find((value) => typeof value === "string" && value.trim()) ??
+      Object.values(args).find((value) => typeof value === "string" && value.trim() && value.length <= 200);
+    const label = normalizeLabel(chosen)?.label;
+    if (!label) return undefined;
+    return label.length > 100 ? `${label.slice(0, 97)}...` : label;
+  }
   ordered(sources) {
     const ids = new Set([...sources].map((s) => s.ref));
-    return this.entries.flatMap((entry) =>
-      [this.byRef.get(refFor(entry.id)), this.byRef.get(textRef(refFor(entry.id)))].filter(
-        (s) => !!s && ids.has(s.ref),
-      ),
-    );
+    return this.entries.flatMap((entry) => {
+      const source = this.byRef.get(refFor(entry.id));
+      return source && ids.has(source.ref) ? [source] : [];
+    });
   }
 }