@hassangameryt/freeflow 0.1.0 → 0.3.0

package/pi-extension/src/runtime-context.ts

@@ -0,0 +1,347 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { normalizeFreeflowConfig, normalizeLocalFreeflowConfig } from "../../router/dist/index.js";
+
+export const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+
+export const WORKFLOW_COMMANDS = [
+  { command: "discover", skill: "discover" },
+  { command: "write-spec", skill: "write-spec" },
+  { command: "review-artifact", skill: "review-artifact" },
+  { command: "write-plan", skill: "write-plan" },
+  { command: "execute-plan", skill: "execute-plan" },
+  { command: "diagnose-failure", skill: "diagnose-failure" },
+  { command: "verify-work", skill: "verify-work" },
+  { command: "review-work", skill: "review-work" },
+  { command: "commit-work", skill: "commit-work" },
+  { command: "handoff", skill: "handoff" },
+  { command: "bypass", skill: "bypass" },
+  { command: "output-router", skill: "output-router" },
+];
+
+export const CONTRIBUTOR_COMMANDS = [
+  "setup-freeflow",
+  "write-skill",
+  "evaluate-skill",
+];
+
+const MODE_STATE_ENTRY = "freeflow-mode";
+const RESET_MODE_ARGS = new Set(["reset"]);
+
+let runtimeContextCache = null;
+let currentModeOverride = null;
+let lastRouterConfigWarningKey = null;
+let shouldInjectFullRuntimeContext = true;
+
+export function resetRuntimeContextInjection() {
+  shouldInjectFullRuntimeContext = true;
+}
+
+export function consumeRuntimeContextInjectionState() {
+  const shouldInjectFull = shouldInjectFullRuntimeContext;
+  shouldInjectFullRuntimeContext = false;
+  return shouldInjectFull;
+}
+
+async function loadRuntimeContext() {
+  const [modeContractSkill, workflowSkill, interviewGateSkill, discoverSkill, outputRouterSkill] = await Promise.all([
+    readFile(new URL("../../skills/mode-contract/SKILL.md", import.meta.url), "utf8"),
+    readFile(new URL("../../skills/workflow/SKILL.md", import.meta.url), "utf8"),
+    readFile(new URL("../../skills/interview-gate/SKILL.md", import.meta.url), "utf8"),
+    readFile(new URL("../../skills/discover/SKILL.md", import.meta.url), "utf8"),
+    readFile(new URL("../../skills/output-router/SKILL.md", import.meta.url), "utf8"),
+  ]);
+
+  return { modeContractSkill, workflowSkill, interviewGateSkill, discoverSkill, outputRouterSkill };
+}
+
+export async function refreshRuntimeContext() {
+  runtimeContextCache = await loadRuntimeContext();
+  return runtimeContextCache;
+}
+
+export async function getRuntimeContext() {
+  if (runtimeContextCache) {
+    return runtimeContextCache;
+  }
+  return refreshRuntimeContext();
+}
+
+export async function readFreeflowConfig(cwd) {
+  try {
+    const raw = await readFile(join(cwd, ".freeflow/config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export async function readFreeflowLocalConfig(cwd) {
+  try {
+    const raw = await readFile(join(cwd, ".freeflow/local.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function readDefaultMode(cwd) {
+  const parsed = await readFreeflowConfig(cwd);
+  return VALID_MODES.has(parsed.defaultMode) ? parsed.defaultMode : "workflow";
+}
+
+export async function readOutputRouterConfig(cwd) {
+  const [parsed, localParsed] = await Promise.all([readFreeflowConfig(cwd), readFreeflowLocalConfig(cwd)]);
+  const normalized = normalizeFreeflowConfig(parsed);
+  const local = normalizeLocalFreeflowConfig(localParsed);
+  return {
+    config: normalized.config.outputRouter,
+    freeflowConfig: normalized.config,
+    localConfig: local.config,
+    warnings: [...normalized.warnings, ...local.warnings],
+  };
+}
+
+export function notifyRouterConfigWarnings(ctx, routerConfigResult) {
+  if (!routerConfigResult.warnings.length) {
+    return;
+  }
+
+  const key = routerConfigResult.warnings.join("\n");
+  if (key === lastRouterConfigWarningKey) {
+    return;
+  }
+
+  lastRouterConfigWarningKey = key;
+  ctx.ui.notify(`Freeflow config warning: ${routerConfigResult.warnings.join(" ")}`, "warning");
+}
+
+export function restoreModeOverride(ctx) {
+  currentModeOverride = null;
+  const entries = ctx.sessionManager?.getEntries?.() ?? [];
+
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== MODE_STATE_ENTRY) {
+      continue;
+    }
+
+    const mode = entry.data?.currentMode;
+    currentModeOverride = VALID_MODES.has(mode) ? mode : null;
+  }
+}
+
+export async function readModeState(cwd) {
+  const defaultMode = await readDefaultMode(cwd);
+  const currentMode = VALID_MODES.has(currentModeOverride) ? currentModeOverride : null;
+  return {
+    defaultMode,
+    currentMode,
+    effectiveMode: currentMode ?? defaultMode,
+  };
+}
+
+export function setModeStatus(ctx, modeState) {
+  ctx.ui.setStatus("freeflow", `freeflow: ${modeState.effectiveMode}`);
+}
+
+function describeModeState(modeState) {
+  if (modeState.currentMode) {
+    return `current ${modeState.currentMode}; default ${modeState.defaultMode}`;
+  }
+  return `default ${modeState.defaultMode}`;
+}
+
+export function skillPrompt(skill, args) {
+  const trimmed = args?.trim();
+  return trimmed ? `/skill:${skill}\n\n${trimmed}` : `/skill:${skill}`;
+}
+
+export function hasFreeflowActivation(systemPrompt) {
+  return (
+    systemPrompt.includes("## Loaded Mode Contract Skill") &&
+    systemPrompt.includes("## Loaded Workflow Skill") &&
+    systemPrompt.includes("## Loaded Interview Gate Skill")
+  );
+}
+
+export function hasDiscoverActivation(systemPrompt) {
+  return systemPrompt.includes("## Loaded Discover Skill");
+}
+
+export function hasFreeflowPriorityActivation(systemPrompt) {
+  return systemPrompt.includes("## Freeflow Runtime Priority");
+}
+
+export function hasOutputRouterActivation(systemPrompt) {
+  return systemPrompt.includes("## Loaded Output Router Skill");
+}
+
+function outputRouterModeGuidance(mode) {
+  if (mode === "conversation") {
+    return "conversation mode: keep routed-tool guidance soft; answer questions directly.";
+  }
+  if (mode === "strict-workflow") {
+    return "strict-workflow mode: strongest guidance; prefer exact, recoverable routed evidence for risky work.";
+  }
+  return "workflow mode: prefer routed tools for exploration and likely-large command output.";
+}
+
+function outputRouterContext(modeState, freeflowContext, routerConfigResult) {
+  const safetyNetText =
+    routerConfigResult.config.postToolRouting === "off"
+      ? ""
+      : "\n\nOutput-router config note: large native read/bash outputs may be vaulted and replaced with labeled routed output. Use freeflow_search with the output id to recover exact content.";
+
+  return `## Loaded Output Router Skill
+
+Mode guidance: ${outputRouterModeGuidance(modeState.effectiveMode)}${safetyNetText}
+
+\`\`\`md
+${freeflowContext.outputRouterSkill.trim()}
+\`\`\``;
+}
+
+function outputRouterReminderContext(routerConfigResult) {
+  const safetyNet = routerConfigResult.config.postToolRouting === "off"
+    ? "native safety-net=off; native read/bash stay direct unless deliberately small/exact."
+    : `native safety-net=${routerConfigResult.config.postToolRouting}; large native read/bash may be vaulted and labeled with recovery.`;
+  return `## Freeflow Output Router Reminder
+
+Tools remain available every turn:
+
+- Existing repo/vault evidence: \`freeflow_search\`.
+- Snippet/text to coordinates: \`freeflow_search action=get\`.
+- Known coordinates to exact lines: \`freeflow_search action=retrieve\`.
+- Existing data to computed facts/subsets: \`freeflow_search action=transform\`.
+- New noisy/large command or sandboxed script output: \`freeflow_run\`.
+- Independent Freeflow run/search steps: \`freeflow_batch\`.
+- Config, vault, observed-routing, or script-adapter status: \`freeflow_status\`.
+- ${safetyNet}
+
+Prefer routed tools for unknown-size, repo-wide, generated/log-adjacent, structured, or noisy output. Use native read/bash only when direct known-small output is intentional.`;
+}
+
+function runtimePriorityContext() {
+  return `## 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.`;
+}
+
+function modeContractContext(freeflowContext) {
+  return `## Loaded Mode Contract Skill
+
+\`\`\`md
+${freeflowContext.modeContractSkill.trim()}
+\`\`\``;
+}
+
+function discoverContext(freeflowContext) {
+  return `## Loaded Discover Skill
+
+\`\`\`md
+${freeflowContext.discoverSkill.trim()}
+\`\`\``;
+}
+
+export function runtimeContext(
+  modeState,
+  freeflowContext,
+  routerConfigResult,
+  alreadyActivated,
+  routerAlreadyActivated,
+  discoverAlreadyActivated,
+  priorityAlreadyActivated,
+) {
+  const currentMode = modeState.currentMode ?? "none";
+  const priorityText = priorityAlreadyActivated ? "" : `\n\n${runtimePriorityContext()}`;
+  const discoverText = discoverAlreadyActivated ? "" : `\n\n${discoverContext(freeflowContext)}`;
+  const routerText = routerAlreadyActivated || !routerConfigResult.config.enabled ? "" : `\n\n${outputRouterContext(modeState, freeflowContext, routerConfigResult)}`;
+  const routerReminderText = routerConfigResult.config.enabled ? `\n\n${outputRouterReminderContext(routerConfigResult)}` : "";
+  const shortRouterText = routerText || routerReminderText;
+
+  if (alreadyActivated) {
+    return `## Freeflow Runtime Context
+
+Repo default mode from \`.freeflow/config.json\`: ${modeState.defaultMode}.
+Current session mode override: ${currentMode}.
+Effective Freeflow mode: ${modeState.effectiveMode}.
+
+Treat the effective mode as the current mode for this turn. Follow the installed Freeflow rules for that mode; default workflow means use workflow rules for consequential work. Conversation mode is non-mutating only: discussion, read-only inspection, safe read-only commands, and planning in chat. If effective mode is conversation and the user asks to edit, create files, run mutating commands, commit, push, or otherwise change repo/system state, require switching to \`workflow\` or \`strict-workflow\` before acting, even if pressured. If mode interpretation, a mode change, or a mode mismatch affects the next action, use \`mode-contract\` before proceeding. If evidence routing or output-router config affects the next action, use \`output-router\`, \`freeflow_status\`, and live config instead of remembered routing rules. Use the installed Freeflow skills when they match the task. This Pi extension loads context and routes commands only; it does not enforce policy, block tools, grant permissions, or create repo-local hooks.${priorityText}${discoverText}${shortRouterText}`;
+  }
+
+  return `# Freeflow Runtime Context
+
+Freeflow Pi extension loaded this before the agent turn.
+These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.
+
+## Repo Setup
+
+Repo default mode from \`.freeflow/config.json\`: \`${modeState.defaultMode}\`.
+Current session mode override: \`${currentMode}\`.
+Effective Freeflow mode: \`${modeState.effectiveMode}\`.
+Treat the effective mode as the current mode for this agent turn.
+For mode changes or mode interpretation, use \`mode-contract\`.
+Do not announce the current mode on every reply. Mention it when the user asks, setup/config is discussed, or the mode changes the next action.
+
+${runtimePriorityContext()}
+
+${modeContractContext(freeflowContext)}
+
+## Loaded Workflow Skill
+
+\`\`\`md
+${freeflowContext.workflowSkill.trim()}
+\`\`\`
+
+## Loaded Interview Gate Skill
+
+\`\`\`md
+${freeflowContext.interviewGateSkill.trim()}
+\`\`\`
+
+${discoverContext(freeflowContext)}
+
+${routerText ? `${routerText.trimStart()}\n\n` : ""}This Pi extension loads context and routes commands only; it does not enforce policy, block tools, grant permissions, or create repo-local hooks.`;
+}
+
+export async function handleWorkflowCommand(args, ctx, pi) {
+  const arg = args?.trim();
+
+  if (VALID_MODES.has(arg)) {
+    currentModeOverride = arg;
+    pi.appendEntry?.(MODE_STATE_ENTRY, { currentMode: arg });
+    const modeState = await readModeState(ctx.cwd);
+    setModeStatus(ctx, modeState);
+    ctx.ui.notify(
+      `Freeflow mode is now ${modeState.effectiveMode} for this session. Repo default remains ${modeState.defaultMode}.`,
+      "info"
+    );
+    return;
+  }
+
+  if (RESET_MODE_ARGS.has(arg)) {
+    currentModeOverride = null;
+    pi.appendEntry?.(MODE_STATE_ENTRY, { currentMode: null });
+    const modeState = await readModeState(ctx.cwd);
+    setModeStatus(ctx, modeState);
+    ctx.ui.notify(`Freeflow mode reset to repo default: ${modeState.defaultMode}.`, "info");
+    return;
+  }
+
+  const modeState = await readModeState(ctx.cwd);
+  setModeStatus(ctx, modeState);
+  ctx.ui.notify(
+    `Freeflow mode is ${modeState.effectiveMode} (${describeModeState(modeState)}). Use /workflow conversation, /workflow workflow, /workflow strict-workflow, or /workflow reset.`,
+    "info"
+  );
+}

package/pi-extension/src/schemas.ts

@@ -0,0 +1,259 @@
+const STRING_SCHEMA = { type: "string" };
+const PRESERVE_SCHEMA = { type: "string", enum: ["summary", "important", "full"] };
+const SEARCH_ACTION_SCHEMA = {
+  type: "string",
+  enum: ["query", "locate", "get", "retrieve", "expand", "explain", "transform"],
+};
+const EXPANSION_SCHEMA = { type: "string", enum: ["lines_30", "lines_80", "full"] };
+const STREAM_SCHEMA = { type: "string", enum: ["stdout", "stderr", "combined", "raw"] };
+const RUN_FILTER_STREAM_SCHEMA = { type: "string", enum: ["stdout", "stderr", "combined"] };
+const NON_EMPTY_STRING_SCHEMA = { type: "string", minLength: 1 };
+const MAX_CONTEXT_LINES_SCHEMA = { type: "integer", minimum: 0, maximum: 20 };
+const MAX_REGEX_MATCHES_SCHEMA = { type: "integer", minimum: 1, maximum: 1000 };
+const MAX_GROUPS_SCHEMA = { type: "integer", minimum: 1, maximum: 1000 };
+const MAX_LINES_PER_GROUP_SCHEMA = { type: "integer", minimum: 1, maximum: 1000 };
+const MAX_DEDUPE_LINES_SCHEMA = { type: "integer", minimum: 1, maximum: 10000 };
+const MAX_TOP_N_LIMIT_SCHEMA = { type: "integer", minimum: 1, maximum: 1000 };
+const REGEX_FLAGS_SCHEMA = {
+  type: "string",
+  pattern: "^(?!.*([gimsu]).*\\1)[gimsu]*$",
+  description: "Regex flags: g, i, m, s, or u, without duplicates. g is added internally for extraction.",
+};
+const JSON_POINTER_PATTERN = String.raw`^(?:|/(?:[^~/]|~[01])*(?:/(?:[^~/]|~[01])*)*)$`;
+const JSON_PATH_PATTERN = String.raw`^\$(?:\.[A-Za-z_$][A-Za-z0-9_$-]*|\[(?:0|[1-9][0-9]*)\]|\["(?:[^"\\\u0000-\u001F]|\\(?:["\\/bfnrt]|u[0-9A-Fa-f]{4}))*"\])*$`;
+const SCRIPT_LANGUAGE_SCHEMA = { type: "string", enum: ["javascript", "python", "jq"] };
+const SCRIPT_LIMITS_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    timeoutMs: { type: "integer", minimum: 1, maximum: 30000 },
+    maxInputBytes: { type: "integer", minimum: 1, maximum: 10485760 },
+    maxOutputBytes: { type: "integer", minimum: 1, maximum: 1048576 },
+  },
+};
+
+export const FREEFLOW_STATUS_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: "string",
+      enum: ["status", "doctor", "migration"],
+      description: "Status view to render. migration is non-destructive and reports recommendations only.",
+    },
+  },
+};
+
+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." },
+    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." },
+        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." },
+        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." },
+      },
+      required: ["kind"],
+      description: "Source to search, retrieve, or transform. Repo root and vault session are supplied by Freeflow/Pi.",
+    },
+    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." },
+    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." },
+        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." },
+      },
+      required: ["language", "code"],
+      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." },
+        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." },
+        contextLines: MAX_CONTEXT_LINES_SCHEMA,
+        maxMatches: MAX_REGEX_MATCHES_SCHEMA,
+        group: NON_EMPTY_STRING_SCHEMA,
+        maxGroups: MAX_GROUPS_SCHEMA,
+        maxLinesPerGroup: MAX_LINES_PER_GROUP_SCHEMA,
+        trim: { type: "boolean" },
+        caseSensitive: { type: "boolean" },
+        maxLines: MAX_DEDUPE_LINES_SCHEMA,
+        limit: MAX_TOP_N_LIMIT_SCHEMA,
+        sort: { type: "string", enum: ["text", "numeric"] },
+        order: { type: "string", enum: ["asc", "desc"] },
+        dedupe: { type: "boolean" },
+        language: SCRIPT_LANGUAGE_SCHEMA,
+        code: NON_EMPTY_STRING_SCHEMA,
+        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.",
+    },
+    sources: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          kind: { type: "string", enum: ["vault"] },
+          outputId: NON_EMPTY_STRING_SCHEMA,
+          stream: STREAM_SCHEMA,
+          alias: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9_-]{0,63}$" },
+        },
+        required: ["kind", "outputId", "alias"],
+      },
+      description: "Vault sources for action=transform operation.kind=script.",
+    },
+    limits: { ...SCRIPT_LIMITS_SCHEMA, description: "Processing or script transform resource limits." },
+    filters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        producerKind: { type: "string", enum: ["command", "script", "native", "repo", "web", "fetch", "code_search", "mcp", "transform", "other"] },
+        server: STRING_SCHEMA,
+        tool: STRING_SCHEMA,
+        hostToolName: STRING_SCHEMA,
+        stream: STREAM_SCHEMA,
+        recordKind: { type: "string", enum: ["command", "text", "metadata", "repo-file"] },
+        recoverability: { type: "string", enum: ["exact", "redacted", "metadata_only", "none"] },
+      },
+      description: "Vault index filters for source.kind=vault query/locate.",
+    },
+    preserve: { ...PRESERVE_SCHEMA, description: "Fidelity mode. Default: important." },
+    evidence: {
+      type: "object",
+      additionalProperties: true,
+      description: "Evidence packet from a previous freeflow_search result, used for expand.",
+    },
+    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." },
+    lineRange: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        start: { type: "number" },
+        end: { type: "number" },
+      },
+      required: ["start", "end"],
+      description: "Exact 1-based line range for vault retrieve.",
+    },
+    decision: {
+      type: "object",
+      additionalProperties: true,
+      description: "Prior routed result to explain.",
+    },
+  },
+  required: ["action"],
+};
+
+export const FREEFLOW_RUN_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  oneOf: [
+    { required: ["command"] },
+    { required: ["script"] },
+  ],
+  properties: {
+    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." },
+        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." },
+      },
+      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.",
+    },
+    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." },
+    filters: {
+      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." },
+        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." },
+        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.",
+    },
+    scriptFilter: {
+      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. 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." },
+      },
+      required: ["language", "code"],
+      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,
+  properties: {
+    steps: {
+      type: "array",
+      minItems: 1,
+      maxItems: 50,
+      items: {
+        type: "object",
+        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." },
+        },
+        required: ["kind", "input"],
+      },
+      description: "Independent Freeflow-owned steps to run in parallel. No sequencing or external tool orchestration in v1.",
+    },
+    queries: {
+      type: "array",
+      maxItems: 10,
+      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." },
+    preserve: { ...PRESERVE_SCHEMA, description: "Default fidelity mode for steps that do not set preserve." },
+  },
+  required: ["steps"],
+};