docs(agent): document harness hook design

2026-05-16 01:06:27 +02:00
parent 4f40f62b7b
commit b4ee3aaeea
2 changed files with 629 additions and 170 deletions
--- a/packages/agent/docs/hooks.md
+++ b/packages/agent/docs/hooks.md
@@ -0,0 +1,465 @@
+# AgentHarness hooks design
+
+This document describes the target hook system for `AgentHarness` and app-specific harness integrations.
+
+## Goals
+
+- `AgentHarness` emits hook events and consumes typed results.
+- Hook registration, provenance, cleanup, and mutation-chain semantics live in the hooks implementation.
+- There is one registration API and one emission API.
+- Observational and mutation hooks use the same registration API; the event result type determines whether a handler can return a result.
+- Apps can extend the event union, context type, source/provenance type, and reducers without changing `AgentHarness`.
+- Resources and tools carry provenance on their app-specific concrete value types. Hook handlers carry provenance as registration sidecar metadata.
+
+## Value provenance
+
+For non-hook values, provenance belongs on the app-specific concrete type.
+
+```ts
+interface AppSource {
+	path: string;
+	scope: "user" | "project" | "temporary";
+}
+
+type AppSkill = Skill & { source: AppSource };
+type AppPromptTemplate = PromptTemplate & { source: AppSource };
+type AppTool = AgentTool & { source: AppSource };
+```
+
+The harness already accepts generic resource/tool types, so no wrapper such as `{ value, source }` is needed.
+
+```ts
+const harness = new AgentHarness<AppSkill, AppPromptTemplate, AppTool>({
+	resources: { skills, promptTemplates },
+	tools,
+	// ...
+});
+```
+
+Loaders such as `loadSourcedSkills()` and `loadSourcedPromptTemplates()` can map source metadata onto the concrete app value type before passing values to the harness.
+
+## Hook event typing
+
+Each hook event owns its handler result type through a type-only phantom field.
+
+```ts
+declare const HookResult: unique symbol;
+
+export interface HookEvent<TType extends string, TResult = void> {
+	type: TType;
+	readonly [HookResult]?: TResult;
+}
+
+export type ResultOf<TEvent> = TEvent extends { readonly [HookResult]?: infer TResult } ? TResult : void;
+```
+
+Observational events omit the result type:
+
+```ts
+interface MessageStartEvent extends HookEvent<"message_start"> {
+	type: "message_start";
+	message: AgentMessage;
+}
+```
+
+Mutation/policy events declare their result type:
+
+```ts
+interface ContextEvent extends HookEvent<"context", { messages?: AgentMessage[] }> {
+	type: "context";
+	messages: AgentMessage[];
+}
+
+interface ToolCallEvent extends HookEvent<"tool_call", { block?: boolean; reason?: string }> {
+	type: "tool_call";
+	toolName: string;
+	input: Record<string, unknown>;
+}
+```
+
+There is no central result map and no event spec table. The event type itself defines the return type handlers may produce.
+
+## Hook handlers and registration options
+
+Handlers are plain functions. Provenance and cleanup live on the registration.
+
+```ts
+export type HookCleanup = () => void | Promise<void>;
+
+export type HookHandler<TEvent, TContext> = (
+	event: TEvent,
+	context: TContext,
+	signal?: AbortSignal,
+) => ResultOf<TEvent> | void | Promise<ResultOf<TEvent> | void>;
+
+export interface HookRegistrationOptions<TSource> {
+	source?: TSource;
+	cleanup?: HookCleanup;
+}
+```
+
+Example:
+
+```ts
+hooks.on(
+	"context",
+	(event, context) => ({ messages: injectContext(event.messages, context) }),
+	{
+		source: extensionSource,
+		cleanup: () => cache.dispose(),
+	},
+);
+```
+
+The cleanup runs once, either when the returned unregister function is called, or when `clear()` / `dispose()` clears the registration.
+
+## Reducers
+
+Result-producing events need reducers. Observational events do not.
+
+```ts
+type ResultfulEvent<TEvent> = TEvent extends HookEvent<string, infer TResult>
+	? [TResult] extends [void]
+		? never
+		: TEvent
+	: never;
+
+type HookRegistration<TContext, TSource> = {
+	handler: HookHandler<any, TContext>;
+	source?: TSource;
+	cleanup?: HookCleanup;
+	disposed: boolean;
+	order: number;
+};
+
+type Reducer<TEvent, TContext, TSource> = (
+	event: TEvent,
+	registrations: readonly HookRegistration<TContext, TSource>[],
+	context: TContext,
+	signal?: AbortSignal,
+) => Promise<ResultOf<TEvent> | undefined>;
+
+type Reducers<TEvent, TContext, TSource> = {
+	[TType in ResultfulEvent<TEvent>["type"]]: Reducer<
+		Extract<ResultfulEvent<TEvent>, { type: TType }>,
+		TContext,
+		TSource
+	>;
+};
+```
+
+Reducers encode hook semantics, for example:
+
+- `context`: sequential transform; each handler sees current messages.
+- `before_provider_request`: sequential patch/transform; each handler sees current request state.
+- `before_provider_payload`: sequential payload transform.
+- `before_agent_start`: chain `systemPrompt`; collect injected messages.
+- `tool_call`: same mutable event/input visible to later handlers; first `{ block: true }` stops.
+- `tool_result`: sequential patch accumulation; each handler sees current patched result.
+- `message_end`: sequential message replacement; replacement must keep the original role.
+- `session_before_*`: first `{ cancel: true }` stops; otherwise return the last meaningful result.
+
+Base harness reducers are defined once:
+
+```ts
+const agentHarnessReducers = {
+	context: reduceContext,
+	before_provider_request: reduceBeforeProviderRequest,
+	before_provider_payload: reduceBeforeProviderPayload,
+	before_agent_start: reduceBeforeAgentStart,
+	tool_call: reduceToolCall,
+	tool_result: reduceToolResult,
+	message_end: reduceMessageEnd,
+	session_before_compact: reduceFirstCancelOrLast,
+	session_before_tree: reduceFirstCancelOrLast,
+} satisfies Reducers<AgentHarnessEvent, AgentHarnessContext, unknown>;
+```
+
+If `AgentHarnessEvent` gains a new result-producing event, TypeScript forces the reducer table to be updated.
+
+## Single hooks implementation
+
+The hooks implementation stores registrations and runs reducers.
+
+```ts
+class AgentHarnessHooks<
+	TEvent extends HookEvent<string, unknown>,
+	TContext,
+	TSource = unknown,
+> {
+	context: TContext;
+
+	constructor(
+		context: TContext,
+		extraReducers?: ExtraReducers<TEvent, AgentHarnessEvent, TContext, TSource>,
+	) {
+		this.context = context;
+		this.reducers = {
+			...agentHarnessReducers,
+			...extraReducers,
+		} as Reducers<TEvent, TContext, TSource>;
+	}
+
+	setContext(context: TContext): void {
+		this.context = context;
+	}
+
+	on<TType extends TEvent["type"]>(
+		type: TType,
+		handler: HookHandler<Extract<TEvent, { type: TType }>, TContext>,
+		options?: HookRegistrationOptions<TSource>,
+	): () => Promise<void> {
+		// Store the registration and return unregister.
+	}
+
+	async emit<TEmittedEvent extends TEvent>(
+		event: TEmittedEvent,
+		signal?: AbortSignal,
+	): Promise<ResultOf<TEmittedEvent> | undefined> {
+		const registrations = this.getRegistrations(event.type);
+		const reducer = this.reducers[event.type as keyof typeof this.reducers];
+
+		if (reducer) {
+			return reducer(event as never, registrations as never, this.context, signal) as Promise<
+				ResultOf<TEmittedEvent> | undefined
+			>;
+		}
+
+		for (const registration of registrations) {
+			await registration.handler(event, this.context, signal);
+		}
+
+		return undefined;
+	}
+
+	async clear(): Promise<void> {
+		// Remove all registrations and run remaining cleanups once in reverse registration order.
+	}
+
+	dispose(): Promise<void> {
+		return this.clear();
+	}
+}
+```
+
+Public API:
+
+```ts
+hooks.on(...);
+hooks.emit(...);
+hooks.clear();
+hooks.dispose();
+```
+
+There is no wildcard subscription and no separate observer API.
+
+## App-specific events and reducers
+
+Apps extend the event union.
+
+Observational app events need no reducer:
+
+```ts
+interface SessionStartEvent extends HookEvent<"session_start"> {
+	type: "session_start";
+	reason: "startup" | "reload" | "new" | "resume" | "fork";
+}
+```
+
+Result-producing app events need an extra reducer:
+
+```ts
+type InputResult =
+	| { action: "continue" }
+	| { action: "transform"; text: string; images?: ImageContent[] }
+	| { action: "handled" };
+
+interface InputEvent extends HookEvent<"input", InputResult> {
+	type: "input";
+	text: string;
+	images?: ImageContent[];
+	source: "interactive" | "rpc" | "extension";
+}
+```
+
+```ts
+const codingAgentExtraReducers = {
+	input: reduceInput,
+	user_bash: reduceFirstResult,
+	resources_discover: reduceResourcesDiscover,
+	session_before_switch: reduceFirstCancelOrLast,
+	session_before_fork: reduceFirstCancelOrLast,
+} satisfies ExtraReducers<CodingAgentEvent, AgentHarnessEvent, CodingAgentContext, AppSource>;
+```
+
+Base reducers are included by the hooks constructor. Apps only provide reducers for app-specific result-producing events.
+
+```ts
+type CodingAgentEvent =
+	| AgentHarnessEvent<AppSkill, AppPromptTemplate, AppTool>
+	| SessionStartEvent
+	| SessionShutdownEvent
+	| InputEvent
+	| UserBashEvent
+	| ResourcesDiscoverEvent;
+
+const hooks = new AgentHarnessHooks<CodingAgentEvent, CodingAgentContext, AppSource>(
+	context,
+	codingAgentExtraReducers,
+);
+```
+
+## Harness typing
+
+`AgentHarness` stores and exposes the concrete hooks object.
+
+```ts
+type DefaultHooks<TSkill, TPromptTemplate, TTool> = AgentHarnessHooks<
+	AgentHarnessEvent<TSkill, TPromptTemplate, TTool>,
+	undefined,
+	unknown
+>;
+
+class AgentHarness<
+	TSkill extends Skill = Skill,
+	TPromptTemplate extends PromptTemplate = PromptTemplate,
+	TTool extends AgentTool = AgentTool,
+	THooks = DefaultHooks<TSkill, TPromptTemplate, TTool>,
+> {
+	readonly hooks: THooks;
+
+	constructor(options: AgentHarnessOptions<TSkill, TPromptTemplate, TTool, THooks>) {
+		this.hooks = options.hooks ?? createDefaultHooks();
+	}
+}
+```
+
+When custom hooks are passed, TypeScript infers `THooks` from `options.hooks`.
+
+```ts
+const hooks = new CodingAgentHooks(context, codingAgentExtraReducers);
+
+const harness = new AgentHarness({
+	model,
+	session,
+	hooks,
+	resources,
+	tools,
+});
+
+harness.hooks; // CodingAgentHooks
+```
+
+Custom app APIs live on `harness.hooks`; they are not proxied onto `AgentHarness`.
+
+## Harness usage
+
+The harness only emits events and uses typed results.
+
+```ts
+await this.hooks.emit({ type: "message_start", message }, signal);
+```
+
+```ts
+const result = await this.hooks.emit({ type: "context", messages }, signal);
+messages = result?.messages ?? messages;
+```
+
+```ts
+const result = await this.hooks.emit({ type: "tool_call", toolName, input }, signal);
+if (result?.block) return blockedToolResult(result.reason);
+```
+
+`AgentHarness` does not store handlers and does not implement hook chaining semantics.
+
+## Context model
+
+Context is a plain object owned by the hooks implementation.
+
+```ts
+hooks.setContext(nextContext);
+```
+
+Per-run `AbortSignal` is passed separately to `emit()` and handlers.
+
+Dynamic app state should be exposed through small facades instead of late-bound getter mazes.
+
+Example app context:
+
+```ts
+interface CodingAgentContext {
+	harness: HarnessFacade;
+	session: SessionFacade;
+	ui: UiFacade;
+	models: ModelFacade;
+}
+```
+
+The hook context should not expose `waitForIdle()` to hook handlers. A future facade can expose `runWhenIdle(() => Promise<void>)` for safe deferred work.
+
+## Cleanup semantics
+
+Each registration owns at most one cleanup.
+
+- Manual unregister removes the registration and runs its cleanup once.
+- `clear()` removes all remaining registrations and runs their cleanups once.
+- `dispose()` calls `clear()`.
+- Cleanup order is reverse registration order.
+- Cleanup errors are collected; cleanup continues; `clear()` throws an aggregate error if any cleanup failed.
+
+## Error policy
+
+The base hooks implementation can throw handler errors by default.
+
+App-specific hooks that load untrusted/user extensions should use a continue-and-report policy. Reducers receive registration source metadata so they can report errors with provenance:
+
+```ts
+for (const registration of registrations) {
+	try {
+		const result = await registration.handler(event, context, signal);
+		// apply result
+	} catch (error) {
+		reportHookError({
+			event: event.type,
+			source: registration.source,
+			error,
+		});
+	}
+}
+```
+
+## Extension loading sketch
+
+An app-level extension host owns extension loading and non-hook registries. The harness only receives hooks.
+
+```ts
+class ExtensionHost {
+	constructor(private readonly hooks: AgentHarnessHooks<CodingAgentEvent, CodingAgentContext, AppSource>) {}
+
+	async load(paths: string[]): Promise<void> {
+		for (const path of paths) {
+			const extension = await loadExtension(path);
+			const source = createExtensionSource(path);
+
+			const api = {
+				on: (type, handler, cleanup) => {
+					this.hooks.on(type, handler, { source, cleanup });
+				},
+				registerTool: (tool) => {
+					this.tools.set(tool.name, { ...tool, source });
+				},
+			};
+
+			await extension(api);
+		}
+	}
+
+	async clear(): Promise<void> {
+		this.tools.clear();
+		this.commands.clear();
+		await this.hooks.clear();
+	}
+}
+```
+
+Non-hook registries, such as tools, commands, flags, shortcuts, message renderers, providers, and OAuth providers, remain app-level concerns.