From 61ae2772d4ea72da9544abfdd305705e3edd51fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Sat, 14 Nov 2026 18:29:56 +0100 Subject: [PATCH] chore(gates): preserve native registry identity and recoverable lazy loads --- packages/contracts/package.json | 4 + packages/contracts/src/replay-execution.ts | 34 ++++ packages/maestro/src/plugin.ts | 2 +- packages/plugins/src/registry.ts | 74 ++++++-- packages/plugins/src/replay-backend.test.ts | 175 ++++++++++++++++++ packages/plugins/src/replay-backend.ts | 27 ++- packages/plugins/src/validate.ts | 34 +++- packages/plugins/tsconfig.json | 16 +- .../layering/contracts-exports.snapshot.json | 1 + src/host-replay.test.ts | 4 +- src/sdk/plugins.ts | 6 + 11 files changed, 343 insertions(+), 34 deletions(-) create mode 100644 packages/contracts/src/replay-execution.ts diff --git a/packages/contracts/package.json b/packages/contracts/package.json index 6033aaf160..9982191dd2 100644 --- a/packages/contracts/package.json +++ b/packages/contracts/package.json @@ -571,6 +571,10 @@ "./replay-test-execution": { "types": "./src/replay-test-execution.ts", "default": "./src/replay-test-execution.ts" + }, + "./replay-execution": { + "types": "./src/replay-execution.ts", + "default": "./src/replay-execution.ts" } }, "devDependencies": { diff --git a/packages/contracts/src/replay-execution.ts b/packages/contracts/src/replay-execution.ts new file mode 100644 index 0000000000..03b397a292 --- /dev/null +++ b/packages/contracts/src/replay-execution.ts @@ -0,0 +1,34 @@ +/** The managed backend identity that owns native replay and suite execution. */ +export const NATIVE_REPLAY_BACKEND = 'ad'; + +import type { + AdReplayDigestFlags, + AdReplayManifest, + AdReplayRunRequest, + AdReplayRunOutcome, + AdReplayStepRuntime, +} from './ad-replay-execution.ts'; +import type { + ReplayTestSuiteRequest, + ReplayTestSuiteOutcome, + ReplayTestRuntimeDependencies, +} from './replay-test-execution.ts'; + +/** Native execution receives host-owned inspection, step and suite inputs. */ +export type ReplayExecution = Readonly<{ + inspectAdReplay(script: string, digestFlags?: AdReplayDigestFlags): AdReplayManifest; + runAdReplay( + request: AdReplayRunRequest, + runtime: AdReplayStepRuntime, + ): Promise; + runReplayTestSuite( + params: { request: ReplayTestSuiteRequest } & ReplayTestRuntimeDependencies, + ): Promise; +}>; + +/** The managed registry creates one native engine and owns its lifetime. */ +export type ReplayExecutionPlugin = Readonly<{ + create(): ReplayExecution | Promise; +}>; + +export type ReplayExecutionResolver = (packageName?: string) => Promise; diff --git a/packages/maestro/src/plugin.ts b/packages/maestro/src/plugin.ts index f6af5b2c92..be429ece80 100644 --- a/packages/maestro/src/plugin.ts +++ b/packages/maestro/src/plugin.ts @@ -1,7 +1,7 @@ import type { ReplayEnginePlugin } from 'agent-device/plugins'; /** The managed entry is engine-free. Only a selected backend evaluates the implementation. */ -function maestroPlugin(): ReplayEnginePlugin { +function maestroPlugin(): ReplayEnginePlugin<'maestro'> { return { apiVersion: 2, kind: 'replay-backend', diff --git a/packages/plugins/src/registry.ts b/packages/plugins/src/registry.ts index ad2502de23..11c9c137cc 100644 --- a/packages/plugins/src/registry.ts +++ b/packages/plugins/src/registry.ts @@ -1,3 +1,8 @@ +import { NATIVE_REPLAY_BACKEND } from '@agent-device/contracts/replay-execution'; +import type { + ReplayExecution, + ReplayExecutionResolver, +} from '@agent-device/contracts/replay-execution'; import type { ReplayBackend } from '@agent-device/contracts/replay-backend'; import type { ReplayEnginePlugin, @@ -34,6 +39,7 @@ import { validateReplayEnginePlugin, validateReplayEngineSetup, validateReplayBackend, + validateReplayExecution, } from './validate.ts'; /** @@ -93,6 +99,7 @@ type Slot = { replaySetup?: ReplayEngineSetup; replayLoading?: Promise; replayFailure?: unknown; + executionLoading?: Promise; failure?: unknown; registration?: ProviderRegistration; }; @@ -111,6 +118,7 @@ export type ResolvedProviderPlugins = Readonly<{ export type ProviderRegistry = Readonly<{ registrations: readonly ProviderRegistration[]; resolveReplayBackend: ReplayBackendResolver; + resolveReplayExecution: ReplayExecutionResolver; claimedProviders: readonly string[]; inventory: readonly PluginInventoryEntry[]; /** @@ -199,6 +207,29 @@ export async function startProviderRegistry( }); return await resolveRegisteredReplayBackend(resolved, inventory, id, host, packageName); }, + resolveReplayExecution: async (packageName) => { + if (closed) + throw new AppError('COMMAND_FAILED', 'Plugin registry is closed', { + reason: 'plugin-registry-closed', + }); + const slot = requireReplaySlot(resolved, NATIVE_REPLAY_BACKEND, packageName); + if (slot.failure !== undefined) throw slot.failure; + const execution = slot.replaySetup?.execution; + if (!execution) throw invalidPlugin('Native replay plugin must provide execution.create()'); + return await (slot.executionLoading ??= Promise.resolve().then(async () => { + try { + const runtime = validateReplayExecution(await execution.create()); + slot.replayFailure = undefined; + inventory.splice(0, inventory.length, ...resolved.inventory()); + return runtime; + } catch (error) { + slot.executionLoading = undefined; + slot.replayFailure = asPluginFailure(error, 'plugin_load_failed'); + inventory.splice(0, inventory.length, ...resolved.inventory()); + throw slot.replayFailure; + } + })); + }, close: once(async () => { closed = true; const [providers, backends] = await Promise.all([ @@ -259,7 +290,7 @@ async function setUpReplaySlot( ): Promise { const result = await plugin.setup(createPluginHost(env, slot.candidate.hostOptions)); try { - slot.replaySetup = validateReplayEngineSetup(result); + slot.replaySetup = validateReplayEngineSetup(result, plugin.backend); } catch (error) { await cleanUpRejectedSetup(result); throw error; @@ -273,22 +304,13 @@ async function resolveRegisteredReplayBackend( host: import('@agent-device/contracts/replay-backend').ReplayBackendHost, packageName?: string, ): Promise { - const slot = - resolved.slots.find((slot) => slot.backend === id) ?? - resolved.slots.find( - (slot) => packageName !== undefined && slot.candidate.package === packageName, - ); - if (!slot) - throw new AppError('INVALID_ARGS', `Replay backend is not installed: ${id}`, { - reason: 'plugin-not-installed', - backend: id, - }); + const slot = requireReplaySlot(resolved, id, packageName); if (slot.failure !== undefined) throw slot.failure; - const setup = slot.replaySetup; - if (!setup) throw invalidPlugin(`Replay backend was not set up: ${id}`); + const replayBackend = slot.replaySetup?.replayBackend; + if (!replayBackend) throw invalidPlugin(`Replay backend was not set up: ${id}`); return await (slot.replayLoading ??= Promise.resolve().then(async () => { try { - const backend = validateReplayBackend(id, await setup.replayBackend.create(host)); + const backend = validateReplayBackend(id, await replayBackend.create(host)); slot.replayFailure = undefined; inventory.splice(0, inventory.length, ...resolved.inventory()); return backend; @@ -301,11 +323,33 @@ async function resolveRegisteredReplayBackend( })); } +function requireReplaySlot( + resolved: ResolvedProviderPlugins, + id: string, + packageName: string | undefined, +): Slot { + const slot = + resolved.slots.find((slot) => slot.backend === id) ?? + resolved.slots.find( + (slot) => + packageName !== undefined && + slot.candidate.package === packageName && + slot.backend === undefined && + slot.failure !== undefined, + ); + if (!slot) + throw new AppError('INVALID_ARGS', `Replay backend is not installed: ${id}`, { + reason: 'plugin-not-installed', + backend: id, + }); + return slot; +} + async function cleanUpReplaySlot(slot: Slot): Promise { const setup = slot.replaySetup; const plugin = slot.replayPlugin; if (!setup || !plugin) return []; - await slot.replayLoading?.catch(() => {}); + await (slot.replayLoading ?? slot.executionLoading)?.catch(() => {}); return [ { backend: plugin.backend, diff --git a/packages/plugins/src/replay-backend.test.ts b/packages/plugins/src/replay-backend.test.ts index 6580069a02..8ab8afddac 100644 --- a/packages/plugins/src/replay-backend.test.ts +++ b/packages/plugins/src/replay-backend.test.ts @@ -2,6 +2,8 @@ import { expect, test, vi } from 'vitest'; import { resolveProviderPlugins, startProviderRegistry } from './registry.ts'; import type { PluginCandidate, PluginRegistryPolicy } from './registry.ts'; import type { ReplayBackend, ReplayBackendHost } from '@agent-device/contracts/replay-backend'; +import { validateReplayEngineSetup } from './validate.ts'; +import type { ReplayExecution } from '@agent-device/contracts/replay-execution'; import type { ProviderPluginHost } from './host.ts'; import type { ReplayEnginePlugin } from './replay-backend.ts'; @@ -176,3 +178,176 @@ test('one backend disposer cannot delay another backend disposer', async () => { release(); expect(await closing).toHaveLength(2); }); + +test('native execution retries failed lazy loads while sharing claims, caching and disposal', async () => { + const execution: ReplayExecution = { + inspectAdReplay: vi.fn(() => { + throw new Error('inspection is outside registry ownership'); + }), + runAdReplay: vi.fn(async () => { + throw new Error('dispatch is outside registry ownership'); + }), + runReplayTestSuite: vi.fn(async () => { + throw new Error('scheduling is outside registry ownership'); + }), + }; + const create = vi + .fn(async () => execution) + .mockRejectedValueOnce(new Error('native engine failed')); + const competing = { setup: vi.fn(() => ({ execution: { create } })) }; + const competingPlugin = { + apiVersion: 2, + kind: 'replay-backend', + backend: 'ad', + setup: competing.setup, + }; + const dispose = vi.fn(); + const registry = await startProviderRegistry( + await resolveProviderPlugins([ + candidate({ + apiVersion: 2, + kind: 'replay-backend', + backend: 'ad', + setup: () => ({ execution: { create }, dispose }), + }), + candidate(competingPlugin), + ]), + {}, + policy, + ); + expect(registry.inventory).toMatchObject([ + { backend: 'ad', state: 'active' }, + { backend: 'ad', state: 'failed', error: { reason: 'duplicate_replay_backend' } }, + ]); + expect(competing.setup).not.toHaveBeenCalled(); + await expect(registry.resolveReplayBackend('ad', host)).rejects.toMatchObject({ + details: { reason: 'invalid_plugin' }, + }); + expect(registry.inventory[0]).toMatchObject({ backend: 'ad', state: 'active' }); + expect(create).not.toHaveBeenCalled(); + await expect(registry.resolveReplayExecution()).rejects.toMatchObject({ + message: 'native engine failed', + details: { reason: 'plugin_load_failed' }, + }); + expect(create).toHaveBeenCalledTimes(1); + expect(registry.inventory[0]).toMatchObject({ + state: 'failed', + error: { reason: 'plugin_load_failed' }, + }); + const [one, two] = await Promise.all([ + registry.resolveReplayExecution(), + registry.resolveReplayExecution(), + ]); + expect(one).toBe(two); + expect(one).toBe(execution); + expect(await registry.resolveReplayExecution()).toBe(one); + expect(create).toHaveBeenCalledTimes(2); + expect(registry.inventory[0]).toMatchObject({ backend: 'ad', state: 'active' }); + expect(registry.inventory[0]?.error).toBeUndefined(); + await registry.close(); + expect(dispose).toHaveBeenCalledTimes(1); + await expect(registry.resolveReplayExecution()).rejects.toMatchObject({ + details: { reason: 'plugin-registry-closed' }, + }); +}); + +test.each([ + [{ apiVersion: 99 }, 'incompatible_plugin'], + [{ setup: () => ({ execution: {} }) }, 'invalid_plugin'], + [ + { + setup: () => { + throw new Error('failed setup'); + }, + }, + 'plugin_setup_failed', + ], + [{ setup: () => ({ execution: { create: () => ({}) } }) }, 'invalid_plugin'], +])( + 'selected native execution failures preserve their typed cause: %s', + async (override, reason) => { + const registry = await startProviderRegistry( + await resolveProviderPlugins([ + candidate({ + apiVersion: 2, + kind: 'replay-backend', + backend: 'ad', + setup: () => ({ execution: { create: () => ({}) } }), + ...override, + }), + ]), + {}, + policy, + ); + await expect(registry.resolveReplayExecution()).rejects.toMatchObject({ details: { reason } }); + await registry.close(); + }, +); + +test.each([ + ['ad', { replayBackend: { create: vi.fn() } }], + ['maestro', { execution: { create: vi.fn() } }], + ['custom', { execution: { create: vi.fn() } }], +])('setup validates the factory against backend %s', (backend, setup) => { + expect(() => validateReplayEngineSetup(setup, backend)).toThrow( + expect.objectContaining({ details: { reason: 'invalid_plugin' } }), + ); +}); + +test('wrong native capability fails inventory, disposes setup and keeps its first claim', async () => { + const wrong = engine('ad'); + const laterSetup = vi.fn(() => ({ execution: { create: vi.fn() } })); + const registry = await startProviderRegistry( + await resolveProviderPlugins([ + candidate(wrong.plugin), + candidate({ apiVersion: 2, kind: 'replay-backend', backend: 'ad', setup: laterSetup }), + candidate(engine('maestro').plugin), + ]), + {}, + policy, + ); + expect(registry.inventory).toMatchObject([ + { backend: 'ad', state: 'failed', error: { reason: 'invalid_plugin' } }, + { backend: 'ad', state: 'failed', error: { reason: 'duplicate_replay_backend' } }, + { backend: 'maestro', state: 'active' }, + ]); + expect(wrong.dispose).toHaveBeenCalledOnce(); + expect(wrong.create).not.toHaveBeenCalled(); + expect(laterSetup).not.toHaveBeenCalled(); + await expect(registry.resolveReplayExecution()).rejects.toMatchObject({ + details: { reason: 'invalid_plugin' }, + }); + await registry.close(); + expect(wrong.dispose).toHaveBeenCalledOnce(); +}); + +test('a package name cannot select an active foreign backend for native execution', async () => { + const maestro = engine(); + const packageName = '@agent-device/maestro'; + const registry = await startProviderRegistry( + await resolveProviderPlugins([ + { ...candidate(maestro.plugin), package: packageName }, + { + source: 'store', + package: '@agent-device/replay', + load: () => { + throw new Error('selected native package is unreadable'); + }, + }, + ]), + {}, + policy, + ); + try { + await expect(registry.resolveReplayExecution(packageName)).rejects.toMatchObject({ + details: { reason: 'plugin-not-installed', backend: 'ad' }, + }); + await expect(registry.resolveReplayExecution('@agent-device/replay')).rejects.toMatchObject({ + details: { reason: 'plugin_load_failed' }, + }); + expect(maestro.create).not.toHaveBeenCalled(); + expect(await registry.resolveReplayBackend('maestro', host, packageName)).toBe(maestro.runtime); + } finally { + await registry.close(); + } +}); diff --git a/packages/plugins/src/replay-backend.ts b/packages/plugins/src/replay-backend.ts index 85884e878c..937419a8cd 100644 --- a/packages/plugins/src/replay-backend.ts +++ b/packages/plugins/src/replay-backend.ts @@ -1,17 +1,30 @@ import type { ReplayBackendPlugin } from '@agent-device/contracts/replay-backend'; +import type { + NATIVE_REPLAY_BACKEND, + ReplayExecutionPlugin, +} from '@agent-device/contracts/replay-execution'; import type { ProviderPluginHost } from './host.ts'; /** A managed v2 replay engine. The host retains sessions, dispatch, cancellation and cleanup. */ -export type ReplayEnginePlugin = Readonly<{ +export type ReplayEnginePlugin = Readonly<{ apiVersion: 2; kind: 'replay-backend'; - backend: string; - setup(host: ProviderPluginHost): Promise | ReplayEngineSetup; + backend: TBackend; + setup( + host: ProviderPluginHost, + ): Promise> | ReplayEngineSetup; }>; -export type ReplayEngineSetup = Readonly<{ - replayBackend: ReplayBackendPlugin; - dispose?(): Promise | void; -}>; +type NativeExecutionSetup = { execution: ReplayExecutionPlugin; replayBackend?: never }; +type FormatBackendSetup = { replayBackend: ReplayBackendPlugin; execution?: never }; + +/** Native execution belongs to ad; other backend ids supply a format engine. */ +export type ReplayEngineSetup = Readonly< + { dispose?(): Promise | void } & (TBackend extends typeof NATIVE_REPLAY_BACKEND + ? NativeExecutionSetup + : string extends TBackend + ? NativeExecutionSetup | FormatBackendSetup + : FormatBackendSetup) +>; export type { ReplayBackendResolver } from '@agent-device/contracts/replay-backend'; diff --git a/packages/plugins/src/validate.ts b/packages/plugins/src/validate.ts index 10ffdeae9a..cc776900c6 100644 --- a/packages/plugins/src/validate.ts +++ b/packages/plugins/src/validate.ts @@ -1,3 +1,5 @@ +import { NATIVE_REPLAY_BACKEND } from '@agent-device/contracts/replay-execution'; +import type { ReplayExecution } from '@agent-device/contracts/replay-execution'; import type { ReplayBackend } from '@agent-device/contracts/replay-backend'; import type { ReplayEnginePlugin, ReplayEngineSetup } from './replay-backend.ts'; import { AppError } from '@agent-device/kernel/errors'; @@ -158,15 +160,35 @@ export function validateReplayEnginePlugin(value: unknown): ReplayEnginePlugin { return value as ReplayEnginePlugin; } -export function validateReplayEngineSetup(value: unknown): ReplayEngineSetup { +export function validateReplayEngineSetup( + value: unknown, + backend: TBackend, +): ReplayEngineSetup { + if (!isRecord(value) || (value.dispose !== undefined && typeof value.dispose !== 'function')) + throw invalidPlugin('Replay plugin setup must provide a factory and optional dispose()'); + const native = backend === NATIVE_REPLAY_BACKEND; + const factory = native ? value.execution : value.replayBackend; + const other = native ? value.replayBackend : value.execution; + if (other !== undefined || !isRecord(factory) || typeof factory.create !== 'function') + throw invalidPlugin( + native + ? 'Native ad backend setup must provide execution.create()' + : 'Format backend setup must provide replayBackend.create(host)', + ); + return value as ReplayEngineSetup; +} + +export function validateReplayExecution(value: unknown): ReplayExecution { if ( !isRecord(value) || - !isRecord(value.replayBackend) || - typeof value.replayBackend.create !== 'function' || - (value.dispose !== undefined && typeof value.dispose !== 'function') + (['inspectAdReplay', 'runAdReplay', 'runReplayTestSuite'] as const).some( + (name) => typeof value[name] !== 'function', + ) ) - throw invalidPlugin('Replay plugin setup must return replayBackend.create(host)'); - return value as ReplayEngineSetup; + throw invalidPlugin( + 'Native replay execution must provide inspection, replay and suite execution', + ); + return value as ReplayExecution; } export function validateReplayBackend(id: string, value: unknown): ReplayBackend { diff --git a/packages/plugins/tsconfig.json b/packages/plugins/tsconfig.json index 380be0b4f5..4ddd6ceaf5 100644 --- a/packages/plugins/tsconfig.json +++ b/packages/plugins/tsconfig.json @@ -11,9 +11,17 @@ }, "include": ["src"], "references": [ - { "path": "../contracts" }, - { "path": "../host-kit" }, - { "path": "../kernel" }, - { "path": "../test-kit" } + { + "path": "../contracts" + }, + { + "path": "../host-kit" + }, + { + "path": "../kernel" + }, + { + "path": "../test-kit" + } ] } diff --git a/scripts/layering/contracts-exports.snapshot.json b/scripts/layering/contracts-exports.snapshot.json index 8481c3e0ac..28387cd2a0 100644 --- a/scripts/layering/contracts-exports.snapshot.json +++ b/scripts/layering/contracts-exports.snapshot.json @@ -105,6 +105,7 @@ "@agent-device/contracts/replay", "@agent-device/contracts/replay-backend", "@agent-device/contracts/replay-divergence-data", + "@agent-device/contracts/replay-execution", "@agent-device/contracts/replay-script-data", "@agent-device/contracts/replay-test-execution", "@agent-device/contracts/runner-lease-context", diff --git a/src/host-replay.test.ts b/src/host-replay.test.ts index 81c317a697..0174eadba8 100644 --- a/src/host-replay.test.ts +++ b/src/host-replay.test.ts @@ -124,11 +124,13 @@ async function trackedPlugin() { setup: async (host) => { calls.setup += 1; const setup = await maestro.setup(host); + if (!setup.replayBackend) throw new Error('Expected a format backend'); + const replayBackend = setup.replayBackend; return { replayBackend: { create: async (host) => { calls.create += 1; - const backend = await setup.replayBackend.create(host); + const backend = await replayBackend.create(host); return { ...backend, collectSourceFiles: (params) => { diff --git a/src/sdk/plugins.ts b/src/sdk/plugins.ts index 851631fa16..411bccad5a 100644 --- a/src/sdk/plugins.ts +++ b/src/sdk/plugins.ts @@ -28,3 +28,9 @@ export type AgentDevicePluginFactory> = Contra export type { ReplayEnginePlugin, ReplayEngineSetup } from '@agent-device/plugins/replay-backend'; export type { ReplayBackend, ReplayBackendHost } from '@agent-device/contracts/replay-backend'; + +export type { + ReplayExecution, + ReplayExecutionPlugin, + ReplayExecutionResolver, +} from '@agent-device/contracts/replay-execution';