@hassangameryt/freeflow 0.7.0 → 0.7.2

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

@@ -0,0 +1,93 @@
+import { RoutingRuntime, ROUTING_TOOLS } from "./runtime.js";
+import { ROUTING_SCHEMAS, matches, schemaForProfile } from "./schemas.js";
+export { ROUTING_SCHEMAS } from "./schemas.js";
+import { renderRoutingCall, renderRoutingResult } from "./render.js";
+
+const descriptions: Record<string, string> = {
+  freeflow_delegate:
+    "Save a supported assignment contract and request Executor execution. Explicit replace supersedes a quiescent outstanding assignment in the same unit.",
+  freeflow_return:
+    "Save or revise the actual assignment report, or retry its saved handoff without resubmitting text. Returning does not accept or close the unit.",
+  freeflow_unit:
+    "Inspect current responsibility, paginated work history, or exact saved contract/report details. Coordinator can also restore a suspended assessment or close a unit without clearing its history.",
+  freeflow_project:
+    "Inspect current selection and scoped candidates, then add or remove completed exposed Executor sources. #text refs select exact visible assistant text; plain refs retain whole-native meaning. Eligibility and target readiness are distinct.",
+};
+const guidance: Record<string, string[]> = {
+  freeflow_delegate: [
+    "freeflow_delegate is Coordinator-only under Automatic control. Put the contract in the input. Use replace only for explicit same-unit replacement; do not supply IDs.",
+  ],
+  freeflow_return: [
+    "freeflow_return submit saves/revises the actual report; retry completes the saved return without text. Stop ordinary task work after reportSaved. Keep the handoff last; do not batch it with new task tools.",
+  ],
+  freeflow_unit: [
+    "freeflow_unit inspect defaults to current state; view history returns work refs and view detail with ref reads saved contracts/reports. Coordinator assess restores a suspended evidence obligation; close changes work status without clearing communication or completing a Working Record task.",
+  ],
+  freeflow_project: [
+    "freeflow_project inspect shows selection and scoped candidates. Use history scope for earlier exposed evidence. #text refs select exact visible assistant text; 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.",
+  ],
+};
+const unitDefinitions = new WeakMap<object, { definition: any; signature?: string }>();
+export function registerRoutingTools(pi: any, runtime: RoutingRuntime): void {
+  for (const name of ROUTING_TOOLS) {
+    const definition = {
+      name,
+      label: name.replace("freeflow_", "Routing "),
+      description: descriptions[name],
+      parameters: ROUTING_SCHEMAS[name],
+      executionMode: "sequential",
+      promptGuidelines: guidance[name],
+      renderCall: (args: any, _theme: any, context: any) => renderRoutingCall(name, args, context),
+      renderResult: (result: any, options: any, _theme: any, context: any) =>
+        renderRoutingResult(result, options, name, context),
+      async execute(id: string, input: unknown, signal: AbortSignal, _update: unknown, ctx: any) {
+        if (!matches(input, ROUTING_SCHEMAS[name]))
+          throw new Error("Invalid routing arguments; no operation accepted.");
+        return runtime.invoke(name, id, input, signal, ctx);
+      },
+    };
+    pi.registerTool(definition);
+    if (name === "freeflow_unit") unitDefinitions.set(pi, { definition });
+  }
+}
+export function applyRoutingToolVisibility(pi: any, runtime: RoutingRuntime, available: boolean): void {
+  if (!pi.getActiveTools || !pi.setActiveTools) return;
+  const current = new Set<string>(pi.getActiveTools());
+  const state = runtime.state();
+  const unit = unitDefinitions.get(pi);
+  const coordinator = state.effective && state.controlMode === "automatic" && state.activeProfile === "coordinator";
+  const signature = coordinator ? "coordinator" : "inspection";
+  if (unit && unit.signature !== signature) {
+    pi.registerTool({
+      ...unit.definition,
+      description: coordinator
+        ? unit.definition.description
+        : "Inspect current routing responsibility, work history, or exact saved contract/report detail. This profile cannot assess or close units.",
+      promptGuidelines: coordinator
+        ? unit.definition.promptGuidelines
+        : [
+            "freeflow_unit inspect reads current state, view history lists work refs, and view detail with ref reads historical communication. Historical content is not current permission.",
+          ],
+      parameters: schemaForProfile("freeflow_unit", coordinator),
+    });
+    unit.signature = signature;
+  }
+  for (const name of ROUTING_TOOLS) {
+    const enabled =
+      available &&
+      (name === "freeflow_unit" ||
+        (state.effective &&
+          state.controlMode === "automatic" &&
+          (name === "freeflow_delegate"
+            ? state.activeProfile === "coordinator"
+            : state.activeProfile === "executor"))) &&
+      (name !== "freeflow_project" || runtime.projectionEnabled);
+    if (enabled) current.add(name);
+    else current.delete(name);
+  }
+  // Retired experimental tools must never remain available beside the replacement.
+  current.delete("freeflow_switch_profile");
+  current.delete("freeflow_cognitive_routing_history");
+  const next = [...current];
+  if (JSON.stringify(next) !== JSON.stringify(pi.getActiveTools())) pi.setActiveTools(next);
+}

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

@@ -0,0 +1,222 @@
+export const ROUTING_ENTRY = "freeflow-routing-v2";
+export const ROUTING_MESSAGE = "freeflow-routing-v2-state";
+export const PROFILES = ["coordinator", "executor"] as const;
+export const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type Profile = (typeof PROFILES)[number];
+export type Effort = (typeof EFFORTS)[number];
+export type View = Profile | "solo";
+export type Control = "automatic" | "manual" | "inactive";
+export type Delivery = "pending" | "blocked" | "configured" | "superseded";
+export interface Pair {
+  provider: string;
+  modelId: string;
+  thinking: Effort;
+}
+export interface Unit {
+  id: string;
+  objective: string;
+  state: "open" | "closed";
+  assignmentIds: string[];
+  disposition?: string;
+  assessment?: string;
+}
+export interface Assignment {
+  id: string;
+  unitId: string;
+  contract: string;
+  basisUserEntryId: string | null;
+  state: "outstanding" | "returned" | "superseded";
+  delegateHandoffId: string;
+  returnHandoffId?: string;
+}
+export interface Handoff {
+  id: string;
+  kind: "delegate" | "return";
+  assignmentId: string;
+  text: string;
+  from: Profile;
+  to: Profile;
+  executionId: string;
+  toolCallId: string;
+  basisUserEntryId: string | null;
+  state: Delivery;
+  reportRevision: number;
+  outcome?: "completed" | "partial" | "blocked";
+  limitations: string[];
+  reason?: string;
+}
+export interface Problem {
+  ref: string;
+  code: string;
+  detail: string;
+}
+export interface Selection {
+  revision: number;
+  selected: string[];
+  unresolved: Problem[];
+  withdrawals: { ref: string; reason: string }[];
+}
+export interface Reservation {
+  id: string;
+  selectionRevision: number;
+  receiver: Profile;
+  target: Pair;
+  qualification: string;
+  sources: { ref: string; bodyHash: string }[];
+  maximumInputTokens: number;
+  outputReserve: number;
+  estimateMethod: string;
+}
+export interface Execution {
+  id: string;
+  profile: View;
+  assignmentId?: string;
+  basisUserEntryId: string | null;
+  pair: Pair;
+  assistantEntryId?: string;
+  resultEntryIds: string[];
+  outcome?: "completed" | "failed" | "aborted";
+  interrupted?: string;
+}
+export interface Assessment {
+  handoffId: string;
+  assignmentId: string;
+  view: "active" | "suspended";
+  basisUserEntryId: string | null;
+  problems: Problem[];
+  reservation?: Reservation;
+}
+export type EventData =
+  | { type: "execution-interrupted"; executionId: string; reason: string }
+  | { type: "assignment-resumed"; assignmentId: string; basisUserEntryId: string | null }
+  | { type: "control"; control: Control; profile?: Profile; reason: string }
+  | { type: "execution-opened"; execution: Execution }
+  | {
+      type: "execution-bound";
+      executionId: string;
+      assistantEntryId: string;
+      resultEntryIds: string[];
+      outcome: "completed" | "failed" | "aborted";
+    }
+  | {
+      type: "delegate-accepted";
+      unit: Unit;
+      assignment: Assignment;
+      handoff: Handoff;
+      replacement?: { assignmentId: string; supersededHandoffId?: string; reason: string };
+    }
+  | { type: "return-accepted"; handoff: Handoff }
+  | {
+      type: "handoff-retry-requested";
+      handoffId: string;
+      attemptId: string;
+      executionId: string;
+      toolCallId: string;
+      reportRevision: number;
+      selectionRevision: number;
+    }
+  | { type: "handoff-prepared"; handoffId: string; reservation: Reservation }
+  | { type: "handoff-state"; handoffId: string; state: Delivery; reason?: string; observedPair?: Pair }
+  | { type: "selection-changed"; assignmentId: string; selection: Selection }
+  | {
+      type: "assessment-suspended";
+      handoffId: string;
+      reason: "user-attention" | "delivery-gap";
+      basisUserEntryId: string | null;
+      problems: Problem[];
+    }
+  | { type: "assessment-resumed"; handoffId: string; basisUserEntryId: string | null; reservation: Reservation }
+  | {
+      type: "unit-closed";
+      unitId: string;
+      outcome: "accepted" | "cancelled" | "deferred";
+      assessment: string;
+      supersededAssignmentId?: string;
+    }
+  | { type: "sources-exposed"; executionId: string; view: View; sources: { ref: string; bodyHash: string }[] }
+  | {
+      type: "request-observed";
+      executionId: string;
+      profile: View;
+      boundary: "assembled" | "payload-hook";
+      manifestHash: string;
+      handoffId?: string;
+      selectionRevision?: number;
+    };
+export interface RoutingEvent {
+  version: 2;
+  eventId: string;
+  operationId: string;
+  stepId: string;
+  recordedSessionId: string;
+  data: EventData;
+}
+export interface NativeEntry {
+  id: string;
+  parentId: string | null;
+  type: string;
+  customType?: string;
+  data?: unknown;
+  message?: any;
+  [key: string]: any;
+}
+export interface State {
+  control: Control;
+  profile?: Profile;
+  unitId?: string;
+  assignmentId?: string;
+  pendingId?: string;
+  units: Map<string, Unit>;
+  assignments: Map<string, Assignment>;
+  handoffs: Map<string, Handoff>;
+  executions: Map<string, Execution>;
+  selections: Map<string, Selection>;
+  reservations: Map<string, Reservation>;
+  attempts: Map<string, { executionId: string; reportRevision: number; selectionRevision: number }>;
+  exposure: Map<string, string>;
+  authors: Map<string, { profile: View; executionId: string; assignmentId?: string }>;
+  resumeBasis: Map<string, string | null>;
+  assessment?: Assessment;
+  events: Map<string, RoutingEvent>;
+  eventIds: Map<string, string>;
+}
+export class RoutingError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly problems: Problem[] = [],
+  ) {
+    super(message);
+    this.name = "RoutingError";
+  }
+}
+export function fail(code: string, message: string): never {
+  throw new RoutingError(code, message);
+}
+export function requireCondition(condition: unknown, code: string, message = code): asserts condition {
+  if (!condition) fail(code, message);
+}
+export function isObject(value: unknown): value is Record<string, any> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function canonical(value: unknown): string {
+  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: Pair | undefined, right: Pair | undefined): boolean {
+  return !!left && !!right && canonical(left) === canonical(right);
+}
+export const eventKey = (event: RoutingEvent) => JSON.stringify([event.operationId, event.data.type, event.stepId]);
+export const eventValue = (event: RoutingEvent) =>
+  canonical({ version: event.version, operationId: event.operationId, stepId: event.stepId, data: event.data });
+export const emptySelection = (): Selection => ({ revision: 0, selected: [], unresolved: [], withdrawals: [] });
+export const refFor = (id: string) => `ctx:${id}`;
+export function idFor(ref: string): string | undefined {
+  return /^ctx:([^\s:#]+)(?:#text)?$/.exec(ref)?.[1];
+}

package/pi-extension/src/freeflow-context/tool.ts

@@ -105,6 +105,11 @@ function contextParameters(features: ContextFeatureFlags) {
       operationSchema(CONVERSATION_HISTORY_RETRIEVE_PROPERTIES, ["operation", "refs"]),
     );
   }
+  if (oneOf.length === 0) {
+    // Codex rejects an empty oneOf even when the tool is inactive. Keep the
+    // placeholder schema valid until capability-specific operations are enabled.
+    return { type: "object", additionalProperties: false, properties: {} };
+  }
   return { type: "object", oneOf };
 }