@lleverage-ai/agent-sdk 0.0.1

package/dist/hooks/logging.js

@@ -0,0 +1,345 @@
+/**
+ * Logging hook utilities.
+ *
+ * Provides logging hooks for observability and debugging using the unified
+ * hook system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Truncates text to maximum length with ellipsis.
+ */
+function truncate(text, maxLength) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return `${text.slice(0, maxLength)}...`;
+}
+/**
+ * Formats message count by role.
+ */
+function formatMessageCount(messages = []) {
+    const byRole = {};
+    for (const msg of messages) {
+        if (typeof msg === "object" && msg !== null && "role" in msg) {
+            const role = String(msg.role);
+            byRole[role] = (byRole[role] ?? 0) + 1;
+        }
+    }
+    return Object.entries(byRole)
+        .map(([role, count]) => `${count} ${role}`)
+        .join(", ");
+}
+/**
+ * Creates logging hooks for generation lifecycle events.
+ *
+ * Provides Pre/Post logging for generation with timing information,
+ * usage statistics, and error logging.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for generation events
+ *
+ * @example
+ * ```typescript
+ * const logHooks = createLoggingHooks({
+ *   prefix: "[MyAgent]",
+ *   logTiming: true,
+ *   maxTextLength: 100,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [logHooks[0]] }],
+ *     PostGenerate: [{ hooks: [logHooks[1]] }],
+ *     PostGenerateFailure: [{ hooks: [logHooks[2]] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom logger (e.g., structured logging)
+ * const logHooks = createLoggingHooks({
+ *   log: (msg) => logger.info(msg),
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createLoggingHooks(options = {}) {
+    const { log = console.log, logGeneration = true, logTiming = true, maxTextLength = 200, prefix = "[Agent]", logFullMessages = false, } = options;
+    const startTimes = new Map();
+    // PreGenerate: Log request
+    const preGenerate = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        if (!logGeneration)
+            return {};
+        const preGenInput = input;
+        const { messages, temperature, maxTokens } = preGenInput.options;
+        const messageInfo = logFullMessages ? JSON.stringify(messages) : formatMessageCount(messages);
+        let logMsg = `${prefix} PreGenerate:`;
+        logMsg += `\n  Messages: ${messageInfo}`;
+        if (temperature !== undefined)
+            logMsg += `\n  Temperature: ${temperature}`;
+        if (maxTokens !== undefined)
+            logMsg += `\n  MaxTokens: ${maxTokens}`;
+        log(logMsg);
+        // Track start time for this session
+        if (logTiming) {
+            startTimes.set(preGenInput.session_id, Date.now());
+        }
+        return {};
+    };
+    // PostGenerate: Log response
+    const postGenerate = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        if (!logGeneration)
+            return {};
+        const postGenInput = input;
+        const { result } = postGenInput;
+        let logMsg = `${prefix} PostGenerate:`;
+        logMsg += `\n  Text: ${truncate(result.text || "", maxTextLength)}`;
+        logMsg += `\n  Finish: ${result.finishReason}`;
+        if (result.usage) {
+            logMsg += `\n  Tokens: ${result.usage.totalTokens} (${result.usage.inputTokens} in, ${result.usage.outputTokens} out)`;
+        }
+        // Add timing if available
+        if (logTiming) {
+            const startTime = startTimes.get(postGenInput.session_id);
+            if (startTime) {
+                const duration = Date.now() - startTime;
+                logMsg += `\n  Duration: ${duration}ms`;
+                startTimes.delete(postGenInput.session_id);
+            }
+        }
+        log(logMsg);
+        return {};
+    };
+    // PostGenerateFailure: Log error
+    const postGenerateFailure = async (input) => {
+        if (input.hook_event_name !== "PostGenerateFailure")
+            return {};
+        const failureInput = input;
+        let logMsg = `${prefix} PostGenerateFailure:`;
+        logMsg += `\n  Error: ${failureInput.error.message}`;
+        // Add timing if available
+        if (logTiming) {
+            const startTime = startTimes.get(failureInput.session_id);
+            if (startTime) {
+                const duration = Date.now() - startTime;
+                logMsg += `\n  Duration: ${duration}ms (failed)`;
+                startTimes.delete(failureInput.session_id);
+            }
+        }
+        log(logMsg);
+        return {};
+    };
+    return [preGenerate, postGenerate, postGenerateFailure];
+}
+/**
+ * Creates logging hooks for tool execution events.
+ *
+ * Provides Pre/Post logging for tool calls with arguments, results,
+ * and error information.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for tool events
+ *
+ * @example
+ * ```typescript
+ * const toolLogHooks = createToolLoggingHooks({
+ *   prefix: "[Tools]",
+ *   maxTextLength: 150,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreToolUse: [{ hooks: [toolLogHooks[0]] }],
+ *     PostToolUse: [{ hooks: [toolLogHooks[1]] }],
+ *     PostToolUseFailure: [{ hooks: [toolLogHooks[2]] }],
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createToolLoggingHooks(options = {}) {
+    const { log = console.log, logTools = true, logTiming = true, logErrors = true, maxTextLength = 200, prefix = "[Agent]", } = options;
+    const toolStartTimes = new Map();
+    // PreToolUse: Log tool call
+    const preToolUse = async (input, toolUseId) => {
+        if (input.hook_event_name !== "PreToolUse")
+            return {};
+        if (!logTools)
+            return {};
+        const preToolInput = input;
+        let logMsg = `${prefix} PreToolUse: ${preToolInput.tool_name}`;
+        logMsg += `\n  Input: ${truncate(JSON.stringify(preToolInput.tool_input), maxTextLength)}`;
+        log(logMsg);
+        // Track start time
+        if (logTiming && toolUseId) {
+            toolStartTimes.set(toolUseId, Date.now());
+        }
+        return {};
+    };
+    // PostToolUse: Log tool result
+    const postToolUse = async (input, toolUseId) => {
+        if (input.hook_event_name !== "PostToolUse")
+            return {};
+        if (!logTools)
+            return {};
+        const postToolInput = input;
+        let logMsg = `${prefix} PostToolUse: ${postToolInput.tool_name}`;
+        logMsg += `\n  Result: ${truncate(String(postToolInput.tool_response), maxTextLength)}`;
+        // Add timing if available
+        if (logTiming && toolUseId) {
+            const startTime = toolStartTimes.get(toolUseId);
+            if (startTime) {
+                const duration = Date.now() - startTime;
+                logMsg += `\n  Duration: ${duration}ms`;
+                toolStartTimes.delete(toolUseId);
+            }
+        }
+        log(logMsg);
+        return {};
+    };
+    // PostToolUseFailure: Log tool error
+    const postToolUseFailure = async (input, toolUseId) => {
+        if (input.hook_event_name !== "PostToolUseFailure")
+            return {};
+        if (!logErrors)
+            return {};
+        const failureInput = input;
+        let logMsg = `${prefix} PostToolUseFailure: ${failureInput.tool_name}`;
+        logMsg += `\n  Error: ${failureInput.error}`;
+        // Add timing if available
+        if (logTiming && toolUseId) {
+            const startTime = toolStartTimes.get(toolUseId);
+            if (startTime) {
+                const duration = Date.now() - startTime;
+                logMsg += `\n  Duration: ${duration}ms (failed)`;
+                toolStartTimes.delete(toolUseId);
+            }
+        }
+        log(logMsg);
+        return {};
+    };
+    return [preToolUse, postToolUse, postToolUseFailure];
+}
+/**
+ * Creates logging hooks for context compaction events.
+ *
+ * Provides Pre/Post logging for compaction with token savings
+ * and message count information.
+ *
+ * @param options - Configuration options
+ * @returns Array of hooks for compaction events
+ *
+ * @example
+ * ```typescript
+ * const compactLogHooks = createCompactionLoggingHooks({
+ *   prefix: "[Compaction]",
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreCompact: [compactLogHooks[0]],
+ *     PostCompact: [compactLogHooks[1]],
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createCompactionLoggingHooks(options = {}) {
+    const { log = console.log, logCompaction = true, logTiming = true, prefix = "[Agent]" } = options;
+    const compactionStartTimes = new Map();
+    // PreCompact: Log compaction start
+    const preCompact = async (input) => {
+        if (input.hook_event_name !== "PreCompact")
+            return {};
+        if (!logCompaction)
+            return {};
+        const preCompactInput = input;
+        let logMsg = `${prefix} PreCompact:`;
+        logMsg += `\n  Messages: ${preCompactInput.message_count}`;
+        logMsg += `\n  Tokens: ${preCompactInput.tokens_before}`;
+        log(logMsg);
+        // Track start time
+        if (logTiming) {
+            compactionStartTimes.set(preCompactInput.session_id, Date.now());
+        }
+        return {};
+    };
+    // PostCompact: Log compaction result
+    const postCompact = async (input) => {
+        if (input.hook_event_name !== "PostCompact")
+            return {};
+        if (!logCompaction)
+            return {};
+        const postCompactInput = input;
+        const reductionPercent = postCompactInput.tokens_before > 0
+            ? ((postCompactInput.tokens_saved / postCompactInput.tokens_before) * 100).toFixed(1)
+            : "0.0";
+        let logMsg = `${prefix} PostCompact:`;
+        logMsg += `\n  Messages: ${postCompactInput.messages_before} → ${postCompactInput.messages_after}`;
+        logMsg += `\n  Tokens: ${postCompactInput.tokens_before} → ${postCompactInput.tokens_after} (saved ${postCompactInput.tokens_saved}, ${reductionPercent}% reduction)`;
+        // Add timing if available
+        if (logTiming) {
+            const startTime = compactionStartTimes.get(postCompactInput.session_id);
+            if (startTime) {
+                const duration = Date.now() - startTime;
+                logMsg += `\n  Duration: ${duration}ms`;
+                compactionStartTimes.delete(postCompactInput.session_id);
+            }
+        }
+        log(logMsg);
+        return {};
+    };
+    return [preCompact, postCompact];
+}
+/**
+ * Creates comprehensive logging hooks for all lifecycle events.
+ *
+ * Combines generation, tool, and compaction logging into a single set of hooks.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks for all events
+ *
+ * @example
+ * ```typescript
+ * const { generationHooks, toolHooks, compactionHooks } = createComprehensiveLoggingHooks({
+ *   prefix: "[MyAgent]",
+ *   logTiming: true,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [generationHooks[0]],
+ *     PostGenerate: [generationHooks[1]],
+ *     PostGenerateFailure: [generationHooks[2]],
+ *     PreToolUse: [toolHooks[0]],
+ *     PostToolUse: [toolHooks[1]],
+ *     PostToolUseFailure: [toolHooks[2]],
+ *     PreCompact: [compactionHooks[0]],
+ *     PostCompact: [compactionHooks[1]],
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createComprehensiveLoggingHooks(options = {}) {
+    return {
+        generationHooks: createLoggingHooks(options),
+        toolHooks: createToolLoggingHooks(options),
+        compactionHooks: createCompactionLoggingHooks(options),
+    };
+}
+//# sourceMappingURL=logging.js.map

package/dist/hooks/logging.js.map

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

package/dist/hooks/parallel-guardrails.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Guardrails - Content moderation utilities for AI generation.
+ *
+ * This module provides a simple, composable approach to content moderation:
+ * - Guardrails are just async functions that return pass/block results
+ * - Multiple guardrails can race against generation
+ * - First failure aborts everything via shared AbortSignal
+ *
+ * @packageDocumentation
+ */
+import type { UIMessage } from "ai";
+/**
+ * Result from a guardrail check.
+ */
+export interface GuardrailCheckResult {
+    /** Whether the content should be blocked */
+    blocked: boolean;
+    /** Reason for blocking (if blocked) */
+    reason?: string;
+    /** IDs of messages that caused the block */
+    blockedMessageIds?: string[];
+}
+/**
+ * A guardrail is a function that checks content and returns a result.
+ *
+ * Guardrails can be sync or async. They receive the text to check and
+ * an optional AbortSignal for cancellation.
+ *
+ * @example
+ * ```typescript
+ * // Simple regex guardrail
+ * const noSecrets: Guardrail = async (text) => ({
+ *   blocked: /SECRET_API_KEY/i.test(text),
+ *   reason: "Contains sensitive pattern",
+ * });
+ *
+ * // LLM-based guardrail
+ * const llmModeration: Guardrail = async (text, signal) => {
+ *   const result = await moderateWithLLM(text, { signal });
+ *   return {
+ *     blocked: result.flagged,
+ *     reason: result.reason,
+ *   };
+ * };
+ * ```
+ */
+export type Guardrail = (text: string, signal?: AbortSignal) => Promise<GuardrailCheckResult> | GuardrailCheckResult;
+/**
+ * Options for raceGuardrails.
+ */
+export interface RaceGuardrailsOptions {
+    /** Message to show when content is blocked */
+    blockedMessage?: string;
+    /** IDs of messages to remove from client history if blocked */
+    blockedMessageIds?: string[];
+}
+/**
+ * Race multiple guardrails - first failure blocks, all run in parallel.
+ *
+ * Returns a Promise that resolves when all guardrails pass, or rejects
+ * with GeneratePermissionDeniedError if any guardrail blocks.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * // Start guardrails and generation in parallel
+ * const guardrailsPromise = raceGuardrails(
+ *   text,
+ *   [regexGuardrail, llmGuardrail],
+ *   controller.signal,
+ *   {
+ *     blockedMessage: "Content blocked",
+ *     onBlock: () => controller.abort(),
+ *   }
+ * );
+ *
+ * const generation = agent.streamRaw({
+ *   messages,
+ *   signal: controller.signal,
+ * });
+ *
+ * // Wait for guardrails to pass (or throw)
+ * await guardrailsPromise;
+ * ```
+ */
+export declare function raceGuardrails(text: string, guardrails: Guardrail[], signal?: AbortSignal, options?: RaceGuardrailsOptions): Promise<void>;
+/**
+ * Run guardrails in parallel with generation, aborting on first failure.
+ *
+ * This is a convenience wrapper that sets up the abort controller and
+ * coordinates guardrails with the generation function.
+ *
+ * @example
+ * ```typescript
+ * const result = await runWithGuardrails(
+ *   extractText(messages),
+ *   [regexGuardrail, llmGuardrail],
+ *   (signal) => agent.generate({ messages, signal })
+ * );
+ * ```
+ */
+export declare function runWithGuardrails<T>(text: string, guardrails: Guardrail[], generateFn: (signal: AbortSignal) => Promise<T>, options?: RaceGuardrailsOptions): Promise<T>;
+/**
+ * Create a regex-based guardrail.
+ *
+ * @example
+ * ```typescript
+ * const noSecrets = createRegexGuardrail([
+ *   /SECRET_API_KEY/i,
+ *   /password\s*=\s*["'][^"']+["']/i,
+ * ], "Contains sensitive data");
+ * ```
+ */
+export declare function createRegexGuardrail(patterns: RegExp[], reason?: string): Guardrail;
+/**
+ * Create a guardrail with a timeout.
+ *
+ * If the guardrail doesn't complete within the timeout, it returns
+ * a non-blocking result (fail-open behavior).
+ *
+ * @example
+ * ```typescript
+ * const timedLLMGuardrail = withTimeout(llmGuardrail, 5000);
+ * ```
+ */
+export declare function withTimeout(guardrail: Guardrail, timeoutMs: number, failOpen?: boolean): Guardrail;
+/**
+ * Extract text content from UI messages.
+ */
+export declare function extractTextFromMessages(messages: UIMessage[]): string;
+/**
+ * Find the last user message ID from a list of messages.
+ */
+export declare function findLastUserMessageId(messages: UIMessage[]): string | undefined;
+/**
+ * Configuration for buffered output guardrails.
+ */
+export interface OutputGuardrailConfig {
+    /**
+     * Guardrail to run on accumulated output.
+     * Can be a single guardrail or multiple that will be raced.
+     */
+    guardrails: Guardrail | Guardrail[];
+    /**
+     * Minimum buffer size (in characters) before running checks.
+     * Helps avoid excessive API calls for small outputs.
+     * @default 100
+     */
+    minBufferSize?: number;
+    /**
+     * Check interval in milliseconds.
+     * If set, runs periodic checks on accumulated buffer.
+     * @default undefined (only check at end)
+     */
+    checkIntervalMs?: number;
+    /**
+     * Timeout for guardrail checks in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Message to show when content is blocked.
+     * @default "Output blocked by guardrail"
+     */
+    blockedMessage?: string;
+}
+/**
+ * State of the buffered output guardrail.
+ */
+export type BufferedGuardrailState = "buffering" | "passed" | "blocked" | "error";
+/**
+ * Controller for buffered output guardrails.
+ *
+ * Buffers output content and runs guardrail checks before releasing
+ * content to the client.
+ */
+export declare class BufferedOutputGuardrail {
+    private buffer;
+    private chunks;
+    private state;
+    private blockReason;
+    private abortController;
+    private checkPromise;
+    private lastCheckTime;
+    private guardrails;
+    private config;
+    constructor(config: OutputGuardrailConfig);
+    /** Get current state of the guardrail. */
+    get currentState(): BufferedGuardrailState;
+    /** Get the block reason (if blocked). */
+    get reason(): string | null;
+    /** Get the abort signal. */
+    get signal(): AbortSignal;
+    /** Check if guardrail is still buffering. */
+    isBuffering(): boolean;
+    /** Check if guardrail has passed. */
+    hasPassed(): boolean;
+    /** Check if guardrail has blocked content. */
+    hasBlocked(): boolean;
+    /**
+     * Add content to the buffer.
+     * Returns true if content should be forwarded, false if blocked.
+     */
+    addContent(text: string): boolean;
+    /**
+     * Add a chunk to the buffer for later flushing.
+     */
+    addChunk(chunk: unknown): boolean;
+    private startCheck;
+    /**
+     * Finalize the guardrail check.
+     * Call this when output is complete to ensure final check passes.
+     */
+    finalize(): Promise<void>;
+    /** Get the buffered content. */
+    getBuffer(): string;
+    /** Get the buffered chunks. */
+    getChunks(): unknown[];
+    /** Clear the buffer and chunks. */
+    clear(): void;
+    /** Abort the guardrail. */
+    abort(): void;
+}
+/**
+ * Creates a buffered output guardrail.
+ *
+ * @example
+ * ```typescript
+ * const guardrail = createBufferedOutputGuardrail({
+ *   guardrails: [noSecretsGuardrail, noPIIGuardrail],
+ *   minBufferSize: 100,
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'text-delta') {
+ *     if (!guardrail.addContent(chunk.delta)) break;
+ *   }
+ *   guardrail.addChunk(chunk);
+ * }
+ *
+ * await guardrail.finalize();
+ * for (const chunk of guardrail.getChunks()) {
+ *   writer.write(chunk);
+ * }
+ * ```
+ */
+export declare function createBufferedOutputGuardrail(config: OutputGuardrailConfig): BufferedOutputGuardrail;
+/**
+ * Wraps a ReadableStream with buffered output guardrails.
+ *
+ * @example
+ * ```typescript
+ * const guardedStream = wrapStreamWithOutputGuardrail(sourceStream, {
+ *   guardrails: noSecretsGuardrail,
+ * });
+ *
+ * for await (const chunk of guardedStream) {
+ *   writer.write(chunk);
+ * }
+ * ```
+ */
+export declare function wrapStreamWithOutputGuardrail<T extends {
+    type?: string;
+    delta?: string;
+    text?: string;
+}>(stream: ReadableStream<T>, config: OutputGuardrailConfig): ReadableStream<T>;
+//# sourceMappingURL=parallel-guardrails.d.ts.map

package/dist/hooks/parallel-guardrails.d.ts.map

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