stitchkit 0.93.0 → 0.94.1

package/dist/entrypoints/observability.js

@@ -0,0 +1,567 @@
+import {
+  ObservabilityDrainReportSchema,
+  ObservabilitySinkStatusSchema,
+  ObservabilityStatusSchema,
+  aggregateObservabilityStatus,
+  assertDrainBound,
+  createBoundedSinkManager,
+  withinBound
+} from "../index-h6eeys1v.js";
+import {
+  measureSize,
+  redact,
+  sanitizePayload,
+  truncatePreview
+} from "../index-yw4fzmdz.js";
+import {
+  getRequestContext,
+  getTraceId,
+  getUserId,
+  runWithRequestContext,
+  setRequestDimensions,
+  setRequestEndpoint,
+  setRequestError,
+  setRequestUser,
+  wrapInRequestContext
+} from "../index-zfrhfn82.js";
+import"../index-35mh5bhj.js";
+import {
+  childSpan,
+  createTraceContext,
+  formatTraceparent,
+  parseTraceparent,
+  resolvePropagationContext,
+  resolveTraceContext
+} from "../index-zcgf3gqf.js";
+import {
+  recordedErrorMessage
+} from "../index-znfs20ss.js";
+import"../index-p5r7qpdd.js";
+import"../index-2vtcmrj9.js";
+import"../index-kzfs85xp.js";
+import {
+  isRecord
+} from "../index-hffjpmq9.js";
+
+// src/observability/audit.ts
+function writeProjectedDimensions(dimensions, collision) {
+  if (!dimensions)
+    return;
+  const materialized = {};
+  for (const [key, value] of Object.entries(dimensions)) {
+    if (value !== undefined)
+      materialized[key] = value;
+  }
+  if (Object.keys(materialized).length > 0) {
+    setRequestDimensions(materialized, { collision });
+  }
+}
+function createDimensionsProjector(config) {
+  const collision = config.collision ?? "overwrite";
+  return Object.freeze({
+    request(ctx, endpoint) {
+      writeProjectedDimensions(config.request?.(ctx, endpoint), collision);
+    },
+    result(ctx, result, endpoint) {
+      writeProjectedDimensions(config.result?.(ctx, result, endpoint), collision);
+      return result;
+    },
+    error(ctx, error, endpoint) {
+      writeProjectedDimensions(config.error?.(ctx, error, endpoint), collision);
+    }
+  });
+}
+function toolErrorMessage(result) {
+  const { details, hint } = result;
+  if (isRecord(details) && typeof details.message === "string") {
+    return details.message;
+  }
+  return hint;
+}
+function auditErrorMessage(result, thrown) {
+  return recordedErrorMessage(result.code, toolErrorMessage(result), thrown);
+}
+function readString(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function readMcpContext(value) {
+  if (!isRecord(value))
+    return;
+  const era = value.era;
+  const method = value.method;
+  const toolName = value.toolName;
+  if (era !== "modern" && era !== "legacy" || typeof method !== "string" || typeof toolName !== "string") {
+    return;
+  }
+  const protocolVersion = readString(value.protocolVersion);
+  const clientInfoValue = value.clientInfo;
+  const clientInfo = isRecord(clientInfoValue) && typeof clientInfoValue.name === "string" && typeof clientInfoValue.version === "string" ? { name: clientInfoValue.name, version: clientInfoValue.version } : undefined;
+  const outcomeValue = value.outcome;
+  const outcome = outcomeValue === "input_required" || outcomeValue === "declined" || outcomeValue === "cancelled" || outcomeValue === "invalid" || outcomeValue === "complete" ? outcomeValue : undefined;
+  const round = typeof value.round === "number" && Number.isInteger(value.round) && value.round >= 0 ? value.round : undefined;
+  return {
+    era,
+    method,
+    toolName,
+    ...protocolVersion !== undefined && { protocolVersion },
+    ...clientInfo !== undefined && { clientInfo },
+    ...outcome !== undefined && { outcome },
+    ...round !== undefined && { round }
+  };
+}
+function createSinkManager(config) {
+  return createBoundedSinkManager(config);
+}
+function createObservability(config) {
+  const requestManager = config.request ? createSinkManager(config.request) : undefined;
+  const toolManager = config.tools ? createSinkManager(config.tools) : undefined;
+  let closed = false;
+  let drain;
+  let drainStartedAt = 0;
+  let unbounded;
+  const request = config.request ? {
+    includePayload: config.request.includePayload ?? false,
+    complete: ({ context, statusCode, durationMs, payload, outcome }) => {
+      const requestConfig = config.request;
+      if (!requestConfig)
+        return;
+      const cancelled = outcome === "cancelled";
+      if (cancelled && !requestConfig.includeCancelled)
+        return;
+      requestManager?.submit(async () => {
+        let body;
+        if (!cancelled && payload) {
+          try {
+            body = await payload;
+          } catch {
+            body = undefined;
+          }
+        }
+        return {
+          source: context.source,
+          kind: context.kind ?? "request",
+          ...context.name !== undefined && { name: context.name },
+          ...context.method !== undefined && { method: context.method },
+          ...context.path !== undefined && { path: context.path },
+          ...context.serviceName !== undefined && {
+            serviceName: context.serviceName
+          },
+          ...context.action !== undefined && { action: context.action },
+          ...context.dimensions !== undefined && {
+            dimensions: context.dimensions
+          },
+          traceId: context.trace.traceId,
+          spanId: context.trace.spanId,
+          parentSpanId: context.trace.parentSpanId,
+          ok: !cancelled && (statusCode !== undefined ? statusCode < 400 : context.error === undefined),
+          ...cancelled && { outcome: "cancelled" },
+          ...statusCode !== undefined && { statusCode },
+          durationMs,
+          ...!cancelled && {
+            errorCode: context.error?.code,
+            errorMessage: context.error?.message,
+            ...context.error?.details !== undefined && {
+              errorDetail: sanitizePayload(context.error.details, requestConfig.sanitize)
+            }
+          },
+          payload: cancelled ? null : sanitizePayload(body, requestConfig.sanitize),
+          resultSize: null,
+          responseBytes: 0,
+          userId: context.userId,
+          ipAddress: context.ipAddress,
+          userAgent: context.userAgent,
+          startedAt: new Date(Date.now() - durationMs)
+        };
+      });
+    }
+  } : undefined;
+  const toolCall = config.tools ? {
+    afterToolCall: ({ toolName, args, result, durationMs, context, endpoint, error }) => {
+      try {
+        const toolConfig = config.tools;
+        if (!toolConfig)
+          return;
+        const requestCtx = getRequestContext();
+        const span = requestCtx ? childSpan(requestCtx.trace) : createTraceContext();
+        const measure = result.ok ? measureSize(result.data) : { resultSize: null, responseBytes: 0 };
+        const mcp = context.source === "mcp" ? readMcpContext(context.mcp) : undefined;
+        const toolPhase = mcp?.outcome === "input_required" ? "input-round" : "operation";
+        toolManager?.submit(() => ({
+          source: context.source,
+          kind: "request",
+          method: "TOOL",
+          httpMethod: endpoint.method,
+          path: `/${context.source}/${toolName}`,
+          serviceName: endpoint.serviceName,
+          action: endpoint.key,
+          ...requestCtx?.dimensions !== undefined && {
+            dimensions: requestCtx.dimensions
+          },
+          toolName,
+          toolPhase,
+          ...mcp !== undefined && { mcp },
+          traceId: span.traceId,
+          spanId: span.spanId,
+          parentSpanId: span.parentSpanId,
+          ok: result.ok,
+          statusCode: result.ok ? 200 : 400,
+          durationMs,
+          errorCode: result.ok ? undefined : result.code,
+          errorMessage: result.ok ? undefined : auditErrorMessage(result, error),
+          ...!result.ok && result.details !== undefined && {
+            errorDetail: sanitizePayload(result.details, toolConfig.sanitize)
+          },
+          payload: sanitizePayload(args, toolConfig.sanitize),
+          resultSize: measure.resultSize,
+          responseBytes: measure.responseBytes,
+          ..."unserializable" in measure && measure.unserializable && { resultUnserializable: true },
+          userId: readString(context.userId),
+          authMethod: readString(context.authMethod),
+          clientId: readString(context.clientId),
+          ipAddress: readString(context.ipAddress),
+          userAgent: readString(context.userAgent),
+          startedAt: new Date(Date.now() - durationMs)
+        }));
+      } catch {}
+    }
+  } : undefined;
+  const getStatus = () => {
+    const requestStatus = requestManager?.getStatus();
+    const toolsStatus = toolManager?.getStatus();
+    const surfaces = [requestStatus, toolsStatus].filter((status) => status !== undefined);
+    return ObservabilityStatusSchema.parse({
+      ...requestStatus && { request: requestStatus },
+      ...toolsStatus && { tools: toolsStatus },
+      total: aggregateObservabilityStatus(surfaces, closed)
+    });
+  };
+  return {
+    ...request && { request },
+    toolCall: toolCall ?? {},
+    flush(bound) {
+      assertDrainBound(bound);
+      return withinBound(Promise.all([requestManager?.flush(), toolManager?.flush()]), bound);
+    },
+    getStatus,
+    close(bound) {
+      assertDrainBound(bound);
+      if (!drain) {
+        closed = true;
+        drainStartedAt = performance.now();
+        drain = Promise.all([requestManager?.close(), toolManager?.close()]).then(() => {
+          return;
+        });
+      }
+      const startedAt = drainStartedAt;
+      const report = () => {
+        const status = getStatus();
+        return ObservabilityDrainReportSchema.parse({
+          ...status,
+          durationMs: performance.now() - startedAt,
+          drained: status.total.pending + status.total.preparing === 0
+        });
+      };
+      if (!bound?.signal && bound?.timeoutMs === undefined) {
+        unbounded ??= withinBound(drain, undefined).then(report);
+        return unbounded;
+      }
+      return withinBound(drain, bound).then(report);
+    }
+  };
+}
+// src/observability/bounded-logger.ts
+var DEFAULT_REDACT_PATHS = Object.freeze([
+  "*.password",
+  "*.token",
+  "*.cookie",
+  "*.authorization",
+  "*.secret",
+  "**.password",
+  "**.token",
+  "**.cookie",
+  "**.authorization",
+  "**.secret"
+]);
+function asLogRecord(value) {
+  if (isRecord(value)) {
+    if (value._truncated === true) {
+      return {
+        message: "[truncated log entry]",
+        data: {
+          _truncated: true,
+          _originalBytes: value._originalBytes,
+          preview: value.preview
+        }
+      };
+    }
+    const message = typeof value.message === "string" ? value.message : "[sanitized log entry]";
+    const data = value.data;
+    return { message, ...isRecord(data) ? { data } : {} };
+  }
+  return { message: "[truncated log entry]", data: { entry: value } };
+}
+function byteLength(value) {
+  return measureSize(value).responseBytes;
+}
+function fitLogRecord(record, maxBytes) {
+  let message = record.message;
+  let data = record.data ? { ...record.data } : undefined;
+  while (byteLength({ message, data }) > maxBytes) {
+    if (typeof data?.preview === "string" && data.preview.length > 0) {
+      const points = Array.from(data.preview);
+      data.preview = points.length <= 1 ? "" : `${points.slice(0, points.length / 2).join("")}…`;
+      continue;
+    }
+    if (message.length > 16) {
+      const points = Array.from(message);
+      message = `${points.slice(0, points.length / 2).join("")}…`;
+      continue;
+    }
+    data = { _truncated: true };
+    message = "[truncated]";
+    break;
+  }
+  return { message, ...data && { data } };
+}
+function createBoundedLogger(options) {
+  const entryBytes = options.bounds?.entryBytes ?? 65536;
+  if (!Number.isSafeInteger(entryBytes) || entryBytes < 128) {
+    throw new TypeError("createBoundedLogger entryBytes must be an integer of at least 128");
+  }
+  const write = (level, message, data) => {
+    try {
+      const context = getRequestContext();
+      const enriched = {
+        ...data,
+        ...context?.trace.traceId !== undefined && { traceId: context.trace.traceId },
+        ...context?.trace.spanId !== undefined && { spanId: context.trace.spanId },
+        ...context?.userId !== undefined && { userId: context.userId },
+        ...context?.dimensions !== undefined && { dimensions: context.dimensions }
+      };
+      const value = sanitizePayload({ message, data: enriched }, {
+        sensitiveKeys: options.redact?.keys,
+        includeDefaultSensitiveKeys: true,
+        sensitivePaths: [
+          ...DEFAULT_REDACT_PATHS,
+          ...(options.redact?.paths ?? []).map((path) => `data.${path}`)
+        ],
+        sensitiveUrlPatterns: options.sensitiveUrlPatterns,
+        maxStringLength: options.bounds?.stringLength ?? 4000,
+        ...options.bounds?.stringLengthByKey !== undefined && {
+          maxStringLengthByKey: options.bounds.stringLengthByKey
+        },
+        maxCollectionLength: options.bounds?.collectionLength ?? 100,
+        maxDepth: options.bounds?.depth ?? 6,
+        maxBytes: entryBytes
+      });
+      const sanitized = fitLogRecord(asLogRecord(value), entryBytes);
+      const result = options.sink[level](sanitized.message, sanitized.data);
+      if (result instanceof Promise)
+        result.catch(() => {
+          return;
+        });
+    } catch {}
+  };
+  return {
+    info: (message, data) => write("info", message, data),
+    warn: (message, data) => write("warn", message, data),
+    error: (message, data) => write("error", message, data),
+    debug: (message, data) => write("debug", message, data)
+  };
+}
+// src/observability/changes.ts
+var READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+var SECURITY_STATUSES = new Set([401, 403]);
+function auditChanges(event) {
+  if (event.statusCode !== undefined && SECURITY_STATUSES.has(event.statusCode))
+    return true;
+  const verb = event.httpMethod ?? event.method;
+  if (verb === undefined)
+    return true;
+  return !READ_METHODS.has(verb.toUpperCase());
+}
+// src/observability/spool.ts
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+function reviveEvent(event) {
+  return { ...event, startedAt: new Date(event.startedAt) };
+}
+function createSpooledSink(config) {
+  const keyOf = config.key ?? ((event) => event.spanId);
+  const compactAfter = config.compactAfter ?? 512;
+  const undelivered = new Map;
+  let delivered = 0;
+  let tail = Promise.resolve();
+  function serialise(work) {
+    const next = tail.then(work, work);
+    tail = next.catch(() => {
+      return;
+    });
+    return next;
+  }
+  async function append(line, event) {
+    try {
+      await appendFile(config.path, `${JSON.stringify(line)}
+`, "utf8");
+    } catch (error) {
+      if (isMissing(error)) {
+        await mkdir(dirname(config.path), { recursive: true });
+        await appendFile(config.path, `${JSON.stringify(line)}
+`, "utf8");
+        return;
+      }
+      config.onSpoolError?.({ error, ...event !== undefined && { event } });
+    }
+  }
+  async function compact() {
+    const temporary = `${config.path}.compacting`;
+    const body = [...undelivered.entries()].map(([key, event]) => `${JSON.stringify({ k: key, e: event })}
+`).join("");
+    try {
+      await writeFile(temporary, body, "utf8");
+      await rename(temporary, config.path);
+      delivered = 0;
+    } catch (error) {
+      config.onSpoolError?.({ error });
+    }
+  }
+  return {
+    async write(event) {
+      const key = keyOf(event);
+      await serialise(() => append({ k: key, e: event }, event));
+      undelivered.set(key, event);
+      await config.write(event);
+      undelivered.delete(key);
+      delivered += 1;
+      await serialise(async () => {
+        await append({ a: key });
+        if (delivered >= compactAfter)
+          await compact();
+      });
+    },
+    async recover() {
+      let body;
+      try {
+        body = await readFile(config.path, "utf8");
+      } catch (error) {
+        if (!isMissing(error))
+          config.onSpoolError?.({ error });
+        return { replayed: 0, failed: 0 };
+      }
+      const pending = new Map;
+      for (const line of body.split(`
+`)) {
+        if (line.length === 0)
+          continue;
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch (error) {
+          config.onSpoolError?.({ error });
+          continue;
+        }
+        if (parsed.a !== undefined) {
+          pending.delete(parsed.a);
+          continue;
+        }
+        if (parsed.k !== undefined && parsed.e !== undefined) {
+          pending.set(parsed.k, reviveEvent(parsed.e));
+        }
+      }
+      const replayed = pending.size;
+      let failed = 0;
+      for (const [key, event] of pending) {
+        try {
+          await config.write(event);
+          pending.delete(key);
+        } catch (error) {
+          failed += 1;
+          config.onSpoolError?.({ error, event });
+        }
+      }
+      undelivered.clear();
+      for (const [key, event] of pending)
+        undelivered.set(key, event);
+      delivered = 0;
+      await serialise(compact);
+      return { replayed, failed };
+    },
+    pending: () => undelivered.size
+  };
+}
+function code(error) {
+  if (typeof error !== "object" || error === null)
+    return;
+  const value = Reflect.get(error, "code");
+  return typeof value === "string" ? value : undefined;
+}
+var isMissing = (error) => code(error) === "ENOENT";
+// src/observability/work.ts
+async function runUnitOfWork(options, body) {
+  const context = {
+    trace: resolvePropagationContext(options.traceparent === undefined ? undefined : { traceparent: options.traceparent }, undefined),
+    source: options.source ?? "job",
+    kind: "job",
+    name: options.name,
+    startedAt: process.hrtime.bigint(),
+    ...options.dimensions !== undefined && { dimensions: { ...options.dimensions } }
+  };
+  const startedAtMs = Date.now();
+  return runWithRequestContext(context, async () => {
+    try {
+      const value = await body();
+      complete(options.observability, context, startedAtMs);
+      return value;
+    } catch (error) {
+      context.error ??= {
+        ...errorCodeOf(error) !== undefined && { code: errorCodeOf(error) },
+        message: error instanceof Error ? error.message : String(error)
+      };
+      complete(options.observability, context, startedAtMs);
+      throw error;
+    }
+  });
+}
+function errorCodeOf(error) {
+  if (typeof error !== "object" || error === null)
+    return;
+  const code2 = Reflect.get(error, "code");
+  return typeof code2 === "string" ? code2 : undefined;
+}
+function complete(observability, context, startedAtMs) {
+  observability?.request?.complete({
+    context,
+    durationMs: Date.now() - startedAtMs
+  });
+}
+export {
+  wrapInRequestContext,
+  truncatePreview,
+  setRequestUser,
+  setRequestError,
+  setRequestEndpoint,
+  setRequestDimensions,
+  sanitizePayload,
+  runWithRequestContext,
+  runUnitOfWork,
+  resolveTraceContext,
+  resolvePropagationContext,
+  redact,
+  parseTraceparent,
+  measureSize,
+  getUserId,
+  getTraceId,
+  getRequestContext,
+  formatTraceparent,
+  createTraceContext,
+  createSpooledSink,
+  createObservability,
+  createDimensionsProjector,
+  createBoundedLogger,
+  childSpan,
+  auditChanges,
+  ObservabilityStatusSchema,
+  ObservabilitySinkStatusSchema,
+  ObservabilityDrainReportSchema,
+  DEFAULT_REDACT_PATHS
+};

package/dist/entrypoints/primitives.d.ts

@@ -0,0 +1,3 @@
+/** Browser-safe generic values and declarative application policies. */
+export * from '../primitives/index.js';
+//# sourceMappingURL=primitives.d.ts.map

package/dist/entrypoints/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/entrypoints/primitives.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,cAAc,qBAAqB,CAAC"}