fix(amp): colocate standalone event workers

.changeset/fix-amp-event-worker.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Keep standalone event workers beside nested Amp hook wrappers so relocated plugins can execute event routes (#740).

packages/agent-bundle/src/build/entries.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
-import { dirname, extname, join, relative, resolve } from 'node:path';
+import { dirname, extname, join, posix, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { hooksFlightWorkerPath } from '../adapters/composite-layout.ts';
@@ -570,15 +570,24 @@ const hookEntrySourceInputs = (entry: TargetHookEntry): readonly string[] => {
   ]);
 };
 
+const requiresStandaloneHookWorker = (entry: TargetHookEntry): boolean =>
+  entry.hook.eventRoute?.runtime === 'standalone' || entry.hook.eventRoute?.fallback === 'standalone';
+
+const hookWorkerPath = (entry: TargetHookEntry): string =>
+  posix.join(posix.dirname(entry.relativePath), posix.basename(hooksFlightWorkerPath));
+
 export const planCompiledHooks = (
   entries: readonly TargetHookEntry[],
   options: { readonly outDir: string },
 ): readonly CompiledHookEntry[] => {
-  const workerOwner = entries.findIndex((entry) =>
-    entry.hook.eventRoute?.runtime === 'standalone' || entry.hook.eventRoute?.fallback === 'standalone');
+  const workerOwners = new Map<string, number>();
+  entries.forEach((entry, index) => {
+    if (requiresStandaloneHookWorker(entry) && !workerOwners.has(hookWorkerPath(entry))) {
+      workerOwners.set(hookWorkerPath(entry), index);
+    }
+  });
   const workerSourceInputs = Object.freeze([...new Set(entries
-    .filter((entry) =>
-      entry.hook.eventRoute?.runtime === 'standalone' || entry.hook.eventRoute?.fallback === 'standalone')
+    .filter(requiresStandaloneHookWorker)
     .flatMap((entry) => [entry.hook.provenance.sourcePath, entry.hook.source]))]);
   return deepFreeze(entries.map((entry, index) => ({
     event: entry.event,
@@ -600,9 +609,9 @@ export const planCompiledHooks = (
         executorSourceInputs: Object.freeze([entry.hook.provenance.sourcePath, entry.hook.source]),
       }),
     ...(entry.timeout === undefined ? {} : { timeout: entry.timeout }),
-    ...(index === workerOwner
+    ...(workerOwners.get(hookWorkerPath(entry)) === index
       ? {
-        workerOutput: resolveArtifactDestination(options.outDir, hooksFlightWorkerPath),
+        workerOutput: resolveArtifactDestination(options.outDir, hookWorkerPath(entry)),
         workerSourceInputs,
       }
       : {}),
@@ -629,39 +638,41 @@ export const planHooksSurface = (
   const compiled = planCompiledHooks(entries, options);
   const routeEntries = entries.filter((entry) => entry.hook.eventRoute !== undefined);
   const standaloneEventRoutes = [...new Map(routeEntries
-    .filter((entry) =>
-      entry.hook.eventRoute?.runtime === 'standalone' || entry.hook.eventRoute?.fallback === 'standalone')
+    .filter(requiresStandaloneHookWorker)
     .map((entry) => [entry.hook.id, entry.hook])).values()];
+  const workerPlans = [...new Map(entries
+    .filter(requiresStandaloneHookWorker)
+    .map((entry) => [hookWorkerPath(entry), entry.hook])).entries()];
   const workerArtifactEpoch = generatedRouteArtifactEpoch(options.plugin);
   const eventIpcRuntime = routeEntries.length === 0 ? undefined : eventRuntimeModulePath('ipc');
   const eventProjectRuntime = routeEntries.length === 0 ? undefined : eventRuntimeModulePath('project');
   const launchEnvRuntime = launchEnvRuntimePath();
-  const workerEntry = standaloneEventRoutes.length === 0
-    ? undefined
-    : {
-      name: 'hooks-flight',
-      outputRelativePath: hooksFlightWorkerPath,
-      reactServer: true as const,
-      rscManifest: true as const,
-      source: standaloneEventRoutes[0]!.source,
-      sourceInputs: Object.freeze([
-        ...new Set([
-          ...standaloneEventRoutes.flatMap((hook) => [hook.provenance.sourcePath, hook.source]),
-          ...(options.providers ?? []).map((provider) => provider.source),
-          ...(options.state === undefined ? [] : [options.state.provenance.sourcePath, options.state.source]),
-        ]),
+  const workerEntries = workerPlans.map(([outputRelativePath, hook]) => ({
+    name: outputRelativePath === hooksFlightWorkerPath
+      ? 'hooks-flight'
+      : outputRelativePath.replaceAll('/', '-').replace(/\.mjs$/u, ''),
+    outputRelativePath,
+    reactServer: true as const,
+    rscManifest: true as const,
+    source: hook.source,
+    sourceInputs: Object.freeze([
+      ...new Set([
+        ...standaloneEventRoutes.flatMap((hook) => [hook.provenance.sourcePath, hook.source]),
+        ...(options.providers ?? []).map((provider) => provider.source),
+        ...(options.state === undefined ? [] : [options.state.provenance.sourcePath, options.state.source]),
       ]),
-      virtualSource: generatedRouteFlightWorkerSource({
-        artifactEpoch: workerArtifactEpoch,
-        eventRoutes: standaloneEventRoutes,
-        ...(options.noticeDelivery === undefined ? {} : { noticeDelivery: options.noticeDelivery }),
-        providers: options.providers ?? [],
-        routes: [],
-        serverName: 'hooks',
-        ...(options.noticeRetention === undefined ? {} : { noticeRetention: options.noticeRetention }),
-        ...(options.state === undefined ? {} : { state: options.state }),
-      }),
-    };
+    ]),
+    virtualSource: generatedRouteFlightWorkerSource({
+      artifactEpoch: workerArtifactEpoch,
+      eventRoutes: standaloneEventRoutes,
+      ...(options.noticeDelivery === undefined ? {} : { noticeDelivery: options.noticeDelivery }),
+      providers: options.providers ?? [],
+      routes: [],
+      serverName: 'hooks',
+      ...(options.noticeRetention === undefined ? {} : { noticeRetention: options.noticeRetention }),
+      ...(options.state === undefined ? {} : { state: options.state }),
+    }),
+  }));
   return {
     entries: [
       ...compiled.flatMap((entry, index) => {
@@ -716,7 +727,7 @@ export const planHooksSurface = (
           },
         ];
       }),
-      ...(workerEntry === undefined ? [] : [workerEntry]),
+      ...workerEntries,
     ],
     ignoredSourcePaths: [
       runtimeIgnoredRoot(launchEnvRuntime),
@@ -732,7 +743,7 @@ export const planHooksSurface = (
             ?? (() => { throw new Error(`Missing bundled deferred hook executor evidence for ${JSON.stringify(entry.name)}.`); })(),
         }),
         ...(entry.workerOutput === undefined ? {} : {
-          workerSourceInputs: evidenceByPath.get(hooksFlightWorkerPath) ?? (() => { throw new Error('Missing bundled hook Flight worker evidence.'); })(),
+          workerSourceInputs: evidenceByPath.get(hookWorkerPath(entries[index]!)) ?? (() => { throw new Error('Missing bundled hook Flight worker evidence.'); })(),
         }),
       })));
     },

packages/agent-bundle/src/dev/routes/route-invocation-service.ts

@@ -2,7 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { fork, type ChildProcess } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, posix, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import type { AgentDocument, AgentDocumentNode, AgentRenderEvent } from '@agent-bundle/runtime';
@@ -603,7 +603,11 @@ const productionBindingFor = (
         && candidate.hosts.some((candidateHost) => eligibleHosts.has(candidateHost))
         && candidate.launch?.worker !== undefined))
       .find((candidate) => candidate !== undefined);
-    const standalone = manifest.files.find((file) => file.path === hooksFlightWorkerPath)?.path;
+    const standalone = [
+      ...(wrapper === undefined ? wrappers : [wrapper])
+        .map((candidate) => posix.join(posix.dirname(candidate.path), posix.basename(hooksFlightWorkerPath))),
+      hooksFlightWorkerPath,
+    ].find((candidate) => manifest.files.some((file) => file.path === candidate));
     const executable = execution.runtime === 'standalone'
       ? standalone
       : shared?.launch?.worker ?? (execution.fallback === 'standalone' ? standalone : undefined);

packages/agent-bundle/tests/amp-adapter.test.ts

@@ -13,7 +13,7 @@ import { validateArtifact } from '../src/build/validate-artifact.ts';
 import type { JsonObject } from '../src/core/strict-json.ts';
 import type { NormalizedHook, NormalizedPlugin } from '../src/core/types.ts';
 import { projectEventDocument } from '../src/events/projection.ts';
-import { emptyCompiledRouteGraph } from '../src/routes/graph.ts';
+import { compileRouteGraph, emptyCompiledRouteGraph } from '../src/routes/graph.ts';
 import { build } from './support/build.ts';
 import { runNodeScript } from './support/run-node-script.ts';
 
@@ -745,3 +745,88 @@ it('compiles a nested Amp hook wrapper that returns the documented tool.call dec
     await rm(projectRoot, { force: true, recursive: true });
   }
 });
+
+it('runs a relocated standalone event route with its worker inside the Amp plugin', async () => {
+  const projectRoot = await mkdtemp(join(process.cwd(), 'packages', 'agent-bundle', '.amp-event-route-'));
+  const config = join(projectRoot, 'agent-bundle.config.ts');
+  const handler = join(projectRoot, 'src', 'events', 'tool', 'before.tsx');
+  const outputRoot = join(projectRoot, 'artifact');
+  const relocated = join(projectRoot, 'relocated');
+  await mkdir(join(projectRoot, 'src', 'events', 'tool'), { recursive: true });
+  await writeFile(config, 'export default {};\n');
+  await writeFile(handler, [
+    "import { Agent } from '@agent-bundle/runtime';",
+    "import { createElement } from 'react';",
+    "export const config = { runtime: 'standalone' };",
+    "export default async function BeforeTool() {",
+    "  return createElement(Agent.Result, { value: { outcome: 'deny', reason: 'blocked' } });",
+    '}',
+    '',
+  ].join('\n'));
+  const base = plugin();
+  const hook = eventHook('tool-before', 'beforeTool', 'tool/before');
+  const model: NormalizedPlugin = {
+    ...base,
+    hooks: [{
+      ...hook,
+      id: 'hook:event-route:tool-before',
+      name: 'event-route-tool-before',
+      provenance: { kind: 'conventional', sourcePath: handler },
+      source: handler,
+    }],
+    mcpServers: [],
+    metadata: { ...base.metadata, provenance: { kind: 'config', sourcePath: config } },
+    skills: [],
+    targets: [{
+      id: 'target:amp',
+      name: 'amp',
+      provenance: { kind: 'config', sourcePath: config },
+    }],
+  };
+
+  try {
+    const registry = createDefaultRegistry();
+    const routeGraph = await compileRouteGraph(projectRoot, {
+      plugin: { name: 'amp-review', version: '1.0.0' },
+    });
+    const built = await build({
+      model,
+      outputRoot,
+      projectRoot: join(process.cwd(), 'packages', 'agent-bundle'),
+      registry,
+      routeGraph,
+    });
+    const wrapper = '.amp/plugins/amp-review/hooks/event-route-tool-before.mjs';
+    const worker = '.amp/plugins/amp-review/hooks/hooks-flight.mjs';
+    expect(built.manifest.projections).toEqual([{
+      builtInHost: 'amp',
+      documents: { entry: '.amp/plugins/amp-review/index.js' },
+      host: 'amp',
+    }]);
+    expect(built.manifest.files.map((file) => file.path)).toContain(worker);
+    expect(built.manifest.files.map((file) => file.path).filter((path) => path.endsWith('/index.js')))
+      .toEqual(['.amp/plugins/amp-review/index.js']);
+    expect(built.manifest.compiler.provenance).toContainEqual(expect.objectContaining({ path: worker }));
+    expect(built.compileEvidence.assets).toContainEqual(expect.objectContaining({ path: worker }));
+    expect(await validateArtifact({ artifactRoot: outputRoot, registry })).toEqual([]);
+
+    await rename(outputRoot, relocated);
+    const result = await runNodeScript({
+      args: [join(relocated, wrapper)],
+      input: JSON.stringify({
+        hook_event_name: 'tool.call',
+        session_id: 'thread-1',
+        tool_input: { command: 'pwd' },
+        tool_name: 'shell',
+        tool_use_id: 'tool-1',
+      }),
+    });
+    expect(result).toEqual({
+      code: 0,
+      stderr: '',
+      stdout: '{"action":"reject-and-continue","message":"blocked"}',
+    });
+  } finally {
+    await rm(projectRoot, { force: true, recursive: true });
+  }
+});

packages/agent-bundle/tests/amp-install.test.ts

@@ -20,7 +20,9 @@
 ): Promise<void> => {
   const plugin = join(root, '.amp', 'plugins', name);
   await mkdir(join(plugin, 'skills', 'review'), { recursive: true });
+  await mkdir(join(plugin, 'hooks'), { recursive: true });
   await writeFile(join(plugin, 'index.js'), `export default async function () { /* ${marker} */ }\n`);
+  await writeFile(join(plugin, 'hooks', 'hooks-flight.mjs'), `export const marker = ${JSON.stringify(marker)};\n`);
   await writeFile(join(plugin, 'skills', 'review', 'SKILL.md'), '---\nname: review\ndescription: Review code.\n---\n');
   await writeFile(join(root, 'outside.txt'), 'must not be installed\n');
   await writeInstallFixtureManifest(root, { name, version }, [{ host: 'amp' }]);
@@ -52,7 +54,7 @@
       scope: 'user',
     });
 
     expect(installed).toMatchObject({
       destination,
       host: 'amp',
       mode: 'local',
@@ -65,8 +67,10 @@
       'Run `amp plugins list` in a shell to inspect the installed plugin.',
     ]);
     await expect(readFile(join(destination, 'index.js'), 'utf8')).resolves.toContain('first');
+    await expect(readFile(join(destination, 'hooks', 'hooks-flight.mjs'), 'utf8')).resolves.toContain('first');
     await expect(readFile(join(destination, 'outside.txt'), 'utf8')).rejects.toThrow();
     expect(await readInstallReceipt(destination)).toMatchObject({
+      files: expect.arrayContaining(['hooks/hooks-flight.mjs']),
       host: 'amp',
       mode: 'local',
       plugin: pluginName,
@@ -94,6 +98,7 @@
     });
     expect(replaced.state).toBe('replaced');
     await expect(readFile(join(destination, 'index.js'), 'utf8')).resolves.toContain('second');
+    await expect(readFile(join(destination, 'hooks', 'hooks-flight.mjs'), 'utf8')).resolves.toContain('second');
     await expect(readFile(join(destination, 'disabled-state.json'), 'utf8')).resolves.toBe('{"disabled":true}\n');
     await expect(readFile(settings, 'utf8')).resolves.toBe('{"amp.plugins.disabled":["amp-install-fixture"]}\n');
 
@@ -122,6 +127,7 @@
       state: 'uninstalled',
     });
     await expect(readFile(join(destination, 'index.js'), 'utf8')).rejects.toThrow();
+    await expect(readFile(join(destination, 'hooks', 'hooks-flight.mjs'), 'utf8')).rejects.toThrow();
     await expect(readFile(join(destination, 'skills', 'review', 'SKILL.md'), 'utf8')).rejects.toThrow();
     await expect(readFile(join(destination, 'disabled-state.json'), 'utf8')).resolves.toBe('{"disabled":true}\n');
     await expect(readFile(settings, 'utf8')).resolves.toBe('{"amp.plugins.disabled":["amp-install-fixture"]}\n');
@@ -193,7 +199,7 @@
       host: 'amp',
       scope: 'user',
     });
     expect(installed.destination).toBe(join(home, '.config', 'amp', 'plugins', name));
   } finally {
     await rm(root, { force: true, recursive: true });
   }
@@ -243,7 +249,7 @@
       host: 'amp',
       replace: true,
       scope: 'user',
     })).rejects.toThrow('foreign install');
     await expect(readFile(join(destination, 'index.js'), 'utf8')).resolves.toContain('foreign');
   } finally {
     await rm(root, { force: true, recursive: true });
@@ -268,7 +274,7 @@
       home,
       host: 'amp',
       scope: 'user',
     })).rejects.toThrow('unsupported filesystem entry');
     expect(await readdir(outside)).toEqual([]);
   } finally {
     await rm(root, { force: true, recursive: true });

packages/agent-bundle/tests/entries.test.ts

@@ -171,4 +171,45 @@ describe('event-route preflight source graph (#595)', () => {
     expect(executor.virtualSource).toContain('requestEventRuntime');
     expect(executor.virtualSource).toContain('preflight-entries@1.0.0');
   });
+
+  it('emits the standalone worker beside a nested host wrapper', () => {
+    const standalone = {
+      ...hook,
+      eventRoute: { event: 'tool/before' as const, fallback: 'none' as const, runtime: 'standalone' as const },
+      targets: ['amp'],
+    };
+    const nested = planHooks({ ...model, hooks: [standalone] }, 'amp', {
+      commandRoot: '',
+      encodePlaygroundInput: (input) => input,
+      encodePlaygroundOutput: (result) => result,
+      eventNames: {},
+      eventRouteNames: { 'tool/before': 'tool.call' },
+      hostContractRevision: 'test',
+      manifestPath: '.amp/hooks.json',
+      matchers: {},
+      registration: 'api',
+      wrapperPath: (candidate) => `.amp/plugins/preflight-entries/hooks/${candidate.name}.mjs`,
+      wrapperSource: () => 'config-hook-only\n',
+    }).hookEntries;
+    const rootWrapper = {
+      ...nested[0]!,
+      relativePath: 'hooks/event-route-tool-before.claude.mjs',
+      target: 'claude',
+    };
+    const combined = [rootWrapper, ...nested];
+    const workers = [
+      'hooks/hooks-flight.mjs',
+      '.amp/plugins/preflight-entries/hooks/hooks-flight.mjs',
+    ];
+
+    expect(planCompiledHooks(combined, { outDir: '/tmp/artifact' })
+      .flatMap((entry) => entry.workerOutput === undefined ? [] : [entry.workerOutput]))
+      .toEqual(workers.map((worker) => `/tmp/artifact/${worker}`));
+    const outputs = planHooksSurface(combined, {
+      artifactEpoch: 'preflight-entries@1.0.0',
+      outDir: '/tmp/artifact',
+      plugin: { name: 'preflight-entries', version: '1.0.0' },
+    }).entries.map((entry) => entry.outputRelativePath);
+    expect(outputs).toEqual(expect.arrayContaining(workers));
+  });
 });

packages/agent-bundle/tests/route-invocation-service.test.ts

@@ -463,7 +463,20 @@ it('publishes failed event invocations with native provenance', async () => {
   });
 });
 
-it('keeps hostless shared events on their declared standalone fallback', async () => {
+it.each([
+  {
+    host: 'claude',
+    label: 'the shared root',
+    worker: 'hooks/hooks-flight.mjs',
+    wrapper: 'hooks/event-route-tool-after.claude.mjs',
+  },
+  {
+    host: 'amp',
+    label: 'a nested Amp plugin',
+    worker: '.amp/plugins/fixture/hooks/hooks-flight.mjs',
+    wrapper: '.amp/plugins/fixture/hooks/event-route-tool-after.mjs',
+  },
+] as const)('keeps hostless shared events on the standalone fallback in $label', async ({ host, worker, wrapper }) => {
   const route = {
     config: [],
     event: 'tool/after',
@@ -492,14 +505,14 @@ it('keeps hostless shared events on their declared standalone fallback', async (
           manifest: {
             executables: {
               hooks: [{
-                host: 'claude',
+                host,
                 kind: 'event-route',
-                path: 'hooks/event-route-tool-after.claude.mjs',
+                path: wrapper,
                 routeId: route.id,
               }],
               mcpServers: [],
             },
-            files: [{ path: 'hooks/hooks-flight.mjs' }],
+            files: [{ path: worker }],
             routes: {
               digest: 'digest',
               events: [{
@@ -531,7 +544,10 @@ it('keeps hostless shared events on their declared standalone fallback', async (
     diagnostics: [{ code: 'AB8236' }],
     status: 'failed',
   });
-  expect(production).toEqual({ executable: 'hooks/hooks-flight.mjs', kind: 'direct' });
+  expect(production).toEqual({
+    executable: worker,
+    kind: 'direct',
+  });
 });
 
 const echoRoute = {