hybrid 1.1.0 → 1.2.0

package/README.md

@@ -13,7 +13,7 @@ A flexible framework for building AI agents with plugin-based HTTP server extens
 ## Quick Start
 
 ```typescript
-import { Agent, XMTPPlugin, PonderPlugin } from "@hybrd/hybrid"
+import { Agent, XMTPPlugin, PonderPlugin } from "hybrid"
 
 // Create an agent
 const agent = new Agent({
@@ -48,7 +48,7 @@ The framework uses a plugin-based architecture that allows you to extend the age
 ### Creating Custom Plugins
 
 ```typescript
-import type { Plugin } from "@hybrd/hybrid"
+import type { Plugin } from "hybrid"
 import { Hono } from "hono"
 
 function MyCustomPlugin(): Plugin {

package/dist/agent-BxbcW5UC.d.cts

@@ -0,0 +1,401 @@
+import * as ai from 'ai';
+import { UIMessage, LanguageModel, generateText, TelemetrySettings, streamText, UIMessageStreamOnFinishCallback } from 'ai';
+import { z } from 'zod';
+import { HonoVariables, MessageListenerConfig, XmtpConversation, XmtpMessage, XmtpSender, XmtpSubjects, XmtpServiceClient } from '@hybrd/xmtp';
+import { Hono } from 'hono';
+
+/**
+ * Plugin interface for extending the agent's Hono app
+ *
+ * @description
+ * Plugins allow you to extend the agent's HTTP server with additional
+ * routes, middleware, and functionality. Each plugin receives the Hono
+ * app instance and can modify it as needed.
+ *
+ * @template T - Optional context type that can be passed to the plugin
+ */
+interface Plugin<T = Record<string, never>> {
+    /**
+     * Unique identifier for the plugin
+     */
+    name: string;
+    /**
+     * Optional description of what the plugin does
+     */
+    description?: string;
+    /**
+     * Function that applies the plugin to the Hono app
+     *
+     * @param app - The Hono app instance to extend
+     * @param context - Optional context data passed to the plugin
+     */
+    apply: (app: Hono<{
+        Variables: HonoVariables;
+    }>, context?: T) => void | Promise<void>;
+}
+/**
+ * Plugin registry that manages all registered plugins
+ *
+ * @description
+ * The plugin registry allows you to register, configure, and apply
+ * plugins to Hono apps. It provides a centralized way to manage
+ * plugin dependencies and execution order.
+ */
+declare class PluginRegistry<T = Record<string, never>> {
+    private plugins;
+    /**
+     * Registers a plugin with the registry
+     *
+     * @param plugin - The plugin to register
+     * @throws {Error} If a plugin with the same name is already registered
+     */
+    register(plugin: Plugin<T>): void;
+    /**
+     * Unregisters a plugin from the registry
+     *
+     * @param name - The name of the plugin to unregister
+     * @returns True if the plugin was unregistered, false if it wasn't found
+     */
+    unregister(name: string): boolean;
+    /**
+     * Gets a plugin by name
+     *
+     * @param name - The name of the plugin to retrieve
+     * @returns The plugin if found, undefined otherwise
+     */
+    get(name: string): Plugin<T> | undefined;
+    /**
+     * Gets all registered plugins
+     *
+     * @returns Array of all registered plugins
+     */
+    getAll(): Plugin<T>[];
+    /**
+     * Checks if a plugin is registered
+     *
+     * @param name - The name of the plugin to check
+     * @returns True if the plugin is registered, false otherwise
+     */
+    has(name: string): boolean;
+    /**
+     * Applies all registered plugins to a Hono app
+     *
+     * @param app - The Hono app instance to extend
+     * @param context - Optional context data passed to all plugins
+     */
+    applyAll(app: Hono<{
+        Variables: HonoVariables;
+    }>, context?: T): Promise<void>;
+    /**
+     * Clears all registered plugins
+     */
+    clear(): void;
+    /**
+     * Gets the number of registered plugins
+     */
+    get size(): number;
+}
+
+/**
+ * Context type for plugins that need agent information
+ */
+interface PluginContext {
+    agent: Agent<DefaultRuntimeExtension>;
+}
+/**
+ * Options for starting the XMTP tools HTTP server
+ *
+ * @description
+ * Configuration object for the standalone XMTP tools server that provides
+ * basic HTTP endpoints for health checks and XMTP operations.
+ *
+ * @property agent - The agent instance to associate with the server
+ * @property port - The port number to listen on (defaults to 8454)
+ * @property filter - Optional message filter for XMTP messages
+ * @property plugins - Optional array of plugins to apply to the server
+ */
+type ListenOptions = {
+    agent: Agent;
+    port: string;
+    filter?: MessageListenerConfig["filter"];
+    plugins?: Plugin<PluginContext>[];
+};
+/**
+ * Starts a standalone XMTP tools HTTP server
+ *
+ * @description
+ * This function creates and starts a minimal HTTP server specifically for
+ * XMTP tools operations. It includes:
+ * - Health check endpoint at `/health`
+ * - 404 handler for unmatched routes
+ * - Automatic port parsing from string input
+ * - Plugin-based route mounting
+ *
+ * The server runs independently and is useful for scenarios where you need
+ * XMTP tools functionality without the full Hono app integration.
+ *
+ * @param options - Configuration options for the server
+ * @param options.agent - The agent instance to associate with the server
+ * @param options.port - The port number to listen on (parsed as integer)
+ *
+ * @example
+ * ```typescript
+ * listen({
+ *   agent: myAgent,
+ *   port: "3000"
+ * })
+ *
+ * // Server starts on port 3000 with health endpoint at /health
+ * // and all registered plugins applied
+ * ```
+ */
+declare function listen({ agent, port, filter, plugins }: ListenOptions): Promise<void>;
+
+interface BaseRuntime extends Record<string, unknown> {
+    conversation: XmtpConversation;
+    message: XmtpMessage;
+    parentMessage?: XmtpMessage;
+    rootMessage: XmtpMessage;
+    sender: XmtpSender;
+    subjects: XmtpSubjects;
+    xmtpClient: XmtpServiceClient;
+}
+type AgentRuntime = BaseRuntime & {
+    chatId?: string;
+    messages: Array<UIMessage>;
+};
+interface XmtpCredentials {
+    inboxId: string;
+    xmtpServiceUrl: string;
+    xmtpServiceToken: string;
+}
+
+type DefaultRuntimeExtension$1 = Record<string, never>;
+/**
+ * Configuration interface for creating custom tools that integrate with AI SDK.
+ */
+interface ToolConfig<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny, TRuntimeExtension = DefaultRuntimeExtension$1> {
+    /** Unique identifier for the tool */
+    id: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** Zod schema for validating tool input */
+    inputSchema: TInput;
+    /** Optional Zod schema for validating tool output */
+    outputSchema?: TOutput;
+    /** Function that executes the tool's logic */
+    execute: (args: {
+        input: z.infer<TInput>;
+        runtime: AgentRuntime & TRuntimeExtension;
+        messages: UIMessage[];
+    }) => Promise<z.infer<TOutput>>;
+}
+/**
+ * Internal tool interface used throughout the agent framework.
+ * Similar to ToolConfig but without the ID field, used after tool creation.
+ */
+interface Tool<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny, TRuntimeExtension = DefaultRuntimeExtension$1> {
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** Zod schema for validating tool input */
+    inputSchema: TInput;
+    /** Optional Zod schema for validating tool output */
+    outputSchema?: TOutput;
+    /** Function that executes the tool's logic */
+    execute: (args: {
+        input: z.infer<TInput>;
+        runtime: AgentRuntime & TRuntimeExtension;
+        messages: UIMessage[];
+    }) => Promise<z.infer<TOutput>>;
+}
+/**
+ * Factory function to create tools with custom runtime extensions.
+ * Provides proper type inference for input/output schemas and runtime extensions.
+ */
+declare function toolFactory<TRuntimeExtension = DefaultRuntimeExtension$1>(): <TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny>(config: ToolConfig<TInput, TOutput, TRuntimeExtension>) => Tool<TInput, TOutput, TRuntimeExtension>;
+/**
+ * Default tool factory with no runtime extensions.
+ * Type-safe at creation time with proper schema inference.
+ */
+declare const createTool: <TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny>(config: ToolConfig<TInput, TOutput, DefaultRuntimeExtension$1>) => Tool<TInput, TOutput, DefaultRuntimeExtension$1>;
+
+type DefaultRuntimeExtension = Record<string, never>;
+/**
+ * Tool that can be used in Agent configuration.
+ * Extends the base Tool type with runtime extension support.
+ */
+type AgentTool<TRuntimeExtension = DefaultRuntimeExtension> = Tool<z.ZodTypeAny, z.ZodTypeAny, TRuntimeExtension>;
+/**
+ * Function that generates tools dynamically based on messages and runtime context.
+ * Allows for context-aware tool selection and configuration.
+ */
+type ToolGenerator<TRuntimeExtension = DefaultRuntimeExtension> = (props: {
+    messages: UIMessage[];
+    runtime: AgentRuntime & TRuntimeExtension;
+}) => Record<string, AgentTool<TRuntimeExtension>> | Promise<Record<string, AgentTool<TRuntimeExtension>>>;
+/**
+ * Configuration interface for creating an Agent instance.
+ * Supports both static and dynamic configuration through functions.
+ */
+interface AgentConfig<TRuntimeExtension = DefaultRuntimeExtension> {
+    /** Unique identifier for the agent */
+    name: string;
+    /** Language model to use, can be static or dynamically resolved */
+    model: LanguageModel | ((props: {
+        runtime: AgentRuntime & TRuntimeExtension;
+    }) => LanguageModel | Promise<LanguageModel>);
+    /** Tools available to the agent, can be static or dynamically generated */
+    tools?: Record<string, AgentTool<TRuntimeExtension>> | ToolGenerator<TRuntimeExtension>;
+    /** Instructions for the agent, can be static or dynamically resolved */
+    instructions: string | ((props: {
+        messages: UIMessage[];
+        runtime: AgentRuntime & TRuntimeExtension;
+    }) => string | Promise<string>);
+    /** Function to create the runtime extension, type will be inferred */
+    createRuntime?: (runtime: AgentRuntime) => TRuntimeExtension | Promise<TRuntimeExtension>;
+    /** Optional metadata for the agent */
+    metadata?: Record<string, unknown>;
+    /** Maximum number of steps the agent can take */
+    maxSteps?: number;
+    /** Maximum tokens for generation */
+    maxTokens?: number;
+    /** Temperature for generation (0.0 to 2.0) */
+    temperature?: number;
+}
+/**
+ * Options for text generation with the agent.
+ * Extends AI SDK parameters while adding agent-specific options.
+ */
+interface GenerateOptions<TRuntimeExtension = DefaultRuntimeExtension> extends Omit<Parameters<typeof generateText>[0], "model" | "tools" | "instructions" | "onFinish"> {
+    /** Maximum tokens for generation */
+    maxTokens?: number;
+    /** Runtime context for the agent */
+    runtime: AgentRuntime & TRuntimeExtension;
+    /** Optional telemetry configuration */
+    telemetry?: NonNullable<TelemetrySettings>;
+}
+/**
+ * Options for streaming text with the agent.
+ * Extends AI SDK parameters while adding agent-specific options.
+ */
+interface StreamOptions<TRuntimeExtension = DefaultRuntimeExtension> extends Omit<Parameters<typeof streamText>[0], "model" | "tools" | "instructions" | "onFinish"> {
+    /** Maximum tokens for generation */
+    maxTokens?: number;
+    /** Runtime context for the agent */
+    runtime: AgentRuntime & TRuntimeExtension;
+    /** Optional telemetry configuration */
+    telemetry?: NonNullable<TelemetrySettings>;
+    /** Callback when streaming finishes */
+    onFinish?: UIMessageStreamOnFinishCallback<UIMessage>;
+}
+/**
+ * Core Agent implementation using AI SDK 5 directly.
+ * This class provides a flexible interface for creating AI agents with
+ * dynamic configuration, tool support, and streaming capabilities.
+ */
+declare class Agent<TRuntimeExtension = DefaultRuntimeExtension> {
+    /** Agent's unique identifier */
+    readonly name: string;
+    /** Optional description of the agent */
+    readonly description?: string;
+    /** Optional metadata associated with the agent */
+    readonly metadata?: Record<string, unknown>;
+    /** Agent configuration */
+    private readonly config;
+    /** Default parameters for text generation */
+    private readonly generationDefaults;
+    /** Default parameters for text streaming */
+    private readonly streamDefaults;
+    /** Plugin registry for extending the agent's HTTP server */
+    readonly plugins: PluginRegistry<PluginContext>;
+    /**
+     * Creates a new Agent instance with the specified configuration.
+     * @param config - Configuration object for the agent
+     */
+    constructor(config: AgentConfig<TRuntimeExtension>);
+    /**
+     * Resolves dynamic configuration properties (model, tools, instructions) with runtime context.
+     * @param messages - Current conversation messages
+     * @param runtime - Runtime context for the agent
+     * @returns Resolved configuration with model, tools, and instructions
+     */
+    private resolveConfig;
+    /**
+     * Prepares messages by adding system instructions if provided.
+     * Merges instructions with existing system messages or creates new ones.
+     * @param messages - Current conversation messages
+     * @param instructions - System instructions to add
+     * @returns Messages with system instructions properly integrated
+     */
+    private prepareMessages;
+    /**
+     * Generates a text completion using the agent's configuration.
+     * @param messages - Conversation messages to generate from
+     * @param options - Generation options including runtime context
+     * @returns Generated text completion result
+     */
+    generate(messages: UIMessage[], options: GenerateOptions<TRuntimeExtension>): Promise<ai.GenerateTextResult<Record<string, ai.Tool>, unknown>>;
+    /**
+     * Streams a text completion using the agent's configuration.
+     * @param messages - Conversation messages to generate from
+     * @param options - Streaming options including runtime context
+     * @returns Streaming response that can be consumed
+     */
+    stream(messages: UIMessage[], options: StreamOptions<TRuntimeExtension>): Promise<Response>;
+    /**
+     * Gets the agent's configuration for debugging and inspection.
+     * @returns Object containing agent configuration details
+     */
+    getConfig(): {
+        name: string;
+        description: string | undefined;
+        metadata: Record<string, unknown> | undefined;
+        hasModel: boolean;
+        hasTools: boolean;
+        hasInstructions: boolean;
+    };
+    /**
+     * Gets the agent's instructions without running generation.
+     * Useful for external integrations that need instructions separately.
+     * @param options - Options containing runtime context and optional messages
+     * @returns Resolved instructions string
+     */
+    getInstructions(options: {
+        runtime: AgentRuntime & TRuntimeExtension;
+        messages?: UIMessage[];
+    }): Promise<string>;
+    /**
+     * Gets the agent's tools without running generation.
+     * Useful for external integrations that need tools separately.
+     * @param options - Options containing runtime context and optional messages
+     * @returns Resolved tools object
+     */
+    getTools(options: {
+        runtime: AgentRuntime & TRuntimeExtension;
+        messages?: UIMessage[];
+    }): Promise<Record<string, AgentTool<TRuntimeExtension>> | undefined>;
+    /**
+     * Creates the complete runtime context by merging base runtime with custom extension.
+     * @param baseRuntime - The base runtime context containing XMTP properties
+     * @returns Complete runtime context with custom extensions applied
+     */
+    /**
+     * Creates the complete runtime context by merging base runtime with custom extension.
+     * @param baseRuntime - The base runtime context containing XMTP properties
+     * @returns Complete runtime context with custom extensions applied
+     */
+    createRuntimeContext(baseRuntime: AgentRuntime): Promise<AgentRuntime & TRuntimeExtension>;
+    /**
+     * Registers a plugin with the agent
+     *
+     * @param plugin - The plugin to register
+     */
+    use(plugin: Plugin<PluginContext>): void;
+    /**
+     * Starts listening for messages and events using the agent instance.
+     * @param opts - Configuration options for the listener, excluding the agent property
+     */
+    listen(opts: Omit<ListenOptions, "agent">): Promise<void>;
+}
+
+export { Agent as A, type BaseRuntime as B, type DefaultRuntimeExtension as D, type ListenOptions as L, PluginRegistry as P, type Tool as T, type XmtpCredentials as X, type AgentConfig as a, type Plugin as b, createTool as c, type ToolConfig as d, type AgentRuntime as e, type PluginContext as f, listen as l, toolFactory as t };