machine-bridge-mcp 0.16.1 → 0.17.0

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.17.0";
 const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 const MCP_SUPPORTED_PROTOCOL_VERSIONS = serverMetadata.supportedProtocolVersions.map((value) => String(value));
 const JSONRPC_VERSION = "2.0";
@@ -162,14 +162,14 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
   async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
     const size = typeof message === "string" ? new TextEncoder().encode(message).byteLength : message.byteLength;
     if (size > MAX_DAEMON_MESSAGE_BYTES) {
-      try { ws.close(1009, "message too large"); } catch {}
+      closeWebSocketQuietly(ws, 1009, "message too large");
       return;
     }
     let text: string;
     try {
       text = typeof message === "string" ? message : new TextDecoder("utf-8", { fatal: true }).decode(message);
     } catch {
-      try { ws.close(1007, "invalid UTF-8"); } catch {}
+      closeWebSocketQuietly(ws, 1007, "invalid UTF-8");
       return;
     }
     let parsed: unknown;
@@ -187,12 +187,12 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
 
     const socketAttachment = this.socketAttachment(ws);
     if (!socketAttachment) {
-      try { ws.close(1008, "missing daemon attachment"); } catch {}
+      closeWebSocketQuietly(ws, 1008, "missing daemon attachment");
       return;
     }
 
     if (socketAttachment.role === "expired") {
-      try { ws.close(1008, "expired daemon candidate"); } catch {}
+      closeWebSocketQuietly(ws, 1008, "expired daemon candidate");
       return;
     }
 
@@ -204,7 +204,7 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
       const previousDaemons = this.daemonSockets().filter((socket) => socket !== ws);
       if (socketAttachment.role === "candidate") {
         if (!isFreshDaemonCandidate(socketAttachment.connectedAt)) {
-          try { ws.close(1008, "stale daemon candidate"); } catch {}
+          closeWebSocketQuietly(ws, 1008, "stale daemon candidate");
           await this.scheduleCandidateAlarm();
           return;
         }
@@ -225,17 +225,17 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
           role: "expired",
           connectedAt: socketAttachment.connectedAt,
         } satisfies DaemonAttachment);
-        try { ws.close(1011, "daemon hello acknowledgement failed"); } catch {}
+        closeWebSocketQuietly(ws, 1011, "daemon hello acknowledgement failed");
         return;
       }
       for (const socket of previousDaemons) {
-        try { socket.close(1012, "replaced by authenticated daemon"); } catch {}
+        closeWebSocketQuietly(socket, 1012, "replaced by authenticated daemon");
       }
       return;
     }
 
     if (socketAttachment.role !== "daemon") {
-      try { ws.close(1008, "daemon hello required"); } catch {}
+      closeWebSocketQuietly(ws, 1008, "daemon hello required");
       return;
     }
 
@@ -387,7 +387,7 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
       clientRequestKey: requestKey,
       timeoutMs,
       onTimeout: (record) => {
-        try { record.socket.send(JSON.stringify({ type: "cancel_call", id: record.id })); } catch {}
+        sendWebSocketQuietly(record.socket, { type: "cancel_call", id: record.id });
         return new WorkerToolError("timeout", `daemon tool timed out: ${name}`, true);
       },
     });
@@ -410,7 +410,7 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
   private cancelClientRequest(requestKey?: string): void {
     if (!requestKey) return;
     this.pending.cancelRequest(requestKey, (record) => {
-      try { record.socket.send(JSON.stringify({ type: "cancel_call", id: record.id })); } catch {}
+      sendWebSocketQuietly(record.socket, { type: "cancel_call", id: record.id });
       return new WorkerToolError("cancelled", "tool call cancelled by client");
     });
   }
@@ -422,7 +422,7 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
     if (!expected || !(await safeEqual(supplied, expected))) return new Response("Unauthorized daemon", { status: 401 });
 
     for (const socket of this.nonDaemonSockets()) {
-      try { socket.close(1012, "replaced by newer daemon candidate"); } catch {}
+      closeWebSocketQuietly(socket, 1012, "replaced by newer daemon candidate");
     }
 
     const pair = new WebSocketPair();
@@ -508,8 +508,8 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
           role: "expired",
           connectedAt: attachment?.connectedAt ?? new Date(0).toISOString(),
         } satisfies DaemonAttachment);
-        try { socket.send(JSON.stringify({ type: "error", error: "daemon_hello_timeout" })); } catch {}
-        try { socket.close(1008, "daemon hello timeout"); } catch {}
+        sendWebSocketQuietly(socket, { type: "error", error: "daemon_hello_timeout" });
+        closeWebSocketQuietly(socket, 1008, "daemon hello timeout");
         continue;
       }
       nextDeadline = Math.min(nextDeadline, deadline);
@@ -524,7 +524,7 @@ export class BridgeRoom extends DurableObject<BridgeEnv> {
       const attachment = this.socketAttachment(socket);
       const connectedAt = Date.parse(attachment?.connectedAt ?? "");
       if (!Number.isFinite(connectedAt)) {
-        try { socket.close(1008, "invalid daemon candidate timestamp"); } catch {}
+        closeWebSocketQuietly(socket, 1008, "invalid daemon candidate timestamp");
         continue;
       }
       nextDeadline = Math.min(nextDeadline, connectedAt + DAEMON_HELLO_TIMEOUT_MS);
@@ -885,8 +885,24 @@ function isObjectRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function rejectDaemonMessage(ws: WebSocket, error: string, closeCode: number, closeReason: string): void {
-  try { ws.send(JSON.stringify({ type: "error", error })); } catch {}
-  try { ws.close(closeCode, closeReason); } catch {}
+  sendWebSocketQuietly(ws, { type: "error", error });
+  closeWebSocketQuietly(ws, closeCode, closeReason);
+}
+
+function sendWebSocketQuietly(ws: WebSocket, value: unknown): void {
+  try {
+    ws.send(typeof value === "string" ? value : JSON.stringify(value));
+  } catch {
+    // Best-effort protocol cleanup must not replace the primary timeout or rejection.
+  }
+}
+
+function closeWebSocketQuietly(ws: WebSocket, code?: number, reason?: string): void {
+  try {
+    ws.close(code, reason);
+  } catch {
+    // The socket may already be closed or detached; no recovery remains at this boundary.
+  }
 }
 
 function isJsonRpcRequest(value: unknown): value is JsonRpcRequest {

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;
+}