machine-bridge-mcp 0.15.0 → 0.16.0

package/src/local/managed-jobs.mjs

@@ -7,30 +7,29 @@ import { assertStateMaintenanceAvailable, ensureOwnerOnlyDir, ownerOnlyFile } fr
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { currentProcessStartTimeMs, inspectProcessInstance, processStartTimeMs } from "./process-identity.mjs";
 import { readBoundedRegularFileSync, readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
+import { createToolAuthorizer } from "./policy.mjs";
+import { BridgeError } from "./errors.mjs";
+import { inspectResourceFile, normalizeResourceRegistry, publicResourceRegistry, validatePlan, validateResourceName } from "./managed-job-plan.mjs";
+export { inspectResourceFile, publicResourceRegistry, validateResourceName } from "./managed-job-plan.mjs";
 
-const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
 const JOB_ID = /^job_[A-Za-z0-9_-]{24,}$/;
-const RESOURCE_TOKEN = /\{\{resource:([a-z][a-z0-9._-]{0,63})\}\}/g;
-const MAX_RESOURCE_BYTES = 1024 * 1024;
-const MAX_JOB_RESOURCE_BYTES = 8 * 1024 * 1024;
-const MAX_RESOURCES = 64;
 const MAX_JOBS = 50;
 const JOB_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 const MAX_PLAN_BYTES = 1024 * 1024;
-const MAX_TEMPORARY_FILE_BYTES = 512 * 1024;
 const MAX_RECOVERY_ATTEMPTS = 3;
 const RUNNER_PATH = fileURLToPath(new URL("./job-runner.mjs", import.meta.url));
 const ACTIVE_JOB_STATES = new Set(["queued", "running", "cleaning", "interrupted"]);
 const PLAN_RETAINING_STATES = new Set(["staged", ...ACTIVE_JOB_STATES]);
 
 export class ManagedJobManager {
-  constructor({ jobRoot, workspace, policy, resources = {}, resourceStatePath = "", stateRoot = "", logger = console, recover = true }) {
+  constructor({ jobRoot, workspace, policy, authorizeTool = null, resources = {}, resourceStatePath = "", stateRoot = "", logger = console, recover = true }) {
     const jobRootInput = resolve(jobRoot);
     ensureOwnerOnlyDir(jobRootInput);
     this.jobRoot = realpathSync.native ? realpathSync.native(jobRootInput) : realpathSync(jobRootInput);
     const workspaceInput = resolve(workspace);
     this.workspace = realpathSync.native ? realpathSync.native(workspaceInput) : realpathSync(workspaceInput);
     this.policy = policy;
+    this.authorizeTool = createToolAuthorizer(this.policy, authorizeTool);
     this.resources = normalizeResourceRegistry(resources);
     this.resourceStatePath = resourceStatePath ? resolve(resourceStatePath) : "";
     this.stateRoot = stateRoot ? resolve(stateRoot) : "";
@@ -62,6 +61,7 @@ export class ManagedJobManager {
   }
 
   listResources() {
+    this.authorizeTool("list_local_resources");
     this.assertMaintenanceAvailable();
     const resources = [];
     for (const [name, resource] of Object.entries(this.currentResources()).sort(([a], [b]) => a.localeCompare(b))) {
@@ -69,7 +69,9 @@ export class ManagedJobManager {
         const inspected = inspectResourceFile(resource.path, { allowInsecurePermissions: resource.allowInsecurePermissions === true });
         resources.push({ name, kind: "file", available: true, size: inspected.size, mode: inspected.mode });
       } catch (error) {
-        resources.push({ name, kind: "file", available: false, error_class: resourceErrorClass(error) });
+        const errorClass = resourceErrorClass(error);
+        if (errorClass === "resource_unavailable") throw error;
+        resources.push({ name, kind: "file", available: false, error_class: errorClass });
       }
     }
     return { resources, count: resources.length, values_exposed: false, paths_exposed: false };
@@ -91,20 +93,20 @@ export class ManagedJobManager {
 
 
   stage(args = {}) {
+    this.authorizeTool("stage_job");
     this.assertMaintenanceAvailable();
-    if (this.policy.allowWrite !== true) throw new Error("stage_job is disabled by daemon policy");
     return this.createJob(args, { launch: false });
   }
 
   start(args = {}) {
+    this.authorizeTool("start_job");
     this.assertMaintenanceAvailable();
-    this.assertEnabled("start_job");
     return this.createJob(args, { launch: true });
   }
 
   approve(args = {}, { localOperator = false } = {}) {
+    if (!localOperator) throw new BridgeError("policy_denied", "job approval is a local-operator-only action");
     this.assertMaintenanceAvailable();
-    if (!localOperator) this.assertEnabled("approve_job");
     const dir = this.jobDir(args.job_id);
     const transition = acquireJobTransitionLock(dir);
     if (!transition) throw new Error("job state is being modified by another process; retry after inspecting its current status");
@@ -213,6 +215,7 @@ export class ManagedJobManager {
 
 
   list(args = {}) {
+    this.authorizeTool("list_jobs");
     this.assertMaintenanceAvailable();
     this.prune();
     const limit = clampInt(args.limit, 20, 1, MAX_JOBS);
@@ -235,6 +238,7 @@ export class ManagedJobManager {
   }
 
   read(args = {}) {
+    this.authorizeTool("read_job");
     this.assertMaintenanceAvailable();
     const dir = this.jobDir(args.job_id);
     this.reconcileStatus(dir);
@@ -261,6 +265,7 @@ export class ManagedJobManager {
   }
 
   cancel(args = {}) {
+    this.authorizeTool("cancel_job");
     this.assertMaintenanceAvailable();
     const dir = this.jobDir(args.job_id);
     const transition = acquireJobTransitionLock(dir);
@@ -317,11 +322,6 @@ export class ManagedJobManager {
     if (this.stateRoot) assertStateMaintenanceAvailable(this.stateRoot);
   }
 
-  assertEnabled(tool) {
-    if (this.policy.execMode !== "direct" && this.policy.execMode !== "shell") {
-      throw new Error(`${tool} is disabled by daemon policy`);
-    }
-  }
 
   jobDir(value) {
     const id = String(value || "");
@@ -460,210 +460,6 @@ export function loadManagedJobPlan(inputPath) {
   return value;
 }
 
-export function validateResourceName(value) {
-  const name = String(value || "").trim();
-  if (!RESOURCE_NAME.test(name)) throw new Error("resource name must match [a-z][a-z0-9._-]{0,63}");
-  return name;
-}
-
-export function inspectResourceFile(inputPath, { allowInsecurePermissions = false, includeHash = false } = {}) {
-  const path = resolve(String(inputPath || ""));
-  const canonical = realpathFile(path);
-  const { buffer: content, info } = readBoundedRegularFileWithInfoSync(canonical, MAX_RESOURCE_BYTES);
-  if (process.platform !== "win32" && !allowInsecurePermissions && (info.mode & 0o077) !== 0) {
-    throw new Error("resource file is readable by group or others; restrict permissions or use --allow-insecure-permissions");
-  }
-  return {
-    kind: "file",
-    path: canonical,
-    pathAliases: normalizeResourcePathAliases([path, canonical]),
-    size: info.size,
-    mode: process.platform === "win32" ? null : `0${(info.mode & 0o777).toString(8)}`,
-    updatedAt: new Date().toISOString(),
-    allowInsecurePermissions: allowInsecurePermissions === true,
-    ...(includeHash ? { sha256: createHash("sha256").update(content).digest("hex") } : {}),
-  };
-}
-
-export function publicResourceRegistry(resources = {}, { includePaths = false } = {}) {
-  const normalized = normalizeResourceRegistry(resources);
-  return Object.fromEntries(Object.entries(normalized).map(([name, value]) => [name, {
-    kind: value.kind,
-    size: value.size ?? null,
-    mode: value.mode ?? null,
-    updatedAt: value.updatedAt ?? null,
-    allowInsecurePermissions: value.allowInsecurePermissions === true,
-    paths_exposed: includePaths,
-    ...(includePaths ? { path: value.path } : {}),
-  }]));
-}
-
-function validatePlan(args, context) {
-  if (!args || typeof args !== "object" || Array.isArray(args)) throw new Error("job arguments must be an object");
-  const allowed = new Set(["name", "steps", "finally_steps", "temporary_files"]);
-  for (const key of Object.keys(args)) if (!allowed.has(key)) throw new Error(`job contains unknown field: ${key}`);
-  const name = String(args.name || "managed job").trim().slice(0, 128) || "managed job";
-  const steps = validateSteps(args.steps, "steps", context);
-  const finallySteps = validateSteps(args.finally_steps || [], "finally_steps", context, true);
-  const temporaryFiles = validateTemporaryFiles(args.temporary_files || []);
-  if (!steps.length) throw new Error("steps must contain at least one step");
-  return {
-    version: 1,
-    name,
-    workspace: context.workspace,
-    full_env: context.fullEnv,
-    resources: referencedResources([...steps, ...finallySteps], context.resources),
-    temporary_files: temporaryFiles,
-    steps,
-    finally_steps: finallySteps,
-  };
-}
-
-function validateTemporaryFiles(value) {
-  if (!Array.isArray(value) || value.length > 16) throw new Error("temporary_files must contain 0-16 files");
-  const seen = new Set();
-  let totalBytes = 0;
-  return value.map((item, index) => {
-    if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error(`temporary_files[${index}] must be an object`);
-    for (const key of Object.keys(item)) if (!["name", "content", "executable"].includes(key)) throw new Error(`temporary_files[${index}] contains unknown field: ${key}`);
-    const name = validateResourceName(item.name);
-    if (seen.has(name)) throw new Error(`duplicate temporary file name: ${name}`);
-    seen.add(name);
-    const content = boundedString(item.content, 256 * 1024, `temporary_files[${index}].content`);
-    totalBytes += Buffer.byteLength(content);
-    if (totalBytes > MAX_TEMPORARY_FILE_BYTES) throw new Error(`temporary file contents exceed ${MAX_TEMPORARY_FILE_BYTES} bytes`);
-    return { name, content, executable: item.executable === true };
-  });
-}
-
-function validateSteps(value, label, context, allowEmpty = false) {
-  if (!Array.isArray(value) || (!allowEmpty && value.length === 0) || value.length > 16) {
-    throw new Error(`${label} must contain ${allowEmpty ? "0-16" : "1-16"} steps`);
-  }
-  return value.map((input, index) => {
-    if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`${label}[${index}] must be an object`);
-    const allowed = new Set(["name", "argv", "cwd", "env", "env_resources", "stdin", "stdin_resource", "timeout_seconds", "allow_failure", "capture_output"]);
-    for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`${label}[${index}] contains unknown field: ${key}`);
-    if (!Array.isArray(input.argv) || !input.argv.length || input.argv.length > 256) throw new Error(`${label}[${index}].argv must contain 1-256 strings`);
-    const argv = input.argv.map((item) => boundedString(item, 16 * 1024, `${label}[${index}].argv`));
-    if (Buffer.byteLength(JSON.stringify(argv)) > 64 * 1024) throw new Error(`${label}[${index}].argv exceeds 64 KiB`);
-    const cwd = input.cwd === undefined ? context.workspace : resolveJobCwd(input.cwd, context.workspace, context.unrestrictedPaths);
-    const env = validateEnv(input.env, `${label}[${index}].env`);
-    const envResources = validateEnvResources(input.env_resources, `${label}[${index}].env_resources`);
-    for (const key of Object.keys(envResources)) if (Object.prototype.hasOwnProperty.call(env, key)) throw new Error(`${label}[${index}] duplicates ${key} in env and env_resources`);
-    const stdin = input.stdin === undefined ? null : boundedString(input.stdin, 256 * 1024, `${label}[${index}].stdin`);
-    const stdinResource = input.stdin_resource === undefined ? null : validateResourceName(input.stdin_resource);
-    if (stdin !== null && stdinResource !== null) throw new Error(`${label}[${index}] cannot combine stdin and stdin_resource`);
-    return {
-      name: String(input.name || basename(argv[0]) || `step ${index + 1}`).slice(0, 128),
-      argv,
-      cwd,
-      env,
-      env_resources: envResources,
-      stdin,
-      stdin_resource: stdinResource,
-      timeout_seconds: clampInt(input.timeout_seconds, 600, 1, 3600),
-      allow_failure: input.allow_failure === true,
-      capture_output: input.capture_output === "discard" ? "discard" : "redacted",
-    };
-  });
-}
-
-function validateEnv(value, label) {
-  if (value === undefined) return {};
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
-  const entries = Object.entries(value);
-  if (entries.length > 64) throw new Error(`${label} has too many entries`);
-  const out = {};
-  for (const [key, raw] of entries) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${label} contains invalid variable name: ${key}`);
-    out[key] = boundedString(raw, 16 * 1024, `${label}.${key}`);
-  }
-  return out;
-}
-
-function validateEnvResources(value, label) {
-  if (value === undefined) return {};
-  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
-  const entries = Object.entries(value);
-  if (entries.length > 32) throw new Error(`${label} has too many entries`);
-  const out = {};
-  for (const [key, raw] of entries) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${label} contains invalid variable name: ${key}`);
-    out[key] = validateResourceName(raw);
-  }
-  return out;
-}
-
-function referencedResources(steps, registry) {
-  const names = new Set();
-  for (const step of steps) {
-    if (step.stdin_resource) names.add(step.stdin_resource);
-    for (const name of Object.values(step.env_resources || {})) names.add(name);
-    for (const value of [...step.argv, ...Object.values(step.env)]) {
-      for (const match of String(value).matchAll(RESOURCE_TOKEN)) names.add(match[1]);
-    }
-  }
-  if (names.size > MAX_RESOURCES) throw new Error(`job references more than ${MAX_RESOURCES} local resources`);
-  const out = {};
-  let totalBytes = 0;
-  for (const name of names) {
-    const resource = registry[name];
-    if (!resource) throw new Error(`unknown local resource: ${name}`);
-    const inspected = inspectResourceFile(resource.path, { allowInsecurePermissions: resource.allowInsecurePermissions === true, includeHash: true });
-    totalBytes += inspected.size;
-    if (totalBytes > MAX_JOB_RESOURCE_BYTES) throw new Error(`job resources exceed ${MAX_JOB_RESOURCE_BYTES} bytes`);
-    out[name] = {
-      ...inspected,
-      pathAliases: normalizeResourcePathAliases([...(resource.pathAliases || []), ...(inspected.pathAliases || [])]),
-      allowInsecurePermissions: resource.allowInsecurePermissions === true,
-    };
-  }
-  return out;
-}
-
-function normalizeResourceRegistry(resources) {
-  const out = {};
-  if (!resources || typeof resources !== "object" || Array.isArray(resources)) return out;
-  for (const [rawName, rawValue] of Object.entries(resources).slice(0, MAX_RESOURCES)) {
-    const name = validateResourceName(rawName);
-    if (!rawValue || rawValue.kind !== "file" || typeof rawValue.path !== "string") continue;
-    out[name] = {
-      kind: "file",
-      path: resolve(rawValue.path),
-      pathAliases: normalizeResourcePathAliases([rawValue.path, ...(Array.isArray(rawValue.pathAliases) ? rawValue.pathAliases : [])]),
-      size: Number.isFinite(Number(rawValue.size)) ? Number(rawValue.size) : null,
-      mode: rawValue.mode ?? null,
-      updatedAt: rawValue.updatedAt ?? null,
-      allowInsecurePermissions: rawValue.allowInsecurePermissions === true,
-    };
-  }
-  return out;
-}
-
-function normalizeResourcePathAliases(values) {
-  const aliases = [];
-  for (const value of values) {
-    if (typeof value !== "string" || !value || value.includes("\0") || value.length > 4096) continue;
-    const absolute = resolve(value);
-    if (!aliases.includes(absolute)) aliases.push(absolute);
-    if (aliases.length >= 8) break;
-  }
-  return aliases;
-}
-
-function resolveJobCwd(value, workspace, unrestrictedPaths) {
-  const raw = boundedString(value, 4096, "cwd");
-  const candidate = isAbsolute(raw) ? resolve(raw) : resolve(workspace, raw);
-  const canonical = realpathSync.native ? realpathSync.native(candidate) : realpathSync(candidate);
-  const info = statSync(canonical);
-  if (!info.isDirectory()) throw new Error("managed job cwd is not a directory");
-  if (!unrestrictedPaths) {
-    const rel = relative(workspace, canonical);
-    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("managed job cwd is outside the configured workspace");
-  }
-  return canonical;
-}
 
 function failRunnerLaunch(dir, status, error) {
   const now = new Date().toISOString();

package/src/local/observability.mjs

@@ -0,0 +1,83 @@
+const DURATION_BUCKETS_MS = Object.freeze([100, 1000, 10_000, 30_000, 60_000]);
+const MAX_TOOLS = 128;
+const MAX_ERROR_CODES = 64;
+
+export class RuntimeObservability {
+  constructor(options = {}) {
+    this.now = typeof options.now === "function" ? options.now : Date.now;
+    this.startedAt = this.now();
+    this.calls = { started: 0, completed: 0, failed: 0, cancelled: 0, timed_out: 0, slow: 0 };
+    this.byTool = new Map();
+    this.errors = new Map();
+  }
+
+  start(tool) {
+    this.calls.started += 1;
+    const metric = this.toolMetric(tool);
+    metric.started += 1;
+    metric.active += 1;
+  }
+
+  finish(tool, { status, durationMs, errorCode = "", slow = false } = {}) {
+    const metric = this.toolMetric(tool);
+    metric.active = Math.max(0, metric.active - 1);
+    metric.last_duration_ms = boundedDuration(durationMs);
+    metric.max_duration_ms = Math.max(metric.max_duration_ms, metric.last_duration_ms);
+    metric.total_duration_ms += metric.last_duration_ms;
+    metric.duration_buckets[bucketName(metric.last_duration_ms)] += 1;
+    if (status === "completed") { this.calls.completed += 1; metric.completed += 1; }
+    else {
+      this.calls.failed += 1;
+      metric.failed += 1;
+      if (status === "cancelled") this.calls.cancelled += 1;
+      if (status === "timeout") this.calls.timed_out += 1;
+      if (errorCode) this.incrementError(errorCode);
+    }
+    if (slow) { this.calls.slow += 1; metric.slow += 1; }
+  }
+
+  snapshot() {
+    return {
+      uptime_ms: Math.max(0, this.now() - this.startedAt),
+      calls: { ...this.calls },
+      active: [...this.byTool.values()].reduce((sum, metric) => sum + metric.active, 0),
+      errors: Object.fromEntries([...this.errors.entries()].sort(([a], [b]) => a.localeCompare(b))),
+      tools: Object.fromEntries([...this.byTool.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, metric]) => [name, {
+        ...metric,
+        duration_buckets: { ...metric.duration_buckets },
+      }])),
+    };
+  }
+
+  toolMetric(tool) {
+    const name = String(tool || "unknown").slice(0, 128) || "unknown";
+    if (!this.byTool.has(name)) {
+      if (this.byTool.size >= MAX_TOOLS) return this.toolMetric("<other>");
+      this.byTool.set(name, {
+        started: 0, completed: 0, failed: 0, active: 0, slow: 0,
+        total_duration_ms: 0, max_duration_ms: 0, last_duration_ms: 0,
+        duration_buckets: Object.fromEntries([...DURATION_BUCKETS_MS.map((value) => [`le_${value}`, 0]), ["gt_60000", 0]]),
+      });
+    }
+    return this.byTool.get(name);
+  }
+
+  incrementError(code) {
+    const key = String(code || "execution_failed").slice(0, 64);
+    if (!this.errors.has(key) && this.errors.size >= MAX_ERROR_CODES) {
+      this.errors.set("<other>", (this.errors.get("<other>") || 0) + 1);
+      return;
+    }
+    this.errors.set(key, (this.errors.get(key) || 0) + 1);
+  }
+}
+
+function bucketName(durationMs) {
+  for (const threshold of DURATION_BUCKETS_MS) if (durationMs <= threshold) return `le_${threshold}`;
+  return "gt_60000";
+}
+
+function boundedDuration(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.min(Math.floor(number), Number.MAX_SAFE_INTEGER) : 0;
+}

package/src/local/policy.mjs

@@ -0,0 +1,148 @@
+import catalog from "../shared/tool-catalog.json" with { type: "json" };
+import contract from "../shared/policy-contract.json" with { type: "json" };
+import { BridgeError } from "./errors.mjs";
+
+export const DEFAULT_POLICY_PROFILE = String(contract.defaultProfile);
+export const DEFAULT_POLICY_REVISION = Number(contract.revision);
+export const POLICY_PROFILES = Object.freeze(Object.fromEntries(
+  Object.entries(contract.profiles).map(([name, value]) => [name, Object.freeze({ ...value })]),
+));
+export const POLICY_ORIGINS = Object.freeze(new Set(contract.origins.map(String)));
+export const POLICY_AVAILABILITY = Object.freeze(Object.fromEntries(
+  Object.entries(contract.availability).map(([name, value]) => [name, Object.freeze({ ...value })]),
+));
+
+const TOOLS = Object.freeze(catalog.map((tool) => Object.freeze({ ...tool })));
+const TOOL_BY_NAME = new Map(TOOLS.map((tool) => [tool.name, tool]));
+
+export function policyProfile(name, origin = "explicit") {
+  const profile = String(name || "").trim().toLowerCase();
+  if (!POLICY_PROFILES[profile]) throw new BridgeError("invalid_request", `unknown policy profile: ${profile}`);
+  return normalizePolicy({ ...POLICY_PROFILES[profile], origin, revision: DEFAULT_POLICY_REVISION });
+}
+
+export function normalizePolicy(policy = {}) {
+  const execMode = ["off", "direct", "shell"].includes(policy.execMode)
+    ? policy.execMode
+    : policy.allowExec === true
+      ? "shell"
+      : "off";
+  const origin = POLICY_ORIGINS.has(policy.origin) ? policy.origin : "custom";
+  const revision = Number.isInteger(policy.revision) && policy.revision > 0 ? policy.revision : DEFAULT_POLICY_REVISION;
+  const requestedProfile = typeof policy.profile === "string" && policy.profile ? policy.profile : "custom";
+  const normalized = {
+    profile: requestedProfile,
+    origin,
+    revision,
+    allowWrite: policy.allowWrite === true,
+    allowExec: execMode !== "off",
+    execMode,
+    unrestrictedPaths: policy.unrestrictedPaths === true,
+    minimalEnv: policy.minimalEnv !== false,
+    exposeAbsolutePaths: policy.exposeAbsolutePaths === true,
+  };
+  const canonical = POLICY_PROFILES[requestedProfile];
+  if (canonical) Object.assign(normalized, canonical, { allowExec: canonical.execMode !== "off" });
+  return Object.freeze(normalized);
+}
+
+export function policyCapabilitiesEqual(left, right) {
+  return left.allowWrite === right.allowWrite
+    && left.execMode === right.execMode
+    && left.unrestrictedPaths === right.unrestrictedPaths
+    && left.minimalEnv === right.minimalEnv
+    && left.exposeAbsolutePaths === right.exposeAbsolutePaths;
+}
+
+export function isCanonicalFullPolicy(policy = {}) {
+  return policyCapabilitiesEqual(normalizePolicy(policy), POLICY_PROFILES.full);
+}
+
+export function assertCanonicalFullPolicy(policy = {}) {
+  const normalized = normalizePolicy(policy);
+  if (normalized.profile !== "full" || !isCanonicalFullPolicy(normalized)) {
+    throw new BridgeError("policy_denied", "full profile invariant failed: full must enable writes, shell execution, unrestricted paths, full parent environment, and absolute paths");
+  }
+  if (toolNamesForPolicy(normalized).length !== TOOLS.length) {
+    throw new BridgeError("integrity_error", "full profile invariant failed: complete tool catalog is not exposed");
+  }
+  return normalized;
+}
+
+export function policyAllowsAvailability(policy, availability) {
+  const normalized = normalizePolicy(policy);
+  const requirements = POLICY_AVAILABILITY[availability];
+  if (!requirements) return false;
+  if (requirements.profile && normalized.profile !== requirements.profile) return false;
+  if (requirements.allowWrite === true && normalized.allowWrite !== true) return false;
+  if (Array.isArray(requirements.execModes) && !requirements.execModes.includes(normalized.execMode)) return false;
+  if (typeof requirements.unrestrictedPaths === "boolean" && normalized.unrestrictedPaths !== requirements.unrestrictedPaths) return false;
+  if (typeof requirements.minimalEnv === "boolean" && normalized.minimalEnv !== requirements.minimalEnv) return false;
+  if (typeof requirements.exposeAbsolutePaths === "boolean" && normalized.exposeAbsolutePaths !== requirements.exposeAbsolutePaths) return false;
+  return true;
+}
+
+export function toolDefinition(name) {
+  return TOOL_BY_NAME.get(String(name || "")) || null;
+}
+
+export function policyAllowsTool(policy, name) {
+  const tool = toolDefinition(name);
+  return Boolean(tool && policyAllowsAvailability(policy, tool.availability));
+}
+
+export function assertToolAllowed(policy, name) {
+  const tool = toolDefinition(name);
+  if (!tool) throw new BridgeError("not_found", `unknown tool: ${String(name || "")}`);
+  if (!policyAllowsAvailability(policy, tool.availability)) {
+    throw new BridgeError("policy_denied", `tool is disabled by the active policy: ${tool.name}`, {
+      details: { tool: tool.name, availability: tool.availability },
+    });
+  }
+  return tool;
+}
+
+export function toolsForPolicy(policy = {}) {
+  const normalized = normalizePolicy(policy);
+  return TOOLS.filter((tool) => policyAllowsAvailability(normalized, tool.availability))
+    .map(({ availability, ...tool }) => structuredClone(tool));
+}
+
+export function toolNamesForPolicy(policy = {}) {
+  const normalized = normalizePolicy(policy);
+  return TOOLS.filter((tool) => policyAllowsAvailability(normalized, tool.availability)).map((tool) => tool.name);
+}
+
+export function allToolNames() {
+  return TOOLS.map((tool) => tool.name);
+}
+
+
+export function createToolAuthorizer(policy, provided) {
+  if (typeof provided === "function") return provided;
+  const gate = new PolicyGate(policy);
+  return (tool) => gate.assert(tool);
+}
+
+export class PolicyGate {
+  constructor(policy) {
+    this.policy = normalizePolicy(policy);
+    this.allowedNames = new Set(toolNamesForPolicy(this.policy));
+  }
+
+  allows(name) {
+    return this.allowedNames.has(String(name || ""));
+  }
+
+  assert(name) {
+    return assertToolAllowed(this.policy, name);
+  }
+
+  names() {
+    return [...this.allowedNames];
+  }
+
+  definitions() {
+    return toolsForPolicy(this.policy);
+  }
+}