@hassangameryt/freeflow 0.7.1 → 0.7.3

package/command-surface.json

@@ -86,7 +86,13 @@
       "kind": "settings"
     },
     {
-      "command": "/freeflow profile <standard|reasoning|auto>",
+      "command": "/freeflow profile <coordinator|executor|auto>",
+      "handler": "freeflow",
+      "kind": "cognitive-routing-control",
+      "piOnly": true
+    },
+    {
+      "command": "/freeflow resume",
       "handler": "freeflow",
       "kind": "cognitive-routing-control",
       "piOnly": true

package/gemini-extension.json

@@ -1,5 +1,5 @@
 {
   "name": "freeflow",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Feedback-based control system for coding agents."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "format:pi-extension-dist": "prettier --write pi-extension/dist",
-    "build:pi-extension": "tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
+    "build:pi-extension": "node -e \"require('node:fs').rmSync('pi-extension/dist', { recursive: true, force: true })\" && tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
     "build": "npm run build:pi-extension",
     "typecheck": "tsc -p pi-extension/tsconfig.json --noEmit",
     "check": "npm run typecheck && npm run check:source && npm run check:host-manifests && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package",
@@ -101,8 +101,8 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "^22.15.30",
     "prettier": "3.9.5",
     "typescript": "^5.8.3"

package/pi-extension/dist/cognitive-routing-v2/budget.js

@@ -0,0 +1,42 @@
+// A local planning estimate, not a provider token count or an output allocation.
+// In particular, base64 and native usage/metadata are not model text.
+export function estimateRequest(systemPrompt, tools, messages, model) {
+  const text = (value) => Math.ceil(value.length / 3);
+  const content = (value) =>
+    typeof value === "string"
+      ? text(value)
+      : Array.isArray(value)
+        ? value.reduce(
+            (sum, b) =>
+              sum +
+              (b.type === "image"
+                ? 1200
+                : b.type === "toolCall"
+                  ? text(b.name + JSON.stringify(b.arguments ?? {}))
+                  : b.type === "thinking"
+                    ? text(b.thinking ?? "")
+                    : text(b.text ?? "")),
+            0,
+          )
+        : 0;
+  const estimatedTokens =
+    text(systemPrompt) +
+    text(JSON.stringify(tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })))) +
+    messages.reduce((sum, m) => sum + 8 + content(m.content), 0);
+  const window = model?.contextWindow ?? 0;
+  const outputReserve = Math.min(4096, Math.max(1, Math.floor(window / 10)));
+  const maximumInputTokens = Math.max(0, window - outputReserve);
+  const estimateMethod =
+    "Planning estimate: text characters / 3, 1200 tokens/image, schemas and message framing; output headroom is not the provider allocation";
+  const warnings =
+    estimatedTokens > maximumInputTokens
+      ? [
+          {
+            ref: "",
+            code: "budget_estimate",
+            detail: `Estimated input ${estimatedTokens} exceeds planning allowance ${maximumInputTokens}. Actual output allocation and image tokenization are provider-dependent; fit is unconfirmed. Use native compaction or revise explicitly if the provider rejects the request.`,
+          },
+        ]
+      : [];
+  return { estimatedTokens, maximumInputTokens, outputReserve, estimateMethod, warnings };
+}

package/pi-extension/dist/cognitive-routing-v2/config.js

@@ -0,0 +1,136 @@
+import { DELEGATION_MODES, EFFORTS, PROFILES, canonical, isObject, workersForDelegation } from "./types.js";
+export const supportsCognitiveRoutingModelRegistry = (host) =>
+  typeof host?.modelRegistry?.find === "function" && typeof host?.modelRegistry?.getApiKeyAndHeaders === "function";
+export const pairFromProfile = (profile) => ({
+  provider: profile.provider,
+  modelId: profile.model,
+  thinking: profile.thinking,
+});
+function parseLayer(raw) {
+  if (raw === undefined) return {};
+  if (
+    !isObject(raw) ||
+    Object.keys(raw).some((key) => !["enabled", "delegation", "projection", "profiles"].includes(key))
+  )
+    throw new Error(
+      "Routing requires the enabled/delegation/projection/profiles schema; experimental legacy configuration is not migrated.",
+    );
+  for (const key of ["enabled", "projection"])
+    if (raw[key] !== undefined && typeof raw[key] !== "boolean") throw new Error(`${key} must be boolean.`);
+  if (raw.delegation !== undefined && !DELEGATION_MODES.includes(raw.delegation))
+    throw new Error("delegation must be executor, helper, or both.");
+  if (raw.profiles !== undefined) {
+    if (!isObject(raw.profiles) || Object.keys(raw.profiles).some((key) => !PROFILES.includes(key)))
+      throw new Error("Profiles must be coordinator, helper, or executor.");
+    for (const profile of Object.values(raw.profiles)) {
+      if (
+        !isObject(profile) ||
+        Object.keys(profile).some((key) => !["provider", "model", "thinking"].includes(key)) ||
+        typeof profile.provider !== "string" ||
+        !profile.provider.trim() ||
+        typeof profile.model !== "string" ||
+        !profile.model.trim() ||
+        !EFFORTS.includes(profile.thinking)
+      )
+        throw new Error("Each profile requires provider, model, and supported thinking.");
+    }
+  }
+  return raw;
+}
+export async function resolveCognitiveRoutingState(repository, personal, ctx) {
+  const state = {
+    configured: repository?.cognitiveRouting !== undefined || personal?.cognitiveRouting !== undefined,
+    configValid: true,
+    enabled: false,
+    effective: false,
+    enabledSource: "default",
+    delegation: "executor",
+    delegationSource: "default",
+    projection: false,
+    projectionSource: "default",
+    profiles: {},
+    profileSources: {},
+    blockingReason: { code: "disabled", message: "Cognitive Routing is disabled." },
+  };
+  try {
+    for (const [source, raw] of [
+      ["repository", repository?.cognitiveRouting],
+      ["personal", personal?.cognitiveRouting],
+    ]) {
+      const layer = parseLayer(raw);
+      if (layer.enabled !== undefined) {
+        state.enabled = layer.enabled;
+        state.enabledSource = source;
+      }
+      if (layer.delegation !== undefined) {
+        state.delegation = layer.delegation;
+        state.delegationSource = source;
+      }
+      if (layer.projection !== undefined) {
+        state.projection = layer.projection;
+        state.projectionSource = source;
+      }
+      for (const profile of PROFILES)
+        if (layer.profiles?.[profile]) {
+          state.profiles[profile] = layer.profiles[profile];
+          state.profileSources[profile] = source;
+        }
+    }
+  } catch (error) {
+    return {
+      ...state,
+      configValid: false,
+      blockingReason: { code: "config_invalid", message: error instanceof Error ? error.message : String(error) },
+    };
+  }
+  if (!state.enabled) return state;
+  if (!supportsCognitiveRoutingModelRegistry(ctx))
+    return {
+      ...state,
+      blockingReason: { code: "host_unsupported", message: "Required public Pi model registry is unavailable." },
+    };
+  const requiredProfiles = ["coordinator", ...workersForDelegation(state.delegation)];
+  for (const name of requiredProfiles) {
+    const profile = state.profiles[name];
+    if (!profile)
+      return { ...state, blockingReason: { code: "profile_missing", message: `Configure the ${name} profile.` } };
+    const model = ctx.modelRegistry.find(profile.provider, profile.model);
+    if (!model)
+      return { ...state, blockingReason: { code: "profile_unavailable", message: `Model unavailable for ${name}.` } };
+    const clamp = ctx.modelRegistry.clampThinkingLevel?.bind(ctx.modelRegistry);
+    const supported = !model.reasoning
+      ? profile.thinking === "off"
+      : clamp
+        ? clamp(model, profile.thinking) === profile.thinking
+        : model.thinkingLevelMap?.[profile.thinking] !== null &&
+          (!["xhigh", "max"].includes(profile.thinking) || model.thinkingLevelMap?.[profile.thinking] !== undefined);
+    if (!supported)
+      return {
+        ...state,
+        blockingReason: { code: "profile_clamped", message: `Requested ${name} effort is not supported exactly.` },
+      };
+    try {
+      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+      if (!auth?.ok)
+        return {
+          ...state,
+          blockingReason: { code: "profile_unauthenticated", message: `Authentication unavailable for ${name}.` },
+        };
+    } catch {
+      return {
+        ...state,
+        blockingReason: { code: "profile_unauthenticated", message: `Authentication resolution failed for ${name}.` },
+      };
+    }
+  }
+  for (const worker of workersForDelegation(state.delegation))
+    if (canonical(state.profiles.coordinator) === canonical(state.profiles[worker]))
+      return {
+        ...state,
+        blockingReason: {
+          code: "profiles_identical",
+          message: `Configure distinct Coordinator and ${worker} model/effort pairs.`,
+        },
+      };
+  return { ...state, effective: true, blockingReason: { code: "", message: "" } };
+}

package/pi-extension/dist/cognitive-routing-v2/projection.js

@@ -0,0 +1,330 @@
+import { annotateSources } from "../session-sources/provenance.js";
+import { randomUUID } from "node:crypto";
+import { textRef } from "../session-sources/sources.js";
+import { canonical, emptySelection, isWorkerProfile, requireCondition as check } from "./types.js";
+import { estimateRequest } from "./budget.js";
+export function changeSelection(prior, input, sources, state) {
+  check(
+    Array.isArray(input.refs) &&
+      input.refs.length <= 64 &&
+      input.refs.every((r) => typeof r === "string" && r.length <= 512),
+    "invalid_refs",
+  );
+  if (input.operation === "remove")
+    check(
+      typeof input.reason === "string" && input.reason.trim() && input.reason.length <= 2048,
+      "withdrawal_reason_required",
+    );
+  const next = structuredClone(prior);
+  for (const ref of new Set(input.refs)) {
+    const existed = next.selected.includes(ref) || next.unresolved.some((p) => p.ref === ref);
+    if (input.operation === "remove") {
+      next.unresolved = next.unresolved.filter((p) => p.ref !== ref);
+      next.selected = next.selected.filter((r) => r !== ref);
+      if (existed) next.withdrawals.push({ ref, reason: input.reason });
+      continue;
+    }
+    const problem = prior.selected.includes(ref) ? sources.eligible(ref, state) : sources.selectionProblem(ref, state);
+    const index = next.unresolved.findIndex((p) => p.ref === ref);
+    if (problem) {
+      if (index < 0) next.unresolved.push(problem);
+      else next.unresolved[index] = problem;
+    } else {
+      if (index >= 0) next.unresolved.splice(index, 1);
+      if (!next.selected.includes(ref)) next.selected.push(ref);
+    }
+  }
+  if (canonical(next) === canonical(prior)) return prior;
+  next.revision++;
+  return next;
+}
+export function representationProblems(source, model, structural = false) {
+  const message = source.original?.message ?? source.message,
+    content = Array.isArray(source.message.content) ? source.message.content : [];
+  if (message.role === "assistant" && ["error", "aborted"].includes(message.stopReason))
+    return [
+      {
+        ref: source.ref,
+        code: "target_representation",
+        detail:
+          "Native compatibility conversion may omit failed/aborted assistant output; exact delivery is not promised.",
+      },
+    ];
+  if (content.some((b) => b.type === "image") && !model?.input?.includes("image"))
+    return [
+      { ref: source.ref, code: "target_representation", detail: "The receiving model does not support image input." },
+    ];
+  if (
+    !structural &&
+    !source.original &&
+    content.some((b) => b.type === "thinking" && (b.redacted || b.thinkingSignature)) &&
+    (message.provider !== model?.provider || message.model !== model?.id || message.api !== model?.api)
+  )
+    return [
+      {
+        ref: source.ref,
+        code: "target_representation",
+        detail: `Whole native signed content is not qualified across this model boundary. Inspect the explicit assistant-text source ${textRef(source.ref)} when visible text is the intended evidence.`,
+      },
+    ];
+  return [];
+}
+export function prepareView(options) {
+  const { sources, state } = options;
+  const associated = sources.associate(options.messages);
+  const selective = options.projection && options.view === "coordinator";
+  const assessment = state.assessment;
+  const attention = selective && assessment?.view === "suspended" && !options.restoring && !options.preparingReturn;
+  const handoffId = options.preparingReturn ?? (!attention ? assessment?.handoffId : undefined);
+  const handoff = handoffId ? state.handoffs.get(handoffId) : undefined;
+  const assignmentId = handoff?.assignmentId ?? state.assignmentId;
+  const current = assignmentId ? (state.selections.get(assignmentId) ?? emptySelection()) : emptySelection();
+  const required = new Set(selective && !attention && assignmentId ? current.selected : []);
+  const promised = handoff && state.reservations.get(handoff.id);
+  const admitted = new Set();
+  if (selective)
+    for (const selection of state.selections.values()) for (const ref of selection.selected) admitted.add(ref);
+  // Accepted return receipts are communication, independent of selected task evidence.
+  // Their ordinary active occurrence survives closure; compaction still owns its lifetime.
+  const full = new Map();
+  const structural = new Map();
+  const problems = selective && !attention && assignmentId ? [...current.unresolved] : [];
+  for (const item of associated) {
+    if (!item.source) continue;
+    if (
+      !selective ||
+      !isWorkerProfile(item.source.producer) ||
+      admitted.has(item.source.ref) ||
+      (item.source.reportHandoff && state.handoffs.has(item.source.reportHandoff))
+    )
+      full.set(item.source.ref, item.source);
+    const visible = sources.byRef.get(textRef(item.source.ref));
+    if (selective && visible && admitted.has(visible.ref)) full.set(visible.ref, visible);
+  }
+  for (const ref of required) {
+    if (sources.ambiguous.has(ref)) {
+      problems.push({
+        ref,
+        code: "ambiguous_occurrence",
+        detail: "The active representation cannot be associated with one canonical occurrence.",
+      });
+      continue;
+    }
+    const source = sources.byRef.get(ref),
+      error = sources.eligible(ref, state);
+    if (error) {
+      problems.push(error);
+      continue;
+    }
+    const expected =
+      promised && promised.selectionRevision === current.revision
+        ? promised.sources.find((s) => s.ref === ref)
+        : undefined;
+    if (expected && expected.bodyHash !== source.hash) {
+      problems.push({
+        ref,
+        code: "source_changed",
+        detail: "The captured source differs from the prepared reservation.",
+      });
+      continue;
+    }
+    full.set(ref, source);
+  }
+  // A selected result carries its complete native call group; siblings may be structural only.
+  for (const source of full.values()) {
+    const exchange = sources.exchange(source);
+    if (required.has(source.ref)) problems.push(...exchange.problems, ...representationProblems(source, options.model));
+    for (const sibling of exchange.sources) if (!full.has(sibling.ref)) structural.set(sibling.ref, sibling);
+  }
+  for (const source of structural.values())
+    if (source.message.role === "assistant" && required.size)
+      problems.push(...representationProblems(source, options.model, true));
+  const render = (source) => {
+    const message = structuredClone(source.message);
+    if (source.message.role === "assistant" && !full.has(source.ref) && full.has(textRef(source.ref)))
+      message.content = message.content.filter((b) => b.type !== "text");
+    if (full.has(source.ref) || source.message.role !== "toolResult") return message;
+    return {
+      ...structuredClone(source.message),
+      content: [{ type: "text", text: "[Worker result omitted from this view]" }],
+      details: undefined,
+    };
+  };
+  // Insert resolved historical occurrences before the first later native occurrence, retaining
+  // opaque/common messages in their original order rather than moving user input wholesale.
+  const ordered = sources.ordered(new Map([...structural, ...full]).values());
+  const rank = new Map(options.sources.entries.map((entry, index) => [entry.id, index]));
+  const activeRefs = new Set(associated.flatMap((i) => (i.source ? [i.source.ref] : [])));
+  const historical = ordered.filter((s) => !activeRefs.has(s.ref));
+  const emitted = new Set();
+  let messages = [];
+  const renderedSources = new Map();
+  let cursor = 0;
+  const emit = (source) => {
+    if (source.original && full.has(source.original.ref)) return;
+    if (!emitted.has(source.ref)) {
+      const message = render(source);
+      messages.push(message);
+      renderedSources.set(message, source);
+      emitted.add(source.ref);
+    }
+  };
+  for (const item of associated) {
+    if (item.source) {
+      while (
+        cursor < historical.length &&
+        (rank.get(historical[cursor].entry.id) ?? 0) < (rank.get(item.source.entry.id) ?? 0)
+      )
+        emit(historical[cursor++]);
+      const visible = full.get(textRef(item.source.ref));
+      if (visible) emit(visible);
+      if (full.has(item.source.ref) || structural.has(item.source.ref)) emit(item.source);
+    } else messages.push(item.message);
+  }
+  while (cursor < historical.length) emit(historical[cursor++]);
+  const fullSources = [...full.values()];
+  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 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, field, value, metadata = {}) =>
+    messages.some((m) => {
+      const matches = (payload) =>
+        payload?.[field] === value &&
+        Object.entries(metadata).every(([key, expected]) => canonical(payload?.[key]) === canonical(expected));
+      if (m.role === "assistant")
+        return m.content?.some((b) => b.type === "toolCall" && b.id === h.toolCallId && matches(b.arguments));
+      if (m.role !== "toolResult" || m.toolCallId !== h.toolCallId) return false;
+      return m.content?.some((b) => {
+        if (b.type !== "text") return false;
+        try {
+          return matches(JSON.parse(b.text));
+        } catch {
+          return false;
+        }
+      });
+    });
+  const restore = (kind, id, body) =>
+    messages.push({
+      role: "custom",
+      customType: "freeflow-routing-communication",
+      display: false,
+      content: `${kind} ${id}:\n${body}`,
+      timestamp: 0,
+      details: { routingInstance: options.instance },
+    });
+  if (a) {
+    const accepted = state.handoffs.get(a.delegateHandoffId);
+    if (accepted && !hasCommunication(accepted, "contract", a.contract))
+      restore("Current exact assignment", a.id, a.contract);
+  }
+  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(baseReport, "report", baseReport.text, {
+      ...metadata,
+      reportRevision: baseReport.reportRevision,
+      assignmentRef: `assignment:${baseReport.assignmentId}`,
+      reportRef: `report:${baseReport.id}:${baseReport.reportRevision}`,
+    });
+    if (!complete)
+      restore(
+        "Saved report",
+        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);
+  const { estimatedTokens, maximumInputTokens, outputReserve, estimateMethod, warnings } = estimateRequest(
+    options.systemPrompt,
+    options.tools,
+    messages,
+    options.model,
+  );
+  if (warnings.length)
+    messages.push({
+      role: "custom",
+      customType: "freeflow-routing-budget",
+      display: false,
+      content: warnings.map((w) => w.detail).join("\n"),
+      timestamp: 0,
+      details: { routingInstance: options.instance },
+    });
+  if (!options.model?.contextWindow)
+    problems.push({ ref: "", code: "delivery_budget", detail: "Receiving model context capacity is unavailable." });
+  const reservation =
+    handoff && selective
+      ? {
+          id: randomUUID(),
+          selectionRevision: current.revision,
+          receiver: "coordinator",
+          target: options.pair,
+          qualification: `native-structural:${options.model?.api ?? "unknown"}; serialized receipt unobserved`,
+          sources: [...required].flatMap((ref) => {
+            const source = sources.byRef.get(ref);
+            return source ? [{ ref, bodyHash: source.hash }] : [];
+          }),
+          maximumInputTokens,
+          outputReserve,
+          estimateMethod,
+        }
+      : undefined;
+  return {
+    warnings,
+    ready: problems.length === 0,
+    // Recorded usage describes a prior provider view, which may belong to the
+    // other profile. Pi must estimate this assembled view when allocating output.
+    // Normalize request metadata only; canonical usage/billing records stay intact.
+    messages: messages.map((message) => ({
+      ...message,
+      timestamp: Number.isFinite(message.timestamp) ? message.timestamp : 0,
+      ...(message.role === "assistant"
+        ? { usage: { ...message.usage, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 } }
+        : {}),
+    })),
+    problems,
+    fullSources,
+    reservation,
+    estimatedTokens,
+    estimateMethod,
+  };
+}