@harperfast/harper 5.2.0-alpha.4 → 5.2.0-alpha.6

package/agent/agent.ts

@@ -8,17 +8,25 @@
  * 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.
+ * worker-thread-shaped to do. Two tool sources compose: operator-only tools
+ * (FS, schedule, fetch, and the V8 inspector) that are inline, and RBAC-filtered
+ * registry tools (#615/#617) drained for the agent's configured user via
+ * `registryTools.ts`.
  */
 
 import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
+import * as env from '../utility/environment/environmentManager.ts';
 import harperLogger from '../utility/logging/harper_logger.ts';
 import { Models } from '../resources/models/Models.ts';
+import type { AuthedUser } from '../components/mcp/toolRegistry.ts';
+import { workers } from '../server/threads/manageThreads.js';
 import { composeToolset } from './toolset.ts';
+import { buildInspectorTools } from './tools/inspectorTool.ts';
+import { buildBestPracticeTool, loadBestPracticesOverview } from './bestPractices.ts';
+import { composeRegistryTools, ensureOperationsToolsRegistered } from './registryTools.ts';
 import { buildOperations } from './operations.ts';
+import { registerAgentMcpTools } from './mcpTools.ts';
 import { runAgent, _resetInFlightForTests } from './loop.ts';
 import { appendMessage, getSession } from './session.ts';
 import type { AgentConfig, AgentScopes, AgentTool } from './types.ts';
@@ -37,6 +45,8 @@ const DEFAULT_CONFIG: AgentConfig = {
 interface StartOpts {
 	server: {
 		registerOperation: (def: { name: string; execute: (op: any) => any | Promise<any> }) => void;
+		/** Resolve a Harper user (with role/permissions) by username. Password/request unused here. */
+		getUser?: (username: string, password: string | null, request: unknown) => Promise<AuthedUser> | AuthedUser;
 	};
 	// Component-level config plumbed by componentLoader (`...componentConfig`).
 	enabled?: boolean;
@@ -48,6 +58,7 @@ interface StartOpts {
 	allowDestructive?: boolean;
 	user?: string;
 	componentsScope?: string;
+	systemPromptAppend?: string;
 }
 
 export async function startOnMainThread(opts: StartOpts): Promise<void> {
@@ -64,11 +75,63 @@ export async function startOnMainThread(opts: StartOpts): Promise<void> {
 	const models = new Models();
 	const abortControllers = new Map<string, AbortController>();
 	let liveConfig: AgentConfig = config;
-	let composed = composeToolset({
-		allowDestructive: liveConfig.allowDestructive,
-		onFollowup: handleFollowup,
+
+	// Populate the Operations MCP profile on the main thread. `agentIdentity` resolves the enforcement
+	// identity fresh on each call (so a live role change is honored, and an unresolvable non-default
+	// user fails closed); the startup snapshot below is only for `visibleTo` listing.
+	ensureOperationsToolsRegistered();
+	const agentIdentity = () => resolveAgentIdentity(opts.server, liveConfig.user);
+	let registryTools = await composeRegistryToolsForListing(agentIdentity);
+
+	// Operator-only V8 inspector tools. Debug config is read once here — enabling threads_debug opens the
+	// worker inspector ports at thread boot, so it can't be toggled without a restart anyway. Worker
+	// count is a live closure over the pool, so attaches range-check against the current worker set.
+	const inspectorTools = buildInspectorTools({
+		debugEnabled: env.get(CONFIG_PARAMS.THREADS_DEBUG) !== false,
+		startingPort: (env.get(CONFIG_PARAMS.THREADS_DEBUG_STARTINGPORT) as number | undefined) ?? undefined,
+		host: (env.get(CONFIG_PARAMS.THREADS_DEBUG_HOST) as string | undefined) ?? '127.0.0.1',
+		getWorkerCount: () => workers.length,
 	});
 
+	// Harper best-practices skill (@harperfast/skills): the SKILL.md overview goes in the system prompt;
+	// the `harper_best_practice` tool serves the detailed rules on demand. Both degrade to nothing if the
+	// package isn't resolvable, so the agent still runs without it.
+	const bestPracticesOverview = loadBestPracticesOverview();
+	const bestPracticeTool = buildBestPracticeTool();
+	const extraTools: AgentTool[] = bestPracticeTool ? [bestPracticeTool] : [];
+
+	// The grounding + best-practices portion of the system prompt is static for the component's
+	// lifetime (scopes don't change), so build it once here; only the operator's per-run
+	// `systemPromptAppend` is folded on at run time in `startRun`.
+	const staticSystemPrompt = buildStaticSystemPrompt(scopes, bestPracticesOverview);
+
+	function compose(): ReturnType<typeof composeToolset> {
+		return composeToolset({
+			allowDestructive: liveConfig.allowDestructive,
+			onFollowup: handleFollowup,
+			inspectorTools,
+			registryTools,
+			extraTools,
+		});
+	}
+
+	let composed = compose();
+
+	// Build the listing snapshot best-effort: if the configured user can't be resolved (and isn't the
+	// default bootstrap user), `agentIdentity` fails closed — the agent then runs with only its
+	// operator-only tools until the operator fixes `agent.user`. Never falls back to an escalated list.
+	async function composeRegistryToolsForListing(resolveIdentity: () => Promise<AuthedUser>): Promise<AgentTool[]> {
+		try {
+			const listingUser = await resolveIdentity();
+			return composeRegistryTools(listingUser, resolveIdentity);
+		} catch (err) {
+			log.error?.(
+				`Registry tools disabled — agent.user='${liveConfig.user}' could not be resolved: ${err instanceof Error ? err.message : String(err)}`
+			);
+			return [];
+		}
+	}
+
 	// 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) {
@@ -109,6 +172,7 @@ export async function startOnMainThread(opts: StartOpts): Promise<void> {
 			autoApprove: liveConfig.autoApprove,
 			signal: controller.signal,
 			generateOpts: { model: liveConfig.model },
+			systemPrompt: composeSystemPrompt(staticSystemPrompt, liveConfig.systemPromptAppend),
 		})
 			.catch((err) => log.error?.(`Agent run failed for ${sessionId}: ${(err as Error)?.message ?? err}`))
 			.finally(() => {
@@ -137,10 +201,7 @@ export async function startOnMainThread(opts: StartOpts): Promise<void> {
 		const previousAllowDestructive = liveConfig.allowDestructive;
 		liveConfig = { ...liveConfig, ...patch };
 		if (liveConfig.allowDestructive !== previousAllowDestructive) {
-			composed = composeToolset({
-				allowDestructive: liveConfig.allowDestructive,
-				onFollowup: handleFollowup,
-			});
+			composed = compose();
 		}
 		// 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
@@ -158,9 +219,89 @@ export async function startOnMainThread(opts: StartOpts): Promise<void> {
 	});
 	for (const op of operations) opts.server.registerOperation(op);
 
+	// Expose the agent over MCP: register curated agent tools into the registry AFTER the ops exist.
+	// (The generic operations-profile walk ran before this, so allow-listing the agent ops wouldn't
+	// surface them — see mcpTools.ts.) They only reach clients when the MCP surface is enabled.
+	registerAgentMcpTools(operations);
+
 	log.info?.(`Agent component initialized with ${composed.tools.length} tools`);
 }
 
+/**
+ * Grounding prompt so the agent knows what it is, where its files live, and how a Harper app is
+ * shaped. The filesystem tools take a `root` scope enum, so we describe the scopes rather than
+ * spelling out path-prefixing rules.
+ *
+ * We deliberately do NOT enumerate individual tool names here — the model already receives the full
+ * tool schema from the SDK, and duplicating names in the prompt drifts as tools are added/removed and
+ * invites hallucinated calls. This describes the tool *surface* at a category level only.
+ *
+ * The built-in grounding and best-practices overview are static for the component's lifetime, so the
+ * caller precomputes them once (`buildStaticSystemPrompt`) and only the operator
+ * `agent.systemPromptAppend` — which can change via `set_agent_config` without a restart — is folded
+ * in per run by `composeSystemPrompt`.
+ */
+function buildStaticSystemPrompt(scopes: AgentScopes, bestPracticesOverview?: string): string {
+	const parts = [
+		'You are the built-in Harper agent, running on the main thread inside a live Harper server.',
+		'You operate this instance for an operator through the tools provided to you: Harper database/cluster operations, scoped filesystem tools, HTTP fetch against this server, followup scheduling, and (when available) V8 inspector tools for debugging worker threads plus a Harper best-practices lookup. Consult the provided tool schemas for the exact set and their parameters.',
+		'',
+		'Filesystem scopes (the fs tools take a `root` naming one of these; paths are relative to it):',
+		`- components — the app source directory, your only WRITE scope: ${scopes.componentsRoot}`,
+		`- logs — read-only: ${scopes.logDir}`,
+		`- config — read-only: ${scopes.configDir}`,
+		'',
+		'A Harper app is a component directory under the components dir. Define tables/resources in a schema (GraphQL `.graphql` with `@table`/`@export`, or `config.yaml` + resource files). After writing or changing component files, deploy/restart as needed for them to load, then verify by querying the REST endpoint via an HTTP fetch against this server.',
+		'Prefer the operations tools for database/cluster actions; use the filesystem tools for app source. When designing schemas or building app logic, consult the Harper best practices below and read the relevant rule via the best-practice tool. Be concise and verify your work.',
+	];
+	if (bestPracticesOverview) {
+		parts.push('', '=== Harper best practices (overview) ===', bestPracticesOverview);
+	}
+	return parts.join('\n');
+}
+
+/** Fold the operator's per-run `systemPromptAppend` onto the precomputed static base. */
+function composeSystemPrompt(staticPrompt: string, append?: string): string {
+	if (typeof append === 'string' && append.trim()) {
+		return `${staticPrompt}\n\n=== Operator instructions ===\n${append.trim()}`;
+	}
+	return staticPrompt;
+}
+
+/**
+ * Resolve the identity the agent's tool calls run as. Registry tools are enforced
+ * (`hdb_user` at call time) against this user, so an operator who sets `agent.user`
+ * to a restricted role gets a narrowed surface — and a later role change is honored,
+ * because this runs per call rather than once at startup.
+ *
+ * Failure policy — fail closed, with one bounded exception:
+ *   - If `agent.user` resolves to a permissioned user, use it.
+ *   - If it can't be resolved AND it's the *default* `hdb_agent` bootstrap user,
+ *     fall back to a super_user identity (the system user isn't provisioned yet —
+ *     #626 defers creating it). This is the documented default-agent behavior.
+ *   - If it can't be resolved and the operator configured a *non-default* user,
+ *     throw. Silently escalating a misconfigured/transient restricted account to
+ *     super_user is the vulnerability we refuse to introduce.
+ */
+export async function resolveAgentIdentity(server: StartOpts['server'], username: string): Promise<AuthedUser> {
+	let resolved: AuthedUser | undefined;
+	if (typeof server.getUser === 'function') {
+		try {
+			const user = await server.getUser(username, null, null);
+			if (user?.role?.permission) resolved = user;
+		} catch (err) {
+			log.warn?.(`Failed to resolve agent.user='${username}': ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	if (resolved) return resolved;
+
+	if (username === DEFAULT_CONFIG.user) {
+		log.warn?.(`Default agent user '${username}' is not provisioned yet; using super_user bootstrap identity`);
+		return { username, role: { permission: { super_user: true } } };
+	}
+	throw new Error(`agent.user '${username}' could not be resolved to a permissioned user; failing closed`);
+}
+
 function resolveScopes(
 	config: AgentConfig,
 	getConfigPath: (param: string) => string | undefined,
@@ -194,6 +335,7 @@ function mergeConfig(opts: StartOpts): AgentConfig {
 		...(opts.allowDestructive !== undefined && { allowDestructive: !!opts.allowDestructive }),
 		...(opts.user !== undefined && { user: String(opts.user) }),
 		...(opts.componentsScope !== undefined && { componentsScope: String(opts.componentsScope) }),
+		...(opts.systemPromptAppend !== undefined && { systemPromptAppend: String(opts.systemPromptAppend) }),
 	};
 }
 

package/agent/bestPractices.ts

@@ -0,0 +1,58 @@
+/**
+ * Harper best-practices knowledge for the built-in agent (#626).
+ *
+ * Sources the `harper-best-practices` skill from the `@harperfast/skills`
+ * package (versioned with the release, no drift). The package exposes the skill
+ * content directly as module exports — `skillSummary` (the SKILL.md overview),
+ * `ruleNames` (the rule index), and `rules` (name → markdown body) — so we read
+ * from those rather than groveling around the installed package on disk.
+ *
+ * Progressive disclosure, mirroring how the skill is meant to be used:
+ *   - the SKILL.md overview (rule index + when-to-use) is injected into the
+ *     agent's system prompt so it always knows *which* practices exist;
+ *   - the detailed rule bodies are pulled on demand via the
+ *     `harper_best_practice` tool, so the agent only spends context on the
+ *     guidance relevant to the task instead of carrying all ~20 rules.
+ */
+
+import { ruleNames, rules, skillSummary } from '@harperfast/skills';
+import type { AgentTool } from './types.ts';
+
+/** The SKILL.md overview (rule index + guidance), for injection into the system prompt. Undefined if unavailable. */
+export function loadBestPracticesOverview(): string | undefined {
+	return skillSummary || undefined;
+}
+
+/**
+ * A tool that lists the best-practice rules (no arg) or returns one rule's full body (`rule` arg).
+ * Returns undefined when the skill package ships no rules, so the caller simply omits it.
+ */
+export function buildBestPracticeTool(): AgentTool | undefined {
+	if (!ruleNames?.length) return undefined;
+	return {
+		def: {
+			name: 'harper_best_practice',
+			description:
+				'Read a Harper best-practices rule for detailed guidance and code examples — schema design, relationships, automatic/REST APIs, authentication, custom resources, caching, vector indexing, TypeScript type-stripping, deployment, logging, and more. Call with no `rule` to list the available rule names; then call again with a `rule` to read it. Consult these before designing schemas or building app logic.',
+			parameters: {
+				type: 'object',
+				properties: {
+					rule: {
+						type: 'string',
+						description: 'Rule name without extension, e.g. "adding-tables-with-schemas". Omit to list all rules.',
+					},
+				},
+			},
+		},
+		handler: async (args: any) => {
+			const rule = args?.rule ? String(args.rule).trim() : '';
+			if (!rule) return { rules: [...ruleNames] };
+			// A plain map lookup — an unknown or malformed name simply misses, so there's no
+			// path-traversal surface to guard against.
+			const content = (rules as Record<string, string>)[rule];
+			if (content == null)
+				throw new Error(`No such best-practice rule: '${rule}'. Call with no rule to list available rules.`);
+			return { rule, content };
+		},
+	};
+}

package/agent/mcpTools.ts

@@ -0,0 +1,122 @@
+/**
+ * Expose the built-in agent over MCP (#626).
+ *
+ * The generic MCP operations profile (#617) can surface these ops too, but only
+ * when an operator opts them into `mcp.operations.allow` and with generic,
+ * schema-inferred descriptions. We register a *curated* agent tool set directly
+ * into the registry instead: exposed by default (no allow-list entry needed),
+ * with hand-written descriptions and annotations tuned for driving the agent.
+ *
+ * Each tool dispatches through the SAME path the generic operations profile uses
+ * (`makeOperationToolHandler` → `chooseOperation` + `processLocalTransaction`), so
+ * Harper's `verifyPerms` runs at call time and enforces the `requiresSuperUser: true`
+ * declared on each agent op — plus any scoped `operations: ['agent_*']` delegation
+ * role. Listing mirrors that boundary via `canRoleInvokeOperation`. A direct
+ * `op.execute(body)` call is NOT used: it would bypass `verifyPerms` entirely and
+ * let any authenticated MCP user drive the super_user agent.
+ */
+
+import { addTool, canRoleInvokeOperation, type AuthedUser } from '../components/mcp/toolRegistry.ts';
+import { makeOperationToolHandler } from '../components/mcp/tools/operations.ts';
+import harperLogger from '../utility/logging/harper_logger.ts';
+import type { OperationDefinition } from '../server/serverHelpers/serverUtilities.ts';
+
+const log = harperLogger.loggerWithTag('agent');
+
+interface AgentMcpToolMeta {
+	description: string;
+	inputSchema: object;
+	destructive?: boolean;
+	readOnly?: boolean;
+}
+
+// Curated client-facing surface for driving the agent. `set_agent_config` is intentionally excluded
+// — it's an operator/config action, not something an MCP client should reach.
+const AGENT_MCP_TOOLS: Record<string, AgentMcpToolMeta> = {
+	agent_prompt: {
+		description:
+			'Send a prompt to the built-in Harper agent. Starts a new session, or continues one when session_id is given. Returns { session_id, status }; poll get_agent_session for the transcript and result.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				message: { type: 'string', description: 'The instruction/prompt for the agent.' },
+				session_id: { type: 'string', description: 'Optional existing session id to continue the conversation.' },
+			},
+			required: ['message'],
+		},
+		destructive: true, // the agent may take actions in response
+	},
+	get_agent_session: {
+		description:
+			'Read a built-in-agent session: its status, full transcript (messages, tool calls and results), and any pending approvals.',
+		inputSchema: {
+			type: 'object',
+			properties: { session_id: { type: 'string' } },
+			required: ['session_id'],
+		},
+		readOnly: true,
+	},
+	list_agent_sessions: {
+		description: 'List built-in-agent sessions, most recent first.',
+		inputSchema: {
+			type: 'object',
+			properties: { limit: { type: 'integer', minimum: 1, description: 'Max sessions to return (default 100).' } },
+		},
+		readOnly: true,
+	},
+	approve_agent_action: {
+		description:
+			'Approve or deny a pending agent tool call (when autoApprove is off), then resume the run. Get the approval_id from get_agent_session.pendingApprovals.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				session_id: { type: 'string' },
+				approval_id: { type: 'string' },
+				approved: { type: 'boolean', description: 'true to approve (default), false to deny.' },
+			},
+			required: ['session_id', 'approval_id'],
+		},
+		destructive: true,
+	},
+	cancel_agent_run: {
+		description: 'Cancel an in-progress agent run for a session.',
+		inputSchema: {
+			type: 'object',
+			properties: { session_id: { type: 'string' } },
+			required: ['session_id'],
+		},
+		destructive: true,
+	},
+};
+
+/**
+ * Register the curated agent tools into the MCP registry (operations profile). Call after the agent
+ * operations are registered. Safe to call whether or not the MCP HTTP surface is enabled — the tools
+ * simply sit in the registry until an MCP client lists them.
+ */
+export function registerAgentMcpTools(operations: OperationDefinition[]): void {
+	const registered = new Set(operations.map((op) => op.name));
+	let count = 0;
+	for (const [name, meta] of Object.entries(AGENT_MCP_TOOLS)) {
+		if (!registered.has(name)) continue; // op not registered (shouldn't happen) — skip rather than expose a dead tool
+		const annotations = meta.destructive ? { destructiveHint: true } : meta.readOnly ? { readOnlyHint: true } : {};
+		addTool({
+			name,
+			description: meta.description,
+			inputSchema: meta.inputSchema,
+			profile: 'operations',
+			...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+			// List only for users the op's role-level policy would let call it (super_user, or a
+			// scoped `operations: ['agent_*']` delegation role). verifyPerms enforces the same at
+			// call time inside makeOperationToolHandler — this predicate keeps hidden tools out of
+			// the listing, not out of reach.
+			visibleTo: (user: AuthedUser) => canRoleInvokeOperation(user, name),
+			// Route through the standard operation dispatch (chooseOperation + processLocalTransaction),
+			// so verifyPerms runs and the op's requiresSuperUser gate is actually enforced — a direct
+			// op.execute() would skip it. Same handler the generic operations profile uses.
+			handler: makeOperationToolHandler(name),
+		});
+		count++;
+	}
+	log.info?.(`Agent MCP tools registered: ${count}`);
+}

package/agent/operations.ts

@@ -134,7 +134,16 @@ async function approveAgentAction(op: any, deps: OperationDeps) {
 
 async function setAgentConfig(op: any, deps: OperationDeps) {
 	const patch: Partial<AgentConfig> = {};
-	for (const key of ['enabled', 'provider', 'model', 'maxTurns', 'maxCostUsd', 'autoApprove', 'allowDestructive']) {
+	for (const key of [
+		'enabled',
+		'provider',
+		'model',
+		'maxTurns',
+		'maxCostUsd',
+		'autoApprove',
+		'allowDestructive',
+		'systemPromptAppend',
+	]) {
 		if (op?.[key] !== undefined) (patch as any)[key] = op[key];
 	}
 	return deps.setConfig(patch);

package/agent/registryTools.ts

@@ -0,0 +1,117 @@
+/**
+ * Registry tool composition for the built-in agent (#626).
+ *
+ * Folds the unified MCP tool registry (#615) — specifically the Operations
+ * profile (#617) — into the agent's toolset. The agent consumes the *same*
+ * registry the MCP HTTP server exposes, RBAC-filtered for its configured user,
+ * so operators get one tool surface with one permission model.
+ *
+ * Two-step, mirroring the registry's own security model:
+ *   1. `visibleTo(agentUser)` narrows *listing* — the LLM only sees tools it is
+ *      likely allowed to call. This is NOT a security boundary.
+ *   2. Real enforcement runs in the operation handler at call time: each call
+ *      dispatches through Harper's operations runtime with `hdb_user` set to the
+ *      agent's configured identity, so `verifyPerms` gates it regardless of what
+ *      the LLM was shown.
+ *
+ * The Application profile (#618) is intentionally out of scope here; it can fold
+ * in the same way once per-Resource tool generation is wired for the agent.
+ */
+
+import { registerOperationsTools } from '../components/mcp/tools/operations.ts';
+import {
+	snapshotProfileTools,
+	type AuthedUser,
+	type ToolCallContext,
+	type ToolDef as RegistryToolDef,
+	type ToolResult,
+} from '../components/mcp/toolRegistry.ts';
+import harperLogger from '../utility/logging/harper_logger.ts';
+import type { AgentTool, AgentToolContext } from './types.ts';
+
+const log = harperLogger.loggerWithTag('agent');
+
+let operationsRegistered = false;
+
+/**
+ * Populate the Operations profile on the main thread. Idempotent: guarded so a
+ * second call (e.g. an `agent.enabled` flip via `set_agent_config`) is a no-op
+ * rather than re-walking `OPERATION_FUNCTION_MAP` and re-logging. The registry's
+ * `addTool` is `Map.set`-backed, so this stays correct whether or not the
+ * operator also enabled the `mcp:` HTTP surface.
+ */
+export function ensureOperationsToolsRegistered(): void {
+	if (operationsRegistered) return;
+	registerOperationsTools();
+	operationsRegistered = true;
+}
+
+/**
+ * Adapt every Operations-profile registry tool into the agent's {@link AgentTool}
+ * shape. Call {@link ensureOperationsToolsRegistered} first so the profile is
+ * populated.
+ *
+ * Two identities, deliberately split:
+ *   - `listingUser` filters `visibleTo` at compose time — which tools the LLM is
+ *     *shown*. Listing is not a security boundary, so a startup snapshot is fine.
+ *   - `resolveIdentity()` is called *per tool call* to set `hdb_user`, so the
+ *     operation is enforced against the agent user's *current* role. This is what
+ *     honors a role revocation/change without a restart — the enforcement identity
+ *     is never cached in the handler closure.
+ */
+export function composeRegistryTools(listingUser: AuthedUser, resolveIdentity: () => Promise<AuthedUser>): AgentTool[] {
+	const defs = snapshotProfileTools('operations');
+	const out: AgentTool[] = [];
+	for (const def of defs) {
+		if (!def.visibleTo(listingUser)) continue;
+		out.push(adaptRegistryTool(def, resolveIdentity));
+	}
+	log.info?.(`Agent composed ${out.length} operations tool(s) for user '${listingUser?.username ?? 'unknown'}'`);
+	return out;
+}
+
+function adaptRegistryTool(def: RegistryToolDef, resolveIdentity: () => Promise<AuthedUser>): AgentTool {
+	return {
+		def: { name: def.name, description: def.description, parameters: def.inputSchema },
+		// The loop's approval gate keys off `destructive`; the registry expresses the same
+		// intent as the MCP `destructiveHint` annotation.
+		destructive: def.annotations?.destructiveHint === true,
+		handler: async (args: object, ctx: AgentToolContext) => {
+			// Resolve the enforcement identity fresh so a live role change is honored. If the
+			// configured user can no longer be resolved, `resolveIdentity` throws (fail closed) —
+			// the loop turns that into a recoverable tool error rather than running with stale or
+			// escalated privileges.
+			const user = await resolveIdentity();
+			const context: ToolCallContext = {
+				user,
+				profile: 'operations',
+				sessionId: ctx.sessionId,
+				...(ctx.signal ? { signal: ctx.signal } : {}),
+			};
+			const result = await def.handler(args, context);
+			// The loop records a tool observation from the return value and turns a thrown error
+			// into a structured `{ ok: false, error }` note for the next model turn. Mapping
+			// `isError` → throw keeps a Harper operation failure a recoverable observation rather
+			// than aborting the whole run.
+			if (result.isError) throw new Error(errorText(result));
+			return result.structuredContent ?? textOf(result);
+		},
+	};
+}
+
+function textOf(result: ToolResult): string {
+	return (result.content ?? [])
+		.filter((c) => c.type === 'text' && typeof c.text === 'string')
+		.map((c) => c.text)
+		.join('\n');
+}
+
+function errorText(result: ToolResult): string {
+	const text = textOf(result);
+	return text || 'operation failed';
+}
+
+/** Test-only: reset the one-time registration guard between specs. */
+export function _resetRegistryToolsForTests(): void {
+	operationsRegistered = false;
+}

package/agent/session.ts

@@ -60,7 +60,13 @@ export async function createSession(opts: CreateSessionOpts): Promise<AgentSessi
 		createdAt: now,
 		updatedAt: now,
 	};
-	await getAgentSessionTable().primaryStore.put(row.session_id, row);
+	// Write through the Resource-level `put` (transactional), NOT `primaryStore.put`: the transactional
+	// path stages the version/local-timestamp metadata so the record is stored with the metadata prefix.
+	// A raw `primaryStore.put` writes a prefix-less record, which — when it begins with classic shared-
+	// structure record-id #2 (byte 0x42 == 66) — is misread by the RocksDB decode heuristic as a
+	// timestamp-prefixed record (8 bytes stripped → corrupt → "Could not find typed structure"). See
+	// RecordEncoder.ts:328-335.
+	await getAgentSessionTable().put(row);
 	return row;
 }
 
@@ -102,7 +108,7 @@ export function appendMessage(sessionId: string, message: AgentMessage): Promise
 		const session = await requireSession(sessionId);
 		session.messages.push(message);
 		session.updatedAt = Date.now();
-		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		await getAgentSessionTable().put(session);
 		return session;
 	});
 }
@@ -113,7 +119,7 @@ export function setStatus(sessionId: string, status: AgentRunStatus, lastError?:
 		session.status = status;
 		session.lastError = lastError;
 		session.updatedAt = Date.now();
-		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		await getAgentSessionTable().put(session);
 		return session;
 	});
 }
@@ -128,7 +134,7 @@ export function addPendingApproval(
 		session.pendingApprovals.push(entry);
 		session.status = 'awaiting_approval';
 		session.updatedAt = Date.now();
-		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		await getAgentSessionTable().put(session);
 		return entry;
 	});
 }
@@ -142,7 +148,7 @@ export function markApprovalConsumed(sessionId: string, approvalId: string): Pro
 		if (entry.consumed) return;
 		entry.consumed = true;
 		session.updatedAt = Date.now();
-		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		await getAgentSessionTable().put(session);
 	});
 }
 
@@ -162,7 +168,7 @@ export function resolveApproval(sessionId: string, approvalId: string, approved:
 			session.status = 'idle';
 		}
 		session.updatedAt = Date.now();
-		await getAgentSessionTable().primaryStore.put(sessionId, session);
+		await getAgentSessionTable().put(session);
 		return entry;
 	});
 }
@@ -170,7 +176,10 @@ export function resolveApproval(sessionId: string, approvalId: string, approved:
 async function requireSession(sessionId: string): Promise<AgentSessionRow> {
 	const session = await getSession(sessionId);
 	if (!session) throw new Error(`No agent session ${sessionId}`);
-	return session;
+	// The store returns a frozen record, so the read-modify-write mutators below (status, messages,
+	// approvals) would throw "Cannot assign to read only property" if they mutated it in place.
+	// Return a mutable deep copy; the mutator writes it back with `put`.
+	return structuredClone(session);
 }
 
 /**