@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,9 +1,12 @@
-import { createHash } from 'crypto';
 import { AssistantPluginError } from './errors';
-import { getExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistration } from './external-registration';
+import { externalPluginRegistrationSetIdentity, 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 { activateAndVerifyFrontmostApplication, restartVerifiedUserLaunchAgent, startVerifiedUserLaunchAgent, stopVerifiedUserLaunchAgent } from './local-system-adapter';
+import {
+  resolveExternalProviderPolicy,
+  type ExternalProviderPolicyContext,
+} from './external-provider-policy';
 import type { AssistantPluginActionDescriptor, AssistantPluginAdapter, AssistantPluginAuthorizationContext, AssistantPluginCapability, AssistantPluginHealth, AssistantPluginManifest, AssistantPluginPermissionScope } from './types';
 
 interface ProviderManifest {
@@ -61,9 +64,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 providerPolicy = resolveExternalProviderPolicy(registration);
   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) => !(providerPolicy?.allowsMissingProviderAction?.(actionId) ?? false))
     .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;
@@ -145,6 +149,17 @@ function managedSpec(registration: ExternalPluginRegistration): ManagedPluginPro
   };
 }
 
+function providerActionTimeoutMs(
+  registration: ExternalPluginRegistration,
+  actionId: string,
+  explicitTimeoutMs: number | undefined,
+): number | undefined {
+  if (explicitTimeoutMs !== undefined) return explicitTimeoutMs;
+  if (actionId === 'manifest' || actionId === 'health') return registration.transport.healthTimeoutMs;
+  return registration.actions.find((action) => action.actionId === actionId)?.defaultTimeoutMs
+    ?? registration.transport.actionTimeoutMs;
+}
+
 function probeProvider(
   registration: ExternalPluginRegistration,
   requestId: string,
@@ -181,15 +196,17 @@ async function callProvider(
       requestId,
       method: isProviderMethod ? actionId : 'execute',
       params: isProviderMethod ? undefined : { action: actionId, arguments: args },
-      timeoutMs: timeoutMs ?? (isProviderMethod ? registration.transport.healthTimeoutMs : registration.transport.actionTimeoutMs),
+      timeoutMs: providerActionTimeoutMs(registration, actionId, timeoutMs),
       signal,
     }));
   }
+  const descriptor = registration.actions.find((action) => action.actionId === actionId);
   return await (dependencies.managedCall ?? executeManagedPluginProcess)(managedSpec(registration), {
     requestId,
     actionId,
     input: args,
-    timeoutMs: timeoutMs ?? (actionId === 'manifest' || actionId === 'health' ? registration.transport.healthTimeoutMs : registration.transport.actionTimeoutMs),
+    timeoutMs: providerActionTimeoutMs(registration, actionId, timeoutMs),
+    effectOutcomeOnTimeout: descriptor && !descriptor.readOnly ? 'outcome_unknown' : 'failed',
     signal,
   });
 }
@@ -205,208 +222,83 @@ function externalProviderAuthorizationContext(registration: ExternalPluginRegist
   };
 }
 
-function desktopApplicationAuthorizationContext(
+async function resolveExternalAuthorizationContext(
   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);
-}
-
-async function independentlyEnsureExactFrontmostDesktopApplication(
-  bundleId: string,
-  appName: string,
+  input: Parameters<NonNullable<AssistantPluginAdapter['resolveAuthorizationContext']>>[0],
   dependencies: ExternalPluginAdapterDependencies,
-): Promise<void> {
-  const activateAndVerify = dependencies.activateAndVerifyFrontmostApplication ?? activateAndVerifyFrontmostApplication;
-  const proof = await activateAndVerify({ bundleId: bundleId || undefined, appName: appName || undefined });
-  const proofBundleId = typeof proof.bundleId === 'string' ? proof.bundleId.trim() : '';
-  const proofAppName = typeof proof.appName === 'string' ? proof.appName.trim() : '';
-  const proofMatches = bundleId ? proofBundleId === bundleId : proofAppName === appName;
-  if (proof.activated !== true || proof.verified !== true || !proofMatches) {
-    throw new AssistantPluginError(
-      'DESKTOP_ACTIVATION_FALLBACK_IDENTITY_MISMATCH',
-      `Forge did not prove the exact requested application ${bundleId || appName} as frontmost.`,
-      { retryable: true, details: { target: { bundleId, appName }, observed: { bundleId: proofBundleId, appName: proofAppName } } },
-    );
+): Promise<AssistantPluginAuthorizationContext | undefined> {
+  if (EXTERNAL_PROVIDER_LIFECYCLE_ACTIONS.has(input.actionId)) {
+    return externalProviderAuthorizationContext(registration);
   }
+  const providerPolicy = resolveExternalProviderPolicy(registration);
+  if (!providerPolicy?.resolveAuthorizationContext) return undefined;
+  return await providerPolicy.resolveAuthorizationContext(
+    registration,
+    input,
+    externalProviderPolicyContext(registration, dependencies),
+  );
 }
 
-async function openVerifiedDesktopSession(
+function externalProviderPolicyContext(
   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 providerActivationError: AssistantPluginError | undefined;
-  try {
-    result = await callProvider(
+): ExternalProviderPolicyContext {
+  return {
+    callProvider: (requestId, actionId, args, timeoutMs, signal) => callProvider(
       registration,
       requestId,
-      'desktop_session_open',
+      actionId,
       args,
       timeoutMs,
       signal,
       dependencies,
-    );
-  } catch (error) {
-    if (!(error instanceof AssistantPluginError) || error.code !== 'APP_ACTIVATION_FAILED') throw error;
-    providerActivationError = 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,
-    );
-  }
-
-  try {
-    await independentlyEnsureExactFrontmostDesktopApplication(bundleId, appName, dependencies);
-  } catch (verificationError) {
-    const wrappedCode = providerActivationError ? 'DESKTOP_ACTIVATION_FALLBACK_FAILED' : 'DESKTOP_ACTIVATION_NOT_CONFIRMED';
-    const wrappedMessage = providerActivationError
-      ? `Desktop Operator activation failed and Forge could not independently verify ${bundleId || appName} as frontmost.`
-      : `Desktop Operator returned an activated session, but Forge could not independently verify ${bundleId || appName} as frontmost.`;
-    if (verificationError instanceof AssistantPluginError) {
-      throw new AssistantPluginError(wrappedCode, wrappedMessage, {
-        retryable: verificationError.retryable,
-        details: {
-          ...(providerActivationError ? { providerErrorCode: providerActivationError.code } : {}),
-          verificationErrorCode: verificationError.code,
-          verificationErrorMessage: verificationError.message,
-          target: bundleId || appName,
-        },
-      });
-    }
-    throw new AssistantPluginError(wrappedCode, wrappedMessage, {
-      retryable: true,
-      details: {
-        ...(providerActivationError ? { providerErrorCode: providerActivationError.code } : {}),
-        verificationErrorMessage: String(verificationError),
-        target: bundleId || appName,
-      },
-    });
-  }
+    ),
+    verifyProviderIdentity: async (requestId, signal) => {
+      const providerManifest = await callProvider(
+        registration,
+        requestId,
+        'manifest',
+        {},
+        undefined,
+        signal,
+        dependencies,
+      );
+      parseProviderManifest(providerManifest, registration);
+    },
+    activateAndVerifyFrontmostApplication: dependencies.activateAndVerifyFrontmostApplication ?? activateAndVerifyFrontmostApplication,
+  };
+}
 
-  return result;
+interface ExternalPluginAdapterSnapshot {
+  registrationSetIdentity: string;
+  adapters: readonly AssistantPluginAdapter[];
+  byPluginId: ReadonlyMap<string, AssistantPluginAdapter>;
 }
 
-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 externalPluginAdapterSnapshots = new Map<string, ExternalPluginAdapterSnapshot>();
 
-  const interactionId = typeof input.args.interaction_id === 'string' ? input.args.interaction_id.trim() : '';
-  if (!interactionId) return undefined;
+function externalPluginAdapterSnapshot(controllerHome: string): ExternalPluginAdapterSnapshot {
+  const registrationSetIdentity = externalPluginRegistrationSetIdentity(controllerHome);
+  const cached = externalPluginAdapterSnapshots.get(controllerHome);
+  if (cached?.registrationSetIdentity === registrationSetIdentity) return cached;
 
-  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);
+  const adapters = listExternalPluginRegistrations(controllerHome)
+    .map((registration) => createExternalPluginAdapter(registration));
+  const snapshot: ExternalPluginAdapterSnapshot = {
+    registrationSetIdentity,
+    adapters,
+    byPluginId: new Map(adapters.map((adapter) => [adapter.pluginId, adapter])),
+  };
+  externalPluginAdapterSnapshots.set(controllerHome, snapshot);
+  return snapshot;
 }
 
 export function getExternalPluginAdapter(controllerHome: string, pluginId: string): AssistantPluginAdapter | undefined {
-  const registration = getExternalPluginRegistration(controllerHome, pluginId);
-  return registration ? createExternalPluginAdapter(registration) : undefined;
+  return externalPluginAdapterSnapshot(controllerHome).byPluginId.get(pluginId);
 }
 
 export function listExternalPluginAdapters(controllerHome: string): AssistantPluginAdapter[] {
-  return listExternalPluginRegistrations(controllerHome).map((registration) => createExternalPluginAdapter(registration));
+  return [...externalPluginAdapterSnapshot(controllerHome).adapters];
 }
 
 export function createExternalPluginAdapter(
@@ -422,6 +314,7 @@ export function createExternalPluginAdapter(
   return {
     pluginId: registration.pluginId,
     scope: registration.scope,
+    exposure: registration.exposure === 'provider' ? 'internal' : 'product',
     resolveAuthorizationContext: (input) => resolveExternalAuthorizationContext(registration, input, dependencies),
     buildManifest(previousRevision = 0, previousUpdatedAt?: string): AssistantPluginManifest {
       const checkedAt = now().toISOString();
@@ -517,149 +410,15 @@ 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_key') {
-        const sourceInteractionId = typeof input.args.interaction_id === 'string' ? input.args.interaction_id.trim() : '';
-        const keys = Array.isArray(input.args.keys) ? input.args.keys : [];
-        if (!sourceInteractionId || keys.length === 0) {
-          throw providerError('DESKTOP_FOREGROUND_KEY_ARGUMENT_INVALID', 'desktop_key requires interaction_id and at least one key.');
-        }
-        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_KEY_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_KEY_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);
-        }
-        return await callProvider(
-          registration,
-          `${input.requestId}:key`,
-          'desktop_key',
-          { interaction_id: activationInteractionId, keys },
-          input.timeoutMs,
-          input.signal,
-          dependencies,
+      const providerPolicy = resolveExternalProviderPolicy(registration);
+      if (providerPolicy?.executeAction) {
+        const policyResult = await providerPolicy.executeAction(
+          input,
+          externalProviderPolicyContext(registration, dependencies),
         );
+        if (policyResult.handled) return policyResult.result ?? {};
       }
 
-      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-provider-policy.ts

@@ -0,0 +1,48 @@
+import {
+  desktopOperatorAllowsMissingProviderAction,
+  executeDesktopOperatorPolicyAction,
+  resolveDesktopOperatorAuthorizationContext,
+} from './desktop-operator-external-policy';
+import type { ExternalPluginRegistration } from './external-registration';
+import type { DesktopApplicationIdentity, VerifiedDesktopApplicationActivation } from './local-system-adapter';
+import type { AssistantPluginActionExecutionInput, AssistantPluginAuthorizationContext } from './types';
+
+export interface ExternalProviderPolicyContext {
+  callProvider(
+    requestId: string,
+    actionId: string,
+    args: Record<string, unknown>,
+    timeoutMs?: number,
+    signal?: AbortSignal,
+  ): Promise<Record<string, unknown>>;
+  verifyProviderIdentity(requestId: string, signal?: AbortSignal): Promise<void>;
+  activateAndVerifyFrontmostApplication(identity: DesktopApplicationIdentity): Promise<VerifiedDesktopApplicationActivation>;
+}
+
+export interface ExternalProviderPolicyExecutionResult {
+  handled: boolean;
+  result?: Record<string, unknown>;
+}
+
+export interface ExternalProviderPolicy {
+  allowsMissingProviderAction?(actionId: string): boolean;
+  resolveAuthorizationContext?(
+    registration: ExternalPluginRegistration,
+    input: AssistantPluginActionExecutionInput,
+    context: ExternalProviderPolicyContext,
+  ): Promise<AssistantPluginAuthorizationContext | undefined>;
+  executeAction?(
+    input: AssistantPluginActionExecutionInput,
+    context: ExternalProviderPolicyContext,
+  ): Promise<ExternalProviderPolicyExecutionResult>;
+}
+
+const DESKTOP_OPERATOR_EXTERNAL_POLICY: ExternalProviderPolicy = {
+  allowsMissingProviderAction: desktopOperatorAllowsMissingProviderAction,
+  resolveAuthorizationContext: resolveDesktopOperatorAuthorizationContext,
+  executeAction: executeDesktopOperatorPolicyAction,
+};
+
+export function resolveExternalProviderPolicy(registration: ExternalPluginRegistration): ExternalProviderPolicy | undefined {
+  return registration.pluginId === 'desktop_operator' ? DESKTOP_OPERATOR_EXTERNAL_POLICY : undefined;
+}

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

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'fs';
 import { isAbsolute, join } from 'path';
 import { controllerSystemRoot, ensureControllerHome } from '../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
@@ -57,6 +57,8 @@ export interface ExternalPluginRegistration {
   protocolVersion: string;
   scope: AssistantPluginScope;
   enabled: boolean;
+  /** Product registrations appear in normal plugin listings; provider registrations are internal implementation bindings. */
+  exposure?: 'product' | 'provider';
   transport: ExternalPluginTransport;
   lifecycle?: ExternalPluginLifecycle;
   permissions: AssistantPluginPermissionScope[];
@@ -77,6 +79,8 @@ export interface ExternalPluginRegistrationInput {
   protocolVersion: string;
   scope: AssistantPluginScope;
   enabled?: boolean;
+  /** Defaults to product for backward compatibility with schema-v1 registrations. */
+  exposure?: 'product' | 'provider';
   transport: ExternalPluginTransport;
   lifecycle?: ExternalPluginLifecycle;
   permissions: AssistantPluginPermissionScope[];
@@ -94,6 +98,26 @@ export function externalPluginRegistrationPath(controllerHome: string, pluginId:
   return join(registrationRoot(controllerHome), `${sanitizeFileComponent(pluginId)}.json`);
 }
 
+export function externalPluginRegistrationSetIdentity(controllerHome: string): string {
+  const root = registrationRoot(controllerHome);
+  if (!existsSync(root)) return 'absent';
+  const names = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right));
+  return names.map((name) => {
+    const path = join(root, name);
+    try {
+      const stat = statSync(path, { bigint: true });
+      return `${name}:${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+    } catch {
+      // A concurrent registration replacement/removal is itself an identity
+      // change. Do not reuse the prior adapter snapshot across that race.
+      return `${name}:changed`;
+    }
+  }).join('|');
+}
+
 function boundedInteger(value: number | undefined, fallback: number, min: number, max: number): number {
   if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
   return Math.min(Math.max(Math.trunc(value), min), max);
@@ -103,7 +127,7 @@ function normalizedTransport(input: ExternalPluginTransport): ExternalPluginTran
   if (input.kind === 'unix_socket_jsonl') {
     const socketPath = input.socketPath.trim();
     if (!socketPath || !isAbsolute(socketPath)) {
-      throw new Error('EXTERNAL_PLUGIN_SOCKET_PATH_INVALID: trusted registrations require an absolute Unix socket path');
+      throw new Error('EXTERNAL_PLUGIN_SOCKET_PATH_INVALID: trusted registrations require an absolute local socket or Windows named-pipe path');
     }
     return {
       kind: 'unix_socket_jsonl',
@@ -228,6 +252,9 @@ function normalizeRegistrationInput(input: ExternalPluginRegistrationInput): Omi
   const protocolVersion = normalizedString(input.protocolVersion, 'protocol_version', 32);
   if (!PROTOCOL_VERSION_PATTERN.test(protocolVersion)) throw new Error(`EXTERNAL_PLUGIN_PROTOCOL_VERSION_INVALID: ${protocolVersion}`);
   if (!['controller', 'repository'].includes(input.scope)) throw new Error(`EXTERNAL_PLUGIN_SCOPE_INVALID: ${String(input.scope)}`);
+  if (input.exposure !== undefined && !['product', 'provider'].includes(input.exposure)) {
+    throw new Error(`EXTERNAL_PLUGIN_EXPOSURE_INVALID: ${String(input.exposure)}`);
+  }
   return {
     schemaVersion: EXTERNAL_REGISTRATION_SCHEMA_VERSION,
     pluginId,
@@ -238,6 +265,7 @@ function normalizeRegistrationInput(input: ExternalPluginRegistrationInput): Omi
     protocolVersion,
     scope: input.scope,
     enabled: input.enabled !== false,
+    ...(input.exposure !== undefined ? { exposure: input.exposure } : {}),
     transport: normalizedTransport(input.transport),
     lifecycle: normalizedLifecycle(input.lifecycle),
     permissions: structuredClone(input.permissions),

package/src/runtime/plugins/external-unix-socket-probe.cjs

@@ -5,8 +5,7 @@ const net = require('net');
 const path = require('path');
 
 function fail(message) {
-  process.stderr.write(String(message).slice(0, 4000));
-  process.exitCode = 1;
+  process.stderr.write(String(message).slice(0, 4000), () => process.exit(1));
 }
 
 function bounded(value, fallback, min, max) {
@@ -30,6 +29,10 @@ function main() {
     fail('EXTERNAL_PLUGIN_PROBE_REQUEST_INVALID');
     return;
   }
+  if (!/^[a-z][a-z0-9_]{0,127}$/.test(input.method)) {
+    fail('EXTERNAL_PLUGIN_METHOD_INVALID');
+    return;
+  }
   const timeoutMs = bounded(input.timeoutMs, 2000, 100, 10000);
   const maxRequestBytes = bounded(input.maxRequestBytes, 1048576, 1024, 4194304);
   const maxResponseBytes = bounded(input.maxResponseBytes, 1048576, 1024, 4194304);
@@ -57,7 +60,10 @@ function main() {
     if (settled) return;
     settled = true;
     cleanup();
-    process.stdout.write(line);
+    // A named-pipe Socket can keep Bun's event loop alive well after destroy()
+    // on Windows. Exit only after stdout flushes so sync diagnostics stay
+    // bounded by the RPC, not delayed handle reclamation.
+    process.stdout.write(line, () => process.exit(0));
   }
   socket.once('connect', () => socket.write(envelope));
   socket.on('data', (chunk) => {