@moretea-labs/forge 1.8.0 → 1.8.1

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

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from 'crypto';
 import type {
+  ComputerApplicationLaunchProvenance,
   ComputerApplicationTarget,
   ComputerApplicationStableIdentity,
   ComputerApplicationTargetLease,
@@ -11,6 +12,7 @@ import {
   COMPUTER_ELEMENT_OBSERVE_CAPABILITY,
   COMPUTER_INPUT_CAPABILITY,
   COMPUTER_OBSERVE_CAPABILITY,
+  type ComputerConsoleUnlockCommandRequest,
   type ComputerConsoleUnlockPrepareRequest,
   type ComputerConsoleUnlockRequest,
   type ComputerElementSemanticAction,
@@ -48,6 +50,10 @@ const DESKTOP_ELEMENT_OBSERVE_ACTION = 'desktop_element_observe';
 const DESKTOP_ELEMENT_ACTION_ACTION = 'desktop_element_action';
 export const COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION = 'console_unlock_prepare';
 export const COMPUTER_CONSOLE_UNLOCK_ACTION = 'console_unlock';
+export const COMPUTER_CONSOLE_UNLOCK_ENROLL_ACTION = 'console_unlock_enroll';
+export const COMPUTER_CONSOLE_UNLOCK_STATUS_ACTION = 'console_unlock_status';
+export const COMPUTER_CONSOLE_UNLOCK_RECOVER_ACTION = 'console_unlock_recover';
+export const COMPUTER_CONSOLE_UNLOCK_REVOKE_ACTION = 'console_unlock_revoke';
 const DEFAULT_CONSOLE_UNLOCK_TIMEOUT_MS = 15_000;
 const MAX_CONSOLE_UNLOCK_TIMEOUT_MS = 30_000;
 const CONSOLE_CREDENTIAL_HANDLE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -69,6 +75,10 @@ const DESKTOP_PRODUCT_ACTION_IDS = new Set([
   DESKTOP_ELEMENT_ACTION_ACTION,
   COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION,
   COMPUTER_CONSOLE_UNLOCK_ACTION,
+  COMPUTER_CONSOLE_UNLOCK_ENROLL_ACTION,
+  COMPUTER_CONSOLE_UNLOCK_STATUS_ACTION,
+  COMPUTER_CONSOLE_UNLOCK_RECOVER_ACTION,
+  COMPUTER_CONSOLE_UNLOCK_REVOKE_ACTION,
 ]);
 
 function providerActionDescriptor(actionId: string): AssistantPluginActionDescriptor {
@@ -178,6 +188,31 @@ export async function executeProtectedConsoleUnlockInvocation(
   };
 }
 
+export async function executeProtectedConsoleUnlockLifecycle(
+  action: 'console_unlock_enroll' | 'console_unlock_status' | 'console_unlock_recover' | 'console_unlock_revoke',
+  input: ProtectedConsoleUnlockPreparationInput,
+  controllerHome: string,
+): Promise<Record<string, unknown>> {
+  requireConsoleUnlockAuthorization(input.confirmAuthorization);
+  const invocationId = randomUUID();
+  const request: ComputerConsoleUnlockCommandRequest = {
+    capability: COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+    action,
+  };
+  const providerResult = await executeRuntimeComputerConsoleUnlock(
+    request,
+    { kind: 'explicit_single_use', confirmed: true, invocationId },
+    boundedConsoleUnlockTimeoutMs(input.timeoutMs),
+    controllerHome,
+  );
+  return {
+    capability: COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+    action,
+    invocationId,
+    ...providerResult,
+  };
+}
+
 function desktopProductActions(): AssistantPluginActionDescriptor[] {
   const open = providerActionDescriptor('desktop_session_open');
   const close = providerActionDescriptor('desktop_session_close');
@@ -240,6 +275,70 @@ function desktopProductActions(): AssistantPluginActionDescriptor[] {
         additionalProperties: false,
       },
     },
+    {
+      actionId: COMPUTER_CONSOLE_UNLOCK_ENROLL_ACTION,
+      title: 'Enable unattended console recovery',
+      description: 'Enroll provider-local unattended console recovery. Credential collection and Keychain persistence remain entirely inside the native provider.',
+      readOnly: false,
+      risk: 'workspace_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: DEFAULT_CONSOLE_UNLOCK_TIMEOUT_MS,
+      cancellable: true,
+      idempotent: false,
+      executionMode: 'direct_non_persistent',
+      foregroundEffect: 'required',
+      scopes: ['console.unlock'],
+      resourceClaims: [],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: COMPUTER_CONSOLE_UNLOCK_STATUS_ACTION,
+      title: 'Read unattended console recovery status',
+      description: 'Read whether provider-local unattended console recovery is enrolled and available without exposing credential material.',
+      readOnly: true,
+      risk: 'readonly',
+      confirmation: 'authorization',
+      defaultTimeoutMs: DEFAULT_CONSOLE_UNLOCK_TIMEOUT_MS,
+      cancellable: true,
+      idempotent: true,
+      executionMode: 'direct_non_persistent',
+      foregroundEffect: 'none',
+      scopes: ['console.unlock'],
+      resourceClaims: [],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: COMPUTER_CONSOLE_UNLOCK_RECOVER_ACTION,
+      title: 'Recover locked macOS console',
+      description: 'Recover an already-locked console using only the provider-local enrolled credential. No password or credential handle enters Forge.',
+      readOnly: false,
+      risk: 'workspace_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: DEFAULT_CONSOLE_UNLOCK_TIMEOUT_MS,
+      cancellable: true,
+      idempotent: false,
+      executionMode: 'direct_non_persistent',
+      foregroundEffect: 'required',
+      scopes: ['console.unlock'],
+      resourceClaims: [],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+      actionId: COMPUTER_CONSOLE_UNLOCK_REVOKE_ACTION,
+      title: 'Disable unattended console recovery',
+      description: 'Delete the provider-local unattended console recovery credential and disable future recovery.',
+      readOnly: false,
+      risk: 'workspace_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: DEFAULT_CONSOLE_UNLOCK_TIMEOUT_MS,
+      cancellable: true,
+      idempotent: true,
+      executionMode: 'direct_non_persistent',
+      foregroundEffect: 'none',
+      scopes: ['console.unlock'],
+      resourceClaims: [],
+      argumentsSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
     {
       actionId: DESKTOP_ELEMENT_OBSERVE_ACTION,
       title: 'Observe Computer elements',
@@ -318,7 +417,7 @@ function desktopProductPermissions(ready: boolean): AssistantPluginPermissionSco
     { scope: 'desktop.observe', mode: 'read', description: 'Observe bounded desktop accessibility state.', granted: ready, required: false },
     { scope: 'desktop.interact', mode: 'write', description: 'Perform bounded semantic desktop interaction.', granted: ready, required: false },
     { scope: 'desktop.capture', mode: 'read', description: 'Capture an authorized desktop target.', granted: ready, required: false },
-    { scope: 'console.unlock', mode: 'write', description: 'Prepare and consume a provider-local console unlock handle.', granted: ready, required: false },
+    { scope: 'console.unlock', mode: 'write', description: 'Use provider-local temporary unlock or explicitly enrolled unattended console recovery.', granted: ready, required: false },
   ];
 }
 
@@ -330,7 +429,7 @@ function desktopProductCapabilities(): AssistantPluginCapability[] {
     { capabilityId: 'computer.capture.v1', title: 'Computer capture', description: 'Capture authorized desktop state.', scopes: ['desktop.capture'], actions: ['desktop_screenshot'] },
     { capabilityId: COMPUTER_ELEMENT_OBSERVE_CAPABILITY, title: 'Computer element observation', description: 'Observe exact provider-neutral semantic element snapshots for a Forge-owned target.', scopes: ['desktop.observe'], actions: [DESKTOP_ELEMENT_OBSERVE_ACTION] },
     { capabilityId: COMPUTER_ELEMENT_ACTION_CAPABILITY, title: 'Computer element action', description: 'Act on exact observed element refs with observation-epoch fencing.', scopes: ['desktop.interact'], actions: [DESKTOP_ELEMENT_ACTION_ACTION] },
-    { capabilityId: COMPUTER_CONSOLE_UNLOCK_CAPABILITY, title: 'Protected console unlock', description: 'Collect console credential material only inside the native provider and consume an opaque one-shot handle without durable replay state.', scopes: ['console.unlock'], actions: [COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION, COMPUTER_CONSOLE_UNLOCK_ACTION] },
+    { capabilityId: COMPUTER_CONSOLE_UNLOCK_CAPABILITY, title: 'Protected console unlock', description: 'Keep console credential material provider-local while supporting temporary one-shot unlock and opt-in unattended recovery.', scopes: ['console.unlock'], actions: [COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION, COMPUTER_CONSOLE_UNLOCK_ACTION, COMPUTER_CONSOLE_UNLOCK_ENROLL_ACTION, COMPUTER_CONSOLE_UNLOCK_STATUS_ACTION, COMPUTER_CONSOLE_UNLOCK_RECOVER_ACTION, COMPUTER_CONSOLE_UNLOCK_REVOKE_ACTION] },
   ];
 }
 
@@ -367,7 +466,6 @@ function buildComputerManifest(
       sourceOfTruth: [
         ...browser.authority.sourceOfTruth,
         'controllerHome:sqlite/computer_interaction_target',
-        'controllerHome:system/plugins/external/registrations/desktop_operator.json',
       ],
     },
     enabled: browser.enabled || desktop?.enabled === true,
@@ -384,15 +482,20 @@ function buildComputerManifest(
       checkedAt,
       ready,
       probed: browser.health.probed || desktop?.health.probed === true,
-      errors: ready ? [] : [...browser.health.errors, ...(desktopSupported ? (desktop?.health.errors ?? (desktop ? [] : ['Native Computer provider is not installed.'])) : [])],
+      errors: ready ? [] : [
+        ...browser.health.errors,
+        ...(desktopSupported && !desktopReady ? ['Native Computer capabilities are unavailable or not ready.'] : []),
+      ],
       warnings: [
         ...browser.health.warnings,
-        ...(desktopSupported ? (desktop?.health.warnings ?? []) : [`Native Desktop Computer capabilities are unsupported on ${platform}.`]),
+        ...(desktopSupported
+          ? (desktopReady ? [] : ['Native Computer capability diagnostics are available through the internal platform provider.'])
+          : [`Native Desktop Computer capabilities are unsupported on ${platform}.`]),
       ],
       details: {
         partial: !ready && partial,
         browser: { ready: browserReady, state: browser.health.state },
-        desktop: { supported: desktopSupported, ready: desktopReady, state: desktop?.health.state ?? (desktopSupported ? 'not_installed' : 'unsupported'), provider: DESKTOP_PROVIDER_ID },
+        desktop: { supported: desktopSupported, ready: desktopReady, state: desktop?.health.state ?? (desktopSupported ? 'not_installed' : 'unsupported') },
       },
     },
     permissions: [...browser.permissions, ...desktopProductPermissions(desktopReady)],
@@ -618,10 +721,12 @@ async function rebindProviderSession(
       { retryable: false, details: { targetId: target.targetId, stableIdentity: target.stableIdentity } },
     );
   }
+  const processId = providerProcessId(rebound);
   lease.bind({
     providerId: DESKTOP_PROVIDER_ID,
     providerSessionId: interactionId,
     observedAt: new Date().toISOString(),
+    ...(processId !== undefined ? { processId } : {}),
   });
   return interactionId;
 }
@@ -638,6 +743,55 @@ async function ensureProviderBinding(
   return rebindProviderSession(input, lease, provider);
 }
 
+function providerProcessId(result: Record<string, unknown>): number | undefined {
+  const value = result.pid ?? result.process_id;
+  if (value === undefined) return undefined;
+  if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0 || value > 2_147_483_647) {
+    throw new AssistantPluginError(
+      'PLUGIN_COMPUTER_TARGET_PROCESS_ID_INVALID',
+      'Native Computer provider returned an invalid application process identifier.',
+      { retryable: false, details: { processId: value } },
+    );
+  }
+  return value;
+}
+
+function explicitLaunchProvenanceFromProviderResult(
+  result: Record<string, unknown>,
+  processId: number | undefined,
+): ComputerApplicationLaunchProvenance | undefined {
+  const rawOwnership = result.applicationOwnership ?? result.application_ownership;
+  const rawOwnedPid = result.ownedProcessIdentifier ?? result.owned_process_identifier;
+  if (rawOwnership === undefined && rawOwnedPid === undefined) return undefined;
+  if (rawOwnership === 'preexisting' && rawOwnedPid === undefined) return { kind: 'preexisting' };
+  if (rawOwnership === 'provider_launched'
+      && typeof rawOwnedPid === 'number'
+      && Number.isInteger(rawOwnedPid)
+      && rawOwnedPid > 0
+      && rawOwnedPid <= 2_147_483_647
+      && processId === rawOwnedPid) {
+    return { kind: 'provider_launched', processId: rawOwnedPid };
+  }
+  throw new AssistantPluginError(
+    'PLUGIN_COMPUTER_TARGET_LAUNCH_PROVENANCE_INVALID',
+    'Native Computer provider returned inconsistent application launch provenance.',
+    { retryable: false, details: { applicationOwnership: rawOwnership, ownedProcessIdentifier: rawOwnedPid, processId } },
+  );
+}
+
+function inheritedLaunchProvenance(
+  controllerHome: string,
+  processId: number | undefined,
+): ComputerApplicationLaunchProvenance | undefined {
+  if (processId === undefined) return undefined;
+  const owner = computerTargetAuthority.listAllApplications(controllerHome).find((target) =>
+    target.launchProvenance?.kind === 'provider_launched'
+    && target.launchProvenance.processId === processId
+    && target.providerBinding?.processId === processId,
+  );
+  return owner ? { kind: 'provider_launched', processId } : undefined;
+}
+
 function stableIdentityFromProviderResult(
   result: Record<string, unknown>,
   requested: ComputerApplicationStableIdentity,
@@ -689,10 +843,35 @@ async function openDesktopTarget(
     }
     throw error;
   }
+  let processId: number | undefined;
+  let explicitProvenance: ComputerApplicationLaunchProvenance | undefined;
   try {
+    processId = providerProcessId(opened);
+    explicitProvenance = explicitLaunchProvenanceFromProviderResult(opened, processId);
+  } catch (error) {
+    try {
+      await provider.executeAction(providerInput(input, 'desktop_session_close', { interaction_id: interactionId }, 'target-open-provenance-compensate'));
+    } catch (cleanupError) {
+      throw new AssistantPluginError('PLUGIN_COMPUTER_TARGET_LAUNCH_PROVENANCE_CLEANUP_UNKNOWN', 'Computer target launch provenance was invalid and provider-session cleanup could not be confirmed.', {
+        retryable: false,
+        details: { cause: error instanceof Error ? error.message : String(error), cleanupCause: cleanupError instanceof Error ? cleanupError.message : String(cleanupError) },
+      });
+    }
+    throw error;
+  }
+  try {
+    const launchProvenance = explicitProvenance?.kind === 'provider_launched'
+      ? explicitProvenance
+      : inheritedLaunchProvenance(input.controllerHome, processId) ?? explicitProvenance;
     const target = computerTargetAuthority.create(input.controllerHome, {
       stableIdentity,
-      providerBinding: { providerId: DESKTOP_PROVIDER_ID, providerSessionId: interactionId, observedAt: new Date().toISOString() },
+      ...(launchProvenance ? { launchProvenance } : {}),
+      providerBinding: {
+        providerId: DESKTOP_PROVIDER_ID,
+        providerSessionId: interactionId,
+        observedAt: new Date().toISOString(),
+        ...(processId !== undefined ? { processId } : {}),
+      },
     });
     return {
       targetId: target.targetId,
@@ -730,7 +909,27 @@ async function closeDesktopTarget(
         );
       }
       if (provider) {
-        await provider.executeAction(providerInput(input, 'desktop_session_close', { interaction_id: target.providerBinding.providerSessionId }, 'target-close-provider'));
+        const activeTargets = computerTargetAuthority.listAllApplications(input.controllerHome);
+        const anotherActiveTargetUsesBinding = activeTargets.some((candidate) =>
+          candidate.targetId !== target.targetId
+          && candidate.providerBinding?.providerId === target.providerBinding?.providerId
+          && candidate.providerBinding?.providerSessionId === target.providerBinding?.providerSessionId,
+        );
+        if (!anotherActiveTargetUsesBinding) {
+          const ownedProcessId = target.launchProvenance?.kind === 'provider_launched'
+            ? target.launchProvenance.processId
+            : undefined;
+          const anotherActiveTargetUsesOwnedProcess = ownedProcessId !== undefined
+            && activeTargets.some((candidate) =>
+              candidate.targetId !== target.targetId && candidate.providerBinding?.processId === ownedProcessId,
+            );
+          await provider.executeAction(providerInput(input, 'desktop_session_close', {
+            interaction_id: target.providerBinding.providerSessionId,
+            ...(ownedProcessId !== undefined && !anotherActiveTargetUsesOwnedProcess
+              ? { terminate_owned_pid: ownedProcessId }
+              : {}),
+          }, 'target-close-provider'));
+        }
       }
       // A missing registration is authoritative absence only because provider uninstall
       // must stop/remove its native lifecycle before the registration is deleted.
@@ -796,7 +995,7 @@ function targetAuthorization(identity: ComputerApplicationStableIdentity): Assis
 }
 
 async function resolveDesktopAuthorizationContext(input: AssistantPluginActionExecutionInput): Promise<AssistantPluginAuthorizationContext | undefined> {
-  if (input.actionId === COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION || input.actionId === COMPUTER_CONSOLE_UNLOCK_ACTION) return undefined;
+  if ([COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION, COMPUTER_CONSOLE_UNLOCK_ACTION, COMPUTER_CONSOLE_UNLOCK_ENROLL_ACTION, COMPUTER_CONSOLE_UNLOCK_STATUS_ACTION, COMPUTER_CONSOLE_UNLOCK_RECOVER_ACTION, COMPUTER_CONSOLE_UNLOCK_REVOKE_ACTION].includes(input.actionId)) return undefined;
   if (input.actionId === DESKTOP_TARGET_OPEN_ACTION) return targetAuthorization(stableIdentityFromArgs(input.args));
   const targetId = typeof input.args.target_id === 'string' ? input.args.target_id.trim() : '';
   if (targetId) return targetAuthorization(computerTargetAuthority.require(input.controllerHome, targetId).stableIdentity);
@@ -819,15 +1018,27 @@ export const computerPluginAdapter: AssistantPluginAdapter = {
       return executeBrowserPluginAction({ ...input, pluginId: 'browser' });
     }
     if (input.actionId === COMPUTER_CONSOLE_UNLOCK_PREPARE_ACTION) {
-      return executeProtectedConsoleUnlockPreparation({ confirmAuthorization: true, timeoutMs: input.timeoutMs }, input.controllerHome);
+      return executeProtectedConsoleUnlockPreparation({ confirmAuthorization: input.confirmAuthorization === true, timeoutMs: input.timeoutMs }, input.controllerHome);
     }
     if (input.actionId === COMPUTER_CONSOLE_UNLOCK_ACTION) {
       return executeProtectedConsoleUnlockInvocation({
         credentialHandle: typeof input.args.credential_handle === 'string' ? input.args.credential_handle : '',
-        confirmAuthorization: true,
+        confirmAuthorization: input.confirmAuthorization === true,
         timeoutMs: input.timeoutMs,
       }, input.controllerHome);
     }
+    if (input.actionId === COMPUTER_CONSOLE_UNLOCK_ENROLL_ACTION) {
+      return executeProtectedConsoleUnlockLifecycle('console_unlock_enroll', { confirmAuthorization: input.confirmAuthorization === true, timeoutMs: input.timeoutMs }, input.controllerHome);
+    }
+    if (input.actionId === COMPUTER_CONSOLE_UNLOCK_STATUS_ACTION) {
+      return executeProtectedConsoleUnlockLifecycle('console_unlock_status', { confirmAuthorization: input.confirmAuthorization === true, timeoutMs: input.timeoutMs }, input.controllerHome);
+    }
+    if (input.actionId === COMPUTER_CONSOLE_UNLOCK_RECOVER_ACTION) {
+      return executeProtectedConsoleUnlockLifecycle('console_unlock_recover', { confirmAuthorization: input.confirmAuthorization === true, timeoutMs: input.timeoutMs }, input.controllerHome);
+    }
+    if (input.actionId === COMPUTER_CONSOLE_UNLOCK_REVOKE_ACTION) {
+      return executeProtectedConsoleUnlockLifecycle('console_unlock_revoke', { confirmAuthorization: input.confirmAuthorization === true, timeoutMs: input.timeoutMs }, input.controllerHome);
+    }
     if (input.actionId === DESKTOP_TARGET_CLOSE_ACTION) return closeDesktopTarget(input, optionalDesktopProvider(input));
     const provider = desktopProvider(input);
     if (input.actionId === DESKTOP_TARGET_OPEN_ACTION) return openDesktopTarget(input, provider);

package/src/runtime/plugins/desktop-operator-external-policy.ts

@@ -178,14 +178,46 @@ async function observeDesktopPointerTarget(
   return { frame, point, ...(reboundSelector ? { reboundSelector } : {}) };
 }
 
+function focusedAxNodes(root: Record<string, unknown> | undefined): Record<string, unknown>[] {
+  if (!root) return [];
+  const focused: Record<string, unknown>[] = [];
+  const visit = (node: Record<string, unknown>): void => {
+    if (node.focused === true) focused.push(node);
+    for (const child of recordArray(node.children)) visit(child);
+  };
+  visit(root);
+  return focused;
+}
+
 function exactFocusedDesktopWindowId(observation: Record<string, unknown>): number | undefined {
   const snapshot = recordValue(observation.snapshot);
   const root = recordValue(snapshot?.root);
-  const focusedAxWindows = recordArray(root?.children).filter((window) =>
-    firstString(window, 'role') === 'AXWindow' && window.focused === true);
-  if (focusedAxWindows.length !== 1) return undefined;
+  const axWindows = recordArray(root?.children).filter((window) => firstString(window, 'role') === 'AXWindow');
+  const explicitFocused = axWindows.filter((window) => window.focused === true);
+  let focusedAxWindow: Record<string, unknown> | undefined;
+  if (explicitFocused.length === 1) {
+    focusedAxWindow = explicitFocused[0];
+  } else if (explicitFocused.length > 1) {
+    return undefined;
+  } else {
+    // Chromium-family apps can expose the system-frontmost window with
+    // AXWindow.focused=false while a descendant/control in that window is the
+    // unique focused AX node. Recover the same window only from unique bounded
+    // geometry; any ambiguity still fails closed.
+    const focusedNodes = focusedAxNodes(root).filter((node) => firstString(node, 'role') !== 'AXApplication');
+    if (focusedNodes.length !== 1) return undefined;
+    const focusedFrame = desktopFrame(focusedNodes[0]?.frame);
+    if (!focusedFrame) return undefined;
+    const point = desktopFrameCenter(focusedFrame);
+    const containingWindows = axWindows.filter((window) => {
+      const frame = desktopFrame(window.frame);
+      return Boolean(frame && frameContainsPoint(frame, point.x, point.y));
+    });
+    if (containingWindows.length !== 1) return undefined;
+    focusedAxWindow = containingWindows[0];
+  }
 
-  const focusedTitle = firstString(focusedAxWindows[0]!, 'title');
+  const focusedTitle = firstString(focusedAxWindow, 'title');
   if (!focusedTitle) return undefined;
   const matches = recordArray(observation.windows).filter((window) => {
     const windowId = firstNumber(window, 'windowId', 'window_id');

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

@@ -9,7 +9,7 @@ import {
 import type { ExternalPluginRegistrationInput } from './external-registration';
 import type { AssistantPluginActionDescriptor } from './types';
 
-const CONTROLLER_WRITE = [{ resource: 'repo-state' as const, mode: 'write' as const }];
+const CONTROLLER_WRITE = [{ resource: 'provider-state' as const, mode: 'write' as const }];
 const SELECTOR_SCHEMA = {
   type: 'object',
   properties: {
@@ -436,10 +436,10 @@ export function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_session_close',
       title: 'Close desktop session',
-      description: 'Close one Desktop Operator interaction session without terminating the target application.',
+      description: 'Close one Desktop Operator interaction session. Application termination is disabled by default and requires an exact Controller-owned process id.',
       readOnly: false,
       risk: 'workspace_write',
-      confirmation: 'none',
+      confirmation: 'authorization',
       defaultTimeoutMs: 5_000,
       cancellable: true,
       idempotent: true,
@@ -447,7 +447,15 @@ export function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
       resourceClaims: CONTROLLER_WRITE,
       argumentsSchema: {
         type: 'object',
-        properties: { interaction_id: { type: 'string' } },
+        properties: {
+          interaction_id: { type: 'string' },
+          terminate_owned_pid: {
+            type: 'integer',
+            minimum: 1,
+            maximum: 2_147_483_647,
+            description: 'Exact provider-launched process id that the durable Computer target authority has decided is no longer used by another active target.',
+          },
+        },
         required: ['interaction_id'],
         additionalProperties: false,
       },

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

@@ -1,5 +1,5 @@
 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';
@@ -149,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,
@@ -185,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,
   });
 }
@@ -256,13 +269,36 @@ function externalProviderPolicyContext(
   };
 }
 
+interface ExternalPluginAdapterSnapshot {
+  registrationSetIdentity: string;
+  adapters: readonly AssistantPluginAdapter[];
+  byPluginId: ReadonlyMap<string, AssistantPluginAdapter>;
+}
+
+const externalPluginAdapterSnapshots = new Map<string, ExternalPluginAdapterSnapshot>();
+
+function externalPluginAdapterSnapshot(controllerHome: string): ExternalPluginAdapterSnapshot {
+  const registrationSetIdentity = externalPluginRegistrationSetIdentity(controllerHome);
+  const cached = externalPluginAdapterSnapshots.get(controllerHome);
+  if (cached?.registrationSetIdentity === registrationSetIdentity) return cached;
+
+  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(

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';
@@ -98,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);

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

@@ -7,6 +7,7 @@ import type {
   AssistantPluginPermissionScope,
 } from './types';
 import { AssistantPluginError } from './errors';
+import { importStoredGoogleClientSecretFromClipboard } from '../safe-tooling/google-credential-store';
 import {
   type GmailPluginConfig,
   encodeBase64Url,
@@ -127,6 +128,24 @@ function gmailActions(): AssistantPluginActionDescriptor[] {
         additionalProperties: false,
       },
     },
+    {
+      actionId: 'import_oauth_client_secret_from_clipboard',
+      title: 'Import Gmail OAuth client secret',
+      description: 'Consume the current macOS clipboard once, store the OAuth client secret in Keychain, clear the clipboard, and never return credential material.',
+      readOnly: false,
+      risk: 'workspace_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: 10_000,
+      cancellable: false,
+      idempotent: false,
+      scopes: ['gmail.readonly'],
+      resourceClaims: [{ resource: 'provider-state', mode: 'write' }],
+      argumentsSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    },
     {
       actionId: 'list_messages',
       title: 'List Gmail messages',
@@ -668,7 +687,7 @@ function gmailProvider(config: GmailPluginConfig, repoRoot?: string): GmailProvi
 export function buildGmailPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
   const config = loadGmailPluginConfig(root, context);
-  const auth = resolveGoogleAuth('gmail', config, { repoRoot: root });
+  const auth = resolveGoogleAuth('gmail', config, { repoRoot: root, controllerHome: context?.controllerHome });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
     schemaVersion: 1,
@@ -714,9 +733,11 @@ export async function executeGmailPluginAction(input: AssistantPluginActionExecu
       });
       return {
         config,
-        auth: resolveGoogleAuth('gmail', config, { repoRoot: input.repoRoot }),
+        auth: resolveGoogleAuth('gmail', config, { repoRoot: input.repoRoot, controllerHome: input.controllerHome }),
       };
     }
+    case 'import_oauth_client_secret_from_clipboard':
+      return importStoredGoogleClientSecretFromClipboard('gmail');
     case 'list_messages':
       return gmailProvider(current, input.repoRoot).listMessages(input.args, current);
     case 'get_message':

package/src/runtime/plugins/google-calendar-adapter.ts

@@ -394,7 +394,7 @@ function calendarProvider(config: GoogleCalendarPluginConfig, repoRoot?: string)
 export function buildGoogleCalendarPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
   const config = loadGoogleCalendarPluginConfig(root, context);
-  const auth = resolveGoogleAuth('calendar', config, { repoRoot: root });
+  const auth = resolveGoogleAuth('calendar', config, { repoRoot: root, controllerHome: context?.controllerHome });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
     schemaVersion: 1,
@@ -441,7 +441,7 @@ export async function executeGoogleCalendarPluginAction(input: AssistantPluginAc
       });
       return {
         config,
-        auth: resolveGoogleAuth('calendar', config, { repoRoot: input.repoRoot }),
+        auth: resolveGoogleAuth('calendar', config, { repoRoot: input.repoRoot, controllerHome: input.controllerHome }),
       };
     }
     case 'list_events':