@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/control-plane/goal-loop/handoff-packet.ts

@@ -0,0 +1,160 @@
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../../shared/json-files';
+import { redactProviderSummary } from './provider-registry';
+import type {
+  GoalContract,
+  GoalHandoffPacket,
+  GoalHandoffPacketStore,
+} from './types';
+
+export interface HandoffPacketStoreLocation {
+  controllerHome?: string;
+  repoId?: string;
+  root?: string;
+}
+
+export interface HandoffPacketStoreOptions extends HandoffPacketStoreLocation {
+  now?: () => string;
+}
+
+function nowIso(options: HandoffPacketStoreOptions): string {
+  return options.now?.() ?? new Date().toISOString();
+}
+
+export function handoffPacketRoot(location: HandoffPacketStoreLocation): string {
+  if (location.root) {
+    mkdirSync(location.root, { recursive: true });
+    return location.root;
+  }
+  if (!location.controllerHome || !location.repoId) {
+    throw new Error('handoff packet store requires either root or controllerHome + repoId');
+  }
+  const root = join(repositoryControllerRoot(location.controllerHome, location.repoId), 'goal-handoff-packets');
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+export function handoffPacketStorePath(location: HandoffPacketStoreLocation): string {
+  return join(handoffPacketRoot(location), 'index.json');
+}
+
+export function emptyHandoffPacketStore(updatedAt: string): GoalHandoffPacketStore {
+  return { schemaVersion: 1, updatedAt, packets: [] };
+}
+
+export function readHandoffPacketStore(options: HandoffPacketStoreOptions): GoalHandoffPacketStore {
+  return readJsonFile<GoalHandoffPacketStore>(
+    handoffPacketStorePath(options),
+    emptyHandoffPacketStore(nowIso(options)),
+  );
+}
+
+export function writeHandoffPacketStore(
+  options: HandoffPacketStoreOptions,
+  store: GoalHandoffPacketStore,
+): GoalHandoffPacketStore {
+  writeJsonAtomic(handoffPacketStorePath(options), store);
+  return store;
+}
+
+export interface CreateHandoffPacketInput {
+  goal: GoalContract;
+  blockers?: string[];
+  lastEvidence?: Array<{ title: string; summary?: string }>;
+  currentDiffSummary?: string;
+  nextSafeActions?: string[];
+  recommendedProvider?: string;
+  requiredUserDecision?: string;
+  exactToolCallsSuggested?: GoalHandoffPacket['exactToolCallsSuggested'];
+  completedSteps?: string[];
+}
+
+export function createGoalHandoffPacket(
+  options: HandoffPacketStoreOptions,
+  input: CreateHandoffPacketInput,
+): GoalHandoffPacket {
+  const at = nowIso(options);
+  const goal = input.goal;
+  const packetId = `pkt-${sanitizeFileComponent(goal.goalId).slice(0, 24)}-${randomUUID().slice(0, 8)}`;
+
+  const completedSteps =
+    input.completedSteps
+    ?? goal.transitionHistory
+      .filter((entry) => entry.to !== entry.from)
+      .map((entry) => `${entry.from}->${entry.to}: ${entry.reason}`)
+      .slice(-20);
+
+  const packet: GoalHandoffPacket = {
+    schemaVersion: 1,
+    packetId,
+    goalId: goal.goalId,
+    repoId: goal.repoId,
+    objective: goal.objective.slice(0, 2_000),
+    currentState: {
+      status: goal.status,
+      currentStep: goal.currentStep,
+      lastProviderId: goal.lastProviderId,
+      waitingReason: goal.waitingReason,
+    },
+    completedSteps: completedSteps.slice(0, 30),
+    blockers: (input.blockers ?? (goal.waitingReason ? [goal.waitingReason] : [])).slice(0, 20),
+    lastEvidence: (input.lastEvidence
+      ?? goal.artifacts.map((artifact) => ({
+        title: artifact.title,
+        summary: artifact.summary,
+      }))).slice(0, 20),
+    currentDiffSummary: input.currentDiffSummary?.slice(0, 1_000),
+    nextSafeActions: (input.nextSafeActions
+      ?? (goal.nextSafeAction ? [goal.nextSafeAction] : ['Review goal status', 'Approve or continue with an invokable provider']))
+      .slice(0, 15),
+    recommendedProvider: input.recommendedProvider ?? 'chatgpt_handoff',
+    requiredUserDecision: input.requiredUserDecision,
+    exactToolCallsSuggested: (input.exactToolCallsSuggested ?? [
+      {
+        tool: 'goal_status',
+        payload: { goal_id: goal.goalId },
+        risk: 'readonly',
+      },
+      {
+        tool: 'goal_continue',
+        payload: { goal_id: goal.goalId },
+        risk: 'workspace_write',
+      },
+    ]).slice(0, 10),
+    constraints: goal.constraints,
+    acceptanceCriteria: goal.acceptanceCriteria.slice(0, 20),
+    timestamp: at,
+    redacted: true,
+  };
+
+  // Defense-in-depth: never persist secret-like substrings.
+  const sanitized = redactProviderSummary(packet) as GoalHandoffPacket;
+  sanitized.redacted = true;
+
+  const store = readHandoffPacketStore(options);
+  store.packets = [sanitized, ...store.packets].slice(0, 100);
+  store.updatedAt = at;
+  writeHandoffPacketStore(options, store);
+  return sanitized;
+}
+
+export function getGoalHandoffPacket(
+  options: HandoffPacketStoreOptions,
+  packetId: string,
+): GoalHandoffPacket | undefined {
+  const id = sanitizeFileComponent(packetId);
+  return readHandoffPacketStore(options).packets.find((packet) => packet.packetId === id || packet.packetId === packetId);
+}
+
+export function listGoalHandoffPackets(
+  options: HandoffPacketStoreOptions & { goalId?: string; limit?: number },
+): GoalHandoffPacket[] {
+  let packets = readHandoffPacketStore(options).packets;
+  if (options.goalId) {
+    packets = packets.filter((packet) => packet.goalId === options.goalId);
+  }
+  return packets.slice(0, options.limit ?? 20);
+}

package/src/runtime/control-plane/goal-loop/index.ts

@@ -0,0 +1,13 @@
+export * from './types';
+export * from './goal-contract-store';
+export * from './provider-registry';
+export * from './executor-router';
+export * from './policy-gates';
+export * from './failure-taxonomy';
+export * from './handoff-packet';
+export * from './provider-dispatch';
+export * from './goal-loop-engine';
+export * from './config-types';
+export * from './config-store';
+export * from './local-tools';
+export * from './config-facade';

package/src/runtime/control-plane/goal-loop/local-tools.ts

@@ -0,0 +1,290 @@
+import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { homedir } from 'os';
+import { join } from 'path';
+import {
+  isLocalToolEnabledInConfig,
+  readLocalToolConfig,
+  type GoalLoopConfigLocation,
+} from './config-store';
+import type { LocalToolDescriptor } from './config-types';
+
+export interface LocalToolProbeOptions {
+  configLocation?: GoalLoopConfigLocation;
+  env?: NodeJS.ProcessEnv;
+  skipExecutableProbe?: boolean;
+  /** Injected status for tests. */
+  mockTools?: Partial<Record<string, Partial<LocalToolDescriptor>>>;
+}
+
+const TOOL_META: Record<string, {
+  displayName: string;
+  command?: string;
+  capabilityTags: string[];
+  usedByWorkflows: string[];
+  versionArgs?: string[];
+}> = {
+  direct_edit: {
+    displayName: 'Direct Edit',
+    capabilityTags: ['code_patch', 'local_file_mutation'],
+    usedByWorkflows: ['source edit'],
+  },
+  codex_cli: {
+    displayName: 'Codex CLI',
+    command: 'codex',
+    capabilityTags: ['code_patch', 'code_review', 'tool_calling', 'local_file_mutation'],
+    usedByWorkflows: ['source edit', 'tests', 'repair'],
+    versionArgs: ['--version'],
+  },
+  claude_cli: {
+    displayName: 'Claude CLI',
+    command: 'claude',
+    capabilityTags: ['code_patch', 'code_review', 'long_context', 'local_file_mutation'],
+    usedByWorkflows: ['source edit', 'repair', 'planning'],
+    versionArgs: ['--version'],
+  },
+  grok_cli: {
+    displayName: 'Grok CLI',
+    command: 'grok',
+    capabilityTags: ['code_patch', 'code_review', 'tool_calling', 'long_context', 'local_file_mutation'],
+    usedByWorkflows: ['source edit', 'tests', 'repair', 'planning'],
+    versionArgs: ['--version'],
+  },
+  git: {
+    displayName: 'Git',
+    command: 'git',
+    capabilityTags: ['vcs'],
+    usedByWorkflows: ['source edit', 'GitHub issue sync', 'release workflow'],
+    versionArgs: ['--version'],
+  },
+  gh: {
+    displayName: 'GitHub CLI',
+    command: 'gh',
+    capabilityTags: ['github', 'cloud_agent'],
+    usedByWorkflows: ['GitHub issue sync', 'release workflow'],
+    versionArgs: ['--version'],
+  },
+  bun: {
+    displayName: 'Bun',
+    command: 'bun',
+    capabilityTags: ['tests', 'runtime'],
+    usedByWorkflows: ['tests'],
+    versionArgs: ['--version'],
+  },
+  npm: {
+    displayName: 'npm',
+    command: 'npm',
+    capabilityTags: ['tests', 'package_manager'],
+    usedByWorkflows: ['tests', 'release workflow'],
+    versionArgs: ['--version'],
+  },
+  xcodebuild: {
+    displayName: 'xcodebuild',
+    command: 'xcodebuild',
+    capabilityTags: ['ios'],
+    usedByWorkflows: ['iOS smoke review'],
+    versionArgs: ['-version'],
+  },
+  xcrun: {
+    displayName: 'xcrun',
+    command: 'xcrun',
+    capabilityTags: ['ios'],
+    usedByWorkflows: ['iOS smoke review'],
+    versionArgs: ['--version'],
+  },
+  simctl: {
+    displayName: 'simctl',
+    command: 'xcrun',
+    capabilityTags: ['ios', 'simulator'],
+    usedByWorkflows: ['iOS smoke review'],
+  },
+  playwright: {
+    displayName: 'Playwright / browser runtime',
+    command: 'npx',
+    capabilityTags: ['browser_automation'],
+    usedByWorkflows: ['browser automation'],
+  },
+  app_store_connect: {
+    displayName: 'App Store Connect adapter',
+    capabilityTags: ['release', 'ios'],
+    usedByWorkflows: ['release workflow'],
+  },
+  gmail_workspace: {
+    displayName: 'Gmail / Google Workspace',
+    capabilityTags: ['email', 'assistant'],
+    usedByWorkflows: ['assistant triage'],
+  },
+};
+
+function which(command: string, skip?: boolean): string | undefined {
+  if (skip) return undefined;
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('where', [command], { encoding: 'utf8', timeout: 2_000 });
+      return out.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+    }
+    const out = execFileSync('which', [command], { encoding: 'utf8', timeout: 2_000 }).trim();
+    return out || undefined;
+  } catch {
+    for (const prefix of [
+      '/usr/local/bin',
+      '/opt/homebrew/bin',
+      '/usr/bin',
+      join(homedir(), '.local', 'bin'),
+    ]) {
+      const candidate = join(prefix, command);
+      if (existsSync(candidate)) return candidate;
+    }
+    return undefined;
+  }
+}
+
+function versionOf(command: string, args: string[] | undefined, skip?: boolean): string | undefined {
+  if (skip || !args) return undefined;
+  try {
+    const out = execFileSync(command, args, { encoding: 'utf8', timeout: 3_000, maxBuffer: 8_000 });
+    return out.trim().split(/\r?\n/)[0]?.slice(0, 120);
+  } catch {
+    return undefined;
+  }
+}
+
+export function listLocalTools(options: LocalToolProbeOptions = {}): LocalToolDescriptor[] {
+  const config = options.configLocation
+    ? readLocalToolConfig(options.configLocation)
+    : { tools: [] as Array<{ toolId: string; enabled: boolean }> };
+  const at = new Date().toISOString();
+  const skip = options.skipExecutableProbe === true;
+
+  return Object.entries(TOOL_META).map(([toolId, meta]) => {
+    const mock = options.mockTools?.[toolId];
+    if (mock) {
+      const enabled = mock.enabled ?? isLocalToolEnabledInConfig(
+        options.configLocation ? readLocalToolConfig(options.configLocation) : { schemaVersion: 1, updatedAt: at, tools: [] },
+        toolId,
+      );
+      return {
+        toolId,
+        displayName: meta.displayName,
+        status: mock.status ?? (enabled ? 'detected' : 'disabled'),
+        enabled,
+        executablePath: mock.executablePath,
+        version: mock.version,
+        lastHealthCheckAt: mock.lastHealthCheckAt ?? at,
+        capabilityTags: meta.capabilityTags,
+        usedByWorkflows: meta.usedByWorkflows,
+        summary: mock.summary ?? meta.displayName,
+        healthOk: mock.healthOk ?? true,
+        lastErrorSummary: mock.lastErrorSummary,
+      };
+    }
+
+    const enabled = options.configLocation
+      ? isLocalToolEnabledInConfig(readLocalToolConfig(options.configLocation), toolId)
+      : true;
+
+    if (toolId === 'direct_edit') {
+      return {
+        toolId,
+        displayName: meta.displayName,
+        status: enabled ? 'detected' : 'disabled',
+        enabled,
+        lastHealthCheckAt: at,
+        capabilityTags: meta.capabilityTags,
+        usedByWorkflows: meta.usedByWorkflows,
+        summary: enabled
+          ? 'Bounded direct edit applied by forge.'
+          : 'Direct edit disabled by configuration.',
+        healthOk: enabled,
+      };
+    }
+
+    if (toolId === 'app_store_connect' || toolId === 'gmail_workspace') {
+      return {
+        toolId,
+        displayName: meta.displayName,
+        status: enabled ? 'detected' : 'disabled',
+        enabled,
+        lastHealthCheckAt: at,
+        capabilityTags: meta.capabilityTags,
+        usedByWorkflows: meta.usedByWorkflows,
+        summary: enabled
+          ? `${meta.displayName} adapter is managed via plugin configuration (no raw secrets here).`
+          : `${meta.displayName} disabled by configuration.`,
+        healthOk: enabled,
+      };
+    }
+
+    if (toolId === 'simctl') {
+      const path = which('xcrun', skip);
+      const detected = Boolean(path);
+      let status: LocalToolDescriptor['status'] = !enabled ? 'disabled' : detected ? 'detected' : 'missing';
+      return {
+        toolId,
+        displayName: meta.displayName,
+        status,
+        enabled,
+        executablePath: path ? `${path} simctl` : undefined,
+        lastHealthCheckAt: at,
+        capabilityTags: meta.capabilityTags,
+        usedByWorkflows: meta.usedByWorkflows,
+        summary: !enabled
+          ? 'simctl disabled by configuration.'
+          : detected
+            ? 'xcrun simctl available for iOS simulator workflows.'
+            : 'xcrun/simctl not found on PATH.',
+        healthOk: enabled && detected,
+        lastErrorSummary: !detected && enabled ? 'SIMCTL_MISSING' : undefined,
+      };
+    }
+
+    if (toolId === 'playwright') {
+      // Bounded: do not run playwright install; just note npx availability.
+      const path = which('npx', skip) || which('node', skip);
+      const detected = Boolean(path);
+      return {
+        toolId,
+        displayName: meta.displayName,
+        status: !enabled ? 'disabled' : detected ? 'detected' : 'missing',
+        enabled,
+        executablePath: path,
+        lastHealthCheckAt: at,
+        capabilityTags: meta.capabilityTags,
+        usedByWorkflows: meta.usedByWorkflows,
+        summary: !enabled
+          ? 'Browser/Playwright tooling disabled by configuration.'
+          : detected
+            ? 'Node/npx present; browser plugin still owns target allowlists.'
+            : 'Node/npx not found; browser automation may be limited.',
+        healthOk: enabled && detected,
+      };
+    }
+
+    const command = meta.command!;
+    const path = which(command, skip);
+    const detected = Boolean(path);
+    const version = path ? versionOf(path, meta.versionArgs, skip) : undefined;
+    return {
+      toolId,
+      displayName: meta.displayName,
+      status: !enabled ? 'disabled' : detected ? 'detected' : 'missing',
+      enabled,
+      executablePath: path,
+      version,
+      lastHealthCheckAt: at,
+      capabilityTags: meta.capabilityTags,
+      usedByWorkflows: meta.usedByWorkflows,
+      summary: !enabled
+        ? `${meta.displayName} disabled by configuration.`
+        : detected
+          ? `${meta.displayName} detected${version ? ` (${version})` : ''}.`
+          : `${meta.displayName} not found on PATH.`,
+      healthOk: enabled && detected,
+      lastErrorSummary: !detected && enabled ? `${toolId.toUpperCase()}_MISSING` : undefined,
+    };
+  });
+}
+
+export function getLocalTool(toolId: string, options: LocalToolProbeOptions = {}): LocalToolDescriptor | undefined {
+  return listLocalTools(options).find((tool) => tool.toolId === toolId);
+}

package/src/runtime/control-plane/goal-loop/policy-gates.ts

@@ -0,0 +1,203 @@
+import type { ApprovalState, GoalConstraints } from './types';
+
+export type ExternalEffectKind =
+  | 'none'
+  | 'local_repo_write'
+  | 'workspace_write'
+  | 'destructive_file_change'
+  | 'external_write'
+  | 'email_send_or_delete'
+  | 'app_store_connect_write'
+  | 'browser_form_submit'
+  | 'push'
+  | 'release_or_publish'
+  | 'broad_refactor'
+  | 'secret_or_sensitive_path';
+
+export interface GoalPolicyGateInput {
+  effect: ExternalEffectKind;
+  constraints?: GoalConstraints;
+  approvalConfirmed?: boolean;
+  strongConfirmationText?: string;
+  expectedChangedFiles?: number;
+  expectedChangedLines?: number;
+  paths?: string[];
+  /** Broad refactor thresholds (defaults: 40 files / 2000 lines). */
+  broadRefactorFiles?: number;
+  broadRefactorLines?: number;
+}
+
+export interface GoalPolicyGateResult {
+  approvalState: ApprovalState;
+  allowed: boolean;
+  reason: string;
+  requiredConfirmationText?: string;
+  effect: ExternalEffectKind;
+}
+
+const SENSITIVE_PATH_PATTERNS = [
+  /(^|\/)\.env(\.|$)/i,
+  /(^|\/)secrets?\//i,
+  /(^|\/)_ops\//i,
+  /id_rsa|id_ed25519|\.pem$/i,
+  /credentials?\.json$/i,
+  /auth\.json$/i,
+];
+
+const STRONG_CONFIRMATION = 'confirm-destructive-or-external-effect';
+
+export function pathIsSensitive(path: string): boolean {
+  return SENSITIVE_PATH_PATTERNS.some((pattern) => pattern.test(path));
+}
+
+export function evaluateGoalPolicyGate(input: GoalPolicyGateInput): GoalPolicyGateResult {
+  const effect = input.effect;
+  const paths = input.paths ?? [];
+
+  if (paths.some(pathIsSensitive) || effect === 'secret_or_sensitive_path') {
+    return {
+      approvalState: 'blocked_by_policy',
+      allowed: false,
+      reason: 'Secret/config-sensitive paths cannot be mutated through the autonomous goal loop.',
+      effect: 'secret_or_sensitive_path',
+    };
+  }
+
+  if (effect === 'none') {
+    return {
+      approvalState: 'approval_not_required',
+      allowed: true,
+      reason: 'Readonly or policy-neutral operation.',
+      effect,
+    };
+  }
+
+  const requiresStrong =
+    effect === 'destructive_file_change'
+    || effect === 'external_write'
+    || effect === 'email_send_or_delete'
+    || effect === 'app_store_connect_write'
+    || effect === 'browser_form_submit'
+    || effect === 'push'
+    || effect === 'release_or_publish';
+
+  if (effect === 'push' && input.constraints?.allowPush !== true) {
+    return {
+      approvalState: 'blocked_by_policy',
+      allowed: false,
+      reason: 'Push is disabled by goal constraints; remote push requires explicit constraint + approval.',
+      effect,
+    };
+  }
+
+  if (
+    (effect === 'external_write' || effect === 'email_send_or_delete' || effect === 'app_store_connect_write')
+    && input.constraints?.allowExternalWrite !== true
+  ) {
+    return {
+      approvalState: 'strong_confirmation_required',
+      allowed: false,
+      reason: 'External writes require allowExternalWrite constraint and strong confirmation.',
+      requiredConfirmationText: STRONG_CONFIRMATION,
+      effect,
+    };
+  }
+
+  if (effect === 'destructive_file_change' && input.constraints?.allowDestructive !== true) {
+    return {
+      approvalState: 'strong_confirmation_required',
+      allowed: false,
+      reason: 'Destructive file changes require allowDestructive constraint and strong confirmation.',
+      requiredConfirmationText: STRONG_CONFIRMATION,
+      effect,
+    };
+  }
+
+  const fileThreshold = input.broadRefactorFiles ?? 40;
+  const lineThreshold = input.broadRefactorLines ?? 2_000;
+  const files = input.expectedChangedFiles ?? 0;
+  const lines = input.expectedChangedLines ?? 0;
+  if (effect === 'broad_refactor' || files > fileThreshold || lines > lineThreshold) {
+    if (input.approvalConfirmed && input.strongConfirmationText === STRONG_CONFIRMATION) {
+      return {
+        approvalState: 'approval_not_required',
+        allowed: true,
+        reason: 'Broad refactor authorized with strong confirmation.',
+        effect: 'broad_refactor',
+      };
+    }
+    return {
+      approvalState: 'strong_confirmation_required',
+      allowed: false,
+      reason: `Broad refactor exceeds threshold (files>${fileThreshold} or lines>${lineThreshold}) and requires strong confirmation.`,
+      requiredConfirmationText: STRONG_CONFIRMATION,
+      effect: 'broad_refactor',
+    };
+  }
+
+  if (requiresStrong) {
+    if (input.approvalConfirmed && input.strongConfirmationText === STRONG_CONFIRMATION) {
+      return {
+        approvalState: 'approval_not_required',
+        allowed: true,
+        reason: 'Strong confirmation provided for external/destructive effect.',
+        effect,
+      };
+    }
+    return {
+      approvalState: 'strong_confirmation_required',
+      allowed: false,
+      reason: 'Destructive or external side effects require strong confirmation.',
+      requiredConfirmationText: STRONG_CONFIRMATION,
+      effect,
+    };
+  }
+
+  if (effect === 'workspace_write' || effect === 'local_repo_write') {
+    if (input.approvalConfirmed) {
+      return {
+        approvalState: 'approval_not_required',
+        allowed: true,
+        reason: 'Workspace write authorized.',
+        effect,
+      };
+    }
+    // Autonomous/supervised goal loop may perform bounded workspace writes without per-step approval
+    // when not destructive/external. Callers still apply patches via forge.
+    return {
+      approvalState: 'approval_not_required',
+      allowed: true,
+      reason: 'Bounded local/workspace write allowed under goal-loop ownership.',
+      effect,
+    };
+  }
+
+  if (input.approvalConfirmed) {
+    return {
+      approvalState: 'approval_not_required',
+      allowed: true,
+      reason: 'Normal authorization confirmed.',
+      effect,
+    };
+  }
+
+  return {
+    approvalState: 'normal_authorization_required',
+    allowed: false,
+    reason: 'Side-effecting operation requires authorization.',
+    effect,
+  };
+}
+
+export function effectFromRisk(
+  risk: 'readonly' | 'local_repo_write' | 'workspace_write' | 'remote_write' | 'destructive' | 'raw_secret_config',
+  options: { externalWrite?: boolean; push?: boolean } = {},
+): ExternalEffectKind {
+  if (risk === 'raw_secret_config') return 'secret_or_sensitive_path';
+  if (risk === 'destructive') return 'destructive_file_change';
+  if (options.push) return 'push';
+  if (options.externalWrite || risk === 'remote_write') return 'external_write';
+  if (risk === 'workspace_write') return 'workspace_write';
+  if (risk === 'local_repo_write') return 'local_repo_write';
+  return 'none';
+}