@hassangameryt/freeflow 0.7.3 → 0.8.0

package/pi-extension/dist/tool-execution/apply-patch/plan.js

@@ -0,0 +1,201 @@
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { resolveToolPath } from "../file-state.js";
+import { closestMatch } from "../edit-messages.js";
+import { parsePatch } from "./parser.js";
+import { otherMatches, seekSequence } from "./match.js";
+class PlanError extends Error {}
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+const MAX_SHOWN_LINES = 20;
+function notFound(path, hunk, oldLines, lines) {
+  const subject = `${path} hunk ${hunk}`;
+  const match = closestMatch(lines.join("\n"), oldLines.join("\n"));
+  if (!match)
+    return new PlanError(
+      `${subject}: context not found and no similar lines exist in the current file. Read the region you meant, then retry.`,
+    );
+  return new PlanError(
+    [
+      `${subject}: context not found. Closest match, lines ${match.start}–${match.end} (current file contents):`,
+      ...lines.slice(match.start - 1, Math.min(match.end, match.start - 1 + MAX_SHOWN_LINES)),
+      "If these are the lines you meant, retry with context copied exactly from them. If not, read the region you meant, then retry.",
+    ].join("\n"),
+  );
+}
+/** Split text as it was stored so it can be written back the same way: BOM, line ending, final newline. */
+function splitText(raw) {
+  const bom = raw.startsWith("") ? "" : "";
+  const body = raw.slice(bom.length);
+  const firstLf = body.indexOf("\n");
+  const crlf = firstLf > 0 && body[firstLf - 1] === "\r";
+  const lf = body.replace(/\r\n/g, "\n");
+  const finalNewline = lf === "" || lf.endsWith("\n");
+  const lines = lf === "" ? [] : lf.split("\n");
+  if (lf.endsWith("\n")) lines.pop();
+  return { bom, crlf, finalNewline, lines };
+}
+function joinText(parts, lines) {
+  const text = lines.join("\n") + (parts.finalNewline && lines.length > 0 ? "\n" : "");
+  return parts.bom + (parts.crlf ? text.replace(/\n/g, "\r\n") : text);
+}
+/** Codex's compute_replacements, keeping the file's own bytes on context lines. */
+function updateLines(path, lines, chunks, notes) {
+  const replacements = [];
+  let cursor = 0;
+  chunks.forEach((chunk, index) => {
+    const hunk = index + 1;
+    if (chunk.anchor !== undefined) {
+      const anchor = seekSequence(lines, [chunk.anchor], cursor, false);
+      if (!anchor)
+        throw new PlanError(
+          `${path} hunk ${hunk}: @@ line not found: '${chunk.anchor}'. Use a line that exists in the file after the previous hunk, or leave the @@ line empty.`,
+        );
+      cursor = anchor.index + 1;
+    }
+    if (chunk.oldLines.length === 0) {
+      replacements.push({ start: lines.length, length: 0, lines: [...chunk.newLines] });
+      return;
+    }
+    let pattern = chunk.oldLines;
+    let replacement = chunk.newLines;
+    let found = seekSequence(lines, pattern, cursor, chunk.endOfFile);
+    if (!found && pattern.at(-1) === "") {
+      // A trailing empty line stands for the file's final newline, which the line list does not hold.
+      pattern = pattern.slice(0, -1);
+      if (replacement.at(-1) === "") replacement = replacement.slice(0, -1);
+      found = seekSequence(lines, pattern, cursor, chunk.endOfFile);
+    }
+    if (!found) throw notFound(path, hunk, chunk.oldLines, lines);
+    const resolved = [...replacement];
+    for (const [oldIndex, newIndex] of chunk.context)
+      if (oldIndex < pattern.length && newIndex < resolved.length) resolved[newIndex] = lines[found.index + oldIndex];
+    const others = otherMatches(lines, pattern, found.index, found.pass);
+    if (others.length > 0)
+      notes.push(
+        `${path} hunk ${hunk}: its lines also match at line ${others.map((i) => i + 1).join(", ")}; it was applied at line ${found.index + 1}.`,
+      );
+    replacements.push({ start: found.index, length: pattern.length, lines: resolved });
+    cursor = found.index + pattern.length;
+  });
+  const next = [...lines];
+  for (const { start, length, lines: added } of [...replacements].sort((a, b) => b.start - a.start))
+    next.splice(start, length, ...added);
+  return next;
+}
+async function plan(hunks, cwd, files, notes) {
+  if (hunks.length === 0) throw new PlanError("The patch changes no files. Add at least one file section, then retry.");
+  // Later sections see earlier sections' results, as they would if applied one by one.
+  const virtual = new Map();
+  const current = async (abs) => {
+    if (virtual.has(abs)) return virtual.get(abs);
+    if (!(await isFile(abs))) return null;
+    const bytes = await readFile(abs);
+    const text = bytes.toString("utf8");
+    return Buffer.from(text, "utf8").equals(bytes) ? text : "\u0000not-utf8";
+  };
+  const steps = [];
+  for (const hunk of hunks) {
+    const abs = resolveToolPath(hunk.path, cwd);
+    const existing = await current(abs);
+    if (hunk.kind === "add") {
+      if (existing !== null && !virtual.has(abs) && !files.wasRead(hunk.path, cwd))
+        throw new PlanError(
+          `${hunk.path} exists and has not been read in this session. Read ${hunk.path}, then retry the patch.`,
+        );
+      virtual.set(abs, hunk.contents);
+      steps.push({ path: hunk.path, abs, operation: "add", content: hunk.contents });
+      continue;
+    }
+    if (existing === null)
+      throw new PlanError(
+        hunk.kind === "delete"
+          ? `${hunk.path}: file not found; nothing to delete.`
+          : `${hunk.path}: file not found. Use *** Add File: ${hunk.path} to create it.`,
+      );
+    if (existing === "\u0000not-utf8")
+      throw new PlanError(`${hunk.path}: not UTF-8 text; apply_patch edits text files only.`);
+    if (!virtual.has(abs) && (await files.changedSinceObserved(hunk.path, cwd)))
+      notes.push(`${hunk.path} changed since you read it; the patch applied to the current text.`);
+    if (hunk.kind === "delete") {
+      virtual.set(abs, null);
+      steps.push({ path: hunk.path, abs, operation: "delete" });
+      continue;
+    }
+    const parts = splitText(existing);
+    const content = joinText(parts, updateLines(hunk.path, parts.lines, hunk.chunks, notes));
+    if (hunk.moveTo !== undefined) {
+      const toAbs = resolveToolPath(hunk.moveTo, cwd);
+      if ((await current(toAbs)) !== null)
+        throw new PlanError(`${hunk.moveTo} already exists. Delete or rename it first, or move to another path.`);
+      virtual.set(abs, null);
+      virtual.set(toAbs, content);
+      steps.push({ path: hunk.path, abs, operation: "move", to: hunk.moveTo, toAbs, content });
+      continue;
+    }
+    virtual.set(abs, content);
+    steps.push({ path: hunk.path, abs, operation: "update", content });
+  }
+  return steps;
+}
+async function withLocks(paths, fn) {
+  // Sorted, so two patches touching the same files never wait on each other in opposite order.
+  const [first, ...rest] = [...new Set(paths)].sort();
+  return first === undefined ? fn() : withFileMutationQueue(first, () => withLocks(rest, fn));
+}
+async function write(step) {
+  if (step.operation === "delete") return unlink(step.abs);
+  const target = step.toAbs ?? step.abs;
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, step.content, "utf8");
+  if (step.operation === "move") await unlink(step.abs);
+}
+/** Plan the whole patch against current files, then write it; a planning failure writes nothing. */
+export async function applyPatch(text, cwd, files) {
+  const notes = [];
+  let hunks;
+  try {
+    hunks = parsePatch(text);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { status: "not_applied", files: [], notes, error: `Invalid patch: ${reason}. Fix the patch, then retry.` };
+  }
+  const paths = hunks.flatMap((hunk) => [
+    resolveToolPath(hunk.path, cwd),
+    ...(hunk.kind === "update" && hunk.moveTo !== undefined ? [resolveToolPath(hunk.moveTo, cwd)] : []),
+  ]);
+  return withLocks(paths, async () => {
+    let steps;
+    try {
+      steps = await plan(hunks, cwd, files, notes);
+    } catch (error) {
+      if (!(error instanceof PlanError)) throw error;
+      return { status: "not_applied", files: [], notes, error: error.message };
+    }
+    const changes = steps.map((step) => ({
+      path: step.path,
+      operation: step.operation,
+      ...(step.to === undefined ? {} : { to: step.to }),
+      outcome: "not_written",
+    }));
+    for (const [index, step] of steps.entries()) {
+      try {
+        await write(step);
+        changes[index].outcome = "written";
+      } catch (error) {
+        changes[index].outcome = "failed";
+        changes[index].error = error instanceof Error ? error.message : String(error);
+        // A failed write may already have changed its target, so this is never reported as "not applied".
+        // Nothing after it is attempted.
+        return { status: "partial", files: changes, notes };
+      }
+    }
+    return { status: "applied", files: changes, notes };
+  });
+}

package/pi-extension/dist/tool-execution/apply-patch/tool.js

@@ -0,0 +1,84 @@
+import { APPLY_PATCH_LARK_GRAMMAR } from "./grammar.js";
+import { applyPatch } from "./plan.js";
+export const APPLY_PATCH = "apply_patch";
+const DESCRIPTION =
+  "Use the apply_patch tool to edit files. Its input is a patch: *** Begin Patch, then *** Add File:, *** Update File: (optionally followed by *** Move to:) or *** Delete File: sections, then *** End Patch. In update sections, @@ lines anchor a hunk and every other line starts with space (context), - (remove) or + (add). Include enough context lines for each hunk to match one place.";
+const CODES = { add: "A", update: "M", move: "M", delete: "D" };
+/** Codex's summary on success, so GPT models read the result they were trained on. */
+export function resultText(result) {
+  const notes = result.notes;
+  if (result.status === "applied")
+    return [
+      "Success. Updated the following files:",
+      ...result.files.map((file) => `${CODES[file.operation]} ${file.to ?? file.path}`),
+      ...notes,
+    ].join("\n");
+  if (result.status === "not_applied")
+    return [`Patch not applied; no files changed. ${result.error ?? ""}`.trim(), ...notes].join("\n");
+  const named = (outcome) =>
+    result.files.filter((file) => file.outcome === outcome).map((file) => file.to ?? file.path);
+  const failed = result.files.find((file) => file.outcome === "failed");
+  return [
+    `Patch partly applied. Written: ${named("written").join(", ") || "none"}. Not written: ${named("not_written").join(", ") || "none"}. Failed: ${failed?.to ?? failed?.path}: ${failed?.error}.`,
+    "Read the files named above before changing them again.",
+    ...notes,
+  ].join("\n");
+}
+const OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["applied", "not_applied", "partial"] },
+    files: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          operation: { type: "string", enum: ["add", "update", "delete", "move"] },
+          to: { type: "string" },
+          outcome: { type: "string", enum: ["written", "not_written", "failed"] },
+          error: { type: "string" },
+        },
+        required: ["path", "operation", "outcome"],
+      },
+    },
+  },
+  required: ["status", "files"],
+};
+/** Registered once, inactive until Tool Execution is effective (see tool-execution/tools.ts). */
+export function registerApplyPatch(pi, host) {
+  pi.registerTool({
+    name: APPLY_PATCH,
+    label: APPLY_PATCH,
+    description: DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        input: { type: "string", description: "The patch, from *** Begin Patch to *** End Patch." },
+      },
+      required: ["input"],
+    },
+    // GPT-5+ models on OpenAI endpoints receive Codex's freeform grammar tool; other models a one-string function.
+    constrainedSampling: { type: "grammar", variants: { openai_lark: APPLY_PATCH_LARK_GRAMMAR } },
+    outputSchema: OUTPUT_SCHEMA,
+    exposure: "direct",
+    defaultActive: false,
+    executionMode: "sequential",
+    async execute(_id, params, _signal, _update, ctx) {
+      if (!host.effective()) throw new Error("apply_patch is available only while Freeflow Tool Execution is on.");
+      const result = await applyPatch(String(params?.input ?? ""), ctx.cwd, await host.files(ctx));
+      const written = result.files.filter((file) => file.outcome === "written");
+      await host.written(
+        written.flatMap((file) => [file.path, ...(file.to ? [file.to] : [])]),
+        ctx,
+      );
+      return {
+        content: [{ type: "text", text: resultText(result) }],
+        details: result,
+        structuredContent: { status: result.status, files: result.files },
+        ...(result.status === "applied" ? {} : { isError: true }),
+      };
+    },
+  });
+}

package/pi-extension/dist/tool-execution/background.js

@@ -0,0 +1,238 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
+export const BASH_BACKGROUND = "bash_background";
+export const STOP_BACKGROUND = "stop_background";
+export const NOTICE_TYPE = "freeflow-background";
+export const MAX_RUNNING = 16;
+/** Marks harness messages, which arrive on their own schedule, as not written by the user. */
+export const NOTICE_PREFIX = "[Freeflow notice, not from the user]";
+const newId = () => `bg${randomBytes(6).readUIntBE(0, 6).toString(36).slice(-6).padStart(6, "0")}`;
+function labelFor(command, description) {
+  const text = description?.trim() || command.trim().split("\n")[0];
+  return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+}
+function close(stream, trailer) {
+  return new Promise((resolve) => {
+    stream.once("error", () => resolve());
+    stream.end(trailer, () => resolve());
+  });
+}
+/**
+ * Claude Code's background commands on Pi's shell backend: start and return at once, stream output to one file,
+ * notify the model when the command exits, stop on request or when the session ends.
+ */
+export class BackgroundJobs {
+  host;
+  jobs = new Map();
+  constructor(host) {
+    this.host = host;
+  }
+  running() {
+    return [...this.jobs.values()].filter((job) => job.status === "running");
+  }
+  async start(command, description, cwd, sessionId) {
+    const running = this.running();
+    if (running.length >= MAX_RUNNING)
+      throw new Error(`${MAX_RUNNING} background commands are running. Stop one with stop_background, then retry.`);
+    let id = newId();
+    while (this.jobs.has(id)) id = newId();
+    const folder = join(tmpdir(), "freeflow", sessionId.replace(/[^A-Za-z0-9._-]/g, "_"), "background");
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    const outputPath = join(folder, `${id}.output`);
+    const stream = createWriteStream(outputPath, { flags: "w", mode: 0o600 });
+    await new Promise((resolve, reject) => {
+      stream.once("open", () => resolve());
+      stream.once("error", reject);
+    });
+    const controller = new AbortController();
+    let endsWithNewline = true;
+    const job = {
+      id,
+      label: labelFor(command, description),
+      outputPath,
+      controller,
+      status: "running",
+      done: Promise.resolve(),
+    };
+    const run = createLocalBashOperations({ shellPath: this.host.shellPath() }).exec(command, cwd, {
+      onData: (data) => {
+        if (data.length === 0) return;
+        endsWithNewline = data[data.length - 1] === 10;
+        stream.write(data);
+      },
+      signal: controller.signal,
+    });
+    job.done = run.then(
+      async ({ exitCode }) => {
+        const code = exitCode ?? 1;
+        job.exitCode = code;
+        job.status = code === 0 ? "completed" : "failed";
+        await close(stream, `${endsWithNewline ? "" : "\n"}[exited with code ${code}]\n`);
+        this.notify(job);
+      },
+      async (error) => {
+        const lead = endsWithNewline ? "" : "\n";
+        if (job.stopping) {
+          job.status = "stopped";
+          await close(stream, `${lead}${job.stopping === "tool" ? "[stopped]" : "[stopped at session end]"}\n`);
+          return;
+        }
+        // The command could not run (for example, the working directory is gone).
+        job.status = "failed";
+        const message = error instanceof Error ? error.message : String(error);
+        await close(stream, `${lead}[failed to run: ${message}]\n`);
+        this.notify(job, message);
+      },
+    );
+    this.jobs.set(id, job);
+    return { id, outputPath };
+  }
+  async stop(id) {
+    const job = this.jobs.get(id);
+    if (!job) {
+      const running = this.running().map((each) => each.id);
+      throw new Error(
+        `No background command ${id} in this session. Running: ${running.length > 0 ? running.join(", ") : "none"}.`,
+      );
+    }
+    if (job.status === "running" && !job.stopping) {
+      job.stopping = "tool";
+      job.controller.abort();
+    }
+    await job.done;
+    if (job.stopping === "tool" && job.status === "stopped")
+      return { text: `Stopped ${id}.`, structured: { id, status: "stopped" } };
+    const exited =
+      job.exitCode === undefined
+        ? `${id} already ${job.status === "stopped" ? "stopped" : "failed to run"}. Output: ${job.outputPath}.`
+        : `${id} already exited with code ${job.exitCode}. Output: ${job.outputPath}.`;
+    return {
+      text: exited,
+      structured: { id, status: job.status, ...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }) },
+    };
+  }
+  /** Session end: stop every running job, wait for the processes to exit, forget them. No notice is sent. */
+  async stopAll() {
+    const running = this.running();
+    for (const job of running) {
+      job.stopping = "shutdown";
+      job.controller.abort();
+    }
+    await Promise.all(running.map((job) => job.done));
+    this.jobs = new Map();
+  }
+  /** After compaction the model may no longer see which commands it started; restate the running ones once. */
+  restate() {
+    const running = this.running();
+    if (running.length === 0) return;
+    const list = running.map((job) => `${job.id} (${job.label}), output ${job.outputPath}`).join("; ");
+    this.host.send(
+      `${NOTICE_PREFIX} Still running: ${list}. Do not start them again; stop one with stop_background before restarting it.`,
+      { running: running.map((job) => ({ id: job.id, outputPath: job.outputPath })) },
+      false,
+    );
+  }
+  notify(job, runError) {
+    if (job.stopping) return;
+    const outcome =
+      runError !== undefined
+        ? `failed to run: ${runError}`
+        : job.status === "completed"
+          ? "completed"
+          : `failed with exit code ${job.exitCode}`;
+    this.host.send(
+      `${NOTICE_PREFIX} Background command ${job.id} (${job.label}) ${outcome}. Output: ${job.outputPath}.`,
+      {
+        id: job.id,
+        status: job.status,
+        ...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+        outputPath: job.outputPath,
+      },
+      true,
+    );
+  }
+}
+const START_DESCRIPTION = [
+  "Run a shell command in the background. Use it for servers, watchers and commands expected to run longer than two minutes. Returns an ID and an output file at once; you are notified once, when the command exits. Read the output file for output so far.",
+  "To be notified when something becomes ready, run a command that exits when it is: until grep -qE 'Listening|Error|Traceback' server.log; do sleep 1; done. Match the failure lines too: a check that waits only for success stays silent when the process crashes.",
+].join("\n\n");
+const STOP_DESCRIPTION =
+  "Stop a background command started with bash_background. Returns after the command has exited.";
+/** Registered once, inactive until Tool Execution is effective (see tool-execution/tools.ts). */
+export function registerBackgroundTools(pi, jobs, host) {
+  const guard = () => {
+    if (!host.effective())
+      throw new Error("Background commands are available only while Freeflow Tool Execution is on.");
+  };
+  pi.registerTool({
+    name: BASH_BACKGROUND,
+    label: BASH_BACKGROUND,
+    description: START_DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        command: { type: "string", description: "Shell command to run" },
+        description: { type: "string", description: "A few words saying what the command does" },
+      },
+      required: ["command"],
+    },
+    outputSchema: {
+      type: "object",
+      properties: { id: { type: "string" }, outputPath: { type: "string" } },
+      required: ["id", "outputPath"],
+    },
+    exposure: "direct",
+    defaultActive: false,
+    async execute(_id, params, _signal, _u, ctx) {
+      guard();
+      const { id, outputPath } = await jobs.start(
+        String(params?.command ?? ""),
+        params?.description,
+        ctx.cwd,
+        ctx.sessionManager?.getSessionId?.() ?? "session",
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Command running in background with ID ${id}. Output: ${outputPath}. You will be notified when it exits. Read that file for output so far.`,
+          },
+        ],
+        details: { id, outputPath },
+        structuredContent: { id, outputPath },
+      };
+    },
+  });
+  pi.registerTool({
+    name: STOP_BACKGROUND,
+    label: STOP_BACKGROUND,
+    description: STOP_DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: { id: { type: "string", description: "The ID bash_background returned" } },
+      required: ["id"],
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        status: { type: "string", enum: ["stopped", "completed", "failed"] },
+        exitCode: { type: "number" },
+      },
+      required: ["id", "status"],
+    },
+    exposure: "direct",
+    defaultActive: false,
+    async execute(_id, params) {
+      guard();
+      const { text, structured } = await jobs.stop(String(params?.id ?? ""));
+      return { content: [{ type: "text", text }], details: structured, structuredContent: structured };
+    },
+  });
+}

package/pi-extension/dist/tool-execution/bash-guard.js

@@ -0,0 +1,23 @@
+// Two shell habits that lose work once background commands exist: a trailing `&` leaves a process running after the
+// call with no notice and no saved output, and a long foreground sleep holds the session while waiting on something.
+/** Seconds at or above which a foreground sleep is refused. */
+export const LONGEST_FOREGROUND_SLEEP_S = 10;
+const UNIT_SECONDS = { "": 1, s: 1, m: 60, h: 3600, d: 86400 };
+function sleepSeconds(command) {
+  let longest = 0;
+  // A sleep that starts a command: at the start, or after ; & | && || ( { then do.
+  for (const match of command.matchAll(/(?:^|[;&|({]|\bthen\b|\bdo\b)\s*sleep\s+(\d+(?:\.\d+)?)([smhd]?)\b/g))
+    longest = Math.max(longest, Number(match[1]) * UNIT_SECONDS[match[2]]);
+  return longest;
+}
+/** Why a bash command should run through bash_background instead, as one next action; undefined when it need not. */
+export function backgroundRefusal(command) {
+  if (typeof command !== "string") return undefined;
+  const trimmed = command.replace(/\s+$/, "");
+  if (/(^|[^&])&$/.test(trimmed))
+    return "A command ending in & keeps running after this call, with no exit notice and no saved output. Run it with bash_background instead, without the &.";
+  const seconds = sleepSeconds(command);
+  if (seconds >= LONGEST_FOREGROUND_SLEEP_S)
+    return `A foreground sleep of ${seconds} s holds the session. To wait for a condition, run a loop that exits when it holds, such as until <check>; do sleep 1; done, with bash_background; you will be notified when it exits.`;
+  return undefined;
+}

package/pi-extension/dist/tool-execution/config.js

@@ -0,0 +1,22 @@
+export const DEFAULT_TOOL_EXECUTION_CONFIG = Object.freeze({ enabled: false });
+// Settings of the retired v2 runtime (.deprecated/tool-execution-v2). Existing configuration files keep loading;
+// the values no longer do anything.
+const RETIRED_KEYS = ["capture", "programs", "workspace", "discovery", "adapters", "accounting"];
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function validateToolExecutionConfig(value) {
+  if (!record(value)) return "toolExecution must be an object";
+  const unknown = Object.keys(value).find((key) => key !== "enabled" && !RETIRED_KEYS.includes(key));
+  if (unknown) return `toolExecution has unsupported key: ${unknown}`;
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean")
+    return "toolExecution.enabled must be a boolean";
+  return null;
+}
+export function resolveToolExecutionConfig(repository, local, freeflowEnabled) {
+  const repositoryTool = record(repository.toolExecution) ? repository.toolExecution : {};
+  const localTool = record(local.toolExecution) ? local.toolExecution : {};
+  const setting = Object.hasOwn(localTool, "enabled") ? localTool.enabled : repositoryTool.enabled;
+  const enabled = setting === undefined ? DEFAULT_TOOL_EXECUTION_CONFIG.enabled : setting === true;
+  return { enabled, effective: freeflowEnabled && enabled };
+}