@economic/agents 0.0.1-alpha.17 → 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

@@ -113,28 +113,17 @@ declare abstract class AIChatAgent<Env extends Cloudflare.Env = Cloudflare.Env>
    */
   protected log(message: string, payload?: Record<string, unknown>): Promise<void>;
   /**
-   * Records this conversation in the `conversations` D1 table and resets
-   * the idle summarization timer. Called automatically from `persistMessages`
-   * after every turn.
-   *
-   * After each upsert, any pending `generateSummary` schedule is cancelled
-   * and a new one is set for 30 minutes from now. If the user sends another
-   * message before the timer fires, the schedule is cancelled and reset again
-   * (debounce). When the conversation goes idle, `generateSummary` fires and
-   * writes the LLM-generated title and summary to D1.
+   * Records this conversation in the `conversations` D1 table and triggers
+   * LLM-based title/summary generation when appropriate. Called automatically
+   * from `persistMessages` after every turn.
+   *
+   * On the first turn (no existing row), awaits `generateTitleAndSummary` and
+   * inserts the row with title and summary already populated. On subsequent
+   * turns, upserts the timestamp and fire-and-forgets a summary refresh every
+   * `SUMMARY_CONTEXT_MESSAGES` messages (when the context window fully turns
+   * over). Neither path blocks the response to the client.
    */
   private recordConversation;
-  /**
-   * Generates a title and summary for the conversation after 30 minutes of
-   * inactivity. Invoked automatically by the Cloudflare Agents SDK scheduler
-   * — do not call this directly.
-   *
-   * Delegates to `generateConversationSummary` in `features/conversations`,
-   * which fetches the previous summary, slices to the last
-   * `SUMMARY_CONTEXT_MESSAGES` messages, calls `fastModel` with a structured
-   * output schema, and writes the result back to D1.
-   */
-  generateSummary(): Promise<void>;
   /**
    * Builds the parameter object for a `streamText` or `generateText` call,
    * pre-filling `messages`, `activeSkills`, and `fastModel` from this agent instance.
@@ -183,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
+/**
+ * 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>;
 /**
- * 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`.
+ * 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
 /**
@@ -207,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;
 /**
@@ -3724,21 +3716,19 @@ function superRefine(fn) {
 * Records a conversation row in the `conversations` D1 table.
 *
 * Called by `AIChatAgent` after every turn. On first call for a given
-* `durableObjectId` the row is inserted with `created_at` set to now.
+* `durableObjectId` the row is inserted with `created_at` set to now,
+* and with the provided `title` and `summary` if supplied.
 * On subsequent calls only `user_id` and `updated_at` are refreshed —
-* `created_at`, `title`, and `summary` are never overwritten.
-*
-* After upserting, `AIChatAgent` cancels any pending `generateSummary`
-* schedule and resets it to fire 30 minutes from now, debouncing the
-* idle timer on every turn.
+* `created_at`, `title`, and `summary` are never overwritten, preserving
+* any user edits.
 */
-async function recordConversation(db, durableObjectId, userId) {
+async function recordConversation(db, durableObjectId, userId, title, summary) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	await db.prepare(`INSERT INTO conversations (durable_object_id, user_id, title, summary, created_at, updated_at)
-       VALUES (?, ?, NULL, NULL, ?, ?)
+       VALUES (?, ?, ?, ?, ?, ?)
        ON CONFLICT(durable_object_id) DO UPDATE SET
          user_id    = excluded.user_id,
-         updated_at = excluded.updated_at`).bind(durableObjectId, userId, now, now).run();
+         updated_at = excluded.updated_at`).bind(durableObjectId, userId, title ?? null, summary ?? null, now, now).run();
 }
 /**
 * Returns the current `title` and `summary` for a conversation row,
@@ -3754,19 +3744,19 @@ async function updateConversationSummary(db, durableObjectId, title, summary) {
 	await db.prepare(`UPDATE conversations SET title = ?, summary = ? WHERE durable_object_id = ?`).bind(title, summary, durableObjectId).run();
 }
 /**
-* Generates a title and summary for a conversation using the provided model
-* and writes the result back to D1.
+* Generates a title and summary for a conversation using the provided model.
+* Returns the result without writing to D1.
 *
-* Fetches any existing summary first so the model can detect direction changes.
-* Only the last `SUMMARY_CONTEXT_MESSAGES` messages are passed to keep the
-* prompt bounded regardless of total conversation length.
+* Pass `existingSummary` so the model can detect direction changes when
+* updating an existing summary. Omit it (or pass undefined) for the initial
+* generation.
 *
-* Called by `AIChatAgent.generateSummary()` after the idle timer fires.
+* Only the last `SUMMARY_CONTEXT_MESSAGES` messages are used to keep the
+* prompt bounded regardless of total conversation length.
 */
-async function generateConversationSummary(db, durableObjectId, messages, model) {
-	const existing = await getConversationSummary(db, durableObjectId);
+async function generateTitleAndSummary(messages, model, existingSummary) {
 	const recentMessages = await convertToModelMessages(messages.slice(-30));
-	const previousContext = existing?.summary ? `Previous summary: ${existing.summary}\n\nMost recent messages:` : "Conversation:";
+	const previousContext = existingSummary ? `Previous summary: ${existingSummary}\n\nMost recent messages:` : "Conversation:";
 	const { output } = await generateText({
 		model,
 		output: Output.object({ schema: object({
@@ -3775,7 +3765,22 @@ async function generateConversationSummary(db, durableObjectId, messages, model)
 		}) }),
 		prompt: `${previousContext}\n\n${formatMessagesForSummary(recentMessages)}`
 	});
-	await updateConversationSummary(db, durableObjectId, output.title, output.summary);
+	return output;
+}
+/**
+* Generates a title and summary for a conversation using the provided model
+* and writes the result back to D1.
+*
+* Fetches any existing summary first so the model can detect direction changes.
+* Only the last `SUMMARY_CONTEXT_MESSAGES` messages are passed to keep the
+* prompt bounded regardless of total conversation length.
+*
+* Called by `AIChatAgent` every `SUMMARY_CONTEXT_MESSAGES` messages after
+* the first turn.
+*/
+async function generateConversationSummary(db, durableObjectId, messages, model) {
+	const { title, summary } = await generateTitleAndSummary(messages, model, (await getConversationSummary(db, durableObjectId))?.summary ?? void 0);
+	await updateConversationSummary(db, durableObjectId, title, summary);
 }
 //#endregion
 //#region src/agents/AIChatAgent.ts
@@ -3806,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 {
@@ -3828,39 +3833,31 @@ var AIChatAgent = class extends AIChatAgent$1 {
 		await insertAuditEvent(context.db, this.ctx.id.toString(), context.userId, message, payload);
 	}
 	/**
-	* Records this conversation in the `conversations` D1 table and resets
-	* the idle summarization timer. Called automatically from `persistMessages`
-	* after every turn.
-	*
-	* After each upsert, any pending `generateSummary` schedule is cancelled
-	* and a new one is set for 30 minutes from now. If the user sends another
-	* message before the timer fires, the schedule is cancelled and reset again
-	* (debounce). When the conversation goes idle, `generateSummary` fires and
-	* writes the LLM-generated title and summary to D1.
-	*/
-	async recordConversation() {
-		const context = this.resolveD1Context();
-		if (!context) return;
-		await recordConversation(context.db, this.ctx.id.toString(), context.userId);
-		const existing = this.getSchedules({ type: "delayed" }).find((s) => s.callback === "generateSummary");
-		if (existing) await this.cancelSchedule(existing.id);
-		await this.schedule(1800, "generateSummary", {});
-	}
-	/**
-	* Generates a title and summary for the conversation after 30 minutes of
-	* inactivity. Invoked automatically by the Cloudflare Agents SDK scheduler
-	* — do not call this directly.
+	* Records this conversation in the `conversations` D1 table and triggers
+	* LLM-based title/summary generation when appropriate. Called automatically
+	* from `persistMessages` after every turn.
 	*
-	* Delegates to `generateConversationSummary` in `features/conversations`,
-	* which fetches the previous summary, slices to the last
-	* `SUMMARY_CONTEXT_MESSAGES` messages, calls `fastModel` with a structured
-	* output schema, and writes the result back to D1.
+	* On the first turn (no existing row), awaits `generateTitleAndSummary` and
+	* inserts the row with title and summary already populated. On subsequent
+	* turns, upserts the timestamp and fire-and-forgets a summary refresh every
+	* `SUMMARY_CONTEXT_MESSAGES` messages (when the context window fully turns
+	* over). Neither path blocks the response to the client.
 	*/
-	async generateSummary() {
+	async recordConversation(messageCount) {
 		const context = this.resolveD1Context();
 		if (!context) return;
-		await generateConversationSummary(context.db, this.ctx.id.toString(), this.messages, this.fastModel);
-		this.log("conversation summary generated");
+		const durableObjectId = this.ctx.id.toString();
+		if (!await getConversationSummary(context.db, durableObjectId)) {
+			const { title, summary } = await generateTitleAndSummary(this.messages, this.fastModel);
+			await recordConversation(context.db, durableObjectId, context.userId, title, summary);
+			this.log("conversation summary generated");
+		} else {
+			await recordConversation(context.db, durableObjectId, context.userId);
+			if (messageCount % 30 === 0) {
+				generateConversationSummary(context.db, durableObjectId, this.messages, this.fastModel);
+				this.log("conversation summary updated");
+			}
+		}
 	}
 	/**
 	* Builds the parameter object for a `streamText` or `generateText` call,
@@ -3913,7 +3910,7 @@ var AIChatAgent = class extends AIChatAgent$1 {
 	* Returns an empty array if no skills have been loaded yet.
 	*/
 	async getLoadedSkills() {
-		return getStoredSkills(this.sql);
+		return getStoredSkills(this.sql.bind(this));
 	}
 	/**
 	* Extracts skill state from activate_skill results, persists to DO SQLite,
@@ -3944,12 +3941,50 @@ var AIChatAgent = class extends AIChatAgent$1 {
 				} catch {}
 			}
 		}
-		if (latestSkillState !== void 0) saveStoredSkills(this.sql, latestSkillState);
+		if (latestSkillState !== void 0) saveStoredSkills(this.sql.bind(this), latestSkillState);
 		this.log("turn completed", buildTurnSummary(messages, latestSkillState ?? []));
-		this.recordConversation();
+		this.recordConversation(messages.length);
 		const filtered = filterEphemeralMessages(messages);
 		return super.persistMessages(filtered, excludeBroadcastIds, options);
 	}
 };
 //#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.17",
+  "version": "0.0.1-alpha.19",
   "description": "A starter for creating a TypeScript package.",
   "homepage": "https://github.com/author/library#readme",
   "bugs": {