@harperfast/harper 5.0.25 → 5.1.0-beta.1

package/components/deploymentRecorder.ts

@@ -0,0 +1,402 @@
+'use strict';
+
+// DeploymentRecorder — lifecycle owner for one row in system.hdb_deployment.
+//
+// Creates the pending row at deploy start, persists the upload payload into the row's
+// payload_blob (with sha256 + size), and writes the terminal status at the end.
+// Subscribes to a ProgressEmitter so phase transitions and install lines land in
+// event_log as they happen — making the deploy observable by Studio polling
+// get_deployment without an attached CLI. The persisted payload_blob will also serve
+// as the rollback source when that operation lands.
+
+import { randomUUID } from 'node:crypto';
+import { createHash, Hash } from 'node:crypto';
+import type { Readable } from 'node:stream';
+import { databases } from '../resources/databases.ts';
+import { createBlob } from '../resources/blob.ts';
+import * as terms from '../utility/hdbTerms.ts';
+import { ClientError } from '../utility/errors/hdbError.ts';
+import { hostname } from 'node:os';
+import { ProgressEmitter } from '../server/serverHelpers/progressEmitter.ts';
+
+// Bound the event_log so a pathologically chatty install can't grow a row without limit.
+// 200 entries comfortably covers a real deploy with headroom (phase events plus install
+// line summaries). When we exceed the cap, drop the middle rather than the front — the
+// lifecycle spine (prepare → load → replicate → success) is the most valuable context
+// for debugging, and naive front-truncation loses it under a chatty `npm install`.
+const EVENT_LOG_MAX = 200;
+const EVENT_LOG_HEAD_KEEP = 20;
+
+// In-memory registry of live emitters, keyed by deployment_id. Populated for the lifetime
+// of an in-progress deploy on the origin node; get_deployment SSE looks here to tail live
+// events after replaying event_log. Per-node, not replicated — peers don't see another
+// node's in-progress emitters. Cross-node tailing is a later concern.
+const activeEmitters = new Map<string, ProgressEmitter>();
+
+export function getActiveEmitter(deploymentId: string): ProgressEmitter | undefined {
+	return activeEmitters.get(deploymentId);
+}
+
+// Interim cap: ingestPayload currently buffers the entire payload in memory before
+// computing the hash and persisting. This cap prevents an OOM on accidentally-huge
+// uploads. A follow-up will swap this for a true streaming-hash + blob-source pattern
+// that lifts the limit back to whatever the replication path supports.
+const PAYLOAD_BUFFER_CAP_BYTES = 200 * 1024 * 1024;
+
+type DeploymentStatus =
+	| 'pending'
+	| 'extracting'
+	| 'installing'
+	| 'loading'
+	| 'replicating'
+	| 'restarting'
+	| 'success'
+	| 'failed'
+	| 'rolled_back';
+
+interface CreateOptions {
+	project?: string;
+	package_identifier?: string;
+	user?: string;
+	restart_mode?: 'immediate' | 'rolling' | null;
+	rollback_of?: string | null;
+	emitter?: ProgressEmitter;
+}
+
+export class DeploymentRecorder {
+	readonly deploymentId: string;
+	private readonly record: Record<string, any>;
+	private hash: Hash | null = null;
+	private byteCount = 0;
+	private finished = false;
+	private unsubscribe: (() => void) | null = null;
+	private pendingPut: Promise<void> | null = null;
+	private dirty = false;
+
+	private constructor(deploymentId: string, initial: Record<string, any>) {
+		this.deploymentId = deploymentId;
+		this.record = initial;
+	}
+
+	static async create(options: CreateOptions): Promise<DeploymentRecorder> {
+		const deploymentId = randomUUID();
+		const startedAt = Date.now();
+		const record: Record<string, any> = {
+			deployment_id: deploymentId,
+			project: options.project ?? null,
+			package_identifier: options.package_identifier ?? null,
+			payload_hash: null,
+			payload_size: null,
+			payload_blob: null,
+			status: 'pending' as DeploymentStatus,
+			phase: 'pending',
+			event_log: [],
+			peer_results: [],
+			origin_node: hostname(),
+			restart_mode: options.restart_mode ?? null,
+			started_at: startedAt,
+			completed_at: null,
+			user: options.user ?? null,
+			rollback_of: options.rollback_of ?? null,
+			error: null,
+		};
+		const recorder = new DeploymentRecorder(deploymentId, record);
+		await recorder.put();
+		if (options.emitter) {
+			recorder.subscribeTo(options.emitter);
+			activeEmitters.set(deploymentId, options.emitter);
+		}
+		return recorder;
+	}
+
+	/**
+	 * Subscribe to a ProgressEmitter. Each event is appended (bounded) to event_log; phase
+	 * events also update the row's `status` and `phase` fields. Writes coalesce: a put is
+	 * always pending after the first event in a burst, so chatty install output collapses
+	 * to one row update per ~100ms instead of one per line.
+	 */
+	private subscribeTo(emitter: ProgressEmitter): void {
+		this.unsubscribe = emitter.subscribe((event) => {
+			this.appendEvent(event.event, event.data);
+		});
+	}
+
+	private appendEvent(event: string, data: unknown): void {
+		if (this.finished) return;
+		const log = this.record.event_log as Array<Record<string, unknown>>;
+		log.push({ t: Date.now(), event, data });
+		// Keep the head (lifecycle spine) and tail (most-recent activity); drop the middle.
+		if (log.length > EVENT_LOG_MAX) {
+			const tailKeep = EVENT_LOG_MAX - EVENT_LOG_HEAD_KEEP - 1; // -1 for the truncation marker
+			const removedCount = log.length - EVENT_LOG_HEAD_KEEP - tailKeep;
+			log.splice(EVENT_LOG_HEAD_KEEP, log.length - EVENT_LOG_HEAD_KEEP - tailKeep, {
+				t: Date.now(),
+				event: 'truncated',
+				data: { dropped_events: removedCount },
+			});
+		}
+		// Phase events drive the canonical status/phase fields used by list_deployments.
+		if (event === 'phase' && data && typeof data === 'object') {
+			const p = data as { phase?: string; status?: string };
+			if (p.phase) this.record.phase = p.phase;
+			if (p.status === 'start') {
+				const mapped = startStatusFor(p.phase);
+				if (mapped) this.record.status = mapped;
+			}
+		}
+		this.scheduleFlush();
+	}
+
+	// Coalesce writes: at most one in-flight put at a time. While a put is running, mark
+	// the record dirty; the chained continuation issues a follow-up put once the prior one
+	// settles. This keeps event_log writes O(1) puts per burst rather than O(N) per event.
+	private scheduleFlush(): void {
+		if (this.pendingPut) {
+			this.dirty = true;
+			return;
+		}
+		this.pendingPut = this.put().finally(() => {
+			this.pendingPut = null;
+			if (this.dirty) {
+				this.dirty = false;
+				this.scheduleFlush();
+			}
+		});
+	}
+
+	/**
+	 * Drain a payload source (Buffer or Readable) into the row's payload_blob attribute,
+	 * computing sha256 and byte count alongside. After this resolves the row has been
+	 * committed once with the final hash and size, and `this.row.payload_blob.stream()`
+	 * yields a fresh Readable that callers can pass to extraction.
+	 *
+	 * Buffers the payload in memory (subject to PAYLOAD_BUFFER_CAP_BYTES) so the
+	 * hash/size are known synchronously before we commit and so the blob's `saveBlob`
+	 * lifecycle doesn't race with our digest() call. A streaming variant is a planned
+	 * follow-up that uses the unused `hash`/`byteCount` instance fields below.
+	 */
+	async ingestPayload(source: Readable | Buffer | string): Promise<void> {
+		const hash = createHash('sha256');
+		let byteCount = 0;
+		let buffer: Buffer;
+		if (Buffer.isBuffer(source)) {
+			buffer = source;
+		} else if (typeof source === 'string') {
+			// Legacy CBOR/JSON path: payload arrives as a base64-encoded string.
+			buffer = Buffer.from(source, 'base64');
+		} else {
+			const chunks: Buffer[] = [];
+			let collected = 0;
+			for await (const chunk of source as AsyncIterable<Buffer | string>) {
+				const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as any);
+				collected += buf.length;
+				if (collected > PAYLOAD_BUFFER_CAP_BYTES) {
+					(source as Readable).destroy?.();
+					throw new ClientError(
+						`Deploy payload exceeds the ${PAYLOAD_BUFFER_CAP_BYTES} byte buffer cap. ` +
+							`Use a package identifier (npm:/file:/git:) for larger components.`
+					);
+				}
+				chunks.push(buf);
+			}
+			buffer = Buffer.concat(chunks);
+		}
+		if (buffer.length > PAYLOAD_BUFFER_CAP_BYTES) {
+			throw new ClientError(
+				`Deploy payload (${buffer.length} bytes) exceeds the ${PAYLOAD_BUFFER_CAP_BYTES} byte buffer cap. ` +
+					`Use a package identifier (npm:/file:/git:) for larger components.`
+			);
+		}
+		hash.update(buffer);
+		byteCount = buffer.length;
+		this.record.payload_blob = createBlob(buffer, { type: 'application/gzip' });
+		this.record.payload_hash = hash.digest('hex');
+		this.record.payload_size = byteCount;
+		// Touch the unused private fields so the type system stays happy when a streaming
+		// variant lands that uses them.
+		this.hash = hash;
+		this.byteCount = byteCount;
+		await this.put();
+	}
+
+	async transitionPhase(phase: string, status?: DeploymentStatus): Promise<void> {
+		this.record.phase = phase;
+		if (status) this.record.status = status;
+		await this.put();
+	}
+
+	/**
+	 * Upsert a single peer outcome by node name. Called per-peer as each replication
+	 * target settles, so the row reflects in-flight progress rather than only the
+	 * final aggregate. Routes through `scheduleFlush()` so the write coalesces with
+	 * the emitter-driven puts and the latest in-memory state always wins.
+	 *
+	 * Tolerates unknown shapes — anything we can't interpret becomes a plain
+	 * stringified entry so the audit trail at least records that a peer was contacted.
+	 */
+	recordPeer(result: unknown): void {
+		if (this.finished) return;
+		const normalized = normalizePeerResult(result);
+		// Defensive: rows freshly created via create() always have peer_results=[], but if
+		// a replicated row was loaded back where the attribute is absent or null we want
+		// to initialize lazily rather than throw on `.findIndex`.
+		if (!Array.isArray(this.record.peer_results)) this.record.peer_results = [];
+		const list = this.record.peer_results as Array<Record<string, unknown>>;
+		// Upsert by node name when present; otherwise append (we can't dedupe without an id).
+		const nodeName = normalized.node;
+		const idx = nodeName ? list.findIndex((entry) => entry.node === nodeName) : -1;
+		if (idx >= 0) {
+			list[idx] = normalized;
+		} else {
+			list.push(normalized);
+		}
+		this.scheduleFlush();
+	}
+
+	/**
+	 * Bulk-record a final aggregate of peer outcomes. Equivalent to calling recordPeer()
+	 * for each entry. Useful for replication layers that surface results all-at-once
+	 * via Promise.allSettled rather than via a per-peer callback.
+	 */
+	recordPeers(results: unknown): void {
+		if (this.finished) return;
+		if (!Array.isArray(results)) return;
+		for (const result of results) this.recordPeer(result);
+	}
+
+	async finish(status: 'success' | 'failed' | 'rolled_back', error?: unknown): Promise<void> {
+		if (this.finished) return;
+		// Send a terminal sentinel through the emitter (if any) BEFORE we unsubscribe and
+		// remove it from the registry, so any SSE tail subscribers can resolve their wait
+		// even on a code path that doesn't emit an explicit `error` event.
+		const emitter = activeEmitters.get(this.deploymentId);
+		emitter?.emit('_recorder_finished', { status });
+		this.finished = true;
+		this.unsubscribe?.();
+		this.unsubscribe = null;
+		activeEmitters.delete(this.deploymentId);
+		// Drain the ENTIRE coalesced-flush chain before mutating + persisting the terminal
+		// state. Just awaiting `this.pendingPut` once isn't enough: its `.finally` may
+		// re-schedule another put (when `dirty` was set during the in-flight put), and
+		// that re-scheduled put captures a pre-mutation snapshot of the record. Without
+		// this loop, the re-scheduled put can complete AFTER our terminal put and
+		// overwrite status=success with stale state.
+		while (this.pendingPut) {
+			try {
+				await this.pendingPut;
+			} catch {
+				/* the next put surfaces the error */
+			}
+		}
+		this.record.status = status;
+		this.record.completed_at = Date.now();
+		if (error) {
+			const e = error as { message?: string; code?: string | number; stack?: string };
+			this.record.error = {
+				message: e?.message ?? String(error),
+				code: e?.code,
+				phase: this.record.phase,
+			};
+		}
+		await this.put();
+	}
+
+	get row(): Record<string, any> {
+		return this.record;
+	}
+
+	private async put(): Promise<void> {
+		const table = (databases as any).system?.[terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME];
+		if (!table) {
+			// Table missing means the upgrade directive hasn't run yet (or the table got dropped).
+			// We tolerate this — tracking is observability; the deploy itself must still succeed.
+			return;
+		}
+		await table.put(this.record);
+	}
+}
+
+/**
+ * Peer-side helper — wait for the hdb_deployment row to arrive via table replication,
+ * then return it. The row is committed on origin before `replicateOperation` is
+ * called, so peers normally find it immediately; this polling loop is for the rare
+ * case where the operation arrives faster than the table-replication channel.
+ *
+ * The payload_blob's chunks may still be in flight after the row arrives — that's
+ * fine, the Blob's `stream()` / `bytes()` API blocks on incomplete writes
+ * (resources/blob.ts).
+ */
+export async function awaitDeploymentRow(
+	deploymentId: string,
+	options: { timeoutMs?: number; pollIntervalMs?: number; initialPollIntervalMs?: number } = {}
+): Promise<Record<string, any>> {
+	const timeoutMs = options.timeoutMs ?? 30_000;
+	const maxIntervalMs = options.pollIntervalMs ?? 100;
+	// Start fast (5ms) so the common case — replication has already caught up — sees no
+	// human-noticeable latency, then back off exponentially up to maxIntervalMs for the
+	// rare case where the row is genuinely still replicating.
+	let intervalMs = options.initialPollIntervalMs ?? 5;
+	const table = (databases as any).system?.[terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME];
+	if (!table) {
+		throw new Error(
+			`Deployment tracking is not initialized on this node (system.${terms.SYSTEM_TABLE_NAMES.DEPLOYMENT_TABLE_NAME} missing).`
+		);
+	}
+	const deadline = Date.now() + timeoutMs;
+	let lastError: unknown;
+	while (Date.now() < deadline) {
+		try {
+			const row = await table.get(deploymentId);
+			if (row && row.payload_blob != null) return row;
+		} catch (err) {
+			lastError = err;
+		}
+		await new Promise<void>((resolve) => setTimeout(resolve, intervalMs));
+		intervalMs = Math.min(intervalMs * 2, maxIntervalMs);
+	}
+	throw new Error(
+		`Timed out after ${timeoutMs}ms waiting for hdb_deployment row '${deploymentId}' to replicate` +
+			(lastError ? ` (last error: ${(lastError as Error).message ?? lastError})` : '')
+	);
+}
+
+function normalizePeerResult(raw: unknown): Record<string, unknown> {
+	if (!raw || typeof raw !== 'object') {
+		// Replication layer returned a primitive — preserve as a stringified marker so the
+		// audit row at least records that something came back from a peer.
+		return { node: null, status: 'unknown', raw: String(raw) };
+	}
+	const r = raw as Record<string, unknown>;
+	const err = r.error;
+	const hasError =
+		err != null && (typeof err === 'string' ? err.length > 0 : typeof err === 'object' || typeof err === 'number');
+	return {
+		node: r.node ?? r.name ?? r.hostname ?? null,
+		status: hasError ? 'failed' : (r.status ?? 'success'),
+		error: hasError
+			? {
+					message: typeof err === 'object' ? ((err as any).message ?? String(err)) : String(err),
+					code: typeof err === 'object' ? (err as any).code : undefined,
+				}
+			: null,
+		started_at: r.started_at ?? null,
+		completed_at: r.completed_at ?? null,
+	};
+}
+
+function startStatusFor(phase: string | undefined): DeploymentStatus | null {
+	switch (phase) {
+		case 'extract':
+			return 'extracting';
+		case 'install':
+			return 'installing';
+		case 'load':
+			return 'loading';
+		case 'replicate':
+			return 'replicating';
+		case 'restart':
+			return 'restarting';
+		default:
+			return null;
+	}
+}

package/components/deriveURLPath.ts

@@ -1,6 +1,5 @@
-import { join } from 'node:path';
-import type { Component } from './Component.js';
-import type { ComponentV1 } from './ComponentV1.js';
+import type { Component } from './Component.ts';
+import type { ComponentV1 } from './ComponentV1.ts';
 
 function pathStartsWithBase(base: string, path: string) {
 	const re = new RegExp(`^${base}(/|$)`);
@@ -8,6 +7,7 @@ function pathStartsWithBase(base: string, path: string) {
 }
 
 export function deriveURLPath(component: Component | ComponentV1, path: string, type: 'file' | 'directory'): string {
+	path = path.replace(/\\/g, '/'); // converting from potential windows path to URL paths
 	if (path.startsWith('./')) {
 		path = path.slice(2); // remove leading './'
 	}
@@ -53,5 +53,5 @@ export function deriveURLPath(component: Component | ComponentV1, path: string,
 		}
 	}
 
-	return join(component.baseURLPath, path);
+	return component.baseURLPath + path; // note, do NOT use join here, this is not a file system path, this is a URL path
 }

package/components/mcp/adapters/fastify.ts

@@ -0,0 +1,87 @@
+/**
+ * Fastify adapter for the MCP transport core (operations port, #614).
+ *
+ * Maps Fastify's `(request, reply)` ↔ the transport's normalized
+ * Request/Response shape. The route is registered with the
+ * `authAndEnsureUserOnRequest` preValidation hook, so the authenticated
+ * user lands on `request.hdb_user` before this handler runs.
+ *
+ * Fastify auto-parses JSON request bodies; we re-stringify so the core's
+ * `parseMessage` sees the raw envelope it expects. The round-trip is
+ * cheap for the small JSON-RPC frames in the MCP wire format and keeps
+ * the core framework-agnostic.
+ */
+import { handleMcpRequest, type McpProfile, type NormRequest } from '../transport.ts';
+
+interface FastifyLikeRequest {
+	method: string;
+	headers: Record<string, string | string[] | undefined>;
+	body: unknown;
+	/**
+	 * `authAndEnsureUserOnRequest` sets the full user (incl. role + permission
+	 * tree) on `req.hdb_user`. Used for session binding (`username`) and
+	 * forwarded as the transport's `userObject` for resource/tool RBAC.
+	 */
+	hdb_user?: { username?: string; role?: unknown } | null;
+}
+
+interface FastifyLikeReply {
+	code: (status: number) => FastifyLikeReply;
+	header: (name: string, value: string) => FastifyLikeReply;
+	send: (body?: unknown) => unknown;
+}
+
+export function createFastifyHandler(profile: McpProfile) {
+	return async function mcpFastifyHandler(request: FastifyLikeRequest, reply: FastifyLikeReply): Promise<void> {
+		const norm: NormRequest = {
+			method: request.method,
+			headers: normalizeHeaders(request.headers),
+			// Fastify has already parsed the JSON body into an object via its
+			// preParsing pipeline. Pass it through directly — the transport
+			// core's parseMessage accepts both strings and parsed values, so we
+			// avoid an unnecessary stringify/re-parse round trip on the hot path.
+			body: request.body,
+			user: request.hdb_user?.username ?? '',
+			userObject: (request.hdb_user ?? undefined) as NormRequest['userObject'],
+			profile,
+		};
+
+		const res = await handleMcpRequest(norm);
+
+		reply.code(res.status);
+		for (const [name, value] of Object.entries(res.headers)) {
+			reply.header(name, value);
+		}
+
+		if (res.jsonBody !== undefined) {
+			if (!res.headers['Content-Type'] && !res.headers['content-type']) {
+				reply.header('Content-Type', 'application/json');
+			}
+			reply.send(res.jsonBody);
+			return;
+		}
+
+		if (res.sseIterable !== undefined) {
+			// Reserved for #619 (server-push GET stream). Fastify will iterate
+			// the async iterable and write SSE frames via the contentTypes
+			// serializer at `server/serverHelpers/contentTypes.ts:128-162`.
+			if (!res.headers['Content-Type'] && !res.headers['content-type']) {
+				reply.header('Content-Type', 'text/event-stream');
+			}
+			reply.header('Cache-Control', 'no-store');
+			reply.send(res.sseIterable);
+			return;
+		}
+
+		// 202/204/4xx with empty body.
+		reply.send();
+	};
+}
+
+function normalizeHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string | undefined> {
+	const out: Record<string, string | undefined> = {};
+	for (const [name, value] of Object.entries(headers)) {
+		out[name.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+	}
+	return out;
+}

package/components/mcp/adapters/harperHttp.ts

@@ -0,0 +1,103 @@
+/**
+ * Harper-HTTP adapter for the MCP transport core (application port, #614).
+ *
+ * Maps Harper's HTTP handler signature `(request, nextHandler) => { status,
+ * headers, body }` to/from the transport's normalized Request/Response.
+ * Auth runs upstream via `{ after: 'authentication' }` on the registration,
+ * so `request.user` is already populated when this handler fires.
+ *
+ * SSE responses (reserved for #619) are returned as `{ body: iterable,
+ * headers: { 'content-type': 'text/event-stream' } }`. Harper's serializer
+ * at `server/serverHelpers/contentTypes.ts:128-162` picks the SSE writer
+ * automatically and pipes the iterable to the wire.
+ */
+import { handleMcpRequest, type McpProfile, type NormRequest, type NormResponse } from '../transport.ts';
+
+interface HarperHttpRequest {
+	method: string;
+	headers: Iterable<[string, string | string[]]> & { get?: (name: string) => string | undefined };
+	body?: AsyncIterable<Buffer | string>;
+	/**
+	 * Full user object as Harper's auth pipeline attaches it (includes role +
+	 * permission tree). Transport reads `username` for session binding and
+	 * forwards the full object as `userObject` for resource/tool RBAC.
+	 */
+	user?: { username?: string; role?: unknown };
+	isWebSocket?: boolean;
+}
+
+interface HarperHttpResponse {
+	status: number;
+	headers: Record<string, string>;
+	body?: unknown;
+}
+
+export function createHarperHttpHandler(profile: McpProfile) {
+	return async function mcpHarperHttpHandler(
+		request: HarperHttpRequest,
+		nextHandler: (req: HarperHttpRequest) => unknown
+	): Promise<HarperHttpResponse | unknown> {
+		// WebSocket upgrades aren't ours — let the next handler take it.
+		if (request.isWebSocket) return nextHandler(request);
+
+		const norm: NormRequest = {
+			method: request.method,
+			headers: normalizeHeaders(request.headers),
+			body: await readBody(request.body),
+			user: request.user?.username ?? '',
+			userObject: request.user as NormRequest['userObject'],
+			profile,
+		};
+
+		const res = await handleMcpRequest(norm);
+		return toHarperResponse(res);
+	};
+}
+
+function normalizeHeaders(headers: HarperHttpRequest['headers']): Record<string, string | undefined> {
+	const out: Record<string, string | undefined> = {};
+	for (const [name, value] of headers) {
+		out[name.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+	}
+	return out;
+}
+
+async function readBody(body: AsyncIterable<Buffer | string> | undefined): Promise<string> {
+	if (!body) return '';
+	const chunks: Buffer[] = [];
+	for await (const chunk of body) {
+		chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+	}
+	return Buffer.concat(chunks).toString('utf8');
+}
+
+function toHarperResponse(res: NormResponse): HarperHttpResponse {
+	const headers = { ...res.headers };
+
+	if (res.jsonBody !== undefined) {
+		if (!headers['Content-Type'] && !headers['content-type']) {
+			headers['Content-Type'] = 'application/json';
+		}
+		return {
+			status: res.status,
+			headers,
+			body: JSON.stringify(res.jsonBody),
+		};
+	}
+
+	if (res.sseIterable !== undefined) {
+		if (!headers['Content-Type'] && !headers['content-type']) {
+			headers['Content-Type'] = 'text/event-stream';
+		}
+		if (!headers['Cache-Control'] && !headers['cache-control']) {
+			headers['Cache-Control'] = 'no-store';
+		}
+		return {
+			status: res.status,
+			headers,
+			body: res.sseIterable,
+		};
+	}
+
+	return { status: res.status, headers };
+}

package/components/mcp/audit.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-`tools/call` audit logging. Emits a structured info-level log entry
+ * for every tool invocation so operators can replay who-did-what after the
+ * fact. The shape mirrors what Harper's existing operations audit captures
+ * (operation, user, status, duration) plus MCP-specific identity
+ * (session id, profile, tool name).
+ *
+ * Argument summarization runs through a redaction step that drops anything
+ * that looks like a credential (key/secret/password). Operators who need
+ * stricter PII handling configure `mcp.audit.argumentRedactor` to a custom
+ * function via a future component-author hook (v1.1).
+ */
+import harperLogger from '../../utility/logging/harper_logger.ts';
+
+export interface AuditEntry {
+	timestamp: string;
+	profile: 'operations' | 'application';
+	sessionId: string;
+	tool: string;
+	user: string;
+	args: object;
+	status: 'ok' | 'isError' | 'rate_limited' | 'protocol_error';
+	durationMs: number;
+	errorMessage?: string;
+}
+
+const REDACTION_PATTERN = /(secret|password|token|api[-_]?key|credentials?|auth)/i;
+const REDACTION_PLACEHOLDER = '[redacted]';
+const MAX_REDACTION_DEPTH = 10;
+
+/**
+ * Recursively walk an object and replace values for keys matching the
+ * redaction pattern. Bounded depth so a pathological cyclic input doesn't
+ * stall the audit emit; on overflow the entire sub-object is redacted so
+ * a credential buried below the depth limit cannot leak. Returns a shallow
+ * clone — the caller's payload is never mutated.
+ */
+export function redactArgs(value: unknown, depth = 0): unknown {
+	if (value === null || typeof value !== 'object') return value;
+	if (depth > MAX_REDACTION_DEPTH) return REDACTION_PLACEHOLDER;
+	if (Array.isArray(value)) {
+		return value.map((v) => redactArgs(v, depth + 1));
+	}
+	const out: Record<string, unknown> = {};
+	for (const [k, v] of Object.entries(value)) {
+		if (REDACTION_PATTERN.test(k)) {
+			out[k] = REDACTION_PLACEHOLDER;
+		} else {
+			out[k] = redactArgs(v, depth + 1);
+		}
+	}
+	return out;
+}
+
+/** Mask a session id for logging — first 8 chars, suffix elided. */
+export function maskSessionId(id: string): string {
+	if (typeof id !== 'string' || id.length <= 8) return id;
+	return `${id.slice(0, 8)}…`;
+}
+
+/**
+ * Emit a single audit entry. Writes to the structured log channel as INFO
+ * so it's captured by Harper's standard log rotation; downstream tooling
+ * can filter on `category: 'mcp.audit'`.
+ */
+export function emitAuditEntry(entry: AuditEntry): void {
+	try {
+		const masked = { ...entry, sessionId: maskSessionId(entry.sessionId), args: redactArgs(entry.args) };
+		harperLogger.info({ category: 'mcp.audit', ...masked });
+	} catch (err) {
+		// Audit emission must never break a tool call. If logging itself fails
+		// (logger disposed, disk full, whatever), trace-log the loss and move on.
+		harperLogger.trace(`MCP audit emit failed: ${(err as Error).message}`);
+	}
+}