machine-bridge-mcp 0.16.1 → 0.16.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.16.2 - 2026-07-13
+
+### Fixed
+
+- Package the entire `src/worker` directory (instead of just `src/worker/index.ts`) in the published npm package so that global installations have all files required to compile/deploy the Worker.
+- Add regression coverage in packaging tests to verify all worker modules are present.
+
 ## 0.16.1 - 2026-07-13
 
 ### Fixed

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -30,5 +30,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.16.1"
+  "version_name": "0.16.2"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
     "browser-extension",
     "src/local",
     "src/shared",
-    "src/worker/index.ts",
+    "src/worker",
     "scripts",
     "wrangler.jsonc",
     "tsconfig.json",

package/src/local/managed-jobs.mjs

@@ -697,10 +697,17 @@ function runnerProcessIsCurrent(status, dir, { ownerOnly = false } = {}) {
 
 function scrubFinishedPlan(dir, status) {
   if (PLAN_RETAINING_STATES.has(status.status)) return;
-  rmSync(join(dir, "plan.json"), { force: true });
-  rmSync(join(dir, "runner.pid"), { force: true });
-  rmSync(join(dir, "recovery.lock"), { force: true });
-  rmSync(join(dir, "transition.lock"), { force: true });
+  const safeRm = (path) => {
+    try {
+      rmSync(path, { force: true });
+    } catch (error) {
+      if (!["ENOENT", "EPERM", "EACCES"].includes(error.code)) throw error;
+    }
+  };
+  safeRm(join(dir, "plan.json"));
+  safeRm(join(dir, "runner.pid"));
+  safeRm(join(dir, "recovery.lock"));
+  safeRm(join(dir, "transition.lock"));
 }
 
 function reviewablePlan(plan) {

package/src/worker/errors.ts

@@ -0,0 +1,41 @@
+const WORKER_ERROR_CODES = new Set([
+  "cancelled", "timeout", "authentication_failed", "authorization_denied", "policy_denied",
+  "invalid_request", "not_found", "conflict", "limit_exceeded", "permission_denied",
+  "path_boundary", "network_error", "protocol_error", "unavailable", "integrity_error",
+  "execution_failed", "internal_error",
+]);
+
+export class WorkerToolError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(code: string, message: string, retryable = false) {
+    super(message);
+    this.name = "WorkerToolError";
+    this.code = normalizeCode(code);
+    this.retryable = retryable;
+  }
+}
+
+export function daemonToolError(value: unknown): WorkerToolError {
+  const input = asObject(value);
+  const code = normalizeCode(input.code);
+  const message = typeof input.message === "string" && input.message
+    ? input.message.slice(0, 2000)
+    : "daemon tool failed";
+  return new WorkerToolError(code, message, input.retryable === true);
+}
+
+export function publicWorkerToolError(error: unknown): { code: string; message: string; retryable: boolean } {
+  if (error instanceof WorkerToolError) return { code: error.code, message: error.message, retryable: error.retryable };
+  return { code: "execution_failed", message: "tool execution failed", retryable: false };
+}
+
+function normalizeCode(value: unknown): string {
+  const code = String(value || "execution_failed").toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, 64);
+  return WORKER_ERROR_CODES.has(code) ? code : "execution_failed";
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}

package/src/worker/http.ts

@@ -0,0 +1,252 @@
+const UNSAFE_DISPLAY_CONTROLS = /[\u0000-\u001f\u007f\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g;
+
+export class HttpError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function methodNotAllowed(allow: string): Response {
+  return new Response(JSON.stringify({ error: "method_not_allowed" }), {
+    status: 405,
+    headers: {
+      allow,
+      "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
+      "x-content-type-options": "nosniff",
+    },
+  });
+}
+
+export function oauthRedirect(location: URL): Response {
+  return new Response(null, {
+    status: 303,
+    headers: {
+      location: location.href,
+      "cache-control": "no-store",
+      "referrer-policy": "no-referrer",
+      "x-content-type-options": "nosniff",
+    },
+  });
+}
+
+export function authorizationRedirectLocation(redirectUri: string, code: string, state: string): URL {
+  const location = new URL(redirectUri);
+  location.searchParams.append("code", code);
+  if (state) location.searchParams.append("state", state);
+  return location;
+}
+
+export function json(value: unknown, status = 200): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "x-content-type-options": "nosniff",
+    },
+  });
+}
+
+export function html(value: string, status = 200): Response {
+  return new Response(value, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+      "referrer-policy": "no-referrer",
+      "x-content-type-options": "nosniff",
+      "x-frame-options": "DENY",
+    },
+  });
+}
+
+export function baseUrl(request: Request): string {
+  return new URL(request.url).origin;
+}
+
+export function bearerToken(request: Request): string {
+  const match = (request.headers.get("Authorization") ?? "").match(/^Bearer\s+(.+)$/i);
+  return match?.[1]?.trim() ?? "";
+}
+
+export async function parseJsonRequest(request: Request, limit: number): Promise<unknown> {
+  const text = await readBoundedText(request, limit);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new HttpError(400, "invalid_json", "Request body is not valid JSON");
+  }
+}
+
+export async function parseRequestBody(request: Request, limit: number): Promise<Record<string, unknown>> {
+  const contentType = (request.headers.get("content-type") ?? "").toLowerCase();
+  const text = await readBoundedText(request, limit);
+  if (contentType.includes("application/json") || text.trim().startsWith("{")) {
+    let parsed: unknown;
+    try {
+      parsed = text.trim() ? JSON.parse(text) : {};
+    } catch {
+      throw new HttpError(400, "invalid_json", "Request body is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new HttpError(400, "bad_request", "JSON body must be an object");
+    }
+    return parsed as Record<string, unknown>;
+  }
+  return searchParamsObject(new URLSearchParams(text));
+}
+
+export async function readBoundedText(request: Request, limit: number): Promise<string> {
+  const length = Number(request.headers.get("content-length") ?? "0");
+  if (Number.isFinite(length) && length > limit) {
+    throw new HttpError(413, "request_body_too_large", `request body exceeds ${limit} bytes`);
+  }
+  if (!request.body) return "";
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > limit) {
+        await reader.cancel();
+        throw new HttpError(413, "request_body_too_large", `request body exceeds ${limit} bytes`);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const combined = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    combined.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(combined);
+  } catch {
+    throw new HttpError(400, "invalid_encoding", "Request body must be valid UTF-8");
+  }
+}
+
+export function normalizeRedirectUri(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password || url.hash) return null;
+    if (url.protocol === "https:" && url.hostname) return url.toString();
+    if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url.toString();
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function corsPreflight(request: Request, base: string, configured: string): Response {
+  const origin = request.headers.get("Origin") ?? "";
+  if (!isConfiguredOrSameOrigin(origin, base, configured)) return json({ error: "origin_not_allowed" }, 403);
+  const requestedMethod = (request.headers.get("Access-Control-Request-Method") ?? "").toUpperCase();
+  if (requestedMethod && !["GET", "POST"].includes(requestedMethod)) return methodNotAllowed("GET, POST, OPTIONS");
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "access-control-allow-origin": origin,
+      "access-control-allow-methods": "GET, POST, OPTIONS",
+      "access-control-allow-headers": "authorization, content-type, mcp-protocol-version, mcp-session-id",
+      "access-control-max-age": "600",
+      "cache-control": "no-store",
+      "vary": "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
+    },
+  });
+}
+
+export function applyCors(response: Response, request: Request, base: string, configured: string): Response {
+  if (response.status === 101) return response;
+  const origin = request.headers.get("Origin") ?? "";
+  if (!origin || !isConfiguredOrSameOrigin(origin, base, configured)) return response;
+  const headers = new Headers(response.headers);
+  headers.set("access-control-allow-origin", origin);
+  headers.set("access-control-expose-headers", "www-authenticate, mcp-session-id");
+  appendVary(headers, "Origin");
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+export function validateOrigin(request: Request, base: string, configured = ""): boolean {
+  const origin = request.headers.get("Origin");
+  return !origin || isConfiguredOrSameOrigin(origin, base, configured);
+}
+
+export function searchParamsEntries(params: URLSearchParams): Array<[string, string]> {
+  const entries: Array<[string, string]> = [];
+  params.forEach((value, key) => entries.push([key, value]));
+  return entries;
+}
+
+export function searchParamsObject(params: URLSearchParams): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  params.forEach((value, key) => {
+    if (out[key] === undefined) out[key] = value;
+    else if (Array.isArray(out[key])) (out[key] as string[]).push(value);
+    else out[key] = [out[key] as string, value];
+  });
+  return out;
+}
+
+export function normalizeDisplayText(value: string, maxLength: number, fallback = "MCP Client"): string {
+  const normalized = value.replace(UNSAFE_DISPLAY_CONTROLS, " ").replace(/\s+/g, " ").trim();
+  return (normalized || fallback).slice(0, maxLength);
+}
+
+export function sanitizeMetadataText(value: unknown, maxLength: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.replace(UNSAFE_DISPLAY_CONTROLS, " ").replace(/\s+/g, " ").trim();
+  return normalized ? normalized.slice(0, maxLength) : undefined;
+}
+
+export function escapeHtml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+
+export function workerErrorClass(error: unknown): string {
+  if (error instanceof HttpError) return error.code;
+  if (error instanceof TypeError) return "type_error";
+  if (error instanceof RangeError) return "range_error";
+  if (error instanceof Error) return error.name.replace(/[^A-Za-z0-9_-]/g, "_").toLowerCase().slice(0, 64) || "error";
+  return "unknown_error";
+}
+
+function appendVary(headers: Headers, value: string): void {
+  const existing = headers.get("vary");
+  const values = new Set((existing ?? "").split(",").map((item) => item.trim()).filter(Boolean));
+  values.add(value);
+  headers.set("vary", [...values].join(", "));
+}
+
+function isConfiguredOrSameOrigin(origin: string, base: string, configured: string): boolean {
+  if (isDefaultAllowedOrigin(origin, base)) return true;
+  const allowed = configured.split(",").map((item) => item.trim()).filter((item) => item && item !== "null");
+  return allowed.includes(origin);
+}
+
+function isDefaultAllowedOrigin(origin: string, base: string): boolean {
+  try {
+    return new URL(origin).origin === new URL(base).origin;
+  } catch {
+    return false;
+  }
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+}

package/src/worker/index.ts

@@ -17,7 +17,7 @@ import {
 } from "./http";
 
 const SERVER_NAME = String(serverMetadata.name);
-const SERVER_VERSION = "0.16.1";
+const SERVER_VERSION = "0.16.2";
 const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 const MCP_SUPPORTED_PROTOCOL_VERSIONS = serverMetadata.supportedProtocolVersions.map((value) => String(value));
 const JSONRPC_VERSION = "2.0";

package/src/worker/oauth-state.ts

@@ -0,0 +1,170 @@
+export interface OAuthClient {
+  client_id: string;
+  client_name: string;
+  redirect_uris: string[];
+  created_at: number;
+  last_used_at: number;
+  registration_identity?: string;
+}
+
+export interface OAuthCode {
+  client_id: string;
+  redirect_uri: string;
+  code_challenge: string;
+  scope: string;
+  resource: string;
+  expires_at: number;
+}
+
+export interface OAuthToken {
+  client_id: string;
+  scope: string;
+  resource: string;
+  version: string;
+  expires_at: number;
+}
+
+export interface OAuthFailure {
+  count: number;
+  window_started: number;
+  blocked_until: number;
+  last_attempt: number;
+}
+
+export interface OAuthStore {
+  clients: Record<string, OAuthClient>;
+  codes: Record<string, OAuthCode>;
+  tokens: Record<string, OAuthToken>;
+  auth_failures: Record<string, OAuthFailure>;
+}
+
+export interface ValidatedAuthorization {
+  client: OAuthClient;
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+  requestedResource: string;
+  scope: string;
+  state: string;
+}
+
+const AUTH_FAILURE_WINDOW_SECONDS = 10 * 60;
+export const AUTH_BLOCK_SECONDS = 15 * 60;
+const AUTH_FAILURE_LIMIT = 10;
+
+export function validateAuthorizationRequest(
+  body: Record<string, unknown>,
+  base: string,
+  serverName: string,
+  store: OAuthStore,
+): { value: ValidatedAuthorization } | { error: string; status: number } {
+  const responseType = String(body.response_type ?? "");
+  const clientId = String(body.client_id ?? "");
+  const redirectUri = String(body.redirect_uri ?? "");
+  const codeChallenge = String(body.code_challenge ?? "");
+  const codeChallengeMethod = String(body.code_challenge_method ?? "");
+  const requestedResource = String(body.resource ?? `${base}/mcp`);
+  const scope = String(body.scope ?? serverName).trim();
+  const state = body.state === undefined ? "" : typeof body.state === "string" ? body.state : "";
+
+  if (responseType !== "code") return { error: "response_type must be code.", status: 400 };
+  if (requestedResource !== `${base}/mcp`) return { error: "resource mismatch.", status: 400 };
+  if (scope !== serverName) return { error: "unsupported scope.", status: 400 };
+  if (body.state !== undefined && typeof body.state !== "string") return { error: "state must be a string.", status: 400 };
+  if (state.length > 1024) return { error: "state is too long.", status: 400 };
+  if (codeChallengeMethod !== "S256" || !/^[A-Za-z0-9_-]{43}$/.test(codeChallenge)) {
+    return { error: "A valid PKCE S256 challenge is required.", status: 400 };
+  }
+  const client = store.clients[clientId];
+  if (!client) return { error: "Unknown OAuth client.", status: 400 };
+  if (!client.redirect_uris.includes(redirectUri)) return { error: "redirect_uri is not registered.", status: 400 };
+  return { value: { client, clientId, redirectUri, codeChallenge, requestedResource, scope, state } };
+}
+
+export function pruneClientRecordByExpiry<T extends { client_id: string; expires_at: number }>(record: Record<string, T>, clientId: string, keep: number): void {
+  const allowed = new Set(Object.entries(record)
+    .filter(([, value]) => value.client_id === clientId)
+    .sort((left, right) => right[1].expires_at - left[1].expires_at)
+    .slice(0, keep)
+    .map(([key]) => key));
+  for (const [key, value] of Object.entries(record)) {
+    if (value.client_id === clientId && !allowed.has(key)) delete record[key];
+  }
+}
+
+export function pruneRecordByExpiry<T extends { expires_at: number }>(record: Record<string, T>, keep: number): void {
+  const allowed = new Set(Object.entries(record)
+    .sort((left, right) => right[1].expires_at - left[1].expires_at)
+    .slice(0, keep)
+    .map(([key]) => key));
+  for (const key of Object.keys(record)) if (!allowed.has(key)) delete record[key];
+}
+
+export async function authorizationIdentity(request: Request, keyMaterial: string): Promise<string> {
+  const source = (request.headers.get("CF-Connecting-IP") || "unknown").slice(0, 128);
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(keyMaterial),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(source));
+  return `hmac-sha256:${[...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+
+export function recordAuthorizationFailure(store: OAuthStore, identity: string, now: number): void {
+  const current = store.auth_failures[identity];
+  const activeWindow = current && current.window_started + AUTH_FAILURE_WINDOW_SECONDS > now;
+  const count = activeWindow ? current.count + 1 : 1;
+  store.auth_failures[identity] = {
+    count,
+    window_started: activeWindow ? current.window_started : now,
+    blocked_until: count >= AUTH_FAILURE_LIMIT ? now + AUTH_BLOCK_SECONDS : 0,
+    last_attempt: now,
+  };
+}
+
+export function pruneAuthFailures(store: OAuthStore, keep: number): void {
+  const allowed = new Set(Object.entries(store.auth_failures)
+    .sort((left, right) => right[1].last_attempt - left[1].last_attempt)
+    .slice(0, keep)
+    .map(([key]) => key));
+  for (const key of Object.keys(store.auth_failures)) if (!allowed.has(key)) delete store.auth_failures[key];
+}
+
+export function randomToken(prefix: string): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return `${prefix}_${base64Url(bytes)}`;
+}
+
+export async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function safeEqual(left: string, right: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const [leftHash, rightHash] = await Promise.all([
+    crypto.subtle.digest("SHA-256", encoder.encode(left)),
+    crypto.subtle.digest("SHA-256", encoder.encode(right)),
+  ]);
+  const leftBytes = new Uint8Array(leftHash);
+  const rightBytes = new Uint8Array(rightHash);
+  let diff = leftBytes.length ^ rightBytes.length;
+  for (let index = 0; index < Math.max(leftBytes.length, rightBytes.length); index += 1) {
+    diff |= (leftBytes[index] ?? 0) ^ (rightBytes[index] ?? 0);
+  }
+  return diff === 0;
+}
+
+export async function pkceS256(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64Url(new Uint8Array(digest));
+}
+
+function base64Url(bytes: Uint8Array): string {
+  return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}

package/src/worker/observability.ts

@@ -0,0 +1,111 @@
+const MAX_ERROR_CODES = 64;
+const MAX_TOOLS = 128;
+const SENSITIVE_FIELD = /(?:authorization|cookie|credential|password|secret|token|verifier|private[_-]?key)/i;
+
+export class WorkerObservability {
+  private readonly startedAt = Date.now();
+  private readonly requests = { total: 0, successful: 0, client_error: 0, server_error: 0 };
+  private readonly calls = { started: 0, completed: 0, failed: 0, cancelled: 0, timed_out: 0 };
+  private readonly sockets = { candidates: 0, authenticated: 0, disconnected: 0, protocol_errors: 0 };
+  private readonly errors = new Map<string, number>();
+  private readonly tools = new Map<string, { started: number; completed: number; failed: number; active: number }>();
+
+  requestFinished(status: number): void {
+    this.requests.total += 1;
+    if (status >= 500) this.requests.server_error += 1;
+    else if (status >= 400) this.requests.client_error += 1;
+    else this.requests.successful += 1;
+  }
+
+  callStarted(tool: string): void {
+    this.calls.started += 1;
+    const metric = this.toolMetric(tool);
+    metric.started += 1;
+    metric.active += 1;
+  }
+
+  callFinished(tool: string, code = ""): void {
+    const metric = this.toolMetric(tool);
+    metric.active = Math.max(0, metric.active - 1);
+    if (!code) {
+      this.calls.completed += 1;
+      metric.completed += 1;
+      return;
+    }
+    this.calls.failed += 1;
+    metric.failed += 1;
+    if (code === "cancelled") this.calls.cancelled += 1;
+    if (code === "timeout") this.calls.timed_out += 1;
+    this.incrementError(code);
+  }
+
+  socketCandidate(): void { this.sockets.candidates += 1; }
+  socketAuthenticated(): void { this.sockets.authenticated += 1; }
+  socketDisconnected(): void { this.sockets.disconnected += 1; }
+  socketProtocolError(code: string): void {
+    this.sockets.protocol_errors += 1;
+    this.incrementError(code || "protocol_error");
+  }
+
+  snapshot(): Record<string, unknown> {
+    return {
+      uptime_ms: Math.max(0, Date.now() - this.startedAt),
+      requests: { ...this.requests },
+      calls: { ...this.calls },
+      sockets: { ...this.sockets },
+      errors: Object.fromEntries([...this.errors.entries()].sort(([left], [right]) => left.localeCompare(right))),
+      tools: Object.fromEntries([...this.tools.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, metric]) => [name, { ...metric }])),
+    };
+  }
+
+  event(level: "info" | "warn" | "error", event: string, fields: Record<string, unknown> = {}): void {
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      component: "worker",
+      event: sanitizeName(event),
+      ...sanitizeFields(fields),
+    };
+    const text = JSON.stringify(entry);
+    if (level === "error") console.error(text);
+    else if (level === "warn") console.warn(text);
+    else console.log(text);
+  }
+
+  private toolMetric(tool: string): { started: number; completed: number; failed: number; active: number } {
+    const name = sanitizeName(tool) || "unknown";
+    if (!this.tools.has(name)) {
+      if (this.tools.size >= MAX_TOOLS) return this.toolMetric("other");
+      this.tools.set(name, { started: 0, completed: 0, failed: 0, active: 0 });
+    }
+    return this.tools.get(name)!;
+  }
+
+  private incrementError(code: string): void {
+    const key = sanitizeName(code) || "execution_failed";
+    if (!this.errors.has(key) && this.errors.size >= MAX_ERROR_CODES) {
+      this.errors.set("other", (this.errors.get("other") ?? 0) + 1);
+      return;
+    }
+    this.errors.set(key, (this.errors.get(key) ?? 0) + 1);
+  }
+}
+
+function sanitizeName(value: unknown): string {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9._-]/g, "_").slice(0, 128);
+}
+
+function sanitizeFields(fields: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fields).slice(0, 32)) {
+    const safeKey = sanitizeName(key);
+    if (!safeKey) continue;
+    if (SENSITIVE_FIELD.test(safeKey)) {
+      out[safeKey] = "<redacted>";
+      continue;
+    }
+    if (typeof value === "boolean" || typeof value === "number" || value === null) out[safeKey] = value;
+    else if (typeof value === "string") out[safeKey] = value.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, 256);
+  }
+  return out;
+}