@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/README.md

@@ -18,18 +18,11 @@ Harper is an open-source Node.js unified development platform that fuses databas
 
 ---
 
-## Getting Started
+## Quick Installation
 
-1. [Install Harper](https://docs.harperdb.io/docs/getting-started/installation)
-2. [Create Your First App](https://docs.harperdb.io/docs/getting-started/quickstart)
+`npm i -g harper`
 
-## Open Source Note
-
-This repository represents Harper's future direction as an open-source-first platform. The code here is under active development and targets the upcoming **Harper v5** release. If you're looking for production-ready Harper, please refer to **Harper v4** — our current closed-source release documented at https://docs.harper.fast . We're rebuilding Harper from the ground up with an open source core and modular source-available plugins. This code is not yet published or production-ready, but we're excited to build the next generation of Harper in the open. Follow along, provide feedback, and watch as we shape the future of the platform together.
-
-## What is HarperDB?
-
-HarperDB is our previous name. Earlier in 2025, [we rebranded](https://www.harper.fast/announcements/harperdb-proclaims-new-era-for-web-performance-with-corporate-rebrand) to just "Harper" to reflect our evolution from a database to a full performance platform. The core technology remains the same, but we've expanded our vision to encompass more than just database functionality. Since this repo was created from the existing Harper codebase, you may still see references to the old name "HarperDB" in certain places.
+Get started building Harper applications by following our Learn guide: https://docs.harperdb.io/learn
 
 ## Contributing to Harper
 
@@ -43,6 +36,14 @@ For more information on how to contribute, please see our:
 - [Code of Conduct](./CODE_OF_CONDUCT.md)
 - [Support](./SUPPORT.md)
 
+## Harper Pro
+
+[Harper Pro](https://github.com/harperfast/harper-pro) is the source-available distribution of Harper, built on top of this open source `harper` core. It extends the core with enterprise features including multi-node replication, certificate management, and extended profiling and analytics. It is licensed under the [Elastic License 2.0](https://www.elastic.co/licensing/elastic-license).
+
+## What is HarperDB?
+
+HarperDB is our previous name. Earlier in 2025, [we rebranded](https://www.harper.fast/announcements/harperdb-proclaims-new-era-for-web-performance-with-corporate-rebrand) to just "Harper" to reflect our evolution from a database to a full performance platform. The core technology remains the same, but we've expanded our vision to encompass more than just database functionality. Since this repo was created from the existing Harper codebase, you may still see references to the old name "HarperDB" in certain places.
+
 ## Security
 
 Please review our [Security Policy](./SECURITY.md) for reporting vulnerabilities.

package/agent/agent.ts

@@ -0,0 +1,203 @@
+/**
+ * Built-in Harper Agent component (#626).
+ *
+ * `startOnMainThread` is invoked once on the main thread by `componentLoader`.
+ * When `agent.enabled` is `false` (default) the component registers nothing
+ * and returns immediately — opt-in keeps surprise LLM costs at bay. When
+ * enabled, the six operations land on the operations API, the session table
+ * is realized lazily on first use, and the loop runs in-process.
+ *
+ * The component intentionally avoids `handleApplication`: it has nothing
+ * worker-thread-shaped to do. Operator-only tools (FS, schedule, fetch) are
+ * inline; registry-backed tools (#615/#617/#618) will fold in via toolset.ts
+ * once those land.
+ */
+
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
+import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import harperLogger from '../utility/logging/harper_logger.ts';
+import { Models } from '../resources/models/Models.ts';
+import { composeToolset } from './toolset.ts';
+import { buildOperations } from './operations.ts';
+import { runAgent, _resetInFlightForTests } from './loop.ts';
+import { appendMessage, getSession } from './session.ts';
+import type { AgentConfig, AgentScopes, AgentTool } from './types.ts';
+
+const log = harperLogger.loggerWithTag('agent');
+
+const DEFAULT_CONFIG: AgentConfig = {
+	enabled: false,
+	maxTurns: 50,
+	maxCostUsd: 5,
+	autoApprove: false,
+	allowDestructive: false,
+	user: 'hdb_agent',
+};
+
+interface StartOpts {
+	server: {
+		registerOperation: (def: { name: string; execute: (op: any) => any | Promise<any> }) => void;
+	};
+	// Component-level config plumbed by componentLoader (`...componentConfig`).
+	enabled?: boolean;
+	provider?: string;
+	model?: string;
+	maxTurns?: number;
+	maxCostUsd?: number;
+	autoApprove?: boolean;
+	allowDestructive?: boolean;
+	user?: string;
+	componentsScope?: string;
+}
+
+export async function startOnMainThread(opts: StartOpts): Promise<void> {
+	const config = mergeConfig(opts);
+	if (!config.enabled) {
+		log.info?.('Agent component disabled (agent.enabled=false); skipping registration');
+		return;
+	}
+
+	// Lazily required to avoid pulling configUtils at module-eval time for tests.
+	const { getConfigPath, getConfigFilePath } = require('../config/configUtils.js');
+	const scopes = resolveScopes(config, getConfigPath, getConfigFilePath);
+
+	const models = new Models();
+	const abortControllers = new Map<string, AbortController>();
+	let liveConfig: AgentConfig = config;
+	let composed = composeToolset({
+		allowDestructive: liveConfig.allowDestructive,
+		onFollowup: handleFollowup,
+	});
+
+	// Only warn when the operator explicitly configured `maxCostUsd`. Logging on the default
+	// every boot would flood the log without telling anyone anything actionable.
+	if (opts.maxCostUsd !== undefined) {
+		log.warn?.(
+			`agent.maxCostUsd=${liveConfig.maxCostUsd} is advertised but not yet enforced; cost-cap wiring depends on #612 telemetry.`
+		);
+	}
+
+	async function handleFollowup(sessionId: string, prompt: string): Promise<void> {
+		const session = await getSession(sessionId);
+		if (!session) {
+			log.warn?.(`schedule_followup target session ${sessionId} not found`);
+			return;
+		}
+		await appendMessage(sessionId, { role: 'user', content: prompt, createdAt: Date.now() });
+		startRun(sessionId);
+	}
+
+	function currentTools(): AgentTool[] {
+		return composed.tools;
+	}
+
+	function startRun(sessionId: string): void {
+		// A run is already active for this session. `runAgent` coalesces concurrent starts onto the
+		// existing in-flight promise (bound to the existing controller), so creating a second
+		// controller here would orphan it — `cancelRun` would then abort a controller nothing is
+		// listening to, leaving the live run uncancellable. Any message appended before this call
+		// (e.g. by a scheduled followup) is picked up by the in-flight loop on its next turn.
+		if (abortControllers.has(sessionId)) return;
+		const controller = new AbortController();
+		abortControllers.set(sessionId, controller);
+		runAgent({
+			sessionId,
+			models,
+			tools: currentTools(),
+			scopes,
+			maxTurns: liveConfig.maxTurns,
+			autoApprove: liveConfig.autoApprove,
+			signal: controller.signal,
+			generateOpts: { model: liveConfig.model },
+		})
+			.catch((err) => log.error?.(`Agent run failed for ${sessionId}: ${(err as Error)?.message ?? err}`))
+			.finally(() => {
+				if (abortControllers.get(sessionId) === controller) abortControllers.delete(sessionId);
+			});
+	}
+
+	function cancelRun(sessionId: string): boolean {
+		// Clear any scheduled followups first. Without this, a timer set via `schedule_followup`
+		// would fire after the operator cancelled, silently re-injecting a user prompt and kicking
+		// the loop off again — surprising behavior and avoidable LLM cost.
+		for (const [id, followup] of composed.scheduled.entries()) {
+			if (followup.sessionId === sessionId) {
+				clearTimeout(followup.timer);
+				composed.scheduled.delete(id);
+			}
+		}
+		const controller = abortControllers.get(sessionId);
+		if (!controller) return false;
+		controller.abort(new Error('cancelled by operator'));
+		abortControllers.delete(sessionId);
+		return true;
+	}
+
+	function setConfig(patch: Partial<AgentConfig>): AgentConfig {
+		const previousAllowDestructive = liveConfig.allowDestructive;
+		liveConfig = { ...liveConfig, ...patch };
+		if (liveConfig.allowDestructive !== previousAllowDestructive) {
+			composed = composeToolset({
+				allowDestructive: liveConfig.allowDestructive,
+				onFollowup: handleFollowup,
+			});
+		}
+		// NOTE: an already in-flight run captured its toolset (and autoApprove) at start, so flipping
+		// allowDestructive here only affects subsequent runs — the live loop finishes on its existing
+		// toolset. Acceptable: the approval gate still applies on the next turn's run, and operators
+		// who need to halt a run immediately use cancel_agent_run. Tightening to per-turn re-evaluation
+		// would require threading a config getter into the loop; deferred until there's a need.
+		return liveConfig;
+	}
+
+	const operations = buildOperations({
+		getConfig: () => liveConfig,
+		setConfig,
+		startRun,
+		cancelRun,
+	});
+	for (const op of operations) opts.server.registerOperation(op);
+
+	log.info?.(`Agent component initialized with ${composed.tools.length} tools`);
+}
+
+function resolveScopes(
+	config: AgentConfig,
+	getConfigPath: (param: string) => string | undefined,
+	getConfigFilePath?: () => string
+): AgentScopes {
+	const componentsRoot = getConfigPath(CONFIG_PARAMS.COMPONENTSROOT) ?? process.cwd();
+	const logDir = getConfigPath(CONFIG_PARAMS.LOGGING_ROOT) ?? process.cwd();
+	const rootPath = getConfigPath(CONFIG_PARAMS.ROOTPATH) ?? componentsRoot;
+	const configFile = getConfigFilePath?.();
+	const configDir = configFile ? dirname(configFile) : process.cwd();
+	// A relative `componentsScope` is resolved against rootPath, as documented in the schema —
+	// NOT against componentsRoot, which would double-nest (`./components` → componentsRoot/components).
+	// With no scope set, the full componentsRoot is the FS write scope.
+	const scopedComponents = config.componentsScope
+		? isAbsolute(config.componentsScope)
+			? config.componentsScope
+			: resolvePath(rootPath, config.componentsScope)
+		: componentsRoot;
+	return { componentsRoot: scopedComponents, logDir, configDir };
+}
+
+function mergeConfig(opts: StartOpts): AgentConfig {
+	return {
+		...DEFAULT_CONFIG,
+		...(opts.enabled !== undefined && { enabled: !!opts.enabled }),
+		...(opts.provider !== undefined && { provider: String(opts.provider) }),
+		...(opts.model !== undefined && { model: String(opts.model) }),
+		...(opts.maxTurns !== undefined && { maxTurns: Number(opts.maxTurns) }),
+		...(opts.maxCostUsd !== undefined && { maxCostUsd: Number(opts.maxCostUsd) }),
+		...(opts.autoApprove !== undefined && { autoApprove: !!opts.autoApprove }),
+		...(opts.allowDestructive !== undefined && { allowDestructive: !!opts.allowDestructive }),
+		...(opts.user !== undefined && { user: String(opts.user) }),
+		...(opts.componentsScope !== undefined && { componentsScope: String(opts.componentsScope) }),
+	};
+}
+
+/** Test-only: reset module state between specs. */
+export function _resetForTests(): void {
+	_resetInFlightForTests();
+}

package/agent/loop.ts

@@ -0,0 +1,205 @@
+/**
+ * Manual agent loop for the built-in agent (#626).
+ *
+ * Wraps `scope.models.generate({ ..., toolMode: 'return' })` and dispatches
+ * any tool calls the model returns. This is a temporary stand-in for the
+ * unified `toolMode: 'auto'` orchestrator landing in #612 — when that ships,
+ * tool-call dispatch and the per-turn loop collapse into a single
+ * `generate({ ..., toolMode: 'auto' })` call. The approval/abort gates here
+ * still live in the component (the orchestrator won't know about
+ * `destructive` or operator approval semantics).
+ *
+ * Per-session serialization (one concurrent run per session) is handled
+ * here via {@link runAgent}'s in-flight map. Multiple sessions interleave
+ * on the event loop naturally because each turn is mostly awaiting the LLM
+ * or a tool's I/O.
+ */
+
+import type { GenerateOpts, GenerateResult, Message, Models, ToolCall, ToolDef } from '../resources/models/types.ts';
+import { addPendingApproval, appendMessage, getSession, markApprovalConsumed, setStatus } from './session.ts';
+import type { AgentMessage, AgentScopes, AgentTool, AgentToolContext } from './types.ts';
+import { toolMapByName } from './toolset.ts';
+
+export interface RunAgentOpts {
+	sessionId: string;
+	models: Pick<Models, 'generate'>;
+	tools: AgentTool[];
+	scopes: AgentScopes;
+	maxTurns: number;
+	/** When false, destructive tools pause the loop with a pending approval instead of executing. */
+	autoApprove?: boolean;
+	signal?: AbortSignal;
+	generateOpts?: Omit<GenerateOpts, 'toolMode' | 'signal'>;
+	/** System prompt injected as the first turn when the transcript is empty. */
+	systemPrompt?: string;
+}
+
+const inFlight = new Map<string, Promise<void>>();
+
+export function runAgent(opts: RunAgentOpts): Promise<void> {
+	const existing = inFlight.get(opts.sessionId);
+	if (existing) return existing;
+	const run = doRun(opts).finally(() => {
+		if (inFlight.get(opts.sessionId) === run) inFlight.delete(opts.sessionId);
+	});
+	inFlight.set(opts.sessionId, run);
+	return run;
+}
+
+async function doRun(opts: RunAgentOpts): Promise<void> {
+	const toolMap = toolMapByName(opts.tools);
+	const toolDefs: ToolDef[] = opts.tools.map((t) => t.def);
+	await setStatus(opts.sessionId, 'running');
+	const ctx: AgentToolContext = { sessionId: opts.sessionId, signal: opts.signal, scopes: opts.scopes };
+
+	try {
+		// First, drain any resolved-but-unconsumed approvals from a prior pause. Either execute
+		// or refuse each saved call, recording an observation, so the next model turn sees the
+		// result of the operator decision.
+		await consumeResolvedApprovals(opts.sessionId, toolMap, ctx);
+
+		// If a turn produced multiple gated tool calls and the operator has only resolved some of
+		// them, the remaining approvals are still pending — meaning the assistant's tool_calls do
+		// not yet all have tool responses. Re-entering the generate loop now would send an
+		// incomplete tool-response set and the provider would 400. Stay paused until every gated
+		// call for this turn is resolved (each `approve_agent_action` re-runs this path).
+		const afterConsume = await getSession(opts.sessionId);
+		if (afterConsume?.pendingApprovals.some((a) => !a.resolved)) {
+			await setStatus(opts.sessionId, 'awaiting_approval');
+			return;
+		}
+
+		for (let turn = 0; turn < opts.maxTurns; turn++) {
+			if (opts.signal?.aborted) return; // status was already set to `aborted` by cancelRun
+			const session = await getSession(opts.sessionId);
+			if (!session) throw new Error(`Session ${opts.sessionId} vanished mid-run`);
+			const messages = toModelMessages(session.messages, opts.systemPrompt);
+			const result: GenerateResult = await opts.models.generate(
+				{ messages, tools: toolDefs, system: opts.systemPrompt },
+				{ ...opts.generateOpts, toolMode: 'return', signal: opts.signal }
+			);
+
+			await appendMessage(opts.sessionId, {
+				role: 'assistant',
+				content: result.content ?? '',
+				toolCalls: result.toolCalls,
+				createdAt: Date.now(),
+			});
+
+			if (!result.toolCalls || result.toolCalls.length === 0) {
+				await setStatus(opts.sessionId, 'completed');
+				return;
+			}
+
+			const paused = await dispatchToolCalls(result.toolCalls, toolMap, ctx, opts);
+			if (paused || opts.signal?.aborted) return;
+		}
+		await setStatus(opts.sessionId, 'completed', `Reached maxTurns=${opts.maxTurns} without a final answer.`);
+	} catch (err) {
+		// If the abort signal fired, the cancel path already set the session to `aborted` —
+		// don't clobber that with `error`. The rejection here is just the awaited generate/tool
+		// honoring the signal, not a real failure.
+		if (opts.signal?.aborted) return;
+		await setStatus(opts.sessionId, 'error', err instanceof Error ? err.message : String(err));
+		throw err;
+	}
+}
+
+/**
+ * Returns `true` when the loop should pause (any destructive tool call required approval).
+ * Non-destructive calls execute inline and their observations are appended. Destructive calls
+ * register pending approvals but do NOT append a tool message — `consumeResolvedApprovals`
+ * writes the single tool response on the next run. This keeps the 1:1 mapping between
+ * assistant tool_calls and tool responses that LLM APIs enforce, including when the assistant
+ * message mixes destructive and non-destructive calls in the same turn.
+ */
+async function dispatchToolCalls(
+	calls: ToolCall[],
+	toolMap: Map<string, AgentTool>,
+	ctx: AgentToolContext,
+	opts: RunAgentOpts
+): Promise<boolean> {
+	let needsApproval = false;
+	for (const call of calls) {
+		if (opts.signal?.aborted) return true;
+		const tool = toolMap.get(call.name);
+		const destructiveAndGated = tool?.destructive && !opts.autoApprove;
+		if (destructiveAndGated) {
+			await addPendingApproval(opts.sessionId, {
+				toolName: call.name,
+				arguments: call.arguments ?? {},
+				toolCallId: call.id,
+				reason: 'destructive',
+			});
+			needsApproval = true;
+			// Don't break — keep processing remaining calls so non-destructive ones in the same
+			// turn still execute and write their tool responses. Their results may be useful
+			// context for the operator deciding whether to approve.
+			continue;
+		}
+		const observation = await invokeTool(call, toolMap, ctx);
+		await appendMessage(opts.sessionId, {
+			role: 'tool',
+			content: observation,
+			toolCallId: call.id,
+			createdAt: Date.now(),
+		});
+	}
+	return needsApproval;
+}
+
+async function consumeResolvedApprovals(
+	sessionId: string,
+	toolMap: Map<string, AgentTool>,
+	ctx: AgentToolContext
+): Promise<void> {
+	const session = await getSession(sessionId);
+	if (!session) return;
+	const toConsume = session.pendingApprovals.filter((a) => a.resolved && !a.consumed);
+	for (const approval of toConsume) {
+		const observation = approval.approved
+			? await invokeTool(
+					{ id: approval.toolCallId, name: approval.toolName, arguments: approval.arguments },
+					toolMap,
+					ctx
+				)
+			: JSON.stringify({ ok: false, error: 'denied_by_operator', tool: approval.toolName });
+		await appendMessage(sessionId, {
+			role: 'tool',
+			content: observation,
+			toolCallId: approval.toolCallId,
+			createdAt: Date.now(),
+		});
+		await markApprovalConsumed(sessionId, approval.id);
+	}
+}
+
+async function invokeTool(call: ToolCall, toolMap: Map<string, AgentTool>, ctx: AgentToolContext): Promise<string> {
+	const tool = toolMap.get(call.name);
+	if (!tool) return JSON.stringify({ error: 'unknown_tool', name: call.name });
+	try {
+		const result = await tool.handler(call.arguments ?? {}, ctx);
+		return JSON.stringify({ ok: true, result });
+	} catch (err) {
+		return JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) });
+	}
+}
+
+function toModelMessages(items: AgentMessage[], systemPrompt: string | undefined): Message[] {
+	const out: Message[] = [];
+	if (systemPrompt && !items.some((m) => m.role === 'system')) {
+		out.push({ role: 'system', content: systemPrompt });
+	}
+	for (const item of items) {
+		const message: Message = { role: item.role, content: item.content };
+		if (item.toolCalls) message.toolCalls = item.toolCalls;
+		if (item.toolCallId) message.toolCallId = item.toolCallId;
+		out.push(message);
+	}
+	return out;
+}
+
+/** Test-only: clear the in-flight tracking map. */
+export function _resetInFlightForTests(): void {
+	inFlight.clear();
+}

package/agent/operations.ts

@@ -0,0 +1,148 @@
+/**
+ * Operations API surface for the built-in agent (#626).
+ *
+ * Six handlers, all super_user-only — the auth check is inline because none
+ * of these ops are registered in `utility/operation_authorization.ts`'s
+ * `requiredPermissions` map. Without the inline gate, a non-SU request would
+ * fall through the standard flow and be allowed.
+ */
+
+import type { OperationDefinition } from '../server/serverHelpers/serverUtilities.ts';
+import { OPERATIONS_ENUM } from '../utility/hdbTerms.ts';
+import { ClientError } from '../utility/errors/hdbError.ts';
+import { createSession, getSession, listSessions, appendMessage, resolveApproval, setStatus } from './session.ts';
+import type { AgentConfig, AgentMessage, AgentRunStatus } from './types.ts';
+
+export interface OperationDeps {
+	getConfig: () => AgentConfig;
+	setConfig: (patch: Partial<AgentConfig>) => AgentConfig;
+	startRun: (sessionId: string) => void;
+	cancelRun: (sessionId: string) => boolean;
+}
+
+export function buildOperations(deps: OperationDeps): OperationDefinition[] {
+	return [
+		{
+			name: OPERATIONS_ENUM.AGENT_PROMPT,
+			execute: async (op) => agentPrompt(op, deps),
+		},
+		{
+			name: OPERATIONS_ENUM.GET_AGENT_SESSION,
+			execute: async (op) => getAgentSession(op),
+		},
+		{
+			name: OPERATIONS_ENUM.LIST_AGENT_SESSIONS,
+			execute: async (op) => listAgentSessions(op),
+		},
+		{
+			name: OPERATIONS_ENUM.CANCEL_AGENT_RUN,
+			execute: async (op) => cancelAgentRun(op, deps),
+		},
+		{
+			name: OPERATIONS_ENUM.APPROVE_AGENT_ACTION,
+			execute: async (op) => approveAgentAction(op, deps),
+		},
+		{
+			name: OPERATIONS_ENUM.SET_AGENT_CONFIG,
+			execute: async (op) => setAgentConfig(op, deps),
+		},
+	];
+}
+
+function requireSuperUser(op: any): void {
+	if (!op?.hdb_user?.role?.permission?.super_user) {
+		throw new ClientError('Agent operations require super_user', 403);
+	}
+}
+
+async function agentPrompt(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const config = deps.getConfig();
+	if (!config.enabled) {
+		throw new ClientError('Agent component is disabled (agent.enabled=false)', 409);
+	}
+	const message = String(op?.message ?? '').trim();
+	if (!message) throw new ClientError('message is required', 400);
+
+	let sessionId: string = op?.session_id;
+	if (sessionId) {
+		const existing = await getSession(sessionId);
+		if (!existing) throw new ClientError(`Unknown session ${sessionId}`, 404);
+		if (existing.status === 'running' || existing.status === 'awaiting_approval') {
+			throw new ClientError(
+				`Session ${sessionId} is ${existing.status}; resolve or cancel before sending another prompt`,
+				409
+			);
+		}
+		await appendMessage(sessionId, asUserMessage(message));
+	} else {
+		const created = await createSession({
+			user: op?.hdb_user?.username ?? config.user,
+			model: config.model,
+			provider: config.provider,
+			initialMessage: asUserMessage(message),
+		});
+		sessionId = created.session_id;
+	}
+
+	deps.startRun(sessionId);
+	return { session_id: sessionId, status: 'running' satisfies AgentRunStatus };
+}
+
+async function getAgentSession(op: any) {
+	requireSuperUser(op);
+	const sessionId = String(op?.session_id ?? '');
+	if (!sessionId) throw new ClientError('session_id is required', 400);
+	const session = await getSession(sessionId);
+	if (!session) throw new ClientError(`Unknown session ${sessionId}`, 404);
+	return session;
+}
+
+async function listAgentSessions(op: any) {
+	requireSuperUser(op);
+	const limit = Number.isFinite(op?.limit) ? Number(op.limit) : undefined;
+	return { sessions: await listSessions({ limit }) };
+}
+
+async function cancelAgentRun(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const sessionId = String(op?.session_id ?? '');
+	if (!sessionId) throw new ClientError('session_id is required', 400);
+	const session = await getSession(sessionId);
+	if (!session) throw new ClientError(`Unknown session ${sessionId}`, 404);
+	// Abort any active controller (best-effort — there may not be one if the loop is paused
+	// in `awaiting_approval` or sitting `idle` between turns). Always update the persisted
+	// status so a paused session can still be terminated by the operator.
+	const signalledLiveRun = deps.cancelRun(sessionId);
+	const wasTerminal = session.status === 'completed' || session.status === 'aborted' || session.status === 'error';
+	if (!wasTerminal) await setStatus(sessionId, 'aborted', 'Cancelled by operator');
+	return { cancelled: !wasTerminal, signalledLiveRun };
+}
+
+async function approveAgentAction(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const sessionId = String(op?.session_id ?? '');
+	const approvalId = String(op?.approval_id ?? '');
+	if (!sessionId || !approvalId) {
+		throw new ClientError('session_id and approval_id are required', 400);
+	}
+	const approved = op?.approved !== false;
+	const resolved = await resolveApproval(sessionId, approvalId, approved);
+	// Either decision should resume the loop: an approval means execute the saved tool call;
+	// a denial means hand the operator-rejection observation back to the model so it can adjust.
+	deps.startRun(sessionId);
+	return resolved;
+}
+
+async function setAgentConfig(op: any, deps: OperationDeps) {
+	requireSuperUser(op);
+	const patch: Partial<AgentConfig> = {};
+	for (const key of ['enabled', 'provider', 'model', 'maxTurns', 'maxCostUsd', 'autoApprove', 'allowDestructive']) {
+		if (op?.[key] !== undefined) (patch as any)[key] = op[key];
+	}
+	return deps.setConfig(patch);
+}
+
+function asUserMessage(content: string): AgentMessage {
+	return { role: 'user', content, createdAt: Date.now() };
+}