@harperfast/harper 5.0.30 → 5.1.0-beta.2

package/agent/session.ts

@@ -0,0 +1,187 @@
+/**
+ * Built-in agent session storage. Backed by `system.hdb_agent_session` so
+ * transcripts and pending approvals survive restarts. The exported helpers
+ * are async to keep the surface uniform — once the underlying store gains
+ * non-blocking paths the call sites won't have to change.
+ *
+ * Intentionally separate from #511's `ConversationResource`: that primitive
+ * is app-facing (per-tenant, multi-user, user-defined schema) while this
+ * table is server-local and operator-owned.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { table } from '../resources/databases.ts';
+import { SYSTEM_SCHEMA_NAME, SYSTEM_TABLE_NAMES } from '../utility/hdbTerms.ts';
+import type { AgentMessage, AgentRunStatus, AgentSessionRow, ApprovalRequest } from './types.ts';
+
+let cachedTable: any;
+
+export function getAgentSessionTable(): any {
+	if (cachedTable) return cachedTable;
+	cachedTable = table({
+		table: SYSTEM_TABLE_NAMES.AGENT_SESSION_TABLE_NAME,
+		database: SYSTEM_SCHEMA_NAME,
+		audit: true,
+		trackDeletes: false,
+		attributes: [
+			{ name: 'session_id', isPrimaryKey: true },
+			{ name: 'user', type: 'string', indexed: true },
+			{ name: 'status', type: 'string', indexed: true },
+			{ name: 'messages' },
+			{ name: 'pendingApprovals' },
+			{ name: 'model', type: 'string' },
+			{ name: 'provider', type: 'string' },
+			{ name: 'createdAt', type: 'number', indexed: true },
+			{ name: 'updatedAt', type: 'number', indexed: true },
+			{ name: 'lastError', type: 'string' },
+		],
+	});
+	return cachedTable;
+}
+
+export interface CreateSessionOpts {
+	sessionId?: string;
+	user: string;
+	model?: string;
+	provider?: string;
+	initialMessage?: AgentMessage;
+}
+
+export async function createSession(opts: CreateSessionOpts): Promise<AgentSessionRow> {
+	const now = Date.now();
+	const row: AgentSessionRow = {
+		session_id: opts.sessionId ?? randomUUID(),
+		user: opts.user,
+		status: 'idle',
+		messages: opts.initialMessage ? [opts.initialMessage] : [],
+		pendingApprovals: [],
+		model: opts.model,
+		provider: opts.provider,
+		createdAt: now,
+		updatedAt: now,
+	};
+	await getAgentSessionTable().primaryStore.put(row.session_id, row);
+	return row;
+}
+
+export async function getSession(sessionId: string): Promise<AgentSessionRow | undefined> {
+	return getAgentSessionTable().primaryStore.get(sessionId);
+}
+
+export async function listSessions(opts: { limit?: number } = {}): Promise<AgentSessionRow[]> {
+	const limit = opts.limit ?? 100;
+	const out: AgentSessionRow[] = [];
+	for (const entry of getAgentSessionTable().primaryStore.getRange({ reverse: true, limit })) {
+		if (entry.value) out.push(entry.value as AgentSessionRow);
+	}
+	return out;
+}
+
+/**
+ * Per-session mutation lock. Each row mutation is a read-modify-write against the table; without
+ * serialization, two concurrent mutations on the same session (e.g. the loop appending an assistant
+ * message while the operator resolves an approval) both read the same row and the second `put`
+ * clobbers the first — a lost update. This chains all mutations for a given session id so they
+ * apply sequentially. Reads (`getSession`/`listSessions`) intentionally don't take the lock.
+ */
+const sessionLocks = new Map<string, Promise<unknown>>();
+
+function withSessionLock<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
+	const prev = (sessionLocks.get(sessionId) ?? Promise.resolve()).catch(() => {});
+	const result = prev.then(() => fn());
+	const tail = result.catch(() => {});
+	sessionLocks.set(sessionId, tail);
+	void tail.then(() => {
+		if (sessionLocks.get(sessionId) === tail) sessionLocks.delete(sessionId);
+	});
+	return result;
+}
+
+export function appendMessage(sessionId: string, message: AgentMessage): Promise<AgentSessionRow> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		session.messages.push(message);
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return session;
+	});
+}
+
+export function setStatus(sessionId: string, status: AgentRunStatus, lastError?: string): Promise<AgentSessionRow> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		session.status = status;
+		session.lastError = lastError;
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return session;
+	});
+}
+
+export function addPendingApproval(
+	sessionId: string,
+	approval: Omit<ApprovalRequest, 'id' | 'createdAt'>
+): Promise<ApprovalRequest> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		const entry: ApprovalRequest = { ...approval, id: randomUUID(), createdAt: Date.now() };
+		session.pendingApprovals.push(entry);
+		session.status = 'awaiting_approval';
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return entry;
+	});
+}
+
+export function markApprovalConsumed(sessionId: string, approvalId: string): Promise<void> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		const entry = session.pendingApprovals.find((a) => a.id === approvalId);
+		if (!entry) throw new Error(`No pending approval ${approvalId} on session ${sessionId}`);
+		if (!entry.resolved) throw new Error(`Approval ${approvalId} not yet resolved`);
+		if (entry.consumed) return;
+		entry.consumed = true;
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+	});
+}
+
+export function resolveApproval(sessionId: string, approvalId: string, approved: boolean): Promise<ApprovalRequest> {
+	return withSessionLock(sessionId, async () => {
+		const session = await requireSession(sessionId);
+		const entry = session.pendingApprovals.find((a) => a.id === approvalId);
+		if (!entry) throw new Error(`No pending approval ${approvalId} on session ${sessionId}`);
+		if (entry.resolved) throw new Error(`Approval ${approvalId} already resolved`);
+		entry.resolved = true;
+		entry.approved = approved;
+		entry.resolvedAt = Date.now();
+		// Either decision (approve or deny) returns the session to a resumable `idle` state so the
+		// loop can run again and deliver the resulting observation to the model. Operators who want
+		// to terminate the whole run should use `cancel_agent_run` instead of denying.
+		if (!session.pendingApprovals.some((a) => !a.resolved)) {
+			session.status = 'idle';
+		}
+		session.updatedAt = Date.now();
+		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		return entry;
+	});
+}
+
+async function requireSession(sessionId: string): Promise<AgentSessionRow> {
+	const session = await getSession(sessionId);
+	if (!session) throw new Error(`No agent session ${sessionId}`);
+	return session;
+}
+
+/**
+ * Reset the cached table reference. Test-only seam; production code lets the
+ * lazy-getter initialize once per process.
+ */
+export function _resetForTests(): void {
+	cachedTable = undefined;
+}
+
+/** Inject a mock table accessor for unit tests. Pass `undefined` to restore the lazy default. */
+export function _setTableForTests(mock: any): void {
+	cachedTable = mock;
+}

package/agent/tools/fsTools.ts

@@ -0,0 +1,276 @@
+/**
+ * Operator-only filesystem tools for the built-in agent (#626).
+ *
+ * Every path is resolved against the configured scopes (componentsRoot,
+ * logDir, configDir) and rejected if it escapes them. Writes are restricted
+ * to `componentsRoot` — `logDir` and `configDir` are observation-only so
+ * the agent can read logs and inspect config without rewriting either.
+ *
+ * Lifted in spirit from the external `harper-agent` CLI's file tools; the
+ * sandboxing rules are tightened here because the in-process agent can
+ * reach more of the filesystem than a remote CLI.
+ */
+
+import { readFile, writeFile, readdir, stat, mkdir, realpath, lstat, open } from 'node:fs/promises';
+import { resolve, dirname, relative, sep, isAbsolute } from 'node:path';
+import type { AgentTool, AgentToolContext, AgentScopes } from '../types.ts';
+
+const MAX_READ_BYTES = 5 * 1024 * 1024; // 5 MiB
+const MAX_WRITE_BYTES = 5 * 1024 * 1024;
+const MAX_GREP_RESULTS = 500;
+const MAX_PATTERN_LENGTH = 1000;
+const DEFAULT_TAIL_LINES = 200;
+const TAIL_READ_BYTES = 1 * 1024 * 1024; // 1 MiB — enough for thousands of normal log lines
+
+type Access = 'read' | 'write';
+
+async function resolveScoped(scopes: AgentScopes, path: string, access: Access): Promise<string> {
+	const absolute = resolve(path);
+	const candidates = [scopes.componentsRoot];
+	if (access === 'read') {
+		candidates.push(scopes.logDir, scopes.configDir);
+	}
+	// Reject a symlink leaf. `safeRealPath` resolves existing symlinks via `realpath` (so a link to
+	// an out-of-scope *existing* file is caught by the isInside check below) — but a link whose
+	// target does NOT exist makes `realpath` throw, and the fallback returns the link's own in-scope
+	// path. `writeFile`/`readFile` then follow the link out of scope. An explicit lstat closes that
+	// gap: a legitimate component/log/config file is never a symlink.
+	try {
+		const linkStat = await lstat(absolute);
+		if (linkStat.isSymbolicLink()) {
+			throw new Error(`Refusing to ${access} through a symlink: ${path}`);
+		}
+	} catch (err) {
+		// ENOENT (path doesn't exist yet — normal for a new-file write) is fine; rethrow anything else
+		// (including our own symlink rejection).
+		if ((err as NodeJS.ErrnoException)?.code !== 'ENOENT') throw err;
+	}
+	const realAbsolute = await safeRealPath(absolute);
+	for (const root of candidates) {
+		const realRoot = await safeRealPath(root);
+		if (isInside(realAbsolute, realRoot)) return realAbsolute;
+	}
+	throw new Error(`Path is outside the agent's ${access} scope: ${path}`);
+}
+
+async function safeRealPath(p: string): Promise<string> {
+	try {
+		return await realpath(p);
+	} catch {
+		// Missing leaf is fine — resolve the deepest existing ancestor and join.
+		const parent = dirname(p);
+		if (parent === p) return p;
+		const parentReal = await safeRealPath(parent);
+		return resolve(parentReal, p.slice(parent.length + 1));
+	}
+}
+
+function isInside(child: string, parent: string): boolean {
+	const rel = relative(parent, child);
+	// On Windows, `path.relative` returns an absolute path when the two arguments are on
+	// different drive letters (e.g. C:\components vs D:\etc). Without this check the agent
+	// could escape its scope by naming a path on another drive.
+	if (isAbsolute(rel)) return false;
+	return rel === '' || (!rel.startsWith('..') && !rel.includes(`..${sep}`));
+}
+
+export const readFileTool: AgentTool = {
+	def: {
+		name: 'read_file',
+		description: 'Read a UTF-8 text file within componentsRoot, logDir, or configDir.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path.' },
+			},
+			required: ['path'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const path = await resolveScoped(ctx.scopes, args.path, 'read');
+		const st = await stat(path);
+		if (st.size > MAX_READ_BYTES) {
+			throw new Error(`File ${path} exceeds ${MAX_READ_BYTES}-byte read cap (size ${st.size})`);
+		}
+		const content = await readFile(path, 'utf8');
+		return { path, size: st.size, content };
+	},
+};
+
+export const writeFileTool: AgentTool = {
+	def: {
+		name: 'write_file',
+		description: 'Write a UTF-8 text file within componentsRoot. Creates parent directories as needed.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path under componentsRoot.' },
+				content: { type: 'string', description: 'UTF-8 file contents.' },
+			},
+			required: ['path', 'content'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const content = String(args.content ?? '');
+		if (Buffer.byteLength(content, 'utf8') > MAX_WRITE_BYTES) {
+			throw new Error(`Write exceeds ${MAX_WRITE_BYTES}-byte cap`);
+		}
+		const path = await resolveScoped(ctx.scopes, args.path, 'write');
+		await mkdir(dirname(path), { recursive: true });
+		await writeFile(path, content, 'utf8');
+		return { path, bytesWritten: Buffer.byteLength(content, 'utf8') };
+	},
+	destructive: true,
+};
+
+export const listDirTool: AgentTool = {
+	def: {
+		name: 'list_dir',
+		description: 'List the immediate entries in a directory within an allowed scope.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path.' },
+			},
+			required: ['path'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const path = await resolveScoped(ctx.scopes, args.path, 'read');
+		const entries = await readdir(path, { withFileTypes: true });
+		return {
+			path,
+			entries: entries.map((e) => ({
+				name: e.name,
+				kind: e.isDirectory() ? 'directory' : e.isFile() ? 'file' : 'other',
+			})),
+		};
+	},
+};
+
+export const grepFilesTool: AgentTool = {
+	def: {
+		name: 'grep_files',
+		description: 'Search recursively under a scoped directory for a regex pattern. Returns matched lines.',
+		parameters: {
+			type: 'object',
+			properties: {
+				root: { type: 'string', description: 'Directory to search under.' },
+				pattern: { type: 'string', description: 'JavaScript-compatible regular expression source.' },
+				flags: { type: 'string', description: 'Regex flags (default: "i").' },
+				maxResults: { type: 'integer', minimum: 1, maximum: MAX_GREP_RESULTS },
+			},
+			required: ['root', 'pattern'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const root = await resolveScoped(ctx.scopes, args.root, 'read');
+		// Cap pattern length. A maliciously crafted regex (e.g. nested quantifiers) can backtrack
+		// catastrophically and block the main thread; JS has no native per-match timeout. The agent
+		// is super_user-gated so this is self-inflicted DoS rather than a privilege boundary, but a
+		// length cap removes the easiest footgun without a worker-thread regex sandbox.
+		const patternSource = String(args.pattern ?? '');
+		if (patternSource.length > MAX_PATTERN_LENGTH) {
+			throw new Error(`grep pattern exceeds ${MAX_PATTERN_LENGTH}-char cap`);
+		}
+		const pattern = new RegExp(patternSource, args.flags ?? 'i');
+		const cap = Math.min(args.maxResults ?? MAX_GREP_RESULTS, MAX_GREP_RESULTS);
+		const results: Array<{ path: string; line: number; text: string }> = [];
+		await walk(root, async (file) => {
+			if (results.length >= cap) return false;
+			// `stat` first so a multi-GB log or database file can't be slurped into memory by a
+			// well-formed grep request. Anything over the read cap is silently skipped.
+			let size = 0;
+			try {
+				const st = await stat(file);
+				size = st.size;
+			} catch {
+				return true;
+			}
+			if (size > MAX_READ_BYTES) return true;
+			const text = await readFile(file, 'utf8').catch(() => '');
+			if (!text) return true;
+			const lines = text.split('\n');
+			for (let i = 0; i < lines.length; i++) {
+				if (results.length >= cap) return false;
+				if (pattern.test(lines[i])) results.push({ path: file, line: i + 1, text: lines[i] });
+			}
+			return true;
+		});
+		return { root, count: results.length, results };
+	},
+};
+
+export const tailFileTool: AgentTool = {
+	def: {
+		name: 'tail_file',
+		description: 'Return the last N lines of a UTF-8 file. Useful for log tails.',
+		parameters: {
+			type: 'object',
+			properties: {
+				path: { type: 'string', description: 'Absolute filesystem path.' },
+				lines: { type: 'integer', minimum: 1, maximum: 5000 },
+			},
+			required: ['path'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const path = await resolveScoped(ctx.scopes, args.path, 'read');
+		const wanted = Math.min(args.lines ?? DEFAULT_TAIL_LINES, 5000);
+		// Read only the trailing TAIL_READ_BYTES — a multi-GB log file otherwise OOMs the process.
+		const st = await stat(path);
+		const start = Math.max(0, st.size - TAIL_READ_BYTES);
+		const truncated = start > 0;
+		const fh = await open(path, 'r');
+		try {
+			const buf = Buffer.alloc(st.size - start);
+			await fh.read(buf, 0, buf.length, start);
+			const text = buf.toString('utf8');
+			const all = text.split('\n');
+			// `split('\n')` on a file ending with `\n` leaves a trailing empty entry — drop it so the
+			// "last N lines" the agent sees matches what a human reading the file would see.
+			if (all.length > 0 && all[all.length - 1] === '') all.pop();
+			// When we read from a mid-file offset the first "line" is almost certainly a partial
+			// fragment of a real line. Drop it so we don't hand the agent a misleading prefix.
+			if (truncated && all.length > 0) all.shift();
+			const sliceStart = Math.max(0, all.length - wanted);
+			return { path, lines: all.slice(sliceStart), truncated };
+		} finally {
+			await fh.close();
+		}
+	},
+};
+
+export const fsTools: AgentTool[] = [readFileTool, writeFileTool, listDirTool, grepFilesTool, tailFileTool];
+
+async function walk(root: string, visit: (file: string) => Promise<boolean>): Promise<void> {
+	// Resolve the scope root once via realpath so the per-entry symlink check below has a
+	// stable comparison anchor; otherwise a symlink in the root itself could shift the anchor.
+	const realRoot = await safeRealPath(root);
+	const stack: string[] = [root];
+	while (stack.length) {
+		const dir = stack.pop()!;
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const full = resolve(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === 'node_modules' || entry.name === '.git') continue;
+				// Re-resolve via realpath so a symlinked directory pointing outside the scope is rejected.
+				// Without this, `componentsRoot/escape -> /etc` would let grep walk into /etc.
+				const realFull = await safeRealPath(full);
+				if (!isInside(realFull, realRoot)) continue;
+				stack.push(full);
+			} else if (entry.isFile()) {
+				const realFull = await safeRealPath(full);
+				if (!isInside(realFull, realRoot)) continue;
+				const proceed = await visit(full);
+				if (proceed === false) return;
+			}
+		}
+	}
+}

package/agent/tools/httpFetchTool.ts

@@ -0,0 +1,112 @@
+/**
+ * `http_fetch` for the built-in agent (#626). Wraps the platform `fetch`
+ * with a size cap, an inactivity timeout, and a metadata/loopback blocklist
+ * so the agent can probe its own deployed components and pull lightweight
+ * web pages for context without becoming an SSRF vector against cloud
+ * instance-metadata endpoints or unrelated internal services.
+ */
+
+import { isIP } from 'node:net';
+import type { AgentTool, AgentToolContext } from '../types.ts';
+
+const MAX_BYTES = 2 * 1024 * 1024; // 2 MiB cap on response bodies
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Hard-blocked literal hosts. Cloud-metadata services live on these IPs and exposing them
+// to a prompt-controlled fetch is a credential-leak vector. Loopback to the local Harper
+// instance is allowed via `localhost`/`127.0.0.1` for self-testing — those are NOT blocked.
+const BLOCKED_HOSTS = new Set([
+	'169.254.169.254', // AWS / GCP / Azure IMDS
+	'fd00:ec2::254', // AWS IMDSv2 IPv6
+	'metadata.google.internal',
+	'metadata.goog',
+]);
+
+export const httpFetchTool: AgentTool = {
+	def: {
+		name: 'http_fetch',
+		description:
+			"Issue an HTTP request from the Harper server. Useful for hitting the agent's own components on localhost and pulling reference pages.",
+		parameters: {
+			type: 'object',
+			properties: {
+				url: { type: 'string', description: 'Absolute URL.' },
+				method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] },
+				headers: { type: 'object', additionalProperties: { type: 'string' } },
+				body: { type: 'string', description: 'Request body as a string (JSON or form-encoded).' },
+				timeoutMs: { type: 'integer', minimum: 1, maximum: 120_000 },
+			},
+			required: ['url'],
+		},
+	},
+	handler: async (args: any, ctx: AgentToolContext) => {
+		const url = String(args.url ?? '');
+		if (!/^https?:\/\//i.test(url)) throw new Error('http_fetch requires an http(s) URL');
+		let parsed: URL;
+		try {
+			parsed = new URL(url);
+		} catch {
+			throw new Error(`http_fetch could not parse URL: ${url}`);
+		}
+		const host = parsed.hostname.toLowerCase();
+		if (BLOCKED_HOSTS.has(host)) {
+			throw new Error(`http_fetch blocked by metadata-host policy: ${host}`);
+		}
+		// IPv4 link-local (169.254.0.0/16) covers IMDS variants beyond the canonical 169.254.169.254.
+		if (isIP(host) === 4 && host.startsWith('169.254.')) {
+			throw new Error(`http_fetch blocked by link-local policy: ${host}`);
+		}
+		const timeoutMs = Math.min(args.timeoutMs ?? DEFAULT_TIMEOUT_MS, 120_000);
+		const localAbort = new AbortController();
+		const timer = setTimeout(() => localAbort.abort(new Error(`http_fetch timed out after ${timeoutMs}ms`)), timeoutMs);
+		const signal = combineSignals(ctx.signal, localAbort.signal);
+		try {
+			const response = await fetch(url, {
+				method: args.method ?? 'GET',
+				headers: args.headers,
+				body: args.body,
+				signal,
+			});
+			const buffer = await readCapped(response, MAX_BYTES);
+			return {
+				status: response.status,
+				headers: Object.fromEntries(response.headers.entries()),
+				body: buffer.toString('utf8'),
+				truncated: buffer.length === MAX_BYTES,
+			};
+		} finally {
+			clearTimeout(timer);
+		}
+	},
+};
+
+async function readCapped(response: Response, cap: number): Promise<Buffer> {
+	const reader = response.body?.getReader();
+	if (!reader) return Buffer.alloc(0);
+	const chunks: Buffer[] = [];
+	let total = 0;
+	while (total < cap) {
+		const { value, done } = await reader.read();
+		if (done) break;
+		const chunk = Buffer.from(value);
+		const room = cap - total;
+		if (chunk.length > room) {
+			chunks.push(chunk.subarray(0, room));
+			total += room;
+			await reader.cancel().catch(() => {});
+			break;
+		}
+		chunks.push(chunk);
+		total += chunk.length;
+	}
+	return Buffer.concat(chunks, total);
+}
+
+function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+	const present = signals.filter((s): s is AbortSignal => Boolean(s));
+	if (present.length === 0) return undefined;
+	if (present.length === 1) return present[0];
+	// `AbortSignal.any` (Node 20+) manages listener cleanup internally; the manual
+	// `addEventListener` approach leaked listeners on `ctx.signal` for the lifetime of the agent
+	// run when a fetch completed normally.
+	return AbortSignal.any(present);
+}

package/agent/tools/scheduleTool.ts

@@ -0,0 +1,68 @@
+/**
+ * `schedule_followup` for the built-in agent (#626).
+ *
+ * Lives on the main thread so it survives worker-thread restarts that happen
+ * on code reload. The followup callback is injected from the entry point —
+ * this module only schedules the timer and tracks pending entries.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { AgentTool, AgentToolContext } from '../types.ts';
+
+const MAX_DELAY_MS = 24 * 60 * 60 * 1000; // 24h
+const MIN_DELAY_MS = 1_000;
+
+export interface ScheduledFollowup {
+	id: string;
+	sessionId: string;
+	prompt: string;
+	fireAt: number;
+	timer: NodeJS.Timeout;
+}
+
+export interface ScheduleToolDeps {
+	onFollowup: (sessionId: string, prompt: string) => Promise<void> | void;
+}
+
+export function buildScheduleTool(deps: ScheduleToolDeps): {
+	tool: AgentTool;
+	pending: Map<string, ScheduledFollowup>;
+} {
+	const pending = new Map<string, ScheduledFollowup>();
+	const tool: AgentTool = {
+		def: {
+			name: 'schedule_followup',
+			description: 'Re-invoke the agent on the current session after the given delay with a new prompt.',
+			parameters: {
+				type: 'object',
+				properties: {
+					delayMs: { type: 'integer', minimum: MIN_DELAY_MS, maximum: MAX_DELAY_MS },
+					prompt: { type: 'string', description: 'Prompt the agent should re-enter on with.' },
+				},
+				required: ['delayMs', 'prompt'],
+			},
+		},
+		handler: async (args: any, ctx: AgentToolContext) => {
+			const delay = Number(args.delayMs);
+			if (!Number.isFinite(delay) || delay < MIN_DELAY_MS || delay > MAX_DELAY_MS) {
+				throw new Error(`delayMs must be between ${MIN_DELAY_MS} and ${MAX_DELAY_MS}`);
+			}
+			const prompt = String(args.prompt ?? '').trim();
+			if (!prompt) throw new Error('prompt is required');
+			const id = randomUUID();
+			const fireAt = Date.now() + delay;
+			const timer = setTimeout(() => {
+				pending.delete(id);
+				Promise.resolve()
+					.then(() => deps.onFollowup(ctx.sessionId, prompt))
+					.catch(() => {
+						/* swallow — caller logs */
+					});
+			}, delay);
+			timer.unref?.();
+			pending.set(id, { id, sessionId: ctx.sessionId, prompt, fireAt, timer });
+			return { id, fireAt };
+		},
+	};
+	return { tool, pending };
+}

package/agent/toolset.ts

@@ -0,0 +1,43 @@
+/**
+ * Tool composer for the built-in agent (#626).
+ *
+ * Operator-only tools (FS, schedule, fetch) are inline today. Once the
+ * unified MCP tool registry (#615) lands with the Operations (#617) and
+ * Application (#618) profiles, this is the seam where RBAC-filtered
+ * registry tools get folded in for the agent's configured user. The shape
+ * of {@link composeToolset} won't change — only the body gains a registry
+ * lookup.
+ */
+
+import { fsTools } from './tools/fsTools.ts';
+import { httpFetchTool } from './tools/httpFetchTool.ts';
+import { buildScheduleTool, type ScheduleToolDeps, type ScheduledFollowup } from './tools/scheduleTool.ts';
+import type { AgentTool } from './types.ts';
+
+export interface ComposeToolsetOpts extends ScheduleToolDeps {
+	/** When `false`, destructive tools are filtered out at composition time. */
+	allowDestructive?: boolean;
+	/** Operator-injected extras (tests, custom plugins). */
+	extraTools?: AgentTool[];
+}
+
+export interface ComposedToolset {
+	tools: AgentTool[];
+	scheduled: Map<string, ScheduledFollowup>;
+}
+
+export function composeToolset(opts: ComposeToolsetOpts): ComposedToolset {
+	const schedule = buildScheduleTool(opts);
+	const all: AgentTool[] = [...fsTools, httpFetchTool, schedule.tool, ...(opts.extraTools ?? [])];
+	const tools = opts.allowDestructive === false ? all.filter((t) => !t.destructive) : all;
+	return { tools, scheduled: schedule.pending };
+}
+
+export function toolMapByName(tools: AgentTool[]): Map<string, AgentTool> {
+	const map = new Map<string, AgentTool>();
+	for (const tool of tools) {
+		if (map.has(tool.def.name)) throw new Error(`Duplicate tool registered: ${tool.def.name}`);
+		map.set(tool.def.name, tool);
+	}
+	return map;
+}