@moretea-labs/forge 1.7.2 → 1.8.0

package/adapters/mcp/runtime-gateway/recovery-adapter.ts

@@ -0,0 +1,268 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { listControllerChecks } from '../../../src/cli/controller/check-runner';
+import { ensureRepositoryRuntimeStorage } from '../../../src/cli/repositories/runtime-storage';
+import { cachedGitIdentity } from '../../../src/cli/repository/inspector';
+import { inferLocalControllerProcess } from '../../../src/runtime/diagnostics/performance';
+import { listExecutionJobs } from '../../../src/runtime/execution/jobs/store';
+import { listLocalBridgeJobSnapshots } from '../../../src/cli/local-bridge/job-store';
+import { listAssistantPluginManifests } from '../../../src/runtime/plugins/store';
+import { readRepositoryProjectionSnapshot } from '../../../src/runtime/projections/materialized-view';
+import {
+  controllerContextProjectionNeedsRefresh,
+  readControllerContextProjection,
+} from '../../../src/runtime/projections/controller-context';
+import {
+  buildCapabilityRecoverySnapshot,
+  buildRuntimeMaintenanceStatus,
+  executeCapabilityRecoveryAction,
+  executeRuntimeMaintenanceAction,
+  RecoveryApplicationError,
+  listRecoveryAuditRecords,
+  previewRuntimeStorageRepair,
+  applyRuntimeStorageRepair,
+  type RuntimeMaintenanceActionId,
+} from '../../../src/runtime/recovery';
+import { loadMcpRuntimeState } from '../auth';
+import { formatRuntimeSourceDriftMessage } from '../../../src/runtime/control-plane/runtime-generation';
+import { callStandaloneRecoveryTool } from './recovery-client-adapter';
+import {
+  controllerReadinessEvidence,
+  runtimeSourceSnapshotStatus,
+} from './status-inbox-adapter';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+
+async function capabilityRecoveryInput(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: ReturnType<typeof selected>,
+  args: Record<string, unknown>,
+) {
+  const readiness = await controllerReadinessEvidence(ctx, repository);
+  const runtimeSnapshot = readRepositoryProjectionSnapshot(ctx.controllerHome, repository.repoId);
+  const localBridge = loadMcpRuntimeState(repository.canonicalRoot)?.localController;
+  const inferredLocalBridge = inferLocalControllerProcess(repository.canonicalRoot);
+  const contextProjectionSourceRevision = String(
+    runtimeSnapshot.projection.metadata?.contentRevision ?? runtimeSnapshot.projection.revision,
+  );
+  const contextGitIdentity = cachedGitIdentity(repository.canonicalRoot);
+  const contextSourceIdentity = {
+    repoId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+    canonicalRoot: repository.canonicalRoot,
+    head: contextGitIdentity.head,
+    branch: contextGitIdentity.branch,
+    workingTreeFingerprint: contextGitIdentity.workingTreeFingerprint,
+    runtimeGeneration: runtimeSnapshot.projection.metadata?.producerGeneration,
+    sourceRevision: contextProjectionSourceRevision,
+    variant: 'summary' as const,
+    toolset: ctx.toolset,
+    profile: ctx.policy.profile,
+  };
+  const contextProjection = readControllerContextProjection(ctx.controllerHome, repository.repoId, {
+    sourceIdentity: contextSourceIdentity,
+  });
+  const contextProjectionStale = controllerContextProjectionNeedsRefresh(
+    contextProjection,
+    contextProjectionSourceRevision,
+    contextSourceIdentity,
+  );
+  const recentErrors = Array.isArray(args.recent_errors) ? args.recent_errors.map(String) : [];
+  const runtimeSource = runtimeSourceSnapshotStatus(readiness.daemon.source, ctx.runtimeSourceRoot);
+  let runtimeStorageReady: boolean | undefined;
+  let runtimeStorageWarnings: string[] = [];
+  try {
+    const runtimeStorage = ensureRepositoryRuntimeStorage(repository, ctx.controllerHome);
+    runtimeStorageReady = runtimeStorage.readyForExecution;
+    runtimeStorageWarnings = runtimeStorage.warnings;
+  } catch (error) {
+    runtimeStorageReady = false;
+    runtimeStorageWarnings = [error instanceof Error ? error.message : String(error)];
+  }
+  const plugins = listAssistantPluginManifests(ctx.controllerHome, repository, { preferStored: true });
+  const localJobs = listLocalBridgeJobSnapshots(repository.canonicalRoot, 30);
+  const executionJobs = listExecutionJobs(ctx.controllerHome, repository.repoId, 30);
+  return {
+    generatedAt: new Date().toISOString(),
+    daemonStatus: readiness.daemon.status,
+    daemonError: readiness.daemon.error,
+    schedulerStatus: readiness.durableScheduler.status,
+    schedulerHeartbeatAgeMs: readiness.durableScheduler.heartbeatAgeMs,
+    schedulerDispatchHeartbeatAgeMs: readiness.durableScheduler.dispatchHeartbeatAgeMs,
+    queueDepth: readiness.workerLoop.queueDepth,
+    runningWorkers: readiness.workerLoop.runningWorkers,
+    activeLeases: readiness.workerLoop.activeLeases,
+    localBridgeRunning: localBridge?.running ?? inferredLocalBridge?.running,
+    localBridgeError: localBridge?.error,
+    runtimeHealth: readiness.health,
+    runtimeOperationalView: readiness.operationalView,
+    connectorHealthy: undefined,
+    runtimeProjectionStale: runtimeSnapshot.stale,
+    runtimeProjectionPersisted: runtimeSnapshot.persisted,
+    runtimeSourceCoherence: {
+      ready: !runtimeSource.restartRequired,
+      code: runtimeSource.code,
+      reasons: runtimeSource.reasons,
+      summary: runtimeSource.restartRequired
+        ? formatRuntimeSourceDriftMessage(runtimeSource)
+        : 'Runtime source snapshot matches the current Controller Runtime source.',
+    },
+    contextProjectionStale,
+    commandPreviewAvailable: args.command_preview_available === undefined ? true : args.command_preview_available === true,
+    commandExecuteAvailable: args.command_execute_available === undefined ? true : args.command_execute_available === true,
+    issueToolsAvailable: args.issue_tools_available === undefined ? true : args.issue_tools_available === true,
+    jobToolsAvailable: args.job_tools_available === undefined ? true : args.job_tools_available === true,
+    checksAvailable: listControllerChecks(repository.canonicalRoot).length > 0,
+    runtimeStorageReady,
+    runtimeStorageWarnings,
+    pluginStates: plugins.map((plugin) => ({
+      pluginId: plugin.pluginId,
+      enabled: plugin.enabled,
+      healthState: plugin.health.state,
+      ready: plugin.health.ready,
+      errors: plugin.health.errors,
+      warnings: plugin.health.warnings,
+    })),
+    recentErrors,
+    localJobs: localJobs.map((job) => ({ status: job.status, error: job.error, updatedAt: job.updatedAt })),
+    executionJobs: executionJobs.map((job) => ({
+      status: job.status,
+      error: job.error,
+      updatedAt: job.updatedAt,
+      operation: job.payload.operation,
+    })),
+  };
+}
+
+async function capabilityRecoverySnapshot(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: ReturnType<typeof selected>,
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  return buildCapabilityRecoverySnapshot(await capabilityRecoveryInput(ctx, repository, args)) as unknown as Record<string, unknown>;
+}
+
+export async function callRecoveryAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  switch (name) {
+    case 'capability_recovery_probe': {
+      const repository = selected(ctx, args);
+      const snapshot = await buildCapabilityRecoverySnapshot(await capabilityRecoveryInput(ctx, repository, args));
+      const blockingCapabilityCount = snapshot.capabilities
+        .filter((capability) => ['blocked', 'unavailable', 'degraded'].includes(capability.state))
+        .length;
+      const ready = blockingCapabilityCount === 0 && snapshot.platformBlocked !== true;
+      return result({
+        ready,
+        reasonCodes: ready ? [] : [snapshot.externalLifecycleHandoff?.reasonCode ?? 'RUNTIME_DIAGNOSTICS_ATTENTION_REQUIRED'],
+        diagnostics: {
+          capabilityCount: snapshot.capabilities.length,
+          blockingCapabilityCount,
+          platformBlocked: snapshot.platformBlocked === true,
+          recentAuditCount: listRecoveryAuditRecords(ctx.controllerHome, repository.repoId, 10).length,
+        },
+        externalLifecycleHandoff: snapshot.externalLifecycleHandoff,
+        observedAt: snapshot.generatedAt,
+        mutatesState: false,
+        ownsRuntimeLifecycle: false,
+      });
+    }
+    case 'capability_recovery_plan': {
+      const repository = selected(ctx, args);
+      const snapshot = await buildCapabilityRecoverySnapshot(await capabilityRecoveryInput(ctx, repository, args));
+      const blockingCapabilityCount = snapshot.capabilities
+        .filter((capability) => ['blocked', 'unavailable', 'degraded'].includes(capability.state))
+        .length;
+      const ready = blockingCapabilityCount === 0 && snapshot.platformBlocked !== true;
+      return result({
+        ready,
+        reasonCodes: ready ? [] : [snapshot.externalLifecycleHandoff?.reasonCode ?? 'RUNTIME_DIAGNOSTICS_ATTENTION_REQUIRED'],
+        diagnostics: {
+          capabilityCount: snapshot.capabilities.length,
+          blockingCapabilityCount,
+          platformBlocked: snapshot.platformBlocked === true,
+        },
+        observedAt: snapshot.generatedAt,
+        handoffRequired: !ready,
+        externalLifecycleHandoff: snapshot.externalLifecycleHandoff,
+        notes: snapshot.notes,
+        next: ready
+          ? 'Continue through the current Runtime and Work interfaces.'
+          : snapshot.externalLifecycleHandoff
+            ? 'Create or consume an rh_inbox handoff for the external Runtime lifecycle owner. Operate on the existing single forge-runtime only, then verify controller_ready and rh_status source coherence.'
+            : 'Inspect runtime_maintenance_status and create an rh_inbox handoff when operator or external Controller action is required.',
+      });
+    }
+    case 'runtime_maintenance_status': {
+      const repository = selected(ctx, args);
+      return result(buildRuntimeMaintenanceStatus(repository, ctx.controllerHome, {
+        minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+        maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+        cancelPendingApprovals: args.cancel_pending_approvals === true,
+      }) as unknown as Record<string, unknown>);
+    }
+    case 'runtime_maintenance_apply': {
+      const repository = selected(ctx, args);
+      const actionId = String(args.action_id ?? '').trim() as RuntimeMaintenanceActionId;
+      return result(executeRuntimeMaintenanceAction({
+        controllerHome: ctx.controllerHome,
+        repository,
+        actionId,
+        confirmMaintenance: args.confirm_maintenance === true,
+        authorization: typeof args.authorization === 'string' ? args.authorization : undefined,
+        minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+        maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+        cancelPendingApprovals: args.cancel_pending_approvals === true,
+      }) as unknown as Record<string, unknown>);
+    }
+    case 'capability_recovery_apply': {
+      const repository = selected(ctx, args);
+      const actionId = String(args.action_id ?? '').trim();
+      const reason = typeof args.reason === 'string' && args.reason.trim() ? args.reason.trim() : 'manual recovery action';
+      try {
+        return result(await executeCapabilityRecoveryAction({
+          controllerHome: ctx.controllerHome,
+          repository,
+          actionId,
+          reason,
+          confirmAuthorization: args.confirm_authorization === true,
+          authorization: typeof args.authorization === 'string' ? args.authorization : undefined,
+          minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+          maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+          callStandaloneRecoveryTool: (toolName, toolArgs) => callStandaloneRecoveryTool(ctx.controllerHome, toolName, toolArgs),
+          recoverySnapshot: () => capabilityRecoverySnapshot(ctx, repository, args),
+        }) as unknown as Record<string, unknown>);
+      } catch (error) {
+        if (error instanceof RecoveryApplicationError && error.code === 'RECOVERY_ACTION_UNKNOWN') {
+          return result({ error: { code: error.code, message: error.actionId } }, true);
+        }
+        throw error;
+      }
+    }
+    case 'runtime_storage_repair_preview': {
+      const repository = selected(ctx, args);
+      return result(previewRuntimeStorageRepair(repository, ctx.controllerHome, {
+        minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+        maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+      }) as unknown as Record<string, unknown>);
+    }
+    case 'runtime_storage_repair_apply': {
+      const repository = selected(ctx, args);
+      const candidateIds = Array.isArray(args.candidate_ids) ? args.candidate_ids.map(String) : undefined;
+      const applied = applyRuntimeStorageRepair(repository, ctx.controllerHome, {
+        candidateIds,
+        minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+        maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : undefined,
+        confirmRepair: args.confirm_repair === true,
+      });
+      const runtimeStorage = ensureRepositoryRuntimeStorage(repository, ctx.controllerHome);
+      const projection = readRepositoryProjectionSnapshot(ctx.controllerHome, repository.repoId);
+      return result({ ...applied, runtimeStorage, projection });
+    }
+    default:
+      return undefined;
+  }
+}

package/adapters/mcp/runtime-gateway/recovery-client-adapter.ts

@@ -0,0 +1,70 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { gatewayToken, loadRecoveryConfig } from '../../../src/runtime/standalone-recovery/core';
+import {
+  assertCompleteExplicitRecoveryIdentity,
+  hydrateRecoveryToolArguments,
+  isRecoveryStatusDerivableField,
+  recoveryToolRequiredFields,
+  recoveryToolSchemaUnrepresentableError,
+  recoveryToolUnrepresentableRequiredFields,
+} from './recovery-tool-contract';
+
+export function recoveryStructuredPayload(
+  response: Awaited<ReturnType<Client['callTool']>>,
+  operation: string,
+): Record<string, unknown> {
+  if (response.isError) throw new Error(`RECOVERY_TOOL_FAILED: ${operation}`);
+  const payload = response.structuredContent;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error(`RECOVERY_TOOL_PROTOCOL_INVALID: ${operation}`);
+  }
+  return payload as Record<string, unknown>;
+}
+
+export async function recoveryToolArguments(
+  client: Client,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const listed = await client.listTools();
+  const descriptor = listed.tools.find((tool) => tool.name === name);
+  if (!descriptor) throw new Error(`RECOVERY_TOOL_UNKNOWN: ${name}`);
+  assertCompleteExplicitRecoveryIdentity(name, args);
+  const required = recoveryToolRequiredFields(descriptor.inputSchema);
+  const missing = required.filter((field) => !Object.prototype.hasOwnProperty.call(args, field));
+  if (missing.length === 0) return args;
+  const unrepresentable = recoveryToolUnrepresentableRequiredFields(descriptor.inputSchema, args);
+  if (unrepresentable.length) throw recoveryToolSchemaUnrepresentableError(name, unrepresentable);
+  const needsStatus = missing.some(isRecoveryStatusDerivableField);
+  const status = needsStatus
+    ? recoveryStructuredPayload(await client.callTool({ name: 'runtime_status', arguments: {} }), 'runtime_status')
+    : undefined;
+  return hydrateRecoveryToolArguments({ toolName: name, inputSchema: descriptor.inputSchema, args, status });
+}
+
+/** Transport-only bridge to the standalone Recovery Gateway. */
+export async function callStandaloneRecoveryTool(
+  controllerHome: string,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const config = loadRecoveryConfig(controllerHome);
+  const gateway = config.gateway;
+  if (!gateway || gateway.host !== '127.0.0.1') {
+    throw new Error('RECOVERY_GATEWAY_UNAVAILABLE: loopback Recovery Gateway is not configured');
+  }
+  const token = gatewayToken(config);
+  if (!token) throw new Error('RECOVERY_GATEWAY_AUTH_UNAVAILABLE');
+  const transport = new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${gateway.port}/recovery/mcp`), {
+    requestInit: { headers: { Authorization: `Bearer ${token}` } },
+  });
+  const client = new Client({ name: 'forge-runtime-lifecycle-handoff', version: '1.0.0' });
+  try {
+    await client.connect(transport);
+    const effectiveArgs = await recoveryToolArguments(client, name, args);
+    const response = await client.callTool({ name, arguments: effectiveArgs });
+    return recoveryStructuredPayload(response, name);
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}

package/adapters/mcp/runtime-gateway/recovery-tool-contract.ts

@@ -0,0 +1,99 @@
+import { RECOVERY_MUTATION_IDENTITY_FIELDS } from '../../../src/runtime/standalone-recovery/mutation-identity-contract';
+
+const STATUS_DERIVABLE_RECOVERY_FIELDS = new Set<string>([
+  ...RECOVERY_MUTATION_IDENTITY_FIELDS,
+  'expected_active_release_id',
+  'expected_authority_revision',
+]);
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function hasOwn(value: Record<string, unknown>, field: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, field);
+}
+
+export function recoveryToolRequiredFields(inputSchema: unknown): string[] {
+  const schema = record(inputSchema);
+  return Array.isArray(schema?.required)
+    ? schema.required.filter((value): value is string => typeof value === 'string' && Boolean(value.trim()))
+    : [];
+}
+
+export function isRecoveryStatusDerivableField(field: string): boolean {
+  return STATUS_DERIVABLE_RECOVERY_FIELDS.has(field);
+}
+
+export function assertCompleteExplicitRecoveryIdentity(toolName: string, args: Record<string, unknown>): void {
+  const supplied = RECOVERY_MUTATION_IDENTITY_FIELDS.filter((field) => hasOwn(args, field));
+  if (supplied.length === 0 || supplied.length === RECOVERY_MUTATION_IDENTITY_FIELDS.length) return;
+  const missing = RECOVERY_MUTATION_IDENTITY_FIELDS.filter((field) => !hasOwn(args, field));
+  throw new Error(`RECOVERY_TOOL_IDENTITY_PARTIAL:${toolName}:${missing.join(',')}`);
+}
+
+export function recoveryToolUnrepresentableRequiredFields(
+  inputSchema: unknown,
+  args: Record<string, unknown>,
+): string[] {
+  return recoveryToolRequiredFields(inputSchema)
+    .filter((field) => !hasOwn(args, field) && !isRecoveryStatusDerivableField(field));
+}
+
+export function recoveryToolSchemaUnrepresentableError(toolName: string, fields: readonly string[]): Error {
+  return new Error(`RECOVERY_TOOL_SCHEMA_UNREPRESENTABLE:${toolName}:${fields.join(',')}`);
+}
+
+/**
+ * Project only machine facts that Recovery itself exposes through runtime_status.
+ * This is transport hydration, not a second fencing authority. Explicit caller
+ * expectations always win and are later checked by Standalone Recovery.
+ */
+export function recoveryStatusDerivedArguments(status: Record<string, unknown>): Record<string, unknown> {
+  const identity = record(status.identity);
+  if (!identity) return {};
+  const recovery = record(identity.recovery);
+  const targetRuntime = record(identity.targetRuntime);
+  const derived: Record<string, unknown> = {};
+
+  if (typeof identity.host === 'string' && identity.host.trim()) derived.expected_host = identity.host;
+  if (typeof identity.platform === 'string' && identity.platform.trim()) derived.expected_platform = identity.platform;
+  if (typeof identity.controllerHome === 'string' && identity.controllerHome.trim()) derived.expected_controller_home = identity.controllerHome;
+  if (recovery) {
+    derived.expected_recovery_release = typeof recovery.releaseRevision === 'string' && recovery.releaseRevision.trim()
+      ? recovery.releaseRevision
+      : 'none';
+  }
+  if (targetRuntime && typeof targetRuntime.id === 'string' && targetRuntime.id.trim()) {
+    derived.expected_target_runtime = targetRuntime.id;
+  }
+  if (targetRuntime && typeof targetRuntime.activeReleaseId === 'string' && targetRuntime.activeReleaseId.trim()) {
+    derived.expected_active_release_id = targetRuntime.activeReleaseId;
+  }
+  if (targetRuntime && Number.isInteger(targetRuntime.authorityRevision) && Number(targetRuntime.authorityRevision) >= 1) {
+    derived.expected_authority_revision = Number(targetRuntime.authorityRevision);
+  }
+  return derived;
+}
+
+export function hydrateRecoveryToolArguments(input: {
+  toolName: string;
+  inputSchema: unknown;
+  args: Record<string, unknown>;
+  status?: Record<string, unknown>;
+}): Record<string, unknown> {
+  assertCompleteExplicitRecoveryIdentity(input.toolName, input.args);
+  const required = recoveryToolRequiredFields(input.inputSchema);
+  const hydrated = { ...input.args };
+  const derived = input.status ? recoveryStatusDerivedArguments(input.status) : {};
+
+  for (const field of required) {
+    if (!hasOwn(hydrated, field) && hasOwn(derived, field)) hydrated[field] = derived[field];
+  }
+
+  const unresolved = required.filter((field) => !hasOwn(hydrated, field));
+  if (unresolved.length) throw recoveryToolSchemaUnrepresentableError(input.toolName, unresolved);
+  return hydrated;
+}

package/adapters/mcp/runtime-gateway/repository-compat-adapter.ts

@@ -0,0 +1,110 @@
+import type { McpToolDefinition, CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { boundedPluginArtifactImageContent, jsonPreview, result, resultWithPluginArtifactImages } from './result-adapter';
+import { expectedRevision, repositoryRootForRepoId, selected, stringList } from './shared-adapter';
+import { completeReviewedDirectEditWorkAfterCommit, prepareReviewedDirectEditWorkCommit, type ReviewedDirectEditWorkCommitPlan } from '../../../src/runtime/control-plane/execution/direct-edit-work-completion';
+import { repositoryChangeVerify } from '../../../src/cli/controller/composite-operations';
+import {
+  commitSelectedPaths,
+  selectedPathDiff,
+  stageSelectedPaths,
+} from '../../../src/cli/repositories/selected-path-actions';
+
+
+
+export async function callRepositoryCompatibilityAdapter(ctx: MultiRepositoryMcpToolContext, name: string, args: Record<string, unknown>): Promise<CallToolResult | undefined> {
+  try {
+    switch (name) {
+      case 'git_diff_paths': {
+              const repository = selected(ctx, args);
+              return result({
+                ...selectedPathDiff(repository, {
+                  paths: args.paths,
+                  staged: args.staged === true,
+                  maxBytes: typeof args.max_bytes === 'number' ? args.max_bytes : undefined,
+                }),
+              });
+            }
+      case 'git_stage_paths': {
+              const repository = selected(ctx, args);
+              const staged = stageSelectedPaths(ctx.controllerHome, repository, { paths: args.paths });
+              return result({
+                repoId: repository.repoId,
+                checkoutId: repository.activeCheckoutId,
+                ...staged,
+              }, staged.execution.ok !== true);
+            }
+      case 'git_commit_paths': {
+              const repository = selected(ctx, args);
+              let reviewedCommitPlan: ReviewedDirectEditWorkCommitPlan | undefined;
+              let committed;
+              try {
+                committed = commitSelectedPaths(ctx.controllerHome, repository, {
+                  paths: args.paths,
+                  message: args.message,
+                  beforeCommitGuard: ({ stagedPaths, currentHead }) => {
+                    reviewedCommitPlan = prepareReviewedDirectEditWorkCommit({
+                      controllerHome: ctx.controllerHome,
+                      repository,
+                      stagedPaths,
+                      currentHead,
+                    });
+                  },
+                });
+              } catch (error) {
+                return result({
+                  repoId: repository.repoId,
+                  checkoutId: repository.activeCheckoutId,
+                  error: {
+                    code: 'SELECTED_PATH_PRECOMMIT_GUARD_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                  },
+                }, true);
+              }
+              const directEditWorkCompletion = !committed.error && committed.commit?.ok === true && reviewedCommitPlan
+                ? completeReviewedDirectEditWorkAfterCommit({
+                    controllerHome: ctx.controllerHome,
+                    repository,
+                    plan: reviewedCommitPlan,
+                    fallbackBranch: repository.defaultBranch || 'main',
+                  })
+                : undefined;
+              return result({
+                repoId: repository.repoId,
+                checkoutId: repository.activeCheckoutId,
+                ...committed,
+                ...(directEditWorkCompletion ? { directEditWorkCompletion } : {}),
+              }, Boolean(committed.error));
+            }
+      case 'repository_change_verify': {
+              const repository = selected(ctx, args);
+              const expectedFileShas = args.expected_file_shas && typeof args.expected_file_shas === 'object' && !Array.isArray(args.expected_file_shas)
+                ? Object.fromEntries(
+                  Object.entries(args.expected_file_shas as Record<string, unknown>)
+                    .filter((entry): entry is [string, string] => typeof entry[1] === 'string'),
+                )
+                : undefined;
+              const payload = repositoryChangeVerify({
+                repo: repository.canonicalRoot,
+                expectedBranch: typeof args.expected_branch === 'string' ? args.expected_branch : undefined,
+                expectedHead: typeof args.expected_head === 'string' ? args.expected_head : undefined,
+                expectedFileShas,
+                patch: typeof args.patch === 'string' ? args.patch : undefined,
+                allowedPaths: Array.isArray(args.allowed_paths)
+                  ? args.allowed_paths.filter((value): value is string => typeof value === 'string')
+                  : undefined,
+                checks: Array.isArray(args.checks)
+                  ? args.checks.filter((value): value is string => typeof value === 'string')
+                  : undefined,
+                checkTimeoutMs: typeof args.check_timeout_ms === 'number' ? args.check_timeout_ms : undefined,
+              });
+              return result(payload as unknown as Record<string, unknown>, payload.status === 'failed');
+            }
+      default: return undefined;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const structuredCode = /^([A-Z][A-Z0-9_]+)(?::|$)/.exec(message)?.[1];
+    return result({ error: { code: structuredCode ?? 'RUNTIME_TOOL_FAILED', message } }, true);
+  }
+}

package/adapters/mcp/runtime-gateway/result-adapter.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { isAbsolute, relative, resolve, sep } from 'path';
+import type { CallToolResult as SdkCallToolResult } from "@modelcontextprotocol/client";
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import { repositoryControllerRoot } from '../../../src/cli/repositories/controller-home';
+import { redactMcpText } from '../redaction';
+
+/** Transport-only MCP result envelope. No lifecycle or domain mutation belongs here. */
+export function result(value: Record<string, unknown>, isError = false): CallToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value) }],
+    structuredContent: value,
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+const MAX_INLINE_PLUGIN_IMAGE_BYTES = 8 * 1024 * 1024;
+const MAX_INLINE_PLUGIN_IMAGES = 4;
+const INLINE_PLUGIN_IMAGE_MEDIA_TYPES = new Set(['image/png', 'image/jpeg', 'image/webp']);
+
+type McpImageContent = Extract<SdkCallToolResult['content'][number], { type: 'image' }>;
+
+export function boundedPluginArtifactImageContent(
+  controllerHome: string,
+  repoId: string,
+  pluginResult: Record<string, unknown> | undefined,
+): McpImageContent[] {
+  if (!pluginResult) return [];
+  const nestedResult = pluginResult.result && typeof pluginResult.result === 'object' && !Array.isArray(pluginResult.result)
+    ? pluginResult.result as Record<string, unknown>
+    : undefined;
+  const candidates = [
+    ...(Array.isArray(pluginResult.artifactCandidates) ? pluginResult.artifactCandidates : []),
+    ...(nestedResult && Array.isArray(nestedResult.artifactCandidates) ? nestedResult.artifactCandidates : []),
+  ];
+  if (candidates.length === 0) return [];
+  const allowedRoot = resolve(repositoryControllerRoot(controllerHome, repoId));
+  const images: McpImageContent[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const candidate of candidates) {
+    if (images.length >= MAX_INLINE_PLUGIN_IMAGES) break;
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) continue;
+    const record = candidate as Record<string, unknown>;
+    const mediaType = typeof record.mediaType === 'string' ? record.mediaType : '';
+    const path = typeof record.path === 'string' ? record.path : '';
+    if (!INLINE_PLUGIN_IMAGE_MEDIA_TYPES.has(mediaType) || !path) continue;
+
+    const resolvedPath = resolve(path);
+    if (seenPaths.has(resolvedPath)) continue;
+    const rel = relative(allowedRoot, resolvedPath);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
+    if (!existsSync(resolvedPath)) continue;
+
+    try {
+      const stat = statSync(resolvedPath);
+      if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_INLINE_PLUGIN_IMAGE_BYTES) continue;
+      images.push({
+        type: 'image',
+        data: readFileSync(resolvedPath).toString('base64'),
+        mimeType: mediaType,
+      });
+      seenPaths.add(resolvedPath);
+    } catch {
+      // Structured plugin output remains authoritative when an artifact cannot be inlined.
+    }
+  }
+
+  return images;
+}
+
+export function resultWithPluginArtifactImages(
+  value: Record<string, unknown>,
+  controllerHome: string,
+  repoId: string,
+  pluginResult: Record<string, unknown> | undefined,
+): CallToolResult {
+  const images = boundedPluginArtifactImageContent(controllerHome, repoId, pluginResult);
+  const richResult: SdkCallToolResult = {
+    content: [{ type: 'text', text: JSON.stringify(value) }, ...images],
+    structuredContent: value,
+  };
+  return richResult as unknown as CallToolResult;
+}
+
+export function scrubPathText(text: string, replacements: string[]): string {
+  let output = text;
+  for (const replacement of [...new Set(replacements.filter((entry) => entry.startsWith('/')))].sort((left, right) => right.length - left.length)) {
+    output = output.split(replacement).join('<repo>');
+  }
+  return output
+    .replace(/\/(?:private\/)?tmp\/[^\s"']+/g, '<abs-path>')
+    .replace(/\/(?:private\/)?var\/folders\/[^\s"']+/g, '<abs-path>')
+    .replace(/\/Users\/[^\s"']+/g, '<abs-path>')
+    .replace(/[A-Za-z]:\\[^\s"']+/g, '<abs-path>');
+}
+
+export function jsonPreview(
+  value: unknown,
+  maxChars = 800,
+  replacements: string[] = [],
+): { preview: string; truncated: boolean; byteLength: number } {
+  const serialized = JSON.stringify(value);
+  const redacted = redactMcpText(scrubPathText(serialized, replacements)).text;
+  const byteLength = Buffer.byteLength(serialized);
+  if (redacted.length <= maxChars) return { preview: redacted, truncated: false, byteLength };
+  return { preview: `${redacted.slice(0, maxChars)}...`, truncated: true, byteLength };
+}