@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/plugins/desktop-operator-registration.ts

@@ -68,7 +68,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_session_open',
       title: 'Open desktop session',
-      description: 'Launch or locate one application, optionally activate it, and create a bounded interaction session.',
+      description: 'Launch or locate one application and create a bounded interaction session; stays in the background by default, or explicitly activates the target when activate=true.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -83,7 +83,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
           bundle_id: { type: 'string' },
           app_name: { type: 'string' },
           launch: { type: 'boolean' },
-          activate: { type: 'boolean' },
+          activate: { type: 'boolean', description: 'Explicitly activate the target application after launch/lookup. Defaults to false.' },
         },
         anyOf: [{ required: ['bundle_id'] }, { required: ['app_name'] }],
         additionalProperties: false,
@@ -119,7 +119,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_press',
       title: 'Press desktop element',
-      description: 'Press one Accessibility element in an existing desktop interaction session.',
+      description: 'Press one Accessibility element semantically in the background; pointer/coordinate fallback is intentionally unavailable.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -133,8 +133,11 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
         properties: {
           interaction_id: { type: 'string' },
           selector: SELECTOR_SCHEMA,
-          coordinate_fallback: { type: 'boolean' },
-          force_coordinate: { type: 'boolean' },
+          semantic_action: {
+            type: 'string',
+            enum: ['press', 'show_menu', 'pick', 'open', 'confirm'],
+            description: 'Bounded Accessibility action supported by the trusted Desktop Operator provider; defaults to press when omitted.',
+          },
         },
         required: ['interaction_id', 'selector'],
         additionalProperties: false,
@@ -143,7 +146,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_type_text',
       title: 'Type desktop text',
-      description: 'Type text into one selected Accessibility element in an existing interaction session.',
+      description: 'Set text through Accessibility in the background without synthetic keyboard input or application activation.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -167,7 +170,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_key',
       title: 'Press desktop keys',
-      description: 'Send one bounded key chord, optionally activating an existing interaction session first.',
+      description: 'Send one bounded key chord only when the explicit target session is already foreground; the operator never activates it.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -182,7 +185,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
           interaction_id: { type: 'string' },
           keys: { type: 'array', minItems: 1, maxItems: 8, items: { type: 'string' } },
         },
-        required: ['keys'],
+        required: ['interaction_id', 'keys'],
         additionalProperties: false,
       },
     },
@@ -222,7 +225,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_copy',
       title: 'Copy from desktop session',
-      description: 'Activate one explicit desktop session and send Command+C. This foregrounds the target application by design.',
+      description: 'Send Command+C only when the explicit target session is already foreground; the operator never activates it.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -241,7 +244,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_paste',
       title: 'Paste into desktop session',
-      description: 'Activate one explicit desktop session and send Command+V. This foregrounds the target application by design.',
+      description: 'Send Command+V only when the explicit target session is already foreground; the operator never activates it.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -260,7 +263,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_open_url',
       title: 'Open desktop URL',
-      description: 'Open one absolute URL through macOS application routing.',
+      description: 'Open one absolute URL through macOS background routing without activating the destination application.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -407,7 +410,7 @@ export function createDesktopOperatorRegistrationInput(
       { capabilityId: 'desktop.permissions', title: 'Desktop permissions', description: 'Request the official macOS permissions required by Desktop Operator capabilities.', scopes: ['desktop.permissions'], actions: ['desktop_permissions_request'] },
       { capabilityId: 'desktop.session', title: 'Desktop sessions', description: 'Create and close application interaction sessions.', scopes: ['desktop.session'], actions: ['desktop_session_open', 'desktop_session_close'] },
       { capabilityId: 'desktop.observe', title: 'Desktop observation', description: 'Read bounded Accessibility and window state.', scopes: ['desktop.observe'], actions: ['desktop_observe'] },
-      { capabilityId: 'desktop.interact', title: 'Desktop interaction', description: 'Press, type, send keys, and open URLs.', scopes: ['desktop.interact'], actions: ['desktop_press', 'desktop_type_text', 'desktop_key', 'desktop_open_url'] },
+      { capabilityId: 'desktop.interact', title: 'Desktop interaction', description: 'Press controls, type text, send keys, and open URLs.', scopes: ['desktop.interact'], actions: ['desktop_press', 'desktop_type_text', 'desktop_key', 'desktop_open_url'] },
       { capabilityId: 'desktop.capture', title: 'Desktop capture', description: 'Capture authorized screenshots.', scopes: ['desktop.capture'], actions: ['desktop_screenshot'] },
       { capabilityId: 'desktop.clipboard', title: 'Desktop clipboard', description: 'Read or replace plain-text clipboard content and issue explicit copy/paste in a bound session.', scopes: ['desktop.clipboard'], actions: ['desktop_clipboard_read', 'desktop_clipboard_write', 'desktop_copy', 'desktop_paste'] },
       { capabilityId: 'desktop.batch', title: 'Desktop batch', description: 'Run bounded desktop action batches.', scopes: ['desktop.batch'], actions: ['desktop_batch'] },

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

@@ -1,9 +1,10 @@
+import { createHash } from 'crypto';
 import { AssistantPluginError } from './errors';
 import { getExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistration } from './external-registration';
 import { callExternalUnixSocket, probeExternalUnixSocketSync, type ExternalUnixSocketCallOptions } from './external-unix-socket';
 import { executeManagedPluginProcess, executeManagedPluginProcessSync, type ManagedPluginProcessSpec } from './managed-process-adapter';
-import { restartVerifiedUserLaunchAgent, startVerifiedUserLaunchAgent, stopVerifiedUserLaunchAgent } from './local-system-adapter';
-import type { AssistantPluginActionDescriptor, AssistantPluginAdapter, AssistantPluginCapability, AssistantPluginHealth, AssistantPluginManifest, AssistantPluginPermissionScope } from './types';
+import { activateAndVerifyFrontmostApplication, restartVerifiedUserLaunchAgent, startVerifiedUserLaunchAgent, stopVerifiedUserLaunchAgent } from './local-system-adapter';
+import type { AssistantPluginActionDescriptor, AssistantPluginAdapter, AssistantPluginAuthorizationContext, AssistantPluginCapability, AssistantPluginHealth, AssistantPluginManifest, AssistantPluginPermissionScope } from './types';
 
 interface ProviderManifest {
   id: string;
@@ -31,6 +32,7 @@ export interface ExternalPluginAdapterDependencies {
   startVerifiedUserLaunchAgent?: (label: unknown, expectedProgram: unknown) => Record<string, unknown>;
   stopVerifiedUserLaunchAgent?: (label: unknown, expectedProgram: unknown) => Record<string, unknown>;
   restartVerifiedUserLaunchAgent?: (label: unknown, expectedProgram: unknown) => Record<string, unknown>;
+  activateAndVerifyFrontmostApplication?: typeof activateAndVerifyFrontmostApplication;
   now?: () => Date;
 }
 
@@ -59,7 +61,10 @@ function parseProviderManifest(value: Record<string, unknown>, registration: Ext
   if (manifest.protocolVersion !== registration.protocolVersion) throw providerError('EXTERNAL_PLUGIN_PROTOCOL_MISMATCH', `Expected provider protocol ${registration.protocolVersion}, received ${manifest.protocolVersion || 'unknown'}.`);
   if (manifest.scope !== registration.scope) throw providerError('EXTERNAL_PLUGIN_SCOPE_MISMATCH', `Expected provider scope ${registration.scope}, received ${manifest.scope || 'unknown'}.`);
   if (manifest.provider !== registration.provider) throw providerError('EXTERNAL_PLUGIN_PROVIDER_MISMATCH', `Expected provider ${registration.provider}, received ${manifest.provider || 'unknown'}.`);
-  const missingActions = registration.actions.map((action) => action.actionId).filter((actionId) => !manifest.actions.includes(actionId));
+  const missingActions = registration.actions
+    .map((action) => action.actionId)
+    .filter((actionId) => !(registration.pluginId === 'desktop_operator' && ['desktop_pointer_click', 'desktop_foreground_pointer_click'].includes(actionId)))
+    .filter((actionId) => !manifest.actions.includes(actionId));
   if (missingActions.length > 0) throw providerError('EXTERNAL_PLUGIN_ACTION_MISMATCH', `Provider is missing registered actions: ${missingActions.join(', ')}.`);
   return manifest;
 }
@@ -189,6 +194,225 @@ async function callProvider(
   });
 }
 
+function externalProviderAuthorizationContext(registration: ExternalPluginRegistration): AssistantPluginAuthorizationContext {
+  return {
+    target: {
+      kind: 'external-provider',
+      id: registration.pluginId,
+      identityFingerprint: registration.registrationFingerprint,
+    },
+    expiresInMinutes: 30 * 24 * 60,
+  };
+}
+
+function desktopApplicationAuthorizationContext(
+  registration: ExternalPluginRegistration,
+  stableApplicationId: string,
+): AssistantPluginAuthorizationContext {
+  const normalized = stableApplicationId.trim();
+  return {
+    target: {
+      kind: 'desktop-application',
+      id: normalized,
+      identityFingerprint: createHash('sha256')
+        .update(`${registration.registrationFingerprint}\0${normalized}`)
+        .digest('hex'),
+    },
+    expiresInMinutes: 30 * 24 * 60,
+  };
+}
+
+function recordArray(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+    : [];
+}
+
+function firstString(record: Record<string, unknown>, ...keys: string[]): string {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+function firstNumber(record: Record<string, unknown>, ...keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+function desktopSession(status: Record<string, unknown>, interactionId: string): Record<string, unknown> | undefined {
+  return recordArray(status.sessions).find((session) => firstString(session, 'interactionId', 'interaction_id') === interactionId);
+}
+
+function desktopApplicationIsActive(status: Record<string, unknown>, bundleId: string, appName: string): boolean {
+  return recordArray(status.applications).some((application) => {
+    if (application.active !== true || application.terminated === true) return false;
+    const candidateBundleId = firstString(application, 'bundle_id', 'bundleIdentifier');
+    const candidateName = firstString(application, 'name', 'appName');
+    return bundleId ? candidateBundleId === bundleId : Boolean(appName) && candidateName === appName;
+  });
+}
+
+async function openVerifiedDesktopSession(
+  registration: ExternalPluginRegistration,
+  requestId: string,
+  args: Record<string, unknown>,
+  timeoutMs: number | undefined,
+  signal: AbortSignal | undefined,
+  dependencies: ExternalPluginAdapterDependencies,
+): Promise<Record<string, unknown>> {
+  const bundleId = typeof args.bundle_id === 'string' ? args.bundle_id.trim() : '';
+  const appName = typeof args.app_name === 'string' ? args.app_name.trim() : '';
+  if (!bundleId && !appName) {
+    throw providerError('DESKTOP_ACTIVATION_TARGET_UNAVAILABLE', 'Activated desktop sessions require an exact bundle id or application name.');
+  }
+
+  let result: Record<string, unknown>;
+  let fallbackVerified = false;
+  try {
+    result = await callProvider(
+      registration,
+      requestId,
+      'desktop_session_open',
+      args,
+      timeoutMs,
+      signal,
+      dependencies,
+    );
+  } catch (error) {
+    if (!(error instanceof AssistantPluginError) || error.code !== 'APP_ACTIVATION_FAILED') throw error;
+
+    result = await callProvider(
+      registration,
+      `${requestId}:fallback-session`,
+      'desktop_session_open',
+      { ...(bundleId ? { bundle_id: bundleId } : { app_name: appName }), launch: false, activate: false },
+      timeoutMs,
+      signal,
+      dependencies,
+    );
+
+    const activateFallback = dependencies.activateAndVerifyFrontmostApplication ?? activateAndVerifyFrontmostApplication;
+    try {
+      const fallbackProof = await activateFallback({ bundleId: bundleId || undefined, appName: appName || undefined });
+      const proofBundleId = typeof fallbackProof.bundleId === 'string' ? fallbackProof.bundleId.trim() : '';
+      const proofAppName = typeof fallbackProof.appName === 'string' ? fallbackProof.appName.trim() : '';
+      const proofMatches = bundleId ? proofBundleId === bundleId : proofAppName === appName;
+      if (fallbackProof.activated !== true || fallbackProof.verified !== true || !proofMatches) {
+        throw new AssistantPluginError(
+          'DESKTOP_ACTIVATION_FALLBACK_IDENTITY_MISMATCH',
+          `Forge fallback did not prove the exact requested application ${bundleId || appName} as frontmost.`,
+          { retryable: true, details: { target: { bundleId, appName }, observed: { bundleId: proofBundleId, appName: proofAppName } } },
+        );
+      }
+      fallbackVerified = true;
+    } catch (fallbackError) {
+      if (fallbackError instanceof AssistantPluginError) {
+        throw new AssistantPluginError(
+          'DESKTOP_ACTIVATION_FALLBACK_FAILED',
+          `Desktop Operator activation failed and Forge could not independently verify ${bundleId || appName} as frontmost.`,
+          {
+            retryable: fallbackError.retryable,
+            details: {
+              providerErrorCode: error.code,
+              fallbackErrorCode: fallbackError.code,
+              fallbackErrorMessage: fallbackError.message,
+              target: bundleId || appName,
+            },
+          },
+        );
+      }
+      throw new AssistantPluginError(
+        'DESKTOP_ACTIVATION_FALLBACK_FAILED',
+        `Desktop Operator activation failed and Forge fallback failed for ${bundleId || appName}.`,
+        { retryable: true, details: { providerErrorCode: error.code, fallbackErrorMessage: String(fallbackError), target: bundleId || appName } },
+      );
+    }
+  }
+
+  if (!fallbackVerified) {
+    const activeStatus = await callProvider(
+      registration,
+      `${requestId}:active-status`,
+      'desktop_status',
+      { limit: 500 },
+      timeoutMs,
+      signal,
+      dependencies,
+    );
+    if (!desktopApplicationIsActive(activeStatus, bundleId, appName)) {
+      throw providerError('DESKTOP_ACTIVATION_NOT_CONFIRMED', `Desktop Operator did not confirm ${bundleId || appName} as the frontmost application after activation.`, true);
+    }
+  }
+  return result;
+}
+
+async function resolveExternalAuthorizationContext(
+  registration: ExternalPluginRegistration,
+  input: Parameters<NonNullable<AssistantPluginAdapter['resolveAuthorizationContext']>>[0],
+  dependencies: ExternalPluginAdapterDependencies,
+): Promise<AssistantPluginAuthorizationContext | undefined> {
+  if (EXTERNAL_PROVIDER_LIFECYCLE_ACTIONS.has(input.actionId)) {
+    return externalProviderAuthorizationContext(registration);
+  }
+  if (registration.pluginId !== 'desktop_operator') return undefined;
+  if (input.actionId === 'desktop_permissions_request') {
+    return externalProviderAuthorizationContext(registration);
+  }
+  if (input.actionId === 'desktop_session_open') {
+    const bundleId = typeof input.args.bundle_id === 'string' ? input.args.bundle_id.trim() : '';
+    return bundleId ? desktopApplicationAuthorizationContext(registration, bundleId) : undefined;
+  }
+
+  const interactionId = typeof input.args.interaction_id === 'string' ? input.args.interaction_id.trim() : '';
+  if (!interactionId) return undefined;
+
+  const providerManifest = await callProvider(
+    registration,
+    `${input.requestId}:authorization-target:manifest`,
+    'manifest',
+    {},
+    undefined,
+    input.signal,
+    dependencies,
+  );
+  parseProviderManifest(providerManifest, registration);
+  const status = await callProvider(
+    registration,
+    `${input.requestId}:authorization-target:desktop-status`,
+    'desktop_status',
+    { limit: 500 },
+    input.timeoutMs,
+    input.signal,
+    dependencies,
+  );
+  const sessions = Array.isArray(status.sessions) ? status.sessions : [];
+  const session = sessions.find((entry) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
+    const record = entry as Record<string, unknown>;
+    const id = typeof record.interactionId === 'string' ? record.interactionId : typeof record.interaction_id === 'string' ? record.interaction_id : '';
+    return id === interactionId;
+  }) as Record<string, unknown> | undefined;
+  if (!session) {
+    throw providerError('EXTERNAL_PLUGIN_AUTHORIZATION_TARGET_UNAVAILABLE', `Desktop session ${interactionId} was not found while resolving its stable authorization target.`, false);
+  }
+  const bundleId = typeof session.bundleIdentifier === 'string' ? session.bundleIdentifier.trim()
+    : typeof session.bundle_identifier === 'string' ? session.bundle_identifier.trim()
+      : '';
+  const appName = typeof session.appName === 'string' ? session.appName.trim()
+    : typeof session.app_name === 'string' ? session.app_name.trim()
+      : '';
+  const stableApplicationId = bundleId || (appName ? `name:${appName.toLowerCase()}` : '');
+  if (!stableApplicationId) {
+    throw providerError('EXTERNAL_PLUGIN_AUTHORIZATION_TARGET_UNAVAILABLE', `Desktop session ${interactionId} has no stable application identity.`, false);
+  }
+  return desktopApplicationAuthorizationContext(registration, stableApplicationId);
+}
+
 export function getExternalPluginAdapter(controllerHome: string, pluginId: string): AssistantPluginAdapter | undefined {
   const registration = getExternalPluginRegistration(controllerHome, pluginId);
   return registration ? createExternalPluginAdapter(registration) : undefined;
@@ -211,6 +435,7 @@ export function createExternalPluginAdapter(
   return {
     pluginId: registration.pluginId,
     scope: registration.scope,
+    resolveAuthorizationContext: (input) => resolveExternalAuthorizationContext(registration, input, dependencies),
     buildManifest(previousRevision = 0, previousUpdatedAt?: string): AssistantPluginManifest {
       const checkedAt = now().toISOString();
       if (!registration.enabled) {
@@ -305,6 +530,102 @@ export function createExternalPluginAdapter(
         );
         parseProviderManifest(providerManifest, registration);
       }
+      if (registration.pluginId === 'desktop_operator' && input.actionId === 'desktop_foreground_pointer_click') {
+        const sourceInteractionId = typeof input.args.interaction_id === 'string' ? input.args.interaction_id.trim() : '';
+        const requestedWindowId = typeof input.args.window_id === 'number' && Number.isInteger(input.args.window_id) ? input.args.window_id : undefined;
+        const x = typeof input.args.x === 'number' && Number.isFinite(input.args.x) ? input.args.x : undefined;
+        const y = typeof input.args.y === 'number' && Number.isFinite(input.args.y) ? input.args.y : undefined;
+        if (!sourceInteractionId || !requestedWindowId || x === undefined || y === undefined) {
+          throw providerError('DESKTOP_FOREGROUND_POINTER_ARGUMENT_INVALID', 'desktop_foreground_pointer_click requires interaction_id, window_id, x, and y.');
+        }
+
+        const sourceStatus = await callProvider(
+          registration,
+          `${input.requestId}:source-status`,
+          'desktop_status',
+          { limit: 500 },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+        const sourceSession = desktopSession(sourceStatus, sourceInteractionId);
+        if (!sourceSession) {
+          throw providerError('DESKTOP_FOREGROUND_POINTER_SESSION_NOT_FOUND', `Desktop session ${sourceInteractionId} is no longer available.`, true);
+        }
+        const bundleId = firstString(sourceSession, 'bundleIdentifier', 'bundle_id');
+        const appName = firstString(sourceSession, 'appName', 'app_name');
+        if (!bundleId && !appName) {
+          throw providerError('DESKTOP_FOREGROUND_POINTER_TARGET_UNAVAILABLE', `Desktop session ${sourceInteractionId} has no stable application identity.`);
+        }
+
+        const activation = await openVerifiedDesktopSession(
+          registration,
+          `${input.requestId}:activate`,
+          { ...(bundleId ? { bundle_id: bundleId } : { app_name: appName }), launch: false, activate: true },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+        const activationInteractionId = firstString(activation, 'interactionId', 'interaction_id');
+        if (!activationInteractionId) {
+          throw providerError('DESKTOP_ACTIVATION_SESSION_MISSING', 'Desktop Operator activated the application without returning a bound interaction session.', true);
+        }
+
+        const screenshot = await callProvider(
+          registration,
+          `${input.requestId}:screenshot`,
+          'desktop_screenshot',
+          {
+            interaction_id: activationInteractionId,
+            scope: 'window',
+            window_id: requestedWindowId,
+            ...(typeof input.args.label === 'string' && input.args.label.trim() ? { label: input.args.label.trim() } : {}),
+          },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+        const visualRevision = firstNumber(screenshot, 'visual_revision', 'visualRevision');
+        const capturedWindowId = firstNumber(screenshot, 'windowId', 'window_id') ?? requestedWindowId;
+        if (!visualRevision || !capturedWindowId) {
+          throw providerError('DESKTOP_FOREGROUND_CAPTURE_INVALID', 'Desktop Operator did not return a fresh visual revision for the foreground window.', true);
+        }
+
+        const click = await callProvider(
+          registration,
+          `${input.requestId}:click`,
+          'desktop_pointer_click',
+          {
+            interaction_id: activationInteractionId,
+            window_id: capturedWindowId,
+            visual_revision: visualRevision,
+            x,
+            y,
+          },
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+        return {
+          interactionId: activationInteractionId,
+          activationVerified: true,
+          windowId: capturedWindowId,
+          visualRevision,
+          screenshot,
+          click,
+        };
+      }
+
+      if (registration.pluginId === 'desktop_operator' && input.actionId === 'desktop_session_open' && input.args.activate === true) {
+        return await openVerifiedDesktopSession(
+          registration,
+          input.requestId,
+          input.args,
+          input.timeoutMs,
+          input.signal,
+          dependencies,
+        );
+      }
       return await callProvider(
         registration,
         input.requestId,

package/src/runtime/plugins/external-registration.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readdirSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'fs';
 import { isAbsolute, join } from 'path';
 import { controllerSystemRoot, ensureControllerHome } from '../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
@@ -284,6 +284,34 @@ export function listExternalPluginRegistrations(controllerHome: string): Externa
     .sort((left, right) => left.pluginId.localeCompare(right.pluginId));
 }
 
+export interface ExternalPluginRegistrationPreview {
+  pluginId: string;
+  currentRevision: number;
+  nextRevision: number;
+  registrationFingerprint: string;
+  currentFingerprint?: string;
+  wouldChange: boolean;
+  registration: Omit<ExternalPluginRegistration, 'revision' | 'registrationFingerprint' | 'installedAt' | 'updatedAt'>;
+}
+
+export function previewExternalPluginRegistration(
+  controllerHome: string,
+  input: ExternalPluginRegistrationInput,
+): ExternalPluginRegistrationPreview {
+  const normalized = normalizeRegistrationInput(input);
+  const existing = getExternalPluginRegistration(controllerHome, normalized.pluginId);
+  const fingerprint = registrationFingerprint(normalized);
+  return {
+    pluginId: normalized.pluginId,
+    currentRevision: existing?.revision ?? 0,
+    nextRevision: existing && existing.registrationFingerprint === fingerprint ? existing.revision : (existing?.revision ?? 0) + 1,
+    registrationFingerprint: fingerprint,
+    currentFingerprint: existing?.registrationFingerprint,
+    wouldChange: existing?.registrationFingerprint !== fingerprint,
+    registration: normalized,
+  };
+}
+
 export function installExternalPluginRegistration(
   controllerHome: string,
   input: ExternalPluginRegistrationInput,
@@ -291,14 +319,19 @@ export function installExternalPluginRegistration(
 ): ExternalPluginRegistration {
   const normalized = normalizeRegistrationInput(input);
   const existing = getExternalPluginRegistration(controllerHome, normalized.pluginId);
-  if (options.expectedRevision !== undefined && existing?.revision !== options.expectedRevision) {
-    throw new Error(`EXTERNAL_PLUGIN_REGISTRATION_REVISION_CONFLICT: expected ${options.expectedRevision}, current ${existing?.revision ?? 0}`);
+  const fingerprint = registrationFingerprint(normalized);
+  // Identical desired state is idempotent, including a replay carrying the old
+  // expected revision after the first write committed.
+  if (existing?.registrationFingerprint === fingerprint) return existing;
+  const currentRevision = existing?.revision ?? 0;
+  if (options.expectedRevision !== undefined && currentRevision !== options.expectedRevision) {
+    throw new Error(`EXTERNAL_PLUGIN_REGISTRATION_REVISION_CONFLICT: expected ${options.expectedRevision}, current ${currentRevision}`);
   }
   const at = (options.now ?? new Date()).toISOString();
   const next: ExternalPluginRegistration = {
     ...normalized,
-    revision: (existing?.revision ?? 0) + 1,
-    registrationFingerprint: registrationFingerprint(normalized),
+    revision: currentRevision + 1,
+    registrationFingerprint: fingerprint,
     installedAt: existing?.installedAt ?? at,
     updatedAt: at,
   };
@@ -306,3 +339,49 @@ export function installExternalPluginRegistration(
   writeJsonAtomic(externalPluginRegistrationPath(controllerHome, next.pluginId), next);
   return next;
 }
+
+function registrationInputFromStored(
+  registration: ExternalPluginRegistration,
+  patch: Partial<Pick<ExternalPluginRegistrationInput, 'enabled'>> = {},
+): ExternalPluginRegistrationInput {
+  return {
+    pluginId: registration.pluginId,
+    providerPluginId: registration.providerPluginId,
+    displayName: registration.displayName,
+    provider: registration.provider,
+    pluginVersion: registration.pluginVersion,
+    protocolVersion: registration.protocolVersion,
+    scope: registration.scope,
+    enabled: patch.enabled ?? registration.enabled,
+    transport: structuredClone(registration.transport),
+    lifecycle: registration.lifecycle ? structuredClone(registration.lifecycle) : undefined,
+    permissions: structuredClone(registration.permissions),
+    capabilities: structuredClone(registration.capabilities),
+    actions: structuredClone(registration.actions),
+    legacyIdentities: [...(registration.legacyIdentities ?? [])],
+  };
+}
+
+export function disableExternalPluginRegistration(
+  controllerHome: string,
+  pluginId: string,
+  options: { expectedRevision?: number; now?: Date } = {},
+): ExternalPluginRegistration {
+  const existing = getExternalPluginRegistration(controllerHome, pluginId);
+  if (!existing) throw new Error(`EXTERNAL_PLUGIN_REGISTRATION_NOT_FOUND: ${pluginId}`);
+  return installExternalPluginRegistration(controllerHome, registrationInputFromStored(existing, { enabled: false }), options);
+}
+
+export function removeExternalPluginRegistration(
+  controllerHome: string,
+  pluginId: string,
+  options: { expectedRevision?: number } = {},
+): ExternalPluginRegistration {
+  const existing = getExternalPluginRegistration(controllerHome, pluginId);
+  if (!existing) throw new Error(`EXTERNAL_PLUGIN_REGISTRATION_NOT_FOUND: ${pluginId}`);
+  if (options.expectedRevision !== undefined && existing.revision !== options.expectedRevision) {
+    throw new Error(`EXTERNAL_PLUGIN_REGISTRATION_REVISION_CONFLICT: expected ${options.expectedRevision}, current ${existing.revision}`);
+  }
+  rmSync(externalPluginRegistrationPath(controllerHome, existing.pluginId));
+  return existing;
+}

package/src/runtime/plugins/external-unix-socket.ts

@@ -1,7 +1,7 @@
 import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
 import { createConnection, type Socket } from 'net';
-import { dirname, isAbsolute, join } from 'path';
+import { dirname, isAbsolute, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { resolveBunExecutable } from '../shared/process-environment';
 import { AssistantPluginError } from './errors';
@@ -178,7 +178,13 @@ export async function callExternalUnixSocket(
 export function resolveExternalPluginProbeSidecarPath(
   execPath: string = process.execPath,
   moduleUrl: string = import.meta.url,
+  env: NodeJS.ProcessEnv = process.env,
 ): string {
+  const configuredReleaseRoot = env.FORGE_RELEASE_PATH?.trim();
+  if (configuredReleaseRoot) {
+    const releaseSidecar = join(resolve(configuredReleaseRoot), 'external-unix-socket-probe.cjs');
+    if (existsSync(releaseSidecar)) return releaseSidecar;
+  }
   const releaseSibling = join(dirname(execPath), 'external-unix-socket-probe.cjs');
   if (existsSync(releaseSibling)) return releaseSibling;
   const moduleSibling = fileURLToPath(new URL('./external-unix-socket-probe.cjs', moduleUrl));

package/src/runtime/plugins/first-party-registry.ts

@@ -1,13 +1,14 @@
 import { appStoreConnectPluginAdapter } from './app-store-connect-adapter';
 import { browserPluginAdapter } from './browser-adapter';
-import { desktopPluginAdapter } from './desktop-adapter';
 import { githubPluginAdapter } from './github-adapter';
 import { gmailPluginAdapter } from './gmail-adapter';
 import { googleCalendarPluginAdapter } from './google-calendar-adapter';
 import { googleTasksPluginAdapter } from './google-tasks-adapter';
 import { iosPluginAdapter } from './ios-adapter';
 import { localSystemPluginAdapter } from './local-system-adapter';
+import { pluginManagementAdapter } from './plugin-management-adapter';
 import { resendPluginAdapter } from './resend-adapter';
+import { xiaohongshuPluginAdapter } from './xiaohongshu-publish';
 import type { AssistantPluginAdapter } from './types';
 
 const FIRST_PARTY_PLUGIN_ADAPTERS: readonly AssistantPluginAdapter[] = [
@@ -19,8 +20,9 @@ const FIRST_PARTY_PLUGIN_ADAPTERS: readonly AssistantPluginAdapter[] = [
   googleCalendarPluginAdapter,
   googleTasksPluginAdapter,
   resendPluginAdapter,
+  xiaohongshuPluginAdapter,
   localSystemPluginAdapter,
-  desktopPluginAdapter,
+  pluginManagementAdapter,
 ];
 
 export function listFirstPartyPluginAdapters(): readonly AssistantPluginAdapter[] {