stitchkit 0.68.0 → 0.68.1

package/dist/{index-7pn02bgv.js → index-cszjsxy5.js}

@@ -1,22 +1,23 @@
+import {
+  contractToolMountable,
+  createToolRunner,
+  formatToolError
+} from "./index-7etq650s.js";
 import {
   coerceJsonArgs,
-  executeToolMethod,
   toolResultFromError
-} from "./index-avjd67h6.js";
+} from "./index-cz32amcb.js";
 import {
   isWithinDir
 } from "./index-sbdmyz75.js";
 import {
-  assertToolExtensionCompatible,
   assertUniqueToolName,
   buildToolPresentationSchema,
   projectRuntimeTool,
   projectToolSurface
 } from "./index-vkk06pv1.js";
 import {
-  mergeSchemas,
-  objectShapeKeys,
-  rebuildObject
+  objectShapeKeys
 } from "./index-6djpbnda.js";
 import {
   jsonSchemaFields
@@ -31,68 +32,6 @@ import {
   isRecord
 } from "./index-smpbdg6k.js";
 
-// src/tools/mount.ts
-import { z } from "zod";
-function applyExtend(base, extra) {
-  if (base instanceof z.ZodObject) {
-    assertToolExtensionCompatible(base, extra);
-    return rebuildObject(base, { ...extra, ...base.shape });
-  }
-  return z.intersection(z.object(extra), base);
-}
-function contractToolMountable(projected, extend) {
-  const method = projected.source;
-  const baseArgumentSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
-  const argumentSchema = projected.shouldExtend && extend ? applyExtend(baseArgumentSchema, extend.schema) : baseArgumentSchema;
-  return {
-    method,
-    name: projected.name,
-    argumentSchema,
-    presentationSchema: projected.presentationSchema,
-    shouldExtend: projected.shouldExtend
-  };
-}
-function collectTools(service, transport, config = {}) {
-  const { extend, flattenUnionInput = false, assertNames = true } = config;
-  const tools = [];
-  for (const projected of projectToolSurface({ services: [service] }, transport === "HTTP" ? "AGENT" : transport, {
-    extend,
-    flattenUnionInput,
-    assertNames,
-    assertUniqueNames: false
-  })) {
-    if (projected.kind !== "contract")
-      continue;
-    tools.push(contractToolMountable(projected, extend));
-  }
-  return tools;
-}
-function createToolRunner(config) {
-  const extension = config.extend ? {
-    schema: z.object(config.extend.schema),
-    resolve: config.extend.resolve
-  } : undefined;
-  return async function runOneToolCall(tool, rawArgs, context) {
-    return executeToolMethod(tool.method, tool.name, rawArgs, { ...config.context, ...context, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true, config.onOutputStrip ? (paths) => config.onOutputStrip?.(tool.name, paths) : undefined, tool.shouldExtend ? extension : undefined);
-  };
-}
-function formatToolError(result, toolName, errorHint) {
-  const err = { error: result.code };
-  if (result.details)
-    err.details = result.details;
-  const hints = [];
-  if (result.hint)
-    hints.push(result.hint);
-  if (errorHint && toolName) {
-    const global = errorHint(toolName, result.code);
-    if (global)
-      hints.push(global);
-  }
-  if (hints.length > 0)
-    err._hint = hints.join(" ");
-  return err;
-}
-
 // src/tools/runtime-tool.ts
 function defineRuntimeTool(definition) {
   if (definition.transports?.length === 0) {
@@ -175,7 +114,7 @@ function runtimeToolMountable(definition, assertName = true) {
 }
 
 // src/tools/cli-args.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 var NUMERIC_VALUE = /^-(\d+\.?\d*|\.\d+)$/;
 var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help"]);
 var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir"]);
@@ -284,27 +223,27 @@ class CliArgumentError extends Error {
   name = "CliArgumentError";
 }
 function unwrap(field) {
-  if (field instanceof z2.ZodOptional || field instanceof z2.ZodNullable || field instanceof z2.ZodDefault) {
+  if (field instanceof z.ZodOptional || field instanceof z.ZodNullable || field instanceof z.ZodDefault) {
     return unwrap(field.unwrap());
   }
   return field;
 }
 function classify(field) {
-  if (field instanceof z2.ZodBoolean)
+  if (field instanceof z.ZodBoolean)
     return "boolean";
-  if (field instanceof z2.ZodNumber)
+  if (field instanceof z.ZodNumber)
     return "number";
-  if (field instanceof z2.ZodBigInt)
+  if (field instanceof z.ZodBigInt)
     return "bigint";
-  if (field instanceof z2.ZodDate)
+  if (field instanceof z.ZodDate)
     return "date";
-  if (field instanceof z2.ZodEnum)
+  if (field instanceof z.ZodEnum)
     return "enum";
-  if (field instanceof z2.ZodArray)
+  if (field instanceof z.ZodArray)
     return "array";
-  if (field instanceof z2.ZodObject)
+  if (field instanceof z.ZodObject)
     return "object";
-  if (field instanceof z2.ZodString || field instanceof z2.ZodLiteral)
+  if (field instanceof z.ZodString || field instanceof z.ZodLiteral)
     return "string";
   return "other";
 }
@@ -324,11 +263,11 @@ function mergeField(fields, name, info) {
 }
 function collectSchemaFields(schema, fields) {
   const base = unwrap(schema);
-  if (base instanceof z2.ZodObject) {
+  if (base instanceof z.ZodObject) {
     for (const [name, raw] of Object.entries(base.shape)) {
       const fieldBase = unwrap(raw);
       const kind = classify(fieldBase);
-      if (kind === "array" && fieldBase instanceof z2.ZodArray) {
+      if (kind === "array" && fieldBase instanceof z.ZodArray) {
         mergeField(fields, name, { kind, elementKind: classify(unwrap(fieldBase.element)) });
       } else {
         mergeField(fields, name, { kind });
@@ -336,12 +275,12 @@ function collectSchemaFields(schema, fields) {
     }
     return;
   }
-  if (base instanceof z2.ZodUnion) {
+  if (base instanceof z.ZodUnion) {
     for (const option of base.def.options)
       collectSchemaFields(option, fields);
     return;
   }
-  if (base instanceof z2.ZodIntersection) {
+  if (base instanceof z.ZodIntersection) {
     collectSchemaFields(base.def.left, fields);
     collectSchemaFields(base.def.right, fields);
     return;
@@ -1735,4 +1674,4 @@ async function createCli(config) {
   return exit(downloadsOk ? exitCode : 1);
 }
 
-export { collectTools, createToolRunner, formatToolError, defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, pollUntilDone, createCli };
+export { defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, pollUntilDone, createCli };

package/dist/index-g2j2m6vv.js

@@ -0,0 +1,63 @@
+import {
+  collectTools,
+  createToolRunner
+} from "./index-7etq650s.js";
+import {
+  toolErrorFromResult
+} from "./index-cz32amcb.js";
+import {
+  assertUniqueToolName
+} from "./index-vkk06pv1.js";
+import {
+  AppError
+} from "./index-0w9abg87.js";
+
+// src/tools/invoker.ts
+function createToolInvoker(services, config) {
+  const serviceList = Array.isArray(services) ? services : [services];
+  const tools = new Map;
+  for (const service of serviceList) {
+    for (const tool of collectTools(service, config.transport, {
+      extend: config.extend,
+      flattenUnionInput: config.flattenUnionInput
+    })) {
+      assertUniqueToolName(tool.name, tools.has(tool.name), "in-process tool name");
+      tools.set(tool.name, tool);
+    }
+  }
+  const names = Object.freeze([...tools.keys()].sort());
+  const operation = (name) => {
+    const tool = tools.get(name);
+    if (tool)
+      return tool;
+    throw new AppError("NOT_FOUND", `Unknown tool: ${name}`, 404, {
+      available: names
+    });
+  };
+  const run = (name, args, options = {}) => {
+    const runTool = createToolRunner({
+      source: options.source ?? "internal",
+      context: options.context,
+      hooks: options.hooks,
+      lifecycle: options.lifecycle,
+      extend: config.extend,
+      coerceJsonArgs: config.coerceJsonArgs,
+      onOutputStrip: options.onOutputStrip
+    });
+    return runTool(operation(name), args);
+  };
+  return Object.freeze({
+    names,
+    invoke(name, args, options) {
+      return run(name, args, options);
+    },
+    async invokeOrThrow(name, args, options) {
+      const result = await run(name, args, options);
+      if (!result.ok)
+        throw toolErrorFromResult(result);
+      return result.data;
+    }
+  });
+}
+
+export { createToolInvoker };

package/dist/{index-nymn7wbg.js → index-nck3yx3y.js}

@@ -8,9 +8,6 @@ import {
   guardSignalCallback,
   reportSignalError
 } from "./index-pr0qsmjy.js";
-import {
-  ShutdownOptionsSchema
-} from "./index-dk6e56g0.js";
 import {
   extractIp,
   getClientInfo,
@@ -22,6 +19,9 @@ import {
   setRequestEndpoint,
   setRequestError
 } from "./index-69m2278y.js";
+import {
+  ShutdownOptionsSchema
+} from "./index-dk6e56g0.js";
 import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   errorCode,
@@ -2759,14 +2759,13 @@ function bunUnixRequest(options) {
         return;
       }
       const bytes = Math.min(chunkRemaining, wire.byteLength, MAX_BODY_CHUNK_BYTES);
-      enqueue(takeWire(bytes));
-      if (settled)
-        return;
+      const value = takeWire(bytes);
       chunkRemaining -= bytes;
       if (chunkRemaining === 0) {
         chunkRemaining = undefined;
         expectChunkCrlf = true;
       }
+      enqueue(value);
       return;
     }
   };
@@ -2816,7 +2815,7 @@ function bunUnixRequest(options) {
       }
       return;
     }
-    if (headerEnd > options.maxHeaderBytes) {
+    if (headerEnd + 4 > options.maxHeaderBytes) {
       fail(new UnixClientTransportError("UNIX_HEADERS_TOO_LARGE", `Unix response headers exceed the ${options.maxHeaderBytes} byte limit`, "response-received"));
       return;
     }
@@ -2988,6 +2987,9 @@ function responseHeaders2(response) {
   }
   return headers;
 }
+function isNodeHeaderOverflow(error) {
+  return typeof error === "object" && error !== null && Reflect.get(error, "code") === "HPE_HEADER_OVERFLOW";
+}
 function redirectedRequest(request, location, status, body) {
   const url = new URL(location, request.url);
   const changesToGet = status === 303 || (status === 301 || status === 302) && request.method === "POST";
@@ -3083,7 +3085,8 @@ function createUnixClientTransport(config) {
         method: request.method,
         headers,
         agent,
-        signal: request.signal
+        signal: request.signal,
+        maxHeaderSize: maxHeaderBytes
       }, resolveOnce);
       let connected = false;
       let requestStartBytes = 0;
@@ -3106,6 +3109,10 @@ function createUnixClientTransport(config) {
       timer.unref();
       outgoing.once("response", () => clearTimeout(timer));
       outgoing.once("error", (error) => {
+        if (isNodeHeaderOverflow(error)) {
+          rejectOnce(new UnixClientTransportError("UNIX_HEADERS_TOO_LARGE", `Unix response headers exceed the ${maxHeaderBytes} byte limit`, "response-received", { cause: error }));
+          return;
+        }
         const dispatched = connected && (outgoing.socket?.bytesWritten ?? requestStartBytes) > requestStartBytes;
         rejectOnce(new UnixClientTransportError(dispatched ? "UNIX_DELIVERY_UNCERTAIN" : "UNIX_CONNECT_FAILED", dispatched ? "Unix request transport failed after dispatch may have begun" : "Unix socket connection failed before request dispatch", dispatched ? "possibly-dispatched" : "not-dispatched", { cause: error }));
       });

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { type ClientConfig, type ClientContract, type ClientFetch, type ClientRegistryValue, type ContractClientConfig, contractEndpointMatchers, createClient, createClients, createScopedClients, createScopedUrlBuilders, createUrlBuilder, createUrlBuilders, type PathPrefixArgs, type RegistryScope, type ScopeClientConfigs, type ScopedClientRegistry, type ScopedUrlBuilderRegistry, type UrlBuilderConfig, } from './browser/client';
-export { ApiError, type ApiEvent, type ApiEventListener, type ConfiguredHttpClient, createHttpClient, type HeaderProvider, type HttpClient, type HttpClientConfig, type RequestOptions, type UnauthorizedMatcher, } from './browser/http';
-export type { BindRealtimeClientOptions, BoundRealtimeClient, RealtimeClient, RealtimeClientOptions, RealtimeClientTransport, SocketEventMap, SocketIOClient, SocketIOClientConfig, SocketIOClientPeerLoaders, } from './browser/socket-io';
-export { bindRealtimeClient, createRealtimeClient, createSocketIOClient, } from './browser/socket-io';
-export { type ParseNDJSONOptions, type ParseSSEOptions, parseNDJSON, parseSSE, } from './browser/stream';
-export * from './contract';
-export type { StitchLogger } from './logger';
-export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, type TraceContext, } from './observability/trace';
-export * from './realtime';
-export { createRetainedTopics, type RetainedTopics } from './retained';
+export { type ClientConfig, type ClientContract, type ClientFetch, type ClientRegistryValue, type ContractClientConfig, contractEndpointMatchers, createClient, createClients, createScopedClients, createScopedUrlBuilders, createUrlBuilder, createUrlBuilders, type PathPrefixArgs, type RegistryScope, type ScopeClientConfigs, type ScopedClientRegistry, type ScopedUrlBuilderRegistry, type UrlBuilderConfig, } from './browser/client.js';
+export { ApiError, type ApiEvent, type ApiEventListener, type ConfiguredHttpClient, createHttpClient, type HeaderProvider, type HttpClient, type HttpClientConfig, type RequestOptions, type UnauthorizedMatcher, } from './browser/http.js';
+export type { BindRealtimeClientOptions, BoundRealtimeClient, RealtimeClient, RealtimeClientOptions, RealtimeClientTransport, SocketEventMap, SocketIOClient, SocketIOClientConfig, SocketIOClientPeerLoaders, } from './browser/socket-io.js';
+export { bindRealtimeClient, createRealtimeClient, createSocketIOClient, } from './browser/socket-io.js';
+export { type ParseNDJSONOptions, type ParseSSEOptions, parseNDJSON, parseSSE, } from './browser/stream.js';
+export * from './contract/index.js';
+export type { StitchLogger } from './logger.js';
+export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, type TraceContext, } from './observability/trace.js';
+export * from './realtime/index.js';
+export { createRetainedTopics, type RetainedTopics } from './retained.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -464,8 +464,8 @@ class ApiError extends Error {
   details;
   hint;
   traceId;
-  constructor(code, status = 0, details, message, hint, traceId) {
-    super(message ?? `API Error: ${code}`);
+  constructor(code, status = 0, details, message, hint, traceId, options) {
+    super(message ?? `API Error: ${code}`, options);
     this.code = code;
     this.status = status;
     this.details = details;
@@ -1004,7 +1004,7 @@ function createFetchExecutor(endpoint, prefix, config, contractConfig) {
       if (ApiError.is(error))
         throw error;
       const message = error instanceof Error ? error.message : undefined;
-      throw new ApiError("UNKNOWN_ERROR", 0, message ? { message } : undefined, message);
+      throw new ApiError("UNKNOWN_ERROR", 0, message ? { message } : undefined, message, undefined, undefined, { cause: error });
     }
   };
 }
@@ -1446,7 +1446,7 @@ var SOCKET_IO_CLIENT = "socket.io-client";
 var ioLoader = null;
 function loadIo() {
   if (!ioLoader) {
-    ioLoader = import(SOCKET_IO_CLIENT).then((mod) => mod.io, (cause) => {
+    ioLoader = import(/* webpackIgnore: true */ SOCKET_IO_CLIENT).then((mod) => mod.io, (cause) => {
       ioLoader = null;
       throw new Error("stitchkit: createSocketIOClient needs the \"socket.io-client\" peer — install it (e.g. `bun add socket.io-client`). Shipping one self-contained artifact instead? Pass `peers: { client: () => import('socket.io-client') }` so your bundler puts it inside.", { cause });
     });

package/dist/internal/errors.d.ts

@@ -1,5 +1,5 @@
 import { type ZodType, z } from 'zod';
-import { AppError } from '../contract';
+import { AppError } from '../contract/index.js';
 export declare function formatZodError(error: z.ZodError): string;
 /** One field-level validation issue — the structured sibling of `formatZodError`. */
 export interface ZodIssueSummary {

package/dist/internal/observability-sink.d.ts

@@ -1,4 +1,4 @@
-import { type ObservabilitySinkStatus } from '../observability/status';
+import { type ObservabilitySinkStatus } from '../observability/status.js';
 export type BoundedSinkDropReason = 'capacity' | 'closed';
 export interface BoundedSinkError<EVENT> {
     error: unknown;

package/dist/node.d.ts

@@ -4,15 +4,15 @@
  * srvx-backed `serveNode`, `implement`, the error helpers and (lazily-loaded,
  * Node-safe) `createSocketIOServer`.
  */
-export { AppError, appError, badRequest, conflict, forbidden, notFound, rateLimited, unauthorized, } from './contract';
-export { createHandler } from './server/create';
-export { createImplement, createImplementRegistry, createMultipartStream, createScopedImplement, createScopedImplementRegistry, type ExactRegistryHandlers, type ExactScopedRegistryHandlers, type ImplementationRegistry, implement, implementRegistry, type KeyedServices, type MultipartStreamConfig, type RegistryHandlers, type ScopedImplementationRegistry, type ScopedRegistryHandlers, type StreamScope, } from './server/implement';
-export type { LogFormat } from './server/logger';
-export { type NodeRuntimeServer, type NodeServerConfig, type NodeServerHandle, type NodeSocketLifecycle, serveNode, } from './server/node';
-export { bindProcessSignals, type ProcessSignalName, type ProcessSignalsBinding, type ProcessSignalsErrorPhase, type ProcessSignalsOptions, type ShutdownTarget, type SignalSource, } from './server/process-signals';
-export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './server/realtime';
-export { type ManagedServerHandle, type ShutdownOptions, ShutdownOptionsSchema, type ShutdownResult, ShutdownResultSchema, type ShutdownState, ShutdownStateSchema, type ShutdownStatus, ShutdownStatusSchema, } from './server/shutdown';
-export { createNodeSocketIOServer as createSocketIOServer, type NodeSocketIOServerHandle as SocketIOServerHandle, type SocketIOHandshakeConfig, type SocketIOPeerLoaders, type SocketIORequestPolicy, type SocketIOServerConfig, } from './server/socket-io-node';
-export type { EffectiveScope, FetchComposition, FetchHandler, HandlerConfig, LoggingConfig, LogOutcome, RawRoute, RawRouteContext, ScopeContexts, ScopedHandlers, ServiceDef, } from './server/types';
-export { createUnixClientTransport, type UnixClientDeliveryState, type UnixClientTransport, type UnixClientTransportConfig, UnixClientTransportError, type UnixClientTransportErrorCode, } from './server/unix-client';
+export { AppError, appError, badRequest, conflict, forbidden, notFound, rateLimited, unauthorized, } from './contract/index.js';
+export { createHandler } from './server/create.js';
+export { createImplement, createImplementRegistry, createMultipartStream, createScopedImplement, createScopedImplementRegistry, type ExactRegistryHandlers, type ExactScopedRegistryHandlers, type ImplementationRegistry, implement, implementRegistry, type KeyedServices, type MultipartStreamConfig, type RegistryHandlers, type ScopedImplementationRegistry, type ScopedRegistryHandlers, type StreamScope, } from './server/implement.js';
+export type { LogFormat } from './server/logger.js';
+export { type NodeRuntimeServer, type NodeServerConfig, type NodeServerHandle, type NodeSocketLifecycle, serveNode, } from './server/node.js';
+export { bindProcessSignals, type ProcessSignalName, type ProcessSignalsBinding, type ProcessSignalsErrorPhase, type ProcessSignalsOptions, type ShutdownTarget, type SignalSource, } from './server/process-signals.js';
+export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './server/realtime.js';
+export { type ManagedServerHandle, type ShutdownOptions, ShutdownOptionsSchema, type ShutdownResult, ShutdownResultSchema, type ShutdownState, ShutdownStateSchema, type ShutdownStatus, ShutdownStatusSchema, } from './server/shutdown.js';
+export { createNodeSocketIOServer as createSocketIOServer, type NodeSocketIOServerHandle as SocketIOServerHandle, type SocketIOHandshakeConfig, type SocketIOPeerLoaders, type SocketIORequestPolicy, type SocketIOServerConfig, } from './server/socket-io-node.js';
+export type { EffectiveScope, FetchComposition, FetchHandler, HandlerConfig, LoggingConfig, LogOutcome, RawRoute, RawRouteContext, ScopeContexts, ScopedHandlers, ServiceDef, } from './server/types.js';
+export { createUnixClientTransport, type UnixClientDeliveryState, type UnixClientTransport, type UnixClientTransportConfig, UnixClientTransportError, type UnixClientTransportErrorCode, } from './server/unix-client.js';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.js

@@ -5,7 +5,7 @@ import {
   createHandler,
   createSocketIOServer,
   createUnixClientTransport
-} from "./index-nymn7wbg.js";
+} from "./index-nck3yx3y.js";
 import {
   createImplement,
   createImplementRegistry,
@@ -15,6 +15,7 @@ import {
   implement,
   implementRegistry
 } from "./index-pr0qsmjy.js";
+import"./index-69m2278y.js";
 import"./index-557by2db.js";
 import {
   ShutdownOptionsSchema,
@@ -23,7 +24,6 @@ import {
   ShutdownStatusSchema,
   createServerLifecycle
 } from "./index-dk6e56g0.js";
-import"./index-69m2278y.js";
 import"./index-9ky9hhg3.js";
 import"./index-smpbdg6k.js";
 import {

package/dist/observability/audit.d.ts

@@ -1,8 +1,8 @@
-import type { ToolCallHooks } from '../tools/execute';
-import { type RequestContext } from './context';
-import type { RequestEvent } from './event';
-import { type SanitizeOptions } from './sanitize';
-import { type ObservabilityDrainReport, type ObservabilityStatus } from './status';
+import type { ToolCallHooks } from '../tools/execute.js';
+import { type RequestContext } from './context.js';
+import type { RequestEvent } from './event.js';
+import { type SanitizeOptions } from './sanitize.js';
+import { type ObservabilityDrainReport, type ObservabilityStatus } from './status.js';
 /** One isolated RequestEvent sink and its sanitisation policy. */
 export interface RequestEventSinkConfig {
     /**

package/dist/observability/context.d.ts

@@ -1,5 +1,5 @@
-import type { TransportSource } from '../contract';
-import { type TraceContext } from './trace';
+import type { TransportSource } from '../contract/index.js';
+import { type TraceContext } from './trace.js';
 /** Everything known about the request in flight. */
 export interface RequestContext {
     /** W3C trace ids for this request. */

package/dist/observability/event.d.ts

@@ -1,5 +1,5 @@
-import type { HttpMethod, McpCallContext, TransportSource } from '../contract';
-import type { JsonValue } from './sanitize';
+import type { HttpMethod, McpCallContext, TransportSource } from '../contract/index.js';
+import type { JsonValue } from './sanitize.js';
 /**
  * A normalised audit event — one shape for a completed call on any surface
  * (an HTTP request, an MCP tool call, an agent tool call). `createObservability`

package/dist/observability/index.d.ts

@@ -6,10 +6,10 @@
  * framework-owned HTTP completion plus canonical tool hooks into independent
  * sinks.
  */
-export { createObservability, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit';
-export { getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, type WrapRequestContextOptions, wrapInRequestContext, } from './context';
-export type { RequestEvent } from './event';
-export { type JsonValue, measureSize, redact, type SanitizeOptions, type SizeMeasure, sanitizePayload, truncatePreview, } from './sanitize';
-export { type ObservabilityDrainReport, ObservabilityDrainReportSchema, type ObservabilitySinkStatus, ObservabilitySinkStatusSchema, type ObservabilityStatus, ObservabilityStatusSchema, } from './status';
-export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, resolvePropagationContext, resolveTraceContext, type TraceContext, } from './trace';
+export { createObservability, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit.js';
+export { getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, type WrapRequestContextOptions, wrapInRequestContext, } from './context.js';
+export type { RequestEvent } from './event.js';
+export { type JsonValue, measureSize, redact, type SanitizeOptions, type SizeMeasure, sanitizePayload, truncatePreview, } from './sanitize.js';
+export { type ObservabilityDrainReport, ObservabilityDrainReportSchema, type ObservabilitySinkStatus, ObservabilitySinkStatusSchema, type ObservabilityStatus, ObservabilityStatusSchema, } from './status.js';
+export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, resolvePropagationContext, resolveTraceContext, type TraceContext, } from './trace.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -4,7 +4,7 @@
  * infinite TanStack Query data without changing its envelope metadata.
  */
 import type { QueryKey } from '@tanstack/react-query';
-import type { CacheBridgeHandler } from './cache-bridge';
+import type { CacheBridgeHandler } from './cache-bridge.js';
 /** The `deleted` event may carry the whole entity or only its id. */
 export type DeletedPayload<TData> = TData | {
     id: string;
@@ -26,6 +26,27 @@ export type EntityCacheEvent<TData> = {
 /** A static cache key/prefix or an event-aware key factory. */
 export type EntityCacheKey<TData> = QueryKey | ((event: EntityCacheEvent<TData>) => QueryKey);
 export type EntityCacheListShape = 'array' | 'paginated' | 'infinite-array' | 'infinite-paginated';
+export type EntityCacheMembership = 'include' | 'exclude' | 'unknown';
+export interface EntityCacheMembershipPolicy<TData> {
+    /** Backend-equivalent membership for this exact cached query key. */
+    evaluate(event: EntityCacheEvent<TData>, queryKey: QueryKey): EntityCacheMembership;
+    /** What to do when the event cannot prove membership. Default `preserve`. */
+    unknown?: 'preserve' | 'invalidate';
+}
+export interface EntityCacheTotalDeltaInput<TData> {
+    event: EntityCacheEvent<TData>;
+    queryKey: QueryKey;
+    present: boolean;
+    membership: EntityCacheMembership;
+}
+export interface EntityCacheTotalPolicy<TData> {
+    /** Reconcile a numeric `total` field when the event proves a delta. */
+    mode: 'reconcile';
+    /** Override the conservative built-in delta when the event carries transition evidence. */
+    delta?(input: EntityCacheTotalDeltaInput<TData>): number | 'unknown';
+    /** What to do when an unseen id makes the delta unknowable. Default `preserve`. */
+    unknown?: 'preserve' | 'invalidate';
+}
 /** List envelope, scoped key and explicit CRUD policies. */
 export interface EntityCacheListConfig<TData, TListItem> {
     /** Static query-key prefix or an event-aware scoped key factory. */
@@ -38,6 +59,10 @@ export interface EntityCacheListConfig<TData, TListItem> {
     compare?: (left: TListItem, right: TListItem) => number;
     /** Cached data envelope; no runtime shape inference is performed. */
     shape: EntityCacheListShape;
+    /** Optional per-query filter membership. Omit for the envelope-preserving legacy path. */
+    membership?: EntityCacheMembershipPolicy<TData>;
+    /** Optional reconciliation of a numeric paginated `total` field. */
+    total?: EntityCacheTotalPolicy<TData>;
 }
 /** Config for `createEntityCacheHandlers`. */
 export interface EntityCacheConfig<TData, TListItem = TData> {

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

@@ -1 +1 @@
-{"version":3,"file":"entity-cache.d.ts","sourceRoot":"","sources":["../../src/react/entity-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,qEAAqE;AACrE,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,CAAC,KAAK,IAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAC5B,OAAO,GACP,WAAW,GACX,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB,CAAC,KAAK,EAAE,SAAS;IACrD,oEAAoE;IACpE,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC;IAC1B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;IACxD,qEAAqE;IACrE,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK;IACzD,uDAAuD;IACvD,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,MAAM,CAAC;IACjC,kEAAkE;IAClE,aAAa,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC;IAC3C,sEAAsE;IACtE,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC;IACzC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC;IAC1D,yEAAyE;IACzE,IAAI,EAAE,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9C,iFAAiF;IACjF,SAAS,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACxC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;CACpD;AAiJD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,EAChE,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,GAC1C,mBAAmB,CAAC,KAAK,CAAC,CAkD5B"}
+{"version":3,"file":"entity-cache.d.ts","sourceRoot":"","sources":["../../src/react/entity-cache.ts"],"names":[],"mappings":"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"}

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, } from './react/cache-bridge';
-export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query';
-export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheEvent, type EntityCacheHandlers, type EntityCacheKey, type EntityCacheListConfig, type EntityCacheListShape, } from './react/entity-cache';
+export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, } from './react/cache-bridge.js';
+export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query.js';
+export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheEvent, type EntityCacheHandlers, type EntityCacheKey, type EntityCacheListConfig, type EntityCacheListShape, type EntityCacheMembership, type EntityCacheMembershipPolicy, type EntityCacheTotalDeltaInput, type EntityCacheTotalPolicy, } from './react/entity-cache.js';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC"}