stitchkit 0.0.1 → 0.2.0

package/dist/internal/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CASxD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAWrD"}

package/dist/internal/typed.d.ts

@@ -0,0 +1,9 @@
+export declare function typedEntries<T extends object>(value: T): Array<{
+    [K in keyof T]: [K, T[K]];
+}[keyof T]>;
+/** Narrow an unknown value to a plain object — not `null`, not an array. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function mapObject<TSource extends object, TResult extends {
+    [K in keyof TSource]?: unknown;
+}>(source: TSource, mapper: <K extends keyof TSource>(key: K, value: TSource[K]) => TResult[K] | undefined): TResult;
+//# sourceMappingURL=typed.d.ts.map

package/dist/internal/typed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../src/internal/typed.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,KAAK,EAAE,CAAC,GACP,KAAK,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAE/C;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,SAAS,CACvB,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE,OAAO;CAAE,EAElD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,GACrF,OAAO,CAOT"}

package/dist/node.d.ts

@@ -0,0 +1,4 @@
+export { createHandler } from './server/create';
+export { type NodeServerConfig, type NodeServerHandle, serveNode } from './server/node';
+export type { HandlerConfig } from './server/types';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/node.js

@@ -0,0 +1,26 @@
+import {
+  createHandler
+} from "./index-v2z2v3mq.js";
+import"./index-a35v22fh.js";
+import"./index-kckky6zw.js";
+import"./index-ke4mx4ea.js";
+// src/server/node.ts
+import { serve } from "srvx";
+async function serveNode(config) {
+  const { port = 3000, hostname, ...handlerConfig } = config;
+  const handler = createHandler(handlerConfig);
+  const server = serve({ port, hostname, fetch: handler });
+  await server.ready();
+  const listenUrl = server.url ?? `http://${hostname ?? "localhost"}:${port}`;
+  const resolvedPort = Number(new URL(listenUrl).port) || port;
+  const resolvedHost = hostname ?? "localhost";
+  return {
+    url: `http://${resolvedHost}:${resolvedPort}`,
+    port: resolvedPort,
+    close: (closeActive) => server.close(closeActive)
+  };
+}
+export {
+  serveNode,
+  createHandler
+};

package/dist/observability/audit.d.ts

@@ -0,0 +1,32 @@
+import type { ToolCallHooks } from '../tools/execute';
+import type { RequestEvent } from './event';
+import { type SanitizeOptions } from './sanitize';
+/** Config for `createAuditHook`. */
+export interface AuditConfig {
+    /**
+     * The sink — persists one audit event. It runs fire-and-forget and its own
+     * errors are swallowed, so a slow or failing write never blocks or breaks the
+     * request it observes. Keep it asynchronous and self-contained.
+     */
+    write: (event: RequestEvent) => void | Promise<void>;
+    /** Keep only events for which this returns `true`. Default: keep every event. */
+    filter?: (event: RequestEvent) => boolean;
+    /** Payload sanitisation tuning — passed through to `sanitizePayload`. */
+    sanitize?: SanitizeOptions;
+}
+/** What `createAuditHook` returns — one wiring point per surface. */
+export interface AuditHook {
+    /**
+     * Wrap the HTTP fetch handler — audits every request from its final
+     * response (success and error alike). Compose it INSIDE `wrapInRequestContext`
+     * (it reads that context for trace ids, timing and identity).
+     */
+    http: <S>(handler: (req: Request, server: S) => Promise<Response>) => (req: Request, server: S) => Promise<Response>;
+    /**
+     * Tool-call hooks — audits every MCP / agent tool call. Pass as `hooks` to
+     * `createMcpHandler`, `createStdioMcpServer` or `mountAgent`.
+     */
+    toolCall: ToolCallHooks;
+}
+export declare function createAuditHook(config: AuditConfig): AuditHook;
+//# sourceMappingURL=audit.d.ts.map

package/dist/observability/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC,EACN,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,KACpD,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AAmBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CA6F9D"}

package/dist/observability/context.d.ts

@@ -0,0 +1,60 @@
+import type { TransportSource } from '../contract';
+import { type TraceContext } from './trace';
+/** Everything known about the request in flight. */
+export interface RequestContext {
+    /** W3C trace ids for this request. */
+    trace: TraceContext;
+    /** Which surface the request arrived on. */
+    source: TransportSource;
+    /** HTTP verb. */
+    method: string;
+    /** Request path. */
+    path: string;
+    /** Monotonic start, for duration — `process.hrtime.bigint()`. */
+    startedAt: bigint;
+    /** Client IP, when resolvable. */
+    ipAddress?: string;
+    /** Client user-agent, when present. */
+    userAgent?: string;
+    /** Resolved user id — set late, once auth has run. */
+    userId?: string;
+    /** Error outcome — set late, by the error handler. */
+    error?: {
+        code?: string;
+        message?: string;
+    };
+}
+/** Run `fn` with `ctx` as the active request context. */
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+/** The active request context, or `undefined` outside any request. */
+export declare function getRequestContext(): RequestContext | undefined;
+/** The active trace id — the one id to stamp on every log line. */
+export declare function getTraceId(): string | undefined;
+/** The active user id, once auth has resolved it. */
+export declare function getUserId(): string | undefined;
+/**
+ * Attach the resolved user to the active context. The ALS record is mutable —
+ * the update is visible to everything already holding the context. Call this
+ * from the auth hook.
+ */
+export declare function setRequestUser(userId: string): void;
+/**
+ * Record the error outcome on the active context. Call this from the error
+ * handler — the audit hook reads it when the request completes.
+ */
+export declare function setRequestError(error: {
+    code?: string;
+    message?: string;
+}): void;
+/**
+ * Wrap a fetch handler so it runs inside a fresh `RequestContext` — trace ids
+ * (the inbound `traceparent` continued, or freshly minted), timing and client
+ * info.
+ *
+ * Compose it as the OUTERMOST wrapper of the server's fetch handler. To make
+ * the framework router reuse this trace id (so request logs and application
+ * logs share one id), pass `traceId: getTraceId` to `createServer` /
+ * `createHandler`.
+ */
+export declare function wrapInRequestContext<S>(handler: (req: Request, server: S) => Promise<Response>): (req: Request, server: S) => Promise<Response>;
+//# sourceMappingURL=context.d.ts.map

package/dist/observability/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/observability/context.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjE,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,CAAC;IACxB,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAID,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED,mEAAmE;AACnE,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAE/C;AAED,qDAAqD;AACrD,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,GACtD,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAYhD"}

package/dist/observability/event.d.ts

@@ -0,0 +1,49 @@
+import type { TransportSource } from '../contract';
+import type { JsonValue } from './sanitize';
+/**
+ * A normalised audit event — one shape for a completed call on any surface
+ * (an HTTP request, an MCP tool call, an agent tool call). `createAuditHook`
+ * produces it and hands it to the project's `write` sink. The project maps it
+ * onto its own audit table; stitchkit owns the normalisation.
+ */
+export interface RequestEvent {
+    /** Surface the call arrived on. */
+    source: TransportSource;
+    /** HTTP verb, or `TOOL` for a tool call. */
+    method: string;
+    /** Request path — `/api/...` for HTTP, `/{source}/{tool}` for a tool call. */
+    path: string;
+    /** Tool name — tool calls only. */
+    toolName?: string;
+    /** W3C trace id — correlates every span of one logical request. */
+    traceId: string;
+    /** W3C span id — unique to this call. */
+    spanId: string;
+    /** Parent span id, when this call is nested under another. */
+    parentSpanId?: string;
+    /** Whether the call succeeded. */
+    ok: boolean;
+    /** HTTP status — the real status for HTTP, `200` / `400` for a tool call. */
+    statusCode: number;
+    /** Wall-clock duration. */
+    durationMs: number;
+    /** Error code — failures only. */
+    errorCode?: string;
+    /** Error message — failures only. */
+    errorMessage?: string;
+    /** Sanitised request payload — the HTTP body or the tool arguments. */
+    payload: JsonValue | null;
+    /** Item count of the result, when it is a list. */
+    resultSize: number | null;
+    /** Serialised byte length of the result. */
+    responseBytes: number;
+    /** Resolved user id, when authenticated. */
+    userId?: string;
+    /** Client IP. */
+    ipAddress?: string;
+    /** Client user-agent. */
+    userAgent?: string;
+    /** When the call started. */
+    startedAt: Date;
+}
+//# sourceMappingURL=event.d.ts.map

package/dist/observability/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/observability/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,mDAAmD;IACnD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CACjB"}

package/dist/observability/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `stitchkit/observability` — the audit layer one level above the raw hooks.
+ *
+ * W3C trace context, an `AsyncLocalStorage` request context, payload
+ * sanitisation, a normalised `RequestEvent`, and `createAuditHook` to wire it
+ * all into one sink. A project's logging becomes a table plus a `write`
+ * function — nothing else.
+ */
+export { type AuditConfig, type AuditHook, createAuditHook } from './audit';
+export { getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, setRequestError, setRequestUser, wrapInRequestContext, } from './context';
+export type { RequestEvent } from './event';
+export { type JsonValue, measureSize, redact, type SanitizeOptions, type SizeMeasure, sanitizePayload, truncatePreview, } from './sanitize';
+export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, resolveTraceContext, type TraceContext, } from './trace';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,266 @@
+import {
+  isRecord
+} from "../index-809wc1tt.js";
+import {
+  getClientInfo
+} from "../index-ke4mx4ea.js";
+
+// src/observability/context.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// src/observability/trace.ts
+var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
+function randomHex(bytes) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  let hex = "";
+  for (const byte of arr)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+function createTraceContext() {
+  return { traceId: randomHex(16), spanId: randomHex(8) };
+}
+function parseTraceparent(header) {
+  if (!header)
+    return null;
+  const match = TRACEPARENT_RE.exec(header.trim());
+  if (!match?.[1] || !match[2])
+    return null;
+  return {
+    traceId: match[1].toLowerCase(),
+    spanId: randomHex(8),
+    parentSpanId: match[2].toLowerCase()
+  };
+}
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-01`;
+}
+function resolveTraceContext(req) {
+  return parseTraceparent(req.headers.get("traceparent")) ?? createTraceContext();
+}
+function childSpan(parent) {
+  return {
+    traceId: parent.traceId,
+    spanId: randomHex(8),
+    parentSpanId: parent.spanId
+  };
+}
+
+// src/observability/context.ts
+var storage = new AsyncLocalStorage;
+function runWithRequestContext(ctx, fn) {
+  return storage.run(ctx, fn);
+}
+function getRequestContext() {
+  return storage.getStore();
+}
+function getTraceId() {
+  return storage.getStore()?.trace.traceId;
+}
+function getUserId() {
+  return storage.getStore()?.userId;
+}
+function setRequestUser(userId) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.userId = userId;
+}
+function setRequestError(error) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.error = error;
+}
+function wrapInRequestContext(handler) {
+  return (req, server) => {
+    const ctx = {
+      trace: resolveTraceContext(req),
+      source: "http",
+      method: req.method,
+      path: new URL(req.url).pathname,
+      startedAt: process.hrtime.bigint(),
+      ...getClientInfo(req)
+    };
+    return runWithRequestContext(ctx, () => handler(req, server));
+  };
+}
+
+// src/observability/sanitize.ts
+var DEFAULT_SENSITIVE_KEYS = /(password|passwd|pwd|secret|token|apikey|api[-_ ]?key|auth|authorization|bearer|session|cookie|init[-_ ]?data|credential|private[-_ ]?key)/i;
+var DEFAULT_MAX_BYTES = 16000;
+var DEFAULT_MAX_DEPTH = 20;
+var MASK = "[redacted]";
+function redact(value, options = {}) {
+  const sensitive = options.sensitiveKeys ?? DEFAULT_SENSITIVE_KEYS;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const walk = (input, depth) => {
+    if (depth > maxDepth)
+      return "[max depth]";
+    if (input === null || input === undefined)
+      return null;
+    if (typeof input === "string" || typeof input === "number" || typeof input === "boolean") {
+      return input;
+    }
+    if (input instanceof Uint8Array || input instanceof ArrayBuffer) {
+      return { _type: "binary", size: input.byteLength };
+    }
+    if (input instanceof Blob) {
+      return { _type: "blob", size: input.size, mime: input.type };
+    }
+    if (typeof FormData !== "undefined" && input instanceof FormData) {
+      return { _type: "formdata", keys: [...input.keys()] };
+    }
+    if (Array.isArray(input)) {
+      return input.map((item) => walk(item, depth + 1));
+    }
+    if (isRecord(input)) {
+      const out = {};
+      for (const [key, val] of Object.entries(input)) {
+        out[key] = sensitive.test(key) ? MASK : walk(val, depth + 1);
+      }
+      return out;
+    }
+    return String(input);
+  };
+  return walk(value, 0);
+}
+function truncatePreview(value, maxBytes = DEFAULT_MAX_BYTES) {
+  const json = JSON.stringify(value);
+  if (json.length <= maxBytes)
+    return value;
+  return {
+    _truncated: true,
+    _originalBytes: json.length,
+    preview: `${json.slice(0, maxBytes)}…`
+  };
+}
+function sanitizePayload(value, options = {}) {
+  if (value === undefined || value === null)
+    return null;
+  return truncatePreview(redact(value, options), options.maxBytes ?? DEFAULT_MAX_BYTES);
+}
+function measureSize(value) {
+  if (value === undefined || value === null) {
+    return { resultSize: null, responseBytes: 0 };
+  }
+  const responseBytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+  if (Array.isArray(value)) {
+    return { resultSize: value.length, responseBytes };
+  }
+  if (typeof value === "object" && "items" in value && Array.isArray(value.items)) {
+    return { resultSize: value.items.length, responseBytes };
+  }
+  return { resultSize: null, responseBytes };
+}
+
+// src/observability/audit.ts
+var BODY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+function toolErrorMessage(result) {
+  const { details, hint } = result;
+  if (isRecord(details) && typeof details.message === "string") {
+    return details.message;
+  }
+  return hint;
+}
+function readString(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function createAuditHook(config) {
+  const { write, filter, sanitize } = config;
+  const emit = async (event) => {
+    try {
+      if (filter && !filter(event))
+        return;
+      await write(event);
+    } catch {}
+  };
+  const http = (handler) => {
+    return async (req, server) => {
+      const bodyClone = BODY_METHODS.has(req.method) ? req.clone() : null;
+      const res = await handler(req, server);
+      const ctx = getRequestContext();
+      if (ctx) {
+        const durationMs = Math.round(Number(process.hrtime.bigint() - ctx.startedAt) / 1e6);
+        (async () => {
+          let body;
+          if (bodyClone) {
+            try {
+              body = await bodyClone.json();
+            } catch {
+              body = undefined;
+            }
+          }
+          await emit({
+            source: ctx.source,
+            method: ctx.method,
+            path: ctx.path,
+            traceId: ctx.trace.traceId,
+            spanId: ctx.trace.spanId,
+            parentSpanId: ctx.trace.parentSpanId,
+            ok: res.status < 400,
+            statusCode: res.status,
+            durationMs,
+            errorCode: ctx.error?.code,
+            errorMessage: ctx.error?.message,
+            payload: sanitizePayload(body, sanitize),
+            resultSize: null,
+            responseBytes: 0,
+            userId: ctx.userId,
+            ipAddress: ctx.ipAddress,
+            userAgent: ctx.userAgent,
+            startedAt: new Date(Date.now() - durationMs)
+          });
+        })();
+      }
+      return res;
+    };
+  };
+  const toolCall = {
+    afterToolCall: (toolName, args, result, durationMs, context) => {
+      const parent = getRequestContext()?.trace;
+      const span = parent ? childSpan(parent) : createTraceContext();
+      const measure = result.ok ? measureSize(result.data) : { resultSize: null, responseBytes: 0 };
+      emit({
+        source: context.source,
+        method: "TOOL",
+        path: `/${context.source}/${toolName}`,
+        toolName,
+        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 : toolErrorMessage(result),
+        payload: sanitizePayload(args, sanitize),
+        resultSize: measure.resultSize,
+        responseBytes: measure.responseBytes,
+        userId: readString(context.userId),
+        ipAddress: readString(context.ipAddress),
+        userAgent: readString(context.userAgent),
+        startedAt: new Date(Date.now() - durationMs)
+      });
+    }
+  };
+  return { http, toolCall };
+}
+export {
+  wrapInRequestContext,
+  truncatePreview,
+  setRequestUser,
+  setRequestError,
+  sanitizePayload,
+  runWithRequestContext,
+  resolveTraceContext,
+  redact,
+  parseTraceparent,
+  measureSize,
+  getUserId,
+  getTraceId,
+  getRequestContext,
+  formatTraceparent,
+  createTraceContext,
+  createAuditHook,
+  childSpan
+};

package/dist/observability/sanitize.d.ts

@@ -0,0 +1,42 @@
+/** A JSON-serialisable value — what a sanitised payload always reduces to. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Tuning for `redact` / `sanitizePayload`. */
+export interface SanitizeOptions {
+    /** Keys whose VALUE is masked. Default covers passwords, tokens, secrets… */
+    sensitiveKeys?: RegExp;
+    /** Cap on the serialised payload — anything larger collapses to a preview. Default 16 KB. */
+    maxBytes?: number;
+    /** Recursion limit — deeper nesting collapses to a marker. Default 20. */
+    maxDepth?: number;
+}
+/** The result of `measureSize`. */
+export interface SizeMeasure {
+    /** Item count, when the value is a list (or a `{ items: [] }` page). */
+    resultSize: number | null;
+    /** Serialised byte length. */
+    responseBytes: number;
+}
+/**
+ * Deep-copy `value` into a JSON-safe shape: secret-named keys masked, binary
+ * blobs reduced to `{ _type, size }` metadata, branches past `maxDepth`
+ * truncated. Always returns a `JsonValue` — safe to store directly.
+ */
+export declare function redact(value: unknown, options?: SanitizeOptions): JsonValue;
+/**
+ * Cap a `JsonValue` by serialised size — anything over `maxBytes` collapses to
+ * a `{ _truncated, _originalBytes, preview }` marker.
+ */
+export declare function truncatePreview(value: JsonValue, maxBytes?: number): JsonValue;
+/**
+ * Sanitise an arbitrary payload for an audit row — `redact` then
+ * `truncatePreview`. `null` / `undefined` reduce to `null`.
+ */
+export declare function sanitizePayload(value: unknown, options?: SanitizeOptions): JsonValue | null;
+/**
+ * Measure a result for the audit row — item count when it is a list (a bare
+ * array or a `{ items: [] }` page), and the serialised byte length.
+ */
+export declare function measureSize(value: unknown): SizeMeasure;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/observability/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/observability/sanitize.ts"],"names":[],"mappings":"AAMA,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8BAA8B;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB;AASD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,SAAS,CAsC/E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,SAAoB,GAAG,SAAS,CAQzF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,eAAoB,GAC5B,SAAS,GAAG,IAAI,CAGlB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAYvD"}

package/dist/observability/trace.d.ts

@@ -0,0 +1,42 @@
+/**
+ * W3C Trace Context — `traceparent` parsing, formatting and span chaining.
+ *
+ * `traceparent` format: `00-{traceId:32hex}-{spanId:16hex}-{flags:2hex}`.
+ * Spec: https://www.w3.org/TR/trace-context/
+ *
+ * A trace id is stable across every span of one logical request — it ties the
+ * front-end call, the HTTP handler and each nested tool call into one timeline.
+ * A span id is unique to a single operation within that trace.
+ */
+/** A point in a distributed trace — one trace, one span, an optional parent. */
+export interface TraceContext {
+    /** 32-hex trace id — stable across every span of one logical request. */
+    traceId: string;
+    /** 16-hex span id — unique to this operation. */
+    spanId: string;
+    /** 16-hex id of the span that caused this one, when there is one. */
+    parentSpanId?: string;
+}
+/** A fresh root trace — a new trace id, a new span id, no parent. */
+export declare function createTraceContext(): TraceContext;
+/**
+ * Parse a `traceparent` header into a `TraceContext`. The inbound span id
+ * becomes THIS context's `parentSpanId` and a fresh span id is minted — the
+ * receiver opens a new span under the caller's trace. Returns `null` for a
+ * missing or malformed header.
+ */
+export declare function parseTraceparent(header: string | null | undefined): TraceContext | null;
+/** Render a `TraceContext` as a `traceparent` header value (sampled flag `01`). */
+export declare function formatTraceparent(ctx: TraceContext): string;
+/**
+ * The trace for an incoming request — the caller's `traceparent` continued
+ * when present and valid, else a fresh root trace.
+ */
+export declare function resolveTraceContext(req: Request): TraceContext;
+/**
+ * A child span of `parent` — the same trace id, a fresh span id, `parentSpanId`
+ * set to the parent's span. Open one per nested operation (e.g. each tool call
+ * inside an HTTP request).
+ */
+export declare function childSpan(parent: TraceContext): TraceContext;
+//# sourceMappingURL=trace.d.ts.map

package/dist/observability/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/observability/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAaD,qEAAqE;AACrE,wBAAgB,kBAAkB,IAAI,YAAY,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CASvF;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAM5D"}

package/dist/react/cache-bridge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Cache bridge — wire socket events into the TanStack Query cache.
+ *
+ * Transport-agnostic: works with ANY emitter exposing `on(event, handler) =>
+ * unsubscribe` — socket.io, stitchkit's `SocketClient`, an `EventTarget`
+ * wrapper. `TEvents` is a socket.io-style event map (`{ event: (payload) =>
+ * void }`, i.e. `ServerToClientEvents`) — so the whole family (all on
+ * socket.io) shares one cache-sync helper.
+ *
+ * Each handler updates `queryClient` in response to a typed server event.
+ * `markFresh(key)` (called from a mutation's onSuccess) records a key as
+ * just-mutated; a handler calls `ctx.isFresh(key)` to skip a stale socket echo
+ * and avoid a double update (mutation result + socket event).
+ */
+import type { QueryClient, QueryKey } from '@tanstack/react-query';
+/** Minimal emitter — subscribe to an event, get an unsubscribe back. */
+export interface CacheBridgeSocket<TEvents> {
+    on<K extends keyof TEvents & string>(event: K, handler: TEvents[K]): () => void;
+}
+export interface CacheBridgeContext {
+    queryClient: QueryClient;
+    /** True if `markFresh(key)` was called for this key within `freshWindow` ms. */
+    isFresh(key: QueryKey): boolean;
+}
+/** Payload of a socket.io-style event entry `(payload) => void`. */
+type EventPayload<T> = T extends (payload: infer P) => unknown ? P : never;
+export type CacheBridgeHandler<TPayload> = (data: TPayload, ctx: CacheBridgeContext) => void;
+export type CacheBridgeHandlers<TEvents> = {
+    [K in keyof TEvents & string]?: CacheBridgeHandler<EventPayload<TEvents[K]>>;
+};
+export interface CacheBridgeConfig<TEvents> {
+    socket: CacheBridgeSocket<TEvents>;
+    /**
+     * The TanStack Query client, or a thunk returning it. A thunk is resolved
+     * lazily at `connect()` time — keeps the bridge SSR-safe when it lives in a
+     * module-level `const` (client components are still evaluated on the server,
+     * where a browser-only `QueryClient` does not exist yet).
+     */
+    queryClient: QueryClient | (() => QueryClient);
+    handlers: CacheBridgeHandlers<TEvents>;
+    /** Window (ms) after `markFresh()` during which `isFresh()` returns true. Default 500. */
+    freshWindow?: number;
+}
+export interface CacheBridge {
+    connect(): void;
+    disconnect(): void;
+    /** Mark a query key as just-mutated. Call from a mutation's onSuccess so
+     *  handlers can skip a stale socket echo via `ctx.isFresh()`. */
+    markFresh(key: QueryKey): void;
+}
+export declare function createCacheBridge<TEvents>(config: CacheBridgeConfig<TEvents>): CacheBridge;
+export {};
+//# sourceMappingURL=cache-bridge.d.ts.map

package/dist/react/cache-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-bridge.d.ts","sourceRoot":"","sources":["../../src/react/cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,wEAAwE;AACxE,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;CACjF;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC;CACjC;AAED,oEAAoE;AACpE,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E,MAAM,MAAM,kBAAkB,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7F,MAAM,MAAM,mBAAmB,CAAC,OAAO,IAAI;KACxC,CAAC,IAAI,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E,CAAC;AAEF,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,WAAW,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAC;IAC/C,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACvC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB;qEACiE;IACjE,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;CAChC;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,WAAW,CA8C1F"}