Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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>;
-}