rivetkit 2.3.18 → 2.3.20

package/dist/tsup/agent-os/index.d.cts

@@ -543,6 +543,29 @@ declare class RivetError extends Error {
     toString(): string;
 }
 
+/** Sample rates keyed by action name, nested like the actor's action groups. */
+interface ActionSampleRates {
+    readonly [name: string]: number | ActionSampleRates;
+}
+/**
+ * {@link ActionSampleRates} limited to the actions of one actor, so a rate for
+ * an action that does not exist is a compile error.
+ */
+type ActionTraceSamplers<TActions> = {
+    readonly [K in keyof TActions]?: TActions[K] extends (...args: never[]) => unknown ? number : ActionTraceSamplers<TActions[K]>;
+};
+/** Trace sampling for one actor definition. */
+interface ActorTracingOptions<TActions> {
+    /**
+     * Share of this actor's invocations that are recorded, from 0 to 1. A rate
+     * lowers what is recorded and never raises it, so an invocation inside a
+     * trace the caller did not record is not recorded at any rate.
+     */
+    readonly sampler?: number;
+    /** Rates that replace `sampler` for single actions. */
+    readonly actions?: ActionTraceSamplers<TActions>;
+}
+
 type UpgradeWebSocket = (createEvents: (c: Context) => any) => Handler;
 type GetUpgradeWebSocket = () => UpgradeWebSocket;
 
@@ -624,6 +647,25 @@ interface ActorOutput {
     error?: unknown;
 }
 
+/** Correlation owned by the currently executing Core actor invocation. */
+interface ActorInvocationTraceContext {
+    /** Ray ID the invocation received, absent when nothing upstream supplied one. */
+    readonly rayId?: string;
+    /** Core-owned invocation span context, absent when tracing is disabled. */
+    readonly span?: ActorInvocationSpanContext;
+}
+/** W3C span context of the Core invocation span. */
+interface ActorInvocationSpanContext {
+    /** W3C trace identifier. */
+    readonly traceId: string;
+    /** W3C span identifier for the Core invocation. */
+    readonly spanId: string;
+    /** OpenTelemetry trace flags encoded as an integer. */
+    readonly traceFlags: number;
+    /** Optional vendor trace state inherited by the Core invocation. */
+    readonly tracestate?: string;
+}
+
 declare const handleBrand: unique symbol;
 type OpaqueHandle<Name extends string> = {
     readonly [handleBrand]: Name;
@@ -642,6 +684,27 @@ interface RuntimeActorKeySegment {
     stringValue?: string;
     numberValue?: number;
 }
+/** Resolves correlation at operation time so retained clients cannot freeze stale context. */
+type CurrentActorInvocation = () => ActorInvocationTraceContext | undefined;
+/** One open call from an actor out to another actor. */
+interface RuntimeOutboundCall {
+    /**
+     * W3C context of the call's own span, to send to the callee so it parents to
+     * the call. Absent when tracing is disabled.
+     */
+    readonly span?: ActorInvocationSpanContext;
+    /**
+     * Records the call's outcome. `error` is the failure encoded the way the
+     * bridge encodes errors, so a structured error keeps its group and code.
+     */
+    finish(error?: string): void;
+}
+/**
+ * Opens the span covering one call out to another actor, or returns `undefined`
+ * outside an invocation or on a runtime without invocation telemetry. Callers
+ * send their own context when it returns nothing.
+ */
+type StartCallSpan = (actorName: string, actionName: string) => RuntimeOutboundCall | undefined;
 interface RuntimeHttpRequest {
     method: string;
     uri: string;
@@ -802,12 +865,19 @@ interface RuntimeSqlBatchStatement {
 interface RuntimeSqlRunResult {
     changes: number;
 }
+/** Sample rates for the traces an actor starts, in the shape core takes. */
+interface RuntimeActorTracingConfig {
+    sampler?: number;
+    /** Keyed by flattened, dot-separated action name. */
+    actions?: Record<string, number>;
+}
 interface RuntimeActorConfig {
     name?: string;
     icon?: string;
     hasDatabase?: boolean;
     remoteSqlite?: boolean;
     sqliteProfiling?: SqliteProfilingOptions;
+    tracing?: RuntimeActorTracingConfig;
     enableActorRuntimeSocket?: boolean;
     hasState?: boolean;
     canHibernateWebsocket?: boolean;
@@ -939,6 +1009,7 @@ interface CoreRuntime {
     serveRegistry(registry: RegistryHandle, config: RuntimeServeConfig): Promise<void>;
     waitRegistryReady(registry: RegistryHandle): Promise<void>;
     shutdownRegistry(registry: RegistryHandle): Promise<void>;
+    shutdownTelemetry?(): Promise<void>;
     registryActorStopThresholdMs?(registry: RegistryHandle): Promise<number | undefined>;
     handleServerlessRequest(registry: RegistryHandle, req: RuntimeServerlessRequest, onStreamEvent: RuntimeServerlessStreamCallback, cancelToken: CancellationTokenHandle, config: RuntimeServeConfig): Promise<RuntimeServerlessResponseHead>;
     serveListener(registry: RegistryHandle, listener: RuntimeListenerConfig, config: RuntimeServeConfig): Promise<void>;
@@ -968,6 +1039,31 @@ interface CoreRuntime {
     actorSaveState(ctx: ActorContextHandle, payload: RuntimeStateDeltaPayload): Promise<void>;
     actorSaveStateAndWorkflowBatch(ctx: ActorContextHandle, writes: RuntimeWorkflowKvWrite[]): Promise<void>;
     actorId(ctx: ActorContextHandle): string;
+    /**
+     * Runs one actor callback with `ctx` as the current invocation: operations
+     * on retained handles for the same actor resolve to it, and its Core span
+     * is the active OpenTelemetry span for the duration of `run`. Only actions,
+     * raw requests, and queue dispatch run this way; other callbacks have no
+     * invocation span.
+     */
+    runWithActorInvocationContext<T>(ctx: ActorContextHandle, run: () => T): T;
+    /**
+     * Correlation of the invocation currently executing for this actor, or
+     * `undefined` outside an invocation or after it finished. A sampled-out
+     * invocation can still expose valid span context for propagation.
+     */
+    actorInvocationTraceContext(ctx: ActorContextHandle): ActorInvocationTraceContext | undefined;
+    /**
+     * Opens the span covering one call this actor makes to another actor. See
+     * `StartCallSpan` for when this returns nothing.
+     */
+    startCallSpan(ctx: ActorContextHandle, actorName: string, actionName: string): RuntimeOutboundCall | undefined;
+    /** Backs `ActorRun.startWorkflowSpan`. */
+    startWorkflowSpan(ctx: ActorContextHandle): Promise<WorkflowSpan>;
+    /** Backs `ActorRun.runOutsideWorkflowSpan`. */
+    runOutsideActorInvocationContext<T>(run: () => T): T;
+    /** Identity of the invocation the caller runs in, usable as a cache key. */
+    currentInvocationScope(): object | undefined;
     actorName(ctx: ActorContextHandle): string;
     actorKey(ctx: ActorContextHandle): RuntimeActorKeySegment[];
     actorRegion(ctx: ActorContextHandle): string;
@@ -1306,7 +1402,7 @@ declare class ActorConnRaw {
      *
      * @protected
      */
-    constructor(client: ClientRaw, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions);
+    constructor(client: ClientRaw, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions, currentActorInvocation?: CurrentActorInvocation);
     send(name: string, body: unknown, options: QueueSendWaitOptions): Promise<QueueSendResult>;
     send(name: string, body: unknown, options?: QueueSendNoWaitOptions): Promise<void>;
     /**
@@ -1442,7 +1538,7 @@ declare class ActorHandleRaw {
      *
      * @protected
      */
-    constructor(client: any, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions, signal?: AbortSignal);
+    constructor(client: any, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions, signal?: AbortSignal, currentActorInvocation?: CurrentActorInvocation, startCallSpan?: StartCallSpan);
     send(name: string, body: unknown, options: QueueSendWaitOptions): Promise<QueueSendResult>;
     send(name: string, body: unknown, options?: QueueSendNoWaitOptions): Promise<void>;
     /**
@@ -1617,6 +1713,18 @@ interface CreateOptions extends QueryOptions {
 }
 declare const ACTOR_CONNS_SYMBOL: unique symbol;
 declare const CREATE_ACTOR_CONN_PROXY: unique symbol;
+/** Options for constructing a raw actor client. */
+interface ClientRawOptions {
+    encoding?: Encoding;
+    gateway?: ActorGatewayOptions;
+}
+/** Runtime-supplied wiring for clients created inside an actor. Set only by the native runtime. */
+interface ActorClientRuntimeOptions {
+    /** Supplies the calling actor's invocation so actor-to-actor clients propagate its trace and ray ID. */
+    currentActorInvocation?: CurrentActorInvocation;
+    /** Opens and finishes the Core span covering an actor-to-actor call. */
+    startCallSpan?: StartCallSpan;
+}
 /**
  * Client for managing & connecting to actors.
  *
@@ -1629,7 +1737,7 @@ declare class ClientRaw {
     /**
      * Creates an instance of Client.
      */
-    constructor(driver: EngineControlClient, encoding: Encoding | undefined, gatewayOptions?: ActorGatewayOptions);
+    constructor(driver: EngineControlClient, options?: ClientRawOptions & ActorClientRuntimeOptions);
     /**
      * Gets a stateless handle to a actor by its ID.
      *
@@ -1936,6 +2044,28 @@ interface ActorContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase
     client<T = any>(): ActorClientFor<T>;
     [key: string]: any;
 }
+/** @experimental How one run of a workflow function ended. */
+type WorkflowOutcome = "completed" | "sleeping" | "evicted" | "failed" | "cancelled";
+/** @experimental How one workflow step attempt ended. `retry` will be tried again, `failed` will not. */
+type WorkflowStepOutcome = "ok" | "retry" | "failed";
+/** @experimental One open run of a workflow function, traced as its own invocation. */
+interface WorkflowSpan {
+    /** Runs `body` attributed to this run. */
+    run<T>(body: () => Promise<T>): Promise<T>;
+    /**
+     * Called by a workflow engine before each attempt at a step. Returns
+     * nothing when tracing is off.
+     */
+    startStep(name: string, attempt: number): WorkflowStepSpan | undefined;
+    finish(outcome: WorkflowOutcome): Promise<void>;
+}
+/** @experimental One open attempt at one workflow step. */
+interface WorkflowStepSpan {
+    /** Runs `body` attributed to this attempt. */
+    run<T>(body: () => Promise<T>): Promise<T>;
+    /** `error` is what the step callback threw. */
+    finish(outcome: WorkflowStepOutcome, error?: unknown): void;
+}
 /** @experimental */
 interface ActorRun {
     /**
@@ -1943,6 +2073,13 @@ interface ActorRun {
      * ensures this actor's run handler is active, starting it if inactive.
      */
     setWakeAt(timestamp: number | null): Promise<void>;
+    /** @experimental Called by a workflow engine each time it runs the workflow function. */
+    startWorkflowSpan(): Promise<WorkflowSpan>;
+    /**
+     * @experimental Runs `body` outside the current workflow run, so a workflow
+     * engine's own history storage stays out of the trace.
+     */
+    runOutsideWorkflowSpan<T>(body: () => T): T;
 }
 type ActionContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> = ActorContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & {
     conn: Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>;
@@ -2008,6 +2145,10 @@ declare const ActorConfigSchema: z$1.ZodObject<{
     onWebSocket: z$1.ZodOptional<z$1.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>;
     actions: z$1.ZodDefault<z$1.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
     actionInputSchemas: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodAny>>;
+    tracing: z$1.ZodOptional<z$1.ZodObject<{
+        sampler: z$1.ZodOptional<z$1.ZodNumber>;
+        actions: z$1.ZodOptional<z$1.ZodType<ActionSampleRates, unknown, z$1.core.$ZodTypeInternals<ActionSampleRates, unknown>>>;
+    }, z$1.core.$strict>>;
     connParamsSchema: z$1.ZodOptional<z$1.ZodAny>;
     events: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodAny>>;
     queues: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodAny>>;
@@ -2248,6 +2389,11 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
      * May mirror nested action groups or use dot-separated low-level action names.
      */
     actionInputSchemas?: ActionInputSchemas;
+    /**
+     * How much of this actor's work is recorded in traces. Defaults to the
+     * process sampler from `OTEL_TRACES_SAMPLER`.
+     */
+    tracing?: ActorTracingOptions<TActions>;
     /**
      * Optional schema for validating connection params in native runtimes.
      */

package/dist/tsup/agent-os/index.d.ts

@@ -543,6 +543,29 @@ declare class RivetError extends Error {
     toString(): string;
 }
 
+/** Sample rates keyed by action name, nested like the actor's action groups. */
+interface ActionSampleRates {
+    readonly [name: string]: number | ActionSampleRates;
+}
+/**
+ * {@link ActionSampleRates} limited to the actions of one actor, so a rate for
+ * an action that does not exist is a compile error.
+ */
+type ActionTraceSamplers<TActions> = {
+    readonly [K in keyof TActions]?: TActions[K] extends (...args: never[]) => unknown ? number : ActionTraceSamplers<TActions[K]>;
+};
+/** Trace sampling for one actor definition. */
+interface ActorTracingOptions<TActions> {
+    /**
+     * Share of this actor's invocations that are recorded, from 0 to 1. A rate
+     * lowers what is recorded and never raises it, so an invocation inside a
+     * trace the caller did not record is not recorded at any rate.
+     */
+    readonly sampler?: number;
+    /** Rates that replace `sampler` for single actions. */
+    readonly actions?: ActionTraceSamplers<TActions>;
+}
+
 type UpgradeWebSocket = (createEvents: (c: Context) => any) => Handler;
 type GetUpgradeWebSocket = () => UpgradeWebSocket;
 
@@ -624,6 +647,25 @@ interface ActorOutput {
     error?: unknown;
 }
 
+/** Correlation owned by the currently executing Core actor invocation. */
+interface ActorInvocationTraceContext {
+    /** Ray ID the invocation received, absent when nothing upstream supplied one. */
+    readonly rayId?: string;
+    /** Core-owned invocation span context, absent when tracing is disabled. */
+    readonly span?: ActorInvocationSpanContext;
+}
+/** W3C span context of the Core invocation span. */
+interface ActorInvocationSpanContext {
+    /** W3C trace identifier. */
+    readonly traceId: string;
+    /** W3C span identifier for the Core invocation. */
+    readonly spanId: string;
+    /** OpenTelemetry trace flags encoded as an integer. */
+    readonly traceFlags: number;
+    /** Optional vendor trace state inherited by the Core invocation. */
+    readonly tracestate?: string;
+}
+
 declare const handleBrand: unique symbol;
 type OpaqueHandle<Name extends string> = {
     readonly [handleBrand]: Name;
@@ -642,6 +684,27 @@ interface RuntimeActorKeySegment {
     stringValue?: string;
     numberValue?: number;
 }
+/** Resolves correlation at operation time so retained clients cannot freeze stale context. */
+type CurrentActorInvocation = () => ActorInvocationTraceContext | undefined;
+/** One open call from an actor out to another actor. */
+interface RuntimeOutboundCall {
+    /**
+     * W3C context of the call's own span, to send to the callee so it parents to
+     * the call. Absent when tracing is disabled.
+     */
+    readonly span?: ActorInvocationSpanContext;
+    /**
+     * Records the call's outcome. `error` is the failure encoded the way the
+     * bridge encodes errors, so a structured error keeps its group and code.
+     */
+    finish(error?: string): void;
+}
+/**
+ * Opens the span covering one call out to another actor, or returns `undefined`
+ * outside an invocation or on a runtime without invocation telemetry. Callers
+ * send their own context when it returns nothing.
+ */
+type StartCallSpan = (actorName: string, actionName: string) => RuntimeOutboundCall | undefined;
 interface RuntimeHttpRequest {
     method: string;
     uri: string;
@@ -802,12 +865,19 @@ interface RuntimeSqlBatchStatement {
 interface RuntimeSqlRunResult {
     changes: number;
 }
+/** Sample rates for the traces an actor starts, in the shape core takes. */
+interface RuntimeActorTracingConfig {
+    sampler?: number;
+    /** Keyed by flattened, dot-separated action name. */
+    actions?: Record<string, number>;
+}
 interface RuntimeActorConfig {
     name?: string;
     icon?: string;
     hasDatabase?: boolean;
     remoteSqlite?: boolean;
     sqliteProfiling?: SqliteProfilingOptions;
+    tracing?: RuntimeActorTracingConfig;
     enableActorRuntimeSocket?: boolean;
     hasState?: boolean;
     canHibernateWebsocket?: boolean;
@@ -939,6 +1009,7 @@ interface CoreRuntime {
     serveRegistry(registry: RegistryHandle, config: RuntimeServeConfig): Promise<void>;
     waitRegistryReady(registry: RegistryHandle): Promise<void>;
     shutdownRegistry(registry: RegistryHandle): Promise<void>;
+    shutdownTelemetry?(): Promise<void>;
     registryActorStopThresholdMs?(registry: RegistryHandle): Promise<number | undefined>;
     handleServerlessRequest(registry: RegistryHandle, req: RuntimeServerlessRequest, onStreamEvent: RuntimeServerlessStreamCallback, cancelToken: CancellationTokenHandle, config: RuntimeServeConfig): Promise<RuntimeServerlessResponseHead>;
     serveListener(registry: RegistryHandle, listener: RuntimeListenerConfig, config: RuntimeServeConfig): Promise<void>;
@@ -968,6 +1039,31 @@ interface CoreRuntime {
     actorSaveState(ctx: ActorContextHandle, payload: RuntimeStateDeltaPayload): Promise<void>;
     actorSaveStateAndWorkflowBatch(ctx: ActorContextHandle, writes: RuntimeWorkflowKvWrite[]): Promise<void>;
     actorId(ctx: ActorContextHandle): string;
+    /**
+     * Runs one actor callback with `ctx` as the current invocation: operations
+     * on retained handles for the same actor resolve to it, and its Core span
+     * is the active OpenTelemetry span for the duration of `run`. Only actions,
+     * raw requests, and queue dispatch run this way; other callbacks have no
+     * invocation span.
+     */
+    runWithActorInvocationContext<T>(ctx: ActorContextHandle, run: () => T): T;
+    /**
+     * Correlation of the invocation currently executing for this actor, or
+     * `undefined` outside an invocation or after it finished. A sampled-out
+     * invocation can still expose valid span context for propagation.
+     */
+    actorInvocationTraceContext(ctx: ActorContextHandle): ActorInvocationTraceContext | undefined;
+    /**
+     * Opens the span covering one call this actor makes to another actor. See
+     * `StartCallSpan` for when this returns nothing.
+     */
+    startCallSpan(ctx: ActorContextHandle, actorName: string, actionName: string): RuntimeOutboundCall | undefined;
+    /** Backs `ActorRun.startWorkflowSpan`. */
+    startWorkflowSpan(ctx: ActorContextHandle): Promise<WorkflowSpan>;
+    /** Backs `ActorRun.runOutsideWorkflowSpan`. */
+    runOutsideActorInvocationContext<T>(run: () => T): T;
+    /** Identity of the invocation the caller runs in, usable as a cache key. */
+    currentInvocationScope(): object | undefined;
     actorName(ctx: ActorContextHandle): string;
     actorKey(ctx: ActorContextHandle): RuntimeActorKeySegment[];
     actorRegion(ctx: ActorContextHandle): string;
@@ -1306,7 +1402,7 @@ declare class ActorConnRaw {
      *
      * @protected
      */
-    constructor(client: ClientRaw, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions);
+    constructor(client: ClientRaw, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions, currentActorInvocation?: CurrentActorInvocation);
     send(name: string, body: unknown, options: QueueSendWaitOptions): Promise<QueueSendResult>;
     send(name: string, body: unknown, options?: QueueSendNoWaitOptions): Promise<void>;
     /**
@@ -1442,7 +1538,7 @@ declare class ActorHandleRaw {
      *
      * @protected
      */
-    constructor(client: any, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions, signal?: AbortSignal);
+    constructor(client: any, driver: EngineControlClient, params: unknown, getParams: (() => Promise<unknown>) | undefined, encoding: Encoding, actorResolutionState: ActorResolutionState, gatewayOptions?: ActorGatewayOptions, signal?: AbortSignal, currentActorInvocation?: CurrentActorInvocation, startCallSpan?: StartCallSpan);
     send(name: string, body: unknown, options: QueueSendWaitOptions): Promise<QueueSendResult>;
     send(name: string, body: unknown, options?: QueueSendNoWaitOptions): Promise<void>;
     /**
@@ -1617,6 +1713,18 @@ interface CreateOptions extends QueryOptions {
 }
 declare const ACTOR_CONNS_SYMBOL: unique symbol;
 declare const CREATE_ACTOR_CONN_PROXY: unique symbol;
+/** Options for constructing a raw actor client. */
+interface ClientRawOptions {
+    encoding?: Encoding;
+    gateway?: ActorGatewayOptions;
+}
+/** Runtime-supplied wiring for clients created inside an actor. Set only by the native runtime. */
+interface ActorClientRuntimeOptions {
+    /** Supplies the calling actor's invocation so actor-to-actor clients propagate its trace and ray ID. */
+    currentActorInvocation?: CurrentActorInvocation;
+    /** Opens and finishes the Core span covering an actor-to-actor call. */
+    startCallSpan?: StartCallSpan;
+}
 /**
  * Client for managing & connecting to actors.
  *
@@ -1629,7 +1737,7 @@ declare class ClientRaw {
     /**
      * Creates an instance of Client.
      */
-    constructor(driver: EngineControlClient, encoding: Encoding | undefined, gatewayOptions?: ActorGatewayOptions);
+    constructor(driver: EngineControlClient, options?: ClientRawOptions & ActorClientRuntimeOptions);
     /**
      * Gets a stateless handle to a actor by its ID.
      *
@@ -1936,6 +2044,28 @@ interface ActorContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase
     client<T = any>(): ActorClientFor<T>;
     [key: string]: any;
 }
+/** @experimental How one run of a workflow function ended. */
+type WorkflowOutcome = "completed" | "sleeping" | "evicted" | "failed" | "cancelled";
+/** @experimental How one workflow step attempt ended. `retry` will be tried again, `failed` will not. */
+type WorkflowStepOutcome = "ok" | "retry" | "failed";
+/** @experimental One open run of a workflow function, traced as its own invocation. */
+interface WorkflowSpan {
+    /** Runs `body` attributed to this run. */
+    run<T>(body: () => Promise<T>): Promise<T>;
+    /**
+     * Called by a workflow engine before each attempt at a step. Returns
+     * nothing when tracing is off.
+     */
+    startStep(name: string, attempt: number): WorkflowStepSpan | undefined;
+    finish(outcome: WorkflowOutcome): Promise<void>;
+}
+/** @experimental One open attempt at one workflow step. */
+interface WorkflowStepSpan {
+    /** Runs `body` attributed to this attempt. */
+    run<T>(body: () => Promise<T>): Promise<T>;
+    /** `error` is what the step callback threw. */
+    finish(outcome: WorkflowStepOutcome, error?: unknown): void;
+}
 /** @experimental */
 interface ActorRun {
     /**
@@ -1943,6 +2073,13 @@ interface ActorRun {
      * ensures this actor's run handler is active, starting it if inactive.
      */
     setWakeAt(timestamp: number | null): Promise<void>;
+    /** @experimental Called by a workflow engine each time it runs the workflow function. */
+    startWorkflowSpan(): Promise<WorkflowSpan>;
+    /**
+     * @experimental Runs `body` outside the current workflow run, so a workflow
+     * engine's own history storage stays out of the trace.
+     */
+    runOutsideWorkflowSpan<T>(body: () => T): T;
 }
 type ActionContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase extends AnyDatabaseProvider, TEvents extends EventSchemaConfig = Record<never, never>, TQueues extends QueueSchemaConfig = Record<never, never>> = ActorContext<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues> & {
     conn: Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>;
@@ -2008,6 +2145,10 @@ declare const ActorConfigSchema: z$1.ZodObject<{
     onWebSocket: z$1.ZodOptional<z$1.ZodCustom<(...args: unknown[]) => unknown, (...args: unknown[]) => unknown>>;
     actions: z$1.ZodDefault<z$1.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
     actionInputSchemas: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodAny>>;
+    tracing: z$1.ZodOptional<z$1.ZodObject<{
+        sampler: z$1.ZodOptional<z$1.ZodNumber>;
+        actions: z$1.ZodOptional<z$1.ZodType<ActionSampleRates, unknown, z$1.core.$ZodTypeInternals<ActionSampleRates, unknown>>>;
+    }, z$1.core.$strict>>;
     connParamsSchema: z$1.ZodOptional<z$1.ZodAny>;
     events: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodAny>>;
     queues: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodAny>>;
@@ -2248,6 +2389,11 @@ interface BaseActorConfig<TState, TConnParams, TConnState, TVars, TInput, TDatab
      * May mirror nested action groups or use dot-separated low-level action names.
      */
     actionInputSchemas?: ActionInputSchemas;
+    /**
+     * How much of this actor's work is recorded in traces. Defaults to the
+     * process sampler from `OTEL_TRACES_SAMPLER`.
+     */
+    tracing?: ActorTracingOptions<TActions>;
     /**
      * Optional schema for validating connection params in native runtimes.
      */

package/dist/tsup/agent-os/index.js

@@ -33,6 +33,26 @@ function flattenActionInputSchemas(actions, schemas) {
   }
   return flattened;
 }
+function flattenActionTraceSamplers(actions, rates = {}) {
+  const handlers = flattenActionHandlers(actions);
+  const flattened = Object.fromEntries(flattenSampleRates(rates, []));
+  for (const name of Object.keys(flattened)) {
+    if (!Object.hasOwn(handlers, name)) {
+      throw new TypeError(
+        `tracing.actions.${name} does not name an action`
+      );
+    }
+  }
+  return flattened;
+}
+function flattenSampleRates(rates, path) {
+  return Object.entries(rates).flatMap(
+    ([segment, rate]) => {
+      const childPath = [...path, segment];
+      return typeof rate === "number" ? [[childPath.join("."), rate]] : flattenSampleRates(rate, childPath);
+    }
+  );
+}
 function collectActionEntries(actions) {
   const entries = [];
   const names = /* @__PURE__ */ new Set();
@@ -228,6 +248,10 @@ var InstanceActorOptionsSchema = InstanceActorOptionsBaseSchema.prefault(() => (
 var ActorOptionsSchema = GlobalActorOptionsBaseSchema.extend(
   InstanceActorOptionsBaseSchema.shape
 ).strict().prefault(() => ({}));
+var zSampleRate = z.number().min(0).max(1);
+var zActionSampleRates = z.lazy(
+  () => z.record(z.string(), z.union([zSampleRate, zActionSampleRates]))
+);
 var ActorConfigSchema = z.object({
   onCreate: zFunction().optional(),
   onDestroy: zFunction().optional(),
@@ -244,6 +268,10 @@ var ActorConfigSchema = z.object({
   onWebSocket: zFunction().optional(),
   actions: zActionTree.default(() => ({})),
   actionInputSchemas: z.record(z.string(), z.any()).optional(),
+  tracing: z.object({
+    sampler: zSampleRate.optional(),
+    actions: zActionSampleRates.optional()
+  }).strict().optional(),
   connParamsSchema: z.any().optional(),
   events: z.record(z.string(), z.any()).optional(),
   queues: z.record(z.string(), z.any()).optional(),
@@ -391,6 +419,9 @@ var DocActorConfigSchema = z.object({
   actionInputSchemas: z.record(z.string(), z.unknown()).optional().describe(
     "Optional schemas for validating action argument tuples in native runtimes. May mirror nested action groups or use dot-separated low-level action names."
   ),
+  tracing: z.unknown().optional().describe(
+    "Trace sampling for this actor: `sampler` is the share of its invocations that are recorded, from 0 to 1, with optional per-action rates under `actions`. A rate lowers what is recorded and never raises it. Defaults to the process sampler from OTEL_TRACES_SAMPLER."
+  ),
   connParamsSchema: z.unknown().optional().describe(
     "Optional schema for validating connection params in native runtimes."
   ),
@@ -420,7 +451,7 @@ function isRivetErrorCode(error, group, code) {
 // package.json
 var package_default = {
   name: "rivetkit",
-  version: "2.3.18",
+  version: "2.3.20",
   description: "Lightweight libraries for building stateful actors on edge platforms",
   license: "Apache-2.0",
   keywords: [
@@ -629,6 +660,7 @@ var package_default = {
   },
   dependencies: {
     "@hono/zod-openapi": "^1.1.5",
+    "@opentelemetry/api": "^1.1.0",
     "@rivet-dev/agent-os-core": "^0.1.1",
     "@rivet-dev/services": "^0.1.5",
     "@rivetkit/bare-ts": "^0.6.2",
@@ -655,6 +687,7 @@ var package_default = {
     "@copilotkit/llmock": "^1.6.0",
     "@hono/node-server": "^1.18.2",
     "@hono/node-ws": "^1.1.1",
+    "@opentelemetry/sdk-trace-node": "2.11.0",
     "@rivet-dev/agent-os-common": "*",
     "@rivet-dev/agent-os-pi": "^0.1.1",
     "@standard-schema/spec": "^1.0.0",
@@ -887,12 +920,14 @@ var ActorDefinition = class {
   }
 };
 function actor(input) {
+  var _a;
   warnDeprecatedOptionKeys(
     input == null ? void 0 : input.options
   );
   const config = ActorConfigSchema.parse(input);
   flattenActionHandlers(config.actions);
   flattenActionInputSchemas(config.actions, config.actionInputSchemas);
+  flattenActionTraceSamplers(config.actions, (_a = config.tracing) == null ? void 0 : _a.actions);
   return new ActorDefinition(config);
 }