@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/plugins/types.ts

@@ -60,7 +60,7 @@ export interface AssistantPluginActionDescriptor {
    * for a bound remote_effect Work.
    */
   remoteEffectWorkCompletion?: 'intermediate' | 'terminal';
-  executionMode?: 'runtime' | 'lightweight_process';
+  executionMode?: 'runtime' | 'lightweight_process' | 'direct_non_persistent';
   foregroundEffect?: AssistantPluginForegroundEffect;
   scopes: string[];
   resourceClaims: AssistantPluginActionResourceClaim[];
@@ -131,6 +131,8 @@ export interface AssistantPluginActionRequest {
   args: Record<string, unknown>;
   timeoutMs?: number;
   signal?: AbortSignal;
+  /** Exact reusable grants bound to the Workflow asset. Never accepts grant contents. */
+  authorizationGrantRefs?: readonly string[];
   confirmAuthorization?: boolean;
   confirmationText?: string;
   origin: ExecutionJobOrigin;
@@ -148,6 +150,8 @@ export interface AssistantPluginActionExecutionInput {
   jobId?: string;
   timeoutMs?: number;
   signal?: AbortSignal;
+  /** Exact reusable grants bound to the Workflow asset. Never accepts grant contents. */
+  authorizationGrantRefs?: readonly string[];
   /** Internal absolute request deadline; propagated only across nested adapter actions. */
   deadlineAtMs?: number;
   /** Internal proof that this exact adapter instance just built and validated the live provider manifest. */
@@ -155,6 +159,7 @@ export interface AssistantPluginActionExecutionInput {
 }
 
 export type AssistantPluginScope = 'repository' | 'controller' | 'controller_with_repository_overlay';
+export type AssistantPluginExposure = 'product' | 'internal';
 
 export interface AssistantPluginBuildContext {
   controllerHome: string;
@@ -166,6 +171,8 @@ export interface AssistantPluginBuildContext {
 export interface AssistantPluginAdapter {
   pluginId: string;
   scope?: AssistantPluginScope;
+  /** Internal adapters remain exactly addressable by trusted composition but are omitted from normal user-facing plugin listings. */
+  exposure?: AssistantPluginExposure;
   buildManifest(previousRevision?: number, previousUpdatedAt?: string, repoRoot?: string, context?: AssistantPluginBuildContext): AssistantPluginManifest;
   /** Resolve an exact stable resource identity for reusable authorization-class actions. */
   resolveAuthorizationContext?(input: AssistantPluginActionExecutionInput): Promise<AssistantPluginAuthorizationContext | undefined>;

package/src/runtime/plugins/uu-remote-rescue-registration.ts

@@ -0,0 +1,155 @@
+import type { ExternalPluginRegistrationInput } from './external-registration';
+import type { AssistantPluginActionDescriptor } from './types';
+
+export const UU_REMOTE_RESCUE_PLUGIN_ID = 'uu_remote_rescue';
+export const UU_REMOTE_RESCUE_PLUGIN_VERSION = '0.1.1';
+export const UU_REMOTE_RESCUE_PROTOCOL_VERSION = '1.0';
+export const UU_REMOTE_RESCUE_CAPABILITIES = [
+  'uu_remote.device_identity.v1',
+  'uu_remote.terminal_transport.v1',
+  'forge_wsl.health.v1',
+  'forge_wsl.service_recovery.v1',
+  'forge_wsl.host_recovery.v1',
+] as const;
+
+const REMOTE_WRITE = [{ resource: 'remote' as const, mode: 'write' as const }];
+const NO_ARGUMENTS = { type: 'object', properties: {}, additionalProperties: false } as const;
+
+function actions(): AssistantPluginActionDescriptor[] {
+  return [
+    {
+      actionId: 'device_status',
+      title: 'Read UU Remote rescue target status',
+      description: 'Verify the registration-bound UU Remote Windows device by exact device id, exact device name, platform, and online state.',
+      readOnly: true,
+      risk: 'readonly',
+      confirmation: 'none',
+      defaultTimeoutMs: 10_000,
+      cancellable: true,
+      idempotent: true,
+      foregroundEffect: 'none',
+      scopes: ['uu-rescue.device'],
+      resourceClaims: [],
+      argumentsSchema: NO_ARGUMENTS,
+    },
+    {
+      actionId: 'wsl_status',
+      title: 'Read WSL status through UU Remote',
+      description: 'Open the exact UU Remote terminal and run only the built-in WSL status/list observation command.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: 30_000,
+      cancellable: true,
+      idempotent: true,
+      foregroundEffect: 'required',
+      scopes: ['uu-rescue.observe'],
+      resourceClaims: REMOTE_WRITE,
+      argumentsSchema: NO_ARGUMENTS,
+    },
+    {
+      actionId: 'forge_health',
+      title: 'Read remote WSL Forge health',
+      description: 'Read Controller Home presence, migration record, and the exact Runtime, Connector, and Recovery systemd-user service states through a fixed remote probe.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: 30_000,
+      cancellable: true,
+      idempotent: true,
+      foregroundEffect: 'required',
+      scopes: ['uu-rescue.observe'],
+      resourceClaims: REMOTE_WRITE,
+      argumentsSchema: NO_ARGUMENTS,
+    },
+    ...(['runtime_start', 'runtime_restart', 'connector_start', 'connector_restart', 'recovery_start', 'recovery_restart', 'runtime_recover'] as const).map((actionId): AssistantPluginActionDescriptor => ({
+      actionId,
+      title: ({
+        runtime_start: 'Start remote Forge Runtime',
+        runtime_restart: 'Restart remote Forge Runtime',
+        connector_start: 'Start remote Forge Connector',
+        connector_restart: 'Restart remote Forge Connector',
+        recovery_start: 'Start remote Forge Recovery services',
+        recovery_restart: 'Restart remote Forge Recovery services',
+        runtime_recover: 'Recover remote Forge Runtime',
+      } as const)[actionId],
+      description: actionId === 'runtime_recover'
+        ? 'Invoke only the canonical `forge recovery recover --controller-home <configured-home>` transaction inside the configured WSL distro.'
+        : 'Operate only the registration-derived canonical systemd-user unit(s); no caller-provided service name or shell command is accepted.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: actionId === 'runtime_recover' ? 120_000 : 30_000,
+      cancellable: true,
+      idempotent: actionId.endsWith('_start'),
+      foregroundEffect: 'required',
+      scopes: ['uu-rescue.recover'],
+      resourceClaims: REMOTE_WRITE,
+      argumentsSchema: NO_ARGUMENTS,
+    })),
+    ...(['host_tunnel_restart_dispatch', 'host_full_recover_dispatch'] as const).map((actionId): AssistantPluginActionDescriptor => ({
+      actionId,
+      title: actionId === 'host_tunnel_restart_dispatch'
+        ? 'Dispatch independent host tunnel recovery'
+        : 'Dispatch independent host full recovery',
+      description: actionId === 'host_tunnel_restart_dispatch'
+        ? 'Safely dispatch the fixed independent Windows/WSL Recovery tunnel_restart action to the registration-bound UU Remote Windows host. Success proves only dispatch; Forge Cloud connectivity must verify recovery.'
+        : 'Safely dispatch the fixed independent Windows/WSL Recovery full_recover action to the registration-bound UU Remote Windows host. Success proves only dispatch; Forge Cloud connectivity must verify recovery.',
+      readOnly: false,
+      risk: 'remote_write',
+      confirmation: 'authorization',
+      defaultTimeoutMs: 30_000,
+      cancellable: true,
+      idempotent: false,
+      foregroundEffect: 'required',
+      scopes: ['uu-rescue.recover'],
+      resourceClaims: REMOTE_WRITE,
+      argumentsSchema: NO_ARGUMENTS,
+    })),
+  ];
+}
+
+export interface UuRemoteRescueRegistrationOptions {
+  runtimeExecutable: string;
+  helperPath: string;
+  configDirectory: string;
+  enabled?: boolean;
+}
+
+export function createUuRemoteRescueRegistrationInput(
+  options: UuRemoteRescueRegistrationOptions,
+): ExternalPluginRegistrationInput {
+  const registeredActions = actions();
+  return {
+    pluginId: UU_REMOTE_RESCUE_PLUGIN_ID,
+    providerPluginId: UU_REMOTE_RESCUE_PLUGIN_ID,
+    displayName: 'Forge UU Remote Rescue',
+    provider: 'local-macos',
+    pluginVersion: UU_REMOTE_RESCUE_PLUGIN_VERSION,
+    protocolVersion: UU_REMOTE_RESCUE_PROTOCOL_VERSION,
+    scope: 'controller',
+    enabled: options.enabled !== false,
+    transport: {
+      kind: 'managed_cli_json',
+      runtimeExecutable: options.runtimeExecutable,
+      helperPath: options.helperPath,
+      cwd: options.configDirectory,
+      requiredCapabilities: [...UU_REMOTE_RESCUE_CAPABILITIES],
+      healthTimeoutMs: 10_000,
+      actionTimeoutMs: 120_000,
+      maxRequestBytes: 64 * 1024,
+      maxResponseBytes: 256 * 1024,
+    },
+    permissions: [
+      { scope: 'uu-rescue.device', mode: 'read', description: 'Read only the exact configured UU Remote device identity and online state.', granted: true, required: true },
+      { scope: 'uu-rescue.observe', mode: 'write', description: 'Open the exact configured UU terminal transiently and send only built-in diagnostic commands.', granted: true, required: false },
+      { scope: 'uu-rescue.recover', mode: 'write', description: 'Operate only the configured WSL Forge Runtime, Connector, and Recovery service identities using fixed recovery actions.', granted: true, required: false },
+    ],
+    capabilities: [
+      { capabilityId: 'uu-rescue.device', title: 'UU Remote rescue device identity', description: 'Exact device identity and online-state fencing.', scopes: ['uu-rescue.device'], actions: ['device_status'] },
+      { capabilityId: 'uu-rescue.observe', title: 'Remote WSL/Forge observation', description: 'Fixed WSL and Forge health probes over the UU Remote terminal.', scopes: ['uu-rescue.observe'], actions: ['wsl_status', 'forge_health'] },
+      { capabilityId: 'uu-rescue.recover', title: 'Remote Forge recovery', description: 'Allowlisted start/restart/recovery operations for the existing single Forge service authorities.', scopes: ['uu-rescue.recover'], actions: ['runtime_start', 'runtime_restart', 'connector_start', 'connector_restart', 'recovery_start', 'recovery_restart', 'runtime_recover', 'host_tunnel_restart_dispatch', 'host_full_recover_dispatch'] },
+    ],
+    actions: registeredActions,
+  };
+}

package/src/runtime/plugins/windows-host-recovery-install.ts

@@ -0,0 +1,68 @@
+import { createHash } from 'crypto';
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { controllerSystemRoot } from '../../cli/repositories/controller-home';
+import { discoverWslWindowsHostEnvironment, type WindowsHostEnvironment } from '../platform/windows-host-discovery';
+import { resolveWindowsRecoveryDeployment } from '../platform/windows-recovery-deployment';
+import { installExternalPluginRegistration } from './external-registration';
+import { createWindowsHostRecoveryRegistrationInput } from './windows-host-recovery-registration';
+
+function atomicCopy(source: string, destination: string, mode: number): void {
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+  const temporary = `${destination}.${process.pid}.tmp`;
+  copyFileSync(source, temporary);
+  chmodSync(temporary, mode);
+  renameSync(temporary, destination);
+}
+function atomicJson(path: string, value: Record<string, unknown>): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  renameSync(temporary, path);
+}
+function sha256(path: string): string { return createHash('sha256').update(readFileSync(path)).digest('hex'); }
+function packagedHelperPath(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  return resolve(moduleDir, '..', '..', '..', 'scripts', 'forge-windows-host-recovery-helper.mjs');
+}
+
+export function installWindowsHostRecoveryPlugin(options: {
+  controllerHome: string;
+  rescueRoot?: string;
+  helperSource?: string;
+  runtimeExecutable?: string;
+  enabled?: boolean;
+  host?: WindowsHostEnvironment;
+  recoveryScriptHostPath?: string;
+  recoveryScriptWindowsPath?: string;
+  powershellHostPath?: string;
+  powershellWindowsPath?: string;
+}): Record<string, unknown> {
+  const controllerHome = resolve(options.controllerHome);
+  const rescueRoot = resolve(options.rescueRoot ?? join(homedir(), '.forge-recovery'));
+  const helperSource = resolve(options.helperSource ?? packagedHelperPath());
+  const host = options.host ?? discoverWslWindowsHostEnvironment();
+  const deployment = resolveWindowsRecoveryDeployment({
+    rescueRoot,
+    host,
+    recoveryScriptHostPath: options.recoveryScriptHostPath,
+    recoveryScriptWindowsPath: options.recoveryScriptWindowsPath,
+    powershellHostPath: options.powershellHostPath,
+    powershellWindowsPath: options.powershellWindowsPath,
+  });
+  const helperPath = join(rescueRoot, 'bin', 'forge-windows-host-recovery-helper.mjs');
+  const configDirectory = join(controllerSystemRoot(controllerHome), 'plugins', 'windows-host-recovery');
+  const configPath = join(configDirectory, 'config.json');
+  atomicCopy(helperSource, helperPath, 0o700);
+  const scriptSha256 = sha256(deployment.recoveryScriptHostPath);
+  atomicJson(configPath, { schemaVersion: 1, expectedScriptSha256: scriptSha256, deployment });
+  const registration = installExternalPluginRegistration(controllerHome, createWindowsHostRecoveryRegistrationInput({
+    runtimeExecutable: options.runtimeExecutable ?? process.execPath,
+    helperPath,
+    configDirectory,
+    enabled: options.enabled !== false,
+  }));
+  return { registration, helperPath, configPath, deployment, scriptSha256 };
+}

package/src/runtime/plugins/windows-host-recovery-registration.ts

@@ -0,0 +1,85 @@
+import type { ExternalPluginRegistrationInput } from './external-registration';
+import type { AssistantPluginActionDescriptor } from './types';
+
+export const WINDOWS_HOST_RECOVERY_PLUGIN_ID = 'windows_host_recovery';
+export const WINDOWS_HOST_RECOVERY_PLUGIN_VERSION = '0.1.4';
+export const WINDOWS_HOST_RECOVERY_PROTOCOL_VERSION = '1.0';
+export const WINDOWS_HOST_RECOVERY_CAPABILITIES = [
+  'windows_host.identity.v1',
+  'windows_host.recovery_task.v1',
+  'forge_wsl.host_recovery.v1',
+] as const;
+
+const NO_ARGUMENTS = { type: 'object', properties: {}, additionalProperties: false } as const;
+const REMOTE_WRITE = [{ resource: 'remote' as const, mode: 'write' as const }];
+const ACTIONS = [
+  'host_status', 'task_status', 'task_install', 'task_run',
+  'wsl_status', 'wsl_start', 'forge_source_status', 'controller_status',
+  'runtime_status', 'runtime_start', 'runtime_restart',
+  'connector_status', 'connector_start', 'connector_restart',
+  'recovery_status', 'recovery_start', 'recovery_restart',
+  'tunnel_status', 'tunnel_start', 'tunnel_restart',
+  'forge_cloud_verify', 'full_recover',
+] as const;
+const READONLY = new Set<string>(['host_status', 'task_status', 'wsl_status', 'forge_source_status', 'controller_status', 'runtime_status', 'connector_status', 'recovery_status', 'tunnel_status', 'forge_cloud_verify']);
+
+function actionDescriptors(): AssistantPluginActionDescriptor[] {
+  return ACTIONS.map((actionId) => {
+    const readOnly = READONLY.has(actionId);
+    return {
+      actionId,
+      title: `Windows host recovery: ${actionId}`,
+      description: readOnly
+        ? 'Read one fixed Windows/WSL recovery status surface; no caller-provided command or target is accepted.'
+        : 'Execute one allowlisted Windows/WSL recovery action against the canonical ForgeRecovery.ps1 installation; no caller-provided command, path, task, service, or shell argument is accepted.',
+      readOnly,
+      risk: readOnly ? 'readonly' : 'remote_write',
+      confirmation: readOnly ? 'none' : 'authorization',
+      defaultTimeoutMs: actionId === 'full_recover' ? 120_000 : 30_000,
+      cancellable: true,
+      idempotent: !actionId.endsWith('_restart') && actionId !== 'task_run',
+      foregroundEffect: 'none',
+      scopes: [readOnly ? 'windows-recovery.observe' : 'windows-recovery.recover'],
+      resourceClaims: readOnly ? [] : REMOTE_WRITE,
+      argumentsSchema: NO_ARGUMENTS,
+    } satisfies AssistantPluginActionDescriptor;
+  });
+}
+
+export function createWindowsHostRecoveryRegistrationInput(options: {
+  runtimeExecutable: string;
+  helperPath: string;
+  configDirectory: string;
+  enabled?: boolean;
+}): ExternalPluginRegistrationInput {
+  return {
+    pluginId: WINDOWS_HOST_RECOVERY_PLUGIN_ID,
+    providerPluginId: WINDOWS_HOST_RECOVERY_PLUGIN_ID,
+    displayName: 'Forge Windows Host Recovery',
+    provider: 'local-wsl-windows',
+    pluginVersion: WINDOWS_HOST_RECOVERY_PLUGIN_VERSION,
+    protocolVersion: WINDOWS_HOST_RECOVERY_PROTOCOL_VERSION,
+    scope: 'controller',
+    enabled: options.enabled !== false,
+    transport: {
+      kind: 'managed_cli_json',
+      runtimeExecutable: options.runtimeExecutable,
+      helperPath: options.helperPath,
+      cwd: options.configDirectory,
+      requiredCapabilities: [...WINDOWS_HOST_RECOVERY_CAPABILITIES],
+      healthTimeoutMs: 10_000,
+      actionTimeoutMs: 120_000,
+      maxRequestBytes: 32 * 1024,
+      maxResponseBytes: 256 * 1024,
+    },
+    permissions: [
+      { scope: 'windows-recovery.observe', mode: 'read', description: 'Read only fixed Windows host and WSL Recovery status surfaces.', granted: true, required: true },
+      { scope: 'windows-recovery.recover', mode: 'write', description: 'Run only fixed Windows Task Scheduler and WSL Forge recovery actions.', granted: true, required: false },
+    ],
+    capabilities: [
+      { capabilityId: 'windows-recovery.observe', title: 'Windows Recovery observation', description: 'Fixed host/task/WSL health observations.', scopes: ['windows-recovery.observe'], actions: ACTIONS.filter((action) => READONLY.has(action)) },
+      { capabilityId: 'windows-recovery.recover', title: 'Windows Recovery control', description: 'Allowlisted host cold-start and WSL service recovery actions.', scopes: ['windows-recovery.recover'], actions: ACTIONS.filter((action) => !READONLY.has(action)) },
+    ],
+    actions: actionDescriptors(),
+  };
+}