agents 0.15.0 → 0.16.0

package/dist/experimental/memory/session/index.d.ts

@@ -1,22 +1,24 @@
 import {
-  A as CompactContext,
+  A as StoredCompaction,
   C as isSearchProvider,
-  D as SessionProvider,
-  E as SearchResult,
-  F as SessionTokenCounter,
-  I as SessionTokenCounterInput,
-  M as SessionMessage,
-  N as SessionMessagePart,
-  O as StoredCompaction,
-  P as SessionOptions,
+  D as RecentHistoryResult,
+  E as HistoryRowStat,
+  F as SessionMessagePart,
+  I as SessionOptions,
+  L as SessionTokenCounter,
+  M as CompactContext,
+  N as CompactionErrorHandler,
+  O as SearchResult,
+  P as SessionMessage,
+  R as SessionTokenCounterInput,
   S as SearchProvider,
   T as SqlProvider,
   _ as isWritableProvider,
   b as isSkillProvider,
   g as WritableContextProvider,
   h as ContextProvider,
-  j as CompactionErrorHandler,
-  k as CompactAfterOptions,
+  j as CompactAfterOptions,
+  k as SessionProvider,
   m as ContextConfig,
   p as ContextBlock,
   r as CompactResult,
@@ -24,7 +26,7 @@ import {
   w as AgentSessionProvider,
   x as AgentSearchProvider,
   y as SkillProvider
-} from "../../../compaction-helpers-BEUILPss.js";
+} from "../../../compaction-helpers-DVcu5lPN.js";
 import { ToolSet } from "ai";
 
 //#region src/experimental/memory/session/session.d.ts
@@ -151,8 +153,31 @@ declare class Session {
    * for load_context tool results that haven't been unloaded.
    * Runs once per init to survive hibernation / eviction, including for
    * async SessionProviders (e.g. Postgres) where we must `await` history.
+   *
+   * Skipped entirely when no skill-capable provider is configured —
+   * `load_context` results can only exist when a skill block was registered,
+   * and the scan would otherwise read the whole transcript on every wake,
+   * bypassing byte-budgeted hydration (#1710). A skill block added later via
+   * `addContext()` triggers the scan at that point instead.
    */
   private _restoreLoadedSkills;
+  private _skillScanRan;
+  /**
+   * Scan stored history for load/unload_context tool results and restore
+   * the loaded-skill tracking set.
+   *
+   * Memory-bounded when the provider supports `getHistoryRowStats`: rows
+   * are enumerated without content, then only assistant rows are fetched
+   * and scanned ONE AT A TIME — peak memory is a single message instead of
+   * the whole transcript. Falls back to a full `getHistory()` read for
+   * providers without row stats (e.g. Postgres).
+   *
+   * Note: the bounded path scans raw path rows, so `load_context` results
+   * inside compacted ranges are still seen (the full-read path hides them
+   * behind compaction overlays). That superset is intentional — the stored
+   * tool result still exists and can be reclaimed by `unloadSkill`.
+   */
+  private _scanHistoryForLoadedSkills;
   /**
    * Reclaim context-window tokens consumed by a previously loaded skill.
    *
@@ -170,6 +195,30 @@ declare class Session {
    */
   private _reclaimLoadedSkill;
   getHistory(leafId?: string | null): Promise<SessionMessage[]>;
+  private _warnedNoRecentHistorySupport;
+  /**
+   * Byte-budgeted read of the most recent messages on the active branch
+   * path (always at least the leaf message, and at least
+   * `minRecentMessages` when the path is long enough). Lets hosts hydrate
+   * a bounded window instead of the full transcript so wake-time memory
+   * scales with the budget rather than total session history (#1710).
+   *
+   * Falls back to a full (untruncated) read when the provider doesn't
+   * implement `getRecentHistory`. The fallback reports honest metadata
+   * (`truncated: false` and the real serialized size) and warns once so a
+   * host relying on the budget knows it is not being enforced.
+   */
+  getRecentHistory(
+    maxContentBytes: number,
+    minRecentMessages?: number
+  ): Promise<RecentHistoryResult>;
+  /**
+   * Per-row stored sizes for the active branch path (root → leaf) WITHOUT
+   * loading message content, or `null` when the provider doesn't support it.
+   * Lets hosts find oversized rows (e.g. inline base64 media) and process
+   * them one at a time with bounded memory.
+   */
+  getHistoryRowStats(): Promise<HistoryRowStat[] | null>;
   getMessage(id: string): Promise<SessionMessage | null>;
   getLatestLeaf(): Promise<SessionMessage | null>;
   getBranches(messageId: string): Promise<SessionMessage[]>;
@@ -186,6 +235,18 @@ declare class Session {
   ): Promise<void>;
   private _appendMessage;
   updateMessage(message: SessionMessage): Promise<void>;
+  /**
+   * @internal
+   * Rewrite a stored message WITHOUT the public-write side effects: no
+   * token-estimate status broadcast (which reads the FULL history) and no
+   * auto-compaction check. For framework maintenance passes that rewrite
+   * many rows with bounded memory — e.g. media eviction (#1710) — where the
+   * per-row full-history estimate would reintroduce the memory pressure the
+   * pass exists to remove. The message-change listener still fires so a
+   * cache-owning host stays coherent. Application code should use
+   * `updateMessage`.
+   */
+  internal_rewriteMessage(message: SessionMessage): Promise<void>;
   deleteMessages(messageIds: string[]): Promise<void>;
   clearMessages(): Promise<void>;
   addCompaction(
@@ -576,6 +637,7 @@ export {
   type ContextBlock,
   type ContextConfig,
   type ContextProvider,
+  type HistoryRowStat,
   type PgClientLike,
   type PostgresClient,
   type PostgresConnection,
@@ -583,6 +645,7 @@ export {
   PostgresSearchProvider,
   PostgresSessionProvider,
   R2SkillProvider,
+  type RecentHistoryResult,
   type SearchProvider,
   type SearchResult,
   Session,

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

@@ -482,6 +482,14 @@ var ContextBlocks = class {
 		return Array.from(this.blocks.values()).some((b) => b.isSkill);
 	}
 	/**
+	* Check whether any CONFIGURED provider is skill-capable, without
+	* requiring `load()` to have run. Used by Session to decide whether the
+	* init-time loaded-skill restore scan is needed at all.
+	*/
+	hasSkillCapableConfigs() {
+		return this.configs.some((c) => c.provider !== void 0 && isSkillProvider(c.provider));
+	}
+	/**
 	* Get skill block labels.
 	*/
 	getSkillLabels() {
@@ -708,6 +716,22 @@ var ContextBlocks = class {
 };
 //#endregion
 //#region src/experimental/memory/session/providers/agent.ts
+/**
+* Bounds for each content-hydration query on a history path.
+*
+* Message rows can be up to ~1.8MB each (see ROW_MAX_BYTES in agents/chat),
+* so content is fetched in bounded batches rather than one statement to keep
+* any per-statement buffering in the SQLite layer small. In workerd the
+* SQLite allocator shares the isolate's memory budget with the JS heap —
+* oversized transient result sets surface as SQLITE_NOMEM (#1710).
+*
+* Chunks are bounded by BOTH row count and cumulative stored bytes (sizes
+* come from the path row stats, so no content is read to compute them).
+* Without the byte bound, 50 near-cap rows could still materialize ~90MB
+* in a single statement.
+*/
+const HISTORY_CONTENT_CHUNK_SIZE = 50;
+const HISTORY_CONTENT_CHUNK_BYTES = 4 * 1024 * 1024;
 var AgentSessionProvider = class {
 	/**
 	* @param agent - Agent or any object with a `sql` tagged template method
@@ -772,29 +796,47 @@ var AgentSessionProvider = class {
 	}
 	getHistory(leafId) {
 		this.ensureTable();
-		const leaf = leafId ? this.agent.sql`
-          SELECT id FROM assistant_messages WHERE id = ${leafId} AND session_id = ${this.sessionId}
-        `[0] : this.latestLeafRow();
+		const leaf = leafId ? this.leafRowById(leafId) : this.latestLeafRow();
 		if (!leaf) return [];
-		const path = this.agent.sql`
-      WITH RECURSIVE path AS (
-        SELECT *, 0 as depth FROM assistant_messages WHERE id = ${leaf.id}
-        UNION ALL
-        SELECT m.*, p.depth + 1 FROM assistant_messages m
-        JOIN path p ON m.id = p.parent_id
-        WHERE m.session_id = ${this.sessionId} AND p.depth < 10000
-      )
-      SELECT content FROM path ORDER BY depth DESC
-    `;
-		const messages = this.parseRows(path);
+		const messages = this.messagesByPathStats(this.pathRowStats(leaf.id));
 		const compactions = this.getCompactions();
 		if (compactions.length === 0) return messages;
 		return this.applyCompactions(messages, compactions);
 	}
+	getRecentHistory(leafId, maxContentBytes, minRecentMessages = 1) {
+		this.ensureTable();
+		const leaf = leafId ? this.leafRowById(leafId) : this.latestLeafRow();
+		if (!leaf) return {
+			messages: [],
+			truncated: false,
+			totalContentBytes: 0
+		};
+		const stats = this.pathRowStats(leaf.id);
+		const totalContentBytes = stats.reduce((sum, row) => sum + row.bytes, 0);
+		const minRecent = Math.max(1, Math.floor(minRecentMessages));
+		let start = stats.length - 1;
+		let used = stats[start]?.bytes ?? 0;
+		while (start > 0 && (stats.length - start < minRecent || used + stats[start - 1].bytes <= maxContentBytes)) {
+			start--;
+			used += stats[start].bytes;
+		}
+		const messages = this.messagesByPathStats(stats.slice(start));
+		const compactions = this.getCompactions();
+		return {
+			messages: compactions.length === 0 ? messages : this.applyCompactions(messages, compactions),
+			truncated: start > 0,
+			totalContentBytes
+		};
+	}
+	getHistoryRowStats(leafId) {
+		this.ensureTable();
+		const leaf = leafId ? this.leafRowById(leafId) : this.latestLeafRow();
+		return leaf ? this.pathRowStats(leaf.id) : [];
+	}
 	getLatestLeaf() {
 		this.ensureTable();
 		const row = this.latestLeafRow();
-		return row ? this.parse(row.content) : null;
+		return row ? this.getMessage(row.id) : null;
 	}
 	getBranches(messageId) {
 		this.ensureTable();
@@ -910,12 +952,80 @@ var AgentSessionProvider = class {
 	}
 	latestLeafRow() {
 		return this.agent.sql`
-      SELECT m.id, m.content FROM assistant_messages m
+      SELECT m.id FROM assistant_messages m
       LEFT JOIN assistant_messages c ON c.parent_id = m.id AND c.session_id = ${this.sessionId}
       WHERE c.id IS NULL AND m.session_id = ${this.sessionId}
       ORDER BY m.created_at DESC, m.rowid DESC LIMIT 1
     `[0] ?? null;
 	}
+	leafRowById(leafId) {
+		return this.agent.sql`
+      SELECT id FROM assistant_messages WHERE id = ${leafId} AND session_id = ${this.sessionId}
+    `[0] ?? null;
+	}
+	/**
+	* The active branch path as (id, role, content size) rows, root → leaf.
+	*
+	* Recurses over (id, parent_id) only. Carrying `content` through the
+	* recursive queue AND the ORDER BY sorter materializes the entire
+	* transcript several times over inside SQLite's allocator, which in
+	* workerd shares the isolate's memory budget with the JS heap — large
+	* media-heavy sessions then fail with SQLITE_NOMEM on wake (#1710).
+	* Content is fetched separately in bounded chunks (`messagesByPathStats`).
+	*/
+	pathRowStats(leafId) {
+		return this.agent.sql`
+      WITH RECURSIVE path(id, parent_id, depth) AS (
+        SELECT id, parent_id, 0 FROM assistant_messages WHERE id = ${leafId}
+        UNION ALL
+        SELECT m.id, m.parent_id, p.depth + 1 FROM assistant_messages m
+        JOIN path p ON m.id = p.parent_id
+        WHERE m.session_id = ${this.sessionId} AND p.depth < 10000
+      )
+      SELECT path.id AS id, am.role AS role, LENGTH(CAST(am.content AS BLOB)) AS bytes
+      FROM path JOIN assistant_messages am ON am.id = path.id
+      ORDER BY path.depth DESC
+    `;
+	}
+	/**
+	* Fetch and parse message content for an ordered list of path rows.
+	*
+	* Content is read in chunks bounded by both row count and cumulative
+	* stored bytes (no ORDER BY — SQLite streams rows without materializing
+	* the result set) and reassembled in path order. Rows that fail to parse
+	* are skipped, matching previous behavior.
+	*/
+	messagesByPathStats(rows) {
+		const contentById = /* @__PURE__ */ new Map();
+		const fetchChunk = (ids) => {
+			const fetched = this.agent.sql`
+        SELECT id, content FROM assistant_messages
+        WHERE session_id = ${this.sessionId}
+          AND id IN (SELECT value FROM json_each(${JSON.stringify(ids)}))
+      `;
+			for (const row of fetched) contentById.set(row.id, row.content);
+		};
+		let chunk = [];
+		let chunkBytes = 0;
+		for (const row of rows) {
+			if (chunk.length > 0 && (chunk.length >= HISTORY_CONTENT_CHUNK_SIZE || chunkBytes + row.bytes > HISTORY_CONTENT_CHUNK_BYTES)) {
+				fetchChunk(chunk);
+				chunk = [];
+				chunkBytes = 0;
+			}
+			chunk.push(row.id);
+			chunkBytes += row.bytes;
+		}
+		if (chunk.length > 0) fetchChunk(chunk);
+		const result = [];
+		for (const row of rows) {
+			const content = contentById.get(row.id);
+			if (content === void 0) continue;
+			const msg = this.parse(content);
+			if (msg) result.push(msg);
+		}
+		return result;
+	}
 	indexFTS(message) {
 		const text = message.parts.filter((p) => p.type === "text").map((p) => p.text).join(" ");
 		this.deleteFTS(message.id);
@@ -1023,6 +1133,8 @@ var Session = class Session {
 	constructor(storage, options) {
 		this._warnedCompactionNoOp = false;
 		this._ready = false;
+		this._skillScanRan = false;
+		this._warnedNoRecentHistorySupport = false;
 		this.storage = storage;
 		this.context = new ContextBlocks(options?.context ?? [], options?.promptStore);
 		this._tokenCounter = options?.tokenCounter;
@@ -1171,12 +1283,37 @@ var Session = class Session {
 	* for load_context tool results that haven't been unloaded.
 	* Runs once per init to survive hibernation / eviction, including for
 	* async SessionProviders (e.g. Postgres) where we must `await` history.
+	*
+	* Skipped entirely when no skill-capable provider is configured —
+	* `load_context` results can only exist when a skill block was registered,
+	* and the scan would otherwise read the whole transcript on every wake,
+	* bypassing byte-budgeted hydration (#1710). A skill block added later via
+	* `addContext()` triggers the scan at that point instead.
 	*/
 	async _restoreLoadedSkills() {
-		const history = await this.storage.getHistory();
+		if (!this.context.hasSkillCapableConfigs()) return;
+		await this._scanHistoryForLoadedSkills();
+	}
+	/**
+	* Scan stored history for load/unload_context tool results and restore
+	* the loaded-skill tracking set.
+	*
+	* Memory-bounded when the provider supports `getHistoryRowStats`: rows
+	* are enumerated without content, then only assistant rows are fetched
+	* and scanned ONE AT A TIME — peak memory is a single message instead of
+	* the whole transcript. Falls back to a full `getHistory()` read for
+	* providers without row stats (e.g. Postgres).
+	*
+	* Note: the bounded path scans raw path rows, so `load_context` results
+	* inside compacted ranges are still seen (the full-read path hides them
+	* behind compaction overlays). That superset is intentional — the stored
+	* tool result still exists and can be reclaimed by `unloadSkill`.
+	*/
+	async _scanHistoryForLoadedSkills() {
+		this._skillScanRan = true;
 		const loaded = /* @__PURE__ */ new Set();
-		for (const msg of history) {
-			if (msg.role !== "assistant") continue;
+		const scanMessage = (msg) => {
+			if (msg.role !== "assistant") return;
 			for (const part of msg.parts) if (part.toolName === "load_context" && part.state === "output-available") {
 				const input = part.input;
 				if (input?.label && input?.key) {
@@ -1188,7 +1325,15 @@ var Session = class Session {
 				const input = part.input;
 				if (input?.label && input?.key) loaded.delete(`${input.label}:${input.key}`);
 			}
-		}
+		};
+		if (this.storage.getHistoryRowStats) {
+			const stats = await this.storage.getHistoryRowStats();
+			for (const row of stats) {
+				if (row.role !== "assistant") continue;
+				const msg = await this.storage.getMessage(row.id);
+				if (msg) scanMessage(msg);
+			}
+		} else for (const msg of await this.storage.getHistory()) scanMessage(msg);
 		if (loaded.size > 0) this.context.restoreLoadedSkills(loaded);
 	}
 	/**
@@ -1238,6 +1383,45 @@ var Session = class Session {
 		await this._ensureRestored();
 		return this.storage.getHistory(leafId);
 	}
+	/**
+	* Byte-budgeted read of the most recent messages on the active branch
+	* path (always at least the leaf message, and at least
+	* `minRecentMessages` when the path is long enough). Lets hosts hydrate
+	* a bounded window instead of the full transcript so wake-time memory
+	* scales with the budget rather than total session history (#1710).
+	*
+	* Falls back to a full (untruncated) read when the provider doesn't
+	* implement `getRecentHistory`. The fallback reports honest metadata
+	* (`truncated: false` and the real serialized size) and warns once so a
+	* host relying on the budget knows it is not being enforced.
+	*/
+	async getRecentHistory(maxContentBytes, minRecentMessages = 1) {
+		await this._ensureRestored();
+		if (this.storage.getRecentHistory) return this.storage.getRecentHistory(null, maxContentBytes, minRecentMessages);
+		if (!this._warnedNoRecentHistorySupport) {
+			this._warnedNoRecentHistorySupport = true;
+			console.warn("[Session] The configured SessionProvider does not implement getRecentHistory; the requested byte budget cannot be enforced and the FULL history was loaded. Implement getRecentHistory (and getHistoryRowStats) on the provider to bound hydration.");
+		}
+		const messages = await this.storage.getHistory();
+		let totalContentBytes = 0;
+		for (const message of messages) totalContentBytes += JSON.stringify(message).length;
+		return {
+			messages,
+			truncated: false,
+			totalContentBytes
+		};
+	}
+	/**
+	* Per-row stored sizes for the active branch path (root → leaf) WITHOUT
+	* loading message content, or `null` when the provider doesn't support it.
+	* Lets hosts find oversized rows (e.g. inline base64 media) and process
+	* them one at a time with bounded memory.
+	*/
+	async getHistoryRowStats() {
+		await this._ensureRestored();
+		if (!this.storage.getHistoryRowStats) return null;
+		return this.storage.getHistoryRowStats();
+	}
 	async getMessage(id) {
 		await this._ensureRestored();
 		return this.storage.getMessage(id);
@@ -1351,6 +1535,25 @@ var Session = class Session {
 			message
 		});
 	}
+	/**
+	* @internal
+	* Rewrite a stored message WITHOUT the public-write side effects: no
+	* token-estimate status broadcast (which reads the FULL history) and no
+	* auto-compaction check. For framework maintenance passes that rewrite
+	* many rows with bounded memory — e.g. media eviction (#1710) — where the
+	* per-row full-history estimate would reintroduce the memory pressure the
+	* pass exists to remove. The message-change listener still fires so a
+	* cache-owning host stays coherent. Application code should use
+	* `updateMessage`.
+	*/
+	async internal_rewriteMessage(message) {
+		await this._ensureRestored();
+		await this.storage.updateMessage(message);
+		await this._notifyMessagesChanged({
+			type: "update",
+			message
+		});
+	}
 	async deleteMessages(messageIds) {
 		await this._ensureRestored();
 		await this.storage.deleteMessages(messageIds);
@@ -1452,12 +1655,14 @@ var Session = class Session {
 			const key = this._sessionId ? `${label}_${this._sessionId}` : label;
 			provider = new AgentContextProvider(this._agent, key);
 		}
-		return this.context.addBlock({
+		const block = await this.context.addBlock({
 			label,
 			description: opts.description,
 			maxTokens: opts.maxTokens,
 			provider
 		});
+		if (block.isSkill && !this._skillScanRan) await this._scanHistoryForLoadedSkills();
+		return block;
 	}
 	/**
 	* Remove a dynamically registered context block.