@hassangameryt/freeflow 0.5.0 → 0.7.0

package/pi-extension/src/cognitive-routing/tool.ts

@@ -0,0 +1,273 @@
+import type { CognitiveRoutingController, CognitiveRoutingSwitchResult } from "./controller.js";
+import { textComponent } from "../ui/text-component.js";
+import type { CognitiveRoutingHistoryOptions, CognitiveRoutingHistoryResult } from "./history.js";
+import type { CognitiveRoutingProfileName } from "./types.js";
+
+export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
+export const COGNITIVE_ROUTING_HISTORY_TOOL_NAME = "freeflow_cognitive_routing_history";
+
+export const COGNITIVE_ROUTING_HISTORY_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    scope: {
+      type: "string",
+      enum: ["session", "active-branch"],
+      description: "History scope to read.",
+    },
+    anomaliesOnly: {
+      type: "boolean",
+      description: "Return only events whose integrity is anomaly.",
+    },
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: 100,
+      description: "Maximum number of newest events to return.",
+    },
+  },
+  required: [],
+};
+
+export const COGNITIVE_ROUTING_SWITCH_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    target: {
+      type: "string",
+      enum: ["standard", "reasoning"],
+      description: "The configured Cognitive Routing profile to activate.",
+    },
+    reason: {
+      type: "string",
+      minLength: 1,
+      maxLength: 160,
+      description: "A concise one-line reason for the profile transition.",
+    },
+  },
+  required: ["target", "reason"],
+};
+
+type HistoryToolParams = {
+  scope?: unknown;
+  anomaliesOnly?: unknown;
+  limit?: unknown;
+};
+
+type HistoryReader = (
+  options: CognitiveRoutingHistoryOptions,
+  context?: unknown,
+) => CognitiveRoutingHistoryResult | Promise<CognitiveRoutingHistoryResult>;
+
+type SwitchToolParams = {
+  target?: unknown;
+  reason?: unknown;
+};
+
+type RenderedSwitchResult =
+  | {
+      status: "active";
+      profile: CognitiveRoutingProfileName;
+      changed?: boolean;
+      from?: CognitiveRoutingProfileName;
+      to?: CognitiveRoutingProfileName;
+    }
+  | { status: "blocked" | "inactive"; reason: string };
+
+function resultText(result: CognitiveRoutingSwitchResult): string {
+  if (result.status === "active") {
+    const fields = [COGNITIVE_ROUTING_SWITCH_TOOL_NAME + "|active", `profile|${result.profile}`];
+    if (result.changed !== undefined) fields.push(`changed|${result.changed}`);
+    if (result.from) fields.push(`from|${result.from}`);
+    if (result.to) fields.push(`to|${result.to}`);
+    return fields.join("\n");
+  }
+  return `${COGNITIVE_ROUTING_SWITCH_TOOL_NAME}|${result.status}\nreason|${result.reason}`;
+}
+
+function blocked(reason: string): CognitiveRoutingSwitchResult {
+  return { status: "blocked", reason };
+}
+
+function renderNothing() {
+  return {
+    render() {
+      return [];
+    },
+    invalidate() {},
+  };
+}
+
+function renderTransition(text: string, theme: any) {
+  return textComponent(theme?.fg ? theme.fg("accent", text) : text);
+}
+
+function isProfileName(value: unknown): value is CognitiveRoutingProfileName {
+  return value === "standard" || value === "reasoning";
+}
+
+function resultFromPayload(payload: any): RenderedSwitchResult | undefined {
+  const details = payload?.details?.result ?? payload?.result ?? payload?.details;
+  if (details && (details.status === "active" || details.status === "blocked" || details.status === "inactive")) {
+    if (details.status !== "active") return details as CognitiveRoutingSwitchResult;
+    if (!isProfileName(details.profile)) return undefined;
+    return {
+      status: "active",
+      profile: details.profile,
+      ...(typeof details.changed === "boolean" ? { changed: details.changed } : {}),
+      ...(isProfileName(details.from) ? { from: details.from } : {}),
+      ...(isProfileName(details.to) ? { to: details.to } : {}),
+    };
+  }
+
+  const text = Array.isArray(payload?.content)
+    ? payload.content.find((part: any) => part?.type === "text")?.text
+    : undefined;
+  if (typeof text !== "string") return undefined;
+  const fields = new Map<string, string>();
+  for (const line of text.split("\\n")) {
+    const separator = line.indexOf("|");
+    if (separator <= 0) continue;
+    fields.set(line.slice(0, separator), line.slice(separator + 1));
+  }
+  const status = fields.get(COGNITIVE_ROUTING_SWITCH_TOOL_NAME);
+  if (status === "active") {
+    const profile = fields.get("profile");
+    if (!isProfileName(profile)) return undefined;
+    const changed = fields.get("changed");
+    const from = fields.get("from");
+    const to = fields.get("to");
+    return {
+      status,
+      profile,
+      ...(changed === "true" || changed === "false" ? { changed: changed === "true" } : {}),
+      ...(isProfileName(from) ? { from } : {}),
+      ...(isProfileName(to) ? { to } : {}),
+    };
+  }
+  if (status === "blocked" || status === "inactive") {
+    const reason = fields.get("reason");
+    return reason ? { status, reason } : undefined;
+  }
+  return undefined;
+}
+
+function historyOptions(params: HistoryToolParams): CognitiveRoutingHistoryOptions {
+  return {
+    ...(params.scope === "active-branch" ? { scope: "active-branch" as const } : {}),
+    ...(params.anomaliesOnly === true ? { anomaliesOnly: true } : {}),
+    ...(Number.isInteger(params.limit) ? { limit: Math.max(1, Math.min(100, params.limit as number)) } : {}),
+  };
+}
+
+function validateParams(
+  params: SwitchToolParams,
+): { status: "valid"; target: CognitiveRoutingProfileName; reason: string } | { status: "invalid"; reason: string } {
+  if (params.target !== "standard" && params.target !== "reasoning") {
+    return { status: "invalid", reason: "target_must_be_standard_or_reasoning" };
+  }
+  if (typeof params.reason !== "string") {
+    return { status: "invalid", reason: "reason_required" };
+  }
+  const reason = params.reason.trim();
+  if (!reason) return { status: "invalid", reason: "reason_required" };
+  if (reason.includes("\n") || reason.includes("\r"))
+    return { status: "invalid", reason: "reason_must_be_single_line" };
+  if (reason.length > 160) return { status: "invalid", reason: "reason_too_long" };
+  return { status: "valid", target: params.target, reason };
+}
+
+export function registerCognitiveRoutingTool(
+  pi: {
+    registerTool(tool: Record<string, unknown>): void;
+  },
+  getController: () => CognitiveRoutingController | undefined,
+) {
+  pi.registerTool({
+    name: COGNITIVE_ROUTING_SWITCH_TOOL_NAME,
+    label: "Switch Cognitive Profile",
+    description: "Request one bounded Cognitive Routing profile transition while automatic control is active.",
+    promptSnippet: "Switch between the configured standard and reasoning profiles when the current task needs it.",
+    promptGuidelines: [
+      "Use only when the current task needs a different reasoning profile.",
+      "Give one concise sentence as the reason and make this the only tool call in the response.",
+      "Do not call this tool while a deterministic manual profile hold is active.",
+    ],
+    parameters: COGNITIVE_ROUTING_SWITCH_PARAMETERS,
+    executionMode: "sequential",
+    async execute(_toolCallId: string, params: SwitchToolParams, _signal: unknown, _onUpdate: unknown, _ctx: unknown) {
+      const controller = getController();
+      const input = validateParams(params ?? {});
+      let result: CognitiveRoutingSwitchResult;
+      if (input.status === "invalid") {
+        result = blocked(input.reason);
+      } else if (!controller) {
+        result = blocked("not_available");
+      } else if (!controller.state().effective) {
+        result = blocked("not_active");
+      } else if (controller.state().controlMode === "automatic") {
+        result = await controller.switchAutomaticProfile(input.target, input.reason);
+      } else {
+        result = blocked("manual_hold");
+      }
+      return {
+        content: [{ type: "text", text: resultText(result) }],
+        details: { result },
+      };
+    },
+    renderCall(_args: SwitchToolParams, _theme: any) {
+      return renderNothing();
+    },
+    renderResult(result: any, _options: any, theme: any) {
+      const outcome = resultFromPayload(result);
+      if (outcome?.status === "active") {
+        if (outcome.changed === true && outcome.from && outcome.to) {
+          return renderTransition(`Cognitive Routing: ${outcome.from} → ${outcome.to}`, theme);
+        }
+        if (outcome.changed === false && outcome.to) {
+          return renderTransition(`Cognitive Routing: ${outcome.to} (already active)`, theme);
+        }
+        return renderTransition(`Cognitive Routing: active · ${outcome.profile}`, theme);
+      }
+      if (outcome) {
+        return renderTransition(`Cognitive Routing: ${outcome.status} · ${outcome.reason}`, theme);
+      }
+      return renderTransition(`Cognitive Routing: ${result?.isError ? "error" : "result unavailable"}`, theme);
+    },
+  });
+}
+
+export function registerCognitiveRoutingHistoryTool(
+  pi: {
+    registerTool(tool: Record<string, unknown>): void;
+  },
+  readHistory: HistoryReader,
+) {
+  pi.registerTool({
+    name: COGNITIVE_ROUTING_HISTORY_TOOL_NAME,
+    label: "Read Cognitive Routing History",
+    description:
+      "Read the deterministic Cognitive Routing transition history without changing routing or session state.",
+    promptSnippet: "Inspect Cognitive Routing transition history when debugging or monitoring profile behavior.",
+    promptGuidelines: [
+      "Use only when debugging or monitoring Cognitive Routing is requested.",
+      "This tool is read-only and does not change profile, control, branch, or session state.",
+      "Use scope=active-branch to inspect only the current branch ancestry.",
+      "Use anomaliesOnly=true to inspect only integrity anomalies.",
+    ],
+    parameters: COGNITIVE_ROUTING_HISTORY_PARAMETERS,
+    async execute(
+      _toolCallId: string,
+      params: HistoryToolParams,
+      _signal: unknown,
+      _onUpdate: unknown,
+      context: unknown,
+    ) {
+      const result = await readHistory(historyOptions(params ?? {}), context);
+      return {
+        content: [{ type: "text", text: `Cognitive Routing history\n${JSON.stringify(result)}` }],
+        details: { result },
+      };
+    },
+  });
+}

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

@@ -0,0 +1,89 @@
+export const COGNITIVE_ROUTING_PROFILE_NAMES = ["standard", "reasoning"] as const;
+export const COGNITIVE_ROUTING_SESSION_START_CONTROLS = ["automatic", "manual"] as const;
+
+export type CognitiveRoutingProfileName = (typeof COGNITIVE_ROUTING_PROFILE_NAMES)[number];
+export type CognitiveRoutingSessionStartControl = (typeof COGNITIVE_ROUTING_SESSION_START_CONTROLS)[number];
+export type CognitiveRoutingThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type CognitiveRoutingConfigSource = "default" | "repository" | "personal";
+
+export interface CognitiveRoutingSessionStart {
+  control: CognitiveRoutingSessionStartControl;
+  profile: CognitiveRoutingProfileName;
+}
+
+export const DEFAULT_COGNITIVE_ROUTING_SESSION_START = {
+  control: "automatic",
+  profile: "reasoning",
+} as const satisfies CognitiveRoutingSessionStart;
+
+export interface CognitiveRoutingProfile {
+  provider: string;
+  model: string;
+  thinkingLevel: CognitiveRoutingThinkingLevel;
+}
+
+export interface CognitiveRoutingConfigError {
+  code:
+    | "invalid_block"
+    | "invalid_enabled"
+    | "invalid_profiles"
+    | "invalid_profile"
+    | "invalid_session_start"
+    | "unsupported_key";
+  message: string;
+  profile?: CognitiveRoutingProfileName;
+  source: "repository" | "personal";
+}
+
+export interface CognitiveRoutingConfigResolution {
+  configured: boolean;
+  valid: boolean;
+  enabled: boolean;
+  enabledSource: CognitiveRoutingConfigSource;
+  profiles: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingProfile>>;
+  profileSources: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingConfigSource>>;
+  sessionStart: CognitiveRoutingSessionStart;
+  sessionStartSources: {
+    control: CognitiveRoutingConfigSource;
+    profile: CognitiveRoutingConfigSource;
+  };
+  error?: CognitiveRoutingConfigError;
+}
+
+export type CognitiveRoutingBlockCode =
+  | "disabled"
+  | "config_invalid"
+  | "host_unsupported"
+  | "profile_missing"
+  | "profile_unavailable"
+  | "profile_unauthenticated"
+  | "profile_clamped"
+  | "profiles_identical"
+  | "runtime_disabled";
+
+export interface CognitiveRoutingBlockingReason {
+  code: CognitiveRoutingBlockCode;
+  message: string;
+  profile?: CognitiveRoutingProfileName;
+}
+
+export interface CognitiveRoutingResolvedProfile extends CognitiveRoutingProfile {
+  effectiveThinkingLevel: CognitiveRoutingThinkingLevel;
+}
+
+export interface CognitiveRoutingCapabilityState {
+  configured: boolean;
+  configValid: boolean;
+  enabled: boolean;
+  effective: boolean;
+  enabledSource: CognitiveRoutingConfigSource;
+  profiles: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingProfile>>;
+  profileSources: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingConfigSource>>;
+  sessionStart: CognitiveRoutingSessionStart;
+  sessionStartSources: {
+    control: CognitiveRoutingConfigSource;
+    profile: CognitiveRoutingConfigSource;
+  };
+  resolvedProfiles: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingResolvedProfile>>;
+  blockingReason: CognitiveRoutingBlockingReason;
+}

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

@@ -0,0 +1,111 @@
+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

@@ -0,0 +1,62 @@
+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}`;
+}