@namzu/sdk 44.3.0 → 45.1.0

package/src/tools/schedules/prompt-scan.ts

@@ -0,0 +1,96 @@
+/**
+ * A tripwire over a scheduled prompt, run when the job is proposed.
+ *
+ * A scheduled prompt runs later with nobody watching, so a prompt that hides
+ * characters, tells the model to ignore its instructions, or reads secrets and
+ * sends them somewhere deserves a second look before anyone confirms it.
+ * Findings are shown to the person confirming; they never block on their own,
+ * because the operator may mean exactly what they wrote.
+ */
+
+/** Characters that render as nothing or reorder what is shown. */
+/** Invisible and direction-changing code point ranges, inclusive. */
+const INVISIBLE_RANGES: readonly (readonly [number, number])[] = [
+	[0x200b, 0x200f],
+	[0x202a, 0x202e],
+	[0x2060, 0x2064],
+	[0x2066, 0x2069],
+	[0xfeff, 0xfeff],
+	[0x00ad, 0x00ad],
+]
+
+function isInvisible(code: number): boolean {
+	return INVISIBLE_RANGES.some(([lo, hi]) => code >= lo && code <= hi)
+}
+
+function hasInvisible(text: string): boolean {
+	for (const ch of text) if (isInvisible(ch.codePointAt(0) ?? 0)) return true
+	return false
+}
+
+/** C0 controls other than tab, newline and carriage return, and DEL. */
+function isControl(code: number): boolean {
+	return (code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d) || code === 0x7f
+}
+
+function hasControl(text: string): boolean {
+	for (let i = 0; i < text.length; i++) if (isControl(text.charCodeAt(i))) return true
+	return false
+}
+
+const DIRECTIVES: readonly RegExp[] = [
+	/\bignore (all |any )?(the )?(previous|prior|above|earlier) (instructions|rules|messages)\b/i,
+	/\bdisregard (all |any )?(the )?(previous|prior|above|system) /i,
+	/\b(reveal|print|show|repeat) (your|the) (system prompt|instructions)\b/i,
+	/\byou are no longer\b/i,
+]
+
+const SECRET_READS: readonly RegExp[] = [
+	/~?\/?\.ssh\b|\bid_(rsa|ed25519|ecdsa)\b/i,
+	/\.aws\/credentials|\.config\/gcloud|\.kube\/config|\.netrc\b|\.npmrc\b|\.pypirc\b/i,
+	/\bcredentials\.json\b|\.env\b/i,
+	/\b(printenv|env)\b\s*($|[|;&>])/i,
+	/\b[A-Z0-9_]*(API_KEY|SECRET|TOKEN|PASSWORD)\b/,
+]
+
+const EXFILTRATION: readonly RegExp[] = [
+	/\b(curl|wget)\b[^\n|]*\|\s*(ba|z|da)?sh\b/i,
+	/\bcurl\b[^\n]*\s(-d|--data(-binary|-raw)?|-F|--form|-T|--upload-file|-X\s*(POST|PUT))\b/i,
+	/\b(nc|ncat|netcat|socat)\b\s+\S+\s+\d+/i,
+	/\bbase64\b[^\n]*\|\s*(curl|wget|nc)\b/i,
+]
+
+/** What the scan found, as sentences for the confirmation screen. Empty when nothing. */
+export function scanSchedulePrompt(prompt: string): string[] {
+	const findings: string[] = []
+	if (hasInvisible(prompt)) {
+		findings.push('The prompt contains invisible or direction-changing characters.')
+	}
+	if (hasControl(prompt)) findings.push('The prompt contains control characters.')
+	if (DIRECTIVES.some((re) => re.test(prompt))) {
+		findings.push('The prompt tells the model to ignore or reveal its instructions.')
+	}
+	if (SECRET_READS.some((re) => re.test(prompt))) {
+		findings.push('The prompt mentions credentials, keys or secret files.')
+	}
+	if (EXFILTRATION.some((re) => re.test(prompt))) {
+		findings.push('The prompt pipes a download into a shell or sends data to a remote address.')
+	}
+	return findings
+}
+
+/**
+ * The prompt with every invisible and control character made visible as
+ * `<U+XXXX>`, so the person confirming sees what the model will read.
+ */
+export function revealHiddenCharacters(prompt: string): string {
+	let out = ''
+	for (const ch of prompt) {
+		const code = ch.codePointAt(0) ?? 0
+		out +=
+			isControl(code) || isInvisible(code)
+				? `<U+${code.toString(16).toUpperCase().padStart(4, '0')}>`
+				: ch
+	}
+	return out
+}

package/src/tools/schedules/schedule-tool.ts

@@ -0,0 +1,376 @@
+import { z } from 'zod'
+import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
+import { canonicalizeBrowserSitePattern } from '../builtins/browser-url.js'
+import { defineTool } from '../defineTool.js'
+import { presentScheduleCall, presentScheduleResult } from './present.js'
+import { scanSchedulePrompt } from './prompt-scan.js'
+import type {
+	ScheduleBrowserGrant,
+	ScheduleBrowserSiteLevel,
+	ScheduleJobDraft,
+	ScheduleToolHost,
+} from './types.js'
+
+export const SCHEDULE_TOOL_NAME = 'schedule'
+
+/**
+ * A person reads the whole proposal — the prompt, the rules, the schedule,
+ * the credential source — before answering `create`, `resume` or `delete`.
+ * The executor's `DEFAULT_TOOL_TIMEOUT_MS` (two minutes) is sized for a tool
+ * call, not a person on the other end of a screen, and would abandon the
+ * call out from under them mid-read. `save_skill`
+ * (`packages/cli/src/skills/save.ts`) waits on the same kind of answer and
+ * uses the same thirty minutes, for the same reason.
+ */
+const OPERATOR_CONFIRM_TIMEOUT_MS = 30 * 60_000
+
+const EFFECT = z.enum(['allow', 'ask', 'deny'])
+const NETWORK_TOOLS = ['web_fetch', 'web_search']
+const BROWSER_PROFILE = /^[a-z0-9][a-z0-9-]{0,62}$/
+
+const inputSchema = z.object({
+	action: z
+		.enum(['create', 'list', 'pause', 'resume', 'delete'])
+		.describe('What to do. create, resume and delete ask the operator first.'),
+	name: z
+		.string()
+		.regex(/^[a-z0-9][a-z0-9-]{0,62}$/)
+		.optional()
+		.describe('create: job name, lowercase letters, digits and dashes'),
+	prompt: z.string().min(1).max(20_000).optional().describe('create: what the run is asked to do'),
+	when: z
+		.string()
+		.optional()
+		.describe('create: "every 30m", "0 9 * * 1-5" (cron), "at 2026-09-24 09:00", "in 2h"'),
+	folder: z
+		.string()
+		.optional()
+		.describe("create: folder to run in; leave unset for the session's unless the user named one"),
+	tz: z
+		.string()
+		.optional()
+		.describe(
+			"create: IANA time zone; leave unset for the operator's own zone unless the user named another",
+		),
+	permissions: z
+		.object({
+			preset: z
+				.enum(['read-only', 'edit-in-folder'])
+				.optional()
+				.describe(
+					'read-only: read/glob/grep/ls only. edit-in-folder: also edit and write, bash asks',
+				),
+			unmatched: z
+				.enum(['park', 'deny'])
+				.describe('A call no rule covers: park (wait for the operator) or deny'),
+			execution: z
+				.enum(['host', 'sandbox'])
+				.optional()
+				.describe(
+					'Where commands run; leave unset (this machine) unless the user asked for a sandbox',
+				),
+			rules: z
+				.record(z.string(), z.union([EFFECT, z.record(z.string(), EFFECT)]))
+				.optional()
+				.describe('Extra rules, e.g. {"bash": {"npm test*": "allow"}}'),
+			browser: z
+				.object({
+					profile: z
+						.string()
+						.regex(BROWSER_PROFILE)
+						.describe('Browser profile the operator signed in with, e.g. "work"'),
+					sites: z
+						.record(z.string(), z.enum(['read', 'ask', 'act']))
+						.describe(
+							'Site to level, e.g. {"https://github.com": "read"}. read: open and read only; ask: changes wait for the operator; act: changes run unasked. Unlisted sites are denied; there is no "*".',
+						),
+					headed: z.boolean().optional().describe('Show the browser window; default no window'),
+				})
+				.optional()
+				.describe('Browser access; omit for none'),
+		})
+		.optional()
+		.describe('create: REQUIRED explicit permission set; there is no default'),
+	budget: z
+		.object({
+			maxIterations: z
+				.number()
+				.int()
+				.positive()
+				.optional()
+				.describe(
+					'Model steps one run may take (each model call with its tool calls is one step), not how many times the job runs. Omit for the default; a browser task takes 10 or more.',
+				),
+			tokenBudget: z
+				.number()
+				.int()
+				.positive()
+				.optional()
+				.describe(
+					'Tokens one run may spend in total. Every model call resends the whole prompt (often 10,000-30,000 tokens each), so a run needs far more than its answer; omit for the default.',
+				),
+			timeoutMs: z
+				.number()
+				.int()
+				.positive()
+				.optional()
+				.describe('Wall clock of one run, in milliseconds'),
+		})
+		.optional()
+		.describe('Limits of ONE run; omit to use the defaults'),
+	job: z.string().optional().describe('pause/resume/delete: job name'),
+	allFolders: z.boolean().optional().describe('list: include jobs of other folders (names only)'),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+function refuse(error: string): ToolResult {
+	return { success: false, output: '', error }
+}
+
+function effectsOf(rule: unknown): string[] {
+	if (typeof rule === 'string') return [rule]
+	if (rule && typeof rule === 'object') return Object.values(rule as Record<string, string>)
+	return []
+}
+
+/**
+ * Refuse a network tool beside a shell that runs on the host: a scheduled run
+ * that can both read the machine and reach the internet, unattended, is the
+ * exfiltration shape, and only the operator can choose it.
+ */
+function networkWithHostShell(draft: ScheduleJobDraft): boolean {
+	const rules = draft.permissions.rules ?? {}
+	const network =
+		draft.permissions.browser !== undefined ||
+		NETWORK_TOOLS.some((t) => effectsOf(rules[t]).some((e) => e === 'allow' || e === 'ask'))
+	if (!network) return false
+	const bashEffects = effectsOf(rules.bash)
+	// The read-only preset denies bash; its rules are expanded by the host,
+	// so the draft carries only its name.
+	const shellPossible =
+		bashEffects.length > 0
+			? bashEffects.some((e) => e !== 'deny')
+			: draft.permissions.preset !== 'read-only' && draft.permissions.unmatched !== 'deny'
+	return shellPossible && (draft.permissions.execution ?? 'host') === 'host'
+}
+
+/**
+ * The browser grant with its site keys canonicalised, or why it is refused.
+ * Keys are rewritten so the host, the confirmation and the compiled rules
+ * all see one spelling of each site.
+ */
+function browserGrant(
+	host: ScheduleToolHost,
+	proposed: NonNullable<NonNullable<Input['permissions']>['browser']>,
+): { ok: true; grant: ScheduleBrowserGrant } | { ok: false; error: string } {
+	if (host.browserGrants !== true) {
+		return {
+			ok: false,
+			error:
+				'This host cannot give a scheduled job browser access. Propose the job without permissions.browser, or ask the operator to add it with `namzu schedule add`.',
+		}
+	}
+	const entries = Object.entries(proposed.sites)
+	if (entries.length === 0) {
+		return {
+			ok: false,
+			error:
+				'permissions.browser.sites is empty; list each site the run may open, e.g. {"https://github.com": "read"}.',
+		}
+	}
+	const sites: Record<string, ScheduleBrowserSiteLevel> = {}
+	for (const [key, level] of entries) {
+		if (key.trim() === '*') {
+			return {
+				ok: false,
+				error:
+					'A scheduled job cannot grant every site ("*"); unlisted sites are always denied. List each site.',
+			}
+		}
+		const verdict = canonicalizeBrowserSitePattern(key)
+		if (!verdict.ok) return { ok: false, error: `permissions.browser.sites: ${verdict.reason}` }
+		if (verdict.pattern in sites && sites[verdict.pattern] !== level) {
+			return {
+				ok: false,
+				error: `permissions.browser.sites names ${verdict.pattern} twice with different levels.`,
+			}
+		}
+		sites[verdict.pattern] = level
+	}
+	return {
+		ok: true,
+		grant: {
+			profile: proposed.profile,
+			sites,
+			...(proposed.headed !== undefined ? { headed: proposed.headed } : {}),
+		},
+	}
+}
+
+async function create(
+	host: ScheduleToolHost,
+	input: Input,
+	signal: AbortSignal | undefined,
+): Promise<ToolResult> {
+	const missing = (['name', 'prompt', 'when', 'permissions'] as const).filter(
+		(k) => input[k] === undefined,
+	)
+	if (missing.length > 0) {
+		return refuse(
+			`create needs ${missing.join(', ')}. permissions is required: propose an explicit set (a preset and/or rules, plus unmatched).`,
+		)
+	}
+	const proposed = input.permissions as NonNullable<Input['permissions']>
+	if (!proposed.preset && !proposed.rules && !proposed.browser) {
+		return refuse(
+			'permissions needs a preset, rules or a browser grant; an empty permission set is not a choice.',
+		)
+	}
+	let permissions: ScheduleJobDraft['permissions'] = proposed
+	if (proposed.browser) {
+		const grant = browserGrant(host, proposed.browser)
+		if (!grant.ok) return refuse(grant.error)
+		permissions = { ...proposed, browser: grant.grant }
+	}
+	const draft: ScheduleJobDraft = {
+		name: input.name as string,
+		prompt: input.prompt as string,
+		when: input.when as string,
+		...(input.folder !== undefined ? { folder: input.folder } : {}),
+		...(input.tz !== undefined ? { tz: input.tz } : {}),
+		permissions,
+		...(input.budget ? { budget: input.budget } : {}),
+	}
+	if (networkWithHostShell(draft)) {
+		return refuse(
+			'A scheduled job proposed here cannot combine web or browser access with a shell on the host. Deny bash, use execution "sandbox", or ask the operator to create it with `namzu schedule add`.',
+		)
+	}
+	let preview: Awaited<ReturnType<ScheduleToolHost['preview']>>
+	try {
+		preview = await host.preview(draft)
+	} catch (error) {
+		return refuse(error instanceof Error ? error.message : String(error))
+	}
+	let answer: string
+	try {
+		answer = await host.confirm(
+			{
+				preview,
+				promptFindings: scanSchedulePrompt(preview.prompt),
+				proposedBy: 'model',
+			},
+			signal,
+		)
+	} catch {
+		answer = 'cancel'
+	}
+	// The deadline or the turn can settle `host.confirm` from underneath a
+	// host that resolves optimistically on its own close; never create on an
+	// answer that arrived after the operator was no longer being asked.
+	if (signal?.aborted) answer = 'cancel'
+	if (answer !== 'create' && answer !== 'create-paused') {
+		return {
+			success: false,
+			output: '',
+			error: 'The operator did not confirm the job, so it was not created.',
+			data: { cancelled: true },
+		}
+	}
+	const created = await host.create(draft, preview, { paused: answer === 'create-paused' })
+	const said =
+		answer === 'create-paused'
+			? `Job "${created.name}" was created paused. The operator can resume it with /schedule.`
+			: `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results arrive as a notification and a session.`
+	return {
+		success: true,
+		output: created.note ? `${said} ${created.note}` : said,
+		data: { name: created.name, paused: answer === 'create-paused' },
+	}
+}
+
+async function list(host: ScheduleToolHost, input: Input): Promise<ToolResult> {
+	const jobs = await host.list({ allFolders: input.allFolders === true })
+	if (jobs.length === 0) return { success: true, output: 'No scheduled jobs.', data: { jobs: [] } }
+	const lines = jobs.map(
+		(j) =>
+			`${j.name} · ${j.state} · ${j.schedule}${j.nextFireAt ? ` · next ${j.nextFireAt}` : ''}${j.lastStatus ? ` · last ${j.lastStatus}` : ''} · ${j.folder}`,
+	)
+	return { success: true, output: lines.join('\n'), data: { jobs } }
+}
+
+async function lifecycle(
+	host: ScheduleToolHost,
+	input: Input,
+	action: 'pause' | 'resume' | 'delete',
+	signal: AbortSignal | undefined,
+): Promise<ToolResult> {
+	if (!input.job) return refuse(`${action} needs job (the job's name).`)
+	const job = await host.find(input.job)
+	if (!job) return refuse(`No scheduled job is named "${input.job}".`)
+	if (action !== 'pause') {
+		let confirmed = false
+		try {
+			confirmed = await host.confirmAction(job, action, signal)
+		} catch {
+			confirmed = false
+		}
+		if (signal?.aborted) confirmed = false
+		if (!confirmed)
+			return {
+				...refuse(`The operator did not confirm; "${job.name}" was not changed.`),
+				data: { cancelled: true },
+			}
+	}
+	if (action === 'pause') await host.pause(job.name)
+	else if (action === 'resume') await host.resume(job.name)
+	else await host.delete(job.name)
+	const verb = action === 'pause' ? 'paused' : action === 'resume' ? 'resumed' : 'deleted'
+	return { success: true, output: `Job "${job.name}" ${verb}.`, data: { name: job.name, action } }
+}
+
+/**
+ * The `schedule` tool: create, list, pause, resume and delete the operator's
+ * scheduled jobs from a conversation.
+ *
+ * Creation, resuming and deleting are confirmed by a person through the host
+ * (`ScheduleToolHost.confirm`), on a screen the host draws from its own
+ * computation. The model cannot propose that uncovered calls run without
+ * asking, nor web access beside a host shell. Register it only where a person
+ * is present to confirm: never in a headless run, a scheduled run or a
+ * sub-agent.
+ */
+export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
+	return [
+		defineTool({
+			name: SCHEDULE_TOOL_NAME,
+			description:
+				"Manage the operator's scheduled jobs: prompts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, resume and delete are confirmed by the operator; pause is not. A job needs name, prompt, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). Leave every other field (folder, tz, execution, budget, headed) unset unless the user asked for it: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
+			inputSchema,
+			category: 'custom',
+			permissions: [],
+			readOnly: (input) => input.action === 'list',
+			// `delete` removes a job only after the operator confirms it on the
+			// host's own screen; a destructive flag would put a second review,
+			// over the raw arguments, in front of that confirmation.
+			destructive: false,
+			concurrencySafe: false,
+			presentCall: presentScheduleCall,
+			presentResult: presentScheduleResult,
+			// A person, not a tool, answers `create`/`resume`/`delete`; see
+			// `OPERATOR_CONFIRM_TIMEOUT_MS`.
+			timeoutMs: OPERATOR_CONFIRM_TIMEOUT_MS,
+			async execute(input, context: ToolContext) {
+				switch (input.action) {
+					case 'create':
+						return create(host, input, context.abortSignal)
+					case 'list':
+						return list(host, input)
+					default:
+						return lifecycle(host, input, input.action, context.abortSignal)
+				}
+			},
+		}),
+	]
+}

package/src/tools/schedules/types.ts

@@ -0,0 +1,197 @@
+/**
+ * The host side of the `schedule` and `session_loop` tools.
+ *
+ * The SDK holds the tool's contract with the model — its schema, its refusals
+ * and its confirmation rule — and nothing about where jobs are stored or how
+ * a confirmation is drawn. The host supplies both, and it computes every
+ * field a person is asked to confirm: the model's own words are never what
+ * the confirmation shows as fact.
+ */
+
+/** A rule effect, in the vocabulary of the CLI's `[permissions]` table. */
+export type ScheduleRuleEffect = 'allow' | 'ask' | 'deny'
+
+/** What the model proposes. Validated by the tool's schema, then by the host. */
+export interface ScheduleJobDraft {
+	readonly name: string
+	readonly prompt: string
+	/** Schedule words: `every 30m`, `0 9 * * 1-5`, `at 09:00`, `in 2h`. */
+	readonly when: string
+	/** Folder the job runs in. Absent: the session's working directory. */
+	readonly folder?: string
+	/** IANA zone for a cron expression or a local time. Absent: the host's. */
+	readonly tz?: string
+	readonly permissions: {
+		readonly preset?: 'read-only' | 'edit-in-folder'
+		/**
+		 * What happens to a call no rule covers. The model may choose `park`
+		 * (wait for the operator) or `deny`; running uncovered calls without
+		 * asking is an operator decision the tool cannot propose.
+		 */
+		readonly unmatched: 'park' | 'deny'
+		readonly execution?: 'host' | 'sandbox'
+		readonly rules?: Readonly<
+			Record<string, ScheduleRuleEffect | Readonly<Record<string, ScheduleRuleEffect>>>
+		>
+		/**
+		 * Browser access for the run. Absent: the `browser` and `browser_act`
+		 * tools are denied. Present: only the listed sites are reachable, at
+		 * the listed level, and every other site is denied — there is no
+		 * catch-all key. The tool refuses this block unless the host sets
+		 * {@link ScheduleToolHost.browserGrants}.
+		 */
+		readonly browser?: ScheduleBrowserGrant
+	}
+	readonly budget?: {
+		readonly maxIterations?: number
+		readonly tokenBudget?: number
+		readonly timeoutMs?: number
+	}
+}
+
+/**
+ * How far a scheduled run may go on one site. `read`: open and read pages,
+ * never change them. `ask`: open and change pages, each change parked for the
+ * operator. `act`: open and change pages without asking.
+ */
+export type ScheduleBrowserSiteLevel = 'read' | 'ask' | 'act'
+
+/** A scheduled job's browser grant. */
+export interface ScheduleBrowserGrant {
+	/** The browser profile the run uses; the operator's, signed in beforehand. */
+	readonly profile: string
+	/**
+	 * Canonical site key (`https://github.com`, `https://*.example.com`,
+	 * `http://localhost:*`) to level. The tool canonicalises the keys the
+	 * model wrote (see `canonicalizeBrowserSitePattern`) before the host sees
+	 * them. Unlisted sites are denied.
+	 */
+	readonly sites: Readonly<Record<string, ScheduleBrowserSiteLevel>>
+	/** Show the browser window during the run. Default: no window. */
+	readonly headed?: boolean
+}
+
+/** What the person confirming is shown. Every field is the host's own computation. */
+export interface ScheduleJobPreview {
+	readonly name: string
+	/** The canonical folder the job would run in. */
+	readonly folder: string
+	/** True when `folder` is outside the session's working directory and added directories. */
+	readonly outsideSessionRoots: boolean
+	readonly prompt: string
+	/** The schedule in words, with its zone. */
+	readonly schedule: string
+	/** The next fire times, ISO-8601 UTC. */
+	readonly nextFireTimes: readonly string[]
+	/** The permission set expanded to one line per rule, config denies included. */
+	readonly rules: readonly string[]
+	readonly unmatched: 'park' | 'deny' | 'allow'
+	readonly execution: 'host' | 'sandbox'
+	/** A rule lets the run reach the network. */
+	readonly networkAccess: boolean
+	readonly budget: {
+		readonly maxIterations: number
+		readonly tokenBudget: number
+		readonly timeoutMs: number
+	}
+	/** Runs per day at most, times the token budget. Absent for a one-shot. */
+	readonly dailyTokenCeiling?: number
+	/** Provider and model the job is pinned to. */
+	readonly model: string
+	/** Where the run's credential comes from, in words. */
+	readonly credentialSource?: string
+	/** Anything the host wants said in the warning colour. */
+	readonly warnings: readonly string[]
+}
+
+/** A job as the `list` action reports it. */
+export interface ScheduleJobSummary {
+	readonly name: string
+	readonly folder: string
+	readonly state: string
+	readonly schedule: string
+	readonly nextFireAt?: string
+	readonly lastStatus?: string
+	/** Present only for jobs in the session's own folder. */
+	readonly prompt?: string
+}
+
+/** What the person answered to a proposed job. */
+export type ScheduleConfirmAnswer = 'create' | 'create-paused' | 'cancel'
+
+export interface ScheduleConfirmRequest {
+	readonly preview: ScheduleJobPreview
+	/** The prompt tripwire's findings over `preview.prompt`. */
+	readonly promptFindings: readonly string[]
+	/** Always `model` from this tool: the banner says it was not the operator. */
+	readonly proposedBy: 'model'
+}
+
+export interface ScheduleToolHost {
+	/**
+	 * The host can store and enforce {@link ScheduleJobDraft.permissions}
+	 * `.browser`. Absent or false: the tool refuses a draft carrying one,
+	 * rather than let the host drop it and confirm a job the model believes
+	 * can use the browser.
+	 */
+	readonly browserGrants?: boolean
+	/** Validate the draft and compute what the person will be shown. Throws with a message on a refusal. */
+	preview(draft: ScheduleJobDraft): Promise<ScheduleJobPreview>
+	/**
+	 * Ask the person. Anything but `create` or `create-paused` — `cancel`, a
+	 * thrown error, a closed screen — means no job.
+	 *
+	 * `signal` fires when the tool's own confirmation deadline elapses or the
+	 * turn is aborted; a host that draws a screen closes it then rather than
+	 * leaving it live after the tool has given up on the answer.
+	 */
+	confirm(request: ScheduleConfirmRequest, signal?: AbortSignal): Promise<ScheduleConfirmAnswer>
+	/**
+	 * Create the job the person confirmed. `note`, when given, is appended to
+	 * what the model is told, for what the person must still do before the
+	 * job runs (install a scheduler, say): the model reports the job as set
+	 * up otherwise.
+	 */
+	create(
+		draft: ScheduleJobDraft,
+		preview: ScheduleJobPreview,
+		options: { readonly paused: boolean },
+	): Promise<{ readonly name: string; readonly note?: string }>
+	/** Jobs, the session folder's in full, other folders' without their prompts. */
+	list(options: { readonly allFolders: boolean }): Promise<readonly ScheduleJobSummary[]>
+	/** A job by name or id prefix, or undefined. */
+	find(job: string): Promise<ScheduleJobSummary | undefined>
+	/** Ask the person to confirm resuming or deleting a job. See `confirm` on `signal`. */
+	confirmAction(
+		job: ScheduleJobSummary,
+		action: 'resume' | 'delete',
+		signal?: AbortSignal,
+	): Promise<boolean>
+	pause(job: string): Promise<void>
+	resume(job: string): Promise<void>
+	delete(job: string): Promise<void>
+}
+
+/** A prompt the session re-sends to itself on an interval. */
+export interface SessionLoop {
+	readonly id: string
+	/** The interval in words. */
+	readonly schedule: string
+	readonly prompt: string
+	readonly createdAt: string
+	readonly expiresAt?: string
+	readonly lastFiredAt?: string
+	readonly createdBy: 'operator' | 'model'
+}
+
+export interface SessionLoopHost {
+	/** Throws with a message when the interval is not usable or the loop limit is reached. */
+	create(request: {
+		readonly interval: string
+		readonly prompt: string
+		readonly createdBy: 'model'
+	}): Promise<SessionLoop>
+	list(): readonly SessionLoop[]
+	/** Stop one loop by id, or every loop with `all`. Returns how many stopped. */
+	delete(id: string): Promise<number>
+}