@hassangameryt/freeflow 0.1.0 → 0.3.0

package/{plugins/freeflow/hooks → hooks}/freeflow-runtime-context.mjs

@@ -47,19 +47,19 @@ function findWorkspaceRoot(cwd) {
 }
 
 function loadRuntimeContext() {
+  const modeContractSkill = readText(path.join(PLUGIN_ROOT, "skills", "mode-contract", "SKILL.md"));
   const workflowSkill = readText(path.join(PLUGIN_ROOT, "skills", "workflow", "SKILL.md"));
-  const workflowMap = readText(
-    path.join(PLUGIN_ROOT, "skills", "workflow", "references", "workflow-map.md")
-  );
   const interviewGateSkill = readText(
     path.join(PLUGIN_ROOT, "skills", "interview-gate", "SKILL.md")
   );
+  const discoverSkill = readText(path.join(PLUGIN_ROOT, "skills", "discover", "SKILL.md"));
+  const outputRouterSkill = readText(path.join(PLUGIN_ROOT, "skills", "output-router", "SKILL.md"));
 
-  if (!workflowSkill || !workflowMap || !interviewGateSkill) {
+  if (!modeContractSkill || !workflowSkill || !interviewGateSkill || !discoverSkill || !outputRouterSkill) {
     throw new Error("Freeflow runtime context files are missing.");
   }
 
-  return { workflowSkill, workflowMap, interviewGateSkill };
+  return { modeContractSkill, workflowSkill, interviewGateSkill, discoverSkill, outputRouterSkill };
 }
 
 function readConfig(root) {
@@ -71,17 +71,48 @@ function readConfig(root) {
 
   try {
     const parsed = JSON.parse(body);
-    const keys = Object.keys(parsed);
-    const valid =
-      keys.length === 1 &&
-      Object.prototype.hasOwnProperty.call(parsed, "defaultMode") &&
-      VALID_MODES.has(parsed.defaultMode);
-    return { exists: true, valid, defaultMode: parsed.defaultMode ?? null };
+    const valid = isValidSetupConfig(parsed);
+    return { exists: true, valid, defaultMode: parsed?.defaultMode ?? null };
   } catch {
     return { exists: true, valid: false, defaultMode: null };
   }
 }
 
+function isValidSetupConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const allowedKeys = new Set(["defaultMode", "outputRouter", "observedRouting", "scriptTransform"]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return false;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(value, "defaultMode") || !VALID_MODES.has(value.defaultMode)) {
+    return false;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(value, "outputRouter")) {
+    if (!Boolean(value.outputRouter) || typeof value.outputRouter !== "object" || Array.isArray(value.outputRouter)) {
+      return false;
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(value, "observedRouting")) {
+    if (!Boolean(value.observedRouting) || typeof value.observedRouting !== "object" || Array.isArray(value.observedRouting)) {
+      return false;
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(value, "scriptTransform")) {
+    if (!Boolean(value.scriptTransform) || typeof value.scriptTransform !== "object" || Array.isArray(value.scriptTransform)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
 function inspectSetup(root) {
   const config = readConfig(root);
   const agents = readText(path.join(root, "AGENTS.md")) || "";
@@ -170,7 +201,7 @@ function shouldInject(eventName) {
 
 function buildContext(input) {
   const root = findWorkspaceRoot(input.cwd || process.cwd());
-  const { workflowSkill, workflowMap, interviewGateSkill } = loadRuntimeContext();
+  const { modeContractSkill, workflowSkill, interviewGateSkill, discoverSkill, outputRouterSkill } = loadRuntimeContext();
 
   return [
     "# Freeflow Runtime Context",
@@ -181,6 +212,21 @@ function buildContext(input) {
     "## Repo Setup",
     buildSetupStatus(root),
     "",
+    "## Freeflow Runtime Priority",
+    "Mode Contract handles mode setting, mode interpretation, and mode mismatch before task routing when mode is at issue.",
+    "",
+    "Priority order for matched non-mode workflow skills:",
+    "",
+    "1. Workflow classifies conversation versus consequential work.",
+    "2. Interview Gate stops silent decisions, user-owned decisions, source-truth conflicts, and question-to-action mistakes.",
+    "3. Discover handles context-building after no immediate stop condition remains. Use it before first repo/code exploration or design answers for consequential product/API/tool/runtime hypotheses.",
+    "4. Output Router chooses evidence transport after the workflow/interview/discover route is clear.",
+    "",
+    "## Loaded Mode Contract Skill",
+    "```md",
+    modeContractSkill.trim(),
+    "```",
+    "",
     "## Loaded Workflow Skill",
     "```md",
     workflowSkill.trim(),
@@ -191,9 +237,14 @@ function buildContext(input) {
     interviewGateSkill.trim(),
     "```",
     "",
-    "## Loaded Workflow Map",
+    "## Loaded Discover Skill",
+    "```md",
+    discoverSkill.trim(),
+    "```",
+    "",
+    "## Loaded Output Router Skill",
     "```md",
-    workflowMap.trim(),
+    outputRouterSkill.trim(),
     "```"
   ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Lightweight workflow for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -15,6 +15,21 @@
   },
   "license": "MIT",
   "type": "module",
+  "scripts": {
+    "build:router": "tsc -p router/tsconfig.json",
+    "build:pi-extension": "tsc -p pi-extension/tsconfig.json",
+    "build": "npm run build:router && npm run build:pi-extension",
+    "test:router": "npm run build && node --test $(find router/tests -name '*.test.js' | sort)",
+    "bench:router": "npm run build:router && node router/dist/benchmarks/benchmarks.js",
+    "bench:router:commands": "npm run build:router && node router/dist/benchmarks/command-benchmarks.js",
+    "bench:router:context-saving-baseline": "npm run build:router && node router/dist/benchmarks/context-saving-baseline.js",
+    "bench:router:context-mode-normalized": "npm run build:router && node router/dist/benchmarks/context-mode-normalized-benchmarks.js",
+    "bench:router:context-mode-real-deep": "npm run build:router && node router/dist/benchmarks/context-mode-real-deep-benchmark.js",
+    "bench:router:storage-policy": "npm run build:router && node router/dist/benchmarks/storage-policy-benchmarks.js",
+    "bench:router:index": "npm run build:router && node router/dist/benchmarks/index-benchmarks.js",
+    "bench:router:vault-index": "npm run build:router && node router/dist/benchmarks/vault-index-benchmarks.js",
+    "bench:router:codex-qa": "npm run build:router && node router/dist/benchmarks/codex-qa-benchmarks.js"
+  },
   "keywords": [
     "pi-package",
     "agent-skills",
@@ -29,25 +44,43 @@
   ],
   "pi": {
     "skills": [
-      "plugins/freeflow/skills"
+      "skills"
     ],
     "extensions": [
-      "plugins/freeflow/pi-extension/index.js"
+      "pi-extension/dist/index.js"
     ],
-    "image": "https://raw.githubusercontent.com/hassan-mohiddin/freeflow/main/plugins/freeflow/assets/freeflow-plugin-icon-transparent.png"
+    "image": "https://raw.githubusercontent.com/hassan-mohiddin/freeflow/main/assets/freeflow-plugin-icon-transparent.png"
   },
   "files": [
     ".agents/**",
     ".claude-plugin/**",
+    ".codex-plugin/**",
     "LICENSE",
     "README.md",
-    "plugins/freeflow/.claude-plugin/**",
-    "plugins/freeflow/.codex-plugin/**",
-    "plugins/freeflow/assets/**",
-    "plugins/freeflow/command-surface.json",
-    "plugins/freeflow/docs/**",
-    "plugins/freeflow/hooks/**",
-    "plugins/freeflow/pi-extension/**",
-    "plugins/freeflow/skills/**"
-  ]
+    "assets/**",
+    "command-surface.json",
+    "plugin-docs/README.md",
+    "plugin-docs/workflow.md",
+    "plugin-docs/skills.md",
+    "plugin-docs/architecture.md",
+    "plugin-docs/output-router.md",
+    "plugin-docs/release-evidence.md",
+    "plugin-docs/adr/**",
+    "evals/README.md",
+    "evals/fixtures/**",
+    "evals/prompts/**",
+    "evals/registries/**",
+    "evals/reports/**",
+    "evals/runbooks/**",
+    "evals/scripts/**",
+    "evals/suites/**",
+    "hooks/**",
+    "pi-extension/**",
+    "router/dist/**",
+    "skills/**"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "typescript": "^5.8.3"
+  }
 }

package/pi-extension/dist/host-producer-identification.js

@@ -0,0 +1,186 @@
+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." },
+    },
+};
+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, observedRoutingConfig) {
+    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) {
+    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) {
+    const toolName = typeof event?.toolName === "string" ? event.toolName : "";
+    return BUILT_IN_PI_PRODUCERS[toolName];
+}
+export function classifyObservedProducerRisk(producer, event) {
+    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) {
+    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) {
+    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) {
+    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, verbs) {
+    const normalized = toolName.toLowerCase();
+    return verbs.some((verb) => {
+        const escaped = verb.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+        return new RegExp(`(^|[_-])${escaped}([_-]|$)`).test(normalized);
+    });
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/pi-extension/dist/index.js

@@ -0,0 +1,85 @@
+import { handleNativeToolSafetyNet } from "./native-safety-net.js";
+import { handleObservedToolRouting } from "./observed-tool-routing.js";
+import { registerRouterTools } from "./router-tools.js";
+import { CONTRIBUTOR_COMMANDS, WORKFLOW_COMMANDS, getRuntimeContext, handleWorkflowCommand, hasDiscoverActivation, hasFreeflowActivation, hasFreeflowPriorityActivation, hasOutputRouterActivation, consumeRuntimeContextInjectionState, readModeState, readOutputRouterConfig, refreshRuntimeContext, resetRuntimeContextInjection, restoreModeOverride, runtimeContext, setModeStatus, skillPrompt, notifyRouterConfigWarnings, } from "./runtime-context.js";
+export default function freeflow(pi) {
+    resetRuntimeContextInjection();
+    registerRouterTools(pi);
+    pi.on("session_start", async (_event, ctx) => {
+        resetRuntimeContextInjection();
+        restoreModeOverride(ctx);
+        const [modeState, routerConfigResult] = await Promise.all([
+            readModeState(ctx.cwd),
+            readOutputRouterConfig(ctx.cwd),
+            refreshRuntimeContext(),
+        ]);
+        setModeStatus(ctx, modeState);
+        notifyRouterConfigWarnings(ctx, routerConfigResult);
+    });
+    pi.on("session_compact", async (_event, ctx) => {
+        resetRuntimeContextInjection();
+        const [modeState, routerConfigResult] = await Promise.all([
+            readModeState(ctx.cwd),
+            readOutputRouterConfig(ctx.cwd),
+            refreshRuntimeContext(),
+        ]);
+        setModeStatus(ctx, modeState);
+        notifyRouterConfigWarnings(ctx, routerConfigResult);
+    });
+    pi.on("before_agent_start", async (event, ctx) => {
+        const [modeState, freeflowContext, routerConfigResult] = await Promise.all([
+            readModeState(ctx.cwd),
+            getRuntimeContext(),
+            readOutputRouterConfig(ctx.cwd),
+        ]);
+        setModeStatus(ctx, modeState);
+        notifyRouterConfigWarnings(ctx, routerConfigResult);
+        // Full skill markdown is expensive. Inject it once per session/compaction boundary,
+        // then keep later turns to a short mode/priority refresh.
+        const injectFullRuntimeContext = consumeRuntimeContextInjectionState();
+        const hasFullRuntimeContext = !injectFullRuntimeContext || hasFreeflowActivation(event.systemPrompt);
+        const routerAlreadyActivated = !injectFullRuntimeContext || hasOutputRouterActivation(event.systemPrompt);
+        const discoverAlreadyActivated = !injectFullRuntimeContext || hasDiscoverActivation(event.systemPrompt);
+        const priorityAlreadyActivated = hasFreeflowPriorityActivation(event.systemPrompt);
+        return {
+            systemPrompt: event.systemPrompt +
+                "\n\n" +
+                runtimeContext(modeState, freeflowContext, routerConfigResult, hasFullRuntimeContext, routerAlreadyActivated, discoverAlreadyActivated, priorityAlreadyActivated),
+        };
+    });
+    pi.on("tool_result", async (event, ctx) => {
+        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}`,
+            handler: async (args) => {
+                await pi.sendUserMessage(skillPrompt(skill, args));
+            },
+        });
+    }
+    for (const skill of CONTRIBUTOR_COMMANDS) {
+        pi.registerCommand(skill, {
+            description: `Run Freeflow ${skill}`,
+            handler: async (args) => {
+                await pi.sendUserMessage(skillPrompt(skill, args));
+            },
+        });
+    }
+    pi.registerCommand("workflow", {
+        description: "Set or inspect the current Freeflow session mode",
+        getArgumentCompletions: (prefix) => {
+            const query = prefix ?? "";
+            const values = ["conversation", "workflow", "strict-workflow", "reset"];
+            const filtered = values.filter((value) => value.startsWith(query));
+            return filtered.map((value) => ({ value, label: value }));
+        },
+        handler: async (args, ctx) => {
+            await handleWorkflowCommand(args, ctx, pi);
+        },
+    });
+}

package/pi-extension/dist/mcp-config.js

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