hono-agents 0.0.0-00ba881

package/README.md

@@ -0,0 +1,109 @@
+# 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 agents hono hono-agents
+```
+
+## Usage
+
+```ts
+import { Hono } from "hono";
+import { Agent } from "agents";
+import { agentsMiddleware } from "hono-agents";
+
+// 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, add bindings to your `wrangler.jsonc` file:
+
+```json
+{
+  "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
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import * as hono from "hono";
+import { Env } from "hono";
+import { AgentOptions } from "agents";
+
+/**
+ * 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<Env, string, {}>;
+
+export { agentsMiddleware };

package/dist/index.js

@@ -0,0 +1,43 @@
+// src/index.ts
+import { routeAgentRequest } from "agents";
+import { env } from "hono/adapter";
+import { createMiddleware } from "hono/factory";
+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";
+}
+async function handleWebSocketUpgrade(c, options) {
+  const response = await routeAgentRequest(
+    c.req.raw,
+    env(c),
+    options
+  );
+  if (!response?.webSocket) {
+    return null;
+  }
+  return new Response(null, {
+    status: 101,
+    webSocket: response.webSocket
+  });
+}
+async function handleHttpRequest(c, options) {
+  return routeAgentRequest(c.req.raw, 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 type { AgentOptions } from \"agents\";\nimport { routeAgentRequest } from \"agents\";\nimport type { Context, Env } from \"hono\";\nimport { env } from \"hono/adapter\";\nimport { createMiddleware } from \"hono/factory\";\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<Env>(async (c, next) => {\n    try {\n      const handler = isWebSocketUpgrade(c)\n        ? handleWebSocketUpgrade\n        : handleHttpRequest;\n\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 * 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 response = await routeAgentRequest(\n    c.req.raw,\n    env(c) satisfies Env,\n    options\n  );\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  return routeAgentRequest(c.req.raw, env(c) satisfies Env, options);\n}\n"],"mappings":";AACA,SAAS,yBAAyB;AAElC,SAAS,WAAW;AACpB,SAAS,wBAAwB;AAgB1B,SAAS,iBACd,KACA;AACA,SAAO,iBAAsB,OAAO,GAAG,SAAS;AAC9C,QAAI;AACF,YAAM,UAAU,mBAAmB,CAAC,IAChC,yBACA;AAEJ,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,eAAe,uBACb,GACA,SACA;AACA,QAAM,WAAW,MAAM;AAAA,IACrB,EAAE,IAAI;AAAA,IACN,IAAI,CAAC;AAAA,IACL;AAAA,EACF;AAEA,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,SAAO,kBAAkB,EAAE,IAAI,KAAK,IAAI,CAAC,GAAiB,OAAO;AACnE;","names":[]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "author": "Cloudflare Inc.",
+  "bugs": {
+    "url": "https://github.com/cloudflare/agents/issues"
+  },
+  "description": "Add Cloudflare Agents to your Hono app",
+  "devDependencies": {
+    "agents": "0.0.0-00ba881",
+    "hono": "^4.9.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "cloudflare",
+    "agents",
+    "hono"
+  ],
+  "license": "MIT",
+  "main": "src/index.ts",
+  "name": "hono-agents",
+  "peerDependencies": {
+    "agents": "0.0.0-00ba881",
+    "hono": "^4.6.17"
+  },
+  "repository": {
+    "directory": "packages/hono-agents",
+    "type": "git",
+    "url": "git+https://github.com/cloudflare/agents.git"
+  },
+  "scripts": {
+    "build": "tsx ./scripts/build.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "version": "0.0.0-00ba881"
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+import type { AgentOptions } from "agents";
+import { routeAgentRequest } from "agents";
+import type { Context, Env } from "hono";
+import { env } from "hono/adapter";
+import { createMiddleware } from "hono/factory";
+
+/**
+ * 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<Env>(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";
+}
+
+/**
+ * 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 response = await routeAgentRequest(
+    c.req.raw,
+    env(c) satisfies Env,
+    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>
+) {
+  return routeAgentRequest(c.req.raw, env(c) satisfies Env, options);
+}