@namzu/sdk 52.2.0 → 52.3.0

package/src/runtime/jobs/awaited-jobs.ts

@@ -7,7 +7,30 @@ import type { BackgroundJob, BackgroundJobRegistry } from './registry.js'
  * test that needs two exits and nothing else should not have to spawn
  * processes to produce them.
  */
-export type AwaitedJobSource = Pick<BackgroundJobRegistry, 'get' | 'onExit'>
+export type AwaitedJobSource = Pick<BackgroundJobRegistry, 'get' | 'onExit'> &
+	Partial<Pick<BackgroundJobRegistry, 'onMonitorEvent'>>
+
+/**
+ * Turn the adapter into the holder of a turn for the monitors the TURN owns.
+ *
+ * A monitor is the one kind of job whose point is that it keeps going, so
+ * "the model said it is waiting" cannot be the signal that holds a turn open
+ * for it: the model starts it and goes on. The signal is ownership instead. A
+ * turn that owns its jobs itself (a sub-agent, a plain SDK host: nobody
+ * outside the turn is listening) has no one else to hear a monitor's events,
+ * so ending while one runs would start a watch and discard everything it
+ * finds. A SESSION-owned monitor never comes through here: its host hears the
+ * events and wakes on them, and holding the turn for it would delay the end of
+ * every turn for as long as the watch lives.
+ */
+export interface MonitorHold {
+	/**
+	 * Whether the monitor notices the turn queued are still unread. The same
+	 * second opinion `unreadNotice` is for exits: it can only narrow what counts
+	 * as pending, never open a hold.
+	 */
+	readonly unreadNotice: () => boolean
+}
 
 /** Exits and the text that puts them in front of the model. See {@link AwaitedJobs.takeDelivery}. */
 export interface DeliverableJobExits {
@@ -49,6 +72,10 @@ export class AwaitedJobs {
 	private exits: BackgroundJob[] = []
 	private readonly arrivals = new Set<() => void>()
 	private detach?: () => void
+	/** Running monitors the turn owns and holds itself open for. */
+	private readonly monitors = new Set<string>()
+	/** Monitor events and ends since the notices were last delivered. */
+	private monitorArrivals = 0
 
 	constructor(
 		private readonly source: AwaitedJobSource,
@@ -83,6 +110,8 @@ export class AwaitedJobs {
 		 * unread by definition.
 		 */
 		private readonly unreadNotice?: () => boolean,
+		/** Present when the turn owns its monitors; see {@link MonitorHold}. */
+		private readonly monitorHold?: MonitorHold,
 	) {}
 
 	/**
@@ -94,20 +123,109 @@ export class AwaitedJobs {
 	 */
 	attach(): () => void {
 		if (this.detach) return this.detach
-		this.detach = this.source.onExit((job) => {
+		const stopMonitorEvents = this.monitorHold
+			? this.source.onMonitorEvent?.((event) => {
+					if (event.owner !== this.owner || !this.monitors.has(event.jobId)) return
+					this.arrive()
+				})
+			: undefined
+		const stopExits = this.source.onExit((job) => {
 			// `onExit` is a broadcast over a registry a host may share between
 			// runs, and the filter is the same one the exit-notice channel
 			// applies in `runtime/query/index.ts`.
 			if (job.owner !== this.owner) return
+			// A monitor's end is news of its own kind, delivered with its events
+			// rather than paired with a job-exit notice. It also leaves the
+			// awaited set if the model happened to `wait_for_job` it, so the one
+			// end cannot be waited for twice.
+			if (this.monitors.delete(job.id)) {
+				this.outstanding.delete(job.id)
+				this.arrive()
+				return
+			}
 			// `outstanding` is the gate, so an id nobody awaited is ignored and
 			// a second announcement for the same job cannot queue twice.
 			if (!this.outstanding.delete(job.id)) return
 			this.exits.push(job)
 			for (const wake of [...this.arrivals]) wake()
 		})
+		this.detach = () => {
+			stopMonitorEvents?.()
+			stopExits()
+		}
 		return this.detach
 	}
 
+	private arrive(): void {
+		this.monitorArrivals++
+		for (const wake of [...this.arrivals]) wake()
+	}
+
+	/**
+	 * Say that the turn owns this running monitor and must not end while it
+	 * runs. Called by the executor when the bound registry starts one, and a
+	 * no-op on a turn that does not own its monitors.
+	 */
+	expectMonitor(id: string): void {
+		if (!this.monitorHold) return
+		let job: BackgroundJob
+		try {
+			job = this.source.get(id)
+		} catch {
+			return
+		}
+		if (job.owner !== this.owner || job.status !== 'running') return
+		this.monitors.add(id)
+	}
+
+	/** Monitor events or ends the model has not been shown yet. */
+	private get unreadMonitor(): boolean {
+		if (this.monitorArrivals === 0) return false
+		return this.monitorHold?.unreadNotice() ?? false
+	}
+
+	/**
+	 * Milliseconds until the last held monitor expires, or `undefined` when the
+	 * turn holds none. A monitor's own expiry is the bound on holding for it: a
+	 * hold that ended earlier would walk away from a watch with time left, and
+	 * one that ended later would be waiting for a stop that has already come.
+	 */
+	monitorHoldMs(now: number = Date.now()): number | undefined {
+		let until: number | undefined
+		for (const id of this.monitors) {
+			let expiresAt: number | undefined
+			try {
+				expiresAt = this.source.get(id).expiresAt
+			} catch {
+				continue
+			}
+			if (expiresAt !== undefined) until = Math.max(until ?? 0, expiresAt)
+		}
+		return until === undefined ? undefined : Math.max(0, until - now)
+	}
+
+	/**
+	 * Say that the queued monitor notices have been put in front of the model.
+	 * The counterpart of {@link noticesDelivered}, for the tool-result path.
+	 */
+	monitorNoticesDelivered(): void {
+		this.monitorArrivals = 0
+	}
+
+	/**
+	 * Take the monitor notices together with the record that they were
+	 * delivered, or neither. The pairing is {@link takeDelivery}'s, for the
+	 * same reason: marking them delivered when no text was written would
+	 * strand what arrived.
+	 */
+	takeMonitorDelivery(notice: () => string | undefined): string | undefined {
+		if (this.monitorArrivals === 0) return undefined
+		const text = notice()
+		if (text === undefined) return undefined
+		this.monitorArrivals = 0
+		return text
+	}
+
 	/**
 	 * Say that the model is waiting on this job's exit.
 	 *
@@ -150,7 +268,9 @@ export class AwaitedJobs {
 
 	/** Whether an awaited job is still running, or one has exited unread. */
 	get hasPendingWork(): boolean {
-		return this.unreadExits || this.outstanding.size > 0
+		return (
+			this.unreadExits || this.outstanding.size > 0 || this.monitors.size > 0 || this.unreadMonitor
+		)
 	}
 
 	/**
@@ -163,8 +283,8 @@ export class AwaitedJobs {
 	 */
 	waitForArrival(timeoutMs: number, signal?: AbortSignal): Promise<void> {
 		if (signal?.aborted) return Promise.resolve()
-		if (this.unreadExits) return Promise.resolve()
-		if (this.outstanding.size === 0) return Promise.resolve()
+		if (this.unreadExits || this.unreadMonitor) return Promise.resolve()
+		if (this.outstanding.size === 0 && this.monitors.size === 0) return Promise.resolve()
 
 		return new Promise((resolve) => {
 			const finish = (): void => {
@@ -263,6 +383,8 @@ export class AwaitedJobs {
 		this.detach?.()
 		this.detach = undefined
 		this.outstanding.clear()
+		this.monitors.clear()
+		this.monitorArrivals = 0
 		this.exits = []
 		// Release anyone still waiting. A closed adapter would otherwise hold
 		// them to their own deadline for an exit that can no longer reach them.

package/src/runtime/jobs/monitor-stream.ts

@@ -0,0 +1,269 @@
+/**
+ * Turns a command's stdout into a few model-sized events.
+ *
+ * A watcher (`tail -f`, a poll loop, `gh run watch`) can print a line every
+ * millisecond, and every line the model is told about costs a context resend.
+ * So a monitor does not forward lines, it forwards BATCHES: lines are split,
+ * trimmed and truncated here, held for a short fixed window, and delivered
+ * together, and the batches themselves are rationed by a token bucket. A
+ * source that outruns the ration is first told so, then stopped, because a
+ * model that is flooded stops reading and one that is silenced does not know
+ * to look.
+ *
+ * Pure: no process, no registry, no model. The clock and the timer are
+ * injectable (and default to the globals read at call time, so fake timers
+ * work without any injection), which is what lets the tests advance a window
+ * by calling a function rather than by waiting for one.
+ *
+ * The constants and the wording come from the reference implementation of this
+ * tool; deviations are named where they are made.
+ */
+
+/** A longer line keeps its first this-many characters. */
+export const MONITOR_LINE_MAX_CHARS = 500
+/** A joined batch longer than this keeps its first this-many characters. */
+export const MONITOR_BATCH_MAX_CHARS = 3000
+/**
+ * The first buffered line arms ONE timer for this long; everything that
+ * arrives before it fires rides in the same batch. A fixed window, not a
+ * debounce: a source that never pauses still gets a batch every window
+ * instead of never.
+ */
+export const MONITOR_BATCH_WINDOW_MS = 200
+/** A partial line (no newline yet) keeps its tail past this many bytes. */
+export const MONITOR_PARTIAL_LINE_MAX_BYTES = 1024 * 1024
+/** One token per BATCH, not per line. */
+export const MONITOR_BUCKET_CAPACITY = 10
+export const MONITOR_BUCKET_REFILL_MS = 2000
+/** Suppression older than this, with another batch dropped, stops the monitor. */
+export const MONITOR_SUPPRESSION_LIMIT_MS = 30_000
+/** The effective ceiling on a monitor's life; a host may lower it, never raise it past the schema. */
+export const MONITOR_TIMEOUT_CAP_MS = 1_800_000
+export const MONITOR_TIMEOUT_DEFAULT_MS = 300_000
+export const MONITOR_TIMEOUT_MIN_MS = 1000
+/** The schema ceiling; anything between the cap and this is clamped, not refused. */
+export const MONITOR_TIMEOUT_MAX_MS = 3_600_000
+/** One notification handed to the model is cut to this many characters, in the middle. */
+export const MONITOR_NOTIFICATION_MAX_CHARS = 100_000
+/**
+ * One event's content is shrunk to this many characters BEFORE it is framed,
+ * so the notification cap never has to cut inside an envelope. A batch is at
+ * most 3000, so this only matters to a notice or a caller that outgrew that.
+ */
+export const MONITOR_EVENT_CONTENT_MAX_CHARS = 20_000
+
+const LINE_TRUNCATED = '...(truncated)'
+const BATCH_TRUNCATED = '\n...(truncated)'
+
+/** `30m`, `5m`, `90s`: whole minutes as minutes, anything else in seconds. */
+export function formatMonitorDuration(ms: number): string {
+	const seconds = Math.max(1, Math.round(ms / 1000))
+	return seconds % 60 === 0 ? `${seconds / 60}m` : `${seconds}s`
+}
+
+export function suppressionNotice(count: number): string {
+	return `[${count} events suppressed — output rate too high. Consider stopping this monitor and starting it with a more selective command.]`
+}
+
+export function tooMuchOutputNotice(count: number, overMs: number): string {
+	return `[Monitor stopped — too much output (${count} events suppressed over ${formatMonitorDuration(overMs)}). Restart it with a more selective command.]`
+}
+
+export function expiryNotice(ms: number, delivered: number): string {
+	return delivered > 0
+		? `[Monitor expired after ${formatMonitorDuration(ms)} with ${delivered} events delivered. Start it again if you still need the watch.]`
+		: `[Monitor expired after ${formatMonitorDuration(ms)} with no events delivered. Start it again if you still need the watch — and widen the filter if silence was unexpected.]`
+}
+
+export interface MonitorStreamStats {
+	/** Batches handed to `onBatch`. */
+	readonly eventsDelivered: number
+	/** Batches the bucket dropped, over the monitor's whole life. */
+	readonly suppressed: number
+	/** Characters pushed in, before any trimming: zero means the command never wrote to stdout. */
+	readonly stdoutChars: number
+}
+
+export interface MonitorStreamOptions {
+	/** One batch of lines, joined with `\n`. */
+	onBatch(text: string): void
+	/** Housekeeping text from the stream itself (the suppression notice). Not rationed. */
+	onNotice(text: string): void
+	/**
+	 * The source was suppressed for too long and another batch was dropped. The
+	 * stream is closed before this is called; stopping the process is the
+	 * caller's.
+	 */
+	onOverflow(info: { readonly suppressed: number; readonly overMs: number }): void
+	now?: () => number
+	setTimer?: (callback: () => void, ms: number) => unknown
+	clearTimer?: (handle: unknown) => void
+}
+
+export interface MonitorStream {
+	/** Feed raw stdout text; chunks may split a line anywhere. */
+	push(text: string): void
+	/** Emit the pending batch now, without the partial line. For expiry. */
+	flush(): void
+	/** The end of the stream: the partial line counts as a line, then everything pending is emitted. */
+	drain(): void
+	/** Stop for good. Whatever is pending is discarded. */
+	close(): void
+	stats(): MonitorStreamStats
+}
+
+/** The tail of `text` that fits `maxBytes`, starting on a whole code point. */
+function keepTail(text: string, maxBytes: number): string {
+	const bytes = Buffer.from(text)
+	if (bytes.length <= maxBytes) return text
+	let start = bytes.length - maxBytes
+	while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80) start++
+	return bytes.subarray(start).toString('utf8')
+}
+
+export function createMonitorStream(options: MonitorStreamOptions): MonitorStream {
+	const now = options.now ?? (() => Date.now())
+	const setTimer =
+		options.setTimer ??
+		((callback: () => void, ms: number) => {
+			const handle = setTimeout(callback, ms)
+			// A pending batch must not keep a process alive; the job's own exit
+			// drains it.
+			handle.unref?.()
+			return handle
+		})
+	const clearTimer =
+		options.clearTimer ?? ((handle: unknown) => clearTimeout(handle as NodeJS.Timeout))
+
+	let closed = false
+	let partial = ''
+	let lines: string[] = []
+	let timer: unknown
+	let timerArmed = false
+
+	let tokens = MONITOR_BUCKET_CAPACITY
+	let refilledAt = now()
+
+	let eventsDelivered = 0
+	let suppressedTotal = 0
+	let stdoutChars = 0
+
+	// The suppression tracker. `count` is what the auto-stop reports; `unannounced`
+	// is what the next notice reports. They differ after a notice, because the
+	// tracker outlives it on purpose: a source that is told and keeps going must
+	// still reach the 30 s rule.
+	let suppressionStartedAt: number | undefined
+	let lastDropAt = 0
+	let count = 0
+	let unannounced = 0
+	let noticeEmitted = false
+
+	const refill = (at: number): void => {
+		const elapsed = at - refilledAt
+		if (elapsed <= 0) return
+		tokens = Math.min(MONITOR_BUCKET_CAPACITY, tokens + elapsed / MONITOR_BUCKET_REFILL_MS)
+		refilledAt = at
+	}
+
+	const deliver = (batch: string): void => {
+		const at = now()
+		// Reset only after a notice went out AND the source has been quiet for
+		// three refills. Resetting on quiet alone would let a source that is
+		// dropped every other window never reach the stop rule.
+		if (noticeEmitted && at - lastDropAt > 3 * MONITOR_BUCKET_REFILL_MS) {
+			suppressionStartedAt = undefined
+			count = 0
+			unannounced = 0
+			noticeEmitted = false
+		}
+		refill(at)
+		if (tokens >= 1) {
+			tokens -= 1
+			if (unannounced > 0) {
+				options.onNotice(suppressionNotice(unannounced))
+				unannounced = 0
+				noticeEmitted = true
+			}
+			eventsDelivered++
+			options.onBatch(batch)
+			return
+		}
+		// Whether the rule fires is decided by when suppression BEGAN, before
+		// this drop is counted, and the count reported includes it.
+		const began = suppressionStartedAt
+		suppressionStartedAt ??= at
+		lastDropAt = at
+		suppressedTotal++
+		count++
+		unannounced++
+		if (began !== undefined && at - began > MONITOR_SUPPRESSION_LIMIT_MS) {
+			stop()
+			options.onOverflow({ suppressed: count, overMs: at - began })
+		}
+	}
+
+	const emitPending = (): void => {
+		if (timerArmed) {
+			clearTimer(timer)
+			timerArmed = false
+		}
+		if (lines.length === 0) return
+		let batch = lines.join('\n')
+		lines = []
+		if (batch.length > MONITOR_BATCH_MAX_CHARS) {
+			batch = batch.slice(0, MONITOR_BATCH_MAX_CHARS) + BATCH_TRUNCATED
+		}
+		deliver(batch)
+	}
+
+	const addLine = (raw: string): void => {
+		const line = raw.trim()
+		if (line.length === 0) return
+		lines.push(
+			line.length > MONITOR_LINE_MAX_CHARS
+				? line.slice(0, MONITOR_LINE_MAX_CHARS) + LINE_TRUNCATED
+				: line,
+		)
+		if (!timerArmed) {
+			timerArmed = true
+			timer = setTimer(() => {
+				timerArmed = false
+				if (!closed) emitPending()
+			}, MONITOR_BATCH_WINDOW_MS)
+		}
+	}
+
+	const stop = (): void => {
+		closed = true
+		if (timerArmed) {
+			clearTimer(timer)
+			timerArmed = false
+		}
+		lines = []
+		partial = ''
+	}
+
+	return {
+		push(text) {
+			if (closed || text.length === 0) return
+			stdoutChars += text.length
+			const buffered = partial + text
+			const parts = buffered.split('\n')
+			partial = keepTail(parts.pop() ?? '', MONITOR_PARTIAL_LINE_MAX_BYTES)
+			for (const part of parts) addLine(part)
+		},
+		flush() {
+			if (closed) return
+			emitPending()
+		},
+		drain() {
+			if (closed) return
+			const rest = partial
+			partial = ''
+			addLine(rest)
+			emitPending()
+		},
+		close: stop,
+		stats: () => ({ eventsDelivered, suppressed: suppressedTotal, stdoutChars }),
+	}
+}