@namzu/sdk 45.0.0 → 45.1.0

package/src/tools/builtins/skill.ts

@@ -256,6 +256,24 @@ export const SkillTool = defineTool({
 	destructive: false,
 	concurrencySafe: true,
 
+	// The body is instructions for the model, often a hundred lines; the
+	// person needs the row that says which skill was read, not the text.
+	presentCall(input: SkillInput) {
+		const name = typeof input?.name === 'string' ? input.name : undefined
+		return {
+			kind: 'generic',
+			presentation: 'activity',
+			label:
+				name === undefined
+					? input?.cursor === undefined
+						? 'List skills'
+						: 'List more skills'
+					: `Read skill ${name}${input.cursor === undefined ? '' : ' (continued)'}`,
+		}
+	},
+	presentResult: (_input: SkillInput, result) =>
+		result.success ? { kind: 'generic', label: 'read', visibility: 'hidden' } : undefined,
+
 	async execute(input: SkillInput, context) {
 		if (!context.skills) {
 			return {

package/src/tools/defineTool.ts

@@ -65,6 +65,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	commandDialect?: ToolDefinition['commandDialect']
 	/** The argument holding a filesystem path; see {@link ToolDefinition.pathArgument}. */
 	pathArgument?: string
+	/** The argument holding a canonical URL; see {@link ToolDefinition.urlArgument}. */
+	urlArgument?: string
 	/** The argument asking to leave the sandbox; see {@link ToolDefinition.sandboxEscapeArgument}. */
 	sandboxEscapeArgument?: string
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
@@ -117,6 +119,7 @@ export function defineTool<S extends z.ZodType>(
 		...(options.commandArgument !== undefined ? { commandArgument: options.commandArgument } : {}),
 		...(options.commandDialect !== undefined ? { commandDialect: options.commandDialect } : {}),
 		...(options.pathArgument !== undefined ? { pathArgument: options.pathArgument } : {}),
+		...(options.urlArgument !== undefined ? { urlArgument: options.urlArgument } : {}),
 		...(options.sandboxEscapeArgument !== undefined
 			? { sandboxEscapeArgument: options.sandboxEscapeArgument }
 			: {}),

package/src/tools/schedules/index.ts

@@ -0,0 +1,4 @@
+export { buildScheduleTools, SCHEDULE_TOOL_NAME } from './schedule-tool.js'
+export { buildSessionLoopTools, SESSION_LOOP_TOOL_NAME } from './loop-tool.js'
+export { revealHiddenCharacters, scanSchedulePrompt } from './prompt-scan.js'
+export type * from './types.js'

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

@@ -0,0 +1,85 @@
+import { z } from 'zod'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+import { presentLoopCall, presentLoopResult } from './present.js'
+import type { SessionLoopHost } from './types.js'
+
+export const SESSION_LOOP_TOOL_NAME = 'session_loop'
+
+const inputSchema = z.object({
+	action: z.enum(['create', 'list', 'delete']),
+	interval: z
+		.string()
+		.optional()
+		.describe('create: how often, e.g. "5m", "1h", or a five-field cron expression'),
+	prompt: z.string().min(1).max(4_000).optional().describe('create: the message to send each time'),
+	id: z.string().optional().describe('delete: the loop id, or "all"'),
+})
+
+/**
+ * The `session_loop` tool: re-send a prompt to THIS conversation on an
+ * interval, between turns, while the session is open.
+ *
+ * `create` is an ordinary reviewed call — not exempt from review — so in
+ * `prompt` mode the operator sees it before a loop exists; a loop a model
+ * created is labelled as such wherever it is shown. `list` and `delete` only
+ * read or remove loops.
+ */
+export function buildSessionLoopTools(host: SessionLoopHost): ToolDefinition[] {
+	return [
+		defineTool({
+			name: SESSION_LOOP_TOOL_NAME,
+			description:
+				'Re-send a prompt to this conversation on an interval while the session stays open (between turns only; stops when the session closes; expires after 7 days). Use only when the user asks for something to repeat. Minimum interval one minute.',
+			inputSchema,
+			category: 'custom',
+			permissions: [],
+			readOnly: (input) => input.action !== 'create',
+			destructive: false,
+			concurrencySafe: false,
+			presentCall: presentLoopCall,
+			presentResult: presentLoopResult,
+			async execute(input) {
+				if (input.action === 'list') {
+					const loops = host.list()
+					return {
+						success: true,
+						output:
+							loops.length === 0
+								? 'No loops in this session.'
+								: loops.map((l) => `${l.id} · ${l.schedule} · ${l.prompt.slice(0, 80)}`).join('\n'),
+						data: { loops },
+					}
+				}
+				if (input.action === 'delete') {
+					if (!input.id) return { success: false, output: '', error: 'delete needs id (or "all").' }
+					const stopped = await host.delete(input.id)
+					return stopped === 0
+						? { success: false, output: '', error: `No loop has id "${input.id}".` }
+						: { success: true, output: `Stopped ${stopped} loop${stopped === 1 ? '' : 's'}.` }
+				}
+				if (!input.interval || !input.prompt) {
+					return { success: false, output: '', error: 'create needs interval and prompt.' }
+				}
+				try {
+					const loop = await host.create({
+						interval: input.interval,
+						prompt: input.prompt,
+						createdBy: 'model',
+					})
+					return {
+						success: true,
+						output: `Loop ${loop.id} created: ${loop.schedule}. The operator can stop it with /loop stop ${loop.id}.`,
+						data: { id: loop.id },
+					}
+				} catch (error) {
+					return {
+						success: false,
+						output: '',
+						error: error instanceof Error ? error.message : String(error),
+					}
+				}
+			},
+		}),
+	]
+}

package/src/tools/schedules/present.ts

@@ -0,0 +1,86 @@
+import type { ToolResult } from '../../types/tool/index.js'
+import type { ToolCallView, ToolResultView } from '../../types/tool/presentation.js'
+
+/**
+ * How the schedule tools read to a person: in words, never ids or JSON.
+ */
+
+const MAX = 80
+
+function oneLine(value: unknown): string {
+	if (typeof value !== 'string') return ''
+	const flat = value.replace(/\s+/g, ' ').trim()
+	return flat.length > MAX ? `${flat.slice(0, MAX - 1)}…` : flat
+}
+
+function activity(label: string): ToolCallView {
+	return { kind: 'generic', presentation: 'activity', label }
+}
+
+const HIDDEN: ToolResultView = { kind: 'generic', label: '', visibility: 'hidden' }
+
+export function presentScheduleCall(input: {
+	readonly action?: unknown
+	readonly name?: unknown
+	readonly when?: unknown
+	readonly job?: unknown
+}): ToolCallView {
+	switch (input.action) {
+		case 'create': {
+			const name = oneLine(input.name)
+			const when = oneLine(input.when)
+			return activity(`Propose scheduled job${name ? ` · ${name}` : ''}${when ? ` · ${when}` : ''}`)
+		}
+		case 'list':
+			return activity('List scheduled jobs')
+		case 'pause':
+			return activity(`Pause scheduled job · ${oneLine(input.job)}`)
+		case 'resume':
+			return activity(`Resume scheduled job · ${oneLine(input.job)}`)
+		case 'delete':
+			return activity(`Delete scheduled job · ${oneLine(input.job)}`)
+		default:
+			return activity('Scheduled jobs')
+	}
+}
+
+/** The operator answered no on the tool's own screen: not a failure. */
+function operatorCancelled(result: ToolResult): boolean {
+	const data = result.data as { cancelled?: unknown } | undefined
+	return data?.cancelled === true
+}
+
+export function presentScheduleResult(input: unknown, result: ToolResult): ToolResultView {
+	if (!result.success && operatorCancelled(result)) {
+		const action = (input as { action?: unknown } | null)?.action
+		return {
+			kind: 'generic',
+			outcome: 'cancelled',
+			label: action === 'create' ? 'Cancelled — no job was created' : 'Cancelled — nothing changed',
+		}
+	}
+	if (!result.success) return { kind: 'generic', label: oneLine(result.error) || 'Not done' }
+	return HIDDEN
+}
+
+export function presentLoopCall(input: {
+	readonly action?: unknown
+	readonly interval?: unknown
+	readonly prompt?: unknown
+}): ToolCallView {
+	switch (input.action) {
+		case 'create':
+			return activity(`Loop ${oneLine(input.interval)} · ${oneLine(input.prompt)}`)
+		case 'list':
+			return activity('List loops')
+		case 'delete':
+			return activity('Stop loop')
+		default:
+			return activity('Loops')
+	}
+}
+
+export function presentLoopResult(_input: unknown, result: ToolResult): ToolResultView {
+	if (!result.success) return { kind: 'generic', label: oneLine(result.error) || 'Not done' }
+	return HIDDEN
+}

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)
+				}
+			},
+		}),
+	]
+}