@hybrd/types 0.7.6 → 1.4.1

package/README.md

@@ -1,21 +1,58 @@
 # @hybrd/types
 
-Solidity + TypeScript Framework for rapid Web3 development.
+This package is part of the Hybrid monorepo.
 
-## Documentation
+Hybrid makes it easy for developers to create intelligent agents that can understand natural language, process messages, and respond through XMTP's decentralized messaging protocol.
 
-For full documentation and examples, visit [hybrid.dev](https://hybrid.dev).
+See [hybrid.dev](https://hybrid.dev) for more information.
 
-## Installation
+## 📦 Quickstart
 
-```sh
-npm install hybrid
+Getting started with Hybrid is simple:
+
+### 1. Initialize your project
+
+```bash
+npm create hybrid my-agent
+cd my-agent
+```
+
+This creates all the necessary files and configuration for your agent.
+
+### 2. Get your OpenRouter API key
+   
+Visit [OpenRouter](https://openrouter.ai/keys), create an account and generate an API key
+
+Add it to your `.env` file:
+
+```env
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+```
+
+### 3. Generate XMTP keys
+
+```bash
+hybrid keys
 ```
 
-## Community
+or automatically add it to your `.env` file:  
+
+```bash
+hybrid keys --write
+```
 
-Check out the following places for more wagmi-related content:
+### 4. Register your wallet with XMTP
+
+```bash
+hybrid register
+```
+
+This generates secure wallet and encryption keys for your XMTP agent.
+
+  ### 5. Start developing
+
+```bash
+hybrid dev
+```
 
-- Join the discussions on [Discord](https://discord.gg/AcJFXZ9Mfk)
-- Follow [@hybrid\_\_dev](https://twitter.com/hybrid__dev) on Twitter for project updates
-- Contribute or fork on [GitHub](https://github.com/hybridhq/hybrid)
+Your agent will start listening for XMTP messages and you're ready to build!

package/dist/index.cjs

@@ -0,0 +1,124 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BehaviorRegistryImpl: () => BehaviorRegistryImpl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/behavior.ts
+var BehaviorRegistryImpl = class {
+  behaviors = [];
+  /**
+   * Register a behavior with the registry
+   */
+  register(behavior) {
+    this.behaviors.push(behavior);
+  }
+  /**
+   * Register multiple behaviors at once
+   */
+  registerAll(behaviors) {
+    this.behaviors.push(...behaviors);
+  }
+  /**
+   * Get all registered behaviors
+   */
+  getAll() {
+    return [...this.behaviors];
+  }
+  /**
+   * Get behaviors that should run before the agent responds
+   */
+  getBeforeBehaviors() {
+    return this.behaviors.filter((behavior) => behavior.before);
+  }
+  /**
+   * Get behaviors that should run after the agent responds
+   */
+  getAfterBehaviors() {
+    return this.behaviors.filter((behavior) => behavior.after);
+  }
+  /**
+   * Execute all before-response behaviors as a middleware chain
+   */
+  async executeBefore(context) {
+    const behaviors = this.getBeforeBehaviors();
+    let currentIndex = 0;
+    const next = async () => {
+      if (currentIndex >= behaviors.length) {
+        return;
+      }
+      const behavior = behaviors[currentIndex];
+      if (!behavior) {
+        return;
+      }
+      currentIndex++;
+      try {
+        await behavior.before?.(context);
+      } catch (error) {
+        console.error(
+          `Error executing before behavior "${behavior.id}":`,
+          error
+        );
+      }
+    };
+    context.next = next;
+    await next();
+    context.stopped = currentIndex < behaviors.length;
+  }
+  /**
+   * Execute all after-response behaviors as a middleware chain
+   */
+  async executeAfter(context) {
+    const behaviors = this.getAfterBehaviors();
+    let currentIndex = 0;
+    const next = async () => {
+      if (currentIndex >= behaviors.length) {
+        return;
+      }
+      const behavior = behaviors[currentIndex];
+      if (!behavior) {
+        return;
+      }
+      currentIndex++;
+      try {
+        await behavior.after?.(context);
+      } catch (error) {
+        console.error(`Error executing after behavior "${behavior.id}":`, error);
+      }
+    };
+    context.next = next;
+    await next();
+    context.stopped = currentIndex < behaviors.length;
+  }
+  /**
+   * Clear all registered behaviors
+   */
+  clear() {
+    this.behaviors = [];
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BehaviorRegistryImpl
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/behavior.ts"],"sourcesContent":["// Agent types\nexport type {\n\tAgentConfig,\n\tDefaultRuntimeExtension,\n\tGenerateOptions,\n\tListenOptions,\n\tStreamOptions,\n\tToolGenerator\n} from \"./agent\"\n\nexport type { Agent, AgentMessage } from \"./agent\"\n\n// Tool types\nexport type {\n\tAnyTool,\n\tTool,\n\tToolConfig\n} from \"./tool\"\n\n// Plugin types\nexport type {\n\tPlugin,\n\tPluginContext,\n\tPluginRegistry\n} from \"./plugin\"\n\n// Runtime types\nexport type { AgentRuntime } from \"./runtime\"\n\n// XMTP types\nexport type {\n\tHonoVariables,\n\tXmtpClient,\n\tXmtpConversation,\n\tXmtpMessage,\n\tXmtpSender,\n\tXmtpSubjects\n} from \"./xmtp\"\n\n// Resolver types\nexport type { Resolver } from \"./resolver\"\n\n// Behavior types\nexport { BehaviorRegistryImpl } from \"./behavior\"\nexport type {\n\tBehavior,\n\tBehaviorConfig,\n\tBehaviorContext,\n\tBehaviorInstance,\n\tBehaviorObject,\n\tBehaviorRegistry\n} from \"./behavior\"\n","import type { AgentRuntime } from \"./runtime\"\nimport type { XmtpClient, XmtpConversation, XmtpMessage } from \"./xmtp\"\n\n/**\n * Configuration options for a behavior\n */\nexport interface BehaviorConfig {\n\t/** Whether the behavior is enabled */\n\tenabled?: boolean\n\t/** Optional configuration data for the behavior */\n\tconfig?: Record<string, unknown>\n}\n\n/**\n * Context provided to behaviors when they execute\n */\nexport interface BehaviorContext<TRuntimeExtension = Record<string, never>> {\n\t/** The base runtime context */\n\truntime: AgentRuntime & TRuntimeExtension\n\t/** The XMTP client instance */\n\tclient: XmtpClient\n\t/** The conversation the message came from */\n\tconversation: XmtpConversation\n\t/** The message that triggered the behavior */\n\tmessage: XmtpMessage\n\t/** The agent's response (available in post-response behaviors) */\n\tresponse?: string\n\t/** Send options that behaviors can modify */\n\tsendOptions?: {\n\t\t/** Whether to thread the reply to the original message */\n\t\tthreaded?: boolean\n\t\t/** Content type override */\n\t\tcontentType?: string\n\t\t/** Whether this message should be filtered out and not processed */\n\t\tfiltered?: boolean\n\t\t/** Additional metadata */\n\t\tmetadata?: Record<string, unknown>\n\t}\n\t/**\n\t * Continue to the next behavior in the middleware chain\n\t * If not called, the behavior chain stops processing\n\t */\n\tnext?: () => Promise<void>\n\t/**\n\t * Whether the middleware chain was stopped early\n\t * This gets set to true when a behavior doesn't call next()\n\t */\n\tstopped?: boolean\n}\n\n/**\n * A behavior that can be executed before or after agent responses\n */\nexport interface BehaviorObject<TRuntimeExtension = Record<string, never>> {\n\t/** Unique identifier for the behavior */\n\tid: string\n\t/** Configuration for the behavior */\n\tconfig: BehaviorConfig\n\t/**\n\t * Execute the behavior before the agent responds\n\t * @param context - The context in which to execute the behavior\n\t */\n\tbefore?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void\n\t/**\n\t * Execute the behavior after the agent responds\n\t * @param context - The context in which to execute the behavior\n\t */\n\tafter?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void\n}\n\n/**\n * Factory function to create a behavior instance\n */\nexport type Behavior<TConfig = Record<string, unknown>> = (\n\tconfig: TConfig & BehaviorConfig\n) => BehaviorObject\n\n/**\n * Pre-configured behavior instance that can be used directly\n */\nexport type BehaviorInstance = Behavior\n\n/**\n * Behavior registry for managing and executing behaviors\n */\nexport interface BehaviorRegistry {\n\t/**\n\t * Register a behavior with the registry\n\t */\n\tregister(behavior: BehaviorObject): void\n\n\t/**\n\t * Register multiple behaviors at once\n\t */\n\tregisterAll(behaviors: BehaviorObject[]): void\n\n\t/**\n\t * Get all registered behaviors\n\t */\n\tgetAll(): BehaviorObject[]\n\n\t/**\n\t * Get behaviors that should run before the agent responds\n\t */\n\tgetBeforeBehaviors(): BehaviorObject[]\n\n\t/**\n\t * Get behaviors that should run after the agent responds\n\t */\n\tgetAfterBehaviors(): BehaviorObject[]\n\n\t/**\n\t * Execute all before-response behaviors as a middleware chain\n\t */\n\texecuteBefore(context: BehaviorContext): Promise<void>\n\n\t/**\n\t * Execute all after-response behaviors as a middleware chain\n\t */\n\texecuteAfter(context: BehaviorContext): Promise<void>\n\n\t/**\n\t * Clear all registered behaviors\n\t */\n\tclear(): void\n}\n\n/**\n * Concrete implementation of the BehaviorRegistry interface\n */\nexport class BehaviorRegistryImpl implements BehaviorRegistry {\n\tprivate behaviors: BehaviorObject[] = []\n\n\t/**\n\t * Register a behavior with the registry\n\t */\n\tregister(behavior: BehaviorObject): void {\n\t\tthis.behaviors.push(behavior)\n\t}\n\n\t/**\n\t * Register multiple behaviors at once\n\t */\n\tregisterAll(behaviors: BehaviorObject[]): void {\n\t\t// Register behavior objects directly\n\t\tthis.behaviors.push(...behaviors)\n\t}\n\n\t/**\n\t * Get all registered behaviors\n\t */\n\tgetAll(): BehaviorObject[] {\n\t\treturn [...this.behaviors]\n\t}\n\n\t/**\n\t * Get behaviors that should run before the agent responds\n\t */\n\tgetBeforeBehaviors(): BehaviorObject[] {\n\t\treturn this.behaviors.filter((behavior) => behavior.before)\n\t}\n\n\t/**\n\t * Get behaviors that should run after the agent responds\n\t */\n\tgetAfterBehaviors(): BehaviorObject[] {\n\t\treturn this.behaviors.filter((behavior) => behavior.after)\n\t}\n\n\t/**\n\t * Execute all before-response behaviors as a middleware chain\n\t */\n\tasync executeBefore(context: BehaviorContext): Promise<void> {\n\t\tconst behaviors = this.getBeforeBehaviors()\n\n\t\t// Create a middleware chain\n\t\tlet currentIndex = 0\n\t\tconst next = async (): Promise<void> => {\n\t\t\tif (currentIndex >= behaviors.length) {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst behavior = behaviors[currentIndex]\n\t\t\tif (!behavior) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tcurrentIndex++\n\n\t\t\ttry {\n\t\t\t\tawait behavior.before?.(context)\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(\n\t\t\t\t\t`Error executing before behavior \"${behavior.id}\":`,\n\t\t\t\t\terror\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\n\t\t// Set the next function in the context\n\t\tcontext.next = next\n\n\t\t// Start the chain\n\t\tawait next()\n\n\t\t// Check if the chain was stopped early\n\t\tcontext.stopped = currentIndex < behaviors.length\n\t}\n\n\t/**\n\t * Execute all after-response behaviors as a middleware chain\n\t */\n\tasync executeAfter(context: BehaviorContext): Promise<void> {\n\t\tconst behaviors = this.getAfterBehaviors()\n\n\t\t// Create a middleware chain\n\t\tlet currentIndex = 0\n\t\tconst next = async (): Promise<void> => {\n\t\t\tif (currentIndex >= behaviors.length) {\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst behavior = behaviors[currentIndex]\n\t\t\tif (!behavior) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tcurrentIndex++\n\n\t\t\ttry {\n\t\t\t\tawait behavior.after?.(context)\n\t\t\t} catch (error) {\n\t\t\t\tconsole.error(`Error executing after behavior \"${behavior.id}\":`, error)\n\t\t\t}\n\t\t}\n\n\t\t// Set the next function in the context\n\t\tcontext.next = next\n\n\t\t// Start the chain\n\t\tawait next()\n\n\t\t// Check if the chain was stopped early\n\t\tcontext.stopped = currentIndex < behaviors.length\n\t}\n\n\t/**\n\t * Clear all registered behaviors\n\t */\n\tclear(): void {\n\t\tthis.behaviors = []\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACkIO,IAAM,uBAAN,MAAuD;AAAA,EACrD,YAA8B,CAAC;AAAA;AAAA;AAAA;AAAA,EAKvC,SAAS,UAAgC;AACxC,SAAK,UAAU,KAAK,QAAQ;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA,EAKA,YAAY,WAAmC;AAE9C,SAAK,UAAU,KAAK,GAAG,SAAS;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA,EAKA,SAA2B;AAC1B,WAAO,CAAC,GAAG,KAAK,SAAS;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA,EAKA,qBAAuC;AACtC,WAAO,KAAK,UAAU,OAAO,CAAC,aAAa,SAAS,MAAM;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA,EAKA,oBAAsC;AACrC,WAAO,KAAK,UAAU,OAAO,CAAC,aAAa,SAAS,KAAK;AAAA,EAC1D;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,cAAc,SAAyC;AAC5D,UAAM,YAAY,KAAK,mBAAmB;AAG1C,QAAI,eAAe;AACnB,UAAM,OAAO,YAA2B;AACvC,UAAI,gBAAgB,UAAU,QAAQ;AACrC;AAAA,MACD;AAEA,YAAM,WAAW,UAAU,YAAY;AACvC,UAAI,CAAC,UAAU;AACd;AAAA,MACD;AACA;AAEA,UAAI;AACH,cAAM,SAAS,SAAS,OAAO;AAAA,MAChC,SAAS,OAAO;AACf,gBAAQ;AAAA,UACP,oCAAoC,SAAS,EAAE;AAAA,UAC/C;AAAA,QACD;AAAA,MACD;AAAA,IACD;AAGA,YAAQ,OAAO;AAGf,UAAM,KAAK;AAGX,YAAQ,UAAU,eAAe,UAAU;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,aAAa,SAAyC;AAC3D,UAAM,YAAY,KAAK,kBAAkB;AAGzC,QAAI,eAAe;AACnB,UAAM,OAAO,YAA2B;AACvC,UAAI,gBAAgB,UAAU,QAAQ;AACrC;AAAA,MACD;AAEA,YAAM,WAAW,UAAU,YAAY;AACvC,UAAI,CAAC,UAAU;AACd;AAAA,MACD;AACA;AAEA,UAAI;AACH,cAAM,SAAS,QAAQ,OAAO;AAAA,MAC/B,SAAS,OAAO;AACf,gBAAQ,MAAM,mCAAmC,SAAS,EAAE,MAAM,KAAK;AAAA,MACxE;AAAA,IACD;AAGA,YAAQ,OAAO;AAGf,UAAM,KAAK;AAGX,YAAQ,UAAU,eAAe,UAAU;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA,EAKA,QAAc;AACb,SAAK,YAAY,CAAC;AAAA,EACnB;AACD;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,418 @@
+import { UIMessage, LanguageModel, generateText, TelemetrySettings, streamText, UIMessageStreamOnFinishCallback } from 'ai';
+import { Conversation, DecodedMessage, Client } from '@xmtp/node-sdk';
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+/**
+ * Resolver interface for address resolution
+ */
+interface Resolver {
+    resolve: (address: string) => Promise<string | null>;
+}
+
+/**
+ * @fileoverview XMTP Types
+ *
+ * Type definitions for both the XMTP core client and service client library.
+ */
+
+type HonoVariables = {
+    xmtpClient: XmtpClient;
+    resolver?: Resolver;
+};
+type XmtpClient = Client<unknown>;
+type XmtpConversation = Conversation<unknown>;
+type XmtpMessage = DecodedMessage<unknown>;
+type XmtpSender = {
+    address: string;
+    inboxId: string;
+    name: string;
+    basename?: string;
+};
+type XmtpSubjects = Record<string, `0x${string}`>;
+
+/**
+ * Base runtime that is always included in agents and tools.
+ * Additional fields can be added via generic type parameters as intersections.
+ *
+ * Example usage:
+ * - Basic: AgentRuntime (just chatId and messages)
+ * - Extended: AgentRuntime & { userId: string } (adds userId field)
+ */
+interface AgentRuntime {
+    conversation: XmtpConversation;
+    message: XmtpMessage;
+    xmtpClient: XmtpClient;
+}
+
+/**
+ * Configuration options for a behavior
+ */
+interface BehaviorConfig {
+    /** Whether the behavior is enabled */
+    enabled?: boolean;
+    /** Optional configuration data for the behavior */
+    config?: Record<string, unknown>;
+}
+/**
+ * Context provided to behaviors when they execute
+ */
+interface BehaviorContext<TRuntimeExtension = Record<string, never>> {
+    /** The base runtime context */
+    runtime: AgentRuntime & TRuntimeExtension;
+    /** The XMTP client instance */
+    client: XmtpClient;
+    /** The conversation the message came from */
+    conversation: XmtpConversation;
+    /** The message that triggered the behavior */
+    message: XmtpMessage;
+    /** The agent's response (available in post-response behaviors) */
+    response?: string;
+    /** Send options that behaviors can modify */
+    sendOptions?: {
+        /** Whether to thread the reply to the original message */
+        threaded?: boolean;
+        /** Content type override */
+        contentType?: string;
+        /** Whether this message should be filtered out and not processed */
+        filtered?: boolean;
+        /** Additional metadata */
+        metadata?: Record<string, unknown>;
+    };
+    /**
+     * Continue to the next behavior in the middleware chain
+     * If not called, the behavior chain stops processing
+     */
+    next?: () => Promise<void>;
+    /**
+     * Whether the middleware chain was stopped early
+     * This gets set to true when a behavior doesn't call next()
+     */
+    stopped?: boolean;
+}
+/**
+ * A behavior that can be executed before or after agent responses
+ */
+interface BehaviorObject<TRuntimeExtension = Record<string, never>> {
+    /** Unique identifier for the behavior */
+    id: string;
+    /** Configuration for the behavior */
+    config: BehaviorConfig;
+    /**
+     * Execute the behavior before the agent responds
+     * @param context - The context in which to execute the behavior
+     */
+    before?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void;
+    /**
+     * Execute the behavior after the agent responds
+     * @param context - The context in which to execute the behavior
+     */
+    after?(context: BehaviorContext<TRuntimeExtension>): Promise<void> | void;
+}
+/**
+ * Factory function to create a behavior instance
+ */
+type Behavior<TConfig = Record<string, unknown>> = (config: TConfig & BehaviorConfig) => BehaviorObject;
+/**
+ * Pre-configured behavior instance that can be used directly
+ */
+type BehaviorInstance = Behavior;
+/**
+ * Behavior registry for managing and executing behaviors
+ */
+interface BehaviorRegistry {
+    /**
+     * Register a behavior with the registry
+     */
+    register(behavior: BehaviorObject): void;
+    /**
+     * Register multiple behaviors at once
+     */
+    registerAll(behaviors: BehaviorObject[]): void;
+    /**
+     * Get all registered behaviors
+     */
+    getAll(): BehaviorObject[];
+    /**
+     * Get behaviors that should run before the agent responds
+     */
+    getBeforeBehaviors(): BehaviorObject[];
+    /**
+     * Get behaviors that should run after the agent responds
+     */
+    getAfterBehaviors(): BehaviorObject[];
+    /**
+     * Execute all before-response behaviors as a middleware chain
+     */
+    executeBefore(context: BehaviorContext): Promise<void>;
+    /**
+     * Execute all after-response behaviors as a middleware chain
+     */
+    executeAfter(context: BehaviorContext): Promise<void>;
+    /**
+     * Clear all registered behaviors
+     */
+    clear(): void;
+}
+/**
+ * Concrete implementation of the BehaviorRegistry interface
+ */
+declare class BehaviorRegistryImpl implements BehaviorRegistry {
+    private behaviors;
+    /**
+     * Register a behavior with the registry
+     */
+    register(behavior: BehaviorObject): void;
+    /**
+     * Register multiple behaviors at once
+     */
+    registerAll(behaviors: BehaviorObject[]): void;
+    /**
+     * Get all registered behaviors
+     */
+    getAll(): BehaviorObject[];
+    /**
+     * Get behaviors that should run before the agent responds
+     */
+    getBeforeBehaviors(): BehaviorObject[];
+    /**
+     * Get behaviors that should run after the agent responds
+     */
+    getAfterBehaviors(): BehaviorObject[];
+    /**
+     * Execute all before-response behaviors as a middleware chain
+     */
+    executeBefore(context: BehaviorContext): Promise<void>;
+    /**
+     * Execute all after-response behaviors as a middleware chain
+     */
+    executeAfter(context: BehaviorContext): Promise<void>;
+    /**
+     * Clear all registered behaviors
+     */
+    clear(): void;
+}
+
+/**
+ * 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.
+ */
+interface PluginRegistry<TContext = unknown> {
+    register: (plugin: Plugin<TContext>) => void;
+    applyAll: (app: Hono<{
+        Variables: HonoVariables;
+    }>, context: TContext) => Promise<void>;
+}
+interface PluginContext {
+    agent: Agent;
+    behaviors?: BehaviorRegistry;
+}
+
+/**
+ * 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> {
+    /** 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> {
+    /** 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>>;
+}
+type AnyTool<TRuntimeExtension = DefaultRuntimeExtension> = Tool<any, any, TRuntimeExtension>;
+
+type AgentMessage = UIMessage;
+interface Agent<TRuntimeExtension = Record<string, never>, TPluginContext = unknown> {
+    /** Agent's unique identifier */
+    readonly name: string;
+    /** Plugin registry for extending the agent's HTTP server */
+    readonly plugins: PluginRegistry<TPluginContext>;
+    /**
+     * 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: AgentMessage[], options: GenerateOptions<TRuntimeExtension>): Promise<Awaited<ReturnType<typeof generateText>>>;
+    /**
+     * 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: AgentMessage[], options: StreamOptions<TRuntimeExtension>): Promise<Response>;
+    /**
+     * Gets the agent's configuration for debugging and inspection.
+     * @returns Object containing agent configuration details
+     */
+    getConfig(): {
+        name: string;
+        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?: AgentMessage[];
+    }): Promise<string | undefined>;
+    /**
+     * 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?: AgentMessage[];
+    }): Promise<Record<string, AnyTool<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
+     */
+    createRuntimeContext(baseRuntime: AgentRuntime): Promise<AgentRuntime & TRuntimeExtension>;
+    /**
+     * Registers a plugin with the agent
+     * @param plugin - The plugin to register
+     */
+    use(plugin: Plugin<TPluginContext>): 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>;
+}
+type DefaultRuntimeExtension = Record<string, never>;
+type ToolGenerator<TRuntimeExtension = DefaultRuntimeExtension> = (props: {
+    runtime: AgentRuntime & TRuntimeExtension;
+    messages: AgentMessage[];
+}) => Record<string, AnyTool<TRuntimeExtension>> | Promise<Record<string, AnyTool<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, AnyTool<TRuntimeExtension>> | ToolGenerator<TRuntimeExtension>;
+    /** Instructions for the agent, can be static or dynamically resolved */
+    instructions: string | ((props: {
+        messages: AgentMessage[];
+        runtime: AgentRuntime & TRuntimeExtension;
+    }) => string | Promise<string>);
+    /** Function to create the runtime extension, type will be inferred */
+    createRuntime?: (runtime: AgentRuntime) => TRuntimeExtension | Promise<TRuntimeExtension>;
+    /** 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>;
+}
+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<AgentMessage>;
+}
+/**
+ * Options for starting the agent listener
+ * @property agent - The agent instance to use
+ * @property port - The port number to listen on (defaults to 8454)
+ * @property plugins - Optional array of plugins to apply to the server
+ * @property behaviors - Optional array of behaviors to apply to message processing
+ */
+interface ListenOptions {
+    agent: Agent<unknown, unknown>;
+    port: string;
+    plugins?: Plugin<unknown>[];
+    behaviors?: BehaviorObject[];
+}
+
+export { type Agent, type AgentConfig, type AgentMessage, type AgentRuntime, type AnyTool, type Behavior, type BehaviorConfig, type BehaviorContext, type BehaviorInstance, type BehaviorObject, type BehaviorRegistry, BehaviorRegistryImpl, type DefaultRuntimeExtension, type GenerateOptions, type HonoVariables, type ListenOptions, type Plugin, type PluginContext, type PluginRegistry, type Resolver, type StreamOptions, type Tool, type ToolConfig, type ToolGenerator, type XmtpClient, type XmtpConversation, type XmtpMessage, type XmtpSender, type XmtpSubjects };