@moretea-labs/forge 1.5.1 → 1.6.0

package/src/runtime/model-clients/deepseek-adapter.ts

@@ -104,24 +104,6 @@ export function buildModelControlPlaneSummary(env: NodeJS.ProcessEnv = process.e
 
 export function deepSeekFunctionToolManifest(): Array<Record<string, unknown>> {
   return [
-    {
-      type: 'function',
-      function: {
-        name: 'forge_web_target_snapshot',
-        description: 'Create a read-only snapshot for a pre-allowed web target by target_key and path. Does not accept arbitrary URLs.',
-        parameters: {
-          type: 'object',
-          properties: {
-            target_key: { type: 'string' },
-            path: { type: 'string' },
-            capture: { type: 'string', enum: ['title', 'text', 'screenshot'] },
-            max_chars: { type: 'number' },
-          },
-          required: ['target_key'],
-          additionalProperties: false,
-        },
-      },
-    },
     {
       type: 'function',
       function: {
@@ -267,20 +249,6 @@ export function prepareDeepSeekToolCall(functionName: string, functionArguments:
     opaquePayloadAccepted: false as const,
   };
   switch (functionName) {
-    case 'forge_web_target_snapshot':
-      return {
-        provider: 'deepseek',
-        accepted: true,
-        functionName,
-        mappedOperation: 'web_target_snapshot',
-        mappedArguments: {
-          target_key: functionArguments.target_key,
-          path: functionArguments.path,
-          capture: functionArguments.capture,
-          max_chars: functionArguments.max_chars,
-        },
-        safety,
-      };
     case 'forge_plugin_config_summary':
       return {
         provider: 'deepseek',

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

@@ -69,7 +69,6 @@ interface BrowserPluginConfig {
   nativeAttachMode?: BrowserNativeAttachMode;
   nativeBrowserCandidates?: MacOsBrowserProduct[];
   defaultTimeoutMs?: number;
-  allowedDomains?: string[];
 }
 
 interface BrowserTabResumeState {
@@ -130,7 +129,6 @@ type BrowserContextLike = {
   pages(): PageLike[];
   newPage(): Promise<PageLike>;
   close(): Promise<void>;
-  route(pattern: string, handler: (route: RouteLike) => Promise<void> | void): Promise<void>;
 };
 
 type BrowserLike = {
@@ -168,13 +166,6 @@ type PageLike = {
   keyboard?: { press(key: string): Promise<void> };
 };
 
-type RequestLike = { url(): string };
-type RouteLike = {
-  request(): RequestLike;
-  continue(): Promise<void>;
-  abort(errorCode?: string): Promise<void>;
-};
-
 type PlaywrightRuntime = {
   chromium: {
     launchPersistentContext(userDataDir: string, options: Record<string, unknown>): Promise<BrowserContextLike>;
@@ -280,13 +271,6 @@ function browserProductList(value: unknown): MacOsBrowserProduct[] | undefined {
   return normalized.length > 0 ? Array.from(new Set(normalized)) : undefined;
 }
 
-function stringArray(value: unknown): string[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const normalized = value
-    .map((entry) => String(entry).trim().toLowerCase())
-    .filter(Boolean);
-  return normalized.length > 0 ? Array.from(new Set(normalized)) : undefined;
-}
 
 function stringList(value: unknown): string[] | undefined {
   if (!Array.isArray(value)) return undefined;
@@ -362,7 +346,6 @@ function normalizeConfig(raw: Partial<BrowserPluginConfig>): BrowserPluginConfig
     nativeAttachMode: browserNativeAttachMode(raw.nativeAttachMode) ?? 'auto',
     nativeBrowserCandidates: browserProductList(raw.nativeBrowserCandidates) ?? ['vivaldi', 'chrome'],
     defaultTimeoutMs: typeof raw.defaultTimeoutMs === 'number' ? positiveNumber(raw.defaultTimeoutMs, DEFAULT_TIMEOUT_MS) : undefined,
-    allowedDomains: stringArray(raw.allowedDomains),
   };
 }
 
@@ -383,9 +366,9 @@ function loadConfig(repoRoot: string): BrowserPluginConfig {
   return normalizeConfig(readJson<Partial<BrowserPluginConfig>>(configPath(repoRoot)) ?? {});
 }
 
-export function readBrowserPluginConfiguration(repoRoot: string): { enabled: boolean; allowedDomains: string[] } {
+export function readBrowserPluginConfiguration(repoRoot: string): { enabled: boolean } {
   const config = loadConfig(repoRoot);
-  return { enabled: config.enabled, allowedDomains: [...(config.allowedDomains ?? [])] };
+  return { enabled: config.enabled };
 }
 
 function saveConfig(repoRoot: string, patch: Partial<BrowserPluginConfig>): BrowserPluginConfig {
@@ -429,27 +412,6 @@ function normalizedUrl(value: unknown): string {
   return parsed.toString();
 }
 
-function isRemoteHttpUrl(url: string): boolean {
-  try {
-    const parsed = new URL(url);
-    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
-  } catch {
-    return false;
-  }
-}
-
-function isUrlAllowed(url: string, config: BrowserPluginConfig): boolean {
-  if (!config.allowedDomains || config.allowedDomains.length === 0) return true;
-  if (!isRemoteHttpUrl(url)) return true;
-  const hostname = new URL(url).hostname.toLowerCase();
-  return config.allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
-}
-
-function assertUrlAllowed(url: string, config: BrowserPluginConfig): void {
-  if (isUrlAllowed(url, config)) return;
-  const hostname = new URL(url).hostname.toLowerCase();
-  throw new AssistantPluginError('PLUGIN_POLICY_BLOCKED', `Domain is not allowed: ${hostname}`, { retryable: false });
-}
 
 function waitUntil(value: unknown): WaitUntil {
   return value === 'load' || value === 'networkidle' || value === 'domcontentloaded' ? value : 'domcontentloaded';
@@ -561,9 +523,6 @@ function validateConfig(config: BrowserPluginConfig): string[] {
 
 function configWarnings(config: BrowserPluginConfig): string[] {
   const warnings: string[] = [];
-  if (!config.allowedDomains || config.allowedDomains.length === 0) {
-    warnings.push('allowedDomains is empty; browser actions can target any domain.');
-  }
   if (config.profileMode === 'custom') {
     warnings.push('Custom profile mode uses the configured browser profile directly. If the browser reports the profile is in use, fully close the matching browser instance first.');
     if (!config.executablePath && (config.browserChannel ?? 'chromium') === 'chromium') {
@@ -695,17 +654,6 @@ async function delay(ms: number): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function applyDomainGuard(context: BrowserContextLike, config: BrowserPluginConfig): Promise<void> {
-  if (!config.allowedDomains || config.allowedDomains.length === 0) return;
-  await context.route('**/*', async (route) => {
-    const url = route.request().url();
-    if (isUrlAllowed(url, config)) {
-      await route.continue();
-      return;
-    }
-    await route.abort('blockedbyclient');
-  });
-}
 
 function selectedProfile(config: BrowserPluginConfig, repoRoot: string, activeMode: BrowserMode = 'managed_persistent', sessionId?: string): BrowserProfileSelection {
   if (activeMode === 'isolated') {
@@ -848,6 +796,14 @@ function comparableUrl(value: string): string {
   }
 }
 
+function sameOrigin(left: string, right: string): boolean {
+  try {
+    return new URL(left).origin === new URL(right).origin;
+  } catch {
+    return false;
+  }
+}
+
 function isBlankPage(url: string): boolean {
   return !url || url === 'about:blank' || url === 'chrome://newtab/';
 }
@@ -1103,7 +1059,6 @@ async function openManagedContext(
   assertBrowserProfileAvailable(repoRoot, profile.selectedProfilePath);
   mkdirSync(profile.profileDir, { recursive: true });
   const context = await runtime.chromium.launchPersistentContext(profile.profileDir, launchOptionsForRepo(repoRoot, config, profile));
-  await applyDomainGuard(context, config);
   const selected = await selectPage(context, target);
   const timeout = positiveNumber(args.timeout_ms, config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS);
   let response: { status?: () => number } | null | undefined;
@@ -1168,7 +1123,6 @@ async function openAttachedContext(
       try {
         const context = browser.contexts()[0] ?? (browser.newContext ? await browser.newContext() : undefined);
         if (!context) throw new Error('CDP connection did not expose a browser context.');
-        await applyDomainGuard(context, config);
         const selected = await selectPage(context, target, { allowBlank: false, allowNewPage: false, requireOwnedToken: true });
       const timeout = positiveNumber(args.timeout_ms, config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS);
       let response: { status?: () => number } | null | undefined;
@@ -1275,7 +1229,11 @@ async function openNativeAttachedContext(
     }
     if (comparableUrl(page.url()) !== comparableUrl(target.url)) {
       const currentRef = (page as unknown as { tabRef?: () => MacOsBrowserTabRef | undefined }).tabRef?.();
-      if (!currentRef) {
+      const sessionTargetUnchanged = Boolean(target.existingSession?.url) && comparableUrl(target.url) === comparableUrl(target.existingSession?.url ?? '');
+      const preserveOwnedSameOriginDrift = matchedBy === 'owned_token' && sessionTargetUnchanged && sameOrigin(page.url(), target.url);
+      if (preserveOwnedSameOriginDrift) {
+        sessionResume = { sessionId: target.sessionId, status: 'matched', reason: 'Plugin-owned tab navigated within the same origin; preserved the live tab and refreshed its session URL.', savedTab };
+      } else if (!currentRef) {
         await page.goto(target.url, { waitUntil: waitUntil(args.wait_until), timeout });
       } else {
         const replacement = await createMacOsBrowserOwnedPage(discovered.attachment, target.url, timeout) as unknown as PageLike;
@@ -1292,7 +1250,6 @@ async function openNativeAttachedContext(
       await page.waitForLoadState(waitUntil(args.wait_until), { timeout });
     }
     const pageUrl = normalizedUrl(page.url());
-    assertUrlAllowed(pageUrl, config);
     const nativeRef = (page as unknown as { tabRef?: () => MacOsBrowserTabRef | undefined }).tabRef?.();
     if (!nativeRef) throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_OWNERSHIP_MISSING', 'Native browser did not return a stable plugin-owned tab reference.', { retryable: true });
     const title = matchedBy === 'owned_token' ? (target.existingSession?.title ?? '') : '';
@@ -1386,7 +1343,6 @@ async function withPage<T>(
   run: (page: PageLike, diagnostics: PageDiagnostics, connection: BrowserConnectionSummary) => Promise<T>,
   options: { persistSession?: boolean } = {},
 ): Promise<T> {
-  assertUrlAllowed(target.url, config);
   const retries = Math.min(Math.max(positiveNumber(args.retries, 1), 1), 3);
   let lastError: unknown;
   for (let attempt = 1; attempt <= retries; attempt += 1) {
@@ -1396,7 +1352,6 @@ async function withPage<T>(
       const result = await run(handle.page, handle.diagnostics, handle.connection);
       if (options.persistSession) {
         const identity = await readPageIdentity(handle.page, handle.connection);
-        assertUrlAllowed(identity.url, config);
         saveSession(repoRoot, sessionFromPage(target, identity.url, identity.title, handle.connection));
       }
       return result;
@@ -1590,7 +1545,6 @@ async function finalizeInteractiveAction(
   const identity = await readPageIdentity(page, connection);
   const title = identity.title;
   const pageUrl = identity.url;
-  assertUrlAllowed(pageUrl, config);
   const session = sessionFromPage(target, pageUrl, title, connection);
   saveSession(repoRoot, session);
   let screenshot: BrowserActionScreenshot | undefined;
@@ -1671,7 +1625,7 @@ function capabilities(): AssistantPluginCapability[] {
     {
       capabilityId: 'browser-interaction',
       title: 'Browser Interaction',
-      description: 'Perform explicit form and pointer interactions on allowed domains through the persistent Playwright profile.',
+      description: 'Perform explicit form and pointer interactions on HTTP(S) pages through the persistent Playwright profile.',
       scopes: ['browser.interact', 'browser.profile'],
       actions: [
         'click', 'double_click', 'hover', 'focus', 'type', 'fill', 'select_option',
@@ -1749,8 +1703,6 @@ function actions(): AssistantPluginActionDescriptor[] {
           native_attach_mode: { type: 'string', enum: ['auto', 'disabled'] },
           native_browser_candidates: { type: 'array', items: { type: 'string', enum: ['vivaldi', 'chrome'] }, maxItems: 2 },
           default_timeout_ms: { type: 'number' },
-          allowed_domains: { type: 'array', items: { type: 'string' } },
-          clear_allowed_domains: { type: 'boolean' },
         },
         additionalProperties: false,
       },
@@ -1758,7 +1710,7 @@ function actions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'create_session',
       title: 'Create browser session',
-      description: 'Open an allowed URL and persist a reusable session id.',
+      description: 'Open an HTTP(S) URL and persist a reusable session id.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
       scopes: ['browser.read', 'browser.profile'], resourceClaims: [{ resource: 'repo-state', mode: 'write' }, ...readRemote],
       argumentsSchema: sessionTargetSchema({ extract_text: { type: 'boolean' }, max_chars: { type: 'number' } }, ['url']),
@@ -1826,7 +1778,7 @@ function actions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'open_page',
       title: 'Open page',
-      description: 'Open an allowed URL with the persistent profile and save a lightweight session.',
+      description: 'Open an HTTP(S) URL with the persistent profile and save a lightweight session.',
       readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
       scopes: ['browser.read'], resourceClaims: readRemote,
       argumentsSchema: sessionTargetSchema({ extract_text: { type: 'boolean' }, max_chars: { type: 'number' } }, ['url']),
@@ -1834,7 +1786,7 @@ function actions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'navigate',
       title: 'Navigate',
-      description: 'Navigate an existing session or open a new page to an allowed URL.',
+      description: 'Navigate an existing session or open a new page to an HTTP(S) URL.',
       readOnly: true, risk: 'readonly', confirmation: 'none', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
       scopes: ['browser.read'], resourceClaims: readRemote,
       argumentsSchema: sessionTargetSchema({}, ['url']),
@@ -2089,7 +2041,6 @@ function browserUserFacingStatus(config: BrowserPluginConfig, ready: boolean, se
   if (!config.enabled) return 'disabled';
   if (!ready) return 'not ready';
   if (sessionCount > 0) return 'session active';
-  if (config.allowedDomains && config.allowedDomains.length > 0) return 'domain restricted';
   return 'ready';
 }
 
@@ -2212,7 +2163,6 @@ function health(config: BrowserPluginConfig, repoRoot?: string): AssistantPlugin
     details: {
       ...baseDetails,
       nativeAttachObservation: nativeObservation,
-      allowedDomains: config.allowedDomains,
       provider: config.browserMode === 'attach_preferred'
         ? 'cdp-or-macos-active-browser-or-persistent-context'
         : 'playwright-persistent-context',
@@ -2310,7 +2260,6 @@ export async function executeBrowserPluginAction(input: AssistantPluginActionExe
           defaultTimeoutMs: typeof args.default_timeout_ms === 'number'
             ? positiveNumber(args.default_timeout_ms, DEFAULT_TIMEOUT_MS)
             : current.defaultTimeoutMs,
-          allowedDomains: args.clear_allowed_domains === true ? undefined : stringArray(args.allowed_domains) ?? current.allowedDomains,
         });
         const configErrors = validateConfig(config);
         if (configErrors.length > 0) {
@@ -2366,7 +2315,6 @@ export async function executeBrowserPluginAction(input: AssistantPluginActionExe
       }
       case 'request_human_handoff': {
         const target = resolveActionTarget(input.repoRoot, input.args);
-        assertUrlAllowed(target.url, current);
         const nativeSession = target.existingSession;
         const nativeTab = nativeSession?.browser?.tab;
         const nativeBrowser = nativeSession?.browser?.provider === 'macos-apple-events'
@@ -2398,7 +2346,6 @@ export async function executeBrowserPluginAction(input: AssistantPluginActionExe
           profileDirectory: profile.profileDirectory,
           browserChannel: current.browserChannel,
           executablePath: current.executablePath ? resolveConfiguredPath(input.repoRoot, current.executablePath) : undefined,
-          allowedDomains: current.allowedDomains,
           defaultTimeoutMs: current.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS,
           nativeBrowser,
           reason: stringValue(input.args.reason) ?? 'manual_review',

package/src/runtime/plugins/browser-handoff-host.ts

@@ -19,16 +19,10 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function hostnameAllowed(hostname: string, allowedDomains?: string[]): boolean {
-  if (!allowedDomains || allowedDomains.length === 0) return true;
-  const normalized = hostname.toLowerCase();
-  return allowedDomains.some((domain) => normalized === domain || normalized.endsWith(`.${domain}`));
-}
-
-function assertAllowed(url: string, allowedDomains?: string[]): void {
+function assertHttpUrl(url: string): void {
   const parsed = new URL(url);
-  if (!['http:', 'https:'].includes(parsed.protocol) || !hostnameAllowed(parsed.hostname, allowedDomains)) {
-    throw new Error(`URL is outside the browser handoff allowlist: ${url}`);
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Browser handoff only supports HTTP(S) URLs: ${url}`);
   }
 }
 
@@ -105,7 +99,7 @@ async function runNativeHandoff(specPath: string, spec: BrowserHandoffLaunchSpec
       if (resume) {
         removeInteractionCommand(spec.repoRoot, 'browser', spec.interactionId, 'resume');
         metadata = await readMacOsBrowserOwnedTabMetadata(native.product, native.ref, spec.defaultTimeoutMs);
-        assertAllowed(metadata.url, spec.allowedDomains);
+        assertHttpUrl(metadata.url);
         const existing = existsSync(spec.sessionPath)
           ? readJsonFile<Record<string, unknown>>(spec.sessionPath, {})
           : {};
@@ -146,7 +140,7 @@ async function main(): Promise<void> {
   const specPath = process.argv[2];
   if (!specPath) throw new Error('browser handoff launch spec path is required');
   const spec = readJsonFile<BrowserHandoffLaunchSpec>(specPath);
-  assertAllowed(spec.url, spec.allowedDomains);
+  assertHttpUrl(spec.url);
   if (spec.nativeBrowser) {
     await runNativeHandoff(specPath, spec);
     return;
@@ -166,11 +160,6 @@ async function main(): Promise<void> {
           title(): Promise<string>;
           bringToFront?(): Promise<void>;
         }>;
-        route(pattern: string, handler: (route: {
-          request(): { url(): string };
-          continue(): Promise<void>;
-          abort(errorCode?: string): Promise<void>;
-        }) => Promise<void> | void): Promise<void>;
         close(): Promise<void>;
       }>;
     };
@@ -205,20 +194,6 @@ async function main(): Promise<void> {
 
   try {
     context = await playwright.chromium.launchPersistentContext(spec.profileDir, launchOptions);
-    await context.route('**/*', async (route) => {
-      const requestUrl = route.request().url();
-      try {
-        const parsed = new URL(requestUrl);
-        if (['http:', 'https:'].includes(parsed.protocol) && !hostnameAllowed(parsed.hostname, spec.allowedDomains)) {
-          await route.abort('blockedbyclient');
-          return;
-        }
-      } catch {
-        await route.abort('blockedbyclient');
-        return;
-      }
-      await route.continue();
-    });
     let page = context.pages()[0] ?? await context.newPage();
     await page.goto(spec.url, { waitUntil: 'domcontentloaded', timeout: spec.defaultTimeoutMs });
     if (page.bringToFront) await page.bringToFront();
@@ -263,7 +238,7 @@ async function main(): Promise<void> {
       const resume = readInteractionCommand(spec.repoRoot, 'browser', spec.interactionId, 'resume');
       if (resume) {
         removeInteractionCommand(spec.repoRoot, 'browser', spec.interactionId, 'resume');
-        assertAllowed(page.url(), spec.allowedDomains);
+        assertHttpUrl(page.url());
         const existing = existsSync(spec.sessionPath)
           ? readJsonFile<Record<string, unknown>>(spec.sessionPath, {})
           : {};

package/src/runtime/plugins/browser-handoff.ts

@@ -38,7 +38,6 @@ export interface BrowserHandoffLaunchSpec {
   profileDirectory?: string;
   browserChannel?: string;
   executablePath?: string;
-  allowedDomains?: string[];
   defaultTimeoutMs: number;
   nativeBrowser?: { product: MacOsBrowserProduct; ref: MacOsBrowserTabRef };
   expiresAt: string;
@@ -57,7 +56,6 @@ export interface BrowserHandoffStartInput {
   profileDirectory?: string;
   browserChannel?: string;
   executablePath?: string;
-  allowedDomains?: string[];
   defaultTimeoutMs: number;
   nativeBrowser?: { product: MacOsBrowserProduct; ref: MacOsBrowserTabRef };
   reason: string;
@@ -326,7 +324,6 @@ export async function startBrowserHandoff(input: BrowserHandoffStartInput): Prom
     profileDirectory: input.profileDirectory,
     browserChannel: input.browserChannel,
     executablePath: input.executablePath,
-    allowedDomains: input.allowedDomains,
     defaultTimeoutMs: input.defaultTimeoutMs,
     nativeBrowser: input.nativeBrowser,
     expiresAt,

package/src/runtime/plugins/browser-macos-bridge.ts

@@ -735,6 +735,14 @@ export class MacOsAppleEventsPage {
       if (this.targetRef) {
         try {
           const metadata = await this.refreshMetadata();
+          const transitionalUrl = !metadata.url
+            || metadata.url === 'about:blank'
+            || metadata.url === 'chrome://newtab/'
+            || metadata.url === 'vivaldi://newtab/';
+          if (transitionalUrl) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            continue;
+          }
           if (metadata.loading === false) return;
         } catch {
           // Fall through to DOM readiness when native loading metadata is unavailable.

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 in the background and create a bounded interaction session without stealing foreground focus.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -83,7 +83,6 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
           bundle_id: { type: 'string' },
           app_name: { type: 'string' },
           launch: { type: 'boolean' },
-          activate: { type: 'boolean' },
         },
         anyOf: [{ required: ['bundle_id'] }, { required: ['app_name'] }],
         additionalProperties: false,
@@ -119,7 +118,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 +132,6 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
         properties: {
           interaction_id: { type: 'string' },
           selector: SELECTOR_SCHEMA,
-          coordinate_fallback: { type: 'boolean' },
-          force_coordinate: { type: 'boolean' },
         },
         required: ['interaction_id', 'selector'],
         additionalProperties: false,
@@ -143,7 +140,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 +164,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 +179,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 +219,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 +238,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 +257,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',

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/first-party-registry.ts

@@ -1,12 +1,12 @@
 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 type { AssistantPluginAdapter } from './types';
 
@@ -20,7 +20,7 @@ const FIRST_PARTY_PLUGIN_ADAPTERS: readonly AssistantPluginAdapter[] = [
   googleTasksPluginAdapter,
   resendPluginAdapter,
   localSystemPluginAdapter,
-  desktopPluginAdapter,
+  pluginManagementAdapter,
 ];
 
 export function listFirstPartyPluginAdapters(): readonly AssistantPluginAdapter[] {