hybrid 1.2.5 → 1.2.7

package/README.md

@@ -1,167 +1,66 @@
-# Hybrid Agent Framework
-
-A flexible framework for building AI agents with plugin-based HTTP server extensions.
-
-## Features
-
-- **AI Agent Core**: Built on AI SDK 5 with streaming and tool support
-- **Plugin System**: Extensible HTTP server with Hono integration
-- **XMTP Integration**: Built-in XMTP messaging capabilities
-- **Blockchain Events**: Ponder integration for blockchain event handling
-- **TypeScript First**: Full type safety and modern TypeScript patterns
-
-## Quick Start
-
-```typescript
-import { Agent, XMTPPlugin, PonderPlugin } from "hybrid"
-
-// Create an agent
-const agent = new Agent({
-  name: "my-agent",
-  model: "gpt-4",
-  instructions: "You are a helpful AI assistant."
-})
-
-// Start the server with plugins
-await agent.listen({
-  port: "3000",
-  filter: async ({ message }) => {
-    console.log("Received message:", message)
-    return true // Accept all messages
-  },
-  plugins: [
-    XMTPPlugin(),
-    PonderPlugin()
-  ]
-})
-```
-
-## Plugin System
-
-The framework uses a plugin-based architecture that allows you to extend the agent's HTTP server with additional functionality.
-
-### Built-in Plugins
-
-- **XMTPPlugin**: Provides XMTP messaging capabilities
-- **PonderPlugin**: Handles blockchain events via Ponder
-
-### Creating Custom Plugins
-
-```typescript
-import type { Plugin } from "hybrid"
-import { Hono } from "hono"
-
-function MyCustomPlugin(): Plugin {
-  return {
-    name: "my-custom",
-    description: "My custom functionality",
-    apply: (app) => {
-      app.get("/custom", (c) => c.json({ message: "Hello from custom plugin!" }))
-    }
-  }
-}
-
-// Use the plugin
-const agent = new Agent({
-  name: "my-agent",
-  model: "gpt-4",
-  instructions: "You are a helpful AI assistant."
-})
-
-// Start server with plugins
-await agent.listen({
-  port: "3000",
-  plugins: [
-    XMTPPlugin(),
-    PonderPlugin(),
-    MyCustomPlugin()
-  ]
-})
-```
+# Hybrid - Typescript Framework for building commerce-connected AI Agents.
 
-### Plugin Registry
+An open-source agent framework for building conversational AI agents on XMTP. 
 
-You can also register plugins dynamically:
+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.
 
-```typescript
-// Register a plugin after agent creation
-agent.use(MyCustomPlugin())
+See [http://hybriddev.com](http://hybrid.dev) for more information.
 
-// Check registered plugins
-console.log(`Agent has ${agent.plugins.size} plugins`)
+## 📦 Quickstart
 
-// Get a specific plugin
-const plugin = agent.plugins.get("my-custom")
+Getting started with Hybrid is simple:
 
-// Check if a plugin is registered
-if (agent.plugins.has("xmtp")) {
-  console.log("XMTP plugin is registered")
-}
-```
+### 1. Initialize your project
 
-### Plugin Context
-
-Plugins receive a context object with the agent instance:
-
-```typescript
-function MyPlugin(): Plugin {
-  return {
-    name: "my-plugin",
-    description: "My plugin",
-    apply: (app, context) => {
-      if (context) {
-        console.log(`Plugin applied to agent: ${context.agent.name}`)
-      }
-      
-      app.get("/my-endpoint", (c) => c.json({ message: "Hello!" }))
-    }
-  }
-}
+```bash
+npm create hybrid my-agent
+cd my-agent
 ```
 
-## Architecture
+This creates all the necessary files and configuration for your agent.
 
-The framework consists of several core components:
+### 2. Get your OpenRouter API key
+   
+Visit [OpenRouter](https://openrouter.ai/keys), create an account and generate an API key
 
-- **Agent**: Main AI agent with streaming and tool support
-- **Plugin System**: Extensible HTTP server architecture with Hono
-- **Tool System**: AI SDK compatible tool framework
-- **Server**: Hono-based HTTP server with plugin support
+Add it to your `.env` file:
 
-### Plugin Lifecycle
+```env
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+```
 
-1. **Registration**: Plugins are registered during agent creation or via `agent.use()`
-2. **Application**: When `agent.listen()` is called, all plugins are applied to the Hono app
-3. **Execution**: Plugins can add routes, middleware, and other functionality to the app
+### 3. Generate XMTP keys
 
-## Examples
+```bash
+hybrid keys
+```
 
-See the `examples/` directory for complete usage examples:
+or automatically add it to your `.env` file:  
 
-- `plugin-usage.ts`: Comprehensive plugin usage examples
-- Basic plugin registration
-- Dynamic plugin registration
-- Custom plugin creation
-- Plugin registry inspection
-- Server startup with plugins
+```bash
+hybrid keys --write
+```
 
-## Development
+### 4. Register your wallet with XMTP
 
 ```bash
-# Install dependencies
-pnpm install
+hybrid register
+```
 
-# Build the package
-pnpm build
+This generates secure wallet and encryption keys for your XMTP agent.
 
-# Run tests
-pnpm test
+### 5. Register your wallet with XMTP
 
-# Type check
-pnpm typecheck
+```bash
+hybrid register
 ```
 
-## License
+  ### 6. Start developing
+
+```bash
+hybrid dev
+```
 
-MIT
+Your agent will start listening for XMTP messages and you're ready to build! 
 
+Go to [https://xmtp.chat/dm/](https://xmtp.chat/dm/) and send a message to your agent.

package/README.md.old

@@ -0,0 +1,167 @@
+# Hybrid Agent Framework
+
+A flexible framework for building AI agents with plugin-based HTTP server extensions.
+
+## Features
+
+- **AI Agent Core**: Built on AI SDK 5 with streaming and tool support
+- **Plugin System**: Extensible HTTP server with Hono integration
+- **XMTP Integration**: Built-in XMTP messaging capabilities
+- **Blockchain Events**: Ponder integration for blockchain event handling
+- **TypeScript First**: Full type safety and modern TypeScript patterns
+
+## Quick Start
+
+```typescript
+import { Agent, XMTPPlugin, PonderPlugin } from "hybrid"
+
+// Create an agent
+const agent = new Agent({
+  name: "my-agent",
+  model: "gpt-4",
+  instructions: "You are a helpful AI assistant."
+})
+
+// Start the server with plugins
+await agent.listen({
+  port: "3000",
+  filter: async ({ message }) => {
+    console.log("Received message:", message)
+    return true // Accept all messages
+  },
+  plugins: [
+    XMTPPlugin(),
+    PonderPlugin()
+  ]
+})
+```
+
+## Plugin System
+
+The framework uses a plugin-based architecture that allows you to extend the agent's HTTP server with additional functionality.
+
+### Built-in Plugins
+
+- **XMTPPlugin**: Provides XMTP messaging capabilities
+- **PonderPlugin**: Handles blockchain events via Ponder
+
+### Creating Custom Plugins
+
+```typescript
+import type { Plugin } from "hybrid"
+import { Hono } from "hono"
+
+function MyCustomPlugin(): Plugin {
+  return {
+    name: "my-custom",
+    description: "My custom functionality",
+    apply: (app) => {
+      app.get("/custom", (c) => c.json({ message: "Hello from custom plugin!" }))
+    }
+  }
+}
+
+// Use the plugin
+const agent = new Agent({
+  name: "my-agent",
+  model: "gpt-4",
+  instructions: "You are a helpful AI assistant."
+})
+
+// Start server with plugins
+await agent.listen({
+  port: "3000",
+  plugins: [
+    XMTPPlugin(),
+    PonderPlugin(),
+    MyCustomPlugin()
+  ]
+})
+```
+
+### Plugin Registry
+
+You can also register plugins dynamically:
+
+```typescript
+// Register a plugin after agent creation
+agent.use(MyCustomPlugin())
+
+// Check registered plugins
+console.log(`Agent has ${agent.plugins.size} plugins`)
+
+// Get a specific plugin
+const plugin = agent.plugins.get("my-custom")
+
+// Check if a plugin is registered
+if (agent.plugins.has("xmtp")) {
+  console.log("XMTP plugin is registered")
+}
+```
+
+### Plugin Context
+
+Plugins receive a context object with the agent instance:
+
+```typescript
+function MyPlugin(): Plugin {
+  return {
+    name: "my-plugin",
+    description: "My plugin",
+    apply: (app, context) => {
+      if (context) {
+        console.log(`Plugin applied to agent: ${context.agent.name}`)
+      }
+      
+      app.get("/my-endpoint", (c) => c.json({ message: "Hello!" }))
+    }
+  }
+}
+```
+
+## Architecture
+
+The framework consists of several core components:
+
+- **Agent**: Main AI agent with streaming and tool support
+- **Plugin System**: Extensible HTTP server architecture with Hono
+- **Tool System**: AI SDK compatible tool framework
+- **Server**: Hono-based HTTP server with plugin support
+
+### Plugin Lifecycle
+
+1. **Registration**: Plugins are registered during agent creation or via `agent.use()`
+2. **Application**: When `agent.listen()` is called, all plugins are applied to the Hono app
+3. **Execution**: Plugins can add routes, middleware, and other functionality to the app
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+
+- `plugin-usage.ts`: Comprehensive plugin usage examples
+- Basic plugin registration
+- Dynamic plugin registration
+- Custom plugin creation
+- Plugin registry inspection
+- Server startup with plugins
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm build
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -120,8 +120,24 @@ function generateXMTPToolsToken(payload) {
 var BG_STARTED = Symbol("BG_STARTED");
 var BG_STATE = Symbol("BG_STATE");
 var BG_STOP = Symbol("BG_STOP");
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("AbortError"));
+      return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    if (signal) {
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timeout);
+          reject(new Error("AbortError"));
+        },
+        { once: true }
+      );
+    }
+  });
 }
 function createBackgroundMessageProcessor(opts) {
   if (!opts?.agent || !opts?.xmtpClient) {
@@ -294,10 +310,18 @@ function createBackgroundMessageProcessor(opts) {
             );
           }
         }
-        await sleep(nextDelay);
+        try {
+          await sleep(nextDelay, signal);
+        } catch (error) {
+          if (error instanceof Error && error.name === "AbortError") {
+            break;
+          }
+          throw error;
+        }
       }
       try {
         if (state.listenerRunning) {
+          console.log("[XMTP Background] Stopping message listener...");
           await listener.stop();
         }
       } catch (error) {
@@ -392,11 +416,51 @@ async function listen({
   app.notFound((c) => {
     return c.json({ error: "Not found" }, 404);
   });
-  (0, import_node_server.serve)({
-    fetch: app.fetch,
-    port: Number.parseInt(port || "8454")
+  const httpPort = Number.parseInt(port || "8454");
+  const shutdown = async () => {
+    console.log("Waiting for graceful termination...");
+    try {
+      stopBackground();
+    } catch (error) {
+      console.error("Error stopping background processor:", error);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 1e3));
+  };
+  process.once("SIGINT", async () => {
+    await shutdown();
+    process.exit(0);
+  });
+  process.once("SIGTERM", async () => {
+    await shutdown();
+    process.exit(0);
+  });
+  process.on("uncaughtException", async (error) => {
+    console.error("Uncaught exception:", error);
+    await shutdown();
+    process.exit(1);
   });
-  console.log(`\u2705 XMTP Tools HTTP Server running`);
+  process.on("unhandledRejection", async (reason) => {
+    console.error("Unhandled rejection:", reason);
+    await shutdown();
+    process.exit(1);
+  });
+  try {
+    (0, import_node_server.serve)({
+      fetch: app.fetch,
+      port: httpPort
+    });
+    console.log(`\u2705 XMTP Tools HTTP Server running on port ${httpPort}`);
+  } catch (error) {
+    if (error.code === "EADDRINUSE") {
+      console.error(
+        `\u274C Port ${httpPort} is already in use. Please stop the existing server or use a different port.`
+      );
+      process.exit(1);
+    } else {
+      console.error("Server error:", error);
+      process.exit(1);
+    }
+  }
 }
 
 // src/core/plugin.ts