machine-bridge-mcp 1.1.5 → 1.2.1

package/scripts/coverage-check.mjs

@@ -9,16 +9,24 @@ const coverageDir = mkdtempSync(resolve(tmpdir(), "machine-bridge-coverage-"));
 const tests = [
   "tests/policy-test.mjs",
   "tests/runtime-infrastructure-test.mjs",
+  "tests/runtime-boundaries-test.mjs",
   "tests/worker-runtime-infrastructure-test.mjs",
+  "tests/worker-oauth-controller-test.mjs",
   "tests/logging-structure-test.mjs",
   "tests/runtime-handler-matrix-test.mjs",
   "tests/cli-entrypoint-test.mjs",
+  "tests/cli-service-test.mjs",
   "tests/local-self-test.mjs",
+  "tests/runtime-self-test.mjs",
   "tests/numbers-test.mjs",
   "tests/records-test.mjs",
   "tests/project-metadata-test.mjs",
   "tests/state-inventory-test.mjs",
   "tests/worker-deployment-test.mjs",
+  "tests/agent-context-test.mjs",
+  "tests/capability-ranking-test.mjs",
+  "tests/browser-bridge-test.mjs",
+  "tests/monotonic-deadline-test.mjs",
 ];
 
 try {
@@ -38,27 +46,36 @@ try {
 
   const coverage = collectCoverage(coverageDir);
   const thresholds = {
-    "src/local/policy.mjs": [75, 45],
+    "src/local/policy.mjs": [90, 65],
     "src/local/errors.mjs": [70, 50],
-    "src/local/call-registry.mjs": [80, 50],
-    "src/local/tool-executor.mjs": [90, 25],
-    "src/local/observability.mjs": [65, 35],
+    "src/local/call-registry.mjs": [85, 55],
+    "src/local/tool-executor.mjs": [90, 40],
+    "src/local/observability.mjs": [95, 40],
     "src/local/process-tracker.mjs": [65, 35],
     "src/local/log.mjs": [60, 40],
-    "src/local/runtime.mjs": [60, 35],
-    "src/local/cli.mjs": [45, 20],
+    "src/local/runtime.mjs": [75, 55],
+    "src/local/cli.mjs": [48, 21.9],
+    "src/local/cli-service.mjs": [90, 65],
     "src/local/cli-options.mjs": [65, 35],
     "src/local/cli-policy.mjs": [70, 35],
     "src/local/numbers.mjs": [100, 100],
     "src/local/records.mjs": [100, 100],
-    "src/local/project-metadata.mjs": [85, 55],
+    "src/local/project-metadata.mjs": [95, 55],
     "src/local/state-inventory.mjs": [85, 55],
     "src/local/network-proxy.mjs": [90, 65],
     "src/local/worker-health.mjs": [85, 60],
     "src/local/worker-deployment.mjs": [80, 55],
-    "src/worker/pending-calls.ts": [85, null],
-    "src/worker/policy.ts": [90, null],
-    "src/worker/errors.ts": [100, null],
+    "src/local/agent-contract.mjs": [95, 40],
+    "src/local/capability-ranking.mjs": [95, 70],
+    "src/local/browser-extension-protocol.mjs": [95, 35],
+    "src/local/browser-operation-service.mjs": [80, 50],
+    "src/local/runtime-reporting.mjs": [95, 75],
+    "src/local/runtime-diagnostics.mjs": [75, 65],
+    "src/local/runtime-capabilities.mjs": [75, 45],
+    "src/local/monotonic-deadline.mjs": [100, 100],
+    "src/worker/pending-calls.ts": [90, 35],
+    "src/worker/policy.ts": [100, 25],
+    "src/worker/errors.ts": [100, 40],
   };
   const failures = [];
   for (const [file, [minimumFunctions, minimumBlocks]] of Object.entries(thresholds)) {

package/src/local/account-access.mjs

@@ -3,20 +3,22 @@ import { BridgeError } from "./errors.mjs";
 import { policyProfile, toolNamesForPolicy, assertToolAllowed } from "./policy.mjs";
 
 export const ACCOUNT_ACCESS_REVISION = Number(accessContract.revision);
-export const ACCOUNT_ROLES = Object.freeze(Object.fromEntries(
-  Object.entries(accessContract.roles).map(([name, value]) => [name, Object.freeze({ ...value })]),
-));
+const ACCOUNT_ROLE_ENTRIES = Object.entries(accessContract.roles)
+  .map(([name, value]) => [name, Object.freeze({ ...value })]);
+const ACCOUNT_ROLE_BY_NAME = new Map(ACCOUNT_ROLE_ENTRIES);
+export const ACCOUNT_ROLES = Object.freeze(Object.fromEntries(ACCOUNT_ROLE_ENTRIES));
+export const DEFAULT_ACCOUNT_ROLE = String(accessContract.defaultRole);
 export const OWNER_ACCOUNT_ROLE = String(accessContract.ownerRole);
 
 export function normalizeAccountRole(value) {
   const role = String(value || "").trim().toLowerCase();
-  if (!ACCOUNT_ROLES[role]) throw new BridgeError("invalid_request", `unknown account role: ${role}`);
+  if (!ACCOUNT_ROLE_BY_NAME.has(role)) throw new BridgeError("invalid_request", `unknown account role: ${role}`);
   return role;
 }
 
 export function accountRolePolicy(role) {
   const normalized = normalizeAccountRole(role);
-  return policyProfile(ACCOUNT_ROLES[normalized].profile, "explicit");
+  return policyProfile(ACCOUNT_ROLE_BY_NAME.get(normalized).profile, "explicit");
 }
 
 export function accountRoleToolNames(role) {

package/src/local/agent-context.mjs

@@ -2,11 +2,15 @@ import { createHash } from "node:crypto";
 import { commandMatchText, recommendTools, relevanceScore } from "./capability-ranking.mjs";
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { createBuiltinInstruction, discoverAutomaticProjectInstruction } from "./default-instructions.mjs";
 import { automaticPackageCommands, readProjectPackageMetadata } from "./project-package.mjs";
 import { clampInteger } from "./numbers.mjs";
-import { isPlainRecord } from "./records.mjs";
+import {
+  MAX_COMMAND_ARGUMENT_BYTES, MAX_COMMANDS, MAX_SKILL_ROOTS,
+  assertAllowedPath, assertContainedPath, isContainedPath, normalizeAgentConfig, requiredString,
+  resolveConfiguredPath, resolveInstructionPath, validateStringArray,
+} from "./agent-contract.mjs";
 
 const CONFIG_RELATIVE_PATH = join(".machine-bridge", "agent.json");
 const GLOBAL_CONFIG_RELATIVE_PATH = join(".config", "machine-bridge-mcp", "agent.json");
@@ -15,20 +19,12 @@ const DEFAULT_INSTRUCTION_MAX_BYTES = 32 * 1024;
 const MAX_CONTEXT_SKILL_SUMMARY_CHARS = 8_000;
 const MAX_CONFIG_BYTES = 256 * 1024;
 const MAX_INSTRUCTION_FILE_BYTES = 512 * 1024;
-const MAX_TOTAL_INSTRUCTION_BYTES = 2 * 1024 * 1024;
 const MAX_INSTRUCTION_FILES = 64;
 const MAX_SKILL_ENTRY_BYTES = 512 * 1024;
-const MAX_SKILL_ROOTS = 32;
 const MAX_SKILL_RESULTS = 500;
 const MAX_SKILL_SCAN_ENTRIES = 20_000;
 const MAX_SKILL_SCAN_DEPTH = 8;
 const MAX_SKILL_FILES = 500;
-const MAX_COMMANDS = 128;
-const MAX_COMMAND_ARGV = 128;
-const MAX_COMMAND_ARGUMENT_BYTES = 256 * 1024;
-const COMMAND_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
-const CONFIG_KEYS = new Set(["version", "builtin_instructions", "automatic_project_context", "model_instructions_file", "instruction_files", "instruction_max_bytes", "skill_roots", "commands"]);
-const COMMAND_KEYS = new Set(["description", "argv", "cwd", "timeout_seconds", "allow_extra_args"]);
 
 export class AgentContextManager {
   constructor({ workspace, policy, displayPath, resolveExistingPath, throwIfCancelled = () => {}, home = process.env.HOME || process.env.USERPROFILE || "", codexHome = process.env.CODEX_HOME || "" }) {
@@ -84,7 +80,6 @@ export class AgentContextManager {
     return result;
   }
 
-
   async sessionBootstrap(args = {}, context = {}) {
     const state = await this.discoverState(args.path || ".", context);
     const fingerprint = capabilityFingerprint(state, []);
@@ -522,109 +517,7 @@ async function readOptionalConfig(configPath, allowedRoot, rejectPathAliases) {
   } catch {
     throw new Error(`agent config is not valid JSON: ${configPath}`);
   }
-  return normalizeConfig(parsed, configPath);
-}
-
-function normalizeConfig(value, configPath) {
-  if (!isPlainRecord(value)) throw new Error(`agent config must be a JSON object: ${configPath}`);
-  for (const key of Object.keys(value)) if (!CONFIG_KEYS.has(key)) throw new Error(`unknown agent config field '${key}': ${configPath}`);
-  if (value.version !== 1) throw new Error(`agent config version must be 1: ${configPath}`);
-  const result = {
-    builtinInstructions: null,
-    automaticProjectContext: null,
-    modelInstructionsFile: null,
-    instructionFiles: null,
-    instructionMaxBytes: null,
-    skillRoots: null,
-    commands: new Map(),
-  };
-  if (value.builtin_instructions !== undefined) {
-    if (typeof value.builtin_instructions !== "boolean") throw new Error(`builtin_instructions must be boolean: ${configPath}`);
-    result.builtinInstructions = value.builtin_instructions;
-  }
-  if (value.automatic_project_context !== undefined) {
-    if (typeof value.automatic_project_context !== "boolean") throw new Error(`automatic_project_context must be boolean: ${configPath}`);
-    result.automaticProjectContext = value.automatic_project_context;
-  }
-  if (value.model_instructions_file !== undefined) {
-    result.modelInstructionsFile = requiredString(value.model_instructions_file, "model_instructions_file");
-  }
-  if (value.instruction_files !== undefined) {
-    result.instructionFiles = validateInstructionFiles(value.instruction_files, configPath);
-  }
-  if (value.instruction_max_bytes !== undefined) {
-    if (!Number.isInteger(value.instruction_max_bytes) || value.instruction_max_bytes < 1024 || value.instruction_max_bytes > MAX_TOTAL_INSTRUCTION_BYTES) {
-      throw new Error(`instruction_max_bytes must be an integer from 1024 to ${MAX_TOTAL_INSTRUCTION_BYTES}: ${configPath}`);
-    }
-    result.instructionMaxBytes = value.instruction_max_bytes;
-  }
-  if (value.skill_roots !== undefined) {
-    result.skillRoots = validateStringArray(value.skill_roots, "skill_roots", MAX_SKILL_ROOTS, MAX_COMMAND_ARGUMENT_BYTES);
-  }
-  if (value.commands !== undefined) {
-    if (!isPlainRecord(value.commands)) throw new Error(`agent config commands must be an object: ${configPath}`);
-    for (const [name, definition] of Object.entries(value.commands)) {
-      if (!COMMAND_NAME_PATTERN.test(name)) throw new Error(`invalid registered command name '${name}': ${configPath}`);
-      if (definition === null) {
-        result.commands.set(name, null);
-        continue;
-      }
-      result.commands.set(name, normalizeCommand(definition, name, configPath));
-    }
-  }
-  return result;
-}
-
-function normalizeCommand(value, name, configPath) {
-  if (!isPlainRecord(value)) throw new Error(`registered command '${name}' must be an object: ${configPath}`);
-  for (const key of Object.keys(value)) if (!COMMAND_KEYS.has(key)) throw new Error(`unknown field '${key}' for registered command '${name}': ${configPath}`);
-  const argv = validateStringArray(value.argv, `commands.${name}.argv`, MAX_COMMAND_ARGV, MAX_COMMAND_ARGUMENT_BYTES);
-  if (!argv.length) throw new Error(`registered command '${name}' requires a non-empty argv: ${configPath}`);
-  const description = typeof value.description === "string" ? value.description.trim() : "";
-  if (!description || description.length > 1000) throw new Error(`registered command '${name}' requires a description of at most 1000 characters: ${configPath}`);
-  const cwd = value.cwd === undefined ? "." : requiredString(value.cwd, `commands.${name}.cwd`);
-  const timeoutSeconds = clampInteger(value.timeout_seconds, 120, 1, 600);
-  if (value.timeout_seconds !== undefined && timeoutSeconds !== value.timeout_seconds) {
-    throw new Error(`registered command '${name}' timeout_seconds must be an integer from 1 to 600: ${configPath}`);
-  }
-  if (value.allow_extra_args !== undefined && typeof value.allow_extra_args !== "boolean") {
-    throw new Error(`registered command '${name}' allow_extra_args must be boolean: ${configPath}`);
-  }
-  return {
-    description,
-    argv,
-    cwd,
-    timeoutSeconds,
-    allowExtraArgs: value.allow_extra_args === true,
-  };
-}
-
-function validateInstructionFiles(value, configPath) {
-  const files = validateStringArray(value, "instruction_files", 32, 64 * 1024);
-  if (!files.length) throw new Error(`instruction_files must not be empty: ${configPath}`);
-  for (const name of files) resolveInstructionPath("/", name);
-  return files;
-}
-
-function resolveInstructionPath(directory, configuredName) {
-  const raw = requiredString(configuredName, "instruction file name");
-  if (raw.includes("\0") || isAbsolute(raw)) throw new Error(`instruction file path must be relative: ${raw}`);
-  const candidate = resolve(directory, raw);
-  assertContainedPath(resolve(directory), candidate, "instruction file path");
-  return candidate;
-}
-
-function resolveConfiguredPath(configuredPath, baseDir, home, workspace, unrestricted) {
-  const raw = requiredString(configuredPath, "configured path");
-  if (raw.includes("\0")) throw new Error("configured path contains a NUL byte");
-  let expanded = raw;
-  if (raw === "~" || raw.startsWith(`~${sep}`) || raw.startsWith("~/") || raw.startsWith("~\\")) {
-    if (!home) throw new Error("HOME or USERPROFILE is required to expand '~'");
-    expanded = raw === "~" ? home : join(home, raw.slice(2));
-  }
-  const candidate = isAbsolute(expanded) ? resolve(expanded) : resolve(baseDir, expanded);
-  assertAllowedPath(candidate, workspace, unrestricted, "configured path");
-  return candidate;
+  return normalizeAgentConfig(parsed, configPath);
 }
 
 async function findSkillEntrypoint(directory) {
@@ -680,7 +573,6 @@ export function parseSkillMetadata(content) {
   return metadata;
 }
 
-
 async function listSkillFiles(root, maxFiles, context, throwIfCancelled) {
   const files = [];
   const stack = [{ directory: root, depth: 0 }];
@@ -853,42 +745,10 @@ async function readRegularUtf8(filePath, maxBytes, label) {
   }
 }
 
-function validateStringArray(value, label, maxItems, maxBytes) {
-  if (!Array.isArray(value)) throw new Error(`${label} must be an array of strings`);
-  if (value.length > maxItems) throw new Error(`${label} contains more than ${maxItems} items`);
-  let bytes = 0;
-  return value.map((item, index) => {
-    if (typeof item !== "string" || !item.length || item.includes("\0")) throw new Error(`${label}[${index}] must be a non-empty string without NUL bytes`);
-    bytes += Buffer.byteLength(item);
-    if (bytes > maxBytes) throw new Error(`${label} exceeds maximum encoded size (${maxBytes} bytes)`);
-    return item;
-  });
-}
-
-function assertAllowedPath(candidate, workspace, unrestricted, label) {
-  if (!unrestricted) assertContainedPath(workspace, candidate, label);
-}
-
-function assertContainedPath(root, target, label) {
-  if (isContainedPath(root, target)) return;
-  throw new Error(`${label} is outside the configured workspace`);
-}
-
-function isContainedPath(root, target) {
-  const rel = relative(resolve(root), resolve(target));
-  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
-}
-
-
 function boundedMessage(error) {
   return String(error?.message || error || "invalid local skill").replace(/[\r\n]+/g, " ").slice(0, 1000);
 }
 
-function requiredString(value, label) {
-  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required`);
-  return value.trim();
-}
-
 function unquoteScalar(value) {
   if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
     return value.slice(1, -1);
@@ -896,7 +756,6 @@ function unquoteScalar(value) {
   return value;
 }
 
-
 function sha256(value) {
   return createHash("sha256").update(String(value)).digest("hex");
 }

package/src/local/agent-contract.mjs

@@ -0,0 +1,206 @@
+// @ts-check
+
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { clampInteger } from "./numbers.mjs";
+import { isPlainRecord } from "./records.mjs";
+
+export const MAX_TOTAL_INSTRUCTION_BYTES = 2 * 1024 * 1024;
+export const MAX_SKILL_ROOTS = 32;
+export const MAX_COMMANDS = 128;
+export const MAX_COMMAND_ARGV = 128;
+export const MAX_COMMAND_ARGUMENT_BYTES = 256 * 1024;
+
+const COMMAND_NAME_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/;
+const CONFIG_KEYS = new Set([
+  "version", "builtin_instructions", "automatic_project_context", "model_instructions_file",
+  "instruction_files", "instruction_max_bytes", "skill_roots", "commands",
+]);
+const COMMAND_KEYS = new Set(["description", "argv", "cwd", "timeout_seconds", "allow_extra_args"]);
+
+/**
+ * @typedef {{
+ *   description: string,
+ *   argv: string[],
+ *   cwd: string,
+ *   timeoutSeconds: number,
+ *   allowExtraArgs: boolean,
+ * }} NormalizedCommand
+ */
+
+/**
+ * @typedef {{
+ *   builtinInstructions: boolean | null,
+ *   automaticProjectContext: boolean | null,
+ *   modelInstructionsFile: string | null,
+ *   instructionFiles: string[] | null,
+ *   instructionMaxBytes: number | null,
+ *   skillRoots: string[] | null,
+ *   commands: Map<string, NormalizedCommand | null>,
+ * }} NormalizedAgentConfig
+ */
+
+/**
+ * @param {unknown} value
+ * @param {string} configPath
+ * @returns {NormalizedAgentConfig}
+ */
+export function normalizeAgentConfig(value, configPath) {
+  if (!isPlainRecord(value)) throw new Error(`agent config must be a JSON object: ${configPath}`);
+  for (const key of Object.keys(value)) {
+    if (!CONFIG_KEYS.has(key)) throw new Error(`unknown agent config field '${key}': ${configPath}`);
+  }
+  if (value.version !== 1) throw new Error(`agent config version must be 1: ${configPath}`);
+  /** @type {NormalizedAgentConfig} */
+  const result = {
+    builtinInstructions: null,
+    automaticProjectContext: null,
+    modelInstructionsFile: null,
+    instructionFiles: null,
+    instructionMaxBytes: null,
+    skillRoots: null,
+    commands: new Map(),
+  };
+  if (value.builtin_instructions !== undefined) {
+    if (typeof value.builtin_instructions !== "boolean") throw new Error(`builtin_instructions must be boolean: ${configPath}`);
+    result.builtinInstructions = value.builtin_instructions;
+  }
+  if (value.automatic_project_context !== undefined) {
+    if (typeof value.automatic_project_context !== "boolean") throw new Error(`automatic_project_context must be boolean: ${configPath}`);
+    result.automaticProjectContext = value.automatic_project_context;
+  }
+  if (value.model_instructions_file !== undefined) {
+    result.modelInstructionsFile = requiredString(value.model_instructions_file, "model_instructions_file");
+  }
+  if (value.instruction_files !== undefined) {
+    result.instructionFiles = validateInstructionFiles(value.instruction_files, configPath);
+  }
+  if (value.instruction_max_bytes !== undefined) {
+    const maximum = value.instruction_max_bytes;
+    if (typeof maximum !== "number" || !Number.isInteger(maximum)
+        || maximum < 1024 || maximum > MAX_TOTAL_INSTRUCTION_BYTES) {
+      throw new Error(`instruction_max_bytes must be an integer from 1024 to ${MAX_TOTAL_INSTRUCTION_BYTES}: ${configPath}`);
+    }
+    result.instructionMaxBytes = maximum;
+  }
+  if (value.skill_roots !== undefined) {
+    result.skillRoots = validateStringArray(value.skill_roots, "skill_roots", MAX_SKILL_ROOTS, MAX_COMMAND_ARGUMENT_BYTES);
+  }
+  if (value.commands !== undefined) {
+    if (!isPlainRecord(value.commands)) throw new Error(`agent config commands must be an object: ${configPath}`);
+    for (const [name, definition] of Object.entries(value.commands)) {
+      if (!COMMAND_NAME_PATTERN.test(name)) throw new Error(`invalid registered command name '${name}': ${configPath}`);
+      result.commands.set(name, definition === null ? null : normalizeCommand(definition, name, configPath));
+    }
+  }
+  return result;
+}
+
+/** @param {string} directory @param {unknown} configuredName */
+export function resolveInstructionPath(directory, configuredName) {
+  const raw = requiredString(configuredName, "instruction file name");
+  if (raw.includes("\0") || isAbsolute(raw)) throw new Error(`instruction file path must be relative: ${raw}`);
+  const candidate = resolve(directory, raw);
+  assertContainedPath(resolve(directory), candidate, "instruction file path");
+  return candidate;
+}
+
+/**
+ * @param {unknown} configuredPath
+ * @param {string} baseDir
+ * @param {string} home
+ * @param {string} workspace
+ * @param {boolean} unrestricted
+ */
+export function resolveConfiguredPath(configuredPath, baseDir, home, workspace, unrestricted) {
+  const raw = requiredString(configuredPath, "configured path");
+  if (raw.includes("\0")) throw new Error("configured path contains a NUL byte");
+  let expanded = raw;
+  if (raw === "~" || raw.startsWith(`~${sep}`) || raw.startsWith("~/") || raw.startsWith("~\\")) {
+    if (!home) throw new Error("HOME or USERPROFILE is required to expand '~'");
+    expanded = raw === "~" ? home : join(home, raw.slice(2));
+  }
+  const candidate = isAbsolute(expanded) ? resolve(expanded) : resolve(baseDir, expanded);
+  assertAllowedPath(candidate, workspace, unrestricted, "configured path");
+  return candidate;
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} maxItems
+ * @param {number} maxBytes
+ * @returns {string[]}
+ */
+export function validateStringArray(value, label, maxItems, maxBytes) {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array of strings`);
+  if (value.length > maxItems) throw new Error(`${label} contains more than ${maxItems} items`);
+  let bytes = 0;
+  return value.map((item, index) => {
+    if (typeof item !== "string" || !item.length || item.includes("\0")) {
+      throw new Error(`${label}[${index}] must be a non-empty string without NUL bytes`);
+    }
+    bytes += Buffer.byteLength(item);
+    if (bytes > maxBytes) throw new Error(`${label} exceeds maximum encoded size (${maxBytes} bytes)`);
+    return item;
+  });
+}
+
+/** @param {string} candidate @param {string} workspace @param {boolean} unrestricted @param {string} label */
+export function assertAllowedPath(candidate, workspace, unrestricted, label) {
+  if (!unrestricted) assertContainedPath(workspace, candidate, label);
+}
+
+/** @param {string} root @param {string} target @param {string} label */
+export function assertContainedPath(root, target, label) {
+  if (isContainedPath(root, target)) return;
+  throw new Error(`${label} is outside the configured workspace`);
+}
+
+/** @param {string} root @param {string} target */
+export function isContainedPath(root, target) {
+  const rel = relative(resolve(root), resolve(target));
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+/** @param {unknown} value @param {string} label */
+export function requiredString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required`);
+  return value.trim();
+}
+
+/** @param {unknown} value @param {string} name @param {string} configPath @returns {NormalizedCommand} */
+function normalizeCommand(value, name, configPath) {
+  if (!isPlainRecord(value)) throw new Error(`registered command '${name}' must be an object: ${configPath}`);
+  for (const key of Object.keys(value)) {
+    if (!COMMAND_KEYS.has(key)) throw new Error(`unknown field '${key}' for registered command '${name}': ${configPath}`);
+  }
+  const argv = validateStringArray(value.argv, `commands.${name}.argv`, MAX_COMMAND_ARGV, MAX_COMMAND_ARGUMENT_BYTES);
+  if (!argv.length) throw new Error(`registered command '${name}' requires a non-empty argv: ${configPath}`);
+  const description = typeof value.description === "string" ? value.description.trim() : "";
+  if (!description || description.length > 1000) {
+    throw new Error(`registered command '${name}' requires a description of at most 1000 characters: ${configPath}`);
+  }
+  const cwd = value.cwd === undefined ? "." : requiredString(value.cwd, `commands.${name}.cwd`);
+  const timeoutSeconds = clampInteger(value.timeout_seconds, 120, 1, 600);
+  if (value.timeout_seconds !== undefined && timeoutSeconds !== value.timeout_seconds) {
+    throw new Error(`registered command '${name}' timeout_seconds must be an integer from 1 to 600: ${configPath}`);
+  }
+  if (value.allow_extra_args !== undefined && typeof value.allow_extra_args !== "boolean") {
+    throw new Error(`registered command '${name}' allow_extra_args must be boolean: ${configPath}`);
+  }
+  return {
+    description,
+    argv,
+    cwd,
+    timeoutSeconds,
+    allowExtraArgs: value.allow_extra_args === true,
+  };
+}
+
+/** @param {unknown} value @param {string} configPath */
+function validateInstructionFiles(value, configPath) {
+  const files = validateStringArray(value, "instruction_files", 32, 64 * 1024);
+  if (!files.length) throw new Error(`instruction_files must not be empty: ${configPath}`);
+  for (const name of files) resolveInstructionPath("/", name);
+  return files;
+}