@hassangameryt/freeflow 0.7.3 → 0.9.0

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

@@ -9,14 +9,14 @@ const locatorText = (locator) => {
   return locator.label ? `${locator.label}${locator.truncated ? " [truncated]" : ""} · ${identity}` : identity;
 };
 function title(name, operation) {
-  if (name === "freeflow_delegate") return operation === "replace" ? "Replace assignment" : "Delegate assignment";
-  if (name === "freeflow_return")
+  if (name === "delegate_work") return operation === "replace" ? "Replace assignment" : "Delegate assignment";
+  if (name === "return_work")
     return operation === "retry"
       ? "Retry return"
       : operation === "supplement"
         ? "Return recovery supplement"
         : "Return to Coordinator";
-  if (name === "freeflow_project")
+  if (name === "select_evidence")
     return (
       {
         add: "Select evidence",
@@ -25,7 +25,7 @@ function title(name, operation) {
         list: "List evidence",
       }[operation ?? ""] ?? "Evidence"
     );
-  if (name === "freeflow_unit")
+  if (name === "routing_unit")
     return (
       {
         inspect: "Inspect routing",
@@ -41,14 +41,14 @@ function title(name, operation) {
 }
 function draft(name, args, expanded) {
   const sections = [];
-  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));
+  if (name === "delegate_work") sections.push(text(args.contract));
+  if (name === "return_work") sections.push(text(args.report));
+  if (name === "routing_unit" && args.operation === "close") sections.push(text(args.assessment));
+  if (name === "routing_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");
-  if (name === "freeflow_project" && Array.isArray(args.refs))
+  if (name === "select_evidence" && Array.isArray(args.refs))
     sections.push(args.refs.filter((r) => typeof r === "string").join("\n"));
   for (const key of ["scope", "view", "ref", "cursor"])
     if (typeof args[key] === "string") sections.push(`${capital(key)}: ${args[key]}`);
@@ -63,13 +63,13 @@ export function renderRoutingCall(name, args = {}, context = {}) {
   if (context.isPartial === false) return new Text(heading, 0, 0);
   const writing = context.argsComplete !== true;
   const noun =
-    name === "freeflow_delegate"
+    name === "delegate_work"
       ? "assignment"
-      : name === "freeflow_return"
+      : name === "return_work"
         ? args.operation === "supplement"
           ? "supplement"
           : "report"
-        : name === "freeflow_unit" && args.operation === "close"
+        : name === "routing_unit" && args.operation === "close"
           ? "assessment"
           : undefined;
   const body = draft(name, args, context.expanded === true);
@@ -108,8 +108,8 @@ function summary(receipt, name, args) {
     return reasons[receipt.code] || text(receipt.message).split("\n")[0] || "Operation needs attention";
   }
   if (receipt.status === "suspended") return "Couldn’t restore evidence · Assessment remains paused";
-  if (name === "freeflow_delegate") return `${operation === "replace" ? "Replacement" : "Assignment"} saved`;
-  if (name === "freeflow_project") {
+  if (name === "delegate_work") return `${operation === "replace" ? "Replacement" : "Assignment"} saved`;
+  if (name === "select_evidence") {
     const selected = (receipt.selected ?? receipt.evidence?.selected ?? []).length;
     if (operation === "list")
       return `${count(receipt.count ?? receipt.items?.length ?? 0, "source")}${Number.isInteger(receipt.selectableCount) ? ` · ${receipt.selectableCount} selectable` : ""}`;
@@ -132,7 +132,7 @@ function summary(receipt, name, args) {
       receipt.items.every((i) => ["already_selected", "unchanged"].includes(i.status));
     return `${unchanged ? "No changes · " : ""}${count(selected, "source")} selected${receipt.ready === false ? ` · ${issue}` : operation === "inspect" ? " · No unresolved references" : ""}`;
   }
-  if (name === "freeflow_unit") {
+  if (name === "routing_unit") {
     if (operation === "close") return capital(receipt.outcome ?? "closed");
     if (operation === "recover") return "Recovery request saved";
     if (operation === "cancel-recovery") return "Evidence recovery cancelled";

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

@@ -0,0 +1,398 @@
+import { randomUUID } from "node:crypto";
+import { findRoutingSkill } from "./bootstrap.js";
+import { ContextAssembler } from "./assembler.js";
+import { EventStore } from "./event-store.js";
+import { ToolGate } from "./gate.js";
+import { Handoffs } from "./handoffs.js";
+import { ToolHandlers } from "./handlers.js";
+import { ModelControl } from "./model-control.js";
+import { RoutingSession } from "./session.js";
+import { RoutingStatus } from "./status.js";
+import { isTaskEvidence } from "./sources.js";
+import { PROFILES, canonical, isWorkerProfile, requireCondition as check, samePair } from "./types.js";
+/**
+ * Cognitive Routing as the Pi extension sees it. Binds routing to the current session, follows ancestry and
+ * configuration changes, handles /freeflow profile and resume commands, and forwards each host hook to the part that
+ * owns it: model control, status, the tool gate, request assembly, handoffs, and the routing tools.
+ */
+export class RoutingRuntime {
+  pi;
+  packageRoots;
+  /** State shared with every part of routing for the bound session. */
+  session = new RoutingSession();
+  models;
+  status;
+  gate;
+  assembler;
+  handoffs;
+  tools;
+  targetSignature;
+  constructor(pi, packageRoots = []) {
+    this.pi = pi;
+    this.packageRoots = packageRoots;
+    this.session.routingSkill = findRoutingSkill(this.packageRoots);
+    this.models = new ModelControl(this.session, this.pi);
+    this.status = new RoutingStatus(this.session, this.models);
+    this.gate = new ToolGate(this.session, this.packageRoots);
+    this.assembler = new ContextAssembler(this.session, this.pi, this.models);
+    this.handoffs = new Handoffs(this.session, this.pi, this.models, this.assembler);
+    this.tools = new ToolHandlers(this.session, this.models, this.gate, this.assembler, this.status);
+  }
+  get projectionEnabled() {
+    return this.session.projectionEnabled;
+  }
+  async settled(ctx) {
+    if (!this.session.store || !this.session.supported() || this.session.store.blocked || !ctx.isIdle?.()) return;
+    this.session.ctx = ctx;
+    this.session.retireUnbound(
+      "Native run settled without a complete source binding; prior effects remain unresolved.",
+    );
+  }
+  /** The Coordinator's model while a delegated worker holds the assignment; the Coordinator resumes on return. */
+  suspendedCoordinator() {
+    try {
+      const state = this.session.stateData();
+      if (
+        !this.session.supported() ||
+        state.control !== "automatic" ||
+        !isWorkerProfile(state.profile) ||
+        !state.assignmentId
+      )
+        return;
+      const pair = this.session.profilePair("coordinator");
+      return { provider: pair.provider, modelId: pair.modelId, requester: "coordinator" };
+    } catch {
+      return;
+    }
+  }
+  async bind(ctx, capability, startup = false) {
+    this.session.token = randomUUID();
+    this.session.ctx = ctx;
+    this.session.capability = capability;
+    this.session.resetTurn();
+    this.session.manualHold = undefined;
+    this.session.automaticControl = false;
+    this.models.applying = undefined;
+    this.models.externalChange = false;
+    this.session.error = undefined;
+    this.session.projectionError = undefined;
+    this.session.operations = Promise.resolve();
+    this.targetSignature = canonical({ delegation: capability.delegation, profiles: capability.profiles });
+    this.session.suppressed = startup && process.argv.some((a) => /^(--model|--thinking)(=|$)/.test(a));
+    this.session.store = new EventStore(this.pi, ctx.sessionManager);
+    const subject = this.session.subject();
+    if (!capability.effective || this.session.suppressed) return;
+    try {
+      await this.session.store.reconcile();
+      this.session.guard(subject);
+      const state = this.session.stateData();
+      this.session.manualHold = state.control === "manual" ? state.profile : undefined;
+      this.session.automaticControl = !state.events.size || state.control === "automatic";
+      await this.models.validateProfilePairs(this.session.profilePairs(this.session.requiredProfiles(state)));
+      this.models.announcePresets(ctx);
+      const interrupted = this.handoffs.interruptedRun(state);
+      const resumable = this.handoffs.resumableAssignment(state);
+      this.session.retireUnbound("Session rebind found an unfinished execution; no task effects replayed.");
+      if (!state.events.size) {
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Initial routing activation",
+            }),
+          subject,
+        );
+      } else if (
+        state.control === "automatic" &&
+        state.profile &&
+        !samePair(this.models.intended(), this.session.profilePair(state.profile))
+      ) {
+        // Reload reconstructs responsibility; it does not silently reapply the last setter.
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Rebind reconciles historical responsibility with current host control",
+            }),
+          subject,
+        );
+      }
+      // Only a run cut off mid-flight resumes on its own; reopening an idle session never starts work.
+      if (interrupted && ctx.hasUI) {
+        const token = this.session.token;
+        setTimeout(() => void this.handoffs.resumeAfterCrash(ctx, token), 0);
+      } else if (resumable)
+        ctx.ui?.notify?.(
+          `The ${resumable.worker} assignment is unchanged. Run /freeflow resume to continue it; a new message goes to Coordinator.`,
+          "info",
+        );
+    } catch (error) {
+      if (this.session.current(subject)) this.session.mark(error);
+    }
+  }
+  /** Write routing events staged before the session's first prompt; nothing to write once routing is unbound. */
+  writeStaged(events) {
+    if (!this.session.store || !events.length) return;
+    try {
+      this.session.store.writeStaged(events);
+    } catch (error) {
+      this.session.mark(error);
+    }
+  }
+  unbind() {
+    this.session.token = randomUUID();
+    this.session.store = undefined;
+    this.session.ctx = undefined;
+    this.session.resetTurn();
+  }
+  async refresh(ctx, capability) {
+    this.session.ctx = ctx;
+    const was = this.session.capability?.effective === true;
+    const signature = canonical({ delegation: capability.delegation, profiles: capability.profiles });
+    if (this.session.capability && (was !== capability.effective || signature !== this.targetSignature))
+      this.session.revision++;
+    this.session.capability = capability;
+    if (!capability.effective) {
+      this.session.turn = undefined;
+      return;
+    }
+    if (!this.session.store) {
+      await this.bind(ctx, capability);
+      return;
+    }
+    if (!was) {
+      const subject = this.session.subject();
+      this.session.suppressed = false;
+      try {
+        await this.session.store.reconcile();
+        this.session.guard(subject);
+        this.session.error = undefined;
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Capability re-enabled; Coordinator reconciliation",
+            }),
+          subject,
+        );
+        this.session.automaticControl = true;
+      } catch (error) {
+        if (this.session.current(subject)) this.session.mark(error);
+      }
+    } else if (this.targetSignature && signature !== this.targetSignature) {
+      this.session.error = "configuration_changed: reconcile profile configuration before automatic execution";
+      this.session.announceBlock(ctx);
+    }
+    if (
+      canonical({ delegation: this.session.capability?.delegation, profiles: this.session.capability?.profiles }) ===
+      signature
+    )
+      this.targetSignature = signature;
+    this.models.announcePresets(ctx);
+  }
+  async ancestryChanged(ctx, navigation = true) {
+    this.session.revision++;
+    this.session.ctx = ctx;
+    this.session.resetTurn();
+    if (!this.session.store || !this.session.supported()) return;
+    const subject = this.session.subject();
+    try {
+      await this.session.store.reconcile();
+      this.session.guard(subject);
+      this.session.error = undefined;
+      const state = this.session.stateData();
+      await this.models.validateProfilePairs(this.session.profilePairs(this.session.requiredProfiles(state)));
+      this.session.retireUnbound(
+        "Selected historical ancestry ends before execution binding; effects are not replayed.",
+      );
+      if (this.session.manualHold) {
+        const held = this.session.manualHold;
+        await this.models.transition(
+          this.session.profilePair(held),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "manual",
+              profile: held,
+              reason: "Current explicit manual hold survives navigation",
+            }),
+          subject,
+        );
+      } else if (
+        (this.session.automaticControl || !state.events.size) &&
+        (navigation || !samePair(this.models.intended(), this.session.profilePair(state.profile ?? "coordinator")))
+      ) {
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Coordinator reconciles selected native ancestry",
+            }),
+          subject,
+        );
+      }
+    } catch (error) {
+      if (this.session.current(subject)) this.session.mark(error);
+    }
+  }
+  async command(args, ctx) {
+    const words = args.trim().split(/\s+/);
+    if (!["profile", "resume"].includes(words[0])) return false;
+    try {
+      if (words[0] === "profile" && words[1] === "history") {
+        check(words.length === 2 || (words.length === 3 && words[2] === "diagnostics"), "invalid_history_command");
+        ctx.ui.notify(
+          JSON.stringify(
+            words[2] === "diagnostics"
+              ? this.status.detail(30)
+              : this.tools.inspectUnit({ view: "history", limit: 30 }),
+          ),
+          "info",
+        );
+        return true;
+      }
+      check(ctx.isIdle?.(), "not_idle");
+      this.session.ctx = ctx;
+      if (words[0] === "resume" && words.length === 1) {
+        await this.handoffs.resume(ctx);
+        return true;
+      }
+      check(
+        words.length === 2 && [...PROFILES, "auto"].includes(words[1]),
+        "invalid_profile_command",
+        "Use /freeflow profile coordinator|helper|executor|auto|history, or /freeflow resume.",
+      );
+      const result =
+        words[1] === "auto" ? await this.models.setAutomaticControl() : await this.models.setManualProfile(words[1]);
+      ctx.ui.notify(JSON.stringify(result), result.status === "blocked" ? "warning" : "info");
+    } catch (error) {
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
+    return true;
+  }
+  beforeRun(ctx, trigger) {
+    return this.models.beforeRun(ctx, trigger);
+  }
+  runStarted() {
+    this.models.runStarted();
+  }
+  startedByMessage(message) {
+    return this.models.startedByMessage(message);
+  }
+  nativeChange(ctx) {
+    return this.models.nativeChange(ctx);
+  }
+  cycleManualProfile() {
+    return this.models.cycleManualProfile();
+  }
+  setManualProfile(profile, _mechanism) {
+    return this.models.setManualProfile(profile, _mechanism);
+  }
+  setAutomaticControl(_mechanism) {
+    return this.models.setAutomaticControl(_mechanism);
+  }
+  sessionProfileOverrides() {
+    return this.models.sessionProfileOverrides();
+  }
+  sessionDelegationOverride() {
+    return this.models.sessionDelegationOverride();
+  }
+  setSessionDelegationOverride(override, mechanism = "Session delegation override") {
+    return this.models.setSessionDelegationOverride(override, mechanism);
+  }
+  setSessionProfileOverride(profile, override, mechanism = "Session profile override") {
+    return this.models.setSessionProfileOverride(profile, override, mechanism);
+  }
+  resetSessionProfileOverrides(mechanism = "Reset session profile overrides") {
+    return this.models.resetSessionProfileOverrides(mechanism);
+  }
+  preflight(event, ctx) {
+    return this.gate.preflight(event, ctx);
+  }
+  operationScope(ctx = this.session.ctx) {
+    return this.gate.operationScope(ctx);
+  }
+  observationScope() {
+    return this.gate.observationScope();
+  }
+  admitOperation(scope, effect, _operation, ctx = this.session.ctx) {
+    return this.gate.admitOperation(scope, effect, _operation, ctx);
+  }
+  admitProgram(scope, ctx = this.session.ctx) {
+    return this.gate.admitProgram(scope, ctx);
+  }
+  resultReadAccess(id) {
+    return this.gate.resultReadAccess(id);
+  }
+  budgetNotice(messages, ctx) {
+    return this.assembler.budgetNotice(messages, ctx);
+  }
+  context(ctx, incoming) {
+    return this.assembler.context(ctx, incoming);
+  }
+  messageEnd(message) {
+    return this.handoffs.messageEnd(message);
+  }
+  turnEnd(event, ctx) {
+    return this.handoffs.turnEnd(event, ctx);
+  }
+  state() {
+    return this.status.state();
+  }
+  /** The assignment in progress, if any; Freeflow compaction records it so routing can tell the worker it compacted. */
+  currentAssignment() {
+    if (!this.state().effective) return undefined;
+    return this.session.stateData().assignmentId ?? undefined;
+  }
+  /**
+   * The assignment in progress, for compaction: the entries of the tool results it produced (task evidence only) and
+   * the refs already selected as its evidence. Undefined when no worker holds an assignment.
+   */
+  assignmentResults() {
+    try {
+      const state = this.session.stateData();
+      const assignmentId = state.assignmentId;
+      if (!this.state().effective || !assignmentId) return undefined;
+      const entryIds = new Set();
+      for (const source of this.session.sources().byRef.values())
+        if (source.assignmentId === assignmentId && isTaskEvidence(source)) entryIds.add(source.entry.id);
+      return { entryIds, selected: new Set(state.selections.get(assignmentId)?.selected ?? []) };
+    } catch {
+      return undefined;
+    }
+  }
+  /** A source ref's tool result, for compaction to carry; only task evidence, the results routing lets be selected. */
+  evidenceSource(ref) {
+    try {
+      const source = this.session.sources().byRef.get(ref);
+      if (!source || !isTaskEvidence(source)) return undefined;
+      const text = (source.message.content ?? [])
+        .map((part) => (part?.type === "text" ? part.text : part?.type === "image" ? "[image]" : ""))
+        .join("");
+      return { tool: source.message.toolName ?? "tool", text };
+    } catch {
+      return undefined;
+    }
+  }
+  setResultGrantPort(port) {
+    return this.tools.setResultGrantPort(port);
+  }
+  setEffectFencePort(port) {
+    return this.tools.setEffectFencePort(port);
+  }
+  invoke(name, callId, input, signal, ctx) {
+    return this.tools.invoke(name, callId, input, signal, ctx);
+  }
+}

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

@@ -40,7 +40,7 @@ const report = (name) =>
     ["operation", "report", "outcome"],
   );
 export const ROUTING_SCHEMAS = {
-  freeflow_delegate: {
+  delegate_work: {
     oneOf: [
       object({ operation: operation("assign"), contract: string(), worker }, ["operation", "contract"]),
       object({ operation: operation("replace"), contract: string(), reason: string(2048), worker }, [
@@ -50,8 +50,8 @@ export const ROUTING_SCHEMAS = {
       ]),
     ],
   },
-  freeflow_return: { oneOf: [report("submit"), report("supplement"), object({ operation: operation("retry") })] },
-  freeflow_unit: {
+  return_work: { oneOf: [report("submit"), report("supplement"), object({ operation: operation("retry") })] },
+  routing_unit: {
     oneOf: [
       object(
         {
@@ -69,6 +69,7 @@ export const ROUTING_SCHEMAS = {
           operation: operation("recover"),
           request: string(),
           paths: { type: "array", maxItems: 32, items: string(4096) },
+          results: { type: "array", maxItems: 32, uniqueItems: true, items: string(256) },
         },
         ["operation", "request"],
       ),
@@ -80,7 +81,7 @@ export const ROUTING_SCHEMAS = {
       }),
     ],
   },
-  freeflow_project: {
+  select_evidence: {
     oneOf: [
       object(
         {
@@ -140,6 +141,48 @@ for (const schema of Object.values(ROUTING_SCHEMAS)) {
       description:
         "For add, use exact eligible visible refs directly when their 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 to clear its unresolved request and requires reason.",
     };
+  // The provider sees one flattened root, so each field names the operations whose strict shape accepts it.
+  const operations = schema.oneOf.map((branch) => branch.properties.operation.enum[0]);
+  for (const [field, property] of Object.entries(schema.properties)) {
+    if (field === "operation") continue;
+    const accepting = operations.filter((_op, i) => Object.hasOwn(schema.oneOf[i].properties, field));
+    if (accepting.length === operations.length) continue;
+    const scope = `Only for operation: ${accepting.join(", ")}.`;
+    schema.properties[field] = {
+      ...property,
+      description: property.description ? `${property.description} ${scope}` : scope,
+    };
+  }
+}
+const expected = (schema) =>
+  schema.enum
+    ? `one of ${schema.enum.join(", ")}`
+    : schema.type === "string"
+      ? `a non-empty string of at most ${schema.maxLength} characters`
+      : schema.type === "array"
+        ? `an array of at most ${schema.maxItems} items`
+        : schema.type === "integer"
+          ? `an integer from ${schema.minimum} to ${schema.maximum}`
+          : `type ${schema.type}`;
+/** Explain why routing arguments match no strict operation shape, naming what to change. */
+export function explainRoutingArguments(name, input) {
+  const schema = ROUTING_SCHEMAS[name];
+  const operations = schema.oneOf.map((branch) => branch.properties.operation.enum[0]);
+  const operation = isObject(input) ? input.operation : undefined;
+  const branch = schema.oneOf.find((b) => b.properties.operation.enum[0] === operation);
+  if (!isObject(input) || !branch)
+    return `Invalid ${name} arguments: operation must be one of ${operations.join(", ")}. No operation was accepted.`;
+  const allowed = Object.keys(branch.properties);
+  const problems = [];
+  const unknown = Object.keys(input).filter((field) => !allowed.includes(field));
+  if (unknown.length) problems.push(`remove field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}`);
+  const missing = branch.required.filter((field) => !Object.hasOwn(input, field));
+  if (missing.length) problems.push(`missing required field${missing.length > 1 ? "s" : ""} ${missing.join(", ")}`);
+  for (const field of allowed)
+    if (Object.hasOwn(input, field) && !matches(input[field], branch.properties[field]))
+      problems.push(`${field} must be ${expected(branch.properties[field])}`);
+  if (!problems.length) problems.push("arguments do not match this operation's shape");
+  return `Invalid ${name} arguments for operation ${operation}: ${problems.join("; ")}. Allowed fields: ${allowed.join(", ")}. No operation was accepted.`;
 }
 export function matches(value, schema) {
   if (schema.oneOf) return schema.oneOf.filter((branch) => matches(value, branch)).length === 1;
@@ -164,10 +207,3 @@ export function matches(value, schema) {
     return Number.isSafeInteger(value) && value >= schema.minimum && value <= schema.maximum;
   return false;
 }
-export function schemaForProfile(name, coordinator) {
-  const schema = ROUTING_SCHEMAS[name];
-  if (name !== "freeflow_unit" || coordinator) return schema;
-  const branches = schema.oneOf.filter((b) => b.properties.operation.enum[0] === "inspect");
-  const properties = Object.assign({}, ...branches.map((b) => b.properties));
-  return { ...schema, properties, oneOf: branches };
-}