@moretea-labs/forge 1.7.1 → 1.8.0

package/adapters/mcp/tool-capability-cache.ts

@@ -0,0 +1,87 @@
+import type { McpToolDefinition } from './tool-mapping/tools';
+
+export type ControllerCapabilityGroup = 'core' | 'repository' | 'workflow' | 'git' | 'runtime' | 'plugins' | 'admin' | 'legacy';
+
+export interface CapabilityGroupSnapshot {
+  group: ControllerCapabilityGroup;
+  toolNames: string[];
+  definitions: McpToolDefinition[];
+}
+
+export interface ToolDefinitionCacheOptions {
+  maxSessions?: number;
+  maxEntriesPerSession?: number;
+}
+
+const CORE_TOOL_NAMES = new Set(['rh_context', 'rh_access', 'rh_work', 'rh_status', 'rh_inbox']);
+
+export function controllerCapabilityGroupForTool(name: string): ControllerCapabilityGroup {
+  if (CORE_TOOL_NAMES.has(name)) return 'core';
+  if (name.startsWith('repository_git_') || name.startsWith('git_')) return 'git';
+  if (name.startsWith('repository_')) return 'repository';
+  if (name.startsWith('plugin_') || name === 'list_plugins') return 'plugins';
+  if (name.startsWith('runtime_') || name.startsWith('controller_')) return 'runtime';
+  if (name.startsWith('work_') || name.startsWith('session_') || name.startsWith('approval_') || name.startsWith('result_')) return 'workflow';
+  if (name.startsWith('admin_')) return 'admin';
+  return 'legacy';
+}
+
+export function groupControllerToolDefinitions(definitions: readonly McpToolDefinition[]): CapabilityGroupSnapshot[] {
+  const grouped = new Map<ControllerCapabilityGroup, McpToolDefinition[]>();
+  for (const definition of definitions) {
+    const group = controllerCapabilityGroupForTool(definition.name);
+    const entries = grouped.get(group) ?? [];
+    entries.push(definition);
+    grouped.set(group, entries);
+  }
+  return [...grouped.entries()].map(([group, entries]) => ({ group, toolNames: entries.map((entry) => entry.name), definitions: entries }));
+}
+
+export class SessionToolDefinitionCache {
+  private readonly sessions = new Map<string, Map<string, readonly McpToolDefinition[]>>();
+  private readonly maxSessions: number;
+  private readonly maxEntriesPerSession: number;
+
+  constructor(options: ToolDefinitionCacheOptions = {}) {
+    this.maxSessions = Math.max(1, options.maxSessions ?? 32);
+    this.maxEntriesPerSession = Math.max(1, options.maxEntriesPerSession ?? 16);
+  }
+
+  getOrCreate(sessionId: string, cacheKey: string, factory: () => readonly McpToolDefinition[]): readonly McpToolDefinition[] {
+    let session = this.sessions.get(sessionId);
+    if (!session) {
+      session = new Map();
+      this.sessions.set(sessionId, session);
+      this.trimSessions();
+    } else {
+      this.sessions.delete(sessionId);
+      this.sessions.set(sessionId, session);
+    }
+    const cached = session.get(cacheKey);
+    if (cached) {
+      session.delete(cacheKey);
+      session.set(cacheKey, cached);
+      return cached;
+    }
+    const created = Object.freeze([...factory()]);
+    session.set(cacheKey, created);
+    while (session.size > this.maxEntriesPerSession) {
+      const oldest = session.keys().next().value;
+      if (oldest === undefined) break;
+      session.delete(oldest);
+    }
+    return created;
+  }
+
+  invalidateSession(sessionId: string): void { this.sessions.delete(sessionId); }
+  clear(): void { this.sessions.clear(); }
+  get sessionCount(): number { return this.sessions.size; }
+
+  private trimSessions(): void {
+    while (this.sessions.size > this.maxSessions) {
+      const oldest = this.sessions.keys().next().value;
+      if (oldest === undefined) break;
+      this.sessions.delete(oldest);
+    }
+  }
+}

package/adapters/mcp/tool-mapping/access-tools.ts

@@ -0,0 +1,387 @@
+import {
+  accessModeDescriptor,
+  isAccessMode,
+  readRepositoryAccessPolicy,
+  writeRepositoryAccessPolicy,
+} from '../../../src/runtime/control-plane/governance/access-policy';
+import {
+  persistControllerAccessMode,
+  resolveControllerAccessState,
+} from '../access-mode';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { loadRepositoryRegistry, resolveRepositorySelection } from '../../../src/cli/repositories/registry';
+import type { CallToolResult, McpToolDefinition } from './tools';
+
+function definition(
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: string[] = [],
+  readOnlyHint = true,
+): McpToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties,
+      ...(required.length ? { required } : {}),
+      additionalProperties: false,
+    },
+    annotations: {
+      readOnlyHint,
+      openWorldHint: false,
+      destructiveHint: false,
+    },
+  };
+}
+
+const repoId = { type: 'string', description: 'Stable repository id. Omit when exactly one repository is selected. Cannot be combined with all_repositories.' };
+
+export const accessToolDefinitions: McpToolDefinition[] = [
+  definition(
+    'rh_access',
+    'Always-exposed compatibility policy. Normal operations follow the host AI permission model; the MCP tool schema remains stable.',
+    {
+      operation: {
+        type: 'string',
+        enum: ['get', 'preview', 'set'],
+        description: 'Defaults to get.',
+      },
+      repo_id: repoId,
+      all_repositories: {
+        type: 'boolean',
+        description: 'When setting access, also update every enabled repository policy to the selected mode.',
+      },
+      mode: {
+        type: 'string',
+        enum: ['request', 'full_access'],
+        description: 'Target mode for preview or set.',
+      },
+      confirm_authorization: {
+        type: 'boolean',
+        description: 'Deprecated compatibility field. Normal mode changes use the host AI permission decision and do not require a second Forge confirmation.',
+      },
+      confirmation_text: {
+        type: 'string',
+        description: 'Optional compatibility confirmation text. Tool exposure never changes and no reconnect is required.',
+      },
+    },
+    [],
+    false,
+  ),
+  definition(
+    'repository_access_get',
+    'Read the Request or Full Access permission level for the selected repository.',
+    { repo_id: repoId },
+  ),
+  definition(
+    'repository_access_preview',
+    'Preview how Request or Full Access changes execution approval behavior. Tool discovery remains unchanged.',
+    {
+      repo_id: repoId,
+      all_repositories: {
+        type: 'boolean',
+        description: 'Preview the selected mode for every enabled repository policy.',
+      },
+      mode: {
+        type: 'string',
+        enum: ['request', 'full_access'],
+        description: 'Target access mode.',
+      },
+    },
+  ),
+  definition(
+    'repository_access_set',
+    'Set one or all enabled repository compatibility modes. Normal operations follow the host AI permission model; secrets, outside-repository paths, and destructive operations retain hard gates.',
+    {
+      repo_id: repoId,
+      all_repositories: {
+        type: 'boolean',
+        description: 'When true, apply the mode to every enabled registered repository. Cannot be combined with repo_id.',
+      },
+      mode: {
+        type: 'string',
+        enum: ['request', 'full_access'],
+        description: 'Request asks before elevated local effects. Full Access permits normal local repository work without repeated approval prompts.',
+      },
+      confirm_authorization: {
+        type: 'boolean',
+        description: 'Deprecated compatibility field. It is accepted but no longer required as a second authorization layer.',
+      },
+      confirmation_text: {
+        type: 'string',
+        description: 'Optional compatibility confirmation text; explicit confirm_authorization is sufficient.',
+      },
+    },
+    ['mode'],
+    false,
+  ),
+];
+
+export const accessToolNames = accessToolDefinitions.map((tool) => tool.name);
+
+function selected(ctx: MultiRepositoryMcpToolContext, args: Record<string, unknown>) {
+  return resolveRepositorySelection({
+    repoId: typeof args.repo_id === 'string' ? args.repo_id : undefined,
+    explicitPath: ctx.explicitRepository?.canonicalRoot,
+    controllerHome: ctx.controllerHome,
+    allowSoleRepository: true,
+  });
+}
+
+function result(value: Record<string, unknown>, isError = false): CallToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    structuredContent: value,
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+function accessToolGroups(_mode: 'request' | 'full_access'): string[] {
+  // Discovery is intentionally stable across modes. These are availability
+  // groups, not automatically-authorized effect groups.
+  return [
+    'status_and_readiness',
+    'repository_selection',
+    'approval_and_handoffs',
+    'access_control_plane',
+    'repository_reads',
+    'repository_writes_and_patches',
+    'commands_and_checks',
+    'git_and_branches',
+    'worktrees_and_task_runs',
+    'direct_edit_sessions',
+    'ios_xcode_and_simulator',
+    'screenshots_and_review_artifacts',
+  ];
+}
+
+function accessStatePayload(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: ReturnType<typeof selected>,
+  configured = resolveControllerAccessState({
+    controllerHome: ctx.controllerHome,
+    repoRoot: ctx.explicitRepository?.canonicalRoot,
+  }),
+  effective = resolveControllerAccessState({
+    controllerHome: ctx.controllerHome,
+    repoRoot: ctx.explicitRepository?.canonicalRoot,
+    toolsetOverride: ctx.toolset,
+    toolsetLocked: ctx.toolsetLocked,
+  }),
+) {
+  const repositoryPolicy = readRepositoryAccessPolicy(ctx.controllerHome, repository.repoId);
+  return {
+    configuredAccessMode: configured.configuredAccessMode,
+    effectiveAccessMode: effective.effectiveAccessMode,
+    effectiveToolset: effective.effectiveToolset,
+    exposureRevision: configured.exposureRevision,
+    lastAppliedAt: configured.lastAppliedAt,
+    source: effective.source,
+    reconnectRequired: false,
+    schemaRefreshRequired: false,
+    toolSchemaStable: true,
+    restartRequired: false,
+    repository: {
+      repoId: repository.repoId,
+      name: repository.displayName,
+    },
+    repositoryPolicy,
+    repositoryPolicyDescriptor: accessModeDescriptor(repositoryPolicy.mode),
+    toolGroups: accessToolGroups(effective.effectiveAccessMode),
+  };
+}
+
+function previewPayload(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: ReturnType<typeof selected>,
+  mode: 'request' | 'full_access',
+  applyAll: boolean,
+) {
+  const currentConfigured = resolveControllerAccessState({
+    controllerHome: ctx.controllerHome,
+    repoRoot: ctx.explicitRepository?.canonicalRoot,
+  });
+  const currentEffective = resolveControllerAccessState({
+    controllerHome: ctx.controllerHome,
+    repoRoot: ctx.explicitRepository?.canonicalRoot,
+    toolsetOverride: ctx.toolset,
+    toolsetLocked: ctx.toolsetLocked,
+  });
+  const currentPolicy = readRepositoryAccessPolicy(ctx.controllerHome, repository.repoId);
+  const currentGroups = accessToolGroups(currentEffective.effectiveAccessMode);
+  const nextGroups = accessToolGroups(mode);
+  return {
+    current: {
+      ...accessStatePayload(ctx, repository, currentConfigured, currentEffective),
+      toolGroups: currentGroups,
+    },
+    target: {
+      configuredAccessMode: mode,
+      effectiveAccessMode: mode,
+      effectiveToolset: currentEffective.effectiveToolset,
+      exposureRevision: currentConfigured.exposureRevision + (currentConfigured.configuredAccessMode === mode ? 0 : 1),
+      source: 'controller_home.access_mode',
+      toolGroups: nextGroups,
+      repositoryPolicyMode: mode,
+      repositoryPolicyDescriptor: accessModeDescriptor(mode),
+    },
+    changes: {
+      modeChanged: currentConfigured.configuredAccessMode !== mode,
+      toolsetChanged: false,
+      repositoryPolicyWillChange: currentPolicy.mode !== mode,
+      addedToolGroups: nextGroups.filter((group) => !currentGroups.includes(group)),
+      removedToolGroups: currentGroups.filter((group) => !nextGroups.includes(group)),
+      scope: applyAll ? 'all_enabled_repositories' : 'repository',
+    },
+    reconnectRequired: false,
+    schemaRefreshRequired: false,
+    toolSchemaStable: true,
+    restartRequired: false,
+    warning: 'Access mode changes execution approval only. The selected Core/Advanced/Full schema remains unchanged without reconnecting.',
+  };
+}
+
+export function callAccessTool(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+): CallToolResult | null {
+  if (!accessToolNames.includes(name)) return null;
+  try {
+    if (name === 'rh_access') {
+      const operation = args.operation === 'preview' || args.operation === 'set' ? args.operation : 'get';
+      const repository = selected(ctx, args);
+      if (operation === 'get') return result(accessStatePayload(ctx, repository));
+
+      const mode = args.mode;
+      if (!isAccessMode(mode)) {
+        return result({
+          error: {
+            code: 'ACCESS_MODE_INVALID',
+            message: 'mode must be request or full_access',
+          },
+        }, true);
+      }
+
+      const applyAll = args.all_repositories === true;
+      if (operation === 'preview') return result(previewPayload(ctx, repository, mode, applyAll));
+
+      const persisted = persistControllerAccessMode(ctx.controllerHome, mode, ctx.explicitRepository?.canonicalRoot);
+      if (applyAll) {
+        const repositories = loadRepositoryRegistry(ctx.controllerHome).repositories
+          .filter((entry) => entry.enabled !== false);
+        for (const entry of repositories) writeRepositoryAccessPolicy(ctx.controllerHome, entry.repoId, mode, 'user');
+      } else {
+        writeRepositoryAccessPolicy(ctx.controllerHome, repository.repoId, mode, 'user');
+      }
+      const configured = persisted.state;
+      const effective = resolveControllerAccessState({
+        controllerHome: ctx.controllerHome,
+        repoRoot: ctx.explicitRepository?.canonicalRoot,
+        toolsetOverride: ctx.toolset,
+        toolsetLocked: ctx.toolsetLocked,
+      });
+      return result({
+        ...accessStatePayload(ctx, repository, configured, effective),
+        updatedConfigPath: persisted.configPath,
+        scope: applyAll ? 'all_enabled_repositories' : 'repository',
+        warning: 'Access mode was saved. It affects new execution-policy snapshots immediately; no Connector reconnect or schema refresh is required.',
+      });
+    }
+
+    if (name === 'repository_access_get') {
+      const repository = selected(ctx, args);
+      const policy = readRepositoryAccessPolicy(ctx.controllerHome, repository.repoId);
+      return result({
+        repository: {
+          repoId: repository.repoId,
+          name: repository.displayName,
+        },
+        policy,
+        descriptor: accessModeDescriptor(policy.mode),
+        scope: 'repository',
+        storage: 'controllerHome',
+      });
+    }
+
+    if (name === 'repository_access_preview') {
+      const repository = selected(ctx, args);
+      const mode = isAccessMode(args.mode) ? args.mode : readRepositoryAccessPolicy(ctx.controllerHome, repository.repoId).mode;
+      return result(previewPayload(ctx, repository, mode, args.all_repositories === true));
+    }
+
+    const mode = args.mode;
+    if (!isAccessMode(mode)) {
+      return result({
+        error: {
+          code: 'ACCESS_MODE_INVALID',
+          message: 'mode must be request or full_access',
+        },
+      }, true);
+    }
+    const applyAll = args.all_repositories === true;
+    if (applyAll && typeof args.repo_id === 'string' && args.repo_id.trim()) {
+      return result({
+        error: {
+          code: 'ACCESS_MODE_SCOPE_INVALID',
+          message: 'repo_id cannot be combined with all_repositories.',
+        },
+      }, true);
+    }
+
+    if (applyAll) {
+      const repositories = loadRepositoryRegistry(ctx.controllerHome).repositories
+        .filter((repository) => repository.enabled !== false);
+      const updated = repositories.map((repository) => ({
+        repository: {
+          repoId: repository.repoId,
+          name: repository.displayName,
+        },
+        policy: writeRepositoryAccessPolicy(ctx.controllerHome, repository.repoId, mode, 'user'),
+      }));
+      return result({
+        mode,
+        descriptor: accessModeDescriptor(mode),
+        scope: 'all_enabled_repositories',
+        storage: 'controllerHome',
+        updatedCount: updated.length,
+        repositories: updated,
+        reconnectRequired: false,
+        schemaRefreshRequired: false,
+        toolSchemaStable: true,
+        warning: mode === 'full_access'
+          ? 'Host-managed mode is active for every enabled repository. Normal work, including ordinary remote writes, follows the host AI permission model; destructive actions, outside-repository paths, and raw secrets retain hard gates.'
+          : 'Compatibility mode is stored for every enabled repository. Normal work still follows the host AI permission model; hard safety gates are unchanged.',
+      });
+    }
+
+    const repository = selected(ctx, args);
+    const policy = writeRepositoryAccessPolicy(ctx.controllerHome, repository.repoId, mode, 'user');
+    return result({
+      repository: {
+        repoId: repository.repoId,
+        name: repository.displayName,
+      },
+      policy,
+      descriptor: accessModeDescriptor(policy.mode),
+      scope: 'repository',
+      storage: 'controllerHome',
+      reconnectRequired: false,
+      schemaRefreshRequired: false,
+      toolSchemaStable: true,
+      warning: mode === 'full_access'
+        ? 'Host-managed mode is active. Normal work, including ordinary remote writes, follows the host AI permission model; destructive actions, outside-repository paths, and raw secrets retain hard gates.'
+        : 'Compatibility mode is stored. Normal work still follows the host AI permission model; hard safety gates are unchanged.',
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return result({
+      error: {
+        code: message.includes(':') ? message.slice(0, message.indexOf(':')) : 'ACCESS_POLICY_FAILED',
+        message,
+      },
+    }, true);
+  }
+}