@namzu/sdk 60.0.0 → 60.2.0

package/src/types/session/events.ts

@@ -102,7 +102,12 @@ type CoreSessionEvent =
 			/** The token ledger this turn spends from, keyed by the root turn. */
 			budget?: TurnBudgetBinding
 	  }
-	| { type: 'iteration_started'; sessionId: SessionId; turnId: TurnId; iteration: number }
+	| {
+			type: 'iteration_started'
+			sessionId: SessionId
+			turnId: TurnId
+			iteration: number
+	  }
 	/**
 	 * Who answers when this turn asks a human, changed mid-turn.
 	 *
@@ -206,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
@@ -454,6 +493,40 @@ type CoreSessionEvent =
 			 */
 			restart?: boolean
 	  }
+	/**
+	 * The model declined to answer, and what the turn did about it.
+	 *
+	 * The provider finished a reply as a refusal or a safety block. The refused
+	 * reply is kept out of the history sent next. `outcome` says what followed:
+	 *
+	 * - `'fallback'`: the request is being re-run on `fallbackModel`, which the
+	 *   rest of the turn keeps. A host that owns the session's model is expected
+	 *   to keep it for later turns too and to say so.
+	 * - `'retry'`: no other model was available and the refused reply had
+	 *   partial output, so the request is being re-run once on the same model
+	 *   with a note that the previous reply was stopped.
+	 * - `'declined'`: nothing recovered it. The turn settles with stop reason
+	 *   `'refused'`.
+	 *
+	 * Like `provider_fallback`, this is the feature's honesty: a swapped model
+	 * must be shown, not logged. It is emitted before the re-run starts.
+	 */
+	| {
+			type: 'model_refusal'
+			sessionId: SessionId
+			turnId: TurnId
+			iteration: number
+			/** The model that declined. */
+			model: string
+			providerId: string
+			outcome: 'fallback' | 'retry' | 'declined'
+			/** The model the request moves to. Set only with `outcome: 'fallback'`. */
+			fallbackModel?: string
+			/** The provider's own classification, when it gave one. */
+			category?: string
+			/** The provider's own sentence, when it gave one. Show it; do not parse it. */
+			explanation?: string
+	  }
 	| {
 			type: 'tool_completed'
 			/** Bounded result view; omitted when output was overridden or truncated. */
@@ -892,7 +965,12 @@ type CoreSessionEvent =
 			steps: PlanStep[]
 			summary?: string
 	  }
-	| { type: 'plan_approved'; sessionId: SessionId; turnId: TurnId; planId: PlanId }
+	| {
+			type: 'plan_approved'
+			sessionId: SessionId
+			turnId: TurnId
+			planId: PlanId
+	  }
 	| {
 			type: 'plan_rejected'
 			sessionId: SessionId
@@ -923,7 +1001,12 @@ type CoreSessionEvent =
 	 * through `onContextCreated`, so they proved the plan settled without ever
 	 * asking whether a consumer of the EVENT STREAM could see it.
 	 */
-	| { type: 'plan_completed'; sessionId: SessionId; turnId: TurnId; planId: PlanId }
+	| {
+			type: 'plan_completed'
+			sessionId: SessionId
+			turnId: TurnId
+			planId: PlanId
+	  }
 	/**
 	 * The plan is over and it did not finish.
 	 *
@@ -931,7 +1014,13 @@ type CoreSessionEvent =
 	 * an event that says "failed" without saying why puts the reader back
 	 * where the missing event did.
 	 */
-	| { type: 'plan_failed'; sessionId: SessionId; turnId: TurnId; planId: PlanId; reason?: string }
+	| {
+			type: 'plan_failed'
+			sessionId: SessionId
+			turnId: TurnId
+			planId: PlanId
+			reason?: string
+	  }
 	| {
 			type: 'agent_pending'
 			sessionId: SessionId
@@ -1103,7 +1192,12 @@ type CoreSessionEvent =
 			exitCode: number
 			durationMs: number
 	  }
-	| { type: 'sandbox_destroyed'; sessionId: SessionId; turnId?: TurnId; sandboxId: SandboxId }
+	| {
+			type: 'sandbox_destroyed'
+			sessionId: SessionId
+			turnId?: TurnId
+			sandboxId: SandboxId
+	  }
 	// ─────────────────────────────────────────────────────────────────────
 	// v3 message + tool-input lifecycle (additive 2026-05; see
 	// ses_001-tool-stream-events). These are not yet emitted by the
@@ -1310,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.
@@ -1321,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'
@@ -1336,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

@@ -236,6 +236,7 @@ const stopReason = z.enum([
 	'step_refused',
 	'structured_output_failed',
 	'output_limit',
+	'refused',
 	'answer_rejected',
 	'input_guardrail',
 	'output_guardrail',
@@ -646,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,
@@ -655,6 +658,7 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	hosted_tool: true,
 	provider_retry: true,
 	provider_fallback: true,
+	model_refusal: true,
 	tool_completed: true,
 	user_question_asked: true,
 	user_question_answered: true,
@@ -749,6 +753,7 @@ const TURN_BOUND_OTHER_TYPE_LIST = [
 	'hosted_tool',
 	'provider_retry',
 	'provider_fallback',
+	'model_refusal',
 	'tool_completed',
 	'user_question_asked',
 	'user_question_answered',

package/src/types/session/stop-reason.ts

@@ -53,6 +53,17 @@ export type StopReason =
 	 * looking for a loop instead of at the reviewer.
 	 */
 	| 'answer_rejected'
+	/**
+	 * The model declined to answer and nothing recovered it.
+	 *
+	 * Its provider finished the reply as a refusal or a safety block, and the
+	 * one automatic retry this turn allows was not available or was refused
+	 * too. Distinct from `end_turn` so a host never reads a declined request
+	 * as a finished one, and from `error` because nothing failed: the model
+	 * answered, and the answer was no. The refused reply is not in the
+	 * history; a `model_refusal` event carries what the provider said.
+	 */
+	| 'refused'
 	/** An input guardrail refused the turn before it started. */
 	| 'input_guardrail'
 	/** An output guardrail refused the produced result. */

package/src/utils/temp.ts

@@ -0,0 +1,250 @@
+import { createHash } from 'node:crypto'
+import { lstatSync, mkdirSync, mkdtempSync } from 'node:fs'
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir, userInfo } from 'node:os'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/**
+ * Namzu's own scratch space: the one place that decides where temporary files
+ * go, who may enter, and what a failure to create it says.
+ *
+ * The base is `NAMZU_TMPDIR` when it is set, otherwise the operating system's
+ * temporary directory. Under it, `namzu-<user>` is private to the user (mode
+ * 0700, refused when it is a symbolic link, not a directory, owned by someone
+ * else, or open to group and others). A failure is never answered by quietly
+ * using another directory: it is a {@link TempDirectoryError} that names the
+ * directory, the cause and `NAMZU_TMPDIR`.
+ */
+
+/** The environment variable that moves Namzu's scratch space to another folder or disk. */
+export const NAMZU_TMPDIR_ENV = 'NAMZU_TMPDIR'
+
+export type TempDirectoryFailure =
+	| 'volume_full'
+	| 'quota_exceeded'
+	| 'not_writable'
+	| 'missing'
+	| 'not_absolute'
+	| 'refused'
+
+/** Namzu's scratch directory cannot be used. `message` is a sentence for a person. */
+export class TempDirectoryError extends Error {
+	override readonly name = 'TempDirectoryError'
+	constructor(
+		message: string,
+		readonly reason: TempDirectoryFailure,
+		readonly directory: string,
+	) {
+		super(message)
+	}
+}
+
+export interface PrivateTempRootOptions {
+	/** Base directory. Default `NAMZU_TMPDIR`, else `os.tmpdir()`. */
+	readonly tmpdir?: string
+	/** Default `process.env`. */
+	readonly env?: NodeJS.ProcessEnv
+	/** Default `process.platform`. */
+	readonly platform?: NodeJS.Platform
+	/**
+	 * Default `process.getuid`. Pass `undefined` explicitly to model a
+	 * platform without it (win32).
+	 */
+	readonly getuid?: (() => number) | undefined
+	/** Default `os.userInfo().username`. */
+	readonly username?: () => string
+}
+
+/**
+ * The directory under which Namzu keeps its temporary files: `NAMZU_TMPDIR`
+ * when set (it must be an absolute path), otherwise `os.tmpdir()`. Nothing is
+ * created or checked.
+ */
+export function resolveTempBase(env: NodeJS.ProcessEnv = process.env): string {
+	const configured = env[NAMZU_TMPDIR_ENV]?.trim()
+	if (!configured) return tmpdir()
+	if (!isAbsolute(configured)) {
+		throw new TempDirectoryError(
+			`${NAMZU_TMPDIR_ENV} must be a full path, but it is "${configured}". Set it to a folder on a disk with free space.`,
+			'not_absolute',
+			configured,
+		)
+	}
+	return configured
+}
+
+/** The sentence for a directory that could not be created or written. */
+function explain(error: unknown, directory: string): TempDirectoryError | undefined {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code
+	const elsewhere = `Free some space and start again, or set ${NAMZU_TMPDIR_ENV} to a folder on another disk.`
+	switch (code) {
+		case 'ENOSPC':
+			return new TempDirectoryError(
+				`The disk is full, so Namzu could not create ${directory}. ${elsewhere}`,
+				'volume_full',
+				directory,
+			)
+		case 'EDQUOT':
+			return new TempDirectoryError(
+				`Your disk quota is used up, so Namzu could not create ${directory}. ${elsewhere}`,
+				'quota_exceeded',
+				directory,
+			)
+		case 'EACCES':
+		case 'EPERM':
+		case 'EROFS':
+			return new TempDirectoryError(
+				`Namzu could not create ${directory} because the folder cannot be written to. Set ${NAMZU_TMPDIR_ENV} to a folder you can write to.`,
+				'not_writable',
+				directory,
+			)
+		case 'ENOENT':
+			return new TempDirectoryError(
+				`Namzu could not create ${directory} because its parent folder does not exist. Create that folder, or set ${NAMZU_TMPDIR_ENV} to one that does.`,
+				'missing',
+				directory,
+			)
+		default:
+			return undefined
+	}
+}
+
+function refuse(root: string, why: string): TempDirectoryError {
+	return new TempDirectoryError(
+		`Refusing temporary root ${root}: ${why} Set ${NAMZU_TMPDIR_ENV} to a folder only you can write to.`,
+		'refused',
+		root,
+	)
+}
+
+function sha256Hex(value: string): string {
+	return createHash('sha256').update(value).digest('hex')
+}
+
+/**
+ * The per-user private root, `<base>/namzu-<user>`, created if missing.
+ *
+ * `<user>` is the numeric uid where the platform has one; otherwise the first
+ * 12 hex digits of the SHA-256 of the user name; otherwise `user`. On POSIX
+ * the directory is created with mode 0700 and refused if it is a symlink, not
+ * a directory, owned by another uid, or open to group or others. On win32
+ * `%TEMP%` is already per user: a symlink or junction is refused and the
+ * owner check is skipped.
+ *
+ * @throws {TempDirectoryError} when it cannot be created or is not safe to use.
+ */
+/**
+ * Where {@link privateTempRoot} lives, without creating or checking anything.
+ * For a caller that needs to know a path before it is worth making it.
+ */
+export function privateTempRootPath(options: PrivateTempRootOptions = {}): string {
+	const getuid = 'getuid' in options ? options.getuid : process.getuid?.bind(process)
+	let user = 'user'
+	if (typeof getuid === 'function') {
+		user = String(getuid())
+	} else {
+		try {
+			const name = (options.username ?? (() => userInfo().username))()
+			if (name.length > 0) user = sha256Hex(name).slice(0, 12)
+		} catch {
+			// No user database entry: fall back to the fixed segment.
+		}
+	}
+	return join(options.tmpdir ?? resolveTempBase(options.env), `namzu-${user}`)
+}
+
+export function privateTempRoot(options: PrivateTempRootOptions = {}): string {
+	const platform = options.platform ?? process.platform
+	const getuid = 'getuid' in options ? options.getuid : process.getuid?.bind(process)
+	const root = privateTempRootPath(options)
+	try {
+		mkdirSync(root, { mode: 0o700 })
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw explain(error, root) ?? error
+	}
+	const entry = lstatSync(root)
+	if (entry.isSymbolicLink()) throw refuse(root, 'it is a symbolic link.')
+	if (!entry.isDirectory()) throw refuse(root, 'it is not a directory.')
+	if (platform !== 'win32' && typeof getuid === 'function') {
+		if (entry.uid !== getuid()) throw refuse(root, `it belongs to uid ${entry.uid}.`)
+		if ((entry.mode & 0o077) !== 0) {
+			throw refuse(
+				root,
+				`mode ${(entry.mode & 0o777).toString(8)} lets other users in; it must be 700.`,
+			)
+		}
+	}
+	return root
+}
+
+/** A new empty directory named `<prefix>XXXXXX` inside the private root. */
+export function createTempDirSync(prefix: string, options: PrivateTempRootOptions = {}): string {
+	const root = privateTempRoot(options)
+	try {
+		return mkdtempSync(join(root, prefix))
+	} catch (error) {
+		throw explain(error, join(root, prefix)) ?? error
+	}
+}
+
+/** As {@link createTempDirSync}, without blocking the event loop. */
+export async function createTempDir(
+	prefix: string,
+	options: PrivateTempRootOptions = {},
+): Promise<string> {
+	const root = privateTempRoot(options)
+	try {
+		return await mkdtemp(join(root, prefix))
+	} catch (error) {
+		throw explain(error, join(root, prefix)) ?? error
+	}
+}
+
+/**
+ * The path of a file named `name` inside the private root. The file itself is
+ * not created; the caller opens it, and a write that fails because the disk is
+ * full is the caller's to report.
+ */
+export function tempFilePath(name: string, options: PrivateTempRootOptions = {}): string {
+	return join(privateTempRoot(options), name)
+}
+
+/**
+ * Make a session's scratch folder (and the folders above it, mode 0700) and
+ * confirm it is safe to treat as a place the session may write freely: it lies
+ * inside the private root, and neither it nor any folder between it and the
+ * root is a symbolic link, a non-folder or owned by someone else. Made on
+ * first use, not before, so a session that never needs it leaves nothing behind.
+ *
+ * @throws {TempDirectoryError} when it cannot be made or is not safe; the
+ * caller then leaves the folder outside the session's roots.
+ */
+export function ensureScratchpadDirectory(
+	directory: string,
+	options: PrivateTempRootOptions = {},
+): string {
+	const root = privateTempRoot(options)
+	const target = resolve(directory)
+	const inside = relative(root, target)
+	if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
+		throw refuse(target, 'it is not inside the private temporary folder.')
+	}
+	const getuid = 'getuid' in options ? options.getuid : process.getuid?.bind(process)
+	const platform = options.platform ?? process.platform
+	let current = root
+	for (const part of inside.split(sep)) {
+		current = join(current, part)
+		try {
+			mkdirSync(current, { mode: 0o700 })
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw explain(error, current) ?? error
+		}
+		const entry = lstatSync(current)
+		if (entry.isSymbolicLink()) throw refuse(current, 'it is a symbolic link.')
+		if (!entry.isDirectory()) throw refuse(current, 'it is not a directory.')
+		if (platform !== 'win32' && typeof getuid === 'function' && entry.uid !== getuid()) {
+			throw refuse(current, `it belongs to uid ${entry.uid}.`)
+		}
+	}
+	return target
+}