@namzu/sdk 59.0.0 → 60.1.0

package/src/runtime/jobs/liveness.ts

@@ -0,0 +1,144 @@
+/**
+ * What a host can say about one running item, from three facts it reads
+ * itself: where it is, when it last made progress, and whether it is alive.
+ *
+ * Pure: no clock, no process probe. The caller passes `now` and the probe's
+ * answer, so the same table of cases runs under a fake clock. The kinds
+ * (background job, monitor, delegated agent, workflow run) share one verdict
+ * so the outstanding-work note and every status read print the same words.
+ */
+
+/** Silence shorter than this still reads as progress. */
+export const LIVENESS_QUIET_MS = 30_000
+
+/**
+ * Silence from an item that is alive and has no known reason to wait. The
+ * same number `wait_for_job` uses for its idle bound, so there is one
+ * threshold to explain.
+ */
+export const LIVENESS_STALLED_MS = 2 * 60 * 1000
+
+export type LivenessKind = 'job' | 'monitor' | 'agent' | 'workflow'
+
+export type LivenessVerdict = 'progressing' | 'waiting' | 'stalled' | 'dead' | 'finished'
+
+export interface LivenessInput {
+	readonly kind: LivenessKind
+	readonly id: string
+	/** Short name the person would recognise: a command, a description, a workflow name. */
+	readonly label: string
+	/** Where it is: the last output line, the current tool, the phase. One line, already bounded. */
+	readonly where?: string
+	readonly startedAt: number
+	/** When it last made progress (epoch ms). Absent means it has not yet: the start counts. */
+	readonly lastProgressAt?: number
+	/** The probe's answer: is the process or run still there. */
+	readonly alive: boolean
+	/** A result or an end has arrived. */
+	readonly finished?: boolean
+	/** What it is known to be waiting on, when it is waiting for a reason (a tool, a free slot). */
+	readonly waitingOn?: string
+	readonly waitingSince?: number
+}
+
+export interface Liveness {
+	readonly kind: LivenessKind
+	readonly id: string
+	readonly label: string
+	readonly where?: string
+	readonly verdict: LivenessVerdict
+	/** Whole seconds since the last progress (or the start). */
+	readonly idleSeconds: number
+	/** Whole seconds since it started. */
+	readonly ageSeconds: number
+	/** Present when the verdict is `waiting` with a reason. */
+	readonly waitingOn?: string
+	readonly waitingSeconds?: number
+}
+
+export interface LivenessThresholds {
+	readonly quietMs?: number
+	readonly stalledMs?: number
+}
+
+const seconds = (ms: number): number => Math.max(0, Math.floor(ms / 1000))
+
+/** Decide the verdict. Order matters: a result beats everything, then death, then the reason to wait. */
+export function judgeLiveness(
+	input: LivenessInput,
+	now: number,
+	thresholds: LivenessThresholds = {},
+): Liveness {
+	const quietMs = thresholds.quietMs ?? LIVENESS_QUIET_MS
+	const stalledMs = thresholds.stalledMs ?? LIVENESS_STALLED_MS
+	const last = Math.max(input.startedAt, input.lastProgressAt ?? input.startedAt)
+	const idle = Math.max(0, now - last)
+	let verdict: LivenessVerdict
+	if (input.finished) verdict = 'finished'
+	else if (!input.alive) verdict = 'dead'
+	else if (input.waitingOn !== undefined) verdict = 'waiting'
+	else if (idle >= stalledMs) verdict = 'stalled'
+	else if (idle >= quietMs) verdict = 'waiting'
+	else verdict = 'progressing'
+	const waitingOn =
+		verdict === 'waiting' && input.waitingOn !== undefined ? input.waitingOn : undefined
+	const waitingSince = input.waitingSince ?? last
+	return {
+		kind: input.kind,
+		id: input.id,
+		label: input.label,
+		...(input.where !== undefined ? { where: input.where } : {}),
+		verdict,
+		idleSeconds: seconds(idle),
+		ageSeconds: seconds(now - input.startedAt),
+		...(waitingOn !== undefined ? { waitingOn, waitingSeconds: seconds(now - waitingSince) } : {}),
+	}
+}
+
+/** `45s`, `3m 05s`, `1h 02m`: short, for a line a person or the model reads. */
+export function formatLivenessAge(totalSeconds: number): string {
+	const s = Math.max(0, Math.floor(totalSeconds))
+	if (s < 60) return `${s}s`
+	const m = Math.floor(s / 60)
+	if (m < 60) return `${m}m ${String(s % 60).padStart(2, '0')}s`
+	return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, '0')}m`
+}
+
+function oneLine(text: string, max: number): string {
+	const flat = text.replace(/\s+/g, ' ').trim()
+	return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`
+}
+
+const LABEL_MAX = 80
+const WHERE_MAX = 120
+
+/**
+ * One line per item, the same for the note and for the list reads:
+ * `job b1a2 "npm test" - progressing - last progress 4s ago - at: compiling`.
+ * Everything free-form is clipped and flattened; the line carries data, not
+ * instructions.
+ */
+export function formatLivenessLine(item: Liveness): string {
+	const parts = [`${item.kind} ${item.id} "${oneLine(item.label, LABEL_MAX)}"`]
+	if (item.verdict === 'waiting' && item.waitingOn !== undefined) {
+		parts.push(
+			`waiting on ${oneLine(item.waitingOn, LABEL_MAX)} for ${formatLivenessAge(item.waitingSeconds ?? item.idleSeconds)}`,
+		)
+	} else if (item.verdict === 'finished') {
+		parts.push(`finished after ${formatLivenessAge(item.ageSeconds)}`)
+	} else if (item.verdict === 'dead') {
+		parts.push(
+			`dead: gone without a result after ${formatLivenessAge(item.ageSeconds)}, last progress ${formatLivenessAge(item.idleSeconds)} ago`,
+		)
+	} else {
+		parts.push(item.verdict)
+		parts.push(
+			item.idleSeconds === 0
+				? 'last progress just now'
+				: `last progress ${formatLivenessAge(item.idleSeconds)} ago`,
+		)
+	}
+	if (item.where !== undefined && item.where.length > 0)
+		parts.push(`at: ${oneLine(item.where, WHERE_MAX)}`)
+	return parts.join(' - ')
+}

package/src/runtime/jobs/registry.ts

@@ -1,7 +1,7 @@
 import type { spawn } from 'node:child_process'
 
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js'
-import { killTree } from '../../process/kill-tree.js'
+import { isSignalablePid, killTree } from '../../process/kill-tree.js'
 import { describeSpawnFailure, spawnHostShell } from '../../tools/command-shell.js'
 import { scrubInheritedEnv } from '../../tools/env-scrub.js'
 import { createHostOutputDecoder } from '../../tools/host-output.js'
@@ -12,6 +12,7 @@ import type {
 import type { MonitorWebSocketTarget } from '../../types/tool/index.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { oneMetadataLine } from '../system-events.js'
+import { stopAtHostExit } from './host-exit-finalizer.js'
 import { createBackgroundJobId } from './job-id.js'
 import {
 	MONITOR_TIMEOUT_CAP_MS,
@@ -53,6 +54,10 @@ export interface BackgroundJob {
 	readonly command: string
 	readonly status: BackgroundJobStatus
 	readonly startedAt: number
+	/** When the job last wrote output (epoch ms). Absent until it has written anything. */
+	readonly lastOutputAt?: number
+	/** The last non-empty output line, flattened and clipped to {@link LAST_OUTPUT_LINE_MAX}. */
+	readonly lastOutputLine?: string
 	readonly exitedAt?: number
 	readonly exitCode?: number
 	readonly signal?: string
@@ -347,7 +352,7 @@ interface MonitorState {
 
 /** Whether any process of the group led by `pid` is still alive. */
 function groupAlive(pid: number | undefined): boolean {
-	if (pid === undefined || process.platform === 'win32') return false
+	if (!isSignalablePid(pid) || process.platform === 'win32') return false
 	try {
 		process.kill(-pid, 0)
 		return true
@@ -356,8 +361,67 @@ function groupAlive(pid: number | undefined): boolean {
 	}
 }
 
+/**
+ * The same probe for a status read: a group that exists but is not ours to
+ * signal (EPERM) is there. The close handler keeps {@link groupAlive}, which
+ * must not wait on a group it can never see end.
+ *
+ * Not proof the group is still the job's: between the group ending and the
+ * record closing, a recycled pid that leads a new group would read as alive.
+ * The close handler polls every {@link GROUP_POLL_MS}, so the window is
+ * that small.
+ */
+function groupPresent(pid: number): boolean {
+	if (!isSignalablePid(pid)) return false
+	try {
+		process.kill(-pid, 0)
+		return true
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === 'EPERM'
+	}
+}
+
 const GROUP_POLL_MS = 250
 
+/** Longest `lastOutputLine` kept on a job record. */
+export const LAST_OUTPUT_LINE_MAX = 160
+
+/**
+ * Drop terminal control sequences and control characters, keeping one space
+ * where a control character stood. Done by code point so no pattern has to
+ * spell a control character.
+ */
+function plainLine(raw: string): string {
+	let out = ''
+	let i = 0
+	while (i < raw.length) {
+		const code = raw.charCodeAt(i)
+		if (code === 0x1b && raw[i + 1] === '[') {
+			// CSI: parameters and intermediates, then one final byte in @..~.
+			i += 2
+			while (i < raw.length && raw.charCodeAt(i) >= 0x20 && raw.charCodeAt(i) <= 0x3f) i += 1
+			i += 1
+			continue
+		}
+		out += code < 0x20 || code === 0x7f ? ' ' : (raw[i] ?? '')
+		i += 1
+	}
+	return out.replace(/ {2,}/g, ' ').trim()
+}
+
+/** The last non-empty line of `text`, flattened and clipped; `undefined` when it has none. */
+function lastLineOf(text: string): string | undefined {
+	const lines = text.split('\n')
+	for (let index = lines.length - 1; index >= 0; index -= 1) {
+		const flat = plainLine(lines[index] ?? '')
+		if (flat.length > 0)
+			return flat.length <= LAST_OUTPUT_LINE_MAX
+				? flat
+				: `${flat.slice(0, LAST_OUTPUT_LINE_MAX - 1)}…`
+	}
+	return undefined
+}
+
 /**
  * Why a command that was running in the foreground moved to the background:
  * the person asked (`user`), or the person sent a message that has to reach
@@ -708,6 +772,7 @@ export class BackgroundJobRegistry {
 				const finalize = (code: number | null, signal: NodeJS.Signals | null): void => {
 					if (finalized) return
 					finalized = true
+					untrackAtHostExit()
 					entry.record = {
 						...entry.record,
 						// A job killed by this registry says `killed`, not
@@ -788,11 +853,26 @@ export class BackgroundJobRegistry {
 			}),
 		}
 		entry.finalize = finalizeEntry
+		// A job that is not stopped before the host exits is an orphan: nothing
+		// owns its id any more. A remote job confirms its own termination and is
+		// not signalled from an exit listener.
+		const untrackAtHostExit = entry.terminateProcess
+			? () => {}
+			: stopAtHostExit({
+					child,
+					...(entry.killProcess ? { kill: entry.killProcess } : {}),
+				})
 
 		const append = (text: string, stream: 'stdout' | 'stderr'): void => {
 			const chunk: OutputChunk = { stream, offset: entry.produced, bytes: Buffer.from(text) }
 			if (chunk.bytes.length === 0) return
 			entry.produced += chunk.bytes.length
+			const line = lastLineOf(text)
+			entry.record = {
+				...entry.record,
+				lastOutputAt: Date.now(),
+				...(line !== undefined ? { lastOutputLine: line } : {}),
+			}
 			entry.buffer += text
 			entry.buffer = outputTail(entry.buffer, this.maxBytes).text
 			entry.outputChunks.push(chunk)
@@ -898,6 +978,20 @@ export class BackgroundJobRegistry {
 		return entry.record
 	}
 
+	/**
+	 * Whether the job's process group is still there, asked of the system rather
+	 * than inferred from the record. A job with no process of its own to probe
+	 * (a sandboxed or WebSocket source, or a platform without process groups)
+	 * is alive exactly when the registry says it is running.
+	 */
+	isAlive(id: string): boolean {
+		const entry = this.jobs.get(id)
+		if (!entry || entry.record.status !== 'running') return false
+		const pid = entry.child.pid
+		if (pid === undefined || process.platform === 'win32') return true
+		return groupPresent(pid)
+	}
+
 	/**
 	 * Await one job's exit — the public counterpart to `onExit`, for a
 	 * caller that wants a single result rather than a standing
@@ -1253,6 +1347,12 @@ export function bindOwner(
 		 * than present and silently doing nothing.
 		 */
 		readonly onAwaited?: (id: string) => void
+		/**
+		 * Be told that a tool result has handed the model this job's exit, so the
+		 * notice announcing the same exit can be withdrawn. Like `onAwaited` it
+		 * belongs to the turn; absent, `markCollected` is absent from the ref.
+		 */
+		readonly onCollected?: (id: string) => void
 		/**
 		 * The longest a monitor started through this binding may live. A host
 		 * may lower it (a single-shot run has no tomorrow to watch for); the
@@ -1387,11 +1487,23 @@ export function bindOwner(
 					},
 				}
 			: {}),
+		...(defaults.onCollected
+			? {
+					markCollected: (id: string) => {
+						mine(id)
+						defaults.onCollected?.(id)
+					},
+				}
+			: {}),
 		kill: async (id: string) => {
 			mine(id)
 			return await registry.kill(id)
 		},
 		list: () => registry.list(owner),
+		isAlive: (id: string) => {
+			mine(id)
+			return registry.isAlive(id)
+		},
 	}
 }
 

package/src/runtime/jobs/wake-budget.ts

@@ -0,0 +1,55 @@
+/**
+ * A bound on how many times in a row a session wakes the model on its own.
+ *
+ * A finished background job wakes an idle session, and the turn that wakes may
+ * start another job whose exit wakes it again, with nobody reading. For an
+ * owner that nobody is watching, that chain never has to end. The budget caps
+ * it: after `max` wakes in a row no further exit wakes the model, and the
+ * exits stay pending so the next message from a person carries them.
+ *
+ * **Off unless asked.** An interactive session has a person to stop it, and a
+ * cap there would only get in the way. `max` of `undefined` (or anything that
+ * is not a positive integer) never limits.
+ *
+ * **Only a person resets it.** A wake, a job notice or a tool result is not
+ * evidence anyone is looking; a human message is.
+ */
+export class WakeBudget {
+	private woken = 0
+	private readonly max: number | undefined
+
+	constructor(max?: number) {
+		this.max = max !== undefined && Number.isInteger(max) && max > 0 ? max : undefined
+	}
+
+	/** Whether another automatic wake is allowed. */
+	get canWake(): boolean {
+		return this.max === undefined || this.woken < this.max
+	}
+
+	/** Count one automatic wake. Call when a wake begins a turn. */
+	recordWake(): void {
+		this.woken++
+	}
+
+	/** A person wrote: the chain is attended again. */
+	reset(): void {
+		this.woken = 0
+	}
+
+	/** Wakes since the last human message. */
+	get consecutiveWakes(): number {
+		return this.woken
+	}
+}
+
+/**
+ * The budget a host asked for through `NAMZU_MAX_CONSECUTIVE_WAKES`, or an
+ * unlimited one. Anything but a positive integer means no limit.
+ */
+export function wakeBudgetFromEnv(
+	env: Record<string, string | undefined> = process.env,
+): WakeBudget {
+	const raw = env.NAMZU_MAX_CONSECUTIVE_WAKES?.trim()
+	return new WakeBudget(raw && /^\d+$/.test(raw) ? Number(raw) : undefined)
+}

package/src/runtime/query/detached-calls.ts

@@ -0,0 +1,135 @@
+import { frameNotice } from '../../types/message/notice-frame.js'
+import type { ToolCallOutcome } from './executor.js'
+
+/**
+ * Tool calls that were still running when the operator wrote.
+ *
+ * A model cannot answer while a `tool_use` block has no `tool_result`, and a
+ * long call used to hold the operator's question until it finished: the person
+ * asked how things stand and heard nothing for as long as the call took. When
+ * the operator writes while a call has been running for a while, the batch
+ * answers the unfinished calls with a placeholder result, the model reads the
+ * message at once, and the call carries on untouched. Its real result reaches
+ * the model later as a message of its own that names the call.
+ *
+ * This holds the bookkeeping for one turn: which calls were handed back this
+ * way, and the outcomes that have arrived since.
+ */
+
+/** How long a call must have been running before an operator message detaches it. */
+export const DETACH_AFTER_MS = 2_000
+
+/**
+ * What a model reads as the result of a call that is still running.
+ *
+ * It says the call goes on, what not to do about it, and what to tell the
+ * person; the model never sees these words as anything the tool printed.
+ */
+export function stillRunningResult(toolName: string, started = true): string {
+	if (!started) {
+		return [
+			`[Waiting to start] The ${toolName} call has not started: it is queued behind an earlier call in this batch. The operator wrote a message while the batch ran, and that message follows so you can answer it now.`,
+			'The call will start by itself when the earlier one ends, and its result will arrive in a later message that names this call id.',
+			'Repeating the call would run the work twice, and waiting or polling for it would delay your answer, so do neither. If they ask, say it has not started yet.',
+		].join('\n')
+	}
+	return [
+		`[Still running] The ${toolName} call has not finished. The operator wrote a message while it ran, and that message follows so you can answer it now.`,
+		'The call was not interrupted. Its result will arrive on its own, in a later message that names this call id.',
+		'Repeating the call would run the work twice, and waiting or polling for it would delay your answer, so do neither.',
+		'You cannot stop it from here, so do not say you cancelled or dropped it. On the operator’s screen it still shows as in progress; if they ask, say it is still running.',
+	].join('\n')
+}
+
+/** What a model reads when a call it was told was still running has finished. */
+export function formatLateResults(outcomes: readonly ToolCallOutcome[]): string {
+	const parts = outcomes.map(
+		(outcome) =>
+			`The ${outcome.toolName} call with id ${outcome.toolCallId}, which you were told was still running, has finished${outcome.isError ? ' with an error' : ''}. This is what it returned:\n${outcome.output}`,
+	)
+	return frameNotice('job', '[Tool call finished]', parts.join('\n\n'))
+}
+
+export class DetachedCalls {
+	private readonly open = new Map<string, string>()
+	private arrived: ToolCallOutcome[] = []
+	private readonly waiters = new Set<() => void>()
+
+	/**
+	 * `waitForOperator` resolves when the operator wrote and at no other wake: a
+	 * child's notice or a peer's mail must not hand a call back, because the
+	 * model would then get a turn with no question to answer.
+	 */
+	constructor(readonly waitForOperator?: (signal: AbortSignal) => Promise<void>) {}
+
+	/** A call was answered with the placeholder and is still running. */
+	begin(toolCallId: string, toolName: string): void {
+		this.open.set(toolCallId, toolName)
+	}
+
+	/** The real outcome of a detached call. Ignored for a call that was never detached. */
+	settle(outcome: ToolCallOutcome): void {
+		if (!this.open.delete(outcome.toolCallId)) return
+		this.arrived.push(outcome)
+		this.wake()
+	}
+
+	/** True while a call is still running or its outcome has not been read. */
+	get hasWork(): boolean {
+		return this.open.size > 0 || this.arrived.length > 0
+	}
+
+	/** Calls still running. */
+	get running(): number {
+		return this.open.size
+	}
+
+	/** The outcomes that have arrived since the last read, in arrival order. */
+	take(): readonly ToolCallOutcome[] {
+		const taken = this.arrived
+		this.arrived = []
+		return taken
+	}
+
+	/**
+	 * Resolves when an outcome is waiting, when nothing is running, after
+	 * `graceMs`, or rejects when `signal` aborts. Resolving early is never
+	 * delivery: the caller reads with {@link take}.
+	 */
+	waitForArrival(graceMs: number, signal: AbortSignal): Promise<void> {
+		if (this.arrived.length > 0 || this.open.size === 0) return Promise.resolve()
+		if (signal.aborted) return Promise.reject(signal.reason)
+		return new Promise<void>((resolve, reject) => {
+			const done = (): void => {
+				clearTimeout(timer)
+				this.waiters.delete(wake)
+				signal.removeEventListener('abort', abort)
+			}
+			const wake = (): void => {
+				done()
+				resolve()
+			}
+			const abort = (): void => {
+				done()
+				reject(signal.reason)
+			}
+			const timer = setTimeout(wake, Math.max(0, graceMs))
+			this.waiters.add(wake)
+			signal.addEventListener('abort', abort, { once: true })
+		})
+	}
+
+	private wake(): void {
+		for (const wake of [...this.waiters]) wake()
+	}
+}
+
+/**
+ * What one batch needs to hand its unfinished calls back. `requested` settles
+ * once the operator has written and the batch has run for {@link DETACH_AFTER_MS};
+ * `calls` receives each call that was handed back and, later, its outcome.
+ */
+export interface BatchDetach {
+	readonly requested: Promise<void>
+	readonly calls: DetachedCalls
+}