@hassangameryt/freeflow 0.2.0 → 0.4.0

package/pi-extension/freeflow/index.js

@@ -0,0 +1 @@
+export { default } from "../dist/index.js";

package/pi-extension/src/index.ts

@@ -0,0 +1,295 @@
+import { handleNativeToolSafetyNet } from "./output-router/native-safety-net.js";
+import { handleObservedToolRouting } from "./output-router/observed-tool-routing.js";
+import { registerRouterTools } from "./output-router/router-tools.js";
+import { handleFreeflowCommand, handleOutputRouterCommand } from "./settings/settings-ui.js";
+import {
+  CONTRIBUTOR_COMMANDS,
+  WORKFLOW_COMMANDS,
+  WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
+  FREEFLOW_STATUS_TOOL_NAME,
+  freeflowModelSkillPaths,
+  freeflowSkillPath,
+  getRuntimeContext,
+  OUTPUT_ROUTER_TOOL_NAMES,
+  readCapabilityState,
+  readModeState,
+  readOutputRouterConfig,
+  refreshRuntimeContext,
+  restoreModeOverride,
+  runtimeContext,
+  workflowBootstrapMessage,
+  setModeStatus,
+  skillPrompt,
+  notifyRouterConfigWarnings,
+} from "./runtime/runtime-context.js";
+
+function isOutputRouterToolName(name: string): boolean {
+  return OUTPUT_ROUTER_TOOL_NAMES.includes(name);
+}
+
+async function applyCapabilityToolVisibility(pi: any, ctx: any, capabilityState = undefined): Promise<void> {
+  if (typeof pi?.setActiveTools !== "function" || typeof pi?.getAllTools !== "function") {
+    return;
+  }
+
+  const state = capabilityState ?? (await readCapabilityState(ctx.cwd));
+  const allToolNames = pi
+    .getAllTools()
+    .map((tool: any) => tool?.name)
+    .filter(Boolean);
+  const allToolNameSet = new Set(allToolNames);
+  const currentActive = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : undefined;
+  const active = new Set(
+    (Array.isArray(currentActive) ? currentActive : allToolNames).filter((name: string) => allToolNameSet.has(name)),
+  );
+
+  if (allToolNameSet.has(FREEFLOW_STATUS_TOOL_NAME)) {
+    if (state.configured && state.enabled) active.add(FREEFLOW_STATUS_TOOL_NAME);
+    else active.delete(FREEFLOW_STATUS_TOOL_NAME);
+  }
+
+  for (const toolName of OUTPUT_ROUTER_TOOL_NAMES) {
+    if (!allToolNameSet.has(toolName)) continue;
+    if (state.outputRouter.enabled) active.add(toolName);
+    else active.delete(toolName);
+  }
+
+  pi.setActiveTools([...active]);
+}
+
+async function applyLiveCapabilityState(pi: any, ctx: any): Promise<void> {
+  const [modeState, capabilityState] = await Promise.all([readModeState(ctx.cwd), readCapabilityState(ctx.cwd)]);
+  await refreshRuntimeContext(capabilityState);
+  setModeStatus(ctx, modeState, capabilityState);
+  await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+}
+
+function disabledToolCall(toolName: string, capability: string) {
+  const command = capability === "freeflow" ? "/freeflow settings" : `/${capability} settings`;
+  return {
+    block: true,
+    reason: `${toolName} is disabled by Freeflow config. Configure ${capability} with ${command}.`,
+  };
+}
+
+function capabilityCompletions(prefix: string | undefined) {
+  const query = prefix ?? "";
+  return [
+    { value: "settings", label: "settings", description: "Open repository Output Router settings" },
+    { value: "status", label: "status", description: "Show effective Output Router state" },
+    { value: "enable", label: "enable", description: "Enable Output Router for this repository" },
+    { value: "disable", label: "disable", description: "Disable Output Router for this repository" },
+  ].filter((item) => item.value.startsWith(query));
+}
+
+function freeflowCompletions(prefix: string | undefined) {
+  const query = prefix ?? "";
+  if (query.startsWith("settings ")) {
+    const settingsQuery = query.slice("settings ".length);
+    return [
+      { value: "session", label: "session", description: "Override Freeflow for this Pi session" },
+      { value: "local", label: "local", description: "Edit personal overrides for this repository" },
+      { value: "repo", label: "repo", description: "Edit shared repository settings" },
+    ]
+      .filter((item) => item.value.startsWith(settingsQuery))
+      .map((item) => ({ ...item, value: `settings ${item.value}` }));
+  }
+  if (query.startsWith("mode ")) {
+    const modeQuery = query.slice("mode ".length);
+    return [
+      { value: "conversation", label: "conversation", description: "Read-only discussion and inspection" },
+      { value: "workflow", label: "workflow", description: "Adaptive workflow for consequential work" },
+      { value: "strict-workflow", label: "strict-workflow", description: "Stronger pressure at high-risk boundaries" },
+      {
+        value: "reset",
+        label: "reset",
+        description: "Clear the session override and use the configured default",
+      },
+    ]
+      .filter((item) => item.value.startsWith(modeQuery))
+      .map((item) => ({ ...item, value: `mode ${item.value}` }));
+  }
+  return [
+    { value: "settings", label: "settings", description: "Open personal override settings" },
+    { value: "status", label: "status", description: "Show effective Freeflow state" },
+    { value: "mode", label: "mode", description: "Select a temporary session mode" },
+    { value: "enable", label: "enable", description: "Enable Freeflow for this repository" },
+    { value: "disable", label: "disable", description: "Disable Freeflow for this repository" },
+  ].filter((item) => item.value.startsWith(query));
+}
+
+function bypassCompletions(prefix: string | undefined) {
+  const query = prefix ?? "";
+  return [
+    { 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(query));
+}
+
+async function sendSkillCommand(pi: any, ctx: any, skill: string, args: string | undefined) {
+  const state = await readCapabilityState(ctx.cwd);
+  if (skill === "setup-freeflow" && !state.configured) {
+    await pi.sendUserMessage(skillPrompt(skill, args));
+    return;
+  }
+  if (!state.configured) {
+    ctx.ui.notify("Freeflow is installed but this repo is not set up. Run /setup-freeflow first.", "warning");
+    return;
+  }
+  if (!state.enabled) {
+    ctx.ui.notify(
+      "Freeflow is disabled for this repo. Use /freeflow enable or /freeflow settings to re-enable it.",
+      "warning",
+    );
+    return;
+  }
+  if (!state.skills.effective) {
+    ctx.ui.notify("Freeflow skills are disabled. Use /freeflow settings to enable skills.", "warning");
+    return;
+  }
+  await pi.sendUserMessage(skillPrompt(skill, args));
+}
+
+export default function freeflow(pi) {
+  registerRouterTools(pi);
+
+  pi.on("resources_discover", async (event, ctx) => {
+    const cwd = ctx?.cwd ?? event?.cwd ?? process.cwd();
+    const state = await readCapabilityState(cwd);
+    if (!state.configured) {
+      return { skillPaths: [freeflowSkillPath("setup-freeflow")] };
+    }
+    if (!state.enabled || !state.skills.effective) {
+      return { skillPaths: [] };
+    }
+    return { skillPaths: freeflowModelSkillPaths() };
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    restoreModeOverride(ctx);
+    const [modeState, routerConfigResult, capabilityState] = await Promise.all([
+      readModeState(ctx.cwd),
+      readOutputRouterConfig(ctx.cwd),
+      readCapabilityState(ctx.cwd),
+    ]);
+    await refreshRuntimeContext(capabilityState);
+    setModeStatus(ctx, modeState, capabilityState);
+    notifyRouterConfigWarnings(ctx, routerConfigResult);
+    await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    restoreModeOverride(ctx);
+    await applyLiveCapabilityState(pi, ctx);
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    const [modeState, routerConfigResult, capabilityState] = await Promise.all([
+      readModeState(ctx.cwd),
+      readOutputRouterConfig(ctx.cwd),
+      readCapabilityState(ctx.cwd),
+    ]);
+    await refreshRuntimeContext(capabilityState);
+    setModeStatus(ctx, modeState, capabilityState);
+    notifyRouterConfigWarnings(ctx, routerConfigResult);
+    await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const [modeState, routerConfigResult, capabilityState] = await Promise.all([
+      readModeState(ctx.cwd),
+      readOutputRouterConfig(ctx.cwd),
+      readCapabilityState(ctx.cwd),
+    ]);
+    const freeflowContext = await getRuntimeContext(capabilityState);
+    setModeStatus(ctx, modeState, capabilityState);
+    notifyRouterConfigWarnings(ctx, routerConfigResult);
+    await applyCapabilityToolVisibility(pi, ctx, capabilityState);
+    const freeflowRuntimeContext = runtimeContext(modeState, freeflowContext, routerConfigResult, capabilityState);
+    const workflowMessage = workflowBootstrapMessage(freeflowContext, capabilityState, ctx.sessionManager);
+    const systemPrompt = freeflowRuntimeContext
+      ? `${event.systemPrompt}\n\n${freeflowRuntimeContext}`
+      : event.systemPrompt;
+    return { message: workflowMessage, systemPrompt };
+  });
+
+  pi.on("context", async (event, ctx) => {
+    const capabilityState = await readCapabilityState(ctx.cwd);
+    if (capabilityState.skills.effective) {
+      return undefined;
+    }
+
+    const messages = event.messages.filter(
+      (message) => !(message?.role === "custom" && message?.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE),
+    );
+    return messages.length === event.messages.length ? undefined : { messages };
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const capabilityState = await readCapabilityState(ctx.cwd);
+    const toolName = typeof event?.toolName === "string" ? event.toolName : "";
+    if ((!capabilityState.configured || !capabilityState.enabled) && toolName === FREEFLOW_STATUS_TOOL_NAME) {
+      return disabledToolCall(toolName, "freeflow");
+    }
+    if (!capabilityState.outputRouter.enabled && isOutputRouterToolName(toolName)) {
+      return disabledToolCall(toolName, "output-router");
+    }
+    return undefined;
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    const capabilityState = await readCapabilityState(ctx.cwd);
+    if (!capabilityState.outputRouter.enabled) {
+      return undefined;
+    }
+    const observed = await handleObservedToolRouting(event, ctx);
+    if (observed) {
+      return observed;
+    }
+    return handleNativeToolSafetyNet(event, 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: bypassCompletions } : {}),
+      handler: async (args, ctx) => {
+        await sendSkillCommand(pi, ctx, skill, args);
+      },
+    });
+  }
+
+  for (const skill of CONTRIBUTOR_COMMANDS) {
+    pi.registerCommand(skill, {
+      description: `Run Freeflow ${skill}`,
+      handler: async (args, ctx) => {
+        await sendSkillCommand(pi, ctx, skill, args);
+      },
+    });
+  }
+
+  pi.registerCommand("freeflow", {
+    description: "Open unified Freeflow settings or print compact status",
+    getArgumentCompletions: freeflowCompletions,
+    handler: async (args, ctx) => {
+      await handleFreeflowCommand(
+        args,
+        ctx,
+        async () => {
+          await applyLiveCapabilityState(pi, ctx);
+        },
+        pi,
+      );
+    },
+  });
+
+  pi.registerCommand("output-router", {
+    description: "Open Freeflow Output Router settings or print compact status",
+    getArgumentCompletions: capabilityCompletions,
+    handler: async (args, ctx) => {
+      await handleOutputRouterCommand(args, ctx, async () => {
+        await applyLiveCapabilityState(pi, ctx);
+      });
+    },
+  });
+}

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

@@ -0,0 +1,32 @@
+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/output-router/host-producer-identification.ts

@@ -0,0 +1,256 @@
+const BUILT_IN_PI_PRODUCERS = {
+  web_search: {
+    configKey: "web",
+    producer: { kind: "web", tool: "web_search" },
+    risk: { classification: "read", source: "manifest", reason: "Pi web_search is a read-only evidence producer." },
+  },
+  fetch_content: {
+    configKey: "fetch",
+    producer: { kind: "fetch", tool: "fetch_content" },
+    risk: { classification: "read", source: "manifest", reason: "Pi fetch_content is a read-only evidence producer." },
+  },
+  code_search: {
+    configKey: "codeSearch",
+    producer: { kind: "code_search", tool: "code_search" },
+    risk: { classification: "read", source: "manifest", reason: "Pi code_search is a read-only evidence producer." },
+  },
+} as const;
+
+const READ_VERBS = [
+  "get",
+  "list",
+  "search",
+  "fetch",
+  "read",
+  "query",
+  "find",
+  "describe",
+  "diagnostic",
+  "diagnostics",
+  "overview",
+  "lookup",
+  "show",
+];
+
+const WRITE_VERBS = [
+  "create",
+  "update",
+  "delete",
+  "remove",
+  "patch",
+  "post",
+  "put",
+  "deploy",
+  "restart",
+  "rename",
+  "mutate",
+  "set",
+  "write",
+  "send",
+  "transition",
+  "close",
+  "merge",
+  "rerun",
+  "cancel",
+];
+
+export function resolvePiObservedRoutingDecision(event: any, observedRoutingConfig: any) {
+  const host = { name: "pi", toolName: typeof event?.toolName === "string" ? event.toolName : "unknown" };
+
+  if (!observedRoutingConfig || observedRoutingConfig.enabled !== true) {
+    return { route: false, reason: "observedRouting.enabled is not true." };
+  }
+
+  const mcpProducer = identifyPiMcpProducer(event);
+  if (mcpProducer) {
+    const serverConfig = observedRoutingConfig.mcp?.servers?.[mcpProducer.server];
+    if (!serverConfig?.enabled) {
+      return { route: false, reason: `MCP server ${mcpProducer.server} is not enabled for observed routing.` };
+    }
+    return {
+      route: true,
+      host,
+      producer: mcpProducer,
+      persistence: serverConfig.persistence,
+      risk: classifyObservedProducerRisk(mcpProducer, event),
+    };
+  }
+
+  const builtIn = identifyBuiltInPiProducer(event);
+  if (builtIn) {
+    const producerConfig = observedRoutingConfig[builtIn.configKey];
+    if (!producerConfig?.enabled) {
+      return { route: false, reason: `Pi ${host.toolName} observed routing is not enabled.` };
+    }
+    return {
+      route: true,
+      host,
+      producer: { ...builtIn.producer },
+      persistence: producerConfig.persistence,
+      risk: { ...builtIn.risk },
+    };
+  }
+
+  return { route: false, reason: `Pi tool ${host.toolName} is not an observed-routing producer.` };
+}
+
+export function identifyPiMcpProducer(event: any) {
+  const toolName = typeof event?.toolName === "string" ? event.toolName : "";
+  const input = isRecord(event?.input) ? event.input : {};
+  const details = isRecord(event?.details) ? event.details : {};
+  const detailMcp = isRecord(details.mcp) ? details.mcp : {};
+  const inputProducer = isRecord(input.producer) ? input.producer : {};
+  const detailProducer = isRecord(details.producer) ? details.producer : {};
+  const split = splitMcpToolName(toolName);
+
+  const server = firstString(
+    input.server,
+    input.mcpServer,
+    inputProducer.server,
+    details.server,
+    detailMcp.server,
+    detailProducer.server,
+    split?.server,
+  );
+  const tool = firstString(
+    input.tool,
+    input.name,
+    inputProducer.tool,
+    details.tool,
+    detailMcp.tool,
+    detailProducer.tool,
+    split?.tool,
+  );
+
+  if (!server || !tool) {
+    return undefined;
+  }
+
+  if (
+    toolName !== "mcp" &&
+    !toolName.startsWith("mcp__") &&
+    !detailMcp.server &&
+    detailProducer.kind !== "mcp" &&
+    inputProducer.kind !== "mcp"
+  ) {
+    return undefined;
+  }
+
+  return { kind: "mcp", server, tool };
+}
+
+export function identifyBuiltInPiProducer(event: any) {
+  const toolName = typeof event?.toolName === "string" ? event.toolName : "";
+  return BUILT_IN_PI_PRODUCERS[toolName as keyof typeof BUILT_IN_PI_PRODUCERS];
+}
+
+export function classifyObservedProducerRisk(producer: any, event?: any) {
+  const configured = configuredRisk(event);
+  if (configured) {
+    return configured;
+  }
+
+  const annotation = mcpAnnotationRisk(event);
+  if (annotation) {
+    return annotation;
+  }
+
+  if (producer?.kind === "web" || producer?.kind === "fetch" || producer?.kind === "code_search") {
+    return {
+      classification: "read",
+      source: "manifest",
+      reason: `${producer.kind} is treated as a read-only Pi evidence producer.`,
+    };
+  }
+
+  const tool = typeof producer?.tool === "string" ? producer.tool : "";
+  if (matchesVerb(tool, WRITE_VERBS)) {
+    return {
+      classification: "write",
+      source: "heuristic",
+      reason: `MCP tool name ${tool} matched a write-like verb heuristic.`,
+    };
+  }
+  if (matchesVerb(tool, READ_VERBS)) {
+    return {
+      classification: "read",
+      source: "heuristic",
+      reason: `MCP tool name ${tool} matched a read-like verb heuristic.`,
+    };
+  }
+
+  return {
+    classification: "unknown",
+    source: "unknown",
+    reason: "No configured risk, MCP annotation, manifest entry, or deterministic name heuristic matched.",
+  };
+}
+
+function configuredRisk(event: any) {
+  const candidate = event?.details?.freeflow?.risk ?? event?.details?.observedRouting?.risk;
+  if (!isRecord(candidate)) {
+    return undefined;
+  }
+  if (!["read", "write", "unknown"].includes(String(candidate.classification))) {
+    return undefined;
+  }
+  return {
+    classification: candidate.classification,
+    source: "configured",
+    reason: typeof candidate.reason === "string" ? candidate.reason : "Configured observed producer risk override.",
+  };
+}
+
+function mcpAnnotationRisk(event: any) {
+  const annotations = event?.details?.mcp?.annotations ?? event?.details?.annotations;
+  if (!isRecord(annotations)) {
+    return undefined;
+  }
+  if (annotations.destructiveHint === true || annotations.write === true || annotations.mutating === true) {
+    return {
+      classification: "write",
+      source: "mcp_annotation",
+      reason: "MCP annotations indicate a mutating/destructive operation.",
+    };
+  }
+  if (annotations.readOnlyHint === true || annotations.readOnly === true) {
+    return {
+      classification: "read",
+      source: "mcp_annotation",
+      reason: "MCP annotations indicate a read-only operation.",
+    };
+  }
+  return undefined;
+}
+
+function splitMcpToolName(toolName: string): { server: string; tool: string } | undefined {
+  if (!toolName.startsWith("mcp__")) {
+    return undefined;
+  }
+  const parts = toolName.split("__");
+  if (parts.length < 3) {
+    return undefined;
+  }
+  return { server: parts[1], tool: parts.slice(2).join("__") };
+}
+
+function matchesVerb(toolName: string, verbs: readonly string[]): boolean {
+  const normalized = toolName.toLowerCase();
+  return verbs.some((verb) => {
+    const escaped = verb.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    return new RegExp(`(^|[_-])${escaped}([_-]|$)`).test(normalized);
+  });
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}