@code-yeongyu/senpi-agent-core 2026.9.12 → 2026.9.13

package/dist/harness/execution/tools.d.ts

@@ -0,0 +1,67 @@
+import { type ToolResultMessage } from "@earendil-works/pi-ai";
+import type { AgentToolCall, AgentToolResult } from "../../types.ts";
+import { type Context } from "../context.ts";
+import type { JsonValue } from "../session/types.ts";
+import type { AgentHarnessTool, AgentHarnessToolInvocation, AgentHarnessToolUpdateCallback } from "../types.ts";
+import type { Gate } from "./effect-gate.ts";
+/** A tool call whose tool exists and whose prepared arguments passed validation. */
+export interface PreparedToolCall<TContext extends object | undefined> {
+    toolCall: AgentToolCall;
+    tool: AgentHarnessTool<TContext>;
+    args: Record<string, JsonValue>;
+}
+/** Synthetic result produced without crossing the external tool-effect boundary. */
+export interface ImmediateToolOutcome {
+    kind: "immediate";
+    toolCall: AgentToolCall;
+    result: AgentToolResult<unknown>;
+    isError: true;
+    terminate: boolean;
+}
+/** Aggregated decision from the before-tool hook pipeline. */
+export interface BeforeToolDecision {
+    args?: Record<string, JsonValue>;
+    block?: {
+        reason: string;
+        terminate?: boolean;
+    };
+}
+/** A prepared call cleared for durable intent publication and execution. */
+export interface ClearedToolCall<TContext extends object | undefined> {
+    toolCall: AgentToolCall;
+    tool: AgentHarnessTool<TContext>;
+    args: Record<string, JsonValue>;
+}
+/** Raw phase-two tool output before after-tool patching. */
+export interface ExecutedToolCall {
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+}
+/** Aggregated patch from the after-tool hook pipeline. */
+export interface AfterToolPatch {
+    content?: AgentToolResult<unknown>["content"];
+    details?: JsonValue;
+    isError?: boolean;
+    usage?: AgentToolResult<unknown>["usage"];
+    terminate?: boolean;
+}
+/** Final tool output ready to become a durable tool-result message. */
+export interface FinalizedToolCall {
+    toolCall: AgentToolCall;
+    result: AgentToolResult<unknown>;
+    isError: boolean;
+    terminate: boolean;
+}
+/** Resolve a tool, apply its deterministic argument preparation, and validate the result. */
+export declare function prepareToolCall<TContext extends object | undefined>(call: AgentToolCall, tools: AgentHarnessTool<TContext>[]): PreparedToolCall<TContext> | ImmediateToolOutcome;
+/** Apply an explicit hook decision and revalidate replacement arguments. */
+export declare function applyBeforeToolDecision<TContext extends object | undefined>(prepared: PreparedToolCall<TContext>, decision: BeforeToolDecision | undefined): ClearedToolCall<TContext> | ImmediateToolOutcome;
+/** Execute one cleared external tool effect, converting expected tool throws to error output. */
+export declare function executeToolCall<TContext extends object | undefined>(call: ClearedToolCall<TContext>, gate: Gate, onUpdate: AgentHarnessToolUpdateCallback<unknown>, toolContext: TContext, invocation: AgentHarnessToolInvocation, context: Context): Promise<ExecutedToolCall>;
+/** Apply an after-tool patch field by field. */
+export declare function finalizeToolCall<TContext extends object | undefined>(call: ClearedToolCall<TContext>, executed: ExecutedToolCall, patch: AfterToolPatch | undefined): FinalizedToolCall;
+/** Reconstruct the canonical tool result represented by a staged transcript message. */
+export declare function toolResultFromMessage(message: ToolResultMessage<unknown>, terminate: boolean): AgentToolResult<unknown>;
+/** Convert finalized tool output to the provider-facing transcript message. */
+export declare function createToolResultMessage(call: FinalizedToolCall): ToolResultMessage;
+//# sourceMappingURL=tools.d.ts.map

package/dist/harness/execution/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/harness/execution/tools.ts"],"names":[],"mappings":"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"}

package/dist/harness/execution/tools.js

@@ -0,0 +1,121 @@
+import { validateToolArguments } from "@earendil-works/pi-ai";
+import { withAbortSignal } from "../context.js";
+function createErrorToolResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        details: undefined,
+    };
+}
+function immediateError(toolCall, message, terminate = false) {
+    return {
+        kind: "immediate",
+        toolCall,
+        result: createErrorToolResult(message),
+        isError: true,
+        terminate,
+    };
+}
+/** Resolve a tool, apply its deterministic argument preparation, and validate the result. */
+export function prepareToolCall(call, tools) {
+    const tool = tools.find((candidate) => candidate.name === call.name);
+    if (!tool) {
+        return immediateError(call, `Tool ${JSON.stringify(call.name)} is unavailable`);
+    }
+    try {
+        const preparedArguments = tool.prepareArguments ? tool.prepareArguments(call.arguments) : call.arguments;
+        const preparedCall = preparedArguments === call.arguments
+            ? call
+            : { ...call, arguments: preparedArguments };
+        const args = validateToolArguments(tool, preparedCall);
+        return { toolCall: call, tool, args };
+    }
+    catch (error) {
+        return immediateError(call, error instanceof Error ? error.message : String(error));
+    }
+}
+/** Apply an explicit hook decision and revalidate replacement arguments. */
+export function applyBeforeToolDecision(prepared, decision) {
+    if (decision?.block) {
+        return immediateError(prepared.toolCall, decision.block.reason, decision.block.terminate === true);
+    }
+    if (!decision?.args) {
+        return { toolCall: prepared.toolCall, tool: prepared.tool, args: prepared.args };
+    }
+    try {
+        const validatedArgs = validateToolArguments(prepared.tool, {
+            ...prepared.toolCall,
+            arguments: decision.args,
+        });
+        return { toolCall: prepared.toolCall, tool: prepared.tool, args: validatedArgs };
+    }
+    catch (error) {
+        return immediateError(prepared.toolCall, error instanceof Error ? error.message : String(error));
+    }
+}
+/** Execute one cleared external tool effect, converting expected tool throws to error output. */
+export function executeToolCall(call, gate, onUpdate, toolContext, invocation, context) {
+    let acceptingUpdates = true;
+    return gate.admit(async () => {
+        const admittedContext = withAbortSignal(gate.signal, context);
+        admittedContext.abortSignal?.throwIfAborted();
+        try {
+            const result = await call.tool.execute(call.toolCall.id, call.args, (partial, options) => {
+                if (acceptingUpdates)
+                    onUpdate(partial, options);
+            }, toolContext, invocation, admittedContext);
+            return { result, isError: false };
+        }
+        catch (error) {
+            return {
+                result: createErrorToolResult(error instanceof Error ? error.message : String(error)),
+                isError: true,
+            };
+        }
+        finally {
+            acceptingUpdates = false;
+        }
+    });
+}
+/** Apply an after-tool patch field by field. */
+export function finalizeToolCall(call, executed, patch) {
+    const result = patch
+        ? {
+            ...executed.result,
+            content: patch.content === undefined ? executed.result.content : patch.content,
+            details: patch.details === undefined ? executed.result.details : patch.details,
+            usage: patch.usage === undefined ? executed.result.usage : patch.usage,
+            terminate: patch.terminate === undefined ? executed.result.terminate : patch.terminate,
+        }
+        : executed.result;
+    return {
+        toolCall: call.toolCall,
+        result,
+        isError: patch?.isError ?? executed.isError,
+        terminate: result.terminate === true,
+    };
+}
+/** Reconstruct the canonical tool result represented by a staged transcript message. */
+export function toolResultFromMessage(message, terminate) {
+    return {
+        content: message.content,
+        details: message.details,
+        ...(message.usage === undefined ? {} : { usage: message.usage }),
+        ...(message.addedToolNames === undefined ? {} : { addedToolNames: message.addedToolNames }),
+        ...(terminate ? { terminate: true } : {}),
+    };
+}
+/** Convert finalized tool output to the provider-facing transcript message. */
+export function createToolResultMessage(call) {
+    return {
+        role: "toolResult",
+        toolCallId: call.toolCall.id,
+        toolName: call.toolCall.name,
+        content: call.result.content ?? [],
+        ...(call.result.details === undefined ? {} : { details: call.result.details }),
+        ...(call.result.usage === undefined ? {} : { usage: call.result.usage }),
+        ...(call.result.addedToolNames?.length ? { addedToolNames: call.result.addedToolNames } : {}),
+        isError: call.isError,
+        timestamp: Date.now(),
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/harness/execution/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/harness/execution/tools.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ToolResultMessage, validateToolArguments } from \"@earendil-works/pi-ai\";\nimport type { AgentToolCall, AgentToolResult } from \"../../types.ts\";\nimport { type Context, withAbortSignal } from \"../context.ts\";\nimport type { JsonValue } from \"../session/types.ts\";\nimport type { AgentHarnessTool, AgentHarnessToolInvocation, AgentHarnessToolUpdateCallback } from \"../types.ts\";\nimport type { Gate } from \"./effect-gate.ts\";\n\n/** A tool call whose tool exists and whose prepared arguments passed validation. */\nexport interface PreparedToolCall<TContext extends object | undefined> {\n\ttoolCall: AgentToolCall;\n\ttool: AgentHarnessTool<TContext>;\n\targs: Record<string, JsonValue>;\n}\n\n/** Synthetic result produced without crossing the external tool-effect boundary. */\nexport interface ImmediateToolOutcome {\n\tkind: \"immediate\";\n\ttoolCall: AgentToolCall;\n\tresult: AgentToolResult<unknown>;\n\tisError: true;\n\tterminate: boolean;\n}\n\n/** Aggregated decision from the before-tool hook pipeline. */\nexport interface BeforeToolDecision {\n\targs?: Record<string, JsonValue>;\n\tblock?: { reason: string; terminate?: boolean };\n}\n\n/** A prepared call cleared for durable intent publication and execution. */\nexport interface ClearedToolCall<TContext extends object | undefined> {\n\ttoolCall: AgentToolCall;\n\ttool: AgentHarnessTool<TContext>;\n\targs: Record<string, JsonValue>;\n}\n\n/** Raw phase-two tool output before after-tool patching. */\nexport interface ExecutedToolCall {\n\tresult: AgentToolResult<unknown>;\n\tisError: boolean;\n}\n\n/** Aggregated patch from the after-tool hook pipeline. */\nexport interface AfterToolPatch {\n\tcontent?: AgentToolResult<unknown>[\"content\"];\n\tdetails?: JsonValue;\n\tisError?: boolean;\n\tusage?: AgentToolResult<unknown>[\"usage\"];\n\tterminate?: boolean;\n}\n\n/** Final tool output ready to become a durable tool-result message. */\nexport interface FinalizedToolCall {\n\ttoolCall: AgentToolCall;\n\tresult: AgentToolResult<unknown>;\n\tisError: boolean;\n\tterminate: boolean;\n}\n\nfunction createErrorToolResult(message: string): AgentToolResult<unknown> {\n\treturn {\n\t\tcontent: [{ type: \"text\", text: message }],\n\t\tdetails: undefined,\n\t};\n}\n\nfunction immediateError(toolCall: AgentToolCall, message: string, terminate = false): ImmediateToolOutcome {\n\treturn {\n\t\tkind: \"immediate\",\n\t\ttoolCall,\n\t\tresult: createErrorToolResult(message),\n\t\tisError: true,\n\t\tterminate,\n\t};\n}\n\n/** Resolve a tool, apply its deterministic argument preparation, and validate the result. */\nexport function prepareToolCall<TContext extends object | undefined>(\n\tcall: AgentToolCall,\n\ttools: AgentHarnessTool<TContext>[],\n): PreparedToolCall<TContext> | ImmediateToolOutcome {\n\tconst tool = tools.find((candidate) => candidate.name === call.name);\n\tif (!tool) {\n\t\treturn immediateError(call, `Tool ${JSON.stringify(call.name)} is unavailable`);\n\t}\n\n\ttry {\n\t\tconst preparedArguments = tool.prepareArguments ? tool.prepareArguments(call.arguments) : call.arguments;\n\t\tconst preparedCall: AgentToolCall =\n\t\t\tpreparedArguments === call.arguments\n\t\t\t\t? call\n\t\t\t\t: { ...call, arguments: preparedArguments as Record<string, JsonValue> };\n\t\tconst args = validateToolArguments(tool, preparedCall) as Record<string, JsonValue>;\n\t\treturn { toolCall: call, tool, args };\n\t} catch (error) {\n\t\treturn immediateError(call, error instanceof Error ? error.message : String(error));\n\t}\n}\n\n/** Apply an explicit hook decision and revalidate replacement arguments. */\nexport function applyBeforeToolDecision<TContext extends object | undefined>(\n\tprepared: PreparedToolCall<TContext>,\n\tdecision: BeforeToolDecision | undefined,\n): ClearedToolCall<TContext> | ImmediateToolOutcome {\n\tif (decision?.block) {\n\t\treturn immediateError(prepared.toolCall, decision.block.reason, decision.block.terminate === true);\n\t}\n\n\tif (!decision?.args) {\n\t\treturn { toolCall: prepared.toolCall, tool: prepared.tool, args: prepared.args };\n\t}\n\n\ttry {\n\t\tconst validatedArgs = validateToolArguments(prepared.tool, {\n\t\t\t...prepared.toolCall,\n\t\t\targuments: decision.args,\n\t\t}) as Record<string, JsonValue>;\n\t\treturn { toolCall: prepared.toolCall, tool: prepared.tool, args: validatedArgs };\n\t} catch (error) {\n\t\treturn immediateError(prepared.toolCall, error instanceof Error ? error.message : String(error));\n\t}\n}\n\n/** Execute one cleared external tool effect, converting expected tool throws to error output. */\nexport function executeToolCall<TContext extends object | undefined>(\n\tcall: ClearedToolCall<TContext>,\n\tgate: Gate,\n\tonUpdate: AgentHarnessToolUpdateCallback<unknown>,\n\ttoolContext: TContext,\n\tinvocation: AgentHarnessToolInvocation,\n\tcontext: Context,\n): Promise<ExecutedToolCall> {\n\tlet acceptingUpdates = true;\n\treturn gate.admit(async () => {\n\t\tconst admittedContext = withAbortSignal(gate.signal, context);\n\t\tadmittedContext.abortSignal?.throwIfAborted();\n\t\ttry {\n\t\t\tconst result = await call.tool.execute(\n\t\t\t\tcall.toolCall.id,\n\t\t\t\tcall.args,\n\t\t\t\t(partial, options) => {\n\t\t\t\t\tif (acceptingUpdates) onUpdate(partial, options);\n\t\t\t\t},\n\t\t\t\ttoolContext,\n\t\t\t\tinvocation,\n\t\t\t\tadmittedContext,\n\t\t\t);\n\t\t\treturn { result, isError: false };\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tresult: createErrorToolResult(error instanceof Error ? error.message : String(error)),\n\t\t\t\tisError: true,\n\t\t\t};\n\t\t} finally {\n\t\t\tacceptingUpdates = false;\n\t\t}\n\t});\n}\n\n/** Apply an after-tool patch field by field. */\nexport function finalizeToolCall<TContext extends object | undefined>(\n\tcall: ClearedToolCall<TContext>,\n\texecuted: ExecutedToolCall,\n\tpatch: AfterToolPatch | undefined,\n): FinalizedToolCall {\n\tconst result: AgentToolResult<unknown> = patch\n\t\t? {\n\t\t\t\t...executed.result,\n\t\t\t\tcontent: patch.content === undefined ? executed.result.content : patch.content,\n\t\t\t\tdetails: patch.details === undefined ? executed.result.details : patch.details,\n\t\t\t\tusage: patch.usage === undefined ? executed.result.usage : patch.usage,\n\t\t\t\tterminate: patch.terminate === undefined ? executed.result.terminate : patch.terminate,\n\t\t\t}\n\t\t: executed.result;\n\treturn {\n\t\ttoolCall: call.toolCall,\n\t\tresult,\n\t\tisError: patch?.isError ?? executed.isError,\n\t\tterminate: result.terminate === true,\n\t};\n}\n\n/** Reconstruct the canonical tool result represented by a staged transcript message. */\nexport function toolResultFromMessage(\n\tmessage: ToolResultMessage<unknown>,\n\tterminate: boolean,\n): AgentToolResult<unknown> {\n\treturn {\n\t\tcontent: message.content,\n\t\tdetails: message.details,\n\t\t...(message.usage === undefined ? {} : { usage: message.usage }),\n\t\t...(message.addedToolNames === undefined ? {} : { addedToolNames: message.addedToolNames }),\n\t\t...(terminate ? { terminate: true } : {}),\n\t};\n}\n\n/** Convert finalized tool output to the provider-facing transcript message. */\nexport function createToolResultMessage(call: FinalizedToolCall): ToolResultMessage {\n\treturn {\n\t\trole: \"toolResult\",\n\t\ttoolCallId: call.toolCall.id,\n\t\ttoolName: call.toolCall.name,\n\t\tcontent: call.result.content ?? [],\n\t\t...(call.result.details === undefined ? {} : { details: call.result.details }),\n\t\t...(call.result.usage === undefined ? {} : { usage: call.result.usage }),\n\t\t...(call.result.addedToolNames?.length ? { addedToolNames: call.result.addedToolNames } : {}),\n\t\tisError: call.isError,\n\t\ttimestamp: Date.now(),\n\t};\n}\n"]}

package/dist/harness/hooks.d.ts

@@ -0,0 +1,38 @@
+import type { HookHandler, HookInvocation, HookMap, HookName, Hooks } from "./agent-harness.ts";
+import { type Context } from "./context.ts";
+import type { Gate } from "./execution/effect-gate.ts";
+import type { AgentHarnessStreamOptions, AgentHarnessStreamOptionsPatch } from "./types.ts";
+type HookErrorReporter = (error: Error, hook: HookName, lane: string, context: Context) => void | Promise<void>;
+/** Ordered harness hook registry and aggregate runner. */
+export declare class HookRegistry implements Hooks {
+    private readonly registrations;
+    private readonly reportError;
+    private closedError;
+    constructor(reportError: HookErrorReporter);
+    on<TName extends HookName>(name: TName, handler: HookHandler<TName>, options?: {
+        id?: string;
+    }): () => void;
+    has(name: HookName): boolean;
+    /** Invoke one accepted-operation aggregate after synchronously passing its effect gate. */
+    runWithGate<TName extends HookName>(name: TName, event: HookInvocation<TName>, gate: Gate, context: Context): Promise<HookMap[TName]["result"]>;
+    /** Invoke a tool-hook aggregate with one telemetry span per registered handler. */
+    runToolWithGate<TName extends "before_tool" | "after_tool">(name: TName, event: HookInvocation<TName>, gate: Gate, context: Context): Promise<HookMap[TName]["result"]>;
+    close(error: Error): void;
+    private runAdmitted;
+    private aggregate;
+    private beforeRun;
+    private beforeTool;
+    private transformContext;
+    private beforeRequest;
+    private beforePayload;
+    private afterResponse;
+    private afterTool;
+    private firstStructural;
+    private invokeToolRegistration;
+    private registrationsFor;
+    private invokeAllFailClosed;
+    private invokeAll;
+}
+export declare function applyStreamOptionsPatch(base: AgentHarnessStreamOptions, patch: AgentHarnessStreamOptionsPatch): AgentHarnessStreamOptions;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/harness/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/harness/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChG,OAAO,EAAE,KAAK,OAAO,EAAmB,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AAEvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AAO5F,KAAK,iBAAiB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhH,0DAA0D;AAC1D,qBAAa,YAAa,YAAW,KAAK;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2C;IACzE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,WAAW,CAAoB;IAEvC,YAAY,WAAW,EAAE,iBAAiB,EAEzC;IAED,EAAE,CAAC,KAAK,SAAS,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,OAAO,GAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,IAAI,CAa9G;IAED,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE3B;IAED,2FAA2F;IAC3F,WAAW,CAAC,KAAK,SAAS,QAAQ,EACjC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,EAC5B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAMnC;IAED,mFAAmF;IACnF,eAAe,CAAC,KAAK,SAAS,aAAa,GAAG,YAAY,EACzD,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,EAC5B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,CAUnC;IAED,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAExB;YAEa,WAAW;YAUX,SAAS;YAuCT,SAAS;YA4BT,UAAU;YAgCV,gBAAgB;YA8BhB,aAAa;YA4Bb,aAAa;YAwBb,aAAa;YAwBb,SAAS;YA2CT,eAAe;IAiC7B,OAAO,CAAC,sBAAsB;IAmC9B,OAAO,CAAC,gBAAgB;YAIV,mBAAmB;YAgBnB,SAAS;CAmBvB;AAED,wBAAgB,uBAAuB,CACtC,IAAI,EAAE,yBAAyB,EAC/B,KAAK,EAAE,8BAA8B,GACnC,yBAAyB,CAsC3B"}

package/dist/harness/hooks.js

@@ -0,0 +1,404 @@
+import { withAbortSignal } from "./context.js";
+import { startHarnessSpan } from "./telemetry.js";
+/** Ordered harness hook registry and aggregate runner. */
+export class HookRegistry {
+    constructor(reportError) {
+        this.registrations = new Map();
+        this.reportError = reportError;
+    }
+    on(name, handler, options = {}) {
+        if (this.closedError !== undefined)
+            throw this.closedError;
+        const registrations = this.registrations.get(name) ?? [];
+        const registration = {
+            ...(options.id === undefined ? {} : { id: options.id }),
+            handler: (event, context) => handler(event, context),
+        };
+        registrations.push(registration);
+        this.registrations.set(name, registrations);
+        return () => {
+            const index = registrations.indexOf(registration);
+            if (index !== -1)
+                registrations.splice(index, 1);
+        };
+    }
+    has(name) {
+        return (this.registrations.get(name)?.length ?? 0) !== 0;
+    }
+    /** Invoke one accepted-operation aggregate after synchronously passing its effect gate. */
+    runWithGate(name, event, gate, context) {
+        return gate.admit(() => {
+            const admittedContext = withAbortSignal(gate.signal, context);
+            admittedContext.abortSignal?.throwIfAborted();
+            return this.runAdmitted(name, event, admittedContext);
+        });
+    }
+    /** Invoke a tool-hook aggregate with one telemetry span per registered handler. */
+    runToolWithGate(name, event, gate, context) {
+        return gate.admit(() => {
+            const admittedContext = withAbortSignal(gate.signal, context);
+            admittedContext.abortSignal?.throwIfAborted();
+            return (name === "before_tool"
+                ? this.beforeTool(event, admittedContext)
+                : this.afterTool(event, admittedContext));
+        });
+    }
+    close(error) {
+        this.closedError ??= error;
+    }
+    async runAdmitted(name, event, context) {
+        if (this.closedError !== undefined)
+            throw this.closedError;
+        const result = await this.aggregate(name, event, context);
+        return result;
+    }
+    async aggregate(name, event, context) {
+        switch (name) {
+            case "before_run":
+                return this.beforeRun(event, context);
+            case "before_drive":
+                await this.invokeAllFailClosed(name, event, context);
+                return undefined;
+            case "before_run_end": {
+                let followUp;
+                await this.invokeAll(name, event, (value) => {
+                    const result = value;
+                    if (result?.followUp !== undefined)
+                        followUp = result.followUp;
+                }, context);
+                return followUp === undefined ? undefined : { followUp };
+            }
+            case "transform_context":
+                return this.transformContext(event, context);
+            case "before_request":
+                return this.beforeRequest(event, context);
+            case "before_payload":
+                return this.beforePayload(event, context);
+            case "after_response":
+                return this.afterResponse(event, context);
+            case "before_tool":
+                return this.beforeTool(event, context);
+            case "after_tool":
+                return this.afterTool(event, context);
+            case "before_compaction":
+                return this.firstStructural(name, event, "compaction", context);
+            case "before_navigation":
+                return this.firstStructural(name, event, "summary", context);
+        }
+    }
+    async beforeRun(event, context) {
+        let prompt = event.prompt;
+        let injected = [];
+        for (const registration of this.registrationsFor("before_run")) {
+            try {
+                const result = (await registration.handler({ ...event, prompt }, context));
+                if (result?.messages !== undefined) {
+                    injected = [...injected, ...result.messages];
+                    prompt = [...prompt, ...result.messages];
+                }
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), "before_run", event.lane, context);
+            }
+        }
+        return injected.length === 0 ? undefined : { messages: injected };
+    }
+    async beforeTool(event, context) {
+        let args = event.args;
+        let block;
+        for (const registration of this.registrationsFor("before_tool")) {
+            try {
+                const result = (await this.invokeToolRegistration("before_tool", registration, { ...event, args }, context));
+                if (result?.args !== undefined)
+                    args = result.args;
+                if (result?.block !== undefined) {
+                    block = result.block;
+                    break;
+                }
+            }
+            catch (error) {
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                await this.reportError(normalized, "before_tool", event.lane, context);
+                block = { reason: normalized.message };
+                break;
+            }
+        }
+        return {
+            ...(args === event.args ? {} : { args }),
+            ...(block === undefined ? {} : { block }),
+        };
+    }
+    async transformContext(event, context) {
+        let messages = event.messages;
+        let systemPrompt = event.systemPrompt;
+        for (const registration of this.registrationsFor("transform_context")) {
+            try {
+                const result = (await registration.handler({
+                    ...event,
+                    messages,
+                    systemPrompt,
+                }, context));
+                if (result?.messages !== undefined)
+                    messages = result.messages;
+                if (result?.systemPrompt !== undefined)
+                    systemPrompt = result.systemPrompt;
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), "transform_context", event.lane, context);
+            }
+        }
+        return { messages, systemPrompt };
+    }
+    async beforeRequest(event, context) {
+        let streamOptions = event.streamOptions;
+        let changed = false;
+        for (const registration of this.registrationsFor("before_request")) {
+            try {
+                const result = (await registration.handler({ ...event, streamOptions }, context));
+                if (result?.streamOptions !== undefined) {
+                    streamOptions = applyStreamOptionsPatch(streamOptions, result.streamOptions);
+                    changed = true;
+                }
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), "before_request", event.lane, context);
+            }
+        }
+        return changed ? { streamOptions: createStreamOptionsPatch(event.streamOptions, streamOptions) } : undefined;
+    }
+    async beforePayload(event, context) {
+        let payload = event.payload;
+        for (const registration of this.registrationsFor("before_payload")) {
+            try {
+                const result = (await registration.handler({ ...event, payload }, context));
+                if (result?.payload !== undefined)
+                    payload = result.payload;
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), "before_payload", event.lane, context);
+            }
+        }
+        return { payload };
+    }
+    async afterResponse(event, context) {
+        let message = event.message;
+        for (const registration of this.registrationsFor("after_response")) {
+            try {
+                const result = (await registration.handler({ ...event, message }, context));
+                if (result?.message !== undefined)
+                    message = result.message;
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), "after_response", event.lane, context);
+            }
+        }
+        return { message };
+    }
+    async afterTool(event, context) {
+        let current = {
+            content: event.content,
+            details: event.details,
+            isError: event.isError,
+            usage: event.usage,
+        };
+        const aggregate = {};
+        for (const registration of this.registrationsFor("after_tool")) {
+            try {
+                const result = (await this.invokeToolRegistration("after_tool", registration, { ...event, ...current }, context));
+                if (result === undefined)
+                    continue;
+                if (result.content !== undefined)
+                    aggregate.content = result.content;
+                if (result.details !== undefined)
+                    aggregate.details = result.details;
+                if (result.isError !== undefined)
+                    aggregate.isError = result.isError;
+                if (result.usage !== undefined)
+                    aggregate.usage = result.usage;
+                if (result.terminate !== undefined)
+                    aggregate.terminate = result.terminate;
+                current = {
+                    content: result.content === undefined ? current.content : result.content,
+                    details: result.details === undefined ? current.details : result.details,
+                    isError: result.isError === undefined ? current.isError : result.isError,
+                    usage: result.usage === undefined ? current.usage : result.usage,
+                };
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), "after_tool", event.lane, context);
+            }
+        }
+        return Object.keys(aggregate).length === 0 ? undefined : aggregate;
+    }
+    async firstStructural(name, event, resultField, context) {
+        for (const registration of this.registrationsFor(name)) {
+            try {
+                const value = await registration.handler(event, context);
+                if (value === undefined || value === null || typeof value !== "object")
+                    continue;
+                const result = value;
+                if (result.decline === true && result[resultField] !== undefined) {
+                    await this.reportError(new Error(`${name} hook cannot return both decline and ${resultField}`), name, event.lane, context);
+                    continue;
+                }
+                if (result.decline === true || result[resultField] !== undefined)
+                    return value;
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), name, event.lane, context);
+            }
+        }
+        return undefined;
+    }
+    invokeToolRegistration(name, registration, event, context) {
+        return startHarnessSpan("pi.harness.hook", {
+            "pi.lane.name": event.lane,
+            "pi.operation.id": event.runId,
+            "pi.hook.name": name,
+            ...(registration.id === undefined ? {} : { "pi.hook.registration_id": registration.id }),
+        }, async (span, spanContext) => {
+            try {
+                const result = await registration.handler(event, spanContext);
+                const blocked = name === "before_tool" &&
+                    result !== null &&
+                    typeof result === "object" &&
+                    "block" in result &&
+                    result.block !== undefined;
+                span.setAttributes({ "pi.hook.outcome": blocked ? "blocked" : "completed" });
+                return result;
+            }
+            catch (error) {
+                span.setAttributes({ "pi.hook.outcome": "failed" });
+                span.setStatus({ status: "error" });
+                throw error;
+            }
+        }, context);
+    }
+    registrationsFor(name) {
+        return [...(this.registrations.get(name) ?? [])];
+    }
+    async invokeAllFailClosed(name, event, context) {
+        for (const registration of this.registrationsFor(name)) {
+            try {
+                await registration.handler(event, context);
+            }
+            catch (error) {
+                const normalized = error instanceof Error ? error : new Error(String(error));
+                await this.reportError(normalized, name, event.lane, context);
+                throw normalized;
+            }
+        }
+    }
+    async invokeAll(name, event, apply, context) {
+        for (const registration of this.registrationsFor(name)) {
+            try {
+                apply(await registration.handler(event, context));
+            }
+            catch (error) {
+                await this.reportError(error instanceof Error ? error : new Error(String(error)), name, event.lane, context);
+            }
+        }
+    }
+}
+export function applyStreamOptionsPatch(base, patch) {
+    const next = { ...base };
+    for (const key of [
+        "transport",
+        "timeoutMs",
+        "maxRetries",
+        "maxRetryDelayMs",
+        "cacheRetention",
+        "deferred",
+    ]) {
+        if (!(key in patch))
+            continue;
+        const value = patch[key];
+        if (value === undefined)
+            delete next[key];
+        else
+            Object.assign(next, { [key]: value });
+    }
+    if ("headers" in patch) {
+        if (patch.headers === undefined)
+            delete next.headers;
+        else {
+            const headers = { ...next.headers };
+            for (const [key, value] of Object.entries(patch.headers)) {
+                if (value === undefined)
+                    delete headers[key];
+                else
+                    headers[key] = value;
+            }
+            next.headers = headers;
+        }
+    }
+    if ("metadata" in patch) {
+        if (patch.metadata === undefined)
+            delete next.metadata;
+        else {
+            const metadata = { ...next.metadata };
+            for (const [key, value] of Object.entries(patch.metadata)) {
+                if (value === undefined)
+                    delete metadata[key];
+                else
+                    metadata[key] = value;
+            }
+            next.metadata = metadata;
+        }
+    }
+    return next;
+}
+function createStreamOptionsPatch(base, value) {
+    const patch = {};
+    for (const key of [
+        "transport",
+        "timeoutMs",
+        "maxRetries",
+        "maxRetryDelayMs",
+        "cacheRetention",
+        "deferred",
+    ]) {
+        if (base[key] !== value[key])
+            Object.assign(patch, { [key]: value[key] });
+    }
+    if (base.headers !== value.headers) {
+        if (value.headers === undefined)
+            patch.headers = undefined;
+        else {
+            const headers = {};
+            for (const key of Object.keys(base.headers ?? {})) {
+                if (!(key in value.headers))
+                    headers[key] = undefined;
+            }
+            for (const [key, header] of Object.entries(value.headers)) {
+                if (base.headers?.[key] !== header)
+                    headers[key] = header;
+            }
+            if (base.headers === undefined && Object.keys(headers).length === 0)
+                patch.headers = {};
+            else if (Object.keys(headers).length !== 0)
+                patch.headers = headers;
+        }
+    }
+    if (base.metadata !== value.metadata) {
+        if (value.metadata === undefined)
+            patch.metadata = undefined;
+        else {
+            const metadata = {};
+            for (const key of Object.keys(base.metadata ?? {})) {
+                if (!(key in value.metadata))
+                    metadata[key] = undefined;
+            }
+            for (const [key, metadataValue] of Object.entries(value.metadata)) {
+                if (base.metadata?.[key] !== metadataValue)
+                    metadata[key] = metadataValue;
+            }
+            if (base.metadata === undefined && Object.keys(metadata).length === 0)
+                patch.metadata = {};
+            else if (Object.keys(metadata).length !== 0)
+                patch.metadata = metadata;
+        }
+    }
+    return patch;
+}
+//# sourceMappingURL=hooks.js.map