@hassangameryt/freeflow 0.7.2 → 0.7.3

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

@@ -0,0 +1,39 @@
+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/sources.ts

@@ -3,6 +3,7 @@ import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import {
   canonical,
   idFor,
+  isWorkerProfile,
   refFor,
   type NativeEntry,
   type State,
@@ -10,6 +11,12 @@ import {
   type Problem,
 } from "../cognitive-routing-v2/types.js";
 
+export interface EvidenceLocator {
+  callRef: string;
+  toolCallId: string;
+  label?: string;
+  truncated?: boolean;
+}
 export interface Source {
   ref: string;
   entry: NativeEntry;
@@ -22,6 +29,15 @@ export interface Source {
   original?: Source;
   reportHandoff?: string;
 }
+export interface NativeToolCall {
+  id: string;
+  name: string;
+  arguments?: unknown;
+}
+export type EvidenceLocatorProvider = (
+  assistant: Source,
+  call: NativeToolCall,
+) => Pick<EvidenceLocator, "label" | "truncated"> | undefined;
 export interface Associated {
   message: any;
   source?: Source;
@@ -45,6 +61,31 @@ interface Exchange {
   results: Map<string, Source[]>;
 }
 const callKey = (id: string, name: string) => JSON.stringify([id, name]);
+const locatorLimit = 160;
+
+function normalizeLabel(value: unknown): Pick<EvidenceLocator, "label" | "truncated"> | undefined {
+  if (typeof value !== "string") return undefined;
+  const clean = value
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!clean) return undefined;
+  if (clean.length <= locatorLimit) return { label: clean, truncated: false };
+  return { label: `${clean.slice(0, locatorLimit - 3)}...`, truncated: true };
+}
+
+function locatorForCall(
+  assistant: Source,
+  call: NativeToolCall,
+  locatorProvider?: EvidenceLocatorProvider,
+): EvidenceLocator | undefined {
+  if (typeof assistant.ref !== "string" || typeof call.id !== "string" || typeof call.name !== "string")
+    return undefined;
+  const locator: EvidenceLocator = { callRef: assistant.ref, toolCallId: call.id };
+  const details = locatorProvider?.(assistant, call);
+  const label = normalizeLabel(details?.label);
+  return label ? { ...locator, ...label, truncated: details?.truncated === true || label.truncated } : locator;
+}
 
 export class Sources {
   readonly byRef = new Map<string, Source>();
@@ -56,7 +97,14 @@ export class Sources {
   private associated?: { messages: readonly any[]; items: Associated[] };
   entries: readonly NativeEntry[] = [];
   private activeIds?: ReadonlySet<string>;
-  constructor(entries: readonly NativeEntry[], state: State, activeIds?: ReadonlySet<string>) {
+  private readonly locatorProvider?: EvidenceLocatorProvider;
+  constructor(
+    entries: readonly NativeEntry[],
+    state: State,
+    activeIds?: ReadonlySet<string>,
+    locatorProvider?: EvidenceLocatorProvider,
+  ) {
+    this.locatorProvider = locatorProvider;
     this.refresh(entries, state, activeIds);
   }
   refresh(entries: readonly NativeEntry[], state: State, activeIds?: ReadonlySet<string>): void {
@@ -89,7 +137,11 @@ export class Sources {
           if (block.type === "text") {
             try {
               const receipt = JSON.parse(block.text);
-              if (receipt.reportSaved && typeof receipt.report === "string" && typeof receipt.handoff === "string")
+              if (
+                ((receipt.reportSaved && typeof receipt.report === "string") ||
+                  (receipt.supplementSaved && typeof receipt.supplement === "string")) &&
+                typeof receipt.handoff === "string"
+              )
                 source.reportHandoff = receipt.handoff;
             } catch {}
           }
@@ -153,7 +205,15 @@ export class Sources {
     this.ambiguous.clear();
     for (const source of this.byRef.values()) source.active = false;
     const used = new Set<string>(),
-      hashes = messages.map(bodyHash),
+      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;
+      }),
       remaining = new Map<string, number>();
     for (const hash of hashes) remaining.set(hash, (remaining.get(hash) ?? 0) + 1);
     const items = messages.map((message, index) => {
@@ -192,13 +252,13 @@ export class Sources {
         code: "source_changed",
         detail: "The captured source changed; reconcile evidence before delivery.",
       };
-    if (source.producer !== "executor")
-      return { ref, code: "source_origin", detail: "Selection requires observed Executor attribution." };
+    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)
       return {
         ref,
         code: "source_unexposed",
-        detail: "The captured body has not been fully exposed to Executor on this ancestry.",
+        detail: "The captured body has not been fully exposed to a worker on this ancestry.",
       };
     return undefined;
   }
@@ -252,6 +312,17 @@ export class Sources {
     }
     return { sources, problems };
   }
+  locator(ref: string): EvidenceLocator | undefined {
+    const source = this.byRef.get(ref);
+    if (!source || source.original || 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: any) => b.type === "toolCall") ?? [];
+    const matches = calls.filter(
+      (call: any) => call.id === source.message.toolCallId && call.name === source.message.toolName,
+    );
+    return matches.length === 1 ? locatorForCall(group.assistant, matches[0], this.locatorProvider) : undefined;
+  }
   ordered(sources: Iterable<Source>): Source[] {
     const ids = new Set([...sources].map((s) => s.ref));
     return this.entries.flatMap((entry) =>