@moretea-labs/forge 1.8.0 → 1.8.2

package/adapters/mcp/runtime-gateway/routing-policy.ts

@@ -0,0 +1,506 @@
+import { createHash } from 'crypto';
+import type { McpToolDefinition } from '../../../packages/protocols/mcp/tool-contract';
+import type { ExecutionTimeoutPolicy } from '../../../src/runtime/execution/jobs/types';
+import { classifyRepositoryCommand } from '../../../src/cli/repositories/command-classifier';
+import { isFastEligibleTool, routeExecution, type ExecutionDecision } from '../../../src/runtime/execution/thin-harness';
+import { classifyRepositoryCommandRoute } from '../../../src/runtime/execution/process-runtime';
+import { isProcessIsolatedReadDiagnostic } from '../../../src/runtime/diagnostics/process-facade';
+
+/** Pure deterministic MCP Gateway placement policy. No execution or lifecycle mutation belongs here. */
+const DIRECT_REPOSITORY_TOOLS = new Set(['repository_list', 'repository_get', 'repository_workbench']);
+const DIRECT_CONTROL_WRITE_TOOLS = new Set([
+  'runtime_maintenance_apply',
+  // Protected credential preparation and physical input own their authorization boundary.
+  // Neither may be promoted into Process/ExecutionJob persistence or replay.
+  'computer_console_unlock_prepare',
+  'computer_console_unlock',
+  'computer_console_unlock_enroll',
+  'computer_console_unlock_status',
+  'computer_console_unlock_recover',
+  'computer_console_unlock_revoke',
+]);
+
+const THIN_ROUTED_TOOLS = new Set([
+  'execute_command',
+  'repository_safe_patch_apply',
+  'repository_safe_patch_plan',
+  'capability_execute',
+  'repository_git_status',
+  'repository_git_diff',
+  'repository_git_commit',
+  'git_stage_paths',
+  'git_commit_paths',
+  'git_diff_paths',
+  'apply_patch',
+  'apply_edit_operations',
+  'search_repository',
+  'read_file_range',
+  'read_repository_file',
+  // Checks and edit verification use Process Runtime unless multi-phase/release requires Durable.
+  'run_check',
+  'verify_edit_session',
+]);
+
+/** Blocking native host tools must never execute on the public MCP event loop. */
+const GATEWAY_ISOLATED_TOOLS = new Set([
+  // Native Apple tooling uses synchronous xcodebuild/simctl subprocesses.
+  'ios_review_packet', 'ios_xcode_status', 'ios_simulators_list', 'ios_project_discover',
+  'ios_schemes_list', 'ios_simulator_boot', 'ios_app_build', 'ios_app_install',
+  'ios_app_launch', 'ios_simulator_screenshot', 'ios_simulator_log_tail', 'ios_ui_smoke_test',
+  // Diagnostics and maintenance perform process-table and recursive filesystem scans.
+  'workflow_watchdog_report', 'runtime_cleanup_preview', 'runtime_cleanup_apply',
+  'runtime_maintenance_status', 'runtime_maintenance_apply',
+  // Release and recovery operations may spawn Git/process checks or restart managed children.
+  'release_gate', 'runtime_recovery', 'capability_recovery',
+]);
+
+export function isGatewayIsolatedTool(name: string): boolean {
+  return GATEWAY_ISOLATED_TOOLS.has(name);
+}
+
+/**
+ * Tools that own their execution boundary and must never fall through to
+ * retired generic ExecutionJob creation. Legacy iOS atomics are compatibility
+ * adapters over the typed iOS plugin authority.
+ */
+const SELF_MANAGED_DURABLE_TOOLS = new Set([
+  'plugin_action_execute',
+  'ios_xcode_status', 'ios_simulators_list', 'ios_project_discover', 'ios_schemes_list',
+  'ios_simulator_boot', 'ios_app_build', 'ios_app_install', 'ios_app_launch',
+  'ios_simulator_screenshot', 'ios_simulator_log_tail', 'ios_ui_smoke_test',
+]);
+
+export function isSelfManagedDurableTool(name: string): boolean {
+  return SELF_MANAGED_DURABLE_TOOLS.has(name);
+}
+/** High-frequency bounded reads execute in the current MCP request. */
+const DIRECT_HOT_READ_TOOLS = new Set([
+  'get_task_run', 'get_task_run_events', 'get_task_run_log',
+  'get_job', 'list_jobs',
+  'work_status_digest', 'work_result_summary',
+  'controller_ready', 'repository_runtime_snapshot',
+  'rh_status', 'rh_context', 'rh_inbox',
+  'repository_git_status', 'repository_git_diff', 'git_diff_paths',
+]);
+
+export function isDirectHotReadTool(name: string): boolean {
+  return DIRECT_HOT_READ_TOOLS.has(name);
+}
+/** Small interactive development writes: run synchronously by default so ChatGPT/GUI get immediate results. */
+const INTERACTIVE_SYNC_WRITE_TOOLS = new Set([
+  'repository_safe_patch_apply',
+  'capability_execute',
+  'repository_git_create_branch',
+  'repository_git_switch_branch',
+  'repository_git_merge_branch',
+  'repository_git_delete_branch',
+  'repository_git_commit',
+  'repository_git_finish_workflow',
+  'begin_edit_session',
+  'apply_patch',
+  'apply_edit_operations',
+  'create_edit_savepoint',
+  'git_stage_paths',
+  'git_commit_paths',
+  // Recovery writes against an existing Run must remain available while legacy
+  // Runs are the very thing preventing runtime-storage relocation. These tools
+  // do not create new execution ownership or dispatch new work.
+  'finish_task_run',
+  'cancel_task_run',
+]);
+const AGENT_DELEGATION_TOOLS = new Set([
+  'dispatch_task',
+  'launch_issue',
+  'dispatch_ready_tasks',
+  'retry_task_run',
+  'quick_agent_session',
+]);
+const EXPLICIT_EXTERNAL_CONTROLLER_TOOLS = new Set([
+  'publish_issue_to_github',
+  'close_github_issue',
+  'request_release_gate',
+]);
+
+const GATEWAY_ROUTE_BEHAVIOR_PROBES: ReadonlyArray<{
+  id: string;
+  operation: string;
+  args: Record<string, unknown>;
+}> = [
+  { id: 'hot-read', operation: 'controller_ready', args: {} },
+  { id: 'isolated-read-diagnostic', operation: 'workflow_watchdog_report', args: {} },
+  { id: 'readonly-command', operation: 'execute_command', args: { command: ['git', 'status', '--short'] } },
+  { id: 'managed-local-command', operation: 'execute_command', args: { command: ['bun', 'run', 'check:type'], timeout_ms: 120_000 } },
+  { id: 'focused-check', operation: 'run_check', args: { check_id: 'package:check:type' } },
+  { id: 'release-check', operation: 'run_check', args: { check_id: 'package:check:release' } },
+  { id: 'interactive-write', operation: 'repository_safe_patch_apply', args: { operations: [] } },
+  { id: 'external-controller', operation: 'request_release_gate', args: {} },
+  { id: 'unknown-tool', operation: '__route_behavior_probe_unknown__', args: {} },
+];
+
+export interface GatewayRouteBehaviorSnapshot {
+  schemaVersion: 1;
+  fingerprint: string;
+  probeCount: number;
+  probes: Array<{
+    id: string;
+    operation: string;
+    path: 'direct' | 'fast' | 'durable' | 'reject';
+    reasons: string[];
+    decision?: {
+      mode: string;
+      risk: string;
+      estimatedClass: string;
+      requiresIsolation: boolean;
+      requiresRecovery: boolean;
+      effects: Record<string, boolean>;
+    };
+  }>;
+}
+
+/**
+ * Fingerprint the real Gateway classifier over a fixed, bounded behavior matrix.
+ * This is deliberately distinct from the MCP schema/tool-surface fingerprint.
+ */
+export function gatewayRouteBehaviorSnapshot(): GatewayRouteBehaviorSnapshot {
+  const probes = GATEWAY_ROUTE_BEHAVIOR_PROBES.map((probe) => {
+    const classification = classifyGatewayExecutionPath(probe.operation, probe.args);
+    return {
+      id: probe.id,
+      operation: probe.operation,
+      path: classification.path,
+      reasons: [...classification.reasons],
+      ...(classification.decision ? {
+        decision: {
+          mode: classification.decision.mode,
+          risk: classification.decision.risk,
+          estimatedClass: classification.decision.estimatedClass,
+          requiresIsolation: classification.decision.requiresIsolation,
+          requiresRecovery: classification.decision.requiresRecovery,
+          effects: { ...classification.decision.effects },
+        },
+      } : {}),
+    };
+  });
+  return {
+    schemaVersion: 1,
+    fingerprint: createHash('sha256').update(JSON.stringify(probes)).digest('hex'),
+    probeCount: probes.length,
+    probes,
+  };
+}
+const MAX_DURABLE_TIMEOUT_MS = 24 * 60 * 60_000;
+
+function durableTimeoutMs(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.max(1_000, Math.min(Math.trunc(value), MAX_DURABLE_TIMEOUT_MS));
+}
+
+function wantsAsyncExecution(args: Record<string, unknown>): boolean {
+  return args.apply_mode === 'async'
+    || args.mode === 'async'
+    || args.mode === 'durable'
+    || args.async === true
+    || args.background === true;
+}
+
+/** Release checks cross the external Controller boundary when explicitly
+ * requested asynchronously; ordinary checks remain Process-Runtime local. */
+function isReleaseCheckId(value: unknown): boolean {
+  const id = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return id === 'check:release' || id === 'package:check:release';
+}
+
+export function runsAsInteractiveSyncWrite(
+  name: string,
+  args: Record<string, unknown> = {},
+): boolean {
+  return INTERACTIVE_SYNC_WRITE_TOOLS.has(name) && !wantsAsyncExecution(args);
+}
+
+export function wantsWaitForResult(args: Record<string, unknown>): boolean {
+  return args.wait === true
+    || args.await_result === true
+    || args.wait_for_result === true;
+}
+
+export function waitTimeoutMs(args: Record<string, unknown>): number {
+  const explicitInteractiveWait = args.interactive_wait_ms ?? args.wait_ms;
+  if (typeof explicitInteractiveWait === 'number' && Number.isFinite(explicitInteractiveWait)) {
+    return Math.max(200, Math.min(Math.trunc(explicitInteractiveWait), 120_000));
+  }
+  if (typeof args.timeout_ms === 'number' && Number.isFinite(args.timeout_ms) && wantsWaitForResult(args)) {
+    return Math.max(200, Math.min(Math.trunc(args.timeout_ms), 120_000));
+  }
+  return 15_000;
+}
+
+export function operationExecutionTimeoutMsForMcpCall(
+  name: string,
+  args: Record<string, unknown>,
+): number {
+  const requested = args.execution_timeout_ms ?? args.timeout_ms;
+  return durableTimeoutMs(requested, AGENT_DELEGATION_TOOLS.has(name) ? 60 * 60_000 : 15 * 60_000);
+}
+
+/**
+ * Build independent budgets for the durable Parent Job. Agent delegation keeps
+ * the caller's operation execution budget on the Child Run; the Parent only
+ * receives enough execution time to create and durably associate that child.
+ */
+export function executionTimeoutPolicyForMcpCall(
+  name: string,
+  args: Record<string, unknown>,
+): ExecutionTimeoutPolicy {
+  const operationExecutionMs = operationExecutionTimeoutMsForMcpCall(name, args);
+  const agentDelegation = AGENT_DELEGATION_TOOLS.has(name);
+  return {
+    admissionTimeoutMs: durableTimeoutMs(
+      args.admission_timeout_ms,
+      agentDelegation ? 5 * 60_000 : operationExecutionMs,
+    ),
+    queueTimeoutMs: durableTimeoutMs(
+      args.queue_timeout_ms,
+      agentDelegation ? MAX_DURABLE_TIMEOUT_MS : operationExecutionMs,
+    ),
+    executionTimeoutMs: agentDelegation ? 120_000 : operationExecutionMs,
+    interactiveWaitMs: waitTimeoutMs(args),
+  };
+}
+
+export function classifyGatewayExecutionPath(
+  name: string,
+  args: Record<string, unknown> = {},
+  opts: { allowReadOnly?: boolean; forceDurable?: boolean; definition?: McpToolDefinition } = {},
+): {
+  path: 'direct' | 'fast' | 'durable' | 'reject';
+  reasons: string[];
+  decision?: ExecutionDecision;
+} {
+  // Heavy read-only diagnostics must leave the Gateway event loop before the
+  // generic read-only shortcut. Process Runtime preserves the same request and
+  // returns either the completed JSON or a queryable process handle.
+  if (isProcessIsolatedReadDiagnostic(name)) {
+    return { path: 'fast', reasons: ['isolated_read_diagnostic_process'] };
+  }
+  // Registered bounded reads execute through their real handler.
+  if (opts.definition?.annotations?.readOnlyHint === true) {
+    return { path: 'direct', reasons: ['registered_readonly_tool'] };
+  }
+  if (name.startsWith('repository_') && DIRECT_REPOSITORY_TOOLS.has(name)) {
+    return { path: 'direct', reasons: ['direct_repository_tool'] };
+  }
+  if (isDirectHotReadTool(name)) {
+    return { path: 'direct', reasons: ['direct_hot_read'] };
+  }
+  if (runsAsInteractiveSyncWrite(name, args)) {
+    return { path: 'direct', reasons: ['interactive_sync_write'] };
+  }
+  if (isSelfManagedDurableTool(name)) {
+    return { path: 'direct', reasons: ['self_managed_durable_boundary'] };
+  }
+  if (DIRECT_CONTROL_WRITE_TOOLS.has(name) && !wantsAsyncExecution(args)) {
+    return { path: 'direct', reasons: ['bounded_direct_control_write'] };
+  }
+  if (EXPLICIT_EXTERNAL_CONTROLLER_TOOLS.has(name)) {
+    return { path: 'durable', reasons: ['explicit_external_controller_boundary'] };
+  }
+  if (opts.forceDurable === true || isGatewayIsolatedTool(name)) {
+    return {
+      path: 'durable',
+      reasons: opts.forceDurable ? ['force_durable'] : ['gateway_isolated_tool'],
+    };
+  }
+  const selfManagedProcessAsync = (
+    name === 'execute_command'
+    || name === 'run_check'
+    || name === 'verify_edit_session'
+  ) && (
+    args.apply_mode === 'async'
+    || args.mode === 'async'
+    || args.async === true
+    || args.background === true
+  ) && !(name === 'run_check' && isReleaseCheckId(args.check_id ?? args.checkId));
+  // Async on Process-Runtime-owned tools means return the managed Process
+  // handle immediately. It must not promote local work into the retired
+  // ExecutionJob path. Explicit durable mode still crosses the external
+  // Controller boundary.
+  if (wantsAsyncExecution(args) && !selfManagedProcessAsync) {
+    return {
+      path: 'durable',
+      reasons: ['caller_requested_async_or_durable'],
+    };
+  }
+  // run_check: Process Runtime for ordinary checks; Durable only for release/multi-phase.
+  if (name === 'run_check') {
+    const checkId = String(args.check_id ?? args.checkId ?? '').trim();
+    const batchCheckIds = Array.isArray(args.check_ids)
+      ? args.check_ids.map((value) => String(value).trim()).filter(Boolean)
+      : [];
+    if (args.mode === 'durable' || args.force_durable === true) {
+      return { path: 'durable', reasons: ['caller_requested_durable_check'] };
+    }
+    if (isReleaseCheckId(checkId) && batchCheckIds.length === 0) {
+      return { path: 'durable', reasons: ['release_check_requires_durable_boundary'] };
+    }
+    // Gateway owns transport placement, not Check lifecycle semantics. Until
+    // the registered ControllerCheck is resolved by the Check owner below,
+    // never infer Durable handling from a caller-provided id string.
+    // Route as "fast" so shouldCreateDurableJob returns false; actual execution
+    // uses Process Runtime (direct or managed handle) in routeDurableMcpCall / legacy handler.
+    return {
+      path: 'fast',
+      reasons: ['run_check_process_runtime'],
+      decision: {
+        mode: 'fast',
+        reasons: ['run_check_process_runtime'],
+        risk: 'workspace_write',
+        estimatedClass: 'short',
+        requiresIsolation: false,
+        requiresRecovery: false,
+        effects: {
+          readsWorkspace: true,
+          mutatesWorkspace: true,
+          mutatesGitRefs: false,
+          remoteWrite: false,
+        },
+      },
+    };
+  }
+
+  // verify_edit_session is a Process Runtime orchestration surface. It may
+  // return a managed handle, but it must never be promoted to a retired
+  // ExecutionJob/LocalJob merely because the edit session has checks.
+  if (name === 'verify_edit_session') {
+    if (args.mode === 'durable' || args.force_durable === true) {
+      return { path: 'durable', reasons: ['caller_requested_durable_edit_verification'] };
+    }
+    return {
+      path: 'fast',
+      reasons: ['verify_edit_session_process_runtime'],
+      decision: {
+        mode: 'fast',
+        reasons: ['verify_edit_session_process_runtime'],
+        risk: 'workspace_write',
+        estimatedClass: 'short',
+        requiresIsolation: false,
+        requiresRecovery: false,
+        effects: {
+          readsWorkspace: true,
+          mutatesWorkspace: true,
+          mutatesGitRefs: false,
+          remoteWrite: false,
+        },
+      },
+    };
+  }
+
+  // Host commands are already placed explicitly by the model and authorized
+  // by the ForgeInstance process:exec Grant. Never route them through a
+  // repository classifier or infer a Work/Plan from the shell command.
+  if (name === 'execute_command' && args.scope === 'host') {
+    return { path: 'fast', reasons: ['explicit_host_process_runtime'] };
+  }
+  if (name === 'execute_command' && args.dry_run === true) {
+    return { path: 'direct', reasons: ['explicit_command_preview_only'] };
+  }
+  // Repository commands use the existing Process Runtime classifier only for
+  // process handling and mechanical write protection.
+  if (name === 'execute_command') {
+    const command = args.command;
+    if (!(typeof command === 'string' || Array.isArray(command))) {
+      return { path: 'reject', reasons: ['repository_command_missing'] };
+    }
+    const route = classifyRepositoryCommandRoute(command as string | string[], {
+      defaultBranch: typeof args.default_branch === 'string' ? args.default_branch : undefined,
+      timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+    });
+    if (route.route === 'process_direct' || route.route === 'process_managed') {
+      const commandClassification = classifyRepositoryCommand(
+        command as string | string[],
+        typeof args.default_branch === 'string' ? args.default_branch : undefined,
+      );
+      const risk = commandClassification.risk === 'readonly'
+        ? 'readonly'
+        : commandClassification.risk === 'remote_write'
+          ? 'remote_write'
+          : commandClassification.risk === 'destructive'
+            ? 'destructive'
+            : 'workspace_write';
+      const reasons = ['repository_command_process_runtime', route.reason];
+      return {
+        path: 'fast',
+        reasons,
+        decision: {
+          mode: 'fast',
+          reasons,
+          risk,
+          estimatedClass: route.route === 'process_direct' ? 'short' : 'long',
+          requiresIsolation: false,
+          requiresRecovery: false,
+          effects: {
+            readsWorkspace: true,
+            mutatesWorkspace: risk !== 'readonly',
+            mutatesGitRefs: risk !== 'readonly' && /(?:^|\s)git\s+(?:commit|merge|branch|switch|checkout|reset|rebase|tag)\b/i.test(
+              Array.isArray(command) ? command.join(' ') : command,
+            ),
+            remoteWrite: risk === 'remote_write',
+          },
+        },
+      };
+    }
+    if (route.route === 'reject') return { path: 'reject', reasons: [route.reason] };
+    return { path: 'durable', reasons: [route.reason] };
+  }
+
+  if (THIN_ROUTED_TOOLS.has(name)) {
+    const decision = routeExecution({
+      operation: name,
+      mode: args.mode === 'fast' ? 'fast' : 'auto',
+      background: args.background === true || args.apply_mode === 'async' || args.async === true,
+      requiresRecovery: args.requires_recovery === true,
+      requiresIsolation: args.isolation === 'new_worktree' || args.requires_isolation === true,
+      requiresWorktree: args.isolation === 'new_worktree',
+      agentRun: name === 'quick_agent_session' || name === 'dispatch_task',
+      remoteWrite: name.includes('push') || name === 'publish_issue_to_github',
+      timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+      command: args.command as string | string[] | undefined,
+      paths: Array.isArray(args.paths) ? args.paths.map(String) : undefined,
+      allowedPaths: Array.isArray(args.allowed_paths) ? args.allowed_paths.map(String) : undefined,
+      patchOperationCount: Array.isArray(args.operations) ? args.operations.length : undefined,
+      patchPaths: Array.isArray(args.operations)
+        ? args.operations
+          .filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null)
+          .map((entry) => String(entry.path ?? '').trim())
+          .filter(Boolean)
+        : undefined,
+    });
+    if (decision.mode === 'fast') {
+      return {
+        path: 'fast',
+        reasons: decision.reasons,
+        decision,
+      };
+    }
+    if (decision.mode === 'reject') {
+      return { path: 'reject', reasons: decision.reasons, decision };
+    }
+    // Keep isFastEligibleTool as a secondary guard for tools whose operation
+    // name maps to a Fast allowlist entry but routeExecution used a durable alias.
+    if (isFastEligibleTool(name, args)) {
+      return {
+        path: 'fast',
+        reasons: ['thin_router_fast_eligible'],
+      };
+    }
+    return {
+      path: 'durable',
+      reasons: decision.reasons.length > 0 ? decision.reasons : ['thin_router_requires_durable'],
+      decision,
+    };
+  }
+  if (opts.definition) {
+    return { path: 'direct', reasons: ['registered_tool_direct_handler'] };
+  }
+  return { path: 'reject', reasons: ['tool_not_found'] };
+}
+