@hassangameryt/freeflow 0.3.0 → 0.5.0

package/pi-extension/src/{router-tools.ts → output-router/router-tools.ts}

@@ -1,4 +1,13 @@
-import { discoverEryxPythonSandboxAdaptersFromEnv, discoverJqWasmSandboxAdaptersFromEnv, discoverQuickJsWasiSandboxAdaptersFromEnv, freeflowBatch, freeflowTransform, freeflowSearch, freeflowRun, processSource } from "../../router/dist/index.js";
+import {
+  discoverEryxPythonSandboxAdaptersFromEnv,
+  discoverJqWasmSandboxAdaptersFromEnv,
+  discoverQuickJsWasiSandboxAdaptersFromEnv,
+  freeflowBatch,
+  freeflowTransform,
+  freeflowSearch,
+  freeflowRun,
+  processSource,
+} from "../../../router/dist/index.js";
 import { buildFreeflowStatusReport } from "./status.js";
 import {
   renderFreeflowBatchCall,
@@ -10,9 +19,20 @@ import {
   renderFreeflowStatusCall,
   renderFreeflowStatusResult,
 } from "./renderers.js";
-import { readOutputRouterConfig, notifyRouterConfigWarnings } from "./runtime-context.js";
-import { FREEFLOW_BATCH_PARAMETERS, FREEFLOW_RUN_PARAMETERS, FREEFLOW_SEARCH_PARAMETERS, FREEFLOW_STATUS_PARAMETERS } from "./schemas.js";
-import { compactBatchToolText, compactRunToolText, compactSearchToolText, getRouterSessionId, routedToolText } from "./utils.js";
+import { readOutputRouterConfig, notifyRouterConfigWarnings } from "../runtime/runtime-context.js";
+import {
+  FREEFLOW_BATCH_PARAMETERS,
+  FREEFLOW_RUN_PARAMETERS,
+  FREEFLOW_SEARCH_PARAMETERS,
+  FREEFLOW_STATUS_PARAMETERS,
+} from "./schemas.js";
+import {
+  compactBatchToolText,
+  compactRunToolText,
+  compactSearchToolText,
+  getRouterSessionId,
+  routedToolText,
+} from "./utils.js";
 
 function normalizeTransformOperation(operation) {
   if (!operation || typeof operation !== "object" || Array.isArray(operation)) {
@@ -70,7 +90,7 @@ async function normalizeTransformParams(params, ctx) {
 }
 
 async function normalizeSearchEvidenceParams(params, ctx, providedRouterConfigResult = undefined) {
-  const routerConfigResult = providedRouterConfigResult ?? await readOutputRouterConfig(ctx.cwd);
+  const routerConfigResult = providedRouterConfigResult ?? (await readOutputRouterConfig(ctx.cwd));
   if (!providedRouterConfigResult) {
     notifyRouterConfigWarnings(ctx, routerConfigResult);
   }
@@ -88,6 +108,21 @@ async function normalizeSearchEvidenceParams(params, ctx, providedRouterConfigRe
     };
   }
 
+  if (source.kind === "local") {
+    if (!source.root) {
+      throw new Error("freeflow_search source.kind=local requires an explicit absolute source.root.");
+    }
+    return {
+      ...params,
+      generatedPathGlobs: routerConfigResult.config.hints?.generatedPathGlobs,
+      source: {
+        kind: "local",
+        root: source.root,
+        ...(source.path ? { path: source.path } : {}),
+      },
+    };
+  }
+
   if (source.kind === "vault") {
     if (!source.outputId && params.action !== "query" && params.action !== "locate" && params.action !== "get") {
       throw new Error("freeflow_search source.kind=vault requires source.outputId for retrieve, expand, and explain.");
@@ -141,6 +176,37 @@ async function normalizeSearchTransformProcessingParams(params, ctx, routerConfi
     };
   }
 
+  if (source.kind === "local") {
+    if (!source.root) {
+      throw new Error("freeflow_search action=transform source.kind=local requires an explicit absolute source.root.");
+    }
+    if (!source.path) {
+      throw new Error(
+        "freeflow_search action=transform source.kind=local requires source.path for an explicit local file.",
+      );
+    }
+    return {
+      source: { kind: "local-file", root: source.root, path: source.path },
+      options: {
+        sessionId: getRouterSessionId(ctx),
+        vaultRoot: routerConfigResult.config.vault.root,
+        vaultRetention: routerConfigResult.config.vault.retention,
+        goal: params.goal,
+        limits: params.limits,
+        script: params.script,
+        scriptTransform: routerConfigResult.freeflowConfig.scriptTransform,
+        localConfig: routerConfigResult.localConfig,
+        scriptSandboxAdapters: params.script
+          ? [
+              ...(await discoverQuickJsWasiSandboxAdaptersFromEnv()),
+              ...(await discoverJqWasmSandboxAdaptersFromEnv()),
+              ...(await discoverEryxPythonSandboxAdaptersFromEnv()),
+            ]
+          : [],
+      },
+    };
+  }
+
   if (source.kind === "vault") {
     if (!source.outputId) {
       throw new Error("freeflow_search action=transform source.kind=vault requires source.outputId.");
@@ -180,13 +246,14 @@ async function executeSearch(params, ctx, routerConfigResult) {
   if (params.action === "transform") {
     if (params.operation) {
       const normalized = await normalizeTransformParams(params, ctx);
-      const scriptSandboxAdapters = normalized.operation?.kind === "script"
-        ? [
-            ...(await discoverQuickJsWasiSandboxAdaptersFromEnv()),
-            ...(await discoverJqWasmSandboxAdaptersFromEnv()),
-            ...(await discoverEryxPythonSandboxAdaptersFromEnv()),
-          ]
-        : [];
+      const scriptSandboxAdapters =
+        normalized.operation?.kind === "script"
+          ? [
+              ...(await discoverQuickJsWasiSandboxAdaptersFromEnv()),
+              ...(await discoverJqWasmSandboxAdaptersFromEnv()),
+              ...(await discoverEryxPythonSandboxAdaptersFromEnv()),
+            ]
+          : [];
       return freeflowTransform({
         ...normalized,
         sessionId: getRouterSessionId(ctx),
@@ -235,7 +302,9 @@ async function normalizeBatchParams(params, ctx, routerConfigResult) {
     }
     if (step.kind === "search") {
       if (input.action === "transform") {
-        throw new Error("freeflow_batch search transform steps are not public yet; use freeflow_search directly for transform processing.");
+        throw new Error(
+          "freeflow_batch search transform steps are not public yet; use freeflow_search directly for transform processing.",
+        );
       }
       steps.push({
         id: step.id,
@@ -273,6 +342,25 @@ function batchNeedsScriptAdapters(params) {
   });
 }
 
+function disabledByConfigToolResult(toolName) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${toolName}|disabled_by_config\ncapability|output-router\nroute|configure with /output-router settings`,
+      },
+    ],
+    details: {
+      result: {
+        toolStatus: "disabled_by_config",
+        toolName,
+        capability: "output-router",
+        route: "/output-router settings",
+      },
+    },
+  };
+}
+
 function createPiCommandRunner(pi, signal) {
   return {
     async run(request) {
@@ -286,7 +374,9 @@ function createPiCommandRunner(pi, signal) {
       const durationMs = Date.now() - startedAt;
       const killed = Boolean(result.killed);
       const code = typeof result.code === "number" ? result.code : null;
-      const executionStatus = (signal?.aborted ? "cancelled" : killed ? "timed_out" : code === 0 ? "success" : "failed") as "cancelled" | "timed_out" | "success" | "failed";
+      const executionStatus = (
+        signal?.aborted ? "cancelled" : killed ? "timed_out" : code === 0 ? "success" : "failed"
+      ) as "cancelled" | "timed_out" | "success" | "failed";
       return {
         stdout: result.stdout ?? "",
         stderr: result.stderr ?? "",
@@ -304,7 +394,8 @@ export function registerRouterTools(pi) {
     label: "Freeflow Status",
     description:
       "Inspect effective Freeflow router, observed-routing, script-transform, vault, warnings, and non-destructive migration recommendations.",
-    promptSnippet: "Inspect Freeflow effective config, observed routing, script transform, vault status, and migration recommendations.",
+    promptSnippet:
+      "Inspect Freeflow effective config, observed routing, script transform, vault status, and migration recommendations.",
     promptGuidelines: [
       "Use freeflow_status when setup/config/status/doctor evidence is needed.",
       "Status and migration recommendations are read-only; do not rewrite .freeflow/config.json without explicit confirmation.",
@@ -329,10 +420,11 @@ export function registerRouterTools(pi) {
     name: "freeflow_search",
     label: "Freeflow Search",
     description:
-      "Search, retrieve, expand, explain, or transform repo and vaulted Freeflow evidence. Returns compact facts with recoverable source pointers.",
-    promptSnippet: "Search repo/vault evidence or transform file/output sources with compact recoverable results.",
+      "Search, retrieve, expand, explain, or transform repo, explicit local, and vaulted Freeflow evidence. Returns compact facts with recoverable source pointers.",
+    promptSnippet:
+      "Search repo/local/vault evidence or transform file/output sources with compact recoverable results.",
     promptGuidelines: [
-      "Use freeflow_search for targeted repo or vault evidence before reading whole files or dumping captured output.",
+      "Use freeflow_search for targeted repo, explicit local, or vault evidence before reading whole files or dumping captured output.",
       "Use freeflow_search with source.kind=vault and an outputId to recover exact output from freeflow_run.",
       "Use freeflow_search action=transform for file/output processing through deterministic reducers or explicit scripts.",
     ],
@@ -340,6 +432,9 @@ export function registerRouterTools(pi) {
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
       notifyRouterConfigWarnings(ctx, routerConfigResult);
+      if (!routerConfigResult.config.enabled) {
+        return disabledByConfigToolResult("freeflow_search");
+      }
       const result = await executeSearch(params, ctx, routerConfigResult);
       return {
         content: [{ type: "text", text: compactSearchToolText(result) }],
@@ -369,14 +464,18 @@ export function registerRouterTools(pi) {
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
       notifyRouterConfigWarnings(ctx, routerConfigResult);
+      if (!routerConfigResult.config.enabled) {
+        return disabledByConfigToolResult("freeflow_run");
+      }
       const runner = createPiCommandRunner(pi, signal);
-      const scriptSandboxAdapters = params.script || params.scriptFilter
-        ? [
-            ...(await discoverQuickJsWasiSandboxAdaptersFromEnv()),
-            ...(await discoverJqWasmSandboxAdaptersFromEnv()),
-            ...(await discoverEryxPythonSandboxAdaptersFromEnv()),
-          ]
-        : [];
+      const scriptSandboxAdapters =
+        params.script || params.scriptFilter
+          ? [
+              ...(await discoverQuickJsWasiSandboxAdaptersFromEnv()),
+              ...(await discoverJqWasmSandboxAdaptersFromEnv()),
+              ...(await discoverEryxPythonSandboxAdaptersFromEnv()),
+            ]
+          : [];
       const result = await freeflowRun(
         {
           command: params.command,
@@ -421,18 +520,21 @@ export function registerRouterTools(pi) {
     name: "freeflow_batch",
     label: "Freeflow Batch",
     description:
-      "Run independent Freeflow-owned operations in parallel and return one compact summary while preserving full child results in details.result.steps.",
+      "Run independent Freeflow-owned run/search operations in parallel and return one compact summary while preserving full child results in details.result.steps.",
     promptSnippet: "Batch independent Freeflow run/search operations with compact model-visible output.",
     promptGuidelines: [
-      "Use freeflow_batch when several independent Freeflow-owned run/search operations can run in parallel.",
+      "Use freeflow_batch when several independent Freeflow run/search operations can run in parallel.",
       "Use queries[] when the batch should answer deterministic fact requests from completed child evidence handles.",
-      "Do not use freeflow_batch for sequenced workflows, arbitrary external tool orchestration, or mutating batch work in v1.",
+      "Do not use freeflow_batch for sequenced workflows, arbitrary external tool orchestration, or unsafe parallel writer behavior.",
       "Intermediate child outputs are suppressed unless needed for query answers; inspect details.result.steps or child recovery ids when needed.",
     ],
     parameters: FREEFLOW_BATCH_PARAMETERS,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
       notifyRouterConfigWarnings(ctx, routerConfigResult);
+      if (!routerConfigResult.config.enabled) {
+        return disabledByConfigToolResult("freeflow_batch");
+      }
       const normalized = await normalizeBatchParams(params, ctx, routerConfigResult);
       const runner = createPiCommandRunner(pi, signal);
       const scriptSandboxAdapters = batchNeedsScriptAdapters(params)
@@ -474,5 +576,4 @@ export function registerRouterTools(pi) {
       return renderFreeflowBatchResult(result, options, theme);
     },
   });
-
 }

package/pi-extension/src/{schemas.ts → output-router/schemas.ts}

@@ -48,47 +48,111 @@ export const FREEFLOW_SEARCH_PARAMETERS = {
   type: "object",
   additionalProperties: false,
   properties: {
-    action: { ...SEARCH_ACTION_SCHEMA, description: "Search/retrieval action to perform, or transform to process a repo/vault source." },
+    action: {
+      ...SEARCH_ACTION_SCHEMA,
+      description: "Search/retrieval action to perform, or transform to process a repo/local/vault source.",
+    },
     source: {
       type: "object",
       additionalProperties: false,
       properties: {
-        kind: { type: "string", enum: ["repo", "vault"] },
-        path: { ...STRING_SCHEMA, description: "Repo path for source.kind=repo." },
-        outputId: { ...STRING_SCHEMA, description: "Vault output id for source.kind=vault. Optional for vault query/locate." },
+        kind: { type: "string", enum: ["repo", "local", "vault"] },
+        root: { ...STRING_SCHEMA, description: "Absolute local root for source.kind=local." },
+        path: {
+          ...STRING_SCHEMA,
+          description: "Repo path for source.kind=repo, or relative local path for source.kind=local.",
+        },
+        outputId: {
+          ...STRING_SCHEMA,
+          description: "Vault output id for source.kind=vault. Optional for vault query/locate.",
+        },
         stream: { ...STREAM_SCHEMA, description: "Vault stream to read or filter." },
-        producerKind: { type: "string", enum: ["command", "script", "native", "repo", "web", "fetch", "code_search", "mcp", "transform", "other"], description: "Vault index producer-kind filter for source.kind=vault query/locate." },
+        producerKind: {
+          type: "string",
+          enum: ["command", "script", "native", "repo", "web", "fetch", "code_search", "mcp", "transform", "other"],
+          description: "Vault index producer-kind filter for source.kind=vault query/locate.",
+        },
         server: { ...STRING_SCHEMA, description: "Vault index MCP server filter for source.kind=vault query/locate." },
         tool: { ...STRING_SCHEMA, description: "Vault index MCP/tool filter for source.kind=vault query/locate." },
-        hostToolName: { ...STRING_SCHEMA, description: "Vault index host-tool filter for source.kind=vault query/locate." },
-        recordKind: { type: "string", enum: ["command", "text", "metadata", "repo-file"], description: "Vault record-kind filter for source.kind=vault query/locate." },
-        recoverability: { type: "string", enum: ["exact", "redacted", "metadata_only", "none"], description: "Vault recoverability filter for source.kind=vault query/locate." },
+        hostToolName: {
+          ...STRING_SCHEMA,
+          description: "Vault index host-tool filter for source.kind=vault query/locate.",
+        },
+        recordKind: {
+          type: "string",
+          enum: ["command", "text", "metadata", "repo-file"],
+          description: "Vault record-kind filter for source.kind=vault query/locate.",
+        },
+        recoverability: {
+          type: "string",
+          enum: ["exact", "redacted", "metadata_only", "none"],
+          description: "Vault recoverability filter for source.kind=vault query/locate.",
+        },
       },
       required: ["kind"],
-      description: "Source to search, retrieve, or transform. Repo root and vault session are supplied by Freeflow/Pi.",
+      description:
+        "Source to search, retrieve, or transform. Repo root and vault session are supplied by Freeflow/Pi; local sources require an explicit absolute root per call.",
     },
     query: { ...STRING_SCHEMA, description: "Text query for query/locate actions." },
-    goal: { ...STRING_SCHEMA, description: "Goal for action=transform, such as log analysis, CSV summary, or test output processing." },
+    goal: {
+      ...STRING_SCHEMA,
+      description: "Goal for action=transform, such as log analysis, CSV summary, or test output processing.",
+    },
     script: {
       type: "object",
       additionalProperties: false,
       properties: {
         language: { ...SCRIPT_LANGUAGE_SCHEMA, description: "Processing script language." },
-        code: { ...NON_EMPTY_STRING_SCHEMA, description: "Processing script code. Raw code is not persisted by default." },
+        code: {
+          ...NON_EMPTY_STRING_SCHEMA,
+          description: "Processing script code. Raw code is not persisted by default.",
+        },
         label: { ...NON_EMPTY_STRING_SCHEMA, description: "Optional script label." },
-        alias: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$", description: "Input source alias exposed to the processing script." },
-        policy: { type: "string", enum: ["sandboxed", "unsafe-unsandboxed"], description: "Script execution policy. unsafe-unsandboxed requires local-only opt-in and is visibly labeled." },
-        limits: { ...SCRIPT_LIMITS_SCHEMA, description: "Script resource limits. They only tighten configured limits." },
+        alias: {
+          type: "string",
+          pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$",
+          description: "Input source alias exposed to the processing script.",
+        },
+        policy: {
+          type: "string",
+          enum: ["sandboxed", "unsafe-unsandboxed"],
+          description: "Script execution policy. unsafe-unsandboxed requires local-only opt-in and is visibly labeled.",
+        },
+        limits: {
+          ...SCRIPT_LIMITS_SCHEMA,
+          description: "Script resource limits. They only tighten configured limits.",
+        },
       },
       required: ["language", "code"],
-      description: "Optional programmable processing for action=transform. Sandboxed remains default; unsafe-unsandboxed requires .freeflow/local.json opt-in.",
+      description:
+        "Optional programmable processing for action=transform. Sandboxed remains default; unsafe-unsandboxed requires .freeflow/local.json opt-in.",
     },
     operation: {
       type: "object",
       additionalProperties: false,
       properties: {
-        kind: { type: "string", enum: ["regexFilter", "countMatches", "jsonExtract", "groupByRegex", "dedupe", "topN", "extractUrls", "extractCitations", "lineStats", "sizeStats", "script"], description: "Deterministic transform operation for action=transform over vaulted output, or sandboxed script transform." },
-        pattern: { ...NON_EMPTY_STRING_SCHEMA, description: "Regex pattern for regexFilter, countMatches, groupByRegex, or regex-backed topN." },
+        kind: {
+          type: "string",
+          enum: [
+            "regexFilter",
+            "countMatches",
+            "jsonExtract",
+            "groupByRegex",
+            "dedupe",
+            "topN",
+            "extractUrls",
+            "extractCitations",
+            "lineStats",
+            "sizeStats",
+            "script",
+          ],
+          description:
+            "Deterministic transform operation for action=transform over vaulted output, or sandboxed script transform.",
+        },
+        pattern: {
+          ...NON_EMPTY_STRING_SCHEMA,
+          description: "Regex pattern for regexFilter, countMatches, groupByRegex, or regex-backed topN.",
+        },
         flags: REGEX_FLAGS_SCHEMA,
         pointer: { ...STRING_SCHEMA, pattern: JSON_POINTER_PATTERN, description: "JSON Pointer for jsonExtract." },
         path: { ...NON_EMPTY_STRING_SCHEMA, pattern: JSON_PATH_PATTERN, description: "JSON path for jsonExtract." },
@@ -109,7 +173,8 @@ export const FREEFLOW_SEARCH_PARAMETERS = {
         label: NON_EMPTY_STRING_SCHEMA,
       },
       required: ["kind"],
-      description: "Optional deterministic transform operation for action=transform. Existing source raw output remains recoverable by lineage when available.",
+      description:
+        "Optional deterministic transform operation for action=transform. Existing source raw output remains recoverable by lineage when available.",
     },
     sources: {
       type: "array",
@@ -132,7 +197,10 @@ export const FREEFLOW_SEARCH_PARAMETERS = {
       type: "object",
       additionalProperties: false,
       properties: {
-        producerKind: { type: "string", enum: ["command", "script", "native", "repo", "web", "fetch", "code_search", "mcp", "transform", "other"] },
+        producerKind: {
+          type: "string",
+          enum: ["command", "script", "native", "repo", "web", "fetch", "code_search", "mcp", "transform", "other"],
+        },
         server: STRING_SCHEMA,
         tool: STRING_SCHEMA,
         hostToolName: STRING_SCHEMA,
@@ -150,7 +218,11 @@ export const FREEFLOW_SEARCH_PARAMETERS = {
     },
     expansion: { ...EXPANSION_SCHEMA, description: "Expansion breadth for expand action." },
     maxFullBytes: { type: "number", description: "Cap for preserve=full before exact chunks are returned." },
-    topK: { type: "number", description: "Number of ranked repo or vault candidates for query/locate. Defaults: query=1, locate=5; max 10." },
+    topK: {
+      type: "number",
+      description:
+        "Number of ranked repo, local, or vault candidates for query/locate. Defaults: query=1, locate=5; max 10.",
+    },
     lineRange: {
       type: "object",
       additionalProperties: false,
@@ -173,25 +245,42 @@ export const FREEFLOW_SEARCH_PARAMETERS = {
 export const FREEFLOW_RUN_PARAMETERS = {
   type: "object",
   additionalProperties: false,
-  oneOf: [
-    { required: ["command"] },
-    { required: ["script"] },
-  ],
+  oneOf: [{ required: ["command"] }, { required: ["script"] }],
   properties: {
-    command: { ...STRING_SCHEMA, description: "Shell command to run through Pi's approved command runner. Mutually exclusive with script." },
+    command: {
+      ...STRING_SCHEMA,
+      description: "Shell command to run through Pi's approved command runner. Mutually exclusive with script.",
+    },
     script: {
       type: "object",
       additionalProperties: false,
       properties: {
-        language: { ...SCRIPT_LANGUAGE_SCHEMA, description: "Sandboxed script language. Requires configured scriptTransform.enabled and a proof-backed adapter." },
-        code: { ...NON_EMPTY_STRING_SCHEMA, description: "Script code to run as the base producer. Raw code is not persisted; metadata stores a code hash." },
+        language: {
+          ...SCRIPT_LANGUAGE_SCHEMA,
+          description:
+            "Sandboxed script language. Requires configured scriptTransform.enabled and a proof-backed adapter.",
+        },
+        code: {
+          ...NON_EMPTY_STRING_SCHEMA,
+          description:
+            "Script code to run as the base producer. Raw code is not persisted; metadata stores a code hash.",
+        },
         label: { ...NON_EMPTY_STRING_SCHEMA, description: "Optional script producer label." },
-        limits: { ...SCRIPT_LIMITS_SCHEMA, description: "Script resource limits. They only tighten configured scriptTransform defaults. Top-level timeoutMs is used as timeoutMs when script.limits.timeoutMs is omitted." },
+        limits: {
+          ...SCRIPT_LIMITS_SCHEMA,
+          description:
+            "Script resource limits. They only tighten configured scriptTransform defaults. Top-level timeoutMs is used as timeoutMs when script.limits.timeoutMs is omitted.",
+        },
       },
       required: ["language", "code"],
-      description: "Sandboxed script to run as the base producer for freeflow_run. Mutually exclusive with command. Captured stdout/stderr route through normal run storage, parsing, filtering, and recovery.",
+      description:
+        "Sandboxed script to run as the base producer for freeflow_run. Mutually exclusive with command. Captured stdout/stderr route through normal run storage, parsing, filtering, and recovery.",
+    },
+    cwd: {
+      ...STRING_SCHEMA,
+      description:
+        "Working directory. Defaults to the current Pi cwd. For sandboxed script producers this is metadata only; repo/home/env/network are not mounted.",
     },
-    cwd: { ...STRING_SCHEMA, description: "Working directory. Defaults to the current Pi cwd. For sandboxed script producers this is metadata only; repo/home/env/network are not mounted." },
     timeoutMs: { type: "number", description: "Optional timeout in milliseconds." },
     preserve: { ...PRESERVE_SCHEMA, description: "Fidelity mode. Default: important." },
     goal: { ...STRING_SCHEMA, description: "Goal such as verification, test, build, or search." },
@@ -199,33 +288,56 @@ export const FREEFLOW_RUN_PARAMETERS = {
       type: "object",
       additionalProperties: false,
       properties: {
-        stream: { ...RUN_FILTER_STREAM_SCHEMA, description: "Output stream to filter. Defaults to Freeflow's selected routed stream." },
-        include: { type: "array", items: NON_EMPTY_STRING_SCHEMA, description: "Regex patterns; keep lines matching any pattern." },
-        exclude: { type: "array", items: NON_EMPTY_STRING_SCHEMA, description: "Regex patterns; drop lines matching any pattern after include filtering." },
+        stream: {
+          ...RUN_FILTER_STREAM_SCHEMA,
+          description: "Output stream to filter. Defaults to Freeflow's selected routed stream.",
+        },
+        include: {
+          type: "array",
+          items: NON_EMPTY_STRING_SCHEMA,
+          description: "Regex patterns; keep lines matching any pattern.",
+        },
+        exclude: {
+          type: "array",
+          items: NON_EMPTY_STRING_SCHEMA,
+          description: "Regex patterns; drop lines matching any pattern after include filtering.",
+        },
         flags: REGEX_FLAGS_SCHEMA,
         head: { type: "integer", minimum: 1, description: "Keep the first N filtered lines." },
-        tail: { type: "integer", minimum: 1, description: "Keep the last N filtered lines. With head, returns the union of both spans." },
+        tail: {
+          type: "integer",
+          minimum: 1,
+          description: "Keep the last N filtered lines. With head, returns the union of both spans.",
+        },
         maxLines: { type: "integer", minimum: 1, description: "Maximum filtered lines to return." },
         maxBytes: { type: "integer", minimum: 1, description: "Maximum bytes of filtered evidence to return." },
       },
-      description: "Declarative line filters applied after raw capture and before routed evidence is returned. Exact raw output remains recoverable.",
+      description:
+        "Declarative line filters applied after raw capture and before routed evidence is returned. Exact raw output remains recoverable.",
     },
     scriptFilter: {
       type: "object",
       additionalProperties: false,
       properties: {
-        language: { ...SCRIPT_LANGUAGE_SCHEMA, description: "Sandboxed script language. Requires configured scriptTransform.enabled and a proof-backed adapter." },
+        language: {
+          ...SCRIPT_LANGUAGE_SCHEMA,
+          description:
+            "Sandboxed script language. Requires configured scriptTransform.enabled and a proof-backed adapter.",
+        },
         code: { ...NON_EMPTY_STRING_SCHEMA, description: "Script code. Raw code is not persisted by default." },
         label: { ...NON_EMPTY_STRING_SCHEMA, description: "Optional script filter label." },
-        limits: { ...SCRIPT_LIMITS_SCHEMA, description: "Script resource limits. They only tighten configured scriptTransform defaults." },
+        limits: {
+          ...SCRIPT_LIMITS_SCHEMA,
+          description: "Script resource limits. They only tighten configured scriptTransform defaults.",
+        },
       },
       required: ["language", "code"],
-      description: "Sandboxed programmable filter over captured stdout/stderr/combined after raw command output is vaulted. No unsandboxed fallback is used.",
+      description:
+        "Sandboxed programmable filter over captured stdout/stderr/combined after raw command output is vaulted. No unsandboxed fallback is used.",
     },
   },
 };
 
-
 export const FREEFLOW_BATCH_PARAMETERS = {
   type: "object",
   additionalProperties: false,
@@ -239,12 +351,23 @@ export const FREEFLOW_BATCH_PARAMETERS = {
         additionalProperties: false,
         properties: {
           id: { ...NON_EMPTY_STRING_SCHEMA, description: "Optional stable step id for matching results." },
-          kind: { type: "string", enum: ["run", "search"], description: "Freeflow-owned public operation kind. Steps are independent and run in parallel." },
-          input: { type: "object", additionalProperties: true, description: "Input for the selected Freeflow operation. Uses the same shape as freeflow_run or freeflow_search." },
+          kind: {
+            type: "string",
+            enum: ["run", "search"],
+            description:
+              "Freeflow-owned public operation kind. Steps are independent and run in parallel when their safety contracts allow it.",
+          },
+          input: {
+            type: "object",
+            additionalProperties: true,
+            description:
+              "Input for the selected Freeflow operation. Uses the same shape as freeflow_run or freeflow_search.",
+          },
         },
         required: ["kind", "input"],
       },
-      description: "Independent Freeflow-owned steps to run in parallel. No sequencing or external tool orchestration in v1.",
+      description:
+        "Independent Freeflow-owned steps to run in parallel. No sequencing, arbitrary external tool orchestration, or unsafe parallel writer behavior.",
     },
     queries: {
       type: "array",
@@ -252,7 +375,12 @@ export const FREEFLOW_BATCH_PARAMETERS = {
       items: { ...NON_EMPTY_STRING_SCHEMA, maxLength: 500 },
       description: "Optional independent query/fact requests to answer from completed child evidence handles.",
     },
-    concurrency: { type: "integer", minimum: 1, maximum: 16, description: "Maximum number of independent steps to run at once. Default: 4." },
+    concurrency: {
+      type: "integer",
+      minimum: 1,
+      maximum: 16,
+      description: "Maximum number of independent steps to run at once. Default: 4.",
+    },
     preserve: { ...PRESERVE_SCHEMA, description: "Default fidelity mode for steps that do not set preserve." },
   },
   required: ["steps"],