@economic/agents 0.0.1-alpha.18 → 0.0.1-alpha.19

package/README.md

@@ -13,6 +13,7 @@ npm install @economic/agents ai @cloudflare/ai-chat
 `@economic/agents` provides:
 
 - **`AIChatAgent`** — an abstract Cloudflare Durable Object base class. Implement `onChatMessage`, call `this.buildLLMParams()`, and pass the result to `streamText` from the AI SDK.
+- **`guard`** — optional TypeScript 5+ method decorator for `onChatMessage`. Runs your function with `options.body`; return a `Response` to short-circuit (e.g. auth), or nothing to continue.
 - **`buildLLMParams`** — the standalone version of the above, for use outside of `AIChatAgent` or in custom agent implementations.
 
 Skills and compaction are AI SDK concerns — they control what goes to the LLM. The CF layer is responsible for WebSockets, Durable Objects, and message persistence. These are kept separate.
@@ -121,6 +122,43 @@ Protected method on `AIChatAgent`. Wraps the standalone `buildLLMParams` functio
 
 Config is everything accepted by the standalone `buildLLMParams` except `messages`, `activeSkills`, and `fastModel`.
 
+### `guard`
+
+Method decorator (TypeScript 5+ stage-3) for handlers shaped like `onChatMessage(onFinish, options?)`. Before your method runs, it calls your `GuardFn` with `options?.body` (the same custom body the client sends via `useAgentChat` / `body` on the chat request).
+
+- Return **`undefined` / nothing** — the decorated method runs as usual.
+- Return a **`Response`** — that response is returned immediately; `onChatMessage` is not called.
+
+All policy (tokens, tiers, rate limits) lives in the guard function; the decorator only forwards `body` and branches on whether a `Response` was returned.
+
+```typescript
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { AIChatAgent, guard, type GuardFn } from "@economic/agents";
+
+const requireToken: GuardFn = async (body) => {
+  const token = body?.token;
+  if (typeof token !== "string" || !(await isValidToken(token))) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+};
+
+export class ChatAgent extends AIChatAgent<Env> {
+  protected fastModel = openai("gpt-4o-mini");
+
+  @guard(requireToken)
+  async onChatMessage(onFinish, options) {
+    const params = await this.buildLLMParams({
+      options,
+      onFinish,
+      model: openai("gpt-4o"),
+      system: "You are a helpful assistant.",
+    });
+    return streamText(params).toUIMessageStreamResponse();
+  }
+}
+```
+
 ### `fastModel` property
 
 Override `fastModel` on your subclass to enable automatic compaction and future background conversation summarization:
@@ -503,17 +541,19 @@ If `userId` is not set on the request body, the upsert is skipped and a `console
 
 ### Functions
 
-| Export           | Signature                              | Description                                                          |
-| ---------------- | -------------------------------------- | -------------------------------------------------------------------- |
-| `buildLLMParams` | `async (config) => Promise<LLMParams>` | Builds the full parameter object for `streamText` or `generateText`. |
+| Export           | Signature                              | Description                                                                                            |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `guard`          | `(guardFn: GuardFn)`                   | Method decorator: runs `guardFn` with `options.body`; a returned `Response` short-circuits the method. |
+| `buildLLMParams` | `async (config) => Promise<LLMParams>` | Builds the full parameter object for `streamText` or `generateText`.                                   |
 
 ### Types
 
-| Export                 | Description                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------- |
-| `Skill`                | A named group of tools with optional guidance.                                  |
-| `AgentContext<TBody>`  | Request body type merged with `log`. Use as the type of `experimental_context`. |
-| `BuildLLMParamsConfig` | Config type for the standalone `buildLLMParams` function.                       |
+| Export                 | Description                                                                                                      |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `GuardFn`              | `(body) => Response \| void \| Promise<...>`. Receives chat request `body`; return `Response` to block the turn. |
+| `Skill`                | A named group of tools with optional guidance.                                                                   |
+| `AgentContext<TBody>`  | Request body type merged with `log`. Use as the type of `experimental_context`.                                  |
+| `BuildLLMParamsConfig` | Config type for the standalone `buildLLMParams` function.                                                        |
 
 ---
 

package/dist/index.d.mts

@@ -172,13 +172,46 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
   }): Promise<void>;
 }
 //#endregion
-//#region src/features/compaction/index.d.ts
+//#region src/decorators/guard.d.ts
 /**
- * Number of recent messages to keep verbatim when compaction runs.
- * Older messages beyond this count are summarised into a single system message.
- * Used as the default when `maxMessagesBeforeCompaction` is not provided to `buildLLMParams`.
+ * Function run before a guarded handler (e.g. `onChatMessage`). Receives the
+ * custom request body from chat options (`options.body`, same shape as
+ * `OnChatMessageOptions` from `@cloudflare/ai-chat`).
+ *
+ * Return a {@link Response} to short-circuit and skip the decorated method.
+ * Return nothing (or `undefined`) to allow the method to run.
+ *
+ * Typical uses include auth, rate limits, or feature flags — all logic lives here;
+ * the `guard` decorator only forwards `body` and handles the return shape.
+ */
+type GuardFn = (body: Record<string, unknown> | undefined) => Response | void | Promise<Response | void>;
+/**
+ * Method decorator (TypeScript 5+ stage-3) that runs `guardFn` with the second
+ * argument's `body` (the chat request body). If `guardFn` returns a
+ * {@link Response}, that value is returned and the original method is not called.
+ *
+ * Intended for `onChatMessage(onFinish, options?)` on subclasses of
+ * `AIChatAgent`; `options` is read as `{ body?: Record<string, unknown> }`.
+ *
+ * @param guardFn - Called with `options?.body` before the method body.
+ *
+ * @example
+ * ```ts
+ * const requireToken: GuardFn = async (body) => {
+ *   if (!await isValidToken(body?.token)) {
+ *     return new Response("Unauthorized", { status: 401 });
+ *   }
+ * };
+ *
+ * class MyAgent extends AIChatAgent<Env> {
+ *   @guard(requireToken)
+ *   async onChatMessage(onFinish, options) {
+ *     // ...
+ *   }
+ * }
+ * ```
  */
-declare const DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION = 15;
+declare function guard(guardFn: GuardFn): (target: Function, _context: ClassMethodDecoratorContext) => (this: unknown, ...args: unknown[]) => Promise<unknown>;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -196,4 +229,4 @@ type AgentContext<TBody = Record<string, unknown>> = TBody & {
   log: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
 };
 //#endregion
-export { AIChatAgent, type AgentContext, type BuildLLMParamsConfig, DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION, type Skill, buildLLMParams };
+export { AIChatAgent, type AgentContext, type BuildLLMParamsConfig, type GuardFn, type Skill, buildLLMParams, guard };

package/dist/index.mjs

@@ -174,14 +174,6 @@ function filterEphemeralMessages(messages) {
 		}];
 	});
 }
-//#endregion
-//#region src/features/compaction/index.ts
-/**
-* Number of recent messages to keep verbatim when compaction runs.
-* Older messages beyond this count are summarised into a single system message.
-* Used as the default when `maxMessagesBeforeCompaction` is not provided to `buildLLMParams`.
-*/
-const DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION = 15;
 const TOOL_RESULT_PREVIEW_CHARS = 200;
 const SUMMARY_MAX_TOKENS = 4e3;
 /**
@@ -3819,7 +3811,7 @@ var AIChatAgent = class extends AIChatAgent$1 {
 		const db = this.env.AGENT_DB;
 		if (!db) return null;
 		if (!this._userId) {
-			console.error("[AIChatAgent] D1 write skipped: userId not set on request body");
+			console.error("[AIChatAgent] Logging & conversation tracking skipped: userId not set on request body");
 			return null;
 		}
 		return {
@@ -3957,4 +3949,42 @@ var AIChatAgent = class extends AIChatAgent$1 {
 	}
 };
 //#endregion
-export { AIChatAgent, DEFAULT_MAX_MESSAGES_BEFORE_COMPACTION, buildLLMParams };
+//#region src/decorators/guard.ts
+/**
+* Method decorator (TypeScript 5+ stage-3) that runs `guardFn` with the second
+* argument's `body` (the chat request body). If `guardFn` returns a
+* {@link Response}, that value is returned and the original method is not called.
+*
+* Intended for `onChatMessage(onFinish, options?)` on subclasses of
+* `AIChatAgent`; `options` is read as `{ body?: Record<string, unknown> }`.
+*
+* @param guardFn - Called with `options?.body` before the method body.
+*
+* @example
+* ```ts
+* const requireToken: GuardFn = async (body) => {
+*   if (!await isValidToken(body?.token)) {
+*     return new Response("Unauthorized", { status: 401 });
+*   }
+* };
+*
+* class MyAgent extends AIChatAgent<Env> {
+*   @guard(requireToken)
+*   async onChatMessage(onFinish, options) {
+*     // ...
+*   }
+* }
+* ```
+*/
+function guard(guardFn) {
+	return function(target, _context) {
+		return async function(...args) {
+			const options = args[1];
+			const result = await guardFn(options?.body);
+			if (result instanceof Response) return result;
+			return target.apply(this, args);
+		};
+	};
+}
+//#endregion
+export { AIChatAgent, buildLLMParams, guard };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "0.0.1-alpha.18",
+  "version": "0.0.1-alpha.19",
   "description": "A starter for creating a TypeScript package.",
   "homepage": "https://github.com/author/library#readme",
   "bugs": {