@moretea-labs/forge 1.5.0-rc.1

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

@@ -0,0 +1,322 @@
+import { AssistantPluginError } from './errors';
+import { getExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistration } from './external-registration';
+import { callExternalUnixSocket, probeExternalUnixSocketSync, type ExternalUnixSocketCallOptions } from './external-unix-socket';
+import { executeManagedPluginProcess, executeManagedPluginProcessSync, type ManagedPluginProcessSpec } from './managed-process-adapter';
+import { restartVerifiedUserLaunchAgent, startVerifiedUserLaunchAgent, stopVerifiedUserLaunchAgent } from './local-system-adapter';
+import type { AssistantPluginActionDescriptor, AssistantPluginAdapter, AssistantPluginCapability, AssistantPluginHealth, AssistantPluginManifest, AssistantPluginPermissionScope } from './types';
+
+interface ProviderManifest {
+  id: string;
+  name: string;
+  version: string;
+  protocolVersion: string;
+  mode: string;
+  scope: string;
+  provider: string;
+  capabilities: string[];
+  actions: string[];
+}
+
+interface ProviderHealth {
+  state: string;
+  warnings?: string[];
+  [key: string]: unknown;
+}
+
+export interface ExternalPluginAdapterDependencies {
+  probe?: (options: ExternalUnixSocketCallOptions) => Record<string, unknown>;
+  call?: (options: ExternalUnixSocketCallOptions) => Promise<Record<string, unknown>>;
+  managedProbe?: typeof executeManagedPluginProcessSync;
+  managedCall?: typeof executeManagedPluginProcess;
+  startVerifiedUserLaunchAgent?: (label: unknown, expectedProgram: unknown) => Record<string, unknown>;
+  stopVerifiedUserLaunchAgent?: (label: unknown, expectedProgram: unknown) => Record<string, unknown>;
+  restartVerifiedUserLaunchAgent?: (label: unknown, expectedProgram: unknown) => Record<string, unknown>;
+  now?: () => Date;
+}
+
+function providerError(code: string, message: string, retryable = false): AssistantPluginError {
+  return new AssistantPluginError(code, message, { retryable });
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+function parseProviderManifest(value: Record<string, unknown>, registration: ExternalPluginRegistration): ProviderManifest {
+  const manifest: ProviderManifest = {
+    id: typeof value.id === 'string' ? value.id : '',
+    name: typeof value.name === 'string' ? value.name : '',
+    version: typeof value.version === 'string' ? value.version : '',
+    protocolVersion: typeof value.protocolVersion === 'string' ? value.protocolVersion : '',
+    mode: typeof value.mode === 'string' ? value.mode : '',
+    scope: typeof value.scope === 'string' ? value.scope : '',
+    provider: typeof value.provider === 'string' ? value.provider : '',
+    capabilities: stringArray(value.capabilities),
+    actions: stringArray(value.actions),
+  };
+  if (manifest.id !== registration.providerPluginId) throw providerError('EXTERNAL_PLUGIN_IDENTITY_MISMATCH', `Expected provider plugin ${registration.providerPluginId}, received ${manifest.id || 'unknown'}.`);
+  if (manifest.version !== registration.pluginVersion) throw providerError('EXTERNAL_PLUGIN_VERSION_MISMATCH', `Expected provider version ${registration.pluginVersion}, received ${manifest.version || 'unknown'}.`);
+  if (manifest.protocolVersion !== registration.protocolVersion) throw providerError('EXTERNAL_PLUGIN_PROTOCOL_MISMATCH', `Expected provider protocol ${registration.protocolVersion}, received ${manifest.protocolVersion || 'unknown'}.`);
+  if (manifest.scope !== registration.scope) throw providerError('EXTERNAL_PLUGIN_SCOPE_MISMATCH', `Expected provider scope ${registration.scope}, received ${manifest.scope || 'unknown'}.`);
+  if (manifest.provider !== registration.provider) throw providerError('EXTERNAL_PLUGIN_PROVIDER_MISMATCH', `Expected provider ${registration.provider}, received ${manifest.provider || 'unknown'}.`);
+  const missingActions = registration.actions.map((action) => action.actionId).filter((actionId) => !manifest.actions.includes(actionId));
+  if (missingActions.length > 0) throw providerError('EXTERNAL_PLUGIN_ACTION_MISMATCH', `Provider is missing registered actions: ${missingActions.join(', ')}.`);
+  return manifest;
+}
+
+function healthFromProvider(value: Record<string, unknown>, checkedAt: string): AssistantPluginHealth {
+  const health = value as ProviderHealth;
+  const providerState = typeof health.state === 'string' ? health.state : 'degraded';
+  const state = providerState === 'ready' ? 'ready' : providerState === 'error' ? 'error' : 'degraded';
+  const details = Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !['warnings'].includes(key))
+    .slice(0, 30));
+  return {
+    state,
+    checkedAt,
+    ready: state === 'ready',
+    probed: true,
+    errors: state === 'error' ? ['External provider reported an error health state.'] : [],
+    warnings: stringArray(health.warnings).slice(0, 20),
+    details,
+  };
+}
+
+function failedHealth(error: unknown, checkedAt: string): AssistantPluginHealth {
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    state: 'degraded',
+    checkedAt,
+    ready: false,
+    probed: true,
+    errors: [message.slice(0, 1_000)],
+    warnings: [],
+  };
+}
+
+const EXTERNAL_PROVIDER_LIFECYCLE_ACTIONS = new Set(['provider_start', 'provider_stop', 'provider_restart']);
+
+function lifecyclePolicy(registration: ExternalPluginRegistration): {
+  permissions: AssistantPluginPermissionScope[];
+  capabilities: AssistantPluginCapability[];
+  actions: AssistantPluginActionDescriptor[];
+} {
+  if (!registration.lifecycle) return { permissions: [], capabilities: [], actions: [] };
+  const scope = 'external-provider.lifecycle';
+  const actions: AssistantPluginActionDescriptor[] = [
+    { actionId: 'provider_start', title: 'Start external provider', description: 'Start the registration-bound verified macOS user LaunchAgent for this external provider.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: [scope], resourceClaims: [{ resource: 'repo-state', mode: 'write' }], argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { actionId: 'provider_stop', title: 'Stop external provider', description: 'Stop the registration-bound verified macOS user LaunchAgent for this external provider.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: true, scopes: [scope], resourceClaims: [{ resource: 'repo-state', mode: 'write' }], argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { actionId: 'provider_restart', title: 'Restart external provider', description: 'Restart the registration-bound verified macOS user LaunchAgent for this external provider.', readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 30_000, cancellable: true, idempotent: false, scopes: [scope], resourceClaims: [{ resource: 'repo-state', mode: 'write' }], argumentsSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  ];
+  return {
+    permissions: [{ scope, mode: 'write', description: 'Control only the verified user LaunchAgent bound to this external provider registration.', granted: true, required: false }],
+    capabilities: [{ capabilityId: 'external-provider-lifecycle', title: 'External provider lifecycle', description: 'Start, stop, or restart only the verified macOS user LaunchAgent identity stored in this registration.', scopes: [scope], actions: actions.map((action) => action.actionId) }],
+    actions,
+  };
+}
+
+function socketCallOptions(registration: ExternalPluginRegistration, input: Omit<ExternalUnixSocketCallOptions, 'socketPath' | 'maxRequestBytes' | 'maxResponseBytes'>): ExternalUnixSocketCallOptions {
+  if (registration.transport.kind !== 'unix_socket_jsonl') throw providerError('EXTERNAL_PLUGIN_TRANSPORT_MISMATCH', 'Expected Unix socket transport.', false);
+  return {
+    ...input,
+    socketPath: registration.transport.socketPath,
+    maxRequestBytes: registration.transport.maxRequestBytes,
+    maxResponseBytes: registration.transport.maxResponseBytes,
+  };
+}
+
+function managedSpec(registration: ExternalPluginRegistration): ManagedPluginProcessSpec {
+  if (registration.transport.kind !== 'managed_cli_json') throw providerError('EXTERNAL_PLUGIN_TRANSPORT_MISMATCH', 'Expected managed CLI transport.', false);
+  return {
+    pluginId: registration.providerPluginId,
+    runtimeExecutable: registration.transport.runtimeExecutable,
+    runtimeArgs: registration.transport.runtimeArgs,
+    helperPath: registration.transport.helperPath,
+    cwd: registration.transport.cwd,
+    requiredCapabilities: registration.transport.requiredCapabilities,
+    timeoutMs: registration.transport.actionTimeoutMs,
+    maxRequestBytes: registration.transport.maxRequestBytes,
+    maxResponseBytes: registration.transport.maxResponseBytes,
+  };
+}
+
+function probeProvider(
+  registration: ExternalPluginRegistration,
+  requestId: string,
+  method: 'manifest' | 'health',
+  dependencies: ExternalPluginAdapterDependencies,
+): Record<string, unknown> {
+  if (registration.transport.kind === 'unix_socket_jsonl') {
+    return (dependencies.probe ?? probeExternalUnixSocketSync)(socketCallOptions(registration, {
+      requestId,
+      method,
+      timeoutMs: registration.transport.healthTimeoutMs,
+    }));
+  }
+  return (dependencies.managedProbe ?? executeManagedPluginProcessSync)(managedSpec(registration), {
+    requestId,
+    actionId: method,
+    input: {},
+    timeoutMs: registration.transport.healthTimeoutMs,
+  });
+}
+
+async function callProvider(
+  registration: ExternalPluginRegistration,
+  requestId: string,
+  actionId: string,
+  args: Record<string, unknown>,
+  timeoutMs: number | undefined,
+  signal: AbortSignal | undefined,
+  dependencies: ExternalPluginAdapterDependencies,
+): Promise<Record<string, unknown>> {
+  if (registration.transport.kind === 'unix_socket_jsonl') {
+    const isProviderMethod = actionId === 'manifest' || actionId === 'health';
+    return await (dependencies.call ?? callExternalUnixSocket)(socketCallOptions(registration, {
+      requestId,
+      method: isProviderMethod ? actionId : 'execute',
+      params: isProviderMethod ? undefined : { action: actionId, arguments: args },
+      timeoutMs: timeoutMs ?? (isProviderMethod ? registration.transport.healthTimeoutMs : registration.transport.actionTimeoutMs),
+      signal,
+    }));
+  }
+  return await (dependencies.managedCall ?? executeManagedPluginProcess)(managedSpec(registration), {
+    requestId,
+    actionId,
+    input: args,
+    timeoutMs: timeoutMs ?? (actionId === 'manifest' || actionId === 'health' ? registration.transport.healthTimeoutMs : registration.transport.actionTimeoutMs),
+    signal,
+  });
+}
+
+export function getExternalPluginAdapter(controllerHome: string, pluginId: string): AssistantPluginAdapter | undefined {
+  const registration = getExternalPluginRegistration(controllerHome, pluginId);
+  return registration ? createExternalPluginAdapter(registration) : undefined;
+}
+
+export function listExternalPluginAdapters(controllerHome: string): AssistantPluginAdapter[] {
+  return listExternalPluginRegistrations(controllerHome).map((registration) => createExternalPluginAdapter(registration));
+}
+
+export function createExternalPluginAdapter(
+  registration: ExternalPluginRegistration,
+  dependencies: ExternalPluginAdapterDependencies = {},
+): AssistantPluginAdapter {
+  const startProvider = dependencies.startVerifiedUserLaunchAgent ?? startVerifiedUserLaunchAgent;
+  const stopProvider = dependencies.stopVerifiedUserLaunchAgent ?? stopVerifiedUserLaunchAgent;
+  const restartProvider = dependencies.restartVerifiedUserLaunchAgent ?? restartVerifiedUserLaunchAgent;
+  const now = dependencies.now ?? (() => new Date());
+  const lifecycle = lifecyclePolicy(registration);
+
+  return {
+    pluginId: registration.pluginId,
+    scope: registration.scope,
+    buildManifest(previousRevision = 0, previousUpdatedAt?: string): AssistantPluginManifest {
+      const checkedAt = now().toISOString();
+      if (!registration.enabled) {
+        return {
+          schemaVersion: 1,
+          manifestVersion: 1,
+          revision: Math.max(previousRevision, 1),
+          pluginId: registration.pluginId,
+          provider: registration.provider,
+          displayName: registration.displayName,
+          pluginVersion: registration.pluginVersion,
+          authority: { strategy: 'derived', duplicateStateAllowed: false, sourceOfTruth: [`controllerHome:system/plugins/external/registrations/${registration.pluginId}.json`] },
+          enabled: false,
+          lifecycle: { state: 'disabled', reason: 'External provider registration is disabled.' },
+          health: { state: 'disabled', checkedAt, ready: false, probed: false, errors: [], warnings: [] },
+          permissions: structuredClone([...registration.permissions, ...lifecycle.permissions]),
+          capabilities: structuredClone([...registration.capabilities, ...lifecycle.capabilities]),
+          actions: structuredClone([...registration.actions, ...lifecycle.actions]),
+          updatedAt: previousUpdatedAt ?? checkedAt,
+        };
+      }
+
+      let providerManifest: ProviderManifest | undefined;
+      let health: AssistantPluginHealth;
+      try {
+        providerManifest = parseProviderManifest(probeProvider(
+          registration,
+          `forge-manifest-${registration.pluginId}-${registration.revision}`,
+          'manifest',
+          dependencies,
+        ), registration);
+        health = healthFromProvider(probeProvider(
+          registration,
+          `forge-health-${registration.pluginId}-${registration.revision}`,
+          'health',
+          dependencies,
+        ), checkedAt);
+      } catch (error) {
+        health = failedHealth(error, checkedAt);
+      }
+      const lifecycleState = health.ready ? 'enabled' : health.state === 'error' ? 'error' : 'degraded';
+      return {
+        schemaVersion: 1,
+        manifestVersion: 1,
+        revision: Math.max(previousRevision, 1),
+        pluginId: registration.pluginId,
+        provider: registration.provider,
+        displayName: registration.displayName,
+        pluginVersion: registration.pluginVersion,
+        authority: {
+          strategy: 'derived',
+          duplicateStateAllowed: false,
+          sourceOfTruth: [
+            `controllerHome:system/plugins/external/registrations/${registration.pluginId}.json`,
+            `external-provider:${registration.providerPluginId}@${registration.pluginVersion}`,
+          ],
+        },
+        enabled: true,
+        lifecycle: {
+          state: lifecycleState,
+          reason: health.ready
+            ? 'External provider identity and health are ready.'
+            : providerManifest
+              ? 'External provider identity is valid but health is not ready.'
+              : 'External provider identity/transport could not be verified.',
+        },
+        health,
+        permissions: structuredClone([...registration.permissions, ...lifecycle.permissions]),
+        capabilities: structuredClone([...registration.capabilities, ...lifecycle.capabilities]),
+        actions: structuredClone([...registration.actions, ...lifecycle.actions]),
+        updatedAt: previousUpdatedAt ?? checkedAt,
+      };
+    },
+    async executeAction(input) {
+      if (!registration.enabled) throw providerError('EXTERNAL_PLUGIN_DISABLED', `External provider ${registration.pluginId} is disabled.`);
+      if (EXTERNAL_PROVIDER_LIFECYCLE_ACTIONS.has(input.actionId)) {
+        const bound = registration.lifecycle;
+        if (!bound) throw providerError('EXTERNAL_PLUGIN_LIFECYCLE_NOT_CONFIGURED', `External provider ${registration.pluginId} has no verified lifecycle binding.`);
+        if (input.actionId === 'provider_start') return startProvider(bound.label, bound.expectedProgramContains);
+        if (input.actionId === 'provider_stop') return stopProvider(bound.label, bound.expectedProgramContains);
+        return restartProvider(bound.label, bound.expectedProgramContains);
+      }
+      if (input.providerIdentityPrevalidated !== true) {
+        const providerManifest = await callProvider(
+          registration,
+          `${input.requestId}:manifest`,
+          'manifest',
+          {},
+          undefined,
+          input.signal,
+          dependencies,
+        );
+        parseProviderManifest(providerManifest, registration);
+      }
+      return await callProvider(
+        registration,
+        input.requestId,
+        input.actionId,
+        input.args,
+        input.timeoutMs,
+        input.signal,
+        dependencies,
+      );
+    },
+    shouldRefreshManifestAfterAction(actionId) {
+      return EXTERNAL_PROVIDER_LIFECYCLE_ACTIONS.has(actionId);
+    },
+  };
+}

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

@@ -0,0 +1,308 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readdirSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { controllerSystemRoot, ensureControllerHome } from '../../cli/repositories/controller-home';
+import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
+import type {
+  AssistantPluginActionDescriptor,
+  AssistantPluginCapability,
+  AssistantPluginPermissionScope,
+  AssistantPluginScope,
+} from './types';
+
+const EXTERNAL_REGISTRATION_SCHEMA_VERSION = 1;
+const PLUGIN_ID_PATTERN = /^[a-z][a-z0-9_]{1,63}$/;
+const PROTOCOL_VERSION_PATTERN = /^\d+\.\d+$/;
+
+export interface ExternalPluginUnixSocketTransport {
+  kind: 'unix_socket_jsonl';
+  socketPath: string;
+  maxRequestBytes?: number;
+  maxResponseBytes?: number;
+  healthTimeoutMs?: number;
+  actionTimeoutMs?: number;
+}
+
+export interface ExternalPluginManagedCliTransport {
+  kind: 'managed_cli_json';
+  runtimeExecutable: string;
+  helperPath: string;
+  runtimeArgs?: string[];
+  cwd?: string;
+  requiredCapabilities?: string[];
+  maxRequestBytes?: number;
+  maxResponseBytes?: number;
+  healthTimeoutMs?: number;
+  actionTimeoutMs?: number;
+}
+
+export type ExternalPluginTransport = ExternalPluginUnixSocketTransport | ExternalPluginManagedCliTransport;
+
+export interface ExternalPluginVerifiedUserLaunchAgentLifecycle {
+  kind: 'verified_user_launch_agent';
+  label: string;
+  expectedProgramContains: string;
+}
+
+export type ExternalPluginLifecycle = ExternalPluginVerifiedUserLaunchAgentLifecycle;
+
+export interface ExternalPluginRegistration {
+  schemaVersion: 1;
+  revision: number;
+  pluginId: string;
+  providerPluginId: string;
+  displayName: string;
+  provider: string;
+  pluginVersion: string;
+  protocolVersion: string;
+  scope: AssistantPluginScope;
+  enabled: boolean;
+  transport: ExternalPluginTransport;
+  lifecycle?: ExternalPluginLifecycle;
+  permissions: AssistantPluginPermissionScope[];
+  capabilities: AssistantPluginCapability[];
+  actions: AssistantPluginActionDescriptor[];
+  legacyIdentities?: string[];
+  registrationFingerprint: string;
+  installedAt: string;
+  updatedAt: string;
+}
+
+export interface ExternalPluginRegistrationInput {
+  pluginId: string;
+  providerPluginId?: string;
+  displayName: string;
+  provider: string;
+  pluginVersion: string;
+  protocolVersion: string;
+  scope: AssistantPluginScope;
+  enabled?: boolean;
+  transport: ExternalPluginTransport;
+  lifecycle?: ExternalPluginLifecycle;
+  permissions: AssistantPluginPermissionScope[];
+  capabilities: AssistantPluginCapability[];
+  actions: AssistantPluginActionDescriptor[];
+  legacyIdentities?: string[];
+}
+
+function registrationRoot(controllerHome: string): string {
+  ensureControllerHome(controllerHome);
+  return join(controllerSystemRoot(controllerHome), 'plugins', 'external', 'registrations');
+}
+
+export function externalPluginRegistrationPath(controllerHome: string, pluginId: string): string {
+  return join(registrationRoot(controllerHome), `${sanitizeFileComponent(pluginId)}.json`);
+}
+
+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);
+}
+
+function normalizedTransport(input: ExternalPluginTransport): ExternalPluginTransport {
+  if (input.kind === 'unix_socket_jsonl') {
+    const socketPath = input.socketPath.trim();
+    if (!socketPath || !isAbsolute(socketPath)) {
+      throw new Error('EXTERNAL_PLUGIN_SOCKET_PATH_INVALID: trusted registrations require an absolute Unix socket path');
+    }
+    return {
+      kind: 'unix_socket_jsonl',
+      socketPath,
+      maxRequestBytes: boundedInteger(input.maxRequestBytes, 1_048_576, 1_024, 4 * 1_048_576),
+      maxResponseBytes: boundedInteger(input.maxResponseBytes, 1_048_576, 1_024, 16 * 1_048_576),
+      healthTimeoutMs: boundedInteger(input.healthTimeoutMs, 2_000, 100, 10_000),
+      actionTimeoutMs: boundedInteger(input.actionTimeoutMs, 30_000, 100, 120_000),
+    };
+  }
+  if (input.kind === 'managed_cli_json') {
+    const runtimeExecutable = input.runtimeExecutable.trim();
+    const helperPath = input.helperPath.trim();
+    const cwd = input.cwd?.trim();
+    if (!runtimeExecutable || !isAbsolute(runtimeExecutable)) throw new Error('EXTERNAL_PLUGIN_MANAGED_RUNTIME_INVALID: trusted registrations require an absolute runtime executable');
+    if (!helperPath || !isAbsolute(helperPath)) throw new Error('EXTERNAL_PLUGIN_MANAGED_HELPER_INVALID: trusted registrations require an absolute helper path');
+    if (cwd && !isAbsolute(cwd)) throw new Error('EXTERNAL_PLUGIN_MANAGED_CWD_INVALID: trusted registrations require an absolute cwd');
+    const runtimeArgs = (input.runtimeArgs ?? []).map((value) => value.trim()).filter(Boolean);
+    if (runtimeArgs.length > 20 || runtimeArgs.some((value) => value.length > 1_000)) throw new Error('EXTERNAL_PLUGIN_MANAGED_RUNTIME_ARGS_INVALID');
+    const requiredCapabilities = Array.from(new Set((input.requiredCapabilities ?? []).map((value) => value.trim()).filter(Boolean)));
+    if (requiredCapabilities.length > 100 || requiredCapabilities.some((value) => value.length > 128)) throw new Error('EXTERNAL_PLUGIN_MANAGED_CAPABILITIES_INVALID');
+    return {
+      kind: 'managed_cli_json', runtimeExecutable, helperPath,
+      runtimeArgs,
+      cwd,
+      requiredCapabilities,
+      maxRequestBytes: boundedInteger(input.maxRequestBytes, 1_048_576, 1_024, 16 * 1_048_576),
+      maxResponseBytes: boundedInteger(input.maxResponseBytes, 1_048_576, 1_024, 16 * 1_048_576),
+      healthTimeoutMs: boundedInteger(input.healthTimeoutMs, 2_000, 100, 10_000),
+      actionTimeoutMs: boundedInteger(input.actionTimeoutMs, 30_000, 100, 120_000),
+    };
+  }
+  throw new Error(`EXTERNAL_PLUGIN_TRANSPORT_UNSUPPORTED: ${String((input as { kind?: unknown }).kind)}`);
+}
+
+function normalizedString(value: string, field: string, max = 256): string {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(`EXTERNAL_PLUGIN_${field.toUpperCase()}_REQUIRED`);
+  return normalized.slice(0, max);
+}
+
+function assertPluginId(value: string, field: string): string {
+  const normalized = value.trim();
+  if (!PLUGIN_ID_PATTERN.test(normalized)) throw new Error(`EXTERNAL_PLUGIN_${field.toUpperCase()}_INVALID: ${normalized}`);
+  return normalized;
+}
+
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, canonical(entry)]));
+  }
+  return value;
+}
+
+function registrationFingerprint(input: Omit<ExternalPluginRegistration, 'revision' | 'registrationFingerprint' | 'installedAt' | 'updatedAt'>): string {
+  return createHash('sha256').update(JSON.stringify(canonical(input))).digest('hex');
+}
+
+function normalizedLifecycle(input: ExternalPluginLifecycle | undefined): ExternalPluginLifecycle | undefined {
+  if (!input) return undefined;
+  if (input.kind !== 'verified_user_launch_agent') throw new Error(`EXTERNAL_PLUGIN_LIFECYCLE_UNSUPPORTED: ${String((input as { kind?: unknown }).kind)}`);
+  const label = input.label.trim();
+  if (!/^[A-Za-z0-9._-]{3,200}$/.test(label)) throw new Error(`EXTERNAL_PLUGIN_LIFECYCLE_LABEL_INVALID: ${label}`);
+  const expectedProgramContains = input.expectedProgramContains.trim();
+  if (expectedProgramContains.length < 4 || expectedProgramContains.length > 1024) throw new Error('EXTERNAL_PLUGIN_LIFECYCLE_PROGRAM_IDENTITY_INVALID');
+  return { kind: 'verified_user_launch_agent', label, expectedProgramContains };
+}
+
+function validatePolicy(input: ExternalPluginRegistrationInput): void {
+  const permissionScopes = new Set<string>();
+  for (const permission of input.permissions) {
+    const scope = normalizedString(permission.scope, 'permission_scope', 128);
+    if (permissionScopes.has(scope)) throw new Error(`EXTERNAL_PLUGIN_PERMISSION_DUPLICATE: ${scope}`);
+    permissionScopes.add(scope);
+  }
+
+  const actionIds = new Set<string>();
+  for (const action of input.actions) {
+    const actionId = normalizedString(action.actionId, 'action_id', 128);
+    if (actionIds.has(actionId)) throw new Error(`EXTERNAL_PLUGIN_ACTION_DUPLICATE: ${actionId}`);
+    actionIds.add(actionId);
+    for (const scope of action.scopes) {
+      if (!permissionScopes.has(scope)) throw new Error(`EXTERNAL_PLUGIN_ACTION_SCOPE_UNDECLARED: ${actionId}/${scope}`);
+    }
+    if (action.readOnly && action.risk !== 'readonly') throw new Error(`EXTERNAL_PLUGIN_ACTION_RISK_INVALID: read-only action ${actionId} must use readonly risk`);
+    if (!action.readOnly && action.risk === 'readonly') throw new Error(`EXTERNAL_PLUGIN_ACTION_RISK_INVALID: write action ${actionId} cannot use readonly risk`);
+    if (action.risk === 'destructive' && action.confirmation !== 'strong_confirmation') {
+      throw new Error(`EXTERNAL_PLUGIN_DESTRUCTIVE_CONFIRMATION_REQUIRED: ${actionId}`);
+    }
+  }
+
+  if (input.lifecycle) {
+    const reservedActions = new Set(['provider_start', 'provider_stop', 'provider_restart']);
+    for (const actionId of actionIds) {
+      if (reservedActions.has(actionId)) throw new Error(`EXTERNAL_PLUGIN_LIFECYCLE_ACTION_RESERVED: ${actionId}`);
+    }
+    if (permissionScopes.has('external-provider.lifecycle')) throw new Error('EXTERNAL_PLUGIN_LIFECYCLE_SCOPE_RESERVED');
+  }
+
+  const capabilityIds = new Set<string>();
+  for (const capability of input.capabilities) {
+    const capabilityId = normalizedString(capability.capabilityId, 'capability_id', 128);
+    if (capabilityIds.has(capabilityId)) throw new Error(`EXTERNAL_PLUGIN_CAPABILITY_DUPLICATE: ${capabilityId}`);
+    capabilityIds.add(capabilityId);
+    if (input.lifecycle && capabilityId === 'external-provider-lifecycle') throw new Error('EXTERNAL_PLUGIN_LIFECYCLE_CAPABILITY_RESERVED');
+    for (const actionId of capability.actions) {
+      if (!actionIds.has(actionId)) throw new Error(`EXTERNAL_PLUGIN_CAPABILITY_ACTION_UNKNOWN: ${capabilityId}/${actionId}`);
+    }
+    for (const scope of capability.scopes) {
+      if (!permissionScopes.has(scope)) throw new Error(`EXTERNAL_PLUGIN_CAPABILITY_SCOPE_UNDECLARED: ${capabilityId}/${scope}`);
+    }
+  }
+}
+
+function normalizeRegistrationInput(input: ExternalPluginRegistrationInput): Omit<ExternalPluginRegistration, 'revision' | 'registrationFingerprint' | 'installedAt' | 'updatedAt'> {
+  validatePolicy(input);
+  const pluginId = assertPluginId(input.pluginId, 'plugin_id');
+  const providerPluginId = assertPluginId(input.providerPluginId ?? pluginId, 'provider_plugin_id');
+  const protocolVersion = normalizedString(input.protocolVersion, 'protocol_version', 32);
+  if (!PROTOCOL_VERSION_PATTERN.test(protocolVersion)) throw new Error(`EXTERNAL_PLUGIN_PROTOCOL_VERSION_INVALID: ${protocolVersion}`);
+  if (!['controller', 'repository'].includes(input.scope)) throw new Error(`EXTERNAL_PLUGIN_SCOPE_INVALID: ${String(input.scope)}`);
+  return {
+    schemaVersion: EXTERNAL_REGISTRATION_SCHEMA_VERSION,
+    pluginId,
+    providerPluginId,
+    displayName: normalizedString(input.displayName, 'display_name'),
+    provider: normalizedString(input.provider, 'provider'),
+    pluginVersion: normalizedString(input.pluginVersion, 'plugin_version', 64),
+    protocolVersion,
+    scope: input.scope,
+    enabled: input.enabled !== false,
+    transport: normalizedTransport(input.transport),
+    lifecycle: normalizedLifecycle(input.lifecycle),
+    permissions: structuredClone(input.permissions),
+    capabilities: structuredClone(input.capabilities),
+    actions: structuredClone(input.actions),
+    legacyIdentities: Array.from(new Set((input.legacyIdentities ?? []).map((value) => value.trim()).filter(Boolean))).slice(0, 20),
+  };
+}
+
+export function validateExternalPluginRegistration(value: ExternalPluginRegistration): ExternalPluginRegistration {
+  if (value.schemaVersion !== EXTERNAL_REGISTRATION_SCHEMA_VERSION) throw new Error('EXTERNAL_PLUGIN_REGISTRATION_SCHEMA_UNSUPPORTED');
+  const normalized = normalizeRegistrationInput(value);
+  if (!Number.isInteger(value.revision) || value.revision < 1) throw new Error('EXTERNAL_PLUGIN_REGISTRATION_REVISION_INVALID');
+  if (!value.installedAt || !value.updatedAt) throw new Error('EXTERNAL_PLUGIN_REGISTRATION_TIMESTAMP_REQUIRED');
+  const expectedFingerprint = registrationFingerprint(normalized);
+  if (value.registrationFingerprint !== expectedFingerprint) throw new Error('EXTERNAL_PLUGIN_REGISTRATION_FINGERPRINT_MISMATCH');
+  return {
+    ...normalized,
+    revision: value.revision,
+    registrationFingerprint: expectedFingerprint,
+    installedAt: value.installedAt,
+    updatedAt: value.updatedAt,
+  };
+}
+
+export function getExternalPluginRegistration(controllerHome: string, pluginId: string): ExternalPluginRegistration | undefined {
+  const path = externalPluginRegistrationPath(controllerHome, pluginId);
+  if (!existsSync(path)) return undefined;
+  return validateExternalPluginRegistration(readJsonFile<ExternalPluginRegistration>(path));
+}
+
+export function listExternalPluginRegistrations(controllerHome: string): ExternalPluginRegistration[] {
+  const root = registrationRoot(controllerHome);
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .flatMap((entry) => {
+      try {
+        return [validateExternalPluginRegistration(readJsonFile<ExternalPluginRegistration>(join(root, entry.name)))];
+      } catch {
+        return [];
+      }
+    })
+    .sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+}
+
+export function installExternalPluginRegistration(
+  controllerHome: string,
+  input: ExternalPluginRegistrationInput,
+  options: { expectedRevision?: number; now?: Date } = {},
+): 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 at = (options.now ?? new Date()).toISOString();
+  const next: ExternalPluginRegistration = {
+    ...normalized,
+    revision: (existing?.revision ?? 0) + 1,
+    registrationFingerprint: registrationFingerprint(normalized),
+    installedAt: existing?.installedAt ?? at,
+    updatedAt: at,
+  };
+  mkdirSync(registrationRoot(controllerHome), { recursive: true, mode: 0o700 });
+  writeJsonAtomic(externalPluginRegistrationPath(controllerHome, next.pluginId), next);
+  return next;
+}