@hassangameryt/freeflow 0.4.0 → 0.6.0

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

@@ -0,0 +1,172 @@
+import {
+  COGNITIVE_ROUTING_PROFILE_NAMES,
+  type CognitiveRoutingBlockingReason,
+  type CognitiveRoutingConfigResolution,
+  type CognitiveRoutingProfileName,
+  type CognitiveRoutingResolvedProfile,
+  type CognitiveRoutingThinkingLevel,
+} from "./types.js";
+
+const THINKING_LEVEL_ORDER: CognitiveRoutingThinkingLevel[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+const THINKING_LEVELS = new Set(THINKING_LEVEL_ORDER);
+
+interface ModelRegistryHost {
+  find(provider: string, modelId: string): unknown;
+  getApiKeyAndHeaders(model: unknown): Promise<{ ok: boolean; error?: string }>;
+  clampThinkingLevel(model: unknown, level: CognitiveRoutingThinkingLevel): CognitiveRoutingThinkingLevel;
+}
+
+function modelRegistry(host: unknown): ModelRegistryHost | undefined {
+  if (!host || typeof host !== "object") return undefined;
+  const hostRecord = host as Record<string, unknown>;
+  const candidateValue = hostRecord.modelRegistry ?? hostRecord;
+  if (!candidateValue || typeof candidateValue !== "object") return undefined;
+  const candidate = candidateValue as Record<string, unknown>;
+  if (
+    typeof candidate.find !== "function" ||
+    typeof candidate.getApiKeyAndHeaders !== "function" ||
+    typeof candidate.clampThinkingLevel !== "function"
+  ) {
+    return undefined;
+  }
+  return candidate as unknown as ModelRegistryHost;
+}
+
+function blocking(
+  code: CognitiveRoutingBlockingReason["code"],
+  message: string,
+  profile?: CognitiveRoutingProfileName,
+): CognitiveRoutingBlockingReason {
+  return { code, message, ...(profile ? { profile } : {}) };
+}
+
+function modelIdentity(model: unknown): string | undefined {
+  if (!model || typeof model !== "object") return undefined;
+  const provider = "provider" in model ? model.provider : undefined;
+  const id = "id" in model ? model.id : undefined;
+  return typeof provider === "string" && typeof id === "string" ? `${provider}/${id}` : undefined;
+}
+
+function isWeakened(requested: CognitiveRoutingThinkingLevel, effective: CognitiveRoutingThinkingLevel): boolean {
+  const requestedIndex = THINKING_LEVEL_ORDER.indexOf(requested);
+  const effectiveIndex = THINKING_LEVEL_ORDER.indexOf(effective);
+  return effectiveIndex >= 0 && requestedIndex >= 0 && effectiveIndex < requestedIndex;
+}
+
+export interface CognitiveRoutingPreflightResult {
+  effective: boolean;
+  resolvedProfiles: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingResolvedProfile>>;
+  blockingReason?: CognitiveRoutingBlockingReason;
+}
+
+export async function preflightCognitiveRoutingProfiles(
+  config: CognitiveRoutingConfigResolution,
+  host: unknown,
+): Promise<CognitiveRoutingPreflightResult> {
+  const registry = modelRegistry(host);
+  if (!registry) {
+    return {
+      effective: false,
+      resolvedProfiles: {},
+      blockingReason: blocking("host_unsupported", "Pi does not expose the required Cognitive Routing host controls"),
+    };
+  }
+
+  const resolvedProfiles: Partial<Record<CognitiveRoutingProfileName, CognitiveRoutingResolvedProfile>> = {};
+  const resolvedIdentities: Partial<Record<CognitiveRoutingProfileName, string>> = {};
+  for (const name of COGNITIVE_ROUTING_PROFILE_NAMES) {
+    const profile = config.profiles[name];
+    if (!profile) {
+      return {
+        effective: false,
+        resolvedProfiles,
+        blockingReason: blocking("profile_missing", `Cognitive Routing profile is missing: ${name}`, name),
+      };
+    }
+
+    const model = registry.find(profile.provider, profile.model);
+    if (!model) {
+      return {
+        effective: false,
+        resolvedProfiles,
+        blockingReason: blocking(
+          "profile_unavailable",
+          `Cognitive Routing profile is unavailable: ${profile.provider}/${profile.model}`,
+          name,
+        ),
+      };
+    }
+    let auth: { ok: boolean; error?: string };
+    try {
+      auth = await registry.getApiKeyAndHeaders(model);
+    } catch (error) {
+      auth = { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    if (!auth.ok) {
+      return {
+        effective: false,
+        resolvedProfiles,
+        blockingReason: blocking(
+          "profile_unauthenticated",
+          `Cognitive Routing profile is not authenticated: ${profile.provider}/${profile.model}${auth.error ? ` (${auth.error})` : ""}`,
+          name,
+        ),
+      };
+    }
+
+    const effectiveThinkingLevel = registry.clampThinkingLevel(model, profile.thinkingLevel);
+    if (!THINKING_LEVELS.has(effectiveThinkingLevel)) {
+      return {
+        effective: false,
+        resolvedProfiles,
+        blockingReason: blocking(
+          "host_unsupported",
+          `Pi returned an invalid effective thinking level for ${profile.provider}/${profile.model}`,
+          name,
+        ),
+      };
+    }
+    if (isWeakened(profile.thinkingLevel, effectiveThinkingLevel)) {
+      return {
+        effective: false,
+        resolvedProfiles,
+        blockingReason: blocking(
+          "profile_clamped",
+          `Cognitive Routing profile is weakened by thinking-level clamping: ${profile.provider}/${profile.model}`,
+          name,
+        ),
+      };
+    }
+
+    resolvedProfiles[name] = {
+      ...profile,
+      effectiveThinkingLevel,
+    };
+    resolvedIdentities[name] = modelIdentity(model);
+  }
+
+  const standard = resolvedProfiles.standard;
+  const reasoning = resolvedProfiles.reasoning;
+  if (
+    standard &&
+    reasoning &&
+    resolvedIdentities.standard === resolvedIdentities.reasoning &&
+    standard.effectiveThinkingLevel === reasoning.effectiveThinkingLevel
+  ) {
+    return {
+      effective: false,
+      resolvedProfiles,
+      blockingReason: blocking("profiles_identical", "Cognitive Routing profiles resolve to the same effective pair"),
+    };
+  }
+
+  return { effective: true, resolvedProfiles };
+}

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

@@ -0,0 +1,57 @@
+import { resolveCognitiveRoutingConfig } from "./config.js";
+import { preflightCognitiveRoutingProfiles } from "./host.js";
+import type {
+  CognitiveRoutingBlockingReason,
+  CognitiveRoutingCapabilityState,
+  CognitiveRoutingConfigResolution,
+} from "./types.js";
+
+function blockingReason(code: CognitiveRoutingBlockingReason["code"], message: string): CognitiveRoutingBlockingReason {
+  return { code, message };
+}
+
+function baseState(config: CognitiveRoutingConfigResolution): CognitiveRoutingCapabilityState {
+  return {
+    configured: config.configured,
+    configValid: config.valid,
+    enabled: config.enabled,
+    effective: false,
+    enabledSource: config.enabledSource,
+    profiles: config.profiles,
+    profileSources: config.profileSources,
+    sessionStart: config.sessionStart,
+    sessionStartSources: config.sessionStartSources,
+    resolvedProfiles: {},
+    blockingReason: blockingReason("disabled", "Cognitive Routing is disabled"),
+  };
+}
+
+export async function resolveCognitiveRoutingState(
+  repositoryConfig: unknown,
+  personalConfig: unknown,
+  host: unknown,
+): Promise<CognitiveRoutingCapabilityState> {
+  const config = resolveCognitiveRoutingConfig(repositoryConfig, personalConfig);
+  const state = baseState(config);
+
+  if (!config.valid) {
+    return {
+      ...state,
+      blockingReason: blockingReason(
+        "config_invalid",
+        config.error?.message ?? "Cognitive Routing configuration is invalid",
+      ),
+    };
+  }
+  if (!config.enabled) {
+    return state;
+  }
+
+  const preflight = await preflightCognitiveRoutingProfiles(config, host);
+  return {
+    ...state,
+    effective: preflight.effective,
+    resolvedProfiles: preflight.resolvedProfiles,
+    blockingReason: preflight.blockingReason ?? blockingReason("disabled", "Cognitive Routing is not effective"),
+  };
+}

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

@@ -0,0 +1,272 @@
+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,
+    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: "standard",
+} 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;
+}