@bitfab/sdk 0.28.9 → 0.28.11

package/dist/index.d.cts

@@ -96,6 +96,32 @@ declare function flushTraces(timeoutMs?: number): Promise<void>;
  * case) is still picked up.
  */
 type ApiKeyInput = string | (() => string | undefined);
+type SpanOccurrence = "first" | "last" | number;
+type SpanLookup = {
+    id: string;
+    name?: never;
+    occurrence?: never;
+} | {
+    name: string;
+    id?: never;
+    occurrence?: SpanOccurrence;
+};
+interface CapturedSpan {
+    id: string;
+    traceId: string;
+    parentSpanId: string | null;
+    name: string | null;
+    type: string;
+    input: unknown;
+    output: unknown;
+    contexts: Record<string, unknown>[];
+    prompt: string | null;
+    metadata: Record<string, unknown>;
+    metrics: Record<string, unknown> | null;
+    errors: unknown;
+    startedAt: string | null;
+    endedAt: string | null;
+}
 interface TokenUsage {
     input: number | null;
     output: number | null;
@@ -861,6 +887,8 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
     private activeTraces;
     private readonly getActiveSpanContext;
     private activeSpanMappings;
+    private canonicalTraceIds;
+    private getCanonicalTraceId;
     /**
      * Initialize the tracing processor.
      *
@@ -951,6 +979,8 @@ interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
  * A handle to the current active span, allowing context to be added.
  */
 interface CurrentSpan {
+    /** The Bitfab ID for the current span. */
+    readonly id: string;
     /** The trace ID for the current span. */
     readonly traceId: string;
     /**
@@ -966,7 +996,7 @@ interface CurrentSpan {
 }
 /**
  * A detached handle to a previously-created trace, looked up by its
- * caller-supplied id (the same id passed when the trace was started).
+ * canonical Bitfab trace ID.
  *
  * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage -
  * each method sends to the server immediately. Useful for adding context
@@ -974,7 +1004,7 @@ interface CurrentSpan {
  * agent that wants to annotate the original conversation's trace).
  */
 interface DetachedTrace {
-    /** The caller-supplied trace id this handle resolves. */
+    /** The canonical Bitfab trace ID this handle resolves. */
     readonly traceId: string;
     /**
      * Append a context entry to this trace. Each call adds one entry to the
@@ -1394,25 +1424,30 @@ declare class Bitfab {
     withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
     /**
      * Get a detached handle to a previously-created trace, looked up by the
-     * caller-supplied id (the same id passed at trace creation).
+     * canonical Bitfab trace ID.
      *
      * The returned handle is not tied to AsyncLocalStorage - each method sends
      * to the server immediately. Useful for adding context to a trace from a
      * different process or thread than the one that created it.
      *
-     * Throws synchronously if `traceId` is malformed (empty, too long, or
-     * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
-     * no trace exists with that id in the org; the failure surfaces as a
+     * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+     * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
      * logged warning (fire-and-forget) or via the awaited promise.
      *
      * Example:
      * ```typescript
-     * const trace = client.getTrace("order_abc_123");
+     * const trace = client.getTrace(traceId);
      * await trace.addContext({ refund_status: "approved" });
      * await trace.setMetadata({ region: "us-west" });
      * ```
      */
     getTrace(traceId: string): DetachedTrace;
+    /**
+     * Fetch one persisted span from a trace without loading the full trace.
+     * Name lookups return the last matching span by default. Pass `occurrence`
+     * as `"first"` or a zero-based index to select a different match.
+     */
+    getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
     /**
      * Get a function wrapper for a specific trace function key.
      *
@@ -1614,7 +1649,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.28.9";
+declare const __version__ = "0.28.11";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1682,4 +1717,4 @@ 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 CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+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 CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, 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, getCurrentSpan, getCurrentTrace, reportReplayProgress };

package/dist/index.d.ts

@@ -96,6 +96,32 @@ declare function flushTraces(timeoutMs?: number): Promise<void>;
  * case) is still picked up.
  */
 type ApiKeyInput = string | (() => string | undefined);
+type SpanOccurrence = "first" | "last" | number;
+type SpanLookup = {
+    id: string;
+    name?: never;
+    occurrence?: never;
+} | {
+    name: string;
+    id?: never;
+    occurrence?: SpanOccurrence;
+};
+interface CapturedSpan {
+    id: string;
+    traceId: string;
+    parentSpanId: string | null;
+    name: string | null;
+    type: string;
+    input: unknown;
+    output: unknown;
+    contexts: Record<string, unknown>[];
+    prompt: string | null;
+    metadata: Record<string, unknown>;
+    metrics: Record<string, unknown> | null;
+    errors: unknown;
+    startedAt: string | null;
+    endedAt: string | null;
+}
 interface TokenUsage {
     input: number | null;
     output: number | null;
@@ -861,6 +887,8 @@ declare class BitfabOpenAITracingProcessor implements TracingProcessor {
     private activeTraces;
     private readonly getActiveSpanContext;
     private activeSpanMappings;
+    private canonicalTraceIds;
+    private getCanonicalTraceId;
     /**
      * Initialize the tracing processor.
      *
@@ -951,6 +979,8 @@ interface WrappedBamlFn<TArgs extends unknown[], TReturn> {
  * A handle to the current active span, allowing context to be added.
  */
 interface CurrentSpan {
+    /** The Bitfab ID for the current span. */
+    readonly id: string;
     /** The trace ID for the current span. */
     readonly traceId: string;
     /**
@@ -966,7 +996,7 @@ interface CurrentSpan {
 }
 /**
  * A detached handle to a previously-created trace, looked up by its
- * caller-supplied id (the same id passed when the trace was started).
+ * canonical Bitfab trace ID.
  *
  * Unlike `getCurrentTrace()`, this handle is not tied to AsyncLocalStorage -
  * each method sends to the server immediately. Useful for adding context
@@ -974,7 +1004,7 @@ interface CurrentSpan {
  * agent that wants to annotate the original conversation's trace).
  */
 interface DetachedTrace {
-    /** The caller-supplied trace id this handle resolves. */
+    /** The canonical Bitfab trace ID this handle resolves. */
     readonly traceId: string;
     /**
      * Append a context entry to this trace. Each call adds one entry to the
@@ -1394,25 +1424,30 @@ declare class Bitfab {
     withSpan<TArgs extends unknown[], TReturn>(traceFunctionKey: string, optionsOrFn: SpanOptions | ((...args: TArgs) => TReturn), maybeFn?: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
     /**
      * Get a detached handle to a previously-created trace, looked up by the
-     * caller-supplied id (the same id passed at trace creation).
+     * canonical Bitfab trace ID.
      *
      * The returned handle is not tied to AsyncLocalStorage - each method sends
      * to the server immediately. Useful for adding context to a trace from a
      * different process or thread than the one that created it.
      *
-     * Throws synchronously if `traceId` is malformed (empty, too long, or
-     * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
-     * no trace exists with that id in the org; the failure surfaces as a
+     * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+     * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
      * logged warning (fire-and-forget) or via the awaited promise.
      *
      * Example:
      * ```typescript
-     * const trace = client.getTrace("order_abc_123");
+     * const trace = client.getTrace(traceId);
      * await trace.addContext({ refund_status: "approved" });
      * await trace.setMetadata({ region: "us-west" });
      * ```
      */
     getTrace(traceId: string): DetachedTrace;
+    /**
+     * Fetch one persisted span from a trace without loading the full trace.
+     * Name lookups return the last matching span by default. Pass `occurrence`
+     * as `"first"` or a zero-based index to select a different match.
+     */
+    getTraceSpan(traceId: string, lookup: SpanLookup): Promise<CapturedSpan | null>;
     /**
      * Get a function wrapper for a specific trace function key.
      *
@@ -1614,7 +1649,7 @@ declare class BitfabFunction {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.28.9";
+declare const __version__ = "0.28.11";
 
 /**
  * Constants for the Bitfab SDK.
@@ -1682,4 +1717,4 @@ 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 CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanOptions, type SpanType, type TokenUsage, type TraceResponse, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, finalizers, flushTraces, getCurrentSpan, getCurrentTrace, reportReplayProgress };
+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 CapturedSpan, type CodeChangeFile, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type MockStrategy, type ProviderDefinition, ReplayEnvironment, type ReplayEnvironmentSnapshot, type ReplayItem, type ReplayOptions, type ReplayProgress, type ReplayResult, SUPPORTED_PROVIDERS, type SpanLookup, 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, getCurrentSpan, getCurrentTrace, reportReplayProgress };

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   flushTraces,
   getCurrentSpan,
   getCurrentTrace
-} from "./chunk-VQ4GMKQ7.js";
+} from "./chunk-ZBWTCBVQ.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   BitfabError,

package/dist/node.cjs

@@ -697,7 +697,7 @@ registerAsyncLocalStorageClass(
 );
 
 // src/version.generated.ts
-var __version__ = "0.28.9";
+var __version__ = "0.28.11";
 
 // src/constants.ts
 var DEFAULT_SERVICE_URL = "https://bitfab.ai";
@@ -937,6 +937,50 @@ var HttpClient = class {
   async lookupFunction(name) {
     return this.request("/api/sdk/functions/lookup", { name });
   }
+  async getTraceSpan(traceId, lookup) {
+    const searchParams = new URLSearchParams();
+    if (lookup.id !== void 0) {
+      searchParams.set("id", lookup.id);
+    } else {
+      searchParams.set("name", lookup.name);
+      searchParams.set("occurrence", String(lookup.occurrence ?? "last"));
+    }
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}/span?${searchParams.toString()}`;
+    const response = await this.get(endpoint);
+    return response.span;
+  }
+  async get(endpoint) {
+    const url = `${this.serviceUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.resolveApiKey() ?? ""}` },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new BitfabError(
+          `HTTP ${response.status}: ${errorText.slice(0, 500)}`
+        );
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof BitfabError) {
+        throw error;
+      }
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          throw new BitfabError(`Request timed out after ${this.timeout}ms`);
+        }
+        throw new BitfabError(error.message);
+      }
+      throw new BitfabError("Unknown error occurred");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Send an internal trace (from BAML execution).
    * Fire-and-forget with awaitOnExit - doesn't block the caller.
@@ -993,12 +1037,12 @@ var HttpClient = class {
     });
   }
   /**
-   * Partial update of an existing external trace identified by sourceTraceId.
+   * Partial update of an existing trace identified by its Bitfab trace ID.
    * Used by the detached `client.getTrace(id)` handle. Fire-and-forget;
    * returns a tracked promise that callers may optionally await.
    */
-  patchTrace(sourceTraceId, payload) {
-    const endpoint = `/api/sdk/externalTraces/${encodeURIComponent(sourceTraceId)}`;
+  patchTrace(traceId, payload) {
+    const endpoint = `/api/sdk/traces/${encodeURIComponent(traceId)}`;
     return awaitOnExit(
       this.request(endpoint, payload, { method: "PATCH" })
     ).catch((error) => {
@@ -1336,6 +1380,7 @@ var BitfabClaudeAgentHandler = class {
     const traceId = this.ensureTrace();
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId: parentId ?? null,
@@ -1399,6 +1444,8 @@ var BitfabClaudeAgentHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1428,6 +1475,7 @@ var BitfabClaudeAgentHandler = class {
       externalTrace.metadata = metadata;
     }
     const traceData = {
+      id: traceId,
       type: "sdk-function",
       source: "typescript-sdk-claude-agent-sdk",
       traceFunctionKey: this.traceFunctionKey,
@@ -1696,6 +1744,7 @@ var BitfabClaudeAgentHandler = class {
     }
     Object.assign(llmContext, this.currentLlmUsage);
     const spanInfo = {
+      id: randomUuid(),
       spanId,
       traceId,
       parentId,
@@ -2342,6 +2391,7 @@ var BitfabLangGraphCallbackHandler = class {
     const contexts = Object.keys(lgMetadata).length > 0 ? [lgMetadata] : [];
     const { safe: safeInput, dropped: inputDropped } = toJsonSafeReport(inputData);
     const spanInfo = {
+      id: randomUuid(),
       spanId: runId,
       traceId: invocation.traceId,
       rootRunId: invocation.rootRunId,
@@ -2420,6 +2470,8 @@ var BitfabLangGraphCallbackHandler = class {
       rawSpan.parent_id = spanInfo.parentId;
     }
     const payload = {
+      id: spanInfo.id,
+      traceId: spanInfo.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2435,6 +2487,7 @@ var BitfabLangGraphCallbackHandler = class {
   sendTraceCompletion(rootSpan, activeContext) {
     const completed = activeContext === null;
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2454,6 +2507,7 @@ var BitfabLangGraphCallbackHandler = class {
   }
   sendTraceStart(rootSpan) {
     const traceData = {
+      id: rootSpan.traceId,
       type: "sdk-function",
       source: "typescript-sdk-langgraph",
       traceFunctionKey: this.traceFunctionKey,
@@ -2812,6 +2866,7 @@ var ReplayEnvironment = class {
 init_serialize();
 
 // src/tracing.ts
+init_randomUuid();
 var BitfabOpenAITracingProcessor = class {
   /**
    * Initialize the tracing processor.
@@ -2821,6 +2876,7 @@ var BitfabOpenAITracingProcessor = class {
   constructor(config) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
     this.httpClient = new HttpClient({
       apiKey: config.apiKey,
       serviceUrl: config.serviceUrl ?? DEFAULT_SERVICE_URL,
@@ -2828,6 +2884,15 @@ var BitfabOpenAITracingProcessor = class {
     });
     this.getActiveSpanContext = config.getActiveSpanContext ?? null;
   }
+  getCanonicalTraceId(sourceTraceId) {
+    const existing = this.canonicalTraceIds[sourceTraceId];
+    if (existing) {
+      return existing;
+    }
+    const created = randomUuid();
+    this.canonicalTraceIds[sourceTraceId] = created;
+    return created;
+  }
   /**
    * Called when a trace is started.
    * If there's an active withSpan context, the trace ID is remapped to the
@@ -2839,7 +2904,12 @@ var BitfabOpenAITracingProcessor = class {
     if (activeContext) {
       this.activeSpanMappings[trace.traceId] = activeContext;
     }
-    this.sendTrace(trace, activeContext ? { id: activeContext.traceId } : {});
+    const canonicalTraceId = activeContext?.traceId ?? this.getCanonicalTraceId(trace.traceId);
+    this.canonicalTraceIds[trace.traceId] = canonicalTraceId;
+    this.sendTrace(trace, {
+      id: canonicalTraceId,
+      sourceTraceId: activeContext?.traceId
+    });
   }
   /**
    * Called when a trace is ended.
@@ -2848,11 +2918,13 @@ var BitfabOpenAITracingProcessor = class {
    */
   async onTraceEnd(trace) {
     const mapping = this.activeSpanMappings[trace.traceId];
-    this.sendTrace(
-      trace,
-      mapping ? { id: mapping.traceId } : { completed: true }
-    );
+    this.sendTrace(trace, {
+      completed: mapping === void 0,
+      id: mapping?.traceId ?? this.getCanonicalTraceId(trace.traceId),
+      sourceTraceId: mapping?.traceId
+    });
     delete this.activeSpanMappings[trace.traceId];
+    delete this.canonicalTraceIds[trace.traceId];
     delete this.activeTraces[trace.traceId];
   }
   /**
@@ -2882,22 +2954,25 @@ var BitfabOpenAITracingProcessor = class {
   async shutdown(_timeout) {
     this.activeTraces = {};
     this.activeSpanMappings = {};
+    this.canonicalTraceIds = {};
   }
   /**
    * Send trace to Bitfab API (fire-and-forget).
    * When traceIdOverride is provided, the trace ID is remapped to link
    * the OpenAI trace into an outer withSpan trace.
    */
-  sendTrace(trace, overrides = {}) {
+  sendTrace(trace, options = {}) {
     try {
-      const { completed, ...traceOverrides } = overrides;
       const traceData = trace.toJSON();
-      Object.assign(traceData, traceOverrides);
+      if (options.sourceTraceId) {
+        traceData.id = options.sourceTraceId;
+      }
       this.httpClient.sendExternalTrace({
+        ...options.id && { id: options.id },
         type: "openai",
         source: "typescript-sdk-openai-tracing",
         externalTrace: traceData,
-        completed: completed ?? false
+        completed: options.completed ?? false
       });
     } catch {
     }
@@ -2983,6 +3058,7 @@ var BitfabOpenAITracingProcessor = class {
    */
   buildSpanPayload(serializedSpan, errors) {
     const payload = {
+      id: randomUuid(),
       type: "openai",
       source: "typescript-sdk-openai-tracing",
       sourceTraceId: serializedSpan.trace_id ?? "unknown",
@@ -3005,6 +3081,10 @@ var BitfabOpenAITracingProcessor = class {
     this.extractSpanInputResponse(span, serializedSpan, errors);
     this.applySpanOverrides(serializedSpan, span.traceId ?? "");
     const payload = this.buildSpanPayload(serializedSpan, errors);
+    const canonicalTraceId = span.traceId ? this.getCanonicalTraceId(span.traceId) : void 0;
+    if (canonicalTraceId) {
+      payload.traceId = canonicalTraceId;
+    }
     this.httpClient.sendExternalSpan(payload);
   }
 };
@@ -3143,8 +3223,11 @@ init_warnOnce();
 var activeTraceStates = /* @__PURE__ */ new Map();
 var pendingSpanPromises = /* @__PURE__ */ new Map();
 var asyncLocalStorage = null;
+var initializeAsyncContext = () => {
+  asyncLocalStorage ?? (asyncLocalStorage = createAsyncLocalStorage());
+};
 var asyncLocalStorageReady = asyncStorageReady.then(() => {
-  asyncLocalStorage = createAsyncLocalStorage();
+  initializeAsyncContext();
 });
 var browserSpanStack = [];
 function getSpanStack() {
@@ -3318,24 +3401,19 @@ function extractContextFromCollector(collector) {
     return null;
   }
 }
-var TRACE_ID_PATTERN = /^[a-zA-Z0-9_\-.:]+$/;
-var TRACE_ID_MAX_LENGTH = 256;
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function validateTraceId(traceId) {
-  if (typeof traceId !== "string" || traceId.length === 0) {
-    throw new BitfabError("traceId is required and must be a non-empty string");
+  if (typeof traceId !== "string" || !UUID_PATTERN.test(traceId)) {
+    throw new BitfabError("traceId must be a valid Bitfab trace ID");
   }
-  if (traceId.length > TRACE_ID_MAX_LENGTH) {
-    throw new BitfabError(
-      `traceId must be ${TRACE_ID_MAX_LENGTH} characters or fewer`
-    );
-  }
-  if (!TRACE_ID_PATTERN.test(traceId)) {
-    throw new BitfabError(
-      `traceId may only contain letters, digits, "_", "-", ".", ":"`
-    );
+}
+function validateSpanId(id) {
+  if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+    throw new BitfabError("id must be a valid Bitfab span ID");
   }
 }
 var noOpSpan = {
+  id: "",
   traceId: "",
   addContext() {
   },
@@ -3359,6 +3437,7 @@ function getCurrentSpan() {
     return noOpSpan;
   }
   return {
+    id: current.spanId,
     traceId: current.traceId,
     addContext(context) {
       try {
@@ -3913,6 +3992,7 @@ var Bitfab = class {
       if (!self.isTracingEnabled()) {
         return fn.apply(this, args);
       }
+      initializeAsyncContext();
       if (!asyncLocalStorage && !isAsyncStorageInitDone()) {
         return asyncLocalStorageReady.then(
           () => wrappedFn.apply(this, args)
@@ -4154,20 +4234,19 @@ var Bitfab = class {
   }
   /**
    * Get a detached handle to a previously-created trace, looked up by the
-   * caller-supplied id (the same id passed at trace creation).
+   * canonical Bitfab trace ID.
    *
    * The returned handle is not tied to AsyncLocalStorage - each method sends
    * to the server immediately. Useful for adding context to a trace from a
    * different process or thread than the one that created it.
    *
-   * Throws synchronously if `traceId` is malformed (empty, too long, or
-   * contains characters outside `[a-zA-Z0-9_\-.:]`). Server returns 404 if
-   * no trace exists with that id in the org; the failure surfaces as a
+   * Throws synchronously if `traceId` is not a valid Bitfab trace ID. The
+   * server returns 404 if no trace exists with that ID in the org; the failure surfaces as a
    * logged warning (fire-and-forget) or via the awaited promise.
    *
    * Example:
    * ```typescript
-   * const trace = client.getTrace("order_abc_123");
+   * const trace = client.getTrace(traceId);
    * await trace.addContext({ refund_status: "approved" });
    * await trace.setMetadata({ region: "us-west" });
    * ```
@@ -4207,6 +4286,33 @@ var Bitfab = class {
       }
     };
   }
+  /**
+   * Fetch one persisted span from a trace without loading the full trace.
+   * Name lookups return the last matching span by default. Pass `occurrence`
+   * as `"first"` or a zero-based index to select a different match.
+   */
+  async getTraceSpan(traceId, lookup) {
+    validateTraceId(traceId);
+    const hasId = lookup.id !== void 0;
+    const hasName = lookup.name !== void 0;
+    if (hasId === hasName) {
+      throw new BitfabError("Provide exactly one of id or name");
+    }
+    if (hasId) {
+      validateSpanId(lookup.id);
+    } else {
+      if (lookup.name.length === 0) {
+        throw new BitfabError("name must be a non-empty string");
+      }
+      const occurrence = lookup.occurrence ?? "last";
+      if (occurrence !== "first" && occurrence !== "last" && (!Number.isInteger(occurrence) || occurrence < 0)) {
+        throw new BitfabError(
+          'occurrence must be "first", "last", or a non-negative integer'
+        );
+      }
+    }
+    return this.httpClient.getTraceSpan(traceId, lookup);
+  }
   /**
    * Get a function wrapper for a specific trace function key.
    *
@@ -4265,6 +4371,7 @@ var Bitfab = class {
       };
     }
     return this.httpClient.sendExternalTrace({
+      id: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       traceFunctionKey: params.traceFunctionKey,
@@ -4320,6 +4427,8 @@ var Bitfab = class {
       externalSpan.input_source_span_id = params.inputSourceSpanId;
     }
     return this.httpClient.sendExternalSpan({
+      id: params.spanId,
+      traceId: params.traceId,
       type: "sdk-function",
       source: "typescript-sdk-function",
       sourceTraceId: params.traceId,