@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/control-plane/execution/work-verification-snapshot.ts

@@ -5,7 +5,9 @@ import {
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   readdirSync,
+  rmdirSync,
   rmSync,
   statSync,
   symlinkSync,
@@ -18,7 +20,7 @@ import { globMatches, normalizeMcpRelativePath } from '../../../cli/mcp/paths';
 import { sanitizeFileComponent } from '../../shared/json-files';
 
 const STALE_SNAPSHOT_MS = 6 * 60 * 60_000;
-const SNAPSHOT_MARKER = '.forge-work-verification-snapshot.json';
+const SNAPSHOT_MARKER = '.ai/harness/controller/work-verification-snapshot.json';
 
 export interface WorkVerificationSnapshotScope {
   workId: string;
@@ -91,11 +93,28 @@ function cloneHead(sourceRoot: string, targetRoot: string, head: string): void {
   git(targetRoot, ['checkout', '--detach', '--quiet', head]);
 }
 
+function pruneEmptySnapshotParents(targetRoot: string, targetPath: string): void {
+  const boundary = resolve(targetRoot);
+  let current = dirname(resolve(targetPath));
+  while (current !== boundary) {
+    try {
+      if (readdirSync(current).length > 0) return;
+      rmdirSync(current);
+    } catch {
+      return;
+    }
+    current = dirname(current);
+  }
+}
+
 function overlayPath(sourceRoot: string, targetRoot: string, relativePath: string): void {
   const source = resolve(sourceRoot, relativePath);
   const target = resolve(targetRoot, relativePath);
   rmSync(target, { recursive: true, force: true });
-  if (!existsSync(source)) return;
+  if (!existsSync(source)) {
+    pruneEmptySnapshotParents(targetRoot, target);
+    return;
+  }
   mkdirSync(dirname(target), { recursive: true });
   const stat = lstatSync(source);
   if (stat.isSymbolicLink()) {
@@ -105,11 +124,69 @@ function overlayPath(sourceRoot: string, targetRoot: string, relativePath: strin
   cpSync(source, target, { recursive: stat.isDirectory(), dereference: false, force: true, preserveTimestamps: true });
 }
 
-function linkIgnoredNodeModules(sourceRoot: string, targetRoot: string): void {
-  const source = join(sourceRoot, 'node_modules');
+const DEPENDENCY_LOCK_FILES = ['bun.lock', 'bun.lockb', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'] as const;
+const DEPENDENCY_CONFIG_FILES = ['pnpm-workspace.yaml', 'bunfig.toml', '.npmrc', '.yarnrc.yml'] as const;
+const DEPENDENCY_METADATA_NAMES = ['package.json', ...DEPENDENCY_LOCK_FILES, ...DEPENDENCY_CONFIG_FILES] as const;
+
+function isDependencyMetadataPath(path: string): boolean {
+  const name = path.split('/').pop() ?? path;
+  return DEPENDENCY_METADATA_NAMES.some((candidate) => candidate === name);
+}
+
+function hasUntrackedDependencyMetadata(root: string): boolean {
+  return nulPaths(git(root, ['ls-files', '--others', '--exclude-standard', '-z'])).some(isDependencyMetadataPath);
+}
+
+function dependencyMetadataDigest(root: string): string | undefined {
+  if (!existsSync(join(root, 'package.json'))) return undefined;
+  const rootLock = DEPENDENCY_LOCK_FILES.find((name) => existsSync(join(root, name)));
+  if (!rootLock) return undefined;
+  const pathspecs = DEPENDENCY_METADATA_NAMES.flatMap((name) => [name, `:(glob)**/${name}`]);
+  const tracked = nulPaths(git(root, ['ls-files', '-z', '--', ...pathspecs]));
+  const files = [...new Set(tracked)].sort();
+  if (!files.includes('package.json') || !files.includes(rootLock)) return undefined;
+  const hash = createHash('sha256');
+  for (const path of files) {
+    hash.update(path);
+    hash.update('\0');
+    hash.update(readFileSync(join(root, path)));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function primaryWorktreeRoot(sourceRoot: string): string | undefined {
+  const commonDirValue = git(sourceRoot, ['rev-parse', '--git-common-dir']).toString('utf8').trim();
+  if (!commonDirValue) return undefined;
+  const commonDir = resolve(sourceRoot, commonDirValue);
+  const candidate = dirname(commonDir);
+  if (resolve(candidate) === resolve(sourceRoot)) return undefined;
+  if (!existsSync(join(candidate, '.git'))) return undefined;
+  return candidate;
+}
+
+function linkIgnoredNodeModules(sourceRoot: string, targetRoot: string, dirtyPaths: readonly string[]): void {
+  let source = join(sourceRoot, 'node_modules');
   const target = join(targetRoot, 'node_modules');
-  if (!existsSync(source) || existsSync(target)) return;
-  const ignored = spawnSync('git', ['-C', sourceRoot, 'check-ignore', '--quiet', '--', 'node_modules'], { stdio: 'ignore', timeout: 10_000 });
+  if (existsSync(target)) return;
+  if (!existsSync(source)) {
+    if (dirtyPaths.some(isDependencyMetadataPath)) return;
+    const primaryRoot = primaryWorktreeRoot(sourceRoot);
+    if (!primaryRoot) return;
+    const primaryNodeModules = join(primaryRoot, 'node_modules');
+    if (!existsSync(primaryNodeModules) || hasUntrackedDependencyMetadata(primaryRoot)) return;
+    const sourceDigest = dependencyMetadataDigest(sourceRoot);
+    const primaryDigest = dependencyMetadataDigest(primaryRoot);
+    if (!sourceDigest || sourceDigest !== primaryDigest) return;
+    source = primaryNodeModules;
+  }
+  // An existing managed-worktree node_modules may itself be a symlink. Git
+  // rejects child pathspecs through symlinks, while an absent node_modules
+  // needs a virtual child path so directory-only ignore rules still match.
+  const ignoreProbe = existsSync(join(sourceRoot, 'node_modules'))
+    ? 'node_modules'
+    : 'node_modules/.forge-verification-probe';
+  const ignored = spawnSync('git', ['-C', sourceRoot, 'check-ignore', '--quiet', '--', ignoreProbe], { stdio: 'ignore', timeout: 10_000 });
   if (ignored.status !== 0) return;
   try {
     symlinkSync(source, target, process.platform === 'win32' ? 'junction' : 'dir');
@@ -136,18 +213,18 @@ export function materializeWorkVerificationSnapshot(input: {
       excludedPaths.push(path);
       continue;
     }
-    if (input.scope.allowedPaths.length > 0 && matchesAny(input.scope.allowedPaths, path)) {
+    if (input.scope.allowedPaths.length === 0 || matchesAny(input.scope.allowedPaths, path)) {
       includedPaths.push(path);
       continue;
     }
-    throw new Error(`WORK_VERIFICATION_PATH_OWNERSHIP_AMBIGUOUS: ${path} is dirty but is neither allowed nor forbidden for ${input.scope.workId}`);
+    throw new Error(`WORK_VERIFICATION_PATH_OWNERSHIP_AMBIGUOUS: ${path} is dirty but is outside the allowed path fence for ${input.scope.workId}`);
   }
 
   const root = snapshotRoot(input.controllerHome, input.repoId, input.scope.workId);
   try {
     cloneHead(input.sourceRoot, root, sourceHead);
     for (const path of includedPaths) overlayPath(input.sourceRoot, root, path);
-    linkIgnoredNodeModules(input.sourceRoot, root);
+    linkIgnoredNodeModules(input.sourceRoot, root, dirtyPaths);
     const ownershipDigest = createHash('sha256').update(JSON.stringify({
       sourceHead,
       workId: input.scope.workId,
@@ -156,6 +233,7 @@ export function materializeWorkVerificationSnapshot(input: {
       allowedPaths: [...input.scope.allowedPaths].sort(),
       forbiddenPaths: [...input.scope.forbiddenPaths].sort(),
     })).digest('hex');
+    mkdirSync(dirname(join(root, SNAPSHOT_MARKER)), { recursive: true });
     writeFileSync(join(root, SNAPSHOT_MARKER), `${JSON.stringify({ schemaVersion: 1, ...input.scope, sourceHead, includedPaths, excludedPaths, ownershipDigest }, null, 2)}\n`);
     return { root, sourceHead, includedPaths, excludedPaths, ownershipDigest };
   } catch (error) {

package/src/runtime/control-plane/facade/capability-registry.ts

@@ -1,5 +1,5 @@
 import type { AssistantPluginManifest } from '../../plugins/types';
-import type { CapabilityDescriptor, CapabilityDomain, CapabilityGroupSummary, CapabilityOperationClass, CapabilityRisk, FacadeTool } from './types';
+import type { CapabilityDescriptor, CapabilityDomain, CapabilityExecutionSurface, CapabilityGroupSummary, CapabilityOperationClass, CapabilityRisk, FacadeTool } from './types';
 
 const CORE_CAPABILITIES: CapabilityDescriptor[] = [
   {
@@ -83,24 +83,14 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     summary: 'Diagnose and dry-run repair stuck jobs, stale projections, invalid check pollution, and worker unavailability without treating infrastructure failure as acceptance failure.',
   },
   {
-    capabilityId: 'controller.codex_delegation',
+    capabilityId: 'controller.external_controller',
     domain: 'controller',
     group: 'controller',
     operationClass: 'execute',
     risk: 'workspace_write',
     exposedVia: 'rh_work',
     schemaExposure: 'stable_static',
-    summary: 'Delegate bounded implementation work to Codex or Claude with context packs; workers return evidence and proposals but do not own final acceptance.',
-  },
-  {
-    capabilityId: 'controller.autonomous_goal_loop',
-    domain: 'controller',
-    group: 'controller',
-    operationClass: 'execute',
-    risk: 'workspace_write',
-    exposedVia: 'rh_work',
-    schemaExposure: 'stable_static',
-    summary: 'Advance daemon-owned goal contracts through deterministic policy, executor routing, verification, repair, and handoff.',
+    summary: 'Claim Work ownership and start an external Codex, Claude, or ChatGPT controller through controller_claim and launcher_start, with handoff decisions coordinated through rh_inbox; deprecated delegate is not an execution path.',
   },
   {
     capabilityId: 'controller.work_contract',
@@ -148,9 +138,9 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     group: 'browser',
     operationClass: 'execute',
     risk: 'unknown',
-    exposedVia: 'rh_work',
+    exposedVia: 'plugin_action_execute',
     schemaExposure: 'stable_static',
-    summary: 'Use typed browser target, snapshot, domain grant, and plugin actions when browser capability is configured.',
+    summary: 'Use typed HTTP(S) browser navigation, snapshot, and interaction actions through plugin_action_execute when browser capability is configured.',
   },
   {
     capabilityId: 'platform.ios',
@@ -158,9 +148,9 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     group: 'ios',
     operationClass: 'execute',
     risk: 'workspace_write',
-    exposedVia: 'rh_work',
+    exposedVia: 'plugin_action_execute',
     schemaExposure: 'stable_static',
-    summary: 'Use typed Xcode, simulator launch, screenshot, log, and smoke-test handlers when the local iOS toolchain is ready.',
+    summary: 'Use typed Xcode, simulator, screenshot, log, and smoke-review actions through plugin_action_execute when the local iOS toolchain is ready.',
   },
 ];
 
@@ -185,13 +175,16 @@ function domainFromPlugin(pluginId: string): CapabilityDomain {
   return 'plugin';
 }
 
-function exposedViaFromPluginAction(readOnly: boolean, risk: string): FacadeTool {
-  if (readOnly || risk === 'readonly') return 'rh_context';
-  return 'rh_work';
+function exposedViaFromPluginAction(_readOnly: boolean, _risk: string): CapabilityExecutionSurface {
+  // rh_context exposes schema/policy. plugin_action_execute is the sole action executor.
+  return 'plugin_action_execute';
 }
 
-export function pluginCapabilities(manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor[] {
-  return manifests.flatMap((manifest) => manifest.actions.map((action) => ({
+function pluginCapabilityDescriptor(
+  manifest: AssistantPluginManifest,
+  action: AssistantPluginManifest['actions'][number],
+): CapabilityDescriptor {
+  return {
     capabilityId: `plugin.${manifest.pluginId}.${action.actionId}`,
     domain: domainFromPlugin(manifest.pluginId),
     group: manifest.pluginId === 'browser' ? 'browser' : 'plugin',
@@ -200,7 +193,11 @@ export function pluginCapabilities(manifests: readonly AssistantPluginManifest[]
     exposedVia: exposedViaFromPluginAction(action.readOnly, action.risk),
     schemaExposure: 'plugin_manifest',
     summary: `${manifest.displayName}: ${action.title}. ${action.description}`,
-  } satisfies CapabilityDescriptor)));
+  } satisfies CapabilityDescriptor;
+}
+
+export function pluginCapabilities(manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor[] {
+  return manifests.flatMap((manifest) => manifest.actions.map((action) => pluginCapabilityDescriptor(manifest, action)));
 }
 
 export function listCapabilityDescriptors(manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor[] {
@@ -209,6 +206,97 @@ export function listCapabilityDescriptors(manifests: readonly AssistantPluginMan
   return [...byId.values()].sort((a, b) => a.capabilityId.localeCompare(b.capabilityId));
 }
 
+export interface CapabilitySearchMatch {
+  capabilityId: string;
+  score: number;
+  matchedTerms: string[];
+  descriptor: CapabilityDescriptor;
+}
+
+function normalizedCapabilityText(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[_./:-]+/g, ' ')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+function capabilityIntentTokens(query: string): string[] {
+  return [...new Set(normalizedCapabilityText(query).split(' ').filter((token) => token.length >= 2))];
+}
+
+function intentBoosts(query: string, capabilityId: string): Array<{ label: string; score: number }> {
+  const normalized = normalizedCapabilityText(query);
+  const boosts: Array<{ label: string; score: number }> = [];
+  const appleDevelopmentIntent = /\b(xcode|provision|provisioning|signing|developer account|apple developer)\b/.test(normalized);
+  if (appleDevelopmentIntent) {
+    if (capabilityId === 'platform.ios') boosts.push({ label: 'apple-development', score: 90 });
+    if (capabilityId.startsWith('plugin.ios.')) boosts.push({ label: 'apple-development', score: 72 });
+    if (capabilityId === 'plugin.app_store_connect.auth_status') boosts.push({ label: 'apple-development', score: 88 });
+    else if (capabilityId === 'plugin.app_store_connect.configure') boosts.push({ label: 'apple-development', score: 82 });
+    else if (capabilityId.startsWith('plugin.app_store_connect.')) boosts.push({ label: 'apple-development', score: 28 });
+    if (capabilityId === 'plugin.desktop_operator.desktop_session_open') boosts.push({ label: 'xcode-desktop-fallback', score: 86 });
+    else if (capabilityId === 'plugin.desktop_operator.desktop_observe') boosts.push({ label: 'xcode-desktop-fallback', score: 78 });
+    else if (capabilityId === 'plugin.desktop_operator.desktop_press') boosts.push({ label: 'xcode-desktop-fallback', score: 74 });
+    else if (capabilityId.startsWith('plugin.desktop_operator.')) boosts.push({ label: 'xcode-desktop-fallback', score: 22 });
+  }
+
+  const browserLoginIntent = normalized.includes('browser')
+    && /\b(login|log in|signin|sign in|auth|authentication|session)\b/.test(normalized);
+  if (browserLoginIntent) {
+    if (capabilityId === 'plugin.browser') boosts.push({ label: 'browser-auth', score: 90 });
+    else if (capabilityId.startsWith('plugin.browser.')) boosts.push({ label: 'browser-auth', score: 62 });
+    if (capabilityId === 'plugin.desktop_operator.desktop_session_open') boosts.push({ label: 'browser-desktop-fallback', score: 70 });
+    else if (capabilityId === 'plugin.desktop_operator.desktop_observe') boosts.push({ label: 'browser-desktop-fallback', score: 62 });
+    else if (capabilityId.startsWith('plugin.desktop_operator.')) boosts.push({ label: 'browser-desktop-fallback', score: 18 });
+  }
+  return boosts;
+}
+
+export function searchCapabilityDescriptors(
+  query: string,
+  manifests: readonly AssistantPluginManifest[] = [],
+  limit = 12,
+): CapabilitySearchMatch[] {
+  const normalizedQuery = normalizedCapabilityText(query);
+  if (!normalizedQuery) return [];
+  const tokens = capabilityIntentTokens(query);
+  const boundedLimit = Math.max(1, Math.min(24, Math.floor(limit)));
+
+  return listCapabilityDescriptors(manifests)
+    .map((descriptor): CapabilitySearchMatch | undefined => {
+      const haystack = normalizedCapabilityText([
+        descriptor.capabilityId,
+        descriptor.summary,
+        descriptor.group,
+        descriptor.domain,
+        descriptor.operationClass,
+        descriptor.exposedVia,
+      ].join(' '));
+      let score = haystack.includes(normalizedQuery) ? 48 : 0;
+      const matchedTerms = new Set<string>();
+      for (const token of tokens) {
+        if (!haystack.includes(token)) continue;
+        matchedTerms.add(token);
+        score += descriptor.capabilityId.toLowerCase().includes(token) ? 12 : 5;
+      }
+      for (const boost of intentBoosts(query, descriptor.capabilityId)) {
+        score += boost.score;
+        matchedTerms.add(boost.label);
+      }
+      if (score <= 0) return undefined;
+      return {
+        capabilityId: descriptor.capabilityId,
+        score,
+        matchedTerms: [...matchedTerms].sort(),
+        descriptor,
+      };
+    })
+    .filter((entry): entry is CapabilitySearchMatch => Boolean(entry))
+    .sort((a, b) => b.score - a.score || a.capabilityId.localeCompare(b.capabilityId))
+    .slice(0, boundedLimit);
+}
+
 export function summarizeCapabilityGroups(manifests: readonly AssistantPluginManifest[] = []): CapabilityGroupSummary[] {
   const grouped = new Map<CapabilityDescriptor['group'], CapabilityDescriptor[]>();
   for (const descriptor of listCapabilityDescriptors(manifests)) {
@@ -222,7 +310,8 @@ export function summarizeCapabilityGroups(manifests: readonly AssistantPluginMan
       group,
       capabilityCount: entries.length,
       domains: [...new Set(entries.map((entry) => entry.domain))].sort(),
-      facadeTools: [...new Set(entries.map((entry) => entry.exposedVia))].sort(),
+      executionSurfaces: [...new Set(entries.map((entry) => entry.exposedVia))].sort(),
+      facadeTools: [...new Set(entries.map((entry) => entry.exposedVia).filter((surface): surface is FacadeTool => surface.startsWith('rh_')))].sort(),
       operationClasses: [...new Set(entries.map((entry) => entry.operationClass))].sort(),
       risks: [...new Set(entries.map((entry) => entry.risk))].sort(),
       schemaExposures: [...new Set(entries.map((entry) => entry.schemaExposure))].sort(),
@@ -257,6 +346,12 @@ export function getPluginActionCapabilitySchema(
         scopes: [...action.scopes],
         resourceClaims: structuredClone(action.resourceClaims),
         argumentsSchema: structuredClone(action.argumentsSchema),
+        authorizationReuse: action.confirmation === 'authorization'
+          ? {
+              mode: 'exact_target_persistent_when_adapter_supported',
+              hostPermissionBoundary: 'Tool invocation permission remains host-managed; reusable Forge grants never bypass strong_confirmation or destructive gates.',
+            }
+          : { mode: 'not_reusable' },
         executeWith: 'plugin_action_execute',
       };
     }
@@ -265,5 +360,14 @@ export function getPluginActionCapabilitySchema(
 }
 
 export function getCapabilityDescriptor(capabilityId: string, manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor | undefined {
-  return listCapabilityDescriptors(manifests).find((descriptor) => descriptor.capabilityId === capabilityId);
+  const core = CORE_CAPABILITIES.find((descriptor) => descriptor.capabilityId === capabilityId);
+  if (core) return core;
+  for (const manifest of manifests) {
+    for (const action of manifest.actions) {
+      if (`plugin.${manifest.pluginId}.${action.actionId}` === capabilityId) {
+        return pluginCapabilityDescriptor(manifest, action);
+      }
+    }
+  }
+  return undefined;
 }