@namzu/sdk 52.1.0 → 52.3.0

package/src/tools/builtins/monitor.ts

@@ -0,0 +1,206 @@
+import { z } from 'zod'
+
+import {
+	MONITOR_TIMEOUT_DEFAULT_MS,
+	MONITOR_TIMEOUT_MAX_MS,
+	MONITOR_TIMEOUT_MIN_MS,
+	formatMonitorDuration,
+} from '../../runtime/jobs/monitor-stream.js'
+import {
+	bashToolDialect,
+	hostCommandShell,
+	isWindowsBash,
+	rewriteWindowsNullRedirect,
+} from '../command-shell.js'
+import { defineTool } from '../defineTool.js'
+import {
+	DISABLE_BACKGROUND_TASKS_ENV,
+	backgroundTasksDisabled,
+	isDangerousCommand,
+} from './bash.js'
+
+/**
+ * Watch a command's output while the model keeps working.
+ *
+ * `bash run_in_background` plus `wait_for_job` answers "tell me when this
+ * finishes", and nothing answered "tell me when something happens in it": a
+ * log line, a failed check, a changed status. The only alternative was a
+ * polling loop, which spends a full context resend per look and is silent
+ * between looks. This tool starts the command as a job the registry owns and
+ * turns each line it prints on stdout into an event the model reads on its
+ * next tool result (or wakes it, when it has stopped) — see
+ * `runtime/jobs/monitor-stream.ts` for how lines become batches and why a
+ * source that prints too much is stopped.
+ *
+ * It is a different tool from `bash`, and not a flag on it, for the same
+ * reason `wait_for_job` is: the model chooses by intent. The permission story
+ * is bash's, line for line — a monitor runs a shell command — so the rules
+ * read the command the way they read `bash`'s, and it is never read-only. It
+ * has no way out of the sandbox: a watch that outlives one approved call must
+ * not run outside the boundary that call was approved under.
+ */
+
+const inputSchema = z.object({
+	description: z
+		.string()
+		.min(1)
+		.max(200)
+		.describe(
+			'What you are watching, in a few specific words. It is shown with every event ("Monitor event: <description>"), so make it identify this watch among several: "errors in deploy log", not "monitor".',
+		),
+	command: z
+		.string()
+		.min(1)
+		// Same rewrite as `bash`, for the same reason: the rules read the line a
+		// shell will run.
+		.transform((command) =>
+			isWindowsBash(hostCommandShell()) ? rewriteWindowsNullRedirect(command) : command,
+		)
+		.describe(
+			'The shell command to watch. Each line it prints to stdout becomes an event. It runs until it ends or the timeout; it must not need stdin.',
+		),
+	timeout_ms: z
+		.preprocess(
+			(v) => (typeof v === 'string' ? Number(v) : v),
+			z
+				.number()
+				.int()
+				.min(MONITOR_TIMEOUT_MIN_MS)
+				.max(MONITOR_TIMEOUT_MAX_MS)
+				.default(MONITOR_TIMEOUT_DEFAULT_MS),
+		)
+		.describe(
+			`How long to watch, in milliseconds. Default ${MONITOR_TIMEOUT_DEFAULT_MS}. The host caps it (30 minutes by default; shorter in a single-shot run), and a larger value is lowered to that cap without an error; the result states the time actually granted.`,
+		),
+})
+
+type MonitorInput = z.infer<typeof inputSchema>
+
+export const MONITOR_TOOL_NAME = 'monitor'
+
+/**
+ * What a sandbox without `spawnDetached` is told. The wording of `bash`'s own
+ * refusal names `run_in_background` and `timeout`, neither of which is this
+ * tool's, so it is restated here; the substance is the same and so is the
+ * rule: the watch is never run on the host to get around the sandbox.
+ */
+export const MONITOR_CANNOT_DETACH =
+	'monitor is unavailable: this sandbox cannot start a detached process, and the watch will not be run on the host to get around it. Run the command in the foreground with bash, with a timeout.'
+
+const MONITOR_DESCRIPTION =
+	'Starts a command and tells you about each line it prints to stdout, as it prints it, while you keep working. Lines that arrive within 200 ms come together as one event. Use it to watch a log, a test or deploy run, a status endpoint — anything where you must react to something happening INSIDE a long-running command. For ONE notification when something finishes, do not use this: run bash with run_in_background and wait_for_job. Every stage of a pipe must flush per line or events arrive late or never (grep --line-buffered, awk with fflush(), sed -u; `head` cannot). Make the filter match failure as well as success (crash, Traceback, Error, FAILED, Killed…): silence from a monitor is not success. Poll a remote API no faster than every 30 seconds. stderr is not an event; read it with job. A monitor that prints too much is stopped, so filter at the source. It expires after the timeout (default 5 minutes, at most 30) and you get one notice; start it again if you still need it. Stop one early with job {"action":"kill","id":"<id>"}.'
+
+export const MonitorTool = defineTool({
+	name: MONITOR_TOOL_NAME,
+	description: MONITOR_DESCRIPTION,
+	inputSchema,
+	category: 'shell',
+	// Bash's, because it IS a shell command: the gate reads the line, splits
+	// chains, and applies the operator's rules to each part.
+	commandArgument: 'command',
+	commandDialect: bashToolDialect,
+	permissions: ['shell_execute'],
+	readOnly: false,
+	destructive: (input: MonitorInput) => isDangerousCommand(input.command),
+	// Starting a monitor registers a job against the owner's cap and its id
+	// is then named in later calls; two at once could race the cap, as they
+	// can for a background `bash`.
+	concurrencySafe: false,
+
+	presentCall(input) {
+		if (typeof input.command !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Monitor · ${typeof input.description === 'string' ? input.description : input.command}`,
+			facts: { kind: 'command', command: input.command, background: true },
+		}
+	},
+
+	async execute(input, context) {
+		if (isDangerousCommand(input.command)) {
+			return {
+				success: false,
+				output: '',
+				error: `Dangerous command blocked: "${input.command}"`,
+				facts: { kind: 'failure', reason: 'blocked', subject: MONITOR_TOOL_NAME },
+			}
+		}
+		if (backgroundTasksDisabled()) {
+			return {
+				success: false,
+				output: '',
+				error: `Background jobs are switched off here (${DISABLE_BACKGROUND_TASKS_ENV}), and a monitor is one. Check in the foreground with bash instead.`,
+			}
+		}
+		// Same rule as background bash: the executor withholds the registry from
+		// a sandbox that cannot start a detached process, and this check is for
+		// the direct caller who hands both.
+		if (context.sandbox && context.sandbox.spawnDetached === undefined) {
+			return { success: false, output: '', error: MONITOR_CANNOT_DETACH }
+		}
+		const jobs = context.backgroundJobs
+		if (!jobs) {
+			return {
+				success: false,
+				output: '',
+				error:
+					'monitor was requested, but this host provides no background job registry. Run the command in the foreground with bash, with a timeout.',
+			}
+		}
+		if (!jobs.startMonitor) {
+			return {
+				success: false,
+				output: '',
+				error:
+					'This host cannot deliver monitor events, so no watch was started. Use bash with run_in_background and wait_for_job to be told when a command finishes.',
+			}
+		}
+
+		try {
+			const { job, timeoutMs } = jobs.startMonitor({
+				command: input.command,
+				description: input.description,
+				timeoutMs: input.timeout_ms,
+				workingDirectory: context.workingDirectory,
+			})
+			// `startMonitor` returns before the process exists, and a spawn that
+			// fails reports a tick later; wait for that one event so "started" is
+			// never said of a watch that could not start.
+			const startup = await jobs.awaitStarted?.(job.id)
+			if (startup?.error !== undefined) {
+				return {
+					success: false,
+					output: '',
+					error: `${startup.error} (monitor ${job.id} did not run).`,
+					data: { jobId: job.id, monitor: true, startFailed: true },
+				}
+			}
+			return {
+				success: true,
+				output: `Monitor started (job ${job.id}, expires in ${formatMonitorDuration(timeoutMs)} unless the command ends first; you get one notice at expiry — start it again if you still need the watch). Each line the command prints to stdout reaches you as an event while you keep working; do not poll or sleep. Stop it with job {"action":"kill","id":"${job.id}"}. An event may arrive while you are waiting for the user — it is not their reply.`,
+				data: { jobId: job.id, monitor: true, timeoutMs },
+				facts: { kind: 'command', command: input.command, background: true },
+			}
+		} catch (err) {
+			// The per-owner cap, most likely; naming the limit is actionable.
+			return {
+				success: false,
+				output: '',
+				error: err instanceof Error ? err.message : String(err),
+			}
+		}
+	},
+})
+
+/**
+ * The tool, for a host that opts in.
+ *
+ * Not in `getBuiltinTools()`: a watch needs a host that delivers events and
+ * wakes on them, and offering a tool that starts a job nobody will hear from
+ * is worse than not offering it. A function rather than a constant so a host
+ * can decide per turn, and so it reads like `getCodeAnalysisTools`, beside
+ * which a host mounts it deferred.
+ */
+export function getMonitorTools(): (typeof MonitorTool)[] {
+	return [MonitorTool]
+}

package/src/turn/reporter.ts

@@ -309,6 +309,14 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 					...(event.exitCode !== undefined ? { 'namzu.jobs.exit_code': event.exitCode } : {}),
 				})
 				break
+			case 'monitor_event':
+				log.debug('Monitor event', {
+					'namzu.jobs.id': event.jobId,
+					'namzu.monitor.event_id': event.eventId,
+					'namzu.monitor.kind': event.kind,
+					'namzu.monitor.chars': event.text.length,
+				})
+				break
 			case 'memory_consolidated':
 				log.info('Turn learnings consolidated into the memory store', {
 					'namzu.memory.id': event.memoryId,

package/src/types/code-analysis/index.ts

@@ -0,0 +1,325 @@
+/**
+ * The seam a semantic code index arrives on.
+ *
+ * Declared in the SDK and implemented in `@namzu/analysis`, the same split
+ * `CodeNavigationProvider` uses with `@namzu/lsp`: the kernel owns the shape a
+ * tool programs against, the optional package owns the parser and the store
+ * that answer. A host constructs one and puts it on the tool context — there
+ * is no discovery step.
+ *
+ * Kept here rather than imported from `@namzu/analysis` because the
+ * dependency direction forbids it: `sdk ← analysis`, never the other way.
+ *
+ * ## What this answers that `grep` and a language server do not
+ *
+ * `grep` finds a string and says nothing of the function around it. A
+ * language server resolves a symbol the project's own types can see, and has
+ * nothing to say about a 40 MB bundle with no types and a hundred
+ * single-letter names. This index is for the second case: *which function
+ * contains this literal, what is its exact source, and who calls it by name*,
+ * over code nobody wrote for you to read.
+ *
+ * ## Positions
+ *
+ * Lines and columns are ONE-based, and columns count UTF-16 code units, which
+ * is what a JavaScript string index is. A character outside the Basic
+ * Multilingual Plane therefore takes two columns. `start` / `end` are the
+ * same UTF-16 offsets into the file's text, half-open. A line ends at `\n`.
+ */
+
+/**
+ * How much of the question the answer covers.
+ *
+ * Two cases, and the second carries its reasons. `partial` is not a failure —
+ * the answer is true as far as it goes — but a caller deciding "nothing
+ * calls this" from a partial answer is guessing, and the reasons say what is
+ * missing (a file that did not parse, a file that changed since it was
+ * indexed, a page cut off by `limit`).
+ */
+export type AnalysisCoverage =
+	| { readonly status: 'complete' }
+	| { readonly status: 'partial'; readonly reasons: readonly string[] }
+
+/**
+ * The evidence behind an answer, in three parts.
+ *
+ * - `observed`: what the index read out of the files, stated as fact.
+ * - `inferred`: what was concluded rather than read. A callee matched by
+ *   its TEXT is an inference — the index does no scope analysis, so two
+ *   unrelated functions called `run` are the same callee to it.
+ * - `coverage`: whether the answer is the whole answer.
+ *
+ * Every successful result carries one. An answer without it reads as
+ * certain, and the cases this package exists for are the ones where it is
+ * not.
+ */
+export interface AnalysisEvidence {
+	readonly observed: readonly string[]
+	readonly inferred: readonly string[]
+	readonly coverage: AnalysisCoverage
+}
+
+/**
+ * What a query answers. Three cases, closed, as with `CodeNavigationResult`:
+ * `unsupported` is "this index does not do that", `failed` is "something
+ * broke", and neither is an empty page. An empty page means "I looked and
+ * there are none", the answer a deletion depends on.
+ */
+export type CodeAnalysisResult<T> =
+	| { readonly kind: 'ok'; readonly value: T; readonly evidence: AnalysisEvidence }
+	| { readonly kind: 'unsupported'; readonly reason: string }
+	| { readonly kind: 'failed'; readonly error: string }
+
+/**
+ * One page of a larger answer. `total` is the count across ALL pages, so a
+ * caller can tell a complete list from the first slice of a long one;
+ * `nextCursor` is absent on the last page and is opaque — pass it back
+ * unchanged.
+ */
+export interface AnalysisPage<T> {
+	readonly items: readonly T[]
+	readonly total: number
+	readonly nextCursor?: string
+}
+
+/**
+ * What every request may carry beyond its own fields.
+ *
+ * `signal` stops the call: an index run in progress is abandoned (what it had
+ * already committed stays, so the next call continues from there), and a call
+ * still queued behind another never starts. Without it nothing a user does,
+ * Esc included, can stop a multi-second index of a large tree.
+ */
+export interface AnalysisCallOptions {
+	readonly signal?: AbortSignal
+}
+
+/** The paging arguments every list-returning request takes. */
+export interface AnalysisPaging extends AnalysisCallOptions {
+	/** Items per page. The provider clamps it to its own maximum. */
+	readonly limit?: number
+	/** The previous page's `nextCursor`. */
+	readonly cursor?: string
+}
+
+export type AnalysisFunctionKind =
+	| 'declaration'
+	| 'expression'
+	| 'arrow'
+	| 'method'
+	| 'getter'
+	| 'setter'
+	| 'constructor'
+
+/**
+ * A function, located. `id` is valid until its file changes and is then
+ * re-issued: do not keep one across an `index` that re-read the file.
+ */
+export interface AnalysisFunction {
+	readonly id: number
+	/** `null` for an anonymous function with nothing to infer a name from. */
+	readonly name: string | null
+	readonly kind: AnalysisFunctionKind
+	/** Absolute path. */
+	readonly path: string
+	readonly line: number
+	readonly column: number
+	readonly endLine: number
+	readonly start: number
+	readonly end: number
+}
+
+/** A piece of a file's source, with the honesty about a cut. */
+export interface AnalysisSourceSlice {
+	readonly text: string
+	/** The full length in UTF-16 units, whether or not all of it is in `text`. */
+	readonly chars: number
+	/** `true` when `text` is shorter than `chars` because of the size cap. */
+	readonly truncated: boolean
+}
+
+export interface IndexRequest extends AnalysisCallOptions {
+	/** Absolute directory the index belongs to. */
+	readonly root: string
+	/**
+	 * Index only this file or directory under `root`, instead of all of it.
+	 *
+	 * The way to make progress on a root too big to index whole (a home
+	 * directory): a call that stops at its limits says so, and the next step is
+	 * a narrower `scope`. Work from earlier calls is kept.
+	 */
+	readonly scope?: string
+	/** Re-read every file, ignoring size / mtime / hash. */
+	readonly force?: boolean
+}
+
+export interface IndexSummary {
+	readonly root: string
+	/** Whether the index lives on disk; `false` for an in-memory fallback. */
+	readonly persisted: boolean
+	readonly files: {
+		readonly indexed: number
+		/** Parsed this call (new or changed). */
+		readonly parsed: number
+		/** Seen and left alone: same size and mtime, or same content hash. */
+		readonly unchanged: number
+		readonly removed: number
+		readonly skipped: number
+		readonly withParseErrors: number
+	}
+	/** Why files were skipped, as reason → count. */
+	readonly skippedReasons: Readonly<Record<string, number>>
+	readonly functions: number
+	readonly strings: number
+	readonly calls: number
+	readonly durationMs: number
+	/**
+	 * Why this call stopped before covering `scope`, when it did: a time or
+	 * directory limit. Present means the index is partial; the text names the
+	 * next step.
+	 */
+	readonly truncated?: string
+}
+
+export interface FindLiteralRequest extends AnalysisPaging {
+	readonly root: string
+	/** The substring to look for inside string and template literals. */
+	readonly text: string
+	/** Absolute file or directory to restrict the search to. */
+	readonly path?: string
+	/** Default `true`. */
+	readonly caseSensitive?: boolean
+}
+
+export interface AnalysisLiteralHit {
+	readonly path: string
+	readonly line: number
+	readonly column: number
+	readonly start: number
+	readonly end: number
+	readonly kind: 'string' | 'template' | 'key'
+	/** The literal's value, cut to a preview. */
+	readonly value: string
+	readonly valueTruncated: boolean
+	/** The innermost function around it; absent at the top level of a file. */
+	readonly function?: AnalysisFunction
+	/**
+	 * Present when the file this came from no longer matches the index: the
+	 * position may be off (`changed`) or the file may be gone (`deleted`).
+	 */
+	readonly stale?: 'changed' | 'deleted'
+}
+
+export interface EnclosingFunctionRequest extends AnalysisCallOptions {
+	readonly root: string
+	readonly path: string
+	readonly line: number
+	readonly column?: number
+	/** Cap on the source slice, in UTF-16 units. */
+	readonly maxChars?: number
+}
+
+export interface AnalysisEnclosingFunction {
+	/** `null` when the position is not inside any function — a real answer. */
+	readonly function: AnalysisFunction | null
+	/** The function's parents, innermost first. */
+	readonly parents: readonly AnalysisFunction[]
+	readonly source?: AnalysisSourceSlice
+}
+
+export interface FunctionSourceRequest extends AnalysisPaging {
+	readonly root: string
+	/** A function id from an earlier answer. */
+	readonly id?: number
+	/** Alternatively, a file and a name; several functions can share one. */
+	readonly path?: string
+	readonly name?: string
+	readonly maxChars?: number
+}
+
+export interface AnalysisFunctionSource {
+	readonly function: AnalysisFunction
+	readonly parents: readonly AnalysisFunction[]
+	readonly source: AnalysisSourceSlice
+}
+
+export interface CallersOfRequest extends AnalysisPaging {
+	readonly root: string
+	/** The callee text: `foo`, `obj.foo`, `this.foo`. */
+	readonly name: string
+	/**
+	 * `file` looks in `path` only and is the default, because a callee matched
+	 * by text is far more likely to be the one you mean inside one file than
+	 * across a bundle of unrelated modules that reuse short names.
+	 */
+	readonly scope?: 'file' | 'workspace'
+	readonly path?: string
+	/**
+	 * `exact` matches the callee text as written. `member` also matches any
+	 * `<expression>.name`, which finds method calls whose receiver is unknown.
+	 */
+	readonly match?: 'exact' | 'member'
+}
+
+export interface AnalysisCallSite {
+	readonly path: string
+	readonly line: number
+	readonly column: number
+	readonly callee: string
+	readonly kind: 'call' | 'new'
+	readonly argumentCount: number
+	/** The function the call sits in; absent at the top level of a file. */
+	readonly caller?: AnalysisFunction
+	/** See {@link AnalysisLiteralHit.stale}. */
+	readonly stale?: 'changed' | 'deleted'
+}
+
+export interface ImportsRequest extends AnalysisPaging {
+	readonly root: string
+	readonly path: string
+}
+
+export type AnalysisModuleEdge =
+	| {
+			readonly direction: 'import'
+			readonly kind: 'static' | 'type' | 'require' | 'dynamic'
+			readonly source: string
+			readonly names: readonly string[]
+			readonly line: number
+			readonly column: number
+	  }
+	| {
+			readonly direction: 'export'
+			readonly kind: 'named' | 'default' | 'reexport' | 'star'
+			readonly name: string
+			readonly source?: string
+			readonly line: number
+			readonly column: number
+	  }
+
+export interface CodeAnalysisProvider {
+	/**
+	 * Build or refresh the index for a directory. Incremental: a file whose
+	 * size and mtime are unchanged is not read, and one whose content hash is
+	 * unchanged is not parsed.
+	 */
+	index(request: IndexRequest): Promise<CodeAnalysisResult<IndexSummary>>
+	/** Where a string appears, and the function around each hit. */
+	findLiteral(
+		request: FindLiteralRequest,
+	): Promise<CodeAnalysisResult<AnalysisPage<AnalysisLiteralHit>>>
+	/** The function containing a position, with its source and parent chain. */
+	enclosingFunction(
+		request: EnclosingFunctionRequest,
+	): Promise<CodeAnalysisResult<AnalysisEnclosingFunction>>
+	/** A function's exact source, by id or by file and name. */
+	functionSource(
+		request: FunctionSourceRequest,
+	): Promise<CodeAnalysisResult<AnalysisPage<AnalysisFunctionSource>>>
+	/** Call sites of a name. Matched by text, not by scope; see the evidence. */
+	callersOf(request: CallersOfRequest): Promise<CodeAnalysisResult<AnalysisPage<AnalysisCallSite>>>
+	/** One file's imports and exports. */
+	imports(request: ImportsRequest): Promise<CodeAnalysisResult<AnalysisPage<AnalysisModuleEdge>>>
+	/** Close whatever backs it. Not optional: an open database is a held file. */
+	dispose(): Promise<void>
+}

package/src/types/session/events.ts

@@ -612,6 +612,28 @@ type CoreSessionEvent =
 			status: 'exited' | 'killed'
 			exitCode?: number
 			signal?: string
+			/** Present when the job was a monitor: what it watched and, if the registry stopped it, why. */
+			monitor?: {
+				description: string
+				stopReason?: 'expired' | 'too_much_output' | 'stopped'
+			}
+	  }
+	/**
+	 * A monitor this session (or the owner it runs under) started has
+	 * something to say: a batch of its stdout lines, or a notice from the
+	 * monitor itself (events suppressed, stopped, expired). The model reads it
+	 * on its next tool result; the host learns it from this, whether or not a
+	 * turn is running. `eventId` is what a host acknowledges.
+	 */
+	| {
+			type: 'monitor_event'
+			sessionId: SessionId
+			turnId?: TurnId
+			jobId: string
+			eventId: string
+			description: string
+			kind: 'output' | 'notice'
+			text: string
 	  }
 	/**
 	 * What the turn learned was written to the host's memory store: its
@@ -1229,7 +1251,7 @@ export type ChildSessionLifecycleEvent =
 	| ChildSessionIdledEvent
 
 /**
- * Discriminated union of every live session event: 62 type literals.
+ * Discriminated union of every live session event: 63 type literals.
  *
  * `type` is the sole discriminator for exhaustive switches; envelope fields
  * are additive and never take part in discrimination.
@@ -1247,21 +1269,26 @@ export type SessionEventListener = (event: SessionEvent) => void | Promise<void>
 /**
  * Event types whose volume makes durable persistence wasteful. They reach the
  * live stream and never the session log: the completed message, reasoning
- * block and tool input carry the same content once.
+ * block and tool input carry the same content once. A `monitor_event` is the
+ * same case: the text the model read is already in the transcript as the
+ * 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.
  */
 export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<SessionEventType>([
 	'text_delta',
 	'tool_input_delta',
 	'reasoning_delta',
 	'tool_progress',
+	'monitor_event',
 ])
 
 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 four. */
+/** The event types a session log records: every literal except the ephemeral five. */
 export type PersistedSessionEventType = Exclude<
 	SessionEventType,
-	'text_delta' | 'tool_input_delta' | 'reasoning_delta' | 'tool_progress'
+	'text_delta' | 'tool_input_delta' | 'reasoning_delta' | 'tool_progress' | 'monitor_event'
 >

package/src/types/session/records.ts

@@ -648,6 +648,7 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	turn_resuming: true,
 	guardrail_triggered: true,
 	background_job_exited: true,
+	monitor_event: true,
 	memory_consolidated: true,
 	turn_completed: true,
 	turn_failed: true,
@@ -687,12 +688,12 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	child_session_idled: true,
 }
 
-/** All 62 live event type literals. */
+/** All 63 live event type literals. */
 export const SESSION_EVENT_TYPES: readonly SessionEventType[] = Object.freeze(
 	Object.keys(SESSION_EVENT_TYPE_TABLE) as SessionEventType[],
 )
 
-/** The 58 event types a session log records. */
+/** The 58 event types a session log records: all 63 but the five ephemeral ones. */
 export const PERSISTED_SESSION_EVENT_TYPES: readonly PersistedSessionEventType[] = Object.freeze(
 	SESSION_EVENT_TYPES.filter(
 		(type) => !EPHEMERAL_EVENT_TYPES.has(type),