@hassangameryt/freeflow 0.7.2 → 0.8.0

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

@@ -0,0 +1,209 @@
+import { isObject } from "./types.js";
+const string = (maxLength = 32768, description) => ({
+  type: "string",
+  minLength: 1,
+  maxLength,
+  ...(description ? { description } : {}),
+});
+const object = (properties, required = Object.keys(properties), description, title) => ({
+  type: "object",
+  additionalProperties: false,
+  properties,
+  required,
+  ...(description ? { description } : {}),
+  ...(title ? { title } : {}),
+});
+const operation = (value, description) => ({
+  type: "string",
+  enum: [value],
+  ...(description ? { description } : {}),
+});
+const evidenceRefs = (description) => ({
+  type: "array",
+  maxItems: 64,
+  items: string(512),
+  description,
+});
+const worker = {
+  type: "string",
+  enum: ["helper", "executor"],
+  description: "Worker for this assignment. Required when delegation mode enables both workers.",
+};
+const report = (name) =>
+  object(
+    {
+      operation: operation(name),
+      report: string(),
+      outcome: { type: "string", enum: ["completed", "partial", "blocked"] },
+      limitations: { type: "array", maxItems: 32, items: string(2048) },
+    },
+    ["operation", "report", "outcome"],
+  );
+export const ROUTING_SCHEMAS = {
+  freeflow_delegate: {
+    oneOf: [
+      object({ operation: operation("assign"), contract: string(), worker }, ["operation", "contract"]),
+      object({ operation: operation("replace"), contract: string(), reason: string(2048), worker }, [
+        "operation",
+        "contract",
+        "reason",
+      ]),
+    ],
+  },
+  freeflow_return: { oneOf: [report("submit"), report("supplement"), object({ operation: operation("retry") })] },
+  freeflow_unit: {
+    oneOf: [
+      object(
+        {
+          operation: operation("inspect"),
+          view: { type: "string", enum: ["current", "history", "detail"] },
+          ref: string(128),
+          cursor: string(128),
+          limit: { type: "integer", minimum: 1, maximum: 100 },
+        },
+        ["operation"],
+      ),
+      object({ operation: operation("assess") }),
+      object(
+        {
+          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"],
+      ),
+      object({ operation: operation("cancel-recovery"), reason: string(2048) }),
+      object({
+        operation: operation("close"),
+        outcome: { type: "string", enum: ["accepted", "cancelled", "deferred"] },
+        assessment: string(),
+      }),
+    ],
+  },
+  freeflow_project: {
+    oneOf: [
+      object(
+        {
+          operation: operation("inspect", "Read current selection and offered evidence candidates."),
+          scope: {
+            type: "string",
+            enum: ["selected", "assignment", "active", "history"],
+            description: "Optional candidate scope; omit to inspect the current assignment.",
+          },
+          cursor: string(128, "Use the nextCursor returned by a previous inspection."),
+        },
+        ["operation"],
+        "Inspect selection and candidates without changing evidence state.",
+        "Inspect evidence selection",
+      ),
+      object(
+        {
+          operation: operation("add", "Select eligible worker task-evidence refs; do not include reason."),
+          refs: evidenceRefs(
+            "Exact eligible visible refs for worker task evidence. Add known eligible refs directly; inspect when identity, eligibility, representation, or selection state is unclear. Never add a ref marked not offered for new evidence selection.",
+          ),
+        },
+        ["operation", "refs"],
+        "Add evidence refs. This shape has no reason field.",
+        "Add evidence",
+      ),
+      object(
+        {
+          operation: operation("remove", "Withdraw selected or unresolved refs; reason is required."),
+          refs: evidenceRefs(
+            "Currently selected or unresolved refs to withdraw. A non-selectable ref may be removed with a reason to clear its unresolved request.",
+          ),
+          reason: string(2048, "Required only for remove; explain why the selection is being withdrawn."),
+        },
+        ["operation", "refs", "reason"],
+        "Remove evidence refs. This is the only operation that accepts reason.",
+        "Remove evidence",
+      ),
+    ],
+  },
+};
+// Provider function schemas require an object root. Keep operation-specific branches
+// for runtime validation without leaving the provider-facing root untyped.
+for (const schema of Object.values(ROUTING_SCHEMAS)) {
+  schema.type = "object";
+  schema.additionalProperties = false;
+  schema.required = ["operation"];
+  schema.properties = Object.assign({}, ...schema.oneOf.map((branch) => branch.properties));
+  schema.properties.operation = {
+    type: "string",
+    enum: schema.oneOf.flatMap((branch) => branch.properties.operation.enum),
+    description: "Choose exactly one operation; each operation has a strict shape and rejects unknown fields.",
+  };
+  if (schema.properties.refs)
+    schema.properties.refs = {
+      ...schema.properties.refs,
+      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;
+  if (schema.enum && !schema.enum.includes(value)) return false;
+  if (schema.type === "object")
+    return (
+      isObject(value) &&
+      Object.keys(value).every((k) => schema.properties[k]) &&
+      schema.required.every((k) => Object.hasOwn(value, k)) &&
+      Object.entries(value).every(([k, v]) => matches(v, schema.properties[k]))
+    );
+  if (schema.type === "string")
+    return (
+      typeof value === "string" &&
+      value.length >= (schema.minLength ?? 0) &&
+      value.length <= (schema.maxLength ?? Infinity) &&
+      (!schema.pattern || new RegExp(schema.pattern).test(value))
+    );
+  if (schema.type === "array")
+    return Array.isArray(value) && value.length <= schema.maxItems && value.every((v) => matches(v, schema.items));
+  if (schema.type === "integer")
+    return Number.isSafeInteger(value) && value >= schema.minimum && value <= schema.maximum;
+  return false;
+}

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

@@ -0,0 +1,221 @@
+import { randomUUID } from "node:crypto";
+import { Sources } from "./sources.js";
+import { ViewCache } from "./projection.js";
+import { pairFromProfile } from "./config.js";
+import { initialState } from "./state.js";
+import { RoutingError, isWorkerProfile, requireCondition as check, samePair, workersForDelegation } from "./types.js";
+import { cachedBranch } from "../host/branch.js";
+const STAGED_CONTROL = new Set(["control", "profile-overrides", "delegation-override"]);
+export const ROUTING_RECOVERY_HINT =
+  "Run /freeflow profile auto to reconcile routing, or /freeflow resume to continue saved work.";
+/**
+ * State and identity shared by every part of routing for one bound session: the event journal, the host
+ * context, the current turn, blocking errors, control mode, and the queue that orders control changes.
+ */
+export class RoutingSession {
+  store;
+  ctx;
+  capability;
+  token = randomUUID();
+  turn;
+  messages = [];
+  error;
+  projectionError;
+  suppressed = false;
+  operations = Promise.resolve();
+  revision = 0;
+  manualHold;
+  automaticControl = false;
+  sourceCache;
+  /** Rendered view messages reused across requests (see ViewCache); rebuilt after a rebind or ancestry change. */
+  viewCache = new ViewCache();
+  /** Replayed tool results for the current turn, keyed by operation id. */
+  receipts = new Map();
+  /** Recently served inspection pages, keyed by request; at most eight are kept. */
+  pages = new Map();
+  get projectionEnabled() {
+    return this.supported() && this.capability?.projection === true && this.stateData().control === "automatic";
+  }
+  /** Forgets everything derived for the current turn: its context view, sources, replay receipts, and pages. */
+  resetTurn() {
+    this.turn = undefined;
+    this.messages = [];
+    this.sourceCache = undefined;
+    this.viewCache = new ViewCache();
+    this.receipts.clear();
+    this.pages.clear();
+  }
+  subject() {
+    const branch = cachedBranch(this.store?.reader) ?? [];
+    return {
+      token: this.token,
+      revision: this.revision,
+      store: this.store,
+      leafId: branch.at(-1)?.id ?? null,
+      userId: branch.filter((e) => e.message?.role === "user").at(-1)?.id ?? null,
+    };
+  }
+  current(s) {
+    if (s.token !== this.token || s.revision !== this.revision || s.store !== this.store) return false;
+    const branch = cachedBranch(this.store?.reader) ?? [];
+    return (
+      (!s.leafId || branch.some((e) => e.id === s.leafId)) &&
+      (branch.filter((e) => e.message?.role === "user").at(-1)?.id ?? null) === s.userId
+    );
+  }
+  guard(s) {
+    check(
+      this.current(s),
+      "stale_operation",
+      "Routing state changed while the operation was waiting; no further effects applied.",
+    );
+  }
+  taskBasis(state, assignmentId) {
+    return state.resumeBasis.has(assignmentId)
+      ? state.resumeBasis.get(assignmentId)
+      : state.assignments.get(assignmentId)?.basisUserEntryId;
+  }
+  delegation(state = this.stateData()) {
+    return state.delegationOverride ?? this.capability?.delegation ?? "executor";
+  }
+  enabledWorkers(state = this.stateData()) {
+    return workersForDelegation(this.delegation(state));
+  }
+  assignedWorker(state, assignmentId = state.assignmentId) {
+    const assignment = assignmentId ? state.assignments.get(assignmentId) : undefined;
+    const handoff = assignment ? state.handoffs.get(assignment.delegateHandoffId) : undefined;
+    check(
+      handoff?.kind === "delegate" && handoff.assignmentId === assignment?.id && isWorkerProfile(handoff.to),
+      "assignment_worker_missing",
+      "The current assignment has no valid recorded worker.",
+    );
+    return handoff.to;
+  }
+  requiredProfiles(state = this.stateData(), delegation = this.delegation(state)) {
+    const profiles = new Set(["coordinator", ...workersForDelegation(delegation)]);
+    if (state.profile) profiles.add(state.profile);
+    if (this.manualHold) profiles.add(this.manualHold);
+    const assignment = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+    if (assignment?.state === "outstanding" || state.recoveryId) profiles.add(this.assignedWorker(state));
+    const pending = state.pendingId ? state.handoffs.get(state.pendingId) : undefined;
+    if (pending && isWorkerProfile(pending.to)) profiles.add(pending.to);
+    return [...profiles];
+  }
+  retireUnbound(reason) {
+    for (const execution of this.stateData().executions.values()) {
+      if (!execution.assistantEntryId && !execution.interrupted)
+        this.append({ type: "execution-interrupted", executionId: execution.id, reason });
+    }
+    this.turn = undefined;
+  }
+  openTurn() {
+    if (!this.turn || this.turn.opened) return;
+    const t = this.turn;
+    this.append({
+      type: "execution-opened",
+      execution: {
+        id: t.id,
+        profile: t.profile,
+        assignmentId: t.assignmentId,
+        recoveryId: t.recoveryId,
+        basisUserEntryId: t.basisUserEntryId,
+        pair: t.pair,
+        resultEntryIds: [],
+      },
+    });
+    t.opened = true;
+  }
+  stateData() {
+    return this.store?.state() ?? initialState();
+  }
+  sources(state = this.stateData()) {
+    const branch = cachedBranch(this.ctx.sessionManager);
+    const cache = this.sourceCache;
+    // The cached branch is the same array until the leaf moves, so an unchanged branch needs no filtering.
+    if (cache && cache.branch === branch && cache.authors === state.authors.size) return cache.source;
+    const entries = branch.filter((e) =>
+      ["message", "custom_message", "compaction", "branch_summary"].includes(e.type),
+    );
+    if (
+      cache &&
+      cache.authors === state.authors.size &&
+      entries.length === cache.entries.length &&
+      entries.every((e, i) => e === cache.entries[i])
+    ) {
+      cache.branch = branch;
+      return cache.source;
+    }
+    const active = this.ctx.sessionManager.buildContextEntries?.();
+    const activeIds = active ? new Set(active.map((e) => e.id)) : undefined;
+    const source = cache?.source ?? new Sources([], state);
+    source.refresh(entries, state, activeIds);
+    this.sourceCache = { branch, entries, authors: state.authors.size, source };
+    return source;
+  }
+  observed(ctx = this.ctx) {
+    return ctx?.model?.provider && ctx?.model?.id && ctx?.thinkingLevel
+      ? { provider: ctx.model.provider, modelId: ctx.model.id, thinking: ctx.thinkingLevel }
+      : undefined;
+  }
+  supported() {
+    return !!this.capability?.effective && !this.suppressed;
+  }
+  append(data, op, step) {
+    check(this.store, "routing_unavailable");
+    // Control changes made while no run is active affect no request until the next prompt; stage them there.
+    const stage = STAGED_CONTROL.has(data.type) && this.ctx?.isIdle?.() !== false;
+    return this.store.append(this.store.make(data, op, step), stage);
+  }
+  enqueue(action) {
+    const token = this.token;
+    const result = this.operations.then(() => {
+      check(token === this.token, "stale_instance");
+      return action();
+    });
+    this.operations = result.catch(() => {});
+    return result;
+  }
+  mark(error) {
+    if (this.error && error instanceof RoutingError && error.code === "routing_blocked") return;
+    this.error =
+      error instanceof RoutingError
+        ? `${error.code}: ${error.message}`
+        : error instanceof Error
+          ? error.message
+          : String(error);
+  }
+  announced;
+  // Tell the user once per distinct block; routing stays blocked until an explicit control clears it.
+  announceBlock(ctx) {
+    if (!this.error || this.announced === this.error) return;
+    this.announced = this.error;
+    ctx?.ui?.notify?.(`Cognitive Routing blocked: ${this.error}. ${ROUTING_RECOVERY_HINT}`, "warning");
+  }
+  assertAvailable(profile) {
+    check(
+      this.supported() && this.store && !this.error && !this.store.blocked,
+      "routing_unavailable",
+      this.error ?? this.store?.blocked ?? "Routing is inactive.",
+    );
+    const state = this.stateData();
+    check(state.control === "automatic", "manual_control");
+    if (profile) check(state.profile === profile && this.turn?.profile === profile, "wrong_profile");
+    if (state.profile) check(samePair(this.observed(), this.profilePair(state.profile)), "configuration_mismatch");
+  }
+  configuredProfilePair(profile) {
+    const configured = this.capability?.profiles[profile];
+    check(configured, "profile_missing");
+    return pairFromProfile(configured);
+  }
+  profilePair(profile) {
+    return this.stateData().profileOverrides.get(profile) ?? this.configuredProfilePair(profile);
+  }
+  profilePairs(profiles = this.requiredProfiles()) {
+    return Object.fromEntries(profiles.map((profile) => [profile, this.profilePair(profile)]));
+  }
+  workerBasis(state, assignmentId) {
+    const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
+    if (recovery?.state === "reading") return state.handoffs.get(recovery.requestHandoffId)?.basisUserEntryId ?? null;
+    return this.taskBasis(state, assignmentId);
+  }
+}