@hassangameryt/freeflow 0.7.3 → 0.8.0

package/pi-extension/dist/{cognitive-routing-v2 → cognitive-routing}/state.js

@@ -1,373 +1,13 @@
 import {
-  EFFORTS,
   PROFILES,
   ROUTING_ENTRY,
   canonical,
   eventKey,
   eventValue,
-  isObject,
   isWorkerProfile,
   requireCondition as check,
 } from "./types.js";
-const text = (x, max = 32768) => typeof x === "string" && x.trim().length > 0 && x.length <= max;
-const identity = (x) => text(x, 512);
-const nullableId = (x) => x === null || identity(x);
-const shape = (x, keys) => isObject(x) && Object.keys(x).every((k) => keys.includes(k));
-const uniqueStrings = (x) => Array.isArray(x) && x.every(identity) && new Set(x).size === x.length;
-const pair = (x) =>
-  shape(x, ["provider", "modelId", "thinking"]) &&
-  identity(x.provider) &&
-  identity(x.modelId) &&
-  EFFORTS.includes(x.thinking);
-const profileOverrides = (x) =>
-  isObject(x) &&
-  Object.keys(x).length > 0 &&
-  Object.keys(x).every((key) => PROFILES.includes(key)) &&
-  Object.values(x).every((value) => value === null || pair(value));
-const problemList = (xs) =>
-  Array.isArray(xs) &&
-  xs.every(
-    (x) =>
-      shape(x, ["ref", "code", "detail"]) && typeof x.ref === "string" && text(x.code, 256) && text(x.detail, 4096),
-  );
-const reservation = (r) =>
-  shape(r, [
-    "id",
-    "selectionRevision",
-    "receiver",
-    "target",
-    "qualification",
-    "sources",
-    "maximumInputTokens",
-    "outputReserve",
-    "estimateMethod",
-  ]) &&
-  identity(r.id) &&
-  Number.isSafeInteger(r.selectionRevision) &&
-  r.selectionRevision >= 0 &&
-  PROFILES.includes(r.receiver) &&
-  pair(r.target) &&
-  text(r.qualification) &&
-  Array.isArray(r.sources) &&
-  r.sources.every((s) => shape(s, ["ref", "bodyHash"]) && identity(s.ref) && /^[a-f0-9]{64}$/.test(s.bodyHash)) &&
-  new Set(r.sources.map((s) => s.ref)).size === r.sources.length &&
-  Number.isFinite(r.maximumInputTokens) &&
-  r.maximumInputTokens > 0 &&
-  Number.isFinite(r.outputReserve) &&
-  r.outputReserve >= 0 &&
-  text(r.estimateMethod);
-const recovery = (r) =>
-  shape(r, [
-    "id",
-    "assignmentId",
-    "assessmentHandoffId",
-    "baseReportRevision",
-    "request",
-    "requestedPaths",
-    "paths",
-    "state",
-    "requestHandoffId",
-    "supplementHandoffId",
-    "supplementRevision",
-    "cancellationReason",
-  ]) &&
-  identity(r.id) &&
-  identity(r.assignmentId) &&
-  identity(r.assessmentHandoffId) &&
-  Number.isSafeInteger(r.baseReportRevision) &&
-  r.baseReportRevision > 0 &&
-  text(r.request) &&
-  Array.isArray(r.requestedPaths) &&
-  r.requestedPaths.length <= 32 &&
-  r.requestedPaths.every((path) => text(path, 4096)) &&
-  new Set(r.requestedPaths).size === r.requestedPaths.length &&
-  Array.isArray(r.paths) &&
-  r.paths.length <= 32 &&
-  r.paths.every((path) => text(path, 4096)) &&
-  new Set(r.paths).size === r.paths.length &&
-  ["requested", "reading", "returning", "completed", "cancelled"].includes(r.state) &&
-  identity(r.requestHandoffId) &&
-  (r.supplementHandoffId === undefined || identity(r.supplementHandoffId)) &&
-  Number.isSafeInteger(r.supplementRevision) &&
-  r.supplementRevision >= 0 &&
-  (r.cancellationReason === undefined || text(r.cancellationReason, 2048));
-const handoff = (h) =>
-  shape(h, [
-    "id",
-    "kind",
-    "assignmentId",
-    "text",
-    "from",
-    "to",
-    "executionId",
-    "toolCallId",
-    "basisUserEntryId",
-    "state",
-    "reportRevision",
-    "outcome",
-    "limitations",
-    "reason",
-  ]) &&
-  identity(h.id) &&
-  identity(h.assignmentId) &&
-  text(h.text) &&
-  identity(h.executionId) &&
-  identity(h.toolCallId) &&
-  nullableId(h.basisUserEntryId) &&
-  ["delegate", "return", "recovery-request", "recovery-return"].includes(h.kind) &&
-  PROFILES.includes(h.from) &&
-  PROFILES.includes(h.to) &&
-  h.from !== h.to &&
-  ["pending", "configured", "blocked", "superseded"].includes(h.state) &&
-  Number.isSafeInteger(h.reportRevision) &&
-  h.reportRevision >= 0 &&
-  Array.isArray(h.limitations) &&
-  h.limitations.length <= 32 &&
-  h.limitations.every((x) => text(x, 2048)) &&
-  (h.reason === undefined || text(h.reason, 4096)) &&
-  (h.outcome === undefined || ["completed", "partial", "blocked"].includes(h.outcome)) &&
-  (["delegate", "recovery-request"].includes(h.kind)
-    ? h.outcome === undefined && h.reportRevision === 0
-    : ["completed", "partial", "blocked"].includes(h.outcome) && h.reportRevision > 0);
-const fields = {
-  "execution-interrupted": ["executionId", "reason"],
-  "assignment-resumed": ["assignmentId", "basisUserEntryId"],
-  control: ["control", "profile", "reason"],
-  "profile-overrides": ["overrides", "reason"],
-  "execution-opened": ["execution"],
-  "execution-bound": ["executionId", "assistantEntryId", "resultEntryIds", "outcome"],
-  "delegate-accepted": ["unit", "assignment", "handoff", "replacement"],
-  "return-accepted": ["handoff"],
-  "recovery-request-accepted": ["recovery", "handoff"],
-  "recovery-supplement-accepted": ["recoveryId", "handoff"],
-  "recovery-cancelled": ["recoveryId", "reason"],
-  "handoff-retry-requested": [
-    "handoffId",
-    "attemptId",
-    "executionId",
-    "toolCallId",
-    "reportRevision",
-    "selectionRevision",
-  ],
-  "handoff-prepared": ["handoffId", "reservation"],
-  "handoff-state": ["handoffId", "state", "reason", "observedPair"],
-  "selection-changed": ["assignmentId", "selection"],
-  "assessment-suspended": ["handoffId", "reason", "basisUserEntryId", "problems"],
-  "assessment-resumed": ["handoffId", "basisUserEntryId", "reservation"],
-  "unit-closed": ["unitId", "outcome", "assessment", "supersededAssignmentId"],
-  "sources-exposed": ["executionId", "view", "sources"],
-  "request-observed": ["executionId", "profile", "boundary", "manifestHash", "handoffId", "selectionRevision"],
-};
-export function parseRoutingEvent(raw) {
-  check(
-    isObject(raw) &&
-      raw.version === 2 &&
-      identity(raw.eventId) &&
-      identity(raw.operationId) &&
-      identity(raw.stepId) &&
-      identity(raw.recordedSessionId) &&
-      isObject(raw.data),
-    "invalid_event",
-  );
-  check(
-    Object.keys(raw).every((k) =>
-      ["version", "eventId", "operationId", "stepId", "recordedSessionId", "data"].includes(k),
-    ),
-    "invalid_event_field",
-  );
-  const d = raw.data;
-  check(
-    typeof d.type === "string" &&
-      Object.hasOwn(fields, d.type) &&
-      Object.keys(d).every((k) => k === "type" || fields[d.type].includes(k)),
-    "invalid_event_type",
-  );
-  check(Buffer.byteLength(JSON.stringify(raw)) <= 512 * 1024, "event_too_large");
-  if (d.handoffId !== undefined) check(identity(d.handoffId), "invalid_handoff_id");
-  switch (d.type) {
-    case "execution-interrupted":
-      check(identity(d.executionId) && text(d.reason, 4096), "invalid_interruption");
-      break;
-    case "assignment-resumed":
-      check(identity(d.assignmentId) && nullableId(d.basisUserEntryId), "invalid_resume");
-      break;
-    case "control":
-      check(
-        ["automatic", "manual", "inactive"].includes(d.control) &&
-          text(d.reason, 4096) &&
-          (d.profile === undefined || PROFILES.includes(d.profile)) &&
-          (d.control === "inactive" || PROFILES.includes(d.profile)),
-        "invalid_control",
-      );
-      break;
-    case "profile-overrides":
-      check(profileOverrides(d.overrides) && text(d.reason, 4096), "invalid_profile_overrides");
-      break;
-    case "execution-opened": {
-      const e = d.execution;
-      check(
-        shape(e, ["id", "profile", "assignmentId", "recoveryId", "basisUserEntryId", "pair", "resultEntryIds"]) &&
-          identity(e.id) &&
-          ["solo", ...PROFILES].includes(e.profile) &&
-          nullableId(e.basisUserEntryId) &&
-          pair(e.pair) &&
-          uniqueStrings(e.resultEntryIds) &&
-          e.resultEntryIds.length === 0 &&
-          (e.assignmentId === undefined || identity(e.assignmentId)) &&
-          (e.recoveryId === undefined || identity(e.recoveryId)),
-        "invalid_execution",
-      );
-      break;
-    }
-    case "execution-bound":
-      check(
-        identity(d.executionId) &&
-          identity(d.assistantEntryId) &&
-          uniqueStrings(d.resultEntryIds) &&
-          ["completed", "failed", "aborted"].includes(d.outcome),
-        "invalid_binding",
-      );
-      break;
-    case "delegate-accepted": {
-      const u = d.unit,
-        a = d.assignment,
-        r = d.replacement;
-      check(
-        shape(u, ["id", "objective", "state", "assignmentIds"]) &&
-          identity(u.id) &&
-          text(u.objective) &&
-          u.state === "open" &&
-          uniqueStrings(u.assignmentIds),
-        "invalid_unit",
-      );
-      check(
-        shape(a, ["id", "unitId", "contract", "basisUserEntryId", "state", "delegateHandoffId"]) &&
-          identity(a.id) &&
-          identity(a.unitId) &&
-          text(a.contract) &&
-          nullableId(a.basisUserEntryId) &&
-          a.state === "outstanding" &&
-          identity(a.delegateHandoffId) &&
-          handoff(d.handoff),
-        "invalid_assignment",
-      );
-      check(
-        r === undefined ||
-          (shape(r, ["assignmentId", "supersededHandoffId", "reason"]) &&
-            identity(r.assignmentId) &&
-            text(r.reason, 2048) &&
-            (r.supersededHandoffId === undefined || identity(r.supersededHandoffId))),
-        "invalid_replacement",
-      );
-      break;
-    }
-    case "return-accepted":
-      check(handoff(d.handoff) && d.handoff.kind === "return", "invalid_return");
-      break;
-    case "recovery-request-accepted":
-      check(
-        recovery(d.recovery) &&
-          handoff(d.handoff) &&
-          d.handoff.kind === "recovery-request" &&
-          d.recovery.requestHandoffId === d.handoff.id &&
-          d.recovery.assignmentId === d.handoff.assignmentId &&
-          d.recovery.request === d.handoff.text,
-        "invalid_recovery_request",
-      );
-      break;
-    case "recovery-supplement-accepted":
-      check(
-        identity(d.recoveryId) && handoff(d.handoff) && d.handoff.kind === "recovery-return",
-        "invalid_recovery_supplement",
-      );
-      break;
-    case "recovery-cancelled":
-      check(identity(d.recoveryId) && text(d.reason, 2048), "invalid_recovery_cancellation");
-      break;
-    case "handoff-retry-requested":
-      check(
-        identity(d.attemptId) &&
-          identity(d.executionId) &&
-          identity(d.toolCallId) &&
-          Number.isSafeInteger(d.reportRevision) &&
-          d.reportRevision > 0 &&
-          Number.isSafeInteger(d.selectionRevision) &&
-          d.selectionRevision >= 0,
-        "invalid_retry",
-      );
-      break;
-    case "handoff-prepared":
-      check(reservation(d.reservation), "invalid_reservation");
-      break;
-    case "handoff-state":
-      check(
-        ["configured", "blocked", "superseded"].includes(d.state) &&
-          (d.reason === undefined || text(d.reason, 4096)) &&
-          (d.observedPair === undefined || pair(d.observedPair)),
-        "invalid_delivery",
-      );
-      break;
-    case "selection-changed": {
-      const s = d.selection;
-      check(
-        identity(d.assignmentId) &&
-          shape(s, ["revision", "selected", "unresolved", "withdrawals"]) &&
-          Number.isSafeInteger(s.revision) &&
-          s.revision > 0 &&
-          uniqueStrings(s.selected) &&
-          problemList(s.unresolved) &&
-          Array.isArray(s.withdrawals) &&
-          s.withdrawals.every((w) => shape(w, ["ref", "reason"]) && identity(w.ref) && text(w.reason, 2048)),
-        "invalid_selection",
-      );
-      break;
-    }
-    case "assessment-suspended":
-      check(
-        ["user-attention", "delivery-gap"].includes(d.reason) &&
-          nullableId(d.basisUserEntryId) &&
-          problemList(d.problems),
-        "invalid_suspension",
-      );
-      break;
-    case "assessment-resumed":
-      check(
-        nullableId(d.basisUserEntryId) && (d.reservation === undefined || reservation(d.reservation)),
-        "invalid_resumption",
-      );
-      break;
-    case "unit-closed":
-      check(
-        identity(d.unitId) &&
-          ["accepted", "cancelled", "deferred"].includes(d.outcome) &&
-          text(d.assessment) &&
-          (d.supersededAssignmentId === undefined || identity(d.supersededAssignmentId)),
-        "invalid_closure",
-      );
-      break;
-    case "request-observed":
-      check(
-        identity(d.executionId) &&
-          ["solo", ...PROFILES].includes(d.profile) &&
-          ["assembled", "payload-hook"].includes(d.boundary) &&
-          /^[a-f0-9]{64}$/.test(d.manifestHash) &&
-          (d.selectionRevision === undefined ||
-            (Number.isSafeInteger(d.selectionRevision) && d.selectionRevision >= 0)),
-        "invalid_request_observation",
-      );
-      break;
-    case "sources-exposed":
-      check(
-        identity(d.executionId) &&
-          ["solo", ...PROFILES].includes(d.view) &&
-          Array.isArray(d.sources) &&
-          d.sources.every((s) => shape(s, ["ref", "bodyHash"]) && identity(s.ref) && /^[a-f0-9]{64}$/.test(s.bodyHash)),
-        "invalid_exposure",
-      );
-      break;
-  }
-  return structuredClone(raw);
-}
+import { parseRoutingEvent } from "./event-schema.js";
 export function initialState() {
   return {
     control: "inactive",
@@ -405,7 +45,17 @@ function applyEvent(state, event, owned = false) {
           units: new Map([...state.units].map(([k, v]) => [k, { ...v }])),
           assignments: new Map([...state.assignments].map(([k, v]) => [k, { ...v }])),
           handoffs: new Map([...state.handoffs].map(([k, v]) => [k, { ...v }])),
-          recoveries: new Map([...state.recoveries].map(([k, v]) => [k, { ...v, paths: [...v.paths] }])),
+          recoveries: new Map(
+            [...state.recoveries].map(([k, v]) => [
+              k,
+              {
+                ...v,
+                paths: [...v.paths],
+                requestedResults: [...(v.requestedResults ?? [])],
+                results: (v.results ?? []).map((grant) => ({ ...grant })),
+              },
+            ]),
+          ),
           executions: new Map([...state.executions].map(([k, v]) => [k, { ...v }])),
           selections: new Map(state.selections),
           reservations: new Map(state.reservations),
@@ -426,6 +76,11 @@ function applyEvent(state, event, owned = false) {
     check(h?.kind === "delegate" && h.assignmentId === a?.id && isWorkerProfile(h.to), "assignment_worker_missing");
     return h.to;
   };
+  // A worker response that started but was neither bound nor retired may still be producing effects.
+  const workerRunning = (belongs) =>
+    [...s.executions.values()].some(
+      (x) => belongs(x) && isWorkerProfile(x.profile) && !x.assistantEntryId && !x.interrupted,
+    );
   const pending = () => (s.pendingId ? s.handoffs.get(s.pendingId) : undefined);
   const isPending = () => pending() && ["pending", "blocked"].includes(pending().state);
   const currentReturn = (id) => {
@@ -464,6 +119,9 @@ function applyEvent(state, event, owned = false) {
         else s.profileOverrides.set(profile, override);
       }
       break;
+    case "delegation-override":
+      s.delegationOverride = d.delegation ?? undefined;
+      break;
     case "execution-opened":
       check(!s.executions.has(d.execution.id), "duplicate_execution");
       s.executions.set(d.execution.id, d.execution);
@@ -513,19 +171,17 @@ function applyEvent(state, event, owned = false) {
       );
       if (d.replacement) {
         check(a?.state === "outstanding" && a.id === d.replacement.assignmentId && u, "no_replaceable_assignment");
-        check(
-          ![...s.executions.values()].some(
-            (x) => x.assignmentId === a.id && isWorkerProfile(x.profile) && !x.assistantEntryId && !x.interrupted,
-          ),
-          "unresolved_worker_execution",
-        );
+        check(!workerRunning((x) => x.assignmentId === a.id), "unresolved_worker_execution");
         check(
           !isPending() || (pending().kind === "delegate" && d.replacement.supersededHandoffId === pending().id),
           "handoff_pending",
         );
         a.state = "superseded";
         s.handoffs.get(a.delegateHandoffId).state = "superseded";
-      } else check(a?.state !== "outstanding" && !isPending(), "assignment_outstanding");
+      } else {
+        check(a?.state !== "outstanding" && !isPending(), "assignment_outstanding");
+        check(!s.recoveryId, "recovery_outstanding");
+      }
       s.units.set(d.unit.id, d.unit);
       s.unitId = d.unit.id;
       s.assignments.set(d.assignment.id, d.assignment);
@@ -602,7 +258,11 @@ function applyEvent(state, event, owned = false) {
           !s.recoveries.has(d.recovery.id),
         "recovery_not_available",
       );
-      s.recoveries.set(d.recovery.id, d.recovery);
+      s.recoveries.set(d.recovery.id, {
+        ...d.recovery,
+        requestedResults: [...(d.recovery.requestedResults ?? [])],
+        results: (d.recovery.results ?? []).map((grant) => ({ ...grant })),
+      });
       s.recoveryId = d.recovery.id;
       s.handoffs.set(h.id, h);
       s.pendingId = h.id;
@@ -652,6 +312,7 @@ function applyEvent(state, event, owned = false) {
           ["requested", "reading", "returning"].includes(r.state),
         "recovery_not_cancellable",
       );
+      check(!workerRunning((x) => x.recoveryId === r.id), "unresolved_worker_execution");
       const p = pending();
       if (p) {
         check([r.requestHandoffId, r.supplementHandoffId].includes(p.id), "handoff_pending");
@@ -737,14 +398,10 @@ function applyEvent(state, event, owned = false) {
       break;
     }
     case "assessment-resumed": {
-      check(
-        s.control === "automatic" &&
-          s.profile === "coordinator" &&
-          !s.recoveryId &&
-          s.assessment?.handoffId === d.handoffId &&
-          s.assessment.view === "suspended",
-        s.recoveryId ? "recovery_outstanding" : "assessment_not_suspended",
-      );
+      check(s.control === "automatic" && s.profile === "coordinator", "wrong_control");
+      check(!s.recoveryId, "recovery_outstanding");
+      check(s.assessment?.handoffId === d.handoffId, "assessment_missing");
+      check(s.assessment.view === "suspended", "assessment_not_suspended");
       if (d.reservation)
         check(
           d.reservation.selectionRevision === (s.selections.get(s.assessment.assignmentId)?.revision ?? 0),
@@ -775,6 +432,7 @@ function applyEvent(state, event, owned = false) {
           d.outcome !== "accepted" && ["requested", "reading", "returning"].includes(recovery.state),
           "unfinished_work",
         );
+        check(!workerRunning((x) => x.recoveryId === recovery.id), "unresolved_worker_execution");
         const transfer = pending();
         if (transfer) {
           check([recovery.requestHandoffId, recovery.supplementHandoffId].includes(transfer.id), "handoff_pending");
@@ -787,6 +445,7 @@ function applyEvent(state, event, owned = false) {
       }
       if (a?.state === "outstanding") {
         check(d.supersededAssignmentId === a.id && d.outcome !== "accepted", "supersession_required");
+        check(!workerRunning((x) => x.assignmentId === a.id), "unresolved_worker_execution");
         a.state = "superseded";
       }
       if (pending()) pending().state = "superseded";

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

@@ -0,0 +1,80 @@
+import { initialState } from "./state.js";
+/**
+ * What routing reports about itself: the summary behind Freeflow's status line and the Runtime State sent with each
+ * request (whether routing is active or blocked and why, the running profile, control mode, a switch waiting for the
+ * next prompt, preset warnings), and the detailed view with unit, assignment, handoff, recovery, and recent events
+ * used by unit status and diagnostics.
+ */
+export class RoutingStatus {
+  session;
+  models;
+  constructor(session, models) {
+    this.session = session;
+    this.models = models;
+  }
+  state() {
+    let state;
+    try {
+      state = this.session.stateData();
+    } catch {
+      state = initialState();
+    }
+    const blocked = this.session.error ?? this.session.store?.blocked;
+    return {
+      effective: this.session.supported() && state.control !== "inactive" && !blocked,
+      activeProfile: state.profile,
+      delegation: this.session.delegation(state),
+      controlMode: state.control === "manual" ? `manual-${state.profile}` : state.control,
+      runtimeStatus: blocked
+        ? "blocked"
+        : this.session.supported() && state.control !== "inactive"
+          ? "active"
+          : "inactive",
+      runtimeReason:
+        blocked ?? (this.session.suppressed ? "startup_selection" : this.session.capability?.blockingReason.message),
+      projectionFailure: this.session.projectionError,
+      ...((pending) => (pending ? { pendingPair: `${pending.modelId}/${pending.thinking}` } : {}))(
+        this.models.pending(),
+      ),
+      ...(this.models.heldMismatch(state) ? { pairMismatch: true } : {}),
+      ...((warnings) => (warnings.length ? { presetWarnings: warnings } : {}))(this.models.presetWarnings(state)),
+    };
+  }
+  detail(limit = 0) {
+    const state = this.session.stateData();
+    const unit = state.unitId ? state.units.get(state.unitId) : undefined;
+    const a = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+    return {
+      ...this.state(),
+      unit: unit ? { id: unit.id, state: unit.state, assignments: unit.assignmentIds.length } : null,
+      assignment: a ? { id: a.id, state: a.state, worker: this.session.assignedWorker(state, a.id) } : null,
+      pendingHandoff: state.pendingId ?? null,
+      recovery: state.recoveryId
+        ? (() => {
+            const recovery = state.recoveries.get(state.recoveryId);
+            return recovery
+              ? {
+                  id: recovery.id,
+                  state: recovery.state,
+                  assignmentId: recovery.assignmentId,
+                  assessmentHandoffId: recovery.assessmentHandoffId,
+                  paths: recovery.paths,
+                  results: recovery.results ?? [],
+                  supplementRevision: recovery.supplementRevision,
+                }
+              : null;
+          })()
+        : null,
+      assessment: state.assessment
+        ? { handoffId: state.assessment.handoffId, view: state.assessment.view, problems: state.assessment.problems }
+        : null,
+      ...(limit
+        ? {
+            history: [...state.events.values()]
+              .slice(-Math.min(100, Math.max(1, limit)))
+              .map((e) => ({ event: e.eventId, type: e.data.type, operation: e.operationId })),
+          }
+        : {}),
+    };
+  }
+}

package/pi-extension/dist/{cognitive-routing-v2 → cognitive-routing}/tools.js

@@ -1,5 +1,5 @@
-import { ROUTING_TOOLS } from "./runtime.js";
-import { ROUTING_SCHEMAS, matches } from "./schemas.js";
+import { ROUTING_TOOLS } from "./types.js";
+import { ROUTING_SCHEMAS, explainRoutingArguments, matches } from "./schemas.js";
 export { ROUTING_SCHEMAS } from "./schemas.js";
 import { renderRoutingCall, renderRoutingResult } from "./render.js";
 const descriptions = {
@@ -10,7 +10,7 @@ const descriptions = {
   freeflow_unit:
     "Inspect current responsibility, paginated work history, or exact saved communication. Coordinator can restore an assessment, request or cancel attached evidence recovery, or close a unit without clearing history.",
   freeflow_project:
-    "Inspect current selection and scoped candidates when needed, then add or remove exposed worker task-evidence refs. Strict shapes: inspect uses operation plus optional scope/cursor; add uses operation plus eligible refs only; remove uses operation plus currently selected or unresolved refs plus required reason. Reason is remove-only. #text refs select exact visible assistant text; plain refs retain whole-native meaning.",
+    "Inspect current selection and scoped candidates when needed, then add or remove exposed worker task-evidence refs. Strict shapes: inspect uses operation plus optional scope/cursor; add uses operation plus eligible refs only; remove uses operation plus currently selected or unresolved refs plus required reason. Reason is remove-only. Only tool results are evidence; put anything you would say in the report.",
 };
 const guidance = {
   freeflow_delegate: [
@@ -23,7 +23,7 @@ const guidance = {
     "freeflow_unit inspect defaults to current state; view history returns work refs and detail reads saved communication. Coordinator recover requests bounded evidence work against the current returned assessment; cancel-recovery ends only that recovery; assess restores a suspended evidence obligation; close changes work status without clearing communication or completing a Working Record task.",
   ],
   freeflow_project: [
-    "Use exactly one shape: inspect {operation, scope?, cursor?}; add {operation, refs} with no reason; remove {operation, refs, reason}. Reason is required only for remove and invalid for add/inspect. Add exact eligible visible refs directly when identity and eligibility are clear; inspect when identity, eligibility, representation or selection state is unclear. Never add refs marked not offered for new evidence selection. For remove, use currently selected or unresolved refs; a non-selectable ref may be named only to clear its unresolved request and requires a reason. Use an offered #text ref only when visible assistant text is the intended evidence. Plain refs retain whole-native meaning. Select actual result bodies for execution claims, not merely calls. Correct or explicitly withdraw unresolved items with a limitation. Known previously exposed bodies resolve automatically; target-representation gaps are not successful delivery.",
+    "Use exactly one shape: inspect {operation, scope?, cursor?}; add {operation, refs} with no reason; remove {operation, refs, reason}. Reason is required only for remove and invalid for add/inspect. Add exact eligible visible refs directly when identity and eligibility are clear; inspect when identity, eligibility, representation or selection state is unclear. Never add refs marked not offered for new evidence selection. For remove, use currently selected or unresolved refs; a non-selectable ref may be named only to clear its unresolved request and requires a reason. Only tool results are evidence: select the result bodies behind your claims, not calls or your own messages, and say everything else in the report. Correct or explicitly withdraw unresolved items with a limitation. Known previously exposed bodies resolve automatically; target-representation gaps are not successful delivery.",
   ],
 };
 export function registerRoutingTools(pi, runtime) {
@@ -33,13 +33,14 @@ export function registerRoutingTools(pi, runtime) {
       label: name.replace("freeflow_", "Routing "),
       description: descriptions[name],
       parameters: ROUTING_SCHEMAS[name],
+      // Handoffs and evidence selection are assistant-issued boundaries: codemode scripts must not call them.
+      exposure: "model-only",
       executionMode: "sequential",
       promptGuidelines: guidance[name],
       renderCall: (args, _theme, context) => renderRoutingCall(name, args, context),
       renderResult: (result, options, _theme, context) => renderRoutingResult(result, options, name, context),
       async execute(id, input, signal, _update, ctx) {
-        if (!matches(input, ROUTING_SCHEMAS[name]))
-          throw new Error("Invalid routing arguments; no operation accepted.");
+        if (!matches(input, ROUTING_SCHEMAS[name])) throw new Error(explainRoutingArguments(name, input));
         return runtime.invoke(name, id, input, signal, ctx);
       },
     };
@@ -49,12 +50,11 @@ export function registerRoutingTools(pi, runtime) {
 export function applyRoutingToolVisibility(pi, _runtime, _available = true) {
   if (!pi.getActiveTools || !pi.setActiveTools) return;
   const current = pi.getActiveTools();
-  const ordinary = current.filter(
-    (name) =>
-      !ROUTING_TOOLS.includes(name) &&
-      name !== "freeflow_switch_profile" &&
-      name !== "freeflow_cognitive_routing_history",
+  // Missing routing tools are appended and present ones keep their place, so tools another extension adds later
+  // (tool_search, for one) are never reordered around them.
+  const kept = current.filter(
+    (name) => name !== "freeflow_switch_profile" && name !== "freeflow_cognitive_routing_history",
   );
-  const next = [...ordinary, ...ROUTING_TOOLS];
+  const next = [...kept, ...ROUTING_TOOLS.filter((name) => !kept.includes(name))];
   if (JSON.stringify(next) !== JSON.stringify(current)) pi.setActiveTools(next);
 }

package/pi-extension/dist/{cognitive-routing-v2 → cognitive-routing}/types.js

@@ -1,5 +1,7 @@
+import { canonical } from "../host/canonical.js";
 export const ROUTING_ENTRY = "freeflow-routing-v2";
 export const ROUTING_MESSAGE = "freeflow-routing-v2-state";
+export const ROUTING_ATTENTION_MESSAGE = "freeflow-routing-attention";
 export const WORKER_PROFILES = ["helper", "executor"];
 export const PROFILES = ["coordinator", ...WORKER_PROFILES];
 export const DELEGATION_MODES = ["executor", "helper", "both"];
@@ -25,16 +27,6 @@ export function requireCondition(condition, code, message = code) {
 export function isObject(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
-export function canonical(value) {
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  if (isObject(value))
-    return `{${Object.keys(value)
-      .filter((k) => value[k] !== undefined)
-      .sort()
-      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
-      .join(",")}}`;
-  return JSON.stringify(value) ?? "null";
-}
 export function samePair(left, right) {
   return !!left && !!right && canonical(left) === canonical(right);
 }
@@ -44,5 +36,7 @@ export const eventValue = (event) =>
 export const emptySelection = () => ({ revision: 0, selected: [], unresolved: [], withdrawals: [] });
 export const refFor = (id) => `ctx:${id}`;
 export function idFor(ref) {
-  return /^ctx:([^\s:#]+)(?:#text)?$/.exec(ref)?.[1];
+  return /^ctx:([^\s:#]+)$/.exec(ref)?.[1];
 }
+export { canonical };
+export const ROUTING_TOOLS = ["freeflow_delegate", "freeflow_return", "freeflow_unit", "freeflow_project"];