@moretea-labs/forge 1.8.0 → 1.8.2

package/adapters/mcp/multi-repository.ts

@@ -2,8 +2,7 @@ import { loadMcpLocalConfig, loadMcpServiceLocalConfig } from './auth';
 import { getMcpPolicy, parseMcpProfile } from './policy';
 import { buildMcpToolDefinitions, callMcpTool, type CallToolResult, type McpToolContext, type McpToolDefinition } from './tool-mapping/tools';
 import { DEFAULT_AGENT_TIMEOUT_MS, MAX_AGENT_TIMEOUT_MS, normalizeAgentTimeoutMs } from '../../src/cli/controller/runtime-config';
-import type { McpAgentRunnerName, McpToolset } from './types';
-import { configuredControllerToolset } from './toolset-selection';
+import type { McpAgentRunnerName } from './types';
 import { realpathSync } from 'fs';
 import { resolve } from 'path';
 import { ensureRepoPreferredControllerHome } from '../../src/cli/repositories/controller-home';
@@ -28,10 +27,11 @@ export interface McpServerOptions {
   devRunnerAgents?: string;
   devRunnerTimeoutMs?: number;
   devRunnerMaxTimeoutMs?: number;
-  toolset?: McpToolset | string;
   sessionId?: string;
   principalId?: string;
   controllerType?: McpToolContext['controllerType'];
+  /** Request-scoped host conversation correlation, for example ChatGPT _meta["openai/session"]. */
+  hostConversationSessionId?: string;
   controllerInstanceId?: string;
   /** Canonical Runtime source authority. Internal Runtime MCP only; never an execution repository. */
   runtimeSourceRoot?: string;
@@ -40,25 +40,18 @@ export interface McpServerOptions {
 export interface MultiRepositoryMcpToolContext extends McpToolContext {
   controllerHome: string;
   explicitRepository?: RepositoryRecord;
-  toolset: McpToolset;
-  toolsetLocked: boolean;
+  toolset: 'full';
   runtimeSourceRoot?: string;
 }
 
 type ToolResult = CallToolResult;
 
 const EXECUTION_STORAGE_TOOLS = new Set([
-  'dispatch_task',
-  'launch_issue',
-  'dispatch_ready_tasks',
-  'retry_task_run',
-  'integrate_task_run',
   'begin_edit_session',
   'apply_edit_operations',
   'create_edit_savepoint',
   'rollback_edit_session',
   'finalize_edit_session',
-  'finish_edit_session',
   'verify_edit_session',
   'submit_local_bridge_job',
   'execute_local_bridge_job',
@@ -66,31 +59,10 @@ const EXECUTION_STORAGE_TOOLS = new Set([
 
 const REPOSITORY_LOCKED_TOOLS = new Set([
   ...EXECUTION_STORAGE_TOOLS,
-  'create_issue',
-  'update_issue',
-  'plan_issue',
-  'append_task',
-  'split_task',
-  'supersede_task',
-  'set_task_dependencies',
-  'update_task',
-  'record_task_verification',
-  'accept_verified_task',
-  'publish_issue_to_github',
-  'refresh_github_issue',
-  'close_github_issue',
   'configure_github_plugin',
 ]);
 
 
-export function parseMcpToolset(value: unknown, profile: string): McpToolset {
-  if (profile !== 'controller') return 'full';
-  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
-  if (!normalized) return 'advanced';
-  if (normalized === 'facade' || normalized === 'core' || normalized === 'advanced' || normalized === 'full') return normalized;
-  throw new Error(`invalid MCP toolset "${String(value)}" (expected: facade, core, advanced, or full)`);
-}
-
 function repositoryForExplicitPath(path: string, controllerHome: string): RepositoryRecord | undefined {
   const selectedPath = (() => {
     try { return realpathSync(path); } catch { return resolve(path); }
@@ -301,8 +273,7 @@ export function repositoryScopedToolArgs(
   // checkout after validating the authenticated principal instead of inheriting
   // the repository's currently active checkout.
   const workOwnedCheckoutResolution = [
-    'repository_command_preview',
-    'repository_command_execute',
+    'execute_command',
     'repository_safe_patch_apply',
   ].includes(name)
     && typeof input.work_id === 'string'
@@ -350,28 +321,19 @@ export function createMcpToolContext(opts: McpServerOptions): MultiRepositoryMcp
     : undefined;
   const policyRoot = explicitRepository?.canonicalRoot ?? controllerHome;
   const policy = runtimePolicy(policyRoot, { ...opts, controllerHome });
-  const config = policy.profile === 'controller'
-    ? loadMcpServiceLocalConfig(controllerHome, explicitRepository?.canonicalRoot)
-    : loadMcpLocalConfig(policyRoot);
-  const toolsetOverride = opts.toolset ?? process.env.FORGE_MCP_TOOLSET;
-  const configuredToolset = policy.profile === 'controller'
-    ? configuredControllerToolset(config)
-    : config?.toolset;
-  const toolset = parseMcpToolset(
-    toolsetOverride ?? configuredToolset,
-    policy.profile,
-  );
+  // All Forge capabilities share one public MCP tool registry.
+  // Host authorization remains independent of tool discovery.
   return {
     controllerHome,
     explicitRepository,
     repoRoot: policyRoot,
     policy,
-    toolset,
-    toolsetLocked: toolsetOverride !== undefined || configuredToolset !== undefined,
+    toolset: 'full',
     enableChatgptBrowser: opts.enableChatgptBrowser === true,
     sessionId: opts.sessionId,
     principalId: opts.principalId,
     controllerType: opts.controllerType,
+    hostConversationSessionId: opts.hostConversationSessionId,
     controllerInstanceId: opts.controllerInstanceId,
     runtimeSourceRoot: opts.runtimeSourceRoot,
   };
@@ -418,6 +380,7 @@ export async function callMultiRepositoryTool(
       controllerInstanceId: ctx.controllerInstanceId,
       repoId: repository.repoId,
       checkoutId: repository.activeCheckoutId,
+      publishedToolNames: ctx.publishedToolNames,
     };
     const invoke = async () => await callMcpTool(scopedContext, name, scopedArgs) as ToolResult;
     const result = REPOSITORY_LOCKED_TOOLS.has(name)

package/adapters/mcp/oauth.ts

@@ -22,6 +22,19 @@ interface TokenData {
   clients?: Record<string, OAuthClientInformationFull>;
 }
 
+export interface McpOAuthClientRetirementResult {
+  clientId: string;
+  clientRemoved: boolean;
+  accessTokensRevoked: number;
+  refreshTokensRevoked: number;
+  orphanRefreshTokensPruned: number;
+  changed: boolean;
+}
+
+export interface McpOAuthProviderClientRetirementResult extends McpOAuthClientRetirementResult {
+  authorizationCodesRevoked: number;
+}
+
 function nowSeconds(): number {
   return Math.floor(Date.now() / 1000);
 }
@@ -129,6 +142,50 @@ export class McpOAuthTokenStore implements OAuthRegisteredClientsStore {
     return full;
   }
 
+  retireClient(clientId: string): McpOAuthClientRetirementResult {
+    const normalizedClientId = clientId.trim();
+    if (!normalizedClientId) throw new Error('MCP_OAUTH_CLIENT_ID_REQUIRED');
+
+    const ownedAccessTokens = new Set<string>();
+    for (const [token, info] of this.accessTokens) {
+      if (info.clientId === normalizedClientId) ownedAccessTokens.add(token);
+    }
+
+    let refreshTokensRevoked = 0;
+    let orphanRefreshTokensPruned = 0;
+    for (const [refreshToken, accessToken] of this.refreshTokens) {
+      if (ownedAccessTokens.has(accessToken)) {
+        this.refreshTokens.delete(refreshToken);
+        refreshTokensRevoked += 1;
+        continue;
+      }
+      if (!this.accessTokens.has(accessToken)) {
+        this.refreshTokens.delete(refreshToken);
+        orphanRefreshTokensPruned += 1;
+      }
+    }
+
+    let accessTokensRevoked = 0;
+    for (const token of ownedAccessTokens) {
+      if (this.accessTokens.delete(token)) accessTokensRevoked += 1;
+    }
+    const clientRemoved = this.clients.delete(normalizedClientId);
+    const changed = clientRemoved
+      || accessTokensRevoked > 0
+      || refreshTokensRevoked > 0
+      || orphanRefreshTokensPruned > 0;
+    if (changed) this.flush();
+
+    return {
+      clientId: normalizedClientId,
+      clientRemoved,
+      accessTokensRevoked,
+      refreshTokensRevoked,
+      orphanRefreshTokensPruned,
+      changed,
+    };
+  }
+
   getAccessToken(token: string): AuthInfo | undefined {
     return this.accessTokens.get(token);
   }
@@ -217,6 +274,7 @@ export interface McpOAuthAuthorizationCodeDiagnostics {
 
 export interface McpOAuthProvider extends OAuthServerProvider {
   authorizationCodeDiagnostics(): McpOAuthAuthorizationCodeDiagnostics;
+  retireClient(clientId: string): McpOAuthProviderClientRetirementResult;
 }
 
 export interface McpOAuthProviderOptions {
@@ -296,6 +354,21 @@ export function createMcpOAuthProvider(
       };
     },
 
+    retireClient(clientId: string): McpOAuthProviderClientRetirementResult {
+      const normalizedClientId = clientId.trim();
+      if (!normalizedClientId) throw new Error('MCP_OAUTH_CLIENT_ID_REQUIRED');
+      let authorizationCodesRevoked = 0;
+      for (const [code, pending] of authCodes) {
+        if (pending.clientId === normalizedClientId && authCodes.delete(code)) {
+          authorizationCodesRevoked += 1;
+        }
+      }
+      return {
+        ...store.retireClient(normalizedClientId),
+        authorizationCodesRevoked,
+      };
+    },
+
     get clientsStore(): OAuthRegisteredClientsStore {
       return store;
     },

package/adapters/mcp/paths.ts

@@ -1,5 +1,6 @@
 import { existsSync, lstatSync, realpathSync } from 'fs';
 import { dirname, isAbsolute, resolve, sep } from 'path';
+import { DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH } from '../../packages/kernel/work/api/index';
 import type { McpPathDecision, McpPathIntent, McpPolicy } from './types';
 
 function toPosixPath(value: string): string {
@@ -104,7 +105,9 @@ export function resolveMcpPath(
   if (!normalized.ok || !normalized.relativePath) return normalized;
 
   const relativePath = normalized.relativePath;
-  if (anyDenyGlobMatches(policy.denyGlobs, relativePath)) {
+  const isControllerProjectEngineeringContract = policy.profile === 'controller'
+    && relativePath === DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH;
+  if (!isControllerProjectEngineeringContract && anyDenyGlobMatches(policy.denyGlobs, relativePath)) {
     return { ok: false, relativePath, reason: `path is denied by MCP policy: ${relativePath}` };
   }
 

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

@@ -0,0 +1,62 @@
+import { currentControllerInstanceId, startExecutionSession } from '../../../src/runtime/control-plane/execution/session-store';
+import { writeControllerResult } from '../../../src/runtime/evidence/result-store';
+
+const MAX_INLINE_DIRECT_RESULT_BYTES = 64 * 1024;
+
+export interface BoundedRuntimeResultScope {
+  controllerHome: string;
+  repoId?: string;
+  sessionId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+  workId?: string;
+}
+
+/**
+ * Mechanical transport bounding for runtime-aware MCP adapters. Large values
+ * are persisted through the existing Result Store; no lifecycle or semantic
+ * completion authority is introduced here.
+ */
+export function boundedRuntimeResult(
+  scope: BoundedRuntimeResultScope,
+  value: unknown,
+): { value: unknown; externalized: boolean } {
+  const serialized = JSON.stringify(value, null, 2);
+  if (typeof serialized !== 'string' || Buffer.byteLength(serialized, 'utf8') <= MAX_INLINE_DIRECT_RESULT_BYTES) {
+    return { value, externalized: false };
+  }
+  const controllerInstanceId = scope.controllerInstanceId?.trim() || currentControllerInstanceId();
+  const principalId = scope.principalId?.trim() || `controller-issued:${controllerInstanceId}`;
+  const session = startExecutionSession(scope.controllerHome, {
+    sessionId: scope.sessionId?.trim() || undefined,
+    principalId,
+    controllerInstanceId,
+    capabilitySnapshotVersion: 1,
+  });
+  const stored = writeControllerResult({
+    controllerHome: scope.controllerHome,
+    repoId: scope.repoId,
+    sessionId: session.sessionId,
+    principalId: session.principalId,
+    workId: scope.workId,
+    kind: 'generic',
+    value,
+  });
+  return {
+    externalized: true,
+    value: {
+      externalized: true,
+      truncated: true,
+      byteLength: stored.byteLength,
+      resultRef: stored.resultRef,
+      resultId: stored.resultId,
+      sessionId: session.sessionId,
+      preview: serialized.slice(0, 4_096),
+      detailPointer: {
+        tool: 'result_read',
+        arguments: { session_id: session.sessionId, result_ref: stored.resultRef, limit: 16 },
+      },
+      next: 'Use result_read or result_search with this session_id/result_ref for additional bounded detail.',
+    },
+  };
+}

package/adapters/mcp/runtime-gateway/cognition-settlement.ts

@@ -0,0 +1,201 @@
+import type { CallToolResult, McpToolDefinition } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { parseControllerLearningSignalDrafts, CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS } from '../../../src/runtime/context/automatic-learning';
+import {
+  persistDirectControllerLearning,
+  recordDirectControllerLearningFeedback,
+  type DirectControllerLearningFeedbackDraft,
+} from '../../../src/runtime/context/direct-controller-learning';
+import { selected } from './shared-adapter';
+
+export const COGNITION_SETTLEMENT_PROPERTY = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    work_id: {
+      type: 'string',
+      description: 'Optional selected Work. Forge derives reachable Work/Requirement/Project/Workspace scope and provenance; this is not caller-authored authority.',
+    },
+    learning_signals: {
+      type: 'array',
+      maxItems: CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS,
+      items: { type: 'object' },
+      description: 'Optional model-authored reusable learning using the same LearningSignal contract as rh_work learning_record.',
+    },
+    learning_feedback: {
+      type: 'array',
+      maxItems: 32,
+      items: { type: 'object' },
+      description: 'Optional model-authored used/rejected feedback using the same contract as rh_work learning_feedback.',
+    },
+  },
+  description: 'Optional bounded advisory cognition settlement for a meaningful successful tool outcome. It creates no lifecycle and grants no authority.',
+} as const;
+
+/**
+ * Cognition settlement is transport metadata shared by every Controller tool.
+ * The detailed semantic contract remains owned by the canonical learning parser/writer;
+ * keeping this envelope compact avoids duplicating that schema across every tools/list entry.
+ */
+export function injectCognitionSettlementFields(definition: McpToolDefinition): McpToolDefinition {
+  const schema = definition.inputSchema as {
+    type?: unknown;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+  };
+  if (!schema || schema.type !== 'object') return definition;
+  return {
+    ...definition,
+    inputSchema: {
+      ...schema,
+      properties: {
+        ...(schema.properties ?? {}),
+        cognition_settlement: COGNITION_SETTLEMENT_PROPERTY,
+      },
+    },
+  };
+}
+
+export interface CognitionSettlementReceipt {
+  recorded: boolean;
+  storedMemoryIds: string[];
+  observationIds: string[];
+}
+
+function parseFeedback(raw: unknown): DirectControllerLearningFeedbackDraft[] {
+  if (!Array.isArray(raw)) throw new Error('COGNITION_SETTLEMENT_FEEDBACK_INVALID');
+  if (raw.length === 0 || raw.length > 32) throw new Error('COGNITION_SETTLEMENT_FEEDBACK_ITEMS_INVALID');
+  return raw.map((rawItem, index) => {
+    if (!rawItem || typeof rawItem !== 'object' || Array.isArray(rawItem)) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_ITEM_INVALID: ${index}`);
+    }
+    const item = rawItem as Record<string, unknown>;
+    const memoryAddress = String(item.memory_address ?? '').trim();
+    const decision = String(item.decision ?? '').trim();
+    const reason = String(item.reason ?? '').trim();
+    const rejectionKind = typeof item.rejection_kind === 'string' ? item.rejection_kind.trim() : undefined;
+    if (!memoryAddress || !reason || !['used', 'rejected'].includes(decision)) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_ITEM_INVALID: ${index}`);
+    }
+    if (decision === 'rejected' && !['irrelevant', 'stale', 'contradicted'].includes(rejectionKind ?? '')) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_REJECTION_KIND_REQUIRED: ${index}`);
+    }
+    if (decision === 'used' && rejectionKind) {
+      throw new Error(`COGNITION_SETTLEMENT_FEEDBACK_REJECTION_KIND_UNEXPECTED: ${index}`);
+    }
+    return {
+      memoryAddress,
+      decision: decision as 'used' | 'rejected',
+      reason,
+      ...(rejectionKind ? { rejectionKind: rejectionKind as 'irrelevant' | 'stale' | 'contradicted' } : {}),
+    };
+  });
+}
+
+/** Mechanical settlement shared by ordinary successful MCP outcome boundaries. */
+export function settleCognitionEnvelope(
+  ctx: MultiRepositoryMcpToolContext,
+  args: Record<string, unknown>,
+): CognitionSettlementReceipt | undefined {
+  const raw = args.cognition_settlement;
+  if (raw === undefined) return undefined;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('COGNITION_SETTLEMENT_INVALID');
+  const envelope = raw as Record<string, unknown>;
+  const repository = selected(ctx, args);
+  const workId = typeof envelope.work_id === 'string' && envelope.work_id.trim()
+    ? envelope.work_id.trim()
+    : typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined;
+
+  const storedMemoryIds: string[] = [];
+  const observationIds: string[] = [];
+
+  if (envelope.learning_signals !== undefined) {
+    const signals = parseControllerLearningSignalDrafts(envelope.learning_signals);
+    if (!signals.length) throw new Error('COGNITION_SETTLEMENT_SIGNALS_REQUIRED');
+    const learning = persistDirectControllerLearning({
+      controllerHome: ctx.controllerHome,
+      repository,
+      signals,
+      principalId: ctx.principalId,
+      sessionId: ctx.sessionId,
+      controllerInstanceId: ctx.controllerInstanceId,
+      controllerType: ctx.controllerType,
+      workId,
+    });
+    storedMemoryIds.push(...learning.storedMemoryIds);
+  }
+
+  if (envelope.learning_feedback !== undefined) {
+    const recorded = recordDirectControllerLearningFeedback({
+      controllerHome: ctx.controllerHome,
+      repository,
+      feedback: parseFeedback(envelope.learning_feedback),
+      principalId: ctx.principalId,
+      sessionId: ctx.sessionId,
+      controllerInstanceId: ctx.controllerInstanceId,
+      workId,
+    });
+    observationIds.push(...recorded.observationIds);
+  }
+
+  return {
+    recorded: storedMemoryIds.length > 0 || observationIds.length > 0,
+    storedMemoryIds,
+    observationIds,
+  };
+}
+
+function attachSettlementMetadata(
+  outcome: CallToolResult,
+  metadata: unknown,
+  warning?: string,
+): CallToolResult {
+  const structured = outcome.structuredContent;
+  if (!structured || typeof structured !== 'object' || Array.isArray(structured)) return outcome;
+  const current = structured as Record<string, unknown>;
+  const currentWarnings = Array.isArray(current.warnings)
+    ? current.warnings.filter((item): item is string => typeof item === 'string')
+    : [];
+  const structuredContent = {
+    ...current,
+    cognitionSettlement: metadata,
+    ...(warning ? { warnings: [...currentWarnings, warning] } : {}),
+  };
+  return {
+    ...outcome,
+    structuredContent,
+    content: outcome.content.map((block, index) => index === 0 && block.type === 'text'
+      ? { ...block, text: JSON.stringify(structuredContent) }
+      : block),
+  };
+}
+
+/**
+ * Settle advisory cognition only after the primary tool outcome succeeded.
+ * A settlement defect must never turn an already-applied repository/process/external effect
+ * into a failed tool call that a model might dangerously retry. Explicit learning_record /
+ * learning_feedback calls remain normal first-class operations and keep their own errors.
+ */
+export function settleCognitionAfterTool(
+  ctx: MultiRepositoryMcpToolContext,
+  name: string,
+  args: Record<string, unknown>,
+  outcome: CallToolResult | undefined,
+): CallToolResult | undefined {
+  if (!outcome || outcome.isError || args.cognition_settlement === undefined) return outcome;
+  if (name === 'rh_work' && ['learning_record', 'learning_feedback'].includes(String(args.operation ?? ''))) {
+    return outcome;
+  }
+  try {
+    const receipt = settleCognitionEnvelope(ctx, args);
+    return receipt ? attachSettlementMetadata(outcome, receipt) : outcome;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)(?::|$)/.exec(message)?.[1] ?? 'COGNITION_SETTLEMENT_FAILED';
+    return attachSettlementMetadata(
+      outcome,
+      { recorded: false, error: { code, message } },
+      `COGNITION_SETTLEMENT_FAILED: ${message}`,
+    );
+  }
+}