@namzu/sdk 45.0.0 → 46.0.0

package/src/runtime/query/iteration/phases/handoff.ts

@@ -0,0 +1,74 @@
+import { GENAI, NAMZU } from '../../../../telemetry/attributes.js'
+import { NamzuError } from '../../../../types/errors/index.js'
+import type { SessionEvent } from '../../../../types/session/index.js'
+import type { ToolCallOutcome } from '../../executor.js'
+import type { IterationContext, PhaseSignal } from './context.js'
+
+/**
+ * A tool asked for a person: stop before the next model call.
+ *
+ * Runs after the batch settled, so every result — the one that asked and
+ * its siblings — is already in the transcript and queued for the session
+ * log. The checkpoint written here is taken from that state, which is what
+ * lets a resume continue exactly as it does after a provider pause: the
+ * next step is a model call that sees the results.
+ *
+ * The first request in the batch speaks for it. Two tools that both need a
+ * person need the same thing from the operator — to come and look — and
+ * one pause answers both.
+ *
+ * In a delegated child the turn fails with the reason instead. Nobody
+ * resumes a child's turn: its parent is waiting on a result, and a failed
+ * child with the reason in it is a result the parent's model can act on.
+ */
+export async function* runHandoffPause(
+	ctx: IterationContext,
+	iterationNum: number,
+	results: readonly ToolCallOutcome[],
+): AsyncGenerator<SessionEvent, PhaseSignal> {
+	const requested = results.find((result) => result.handoff !== undefined)
+	const handoff = requested?.handoff
+	if (!requested || !handoff) return 'continue'
+
+	if (ctx.delegated) {
+		ctx.log.info('A tool in a delegated turn needs a person; the turn fails', {
+			[NAMZU.TURN_ID]: ctx.recorder.turnId,
+			[NAMZU.ITERATION]: iterationNum,
+			[GENAI.TOOL_NAME]: requested.toolName,
+		})
+		throw new NamzuError({
+			code: 'tool_error',
+			message: `${requested.toolName} needs a person: ${handoff.reason}`,
+			details: { toolName: requested.toolName, handoff },
+			retryable: false,
+		})
+	}
+
+	const checkpoint = await ctx.checkpointMgr.create(ctx.recorder, iterationNum)
+	await ctx.emitEvent({
+		type: 'checkpoint_created',
+		turnId: ctx.recorder.turnId,
+		checkpointId: checkpoint.id,
+		iteration: iterationNum,
+	})
+	yield* ctx.drainPending()
+
+	await ctx.emitEvent({
+		type: 'turn_paused',
+		budget: ctx.recorder.budget?.summary(),
+		turnId: ctx.recorder.turnId,
+		checkpointId: checkpoint.id,
+		reason: handoff.reason,
+		handoff,
+	})
+	yield* ctx.drainPending()
+	ctx.recorder.setStopReason('paused')
+	ctx.log.info('Turn paused for a person', {
+		[NAMZU.TURN_ID]: ctx.recorder.turnId,
+		[NAMZU.ITERATION]: iterationNum,
+		[GENAI.TOOL_NAME]: requested.toolName,
+		'namzu.checkpoint.id': checkpoint.id,
+		'namzu.runtime.reason': handoff.reason,
+	})
+	return 'stop'
+}

package/src/runtime/query/iteration/phases/index.ts

@@ -6,3 +6,4 @@ export type { ToolReviewOutcome } from './tool-review.js'
 export { runIterationCheckpoint } from './checkpoint.js'
 export { runCompactionCheck } from './compaction.js'
 export { runAdvisoryPhase } from './advisory.js'
+export { runHandoffPause } from './handoff.js'

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -3,6 +3,7 @@ import type { ToolCallSummary } from '../../../../types/hitl/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { SessionEvent } from '../../../../types/session/index.js'
 import type { ShellDialect } from '../../../../types/tool/index.js'
+import { DECLINED_TOOL_CALL_FEEDBACK } from '../../declined.js'
 import type { PreparedToolBatch, ToolCallDenials } from '../../executor.js'
 import {
 	awaitProjectInstructionCallback,
@@ -58,7 +59,9 @@ export async function* runToolReview(
 	// skill grants to read it the same way. A test double without the method
 	// leaves it unset, which reads the line for any POSIX shell.
 	const dialectFor = (toolName: string): { commandDialect?: ShellDialect } => {
-		const executor = ctx.toolExecutor as { commandDialect?: (name: string) => ShellDialect }
+		const executor = ctx.toolExecutor as {
+			commandDialect?: (name: string) => ShellDialect
+		}
 		return typeof executor.commandDialect === 'function'
 			? { commandDialect: executor.commandDialect(toolName) }
 			: {}
@@ -448,7 +451,11 @@ export async function* runToolReview(
 			}
 			for (const path of tc.escalation?.outsidePaths ?? []) {
 				await ctx.recorder.recordAudit({
-					what: { action: 'outside_root_access', tool: tc.name, resource: path },
+					what: {
+						action: 'outside_root_access',
+						tool: tc.name,
+						resource: path,
+					},
 					outcome: 'approved',
 					reason: "the turn's review approved this call",
 				})
@@ -465,7 +472,7 @@ export async function* runToolReview(
 			})
 			yield* ctx.drainPending()
 
-			const feedback = reviewDecision.feedback || 'The user rejected this tool call.'
+			const feedback = reviewDecision.feedback || DECLINED_TOOL_CALL_FEEDBACK
 			const denials = new Map(denyAll(feedback))
 			await settleEscalations(denials, undefined)
 			await settle(denials)
@@ -495,7 +502,7 @@ export async function* runToolReview(
 					}
 				}
 				if (mod.action === 'deny' && !denials.has(mod.toolCallId)) {
-					denials.set(mod.toolCallId, 'The user denied this tool call.')
+					denials.set(mod.toolCallId, DECLINED_TOOL_CALL_FEEDBACK)
 				}
 			}
 

package/src/runtime/query/resume-pending.ts

@@ -14,6 +14,7 @@ import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { ToolExecutionSnapshot } from '../../types/session/tool-execution.js'
 import type { Logger } from '../../utils/logger.js'
 import type { RestoredCheckpoint } from './checkpoint.js'
+import { DECLINED_TOOL_CALL_FEEDBACK } from './declined.js'
 import type { PriorToolResults, ToolCallDenials, ToolExecutor } from './executor.js'
 import { PendingAnswers } from './question-park.js'
 import { readToolExecutions } from './tool-executions.js'
@@ -630,7 +631,7 @@ function derriveDenials(
 			return new Map()
 
 		case 'reject_tools': {
-			const reason = decision.feedback || 'The user rejected this tool call.'
+			const reason = decision.feedback || DECLINED_TOOL_CALL_FEEDBACK
 			return new Map(toolCalls.map((tc) => [tc.id, reason]))
 		}
 
@@ -642,7 +643,7 @@ function derriveDenials(
 			const denials = new Map<string, string>()
 			for (const mod of decision.modifications) {
 				if (mod.action === 'deny') {
-					denials.set(mod.toolCallId, 'The user denied this tool call.')
+					denials.set(mod.toolCallId, DECLINED_TOOL_CALL_FEEDBACK)
 				}
 			}
 			for (const mod of decision.modifications) {

package/src/runtime/query/review-policy.ts

@@ -27,6 +27,7 @@ import type { HITLResumeDecision, ResumeHandler, ToolCallSummary } from '../../t
 import type { ApprovalPolicy } from '../../types/hitl/policy.js'
 import type { SessionId, TurnId } from '../../types/ids/index.js'
 import { PLAN_MODE_REFUSAL } from '../../types/permission/index.js'
+import { DECLINED_TOOL_CALL_FEEDBACK } from './declined.js'
 
 export type ReviewMode =
 	/** Ask a person. The default when a `prompt` is supplied. */
@@ -196,6 +197,28 @@ export const SANDBOX_ESCAPE_UNATTENDED_REFUSAL =
 export const OUTSIDE_ROOTS_UNATTENDED_REFUSAL =
 	"Refused: a call in this batch reaches a path outside the working directory and the added directories, which needs a person to approve it each time, and nobody can be asked in this session. Nothing in this batch ran. Stay inside the working directory, or tell the user which directory you need so they can add it to the session (the CLI's --add-dir)."
 
+/**
+ * What the model is told when a batch would show it the operator's screen for
+ * the first time in a session and nobody can be asked.
+ */
+export const SCREEN_CONSENT_UNATTENDED_REFUSAL =
+	"Refused: this call would send what is on the user's screen to the model provider, which a person agrees to once per session, and nobody can be asked in this session. Nothing in this batch ran. Tell the user computer use needs their consent in an interactive session."
+
+/** What the model is told when the operator declines to share the screen. */
+export const SCREEN_CONSENT_DECLINED_FEEDBACK =
+	'The user declined to share their screen in this session. Nothing in this batch ran. Do not take screenshots or read windows again; ask the user how they want to proceed.'
+
+/**
+ * The sessions whose operator agreed to let the model see the screen.
+ *
+ * A host keeps one for as long as its sessions live and hands the same box to
+ * every policy it builds, so a mode switch keeps the answer and a new session
+ * (a different id) is asked again. The policy only adds to it.
+ */
+export interface ScreenConsentRecord {
+	readonly sessions: Set<string>
+}
+
 /** The batch a person is asked about. */
 export interface ToolReviewRequest {
 	/** Originating session, preserved by createReviewHandler for host attribution. */
@@ -203,6 +226,14 @@ export interface ToolReviewRequest {
 	/** Originating turn, preserved by createReviewHandler for host attribution. */
 	readonly turnId?: TurnId
 	readonly toolCalls: readonly ToolCallSummary[]
+	/**
+	 * This batch would send the screen to the model provider for the first
+	 * time in the session (see {@link ReviewPolicyOptions.screenConsent}).
+	 * The question is whether the model may see the screen for the rest of
+	 * the session; a yes also approves this batch, and later screen captures
+	 * in the session run without asking.
+	 */
+	readonly screenConsent?: true
 }
 
 export type ToolReviewAnswer =
@@ -249,6 +280,24 @@ export interface ReviewPolicyOptions {
 	 * either way.
 	 */
 	readonly skillGrants?: 'honour' | 'ignore'
+	/**
+	 * Ask once per session before the model first sees the screen.
+	 *
+	 * With a record, a batch holding a call that captures the screen
+	 * ({@link capturesScreen}) in a session not yet in `sessions` is put to
+	 * a person first, as a {@link ToolReviewRequest.screenConsent} request,
+	 * even when every call in it only reads: in `prompt`, `accept-edits` and
+	 * `plan`. A yes adds the session; a no refuses the batch. `strict`
+	 * refuses such a call unless a rule allowed it, `auto` never asks, and a
+	 * policy without a `prompt` refuses. A call a rule allowed is never
+	 * asked about. Omitted, the screen is treated like any other read.
+	 */
+	readonly screenConsent?: ScreenConsentRecord
+	/**
+	 * Which calls capture the screen. Default: the tool's own
+	 * `capturesScreen` declaration, read from `registry`; nothing without one.
+	 */
+	readonly capturesScreen?: (name: string, input: unknown) => boolean
 }
 
 /**
@@ -275,10 +324,61 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		options.exempt ??
 		(registry ? (name, input) => isReviewExempt(registry, name, input) : () => false)
 	const remembered = options.remembered ?? { all: false }
+	const capturesScreen =
+		options.capturesScreen ??
+		(registry
+			? (name: string, input: unknown) => {
+					const tool = registry.get(name) ?? registry.get(name.toLowerCase())
+					return tool?.capturesScreen?.(input) === true
+				}
+			: () => false)
 	return async (request): Promise<HITLResumeDecision> => {
 		if (request.type !== 'tool_review') {
 			return request.type === 'plan_approval' ? { action: 'approve_plan' } : { action: 'continue' }
 		}
+		// The one answer a person gives for this batch. The screen question
+		// below shows the whole batch, so its yes also answers any question
+		// the rest of this function would ask; nobody is asked twice.
+		let answered: ToolReviewAnswer | undefined
+		const ask = async (screenConsent?: true): Promise<ToolReviewAnswer> =>
+			answered ??
+			(prompt as ToolReviewPrompt)({
+				sessionId: request.sessionId,
+				turnId: request.turnId,
+				toolCalls: request.toolCalls,
+				...(screenConsent ? { screenConsent } : {}),
+			})
+		// The first look at the screen in a session is the operator's to allow:
+		// what is on it goes to the model provider, and a screenshot reads as
+		// harmlessly as a file read to every rule below. Asked once, in the
+		// modes where a person decides; a rule that allowed the call already
+		// said yes, and a call a rule denied will not run.
+		const consent = options.screenConsent
+		const sessionKey = String(request.sessionId ?? '')
+		if (
+			consent &&
+			mode !== 'auto' &&
+			!consent.sessions.has(sessionKey) &&
+			request.toolCalls.some(
+				(tc) =>
+					tc.authorization?.decision !== 'allow' &&
+					tc.authorization?.decision !== 'deny' &&
+					capturesScreen(tc.name, tc.input),
+			)
+		) {
+			if (mode === 'strict') return { action: 'reject_tools', feedback: STRICT_MODE_REFUSAL }
+			if (!prompt) return { action: 'reject_tools', feedback: SCREEN_CONSENT_UNATTENDED_REFUSAL }
+			const answer = await ask(true)
+			if (answer.kind === 'reject') {
+				return {
+					action: 'reject_tools',
+					feedback: answer.feedback ?? SCREEN_CONSENT_DECLINED_FEEDBACK,
+				}
+			}
+			consent.sessions.add(sessionKey)
+			if (answer.kind === 'approve-all') remembered.all = true
+			answered = answer
+		}
 		if (!batchNeedsReview(request.toolCalls, exempt)) {
 			return { action: 'approve_tools' }
 		}
@@ -325,15 +425,11 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 					? { action: 'approve_tools', confirmedEscalations: escapes }
 					: { action: 'reject_tools', feedback: SANDBOX_ESCAPE_UNATTENDED_REFUSAL }
 			}
-			const answer = await prompt({
-				sessionId: request.sessionId,
-				turnId: request.turnId,
-				toolCalls: request.toolCalls,
-			})
+			const answer = await ask()
 			if (answer.kind === 'reject') {
 				return {
 					action: 'reject_tools',
-					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 				}
 			}
 			// "Approve all" still latches for the calls that follow; it never
@@ -347,15 +443,11 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 		// With nobody to ask it is refused, not approved.
 		if (request.toolCalls.some((tc) => (tc.escalation?.outsidePaths?.length ?? 0) > 0)) {
 			if (!prompt) return { action: 'reject_tools', feedback: OUTSIDE_ROOTS_UNATTENDED_REFUSAL }
-			const answer = await prompt({
-				sessionId: request.sessionId,
-				turnId: request.turnId,
-				toolCalls: request.toolCalls,
-			})
+			const answer = await ask()
 			if (answer.kind === 'reject') {
 				return {
 					action: 'reject_tools',
-					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 				}
 			}
 			// Latches for the ordinary calls that follow, never for the next path.
@@ -382,6 +474,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				),
 		)
 		if (
+			answered === undefined &&
 			options.skillGrants !== 'ignore' &&
 			needsPerson.length > 0 &&
 			needsPerson.every(isSkillGranted)
@@ -391,11 +484,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 				skillGranted: needsPerson.map((tc) => tc.id),
 			}
 		}
-		const answer = await prompt({
-			sessionId: request.sessionId,
-			turnId: request.turnId,
-			toolCalls: request.toolCalls,
-		})
+		const answer = await ask()
 		switch (answer.kind) {
 			case 'approve':
 				return { action: 'approve_tools' }
@@ -405,7 +494,7 @@ export function createReviewHandler(options: ReviewPolicyOptions = {}): ResumeHa
 			case 'reject':
 				return {
 					action: 'reject_tools',
-					feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+					feedback: answer.feedback ?? DECLINED_TOOL_CALL_FEEDBACK,
 				}
 		}
 	}

package/src/schedules/cron.ts

@@ -0,0 +1,202 @@
+/**
+ * Five-field cron, parsed into sets.
+ *
+ * Minute, hour, day of month, month, day of week. Lists, ranges, steps and
+ * three-letter names; `0` and `7` are both Sunday. Vixie semantics for the
+ * two day fields: when BOTH are restricted a day matches if EITHER does, which
+ * is what every cron and every existing crontab assumes.
+ *
+ * Refused, each by name: `L`, `W`, `#`, `?`, a sixth (seconds) field and
+ * `@reboot`. A refused token is a better answer than a job that silently
+ * means something the operator did not write.
+ */
+
+import { ScheduleValidationError } from './errors.js'
+import type { CronExpression } from './types.js'
+
+const MACROS: Readonly<Record<string, string>> = {
+	'@yearly': '0 0 1 1 *',
+	'@annually': '0 0 1 1 *',
+	'@monthly': '0 0 1 * *',
+	'@weekly': '0 0 * * 0',
+	'@daily': '0 0 * * *',
+	'@midnight': '0 0 * * *',
+	'@hourly': '0 * * * *',
+}
+
+const MONTH_NAMES = [
+	'jan',
+	'feb',
+	'mar',
+	'apr',
+	'may',
+	'jun',
+	'jul',
+	'aug',
+	'sep',
+	'oct',
+	'nov',
+	'dec',
+]
+const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat']
+
+interface FieldSpec {
+	readonly label: string
+	readonly min: number
+	readonly max: number
+	readonly names?: readonly string[]
+	/** Where `names[0]` sits in the numeric range. */
+	readonly nameBase?: number
+}
+
+const FIELDS: readonly FieldSpec[] = [
+	{ label: 'minute', min: 0, max: 59 },
+	{ label: 'hour', min: 0, max: 23 },
+	{ label: 'day of month', min: 1, max: 31 },
+	{ label: 'month', min: 1, max: 12, names: MONTH_NAMES, nameBase: 1 },
+	{ label: 'day of week', min: 0, max: 7, names: DAY_NAMES, nameBase: 0 },
+]
+
+function parseValue(raw: string, field: FieldSpec): number {
+	const lower = raw.toLowerCase()
+	if (field.names) {
+		const at = field.names.indexOf(lower)
+		if (at >= 0) return at + (field.nameBase ?? 0)
+	}
+	if (!/^\d+$/.test(raw)) {
+		throw new ScheduleValidationError(`${field.label}: "${raw}" is not a number or a name`, raw)
+	}
+	const n = Number(raw)
+	if (n < field.min || n > field.max) {
+		throw new ScheduleValidationError(
+			`${field.label}: ${n} is outside ${field.min}-${field.max}`,
+			raw,
+		)
+	}
+	return n
+}
+
+function parseField(text: string, field: FieldSpec): number[] {
+	if (text === '') throw new ScheduleValidationError(`${field.label}: empty field`, text)
+	const values = new Set<number>()
+	for (const part of text.split(',')) {
+		if (part === '') throw new ScheduleValidationError(`${field.label}: empty list entry`, text)
+		// Names (`jul`, `wed`) are removed first: they carry the letters the
+		// refused `L` and `W` are spelled with.
+		const withoutNames = part.replace(/[a-z]{3}/gi, (word) =>
+			field.names?.includes(word.toLowerCase()) ? '' : word,
+		)
+		for (const refused of ['L', 'W', '#', '?']) {
+			if (withoutNames.toUpperCase().includes(refused)) {
+				throw new ScheduleValidationError(
+					`${field.label}: "${refused}" is not supported (in "${part}")`,
+					refused,
+				)
+			}
+		}
+		const [rangeText = '', stepText, extra] = part.split('/')
+		if (extra !== undefined) {
+			throw new ScheduleValidationError(`${field.label}: "${part}" has more than one step`, part)
+		}
+		let step = 1
+		if (stepText !== undefined) {
+			if (!/^\d+$/.test(stepText) || Number(stepText) === 0) {
+				throw new ScheduleValidationError(
+					`${field.label}: step "${stepText}" must be a whole number above 0`,
+					part,
+				)
+			}
+			step = Number(stepText)
+		}
+		let lo: number
+		let hi: number
+		if (rangeText === '*') {
+			lo = field.min
+			hi = field.label === 'day of week' ? 6 : field.max
+		} else if (rangeText.includes('-')) {
+			const [a = '', b = '', more] = rangeText.split('-')
+			if (more !== undefined) {
+				throw new ScheduleValidationError(`${field.label}: "${rangeText}" is not a range`, part)
+			}
+			lo = parseValue(a, field)
+			hi = parseValue(b, field)
+			if (hi < lo) {
+				throw new ScheduleValidationError(
+					`${field.label}: range "${rangeText}" runs backwards`,
+					rangeText,
+				)
+			}
+		} else {
+			lo = parseValue(rangeText, field)
+			// `5/15` means "from 5, every 15", as in Vixie cron.
+			hi = stepText !== undefined ? (field.label === 'day of week' ? 6 : field.max) : lo
+		}
+		for (let v = lo; v <= hi; v += step) values.add(v)
+	}
+	return [...values].sort((a, b) => a - b)
+}
+
+/**
+ * Parse a five-field expression or a macro. Throws
+ * {@link ScheduleValidationError} naming the offending token.
+ */
+export function parseCronExpression(input: string): CronExpression {
+	const trimmed = input.trim()
+	if (trimmed === '') throw new ScheduleValidationError('empty cron expression', '')
+	let text = trimmed
+	if (trimmed.startsWith('@')) {
+		const macro = MACROS[trimmed.toLowerCase()]
+		if (!macro) {
+			throw new ScheduleValidationError(`"${trimmed}" is not a supported macro`, trimmed)
+		}
+		text = macro
+	}
+	const fields = text.split(/\s+/)
+	if (fields.length === 6) {
+		throw new ScheduleValidationError(
+			'six fields: a seconds field is not supported; use five fields (minute hour day month weekday)',
+			fields[0],
+		)
+	}
+	if (fields.length !== 5) {
+		throw new ScheduleValidationError(
+			`expected five fields (minute hour day month weekday), got ${fields.length}`,
+			text,
+		)
+	}
+	const [mi = '', ho = '', dom = '', mon = '', dow = ''] = fields
+	const minutes = parseField(mi, FIELDS[0] as FieldSpec)
+	const hours = parseField(ho, FIELDS[1] as FieldSpec)
+	const daysOfMonth = parseField(dom, FIELDS[2] as FieldSpec)
+	const months = parseField(mon, FIELDS[3] as FieldSpec)
+	const weekdays = parseField(dow, FIELDS[4] as FieldSpec)
+	const normalizedWeekdays = [...new Set(weekdays.map((d) => (d === 7 ? 0 : d)))].sort(
+		(a, b) => a - b,
+	)
+	const fixedTime = !/[*/]/.test(mi) && !/[*/]/.test(ho)
+	return {
+		source: fields.join(' '),
+		minutes,
+		hours,
+		daysOfMonth,
+		months,
+		daysOfWeek: normalizedWeekdays,
+		domRestricted: !dom.startsWith('*'),
+		dowRestricted: !dow.startsWith('*'),
+		fixedTime,
+	}
+}
+
+/** Whether the civil date matches the day fields (Vixie OR rule). */
+export function cronMatchesDay(
+	expr: CronExpression,
+	month: number,
+	day: number,
+	weekday: number,
+): boolean {
+	if (!expr.months.includes(month)) return false
+	const domMatch = expr.daysOfMonth.includes(day)
+	const dowMatch = expr.daysOfWeek.includes(weekday)
+	if (expr.domRestricted && expr.dowRestricted) return domMatch || dowMatch
+	return domMatch && dowMatch
+}