@harperfast/harper 5.2.0 → 5.2.1

package/resources/analytics/write.ts

@@ -397,26 +397,28 @@ function storeDBSizeMetrics(analyticsTable: Table, databases: Databases) {
 	}
 }
 
-function storeVolumeMetrics(analyticsTable: Table, databases: Databases) {
-	for (const [db, tables] of Object.entries(databases)) {
-		try {
-			const [firstTable] = Object.values(tables);
-			const storageStats = firstTable?.getStorageStats();
-			if (!storageStats) {
-				continue;
+async function storeVolumeMetrics(analyticsTable: Table, databases: Databases) {
+	await Promise.all(
+		Object.entries(databases).map(async ([db, tables]) => {
+			try {
+				const [firstTable] = Object.values(tables);
+				const storageStats = await firstTable?.getStorageStats();
+				if (!storageStats) {
+					return;
+				}
+				const metric = {
+					metric: METRIC.STORAGE_VOLUME,
+					database: db,
+					...storageStats,
+				};
+				storeMetric(analyticsTable, metric);
+				log.trace?.(`db ${db} storage volume metrics: ${JSON.stringify(metric)}`);
+			} catch (error) {
+				// a table or db was deleted, could get an error here
+				log.warn?.(`Error getting DB volume metrics`, error);
 			}
-			const metric = {
-				metric: METRIC.STORAGE_VOLUME,
-				database: db,
-				...storageStats,
-			};
-			storeMetric(analyticsTable, metric);
-			log.trace?.(`db ${db} storage volume metrics: ${JSON.stringify(metric)}`);
-		} catch (error) {
-			// a table or db was deleted, could get an error here
-			log.warn?.(`Error getting DB volume metrics`, error);
-		}
-	}
+		})
+	);
 }
 
 // RocksDB stat names are kebab-case with a "rocksdb." prefix (e.g. "rocksdb.block.cache.hit");
@@ -1047,7 +1049,7 @@ async function aggregation(fromPeriod, toPeriod = 60000) {
 	storeDBSizeMetrics(analyticsTable, databases);
 
 	// database storage volume metrics
-	storeVolumeMetrics(analyticsTable, databases);
+	await storeVolumeMetrics(analyticsTable, databases);
 
 	// rocksdb engine stats (only for RocksDB-backed databases)
 	const rocksDBPeriod = lastRocksDBStatsTime ? now - lastRocksDBStatsTime : undefined;

package/resources/blob.ts

@@ -55,7 +55,6 @@ type StorageInfo = {
 	recordId?: number;
 	contentBuffer?: any;
 	source?: Readable;
-	storageBuffer?: Buffer;
 	compress?: boolean;
 	flush?: boolean;
 	start?: number;
@@ -829,7 +828,7 @@ class FileBackedBlob extends (Blob as unknown as { new (): Blob }) implements Bl
 			storageInfoForBlob.set(slicedBlob, slicedStorageInfo);
 			if (this.size != undefined)
 				slicedBlob.size = (end == undefined ? this.size : Math.min(end, this.size)) - (start ?? 0);
-		} else if (sourceStorageInfo?.contentBuffer && !sourceStorageInfo.storageBuffer) {
+		} else if (sourceStorageInfo?.contentBuffer) {
 			const slicedStorageInfo = {
 				...sourceStorageInfo,
 				contentBuffer: sourceStorageInfo.contentBuffer.subarray(start, end),
@@ -1340,8 +1339,11 @@ function getNextStorageIndex(blobStoragePaths: string[], fileId: number) {
 	}
 	if (((blobStoragePaths as any).lastUpdated ?? 0) + 60000 < now) {
 		(blobStoragePaths as any).lastUpdated = now;
-		// create a new frequency table based on the available space
-		createFrequencyTableForStoragePaths(blobStoragePaths);
+		// create a new frequency table based on the available space; fire-and-forget, so a
+		// transient stat/mkdir failure must not become an unhandled rejection
+		createFrequencyTableForStoragePaths(blobStoragePaths).catch((error) => {
+			logger.warn?.('Error creating storage path frequency table', error);
+		});
 	}
 	const nextIndex = (blobStoragePaths as any).frequencyTable[fileId % FREQUENCY_TABLE_SIZE];
 	return nextIndex;
@@ -1356,6 +1358,10 @@ async function createFrequencyTableForStoragePaths(blobStoragePaths: string[]) {
 	if (!statfs) return; // statfs is not available on all older node versions
 	const availableSpaces = await Promise.all(
 		blobStoragePaths.map(async (path) => {
+			// This compares MULTIPLE distinct paths against each other, so it always needs the
+			// real per-path number: quota-status.json (see getStorageSpaceStats, #1976) is a
+			// single instance-wide figure that can't tell two disks apart, and would collapse
+			// every path in a multi-volume STORAGE_BLOBPATHS config to the same "available" value.
 			let stats: StatsFs;
 			try {
 				stats = await statfs(path);
@@ -1733,10 +1739,14 @@ addExtension({
 				throw new Error('No store specified, cannot load blob from storage');
 			}
 		} else {
+			// contentBuffer is a *copy* (copyingUnpacker uses copyBuffers), so it stays valid for the
+			// lifetime of the blob. Do not retain the raw ext-body `buffer` here: it is a view into the
+			// store's read buffer, which is recycled by later reads. Keeping it and re-emitting it on
+			// re-encode (e.g. a read-modify-write / REST PATCH) serialized whatever foreign bytes had
+			// since overwritten that buffer, corrupting the record (harper#2103).
 			storageInfoForBlob.set(blob, {
 				storageIndex: 0,
 				fileId: null,
-				storageBuffer: buffer as any,
 				contentBuffer: blobInfo[1] as any,
 			});
 			blob.size = blobInfo[1]?.length;
@@ -1757,9 +1767,6 @@ addExtension({
 		if (blob.type) options.type = blob.type;
 		if (blob.size !== undefined) options.size = blob.size;
 		if (storageInfo) {
-			if (storageInfo.storageBuffer) {
-				return storageInfo.storageBuffer;
-			}
 			if (
 				storageInfo.contentBuffer &&
 				(storageInfo.contentBuffer?.length < FILE_STORAGE_THRESHOLD || blob.saveInRecord)

package/resources/databases.ts

@@ -33,7 +33,7 @@ import { handleLocalTimeForGets } from './RecordEncoder.ts';
 import { deleteRootBlobPathsForDB } from './blob.ts';
 import { CUSTOM_INDEXES } from './indexes/customIndexes.ts';
 import { OpenDBIObject } from '../utility/lmdb/OpenDBIObject.ts';
-import { RocksDatabase, type RocksDatabaseOptions } from '@harperfast/rocksdb-js';
+import { RocksDatabase, supportedCompression, type RocksDatabaseOptions } from '@harperfast/rocksdb-js';
 import { PrimaryRocksDatabase } from './PrimaryRocksDatabase.ts';
 import { replayLogs } from './replayLogs.ts';
 import { totalmem } from 'node:os';
@@ -98,6 +98,80 @@ const DEFAULT_DATABASE_NAME = 'data';
 const DEFINED_TABLES = Symbol('defined-tables');
 const DEFAULT_COMPRESSION_THRESHOLD = (envGet(CONFIG_PARAMS.STORAGE_PAGESIZE) || 4096) - 60; // larger than this requires multiple pages
 initSync();
+/**
+ * The RocksDB block/blob codec for every column family this process opens (`storage.rocks.compression`),
+ * or `undefined` to leave rocksdb-js on its own default (lz4 wherever the native build has it).
+ *
+ * Resolved on the first open and then frozen, deliberately. RocksDB fixes a column family's codec
+ * for as long as it is open and rejects a reopen that disagrees, and Harper's worker threads share
+ * one process-wide column-family registry — so every open, in every thread, has to resolve the same
+ * value. Re-reading config per open does not guarantee that: on a fresh install the system families
+ * are created by `mountHdb()` before the config file exists, so the main thread would resolve
+ * nothing and the workers would resolve the configured codec, after which `__dbis__` cannot be
+ * reopened and Harper fails with "The system database failed to load". The installer stages this
+ * value before `mountHdb()` (see utility/install/installer.ts) so that first open already sees it.
+ *
+ * Unset is NOT "use the build default" for a family that already exists — see toRocksCompression.
+ */
+let resolvedRocksCompression: string | undefined;
+let rocksCompressionResolved = false;
+
+export function getRocksCompression(): string | undefined {
+	if (!rocksCompressionResolved) {
+		resolvedRocksCompression = readDatabaseCodec();
+		rocksCompressionResolved = true;
+	}
+	return resolvedRocksCompression;
+}
+
+/**
+ * Test-only: un-freezes the resolved codec. Production code never calls this — the freeze is the
+ * invariant (see getRocksCompression above) — but a test process runs many unrelated test files in
+ * one process, so whichever file happens to open a RocksDatabase first freezes this for everyone
+ * after it. Tests that need to exercise config changes call this to get back to the unresolved state.
+ */
+export function resetRocksCompression(): void {
+	resolvedRocksCompression = undefined;
+	rocksCompressionResolved = false;
+}
+
+/**
+ * The codec every column family in this process opens under.
+ *
+ * Compression is a deployment setting, not a per-table one. RocksDB opens all of a database's
+ * column families in one call, so the codec has to be decided before the first open — which is
+ * before Harper has read any table's metadata (that catalog is itself one of the families being
+ * opened). Resolving one codec from configuration and applying it to every family is what makes
+ * that possible; it is passed with `compressionForAllColumnFamilies` so families this process
+ * never names individually adopt it too, which is what lets a database created before the codec
+ * existed start compressing.
+ *
+ * `storage.rocks.compression` names a codec outright. Otherwise `storage.compression` (default
+ * true) decides enabled-or-not and the build default fills in the algorithm. Per-table metadata
+ * still records the LMDB-era boolean, but no longer selects: a table persisted as disabled inside
+ * a deployment that enables compression would need its own codec, and it cannot have one.
+ */
+function readDatabaseCodec(): string | undefined {
+	const explicit = readRocksCompressionConfig();
+	if (explicit) return explicit;
+	return toRocksCompression(getDefaultCompression()) as string | undefined;
+}
+
+function readRocksCompressionConfig(): string | undefined {
+	const configured = envGet(CONFIG_PARAMS.STORAGE_ROCKS_COMPRESSION);
+	if (configured === undefined || configured === null || configured === '') return undefined;
+	const requested = String(configured).trim().toLowerCase();
+	if (!requested) return undefined;
+	// Rejected here rather than at the open: an unsupported name throws inside RocksDatabase.open,
+	// which surfaces as the system database failing to load partway through startup.
+	if (!supportedCompression.includes(requested)) {
+		throw new Error(
+			`storage.rocks.compression="${requested}" is not available in this build of @harperfast/rocksdb-js. Supported: ${supportedCompression.join(', ')}`
+		);
+	}
+	return requested;
+}
+
 // I don't know if this is the best place for this, but somewhere we need to specify which tables
 // replicate by default:
 export const NON_REPLICATING_SYSTEM_TABLES = [
@@ -177,22 +251,51 @@ export const tables: Tables = Object.create(null);
 export const databases: Databases = Object.create(null);
 
 /**
- * Map a persisted (LMDB-era) compression value to what rocksdb-js accepts. Table metadata
- * carries values where a defined falsy value (false, '') means compression was explicitly
- * disabled and true/{ threshold, ... } mean enabled with defaults. rocksdb-js >= 2.6
- * validates `compression` strictly and treats UNSET as "use the build default (lz4)", so
- * disabled must be mapped to 'none' explicitly, and true to unset.
+ * Codec used to honor an "enabled, unspecified" compression setting, or `undefined` where the
+ * native build cannot provide it (in which case the request degrades to the build default rather
+ * than throwing).
+ */
+const DEFAULT_ENABLED_CODEC = supportedCompression.includes('lz4') ? 'lz4' : undefined;
+
+/**
+ * Map a persisted (LMDB-era) compression value to what rocksdb-js accepts. Table metadata carries
+ * values where a defined falsy value (false, '') means compression was explicitly disabled, and
+ * `true` / `{ threshold, ... }` mean enabled with defaults — `storage.compression` defaults to
+ * `true` (defaultConfig.yaml), so essentially every pre-existing table asked for compression.
+ *
+ * "Enabled" resolves to an explicit codec rather than to unset. Unset is not equivalent: RocksDB
+ * persists the codec per column family and a reopen that requests nothing inherits what the family
+ * already has, applying the build default only when the family does not yet exist. Leaving these
+ * unset therefore silently ignores the operator's request on every database created before the
+ * native build carried codecs — it keeps writing uncompressed forever, while a brand-new database
+ * gets lz4. Naming the codec makes the setting mean the same thing in both cases.
+ *
+ * This governs newly written files; existing SSTs keep their codec until write traffic rewrites
+ * them (`db.compact()` will not — see getRocksCompression above).
  */
 export function toRocksCompression(compression: unknown): unknown {
-	if (compression === true) return undefined;
-	if (compression !== undefined && !compression) return 'none';
+	if (compression === undefined) return undefined;
+	if (!compression) return 'none';
+	// An object carrying an explicit `algorithm` is already a rocksdb-js request; anything else
+	// (`true`, or an LMDB descriptor like { startingOffset, threshold }) is "enabled, unspecified".
+	if (compression === true || (typeof compression === 'object' && !(compression as { algorithm?: unknown }).algorithm))
+		return DEFAULT_ENABLED_CODEC;
 	return compression;
 }
 
 function openRocksDatabase(path: string, options: RocksDatabaseOptions & { dupSort?: boolean }) {
 	options.disableWAL ??= true;
 	const legacyOptions = options as { compression?: unknown };
-	legacyOptions.compression = toRocksCompression(legacyOptions.compression);
+	// A configured codec applies to every column family, overriding whatever per-table metadata
+	// carries — that metadata records the LMDB-era boolean, so without this there is no way to
+	// select a RocksDB codec for a deployment.
+	// One codec for every column family, and applied to every family this open touches — not just
+	// the one being named. RocksDB opens them all at once and a family's codec cannot change while
+	// it is open, so a family this process never names individually would otherwise stay on
+	// whatever it was created with, forever.
+	const databaseCodec = getRocksCompression();
+	legacyOptions.compression = databaseCodec;
+	if (databaseCodec) (options as { compressionForAllColumnFamilies?: boolean }).compressionForAllColumnFamilies = true;
 	// Apply read-only mode if enabled
 	if (isReadOnlyMode()) {
 		options.readOnly = true;
@@ -588,7 +691,7 @@ function initStores(
 				...internalDbiInit,
 				disableWAL: false,
 				name: INTERNAL_DBIS_NAME,
-			} as any) as RocksDatabaseEx;
+			} as any);
 		} else {
 			attributesDbi = rootStore.openDB(INTERNAL_DBIS_NAME, internalDbiInit as any);
 		}
@@ -1350,7 +1453,11 @@ function openIndex(dbiKey: string, rootStore: RootDatabaseKind, attribute: any)
 		// Enable cache (WeakLRUCache + VT) for all custom-object index stores so the VT is
 		// available before resolveIndexFormat decides the format. Versioned stores need the VT
 		// for cached traversal; legacy stores pay a small per-write cache.delete() overhead only.
-		dbi = openRocksDatabase(rootStore.path, { ...dbiInit, name: dbiKey, cache: isCustomObjectIndex } as any) as any;
+		dbi = openRocksDatabase(rootStore.path, {
+			...dbiInit,
+			name: dbiKey,
+			cache: isCustomObjectIndex,
+		} as any) as any;
 		(dbi as any).rootStore = rootStore;
 		// Custom-index object stores (e.g. HNSW) write graph nodes via plain put() with no staged
 		// transaction timestamp, so their values carry no version and the PrimaryRocksDatabase
@@ -1573,6 +1680,10 @@ export function table<TableResourceType>(tableDefinition: TableDefinition): Tabl
 				clearInterruptedDropEntries(rootStore.path, tableName);
 			}
 			if (rootStore instanceof RocksDatabase) {
+				// Usually a genuinely new column family (existingTableMeta above found no catalog
+				// entry), but an interrupted drop just completed above can leave the physical CF
+				// behind under its old codec even though the catalog entry is gone — same fallback
+				// as the reconcile paths covers that remnant case too.
 				primaryStore = openRocksDatabase(rootStore.path, { ...dbiInit, name: dbiName, cache: true } as any);
 			} else {
 				primaryStore = (rootStore as any).openDB(dbiName, dbiInit as any);
@@ -2183,7 +2294,7 @@ function completeInterruptedDrop(rootStore, attributesDbi, databaseName: string,
 	if (rootStore instanceof RocksDatabase) {
 		for (const columnName of (rootStore as any).columns) {
 			if (columnName.startsWith(tableName + '/')) {
-				const columnStore = openRocksDatabase(rootStore.path, { name: columnName } as any);
+				const columnStore = openRocksDatabase(rootStore.path, { name: columnName });
 				try {
 					columnStore.dropSync();
 				} catch (error) {

package/resources/jsResource.ts

@@ -69,41 +69,13 @@ export class ResourceLoadError extends Error {
  *
  * Once a file has been loaded it cannot be unloaded without a restart.
  *
- * Thus, this plugin only handle files as they are added (`add` event). All other events result in a restart request.
+ * Thus, this plugin only handles files as they are added (`add` event). All other events result in a restart request.
  *
- * A redeploy tears down and reinstalls the component's files while this scope's watcher is paused
- * (see `Scope`/`EntryHandler` deploy lifecycle); on resume the fresh chokidar scan re-emits every
- * existing file as `'add'` — including ones whose contents just changed. Treating those as plain
- * adds would silently re-run against the stale module cache and never flag a restart (harper#1817).
- * So we track which files this scope has already loaded: a re-`add` of a known file is a redeploy of
- * loaded code we cannot hot-swap, and is handled like a `change` — request a restart. A first-time
- * `add` (initial load, or a genuinely new file added at runtime) still loads without a restart.
- *
- * A redeploy that *deletes* a loaded file is a different shape of the same problem: the fresh
- * chokidar scan only reports what's currently on disk, so a file that's gone produces no event at
- * all — no re-`add`, no `unlink` — and the modified-file handling above never sees it. Left
- * unhandled, the deleted resource stays registered and active in memory (harper#1817 follow-up). So
- * we also track which files the post-redeploy scan pass reports, and once that scan's `ready` fires,
- * diff it against everything this scope has ever loaded: anything missing was deleted, and is
- * handled the same way as a modified file — request a restart.
- *
- * That diff must only run for an actual redeploy rescan, not every time `EntryHandler` emits
- * `ready` — it also refires after each ordinary runtime add/change once that file's read settles
- * (its initial-scan-complete latch never resets outside a full rescan), and diffing against that
- * would falsely treat every other already-loaded file as deleted. So the diff window is gated by
- * the scope's own `deploy:start`/`deploy:end` bracket (see `Scope`): `deploy:start` pauses the
- * watcher and opens the window (and is where we reset the scan-file tracking, since no file events
- * can land while paused), and the first `ready` afterward — the resumed watcher's fresh scan
- * completing — closes it and runs the diff.
+ * EntryHandler preserves file identity across a deploy pause/resume and emits `change` or `unlink`
+ * for loaded files that changed or disappeared, so those events request the required restart.
  */
 export async function handleApplication(scope: Scope) {
-	const loadedResourceFiles = new Set<string>();
-	// Files reported as `add` since the most recent `deploy:start`, populated only while
-	// `awaitingPostRedeployScan` is true — see the gating note above.
-	let currentScanFiles = new Set<string>();
-	let awaitingPostRedeployScan = false;
-
-	const entryHandler = scope.handleEntry(async function handleResourceEntry(entryEvent) {
+	scope.handleEntry(async function handleResourceEntry(entryEvent) {
 		if (entryEvent.entryType !== 'file') {
 			scope.logger.warn(
 				`jsResource plugin cannot handle entry type ${entryEvent.entryType}. Modify the 'files' option in ${scope.configFilePath} to only include files.`
@@ -111,13 +83,7 @@ export async function handleApplication(scope: Scope) {
 			return;
 		}
 
-		if (awaitingPostRedeployScan && entryEvent.eventType === 'add') {
-			// Recorded unconditionally — before the loaded/re-add branch below — so the post-scan
-			// deletion diff sees every file this scan reported, whether newly loaded or already known.
-			currentScanFiles.add(entryEvent.absolutePath);
-		}
-
-		if (entryEvent.eventType !== 'add' || loadedResourceFiles.has(entryEvent.absolutePath)) {
+		if (entryEvent.eventType !== 'add') {
 			scope.requestRestart();
 			return;
 		}
@@ -133,9 +99,6 @@ export async function handleApplication(scope: Scope) {
 				scope.logger.debug?.(`Registered root resource: ${path}`);
 			}
 			recurseForResources(scope, resourceModule, root);
-			// Record the load so a later re-`add` of this same file (a redeploy re-scan) is treated
-			// as a change and requests a restart rather than silently re-serving stale cached code.
-			loadedResourceFiles.add(entryEvent.absolutePath);
 			// A JS resource that extends an exported @table is the one carrying author opt-ins
 			// (`static mcpTools`/`mcpPrompts`), and it registers here — after the schema-derived
 			// table class and after the MCP component's boot scan. Signal so listing surfaces
@@ -146,26 +109,6 @@ export async function handleApplication(scope: Scope) {
 			throw new ResourceLoadError(entryEvent.absolutePath, error);
 		}
 	});
-
-	// Optional chaining: a mock/test scope may not implement EventEmitter, and Scope#handleEntry
-	// itself can return undefined (e.g. MissingDefaultFilesOptionError). In real use `scope` is
-	// always an EventEmitter and `entryHandler` is always the EntryHandler backing this watcher.
-	scope.on?.('deploy:start', () => {
-		awaitingPostRedeployScan = true;
-		currentScanFiles = new Set();
-	});
-
-	entryHandler?.on?.('ready', () => {
-		if (!awaitingPostRedeployScan) return;
-		awaitingPostRedeployScan = false;
-		for (const loadedFile of loadedResourceFiles) {
-			if (!currentScanFiles.has(loadedFile)) {
-				// Known file that the just-completed scan never reported — deleted during the redeploy.
-				loadedResourceFiles.delete(loadedFile);
-				scope.requestRestart();
-			}
-		}
-	});
 }
 
 function recurseForResources(scope: Scope, resourceModule: any, prefix: string) {

package/resources/models/Models.ts

@@ -91,6 +91,19 @@ export class Models implements ModelsContract {
 	}
 
 	async embed(input: string | string[], opts: EmbedOpts = {}): Promise<Float32Array[]> {
+		return (await this.embedWithUsage(input, opts)).vectors;
+	}
+
+	/**
+	 * `embed()` plus the result-level `usage` the winning backend reported (all
+	 * built-in embedding backends provide it). Internal path for callers that must
+	 * surface usage on the wire — the `/v1/embeddings` gateway — without changing
+	 * the public `embed()` contract. Not part of the stable models API.
+	 */
+	async embedWithUsage(
+		input: string | string[],
+		opts: EmbedOpts = {}
+	): Promise<{ vectors: Float32Array[]; usage?: TokenUsage }> {
 		const { accounting, signal } = resolveCallContext(opts.signal);
 		const startedAt = performance.now();
 		const resolved = resolveCandidates('embedding', opts.model, buildRequires('embed', opts.requires, false));
@@ -118,7 +131,7 @@ export class Models implements ModelsContract {
 				// success row followed by a failure row from the catch (duplicate).
 				if (result.status !== 'completed') throw new ModelPendingNotSupportedError(backend.name);
 				this.#record(backend, 'embed', opts.model, accounting, undefined, result, attemptStart);
-				return result.output;
+				return { vectors: result.output, usage: result.usage };
 			} catch (err) {
 				this.#recordFailure(backend, 'embed', opts.model, accounting, undefined, attemptStart, err);
 				if (!hasError) {

package/resources/models/backendRegistry.ts

@@ -39,6 +39,16 @@ export function getBackend(kind: ModelKind, logicalName: string): ModelBackend |
 	return (kind === 'embedding' ? embedding : generative).get(logicalName);
 }
 
+/**
+ * Enumerate all registrations for `kind` as `{logicalName, backend}` pairs. Used by
+ * `GET /v1/models` (#631) to advertise selectable model names; `logicalName` is what a
+ * caller passes as `opts.model`, not the backend's own `.name`.
+ */
+export function listBackends(kind: ModelKind): Array<{ logicalName: string; backend: ModelBackend }> {
+	const map = kind === 'embedding' ? embedding : generative;
+	return [...map.entries()].map(([logicalName, backend]) => ({ logicalName, backend }));
+}
+
 /**
  * Resolve the embedding backend mapped to `logicalName` (default: `'default'`).
  * Throws `ModelBackendNotFoundError` if no backend is mapped.

package/resources/models/openaiStream.ts

@@ -21,6 +21,68 @@ export interface OpenAIStreamOptions {
 	model?: string;
 	/** Reuse a caller-supplied completion id across all chunks; one is generated when omitted. */
 	id?: string;
+	/**
+	 * Map a mid-stream backend error to an OpenAI error body for a final `data: {error}`
+	 * SSE frame. Lets the v1 gateway reuse its `toOpenAIError` mapping without this generic
+	 * formatter depending on the v1 layer. When omitted, a generic server_error body is emitted.
+	 */
+	formatError?: (err: unknown) => OpenAIErrorFrameBody;
+}
+
+// Bounds on per-stream tool-call assembly. The backend supplies both the call ids and the
+// argument fields, and this runs on a public HTTP path, so neither can be unbounded. Overflow
+// terminates the stream through the same sanitized error-frame path as any backend failure.
+const MAX_TOOL_CALLS_PER_STREAM = 256;
+const MAX_TOOL_ARGUMENT_KEYS = 1024;
+// Cumulative serialized-character budget across the WHOLE stream's assembly (ids, names,
+// and every argument value as it arrives, plus per-entry JSON syntax so the count is an
+// upper bound on `JSON.stringify(arguments)`, not just the raw content). Call/key counts
+// alone don't bound memory — one key can hold an arbitrarily large value, and the final
+// JSON.stringify duplicates the retained allocation — so the budget is charged per delta
+// (O(delta), no re-serialization of the accumulator) and monotonically: replacing an
+// existing key charges the new value too, so churn cannot smuggle unbounded values under
+// a stable key count. The SSE frame that flushes the calls adds only a bounded constant
+// envelope per call plus string-escaping of the arguments blob (< 2x), so the frame size
+// is bounded by a small multiple of this budget.
+const MAX_TOOL_ASSEMBLY_CHARS = 1_048_576;
+
+/** Signals that a stream exceeded the tool-assembly bounds; surfaced as an SSE error frame. */
+class ToolAssemblyOverflowError extends Error {
+	statusCode = 502;
+}
+
+/**
+ * Merge `source` into `target`, returning the keys added and the serialized characters
+ * charged. Charging over-approximates `JSON.stringify(target).length`: each first add
+ * charges the key plus 4 chars of JSON syntax (`"key":` quotes and colon, plus the
+ * comma/brace share), and every assignment — replacements included — charges the
+ * serialized value. Since a replacement's earlier charge is never refunded, the
+ * cumulative total stays an upper bound on the retained serialization while keeping
+ * accumulation O(delta), not O(total).
+ */
+function assignCountingNewKeys(target: object, source: object): { addedKeys: number; addedChars: number } {
+	let addedKeys = 0;
+	let addedChars = 0;
+	for (const key in source) {
+		if (!(key in target)) {
+			addedKeys++;
+			addedChars += key.length + 4;
+		}
+		const value = (source as Record<string, unknown>)[key];
+		// `?? ''`: JSON.stringify returns undefined for undefined/function/symbol values —
+		// impossible from JSON.parse but reachable from a custom backend's crafted object.
+		addedChars += (JSON.stringify(value) ?? '').length;
+		(target as Record<string, unknown>)[key] = value;
+	}
+	return { addedKeys, addedChars };
+}
+
+/** OpenAI streaming error body (`{ message, type, code, param }` under an `error` key). */
+export interface OpenAIErrorFrameBody {
+	message: string;
+	type: string;
+	code: string | null;
+	param: string | null;
 }
 
 interface OpenAIToolCallDelta {
@@ -46,7 +108,7 @@ interface OpenAIChunk {
 
 /** SSE message envelope consumed by Harper's `text/event-stream` serializer. */
 export interface OpenAIStreamMessage {
-	data: OpenAIChunk | string;
+	data: OpenAIChunk | { error: OpenAIErrorFrameBody } | string;
 }
 
 /**
@@ -71,7 +133,8 @@ export async function* openaiStream(
 	// Emitting incremental fragments would corrupt the OpenAI client's concatenation
 	// (`{"a":1}` + `{"b":2}` → invalid JSON) — Harper's already-buffered upstream model
 	// means we cannot faithfully reproduce per-token argument fragments anyway.
-	const toolAssembly = new Map<string, { index: number; name?: string; arguments: object }>();
+	const toolAssembly = new Map<string, { index: number; name?: string; arguments: object; argumentCount: number }>();
+	let assemblyChars = 0;
 
 	const chunk = (delta: OpenAIDelta, finish: OpenAIFinishReason | null): OpenAIStreamMessage => ({
 		data: {
@@ -83,26 +146,75 @@ export async function* openaiStream(
 		},
 	});
 
-	for await (const token of tokens) {
-		if (token.deltaContent !== undefined) {
-			const delta: OpenAIDelta = {};
-			if (!roleSent) {
-				delta.role = 'assistant';
-				roleSent = true;
+	try {
+		for await (const token of tokens) {
+			if (token.deltaContent !== undefined) {
+				const delta: OpenAIDelta = {};
+				if (!roleSent) {
+					delta.role = 'assistant';
+					roleSent = true;
+				}
+				delta.content = token.deltaContent;
+				yield chunk(delta, null);
 			}
-			delta.content = token.deltaContent;
-			yield chunk(delta, null);
-		}
-		if (token.deltaToolCalls) {
-			for (const incoming of token.deltaToolCalls) {
-				if (!incoming.id) continue;
-				const existing = toolAssembly.get(incoming.id) ?? { index: toolAssembly.size, arguments: {} };
-				if (incoming.name) existing.name = incoming.name;
-				if (incoming.arguments) existing.arguments = { ...existing.arguments, ...incoming.arguments };
-				toolAssembly.set(incoming.id, existing);
+			if (token.deltaToolCalls) {
+				for (const incoming of token.deltaToolCalls) {
+					if (!incoming.id) continue;
+					let existing = toolAssembly.get(incoming.id);
+					if (!existing) {
+						// Cap distinct calls per stream: ids come from the backend, and an
+						// unbounded map on a public HTTP path is a memory risk.
+						if (toolAssembly.size >= MAX_TOOL_CALLS_PER_STREAM) {
+							throw new ToolAssemblyOverflowError(`stream exceeded ${MAX_TOOL_CALLS_PER_STREAM} tool calls`);
+						}
+						// Null-prototype: arguments come from JSON.parse, so a field literally
+						// named `__proto__` is an own property. Object.assign uses [[Set]], which
+						// on an ordinary object would hit Object.prototype's inherited `__proto__`
+						// setter and silently drop the field (the previous spread did not).
+						existing = { index: toolAssembly.size, arguments: Object.create(null), argumentCount: 0 };
+						toolAssembly.set(incoming.id, existing);
+						// + 96: the flush frame's fixed per-call envelope (index/id/type/function
+						// syntax and the argument object's braces), so 256 calls of envelope are
+						// inside the budget too, not on top of it.
+						assemblyChars += incoming.id.length + 96;
+					}
+					if (incoming.name && incoming.name !== existing.name) {
+						assemblyChars += incoming.name.length;
+						existing.name = incoming.name;
+					}
+					// Guard the contract (`ToolCall.arguments` is an object): a string would be
+					// assigned index-wise, inflating the field count from characters.
+					if (incoming.arguments && typeof incoming.arguments === 'object') {
+						// Mutate rather than re-spread — spreading copied every previously
+						// accumulated property on each partial delta (O(n²) as fields grow) — and
+						// count only newly-introduced keys so the bound check stays O(delta) too.
+						const { addedKeys, addedChars } = assignCountingNewKeys(existing.arguments, incoming.arguments);
+						existing.argumentCount += addedKeys;
+						assemblyChars += addedChars;
+						if (existing.argumentCount > MAX_TOOL_ARGUMENT_KEYS) {
+							throw new ToolAssemblyOverflowError(`tool call arguments exceeded ${MAX_TOOL_ARGUMENT_KEYS} fields`);
+						}
+					}
+					if (assemblyChars > MAX_TOOL_ASSEMBLY_CHARS) {
+						throw new ToolAssemblyOverflowError(
+							`stream tool-call assembly exceeded ${MAX_TOOL_ASSEMBLY_CHARS} serialized characters`
+						);
+					}
+				}
 			}
+			if (token.finishReason) finishReason = token.finishReason;
 		}
-		if (token.finishReason) finishReason = token.finishReason;
+	} catch (err) {
+		// The backend can throw partway through the stream (Models#wrapStream re-throws
+		// mid-stream backend errors). Headers/200 are already flushed, so this can't be an
+		// HTTP error status — emit a final OpenAI-shaped `data: {error}` frame so SDK clients
+		// see a parseable error (matching the non-streaming path) instead of an abrupt socket
+		// close. OpenAI terminates the stream on error and sends no `[DONE]`, so we do the same.
+		const error = opts.formatError
+			? opts.formatError(err)
+			: { message: 'Internal server error', type: 'server_error', code: null, param: null };
+		yield { data: { error } };
+		return;
 	}
 
 	if (toolAssembly.size > 0) {