@hassangameryt/freeflow 0.7.3 → 0.9.0

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

@@ -1,62 +0,0 @@
-import { RoutingRuntime, ROUTING_TOOLS } from "./runtime.js";
-import { ROUTING_SCHEMAS, matches } 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 enabled worker execution. Explicit replace supersedes a quiescent outstanding assignment in the same unit.",
-  freeflow_return:
-    "Save or revise the actual assignment report, save an attached recovery supplement, or retry the current saved return without resubmitting text. Returning does not accept or close the unit.",
-  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.",
-};
-const guidance: Record<string, string[]> = {
-  freeflow_delegate: [
-    "freeflow_delegate is Coordinator-only under Automatic control. Put the contract in the input. Choose worker when both Helper and Executor are enabled; the sole worker is inferred otherwise. Use replace only for explicit same-unit replacement; do not supply IDs.",
-  ],
-  freeflow_return: [
-    "freeflow_return submit saves/revises the assignment report; supplement saves separate recovery communication; retry completes the current unchanged saved return without text. Stop ordinary task or recovery-read work after its communication is saved. 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 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.",
-  ],
-};
-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);
-  }
-}
-export function applyRoutingToolVisibility(pi: any, _runtime: RoutingRuntime, _available = true): void {
-  if (!pi.getActiveTools || !pi.setActiveTools) return;
-  const current = pi.getActiveTools();
-  const ordinary = current.filter(
-    (name: string) =>
-      !ROUTING_TOOLS.includes(name as any) &&
-      name !== "freeflow_switch_profile" &&
-      name !== "freeflow_cognitive_routing_history",
-  );
-  const next = [...ordinary, ...ROUTING_TOOLS];
-  if (JSON.stringify(next) !== JSON.stringify(current)) pi.setActiveTools(next);
-}

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

@@ -1,254 +0,0 @@
-export const ROUTING_ENTRY = "freeflow-routing-v2";
-export const ROUTING_MESSAGE = "freeflow-routing-v2-state";
-export const WORKER_PROFILES = ["helper", "executor"] as const;
-export const PROFILES = ["coordinator", ...WORKER_PROFILES] as const;
-export const DELEGATION_MODES = ["executor", "helper", "both"] as const;
-export const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
-export type WorkerProfile = (typeof WORKER_PROFILES)[number];
-export type Profile = (typeof PROFILES)[number];
-export type DelegationMode = (typeof DELEGATION_MODES)[number];
-export type Effort = (typeof EFFORTS)[number];
-export const isWorkerProfile = (value: unknown): value is WorkerProfile =>
-  WORKER_PROFILES.includes(value as WorkerProfile);
-export const workersForDelegation = (mode: DelegationMode): readonly WorkerProfile[] =>
-  mode === "both" ? WORKER_PROFILES : [mode];
-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 type HandoffKind = "delegate" | "return" | "recovery-request" | "recovery-return";
-export interface Handoff {
-  id: string;
-  kind: HandoffKind;
-  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;
-  recoveryId?: 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";
-  suspensionReason?: "recovery" | "user-attention" | "delivery-gap";
-  basisUserEntryId: string | null;
-  problems: Problem[];
-  reservation?: Reservation;
-}
-export interface Recovery {
-  id: string;
-  assignmentId: string;
-  assessmentHandoffId: string;
-  baseReportRevision: number;
-  request: string;
-  requestedPaths: string[];
-  paths: string[];
-  state: "requested" | "reading" | "returning" | "completed" | "cancelled";
-  requestHandoffId: string;
-  supplementHandoffId?: string;
-  supplementRevision: number;
-  cancellationReason?: string;
-}
-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: "profile-overrides"; overrides: Partial<Record<Profile, Pair | null>>; 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: "recovery-request-accepted"; recovery: Recovery; handoff: Handoff }
-  | { type: "recovery-supplement-accepted"; recoveryId: string; handoff: Handoff }
-  | { type: "recovery-cancelled"; recoveryId: string; reason: string }
-  | {
-      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>;
-  recoveries: Map<string, Recovery>;
-  recoveryId?: string;
-  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>;
-  profileOverrides: Map<Profile, Pair>;
-  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/context-virtualization/commands.ts

@@ -1,111 +0,0 @@
-import type { ContextStatus } from "./types.js";
-import type { ContextVirtualizationRuntime } from "./runtime.js";
-
-function formatStatus(
-  status: ContextStatus,
-  features: { contextVirtualization: boolean; conversationHistory: boolean },
-): string {
-  if (!status.available) {
-    return `Freeflow Context: unavailable${status.unavailableReason ? ` (${status.unavailableReason})` : ""}`;
-  }
-  return [
-    "Freeflow Context: available",
-    `Context Virtualization: ${features.contextVirtualization ? "enabled" : "disabled"}`,
-    `Conversation History: ${features.conversationHistory ? "enabled" : "disabled"}`,
-    `Session: ${status.sessionId}`,
-    `Branch: ${status.branchLeafId ?? "root"}`,
-    `Projections: full=${status.counts.full}, archived=${status.counts.archived}, retained=${status.counts.retained}`,
-    `Characters: original=${status.originalCharacters.toLocaleString("en-US")}, projected=${status.projectedCharacters.toLocaleString("en-US")}`,
-    `Availability: history-only=${status.historyOnly}, unresolved=${status.unresolved}`,
-  ].join("\n");
-}
-
-function formatList(status: ContextStatus): string {
-  if (!status.available) return formatStatus(status, { contextVirtualization: true, conversationHistory: false });
-  const items = status.items.filter((item) => item.mode === "archived");
-  if (items.length === 0) return "Context Virtualization: no archived projections in the active session branch.";
-
-  const lines = ["Context Virtualization: archived projections"];
-  for (const item of items) {
-    lines.push(
-      "",
-      `Ref: ${item.ref}`,
-      `Tool: ${item.toolName ?? "tool"}`,
-      `State: ${item.retained === undefined ? "archived" : "retained"}`,
-      `Original: ${item.originalCharacters.toLocaleString("en-US")} characters`,
-      `Projected: ${item.projectedCharacters.toLocaleString("en-US")} characters`,
-      `Availability: ${item.availability}`,
-    );
-    if (item.retained !== undefined) lines.push(`Retained: ${item.retained}`);
-  }
-  return lines.join("\n");
-}
-
-function refsFromArgs(args: string): string[] {
-  return args
-    .split(/[\s,]+/)
-    .map((value) => value.trim())
-    .filter(Boolean);
-}
-
-export async function handleContextCommand(
-  args: string | undefined,
-  ctx: any,
-  runtime: ContextVirtualizationRuntime | undefined,
-  enabled: boolean,
-  conversationHistoryEnabled = false,
-) {
-  const input = (args ?? "status").trim();
-  const [action = "status", ...rest] = input.split(/\s+/);
-  const normalized = action.toLowerCase();
-
-  if (!runtime) {
-    ctx.ui.notify("Context Virtualization is unavailable for this session.", "warning");
-    return { changed: false, error: "unavailable" };
-  }
-
-  if (normalized === "status") {
-    const status = await runtime.status();
-    ctx.ui.notify(
-      formatStatus(status, { contextVirtualization: enabled, conversationHistory: conversationHistoryEnabled }),
-      enabled || conversationHistoryEnabled ? "info" : "warning",
-    );
-    return { changed: false, status };
-  }
-
-  if (normalized === "list") {
-    const status = await runtime.status();
-    ctx.ui.notify(formatList(status), enabled ? "info" : "warning");
-    return { changed: false, status };
-  }
-
-  if (normalized === "restore") {
-    const refs = refsFromArgs(rest.join(" "));
-    if (!enabled) {
-      ctx.ui.notify("Context Virtualization is disabled by configuration; no projection state was changed.", "warning");
-      return { changed: false, error: "disabled" };
-    }
-    const result = await runtime.restore(refs, "user");
-    ctx.ui.notify(
-      result.message ?? `${result.status}: ${result.operation}`,
-      result.status === "ok" ? "info" : "warning",
-    );
-    return { changed: result.status === "ok", result };
-  }
-
-  if (normalized === "reset" && rest.join(" ").toLowerCase() === "all") {
-    if (!enabled) {
-      ctx.ui.notify("Context Virtualization is disabled by configuration; no projection state was changed.", "warning");
-      return { changed: false, error: "disabled" };
-    }
-    const result = await runtime.reset();
-    ctx.ui.notify(
-      result.message ?? `${result.status}: ${result.operation}`,
-      result.status === "ok" ? "info" : "warning",
-    );
-    return { changed: result.status === "ok", result };
-  }
-
-  ctx.ui.notify("Usage: /freeflow context [status|list|restore <ctx:entryId>...|reset all]", "warning");
-  return { changed: false, error: "invalid_action" };
-}

package/pi-extension/src/context-virtualization/projector.ts

@@ -1,62 +0,0 @@
-import { CONTEXT_REF_PREFIX, contextRefForEntry, type ContextProjection, type ContextSourceIdentity } from "./types.js";
-
-export function contentCharacters(content: unknown): number {
-  if (typeof content === "string") return content.length;
-  if (!Array.isArray(content)) return 0;
-  return content.reduce((total, part) => {
-    if (part?.type === "text" && typeof part.text === "string") return total + part.text.length;
-    if (part?.type === "image") return total + 16;
-    return total;
-  }, 0);
-}
-
-export function contextMarker(source: ContextSourceIdentity): { type: "text"; text: string } {
-  return {
-    type: "text",
-    text: `[context-ref: ${contextRefForEntry(source.entryId)}]`,
-  };
-}
-
-export function archiveContent(source: ContextSourceIdentity, retained?: string): string {
-  const marker = `[context archived: ${contextRefForEntry(source.entryId)}]`;
-  if (!retained) return marker;
-  return `${marker}\n\n<retained-context>\n${retained}\n</retained-context>`;
-}
-
-export function fullContent(source: ContextSourceIdentity, content: unknown[] = []): any[] {
-  return [...content, contextMarker(source)];
-}
-
-export function projectedContent(
-  source: ContextSourceIdentity,
-  content: unknown,
-  projection: ContextProjection,
-): any[] {
-  if (projection.mode === "archived") {
-    return [{ type: "text", text: archiveContent(source, projection.retained) }];
-  }
-  return fullContent(source, Array.isArray(content) ? content : [{ type: "text", text: String(content ?? "") }]);
-}
-
-export function projectToolResultMessage(
-  message: any,
-  source: ContextSourceIdentity,
-  projection: ContextProjection,
-): any {
-  return {
-    ...message,
-    content: projectedContent(source, message.content, projection),
-  };
-}
-
-export function projectedCharacters(
-  source: ContextSourceIdentity,
-  message: any,
-  projection: ContextProjection,
-): number {
-  return contentCharacters(projectedContent(source, message?.content, projection));
-}
-
-export function sourceReference(source: ContextSourceIdentity): string {
-  return `${CONTEXT_REF_PREFIX}${source.entryId}`;
-}