feat: delegate reviewed managed automation (#2312)

* feat: delegate reviewed automation through managed lease authority

* fix: preserve lazy simulator readiness through scoped authority

* fix: admit managed operations at their dispatch boundary

* test: move managed automation scenarios to integration lane

* chore(gates): declare the private managed readiness scope export

Author: thymikee

packages/platform-android/src/deployment/native.ts

@@ -3,6 +3,7 @@ import type { PushNotificationInput } from '@agent-device/contracts/app-deployme
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
 import path from 'node:path';
+import { currentManagedDeviceScope } from '@agent-device/provision-kit/managed-device-scope';
 
 export async function installAndroidArtifact(
   host: PlatformRuntimeHost,
@@ -11,6 +12,7 @@ export async function installAndroidArtifact(
   packageNameHint: string | undefined,
   signal: AbortSignal,
 ): Promise<string | undefined> {
+  assertManagedAndroidInstallablePath(installablePath);
   const before = packageNameHint ? undefined : await listInstalledPackages(host, device, signal);
   if (path.extname(installablePath).toLowerCase() === '.aab') {
     await installAndroidBundle(host, device, installablePath, signal);
@@ -29,6 +31,19 @@ export async function installAndroidArtifact(
   return installed.length === 1 ? installed[0] : undefined;
 }
 
+export function assertManagedAndroidInstallablePath(installablePath: string): void {
+  if (currentManagedDeviceScope() && path.extname(installablePath).toLowerCase() === '.aab') {
+    throw new AppError(
+      'UNSUPPORTED_OPERATION',
+      'Managed Android deployment does not support app bundles.',
+      {
+        reason: 'managed-bundle-install-unavailable',
+        hint: 'Install an APK on this managed device.',
+      },
+    );
+  }
+}
+
 export async function uninstallAndroidPackage(
   host: PlatformRuntimeHost,
   device: DeviceInfo,

packages/platform-android/src/deployment/runtime.ts

@@ -4,18 +4,21 @@ import type {
   AppDeploymentRuntimeOperations,
   DeployMaterializedAppInput,
   MaterializeAppSourceInput,
+  MaterializedAppSource,
   PushNotificationInput,
 } from '@agent-device/contracts/app-deployment-runtime';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type { RuntimeOperationFact } from '@agent-device/contracts/platform-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
+import { currentManagedDeviceScope } from '@agent-device/provision-kit/managed-device-scope';
 import { ensureAndroidReady } from '../readiness/runtime.ts';
 import {
   inferAndroidAppName,
   installAndroidArtifact,
   pushAndroidNotification,
   uninstallAndroidPackage,
+  assertManagedAndroidInstallablePath,
 } from './native.ts';
 
 const available = Object.freeze({ available: true } as const);
@@ -66,36 +69,51 @@ async function deployAndroidApp(
     // cache boundary here in the Android deployment owner: clear before boot/resolve/uninstall
     // and after materialization/install, including partial failures.
     return await host.androidDeployment.withInvalidatedAppResolutionCache(device, async () => {
-      if (device.booted !== true) {
-        await ensureAndroidReady(host, device, { headless: false }, signal);
-      }
-      const packageName = await host.androidDeployment.resolveAppPackage(device, input.app);
-      await uninstallAndroidPackage(host, device, packageName, signal);
-      const artifact = await host.androidDeployment.prepareArtifact(
-        { source: { kind: 'path', path: input.appPath } },
-        { resolveIdentity: false, signal },
-      );
+      let artifact: MaterializedAppSource | undefined;
       try {
+        if (currentManagedDeviceScope()) {
+          artifact = await host.androidDeployment.prepareArtifact(
+            { source: { kind: 'path', path: input.appPath } },
+            { resolveIdentity: false, signal },
+          );
+          assertManagedAndroidInstallablePath(artifact.installablePath);
+        }
+        if (device.booted !== true) {
+          await ensureAndroidReady(host, device, { headless: false }, signal);
+        }
+        const packageName = await host.androidDeployment.resolveAppPackage(device, input.app);
+        await uninstallAndroidPackage(host, device, packageName, signal);
+        artifact ??= await host.androidDeployment.prepareArtifact(
+          { source: { kind: 'path', path: input.appPath } },
+          { resolveIdentity: false, signal },
+        );
         await installAndroidArtifact(host, device, artifact.installablePath, undefined, signal);
         return { packageName, launchTarget: packageName };
       } finally {
-        await artifact.cleanup();
+        await artifact?.cleanup();
       }
     });
   }
 
   // Existing install semantics wait for a selected Android target before taking the
   // before-install package inventory. Keep that platform rule here, rather than
   // reviving a daemon readiness adapter.
-  if (device.booted !== true) {
-    await ensureAndroidReady(host, device, { headless: false }, signal);
-  }
-
-  const artifact = await host.androidDeployment.prepareArtifact(
-    { source: { kind: 'path', path: input.appPath } },
-    { resolveIdentity: true, signal },
-  );
+  let artifact: MaterializedAppSource | undefined;
   try {
+    if (currentManagedDeviceScope()) {
+      artifact = await host.androidDeployment.prepareArtifact(
+        { source: { kind: 'path', path: input.appPath } },
+        { resolveIdentity: true, signal },
+      );
+      assertManagedAndroidInstallablePath(artifact.installablePath);
+    }
+    if (device.booted !== true) {
+      await ensureAndroidReady(host, device, { headless: false }, signal);
+    }
+    artifact ??= await host.androidDeployment.prepareArtifact(
+      { source: { kind: 'path', path: input.appPath } },
+      { resolveIdentity: true, signal },
+    );
     const packageName = await installAndroidArtifact(
       host,
       device,
@@ -113,7 +131,7 @@ async function deployAndroidApp(
       launchTarget: packageName,
     };
   } finally {
-    await artifact.cleanup();
+    await artifact?.cleanup();
   }
 }
 

packages/platform-android/src/readiness/runtime.ts

@@ -8,6 +8,7 @@ export type AndroidReadinessHost = Pick<
 >;
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
+import { delegateManagedDeviceReadiness } from '@agent-device/provision-kit/managed-device-scope';
 
 const BOOT_TIMEOUT_MS = 120_000;
 const POLL_MS = 1_000;
@@ -19,6 +20,7 @@ export async function ensureAndroidReady(
   signal: AbortSignal,
 ): Promise<DeviceInfo> {
   signal.throwIfAborted();
+  if (await delegateManagedDeviceReadiness(device)) return { ...device, booted: true };
   if (device.kind === 'emulator' && (device.booted !== true || !isRunningEmulator(device))) {
     return await ensureEmulatorReady(host, device, input, signal);
   }

packages/platform-apple/src/core/simulator.ts

@@ -5,6 +5,7 @@ import { Deadline, retryWithPolicy } from '@agent-device/host-kit/retry';
 
 import { createTtlMemo } from '@agent-device/kernel/ttl-memo';
 import { bootFailureHint, classifyBootFailure } from '@agent-device/provision-kit/boot-diagnostics';
+import { createScopedProvider } from '@agent-device/kernel/scoped-provider';
 
 import {
   IOS_BOOT_TIMEOUT_MS,
@@ -17,6 +18,17 @@ import { runAppleToolCommand, runXcrun } from './tool-provider.ts';
 const IOS_SIMULATOR_HOST_APPS = ['Simulator'] as const;
 const IOS_DEVICE_HUB_HOST_APPS = ['Device Hub', 'Simulator'] as const;
 
+const simulatorReadiness = createScopedProvider<
+  ((device: DeviceInfo) => Promise<void>) | undefined
+>(undefined);
+
+export async function withSimulatorReadiness<T>(
+  ensureReady: (device: DeviceInfo) => Promise<void>,
+  task: () => Promise<T>,
+): Promise<T> {
+  return await simulatorReadiness.run(ensureReady, task);
+}
+
 type OpenIosSimulatorAppOptions = {
   background?: boolean;
   deviceHub?: boolean;
@@ -85,6 +97,12 @@ export async function ensureBootedSimulator(
 ): Promise<void> {
   if (device.kind !== 'simulator') return;
   options.signal?.throwIfAborted();
+  const ensureReady = simulatorReadiness.resolve();
+  if (ensureReady) {
+    await ensureReady(device);
+    options.signal?.throwIfAborted();
+    return;
+  }
 
   const state = wasSimulatorRecentlyObservedBooted(device)
     ? 'Booted'

packages/platform-apple/src/readiness/runtime.ts

@@ -1,6 +1,7 @@
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import { isMacOs, type DeviceInfo } from '@agent-device/kernel/device';
 import { AppError } from '@agent-device/kernel/errors';
+import { delegateManagedDeviceReadiness } from '@agent-device/provision-kit/managed-device-scope';
 import { getSimulatorState, simctlArgs } from '../simulator-state.ts';
 
 /** Readiness reads exactly these host ports; the lifecycle binding composes the same subset. */
@@ -27,6 +28,7 @@ export async function ensureAppleReady(
   options: AppleReadinessOptions = {},
 ): Promise<DeviceInfo> {
   signal.throwIfAborted();
+  if (await delegateManagedDeviceReadiness(device)) return { ...device, booted: true };
   if (isMacOs(device)) return { ...device, booted: true };
   if (device.kind === 'device') {
     await host.deviceReadiness.applePhysical.ensureConnected(device, signal);

packages/platform-apple/src/runtime-simulator-readiness.test.ts

@@ -0,0 +1,50 @@
+import { expect, test, vi } from 'vitest';
+import { managedLocalRuntimeOwner } from '@agent-device/contracts/platform-runtime';
+import { withManagedDeviceScope } from '@agent-device/provision-kit/managed-device-scope';
+import { IOS_SIMULATOR } from './__tests__/device-fixtures.ts';
+import { ensureBootedSimulator } from './core/simulator.ts';
+import { createLocalAppleToolProvider, withAppleToolProvider } from './core/tool-provider.ts';
+import { bindSimulatorReadiness } from './runtime-simulator-readiness.ts';
+
+test('ordinary simulator operations preserve their binding without a readiness override', () => {
+  const operations = { ensureBootedSimulator };
+  expect(bindSimulatorReadiness(operations)).toBe(operations);
+});
+
+test('bound simulator readiness captures authority and refuses mismatches or failures before local boot', async () => {
+  await withAppleToolProvider(
+    createLocalAppleToolProvider({
+      runCommand: async () => {
+        throw new Error('Unexpected local readiness');
+      },
+    }),
+    async () => {
+      const device = { ...IOS_SIMULATOR, simulatorSetPath: '/managed/set' };
+      const admit = vi.fn(async (): Promise<never> => {
+        throw new Error('Deep readiness must not recursively admit');
+      });
+      const operations = await withManagedDeviceScope(
+        {
+          device,
+          owner: managedLocalRuntimeOwner('allocator'),
+          fence: { token: 'fence', generation: 1 },
+          admit,
+          run: async <T>(task: () => Promise<T>) => await task(),
+        },
+        async () => bindSimulatorReadiness(Object.freeze({ ensureBootedSimulator })),
+      );
+      await operations.ensureBootedSimulator(device);
+      expect(admit).not.toHaveBeenCalled();
+      await expect(
+        operations.ensureBootedSimulator({ ...device, simulatorSetPath: undefined }),
+      ).rejects.toMatchObject({ details: { reason: 'managed-device-transport-mismatch' } });
+      expect(admit).not.toHaveBeenCalled();
+      const abort = new AbortController();
+      abort.abort(new Error('cancelled'));
+      await expect(
+        operations.ensureBootedSimulator(device, { signal: abort.signal }),
+      ).rejects.toThrow('cancelled');
+      expect(admit).not.toHaveBeenCalled();
+    },
+  );
+});

packages/platform-apple/src/runtime-simulator-readiness.ts

@@ -0,0 +1,11 @@
+import { withMethodScope } from '@agent-device/kernel/scoped-provider';
+import { resolveManagedDeviceReadiness } from '@agent-device/provision-kit/managed-device-scope';
+import { withSimulatorReadiness } from './core/simulator.ts';
+
+export function bindSimulatorReadiness<T extends object>(operations: T): Readonly<T> {
+  const ensureReady = resolveManagedDeviceReadiness();
+  if (!ensureReady) return Object.freeze(operations);
+  return Object.freeze({
+    ...withMethodScope({ ...operations }, (task) => withSimulatorReadiness(ensureReady, task)),
+  });
+}

packages/platform-apple/src/runtime.ts

@@ -4,6 +4,7 @@ import {
   localRuntimeOwner,
   whenAdmitted,
 } from '@agent-device/contracts/platform-runtime';
+import { bindSimulatorReadiness } from './runtime-simulator-readiness.ts';
 import type { NetworkDumpInput } from '@agent-device/contracts/network-runtime';
 import type {
   PlatformRuntimeHost,
@@ -494,7 +495,7 @@ export function createApplePlatformRuntime(host: PlatformRuntimeHost): PlatformR
         device: logs.device,
         owner,
         facts,
-        operations: Object.freeze(operations),
+        operations: bindSimulatorReadiness(operations),
         [Symbol.asyncDispose]: async () => await logs[Symbol.asyncDispose](),
       }) satisfies DeviceBinding<PlatformRuntimeOperations>;
     },

packages/provision-kit/package.json

@@ -10,6 +10,10 @@
     "@agent-device/kernel": "workspace:*"
   },
   "exports": {
+    "./managed-device-scope": {
+      "types": "./src/managed-device-scope.ts",
+      "default": "./src/managed-device-scope.ts"
+    },
     "./app-resolution-cache": {
       "types": "./src/app-resolution-cache.ts",
       "default": "./src/app-resolution-cache.ts"

packages/provision-kit/src/managed-device-scope.test.ts

@@ -0,0 +1,48 @@
+import { expect, test } from 'vitest';
+import { managedLocalRuntimeOwner } from '@agent-device/contracts/platform-runtime';
+import {
+  currentManagedDeviceScope,
+  delegateManagedDeviceReadiness,
+  withManagedDeviceScope,
+} from './managed-device-scope.ts';
+
+test('managed readiness scopes isolate concurrent devices and leave ordinary readiness untouched', async () => {
+  const ready: string[] = [];
+  const device = {
+    platform: 'android' as const,
+    kind: 'emulator' as const,
+    id: 'one',
+    name: 'one',
+  };
+  const managed = {
+    device,
+    owner: managedLocalRuntimeOwner('allocator'),
+    fence: { token: 'fence', generation: 1 },
+    admit: async <T>(_task: () => Promise<T>): Promise<T> => {
+      throw new Error('Readiness must not recursively admit');
+    },
+    run: async <T>(task: () => Promise<T>) => await task(),
+  };
+  await Promise.all(
+    ['one', 'two'].map(async (id) => {
+      const selected = { ...device, id };
+      await withManagedDeviceScope(
+        {
+          ...managed,
+          device: selected,
+        },
+        async () => {
+          await Promise.resolve();
+          expect(await delegateManagedDeviceReadiness(selected)).toBe(true);
+          ready.push(id);
+          await expect(
+            delegateManagedDeviceReadiness({ ...selected, id: 'foreign' }),
+          ).rejects.toMatchObject({ details: { reason: 'managed-device-transport-mismatch' } });
+        },
+      );
+    }),
+  );
+  expect(ready.sort()).toEqual(['one', 'two']);
+  expect(currentManagedDeviceScope()).toBeUndefined();
+  expect(await delegateManagedDeviceReadiness(device)).toBe(false);
+});