@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,178 +1,47 @@
 import { spawnSync } from 'child_process';
 import { existsSync } from 'fs';
-import { createConnection, type Socket } from 'net';
-import { dirname, isAbsolute, join, resolve } from 'path';
+import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import {
+  callExternalUnixJsonl,
+  decodeExternalUnixJsonlResponse,
+  ExternalUnixJsonlTransportError,
+  normalizeExternalUnixJsonlCall,
+  type ExternalUnixJsonlCallOptions,
+  type ExternalUnixJsonlMethod,
+} from '../../../packages/plugin-runtime/external/index';
 import { resolveBunExecutable } from '../shared/process-environment';
 import { AssistantPluginError } from './errors';
 
-const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_HEALTH_TIMEOUT_MS = 2_000;
-const DEFAULT_MAX_REQUEST_BYTES = 1_048_576;
-const DEFAULT_MAX_RESPONSE_BYTES = 1_048_576;
-const MAX_TIMEOUT_MS = 120_000;
 const MAX_DIAGNOSTIC_CHARS = 4_000;
 
-export type ExternalUnixSocketMethod = 'handshake' | 'manifest' | 'health' | 'execute' | 'macos_browser_automation';
-
-export interface ExternalUnixSocketCallOptions {
-  socketPath: string;
-  requestId: string;
-  method: ExternalUnixSocketMethod;
-  params?: Record<string, unknown>;
-  timeoutMs?: number;
-  maxRequestBytes?: number;
-  maxResponseBytes?: number;
-  signal?: AbortSignal;
-}
-
-interface RpcSuccess {
-  id: string;
-  ok: true;
-  result: unknown;
-}
-
-interface RpcFailure {
-  id: string;
-  ok: false;
-  error: {
-    code: string;
-    message: string;
-    retryable?: boolean;
-    domain?: string;
-    details?: unknown;
-  };
-}
-
-type RpcResponse = RpcSuccess | RpcFailure;
-
-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);
-}
+export type ExternalUnixSocketMethod = ExternalUnixJsonlMethod;
+export interface ExternalUnixSocketCallOptions extends ExternalUnixJsonlCallOptions {}
 
 function transportError(code: string, message: string, options: { retryable?: boolean; details?: Record<string, unknown> } = {}): AssistantPluginError {
   return new AssistantPluginError(code, message.slice(0, 1_000), { retryable: options.retryable ?? true, details: options.details });
 }
 
-function validateSocketPath(socketPath: string): string {
-  const normalized = socketPath.trim();
-  if (!normalized || !isAbsolute(normalized)) throw transportError('EXTERNAL_PLUGIN_SOCKET_PATH_INVALID', 'External provider socket path must be absolute.', { retryable: false });
-  return normalized;
-}
-
-function requestEnvelope(options: ExternalUnixSocketCallOptions): string {
-  const envelope = JSON.stringify({ id: options.requestId, method: options.method, params: options.params ?? {} });
-  const maxRequestBytes = boundedInteger(options.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, 1_024, 4 * DEFAULT_MAX_REQUEST_BYTES);
-  if (Buffer.byteLength(envelope, 'utf8') > maxRequestBytes) {
-    throw transportError('EXTERNAL_PLUGIN_REQUEST_TOO_LARGE', 'External provider request exceeded the bounded input limit.', { retryable: false });
-  }
-  return `${envelope}\n`;
-}
-
-function parseRpcResponse(raw: string, requestId: string): unknown {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw transportError('EXTERNAL_PLUGIN_PROTOCOL_ERROR', 'External provider returned invalid JSON.');
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw transportError('EXTERNAL_PLUGIN_PROTOCOL_ERROR', 'External provider returned an invalid response envelope.');
-  }
-  const response = parsed as Partial<RpcResponse>;
-  if (response.id !== requestId || typeof response.ok !== 'boolean') {
-    throw transportError('EXTERNAL_PLUGIN_PROTOCOL_ERROR', 'External provider returned a mismatched response id or status.');
-  }
-  if (response.ok === true) return (response as RpcSuccess).result;
-  const failure = response as RpcFailure;
-  if (!failure.error || typeof failure.error.code !== 'string' || typeof failure.error.message !== 'string') {
-    throw transportError('EXTERNAL_PLUGIN_PROTOCOL_ERROR', 'External provider returned an invalid structured error.');
+function toAssistantPluginError(error: unknown): AssistantPluginError {
+  if (error instanceof AssistantPluginError) return error;
+  if (error instanceof ExternalUnixJsonlTransportError) {
+    return new AssistantPluginError(error.code, error.detailMessage, {
+      retryable: error.retryable,
+      effectOutcome: error.effectOutcome,
+      details: error.details,
+    });
   }
-  throw new AssistantPluginError(failure.error.code, failure.error.message, {
-    retryable: failure.error.retryable === true,
-    details: {
-      ...(typeof failure.error.domain === 'string' ? { domain: failure.error.domain } : {}),
-      ...(failure.error.details && typeof failure.error.details === 'object' && !Array.isArray(failure.error.details)
-        ? { providerDetails: failure.error.details as Record<string, unknown> }
-        : {}),
-    },
-  });
-}
-
-function normalizeResult(value: unknown): Record<string, unknown> {
-  if (value && typeof value === 'object' && !Array.isArray(value)) return value as Record<string, unknown>;
-  return { value };
-}
-
-function timeoutFor(options: ExternalUnixSocketCallOptions, health = false): number {
-  return boundedInteger(options.timeoutMs, health ? DEFAULT_HEALTH_TIMEOUT_MS : DEFAULT_TIMEOUT_MS, 100, MAX_TIMEOUT_MS);
+  return transportError('EXTERNAL_PLUGIN_TRANSPORT_FAILED', error instanceof Error ? error.message : String(error));
 }
 
 export async function callExternalUnixSocket(
   options: ExternalUnixSocketCallOptions,
 ): Promise<Record<string, unknown>> {
-  const socketPath = validateSocketPath(options.socketPath);
-  const envelope = requestEnvelope(options);
-  if (options.signal?.aborted) throw transportError('EXTERNAL_PLUGIN_ABORTED', 'External provider request was cancelled before connection.');
-  const timeoutMs = timeoutFor(options, options.method === 'health' || options.method === 'handshake' || options.method === 'manifest');
-  const maxResponseBytes = boundedInteger(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, 1_024, 4 * DEFAULT_MAX_RESPONSE_BYTES);
-
-  return await new Promise<Record<string, unknown>>((resolve, reject) => {
-    let socket: Socket | undefined;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let settled = false;
-    let buffer = Buffer.alloc(0);
-
-    const cleanup = (): void => {
-      if (timer) clearTimeout(timer);
-      options.signal?.removeEventListener('abort', onAbort);
-      if (socket && !socket.destroyed) socket.destroy();
-    };
-    const finish = (callback: () => void): void => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      callback();
-    };
-    const fail = (error: unknown): void => finish(() => reject(error instanceof AssistantPluginError
-      ? error
-      : transportError('EXTERNAL_PLUGIN_TRANSPORT_FAILED', error instanceof Error ? error.message : String(error))));
-    const succeed = (value: unknown): void => finish(() => resolve(normalizeResult(value)));
-    const onAbort = (): void => fail(transportError('EXTERNAL_PLUGIN_ABORTED', 'External provider request was cancelled.'));
-
-    timer = setTimeout(() => fail(transportError('EXTERNAL_PLUGIN_TIMEOUT', `External provider request timed out after ${timeoutMs}ms.`)), timeoutMs);
-    timer.unref?.();
-    options.signal?.addEventListener('abort', onAbort, { once: true });
-
-    try {
-      socket = createConnection({ path: socketPath });
-    } catch (error) {
-      fail(error);
-      return;
-    }
-    socket.once('connect', () => socket?.write(envelope));
-    socket.on('data', (chunk: Buffer) => {
-      if (settled) return;
-      if (buffer.length + chunk.length > maxResponseBytes) {
-        fail(transportError('EXTERNAL_PLUGIN_RESPONSE_TOO_LARGE', 'External provider response exceeded the bounded output limit.', { retryable: false }));
-        return;
-      }
-      buffer = Buffer.concat([buffer, chunk]);
-      const newline = buffer.indexOf(0x0A);
-      if (newline < 0) return;
-      const raw = buffer.subarray(0, newline).toString('utf8');
-      try {
-        succeed(parseRpcResponse(raw, options.requestId));
-      } catch (error) {
-        fail(error);
-      }
-    });
-    socket.once('error', (error) => fail(transportError('EXTERNAL_PLUGIN_SOCKET_UNAVAILABLE', error.message)));
-    socket.once('end', () => {
-      if (!settled) fail(transportError('EXTERNAL_PLUGIN_PROTOCOL_ERROR', 'External provider closed the socket before returning a complete response.'));
-    });
-  });
+  try {
+    return await callExternalUnixJsonl(options);
+  } catch (error) {
+    throw toAssistantPluginError(error);
+  }
 }
 
 export function resolveExternalPluginProbeSidecarPath(
@@ -203,42 +72,44 @@ export function resolveExternalPluginProbeRuntime(
 export function probeExternalUnixSocketSync(
   options: ExternalUnixSocketCallOptions,
 ): Record<string, unknown> {
-  validateSocketPath(options.socketPath);
-  const sidecarPath = resolveExternalPluginProbeSidecarPath();
-  const probeRuntime = resolveExternalPluginProbeRuntime();
-  const timeoutMs = timeoutFor(options, true);
-  const input = JSON.stringify({
-    socketPath: options.socketPath,
-    requestId: options.requestId,
-    method: options.method,
-    params: options.params ?? {},
-    timeoutMs,
-    maxRequestBytes: boundedInteger(options.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, 1_024, 4 * DEFAULT_MAX_REQUEST_BYTES),
-    maxResponseBytes: boundedInteger(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, 1_024, 4 * DEFAULT_MAX_RESPONSE_BYTES),
-  });
-  const execution = spawnSync(probeRuntime, [sidecarPath], {
-    input,
-    encoding: 'utf8',
-    timeout: timeoutMs + 1_000,
-    maxBuffer: boundedInteger(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, 1_024, 4 * DEFAULT_MAX_RESPONSE_BYTES) + 16_384,
-    env: Object.fromEntries(Object.entries({
-      PATH: process.env.PATH,
-      HOME: process.env.HOME,
-      TMPDIR: process.env.TMPDIR,
-      TEMP: process.env.TEMP,
-      TMP: process.env.TMP,
-      LANG: process.env.LANG,
-      LC_ALL: process.env.LC_ALL,
-      FORGE_EXTERNAL_PLUGIN_PROBE: '1',
-    }).filter((entry): entry is [string, string] => typeof entry[1] === 'string')),
-    shell: false,
-    windowsHide: true,
-  });
-  if (execution.error) throw transportError('EXTERNAL_PLUGIN_PROBE_FAILED', execution.error.message);
-  if (execution.status !== 0) {
-    const diagnostic = String(execution.stderr || execution.stdout || '').slice(-MAX_DIAGNOSTIC_CHARS);
-    throw transportError('EXTERNAL_PLUGIN_PROBE_FAILED', diagnostic || `Probe sidecar exited with status ${String(execution.status)}.`);
+  try {
+    const normalized = normalizeExternalUnixJsonlCall(options, true);
+    const sidecarPath = resolveExternalPluginProbeSidecarPath();
+    const probeRuntime = resolveExternalPluginProbeRuntime();
+    const input = JSON.stringify({
+      socketPath: normalized.socketPath,
+      requestId: normalized.requestId,
+      method: normalized.method,
+      params: normalized.params,
+      timeoutMs: normalized.timeoutMs,
+      maxRequestBytes: normalized.maxRequestBytes,
+      maxResponseBytes: normalized.maxResponseBytes,
+    });
+    const execution = spawnSync(probeRuntime, [sidecarPath], {
+      input,
+      encoding: 'utf8',
+      timeout: normalized.timeoutMs + 1_000,
+      maxBuffer: normalized.maxResponseBytes + 16_384,
+      env: Object.fromEntries(Object.entries({
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        TMPDIR: process.env.TMPDIR,
+        TEMP: process.env.TEMP,
+        TMP: process.env.TMP,
+        LANG: process.env.LANG,
+        LC_ALL: process.env.LC_ALL,
+        FORGE_EXTERNAL_PLUGIN_PROBE: '1',
+      }).filter((entry): entry is [string, string] => typeof entry[1] === 'string')),
+      shell: false,
+      windowsHide: true,
+    });
+    if (execution.error) throw transportError('EXTERNAL_PLUGIN_PROBE_FAILED', execution.error.message);
+    if (execution.status !== 0) {
+      const diagnostic = String(execution.stderr || execution.stdout || '').slice(-MAX_DIAGNOSTIC_CHARS);
+      throw transportError('EXTERNAL_PLUGIN_PROBE_FAILED', diagnostic || `Probe sidecar exited with status ${String(execution.status)}.`);
+    }
+    return decodeExternalUnixJsonlResponse(String(execution.stdout ?? '').trim(), normalized.requestId);
+  } catch (error) {
+    throw toAssistantPluginError(error);
   }
-  const raw = String(execution.stdout ?? '').trim();
-  return normalizeResult(parseRpcResponse(raw, options.requestId));
 }

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

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, isAbsolute, join, resolve } from 'path';
+import { createDesktopOperatorRegistrationInput } from './desktop-operator-registration';
+import {
+  getExternalPluginRegistration,
+  installExternalPluginRegistration,
+  type ExternalPluginRegistration,
+  type ExternalPluginUnixSocketTransport,
+} from './external-registration';
+
+function isForgeDesktopOperatorBinding(
+  registration: ExternalPluginRegistration,
+): registration is ExternalPluginRegistration & { transport: ExternalPluginUnixSocketTransport } {
+  return registration.pluginId === 'desktop_operator'
+    && registration.providerPluginId === 'desktop_operator'
+    && registration.provider === 'local-macos'
+    && registration.scope === 'controller'
+    && registration.transport.kind === 'unix_socket_jsonl';
+}
+
+const DESKTOP_OPERATOR_BUNDLE_ID = 'com.moretea.forge.desktop-operator';
+const DESKTOP_OPERATOR_APP_NAME = 'Forge Desktop Operator.app';
+
+interface DesktopOperatorInstallReceipt {
+  schemaVersion: 1;
+  pluginId: string;
+  pluginVersion: string;
+  protocolVersion: string;
+  socketPath: string;
+  executablePath: string;
+  manifestPath: string;
+  serviceManager: string;
+  bundleIdentifier: string;
+  launchAgentLabel: string;
+  expectedProgramContains: string;
+}
+
+interface DesktopOperatorInstalledManifest {
+  id?: unknown;
+  version?: unknown;
+  protocolVersion?: unknown;
+}
+
+export interface FirstPartyExternalRegistrationReconcileOptions {
+  /** Test/repair seams only. Production uses the stable provider-owned installation paths. */
+  desktopOperatorInstallReceiptPath?: string;
+  desktopOperatorCanonicalSocketPath?: string;
+  desktopOperatorCanonicalExecutablePath?: string;
+}
+
+function canonicalDesktopOperatorSocketPath(): string {
+  return join(homedir(), 'Library', 'Caches', 'Forge', 'desktop-operator.sock');
+}
+
+function canonicalDesktopOperatorExecutablePath(): string {
+  return join(homedir(), 'Applications', DESKTOP_OPERATOR_APP_NAME, 'Contents', 'MacOS', 'desktop-operator');
+}
+
+function defaultDesktopOperatorInstallReceiptPath(): string {
+  return join(homedir(), 'Library', 'Application Support', 'Forge', 'DesktopOperator', 'registration', 'registration.json');
+}
+
+function parseJsonObject(path: string, code: string): Record<string, unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`${code}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(code);
+  return value as Record<string, unknown>;
+}
+
+function installedDesktopOperatorReleaseIdentity(
+  existing: ExternalPluginRegistration & { transport: ExternalPluginUnixSocketTransport },
+  options: FirstPartyExternalRegistrationReconcileOptions,
+): { pluginVersion: string; protocolVersion: string } | undefined {
+  const lifecycle = existing.lifecycle?.kind === 'verified_user_launch_agent' ? existing.lifecycle : undefined;
+  if (!lifecycle) return undefined;
+
+  const expectedSocketPath = options.desktopOperatorCanonicalSocketPath?.trim() || canonicalDesktopOperatorSocketPath();
+  const expectedExecutablePath = options.desktopOperatorCanonicalExecutablePath?.trim() || canonicalDesktopOperatorExecutablePath();
+  // Only the stable first-party installation may contribute release metadata.
+  // Synthetic/custom registrations keep their existing version authority.
+  if (!isAbsolute(expectedSocketPath)
+    || !isAbsolute(expectedExecutablePath)
+    || resolve(existing.transport.socketPath) !== resolve(expectedSocketPath)
+    || lifecycle.label !== DESKTOP_OPERATOR_BUNDLE_ID
+    || !isAbsolute(lifecycle.expectedProgramContains)
+    || resolve(lifecycle.expectedProgramContains) !== resolve(expectedExecutablePath)) return undefined;
+
+  const receiptPath = resolve(options.desktopOperatorInstallReceiptPath?.trim() || defaultDesktopOperatorInstallReceiptPath());
+  if (!existsSync(receiptPath)) return undefined;
+  const raw = parseJsonObject(receiptPath, 'DESKTOP_OPERATOR_INSTALL_RECEIPT_INVALID');
+  const receipt = raw as unknown as DesktopOperatorInstallReceipt;
+
+  // The receipt is evidence for installed release metadata only. It may never
+  // replace the already-trusted endpoint or lifecycle identity.
+  if (receipt.schemaVersion !== 1
+    || receipt.pluginId !== 'desktop_operator'
+    || typeof receipt.pluginVersion !== 'string' || !receipt.pluginVersion.trim()
+    || typeof receipt.protocolVersion !== 'string' || !receipt.protocolVersion.trim()
+    || typeof receipt.socketPath !== 'string'
+    || resolve(receipt.socketPath) !== resolve(existing.transport.socketPath)
+    || receipt.bundleIdentifier !== DESKTOP_OPERATOR_BUNDLE_ID
+    || receipt.launchAgentLabel !== lifecycle.label
+    || typeof receipt.expectedProgramContains !== 'string' || !receipt.expectedProgramContains.trim()
+    || receipt.serviceManager !== 'launchd-user-agent'
+    || typeof receipt.executablePath !== 'string'
+    || !isAbsolute(receipt.executablePath)
+    || resolve(receipt.executablePath) !== resolve(lifecycle.expectedProgramContains)
+    || !receipt.executablePath.includes(receipt.expectedProgramContains)
+    || !receipt.executablePath.endsWith(`/${DESKTOP_OPERATOR_APP_NAME}/Contents/MacOS/desktop-operator`)
+    || typeof receipt.manifestPath !== 'string'
+    || resolve(receipt.manifestPath) !== resolve(join(dirname(receiptPath), 'forge-plugin.json'))) {
+    throw new Error('DESKTOP_OPERATOR_INSTALL_RECEIPT_IDENTITY_MISMATCH');
+  }
+
+  const manifest = parseJsonObject(receipt.manifestPath, 'DESKTOP_OPERATOR_INSTALLED_MANIFEST_INVALID') as DesktopOperatorInstalledManifest;
+  if (manifest.id !== 'desktop_operator'
+    || manifest.version !== receipt.pluginVersion
+    || manifest.protocolVersion !== receipt.protocolVersion) {
+    throw new Error('DESKTOP_OPERATOR_INSTALLED_MANIFEST_IDENTITY_MISMATCH');
+  }
+  return { pluginVersion: receipt.pluginVersion, protocolVersion: receipt.protocolVersion };
+}
+
+/**
+ * Reconcile one installed first-party external provider to the current Forge-owned
+ * policy contract while preserving installation/runtime identity. The external
+ * registration store remains the only persistence, fingerprint and revision
+ * authority; this layer only materializes desired state from current source.
+ */
+export function reconcileFirstPartyExternalPluginRegistration(
+  controllerHome: string,
+  pluginId: string,
+  options: FirstPartyExternalRegistrationReconcileOptions = {},
+): ExternalPluginRegistration | undefined {
+  const existing = getExternalPluginRegistration(controllerHome, pluginId);
+  if (!existing) return undefined;
+  if (pluginId !== 'desktop_operator' || !isForgeDesktopOperatorBinding(existing)) return existing;
+
+  const lifecycle = existing.lifecycle?.kind === 'verified_user_launch_agent'
+    ? existing.lifecycle
+    : undefined;
+  const installedRelease = installedDesktopOperatorReleaseIdentity(existing, options);
+  const desired = createDesktopOperatorRegistrationInput({
+    socketPath: existing.transport.socketPath,
+    launchAgentLabel: lifecycle?.label,
+    expectedProgramContains: lifecycle?.expectedProgramContains,
+    pluginVersion: installedRelease?.pluginVersion ?? existing.pluginVersion,
+    protocolVersion: installedRelease?.protocolVersion ?? existing.protocolVersion,
+    enabled: existing.enabled,
+  });
+  return installExternalPluginRegistration(controllerHome, desired);
+}
+
+/** Reconcile every currently installed first-party external provider. */
+export function reconcileFirstPartyExternalPluginRegistrations(controllerHome: string): ExternalPluginRegistration[] {
+  const desktop = reconcileFirstPartyExternalPluginRegistration(controllerHome, 'desktop_operator');
+  return desktop ? [desktop] : [];
+}

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

@@ -1,5 +1,6 @@
 import { appStoreConnectPluginAdapter } from './app-store-connect-adapter';
-import { browserPluginAdapter } from './browser-adapter';
+import { browserPluginAdapter } from './browser-registration';
+import { computerPluginAdapter } from './computer-registration';
 import { githubPluginAdapter } from './github-adapter';
 import { gmailPluginAdapter } from './gmail-adapter';
 import { googleCalendarPluginAdapter } from './google-calendar-adapter';
@@ -13,6 +14,7 @@ import type { AssistantPluginAdapter } from './types';
 
 const FIRST_PARTY_PLUGIN_ADAPTERS: readonly AssistantPluginAdapter[] = [
   githubPluginAdapter,
+  computerPluginAdapter,
   browserPluginAdapter,
   appStoreConnectPluginAdapter,
   iosPluginAdapter,

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

@@ -1,7 +1,6 @@
 import {
   closeIssueWithGitHubPlugin,
   getGitHubPluginStatus,
-  githubPluginConfigPath,
   loadGitHubPluginConfig,
   publishIssueWithGitHubPlugin,
   refreshIssueWithGitHubPlugin,
@@ -295,7 +294,7 @@ export function buildGitHubPluginManifest(previousRevision = 0, previousUpdatedA
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: ['repository-registry:github', `repo-local:${githubPluginConfigPath()}`],
+      sourceOfTruth: ['repository-registry:github', 'legacy-import-only:.forge/plugins/github.json'],
     },
     enabled: config.enabled,
     lifecycle: {

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

@@ -1,15 +1,16 @@
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginManifest,
   AssistantPluginPermissionScope,
 } from './types';
 import { AssistantPluginError } from './errors';
+import { importStoredGoogleClientSecretFromClipboard } from '../safe-tooling/google-credential-store';
 import {
   type GmailPluginConfig,
   encodeBase64Url,
-  gmailPluginConfigPath,
   googleApiRequest,
   googlePermission,
   loadGmailPluginConfig,
@@ -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',
@@ -665,10 +684,10 @@ function gmailProvider(config: GmailPluginConfig, repoRoot?: string): GmailProvi
   return config.provider === 'mock' ? mockGmailProvider() : liveGmailProvider(config, repoRoot);
 }
 
-export function buildGmailPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
+export function buildGmailPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
-  const config = loadGmailPluginConfig(root);
-  const auth = resolveGoogleAuth('gmail', config, { repoRoot: root });
+  const config = loadGmailPluginConfig(root, context);
+  const auth = resolveGoogleAuth('gmail', config, { repoRoot: root, controllerHome: context?.controllerHome });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
     schemaVersion: 1,
@@ -681,7 +700,7 @@ export function buildGmailPluginManifest(previousRevision = 0, previousUpdatedAt
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: [`repo-local:${gmailPluginConfigPath()}`, 'env:FORGE_*_ACCESS_TOKEN'],
+      sourceOfTruth: ['controller-home:repositories/<repoId>/plugins/config/gmail.json', 'env:FORGE_*_ACCESS_TOKEN'],
     },
     enabled: config.enabled,
     lifecycle: {
@@ -701,11 +720,11 @@ export function buildGmailPluginManifest(previousRevision = 0, previousUpdatedAt
 }
 
 export async function executeGmailPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const current = loadGmailPluginConfig(input.repoRoot);
+  const current = loadGmailPluginConfig(input.repoRoot, input);
   switch (input.actionId) {
     case 'configure': {
       const args = input.args;
-      const config = saveGmailPluginConfig(input.repoRoot, {
+      const config = saveGmailPluginConfig(input, {
         enabled: typeof args.enabled === 'boolean' ? args.enabled : current.enabled,
         provider: args.provider === 'google-workspace' ? 'google-workspace' : args.provider === 'mock' ? 'mock' : current.provider,
         accountEmail: args.clear_account_email === true ? undefined : stringValue(args.account_email) ?? current.accountEmail,
@@ -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

@@ -1,6 +1,7 @@
 import type {
   AssistantPluginActionDescriptor,
   AssistantPluginActionExecutionInput,
+  AssistantPluginBuildContext,
   AssistantPluginCapability,
   AssistantPluginManifest,
   AssistantPluginPermissionScope,
@@ -9,7 +10,6 @@ import { AssistantPluginError } from './errors';
 import {
   type GoogleCalendarPluginConfig,
   googleApiRequest,
-  googleCalendarPluginConfigPath,
   googlePermission,
   loadGoogleCalendarPluginConfig,
   pluginStateFromGoogleAuth,
@@ -391,10 +391,10 @@ function calendarProvider(config: GoogleCalendarPluginConfig, repoRoot?: string)
   return config.provider === 'mock' ? mockCalendarProvider() : liveCalendarProvider(config, repoRoot);
 }
 
-export function buildGoogleCalendarPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string): AssistantPluginManifest {
+export function buildGoogleCalendarPluginManifest(previousRevision = 0, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest {
   const root = repoRoot ?? process.cwd();
-  const config = loadGoogleCalendarPluginConfig(root);
-  const auth = resolveGoogleAuth('calendar', config, { repoRoot: root });
+  const config = loadGoogleCalendarPluginConfig(root, context);
+  const auth = resolveGoogleAuth('calendar', config, { repoRoot: root, controllerHome: context?.controllerHome });
   const state = pluginStateFromGoogleAuth(config, auth);
   return {
     schemaVersion: 1,
@@ -407,7 +407,7 @@ export function buildGoogleCalendarPluginManifest(previousRevision = 0, previous
     authority: {
       strategy: 'derived',
       duplicateStateAllowed: false,
-      sourceOfTruth: [`repo-local:${googleCalendarPluginConfigPath()}`, 'env:FORGE_*_ACCESS_TOKEN'],
+      sourceOfTruth: ['controller-home:repositories/<repoId>/plugins/config/google-calendar.json', 'env:FORGE_*_ACCESS_TOKEN'],
     },
     enabled: config.enabled,
     lifecycle: {
@@ -427,11 +427,11 @@ export function buildGoogleCalendarPluginManifest(previousRevision = 0, previous
 }
 
 export async function executeGoogleCalendarPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
-  const current = loadGoogleCalendarPluginConfig(input.repoRoot);
+  const current = loadGoogleCalendarPluginConfig(input.repoRoot, input);
   switch (input.actionId) {
     case 'configure': {
       const args = input.args;
-      const config = saveGoogleCalendarPluginConfig(input.repoRoot, {
+      const config = saveGoogleCalendarPluginConfig(input, {
         enabled: typeof args.enabled === 'boolean' ? args.enabled : current.enabled,
         provider: args.provider === 'google-workspace' ? 'google-workspace' : args.provider === 'mock' ? 'mock' : current.provider,
         accountEmail: args.clear_account_email === true ? undefined : stringValue(args.account_email) ?? current.accountEmail,
@@ -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':