@lleverage-ai/agent-sdk 0.0.1

package/dist/middleware/logging.js

@@ -0,0 +1,374 @@
+/**
+ * Logging middleware.
+ *
+ * Provides middleware for logging agent lifecycle events using the SDK's
+ * logging primitives. The middleware is transport-agnostic - users provide
+ * their own transport which determines where logs go.
+ *
+ * @packageDocumentation
+ */
+import { createLogger } from "../observability/logger.js";
+/**
+ * Truncates a string to the specified length.
+ */
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return `${str.slice(0, maxLen)}...`;
+}
+/**
+ * Safely stringifies a value for logging.
+ */
+function safeStringify(value, maxLen) {
+    try {
+        const str = JSON.stringify(value);
+        return truncate(str, maxLen);
+    }
+    catch {
+        return "[Unable to stringify]";
+    }
+}
+/**
+ * Creates logging middleware that logs agent lifecycle events.
+ *
+ * The transport determines where logs go - SDK is agnostic. If you want
+ * streaming to a client, create a transport that writes to your stream.
+ *
+ * @param options - Logging middleware configuration
+ * @returns AgentMiddleware instance
+ *
+ * @example
+ * ```typescript
+ * // Console logging
+ * import { createAgent, createLoggingMiddleware, createConsoleTransport } from "@lleverage-ai/agent-sdk";
+ *
+ * const agent = createAgent({
+ *   model,
+ *   middleware: [
+ *     createLoggingMiddleware({ transport: createConsoleTransport() }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom transport (e.g., streaming to client)
+ * const streamTransport: LogTransport = {
+ *   name: "client-stream",
+ *   write: (entry) => {
+ *     // User decides how to get this to the client
+ *     res.write(`data: ${JSON.stringify(entry)}\n\n`);
+ *   },
+ * };
+ *
+ * const agent = createAgent({
+ *   model,
+ *   middleware: [
+ *     createLoggingMiddleware({ transport: streamTransport }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // External service (e.g., Datadog)
+ * const datadogTransport: LogTransport = {
+ *   name: "datadog",
+ *   write: (entry) => datadog.log(entry.level, entry.message, entry.context),
+ * };
+ *
+ * const agent = createAgent({
+ *   model,
+ *   middleware: [
+ *     createLoggingMiddleware({ transport: datadogTransport }),
+ *   ],
+ * });
+ * ```
+ *
+ * @category Middleware
+ */
+export function createLoggingMiddleware(options) {
+    const { transport, level = "info", events = {}, maxContentLength = 500, includeTiming = true, name = "agent", } = options;
+    // Default all events to enabled
+    const { generation = true, tools = true, compaction = true, failures = true, subagents = true, interrupts = true, } = events;
+    // Create logger with the provided transport
+    const logger = createLogger({
+        name,
+        level,
+        transports: [transport],
+    });
+    // Track timing for operations
+    const generationStartTimes = new Map();
+    const toolStartTimes = new Map();
+    const compactionStartTimes = new Map();
+    const subagentStartTimes = new Map();
+    return {
+        name: "logging",
+        register(ctx) {
+            // Generation logging
+            if (generation) {
+                ctx.onPreGenerate(async (input) => {
+                    if (input.hook_event_name !== "PreGenerate")
+                        return {};
+                    const preInput = input;
+                    if (includeTiming) {
+                        generationStartTimes.set(preInput.session_id, Date.now());
+                    }
+                    logger.info("Generation starting", {
+                        messageCount: preInput.options.messages?.length ?? 0,
+                        hasPrompt: !!preInput.options.prompt,
+                        threadId: preInput.options.threadId,
+                    });
+                    return {};
+                });
+                ctx.onPostGenerate(async (input) => {
+                    if (input.hook_event_name !== "PostGenerate")
+                        return {};
+                    const postInput = input;
+                    const context = {
+                        finishReason: postInput.result.finishReason,
+                        text: truncate(postInput.result.text ?? "", maxContentLength),
+                        stepCount: postInput.result.steps?.length ?? 0,
+                    };
+                    if (postInput.result.usage) {
+                        context.tokens = {
+                            input: postInput.result.usage.inputTokens,
+                            output: postInput.result.usage.outputTokens,
+                            total: postInput.result.usage.totalTokens,
+                        };
+                    }
+                    if (includeTiming) {
+                        const startTime = generationStartTimes.get(postInput.session_id);
+                        if (startTime) {
+                            context.durationMs = Date.now() - startTime;
+                            generationStartTimes.delete(postInput.session_id);
+                        }
+                    }
+                    logger.info("Generation complete", context);
+                    return {};
+                });
+            }
+            // Generation failure logging
+            if (failures) {
+                ctx.onPostGenerateFailure(async (input) => {
+                    if (input.hook_event_name !== "PostGenerateFailure")
+                        return {};
+                    const failInput = input;
+                    const context = {
+                        error: failInput.error?.message ?? "Unknown error",
+                    };
+                    if (includeTiming) {
+                        const startTime = generationStartTimes.get(failInput.session_id);
+                        if (startTime) {
+                            context.durationMs = Date.now() - startTime;
+                            generationStartTimes.delete(failInput.session_id);
+                        }
+                    }
+                    logger.error("Generation failed", failInput.error, context);
+                    return {};
+                });
+            }
+            // Tool logging
+            if (tools) {
+                ctx.onPreToolUse(async (input, toolUseId) => {
+                    if (input.hook_event_name !== "PreToolUse")
+                        return {};
+                    const toolInput = input;
+                    if (includeTiming && toolUseId) {
+                        toolStartTimes.set(toolUseId, Date.now());
+                    }
+                    logger.info(`Tool call: ${toolInput.tool_name}`, {
+                        toolName: toolInput.tool_name,
+                        input: safeStringify(toolInput.tool_input, maxContentLength),
+                    });
+                    return {};
+                });
+                ctx.onPostToolUse(async (input, toolUseId) => {
+                    if (input.hook_event_name !== "PostToolUse")
+                        return {};
+                    const toolInput = input;
+                    const context = {
+                        toolName: toolInput.tool_name,
+                        output: safeStringify(toolInput.tool_response, maxContentLength),
+                    };
+                    if (includeTiming && toolUseId) {
+                        const startTime = toolStartTimes.get(toolUseId);
+                        if (startTime) {
+                            context.durationMs = Date.now() - startTime;
+                            toolStartTimes.delete(toolUseId);
+                        }
+                    }
+                    logger.info(`Tool complete: ${toolInput.tool_name}`, context);
+                    return {};
+                });
+            }
+            // Tool failure logging
+            if (failures) {
+                ctx.onPostToolUseFailure(async (input, toolUseId) => {
+                    if (input.hook_event_name !== "PostToolUseFailure")
+                        return {};
+                    const toolInput = input;
+                    const errorMessage = typeof toolInput.error === "string"
+                        ? toolInput.error
+                        : (toolInput.error?.message ?? "Unknown error");
+                    const context = {
+                        toolName: toolInput.tool_name,
+                        error: errorMessage,
+                    };
+                    if (includeTiming && toolUseId) {
+                        const startTime = toolStartTimes.get(toolUseId);
+                        if (startTime) {
+                            context.durationMs = Date.now() - startTime;
+                            toolStartTimes.delete(toolUseId);
+                        }
+                    }
+                    logger.error(`Tool failed: ${toolInput.tool_name}`, context);
+                    return {};
+                });
+            }
+            // Compaction logging
+            if (compaction) {
+                ctx.onPreCompact(async (input) => {
+                    if (input.hook_event_name !== "PreCompact")
+                        return {};
+                    const compactInput = input;
+                    if (includeTiming) {
+                        compactionStartTimes.set(compactInput.session_id, Date.now());
+                    }
+                    logger.info("Context compaction starting", {
+                        messageCount: compactInput.message_count,
+                        tokensBefore: compactInput.tokens_before,
+                    });
+                    return {};
+                });
+                ctx.onPostCompact(async (input) => {
+                    if (input.hook_event_name !== "PostCompact")
+                        return {};
+                    const compactInput = input;
+                    const reductionPercent = compactInput.tokens_before > 0
+                        ? ((compactInput.tokens_saved / compactInput.tokens_before) * 100).toFixed(1)
+                        : "0.0";
+                    const context = {
+                        messagesBefore: compactInput.messages_before,
+                        messagesAfter: compactInput.messages_after,
+                        tokensBefore: compactInput.tokens_before,
+                        tokensAfter: compactInput.tokens_after,
+                        tokensSaved: compactInput.tokens_saved,
+                        reductionPercent,
+                    };
+                    if (includeTiming) {
+                        const startTime = compactionStartTimes.get(compactInput.session_id);
+                        if (startTime) {
+                            context.durationMs = Date.now() - startTime;
+                            compactionStartTimes.delete(compactInput.session_id);
+                        }
+                    }
+                    logger.info("Context compaction complete", context);
+                    return {};
+                });
+            }
+            // Subagent logging
+            if (subagents) {
+                ctx.onSubagentStart(async (input) => {
+                    if (input.hook_event_name !== "SubagentStart")
+                        return {};
+                    const subagentInput = input;
+                    if (includeTiming) {
+                        subagentStartTimes.set(subagentInput.agent_id, Date.now());
+                    }
+                    logger.info(`Subagent started: ${subagentInput.agent_type}`, {
+                        agentId: subagentInput.agent_id,
+                        agentType: subagentInput.agent_type,
+                        prompt: subagentInput.prompt
+                            ? truncate(subagentInput.prompt, maxContentLength)
+                            : undefined,
+                    });
+                    return {};
+                });
+                ctx.onSubagentStop(async (input) => {
+                    if (input.hook_event_name !== "SubagentStop")
+                        return {};
+                    const subagentInput = input;
+                    const context = {
+                        agentId: subagentInput.agent_id,
+                        agentType: subagentInput.agent_type,
+                    };
+                    if (subagentInput.error) {
+                        context.error = subagentInput.error.message;
+                    }
+                    if (includeTiming) {
+                        const startTime = subagentStartTimes.get(subagentInput.agent_id);
+                        if (startTime) {
+                            context.durationMs = Date.now() - startTime;
+                            subagentStartTimes.delete(subagentInput.agent_id);
+                        }
+                    }
+                    if (subagentInput.error) {
+                        logger.error(`Subagent failed: ${subagentInput.agent_type}`, context);
+                    }
+                    else {
+                        logger.info(`Subagent complete: ${subagentInput.agent_type}`, context);
+                    }
+                    return {};
+                });
+            }
+            // Interrupt logging
+            if (interrupts) {
+                ctx.onInterruptRequested(async (input) => {
+                    if (input.hook_event_name !== "InterruptRequested")
+                        return {};
+                    const interruptInput = input;
+                    const context = {
+                        interruptId: interruptInput.interrupt_id,
+                        interruptType: interruptInput.interrupt_type,
+                    };
+                    if (interruptInput.tool_name) {
+                        context.toolName = interruptInput.tool_name;
+                    }
+                    if (interruptInput.tool_call_id) {
+                        context.toolCallId = interruptInput.tool_call_id;
+                    }
+                    // For approval interrupts, log the request details
+                    if (interruptInput.interrupt_type === "approval") {
+                        logger.info(`Approval requested: ${interruptInput.tool_name}`, context);
+                    }
+                    else {
+                        logger.info(`Interrupt requested: ${interruptInput.interrupt_type}`, context);
+                    }
+                    return {};
+                });
+                ctx.onInterruptResolved(async (input) => {
+                    if (input.hook_event_name !== "InterruptResolved")
+                        return {};
+                    const interruptInput = input;
+                    const context = {
+                        interruptId: interruptInput.interrupt_id,
+                        interruptType: interruptInput.interrupt_type,
+                    };
+                    if (interruptInput.tool_name) {
+                        context.toolName = interruptInput.tool_name;
+                    }
+                    if (interruptInput.tool_call_id) {
+                        context.toolCallId = interruptInput.tool_call_id;
+                    }
+                    // For approval interrupts, log the approval decision
+                    if (interruptInput.interrupt_type === "approval") {
+                        context.approved = interruptInput.approved;
+                        const decision = interruptInput.approved ? "approved" : "denied";
+                        logger.info(`Approval ${decision}: ${interruptInput.tool_name}`, context);
+                    }
+                    else {
+                        logger.info(`Interrupt resolved: ${interruptInput.interrupt_type}`, context);
+                    }
+                    return {};
+                });
+            }
+        },
+        async teardown() {
+            // Flush and close the logger
+            await logger.flush();
+            await logger.close();
+        },
+    };
+}
+//# sourceMappingURL=logging.js.map

package/dist/middleware/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/middleware/logging.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAwF1D;;GAEG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,MAAc;IAC3C,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,GAAG,CAAC;IACrC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,KAAc,EAAE,MAAc;IACnD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAClC,OAAO,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,uBAAuB,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IACvE,MAAM,EACJ,SAAS,EACT,KAAK,GAAG,MAAM,EACd,MAAM,GAAG,EAAE,EACX,gBAAgB,GAAG,GAAG,EACtB,aAAa,GAAG,IAAI,EACpB,IAAI,GAAG,OAAO,GACf,GAAG,OAAO,CAAC;IAEZ,gCAAgC;IAChC,MAAM,EACJ,UAAU,GAAG,IAAI,EACjB,KAAK,GAAG,IAAI,EACZ,UAAU,GAAG,IAAI,EACjB,QAAQ,GAAG,IAAI,EACf,SAAS,GAAG,IAAI,EAChB,UAAU,GAAG,IAAI,GAClB,GAAG,MAAM,CAAC;IAEX,4CAA4C;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAC;QAC1B,IAAI;QACJ,KAAK;QACL,UAAU,EAAE,CAAC,SAAS,CAAC;KACxB,CAAC,CAAC;IAEH,8BAA8B;IAC9B,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjD,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvD,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAkB,CAAC;IAErD,OAAO;QACL,IAAI,EAAE,SAAS;QAEf,QAAQ,CAAC,GAAsB;YAC7B,qBAAqB;YACrB,IAAI,UAAU,EAAE,CAAC;gBACf,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBAChC,IAAI,KAAK,CAAC,eAAe,KAAK,aAAa;wBAAE,OAAO,EAAE,CAAC;oBACvD,MAAM,QAAQ,GAAG,KAAyB,CAAC;oBAE3C,IAAI,aAAa,EAAE,CAAC;wBAClB,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;oBAC5D,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE;wBACjC,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;wBACpD,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM;wBACpC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ;qBACpC,CAAC,CAAC;oBAEH,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;gBAEH,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBACjC,IAAI,KAAK,CAAC,eAAe,KAAK,cAAc;wBAAE,OAAO,EAAE,CAAC;oBACxD,MAAM,SAAS,GAAG,KAA0B,CAAC;oBAE7C,MAAM,OAAO,GAA4B;wBACvC,YAAY,EAAE,SAAS,CAAC,MAAM,CAAC,YAAY;wBAC3C,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,gBAAgB,CAAC;wBAC7D,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;qBAC/C,CAAC;oBAEF,IAAI,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;wBAC3B,OAAO,CAAC,MAAM,GAAG;4BACf,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW;4BACzC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY;4BAC3C,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW;yBAC1C,CAAC;oBACJ,CAAC;oBAED,IAAI,aAAa,EAAE,CAAC;wBAClB,MAAM,SAAS,GAAG,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;wBACjE,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAC5C,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;wBACpD,CAAC;oBACH,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;oBAE5C,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAED,6BAA6B;YAC7B,IAAI,QAAQ,EAAE,CAAC;gBACb,GAAG,CAAC,qBAAqB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBACxC,IAAI,KAAK,CAAC,eAAe,KAAK,qBAAqB;wBAAE,OAAO,EAAE,CAAC;oBAC/D,MAAM,SAAS,GAAG,KAAiC,CAAC;oBAEpD,MAAM,OAAO,GAA4B;wBACvC,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe;qBACnD,CAAC;oBAEF,IAAI,aAAa,EAAE,CAAC;wBAClB,MAAM,SAAS,GAAG,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;wBACjE,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAC5C,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;wBACpD,CAAC;oBACH,CAAC;oBAED,MAAM,CAAC,KAAK,CAAC,mBAAmB,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;oBAE5D,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAED,eAAe;YACf,IAAI,KAAK,EAAE,CAAC;gBACV,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;oBAC1C,IAAI,KAAK,CAAC,eAAe,KAAK,YAAY;wBAAE,OAAO,EAAE,CAAC;oBACtD,MAAM,SAAS,GAAG,KAAwB,CAAC;oBAE3C,IAAI,aAAa,IAAI,SAAS,EAAE,CAAC;wBAC/B,cAAc,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;oBAC5C,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,cAAc,SAAS,CAAC,SAAS,EAAE,EAAE;wBAC/C,QAAQ,EAAE,SAAS,CAAC,SAAS;wBAC7B,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,UAAU,EAAE,gBAAgB,CAAC;qBAC7D,CAAC,CAAC;oBAEH,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;gBAEH,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;oBAC3C,IAAI,KAAK,CAAC,eAAe,KAAK,aAAa;wBAAE,OAAO,EAAE,CAAC;oBACvD,MAAM,SAAS,GAAG,KAAyB,CAAC;oBAE5C,MAAM,OAAO,GAA4B;wBACvC,QAAQ,EAAE,SAAS,CAAC,SAAS;wBAC7B,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,CAAC;qBACjE,CAAC;oBAEF,IAAI,aAAa,IAAI,SAAS,EAAE,CAAC;wBAC/B,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;wBAChD,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAC5C,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;wBACnC,CAAC;oBACH,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,kBAAkB,SAAS,CAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;oBAE9D,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAED,uBAAuB;YACvB,IAAI,QAAQ,EAAE,CAAC;gBACb,GAAG,CAAC,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;oBAClD,IAAI,KAAK,CAAC,eAAe,KAAK,oBAAoB;wBAAE,OAAO,EAAE,CAAC;oBAC9D,MAAM,SAAS,GAAG,KAAgC,CAAC;oBAEnD,MAAM,YAAY,GAChB,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ;wBACjC,CAAC,CAAC,SAAS,CAAC,KAAK;wBACjB,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe,CAAC,CAAC;oBAEpD,MAAM,OAAO,GAA4B;wBACvC,QAAQ,EAAE,SAAS,CAAC,SAAS;wBAC7B,KAAK,EAAE,YAAY;qBACpB,CAAC;oBAEF,IAAI,aAAa,IAAI,SAAS,EAAE,CAAC;wBAC/B,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;wBAChD,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAC5C,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;wBACnC,CAAC;oBACH,CAAC;oBAED,MAAM,CAAC,KAAK,CAAC,gBAAgB,SAAS,CAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;oBAE7D,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAED,qBAAqB;YACrB,IAAI,UAAU,EAAE,CAAC;gBACf,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBAC/B,IAAI,KAAK,CAAC,eAAe,KAAK,YAAY;wBAAE,OAAO,EAAE,CAAC;oBACtD,MAAM,YAAY,GAAG,KAAwB,CAAC;oBAE9C,IAAI,aAAa,EAAE,CAAC;wBAClB,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;oBAChE,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,6BAA6B,EAAE;wBACzC,YAAY,EAAE,YAAY,CAAC,aAAa;wBACxC,YAAY,EAAE,YAAY,CAAC,aAAa;qBACzC,CAAC,CAAC;oBAEH,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;gBAEH,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBAChC,IAAI,KAAK,CAAC,eAAe,KAAK,aAAa;wBAAE,OAAO,EAAE,CAAC;oBACvD,MAAM,YAAY,GAAG,KAAyB,CAAC;oBAE/C,MAAM,gBAAgB,GACpB,YAAY,CAAC,aAAa,GAAG,CAAC;wBAC5B,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,YAAY,GAAG,YAAY,CAAC,aAAa,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;wBAC7E,CAAC,CAAC,KAAK,CAAC;oBAEZ,MAAM,OAAO,GAA4B;wBACvC,cAAc,EAAE,YAAY,CAAC,eAAe;wBAC5C,aAAa,EAAE,YAAY,CAAC,cAAc;wBAC1C,YAAY,EAAE,YAAY,CAAC,aAAa;wBACxC,WAAW,EAAE,YAAY,CAAC,YAAY;wBACtC,WAAW,EAAE,YAAY,CAAC,YAAY;wBACtC,gBAAgB;qBACjB,CAAC;oBAEF,IAAI,aAAa,EAAE,CAAC;wBAClB,MAAM,SAAS,GAAG,oBAAoB,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;wBACpE,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAC5C,oBAAoB,CAAC,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;wBACvD,CAAC;oBACH,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,6BAA6B,EAAE,OAAO,CAAC,CAAC;oBAEpD,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAED,mBAAmB;YACnB,IAAI,SAAS,EAAE,CAAC;gBACd,GAAG,CAAC,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBAClC,IAAI,KAAK,CAAC,eAAe,KAAK,eAAe;wBAAE,OAAO,EAAE,CAAC;oBACzD,MAAM,aAAa,GAAG,KAA2B,CAAC;oBAElD,IAAI,aAAa,EAAE,CAAC;wBAClB,kBAAkB,CAAC,GAAG,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;oBAC7D,CAAC;oBAED,MAAM,CAAC,IAAI,CAAC,qBAAqB,aAAa,CAAC,UAAU,EAAE,EAAE;wBAC3D,OAAO,EAAE,aAAa,CAAC,QAAQ;wBAC/B,SAAS,EAAE,aAAa,CAAC,UAAU;wBACnC,MAAM,EAAE,aAAa,CAAC,MAAM;4BAC1B,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,gBAAgB,CAAC;4BAClD,CAAC,CAAC,SAAS;qBACd,CAAC,CAAC;oBAEH,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;gBAEH,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBACjC,IAAI,KAAK,CAAC,eAAe,KAAK,cAAc;wBAAE,OAAO,EAAE,CAAC;oBACxD,MAAM,aAAa,GAAG,KAA0B,CAAC;oBAEjD,MAAM,OAAO,GAA4B;wBACvC,OAAO,EAAE,aAAa,CAAC,QAAQ;wBAC/B,SAAS,EAAE,aAAa,CAAC,UAAU;qBACpC,CAAC;oBAEF,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC;wBACxB,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;oBAC9C,CAAC;oBAED,IAAI,aAAa,EAAE,CAAC;wBAClB,MAAM,SAAS,GAAG,kBAAkB,CAAC,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;wBACjE,IAAI,SAAS,EAAE,CAAC;4BACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;4BAC5C,kBAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;wBACpD,CAAC;oBACH,CAAC;oBAED,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC;wBACxB,MAAM,CAAC,KAAK,CAAC,oBAAoB,aAAa,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;oBACxE,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,IAAI,CAAC,sBAAsB,aAAa,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;oBACzE,CAAC;oBAED,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;YAED,oBAAoB;YACpB,IAAI,UAAU,EAAE,CAAC;gBACf,GAAG,CAAC,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBACvC,IAAI,KAAK,CAAC,eAAe,KAAK,oBAAoB;wBAAE,OAAO,EAAE,CAAC;oBAC9D,MAAM,cAAc,GAAG,KAAgC,CAAC;oBAExD,MAAM,OAAO,GAA4B;wBACvC,WAAW,EAAE,cAAc,CAAC,YAAY;wBACxC,aAAa,EAAE,cAAc,CAAC,cAAc;qBAC7C,CAAC;oBAEF,IAAI,cAAc,CAAC,SAAS,EAAE,CAAC;wBAC7B,OAAO,CAAC,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC;oBAC9C,CAAC;oBACD,IAAI,cAAc,CAAC,YAAY,EAAE,CAAC;wBAChC,OAAO,CAAC,UAAU,GAAG,cAAc,CAAC,YAAY,CAAC;oBACnD,CAAC;oBAED,mDAAmD;oBACnD,IAAI,cAAc,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;wBACjD,MAAM,CAAC,IAAI,CAAC,uBAAuB,cAAc,CAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;oBAC1E,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,IAAI,CAAC,wBAAwB,cAAc,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;oBAChF,CAAC;oBAED,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;gBAEH,GAAG,CAAC,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBACtC,IAAI,KAAK,CAAC,eAAe,KAAK,mBAAmB;wBAAE,OAAO,EAAE,CAAC;oBAC7D,MAAM,cAAc,GAAG,KAA+B,CAAC;oBAEvD,MAAM,OAAO,GAA4B;wBACvC,WAAW,EAAE,cAAc,CAAC,YAAY;wBACxC,aAAa,EAAE,cAAc,CAAC,cAAc;qBAC7C,CAAC;oBAEF,IAAI,cAAc,CAAC,SAAS,EAAE,CAAC;wBAC7B,OAAO,CAAC,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC;oBAC9C,CAAC;oBACD,IAAI,cAAc,CAAC,YAAY,EAAE,CAAC;wBAChC,OAAO,CAAC,UAAU,GAAG,cAAc,CAAC,YAAY,CAAC;oBACnD,CAAC;oBAED,qDAAqD;oBACrD,IAAI,cAAc,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;wBACjD,OAAO,CAAC,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC;wBAC3C,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;wBACjE,MAAM,CAAC,IAAI,CAAC,YAAY,QAAQ,KAAK,cAAc,CAAC,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;oBAC5E,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,IAAI,CAAC,uBAAuB,cAAc,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,CAAC;oBAC/E,CAAC;oBAED,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,KAAK,CAAC,QAAQ;YACZ,6BAA6B;YAC7B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Middleware type definitions.
+ *
+ * Middleware provides a clean API for adding cross-cutting concerns like
+ * logging, metrics, caching, and rate limiting to agents. Middleware wraps
+ * the underlying hook system with a more ergonomic interface.
+ *
+ * @packageDocumentation
+ */
+import type { HookCallback, HookRegistration } from "../types.js";
+/**
+ * Context provided to middleware for registering hooks.
+ *
+ * Middleware uses this context to register event handlers during agent
+ * creation. Hooks are registered in middleware order, preserving the
+ * order in which middleware was added.
+ *
+ * @category Middleware
+ */
+export interface MiddlewareContext {
+    /**
+     * Register a PreGenerate hook.
+     * Called before each generation request.
+     */
+    onPreGenerate(callback: HookCallback): void;
+    /**
+     * Register a PostGenerate hook.
+     * Called after each successful generation.
+     */
+    onPostGenerate(callback: HookCallback): void;
+    /**
+     * Register a PostGenerateFailure hook.
+     * Called when generation fails.
+     */
+    onPostGenerateFailure(callback: HookCallback): void;
+    /**
+     * Register a PreToolUse hook.
+     * Called before each tool execution.
+     *
+     * @param callback - The hook callback to invoke
+     * @param matcher - Optional regex pattern to match tool names (e.g., "Write|Edit")
+     */
+    onPreToolUse(callback: HookCallback, matcher?: string): void;
+    /**
+     * Register a PostToolUse hook.
+     * Called after each successful tool execution.
+     *
+     * @param callback - The hook callback to invoke
+     * @param matcher - Optional regex pattern to match tool names
+     */
+    onPostToolUse(callback: HookCallback, matcher?: string): void;
+    /**
+     * Register a PostToolUseFailure hook.
+     * Called when tool execution fails.
+     *
+     * @param callback - The hook callback to invoke
+     * @param matcher - Optional regex pattern to match tool names
+     */
+    onPostToolUseFailure(callback: HookCallback, matcher?: string): void;
+    /**
+     * Register a PreCompact hook.
+     * Called before context compaction.
+     */
+    onPreCompact(callback: HookCallback): void;
+    /**
+     * Register a PostCompact hook.
+     * Called after context compaction.
+     */
+    onPostCompact(callback: HookCallback): void;
+    /**
+     * Register a SessionStart hook.
+     * Called when a session starts.
+     */
+    onSessionStart(callback: HookCallback): void;
+    /**
+     * Register a SessionEnd hook.
+     * Called when a session ends.
+     */
+    onSessionEnd(callback: HookCallback): void;
+    /**
+     * Register a SubagentStart hook.
+     * Called when a subagent starts.
+     */
+    onSubagentStart(callback: HookCallback): void;
+    /**
+     * Register a SubagentStop hook.
+     * Called when a subagent stops.
+     */
+    onSubagentStop(callback: HookCallback): void;
+    /**
+     * Register an MCPConnectionFailed hook.
+     * Called when an MCP connection fails.
+     */
+    onMCPConnectionFailed(callback: HookCallback): void;
+    /**
+     * Register an MCPConnectionRestored hook.
+     * Called when an MCP connection is restored.
+     */
+    onMCPConnectionRestored(callback: HookCallback): void;
+    /**
+     * Register an InterruptRequested hook.
+     * Called when an interrupt is requested (approval request, custom interrupt, etc.).
+     */
+    onInterruptRequested(callback: HookCallback): void;
+    /**
+     * Register an InterruptResolved hook.
+     * Called when an interrupt is resolved (approved, denied, or custom response).
+     */
+    onInterruptResolved(callback: HookCallback): void;
+}
+/**
+ * Agent middleware interface.
+ *
+ * Middleware registers hooks and can have lifecycle methods for setup and
+ * teardown. Middleware provides a cleaner API than raw hooks for adding
+ * cross-cutting concerns to agents.
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: AgentMiddleware = {
+ *   name: "logging",
+ *   register(ctx) {
+ *     ctx.onPreGenerate(async (input) => {
+ *       console.log("Generation starting");
+ *       return {};
+ *     });
+ *     ctx.onPostGenerate(async (input) => {
+ *       console.log("Generation complete");
+ *       return {};
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * @category Middleware
+ */
+export interface AgentMiddleware {
+    /**
+     * Unique middleware name.
+     * Used for debugging and error messages.
+     */
+    name: string;
+    /**
+     * Called during agent creation to register hooks.
+     *
+     * Use the context to register event handlers for various lifecycle events.
+     * Hooks are executed in the order middleware was added to the agent.
+     *
+     * @param context - The middleware context for registering hooks
+     */
+    register(context: MiddlewareContext): void;
+    /**
+     * Optional setup called during agent creation.
+     *
+     * Use this for initialization that needs to happen before the agent
+     * starts processing requests, such as establishing connections or
+     * loading configuration.
+     */
+    setup?(): Promise<void> | void;
+    /**
+     * Optional teardown for cleanup.
+     *
+     * Use this to clean up resources when the agent is being disposed,
+     * such as closing connections or flushing buffers.
+     */
+    teardown?(): Promise<void> | void;
+}
+/**
+ * Result of creating a middleware context.
+ *
+ * Contains the context for registering hooks and a function to retrieve
+ * the collected hook registrations.
+ *
+ * @category Middleware
+ * @internal
+ */
+export interface MiddlewareContextResult {
+    /** The context provided to middleware for registering hooks */
+    context: MiddlewareContext;
+    /** Get the collected hook registrations */
+    getHooks(): HookRegistration;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5C;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAEpD;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7D;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9D;;;;;;OAMG;IACH,oBAAoB,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAErE;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE3C;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5C;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE3C;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE9C;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAE7C;;;OAGG;IACH,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAEpD;;;OAGG;IACH,uBAAuB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtD;;;OAGG;IACH,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAEnD;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE/B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,OAAO,EAAE,iBAAiB,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,IAAI,gBAAgB,CAAC;CAC9B"}

package/dist/middleware/types.js

@@ -0,0 +1,11 @@
+/**
+ * Middleware type definitions.
+ *
+ * Middleware provides a clean API for adding cross-cutting concerns like
+ * logging, metrics, caching, and rate limiting to agents. Middleware wraps
+ * the underlying hook system with a more ergonomic interface.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}