@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/plugins/lightweight-action.ts

@@ -0,0 +1,153 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { resolveTrustedNodeExecutable } from '../shared/trusted-node-executable';
+import { startLightweightInternalProcess, waitForLightweightProcess } from '../execution/process-runtime/lightweight-managed';
+import type { ProcessHandle } from '../execution/process-runtime/types';
+import type { AssistantPluginActionRequest } from './types';
+
+interface LightweightPluginActionEnvelope {
+  schemaVersion: 1;
+  controllerHome: string;
+  repoId: string;
+  request: Omit<AssistantPluginActionRequest, 'signal'>;
+}
+
+function privateAtomicWrite(path: string, content: string): void {
+  mkdirSync(resolve(path, '..'), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+function envelopeBytes(controllerHome: string, repository: RepositoryRecord, request: AssistantPluginActionRequest): string {
+  const { signal: _signal, ...serializableRequest } = request;
+  const envelope: LightweightPluginActionEnvelope = {
+    schemaVersion: 1,
+    controllerHome,
+    repoId: repository.repoId,
+    request: serializableRequest,
+  };
+  return `${JSON.stringify(envelope)}\n`;
+}
+
+export interface LightweightPluginActionStart {
+  handle: ProcessHandle;
+  requestSha256: string;
+}
+
+export interface LightweightPluginActionRuntimeInvocation {
+  executable: string;
+  argsPrefix: string[];
+  identity: 'compiled_release_sidecar' | 'package_release_node' | 'source_node';
+}
+
+function trustedNodeExecutable(explicit?: string): string {
+  const executable = explicit?.trim() || resolveTrustedNodeExecutable().executable;
+  if (!executable) {
+    throw new Error('NODE_EXECUTABLE_UNAVAILABLE: typed plugin sidecar requires a bundled Runtime sidecar or trusted Node executable');
+  }
+  return executable;
+}
+
+export function resolveLightweightPluginActionRuntimeInvocation(options: {
+  releasePath?: string;
+  execPath?: string;
+  sourceDir?: string;
+  nodeExecutable?: string;
+} = {}): LightweightPluginActionRuntimeInvocation {
+  const releasePath = (options.releasePath ?? process.env.FORGE_RELEASE_PATH)?.trim();
+  if (releasePath) {
+    const releaseRoot = resolve(releasePath);
+    const compiledSidecar = join(releaseRoot, 'forge-plugin-action-sidecar');
+    if (existsSync(compiledSidecar)) {
+      return { executable: compiledSidecar, argsPrefix: [], identity: 'compiled_release_sidecar' };
+    }
+    const packageSidecar = join(releaseRoot, 'package', 'src', 'runtime', 'plugins', 'plugin-action-sidecar.ts');
+    const packageLoader = join(releaseRoot, 'package', 'src', 'runtime', 'shared', 'node-ts-loader.mjs');
+    if (existsSync(packageSidecar) && existsSync(packageLoader)) {
+      return {
+        executable: trustedNodeExecutable(options.nodeExecutable),
+        argsPrefix: ['--loader', packageLoader, packageSidecar],
+        identity: 'package_release_node',
+      };
+    }
+    throw new Error(`RUNTIME_PLUGIN_ACTION_SIDECAR_UNAVAILABLE: immutable Runtime release has no plugin action sidecar: ${releaseRoot}`);
+  }
+
+  const execPath = options.execPath ?? process.execPath;
+  const compiledSidecar = join(dirname(execPath), 'forge-plugin-action-sidecar');
+  if (existsSync(compiledSidecar)) {
+    return { executable: compiledSidecar, argsPrefix: [], identity: 'compiled_release_sidecar' };
+  }
+
+  const sourceDir = options.sourceDir ?? import.meta.dir;
+  const sourceSidecar = resolve(sourceDir, 'plugin-action-sidecar.ts');
+  const sourceLoader = resolve(sourceDir, '../shared/node-ts-loader.mjs');
+  if (existsSync(sourceSidecar) && existsSync(sourceLoader)) {
+    return {
+      executable: trustedNodeExecutable(options.nodeExecutable),
+      argsPrefix: ['--loader', sourceLoader, sourceSidecar],
+      identity: 'source_node',
+    };
+  }
+  throw new Error(`RUNTIME_PLUGIN_ACTION_SIDECAR_UNAVAILABLE: no runtime-owned plugin action sidecar or loader is available from ${sourceDir}`);
+}
+
+export async function startLightweightPluginAction(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  request: AssistantPluginActionRequest;
+  interactiveWaitMs?: number;
+  timeoutMs: number;
+}): Promise<LightweightPluginActionStart> {
+  const requestToken = createHash('sha256')
+    .update(`${input.repository.repoId}\u0000${input.request.requestId}`)
+    .digest('hex')
+    .slice(0, 24);
+  const requestRoot = join(repositoryControllerRoot(input.controllerHome, input.repository.repoId), 'plugin-action-processes');
+  const requestPath = join(requestRoot, `${requestToken}.request.json`);
+  const bytes = envelopeBytes(input.controllerHome, input.repository, input.request);
+  const requestSha256 = createHash('sha256').update(bytes).digest('hex');
+  if (existsSync(requestPath)) {
+    const existing = readFileSync(requestPath, 'utf8');
+    const existingSha256 = createHash('sha256').update(existing).digest('hex');
+    if (existingSha256 !== requestSha256) {
+      throw new Error(`PROCESS_REQUEST_CONFLICT: plugin request ${input.request.requestId} already has different arguments`);
+    }
+  } else {
+    privateAtomicWrite(requestPath, bytes);
+  }
+
+  const invocation = resolveLightweightPluginActionRuntimeInvocation();
+  const { handle } = await startLightweightInternalProcess({
+    controllerHome: input.controllerHome,
+    repoId: input.repository.repoId,
+    executable: invocation.executable,
+    args: [
+      ...invocation.argsPrefix,
+      '--request', requestPath,
+      '--expected-sha256', requestSha256,
+    ],
+    cwd: input.repository.canonicalRoot,
+    interactiveWaitMs: Math.max(0, input.interactiveWaitMs ?? 750),
+    timeoutMs: input.timeoutMs,
+    workId: input.request.workId,
+    commandId: `plugin-action:${input.request.requestId}`,
+    maxOutputBytes: 64 * 1024,
+    signal: input.request.signal,
+  });
+  return { handle, requestSha256 };
+}
+
+export async function waitLightweightPluginAction(
+  controllerHome: string,
+  repoId: string,
+  processId: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<ProcessHandle> {
+  return waitForLightweightProcess(controllerHome, repoId, processId, { timeoutMs, signal });
+}

package/src/runtime/plugins/local-system-adapter.ts

@@ -1,4 +1,4 @@
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import {
   constants,
@@ -15,6 +15,7 @@ import {
   writeFileSync,
 } from 'fs';
 import { dirname, extname, join, resolve } from 'path';
+import { forgeRuntimeServicePaths } from '../root/service';
 import {
   WorkspaceTargetGrantError,
   authorizeWorkspaceTargetGrant,
@@ -71,6 +72,7 @@ export interface LocalSystemPluginHooks {
   now?: () => Date;
   runCommand?: (command: string, args: string[], timeoutMs?: number) => CommandResult;
   signalProcess?: (pid: number, signal: NodeJS.Signals) => void;
+  scheduleLaunchAgentRestart?: (service: string) => { pid: number };
 }
 
 let hooks: LocalSystemPluginHooks = {};
@@ -169,6 +171,98 @@ function run(command: string, args: string[], timeoutMs = 30_000): CommandResult
   };
 }
 
+export interface DesktopApplicationIdentity {
+  bundleId?: string;
+  appName?: string;
+}
+
+export interface VerifiedDesktopApplicationActivation {
+  activated: true;
+  verified: true;
+  bundleId: string;
+  appName: string;
+  activationCommand: string[];
+  frontmostQueryCommand: string[];
+}
+
+function normalizedDesktopApplicationIdentity(identity: DesktopApplicationIdentity): { bundleId: string; appName: string } {
+  return {
+    bundleId: typeof identity.bundleId === 'string' ? identity.bundleId.trim() : '',
+    appName: typeof identity.appName === 'string' ? identity.appName.trim() : '',
+  };
+}
+
+function frontmostDesktopApplication(): { bundleId: string; appName: string; queryCommand: string[] } {
+  const front = run('/usr/bin/lsappinfo', ['front'], 2_000);
+  const asn = front.stdout.trim();
+  if (!front.ok || !/^ASN:[^\s]+:?$/.test(asn)) {
+    throw new AssistantPluginError('DESKTOP_FALLBACK_FRONTMOST_QUERY_FAILED', 'LaunchServices did not return a valid frontmost application identity.', {
+      retryable: true,
+      details: { status: front.status, stderr: bounded(front.stderr, 2_000).content, stdout: bounded(front.stdout, 2_000).content },
+    });
+  }
+  const info = run('/usr/bin/lsappinfo', ['info', '-only', 'bundleid', '-only', 'name', asn], 2_000);
+  if (!info.ok) {
+    throw new AssistantPluginError('DESKTOP_FALLBACK_FRONTMOST_QUERY_FAILED', 'LaunchServices could not resolve the frontmost application identity.', {
+      retryable: true,
+      details: { status: info.status, stderr: bounded(info.stderr, 2_000).content, asn },
+    });
+  }
+  const bundleId = info.stdout.match(/bundleID="([^"]+)"/)?.[1]?.trim() ?? '';
+  const appName = info.stdout.match(/^"([^"]+)"/m)?.[1]?.trim() ?? '';
+  if (!bundleId && !appName) {
+    throw new AssistantPluginError('DESKTOP_FALLBACK_FRONTMOST_QUERY_FAILED', 'LaunchServices returned frontmost evidence without a stable application identity.', {
+      retryable: true,
+      details: { observed: bounded(info.stdout, 4_000).content, asn },
+    });
+  }
+  return { bundleId, appName, queryCommand: info.command };
+}
+
+export async function activateAndVerifyFrontmostApplication(
+  identity: DesktopApplicationIdentity,
+): Promise<VerifiedDesktopApplicationActivation> {
+  if (process.platform !== 'darwin') {
+    throw new AssistantPluginError('DESKTOP_FALLBACK_ACTIVATION_UNAVAILABLE', 'Forge desktop activation fallback is available only on macOS.', { retryable: false });
+  }
+  const target = normalizedDesktopApplicationIdentity(identity);
+  if (!target.bundleId && !target.appName) {
+    throw new AssistantPluginError('DESKTOP_FALLBACK_ACTIVATION_TARGET_INVALID', 'Desktop activation fallback requires an exact bundle id or application name.', { retryable: false });
+  }
+  const activationArgs = target.bundleId ? ['-b', target.bundleId] : ['-a', target.appName];
+  const activation = run('/usr/bin/open', activationArgs, 5_000);
+  if (!activation.ok) {
+    throw new AssistantPluginError('DESKTOP_FALLBACK_ACTIVATION_FAILED', `LaunchServices could not activate ${target.bundleId || target.appName}.`, {
+      retryable: true,
+      details: { target, status: activation.status, stderr: bounded(activation.stderr, 4_000).content },
+    });
+  }
+
+  let observed: { bundleId: string; appName: string; queryCommand: string[] } | undefined;
+  for (let attempt = 0; attempt < 12; attempt += 1) {
+    observed = frontmostDesktopApplication();
+    const matches = target.bundleId
+      ? observed.bundleId === target.bundleId
+      : observed.appName === target.appName;
+    if (matches) {
+      return {
+        activated: true,
+        verified: true,
+        bundleId: observed.bundleId,
+        appName: observed.appName,
+        activationCommand: activation.command,
+        frontmostQueryCommand: observed.queryCommand,
+      };
+    }
+    if (attempt < 11) await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+
+  throw new AssistantPluginError('DESKTOP_FALLBACK_ACTIVATION_NOT_CONFIRMED', `LaunchServices did not confirm ${target.bundleId || target.appName} as frontmost after activation.`, {
+    retryable: true,
+    details: { target, observed: observed ? { bundleId: observed.bundleId, appName: observed.appName } : undefined, activationCommand: activation.command },
+  });
+}
+
 function projectScriptRuntimePath(runtime: string): string {
   const home = process.env.HOME?.trim();
   const candidates: Record<string, string[]> = {
@@ -450,7 +544,22 @@ function assertInstalledLaunchAgentIdentity(identity: ReturnType<typeof userLaun
   }
 }
 
-export function restartVerifiedUserLaunchAgent(labelValue: unknown, expectedProgramValue: unknown): Record<string, unknown> {
+function scheduleLaunchAgentRestart(service: string): { pid: number } {
+  if (hooks.scheduleLaunchAgentRestart) return hooks.scheduleLaunchAgentRestart(service);
+  const helperSource = `const { spawnSync } = require('node:child_process'); setTimeout(() => { const result = spawnSync('/bin/launchctl', ['kickstart', '-k', ${JSON.stringify(service)}], { stdio: 'ignore' }); process.exit(result.status ?? 1); }, 750);`;
+  const helper = spawn(process.execPath, ['-e', helperSource], { detached: true, stdio: 'ignore', env: process.env });
+  if (!helper.pid) throw new AssistantPluginError('LOCAL_SYSTEM_LAUNCH_AGENT_RESTART_HELPER_FAILED', `Failed to schedule restart for ${service}.`, { retryable: true, details: { service } });
+  helper.unref();
+  return { pid: helper.pid };
+}
+
+function launchAgentObservedPid(observed: string): number | undefined {
+  const match = observed.match(/(?:^|\n)\s*pid = (\d+)\s*(?:\n|$)/);
+  const pid = match ? Number(match[1]) : NaN;
+  return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+
+export function restartVerifiedUserLaunchAgent(labelValue: unknown, expectedProgramValue: unknown, controllerHome?: string): Record<string, unknown> {
   const identity = userLaunchAgentIdentity(labelValue, expectedProgramValue);
   const inspected = run('/bin/launchctl', ['print', identity.service], 15_000);
   if (!inspected.ok) {
@@ -458,14 +567,22 @@ export function restartVerifiedUserLaunchAgent(labelValue: unknown, expectedProg
       retryable: false, details: { label: identity.label, service: identity.service, stderr: bounded(inspected.stderr, 4096).content },
     });
   }
-  assertLaunchAgentObservedIdentity(identity, `${inspected.stdout}\n${inspected.stderr}`);
+  const observed = `${inspected.stdout}\n${inspected.stderr}`;
+  assertLaunchAgentObservedIdentity(identity, observed);
+  const observedPid = launchAgentObservedPid(observed);
+  const canonicalRuntimeLabel = controllerHome ? forgeRuntimeServicePaths(controllerHome).label : undefined;
+  const selfRuntimeTarget = identity.label === canonicalRuntimeLabel || observedPid === process.pid;
+  if (selfRuntimeTarget) {
+    const helper = scheduleLaunchAgentRestart(identity.service);
+    return { restarted: true, restartScheduled: true, selfRestart: true, label: identity.label, service: identity.service, expectedProgramContains: identity.expectedProgram, observedPid, canonicalRuntimeLabel, helperPid: helper.pid, inspectCommand: inspected.command };
+  }
   const restarted = run('/bin/launchctl', ['kickstart', '-k', identity.service], 30_000);
   if (!restarted.ok) {
     throw new AssistantPluginError('LOCAL_SYSTEM_LAUNCH_AGENT_RESTART_FAILED', restarted.stderr.trim() || restarted.stdout.trim() || `Failed to restart ${identity.label}.`, {
-      retryable: true, details: { label: identity.label, service: identity.service, exitCode: restarted.status },
+      retryable: true, details: { label: identity.label, service: identity.service, exitCode: restarted.status, stdout: bounded(restarted.stdout, 4096).content, stderr: bounded(restarted.stderr, 4096).content },
     });
   }
-  return { restarted: true, label: identity.label, service: identity.service, expectedProgramContains: identity.expectedProgram, inspectCommand: inspected.command, restartCommand: restarted.command };
+  return { restarted: true, restartScheduled: false, selfRestart: false, label: identity.label, service: identity.service, expectedProgramContains: identity.expectedProgram, observedPid, inspectCommand: inspected.command, restartCommand: restarted.command };
 }
 
 export function stopVerifiedUserLaunchAgent(labelValue: unknown, expectedProgramValue: unknown): Record<string, unknown> {
@@ -522,7 +639,7 @@ function actions(): AssistantPluginActionDescriptor[] {
     { actionId: 'restart_user_launch_agent', title: 'Restart verified user LaunchAgent', description: 'Restart one loaded user LaunchAgent by exact label only after launchctl evidence contains the expected program identity.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { label: { type: 'string' }, expected_program_contains: { type: 'string' } }, required: ['label', 'expected_program_contains'], additionalProperties: false } },
     { actionId: 'stop_user_launch_agent', title: 'Stop verified user LaunchAgent', description: 'Boot out one exact loaded user LaunchAgent only after its launchd identity matches the expected program.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { label: { type: 'string' }, expected_program_contains: { type: 'string' } }, required: ['label', 'expected_program_contains'], additionalProperties: false } },
     { actionId: 'start_user_launch_agent', title: 'Start verified user LaunchAgent', description: 'Bootstrap or start one exact current-user LaunchAgent from ~/Library/LaunchAgents only after the installed plist matches the expected program identity.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: ['local-system.process'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { label: { type: 'string' }, expected_program_contains: { type: 'string' } }, required: ['label', 'expected_program_contains'], additionalProperties: false } },
-    { actionId: 'open_application', title: 'Open application', description: 'Open one macOS application by name or bundle id.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.open'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { app_name: { type: 'string' }, bundle_id: { type: 'string' } }, additionalProperties: false } },
+    { actionId: 'open_application', title: 'Open application', description: 'Open one macOS application by name or bundle id in the background without stealing foreground focus.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: ['local-system.open'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { app_name: { type: 'string' }, bundle_id: { type: 'string' } }, additionalProperties: false } },
     { actionId: 'list_targets', title: 'List filesystem targets', description: 'List active expiring local filesystem grants.', readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true, scopes: ['local-system.files.read'], resourceClaims: controllerRead, argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
     { actionId: 'authorize_target', title: 'Authorize filesystem target', description: 'Authorize an expiring filesystem target. By default, a path inside a Git project authorizes the whole project/repository root; use scope=directory only when intentionally granting a narrower directory.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: true, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' }, root_path: { type: 'string' }, scope: { type: 'string', enum: ['auto', 'project', 'directory'] }, expires_in_minutes: { type: 'number' }, reason: { type: 'string' }, access: { type: 'string', enum: ['read_only', 'read_write'] } }, required: ['target_key', 'root_path', 'reason'], additionalProperties: false } },
     { actionId: 'revoke_target', title: 'Revoke filesystem target', description: 'Immediately revoke one active filesystem target owned by the authenticated caller.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 15_000, cancellable: true, idempotent: false, scopes: ['local-system.files.write'], resourceClaims: controllerWrite, argumentsSchema: { type: 'object', properties: { target_key: { type: 'string' } }, required: ['target_key'], additionalProperties: false } },
@@ -627,7 +744,7 @@ export async function executeLocalSystemPluginAction(input: AssistantPluginActio
     case 'system_snapshot': return systemSnapshot();
     case 'process_detail': return processDetail(input.args.pid);
     case 'terminate_process': return terminateVerifiedProcess(input.args.pid, input.args.expected_command_contains);
-    case 'restart_user_launch_agent': return restartVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains);
+    case 'restart_user_launch_agent': return restartVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains, input.controllerHome);
     case 'stop_user_launch_agent': return stopVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains);
     case 'start_user_launch_agent': return startVerifiedUserLaunchAgent(input.args.label, input.args.expected_program_contains);
     case 'open_application': {
@@ -636,7 +753,7 @@ export async function executeLocalSystemPluginAction(input: AssistantPluginActio
       if ((!appName && !bundleId) || (appName && bundleId)) {
         throw new AssistantPluginError('PLUGIN_ACTION_ARGUMENT_INVALID', 'Provide exactly one of app_name or bundle_id.', { retryable: false });
       }
-      const command = bundleId ? ['open', '-b', bundleId] : ['open', '-a', appName as string];
+      const command = bundleId ? ['open', '-g', '-b', bundleId] : ['open', '-g', '-a', appName as string];
       const opened = run(command[0], command.slice(1));
       if (!opened.ok) throw new AssistantPluginError('LOCAL_SYSTEM_OPEN_FAILED', opened.stderr || opened.stdout, { retryable: true, details: { command } });
       return { opened: true, command };

package/src/runtime/plugins/macos-capability-broker.ts

@@ -6,6 +6,8 @@ import { AssistantPluginError } from './errors';
 
 const BROKER_PLUGIN_ID = 'desktop_operator';
 const BROKER_PROTOCOL_VERSION = '1.0';
+const BROWSER_AUTOMATION_CAPABILITY = 'macos_browser_automation.v1';
+const BROWSER_AUTOMATION_PROTOCOL_VERSION = 1;
 const MAX_RESPONSE_BYTES = 4 * 1_048_576;
 let testSocketPath: string | undefined;
 
@@ -34,14 +36,10 @@ function unavailable(error: AssistantPluginError, path: string): AssistantPlugin
   );
 }
 
-async function verifyBrokerIdentity(path: string, timeoutMs: number): Promise<void> {
-  const handshake = await callExternalUnixSocket({
-    socketPath: path,
-    requestId: `macos-broker-handshake:${randomUUID()}`,
-    method: 'handshake',
-    timeoutMs: Math.min(timeoutMs, 2_000),
-    maxResponseBytes: 64 * 1024,
-  });
+export function validateMacOsCapabilityBrokerHandshake(
+  handshake: Record<string, unknown>,
+  requestedAction?: string,
+): void {
   if (handshake.pluginId !== BROKER_PLUGIN_ID || handshake.protocolVersion !== BROKER_PROTOCOL_VERSION) {
     throw new AssistantPluginError(
       'PLUGIN_MACOS_CAPABILITY_BROKER_IDENTITY_MISMATCH',
@@ -49,6 +47,53 @@ async function verifyBrokerIdentity(path: string, timeoutMs: number): Promise<vo
       { retryable: false, details: { expectedPluginId: BROKER_PLUGIN_ID, expectedProtocolVersion: BROKER_PROTOCOL_VERSION } },
     );
   }
+  const capabilities = Array.isArray(handshake.internalCapabilities)
+    ? handshake.internalCapabilities.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+  const actions = Array.isArray(handshake.browserAutomationActions)
+    ? handshake.browserAutomationActions.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+  const browserProtocolVersion = handshake.browserAutomationProtocolVersion;
+  const declaresBrowserMetadata = Array.isArray(handshake.internalCapabilities)
+    || Array.isArray(handshake.browserAutomationActions)
+    || browserProtocolVersion !== undefined;
+  // Desktop Operator v0.2.1 predates optional browser capability metadata in its handshake,
+  // but it implements the separately routed macos_browser_automation method. In that legacy
+  // shape, let the real method/action call prove support. Unsupported methods/actions still
+  // fail closed at the provider boundary.
+  if (!declaresBrowserMetadata) return;
+  if (!capabilities.includes(BROWSER_AUTOMATION_CAPABILITY)
+    || browserProtocolVersion !== BROWSER_AUTOMATION_PROTOCOL_VERSION
+    || (requestedAction && !actions.includes(requestedAction))) {
+    throw new AssistantPluginError(
+      'PLUGIN_MACOS_CAPABILITY_BROKER_CAPABILITY_UNSUPPORTED',
+      requestedAction
+        ? `Installed Forge Desktop Operator does not declare required browser automation action ${requestedAction}.`
+        : 'Installed Forge Desktop Operator does not declare the required browser automation capability.',
+      {
+        retryable: false,
+        details: {
+          requiredCapability: BROWSER_AUTOMATION_CAPABILITY,
+          requiredBrowserAutomationProtocolVersion: BROWSER_AUTOMATION_PROTOCOL_VERSION,
+          ...(requestedAction ? { requiredAction: requestedAction } : {}),
+          declaredCapability: capabilities.includes(BROWSER_AUTOMATION_CAPABILITY),
+          declaredBrowserAutomationProtocolVersion: typeof browserProtocolVersion === 'number' ? browserProtocolVersion : null,
+          declaredActionCount: actions.length,
+        },
+      },
+    );
+  }
+}
+
+async function verifyBrokerIdentity(path: string, timeoutMs: number, requestedAction?: string): Promise<void> {
+  const handshake = await callExternalUnixSocket({
+    socketPath: path,
+    requestId: `macos-broker-handshake:${randomUUID()}`,
+    method: 'handshake',
+    timeoutMs: Math.min(timeoutMs, 2_000),
+    maxResponseBytes: 64 * 1024,
+  });
+  validateMacOsCapabilityBrokerHandshake(handshake, requestedAction);
 }
 
 export async function callMacOsCapabilityBroker(
@@ -57,7 +102,8 @@ export async function callMacOsCapabilityBroker(
 ): Promise<Record<string, unknown>> {
   const path = socketPath();
   try {
-    await verifyBrokerIdentity(path, timeoutMs);
+    const requestedAction = typeof params.action === 'string' ? params.action : undefined;
+    await verifyBrokerIdentity(path, timeoutMs, requestedAction);
     return await callExternalUnixSocket({
       socketPath: path,
       requestId: `macos-broker:${randomUUID()}`,

package/src/runtime/plugins/plugin-action-sidecar.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { createHash } from 'crypto';
+import { readFileSync, rmSync } from 'fs';
+import { getRepository } from '../../cli/repositories/registry';
+import type { AssistantPluginActionRequest } from './types';
+import { submitAssistantPluginAction } from './store';
+
+interface Envelope {
+  schemaVersion: 1;
+  controllerHome: string;
+  repoId: string;
+  request: Omit<AssistantPluginActionRequest, 'signal'>;
+}
+
+function required(argv: string[], flag: string): string {
+  const index = argv.indexOf(flag);
+  const value = index >= 0 ? argv[index + 1]?.trim() : undefined;
+  if (!value) throw new Error(`PLUGIN_ACTION_SIDECAR_USAGE: missing ${flag}`);
+  return value;
+}
+
+export async function runPluginActionSidecar(argv = process.argv.slice(2)): Promise<number> {
+  const requestPath = required(argv, '--request');
+  const expectedSha256 = required(argv, '--expected-sha256');
+  try {
+    const bytes = readFileSync(requestPath, 'utf8');
+    const actualSha256 = createHash('sha256').update(bytes).digest('hex');
+    if (actualSha256 !== expectedSha256) {
+      throw new Error('PLUGIN_ACTION_REQUEST_CHANGED: sidecar request fingerprint changed before execution');
+    }
+    const envelope = JSON.parse(bytes) as Envelope;
+    if (envelope.schemaVersion !== 1) throw new Error('PLUGIN_ACTION_REQUEST_VERSION_UNSUPPORTED');
+    const repository = getRepository(envelope.repoId, envelope.controllerHome);
+    const submitted = await submitAssistantPluginAction(
+      envelope.controllerHome,
+      repository,
+      envelope.request,
+    );
+    process.stdout.write(`${JSON.stringify({
+      ok: true,
+      requestId: submitted.receipt.requestId,
+      receiptId: submitted.receipt.receiptId,
+      deduplicated: submitted.deduplicated,
+    })}\n`);
+    return 0;
+  } finally {
+    rmSync(requestPath, { force: true });
+  }
+}
+
+const direct = typeof process.argv[1] === 'string' && process.argv[1].includes('plugin-action-sidecar');
+if (direct) {
+  void runPluginActionSidecar()
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    });
+}