@namzu/sdk 60.1.0 → 60.2.0

package/src/store/session-log/core.ts

@@ -211,8 +211,59 @@ export interface SessionLog {
 	/** The folded conversation (spec §4.5), spills read back. */
 	messages(options?: { readonly throughSeq?: number }): Promise<Message[]>
 	readSpill(ref: SpillRef, options?: SpillReadOptions): Promise<string>
+	/**
+	 * Be told when the log stops being able to write (the disk is full) and
+	 * when it can write again. Returns the function that stops the
+	 * notifications. A log that cannot degrade does not offer this.
+	 */
+	onWriteHealth?(listener: (change: SessionLogWriteHealth) => void): () => void
+}
+
+/** Why a log's writes are failing; each is a full or unwritable volume. */
+export type SessionLogDegradedCause = 'disk_full' | 'quota_exceeded' | 'read_only'
+
+/**
+ * A change in whether a log can write. While `degraded` the session goes on
+ * in memory and the records not yet written wait in a bounded buffer.
+ */
+export type SessionLogWriteHealth =
+	| {
+			readonly state: 'degraded'
+			readonly cause: SessionLogDegradedCause
+			/** Records waiting to be written, including the one that failed. */
+			readonly bufferedRecords: number
+			readonly bufferedBytes: number
+			/**
+			 * Set on the one notification sent when the buffer first overflowed
+			 * and the oldest waiting records were discarded.
+			 */
+			readonly dropping?: true
+	  }
+	| {
+			readonly state: 'recovered'
+			/** Records written from the buffer, in order. */
+			readonly flushedRecords: number
+			/** Records discarded while the buffer was full; the log has a gap where they were. */
+			readonly droppedRecords: number
+	  }
+
+/** The cause when `error` is the volume refusing writes, else `undefined`. */
+export function sessionLogDegradedCause(error: unknown): SessionLogDegradedCause | undefined {
+	switch ((error as NodeJS.ErrnoException | undefined)?.code) {
+		case 'ENOSPC':
+			return 'disk_full'
+		case 'EDQUOT':
+			return 'quota_exceeded'
+		case 'EROFS':
+			return 'read_only'
+		default:
+			return undefined
+	}
 }
 
+/** Default bound on records held in memory while a log cannot write. */
+export const DEFAULT_DEGRADED_BUFFER_BYTES = 8 * 1024 * 1024
+
 /** A draft that is not a valid session record once enveloped. */
 export class InvalidSessionRecordError extends Error {
 	override readonly name = 'InvalidSessionRecordError'
@@ -271,6 +322,12 @@ export interface SessionLogCoreOptions {
 	 * and decisions. `all` or `none` as named.
 	 */
 	readonly sync?: 'boundaries' | 'all' | 'none'
+	/**
+	 * Bytes of records kept in memory while the volume refuses writes (full,
+	 * over quota, read-only). Past it the oldest are discarded. Default
+	 * {@link DEFAULT_DEGRADED_BUFFER_BYTES}.
+	 */
+	readonly degradedBufferBytes?: number
 }
 
 const BOUNDARY_TYPES: ReadonlySet<string> = new Set([
@@ -289,6 +346,8 @@ const BOUNDARY_TYPES: ReadonlySet<string> = new Set([
 
 /** Characters of a spilled message kept inline as its preview. */
 const PREVIEW_CHARS = 2000
+/** Added to a preview whose full body could not be written. */
+const NOT_SAVED_NOTE = '[… the rest of this output could not be saved: the disk is full]'
 /** Default byte bound above which a `compaction` record's summary is spilled. */
 const COMPACTION_SPILL_ABOVE_BYTES = 256 * 1024
 
@@ -339,6 +398,17 @@ export class SessionLogCore implements SessionLog {
 	/** Bytes of the log this instance has verified and applied. */
 	#synced = 0
 	#torn = 0
+	readonly #degradedBufferBytes: number
+	/** Records accepted into the chain that the medium has not taken yet, oldest first. */
+	#pending: { readonly bytes: Buffer; readonly sync: boolean }[] = []
+	#pendingBytes = 0
+	/** Bytes the medium holds while records are pending. */
+	#diskBytes = 0
+	#degradedCause: SessionLogDegradedCause | undefined
+	#droppedRecords = 0
+	#droppedNoticeSent = false
+	#flushedWhileDegraded = 0
+	readonly #healthListeners = new Set<(change: SessionLogWriteHealth) => void>()
 
 	constructor(options: SessionLogCoreOptions) {
 		this.sessionId = options.sessionId
@@ -362,12 +432,40 @@ export class SessionLogCore implements SessionLog {
 			this.#spillAbove,
 		)
 		this.#sync = options.sync ?? 'boundaries'
+		this.#degradedBufferBytes = Math.max(
+			0,
+			options.degradedBufferBytes ?? DEFAULT_DEGRADED_BUFFER_BYTES,
+		)
+	}
+
+	onWriteHealth(listener: (change: SessionLogWriteHealth) => void): () => void {
+		this.#healthListeners.add(listener)
+		return () => {
+			this.#healthListeners.delete(listener)
+		}
+	}
+
+	#notify(change: SessionLogWriteHealth): void {
+		for (const listener of this.#healthListeners) {
+			try {
+				listener(change)
+			} catch {
+				// A listener that throws must not turn a survived write into a failed one.
+			}
+		}
+	}
+
+	/** True while records wait in memory because the volume refuses writes. */
+	get degraded(): boolean {
+		return this.#degradedCause !== undefined
 	}
 
 	// ── state ──
 
 	/** Catch up with the medium: verify and apply whatever was appended since the last sync. */
 	async #catchUp(): Promise<void> {
+		// Records waiting for the disk are ahead of it; the lease keeps others out.
+		if (this.#pending.length > 0) return
 		const size = await this.#medium.size()
 		if (size === this.#synced + this.#torn && size >= this.#synced) return
 		if (size < this.#synced) this.#reset()
@@ -395,6 +493,8 @@ export class SessionLogCore implements SessionLog {
 		this.#turns = new SessionTurnState()
 		this.#synced = 0
 		this.#torn = 0
+		this.#pending = []
+		this.#pendingBytes = 0
 	}
 
 	async #requireCurrent(lease: SessionLease): Promise<void> {
@@ -461,6 +561,8 @@ export class SessionLogCore implements SessionLog {
 	 */
 	release(lease: SessionLease): Promise<void> {
 		return this.#mutex.run(async () => {
+			// One last try to save what the disk refused earlier.
+			if (this.#pending.length > 0) await this.#flushPending().catch(() => undefined)
 			if (this.#held?.fence === lease.fence) {
 				this.#held = undefined
 				untrackHeldSessionLease(this.#holding)
@@ -655,13 +757,126 @@ export class SessionLogCore implements SessionLog {
 		}
 		const bytes = Buffer.from(line, 'utf8')
 		const sync = this.#sync === 'all' || (this.#sync === 'boundaries' && BOUNDARY_TYPES.has(type))
-		await this.#medium.append(bytes, this.#synced, sync)
+		await this.#persist(bytes, sync)
 		const entry = this.#chain.accept(bytes, this.#synced)
 		this.#turns.apply(entry.record)
 		this.#synced += bytes.byteLength
 		return entry
 	}
 
+	/**
+	 * Hand a record's bytes to the medium. A volume that refuses writes (full,
+	 * over quota, read-only) does not fail the record: it waits in a bounded
+	 * buffer and goes out, in order, with the next record that can be written.
+	 * Any other error is thrown as before. Caller holds the mutex.
+	 */
+	async #persist(bytes: Buffer, sync: boolean): Promise<void> {
+		if (this.#pending.length === 0) {
+			try {
+				await this.#medium.append(bytes, this.#synced, sync)
+				return
+			} catch (error) {
+				const cause = sessionLogDegradedCause(error)
+				if (cause === undefined) throw error
+				this.#diskBytes = this.#synced
+				this.#degradedCause = cause
+				this.#bufferRecord(bytes, sync)
+				this.#notify({
+					state: 'degraded',
+					cause,
+					bufferedRecords: this.#pending.length,
+					bufferedBytes: this.#pendingBytes,
+				})
+				return
+			}
+		}
+		const queued = this.#bufferRecord(bytes, sync)
+		try {
+			await this.#flushPending()
+		} catch (error) {
+			// Only the volume refusing writes keeps the session going; anything else
+			// fails this record, which must then not stay queued.
+			if (sessionLogDegradedCause(error) === undefined) {
+				const at = this.#pending.indexOf(queued)
+				if (at !== -1) {
+					this.#pending.splice(at, 1)
+					this.#pendingBytes -= queued.bytes.byteLength
+				}
+				throw error
+			}
+		}
+	}
+
+	#bufferRecord(bytes: Buffer, sync: boolean): { readonly bytes: Buffer; readonly sync: boolean } {
+		const queued = { bytes, sync }
+		this.#pending.push(queued)
+		this.#pendingBytes += bytes.byteLength
+		let dropped = false
+		// The newest record always stays, whatever the bound.
+		while (this.#pendingBytes > this.#degradedBufferBytes && this.#pending.length > 1) {
+			const oldest = this.#pending.shift()
+			if (oldest === undefined) break
+			this.#pendingBytes -= oldest.bytes.byteLength
+			this.#droppedRecords += 1
+			dropped = true
+		}
+		if (dropped && !this.#droppedNoticeSent && this.#degradedCause !== undefined) {
+			this.#droppedNoticeSent = true
+			this.#notify({
+				state: 'degraded',
+				cause: this.#degradedCause,
+				bufferedRecords: this.#pending.length,
+				bufferedBytes: this.#pendingBytes,
+				dropping: true,
+			})
+		}
+		return queued
+	}
+
+	/** Write the buffer in order. Throws the error that stopped it; clears the degraded mark when it empties. */
+	async #flushPending(): Promise<void> {
+		// A refused write may have left part of a record behind; cut it back.
+		const size = await this.#medium.size()
+		if (size > this.#diskBytes) await this.#medium.truncate(this.#diskBytes, size)
+		while (this.#pending.length > 0) {
+			const next = this.#pending[0]
+			if (next === undefined) break
+			await this.#medium.append(next.bytes, this.#diskBytes, next.sync)
+			this.#diskBytes += next.bytes.byteLength
+			this.#pendingBytes -= next.bytes.byteLength
+			this.#pending.shift()
+			this.#flushedWhileDegraded += 1
+		}
+		const flushed = this.#flushedWhileDegraded
+		this.#flushedWhileDegraded = 0
+		const dropped = this.#droppedRecords
+		this.#degradedCause = undefined
+		this.#droppedRecords = 0
+		this.#droppedNoticeSent = false
+		this.#pendingBytes = 0
+		this.#notify({ state: 'recovered', flushedRecords: flushed, droppedRecords: dropped })
+	}
+
+	/**
+	 * Write a message body beside the log. When the volume refuses it the body
+	 * is given up (`undefined`) rather than the record,; the record's own write
+	 * then meets the same refusal and degrades the log.
+	 */
+	async #spillOrLose(
+		key: string,
+		content: Parameters<SpillStore['write']>[1],
+		text: string,
+	): Promise<SpillRef | undefined> {
+		try {
+			return await this.#spills.write(key, content, text)
+		} catch (error) {
+			const cause = sessionLogDegradedCause(error)
+			if (cause === undefined) throw error
+			// The record's own write, next, finds the volume refusing and degrades the log.
+			return undefined
+		}
+	}
+
 	async #spillIfLarge(original: Record<string, unknown>): Promise<Record<string, unknown>> {
 		const candidate = this.#structuredResultSpilling
 			? await this.#spillStructuredResults(original)
@@ -684,11 +899,17 @@ export class SessionLogCore implements SessionLog {
 		if (size <= spillAbove) return candidate
 		if (type === 'turn_completed') {
 			if (typeof candidate.result !== 'string') return candidate
-			const ref = await this.#spills.write(
+			const ref = await this.#spillOrLose(
 				`record:${String(candidate.id)}`,
 				'message',
 				candidate.result,
 			)
+			if (ref === undefined) {
+				return {
+					...candidate,
+					result: `${candidate.result.slice(0, PREVIEW_CHARS)}\n${NOT_SAVED_NOTE}`,
+				}
+			}
 			const preview = `${candidate.result.slice(0, PREVIEW_CHARS)}\n[… ${ref.bytes} bytes spilled to ${ref.path}]`
 			return { ...candidate, result: preview, resultSpill: ref }
 		}
@@ -708,9 +929,20 @@ export class SessionLogCore implements SessionLog {
 				: type === 'message_replaced'
 					? `record:${String(candidate.id)}`
 					: `message:${String(candidate.messageId)}`
-		const ref = await this.#spills.write(key, 'message', JSON.stringify(content))
+		const ref = await this.#spillOrLose(key, 'message', JSON.stringify(content))
 		const text =
 			typeof content.content === 'string' ? content.content : JSON.stringify(content.content)
+		if (ref === undefined) {
+			// The body cannot be kept: the record carries its preview alone.
+			return {
+				...candidate,
+				content: {
+					role: content.role,
+					content: `${text.slice(0, PREVIEW_CHARS)}\n${NOT_SAVED_NOTE}`,
+					...(typeof content.toolCallId === 'string' ? { toolCallId: content.toolCallId } : {}),
+				},
+			}
+		}
 		const preview = {
 			role: content.role,
 			content: `${text.slice(0, PREVIEW_CHARS)}\n[… ${ref.bytes} bytes spilled to ${ref.path}]`,

package/src/store/session-log/disk.ts

@@ -135,7 +135,12 @@ export class DiskLogMedium implements LogMedium {
 export interface DiskSessionLogOptions
 	extends Pick<
 		SessionLogCoreOptions,
-		'now' | 'spillAboveBytes' | 'compactionSpillAboveBytes' | 'structuredResultSpilling' | 'sync'
+		| 'now'
+		| 'spillAboveBytes'
+		| 'compactionSpillAboveBytes'
+		| 'structuredResultSpilling'
+		| 'sync'
+		| 'degradedBufferBytes'
 	> {
 	readonly sessionId: SessionId
 	/** `<session-id>.jsonl`. */
@@ -174,6 +179,7 @@ export class DiskSessionLog extends SessionLogCore {
 			compactionSpillAboveBytes: options.compactionSpillAboveBytes,
 			structuredResultSpilling: options.structuredResultSpilling,
 			sync: options.sync,
+			degradedBufferBytes: options.degradedBufferBytes,
 		})
 		this.file = options.file
 		this.sessionDir = options.sessionDir

package/src/store/session-log/index.ts

@@ -21,6 +21,7 @@ export {
 	type ActiveTurnOptions,
 	type AbandonTurnLogOptions,
 	type BeginTurnOptions,
+	DEFAULT_DEGRADED_BUFFER_BYTES,
 	InvalidSessionRecordError,
 	type LogMedium,
 	type ReadSessionLogOptions,
@@ -29,10 +30,13 @@ export {
 	SessionLogConflictError,
 	SessionLogCore,
 	type SessionLogCoreOptions,
+	type SessionLogDegradedCause,
 	type SessionLogHead,
 	type SessionLogRead,
 	type SessionLogReadSummary,
+	type SessionLogWriteHealth,
 	type SessionRecordDraft,
+	sessionLogDegradedCause,
 	type TurnStartedDraft,
 	walkSessionLog,
 } from './core.js'

package/src/tools/builtins/bash-cwd.ts

@@ -18,9 +18,8 @@
 import { randomUUID } from 'node:crypto'
 import { statSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 
+import { tempFilePath } from '../../utils/temp.js'
 import { type CommandShell, hostCommandShell } from '../command-shell.js'
 import { pathOutsideRoots, toolRoots } from '../paths.js'
 import { readBoundedFile } from './bounded-file-read.js'
@@ -55,7 +54,7 @@ export function withCwdCapture(command: string, file: string): string {
 }
 
 export function newCwdFile(): string {
-	return join(tmpdir(), `namzu-cwd-${randomUUID()}`)
+	return tempFilePath(`cwd-${randomUUID()}`)
 }
 
 /** Where this session's next foreground call starts. Synchronous: the spawn must not wait on it. */

package/src/tools/builtins/read-media.ts

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process'
-import { mkdtemp, readdir, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
+import { createTempDir } from '../../utils/temp.js'
 import { readBoundedFile } from './bounded-file-read.js'
 import { screenshotTargetSize } from './computer-use-image.js'
 import { describeRaster } from './view-image.js'
@@ -254,7 +254,7 @@ export async function readPdfPages(
 		}
 		last = total === null ? PDF_WHOLE_READ_MAX_PAGES : total
 	}
-	const directory = await mkdtemp(join(tmpdir(), 'namzu-pdf-'))
+	const directory = await createTempDir('pdf-')
 	try {
 		const rendered = await renderPages(bytes, first, last, directory, signal)
 		if (!rendered.ok) return { ok: false, message: rendered.message }

package/src/turn/reporter.ts

@@ -455,6 +455,8 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 			case 'tool_calls_admitted':
 			case 'compaction_shed':
 			case 'compaction_started':
+			case 'session_log_degraded':
+			case 'session_log_recovered':
 				// Deliberately silent. The report is what a human reads about a
 				// run; replaying every shed message into it would bury the
 				// summary line that says the pass happened, in exactly the

package/src/types/hitl/index.ts

@@ -300,6 +300,14 @@ export interface ToolCallSummary {
 	 * and `strict`. A host's own handler may ignore it.
 	 */
 	skillGrant?: { readonly skill: string }
+	/**
+	 * Set when this call writes a file inside the session's own scratch folder
+	 * and nothing else about it needs a person: the folder is the session's, so
+	 * the review policy does not ask about it (outside `strict`, which asks about
+	 * everything). A rule that asked for review, a protected path and a tool's
+	 * own `requiresApproval` all keep the call in review whatever this says.
+	 */
+	scratchpadWrite?: true
 	/**
 	 * What a `pre_tool_use` hook answered about approving this call, as the
 	 * hooks reported it. `ask` is acted on by the kernel (it makes the call an

package/src/types/session/events.ts

@@ -211,6 +211,40 @@ type CoreSessionEvent =
 			/** The window the trigger measured against. */
 			contextWindowTokens: number
 	  }
+	/**
+	 * The session log can no longer write: the volume holding it is full, over
+	 * its quota or read-only. The session goes on in memory and the records not
+	 * yet written wait in a bounded buffer, so a reply is not lost, but a
+	 * restart before the log recovers would resume from an older point. Emitted
+	 * once on entering that state, and once more with `dropping` when the
+	 * buffer first overflowed and its oldest records were discarded.
+	 *
+	 * Live only, never recorded: the log is what cannot be written.
+	 */
+	| {
+			type: 'session_log_degraded'
+			sessionId: SessionId
+			turnId?: TurnId
+			cause: 'disk_full' | 'quota_exceeded' | 'read_only'
+			/** Records waiting to be written. */
+			bufferedRecords: number
+			bufferedBytes: number
+			/** The buffer overflowed and the oldest waiting records were discarded. */
+			dropping?: boolean
+	  }
+	/**
+	 * The session log writes again after `session_log_degraded`: the waiting
+	 * records were written, in order. `droppedRecords` is how many were
+	 * discarded while the buffer was full; the log has a gap where they were.
+	 * Live only, never recorded.
+	 */
+	| {
+			type: 'session_log_recovered'
+			sessionId: SessionId
+			turnId?: TurnId
+			flushedRecords: number
+			droppedRecords: number
+	  }
 	| {
 			type: 'compaction_completed'
 			sessionId: SessionId
@@ -1370,6 +1404,8 @@ export type SessionEventListener = (event: SessionEvent) => void | Promise<void>
  * runtime-context message or tool result that carried it, and a noisy watch
  * would write tens of megabytes an hour of raw process output a second time.
  * `background_job_exited.monitor` is the durable record of how a watch ended.
+ * `session_log_degraded` and `session_log_recovered` are ephemeral because the
+ * log is what cannot be written while they matter.
  * `compaction_started` is ephemeral too: it only says a pass is about to run,
  * and the `compaction` record or `compaction_failed` that ends it is the
  * durable fact.
@@ -1381,13 +1417,15 @@ export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<Sess
 	'tool_progress',
 	'monitor_event',
 	'compaction_started',
+	'session_log_degraded',
+	'session_log_recovered',
 ])
 
 export function isEphemeralEvent(event: { readonly type: string }): boolean {
 	return EPHEMERAL_EVENT_TYPES.has(event.type as SessionEventType)
 }
 
-/** The event types a session log records: every literal except the ephemeral six. */
+/** The event types a session log records: every literal except the ephemeral eight. */
 export type PersistedSessionEventType = Exclude<
 	SessionEventType,
 	| 'text_delta'
@@ -1396,4 +1434,6 @@ export type PersistedSessionEventType = Exclude<
 	| 'tool_progress'
 	| 'monitor_event'
 	| 'compaction_started'
+	| 'session_log_degraded'
+	| 'session_log_recovered'
 >

package/src/types/session/records.ts

@@ -647,6 +647,8 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	request_envelope: true,
 	iteration_completed: true,
 	compaction_started: true,
+	session_log_degraded: true,
+	session_log_recovered: true,
 	compaction_shed: true,
 	compaction_completed: true,
 	compaction_tool_results_cleared: true,