agents 0.6.0 → 0.7.1

package/dist/experimental/memory/session/index.js

@@ -0,0 +1,385 @@
+//#region src/experimental/memory/utils/compaction.ts
+/** Default thresholds for microCompaction rules (in chars) */
+const DEFAULTS = {
+	truncateToolOutputs: 3e4,
+	truncateText: 1e4,
+	keepRecent: 4
+};
+/**
+* Parse microCompaction config into resolved rules.
+* Returns null if disabled.
+*/
+function parseMicroCompactionRules(config) {
+	if (config === false) return null;
+	if (config === true) return {
+		truncateToolOutputs: DEFAULTS.truncateToolOutputs,
+		truncateText: DEFAULTS.truncateText,
+		keepRecent: DEFAULTS.keepRecent
+	};
+	const keepRecent = config.keepRecent ?? DEFAULTS.keepRecent;
+	if (!Number.isInteger(keepRecent) || keepRecent < 0) throw new Error("keepRecent must be a non-negative integer");
+	const truncateToolOutputs = config.truncateToolOutputs === false ? false : config.truncateToolOutputs === true || config.truncateToolOutputs === void 0 ? DEFAULTS.truncateToolOutputs : config.truncateToolOutputs;
+	if (typeof truncateToolOutputs === "number" && truncateToolOutputs <= 0) throw new Error("truncateToolOutputs must be a positive number");
+	const truncateText = config.truncateText === false ? false : config.truncateText === true || config.truncateText === void 0 ? DEFAULTS.truncateText : config.truncateText;
+	if (typeof truncateText === "number" && truncateText <= 0) throw new Error("truncateText must be a positive number");
+	return {
+		truncateToolOutputs,
+		truncateText,
+		keepRecent
+	};
+}
+/**
+* Truncate oversized parts in a single message.
+* Returns the same reference if nothing changed (allows callers to skip no-op updates).
+*/
+function truncateMessageParts(msg, rules) {
+	let changed = false;
+	const compactedParts = msg.parts.map((part) => {
+		if (rules.truncateToolOutputs !== false && (part.type.startsWith("tool-") || part.type === "dynamic-tool") && "output" in part) {
+			const toolPart = part;
+			if (toolPart.output !== void 0) {
+				const outputJson = JSON.stringify(toolPart.output);
+				if (outputJson.length > rules.truncateToolOutputs) {
+					changed = true;
+					return {
+						...part,
+						output: `[Truncated ${outputJson.length} bytes] ${outputJson.slice(0, 500)}...`
+					};
+				}
+			}
+		}
+		if (rules.truncateText !== false && part.type === "text" && "text" in part) {
+			const textPart = part;
+			if (textPart.text.length > rules.truncateText) {
+				changed = true;
+				return {
+					...part,
+					text: `${textPart.text.slice(0, rules.truncateText)}... [truncated ${textPart.text.length} chars]`
+				};
+			}
+		}
+		return part;
+	});
+	return changed ? {
+		...msg,
+		parts: compactedParts
+	} : msg;
+}
+/**
+* Apply microCompaction to an array of messages.
+* Returns same reference for unchanged messages (enables skip-update optimization).
+*
+* No keepRecent logic — the caller decides which messages to pass.
+*/
+function microCompact(messages, rules) {
+	return messages.map((msg) => truncateMessageParts(msg, rules));
+}
+
+//#endregion
+//#region src/experimental/memory/utils/tokens.ts
+/** Approximate characters per token for English text */
+const CHARS_PER_TOKEN = 4;
+/** Approximate token multiplier per whitespace-separated word */
+const WORDS_TOKEN_MULTIPLIER = 1.3;
+/** Approximate overhead tokens per message (role, framing) */
+const TOKENS_PER_MESSAGE = 4;
+/**
+* Estimate token count for a string using a hybrid heuristic.
+*
+* Takes the max of two estimates:
+* - Character-based: `length / 4` — better for dense content (JSON, code, URLs)
+* - Word-based: `words * 1.3` — better for natural language prose
+*
+* This is a heuristic. Do not use where exact counts are required.
+*/
+function estimateStringTokens(text) {
+	if (!text) return 0;
+	const charEstimate = text.length / CHARS_PER_TOKEN;
+	const wordEstimate = text.split(/\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;
+	return Math.ceil(Math.max(charEstimate, wordEstimate));
+}
+/**
+* Estimate total token count for an array of UIMessages.
+*
+* Walks each message's parts (text, tool invocations, tool results)
+* and applies per-message overhead.
+*
+* This is a heuristic. Do not use where exact counts are required.
+*/
+function estimateMessageTokens(messages) {
+	let tokens = 0;
+	for (const msg of messages) {
+		tokens += TOKENS_PER_MESSAGE;
+		for (const part of msg.parts) if (part.type === "text") tokens += estimateStringTokens(part.text);
+		else if (part.type.startsWith("tool-") || part.type === "dynamic-tool") {
+			const toolPart = part;
+			if (toolPart.input) tokens += estimateStringTokens(JSON.stringify(toolPart.input));
+			if (toolPart.output) tokens += estimateStringTokens(JSON.stringify(toolPart.output));
+		}
+	}
+	return tokens;
+}
+
+//#endregion
+//#region src/experimental/memory/session/session.ts
+var Session = class {
+	constructor(storage, options) {
+		this.storage = storage;
+		this.microCompactionRules = parseMicroCompactionRules(options?.microCompaction ?? true);
+		this.compactionConfig = options?.compaction ?? null;
+	}
+	getMessages(options) {
+		return this.storage.getMessages(options);
+	}
+	getMessage(id) {
+		return this.storage.getMessage(id);
+	}
+	getLastMessages(n) {
+		return this.storage.getLastMessages(n);
+	}
+	async append(messages) {
+		await this.storage.appendMessages(messages);
+		if (this.shouldAutoCompact()) {
+			if ((await this.compact()).success) return;
+		}
+		if (this.microCompactionRules) {
+			const rules = this.microCompactionRules;
+			const older = this.storage.getOlderMessages(rules.keepRecent);
+			if (older.length > 0) {
+				const compacted = microCompact(older, rules);
+				for (let i = 0; i < older.length; i++) if (compacted[i] !== older[i]) this.storage.updateMessage(compacted[i]);
+			}
+		}
+	}
+	updateMessage(message) {
+		this.storage.updateMessage(message);
+	}
+	deleteMessages(messageIds) {
+		this.storage.deleteMessages(messageIds);
+	}
+	clearMessages() {
+		this.storage.clearMessages();
+	}
+	async compact() {
+		const messages = this.storage.getMessages();
+		if (messages.length === 0) return { success: true };
+		try {
+			let result = messages;
+			if (this.compactionConfig?.fn) result = await this.compactionConfig.fn(result);
+			await this.storage.replaceMessages(result);
+			return { success: true };
+		} catch (err) {
+			return {
+				success: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}
+	/**
+	* Pre-check for auto-compaction using token estimate heuristic.
+	*/
+	shouldAutoCompact() {
+		if (!this.compactionConfig?.tokenThreshold) return false;
+		return estimateMessageTokens(this.storage.getMessages()) > this.compactionConfig.tokenThreshold;
+	}
+};
+
+//#endregion
+//#region src/experimental/memory/session/providers/agent.ts
+/**
+* Session provider that wraps an Agent's SQLite storage.
+* Provides pure CRUD — compaction is handled by the Session wrapper.
+*
+* @example
+* ```typescript
+* import { Session, AgentSessionProvider } from "agents/experimental/memory/session";
+*
+* // In your Agent class:
+* session = new Session(new AgentSessionProvider(this));
+*
+* // With compaction options:
+* session = new Session(new AgentSessionProvider(this), {
+*   microCompaction: { truncateToolOutputs: 2000, keepRecent: 10 },
+*   compaction: { tokenThreshold: 20000, fn: summarize }
+* });
+* ```
+*/
+var AgentSessionProvider = class {
+	constructor(agent) {
+		this.initialized = false;
+		this.agent = agent;
+	}
+	/**
+	* Ensure the messages table exists
+	*/
+	ensureTable() {
+		if (this.initialized) return;
+		this.agent.sql`
+      CREATE TABLE IF NOT EXISTS cf_agents_session_messages (
+        id TEXT PRIMARY KEY,
+        message TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `;
+		this.initialized = true;
+	}
+	/**
+	* Get all messages in AI SDK format
+	*/
+	getMessages(options) {
+		this.ensureTable();
+		if (options?.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 0)) throw new Error("limit must be a non-negative integer");
+		if (options?.offset !== void 0 && (!Number.isInteger(options.offset) || options.offset < 0)) throw new Error("offset must be a non-negative integer");
+		const role = options?.role ?? null;
+		const before = options?.before?.toISOString() ?? null;
+		const after = options?.after?.toISOString() ?? null;
+		const limit = options?.limit ?? -1;
+		const offset = options?.offset ?? 0;
+		const rows = this.agent.sql`
+      SELECT id, message, created_at FROM cf_agents_session_messages
+      WHERE (${role} IS NULL OR json_extract(message, '$.role') = ${role})
+        AND (${before} IS NULL OR created_at < ${before})
+        AND (${after} IS NULL OR created_at > ${after})
+      ORDER BY created_at ASC, rowid ASC
+      LIMIT ${limit} OFFSET ${offset}
+    `;
+		return this.parseRows(rows);
+	}
+	/**
+	* Append one or more messages to storage.
+	*/
+	async appendMessages(messages) {
+		this.ensureTable();
+		const messageArray = Array.isArray(messages) ? messages : [messages];
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		for (const message of messageArray) {
+			const json = JSON.stringify(message);
+			this.agent.sql`
+        INSERT INTO cf_agents_session_messages (id, message, created_at)
+        VALUES (${message.id}, ${json}, ${now})
+        ON CONFLICT(id) DO UPDATE SET message = excluded.message
+      `;
+		}
+	}
+	/**
+	* Update an existing message
+	*/
+	updateMessage(message) {
+		this.ensureTable();
+		const json = JSON.stringify(message);
+		this.agent.sql`
+      UPDATE cf_agents_session_messages
+      SET message = ${json}
+      WHERE id = ${message.id}
+    `;
+	}
+	/**
+	* Delete messages by their IDs
+	*/
+	deleteMessages(messageIds) {
+		this.ensureTable();
+		for (const id of messageIds) this.agent.sql`DELETE FROM cf_agents_session_messages WHERE id = ${id}`;
+	}
+	/**
+	* Clear all messages from the session
+	*/
+	clearMessages() {
+		this.ensureTable();
+		this.agent.sql`DELETE FROM cf_agents_session_messages`;
+	}
+	/**
+	* Get a single message by ID
+	*/
+	getMessage(id) {
+		this.ensureTable();
+		const rows = this.agent.sql`
+      SELECT message FROM cf_agents_session_messages WHERE id = ${id}
+    `;
+		if (rows.length === 0) return null;
+		try {
+			const parsed = JSON.parse(rows[0].message);
+			return this.isValidMessage(parsed) ? parsed : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Get the last N messages (most recent)
+	*/
+	getLastMessages(n) {
+		this.ensureTable();
+		const rows = this.agent.sql`
+      SELECT message FROM cf_agents_session_messages
+      ORDER BY created_at DESC, rowid DESC
+      LIMIT ${n}
+    `;
+		return this.parseRows([...rows].reverse());
+	}
+	/**
+	* Fetch messages outside the recent window (for microCompaction).
+	* Returns all messages except the most recent `keepRecent`.
+	*/
+	getOlderMessages(keepRecent) {
+		this.ensureTable();
+		const rows = this.agent.sql`
+      SELECT id, message FROM cf_agents_session_messages
+      WHERE rowid NOT IN (
+        SELECT rowid FROM cf_agents_session_messages
+        ORDER BY created_at DESC, rowid DESC
+        LIMIT ${keepRecent}
+      )
+    `;
+		return this.parseRows(rows);
+	}
+	/**
+	* Bulk replace all messages.
+	* Preserves original created_at timestamps for surviving messages.
+	*/
+	async replaceMessages(messages) {
+		this.ensureTable();
+		const existingRows = this.agent.sql`
+      SELECT id, created_at FROM cf_agents_session_messages
+    `;
+		const timestampMap = /* @__PURE__ */ new Map();
+		for (const row of existingRows) timestampMap.set(row.id, row.created_at);
+		this.agent.sql`DELETE FROM cf_agents_session_messages`;
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		for (const message of messages) {
+			const json = JSON.stringify(message);
+			const created_at = timestampMap.get(message.id) ?? now;
+			this.agent.sql`
+        INSERT INTO cf_agents_session_messages (id, message, created_at)
+        VALUES (${message.id}, ${json}, ${created_at})
+        ON CONFLICT(id) DO UPDATE SET message = excluded.message
+      `;
+		}
+	}
+	/**
+	* Validate message structure
+	*/
+	isValidMessage(msg) {
+		if (typeof msg !== "object" || msg === null) return false;
+		const m = msg;
+		if (typeof m.id !== "string" || m.id.length === 0) return false;
+		if (m.role !== "user" && m.role !== "assistant" && m.role !== "system") return false;
+		if (!Array.isArray(m.parts)) return false;
+		return true;
+	}
+	/**
+	* Parse message rows from SQL results into UIMessages.
+	*/
+	parseRows(rows) {
+		const messages = [];
+		for (const row of rows) try {
+			const parsed = JSON.parse(row.message);
+			if (this.isValidMessage(parsed)) messages.push(parsed);
+		} catch {
+			if (row.id) console.warn(`[AgentSessionProvider] Skipping malformed message ${row.id}`);
+		}
+		return messages;
+	}
+};
+
+//#endregion
+export { AgentSessionProvider, Session };
+//# sourceMappingURL=index.js.map

package/dist/experimental/memory/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/experimental/memory/utils/compaction.ts","../../../../src/experimental/memory/utils/tokens.ts","../../../../src/experimental/memory/session/session.ts","../../../../src/experimental/memory/session/providers/agent.ts"],"sourcesContent":["/**\n * MicroCompaction Utilities\n *\n * Internal pure functions for lightweight compaction (no LLM).\n * Not exported to users — used by the Session wrapper.\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { MicroCompactionRules } from \"../session/types\";\n\n/** Default thresholds for microCompaction rules (in chars) */\nexport const DEFAULTS = {\n  truncateToolOutputs: 30000,\n  truncateText: 10000,\n  keepRecent: 4\n};\n\n/** Resolved microCompaction rules with actual numeric thresholds */\nexport interface ResolvedMicroCompactionRules {\n  truncateToolOutputs: number | false;\n  truncateText: number | false;\n  keepRecent: number;\n}\n\n/**\n * Parse microCompaction config into resolved rules.\n * Returns null if disabled.\n */\nexport function parseMicroCompactionRules(\n  config: boolean | MicroCompactionRules\n): ResolvedMicroCompactionRules | null {\n  if (config === false) return null;\n\n  if (config === true) {\n    return {\n      truncateToolOutputs: DEFAULTS.truncateToolOutputs,\n      truncateText: DEFAULTS.truncateText,\n      keepRecent: DEFAULTS.keepRecent\n    };\n  }\n\n  // Custom rules object — validate numeric values\n  const keepRecent = config.keepRecent ?? DEFAULTS.keepRecent;\n  if (!Number.isInteger(keepRecent) || keepRecent < 0) {\n    throw new Error(\"keepRecent must be a non-negative integer\");\n  }\n\n  const truncateToolOutputs =\n    config.truncateToolOutputs === false\n      ? false\n      : config.truncateToolOutputs === true ||\n          config.truncateToolOutputs === undefined\n        ? DEFAULTS.truncateToolOutputs\n        : config.truncateToolOutputs;\n  if (typeof truncateToolOutputs === \"number\" && truncateToolOutputs <= 0) {\n    throw new Error(\"truncateToolOutputs must be a positive number\");\n  }\n\n  const truncateText =\n    config.truncateText === false\n      ? false\n      : config.truncateText === true || config.truncateText === undefined\n        ? DEFAULTS.truncateText\n        : config.truncateText;\n  if (typeof truncateText === \"number\" && truncateText <= 0) {\n    throw new Error(\"truncateText must be a positive number\");\n  }\n\n  return { truncateToolOutputs, truncateText, keepRecent };\n}\n\n/**\n * Truncate oversized parts in a single message.\n * Returns the same reference if nothing changed (allows callers to skip no-op updates).\n */\nfunction truncateMessageParts(\n  msg: UIMessage,\n  rules: ResolvedMicroCompactionRules\n): UIMessage {\n  let changed = false;\n\n  const compactedParts = msg.parts.map((part) => {\n    // Truncate tool outputs\n    if (\n      rules.truncateToolOutputs !== false &&\n      (part.type.startsWith(\"tool-\") || part.type === \"dynamic-tool\") &&\n      \"output\" in part\n    ) {\n      const toolPart = part as { output?: unknown };\n      if (toolPart.output !== undefined) {\n        const outputJson = JSON.stringify(toolPart.output);\n        if (outputJson.length > rules.truncateToolOutputs) {\n          changed = true;\n          return {\n            ...part,\n            output: `[Truncated ${outputJson.length} bytes] ${outputJson.slice(0, 500)}...`\n          };\n        }\n      }\n    }\n\n    // Truncate long text parts\n    if (\n      rules.truncateText !== false &&\n      part.type === \"text\" &&\n      \"text\" in part\n    ) {\n      const textPart = part as { type: \"text\"; text: string };\n      if (textPart.text.length > rules.truncateText) {\n        changed = true;\n        return {\n          ...part,\n          text: `${textPart.text.slice(0, rules.truncateText)}... [truncated ${textPart.text.length} chars]`\n        };\n      }\n    }\n\n    return part;\n  });\n\n  return changed ? ({ ...msg, parts: compactedParts } as UIMessage) : msg;\n}\n\n/**\n * Apply microCompaction to an array of messages.\n * Returns same reference for unchanged messages (enables skip-update optimization).\n *\n * No keepRecent logic — the caller decides which messages to pass.\n */\nexport function microCompact(\n  messages: UIMessage[],\n  rules: ResolvedMicroCompactionRules\n): UIMessage[] {\n  return messages.map((msg) => truncateMessageParts(msg, rules));\n}\n","/**\n * Token Estimation Utilities\n *\n * IMPORTANT: These are heuristic estimates, not actual tokenizer counts.\n *\n * We intentionally avoid real tokenizers (e.g. tiktoken, sentencepiece) because:\n * - A single tiktoken instance costs ~80-120MB of heap\n * - Cloudflare Workers have tight memory limits (128MB)\n * - For compaction thresholds, a conservative estimate is sufficient\n *\n * The hybrid approach (max of character-based and word-based estimates) handles\n * both dense token content (JSON, code) and natural language reasonably well.\n *\n * Calibration notes:\n * - Character-based: ~4 chars per token (conservative, from OpenAI guidance)\n * - Word-based: ~1.3 tokens per word (empirical, from Mastra's memory system)\n * - Per-message overhead: ~4 tokens for role/framing (empirical)\n *\n * These ratios are tuned for English. CJK, emoji-heavy, or highly technical\n * content may have different ratios. The conservative estimates help ensure\n * compaction triggers before context windows are actually exceeded.\n */\n\nimport type { UIMessage } from \"ai\";\n\n/** Approximate characters per token for English text */\nexport const CHARS_PER_TOKEN = 4;\n\n/** Approximate token multiplier per whitespace-separated word */\nexport const WORDS_TOKEN_MULTIPLIER = 1.3;\n\n/** Approximate overhead tokens per message (role, framing) */\nexport const TOKENS_PER_MESSAGE = 4;\n\n/**\n * Estimate token count for a string using a hybrid heuristic.\n *\n * Takes the max of two estimates:\n * - Character-based: `length / 4` — better for dense content (JSON, code, URLs)\n * - Word-based: `words * 1.3` — better for natural language prose\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateStringTokens(text: string): number {\n  if (!text) return 0;\n  const charEstimate = text.length / CHARS_PER_TOKEN;\n  const wordEstimate =\n    text.split(/\\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;\n  return Math.ceil(Math.max(charEstimate, wordEstimate));\n}\n\n/**\n * Estimate total token count for an array of UIMessages.\n *\n * Walks each message's parts (text, tool invocations, tool results)\n * and applies per-message overhead.\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateMessageTokens(messages: UIMessage[]): number {\n  let tokens = 0;\n  for (const msg of messages) {\n    tokens += TOKENS_PER_MESSAGE;\n    for (const part of msg.parts) {\n      if (part.type === \"text\") {\n        tokens += estimateStringTokens(\n          (part as { type: \"text\"; text: string }).text\n        );\n      } else if (\n        part.type.startsWith(\"tool-\") ||\n        part.type === \"dynamic-tool\"\n      ) {\n        const toolPart = part as { input?: unknown; output?: unknown };\n        if (toolPart.input) {\n          tokens += estimateStringTokens(JSON.stringify(toolPart.input));\n        }\n        if (toolPart.output) {\n          tokens += estimateStringTokens(JSON.stringify(toolPart.output));\n        }\n      }\n    }\n  }\n  return tokens;\n}\n","/**\n * Session — top-level API for conversation history with compaction.\n *\n * Wraps any SessionProvider (pure storage) and orchestrates compaction:\n * - microCompaction on every append() — cheap, no LLM\n * - full compaction when token threshold exceeded — user-supplied fn\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { SessionProvider } from \"./provider\";\nimport type {\n  MessageQueryOptions,\n  SessionProviderOptions,\n  CompactResult\n} from \"./types\";\nimport {\n  parseMicroCompactionRules,\n  microCompact,\n  type ResolvedMicroCompactionRules\n} from \"../utils/compaction\";\nimport { estimateMessageTokens } from \"../utils/tokens\";\n\nexport class Session {\n  private storage: SessionProvider;\n  private microCompactionRules: ResolvedMicroCompactionRules | null;\n  private compactionConfig: SessionProviderOptions[\"compaction\"] | null;\n\n  constructor(storage: SessionProvider, options?: SessionProviderOptions) {\n    this.storage = storage;\n\n    const mc = options?.microCompaction ?? true;\n    this.microCompactionRules = parseMicroCompactionRules(mc);\n    this.compactionConfig = options?.compaction ?? null;\n  }\n\n  // ── Read (delegated to storage) ────────────────────────────────────\n\n  getMessages(options?: MessageQueryOptions): UIMessage[] {\n    return this.storage.getMessages(options);\n  }\n\n  getMessage(id: string): UIMessage | null {\n    return this.storage.getMessage(id);\n  }\n\n  getLastMessages(n: number): UIMessage[] {\n    return this.storage.getLastMessages(n);\n  }\n\n  // ── Write (delegated + compaction) ─────────────────────────────────\n\n  async append(messages: UIMessage | UIMessage[]): Promise<void> {\n    // 1. Storage inserts\n    await this.storage.appendMessages(messages);\n\n    // 2. Full compaction if token threshold exceeded — runs instead of microCompaction\n    if (this.shouldAutoCompact()) {\n      const result = await this.compact();\n      if (result.success) return;\n      // Fall through to microCompaction if full compaction failed\n    }\n\n    // 3. MicroCompaction on older messages (only if no full compaction)\n    if (this.microCompactionRules) {\n      const rules = this.microCompactionRules;\n      const older = this.storage.getOlderMessages(rules.keepRecent);\n\n      if (older.length > 0) {\n        const compacted = microCompact(older, rules);\n        for (let i = 0; i < older.length; i++) {\n          if (compacted[i] !== older[i]) {\n            this.storage.updateMessage(compacted[i]);\n          }\n        }\n      }\n    }\n  }\n\n  updateMessage(message: UIMessage): void {\n    this.storage.updateMessage(message);\n  }\n\n  deleteMessages(messageIds: string[]): void {\n    this.storage.deleteMessages(messageIds);\n  }\n\n  clearMessages(): void {\n    this.storage.clearMessages();\n  }\n\n  // ── Compaction ─────────────────────────────────────────────────────\n\n  async compact(): Promise<CompactResult> {\n    const messages = this.storage.getMessages();\n\n    if (messages.length === 0) {\n      return { success: true };\n    }\n\n    try {\n      let result = messages;\n\n      if (this.compactionConfig?.fn) {\n        result = await this.compactionConfig.fn(result);\n      }\n\n      await this.storage.replaceMessages(result);\n\n      return { success: true };\n    } catch (err) {\n      return {\n        success: false,\n        error: err instanceof Error ? err.message : String(err)\n      };\n    }\n  }\n\n  /**\n   * Pre-check for auto-compaction using token estimate heuristic.\n   */\n  private shouldAutoCompact(): boolean {\n    if (!this.compactionConfig?.tokenThreshold) return false;\n\n    const messages = this.storage.getMessages();\n    const approxTokens = estimateMessageTokens(messages);\n    return approxTokens > this.compactionConfig.tokenThreshold;\n  }\n}\n","/**\n * Agent Session Provider\n *\n * Pure storage provider that uses the Agent's DO SQLite storage.\n * Compaction is orchestrated by the Session wrapper, not here.\n */\n\nimport type { UIMessage } from \"ai\";\nimport type { SessionProvider } from \"../provider\";\nimport type { MessageQueryOptions } from \"../types\";\n\n/**\n * Interface for objects that provide a sql tagged template method.\n * This matches the Agent class's sql method signature.\n */\nexport interface SqlProvider {\n  sql<T = Record<string, string | number | boolean | null>>(\n    strings: TemplateStringsArray,\n    ...values: (string | number | boolean | null)[]\n  ): T[];\n}\n\n/**\n * Session provider that wraps an Agent's SQLite storage.\n * Provides pure CRUD — compaction is handled by the Session wrapper.\n *\n * @example\n * ```typescript\n * import { Session, AgentSessionProvider } from \"agents/experimental/memory/session\";\n *\n * // In your Agent class:\n * session = new Session(new AgentSessionProvider(this));\n *\n * // With compaction options:\n * session = new Session(new AgentSessionProvider(this), {\n *   microCompaction: { truncateToolOutputs: 2000, keepRecent: 10 },\n *   compaction: { tokenThreshold: 20000, fn: summarize }\n * });\n * ```\n */\nexport class AgentSessionProvider implements SessionProvider {\n  private agent: SqlProvider;\n  private initialized = false;\n\n  constructor(agent: SqlProvider) {\n    this.agent = agent;\n  }\n\n  /**\n   * Ensure the messages table exists\n   */\n  private ensureTable(): void {\n    if (this.initialized) return;\n\n    this.agent.sql`\n      CREATE TABLE IF NOT EXISTS cf_agents_session_messages (\n        id TEXT PRIMARY KEY,\n        message TEXT NOT NULL,\n        created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n      )\n    `;\n    this.initialized = true;\n  }\n\n  /**\n   * Get all messages in AI SDK format\n   */\n  getMessages(options?: MessageQueryOptions): UIMessage[] {\n    this.ensureTable();\n\n    if (\n      options?.limit !== undefined &&\n      (!Number.isInteger(options.limit) || options.limit < 0)\n    ) {\n      throw new Error(\"limit must be a non-negative integer\");\n    }\n    if (\n      options?.offset !== undefined &&\n      (!Number.isInteger(options.offset) || options.offset < 0)\n    ) {\n      throw new Error(\"offset must be a non-negative integer\");\n    }\n\n    type Row = { id: string; message: string; created_at: string };\n    const role = options?.role ?? null;\n    const before = options?.before?.toISOString() ?? null;\n    const after = options?.after?.toISOString() ?? null;\n    const limit = options?.limit ?? -1;\n    const offset = options?.offset ?? 0;\n\n    const rows = this.agent.sql<Row>`\n      SELECT id, message, created_at FROM cf_agents_session_messages\n      WHERE (${role} IS NULL OR json_extract(message, '$.role') = ${role})\n        AND (${before} IS NULL OR created_at < ${before})\n        AND (${after} IS NULL OR created_at > ${after})\n      ORDER BY created_at ASC, rowid ASC\n      LIMIT ${limit} OFFSET ${offset}\n    `;\n\n    return this.parseRows(rows);\n  }\n\n  /**\n   * Append one or more messages to storage.\n   */\n  async appendMessages(messages: UIMessage | UIMessage[]): Promise<void> {\n    this.ensureTable();\n\n    const messageArray = Array.isArray(messages) ? messages : [messages];\n    const now = new Date().toISOString();\n\n    for (const message of messageArray) {\n      const json = JSON.stringify(message);\n      this.agent.sql`\n        INSERT INTO cf_agents_session_messages (id, message, created_at)\n        VALUES (${message.id}, ${json}, ${now})\n        ON CONFLICT(id) DO UPDATE SET message = excluded.message\n      `;\n    }\n  }\n\n  /**\n   * Update an existing message\n   */\n  updateMessage(message: UIMessage): void {\n    this.ensureTable();\n\n    const json = JSON.stringify(message);\n    this.agent.sql`\n      UPDATE cf_agents_session_messages\n      SET message = ${json}\n      WHERE id = ${message.id}\n    `;\n  }\n\n  /**\n   * Delete messages by their IDs\n   */\n  deleteMessages(messageIds: string[]): void {\n    this.ensureTable();\n\n    for (const id of messageIds) {\n      this.agent.sql`DELETE FROM cf_agents_session_messages WHERE id = ${id}`;\n    }\n  }\n\n  /**\n   * Clear all messages from the session\n   */\n  clearMessages(): void {\n    this.ensureTable();\n    this.agent.sql`DELETE FROM cf_agents_session_messages`;\n  }\n\n  /**\n   * Get a single message by ID\n   */\n  getMessage(id: string): UIMessage | null {\n    this.ensureTable();\n\n    const rows = this.agent.sql<{ message: string }>`\n      SELECT message FROM cf_agents_session_messages WHERE id = ${id}\n    `;\n\n    if (rows.length === 0) return null;\n\n    try {\n      const parsed = JSON.parse(rows[0].message);\n      return this.isValidMessage(parsed) ? parsed : null;\n    } catch {\n      return null;\n    }\n  }\n\n  /**\n   * Get the last N messages (most recent)\n   */\n  getLastMessages(n: number): UIMessage[] {\n    this.ensureTable();\n\n    const rows = this.agent.sql<{ message: string }>`\n      SELECT message FROM cf_agents_session_messages\n      ORDER BY created_at DESC, rowid DESC\n      LIMIT ${n}\n    `;\n\n    return this.parseRows([...rows].reverse());\n  }\n\n  /**\n   * Fetch messages outside the recent window (for microCompaction).\n   * Returns all messages except the most recent `keepRecent`.\n   */\n  getOlderMessages(keepRecent: number): UIMessage[] {\n    this.ensureTable();\n\n    type Row = { id: string; message: string };\n    const rows = this.agent.sql<Row>`\n      SELECT id, message FROM cf_agents_session_messages\n      WHERE rowid NOT IN (\n        SELECT rowid FROM cf_agents_session_messages\n        ORDER BY created_at DESC, rowid DESC\n        LIMIT ${keepRecent}\n      )\n    `;\n\n    return this.parseRows(rows);\n  }\n\n  /**\n   * Bulk replace all messages.\n   * Preserves original created_at timestamps for surviving messages.\n   */\n  async replaceMessages(messages: UIMessage[]): Promise<void> {\n    this.ensureTable();\n\n    // Build timestamp map from existing messages before clearing\n    type Row = { id: string; created_at: string };\n    const existingRows = this.agent.sql<Row>`\n      SELECT id, created_at FROM cf_agents_session_messages\n    `;\n    const timestampMap = new Map<string, string>();\n    for (const row of existingRows) {\n      timestampMap.set(row.id, row.created_at);\n    }\n\n    // Durable Objects auto-coalesces all synchronous SQL writes within\n    // a single I/O gate into one atomic batch — no explicit transaction needed.\n    this.agent.sql`DELETE FROM cf_agents_session_messages`;\n\n    const now = new Date().toISOString();\n    for (const message of messages) {\n      const json = JSON.stringify(message);\n      const created_at = timestampMap.get(message.id) ?? now;\n      this.agent.sql`\n        INSERT INTO cf_agents_session_messages (id, message, created_at)\n        VALUES (${message.id}, ${json}, ${created_at})\n        ON CONFLICT(id) DO UPDATE SET message = excluded.message\n      `;\n    }\n  }\n\n  /**\n   * Validate message structure\n   */\n  private isValidMessage(msg: unknown): msg is UIMessage {\n    if (typeof msg !== \"object\" || msg === null) return false;\n    const m = msg as Record<string, unknown>;\n\n    if (typeof m.id !== \"string\" || m.id.length === 0) return false;\n    if (m.role !== \"user\" && m.role !== \"assistant\" && m.role !== \"system\") {\n      return false;\n    }\n    if (!Array.isArray(m.parts)) return false;\n\n    return true;\n  }\n\n  /**\n   * Parse message rows from SQL results into UIMessages.\n   */\n  private parseRows(rows: { id?: string; message: string }[]): UIMessage[] {\n    const messages: UIMessage[] = [];\n    for (const row of rows) {\n      try {\n        const parsed = JSON.parse(row.message);\n        if (this.isValidMessage(parsed)) {\n          messages.push(parsed);\n        }\n      } catch {\n        if (row.id) {\n          console.warn(\n            `[AgentSessionProvider] Skipping malformed message ${row.id}`\n          );\n        }\n      }\n    }\n    return messages;\n  }\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -7,7 +7,7 @@ import { RetryOptions } from "./retries.js";
 import {
   r as MCPConnectionState,
   w as TransportType
-} from "./client-storage-D5nDLKMW.js";
+} from "./client-storage-yDVwzgfF.js";
 import {
   AgentMcpOAuthProvider,
   AgentsOAuthProvider,
@@ -23,7 +23,7 @@ import {
   WorkflowPage,
   WorkflowQueryCriteria
 } from "./workflow-types.js";
-import { Observability } from "./observability/index.js";
+import { Observability, ObservabilityEvent } from "./observability/index.js";
 import { MessageType } from "./types.js";
 import {
   Connection,
@@ -321,6 +321,14 @@ declare class Agent<
    * The observability implementation to use for the Agent
    */
   observability?: Observability;
+  /**
+   * Emit an observability event with auto-generated timestamp.
+   * @internal
+   */
+  protected _emit(
+    type: ObservabilityEvent["type"],
+    payload?: Record<string, unknown>
+  ): void;
   /**
    * Execute SQL queries against the Agent's database
    * @template T Type of the returned rows
@@ -632,6 +640,53 @@ declare class Agent<
    * @returns true if the task was cancelled, false if the task was not found
    */
   cancelSchedule(id: string): Promise<boolean>;
+  /**
+   * Keep the Durable Object alive via alarm heartbeats.
+   * Returns a disposer function that stops the heartbeat when called.
+   *
+   * Use this when you have long-running work and need to prevent the
+   * DO from going idle (eviction after ~70-140s of inactivity).
+   * The heartbeat fires every 30 seconds via the scheduling system.
+   *
+   * @experimental This API may change between releases.
+   *
+   * @example
+   * ```ts
+   * const dispose = await this.keepAlive();
+   * try {
+   *   // ... long-running work ...
+   * } finally {
+   *   dispose();
+   * }
+   * ```
+   */
+  keepAlive(): Promise<() => void>;
+  /**
+   * Run an async function while keeping the Durable Object alive.
+   * The heartbeat is automatically stopped when the function completes
+   * (whether it succeeds or throws).
+   *
+   * This is the recommended way to use keepAlive — it guarantees cleanup
+   * so you cannot forget to dispose the heartbeat.
+   *
+   * @experimental This API may change between releases.
+   *
+   * @example
+   * ```ts
+   * const result = await this.keepAliveWhile(async () => {
+   *   const data = await longRunningComputation();
+   *   return data;
+   * });
+   * ```
+   */
+  keepAliveWhile<T>(fn: () => Promise<T>): Promise<T>;
+  /**
+   * Internal no-op callback invoked by the keepAlive heartbeat schedule.
+   * Its only purpose is to keep the DO alive — the alarm machinery
+   * handles the rest.
+   * @internal
+   */
+  _cf_keepAliveHeartbeat(): Promise<void>;
   private _scheduleNextAlarm;
   /**
    * Method called when an alarm fires.