@harperfast/harper 5.2.0 → 5.2.2

package/resources/jsResource.ts

@@ -69,41 +69,13 @@ export class ResourceLoadError extends Error {
  *
  * Once a file has been loaded it cannot be unloaded without a restart.
  *
- * Thus, this plugin only handle files as they are added (`add` event). All other events result in a restart request.
+ * Thus, this plugin only handles files as they are added (`add` event). All other events result in a restart request.
  *
- * A redeploy tears down and reinstalls the component's files while this scope's watcher is paused
- * (see `Scope`/`EntryHandler` deploy lifecycle); on resume the fresh chokidar scan re-emits every
- * existing file as `'add'` — including ones whose contents just changed. Treating those as plain
- * adds would silently re-run against the stale module cache and never flag a restart (harper#1817).
- * So we track which files this scope has already loaded: a re-`add` of a known file is a redeploy of
- * loaded code we cannot hot-swap, and is handled like a `change` — request a restart. A first-time
- * `add` (initial load, or a genuinely new file added at runtime) still loads without a restart.
- *
- * A redeploy that *deletes* a loaded file is a different shape of the same problem: the fresh
- * chokidar scan only reports what's currently on disk, so a file that's gone produces no event at
- * all — no re-`add`, no `unlink` — and the modified-file handling above never sees it. Left
- * unhandled, the deleted resource stays registered and active in memory (harper#1817 follow-up). So
- * we also track which files the post-redeploy scan pass reports, and once that scan's `ready` fires,
- * diff it against everything this scope has ever loaded: anything missing was deleted, and is
- * handled the same way as a modified file — request a restart.
- *
- * That diff must only run for an actual redeploy rescan, not every time `EntryHandler` emits
- * `ready` — it also refires after each ordinary runtime add/change once that file's read settles
- * (its initial-scan-complete latch never resets outside a full rescan), and diffing against that
- * would falsely treat every other already-loaded file as deleted. So the diff window is gated by
- * the scope's own `deploy:start`/`deploy:end` bracket (see `Scope`): `deploy:start` pauses the
- * watcher and opens the window (and is where we reset the scan-file tracking, since no file events
- * can land while paused), and the first `ready` afterward — the resumed watcher's fresh scan
- * completing — closes it and runs the diff.
+ * EntryHandler preserves file identity across a deploy pause/resume and emits `change` or `unlink`
+ * for loaded files that changed or disappeared, so those events request the required restart.
  */
 export async function handleApplication(scope: Scope) {
-	const loadedResourceFiles = new Set<string>();
-	// Files reported as `add` since the most recent `deploy:start`, populated only while
-	// `awaitingPostRedeployScan` is true — see the gating note above.
-	let currentScanFiles = new Set<string>();
-	let awaitingPostRedeployScan = false;
-
-	const entryHandler = scope.handleEntry(async function handleResourceEntry(entryEvent) {
+	scope.handleEntry(async function handleResourceEntry(entryEvent) {
 		if (entryEvent.entryType !== 'file') {
 			scope.logger.warn(
 				`jsResource plugin cannot handle entry type ${entryEvent.entryType}. Modify the 'files' option in ${scope.configFilePath} to only include files.`
@@ -111,13 +83,7 @@ export async function handleApplication(scope: Scope) {
 			return;
 		}
 
-		if (awaitingPostRedeployScan && entryEvent.eventType === 'add') {
-			// Recorded unconditionally — before the loaded/re-add branch below — so the post-scan
-			// deletion diff sees every file this scan reported, whether newly loaded or already known.
-			currentScanFiles.add(entryEvent.absolutePath);
-		}
-
-		if (entryEvent.eventType !== 'add' || loadedResourceFiles.has(entryEvent.absolutePath)) {
+		if (entryEvent.eventType !== 'add') {
 			scope.requestRestart();
 			return;
 		}
@@ -133,9 +99,6 @@ export async function handleApplication(scope: Scope) {
 				scope.logger.debug?.(`Registered root resource: ${path}`);
 			}
 			recurseForResources(scope, resourceModule, root);
-			// Record the load so a later re-`add` of this same file (a redeploy re-scan) is treated
-			// as a change and requests a restart rather than silently re-serving stale cached code.
-			loadedResourceFiles.add(entryEvent.absolutePath);
 			// A JS resource that extends an exported @table is the one carrying author opt-ins
 			// (`static mcpTools`/`mcpPrompts`), and it registers here — after the schema-derived
 			// table class and after the MCP component's boot scan. Signal so listing surfaces
@@ -146,26 +109,6 @@ export async function handleApplication(scope: Scope) {
 			throw new ResourceLoadError(entryEvent.absolutePath, error);
 		}
 	});
-
-	// Optional chaining: a mock/test scope may not implement EventEmitter, and Scope#handleEntry
-	// itself can return undefined (e.g. MissingDefaultFilesOptionError). In real use `scope` is
-	// always an EventEmitter and `entryHandler` is always the EntryHandler backing this watcher.
-	scope.on?.('deploy:start', () => {
-		awaitingPostRedeployScan = true;
-		currentScanFiles = new Set();
-	});
-
-	entryHandler?.on?.('ready', () => {
-		if (!awaitingPostRedeployScan) return;
-		awaitingPostRedeployScan = false;
-		for (const loadedFile of loadedResourceFiles) {
-			if (!currentScanFiles.has(loadedFile)) {
-				// Known file that the just-completed scan never reported — deleted during the redeploy.
-				loadedResourceFiles.delete(loadedFile);
-				scope.requestRestart();
-			}
-		}
-	});
 }
 
 function recurseForResources(scope: Scope, resourceModule: any, prefix: string) {

package/resources/models/Models.ts

@@ -91,6 +91,19 @@ export class Models implements ModelsContract {
 	}
 
 	async embed(input: string | string[], opts: EmbedOpts = {}): Promise<Float32Array[]> {
+		return (await this.embedWithUsage(input, opts)).vectors;
+	}
+
+	/**
+	 * `embed()` plus the result-level `usage` the winning backend reported (all
+	 * built-in embedding backends provide it). Internal path for callers that must
+	 * surface usage on the wire — the `/v1/embeddings` gateway — without changing
+	 * the public `embed()` contract. Not part of the stable models API.
+	 */
+	async embedWithUsage(
+		input: string | string[],
+		opts: EmbedOpts = {}
+	): Promise<{ vectors: Float32Array[]; usage?: TokenUsage }> {
 		const { accounting, signal } = resolveCallContext(opts.signal);
 		const startedAt = performance.now();
 		const resolved = resolveCandidates('embedding', opts.model, buildRequires('embed', opts.requires, false));
@@ -118,7 +131,7 @@ export class Models implements ModelsContract {
 				// success row followed by a failure row from the catch (duplicate).
 				if (result.status !== 'completed') throw new ModelPendingNotSupportedError(backend.name);
 				this.#record(backend, 'embed', opts.model, accounting, undefined, result, attemptStart);
-				return result.output;
+				return { vectors: result.output, usage: result.usage };
 			} catch (err) {
 				this.#recordFailure(backend, 'embed', opts.model, accounting, undefined, attemptStart, err);
 				if (!hasError) {

package/resources/models/backendRegistry.ts

@@ -39,6 +39,16 @@ export function getBackend(kind: ModelKind, logicalName: string): ModelBackend |
 	return (kind === 'embedding' ? embedding : generative).get(logicalName);
 }
 
+/**
+ * Enumerate all registrations for `kind` as `{logicalName, backend}` pairs. Used by
+ * `GET /v1/models` (#631) to advertise selectable model names; `logicalName` is what a
+ * caller passes as `opts.model`, not the backend's own `.name`.
+ */
+export function listBackends(kind: ModelKind): Array<{ logicalName: string; backend: ModelBackend }> {
+	const map = kind === 'embedding' ? embedding : generative;
+	return [...map.entries()].map(([logicalName, backend]) => ({ logicalName, backend }));
+}
+
 /**
  * Resolve the embedding backend mapped to `logicalName` (default: `'default'`).
  * Throws `ModelBackendNotFoundError` if no backend is mapped.

package/resources/models/openaiStream.ts

@@ -21,6 +21,68 @@ export interface OpenAIStreamOptions {
 	model?: string;
 	/** Reuse a caller-supplied completion id across all chunks; one is generated when omitted. */
 	id?: string;
+	/**
+	 * Map a mid-stream backend error to an OpenAI error body for a final `data: {error}`
+	 * SSE frame. Lets the v1 gateway reuse its `toOpenAIError` mapping without this generic
+	 * formatter depending on the v1 layer. When omitted, a generic server_error body is emitted.
+	 */
+	formatError?: (err: unknown) => OpenAIErrorFrameBody;
+}
+
+// Bounds on per-stream tool-call assembly. The backend supplies both the call ids and the
+// argument fields, and this runs on a public HTTP path, so neither can be unbounded. Overflow
+// terminates the stream through the same sanitized error-frame path as any backend failure.
+const MAX_TOOL_CALLS_PER_STREAM = 256;
+const MAX_TOOL_ARGUMENT_KEYS = 1024;
+// Cumulative serialized-character budget across the WHOLE stream's assembly (ids, names,
+// and every argument value as it arrives, plus per-entry JSON syntax so the count is an
+// upper bound on `JSON.stringify(arguments)`, not just the raw content). Call/key counts
+// alone don't bound memory — one key can hold an arbitrarily large value, and the final
+// JSON.stringify duplicates the retained allocation — so the budget is charged per delta
+// (O(delta), no re-serialization of the accumulator) and monotonically: replacing an
+// existing key charges the new value too, so churn cannot smuggle unbounded values under
+// a stable key count. The SSE frame that flushes the calls adds only a bounded constant
+// envelope per call plus string-escaping of the arguments blob (< 2x), so the frame size
+// is bounded by a small multiple of this budget.
+const MAX_TOOL_ASSEMBLY_CHARS = 1_048_576;
+
+/** Signals that a stream exceeded the tool-assembly bounds; surfaced as an SSE error frame. */
+class ToolAssemblyOverflowError extends Error {
+	statusCode = 502;
+}
+
+/**
+ * Merge `source` into `target`, returning the keys added and the serialized characters
+ * charged. Charging over-approximates `JSON.stringify(target).length`: each first add
+ * charges the key plus 4 chars of JSON syntax (`"key":` quotes and colon, plus the
+ * comma/brace share), and every assignment — replacements included — charges the
+ * serialized value. Since a replacement's earlier charge is never refunded, the
+ * cumulative total stays an upper bound on the retained serialization while keeping
+ * accumulation O(delta), not O(total).
+ */
+function assignCountingNewKeys(target: object, source: object): { addedKeys: number; addedChars: number } {
+	let addedKeys = 0;
+	let addedChars = 0;
+	for (const key in source) {
+		if (!(key in target)) {
+			addedKeys++;
+			addedChars += key.length + 4;
+		}
+		const value = (source as Record<string, unknown>)[key];
+		// `?? ''`: JSON.stringify returns undefined for undefined/function/symbol values —
+		// impossible from JSON.parse but reachable from a custom backend's crafted object.
+		addedChars += (JSON.stringify(value) ?? '').length;
+		(target as Record<string, unknown>)[key] = value;
+	}
+	return { addedKeys, addedChars };
+}
+
+/** OpenAI streaming error body (`{ message, type, code, param }` under an `error` key). */
+export interface OpenAIErrorFrameBody {
+	message: string;
+	type: string;
+	code: string | null;
+	param: string | null;
 }
 
 interface OpenAIToolCallDelta {
@@ -46,7 +108,7 @@ interface OpenAIChunk {
 
 /** SSE message envelope consumed by Harper's `text/event-stream` serializer. */
 export interface OpenAIStreamMessage {
-	data: OpenAIChunk | string;
+	data: OpenAIChunk | { error: OpenAIErrorFrameBody } | string;
 }
 
 /**
@@ -71,7 +133,8 @@ export async function* openaiStream(
 	// Emitting incremental fragments would corrupt the OpenAI client's concatenation
 	// (`{"a":1}` + `{"b":2}` → invalid JSON) — Harper's already-buffered upstream model
 	// means we cannot faithfully reproduce per-token argument fragments anyway.
-	const toolAssembly = new Map<string, { index: number; name?: string; arguments: object }>();
+	const toolAssembly = new Map<string, { index: number; name?: string; arguments: object; argumentCount: number }>();
+	let assemblyChars = 0;
 
 	const chunk = (delta: OpenAIDelta, finish: OpenAIFinishReason | null): OpenAIStreamMessage => ({
 		data: {
@@ -83,26 +146,75 @@ export async function* openaiStream(
 		},
 	});
 
-	for await (const token of tokens) {
-		if (token.deltaContent !== undefined) {
-			const delta: OpenAIDelta = {};
-			if (!roleSent) {
-				delta.role = 'assistant';
-				roleSent = true;
+	try {
+		for await (const token of tokens) {
+			if (token.deltaContent !== undefined) {
+				const delta: OpenAIDelta = {};
+				if (!roleSent) {
+					delta.role = 'assistant';
+					roleSent = true;
+				}
+				delta.content = token.deltaContent;
+				yield chunk(delta, null);
 			}
-			delta.content = token.deltaContent;
-			yield chunk(delta, null);
-		}
-		if (token.deltaToolCalls) {
-			for (const incoming of token.deltaToolCalls) {
-				if (!incoming.id) continue;
-				const existing = toolAssembly.get(incoming.id) ?? { index: toolAssembly.size, arguments: {} };
-				if (incoming.name) existing.name = incoming.name;
-				if (incoming.arguments) existing.arguments = { ...existing.arguments, ...incoming.arguments };
-				toolAssembly.set(incoming.id, existing);
+			if (token.deltaToolCalls) {
+				for (const incoming of token.deltaToolCalls) {
+					if (!incoming.id) continue;
+					let existing = toolAssembly.get(incoming.id);
+					if (!existing) {
+						// Cap distinct calls per stream: ids come from the backend, and an
+						// unbounded map on a public HTTP path is a memory risk.
+						if (toolAssembly.size >= MAX_TOOL_CALLS_PER_STREAM) {
+							throw new ToolAssemblyOverflowError(`stream exceeded ${MAX_TOOL_CALLS_PER_STREAM} tool calls`);
+						}
+						// Null-prototype: arguments come from JSON.parse, so a field literally
+						// named `__proto__` is an own property. Object.assign uses [[Set]], which
+						// on an ordinary object would hit Object.prototype's inherited `__proto__`
+						// setter and silently drop the field (the previous spread did not).
+						existing = { index: toolAssembly.size, arguments: Object.create(null), argumentCount: 0 };
+						toolAssembly.set(incoming.id, existing);
+						// + 96: the flush frame's fixed per-call envelope (index/id/type/function
+						// syntax and the argument object's braces), so 256 calls of envelope are
+						// inside the budget too, not on top of it.
+						assemblyChars += incoming.id.length + 96;
+					}
+					if (incoming.name && incoming.name !== existing.name) {
+						assemblyChars += incoming.name.length;
+						existing.name = incoming.name;
+					}
+					// Guard the contract (`ToolCall.arguments` is an object): a string would be
+					// assigned index-wise, inflating the field count from characters.
+					if (incoming.arguments && typeof incoming.arguments === 'object') {
+						// Mutate rather than re-spread — spreading copied every previously
+						// accumulated property on each partial delta (O(n²) as fields grow) — and
+						// count only newly-introduced keys so the bound check stays O(delta) too.
+						const { addedKeys, addedChars } = assignCountingNewKeys(existing.arguments, incoming.arguments);
+						existing.argumentCount += addedKeys;
+						assemblyChars += addedChars;
+						if (existing.argumentCount > MAX_TOOL_ARGUMENT_KEYS) {
+							throw new ToolAssemblyOverflowError(`tool call arguments exceeded ${MAX_TOOL_ARGUMENT_KEYS} fields`);
+						}
+					}
+					if (assemblyChars > MAX_TOOL_ASSEMBLY_CHARS) {
+						throw new ToolAssemblyOverflowError(
+							`stream tool-call assembly exceeded ${MAX_TOOL_ASSEMBLY_CHARS} serialized characters`
+						);
+					}
+				}
 			}
+			if (token.finishReason) finishReason = token.finishReason;
 		}
-		if (token.finishReason) finishReason = token.finishReason;
+	} catch (err) {
+		// The backend can throw partway through the stream (Models#wrapStream re-throws
+		// mid-stream backend errors). Headers/200 are already flushed, so this can't be an
+		// HTTP error status — emit a final OpenAI-shaped `data: {error}` frame so SDK clients
+		// see a parseable error (matching the non-streaming path) instead of an abrupt socket
+		// close. OpenAI terminates the stream on error and sends no `[DONE]`, so we do the same.
+		const error = opts.formatError
+			? opts.formatError(err)
+			: { message: 'Internal server error', type: 'server_error', code: null, param: null };
+		yield { data: { error } };
+		return;
 	}
 
 	if (toolAssembly.size > 0) {

package/resources/models/v1/chatCompletions.ts

@@ -0,0 +1,128 @@
+/**
+ * `POST /v1/chat/completions` — OpenAI-compatible chat endpoint (#631).
+ *
+ * SSE serving-path note: the OpenAI SDK sends `Accept: application/json` for
+ * ALL requests including streaming ones (`client.ts:1160` in the SDK source).
+ * Harper's REST layer dispatches `Accept: text/event-stream` as CONNECT, and
+ * everything else as the HTTP method. So `stream: true` from an OpenAI SDK
+ * client reaches this `post()` handler, NOT `connect()`. We detect the `stream`
+ * flag in the body and return `{ body: Readable }` which REST.ts bypasses
+ * serialisation on (REST.ts:165-193) — exactly like any SSE resource response,
+ * but initiated from `post()` rather than `connect()`.
+ */
+
+import type { Readable } from 'node:stream';
+import { contentTypes } from '../../../server/serverHelpers/contentTypes.ts';
+import { Resource } from '../../Resource.ts';
+import { models } from '../Models.ts';
+import { openaiStream } from '../openaiStream.ts';
+import { toOpenAIError, badRequest, authorizeV1Request } from './errors.ts';
+import {
+	translateMessages,
+	translateTools,
+	toGenerateInput,
+	toGenerateOpts,
+	toChatCompletion,
+	validateChatRequest,
+} from './translation.ts';
+import type { OAIChatRequest } from './translation.ts';
+
+type SseHandler = { serializeStream: (iterable: AsyncIterable<unknown>) => Readable };
+const sseHandler = contentTypes.get('text/event-stream') as SseHandler;
+
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+export class V1ChatCompletions extends Resource {
+	// Reserve this fixed route: a later app registration at the same path becomes a
+	// loud conflict (ErrorResource) instead of silently replacing the gateway and its
+	// super_user gate. See Resources.set.
+	static reservedPath = true;
+
+	static async post(_target: unknown, body: unknown, request: unknown) {
+		const authError = authorizeV1Request(request as any);
+		if (authError) return authError;
+
+		// REST.ts passes `request.data` directly, which is the (unawaited) streaming
+		// JSON deserializer's Promise — awaiting here is a no-op for callers (e.g.
+		// unit tests) that already pass a plain object. A malformed JSON body rejects
+		// this promise, which is a client error, not a 500.
+		try {
+			body = await body;
+		} catch (err) {
+			return badRequest(`Could not parse request body: ${err instanceof Error ? err.message : 'invalid JSON'}`);
+		}
+		if (!body || typeof body !== 'object' || Array.isArray(body)) {
+			return badRequest('Request body must be a JSON object');
+		}
+		const req = body as OAIChatRequest;
+
+		// Validate the nested wire shapes before mapping: the mappers assume well-formed
+		// input, so an unvalidated `messages:[null]` / `tools:[{}]` would throw a TypeError
+		// and surface as an RFC 9457 500 instead of an OpenAI 400.
+		const invalid = validateChatRequest(req);
+		if (invalid) return badRequest(invalid);
+
+		const model = typeof req.model === 'string' ? req.model : 'default';
+
+		try {
+			const messages = translateMessages(req.messages);
+			// tool_choice: 'none' means "do not call tools" — the only faithful way to honor
+			// that against a returns-tool-calls backend is to not offer the tools at all.
+			// 'required'/named selection are rejected in validateChatRequest.
+			const tools = req.tool_choice === 'none' || !req.tools?.length ? undefined : translateTools(req.tools);
+			const input = toGenerateInput(messages, tools);
+			const opts = toGenerateOpts(req);
+			if (req.stream) {
+				const tokenStream = models.generateStream(input, opts);
+				// serializeStream wraps the async iterable in a Node Readable so REST.ts
+				// can return it without re-serialising. The `body` presence on the return
+				// value skips REST.ts's own serialize() call (REST.ts:165-193).
+				// formatError reuses the non-streaming error mapping so a mid-stream backend
+				// failure reaches the client as an OpenAI-shaped SSE error frame.
+				const readable = sseHandler.serializeStream(
+					openaiStream(tokenStream, { model, formatError: (err) => toOpenAIError(err).data.error })
+				);
+				return {
+					status: 200,
+					headers: {
+						'Content-Type': 'text/event-stream',
+						'Cache-Control': 'no-cache',
+						'X-Accel-Buffering': 'no',
+					},
+					body: readable,
+				};
+			}
+
+			const result = await models.generate(input, opts);
+			return toChatCompletion(result, model);
+		} catch (err) {
+			return toOpenAIError(err);
+		}
+	}
+
+	/**
+	 * A client that sends an explicit `Accept: text/event-stream` with its POST is
+	 * dispatched by REST as CONNECT (REST.ts), not POST. The OpenAI SDK happens to send
+	 * `Accept: application/json` even when streaming, but other valid SSE clients do not.
+	 *
+	 * Without this override the request reached `Resource`'s default `connect`, whose
+	 * instance path returns `subscribe()` — an empty `IterableEventQueue` — so the client
+	 * got a 200 SSE response that stayed open forever emitting nothing, rather than an
+	 * error it could act on.
+	 *
+	 * REST passes `null` as the CONNECT body (`resource.connect(target, null, request)`),
+	 * so the parsed body is taken off the request and handed to the same `post()`
+	 * implementation — one code path, identical validation and error shaping.
+	 *
+	 * `connect` is also reachable from the WebSocket handler with a different signature
+	 * (`resourceRequest, incomingMessages, request`), where there is no `request.data`;
+	 * that case is rejected as a client error rather than returning an envelope the WS
+	 * path would fail to iterate.
+	 */
+	static async connect(target: unknown, _data: unknown, request: unknown) {
+		const data = (request as { data?: unknown })?.data;
+		if (data === undefined) {
+			return badRequest('This endpoint requires a JSON request body; WebSocket connections are not supported');
+		}
+		return this.post(target, data, request);
+	}
+}

package/resources/models/v1/embeddings.ts

@@ -0,0 +1,70 @@
+/**
+ * `POST /v1/embeddings` — OpenAI-compatible embedding endpoint (#631).
+ *
+ * Maps OpenAI's `{ model, input }` request body to `scope.models.embed()` and
+ * returns `{ object: 'list', data: [...], model, usage }` per the OpenAI wire spec.
+ */
+
+import { Resource } from '../../Resource.ts';
+import { models } from '../Models.ts';
+import { toOpenAIError, badRequest, authorizeV1Request } from './errors.ts';
+import { toEmbedOpts, toEmbedResponse } from './translation.ts';
+
+// Cap batched input, matching OpenAI's own 2048-item limit. The endpoint is
+// super_user-only and off by default, so this is a sanity bound (avoid an
+// unbounded fan-out to the backend), not a security control.
+const MAX_EMBEDDING_INPUTS = 2048;
+
+// @ts-ignore — Resource base class is not typed for static dispatch; pattern mirrors login.ts
+export class V1Embeddings extends Resource {
+	// Reserve this fixed route: a later app registration at the same path becomes a
+	// loud conflict (ErrorResource) instead of silently replacing the gateway and its
+	// super_user gate. See Resources.set.
+	static reservedPath = true;
+
+	static async post(_target: unknown, body: Record<string, unknown>, request: unknown) {
+		const authError = authorizeV1Request(request as any);
+		if (authError) return authError;
+
+		// REST.ts passes `request.data` directly, which is the (unawaited) streaming
+		// JSON deserializer's Promise — awaiting here is a no-op for callers (e.g.
+		// unit tests) that already pass a plain object. A malformed JSON body rejects
+		// this promise, which is a client error, not a 500 (matches chatCompletions).
+		try {
+			body = await body;
+		} catch (err) {
+			return badRequest(`Could not parse request body: ${err instanceof Error ? err.message : 'invalid JSON'}`);
+		}
+		if (!body || typeof body !== 'object' || Array.isArray(body))
+			return badRequest('Request body must be a JSON object');
+		const raw = body as Record<string, unknown>;
+
+		// Mirrors validateChatRequest: a non-string model would silently invoke the
+		// configured default rather than being rejected.
+		if (raw.model !== undefined && typeof raw.model !== 'string') return badRequest("'model' must be a string");
+
+		const input = raw.input;
+		if (input === undefined || input === null) return badRequest("'input' is required");
+		if (typeof input !== 'string' && !Array.isArray(input)) {
+			return badRequest("'input' must be a string or array of strings");
+		}
+		if (Array.isArray(input) && !input.every((v) => typeof v === 'string')) {
+			return badRequest("'input' array elements must be strings");
+		}
+		if (Array.isArray(input) && input.length > MAX_EMBEDDING_INPUTS) {
+			return badRequest(`'input' array must not exceed ${MAX_EMBEDDING_INPUTS} items`);
+		}
+
+		const model = typeof raw.model === 'string' ? raw.model : 'default';
+		const opts = toEmbedOpts(raw as any);
+
+		try {
+			// embedWithUsage, not embed(): the public facade drops the result-level usage
+			// backends report, and OpenAI clients read real token counts off the response.
+			const { vectors, usage } = await models.embedWithUsage(input as string | string[], opts);
+			return toEmbedResponse(vectors, model, usage);
+		} catch (err) {
+			return toOpenAIError(err);
+		}
+	}
+}

package/resources/models/v1/errors.ts

@@ -0,0 +1,141 @@
+/**
+ * OpenAI error envelope helpers for the `/v1/*` gateway (#631).
+ *
+ * Harper's REST layer serialises uncaught errors as RFC 9457 Problem Details.
+ * Resources that need the OpenAI `{ error: { message, type, code, param } }`
+ * shape must catch errors themselves and call `toOpenAIError()` / `badRequest()`.
+ */
+
+import { ModelBackendNotFoundError } from '../backendRegistry.ts';
+import { ModelCapabilityError } from '../Models.ts';
+import harperLogger from '../../../utility/logging/harper_logger.ts';
+
+type OpenAIErrorType =
+	'invalid_request_error' | 'server_error' | 'authentication_error' | 'permission_error' | 'api_error';
+
+export interface OpenAIErrorBody {
+	message: string;
+	type: OpenAIErrorType;
+	code: string | null;
+	param: string | null;
+}
+
+/** HTTP response payload from a gateway error; resource methods return this directly. */
+export interface OpenAIErrorResponse {
+	status: number;
+	headers: { 'Content-Type': 'application/json' };
+	data: { error: OpenAIErrorBody };
+}
+
+/**
+ * Map any thrown value to an OpenAI error envelope. Uses `statusCode` when
+ * present (Harper's `ClientError` / `ServerError` convention). Falls back to
+ * `500 server_error`. `ModelBackendNotFoundError` maps to `404 model_not_found`.
+ */
+export function toOpenAIError(err: unknown): OpenAIErrorResponse {
+	let status = 500;
+	let type: OpenAIErrorType = 'server_error';
+	let code: string | null = null;
+
+	if (err instanceof ModelBackendNotFoundError) {
+		status = 404;
+		type = 'invalid_request_error';
+		code = 'model_not_found';
+	} else if (err instanceof ModelCapabilityError) {
+		// Caller-driven mismatch (e.g. `tools` or streaming against a backend that
+		// doesn't support it): the request is what's wrong, not the server. It extends
+		// ServerError (statusCode 500), so this must precede the statusCode branch —
+		// falling through would report a generic sanitized 500 for a client-actionable
+		// condition. The message is safe to pass through: it names only the backend and
+		// the capability the caller asked for.
+		status = 400;
+		type = 'invalid_request_error';
+		code = 'capability_unsupported';
+	} else if (err instanceof Error && typeof (err as any).statusCode === 'number') {
+		status = (err as any).statusCode;
+		if (status === 401) {
+			type = 'authentication_error';
+		} else if (status === 403) {
+			// OpenAI semantics: 401 = bad/missing credentials, 403 = valid credentials
+			// lacking permission (matches authorizeV1Request's own 403 envelope).
+			type = 'permission_error';
+		} else if (status < 500) {
+			type = 'invalid_request_error';
+		} else {
+			type = 'server_error';
+		}
+	}
+
+	// 5xx messages stay generic: internal error strings (backend stack details, file
+	// paths) don't belong in a wire response. The real error goes to the log. 4xx
+	// messages are client-actionable and pass through.
+	let message: string;
+	if (status >= 500) {
+		harperLogger.error('v1 gateway error', err);
+		message = 'Internal server error';
+	} else {
+		message = err instanceof Error ? err.message : 'Bad request';
+	}
+
+	return {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+		data: { error: { message, type, code, param: null } },
+	};
+}
+
+/** Convenience for early request-body validation failures. */
+export function badRequest(message: string): OpenAIErrorResponse {
+	return {
+		status: 400,
+		headers: { 'Content-Type': 'application/json' },
+		data: { error: { message, type: 'invalid_request_error', code: null, param: null } },
+	};
+}
+
+/**
+ * Gate for the `/v1/*` handlers, since overriding the static `get`/`post` methods
+ * bypasses Resource's `transactional()` wrapper and its default `allowRead`/`allowCreate`
+ * checks (Resource.ts:685-733, 426-435) never run for these endpoints.
+ *
+ * Mirrors Resource's default gate (super_user-only) rather than introducing a new
+ * permission — see PR discussion for whether a dedicated `/v1/*` permission should
+ * replace this later.
+ *
+ * Returns an OpenAI-shape error response when access should be denied, or `null`
+ * when the request may proceed.
+ */
+export function authorizeV1Request(request: {
+	user?: { role?: { permission?: { super_user?: boolean } } };
+}): OpenAIErrorResponse | null {
+	const user = request?.user;
+	if (!user) {
+		return {
+			status: 401,
+			headers: { 'Content-Type': 'application/json' },
+			data: {
+				error: {
+					message: 'You must provide valid credentials to access this endpoint.',
+					type: 'authentication_error' as const,
+					code: null,
+					param: null,
+				},
+			},
+		};
+	}
+	if (!user.role?.permission?.super_user) {
+		return {
+			status: 403,
+			headers: { 'Content-Type': 'application/json' },
+			data: {
+				error: {
+					message: 'You do not have permission to access this endpoint.',
+					type: 'permission_error' as const,
+					code: null,
+					param: null,
+				},
+			},
+		};
+	}
+	return null;
+}