@moretea-labs/forge 1.7.1 → 1.8.0

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

@@ -0,0 +1,308 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { buildWorkspaceAuthStatus, prepareWorkspaceAuthLogin, summarizePluginForLowInterception } from '../../../src/runtime/safe-tooling';
+import {
+  assistantPluginScope,
+  controllerPluginRepository,
+  getAssistantPluginManifest,
+  listAssistantPluginManifests,
+} from '../../../src/runtime/plugins/store';
+import { executeAssistantPluginActionApplication } from '../../../src/runtime/plugins/action-application';
+import { mcpPluginExecutionOrigin } from '../../../src/runtime/plugins/execution-origin';
+import type { AssistantPluginManifest } from '../../../src/runtime/plugins/types';
+import { result, resultWithPluginArtifactImages } from './result-adapter';
+import { selected } from './shared-adapter';
+
+function pluginRepository(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+  pluginId: string,
+) {
+  return assistantPluginScope(pluginId, ctx.controllerHome) === 'controller'
+    ? controllerPluginRepository(ctx.controllerHome)
+    : selected(ctx, args);
+}
+
+function summarizePlugin(manifest: AssistantPluginManifest): Record<string, unknown> {
+  return {
+    pluginId: manifest.pluginId,
+    provider: manifest.provider,
+    displayName: manifest.displayName,
+    pluginVersion: manifest.pluginVersion,
+    revision: manifest.revision,
+    enabled: manifest.enabled,
+    lifecycle: manifest.lifecycle,
+    health: manifest.health,
+    authority: manifest.authority,
+    permissions: manifest.permissions,
+    capabilities: manifest.capabilities,
+    actions: manifest.actions.map((action) => ({
+      actionId: action.actionId,
+      title: action.title,
+      description: action.description,
+      readOnly: action.readOnly,
+      risk: action.risk,
+      confirmation: action.confirmation,
+      requiredConfirmationText: action.requiredConfirmationText,
+      defaultTimeoutMs: action.defaultTimeoutMs,
+      cancellable: action.cancellable,
+      idempotent: action.idempotent,
+      scopes: action.scopes,
+      resourceClaims: action.resourceClaims,
+      argumentsSchema: action.argumentsSchema,
+    })),
+    updatedAt: manifest.updatedAt,
+  };
+}
+
+function summarizePluginActionReceipt(manifest: AssistantPluginManifest): Record<string, unknown> {
+  return {
+    pluginId: manifest.pluginId,
+    provider: manifest.provider,
+    displayName: manifest.displayName,
+    pluginVersion: manifest.pluginVersion,
+    revision: manifest.revision,
+    enabled: manifest.enabled,
+    lifecycleState: manifest.lifecycle.state,
+    health: {
+      state: manifest.health.state,
+      ready: manifest.health.ready,
+      checkedAt: manifest.health.checkedAt,
+      errorCount: manifest.health.errors.length,
+      warningCount: manifest.health.warnings.length,
+    },
+    updatedAt: manifest.updatedAt,
+  };
+}
+
+function compactSubmittedPluginActionResult(value: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!value) return undefined;
+  const nested = value.result;
+  if (!nested || typeof nested !== 'object' || Array.isArray(nested)) return value;
+  const work = value.work;
+  return {
+    ...(nested as Record<string, unknown>),
+    ...(work && typeof work === 'object' && !Array.isArray(work) ? { work } : {}),
+  };
+}
+
+export async function callPluginAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  switch (name) {
+    case 'list_plugins': {
+      const controllerRepository = controllerPluginRepository(ctx.controllerHome);
+      const controllerPlugins = listAssistantPluginManifests(ctx.controllerHome, controllerRepository, {
+        forceRefresh: true,
+      }).map(summarizePlugin);
+      let repositoryPlugins: ReturnType<typeof summarizePlugin>[] = [];
+      let repositoryId: string | undefined;
+      try {
+        const repository = selected(ctx, args);
+        repositoryId = repository.repoId;
+        repositoryPlugins = listAssistantPluginManifests(ctx.controllerHome, repository, {
+          forceRefresh: true,
+        }).map(summarizePlugin);
+      } catch (error) {
+        if (typeof args.repo_id === 'string' && args.repo_id.trim()) throw error;
+      }
+      return result({
+        scope: repositoryPlugins.length > 0 ? 'combined' : 'controller',
+        repositoryId,
+        plugins: [...repositoryPlugins, ...controllerPlugins]
+          .sort((left, right) => String(left.pluginId).localeCompare(String(right.pluginId))),
+      });
+    }
+    case 'get_plugin': {
+      const pluginId = String(args.plugin_id ?? '').trim();
+      const repository = pluginRepository(ctx, args, pluginId);
+      return result({
+        scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
+        plugin: summarizePlugin(getAssistantPluginManifest(ctx.controllerHome, repository, pluginId)),
+      });
+    }
+    case 'plugin_action_execute': {
+      const pluginId = String(args.plugin_id ?? '').trim();
+      const workId = typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined;
+      const repository = pluginRepository(ctx, args, pluginId);
+      const workRepository = workId ? selected(ctx, args) : undefined;
+      const actionId = String(args.action_id ?? '').trim();
+      const requestId = String(args.request_id ?? '').trim();
+      const actionArguments = args.arguments && typeof args.arguments === 'object' && !Array.isArray(args.arguments)
+        ? args.arguments as Record<string, unknown>
+        : {};
+      const request = {
+        pluginId,
+        actionId,
+        requestId,
+        workId,
+        ...(workId && workRepository ? { workRepoId: workRepository.repoId } : {}),
+        args: actionArguments,
+        timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+        signal: ctx.signal,
+        confirmAuthorization: args.confirm_authorization === true,
+        confirmationText: typeof args.confirmation_text === 'string' ? args.confirmation_text : undefined,
+        origin: mcpPluginExecutionOrigin(ctx.principalId, 'plugin_action_execute', requestId),
+      };
+      const application = await executeAssistantPluginActionApplication({
+        controllerHome: ctx.controllerHome,
+        repository,
+        request,
+        interactiveWaitMs: typeof args.interactive_wait_ms === 'number' ? args.interactive_wait_ms : 750,
+        wait: args.wait === true,
+        waitMs: typeof args.wait_ms === 'number' ? args.wait_ms : 15_000,
+      });
+
+      if (application.kind === 'direct_read') {
+        const value = {
+          accepted: true,
+          direct: true,
+          durable: false,
+          plugin: summarizePluginActionReceipt(application.manifest),
+          action: {
+            actionId: application.action.actionId,
+            risk: application.action.risk,
+            confirmation: application.action.confirmation,
+          },
+          scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
+          result: application.result,
+          detail: {
+            tool: 'rh_context',
+            arguments: {
+              ...(repository.repoId === '__controller__' ? {} : { repo_id: repository.repoId }),
+              capability_id: `plugin.${pluginId}.${actionId}`,
+              detail_level: 'detail',
+            },
+          },
+          next: 'Continue with the returned bounded result; use rh_context capability detail only when the typed action schema/policy is needed.',
+        };
+        return resultWithPluginArtifactImages(value, ctx.controllerHome, repository.repoId, application.result);
+      }
+
+      if (application.kind === 'direct_non_persistent') {
+        return result({
+          accepted: true,
+          direct: true,
+          durable: false,
+          replayable: false,
+          mode: 'direct_non_persistent',
+          plugin: summarizePluginActionReceipt(application.manifest),
+          action: {
+            actionId: application.action.actionId,
+            risk: application.action.risk,
+            confirmation: application.action.confirmation,
+          },
+          scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
+          requestId,
+          result: application.result,
+          detail: {
+            tool: 'rh_context',
+            arguments: {
+              ...(repository.repoId === '__controller__' ? {} : { repo_id: repository.repoId }),
+              capability_id: `plugin.${pluginId}.${actionId}`,
+              detail_level: 'detail',
+            },
+          },
+          next: 'This protected action completed inline without durable replay state. Use the returned result only for the immediate next protected action.',
+        });
+      }
+
+      if (application.kind === 'lightweight_running') {
+        return result({
+          accepted: true,
+          direct: false,
+          durable: false,
+          mode: 'lightweight_process',
+          plugin: summarizePluginActionReceipt(application.manifest),
+          action: application.action ? {
+            actionId: application.action.actionId,
+            risk: application.action.risk,
+            confirmation: application.action.confirmation,
+            requiredConfirmationText: application.action.requiredConfirmationText,
+          } : { actionId },
+          scope: 'repository',
+          requestId,
+          process: application.process,
+          resultRef: { kind: 'process_logs', processId: application.process.processId },
+          next: 'The typed plugin action is isolated from the Canonical Runtime. Use process_wait on processId; after completion, call plugin_action_execute again with the same request_id to retrieve the deduplicated structured receipt.',
+        });
+      }
+
+      if (application.kind === 'lightweight_failed') {
+        const handle = application.process;
+        return result({
+          accepted: true,
+          direct: false,
+          durable: false,
+          mode: 'lightweight_process',
+          requestId,
+          process: handle,
+          error: {
+            code: handle.timedOut ? 'PLUGIN_ACTION_TIMEOUT' : handle.cancelled ? 'PLUGIN_ACTION_CANCELLED' : 'PLUGIN_ACTION_FAILED',
+            message: handle.stderrTail || handle.stdoutTail || `Plugin action process exited with code ${String(handle.exitCode)}`,
+          },
+        }, true);
+      }
+
+      const submitted = application.submitted;
+      const compactResult = compactSubmittedPluginActionResult(submitted.result);
+      const value = {
+        accepted: true,
+        deduplicated: submitted.deduplicated,
+        direct: true,
+        durable: false,
+        plugin: summarizePluginActionReceipt(submitted.manifest),
+        action: {
+          actionId: submitted.action.actionId,
+          risk: submitted.action.risk,
+          confirmation: submitted.action.confirmation,
+          requiredConfirmationText: submitted.action.requiredConfirmationText,
+        },
+        scope: repository.repoId === '__controller__' ? 'controller' : 'repository',
+        receiptId: submitted.receipt.receiptId,
+        requestId: submitted.receipt.requestId,
+        ...(submitted.receipt.workId ? { workId: submitted.receipt.workId } : {}),
+        authorization: submitted.authorization,
+        result: compactResult,
+        detail: {
+          tool: 'rh_context',
+          arguments: {
+            ...(repository.repoId === '__controller__' ? {} : { repo_id: repository.repoId }),
+            capability_id: `plugin.${pluginId}.${actionId}`,
+            detail_level: 'detail',
+          },
+        },
+        next: 'Continue with the returned bounded plugin result; use rh_context capability detail only when the typed action schema/policy is needed.',
+      };
+      return resultWithPluginArtifactImages(value, ctx.controllerHome, repository.repoId, compactResult);
+    }
+    case 'workspace_auth_status': {
+      const repository = selected(ctx, args);
+      return result(buildWorkspaceAuthStatus(listAssistantPluginManifests(ctx.controllerHome, repository)));
+    }
+    case 'workspace_auth_login_prepare': {
+      selected(ctx, args);
+      return result(prepareWorkspaceAuthLogin(ctx.controllerHome, {
+        service: typeof args.service === 'string' ? args.service : undefined,
+        scopes: Array.isArray(args.scopes) ? args.scopes.map(String) : undefined,
+        redirectUri: typeof args.redirect_uri === 'string' ? args.redirect_uri : undefined,
+      }));
+    }
+    case 'toolchain_plugin_summary': {
+      const pluginId = String(args.plugin_id ?? '').trim();
+      const repository = pluginRepository(ctx, args, pluginId);
+      const manifest = getAssistantPluginManifest(ctx.controllerHome, repository, pluginId);
+      return result({
+        plugin: summarizePluginForLowInterception(manifest),
+        nonOpaque: true,
+        next: manifest.pluginId === 'browser'
+          ? 'Use rh_context for browser capability schemas and plugin_action_execute for typed HTTP(S) browser actions.'
+          : undefined,
+      });
+    }
+    default:
+      return undefined;
+  }
+}

package/adapters/mcp/runtime-gateway/process-tools.ts

@@ -0,0 +1,289 @@
+/**
+ * Repository-scoped Lightweight/Durable Process lifecycle MCP tools.
+ *
+ * process_get / process_wait / process_logs / process_cancel
+ *
+ * These tools attach to an existing in-memory lightweight or persisted durable
+ * handle. They never re-execute the original command.
+ */
+
+import type { McpToolDefinition, CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import {
+  cancelRepositoryCommandProcess,
+  getRepositoryCommandProcess,
+  readRepositoryCommandProcessLogs,
+  waitRepositoryCommandProcess,
+} from '../../../src/runtime/execution/process-runtime';
+import { redactSensitiveText, redactSensitiveValue } from '../../../src/runtime/evidence/sensitive-output';
+
+function definition(
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: string[] = [],
+  readOnlyHint = false,
+  destructiveHint = false,
+): McpToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint, openWorldHint: false, destructiveHint },
+  };
+}
+
+const repoIdProp = {
+  type: 'string',
+  description: 'Repository or ephemeral workspace scope id returned by the originating command. Process must belong to this scope.',
+};
+const processIdProp = {
+  type: 'string',
+  description: 'Lightweight or durable process id returned by run_check / repository_command_execute.',
+};
+
+export const processToolDefinitions: McpToolDefinition[] = [
+  definition(
+    'run_check',
+    'Run one focused repository check, or launch one resource-compatible check wave, through Process Runtime. Use check_id for the existing single-check behavior or check_ids for a batch; do not send both. Batch mode validates the existing check-scheduling resource model and starts every check in one compatible wave concurrently without waiting for completion or creating a second scheduler. Cross-wave, invalid, release, and multi-phase batches fail closed. Long ordinary checks return managed handles; attach only at a real dependency boundary.',
+    {
+      repo_id: repoIdProp,
+      checkout_id: { type: 'string' },
+      check_id: { type: 'string', description: 'Single check id. Mutually exclusive with check_ids.' },
+      check_ids: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 32, uniqueItems: true, description: 'Batch check ids. All requested checks must fit one resource-compatible execution wave; mutually exclusive with check_id.' },
+      timeout_ms: { type: 'number' },
+      request_id: { type: 'string' },
+      issue_id: { type: 'string' },
+      task_id: { type: 'string' },
+      mode: { type: 'string', enum: ['direct', 'async', 'durable'] },
+      apply_mode: { type: 'string', enum: ['sync', 'async'] },
+      force_durable: { type: 'boolean' },
+    },
+    [],
+    false,
+  ),
+  definition(
+    'process_get',
+    'Non-blocking observation of a lightweight or durable process; never re-executes. Use only when the observation can change the next decision. It is not a synchronization join.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+    },
+    ['repo_id', 'process_id'],
+    true,
+  ),
+  definition(
+    'process_wait',
+    'Explicit dependency synchronization for one lightweight or durable process. Call only when the next decision or acceptance boundary is blocked on this exact result; do not use as periodic polling. Waits never re-execute the command.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+      timeout_ms: { type: 'number', description: 'Max wait milliseconds (default 15000).' },
+    },
+    ['repo_id', 'process_id'],
+    true,
+  ),
+  definition(
+    'process_logs',
+    'Read a bounded tail of lightweight or durable process stdout/stderr. Never loads unbounded logs. Readonly.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+      max_bytes: { type: 'number', description: 'Max tail bytes per stream (default 32KiB).' },
+    },
+    ['repo_id', 'process_id'],
+    true,
+  ),
+  definition(
+    'process_cancel',
+    'Cancel a lightweight or durable process through its owning runtime handle. Classified as workspace-write / process-control.',
+    {
+      repo_id: repoIdProp,
+      process_id: processIdProp,
+    },
+    ['repo_id', 'process_id'],
+    false,
+    true,
+  ),
+];
+
+const processToolNames = new Set(processToolDefinitions.map((tool) => tool.name));
+const processAttachmentToolNames = new Set(['process_get', 'process_wait', 'process_logs', 'process_cancel']);
+// A long-lived MCP wait can monopolize shared Runtime request/transport capacity
+// even though the underlying Process wait is asynchronous. Keep public waits
+// short and return a normal running snapshot; the Process continues unchanged
+// and callers can attach again only when the result is a real dependency.
+export const DEFAULT_PROCESS_WAIT_ATTACH_BUDGET_MS = 5_000;
+
+/**
+ * Stable controller-facing continuation semantics for a returned Process.
+ * This is deliberately response-only: Process Runtime remains the sole owner
+ * of execution and no polling scheduler or second state authority is created.
+ */
+export function managedProcessContinuation(handle: { completed?: boolean }): Record<string, string> {
+  if (handle.completed === true) {
+    return {
+      state: 'terminal',
+      nextAction: 'consume_terminal_result',
+      join: 'complete',
+      reexecution: 'forbidden',
+    };
+  }
+  return {
+    state: 'background',
+    nextAction: 'continue_independent_work',
+    join: 'required_at_dependency_boundary',
+    observation: 'process_get_if_it_can_change_the_next_decision',
+    repeatedWait: 'not_recommended',
+    reexecution: 'forbidden',
+  };
+}
+
+function result(value: Record<string, unknown>, isError = false): CallToolResult {
+  const safe = redactSensitiveValue(value).value;
+  return {
+    content: [{ type: 'text', text: JSON.stringify(safe, null, 2) }],
+    structuredContent: safe,
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+function failure(error: unknown): CallToolResult {
+  const message = redactSensitiveText(error instanceof Error ? error.message : String(error)).text;
+  const code = message.includes(':') ? message.slice(0, message.indexOf(':')) : 'PROCESS_TOOL_FAILED';
+  return result({ error: { code, message } }, true);
+}
+
+function requireRepoAndProcess(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+): { repoId: string; processId: string } {
+  const repoId = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
+  const processId = typeof args.process_id === 'string' ? args.process_id.trim() : '';
+  if (!repoId) throw new Error('REPOSITORY_ID_REQUIRED: repo_id is required for process tools');
+  if (!processId) throw new Error('PROCESS_ID_REQUIRED: process_id is required for process tools');
+
+  // The Process handle is the scope authority. Ephemeral workspace targets are
+  // intentionally not registered in Repository Registry, so requiring a live
+  // repository record here would make their returned managed handles impossible
+  // to resume. Exact repo/workspace scope + process id still fails closed.
+  const handle = getRepositoryCommandProcess(ctx.controllerHome, repoId, processId);
+  if (!handle) {
+    throw new Error(`PROCESS_NOT_FOUND: process ${processId} is not registered under repo ${repoId}`);
+  }
+  return { repoId, processId };
+}
+
+function handleToPayload(handle: NonNullable<ReturnType<typeof getRepositoryCommandProcess>>): Record<string, unknown> {
+  return {
+    processId: handle.processId,
+    workId: handle.workId,
+    commandId: handle.commandId,
+    status: handle.status,
+    contractStatus: handle.contractStatus,
+    route: handle.route,
+    pid: handle.pid,
+    startedAt: handle.startedAt,
+    interactiveWaitMs: handle.interactiveWaitMs,
+    timeoutMs: handle.timeoutMs,
+    completed: handle.completed === true,
+    ok: handle.ok,
+    exitCode: handle.exitCode,
+    timedOut: handle.timedOut,
+    cancelled: handle.cancelled,
+    stdout: handle.stdout,
+    stderr: handle.stderr,
+    // Keep the bounded tail available after completion for callers that use it
+    // as their compact log view. Lightweight terminal receipts bound this tail
+    // separately, so retaining the established field does not restore the
+    // previous full-output duplication in persisted state.
+    stdoutTail: handle.stdoutTail,
+    stderrTail: handle.stderrTail,
+    continuation: managedProcessContinuation(handle),
+    durableSideEffects: handle.durableSideEffects,
+  };
+}
+
+export async function callProcessTool(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  // run_check shares this module's public schema, but its execution authority is
+  // the Gateway check facade in router.ts. Only attachment/lifecycle operations
+  // consume an existing process_id here.
+  if (!processAttachmentToolNames.has(name)) return undefined;
+  try {
+    const { repoId, processId } = requireRepoAndProcess(ctx, args);
+    switch (name) {
+      case 'process_get': {
+        const handle = getRepositoryCommandProcess(ctx.controllerHome, repoId, processId);
+        if (!handle) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+        return result({
+          repoId,
+          process: handleToPayload(handle),
+        });
+      }
+      case 'process_wait': {
+        const requestedWaitMs = typeof args.timeout_ms === 'number' && Number.isFinite(args.timeout_ms)
+          ? Math.max(1, Math.trunc(args.timeout_ms))
+          : 15_000;
+        const testBudget = (ctx as MultiRepositoryMcpToolContext & { processWaitAttachBudgetMs?: unknown }).processWaitAttachBudgetMs;
+        const attachBudgetMs = typeof testBudget === 'number' && Number.isFinite(testBudget)
+          ? Math.max(1, Math.trunc(testBudget))
+          : DEFAULT_PROCESS_WAIT_ATTACH_BUDGET_MS;
+        const startedAt = Date.now();
+        const handle = await waitRepositoryCommandProcess(ctx.controllerHome, repoId, processId, {
+          timeoutMs: Math.min(requestedWaitMs, attachBudgetMs),
+        });
+        return result({
+          repoId,
+          process: handleToPayload(handle),
+          synchronization: handle.completed === true ? 'terminal_result_available' : 'continue_independent_work',
+          waitedMs: Date.now() - startedAt,
+          requestedWaitMs,
+          attachBudgetMs,
+          reExecuted: false,
+        });
+      }
+      case 'process_logs': {
+        const maxBytes = typeof args.max_bytes === 'number' && Number.isFinite(args.max_bytes)
+          ? Math.max(256, Math.trunc(args.max_bytes))
+          : 32 * 1024;
+        const logs = readRepositoryCommandProcessLogs(ctx.controllerHome, repoId, processId, maxBytes);
+        if (!logs) throw new Error(`PROCESS_NOT_FOUND: ${processId}`);
+        return result({
+          repoId,
+          processId,
+          stdout: logs.stdout,
+          stderr: logs.stderr,
+          stdoutBytes: logs.stdoutBytes,
+          stderrBytes: logs.stderrBytes,
+          truncated: logs.truncated,
+          maxBytes,
+        });
+      }
+      case 'process_cancel': {
+        const handle = await cancelRepositoryCommandProcess(ctx.controllerHome, repoId, processId);
+        return result({
+          repoId,
+          process: handleToPayload(handle),
+          cancelled: handle.cancelled === true || handle.status === 'cancelled' || handle.status === 'completed_unknown',
+        });
+      }
+      default:
+        return undefined;
+    }
+  } catch (error) {
+    return failure(error);
+  }
+}
+
+export function isProcessTool(name: string): boolean {
+  return processToolNames.has(name);
+}

package/adapters/mcp/runtime-gateway/protected-computer-adapter.ts

@@ -0,0 +1,76 @@
+import { COMPUTER_CONSOLE_UNLOCK_CAPABILITY } from '../../../packages/protocols/computer/index';
+import {
+  executeProtectedConsoleUnlockInvocation,
+  executeProtectedConsoleUnlockPreparation,
+} from '../../../src/runtime/plugins/computer-registration';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import { result } from './result-adapter';
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const FROZEN_CLIENT_PREPARE_CARRIER = 'prepare_provider_local';
+
+function protectedErrorCode(error: unknown): string {
+  if (error && typeof error === 'object' && typeof (error as { code?: unknown }).code === 'string') {
+    return String((error as { code: string }).code);
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return /^([A-Z][A-Z0-9_]+)(?::|$)/.exec(message)?.[1] ?? 'COMPUTER_CONSOLE_UNLOCK_FAILED';
+}
+
+export { executeProtectedConsoleUnlockInvocation, executeProtectedConsoleUnlockPreparation };
+export type {
+  ProtectedConsoleUnlockInvocationInput,
+  ProtectedConsoleUnlockPreparationInput,
+} from '../../../src/runtime/plugins/computer-registration';
+
+export async function callProtectedComputerAdapter(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (name !== 'computer_console_unlock_prepare' && name !== 'computer_console_unlock') return undefined;
+  if (name === 'computer_console_unlock' && args.credential_handle === undefined && typeof args.credential === 'string') {
+    if (args.credential === FROZEN_CLIENT_PREPARE_CARRIER) {
+      name = 'computer_console_unlock_prepare';
+    } else if (UUID_PATTERN.test(args.credential)) {
+      args = { ...args, credential_handle: args.credential };
+    } else {
+      return result({
+        accepted: false,
+        capability: COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+        action: 'unlock_console',
+        error: {
+          code: 'COMPUTER_CONSOLE_UNLOCK_FROZEN_CLIENT_CARRIER_INVALID',
+          message: 'Frozen clients may pass only the provider-local prepare sentinel or an opaque UUID handle; raw credentials are forbidden.',
+        },
+      }, true);
+    }
+  }
+  const action = name === 'computer_console_unlock_prepare' ? 'prepare_unlock_console' : 'unlock_console';
+  try {
+    const payload = name === 'computer_console_unlock_prepare'
+      ? await executeProtectedConsoleUnlockPreparation({
+          confirmAuthorization: args.confirm_authorization === true,
+          timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+        }, ctx.controllerHome)
+      : await executeProtectedConsoleUnlockInvocation({
+          credentialHandle: typeof args.credential_handle === 'string' ? args.credential_handle : '',
+          confirmAuthorization: args.confirm_authorization === true,
+          timeoutMs: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+        }, ctx.controllerHome);
+    return result({ accepted: true, ...payload });
+  } catch (error) {
+    return result({
+      accepted: false,
+      capability: COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+      action,
+      error: {
+        code: protectedErrorCode(error),
+        message: action === 'prepare_unlock_console'
+          ? 'Protected console-unlock credential preparation did not complete.'
+          : 'Protected console unlock did not complete. Provider-local credential material was not exposed.',
+      },
+    }, true);
+  }
+}