@hassangameryt/freeflow 0.7.3 → 0.9.0

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

@@ -1,53 +0,0 @@
-import { entryIdFromContextRef, isFreeflowContextToolName } from "./types.js";
-import type { ResolvedContextEntry } from "./types.js";
-
-export type ContextVisibilityOptions = {
-  contextVirtualizationEnabled: boolean;
-  isSourceFullyProjected?: (entryId: string) => boolean;
-};
-
-export type ContextVisibilitySnapshot = {
-  activeEntryIds: Set<string>;
-  visibleEntryIds: Set<string>;
-  visibleSourceIds: Set<string>;
-  materializedSourceIds: Set<string>;
-};
-
-function isFullyVisible(source: ResolvedContextEntry | undefined, options: ContextVisibilityOptions): boolean {
-  if (source?.kind !== "toolResult" || !options.contextVirtualizationEnabled) return true;
-  return options.isSourceFullyProjected?.(source.source.entryId) ?? true;
-}
-
-function materializedRefs(entry: any): string[] {
-  const result = entry?.message?.details?.result ?? entry?.details?.result;
-  if (result?.operation !== "retrieve" || !Array.isArray(result.items)) return [];
-  return result.items
-    .map((item: any) => entryIdFromContextRef(item?.ref))
-    .filter((entryId: string | undefined): entryId is string => entryId !== undefined);
-}
-
-export function buildContextVisibility(
-  activeEntries: readonly any[],
-  resolvedByEntryId: ReadonlyMap<string, ResolvedContextEntry>,
-  options: ContextVisibilityOptions,
-): ContextVisibilitySnapshot {
-  const activeEntryIds = new Set<string>();
-  const visibleEntryIds = new Set<string>();
-  const visibleSourceIds = new Set<string>();
-  const materializedSourceIds = new Set<string>();
-
-  for (const entry of activeEntries) {
-    if (typeof entry?.id !== "string") continue;
-    activeEntryIds.add(entry.id);
-    const source = resolvedByEntryId.get(entry.id);
-    if (!isFullyVisible(source, options)) continue;
-    visibleEntryIds.add(entry.id);
-    if (source && source.kind !== "custom") visibleSourceIds.add(entry.id);
-
-    if (source?.kind === "toolResult" && isFreeflowContextToolName(source.message?.toolName)) {
-      for (const entryId of materializedRefs(entry)) materializedSourceIds.add(entryId);
-    }
-  }
-
-  return { activeEntryIds, visibleEntryIds, visibleSourceIds, materializedSourceIds };
-}

package/pi-extension/src/index.ts

@@ -1,390 +0,0 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { RequestHistory } from "./runtime/request-history.js";
-import { registerProviderSupport } from "./provider-support/index.js";
-import { RoutingRuntime } from "./cognitive-routing-v2/runtime.js";
-import { workersForDelegation, type Profile } from "./cognitive-routing-v2/types.js";
-import { applyRoutingToolVisibility, registerRoutingTools } from "./cognitive-routing-v2/tools.js";
-import { ConversationHistoryRuntime } from "./conversation-history/runtime.js";
-import { FreeflowContextRuntime } from "./freeflow-context/runtime.js";
-import { CONTEXT_VIRTUALIZATION_TOOL_NAME, registerFreeflowContextTool } from "./freeflow-context/tool.js";
-import { handleContextCommand } from "./context-virtualization/commands.js";
-import { ContextVirtualizationRuntime } from "./context-virtualization/runtime.js";
-import { handleFreeflowCommand } from "./settings/settings-ui.js";
-import { isPiFlowHost } from "./runtime/runtime-identity.js";
-import {
-  CONTRIBUTOR_COMMANDS,
-  WORKFLOW_COMMANDS,
-  freeflowModelSkillPaths,
-  freeflowSkillPath,
-  getRuntimeContext,
-  hasUsableMandatoryPrompts,
-  isPromptAvailable,
-  readCapabilityState,
-  refreshRuntimeContext,
-  restoreSessionOverrides,
-  stableRuntimeContext,
-  STABLE_FREEFLOW_SURFACE,
-  filterBootstrapMessage,
-  setFreeflowStatus,
-  skillPrompt,
-  withFreeflowRuntimeState,
-} from "./runtime/runtime-context.js";
-
-type FreeflowAPI = ExtensionAPI & { host?: unknown };
-async function sendSkillCommand(pi: FreeflowAPI, ctx: ExtensionCommandContext, skill: string, args?: string) {
-  const state = await readCapabilityState(ctx.cwd, ctx, pi.host);
-  if (skill === "setup-freeflow" && !state.configured) {
-    await pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true });
-    return;
-  }
-  if (!state.configured || !state.enabled) {
-    ctx.ui.notify("Run /setup-freeflow or enable Freeflow before dispatching this skill.", "warning");
-    return;
-  }
-  const prompts = await getRuntimeContext(state);
-  if (!hasUsableMandatoryPrompts(prompts)) {
-    ctx.ui.notify("Freeflow core prompts are unavailable; the requested skill cannot be dispatched.", "warning");
-    return;
-  }
-  await pi.sendUserMessage(skillPrompt(skill, args), { expandPromptTemplates: true });
-}
-
-function freeflowCompletions(prefix: string | undefined, routingAvailable: boolean) {
-  const query = prefix ?? "";
-  const choices = query.startsWith("settings ")
-    ? [
-        ["settings session", "session", "Override Freeflow for this Pi session"],
-        ["settings local", "local", "Edit personal overrides for this repository"],
-        ["settings repo", "repo", "Edit shared repository settings"],
-      ]
-    : query.startsWith("profile ") && routingAvailable
-      ? [
-          ["profile coordinator", "coordinator", "Hold Coordinator manually"],
-          ["profile helper", "helper", "Hold Helper manually when enabled"],
-          ["profile executor", "executor", "Hold Executor manually when enabled"],
-          ["profile auto", "auto", "Return to automatic Coordinator reconciliation"],
-          ["profile history", "history", "Read routing observations"],
-        ]
-      : query.startsWith("context ")
-        ? [
-            ["context status", "status", "Show Freeflow Context state"],
-            ["context list", "list", "List archived context projections"],
-            ["context restore", "restore", "Restore one or more context references"],
-            ["context reset all", "reset all", "Reset projection decisions on the active branch"],
-          ]
-        : [
-            ["settings", "settings", "Open personal override settings"],
-            ["status", "status", "Show effective Freeflow state"],
-            ["context", "context", "Inspect Freeflow Context"],
-            ...(routingAvailable
-              ? [
-                  ["profile", "profile", "Hold or release Cognitive Routing profile control"],
-                  ["resume", "resume", "Resume the current saved routing responsibility"],
-                ]
-              : []),
-            ["enable", "enable", "Enable Freeflow for this repository"],
-            ["disable", "disable", "Disable Freeflow for this repository"],
-          ];
-  return choices
-    .filter(([value]) => value.startsWith(query))
-    .map(([value, label, description]) => ({ value, label, description }));
-}
-
-export default function freeflow(pi: FreeflowAPI) {
-  registerProviderSupport(pi);
-  const api = pi as any;
-  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
-  const routing = new RoutingRuntime(api, [packageRoot]);
-  const requestHistory = new RequestHistory(api);
-  let capability: any;
-  let prompts: any;
-  let context: FreeflowContextRuntime | undefined;
-  let virtualization: ContextVirtualizationRuntime | undefined;
-  let history: ConversationHistoryRuntime | undefined;
-  let refreshState = true;
-  let sessionContext: any;
-  let surfaceGeneration = 0;
-
-  const unavailable = (state: any, message: string) => ({
-    ...state,
-    effective: false,
-    blockingReason: { code: "unavailable", message },
-  });
-  async function loadSurface(ctx: any) {
-    const generation = surfaceGeneration;
-    const next = await readCapabilityState(ctx.cwd, ctx, pi.host);
-    const loaded = await getRuntimeContext(STABLE_FREEFLOW_SURFACE);
-    if (generation !== surfaceGeneration) throw new Error("Discarded surface preparation for a replaced session.");
-    if (!hasUsableMandatoryPrompts(loaded)) {
-      for (const key of ["cognitiveRouting", "contextVirtualization", "conversationHistory"])
-        next[key] = unavailable(next[key], "Mandatory Freeflow prompts are unavailable.");
-    }
-    if (next.cognitiveRouting.effective && !isPromptAvailable(loaded.cognitiveRoutingPrompt))
-      next.cognitiveRouting = unavailable(next.cognitiveRouting, "Routing bootstrap cue is unavailable.");
-    if (next.contextVirtualization.effective && !isPromptAvailable(loaded.contextVirtualizationPrompt))
-      next.contextVirtualization = unavailable(
-        next.contextVirtualization,
-        "Context Virtualization guidance is unavailable.",
-      );
-    if (next.conversationHistory.effective && !isPromptAvailable(loaded.conversationHistoryPrompt))
-      next.conversationHistory = unavailable(next.conversationHistory, "Conversation History guidance is unavailable.");
-    // The existing reduction engine is not the future Context Control port. Do not pretend
-    // its independent transform ordering has been qualified with the new projection.
-    if (
-      next.cognitiveRouting.effective &&
-      next.cognitiveRouting.projection &&
-      (next.contextVirtualization.effective || next.conversationHistory.effective)
-    )
-      next.cognitiveRouting = unavailable(
-        next.cognitiveRouting,
-        "New routing projection with legacy context transforms is not qualified. Disable that combination explicitly.",
-      );
-    if (next.cognitiveRouting.enabled && isPiFlowHost(pi.host))
-      next.cognitiveRouting = unavailable(
-        next.cognitiveRouting,
-        "The redesigned PiFlow adapter requires separate qualification.",
-      );
-    capability = next;
-    prompts = loaded;
-    sessionContext = ctx;
-    return next;
-  }
-  function contextTools() {
-    registerFreeflowContextTool(
-      api,
-      () => virtualization,
-      () => history,
-      {
-        contextVirtualization: capability?.contextVirtualization?.effective === true,
-        conversationHistory: capability?.conversationHistory?.effective === true,
-      },
-    );
-    if (api.getActiveTools && api.setActiveTools) {
-      const current = new Set<string>(api.getActiveTools());
-      current.add(CONTEXT_VIRTUALIZATION_TOOL_NAME);
-      const next = [...current];
-      if (JSON.stringify(next) !== JSON.stringify(api.getActiveTools())) api.setActiveTools(next);
-    }
-  }
-  function status(ctx: any) {
-    applyRoutingToolVisibility(api, routing, capability?.cognitiveRouting?.effective === true);
-    setFreeflowStatus(ctx, capability, routing.state(), prompts);
-  }
-  async function update(ctx: any) {
-    const next = await loadSurface(ctx);
-    await routing.refresh(ctx, next.cognitiveRouting);
-    contextTools();
-    status(ctx);
-    refreshState = true;
-  }
-
-  registerRoutingTools(api, routing);
-  registerFreeflowContextTool(
-    api,
-    () => virtualization,
-    () => history,
-    { contextVirtualization: false, conversationHistory: false },
-  );
-
-  pi.on("resources_discover", async (event, ctx) => {
-    const state = capability ?? (await loadSurface(ctx ?? { cwd: (event as any)?.cwd ?? process.cwd() }));
-    return { skillPaths: freeflowModelSkillPaths(STABLE_FREEFLOW_SURFACE) };
-  });
-  pi.on("session_start", async (event, ctx) => {
-    const generation = ++surfaceGeneration;
-    requestHistory.reset();
-    routing.unbind();
-    capability = undefined;
-    prompts = undefined;
-    refreshState = true;
-    restoreSessionOverrides(ctx);
-    const initial = await readCapabilityState(ctx.cwd, ctx, pi.host);
-    await refreshRuntimeContext(STABLE_FREEFLOW_SURFACE);
-    if (generation !== surfaceGeneration) return;
-    await loadSurface(ctx);
-    context = new FreeflowContextRuntime(ctx);
-    virtualization = new ContextVirtualizationRuntime(pi, ctx, context);
-    history = new ConversationHistoryRuntime(
-      ctx,
-      (entryId) => virtualization?.isSourceFullyProjected(entryId) ?? true,
-      context,
-    );
-    await virtualization.recover(ctx);
-    await routing.bind(ctx, capability.cognitiveRouting, (event as any)?.reason !== "reload");
-    contextTools();
-    status(ctx);
-  });
-  pi.on("session_shutdown", async () => {
-    surfaceGeneration++;
-    requestHistory.reset();
-    routing.unbind();
-    context = undefined;
-    virtualization = undefined;
-    history = undefined;
-    capability = undefined;
-    prompts = undefined;
-    sessionContext = undefined;
-  });
-  pi.on("before_agent_start", async (event, ctx) => {
-    await update(ctx);
-    await routing.beforeRun(ctx);
-    status(ctx);
-    const text = stableRuntimeContext(prompts);
-    return { systemPrompt: text ? `${event.systemPrompt}\n\n${text}` : event.systemPrompt };
-  });
-  pi.on("message_end", (event) => routing.messageEnd((event as any).message));
-  pi.on("tool_call", (event, ctx) => {
-    if (
-      (event as any).toolName === CONTEXT_VIRTUALIZATION_TOOL_NAME &&
-      !capability?.contextVirtualization?.effective &&
-      !capability?.conversationHistory?.effective
-    )
-      return { block: true, reason: "Freeflow Context is disabled." };
-    return routing.preflight(event, ctx);
-  });
-  pi.on("turn_end", async (event, ctx) => {
-    await routing.turnEnd(event, ctx);
-    status(ctx);
-  });
-  pi.on("agent_settled", async (_event, ctx) => {
-    await routing.settled(ctx);
-    await update(ctx);
-  });
-  pi.on("model_select", async (_event, ctx) => {
-    await routing.nativeChange(ctx);
-    status(ctx);
-  });
-  pi.on("thinking_level_select", async (_event, ctx) => {
-    await routing.nativeChange(ctx);
-    status(ctx);
-  });
-  pi.on("context", async (event, ctx) => {
-    if (!capability) await loadSurface(ctx);
-    let messages = event.messages.map(filterBootstrapMessage).filter(Boolean);
-    if (virtualization) {
-      virtualization.setContext(ctx);
-      const projected = await virtualization.project(messages, capability.contextVirtualization.effective);
-      messages = projected.messages;
-    }
-    if (history && capability.conversationHistory.effective) {
-      history.setContext(ctx);
-      history.capture(capability.contextVirtualization.effective);
-    }
-    messages = withFreeflowRuntimeState(messages, capability, routing.state(), prompts, {
-      force: refreshState,
-      projectionFailure: routing.state().projectionFailure,
-    });
-    refreshState = false;
-    const routed = await routing.context(ctx, messages);
-    const projected = virtualization?.decorate(routed) ?? routed;
-    const state = routing.state();
-    if (projected.some((message) => message.details?.routingRequestBlocked === true)) return { messages: projected };
-    const view = routing.projectionEnabled && state.activeProfile === "coordinator" ? "coordinator" : "ordinary";
-    return {
-      messages: await requestHistory.assemble(projected, view, ctx, (assembled) =>
-        routing.budgetNotice(assembled, ctx),
-      ),
-    };
-  });
-  const restore = async (ctx: any, navigation = true) => {
-    requestHistory.reset();
-    restoreSessionOverrides(ctx);
-    refreshState = true;
-    if (virtualization) {
-      virtualization.setContext(ctx);
-      await virtualization.recover(ctx);
-    }
-    history?.setContext(ctx);
-    await routing.ancestryChanged(ctx, navigation);
-    await update(ctx);
-  };
-  pi.on("session_tree", async (_event, ctx) => restore(ctx));
-  pi.on("session_compact", async (_event, ctx) => restore(ctx, false));
-  pi.on("session_compact_failed", async (_event, ctx) => {
-    refreshState = true;
-    status(ctx);
-  });
-
-  if (
-    typeof pi.registerShortcut === "function" &&
-    typeof api.appendEntry === "function" &&
-    typeof api.setModel === "function" &&
-    typeof api.setThinkingLevel === "function"
-  ) {
-    pi.registerShortcut("ctrl+shift+r", {
-      description: "Cycle enabled Cognitive Routing manual holds",
-      handler: async (ctx) => {
-        if (!ctx.isIdle()) {
-          ctx.ui.notify("Wait for Pi to become idle before changing control.", "warning");
-          return;
-        }
-        const state = routing.state();
-        const profiles: Profile[] = ["coordinator", ...workersForDelegation(state.delegation)];
-        const current = profiles.indexOf(state.activeProfile ?? "coordinator");
-        const target = profiles[(current + 1) % profiles.length]!;
-        ctx.ui.notify(JSON.stringify(await routing.setManualProfile(target)), "info");
-        await update(ctx);
-      },
-    });
-    pi.registerShortcut("ctrl+shift+a", {
-      description: "Release manual hold to Automatic Coordinator",
-      handler: async (ctx) => {
-        if (!ctx.isIdle()) {
-          ctx.ui.notify("Wait for Pi to become idle before changing control.", "warning");
-          return;
-        }
-        ctx.ui.notify(JSON.stringify(await routing.setAutomaticControl()), "info");
-        await update(ctx);
-      },
-    });
-  }
-  for (const { command, skill } of WORKFLOW_COMMANDS)
-    pi.registerCommand(command, {
-      description: command === skill ? `Run Freeflow ${skill}` : `Run Freeflow ${skill} via ${command}`,
-      ...(command === "bypass"
-        ? {
-            getArgumentCompletions: (prefix: string) =>
-              [
-                { value: "next", label: "next", description: "Skip one optional step" },
-                { value: "task", label: "task", description: "Reduce optional pressure for the current task" },
-              ].filter((item) => item.value.startsWith(prefix ?? "")),
-          }
-        : {}),
-      handler: (args, ctx) => sendSkillCommand(pi, ctx, skill, args),
-    });
-  for (const skill of CONTRIBUTOR_COMMANDS)
-    pi.registerCommand(skill, {
-      description: `Run Freeflow ${skill}`,
-      handler: (args, ctx) => sendSkillCommand(pi, ctx, skill, args),
-    });
-  pi.registerCommand("freeflow", {
-    description: "Freeflow settings, status, profile control, saved-operation resume, and context tools",
-    getArgumentCompletions: (prefix) =>
-      freeflowCompletions(
-        prefix,
-        typeof api.appendEntry === "function" &&
-          typeof api.setModel === "function" &&
-          typeof api.setThinkingLevel === "function",
-      ),
-    handler: async (args, ctx) => {
-      if (await routing.command(args ?? "", ctx)) {
-        await update(ctx);
-        return;
-      }
-      const input = (args ?? "").trim();
-      if (input === "context" || input.startsWith("context ")) {
-        await handleContextCommand(
-          input.slice(7).trim(),
-          ctx,
-          virtualization,
-          capability?.contextVirtualization.effective,
-          capability?.conversationHistory.effective,
-        );
-        return;
-      }
-      await handleFreeflowCommand(args, ctx, async () => update(ctx), pi, routing);
-    },
-  });
-}

package/pi-extension/src/integrations/mcp-config.ts

@@ -1,32 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-
-function getMcpConfigPaths(cwd) {
-  return [
-    join(homedir(), ".config", "mcp", "mcp.json"),
-    join(homedir(), ".pi", "agent", "mcp.json"),
-    resolve(cwd, ".mcp.json"),
-    resolve(cwd, ".pi", "mcp.json"),
-  ];
-}
-
-export async function isMcpServerConfigured(serverName, cwd) {
-  return Boolean(await loadMcpServerConfig(serverName, cwd));
-}
-
-export async function loadMcpServerConfig(serverName, cwd) {
-  let found = null;
-  for (const configPath of getMcpConfigPaths(cwd)) {
-    try {
-      const raw = JSON.parse(await readFile(configPath, "utf8"));
-      const servers = raw?.mcpServers ?? raw?.["mcp-servers"] ?? {};
-      if (servers && typeof servers === "object" && !Array.isArray(servers) && servers[serverName]) {
-        found = servers[serverName];
-      }
-    } catch {
-      // Missing or invalid MCP configs are ignored here; pi-mcp-adapter owns user-facing setup diagnostics.
-    }
-  }
-  return found;
-}

package/pi-extension/src/provider-support/astra/adapter.ts

@@ -1,108 +0,0 @@
-import { assemble, EFFORTS } from "./history.js";
-import { SessionState } from "./session-state.js";
-
-export function requestKey(payload: any, model: any): string | undefined {
-  if (
-    !payload ||
-    payload.model !== "gpt-6-astra" ||
-    model?.id !== payload.model ||
-    payload.store !== false ||
-    !Array.isArray(payload.input) ||
-    !EFFORTS.includes(payload.reasoning?.effort) ||
-    payload.previous_response_id ||
-    payload.conversation ||
-    payload.context_management ||
-    (payload.truncation && payload.truncation !== "disabled") ||
-    (payload.reasoning.mode && payload.reasoning.mode !== "standard") ||
-    payload.agents ||
-    payload.input.some((x: any) => x?.type === "configuration_update" || x?.type === "compaction_trigger")
-  )
-    return;
-  const codex = model.provider === "openai-codex" && model.api === "openai-codex-responses";
-  const api = model.provider === "openai" && model.api === "openai-responses";
-  if (!codex && !api) return;
-  if (model.baseUrl !== undefined && typeof model.baseUrl !== "string") return;
-  const base = (model.baseUrl ?? (codex ? "https://chatgpt.com/backend-api" : "https://api.openai.com/v1")).replace(
-    /\/+$/,
-    "",
-  );
-  const allowed = codex
-    ? [
-        "https://chatgpt.com/backend-api",
-        "https://chatgpt.com/backend-api/codex",
-        "https://chatgpt.com/backend-api/codex/responses",
-      ]
-    : ["https://api.openai.com/v1"];
-  if (!allowed.includes(base)) return;
-  return `${model.provider}/${model.api}/${model.id}`;
-}
-export class AstraAdapter {
-  private session?: { id: string; file?: string; store: SessionState };
-  private generation = 0;
-  private compacting = false;
-  private queue: Promise<unknown> = Promise.resolve();
-  private statusSignature?: string;
-  constructor(private readonly pi: any) {}
-  reset(ctx?: any): void {
-    this.generation++;
-    this.session = undefined;
-    this.compacting = false;
-    this.status(ctx, undefined);
-  }
-  setCompacting(value: boolean): void {
-    this.compacting = value;
-  }
-  private status(ctx: any, label: string | undefined): void {
-    if (this.statusSignature === label) return;
-    this.statusSignature = label;
-    // Diagnostics must never turn a completed payload transformation into an exception.
-    try {
-      ctx.ui?.setStatus?.("freeflow-astra-effort", label);
-    } catch {}
-  }
-  async adapt(payload: any, ctx: any): Promise<any> {
-    const generation = this.generation;
-    const operation = this.queue.then(async () => {
-      const key = requestKey(payload, ctx.model);
-      if (generation !== this.generation || this.compacting || !key) {
-        this.status(ctx, undefined);
-        return payload;
-      }
-      try {
-        const reader = ctx.sessionManager;
-        if (
-          typeof this.pi.appendEntry !== "function" ||
-          !reader?.getLeafId ||
-          !reader.getSessionId ||
-          !reader.getSessionFile
-        )
-          throw new Error("Native session persistence unavailable");
-        const id = reader.getSessionId(),
-          file = reader.getSessionFile();
-        if (!this.session || this.session.id !== id || this.session.file !== file)
-          this.session = { id, file, store: new SessionState(this.pi, reader) };
-        const store = this.session.store,
-          basis = reader.getLeafId();
-        const records = await store.records();
-        if (
-          generation !== this.generation ||
-          reader.getLeafId() !== basis ||
-          this.session?.store !== store ||
-          key !== requestKey(payload, ctx.model)
-        )
-          throw new Error("Astra request changed during preparation");
-        const result = assemble(payload, key, store.generation(), basis, records);
-        if (result.record) store.append(result.record);
-        this.status(ctx, `Astra ${result.effective} · cache baseline ${result.baseline}`);
-        return result.payload;
-      } catch {
-        // Pi swallows hook exceptions. Return the untouched full-history request,
-        // including its requested effort, instead of a partially pinned request.
-        this.status(ctx, "Astra cache adaptation unavailable · native effort");
-        return payload;
-      }
-    });
-    this.queue = operation.catch(() => {});
-    return operation;
-  }
-}