hono-agents 3.0.10 → 3.0.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Cloudflare, Inc.
+
+Permission is hereby granted, free of
+charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -19,13 +19,13 @@ import { agentsMiddleware } from "hono-agents";
 
 // Define your agent classes
 export class ChatAgent extends Agent {
-  async onRequest(request) {
+  async onRequest(_request: Request) {
     return new Response("Ready to assist with chat.");
   }
 }
 
 export class AssistantAgent extends Agent {
-  async onRequest(request) {
+  async onRequest(_request: Request) {
     return new Response("I'm your AI assistant.");
   }
 }
@@ -34,24 +34,45 @@ export class AssistantAgent extends Agent {
 const app = new Hono();
 app.use("*", agentsMiddleware());
 
-// or with authentication
+export default app;
+```
+
+### Authentication
+
+Replace the basic middleware registration with one that authenticates both
+WebSocket connections and HTTP requests:
+
+```ts
+const authorizeAgentRequest = async (req: Request) => {
+  const token = req.headers.get("authorization");
+  // Validate token
+  if (!token) return new Response("Unauthorized", { status: 401 });
+};
+
 app.use(
   "*",
   agentsMiddleware({
     options: {
-      onBeforeConnect: async (req) => {
-        const token = req.headers.get("authorization");
-        // validate token
-        if (!token) return new Response("Unauthorized", { status: 401 });
-      }
+      onBeforeConnect: authorizeAgentRequest,
+      onBeforeRequest: authorizeAgentRequest
     }
   })
 );
+```
+
+### Error handling
 
-// With error handling
+Replace the basic middleware registration to add an error handler:
+
+```ts
 app.use("*", agentsMiddleware({ onError: (error) => console.error(error) }));
+```
+
+### Custom routing
+
+Replace the basic middleware registration to customize routing:
 
-// With custom routing
+```ts
 app.use(
   "*",
   agentsMiddleware({
@@ -60,8 +81,6 @@ app.use(
     }
   })
 );
-
-export default app;
 ```
 
 ## Configuration
@@ -94,6 +113,12 @@ The `agentsMiddleware` function:
 3. Handles WebSocket upgrades for persistent connections
 4. Provides error handling and custom routing options
 
+Requests that do not match an Agent route continue through later Hono middleware
+and routes. Once an Agent route matches, its response—including an HTTP
+rejection—is returned without invoking later handlers. Mount `agentsMiddleware`
+on a narrower path or configure a distinct prefix if the app has other WebSocket
+routes under the same URL prefix.
+
 Agents can:
 
 - Maintain state across requests

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 import { AgentOptions } from "agents";
-import * as _$hono from "hono";
 import { Env } from "hono";
 
 //#region src/index.d.ts
+type AgentEnv<E extends Env> = NonNullable<E["Bindings"]>;
 /**
  * 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 */;
+  /** Cloudflare Agents-specific configuration options */ options?: AgentOptions<
+    AgentEnv<E>
+  > /** Optional error handler for caught errors */;
   onError?: (error: Error) => void;
 };
 /**
@@ -16,7 +18,7 @@ type AgentMiddlewareContext<E extends Env> = {
  */
 declare function agentsMiddleware<E extends Env = Env>(
   ctx?: AgentMiddlewareContext<E>
-): _$hono.MiddlewareHandler<E, string, {}, Response>;
+): import("hono").MiddlewareHandler<E, string, {}, Response>;
 //#endregion
 export { agentsMiddleware };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -29,11 +29,12 @@ function isWebSocketUpgrade(c) {
 }
 /**
 * Handles WebSocket upgrade requests
-* Returns a WebSocket upgrade response if successful, null otherwise
+* Returns matched HTTP responses unchanged and null only when no Agent route matches
 */
 async function handleWebSocketUpgrade(c, options) {
 	const response = await routeAgentRequest(c.req.raw, env(c), options);
-	if (!response?.webSocket) return null;
+	if (response === null) return null;
+	if (!response.webSocket) return response;
 	return new Response(null, {
 		status: 101,
 		webSocket: response.webSocket

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"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<E>(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":";;;;;;;;AAoBA,SAAgB,iBACd,KACA;AACA,QAAO,iBAAoB,OAAO,GAAG,SAAS;AAC5C,MAAI;GAKF,MAAM,WAAW,OAJD,mBAAmB,EAAE,GACjC,yBACA,mBAE2B,GAAG,KAAK,QAAQ;AAE/C,UAAO,aAAa,OAAO,MAAM,MAAM,GAAG;WACnC,OAAO;AACd,OAAI,KAAK,SAAS;AAChB,QAAI,QAAQ,MAAe;AAC3B,WAAO,MAAM;;AAEf,SAAM;;GAER;;;;;;AAOJ,SAAS,mBAAmB,GAAqB;AAC/C,QAAO,EAAE,IAAI,OAAO,UAAU,EAAE,aAAa,KAAK;;;;;;AAOpD,eAAe,uBACb,GACA,SACA;CACA,MAAM,WAAW,MAAM,kBACrB,EAAE,IAAI,KACN,IAAI,EAAE,EACN,QACD;AAED,KAAI,CAAC,UAAU,UACb,QAAO;AAGT,QAAO,IAAI,SAAS,MAAM;EACxB,QAAQ;EACR,WAAW,SAAS;EACrB,CAAC;;;;;;AAOJ,eAAe,kBACb,GACA,SACA;AACA,QAAO,kBAAkB,EAAE,IAAI,KAAK,IAAI,EAAE,EAAgB,QAAQ"}
+{"version":3,"file":"index.js","names":[],"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\ntype AgentEnv<E extends Env> = NonNullable<E[\"Bindings\"]>;\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<AgentEnv<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<E>(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 matched HTTP responses unchanged and null only when no Agent route matches\n */\nasync function handleWebSocketUpgrade<E extends Env>(\n  c: Context<E>,\n  options?: AgentOptions<AgentEnv<E>>\n) {\n  const response = await routeAgentRequest(\n    c.req.raw,\n    env(c) as AgentEnv<E>,\n    options\n  );\n\n  if (response === null) {\n    return null;\n  }\n\n  if (!response.webSocket) {\n    return response;\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<AgentEnv<E>>\n) {\n  return routeAgentRequest(c.req.raw, env(c) as AgentEnv<E>, options);\n}\n"],"mappings":";;;;;;;;AAsBA,SAAgB,iBACd,KACA;CACA,OAAO,iBAAoB,OAAO,GAAG,SAAS;EAC5C,IAAI;GAKF,MAAM,WAAW,OAJD,mBAAmB,CAAC,IAChC,yBACA,kBAAA,CAE2B,GAAG,KAAK,OAAO;GAE9C,OAAO,aAAa,OAAO,MAAM,KAAK,IAAI;EAC5C,SAAS,OAAO;GACd,IAAI,KAAK,SAAS;IAChB,IAAI,QAAQ,KAAc;IAC1B,OAAO,KAAK;GACd;GACA,MAAM;EACR;CACF,CAAC;AACH;;;;;AAMA,SAAS,mBAAmB,GAAqB;CAC/C,OAAO,EAAE,IAAI,OAAO,SAAS,CAAC,EAAE,YAAY,MAAM;AACpD;;;;;AAMA,eAAe,uBACb,GACA,SACA;CACA,MAAM,WAAW,MAAM,kBACrB,EAAE,IAAI,KACN,IAAI,CAAC,GACL,OACF;CAEA,IAAI,aAAa,MACf,OAAO;CAGT,IAAI,CAAC,SAAS,WACZ,OAAO;CAGT,OAAO,IAAI,SAAS,MAAM;EACxB,QAAQ;EACR,WAAW,SAAS;CACtB,CAAC;AACH;;;;;AAMA,eAAe,kBACb,GACA,SACA;CACA,OAAO,kBAAkB,EAAE,IAAI,KAAK,IAAI,CAAC,GAAkB,OAAO;AACpE"}

package/package.json

@@ -5,8 +5,8 @@
   },
   "description": "Add Cloudflare Agents to your Hono app",
   "devDependencies": {
-    "agents": "^0.11.0",
-    "hono": "^4.12.12"
+    "agents": "^0.21.0",
+    "hono": "^4.12.27"
   },
   "publishConfig": {
     "access": "public"
@@ -31,7 +31,7 @@
   "main": "src/index.ts",
   "name": "hono-agents",
   "peerDependencies": {
-    "agents": ">=0.9.0 <1.0.0",
+    "agents": ">=0.17.1 <1.0.0",
     "hono": "^4.6.17"
   },
   "repository": {
@@ -39,10 +39,11 @@
     "type": "git",
     "url": "git+https://github.com/cloudflare/agents.git"
   },
-  "scripts": {
-    "build": "tsx ./scripts/build.ts"
-  },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "3.0.10"
-}
+  "version": "3.0.12",
+  "scripts": {
+    "build": "tsx ./scripts/build.ts",
+    "test": "vitest --run"
+  }
+}

package/src/index.ts

@@ -4,12 +4,14 @@ import type { Context, Env } from "hono";
 import { env } from "hono/adapter";
 import { createMiddleware } from "hono/factory";
 
+type AgentEnv<E extends Env> = NonNullable<E["Bindings"]>;
+
 /**
  * Configuration options for the Cloudflare Agents middleware
  */
 type AgentMiddlewareContext<E extends Env> = {
   /** Cloudflare Agents-specific configuration options */
-  options?: AgentOptions<E>;
+  options?: AgentOptions<AgentEnv<E>>;
   /** Optional error handler for caught errors */
   onError?: (error: Error) => void;
 };
@@ -50,22 +52,26 @@ function isWebSocketUpgrade(c: Context): boolean {
 
 /**
  * Handles WebSocket upgrade requests
- * Returns a WebSocket upgrade response if successful, null otherwise
+ * Returns matched HTTP responses unchanged and null only when no Agent route matches
  */
 async function handleWebSocketUpgrade<E extends Env>(
   c: Context<E>,
-  options?: AgentOptions<E>
+  options?: AgentOptions<AgentEnv<E>>
 ) {
   const response = await routeAgentRequest(
     c.req.raw,
-    env(c) satisfies Env,
+    env(c) as AgentEnv<E>,
     options
   );
 
-  if (!response?.webSocket) {
+  if (response === null) {
     return null;
   }
 
+  if (!response.webSocket) {
+    return response;
+  }
+
   return new Response(null, {
     status: 101,
     webSocket: response.webSocket
@@ -78,7 +84,7 @@ async function handleWebSocketUpgrade<E extends Env>(
  */
 async function handleHttpRequest<E extends Env>(
   c: Context<E>,
-  options?: AgentOptions<E>
+  options?: AgentOptions<AgentEnv<E>>
 ) {
-  return routeAgentRequest(c.req.raw, env(c) satisfies Env, options);
+  return routeAgentRequest(c.req.raw, env(c) as AgentEnv<E>, options);
 }