The Open Framework for Building Agents
fix(eve): make hook declarations portable (#916)
Casey Gowrieb2bc6b60badd
diff --git a/.changeset/tidy-hooks-travel.md b/.changeset/tidy-hooks-travel.mdnew file mode 100644index 000000000..8c428e474--- /dev/null+++ b/.changeset/tidy-hooks-travel.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Make default-exported hooks emit portable extension declarations while preserving typed event handlers and authored event keys.diff --git a/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts b/packages/eve/src/internal/nitro/host/build-extension.scenario.test.tsindex 39692d8b3..7195e4407 100644--- a/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts+++ b/packages/eve/src/internal/nitro/host/build-extension.scenario.test.ts@@ -132,6 +132,35 @@ describe("extension build output", () => {);});+ it("emits portable declarations for default-exported hooks", async () => {+ const root = await createExtensionPackage();+ await mkdir(join(root, "extension", "hooks"), { recursive: true });+ await writeFile(+ join(root, "extension", "hooks", "audit.ts"),+ [+ 'import { defineHook } from "eve/hooks";',+ "",+ "export default defineHook({",+ " events: {",+ ' "action.result"(event) {',+ " console.info(event.data.result);",+ " },",+ " },",+ "});",+ "",+ ].join("\n"),+ "utf8",+ );+ const config = await tryReadExtensionBuildConfig(root);+ const outDir = await buildExtensionPackage(root, config!);++ const declaration = await readFile(join(outDir, "extension", "hooks", "audit.d.ts"), "utf8");+ expect(declaration).toMatch(+ /import\(["']eve\/hooks["']\)\.HookDefinition<["']action\.result["']>/,+ );+ expect(declaration).not.toContain("protocol/message");+ });+it("copies data files and stamps only the extension capabilities in use", async () => {const root = await createExtensionPackage();await writeFile(diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.tsindex c9e5de71f..23a9e0185 100644--- a/packages/eve/src/public/definitions/exact.test.ts+++ b/packages/eve/src/public/definitions/exact.test.ts@@ -1,10 +1,16 @@-import { describe, expect, it } from "vitest";+import { describe, expect, expectTypeOf, it } from "vitest";+import type { HandleMessageStreamEvent } from "#protocol/message.js";import { defineAgent } from "#public/definitions/agent.js";import { none } from "#public/channels/auth.js";import { eveChannel, defaultEveAuth } from "#public/channels/eve.js";import { defineChannel, POST } from "#public/definitions/channel.js";-import { defineHook, type StreamEventHook } from "#public/definitions/hook.js";+import {+ defineHook,+ type HookDefinition,+ type HookEventMap,+ type StreamEventHook,+} from "#public/definitions/hook.js";import { defineInstructions } from "#public/definitions/instructions.js";import { defineInstrumentation } from "#public/definitions/instrumentation.js";import { defineSandbox } from "#public/definitions/sandbox.js";@@ -34,6 +40,10 @@ describe("definition helper exact inputs", () => {expect(experimental_workflow({ maxSubagents: 6 }).maxSubagents).toBe(6);expect(schedule.cron).toBe("0 9 * * *");});++ it("keeps the public hook event map aligned with runtime stream events", () => {+ expectTypeOf<keyof HookEventMap>().toEqualTypeOf<HandleMessageStreamEvent["type"]>();+ });});function typeOnlyFixtures(): void {@@ -182,6 +192,25 @@ function typeOnlyFixtures(): void {},});+ const actionResultHook = defineHook({+ events: {+ "action.result"(event) {+ const eventType: "action.result" = event.type;+ const result = event.data.result;+ void eventType;+ void result;+ },+ },+ });+ expectTypeOf(actionResultHook).toEqualTypeOf<HookDefinition<"action.result">>();++ defineHook({+ events: {+ // @ts-expect-error Hook subscribers must use a public hook event key.+ "internal.event"() {},+ },+ });+eveChannel({auth: none(),onMessage(ctx, message) {diff --git a/packages/eve/src/public/definitions/hook.ts b/packages/eve/src/public/definitions/hook.tsindex 2711f833f..2a9abb4dd 100644--- a/packages/eve/src/public/definitions/hook.ts+++ b/packages/eve/src/public/definitions/hook.ts@@ -1,7 +1,60 @@import type { HandleMessageStreamEvent } from "../../protocol/message.js";import type { SessionContext } from "./callback-context.js";import type { ExactDefinition } from "./exact.js";-import type { GenericHookDefinition, GenericStreamEventHooks } from "#shared/hook-definition.js";++type ProtocolEvent<TType extends HandleMessageStreamEvent["type"]> = Extract<+ HandleMessageStreamEvent,+ { type: TType }+>;++/**+ * Public event contract available to authored hooks.+ *+ * The explicit map keeps hook compatibility independent from the internal+ * protocol union: new protocol events do not become extension hook events+ * until eve exposes them here.+ */+export interface HookEventMap {+ readonly "action.result": ProtocolEvent<"action.result">;+ readonly "actions.requested": ProtocolEvent<"actions.requested">;+ readonly "authorization.completed": ProtocolEvent<"authorization.completed">;+ readonly "authorization.required": ProtocolEvent<"authorization.required">;+ readonly "compaction.completed": ProtocolEvent<"compaction.completed">;+ readonly "compaction.requested": ProtocolEvent<"compaction.requested">;+ readonly "input.requested": ProtocolEvent<"input.requested">;+ readonly "message.appended": ProtocolEvent<"message.appended">;+ readonly "message.completed": ProtocolEvent<"message.completed">;+ readonly "message.received": ProtocolEvent<"message.received">;+ readonly "reasoning.appended": ProtocolEvent<"reasoning.appended">;+ readonly "reasoning.completed": ProtocolEvent<"reasoning.completed">;+ readonly "result.completed": ProtocolEvent<"result.completed">;+ readonly "session.completed": ProtocolEvent<"session.completed">;+ readonly "session.failed": ProtocolEvent<"session.failed">;+ readonly "session.started": ProtocolEvent<"session.started">;+ readonly "session.waiting": ProtocolEvent<"session.waiting">;+ readonly "step.completed": ProtocolEvent<"step.completed">;+ readonly "step.failed": ProtocolEvent<"step.failed">;+ readonly "step.started": ProtocolEvent<"step.started">;+ readonly "subagent.called": ProtocolEvent<"subagent.called">;+ readonly "subagent.completed": ProtocolEvent<"subagent.completed">;+ readonly "subagent.event": ProtocolEvent<"subagent.event">;+ readonly "subagent.started": ProtocolEvent<"subagent.started">;+ readonly "turn.cancelled": ProtocolEvent<"turn.cancelled">;+ readonly "turn.completed": ProtocolEvent<"turn.completed">;+ readonly "turn.failed": ProtocolEvent<"turn.failed">;+ readonly "turn.started": ProtocolEvent<"turn.started">;+}++/** Event type discriminators available to authored hooks. */+export type HookEventType = keyof HookEventMap;++/** Authored hook event keys, including the wildcard subscriber. */+export type HookEventKey = HookEventType | "*";++/** Event received by a handler for one authored hook event key. */+export type HookEvent<TKey extends HookEventKey = HookEventType> = TKey extends HookEventType+ ? HookEventMap[TKey]+ : HookEventMap[HookEventType];/*** Every hook handler receives this context.@@ -23,9 +76,9 @@ export interface HookContext extends SessionContext {/*** Side-effect-only handler for one accepted runtime stream event.*- * `TEvent` is one variant of the runtime stream-event union (a member of- * {@link HandleMessageStreamEvent}). {@link StreamEventHooks} infers `TEvent`- * from the event key. The typed event is the first argument, `ctx` is the last.+ * `TEvent` is one variant of {@link HookEvent}. {@link StreamEventHooks}+ * infers it from the event key. The typed event is the first argument, `ctx`+ * is the last.*/export type StreamEventHook<TEvent> = (event: TEvent, ctx: HookContext) => void | Promise<void>;@@ -35,7 +88,9 @@ export type StreamEventHook<TEvent> = (event: TEvent, ctx: HookContext) => void* `*` matches every accepted runtime stream event and runs after the* typed handler for that event (if any).*/-export type StreamEventHooks = GenericStreamEventHooks<HandleMessageStreamEvent, HookContext>;+export type StreamEventHooks<TKey extends HookEventKey = HookEventKey> = {+ readonly [TKey_ in TKey]?: StreamEventHook<HookEvent<TKey_>>;+};/*** Public hook definition authored in `agent/hooks/*.ts`.@@ -46,17 +101,24 @@ export type StreamEventHooks = GenericStreamEventHooks<HandleMessageStreamEvent,* contribute runtime model messages, use `defineDynamic` +* `defineInstructions` in `agent/instructions/`.*/-export type HookDefinition = GenericHookDefinition<HandleMessageStreamEvent, HookContext>;+export interface HookDefinition<TKey extends HookEventKey = HookEventKey> {+ readonly events?: StreamEventHooks<TKey>;+}++type DefinedHookEventKeys<TDefinition extends HookDefinition> = Extract<+ keyof NonNullable<TDefinition["events"]>,+ HookEventKey+>;/**- * Identity-with-types helper. Returns the passed definition unchanged- * (identity at runtime) while preserving literal inference and rejecting- * any authored key outside `events` as a compile-time error. Authors export- * `defineHook({ events: { "session.started": (event, ctx) => { ... } } })`- * and receive a typed {@link HookDefinition}.+ * Identity-with-types helper. Returns the passed definition unchanged at+ * runtime while preserving its authored event keys behind the public+ * {@link HookDefinition} boundary and rejecting any key outside `events`.+ * Authors export+ * `defineHook({ events: { "session.started": (event, ctx) => { ... } } })`.*/-export function defineHook<T extends HookDefinition>(+export function defineHook<const T extends HookDefinition>(definition: ExactDefinition<T, HookDefinition>,-): T {+): HookDefinition<DefinedHookEventKeys<T>> {return definition;}diff --git a/packages/eve/src/public/hooks/index.ts b/packages/eve/src/public/hooks/index.tsindex 314b5c928..aeeb55dce 100644--- a/packages/eve/src/public/hooks/index.ts+++ b/packages/eve/src/public/hooks/index.ts@@ -9,6 +9,10 @@export {type HookContext,type HookDefinition,+ type HookEvent,+ type HookEventKey,+ type HookEventMap,+ type HookEventType,type StreamEventHook,type StreamEventHooks,defineHook,diff --git a/packages/eve/src/shared/hook-definition.ts b/packages/eve/src/shared/hook-definition.tsdeleted file mode 100644index 733660d45..000000000--- a/packages/eve/src/shared/hook-definition.ts+++ /dev/null@@ -1,37 +0,0 @@-type BaseEvent = { type: string };--/**- * Side-effect-only handler for one accepted runtime stream event.- *- * `TEvent` is one variant of the runtime stream-event union.- * {@link GenericStreamEventHooks} infers `TEvent` from the event key.- */-export type GenericStreamEventHook<TEvent extends BaseEvent, TContext> = (- event: TEvent,- ctx: TContext,-) => void | Promise<void>;--/**- * Map of stream-event subscribers an authored hook file may declare.- *- * `*` matches every accepted runtime stream event and runs after the- * typed handler for that event (if any).- */-export type GenericStreamEventHooks<TEvent extends BaseEvent, TContext> = {- readonly "*"?: GenericStreamEventHook<TEvent, TContext>;-} & {- readonly [K in TEvent["type"]]?: GenericStreamEventHook<Extract<TEvent, { type: K }>, TContext>;-};--/**- * Public hook definition authored in `agent/hooks/*.ts`.- *- * Hook files declare stream-event subscribers (under `events:`) that- * fire after eve has accepted and durably recorded each event.- * Handlers are observe-only: they cannot inject model context. To- * contribute runtime model messages, use `defineDynamic` +- * `defineInstructions` in `agent/instructions/`.- */-export interface GenericHookDefinition<TEvent extends BaseEvent, TContext> {- readonly events?: GenericStreamEventHooks<TEvent, TContext>;-}