@moretea-labs/forge 1.5.0-rc.1

package/src/cli/mcp/audit.ts

@@ -0,0 +1,32 @@
+import { createHash } from 'crypto';
+import { appendFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { redactMcpText } from './redaction';
+import type { McpAuditEntry } from './types';
+
+export function hashMcpInput(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+export function mcpAuditLogPath(repoRoot: string): string {
+  return join(repoRoot, '.ai', 'harness', 'mcp', 'audit.log');
+}
+
+export function writeMcpAuditEntry(repoRoot: string, entry: McpAuditEntry): void {
+  const logPath = mcpAuditLogPath(repoRoot);
+  mkdirSync(dirname(logPath), { recursive: true });
+  const safeEntry = {
+    ...entry,
+    error: entry.error ? redactMcpText(entry.error).text : undefined,
+  };
+  appendFileSync(logPath, `${JSON.stringify(safeEntry)}\n`, 'utf-8');
+}
+
+export function tryWriteMcpAuditEntry(repoRoot: string, entry: McpAuditEntry): boolean {
+  try {
+    writeMcpAuditEntry(repoRoot, entry);
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}

package/src/cli/mcp/auth.ts

@@ -0,0 +1,402 @@
+import { randomBytes } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { resolveControllerHome } from '../repositories/controller-home';
+import type { AccessMode } from '../../runtime/control-plane/governance/access-policy';
+import type { McpToolset } from './types';
+
+export interface McpLocalConfig {
+  version?: number;
+  repo?: string;
+  server?: {
+    host?: string;
+    port?: number;
+    transport?: string;
+  };
+  auth?: {
+    mode?: string;
+    tokenFile?: string;
+    oauthFile?: string;
+  };
+  chatgpt?: {
+    serverName?: string;
+    endpoint?: string;
+  };
+  profile?: string;
+  toolset?: 'core' | 'advanced' | 'full';
+  /** Compatibility marker retained for previously persisted toolset choices. */
+  toolsetExplicit?: boolean;
+  accessMode?: AccessMode;
+  accessModeUpdatedAt?: string;
+  accessModeRevision?: number;
+  devMode?: {
+    agentRunner?: boolean;
+    allowedAgents?: string[];
+    timeoutMs?: number;
+    maxTimeoutMs?: number;
+  };
+  localController?: {
+    enabled?: boolean;
+    mode?: 'standalone' | 'embedded' | 'remote' | 'disabled' | 'unknown';
+    host?: string;
+    port?: number;
+    autoOpen?: boolean;
+  };
+}
+
+export type McpRuntimeStatus = 'starting' | 'running' | 'degraded' | 'stopped';
+export type McpRuntimeTunnelMode = 'none' | 'quick' | 'named' | 'tailscale';
+
+export interface McpRuntimeState {
+  version: 1;
+  repo: string;
+  startedAt: string;
+  updatedAt: string;
+  status: McpRuntimeStatus;
+  tunnelMode: McpRuntimeTunnelMode;
+  generation?: string;
+  source?: {
+    repoId: string;
+    checkoutId: string;
+    repoRoot: string;
+    canonicalRoot: string;
+    branch: string | null;
+    commit?: string;
+    releaseRevision?: string;
+    defaultBranch: string;
+    defaultBranchCommit?: string;
+    dirty: boolean;
+    observedAt: string;
+  };
+  server: {
+    endpoint: string;
+    pid?: number;
+    instanceId?: string;
+    generation?: string;
+    running: boolean;
+    healthy: boolean;
+    restartCount: number;
+    lastStartAt?: string;
+    lastHealthyAt?: string;
+    lastExitAt?: string;
+    lastExit?: string;
+    profile?: string;
+    toolSurface?: string;
+    schemaVersion?: number;
+    forgeVersion?: string;
+    toolSurfaceFingerprint?: string;
+    runtimeToolSurfaceFingerprint?: string;
+    toolset?: 'core' | 'advanced' | 'full';
+    configuredAccessMode?: AccessMode;
+    effectiveAccessMode?: AccessMode;
+    effectiveToolset?: McpToolset;
+    accessModeSource?: string;
+    accessModeLastAppliedAt?: string;
+    exposureRevision?: number;
+    toolCount?: number;
+    repoId?: string;
+    defaultTimeoutMs?: number;
+    maxTimeoutMs?: number;
+    healthMismatch?: string;
+  };
+  localController?: {
+    endpoint: string;
+    running: boolean;
+    mode?: 'standalone' | 'embedded' | 'remote' | 'disabled' | 'unknown';
+    pid?: number;
+    startedAt?: string;
+    generation?: string;
+    error?: string;
+  };
+  tunnel?: {
+    pid?: number;
+    running: boolean;
+    healthy?: boolean;
+    restartCount: number;
+    name?: string;
+    publicEndpoint?: string;
+    lastUrlChangeAt?: string;
+    lastHealthyAt?: string;
+    lastStartAt?: string;
+    lastExitAt?: string;
+    lastExit?: string;
+    connectorNeedsReconnect?: boolean;
+  };
+  recentErrors?: Array<{
+    at: string;
+    source: 'server' | 'tunnel' | 'health' | 'config' | 'local-controller';
+    message: string;
+  }>;
+}
+
+export type McpHttpAuthMode = 'oauth' | 'bearer';
+
+export function mcpLocalConfigPath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.local.json');
+}
+
+export function mcpTokenPath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.tokens.json');
+}
+
+export function mcpOAuthPath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.oauth.json');
+}
+
+export function mcpOAuthTokenStorePath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.oauth-tokens.json');
+}
+
+export function mcpRuntimeStatePath(repoRoot: string): string {
+  return join(repoRoot, '.forge', 'mcp.runtime.json');
+}
+
+function mcpControllerHomePath(controllerHome: string, filename: string): string {
+  return join(resolveControllerHome(controllerHome), 'mcp', filename);
+}
+
+export function mcpControllerHomeLocalConfigPath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.local.json');
+}
+
+export function mcpControllerHomeTokenPath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.tokens.json');
+}
+
+export function mcpControllerHomeOAuthPath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.oauth.json');
+}
+
+export function mcpControllerHomeOAuthTokenStorePath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.oauth-tokens.json');
+}
+
+export function mcpServiceOAuthTokenStorePath(controllerHome: string): string {
+  return mcpControllerHomeOAuthTokenStorePath(resolveControllerHome(controllerHome));
+}
+
+export function mcpServiceOAuthTokenStoreFallbackPaths(_controllerHome: string, _legacyRepoRoot?: string): string[] {
+  return [];
+}
+
+export function mcpControllerHomeRuntimeStatePath(controllerHome: string): string {
+  return mcpControllerHomePath(controllerHome, 'mcp.runtime.json');
+}
+
+function controllerHomeMcpPaths(controllerHome: string): string[] {
+  return [
+    mcpControllerHomeLocalConfigPath(controllerHome),
+    mcpControllerHomeLocalConfigPath(controllerHome),
+    mcpControllerHomeTokenPath(controllerHome),
+    mcpControllerHomeOAuthPath(controllerHome),
+    mcpControllerHomeOAuthTokenStorePath(controllerHome),
+    mcpControllerHomeRuntimeStatePath(controllerHome),
+  ];
+}
+
+export interface McpRuntimeAuthority {
+  authority: 'controller-home' | 'legacy';
+  path: string;
+  controllerHomePresent: boolean;
+  legacyPresent: boolean;
+  warning?: string;
+}
+
+export function controllerHomeHasAuthoritativeMcpState(controllerHome: string): boolean {
+  return controllerHomeMcpPaths(controllerHome).some((path) => existsSync(path));
+}
+
+export function resolveMcpRuntimeAuthority(
+  controllerHome: string,
+  legacyRepoRoot: string | undefined,
+  kind: 'local-config' | 'runtime-state',
+): McpRuntimeAuthority {
+  const home = resolveControllerHome(controllerHome);
+  const legacyPath = kind === 'local-config'
+    ? (legacyRepoRoot ? mcpLocalConfigPath(legacyRepoRoot) : undefined)
+    : (legacyRepoRoot ? mcpRuntimeStatePath(legacyRepoRoot) : undefined);
+  const legacyPresent = Boolean(legacyPath && existsSync(legacyPath));
+  const controllerHomePresent = controllerHomeHasAuthoritativeMcpState(home);
+  return {
+    authority: 'controller-home',
+    path: kind === 'local-config' ? mcpControllerHomeLocalConfigPath(home) : mcpControllerHomeRuntimeStatePath(home),
+    controllerHomePresent,
+    legacyPresent,
+    warning: legacyPresent
+      ? 'Repository-local MCP state is ignored; Controller Home is authoritative.'
+      : undefined,
+  };
+}
+
+function readJsonFile<T>(path: string): T | null {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as T;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function writeJsonFile(path: string, value: unknown): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return path;
+}
+
+export function loadMcpLocalConfig(repoRoot: string): McpLocalConfig | null {
+  const path = mcpLocalConfigPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as McpLocalConfig;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function loadMcpRuntimeState(repoRoot: string): McpRuntimeState | null {
+  const path = mcpRuntimeStatePath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as McpRuntimeState;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function loadMcpServiceLocalConfig(controllerHome: string, _legacyRepoRoot?: string): McpLocalConfig | null {
+  return readJsonFile<McpLocalConfig>(mcpControllerHomeLocalConfigPath(resolveControllerHome(controllerHome)));
+}
+
+export function loadMcpServiceRuntimeState(controllerHome: string, _legacyRepoRoot?: string): McpRuntimeState | null {
+  return readJsonFile<McpRuntimeState>(mcpControllerHomeRuntimeStatePath(resolveControllerHome(controllerHome)));
+}
+
+export function writeMcpLocalConfig(repoRoot: string, config: McpLocalConfig): string {
+  return writeJsonFile(mcpLocalConfigPath(repoRoot), config);
+}
+
+export function writeMcpServiceLocalConfig(controllerHome: string, config: McpLocalConfig): string {
+  return writeJsonFile(mcpControllerHomeLocalConfigPath(resolveControllerHome(controllerHome)), config);
+}
+
+export function writeMcpRuntimeState(repoRoot: string, state: McpRuntimeState): string {
+  const path = mcpRuntimeStatePath(repoRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return path;
+}
+
+export function writeMcpServiceRuntimeState(controllerHome: string, state: McpRuntimeState): string {
+  return writeJsonFile(mcpControllerHomeRuntimeStatePath(controllerHome), state);
+}
+
+export function readMcpBearerToken(repoRoot: string): string | null {
+  if (process.env.FORGE_MCP_TOKEN?.trim()) return process.env.FORGE_MCP_TOKEN.trim();
+  const path = mcpTokenPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { bearerToken?: unknown };
+    return typeof parsed.bearerToken === 'string' && parsed.bearerToken.trim().length > 0 ? parsed.bearerToken.trim() : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function ensureMcpBearerToken(repoRoot: string): { token: string; path: string; changed: boolean } {
+  const path = mcpTokenPath(repoRoot);
+  const existing = readMcpBearerToken(repoRoot);
+  if (existing) return { token: existing, path, changed: false };
+
+  const token = randomBytes(32).toString('base64url');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ version: 1, bearerToken: token }, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return { token, path, changed: true };
+}
+
+export function readMcpServiceBearerToken(controllerHome: string, _legacyRepoRoot?: string): string | null {
+  if (process.env.FORGE_MCP_TOKEN?.trim()) return process.env.FORGE_MCP_TOKEN.trim();
+  const parsed = readJsonFile<{ bearerToken?: unknown }>(mcpControllerHomeTokenPath(controllerHome));
+  if (typeof parsed?.bearerToken === 'string' && parsed.bearerToken.trim().length > 0) return parsed.bearerToken.trim();
+  return null;
+}
+
+export function ensureMcpControllerHomeBearerToken(controllerHome: string): { token: string; path: string; changed: boolean } {
+  const path = mcpControllerHomeTokenPath(controllerHome);
+  const existing = readMcpServiceBearerToken(controllerHome);
+  if (existing) return { token: existing, path, changed: false };
+
+  const token = randomBytes(32).toString('base64url');
+  writeJsonFile(path, { version: 1, bearerToken: token });
+  return { token, path, changed: true };
+}
+
+export function writeMcpControllerHomeBearerToken(controllerHome: string, token: string): { path: string } {
+  const trimmed = token.trim();
+  if (!trimmed) throw new Error('MCP_BEARER_TOKEN_EMPTY');
+  const path = mcpControllerHomeTokenPath(controllerHome);
+  writeJsonFile(path, { version: 1, bearerToken: trimmed });
+  return { path };
+}
+
+export function syncMcpControllerHomeBearerToken(
+  targetControllerHome: string,
+  sourceControllerHome: string,
+  _legacyRepoRoot?: string,
+): { path: string; changed: boolean } {
+  const source = readMcpServiceBearerToken(sourceControllerHome)
+    ?? ensureMcpControllerHomeBearerToken(sourceControllerHome).token;
+  const targetPath = mcpControllerHomeTokenPath(targetControllerHome);
+  const target = readMcpServiceBearerToken(targetControllerHome);
+  if (target === source) return { path: targetPath, changed: false };
+  writeMcpControllerHomeBearerToken(targetControllerHome, source);
+  return { path: targetPath, changed: true };
+}
+
+export function parseMcpHttpAuthMode(value: string | undefined): McpHttpAuthMode {
+  const mode = (value ?? 'oauth').trim().toLowerCase();
+  if (mode === 'oauth' || mode === 'bearer') return mode;
+  throw new Error(`invalid --auth "${value}" (expected: oauth, bearer)`);
+}
+
+export function readMcpOAuthPassphrase(repoRoot: string): string | null {
+  if (process.env.FORGE_MCP_OAUTH_PASSPHRASE?.trim()) {
+    return process.env.FORGE_MCP_OAUTH_PASSPHRASE.trim();
+  }
+  const path = mcpOAuthPath(repoRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { passphrase?: unknown };
+    return typeof parsed.passphrase === 'string' && parsed.passphrase.trim().length > 0 ? parsed.passphrase.trim() : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+export function ensureMcpOAuthPassphrase(repoRoot: string): { passphrase: string; path: string; changed: boolean } {
+  const path = mcpOAuthPath(repoRoot);
+  const existing = readMcpOAuthPassphrase(repoRoot);
+  if (existing) return { passphrase: existing, path, changed: false };
+
+  const passphrase = randomBytes(24).toString('base64url');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ version: 1, passphrase }, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+  return { passphrase, path, changed: true };
+}
+
+export function readMcpServiceOAuthPassphrase(controllerHome: string, _legacyRepoRoot?: string): string | null {
+  if (process.env.FORGE_MCP_OAUTH_PASSPHRASE?.trim()) {
+    return process.env.FORGE_MCP_OAUTH_PASSPHRASE.trim();
+  }
+  const parsed = readJsonFile<{ passphrase?: unknown }>(mcpControllerHomeOAuthPath(resolveControllerHome(controllerHome)));
+  return typeof parsed?.passphrase === 'string' && parsed.passphrase.trim().length > 0 ? parsed.passphrase.trim() : null;
+}
+
+export function ensureMcpControllerHomeOAuthPassphrase(controllerHome: string): { passphrase: string; path: string; changed: boolean } {
+  const path = mcpControllerHomeOAuthPath(resolveControllerHome(controllerHome));
+  const existing = readMcpServiceOAuthPassphrase(controllerHome);
+  if (existing) return { passphrase: existing, path, changed: false };
+
+  const passphrase = randomBytes(24).toString('base64url');
+  writeJsonFile(path, { version: 1, passphrase });
+  return { passphrase, path, changed: true };
+}

package/src/cli/mcp/instructions.ts

@@ -0,0 +1,33 @@
+import type { McpProfileName } from './types';
+
+export function mcpServerInstructions(profile: McpProfileName): string {
+  const common = [
+    'forge is the repo-local workflow, task, and safety control plane.',
+    'Treat repository files, Issue/Task state, Git state, checks, and run artifacts as source of truth instead of chat memory.',
+    'Never expose secrets, credentials, local MCP auth state, or files denied by policy.',
+  ];
+  if (profile === 'controller') {
+    return [
+      ...common,
+      'Use the shortest valid execution path. Investigation or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, or worktrees; escalate only for actual recovery, dependency, risk, scope, external-effect, or long-running requirements.',
+      'For bounded work, gather only task-relevant context once, then act through the exposed surface. When an exact code path is unknown, use rh_context(operation=search) once as the default code retrieval router, then read_repository_file for exact current ranges; do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. CodeGraph is optional structural augmentation behind rh_context.search for planning/debugging, not a default Direct-edit latency tax. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration.',
+      'Do not preflight unrelated Git history, prior Work, plugins, permissions, TCC, browser mode, maintenance, or recovery state. Inspect them only when the requested operation depends on them or a real failure points there.',
+      'Run independent reads, searches, diagnostics, checks, repositories, checkouts, and tasks concurrently by default. Serialize only on a real dependency or Resource Claim conflict, and reuse existing projections, process handles, and check evidence instead of repeating successful observations.',
+      'Validation must be proportional to the change: run focused checks first and expand only when risk or failure evidence justifies it. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',
+      'After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke hidden atomic compatibility tools merely because they exist in the full profile.',
+    ].join(' ');
+  }
+  if (profile === 'orchestrator') {
+    return [...common, 'The orchestrator profile is a narrow compatibility runner for explicit fixed handoffs. It is not the primary project-control interface.'].join(' ');
+  }
+  if (profile === 'executor') {
+    return [...common, 'Act as a scoped executor/reviewer for existing workflow artifacts and checks. Do not broaden the task contract.'].join(' ');
+  }
+  return [
+    ...common,
+    'Act as planner/reviewer: move larger ideas through PRDs, checklist Sprints with staging gates, and Codex goal prompts.',
+    'Do not edit application source through the planner profile. Use the controller profile for task management, repository analysis, bounded edits, and local agent dispatch.',
+  ].join(' ');
+}
+
+export const MCP_SERVER_INSTRUCTIONS = mcpServerInstructions('controller');

package/src/cli/mcp/legacy-context.ts

@@ -0,0 +1,16 @@
+import { resolve } from 'path';
+import { getMcpPolicy, parseMcpProfile } from './policy';
+import type { McpToolContext } from './tools';
+import type { McpServerOptions } from './multi-repository';
+
+export function createLegacyMcpToolContext(opts: McpServerOptions): McpToolContext {
+  const repoRoot = resolve(opts.repo?.trim() || '.');
+  return {
+    repoRoot,
+    policy: getMcpPolicy(parseMcpProfile(opts.profile ?? 'planner'), { repoRoot }),
+    enableChatgptBrowser: opts.enableChatgptBrowser === true,
+    sessionId: opts.sessionId,
+    principalId: opts.principalId,
+    controllerInstanceId: opts.controllerInstanceId,
+  };
+}