hono-agents 0.0.0 → 0.0.5

package/README.md

@@ -0,0 +1,104 @@
+# hono-agents
+
+🔥 Hono ⨉ 🧠 Cloudflare Agents
+
+Add intelligent, stateful AI agents to your Hono app. Create persistent AI agents that can think, communicate, and evolve over time, all integrated seamlessly with your Hono application.
+
+## Installation
+
+```bash
+npm install hono-agents hono agents-sdk
+```
+
+## Usage
+
+```ts
+import { Hono } from "hono";
+import { agentsMiddleware } from "hono-agents";
+import { Agent } from "agents-sdk";
+
+// Define your agent classes
+export class ChatAgent extends Agent {
+  async onRequest(request) {
+    return new Response("Ready to assist with chat.");
+  }
+}
+
+export class AssistantAgent extends Agent {
+  async onRequest(request) {
+    return new Response("I'm your AI assistant.");
+  }
+}
+
+// Basic setup
+const app = new Hono();
+app.use("*", agentsMiddleware());
+
+// or with authentication
+app.use(
+  "*",
+  agentsMiddleware({
+    options: {
+      onBeforeConnect: async (req) => {
+        const token = req.headers.get("authorization");
+        // validate token
+        if (!token) return new Response("Unauthorized", { status: 401 });
+      },
+    },
+  })
+);
+
+// With error handling
+app.use("*", agentsMiddleware({ onError: (error) => console.error(error) }));
+
+// With custom routing
+app.use(
+  "*",
+  agentsMiddleware({
+    options: {
+      prefix: "/agents", // Handles /agents/* routes only
+    },
+  })
+);
+
+export default app;
+```
+
+## Configuration
+
+To properly configure your Cloudflare Workers project to use agents, update your `wrangler.toml` file:
+
+```toml
+[durable_objects]
+bindings = [
+  { name = "ChatAgent", class_name = "ChatAgent" },
+  { name = "AssistantAgent", class_name = "AssistantAgent" }
+]
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["ChatAgent", "AssistantAgent"]
+```
+
+## How It Works
+
+The `agentsMiddleware` function:
+
+1. Detects whether the incoming request is a WebSocket connection or standard HTTP request
+2. Routes the request to the appropriate agent
+3. Handles WebSocket upgrades for persistent connections
+4. Provides error handling and custom routing options
+
+Agents can:
+
+- Maintain state across requests
+- Handle both HTTP and WebSocket connections
+- Schedule tasks for future execution
+- Communicate with AI services
+- Integrate seamlessly with React applications
+
+## License
+
+Learn more about Cloudflare Agents at https://www.npmjs.com/package/agents-sdk
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import * as hono from "hono";
+import { Env } from "hono";
+import { AgentOptions } from "agents-sdk";
+
+/**
+ * Configuration options for the Cloudflare Agents middleware
+ */
+type AgentMiddlewareContext<E extends Env> = {
+  /** Cloudflare Agents-specific configuration options */
+  options?: AgentOptions<E>;
+  /** Optional error handler for caught errors */
+  onError?: (error: Error) => void;
+};
+/**
+ * Creates a middleware for handling Cloudflare Agents WebSocket and HTTP requests
+ * Processes both WebSocket upgrades and standard HTTP requests, delegating them to Cloudflare Agents
+ */
+declare function agentsMiddleware<E extends Env = Env>(
+  ctx?: AgentMiddlewareContext<E>
+): hono.MiddlewareHandler<any, string, {}>;
+
+export { agentsMiddleware };

package/dist/index.js

@@ -0,0 +1,48 @@
+// src/index.ts
+import { env } from "hono/adapter";
+import { createMiddleware } from "hono/factory";
+import { routeAgentRequest } from "agents-sdk";
+function agentsMiddleware(ctx) {
+  return createMiddleware(async (c, next) => {
+    try {
+      const handler = isWebSocketUpgrade(c) ? handleWebSocketUpgrade : handleHttpRequest;
+      const response = await handler(c, ctx?.options);
+      return response === null ? await next() : response;
+    } catch (error) {
+      if (ctx?.onError) {
+        ctx.onError(error);
+        return next();
+      }
+      throw error;
+    }
+  });
+}
+function isWebSocketUpgrade(c) {
+  return c.req.header("upgrade")?.toLowerCase() === "websocket";
+}
+function createRequestFromContext(c) {
+  return new Request(c.req.url, {
+    method: c.req.method,
+    headers: c.req.header(),
+    body: c.req.raw.body
+  });
+}
+async function handleWebSocketUpgrade(c, options) {
+  const req = createRequestFromContext(c);
+  const response = await routeAgentRequest(req, env(c), options);
+  if (!response?.webSocket) {
+    return null;
+  }
+  return new Response(null, {
+    status: 101,
+    webSocket: response.webSocket
+  });
+}
+async function handleHttpRequest(c, options) {
+  const req = createRequestFromContext(c);
+  return routeAgentRequest(req, env(c), options);
+}
+export {
+  agentsMiddleware
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { env } from \"hono/adapter\";\nimport { createMiddleware } from \"hono/factory\";\nimport { routeAgentRequest } from \"agents-sdk\";\n\nimport type { Context, Env } from \"hono\";\nimport type { AgentOptions } from \"agents-sdk\";\n\n/**\n * Configuration options for the Cloudflare Agents middleware\n */\ntype AgentMiddlewareContext<E extends Env> = {\n  /** Cloudflare Agents-specific configuration options */\n  options?: AgentOptions<E>;\n  /** Optional error handler for caught errors */\n  onError?: (error: Error) => void;\n};\n\n/**\n * Creates a middleware for handling Cloudflare Agents WebSocket and HTTP requests\n * Processes both WebSocket upgrades and standard HTTP requests, delegating them to Cloudflare Agents\n */\nexport function agentsMiddleware<E extends Env = Env>(\n  ctx?: AgentMiddlewareContext<E>\n) {\n  return createMiddleware(async (c, next) => {\n    try {\n      const handler = isWebSocketUpgrade(c)\n        ? handleWebSocketUpgrade\n        : handleHttpRequest;\n      const response = await handler(c, ctx?.options);\n\n      return response === null ? await next() : response;\n    } catch (error) {\n      if (ctx?.onError) {\n        ctx.onError(error as Error);\n        return next();\n      }\n      throw error;\n    }\n  });\n}\n\n/**\n * Checks if the incoming request is a WebSocket upgrade request\n * Looks for the 'upgrade' header with a value of 'websocket' (case-insensitive)\n */\nfunction isWebSocketUpgrade(c: Context): boolean {\n  return c.req.header(\"upgrade\")?.toLowerCase() === \"websocket\";\n}\n\n/**\n * Creates a new Request object from the Hono context\n * Preserves the original request's URL, method, headers, and body\n */\nfunction createRequestFromContext(c: Context) {\n  return new Request(c.req.url, {\n    method: c.req.method,\n    headers: c.req.header(),\n    body: c.req.raw.body,\n  });\n}\n\n/**\n * Handles WebSocket upgrade requests\n * Returns a WebSocket upgrade response if successful, null otherwise\n */\nasync function handleWebSocketUpgrade<E extends Env>(\n  c: Context<E>,\n  options?: AgentOptions<E>\n) {\n  const req = createRequestFromContext(c);\n  const response = await routeAgentRequest(req, env(c), options);\n\n  if (!response?.webSocket) {\n    return null;\n  }\n\n  return new Response(null, {\n    status: 101,\n    webSocket: response.webSocket,\n  });\n}\n\n/**\n * Handles standard HTTP requests\n * Forwards the request to Cloudflare Agents and returns the response\n */\nasync function handleHttpRequest<E extends Env>(\n  c: Context<E>,\n  options?: AgentOptions<E>\n) {\n  const req = createRequestFromContext(c);\n  return routeAgentRequest(req, env(c), options);\n}\n"],"mappings":";AAAA,SAAS,WAAW;AACpB,SAAS,wBAAwB;AACjC,SAAS,yBAAyB;AAmB3B,SAAS,iBACd,KACA;AACA,SAAO,iBAAiB,OAAO,GAAG,SAAS;AACzC,QAAI;AACF,YAAM,UAAU,mBAAmB,CAAC,IAChC,yBACA;AACJ,YAAM,WAAW,MAAM,QAAQ,GAAG,KAAK,OAAO;AAE9C,aAAO,aAAa,OAAO,MAAM,KAAK,IAAI;AAAA,IAC5C,SAAS,OAAO;AACd,UAAI,KAAK,SAAS;AAChB,YAAI,QAAQ,KAAc;AAC1B,eAAO,KAAK;AAAA,MACd;AACA,YAAM;AAAA,IACR;AAAA,EACF,CAAC;AACH;AAMA,SAAS,mBAAmB,GAAqB;AAC/C,SAAO,EAAE,IAAI,OAAO,SAAS,GAAG,YAAY,MAAM;AACpD;AAMA,SAAS,yBAAyB,GAAY;AAC5C,SAAO,IAAI,QAAQ,EAAE,IAAI,KAAK;AAAA,IAC5B,QAAQ,EAAE,IAAI;AAAA,IACd,SAAS,EAAE,IAAI,OAAO;AAAA,IACtB,MAAM,EAAE,IAAI,IAAI;AAAA,EAClB,CAAC;AACH;AAMA,eAAe,uBACb,GACA,SACA;AACA,QAAM,MAAM,yBAAyB,CAAC;AACtC,QAAM,WAAW,MAAM,kBAAkB,KAAK,IAAI,CAAC,GAAG,OAAO;AAE7D,MAAI,CAAC,UAAU,WAAW;AACxB,WAAO;AAAA,EACT;AAEA,SAAO,IAAI,SAAS,MAAM;AAAA,IACxB,QAAQ;AAAA,IACR,WAAW,SAAS;AAAA,EACtB,CAAC;AACH;AAMA,eAAe,kBACb,GACA,SACA;AACA,QAAM,MAAM,yBAAyB,CAAC;AACtC,SAAO,kBAAkB,KAAK,IAAI,CAAC,GAAG,OAAO;AAC/C;","names":[]}

package/package.json

@@ -1,12 +1,37 @@
 {
   "name": "hono-agents",
-  "version": "0.0.0",
-  "main": "index.js",
+  "version": "0.0.5",
+  "main": "src/index.ts",
+  "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsx ./scripts/build.ts"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "cloudflare",
+    "agents",
+    "hono"
+  ],
+  "author": "Cloudflare Inc.",
+  "license": "MIT",
+  "description": "Add Cloudflare Agents to your Hono app",
+  "peerDependencies": {
+    "agents-sdk": "^0.0.17",
+    "hono": "^4.6.17"
+  },
+  "devDependencies": {
+    "agents-sdk": "^0.0.17",
+    "hono": "^4.6.17"
+  }
 }

package/src/index.ts

@@ -0,0 +1,94 @@
+import { env } from "hono/adapter";
+import { createMiddleware } from "hono/factory";
+import { routeAgentRequest } from "agents-sdk";
+
+import type { Context, Env } from "hono";
+import type { AgentOptions } from "agents-sdk";
+
+/**
+ * Configuration options for the Cloudflare Agents middleware
+ */
+type AgentMiddlewareContext<E extends Env> = {
+  /** Cloudflare Agents-specific configuration options */
+  options?: AgentOptions<E>;
+  /** Optional error handler for caught errors */
+  onError?: (error: Error) => void;
+};
+
+/**
+ * Creates a middleware for handling Cloudflare Agents WebSocket and HTTP requests
+ * Processes both WebSocket upgrades and standard HTTP requests, delegating them to Cloudflare Agents
+ */
+export function agentsMiddleware<E extends Env = Env>(
+  ctx?: AgentMiddlewareContext<E>
+) {
+  return createMiddleware(async (c, next) => {
+    try {
+      const handler = isWebSocketUpgrade(c)
+        ? handleWebSocketUpgrade
+        : handleHttpRequest;
+      const response = await handler(c, ctx?.options);
+
+      return response === null ? await next() : response;
+    } catch (error) {
+      if (ctx?.onError) {
+        ctx.onError(error as Error);
+        return next();
+      }
+      throw error;
+    }
+  });
+}
+
+/**
+ * Checks if the incoming request is a WebSocket upgrade request
+ * Looks for the 'upgrade' header with a value of 'websocket' (case-insensitive)
+ */
+function isWebSocketUpgrade(c: Context): boolean {
+  return c.req.header("upgrade")?.toLowerCase() === "websocket";
+}
+
+/**
+ * Creates a new Request object from the Hono context
+ * Preserves the original request's URL, method, headers, and body
+ */
+function createRequestFromContext(c: Context) {
+  return new Request(c.req.url, {
+    method: c.req.method,
+    headers: c.req.header(),
+    body: c.req.raw.body,
+  });
+}
+
+/**
+ * Handles WebSocket upgrade requests
+ * Returns a WebSocket upgrade response if successful, null otherwise
+ */
+async function handleWebSocketUpgrade<E extends Env>(
+  c: Context<E>,
+  options?: AgentOptions<E>
+) {
+  const req = createRequestFromContext(c);
+  const response = await routeAgentRequest(req, env(c), options);
+
+  if (!response?.webSocket) {
+    return null;
+  }
+
+  return new Response(null, {
+    status: 101,
+    webSocket: response.webSocket,
+  });
+}
+
+/**
+ * Handles standard HTTP requests
+ * Forwards the request to Cloudflare Agents and returns the response
+ */
+async function handleHttpRequest<E extends Env>(
+  c: Context<E>,
+  options?: AgentOptions<E>
+) {
+  const req = createRequestFromContext(c);
+  return routeAgentRequest(req, env(c), options);
+}