@harperfast/harper-pro 5.0.25 → 5.1.0-beta.1

package/analytics/profile.ts

@@ -32,6 +32,10 @@ const SAMPLING_INTERVAL_IN_MICROSECONDS = 50000;
 export function handleApplication({ options }: Scope) {
 	setTimeout(async () => {
 		if (userCodeFolders.length === 0) return;
+		if (options.get(['profiling']) === false) {
+			log.info?.('Profiling disabled by configuration');
+			return;
+		}
 		// start the profiler
 		if (!profilerStarted) {
 			profilerStarted = true;

package/core/AGENTS.md

@@ -59,19 +59,20 @@ The plugin/application loader. Applications export a `handleApplication(scope)`
 Files within a component are discovered via micromatch glob patterns and automatically mapped to URL paths.
 
 **Server** (`server/`)  
-Two HTTP stacks coexist:
+Multiple HTTP entry points coexist:
 
-- **Native layer** (`server/http.ts`) — direct socket handling for HTTP/1.1, HTTPS, HTTP/2, and WebSockets in one path; highest performance
-- **Fastify layer** (`server/fastifyRoutes.ts`) — used for legacy custom functions; wraps Fastify with autoload
+- **Native layer** (`server/http.ts`) — direct socket handling for application-level HTTP/1.1, HTTPS, HTTP/2, and WebSockets in one path; highest performance. Most user traffic goes through here.
+- **Operations API** (`server/operationsServer.ts`) — Fastify-based JSON operations API (`{operation: 'create_table', ...}`); internal/admin surface.
+- **Custom Functions (legacy)** (`server/fastifyRoutes.ts`) — legacy Fastify autoload for user-defined routes. Don't add new code here.
 
-All inbound protocols (REST, GraphQL, MQTT, NATS, WebSockets) eventually resolve to the same **Resource interface**.
+All inbound protocols (REST, GraphQL, MQTT, NATS, WebSockets) eventually resolve to the same **Resource interface**. See `server/DESIGN.md` for the file-by-file map and the `http.ts` section index.
 
 **Resources** (`resources/`)  
 The universal abstraction. Everything that can be queried or mutated — database tables, caches, message topics, custom endpoints — extends `Resource` (`resources/Resource.ts`).
 
 Static methods (`Resource.get`, `Resource.put`, `Resource.post`, `Resource.delete`, `Resource.patch`, `Resource.subscribe`) are the entry points and are automatically wrapped with `transactional()` for transaction management. Override instance methods (`get`, `put`, etc.) for custom behavior.
 
-`Table.ts` is the database table implementation (~177KB) — the most complex file in the codebase.
+`Table.ts` is the database table implementation (4744 lines, one giant `makeTable()` factory) — the most complex file in the codebase. **Use `resources/DESIGN.md` as a section index instead of reading top-to-bottom.**
 
 **Data Layer** (`dataLayer/`)  
 Legacy translation modules plus SQL translation (`sqlTranslator/`) via AlaSQL; these should be avoided. The storage engine is selectable via `HARPER_STORAGE_ENGINE=lmdb`.
@@ -80,7 +81,62 @@ Legacy translation modules plus SQL translation (`sqlTranslator/`) via AlaSQL; t
 YAML-based. `configUtils.js` parses config; `RootConfigWatcher.ts` enables hot reload. Environment variables override YAML values.
 
 **Utility** (`utility/`)  
-Logging, error types, helpers, async utilities.
+Logging, error types, helpers, async utilities. Most-used: `utility/hdbTerms.ts` (global constants), `utility/logging/harper_logger.js`, `utility/errors/hdbError.js`.
+
+---
+
+## Repository map
+
+Use this to land in the right folder before grepping. Every top-level folder is listed; deeper docs are noted where they exist.
+
+### Source — covered above
+
+- **`components/`** — plugin/app loader. Entry: `Scope.ts`, `OptionsWatcher.ts`. Tests: `unitTests/components/`.
+- **`server/`** — HTTP/WS/MQTT/etc. Entry: `operationsServer.ts` (boot), `http.ts` (native HTTP). **See [server/DESIGN.md](server/DESIGN.md).** Tests: `unitTests/server/`.
+- **`resources/`** — universal Resource abstraction; tables. Entry: `Resource.ts`, `Table.ts`. **See [resources/DESIGN.md](resources/DESIGN.md).** Tests: `unitTests/resources/`.
+- **`dataLayer/`** — legacy translation modules (`insert.js`, `search.js`, `update.js`). **Avoid for new code.** Tests: `unitTests/dataLayer/`.
+- **`config/`** — YAML config + hot reload. Entry: `configUtils.js`, `RootConfigWatcher.ts`. Tests: `unitTests/config/`.
+- **`utility/`** — logging, errors, helpers. Tests: `unitTests/utility/`.
+
+### Other source folders
+
+- **`bin/`** — CLI entry points. `harper.js` is the executable; `run.js` initializes and runs the server; `cliOperations.js` translates CLI args → API operations. Tests: `unitTests/bin/`. **Don't look here for** business logic.
+- **`security/`** — auth, authz, certificate handling, context. Entry: `jsLoader.ts` exposes `getContext()`, `getResponse()`, `getUser()`; `user.ts` for User/Role; `certificateVerification/` for TLS validation; `data_objects/` for permission/role models. Tests: `unitTests/security/`.
+- **`sqlTranslator/`** — SQL → internal operations via AlaSQL AST. Entry: `sqlTranslator/index.js` exports `evaluateSQL`, `processAST`, `convertSQLToAST`, `checkASTPermissions`. **Legacy — avoid for new code.** Tests: `unitTests/sqlTranslator/`.
+- **`validation/`** — input shape validation (Joi + `validate.js`). Entry: `validationWrapper.js`. **Not authorization** — that's in `security/`. Tests: `unitTests/validation/`.
+- **`upgrade/`** — version-upgrade orchestration. Entry: `directivesManager.js` exports `processDirectives()`. Per-version logic in `directives/`. Tests: `integrationTests/upgrade/`.
+- **`launchServiceScripts/`** — thin launchers that delegate to `server/operationsServer.ts`. `checkNodeVersion.js` is the pre-flight Node version check.
+- **`json/`** — system schema definitions. `systemSchema.json` defines built-in tables (`hdb_user`, `hdb_role`, `hdb_permission`). Loaded at startup; no code.
+
+### Non-source
+
+- **`bin/`** — covered above (it's source).
+- **`benchmarks/`** — HNSW vector-search benchmark only (`hnsw-search.js`). Stand-alone; not part of CI.
+- **`build-tools/`** — shell scripts for the build pipeline (`build.sh`, `build-studio.sh`, `download-prebuilds.js`). No tests.
+- **`dev/`** — single dev utility (`sync-commits.js`) for cross-repo commit syncing. Not runtime.
+- **`integrationTests/`** — end-to-end tests against a built distribution. Run with `npm run test:integration` / `npm run test:integration:all`. Subdirs mirror source. See `integrationTests/README.md`.
+- **`unitTests/`** — Mocha unit tests; subdir per source layer. Run with `npm run test:unit:<layer>`.
+- **`static/`** — assets only: `defaultConfig.yaml`, `ascii_logo.txt`.
+
+### Top-level docs to consult
+
+- **[DESIGN.md](DESIGN.md)** — running list of non-obvious internals (RecordObject prototype, getFromSource timing, blob orphan cleanup). Read this before debugging anything record-store-related.
+- **[dependencies.md](dependencies.md)** — rationale for every npm dependency. Required reading before adding a new package.
+- **[storage-format.md](storage-format.md)** — on-disk layout (RocksDB/LMDB).
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — contribution workflow.
+
+---
+
+## Detailed navigation
+
+For megafiles and complex subsystems, jump to the section index instead of reading top-to-bottom:
+
+| If you are touching…                                   | Read first                                 |
+| ------------------------------------------------------ | ------------------------------------------ |
+| Anything in `resources/` (especially `Table.ts`)       | [resources/DESIGN.md](resources/DESIGN.md) |
+| HTTP/WS/MQTT, middleware ordering, content types       | [server/DESIGN.md](server/DESIGN.md)       |
+| Record-store internals (commit timing, blobs, encoder) | [DESIGN.md](DESIGN.md)                     |
+| Adding a dependency                                    | [dependencies.md](dependencies.md)         |
 
 ---
 
@@ -98,6 +154,35 @@ Logging, error types, helpers, async utilities.
 
 ---
 
+## Git / Worktree Setup — Read Before Any Git Operation
+
+This repo lives as a submodule of `harper-pro`. The submodule's git data directory is at
+`../harper-pro/.git/modules/core/` (relative to this repo's root). That directory must contain
+**only git metadata** — `objects/`, `refs/`, `config`, `HEAD`, etc.
+
+**Known recurring failure mode:** If `../harper-pro/.git/modules/core/config` is ever absent or
+replaced by a directory, git silently treats the git data dir as its own work tree. The next
+`git checkout` deposits source files there — including a `config/` directory from the harper
+source tree — which permanently shadows git's config file. Every subsequent agent then hits
+`fatal: unknown error occurred while reading the configuration files` and the cycle repeats.
+
+**Rules to prevent recurrence:**
+
+- Never run `git submodule deinit core` + re-init from the `harper-pro` parent — it regenerates
+  the module config without the required `core.worktree` setting.
+- Never run `git checkout` or `git reset` while your working directory is inside
+  `harper-pro/.git/modules/core/`.
+- If you ever recreate `../harper-pro/.git/modules/core/config` from scratch, it **must** include:
+  ```
+  [core]
+      worktree = ../../../core
+  ```
+- If you see source-tree files (e.g. `server/`, `resources/`, `config/`) appearing inside
+  `../harper-pro/.git/modules/core/`, stop immediately and remove them — they are corrupting the
+  git data directory.
+
+---
+
 ## Non-Obvious Constraints
 
 - `Resource` static methods must stay wrapped with `transactional()` — removing this breaks transaction isolation.
@@ -105,3 +190,4 @@ Logging, error types, helpers, async utilities.
 - `contextStorage` (AsyncLocalStorage) carries per-request context (user, transaction) across async boundaries — this is how authorization and transactions work without explicit parameter threading.
 - Tests under `unitTests/apiTests/` require the server to be stopped first (`node ./dist/bin/harper.js stop`) — `test:unit:apitests` does this automatically.
 - `@export` annotation on a schema class auto-generates a REST API for that table — this is the primary developer-facing API.
+- Test style: write new unit tests with `node:assert/strict` against real modules — **do not add new uses of `sinon` or `rewire`**. Older tests in `unitTests/security/` and `unitTests/utility/` still depend on them but they are not the target shape; match newer tests in `unitTests/config/*`, `unitTests/resources/*`, `unitTests/components/*`. If you can't write a test without stubbing, comment on the issue describing what's missing and stop — don't reach for sinon/rewire as a shortcut.

package/core/DESIGN.md

@@ -71,3 +71,27 @@ The cross-thread subscription path (default `crossThreads`) drives every `Table.
 - **`databaseSubscriptions.activeCount`** is the count of live `Subscription` instances on a database. It is incremented at the end of `addSubscription` (after the Subscription is created, so the `scope: 'full-database'` early-return path correctly skips counting) and decremented in `Subscription.end()`. `notifyFromTransactionData` short-circuits when this is zero — the reusable rocksdb iterator stays put and resumes from its position the next time a subscriber arrives. Without this short-circuit, an idle database with no subscribers still pays the audit-log iteration cost on every commit during replication backlog catch-up.
 - **`notifyScheduled` + `setImmediate`** in the `'committed'` listener defers the iteration off the commit microtask. Multiple `'committed'` events that land in the same event-loop turn collapse into one notify pass. `notifyScheduled` stays set for the entire drain — including across yield-and-resume turns — so a re-entry from a new `'committed'` event cannot spawn a second concurrent notify on the same iterator.
 - **Batched yielding** in `notifyFromTransactionData` (`NOTIFY_BATCH_SIZE`) is gated by `allowYield`. The `'committed'` path passes `allowYield = true`; the `listenToCommits` (same-thread `aftercommit`) path does not, because that path holds an inter-thread `'thread-local-writes'` lock that must not span event-loop turns. `subscribersWithTxns` is carried across yields via `subscriptions.pendingTxnSubscribers` so the `end_txn` signal fires exactly once when the iterator truly drains. When `activeCount` drops to zero mid-yield, the next continuation drops the carry-over to avoid invoking ended subscribers' listeners.
+
+## `createBlob(readable)` and `table.put()` don't synchronously drain the source
+
+When a blob attribute is created from a Node `Readable` (e.g. `createBlob(stream)` then `row.payload_blob = blob; await table.put(row)`), the put does **not** wait for the underlying stream to fully drain into the file before resolving. Internally `saveBlob` kicks off a `writeBlobWithStream` pipeline whose `storageInfo.saving` promise is tracked separately. The put resolves once encoding has captured the blob reference; the bytes finish writing concurrently.
+
+Consequence for callers that wrap the source in a hashing `Transform`: calling `hash.digest('hex')` after `await table.put()` is unsafe — more `chunk.update()` calls can still fire as the stream drains, producing `Error [ERR_CRYPTO_HASH_FINALIZED]: Digest already called`. Options:
+
+- Buffer first, then hash + put (what `components/deploymentRecorder.ts` does for Slice A — small payloads only).
+- Hash via Transform while extraction reads the stream, and only finalize the hash on the Transform's `'end'` event before any second put with the final hash.
+- Await `storageInfo.saving` directly if you have a handle to the FileBackedBlob (the cleanest path for streaming).
+
+Future agents touching `components/deploymentRecorder.ts` for Slice B's streaming variant should pick one of the latter two patterns.
+
+## System table bootstrap: `systemSchema.json` + upgrade directive
+
+Adding a new system table (e.g. `hdb_deployment` in #641 Slice A) requires three changes:
+
+1. **`json/systemSchema.json`** — the table entry. Fresh installs auto-create it via `utility/mount_hdb.ts:createTables()`, which iterates `Object.keys(systemSchema)` on first boot.
+2. **`utility/hdbTerms.ts`** — add the table name to `SYSTEM_TABLE_NAMES`.
+3. **`upgrade/directives/<version>.ts`** — provisions the table on existing installs that already have a system schema. Registered in `upgrade/directives/directivesController.ts` (which is otherwise empty — its `versions` Map gets populated by these imports). The directive shape is `{ version, sync_functions, async_functions }`; copy `5-2-0.ts` for the canonical pattern (uses `bridge.createTable` to match what `mount_hdb` does on a fresh install).
+
+System tables replicate by default. To opt out, add the name to `NON_REPLICATING_SYSTEM_TABLES` in `resources/databases.ts`. The check happens after table init and sets `table.replicate = false` per-node.
+
+If the table needs `audit: true`, set it both in the schema (for fresh installs) **and** on the `CreateTableObject` instance in the directive (for upgrades) — otherwise the two paths diverge.

package/core/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/core/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/core/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();
+}