@bitfab/sdk 0.38.1 → 0.38.3

package/dist/index.d.cts

@@ -523,6 +523,7 @@ declare class HttpClient {
      * Blocks until complete - needed for function execution.
      */
     lookupFunction<T>(name: string): Promise<T>;
+    getAutoTracePolicy<T>(traceFunctionKey: string, protocol: string): Promise<T>;
     getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
     private get;
     /**
@@ -1233,7 +1234,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
-    /** Optional list of specific trace IDs to replay (max 100). */
+    /** Optional list of specific trace IDs to replay (max 100). Mutually exclusive with `datasetId`. */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
     name?: string;
@@ -1290,7 +1291,8 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `traceIds`. When
+     * set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -2098,6 +2100,27 @@ interface SpanMethodDecoratorContext<TThis, TValue> {
 }
 /** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
 type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
+/** Options for experimental automatic subtree tracing. */
+interface TraceOptions {
+    /** Root span name. Defaults to the decorated or wrapped function name. */
+    name?: string;
+    /** Root span type. Descendants are always `function` spans. */
+    type?: SpanType;
+    /** Maximum number of recorded descendant levels. Defaults to 30. */
+    maxDepth?: number;
+    /** Maximum descendant spans recorded per root invocation. Defaults to 500. */
+    maxSpans?: number;
+    /** Qualified or simple function names to leave out of the subtree. */
+    exclude?: readonly string[] | ReadonlySet<string>;
+    /** Record rest-argument wrapper functions. Defaults to false. */
+    includeWrappers?: boolean;
+}
+type StandardTraceMethodDecorator = <This, TArgs extends unknown[], TReturn>(method: (this: This, ...args: TArgs) => TReturn, context: {
+    kind: "method";
+    name: string | symbol;
+}) => (this: This, ...args: TArgs) => TReturn;
+type LegacyTraceMethodDecorator = <This, TArgs extends unknown[], TReturn>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(this: This, ...args: TArgs) => TReturn>) => void;
+type TraceMethodDecorator = StandardTraceMethodDecorator & LegacyTraceMethodDecorator;
 
 /**
  * Client for making provider-based API calls via BAML.
@@ -2117,6 +2140,7 @@ declare class Bitfab {
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
+    private readonly autoTracePolicyRefreshes;
     /**
      * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
      * to every `replay` on this client (after any per-call `mockOverride`). In
@@ -2129,6 +2153,37 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * Decorate a class method as an automatically expanded trace root.
+     *
+     * Build instrumentation turns repository functions called beneath this
+     * method into nested spans. Every generated span preserves structure; only
+     * function IDs selected by the capture policy include inputs and output.
+     * Without a compatible build transform, this still records the decorated
+     * method as a normal rich root span but cannot discover child calls.
+     *
+     * @param traceFunctionKey - Groups traces and their capture policy.
+     * @param options - Root presentation, subtree bounds, and exclusions.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    trace(traceFunctionKey: string, options?: TraceOptions): TraceMethodDecorator;
+    /**
+     * Wrap a function as an automatically expanded trace root.
+     *
+     * This is the function-oriented equivalent of {@link Bitfab.trace}. Build
+     * instrumentation turns repository functions called beneath the wrapped
+     * function into nested spans. Without a compatible transform, this still
+     * records one normal rich root span and runs the function unchanged.
+     *
+     * @param traceFunctionKey - Groups traces and their capture policy.
+     * @param optionsOrFn - Options or the workflow entrypoint to wrap.
+     * @param maybeFn - Workflow entrypoint when options are provided.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    private createAutoTraceRoot;
+    private refreshAutoTraceCapturePolicy;
     /**
      * Flush and permanently close this client's tracing resources: its pending
      * requests and the single span-transport worker shared by its decorators and
@@ -2663,7 +2718,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.1";
+declare const __version__ = "0.38.3";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2731,4 +2786,39 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayProgressItem, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">;
+interface ReplayRegistryContext {
+    /** Values supplied through `--params` and repeated `--param name=value`. */
+    params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+    /** Client instance used by the production traced function. */
+    client: Bitfab;
+    /** The exact traced function production calls. */
+    fn: ReplayFunction;
+    /**
+     * Required for handler-instrumented or otherwise plain callables. Omit for a
+     * `withSpan`-wrapped function and the registry reads the wrapper's key.
+     */
+    traceFunctionKey?: string;
+    /**
+     * Per-function replay behavior and defaults. Put executable configuration
+     * such as `mockOverride` and `adaptInputs` here; command-line values override
+     * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+     */
+    options?: ReplayRegistryOptions;
+    /** Build executable replay behavior from caller-supplied CLI parameters. */
+    optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.d.ts

@@ -523,6 +523,7 @@ declare class HttpClient {
      * Blocks until complete - needed for function execution.
      */
     lookupFunction<T>(name: string): Promise<T>;
+    getAutoTracePolicy<T>(traceFunctionKey: string, protocol: string): Promise<T>;
     getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
     private get;
     /**
@@ -1233,7 +1234,7 @@ interface ReplayOptions {
      * because either source already determines how many traces replay.
      */
     limit?: number;
-    /** Optional list of specific trace IDs to replay (max 100). */
+    /** Optional list of specific trace IDs to replay (max 100). Mutually exclusive with `datasetId`. */
     traceIds?: string[];
     /** Optional display name for the resulting experiment/test run. */
     name?: string;
@@ -1290,7 +1291,8 @@ interface ReplayOptions {
     /** Group ID to associate this replay with an experiment group for live streaming in Studio. */
     experimentGroupId?: string;
     /**
-     * Dataset this replay runs against. When set, the resulting experiment is
+     * Dataset this replay runs against. Mutually exclusive with `traceIds`. When
+     * set, the resulting experiment is
      * durably attributed to the dataset (stored on the test run), so it appears
      * under the dataset's experiments even if the trace lineage can't be
      * reconstructed. Validated server-side against the org.
@@ -2098,6 +2100,27 @@ interface SpanMethodDecoratorContext<TThis, TValue> {
 }
 /** A standard ECMAScript method decorator produced by {@link Bitfab.span}. */
 type SpanMethodDecorator = <TThis, TArgs extends unknown[], TReturn>(originalMethod: (this: TThis, ...args: TArgs) => TReturn, context: SpanMethodDecoratorContext<TThis, (this: TThis, ...args: TArgs) => TReturn>) => (this: TThis, ...args: TArgs) => TReturn;
+/** Options for experimental automatic subtree tracing. */
+interface TraceOptions {
+    /** Root span name. Defaults to the decorated or wrapped function name. */
+    name?: string;
+    /** Root span type. Descendants are always `function` spans. */
+    type?: SpanType;
+    /** Maximum number of recorded descendant levels. Defaults to 30. */
+    maxDepth?: number;
+    /** Maximum descendant spans recorded per root invocation. Defaults to 500. */
+    maxSpans?: number;
+    /** Qualified or simple function names to leave out of the subtree. */
+    exclude?: readonly string[] | ReadonlySet<string>;
+    /** Record rest-argument wrapper functions. Defaults to false. */
+    includeWrappers?: boolean;
+}
+type StandardTraceMethodDecorator = <This, TArgs extends unknown[], TReturn>(method: (this: This, ...args: TArgs) => TReturn, context: {
+    kind: "method";
+    name: string | symbol;
+}) => (this: This, ...args: TArgs) => TReturn;
+type LegacyTraceMethodDecorator = <This, TArgs extends unknown[], TReturn>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(this: This, ...args: TArgs) => TReturn>) => void;
+type TraceMethodDecorator = StandardTraceMethodDecorator & LegacyTraceMethodDecorator;
 
 /**
  * Client for making provider-based API calls via BAML.
@@ -2117,6 +2140,7 @@ declare class Bitfab {
     private readonly httpClient;
     private readonly bamlClient;
     private readonly dbSnapshot;
+    private readonly autoTracePolicyRefreshes;
     /**
      * Mock overrides registered via {@link Bitfab.registerMockOverride}, applied
      * to every `replay` on this client (after any per-call `mockOverride`). In
@@ -2129,6 +2153,37 @@ declare class Bitfab {
      * @param config - Configuration options for the client
      */
     constructor(config: BitfabConfig);
+    /**
+     * Decorate a class method as an automatically expanded trace root.
+     *
+     * Build instrumentation turns repository functions called beneath this
+     * method into nested spans. Every generated span preserves structure; only
+     * function IDs selected by the capture policy include inputs and output.
+     * Without a compatible build transform, this still records the decorated
+     * method as a normal rich root span but cannot discover child calls.
+     *
+     * @param traceFunctionKey - Groups traces and their capture policy.
+     * @param options - Root presentation, subtree bounds, and exclusions.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    trace(traceFunctionKey: string, options?: TraceOptions): TraceMethodDecorator;
+    /**
+     * Wrap a function as an automatically expanded trace root.
+     *
+     * This is the function-oriented equivalent of {@link Bitfab.trace}. Build
+     * instrumentation turns repository functions called beneath the wrapped
+     * function into nested spans. Without a compatible transform, this still
+     * records one normal rich root span and runs the function unchanged.
+     *
+     * @param traceFunctionKey - Groups traces and their capture policy.
+     * @param optionsOrFn - Options or the workflow entrypoint to wrap.
+     * @param maybeFn - Workflow entrypoint when options are provided.
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    withTrace<This, TArgs extends unknown[], TReturn>(traceFunctionKey: string, options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    private createAutoTraceRoot;
+    private refreshAutoTraceCapturePolicy;
     /**
      * Flush and permanently close this client's tracing resources: its pending
      * requests and the single span-transport worker shared by its decorators and
@@ -2663,7 +2718,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.38.1";
+declare const __version__ = "0.38.3";
 
 /**
  * Constants for the Bitfab SDK.
@@ -2731,4 +2786,39 @@ declare const finalizers: {
     readableStream: typeof readableStream;
 };
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayProgress, type ReplayProgressItem, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };
+type ReplayFunction = (...args: any[]) => unknown | Promise<unknown>;
+type ReplayRegistryOptions = Omit<ReplayOptions, "onItemStart" | "onItemFinish" | "onProgress">;
+interface ReplayRegistryContext {
+    /** Values supplied through `--params` and repeated `--param name=value`. */
+    params: Readonly<Record<string, unknown>>;
+}
+type ReplayOptionsFactory = (context: ReplayRegistryContext) => ReplayRegistryOptions | Promise<ReplayRegistryOptions>;
+interface ReplayRegistration {
+    /** Client instance used by the production traced function. */
+    client: Bitfab;
+    /** The exact traced function production calls. */
+    fn: ReplayFunction;
+    /**
+     * Required for handler-instrumented or otherwise plain callables. Omit for a
+     * `withSpan`-wrapped function and the registry reads the wrapper's key.
+     */
+    traceFunctionKey?: string;
+    /**
+     * Per-function replay behavior and defaults. Put executable configuration
+     * such as `mockOverride` and `adaptInputs` here; command-line values override
+     * overlapping scalar defaults such as `mock` and `maxConcurrency`.
+     */
+    options?: ReplayRegistryOptions;
+    /** Build executable replay behavior from caller-supplied CLI parameters. */
+    optionsFactory?: ReplayOptionsFactory;
+}
+type ReplayRegistry = Record<string, ReplayRegistration>;
+/**
+ * Define the project-owned list of replayable functions.
+ *
+ * The registry is deliberately data-only: the SDK owns the replay CLI, so an
+ * SDK upgrade can add replay features without regenerating the project file.
+ */
+declare function defineReplayRegistry<TRegistry extends ReplayRegistry>(registry: TRegistry): TRegistry;
+
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AllowedEnvVars, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, HttpClient, type MockOverride, type MockOverrideCtx, type MockStrategy, type MockValue, type NodeMatcher, type ProviderDefinition, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, serializeReplayResult };

package/dist/index.js

@@ -7,11 +7,13 @@ import {
   BitfabOpenAITracingProcessor,
   BitfabVercelAiHandler,
   SUPPORTED_PROVIDERS,
+  defineReplayRegistry,
   finalizers,
   getCurrentReplayBranch,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-WD4AO3BK.js";
+} from "./chunk-RJPHMJWO.js";
+import "./chunk-GFBQ2AMO.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,
@@ -23,7 +25,8 @@ import {
   flushTraces,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-MGA7ROIK.js";
+} from "./chunk-WX6AEFCP.js";
+import "./chunk-H6LZRFMN.js";
 export {
   BITFAB_PROGRESS_PREFIX,
   Bitfab,
@@ -41,6 +44,7 @@ export {
   ReplayError,
   SUPPORTED_PROVIDERS,
   __version__,
+  defineReplayRegistry,
   finalizers,
   flushTraces,
   getCurrentReplayBranch,