harper 5.1.20 → 5.2.0-alpha.5

package/components/mcp/toolRegistry.ts

@@ -136,9 +136,42 @@ export interface ToolDef extends ToolDescriptor {
 
 const registry = new Map<string, ToolDef>();
 
+/**
+ * Dynamic, per-profile tool source. A profile may register a provider that
+ * computes its tool set *lazily* — walked on every `tools/list` / `tools/call`
+ * rather than snapshotted into the static registry at registration time. The
+ * operations profile uses this so component operations registered after MCP
+ * boot (`server.registerOperation`, e.g. the built-in agent's `agent_prompt`)
+ * still surface once allow-listed, instead of being missed by a one-time walk
+ * of `OPERATION_FUNCTION_MAP` — see components/mcp/tools/operations.ts (#1562).
+ *
+ * On a name collision, a statically-registered tool (`addTool`) for the same
+ * profile wins over a provider entry — a curated tool overrides a generic
+ * same-named provider tool.
+ */
+export interface ProfileToolProvider {
+	/** Every tool the provider currently exposes for its profile. */
+	list(): ToolDef[];
+	/** Resolve a single tool by name, or `undefined` if not currently exposed. */
+	get(name: string): ToolDef | undefined;
+}
+
+const profileProviders = new Map<McpProfile, ProfileToolProvider>();
+
 /** Per-session pagination cache. Invalidated when a fresh `tools/list` (no cursor) call recomputes. */
 const sessionListCache = new Map<string, { tools: ToolDescriptor[] }>();
 
+/**
+ * Install (or, with `undefined`, remove) the dynamic tool provider for a
+ * profile. Idempotent — re-installing swaps the provider. Drops the pagination
+ * caches so the next `tools/list` recomputes against the new provider.
+ */
+export function setProfileToolProvider(profile: McpProfile, provider: ProfileToolProvider | undefined): void {
+	if (provider) profileProviders.set(profile, provider);
+	else profileProviders.delete(profile);
+	sessionListCache.clear();
+}
+
 export function addTool(def: ToolDef): void {
 	if (!def?.name) throw new Error('addTool: name is required');
 	registry.set(def.name, def);
@@ -152,8 +185,33 @@ export function removeTool(name: string): boolean {
 	return existed;
 }
 
-export function getTool(name: string): ToolDef | undefined {
-	return registry.get(name);
+/**
+ * Resolve a tool by name for `tools/call`. Pass the caller's `profile` so
+ * resolution is profile-scoped: the flat name→def registry is a single
+ * namespace shared by both profiles, so without scoping a static tool in one
+ * profile shadows a same-named provider tool in another — the shadowed tool
+ * then lists but is uncallable (the transport rejects the wrong-profile def).
+ *
+ * With a profile: a static registration of that profile wins over its provider
+ * entry (curated tool overrides a generic same-named provider tool), then the
+ * profile's provider, then any static registration by name (harmless — the
+ * transport re-checks `tool.profile`). Without a profile (internal/tests):
+ * static registry first, then any provider.
+ */
+export function getTool(name: string, profile?: McpProfile): ToolDef | undefined {
+	const statik = registry.get(name);
+	if (profile !== undefined) {
+		if (statik?.profile === profile) return statik;
+		const def = profileProviders.get(profile)?.get(name);
+		if (def) return def;
+		return statik;
+	}
+	if (statik) return statik;
+	for (const provider of profileProviders.values()) {
+		const def = provider.get(name);
+		if (def) return def;
+	}
+	return undefined;
 }
 
 /**
@@ -199,6 +257,7 @@ export function clearSessionCache(sessionId: string): void {
 /** Test seam: drop all registrations. */
 export function _resetRegistryForTest(): void {
 	registry.clear();
+	profileProviders.clear();
 	sessionListCache.clear();
 }
 
@@ -258,9 +317,19 @@ export function listTools(args: ListToolsArgs): ListToolsResult {
 }
 
 function computeFilteredList(user: AuthedUser, profile: McpProfile): ToolDescriptor[] {
-	const out: ToolDescriptor[] = [];
+	// Merge the profile's dynamic provider (if any) with its statically-registered
+	// tools, deduping by name. Provider entries are inserted first so a static
+	// registration of the same name overrides them (curated wins — see getTool).
+	const byName = new Map<string, ToolDef>();
+	const provider = profileProviders.get(profile);
+	if (provider) {
+		for (const def of provider.list()) byName.set(def.name, def);
+	}
 	for (const def of registry.values()) {
-		if (def.profile !== profile) continue;
+		if (def.profile === profile) byName.set(def.name, def);
+	}
+	const out: ToolDescriptor[] = [];
+	for (const def of byName.values()) {
 		if (!def.visibleTo(user)) continue;
 		out.push({
 			name: def.name,

package/components/mcp/tools/application.ts

@@ -163,7 +163,34 @@ interface ToolAnnotationsLike {
 	openWorldHint?: boolean;
 }
 
-type ResourcesRegistry = Map<string, ResourceRegistryEntry>;
+/**
+ * True when `pattern`'s only dynamic segment is a single trailing `:id` param (e.g. `widget/:id`).
+ * That is the ONLY shape the verb handlers below bind — `target.id = args.id`, treating `:id` as
+ * the record itself — so a differently-named param (`:widgetId`), more than one param, a `*wildcard`
+ * segment, or an `:id` that is NOT the final segment (`widget/:id/action`, where the route names a
+ * sub-resource, not the widget) would advertise an `id` input the handler never actually threads
+ * onto the real segment(s).
+ */
+function isSimpleIdRoute(pattern: string): boolean {
+	const segments = pattern.split('/');
+	if (segments[segments.length - 1] !== ':id') return false;
+	let paramCount = 0;
+	for (const segment of segments) {
+		if (segment.startsWith('*')) return false;
+		if (segment.startsWith(':')) {
+			if (segment !== ':id') return false;
+			paramCount++;
+		}
+	}
+	return paramCount === 1;
+}
+
+/** A compiled parameterised route (e.g. `/widget/:id`), stored outside the base Map. */
+interface ParamRouteEntry {
+	pattern: string;
+	entry: ResourceRegistryEntry;
+}
+type ResourcesRegistry = Map<string, ResourceRegistryEntry> & { paramRoutes?: ParamRouteEntry[] };
 type RequestTargetCtor = new () => Record<string, unknown> & {
 	conditions?: unknown[];
 	operator?: string;
@@ -228,9 +255,15 @@ function loadRequestTarget(): RequestTargetCtor | undefined {
  *
  * Falls back to the registration-time class only if the registry lookup fails
  * (e.g. the entry was removed), so a stale tool still dispatches *something*.
+ *
+ * Parameterised routes (e.g. `/widget/:id`) live outside the base Map in
+ * `paramRoutes`, so a plain `Map.get(path)` always misses for them — checked
+ * there too, or the live-dispatch guarantee above silently doesn't apply to
+ * param-route resources.
  */
 function liveResource(path: string, fallback: ResourceClassLike): ResourceClassLike {
-	const entry = loadResources()?.get(path);
+	const registry = loadResources();
+	const entry = registry?.get(path) ?? registry?.paramRoutes?.find((route) => route.pattern === path)?.entry;
 	return (entry?.Resource as ResourceClassLike | undefined) ?? fallback;
 }
 
@@ -953,8 +986,7 @@ function makeCustomResourceReader(path: string, capturedClass: ResourceClassLike
 		const Ctor = ResourceClass as unknown as new (id: unknown, ctx: unknown) => Record<string, unknown>;
 		const instance = new Ctor(undefined, buildContext(context.user));
 		const method = instance[methodName] as
-			| ((p: Record<string, string>, ctx: ResourceReadContext) => CustomResourceReadResult)
-			| undefined;
+			((p: Record<string, string>, ctx: ResourceReadContext) => CustomResourceReadResult) | undefined;
 		if (typeof method !== 'function') {
 			throw new Error(`method '${methodName}' is not a function on the constructed Resource`);
 		}
@@ -1107,22 +1139,45 @@ function buildApplicationTools(resources: ResourcesRegistry): void {
 	const claimedSuffixes = new Set<string>();
 	let toolsRegistered = 0;
 	let resourcesConsidered = 0;
-	for (const [path, entry] of resources) {
+
+	// How much of a param route the GENERATED verb handlers can bind:
+	// 'id'   — single-`:id` routes: get/update/patch/delete bind `target.id = args.id`,
+	//          but makeCreateHandler forces `target.isCollection = true` (never binds id)
+	//          and makeSearchHandler is collection-scoped, so create/search are dropped.
+	// 'none' — multi-segment/named-wildcard routes: no generated handler can bind the
+	//          segments yet, so ALL generated verbs are dropped. Author-defined
+	//          mcpTools/mcpPrompts carry their own schemas and handler methods, so they
+	//          register regardless of binding mode.
+	const considerEntry = (
+		path: string,
+		entry: ResourceRegistryEntry | undefined,
+		paramBinding?: 'id' | 'none'
+	): void => {
+		if (!entry) return;
 		resourcesConsidered++;
-		if (!shouldEnumerate(entry)) continue;
+		if (!shouldEnumerate(entry)) return;
 		const ResourceClass = entry.Resource;
 		// @hidden type-level: suppress the Resource from MCP tool listing entirely.
 		// Data remains accessible via direct query/RBAC; only descriptive surfaces drop it.
 		if (ResourceClass?.hidden === true) {
 			harperLogger.trace(`MCP application: '/${path}' suppressed from tool listing (@hidden)`);
-			continue;
+			return;
 		}
 		const verbs = detectVerbs(ResourceClass);
+		if (paramBinding === 'id') {
+			verbs.search = false;
+			verbs.create = false;
+		} else if (paramBinding === 'none') {
+			harperLogger.trace(
+				`MCP application: '/${path}' generated verb tools skipped — multi-segment/named-wildcard binding not yet supported`
+			);
+			verbs.get = verbs.search = verbs.create = verbs.updatePut = verbs.updatePatch = verbs.delete = false;
+		}
 		const hasVerbs = verbs.get || verbs.search || verbs.create || verbs.updatePut || verbs.updatePatch || verbs.delete;
 		const hasCustomTools = Array.isArray(ResourceClass?.mcpTools) && ResourceClass.mcpTools.length > 0;
 		const hasCustomPrompts = Array.isArray(ResourceClass?.mcpPrompts) && ResourceClass.mcpPrompts.length > 0;
 		const hasCustomResources = Array.isArray(ResourceClass?.mcpResources) && ResourceClass.mcpResources.length > 0;
-		if (!hasVerbs && !hasCustomTools && !hasCustomPrompts && !hasCustomResources) continue;
+		if (!hasVerbs && !hasCustomTools && !hasCustomPrompts && !hasCustomResources) return;
 		const databaseName = ResourceClass?.databaseName;
 		const tableName = ResourceClass?.tableName;
 		const suffix = uniqueSuffix(path, databaseName, claimedSuffixes);
@@ -1142,7 +1197,21 @@ function buildApplicationTools(resources: ResourcesRegistry): void {
 		toolsRegistered += registerCustomMcpTools(ResourceClass, path);
 		registerCustomMcpPrompts(ResourceClass, path);
 		registerCustomMcpResources(ResourceClass, path);
+	};
+
+	for (const [path, entry] of resources) considerEntry(path, entry);
+
+	// Parameterised routes (e.g. `/widget/:id`) live OUTSIDE the base Map: Resources.setParamRoute
+	// stores them in `paramRoutes` and returns before the Map insert, so the loop above never sees
+	// them. Without this, a custom resource declaring `static path = '/widget/:id'` produces ZERO MCP
+	// tools — even though it appears in the OpenAPI document, which already iterates `paramRoutes`.
+	// Enumerate them so the tool surface matches the REST surface; the binding mode restricts the
+	// GENERATED verb tools to what their handlers actually bind (see considerEntry), while custom
+	// mcpTools/mcpPrompts register on every route shape.
+	for (const route of resources.paramRoutes ?? []) {
+		considerEntry(route.pattern, route.entry, isSimpleIdRoute(route.pattern) ? 'id' : 'none');
 	}
+
 	harperLogger.info(
 		`MCP application profile: considered ${resourcesConsidered} resource(s), registered ${toolsRegistered} tool(s)`
 	);

package/components/mcp/tools/operations.ts

@@ -1,7 +1,17 @@
 /**
- * Operations-profile tool generation. Walks Harper's `OPERATION_FUNCTION_MAP`
- * and registers one MCP tool per operation that survives the
- * `mcp.operations.allow` / `deny` filter.
+ * Operations-profile tool generation. Exposes one MCP tool per Harper
+ * operation that survives the `mcp.operations.allow` / `deny` filter, computed
+ * *lazily* by walking Harper's live `OPERATION_FUNCTION_MAP` on each
+ * `tools/list` / `tools/call`.
+ *
+ * The list is computed lazily (not snapshotted at registration) because
+ * components register their operations via `server.registerOperation` during
+ * `startOnMainThread`, which runs AFTER the MCP operations profile registers
+ * (see components/mcp/index.ts → registerMcpProfile). A one-time walk at
+ * registration time would miss every component-registered operation (e.g. the
+ * built-in agent's `agent_prompt`), so `mcp.operations.allow` listing them
+ * would silently have no effect — #1562. Walking the live map per request
+ * removes the ordering dependence and stays consistent as components load.
  *
  * The default v1 allow list is read-only and intentionally narrow:
  * `describe_*`, `list_*`, `search_*`, plus an explicit set of safe
@@ -26,12 +36,21 @@
 import * as env from '../../../utility/environment/environmentManager.ts';
 import { CONFIG_PARAMS } from '../../../utility/hdbTerms.ts';
 import harperLogger from '../../../utility/logging/harper_logger.ts';
-import { addTool, canRoleInvokeOperation, type AuthedUser, type ToolResult } from '../toolRegistry.ts';
+import {
+	canRoleInvokeOperation,
+	setProfileToolProvider,
+	type AuthedUser,
+	type ProfileToolProvider,
+	type ToolDef,
+	type ToolResult,
+} from '../toolRegistry.ts';
 import { OPERATION_INPUT_SCHEMAS, PERMISSIVE_SCHEMA } from './schemas/operations.ts';
 import { OPERATION_DESCRIPTIONS } from './schemas/operationDescriptions.ts';
 
-// Eager-resolved at module load. The map is built at Harper boot and
-// doesn't mutate, so caching here is safe.
+// Resolved from Harper's server-helpers graph on demand. The map is built at
+// Harper boot but keeps mutating as components register operations during
+// `startOnMainThread` — the provider below re-reads it per request rather than
+// snapshotting (#1562).
 type OperationFunction = (json: object) => unknown | Promise<unknown>;
 type OperationFunctionMap = Map<string, { operation_function: OperationFunction }>;
 
@@ -115,6 +134,25 @@ export const DEFAULT_ALLOW: readonly string[] = [
 	'read_audit_log',
 ];
 
+/**
+ * Operations excluded from the DEFAULT allow surface even when a glob matches
+ * (`list_*` would otherwise pull in `list_secrets`). The secrets store is key
+ * custody management, not data reads — none of it belongs on an LLM-facing
+ * surface by default, same rationale as the sensitive `get_*` exclusions
+ * above. Operators can still expose these deliberately via
+ * `mcp.operations.allow` (an explicit allow list replaces the default and is
+ * not filtered by this set), where the audit-log redaction of
+ * `value`/`values`/`envelope` applies.
+ */
+export const DEFAULT_EXCLUDED: ReadonlySet<string> = new Set([
+	'set_secret',
+	'grant_secret',
+	'revoke_secret',
+	'list_secrets',
+	'delete_secret',
+	'get_secrets_public_key',
+]);
+
 /**
  * Operations that carry `destructiveHint: true` when opted into the allow
  * list. The hint lets MCP clients surface a confirmation prompt before
@@ -202,7 +240,9 @@ function matchesAny(operation: string, patterns: readonly string[] | undefined):
 }
 
 function isOperationAllowed(operation: string, config: OperationsConfig): boolean {
-	const allowList = config.allow && config.allow.length > 0 ? config.allow : DEFAULT_ALLOW;
+	const usingDefaultAllow = !(config.allow && config.allow.length > 0);
+	if (usingDefaultAllow && DEFAULT_EXCLUDED.has(operation)) return false;
+	const allowList = usingDefaultAllow ? DEFAULT_ALLOW : config.allow;
 	if (!matchesAny(operation, allowList)) return false;
 	if (matchesAny(operation, config.deny)) return false;
 	return true;
@@ -277,35 +317,65 @@ function makeOperationToolHandler(operationName: string) {
 }
 
 /**
- * Idempotent registration: walk the op map, register every operation that
- * passes the allow/deny filter. Safe to invoke multiple times — `addTool`
- * is `Map.set`-backed.
+ * Build the `ToolDef` for one operation. Cheap and stateless — a def is a pure
+ * function of the operation name (its schema, description, annotations, RBAC
+ * predicate, and handler don't depend on the allow/deny config, which only
+ * decides *whether* the op is exposed, checked per request in the provider).
+ * `tools/list` isn't a hot path, so the provider rebuilds defs per call rather
+ * than caching (no module-level state to leak or stale-cache across tests).
+ */
+function buildOperationToolDef(operationName: string): ToolDef {
+	const inputSchema = OPERATION_INPUT_SCHEMAS[operationName] ?? PERMISSIVE_SCHEMA;
+	const annotations: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean } = {};
+	if (isReadOnly(operationName)) annotations.readOnlyHint = true;
+	if (isDestructive(operationName)) annotations.destructiveHint = true;
+	if (isIdempotent(operationName)) annotations.idempotentHint = true;
+	return {
+		name: operationName,
+		description: buildDescription(operationName, operationName in OPERATION_INPUT_SCHEMAS),
+		inputSchema,
+		profile: 'operations',
+		...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+		visibleTo: (user) => canRoleInvokeOperation(user, operationName),
+		handler: makeOperationToolHandler(operationName),
+	};
+}
+
+/**
+ * Lazy operations-profile tool provider. Consulted by the registry on every
+ * `tools/list` / `tools/call`, so it reflects the live `OPERATION_FUNCTION_MAP`
+ * — including operations registered by components after MCP boot (#1562).
+ */
+const operationsToolProvider: ProfileToolProvider = {
+	list(): ToolDef[] {
+		const opMap = getOperationFunctionMap();
+		if (!opMap) {
+			harperLogger.warn('MCP operations profile: OPERATION_FUNCTION_MAP not available; no tools listed');
+			return [];
+		}
+		const config = getOperationsConfig();
+		const defs: ToolDef[] = [];
+		for (const operationName of opMap.keys()) {
+			if (!isOperationAllowed(operationName, config)) continue;
+			defs.push(buildOperationToolDef(operationName));
+		}
+		return defs;
+	},
+	get(operationName: string): ToolDef | undefined {
+		const opMap = getOperationFunctionMap();
+		if (!opMap || !opMap.has(operationName)) return undefined;
+		if (!isOperationAllowed(operationName, getOperationsConfig())) return undefined;
+		return buildOperationToolDef(operationName);
+	},
+};
+
+/**
+ * Install the operations-profile tool provider. The provider is walked lazily
+ * per request rather than snapshotting the op map here, so component operations
+ * registered after this runs still surface once allow-listed (#1562).
+ * Idempotent — re-installing the provider is a no-op swap.
  */
 export function registerOperationsTools(): void {
-	const opMap = getOperationFunctionMap();
-	if (!opMap) {
-		harperLogger.warn('MCP operations profile: OPERATION_FUNCTION_MAP not available; no tools registered');
-		return;
-	}
-	const config = getOperationsConfig();
-	let registered = 0;
-	for (const operationName of opMap.keys()) {
-		if (!isOperationAllowed(operationName, config)) continue;
-		const inputSchema = OPERATION_INPUT_SCHEMAS[operationName] ?? PERMISSIVE_SCHEMA;
-		const annotations: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean } = {};
-		if (isReadOnly(operationName)) annotations.readOnlyHint = true;
-		if (isDestructive(operationName)) annotations.destructiveHint = true;
-		if (isIdempotent(operationName)) annotations.idempotentHint = true;
-		addTool({
-			name: operationName,
-			description: buildDescription(operationName, operationName in OPERATION_INPUT_SCHEMAS),
-			inputSchema,
-			profile: 'operations',
-			...(Object.keys(annotations).length > 0 ? { annotations } : {}),
-			visibleTo: (user) => canRoleInvokeOperation(user, operationName),
-			handler: makeOperationToolHandler(operationName),
-		});
-		registered++;
-	}
-	harperLogger.info(`MCP operations profile: registered ${registered} tool(s)`);
+	setProfileToolProvider('operations', operationsToolProvider);
+	harperLogger.info('MCP operations profile: lazy tool provider installed');
 }

package/components/mcp/tools/schemas/operationDescriptions.ts

@@ -86,7 +86,7 @@ export const OPERATION_DESCRIPTIONS: Record<string, string> = {
 		'Returns one background job by id, with status and result payload (export, backup, deploy, restart, csv loads).',
 	// get_status: server/status/index.ts:104 — Status KV entry; aggregated when id omitted.
 	get_status:
-		'Returns one entry from the in-memory status KV that components publish health and progress to. With no id, returns aggregated status across threads. Safe to poll. Use system_information for server-level health.',
+		'Returns one entry from the in-memory status KV that components publish health and progress to. With no id, returns aggregated status across threads; pass middleware:true to also include the resolved HTTP/upgrade/WebSocket middleware chain order per port. Safe to poll. Use system_information for server-level health.',
 	// get_analytics: resources/analytics/read.ts:44 — Metric series read with filtering + windowing.
 	get_analytics:
 		'Returns analytics metric values with optional attribute filtering, time windowing, and result coalescing. Pair with list_metrics to discover available metrics.',
@@ -192,15 +192,15 @@ export const OPERATION_DESCRIPTIONS: Record<string, string> = {
 	// drop_role: security/role.ts:126 — Delete a role; refuses if assigned.
 	drop_role:
 		'Deletes a role. Refused if any active user is still assigned to the role — drop or reassign those users first.',
-	// create_authentication_tokens: security/tokenAuthentication.ts:86 — Mint operation + refresh token pair.
+	// create_authentication_tokens: security/tokenAuthentication.ts:108 — Mint operation + refresh token pair, or (purpose: 'login') a login-exchange token.
 	create_authentication_tokens:
-		'Creates a JWT operation token and a refresh token after validating credentials. Stores the refresh token on the user record.',
+		"Creates a JWT operation token and a refresh token after validating credentials. Stores the refresh token on the user record. With purpose: 'login', instead mints a single short-lived login-exchange token (not usable as a Bearer API credential) intended for the `login` operation.",
 	// refresh_operation_token: security/tokenAuthentication.ts:171 — Mint new operation token from refresh.
 	refresh_operation_token:
 		'Issues a new operation token using a valid refresh token, without re-authenticating with username/password.',
 	// login: security/auth.ts:371 — Session-based login.
 	login:
-		'Authenticates the caller and creates a session entry. Requires sessions to be enabled in Harper configuration.',
+		'Authenticates the caller and creates a session entry. Accepts username/password, or a `token` from create_authentication_tokens with purpose: "login" to exchange it for the session cookie. Requires sessions to be enabled in Harper configuration.',
 	// logout: security/auth.ts:381 — Session-based logout.
 	logout: "Clears the caller's session. Requires sessions to be enabled.",
 

package/components/mcp/tools/schemas/operations.ts

@@ -268,6 +268,11 @@ export const OPERATION_INPUT_SCHEMAS: Record<string, object> = {
 				type: 'string',
 				description: 'Status entry id. When omitted, returns aggregated status across threads.',
 			},
+			middleware: {
+				type: 'boolean',
+				description:
+					'When true (and no id), include the resolved HTTP/upgrade/WebSocket middleware chain order per port.',
+			},
 		},
 	},
 	get_analytics: {

package/components/mcp/transport.ts

@@ -30,7 +30,8 @@ import { emitAuditEntry } from './audit.ts';
 import { emitMcpLogToSession, isValidMcpLogLevel, setSessionLogLevel } from './logging.ts';
 import { decodeCursor } from './pagination.ts';
 import { seedSessionSnapshot } from './listChanged.ts';
-import { tryAdmit } from './rateLimit.ts';
+import { tryAdmit, resolveClientIdentity } from './rateLimit.ts';
+import { checkDurableQuota } from './quota.ts';
 import { deleteSession, loadSession, saveSession, touchSession, type McpSessionRecord } from './session.ts';
 import { listResources, listResourceTemplates, readResource, completeResourceArgument } from './resources.ts';
 import { ensureApplicationToolsFresh } from './tools/application.ts';
@@ -84,6 +85,12 @@ export interface NormRequest {
 	 */
 	userObject?: AuthedUser;
 	profile: McpProfile;
+	/**
+	 * Client socket IP, for per-client rate limiting and the durable quota
+	 * hook (#1610). Adapters populate from `request.ip`; identity resolution
+	 * (socket vs trusted header) happens in `resolveClientIdentity`.
+	 */
+	clientIp?: string;
 }
 
 export interface NormResponse {
@@ -498,7 +505,7 @@ async function dispatchToolsCall(
 	if (!name) {
 		return jsonResponse(200, buildError(messageId, ERROR_CODES.INVALID_PARAMS, 'tools/call requires params.name'));
 	}
-	const tool = getTool(name);
+	const tool = getTool(name, request.profile);
 	if (!tool || tool.profile !== request.profile) {
 		return jsonResponse(200, buildError(messageId, ERROR_CODES.METHOD_NOT_FOUND, `Unknown tool: ${name}`));
 	}
@@ -513,8 +520,11 @@ async function dispatchToolsCall(
 
 	// Rate limit check — admit-or-deny BEFORE invoking the handler. Failures
 	// surface as `isError: true` with `kind: 'rate_limited'` (NOT a JSON-RPC
-	// error) so the LLM sees and can back off / try later.
-	const decision = tryAdmit(session.id, name, request.profile);
+	// error) so the LLM sees and can back off / try later. Client identity
+	// engages the per-client bucket, the scope that survives session cycling
+	// by anonymous clients (#1610).
+	const clientIdentity = resolveClientIdentity(request.headers, request.clientIp, request.profile);
+	const decision = tryAdmit(session.id, name, request.profile, clientIdentity);
 	if (!decision.allowed) {
 		// Non-strict tsconfig doesn't narrow the discriminated union here.
 		const denied = decision as { allowed: false; reason: string };
@@ -553,6 +563,47 @@ async function dispatchToolsCall(
 		return jsonResponse(200, buildSuccess(messageId, toolResult));
 	}
 
+	// Durable quota hook (#1610): operator-implemented policy behind config
+	// (e.g. a persisted per-IP daily counter). Runs AFTER the cheap in-memory
+	// admit so a rate-limited client can't spam the (possibly table-backed)
+	// hook, and BEFORE the handler. Fail-closed; see quota.ts.
+	const quota = await checkDurableQuota({
+		identity: clientIdentity,
+		tool: name,
+		user,
+		profile: request.profile,
+		sessionId: session.id,
+	});
+	if (quota.allowed === false) {
+		decision.release();
+		const toolResult: ToolResult = {
+			isError: true,
+			content: [
+				{
+					type: 'text',
+					text: JSON.stringify({
+						kind: 'quota_exceeded',
+						tool: name,
+						message: quota.message ?? 'MCP quota exceeded',
+						...(quota.retryAfterSeconds !== undefined ? { retryAfterSeconds: quota.retryAfterSeconds } : {}),
+					}),
+				},
+			],
+		};
+		emitAuditEntry({
+			timestamp: new Date(callStartedAt).toISOString(),
+			profile: request.profile,
+			sessionId: session.id,
+			tool: name,
+			user: user.username ?? request.user,
+			args: args as object,
+			status: 'quota_exceeded',
+			durationMs: 0,
+		});
+		emitMcpLogToSession(session.id, 'notice', { kind: 'quota_exceeded', tool: name }, 'mcp.quota');
+		return jsonResponse(200, buildSuccess(messageId, toolResult));
+	}
+
 	// Per-call cancellation (#1349 §3.3): an inbound `notifications/cancelled`
 	// referencing this request id aborts `signal`. Registered for the call's
 	// lifetime, removed in `finally`.

package/components/ollama/index.ts

@@ -147,7 +147,7 @@ export class OllamaBackend implements ModelBackend {
 			signal,
 		});
 		if (!res.ok) {
-			throw new OllamaBackendError(`Ollama ${path} returned HTTP ${res.status}`);
+			throw new OllamaBackendError(`Ollama ${path} returned HTTP ${res.status}`, res.status);
 		}
 		return res;
 	}
@@ -169,9 +169,13 @@ export function registerOllamaBackend(args: {
 }
 
 export class OllamaBackendError extends ServerError {
-	constructor(message: string) {
+	/** HTTP status returned by the upstream provider, when the failure came from an HTTP response.
+	 * Distinct from ServerError's statusCode, which is Harper's own response status (#1593). */
+	declare upstreamStatus?: number;
+	constructor(message: string, upstreamStatus?: number) {
 		super(message);
 		this.name = 'OllamaBackendError';
+		if (upstreamStatus !== undefined) this.upstreamStatus = upstreamStatus;
 	}
 }
 

package/components/openai/index.ts

@@ -262,7 +262,10 @@ export class OpenAIBackend implements ModelBackend {
 			// doesn't leak request content. Cap length defensively against a
 			// misbehaving compat shim. Falls back to status-only if the body
 			// isn't JSON or doesn't have the envelope.
-			throw new OpenAIBackendError(`OpenAI ${path} returned HTTP ${res.status}${await readErrorSuffix(res)}`);
+			throw new OpenAIBackendError(
+				`OpenAI ${path} returned HTTP ${res.status}${await readErrorSuffix(res)}`,
+				res.status
+			);
 		}
 		return res;
 	}
@@ -306,9 +309,13 @@ export function registerOpenAIBackend(args: {
 }
 
 export class OpenAIBackendError extends ServerError {
-	constructor(message: string) {
+	/** HTTP status returned by the upstream provider, when the failure came from an HTTP response.
+	 * Distinct from ServerError's statusCode, which is Harper's own response status (#1593). */
+	declare upstreamStatus?: number;
+	constructor(message: string, upstreamStatus?: number) {
 		super(message);
 		this.name = 'OpenAIBackendError';
+		if (upstreamStatus !== undefined) this.upstreamStatus = upstreamStatus;
 	}
 }