@moretea-labs/forge 1.6.0 → 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> {
@@ -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': {

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;
+    });
+}

package/src/runtime/plugins/plugin-management-adapter.ts

@@ -6,6 +6,11 @@ import type {
   AssistantPluginPermissionScope,
 } from './types';
 import { AssistantPluginError } from './errors';
+import {
+  listPluginCapabilityAuthorizations,
+  pluginCapabilityAuthorizationOwnerScope,
+  revokePluginCapabilityAuthorization,
+} from './capability-authorization-grants';
 import {
   disableExternalPluginRegistration,
   getExternalPluginRegistration,
@@ -42,17 +47,28 @@ function permissions(): AssistantPluginPermissionScope[] {
     { scope: 'external-plugins.read', mode: 'read', description: 'Read and validate external plugin registrations.', granted: true, required: true },
     { scope: 'external-plugins.write', mode: 'write', description: 'Install, update, and disable validated external plugin registrations.', granted: true, required: true },
     { scope: 'external-plugins.remove', mode: 'write', description: 'Remove one external plugin registration after strong confirmation.', granted: true, required: true },
+    { scope: 'plugin-authorizations.read', mode: 'read', description: 'List reusable plugin capability authorizations owned by the current principal.', granted: true, required: true },
+    { scope: 'plugin-authorizations.revoke', mode: 'write', description: 'Revoke one reusable plugin capability authorization owned by the current principal.', granted: true, required: true },
   ];
 }
 
 function capabilities(): AssistantPluginCapability[] {
-  return [{
-    capabilityId: 'external-plugin-registration-management',
-    title: 'External Plugin Registration Management',
-    description: 'Preview, install/update, inspect, disable, and remove external provider registrations through the canonical validation authority.',
-    scopes: ['external-plugins.read', 'external-plugins.write', 'external-plugins.remove'],
-    actions: ['list_registrations', 'get_registration', 'preview_registration', 'install_registration', 'disable_registration', 'remove_registration'],
-  }];
+  return [
+    {
+      capabilityId: 'external-plugin-registration-management',
+      title: 'External Plugin Registration Management',
+      description: 'Preview, install/update, inspect, disable, and remove external provider registrations through the canonical validation authority.',
+      scopes: ['external-plugins.read', 'external-plugins.write', 'external-plugins.remove'],
+      actions: ['list_registrations', 'get_registration', 'preview_registration', 'install_registration', 'disable_registration', 'remove_registration'],
+    },
+    {
+      capabilityId: 'plugin-capability-authorization-management',
+      title: 'Plugin Capability Authorization Management',
+      description: 'List and revoke persistent exact-target plugin capability authorizations for the current principal.',
+      scopes: ['plugin-authorizations.read', 'plugin-authorizations.revoke'],
+      actions: ['list_capability_authorizations', 'revoke_capability_authorization'],
+    },
+  ];
 }
 
 const registrationProperty = { type: 'object', description: 'ExternalPluginRegistrationInput. Canonical Forge validation rejects invalid identity, transport, lifecycle, permissions, capabilities, and actions.' };
@@ -94,6 +110,18 @@ function actions(): AssistantPluginActionDescriptor[] {
       scopes: ['external-plugins.remove'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
       argumentsSchema: { type: 'object', properties: { plugin_id: { type: 'string' }, expected_revision: { type: 'number' } }, required: ['plugin_id'], additionalProperties: false },
     },
+    {
+      actionId: 'list_capability_authorizations', title: 'List plugin capability authorizations', description: 'List persistent exact-target plugin capability authorizations owned by the current principal; grants owned by other principals are not returned.',
+      readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true,
+      scopes: ['plugin-authorizations.read'], resourceClaims: [{ resource: 'provider-state', mode: 'read' }],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: 'revoke_capability_authorization', title: 'Revoke plugin capability authorization', description: 'Revoke one persistent exact-target plugin capability authorization owned by the current principal.',
+      readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 10_000, cancellable: true, idempotent: true,
+      scopes: ['plugin-authorizations.revoke'], resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
+      argumentsSchema: { type: 'object', properties: { grant_id: { type: 'string' }, reason: { type: 'string' } }, required: ['grant_id', 'reason'], additionalProperties: false },
+    },
   ];
 }
 
@@ -101,7 +129,7 @@ export function buildPluginManagementManifest(previousRevision = 0, previousUpda
   return {
     schemaVersion: 1, manifestVersion: 1, revision: Math.max(1, previousRevision || 1), pluginId: PLUGIN_ID,
     provider: 'forge-controller', displayName: 'Forge Plugin Management', pluginVersion: '1.0.0',
-    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controller-home:plugins/external/registrations'] },
+    authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: ['controller-home:plugins/external/registrations', 'controller-home:system/plugin-capability-authorizations/grants.json'] },
     enabled: true, lifecycle: { state: 'enabled', reason: 'Canonical external plugin registration authority is available.' },
     health: { state: 'ready', checkedAt: now(), ready: true, probed: true, errors: [], warnings: [] },
     permissions: permissions(), capabilities: capabilities(), actions: actions(), updatedAt: previousUpdatedAt ?? now(),
@@ -121,6 +149,19 @@ export async function executePluginManagementAction(input: AssistantPluginAction
     case 'install_registration': return { registration: installExternalPluginRegistration(input.controllerHome, registrationInput(input.args.registration), { expectedRevision: expectedRevision(input.args.expected_revision) }) };
     case 'disable_registration': return { registration: disableExternalPluginRegistration(input.controllerHome, requiredString(input.args.plugin_id, 'plugin_id'), { expectedRevision: expectedRevision(input.args.expected_revision) }) };
     case 'remove_registration': return { removed: removeExternalPluginRegistration(input.controllerHome, requiredString(input.args.plugin_id, 'plugin_id'), { expectedRevision: expectedRevision(input.args.expected_revision) }) };
+    case 'list_capability_authorizations': return {
+      authorizations: listPluginCapabilityAuthorizations(
+        input.controllerHome,
+        pluginCapabilityAuthorizationOwnerScope(input.origin),
+      ),
+    };
+    case 'revoke_capability_authorization': return {
+      authorization: revokePluginCapabilityAuthorization(input.controllerHome, {
+        grantId: requiredString(input.args.grant_id, 'grant_id'),
+        ownerScope: pluginCapabilityAuthorizationOwnerScope(input.origin),
+        reason: requiredString(input.args.reason, 'reason'),
+      }),
+    };
     default: throw new AssistantPluginError('PLUGIN_ACTION_NOT_SUPPORTED', `${PLUGIN_ID}/${input.actionId} is not supported.`, { retryable: false });
   }
 }

package/src/runtime/plugins/resend-adapter.ts

@@ -295,7 +295,7 @@ function actions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'send_email', title: 'Send email with Resend', description: 'Send one email through Resend after strong confirmation.',
       readOnly: false, risk: 'remote_write', confirmation: 'strong_confirmation', requiredConfirmationText: 'send-resend-email',
-      defaultTimeoutMs: 45_000, cancellable: true, idempotent: false, scopes: ['resend.send'], resourceClaims: [{ resource: 'remote', mode: 'exclusive' }],
+      defaultTimeoutMs: 45_000, cancellable: true, idempotent: false, remoteEffectWorkCompletion: 'terminal', scopes: ['resend.send'], resourceClaims: [{ resource: 'remote', mode: 'exclusive' }],
       argumentsSchema: {
         type: 'object',
         properties: {