@hassangameryt/freeflow 0.7.2 → 0.7.3

package/pi-extension/src/cognitive-routing-v2/projection.ts

@@ -1,9 +1,11 @@
+import { annotateSources } from "../session-sources/provenance.js";
 import { randomUUID } from "node:crypto";
-import { Sources, textRef, isTaskEvidence, type Source } from "../session-sources/sources.js";
+import { Sources, textRef, type Source } from "../session-sources/sources.js";
 import {
   canonical,
   emptySelection,
   idFor,
+  isWorkerProfile,
   requireCondition as check,
   type Pair,
   type Problem,
@@ -136,7 +138,7 @@ export function prepareView(options: {
     if (!item.source) continue;
     if (
       !selective ||
-      item.source.producer !== "executor" ||
+      !isWorkerProfile(item.source.producer) ||
       admitted.has(item.source.ref) ||
       (item.source.reportHandoff && state.handoffs.has(item.source.reportHandoff))
     )
@@ -189,7 +191,7 @@ export function prepareView(options: {
     if (full.has(source.ref) || source.message.role !== "toolResult") return message;
     return {
       ...structuredClone(source.message),
-      content: [{ type: "text", text: "[Executor result omitted from this view]" }],
+      content: [{ type: "text", text: "[Worker result omitted from this view]" }],
       details: undefined,
     };
   };
@@ -226,39 +228,28 @@ export function prepareView(options: {
   }
   while (cursor < historical.length) emit(historical[cursor++]);
   const fullSources = [...full.values()];
-  // Stable provenance belongs with every represented occurrence, not a rolling
-  // catalog. Insert before whole exchanges, never between native calls/results.
-  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 =
-        s.producer === "executor" && 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)}` : ""}`,
-      ];
-    });
-    if (rows.length)
-      annotated.push({
-        role: "custom",
-        customType: "freeflow-routing-v2-refs",
-        display: false,
-        content: `Source provenance for the following message/exchange:\n${rows.join("\n")}`,
-        details: { routingInstance: options.instance },
-        timestamp: 0,
-      });
-    annotated.push(...group);
-  }
-  messages = annotated;
+  messages = annotateSources(messages, renderedSources, new Set(full.keys()), sources, options.instance);
   // Restore exact current communication only when its accepted occurrence is absent.
   const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
-  const report = handoff?.kind === "return" ? handoff : undefined;
+  const baseReport = assessment
+    ? state.handoffs.get(assessment.handoffId)
+    : handoff?.kind === "return"
+      ? handoff
+      : undefined;
+  const recovery = state.recoveryId
+    ? state.recoveries.get(state.recoveryId)
+    : [...state.recoveries.values()]
+        .reverse()
+        .find(
+          (candidate) => candidate.assessmentHandoffId === assessment?.handoffId && candidate.state === "completed",
+        );
+  const recoveryRequest = recovery ? state.handoffs.get(recovery.requestHandoffId) : undefined;
+  const supplement =
+    handoff?.kind === "recovery-return"
+      ? handoff
+      : recovery?.supplementHandoffId
+        ? state.handoffs.get(recovery.supplementHandoffId)
+        : undefined;
   const hasCommunication = (h: any, field: string, value: string, metadata: Record<string, any> = {}) =>
     messages.some((m) => {
       const matches = (payload: any) =>
@@ -290,22 +281,41 @@ export function prepareView(options: {
     if (accepted && !hasCommunication(accepted, "contract", a.contract))
       restore("Current exact assignment", a.id, a.contract);
   }
-  if (report) {
-    const metadata = { outcome: report.outcome, limitations: report.limitations };
-    const hasBody = hasCommunication(report, "report", report.text);
+  if (baseReport) {
+    const metadata = { outcome: baseReport.outcome, limitations: baseReport.limitations };
+    const hasBody = hasCommunication(baseReport, "report", baseReport.text);
     // Tool arguments establish accepted content but do not carry harness-assigned
     // revision/lineage. Old receipts and partially retained calls need metadata too.
-    const complete = hasCommunication(report, "report", report.text, {
+    const complete = hasCommunication(baseReport, "report", baseReport.text, {
       ...metadata,
-      reportRevision: report.reportRevision,
-      assignmentRef: `assignment:${report.assignmentId}`,
-      reportRef: `report:${report.id}:${report.reportRevision}`,
+      reportRevision: baseReport.reportRevision,
+      assignmentRef: `assignment:${baseReport.assignmentId}`,
+      reportRef: `report:${baseReport.id}:${baseReport.reportRevision}`,
     });
     if (!complete)
       restore(
         "Saved report",
-        report.id,
-        `Producer: executor\nAssignment: assignment:${report.assignmentId}\nReport ref: report:${report.id}:${report.reportRevision}\nRevision: ${report.reportRevision}\nOutcome: ${report.outcome}\nLimitations: ${JSON.stringify(report.limitations)}${hasBody ? "\nReport text is present in its accepted native occurrence above." : `\nReport:\n${report.text}`}`,
+        baseReport.id,
+        `Producer: ${baseReport.from}\nAssignment: assignment:${baseReport.assignmentId}\nReport ref: report:${baseReport.id}:${baseReport.reportRevision}\nRevision: ${baseReport.reportRevision}\nOutcome: ${baseReport.outcome}\nLimitations: ${JSON.stringify(baseReport.limitations)}${hasBody ? "\nReport text is present in its accepted native occurrence above." : `\nReport:\n${baseReport.text}`}`,
+      );
+  }
+  if (recovery && recoveryRequest && !hasCommunication(recoveryRequest, "request", recovery.request))
+    restore(
+      "Recovery request",
+      recovery.id,
+      `Assignment: assignment:${recovery.assignmentId}\nParent report: report:${recovery.assessmentHandoffId}:${recovery.baseReportRevision}\nAllowed paths: ${JSON.stringify(recovery.paths)}\nRequest:\n${recovery.request}`,
+    );
+  if (recovery && supplement) {
+    const hasBody = hasCommunication(supplement, "report", supplement.text);
+    const complete = hasCommunication(supplement, "report", supplement.text, {
+      outcome: supplement.outcome,
+      limitations: supplement.limitations,
+    });
+    if (!complete)
+      restore(
+        "Recovery supplement",
+        recovery.id,
+        `Assignment: assignment:${recovery.assignmentId}\nParent report: report:${recovery.assessmentHandoffId}:${recovery.baseReportRevision}\nSupplement revision: ${supplement.reportRevision}\nOutcome: ${supplement.outcome}\nLimitations: ${JSON.stringify(supplement.limitations)}${hasBody ? "\nSupplement text is present in its accepted native occurrence above." : `\nSupplement:\n${supplement.text}`}`,
       );
   }
   messages.push(options.runtimeMessage);

package/pi-extension/src/cognitive-routing-v2/render.ts

@@ -12,10 +12,20 @@ const value = (v: unknown) => (typeof v === "string" ? v : v === undefined ? ""
 const text = (v: unknown) => (typeof v === "string" ? v : "");
 const count = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`;
 const capital = (v: string) => (v ? v[0].toUpperCase() + v.slice(1) : "");
+const locatorText = (locator: any) => {
+  if (!locator) return "";
+  const identity = `${locator.toolCallId ?? "unknown call"} (${locator.callRef ?? "unknown source"})`;
+  return locator.label ? `${locator.label}${locator.truncated ? " [truncated]" : ""} · ${identity}` : identity;
+};
 
 function title(name: string, operation?: string): string {
-  if (name === "freeflow_delegate") return operation === "replace" ? "Replace assignment" : "Delegate to Executor";
-  if (name === "freeflow_return") return operation === "retry" ? "Retry return" : "Return to Coordinator";
+  if (name === "freeflow_delegate") return operation === "replace" ? "Replace assignment" : "Delegate assignment";
+  if (name === "freeflow_return")
+    return operation === "retry"
+      ? "Retry return"
+      : operation === "supplement"
+        ? "Return recovery supplement"
+        : "Return to Coordinator";
   if (name === "freeflow_project")
     return (
       (
@@ -34,6 +44,8 @@ function title(name: string, operation?: string): string {
           inspect: "Inspect routing",
           close: "Close unit",
           assess: "Resume assessment",
+          recover: "Recover assessment evidence",
+          "cancel-recovery": "Cancel evidence recovery",
           status: "Routing status",
           history: "Routing history",
         } as Record<string, string>
@@ -47,6 +59,7 @@ function draft(name: string, args: any, expanded: boolean): string {
   if (name === "freeflow_delegate") sections.push(text(args.contract));
   if (name === "freeflow_return") sections.push(text(args.report));
   if (name === "freeflow_unit" && args.operation === "close") sections.push(text(args.assessment));
+  if (name === "freeflow_unit" && args.operation === "recover") sections.push(text(args.request));
   // Metadata can arrive before the main text and otherwise occupy the entire
   // trailing preview forever. Keep the live prose moving; expansion keeps all fields.
   if (!expanded && sections.length) return sections.filter(Boolean).join("\n\n");
@@ -71,7 +84,9 @@ export function renderRoutingCall(name: string, args: any = {}, context: RenderC
     name === "freeflow_delegate"
       ? "assignment"
       : name === "freeflow_return"
-        ? "report"
+        ? args.operation === "supplement"
+          ? "supplement"
+          : "report"
         : name === "freeflow_unit" && args.operation === "close"
           ? "assessment"
           : undefined;
@@ -98,8 +113,8 @@ function summary(receipt: any, name: string, args: any): string {
   const issue = problems.length
     ? `${count(problems.length, "evidence issue")} ${problems.length === 1 ? "needs" : "need"} correction`
     : "Evidence needs correction";
-  if (receipt.reportSaved)
-    return `${operation === "retry" ? "Saved report retained" : "Report saved"}${receipt.ready === false ? ` · ${issue}` : ""}`;
+  if (receipt.reportSaved || receipt.supplementSaved)
+    return `${operation === "retry" ? (receipt.supplementSaved ? "Saved supplement retained" : "Saved report retained") : receipt.supplementSaved ? "Recovery supplement saved" : "Report saved"}${receipt.ready === false ? ` · ${issue}` : ""}`;
   if (receipt.status === "blocked" || receipt.status === "rejected") {
     const reasons: Record<string, string> = {
       wrong_profile: "This operation belongs to the other profile",
@@ -138,6 +153,8 @@ function summary(receipt: any, name: string, args: any): string {
   }
   if (name === "freeflow_unit") {
     if (operation === "close") return capital(receipt.outcome ?? "closed");
+    if (operation === "recover") return "Recovery request saved";
+    if (operation === "cancel-recovery") return "Evidence recovery cancelled";
     if (operation === "assess")
       return receipt.status === "unchanged" ? "Assessment already active" : "Evidence prepared";
     if (receipt.view === "history")
@@ -180,7 +197,7 @@ export function renderRoutingResult(
         `Evidence revision ${facts.revision ?? "unknown"}`,
         ...(facts.selected ?? []).map(
           (s: any) =>
-            `${s.ref} · ${s.kind}${s.producer ? ` · ${s.producer}` : ""}${s.assignment ? ` · assignment ${s.assignment}` : ""}${s.toolName ? ` · ${s.toolName}` : ""}`,
+            `${s.ref} · ${s.kind}${s.producer ? ` · ${s.producer}` : ""}${s.assignment ? ` · assignment ${s.assignment}` : ""}${s.toolName ? ` · ${s.toolName}` : ""}${s.locator ? ` · ${locatorText(s.locator)}` : ""}`,
         ),
         ...(facts.withdrawals ?? []).map((w: any) => `Withdrawn ${w.ref}: ${w.reason}`),
         ...(facts.unresolved ?? []).map((p: any) => `Unresolved ${p.ref}: ${p.detail}`),
@@ -195,9 +212,11 @@ export function renderRoutingResult(
         : "",
     receipt.report
       ? `Saved report\n${receipt.report}`
-      : args.report
-        ? `${receipt.reportSaved ? "Saved" : "Submitted"} report\n${args.report}`
-        : "",
+      : receipt.supplement
+        ? `Saved recovery supplement\n${receipt.supplement}`
+        : args.report
+          ? `${receipt.supplementSaved ? "Saved recovery supplement" : receipt.reportSaved ? "Saved report" : "Submitted report"}\n${args.report}`
+          : "",
     receipt.assessment ? `Assessment\n${value(receipt.assessment)}` : args.assessment,
     evidence,
     receipt.items
@@ -217,7 +236,7 @@ export function renderRoutingResult(
     receipt.candidates
       ?.map(
         (item: any) =>
-          `${item.ref} · ${item.kind} · ${item.producer}${item.toolName ? ` · ${item.toolName}` : ""}${item.assignment ? ` · assignment ${item.assignment}` : ""}\n${item.selected ? "Selected" : "Not selected"} · ${item.active ? "Active" : "Historical"} · ${item.eligible ? "Eligible" : "Ineligible"} · ${item.targetReady ? "No known item target gap" : "Target needs attention"}${item.retainedSelection ? "\nPreviously selected routing source retained; unavailable for new selections." : ""}\n${item.limitations.map((p: any) => `${p.code}: ${p.detail}`).join("\n")}`,
+          `${item.ref} · ${item.kind} · ${item.producer}${item.toolName ? ` · ${item.toolName}` : ""}${item.assignment ? ` · assignment ${item.assignment}` : ""}${item.locator ? ` · ${locatorText(item.locator)}` : ""}\n${item.selected ? "Selected" : "Not selected"} · ${item.active ? "Active" : "Historical"} · ${item.eligible ? "Eligible" : "Ineligible"} · ${item.targetReady ? "No known item target gap" : "Target needs attention"}${item.retainedSelection ? "\nPreviously selected routing source retained; unavailable for new selections." : ""}\n${item.limitations.map((p: any) => `${p.code}: ${p.detail}`).join("\n")}`,
       )
       .join("\n\n"),
     receipt.ref ? `Work ref: ${receipt.ref}` : "",
@@ -233,9 +252,11 @@ export function renderRoutingResult(
       "unit",
       "assignment",
       "assignmentRef",
+      "recovery",
       "handoff",
       "revision",
       "reportRevision",
+      "supplementRevision",
       "outcome",
       "stage",
       "transition",