rivetkit 2.3.19 → 2.3.21

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

@@ -2,6 +2,7 @@ import * as _rivet_dev_agent_os_core from '@rivet-dev/agent-os-core';
 import { AgentOs, JsonRpcNotification, PermissionRequest, CronEvent, AgentCapabilities, AgentInfo, JsonRpcResponse, AgentOsOptions, BatchReadResult, BatchWriteEntry, BatchWriteResult, ReaddirRecursiveOptions, DirEntry, AgentRegistryEntry, SpawnedProcessInfo, ProcessInfo, ProcessTreeNode, SessionModeState, SessionConfigOption, GetEventsOptions, SequencedEvent, PermissionReply, AgentType, CreateSessionOptions, SessionInfo, OpenShellOptions } from '@rivet-dev/agent-os-core';
 import { z as z$1 } from 'zod/v4';
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Rivet } from '@rivetkit/engine-api-full';
 import { Context, Handler, Hono } from 'hono';
 import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
 import * as _rivetkit_rivetkit_wasm from '@rivetkit/rivetkit-wasm';
@@ -272,7 +273,7 @@ declare const RegistryConfigSchema: z.ZodPipe<z.ZodObject<{
     endpoint: string | undefined;
     startServices: boolean;
     namespace: string;
-    token: string;
+    token: string | undefined;
     publicEndpoint: string | undefined;
     publicNamespace: string | undefined;
     publicToken: string | undefined;
@@ -445,6 +446,24 @@ declare class ActorDefinition<S, CP, CS, V, I, DB extends AnyDatabaseProvider, E
     get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q, R>;
 }
 
+/** Options for `client.auth.issueToken()`. `expiresIn` is in seconds. */
+type IssueTokenOptions = Pick<Rivet.AuthTokenCreateRequest, "subject" | "grants"> & {
+    expiresIn?: Rivet.AuthTokenCreateRequest["duration"];
+};
+/** Token timestamps are Unix milliseconds. */
+interface IssuedToken {
+    token: Rivet.AuthTokenCreateResponse["token"];
+    issuedAt: Rivet.AuthTokenCreateResponse["issuedTs"];
+    expiresAt: Rivet.AuthTokenCreateResponse["expiresTs"];
+}
+/** Resources that can be scoped to a single actor ID. */
+type ActorTokenResource = Extract<Rivet.AuthTokenGrant["resource"], "actor_gateway" | "actor" | "actor_kv">;
+type ActorTokenPermissions = Partial<Record<ActorTokenResource, Rivet.AuthTokenGrant["operations"]>>;
+/** Options for `actor.issueToken()`. Omit permissions for gateway read access only. */
+type ActorIssueTokenOptions = Pick<IssueTokenOptions, "subject" | "expiresIn"> & {
+    permissions?: ActorTokenPermissions;
+};
+
 declare const EncodingSchema: z$1.ZodEnum<{
     json: "json";
     cbor: "cbor";
@@ -543,6 +562,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;
 
@@ -553,6 +595,7 @@ interface GatewayRequestOptions {
     skipReadyWait?: boolean;
 }
 interface EngineControlClient {
+    issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
     getForId(input: GetForIdInput): Promise<ActorOutput | undefined>;
     getWithKey(input: GetWithKeyInput): Promise<ActorOutput | undefined>;
     getOrCreateWithKey(input: GetOrCreateWithKeyInput): Promise<ActorOutput>;
@@ -560,6 +603,8 @@ interface EngineControlClient {
     listActors(input: ListActorsInput): Promise<ActorOutput[]>;
     sendRequest(target: GatewayTarget, actorRequest: Request, options?: GatewayRequestOptions): Promise<Response>;
     openWebSocket(path: string, target: GatewayTarget, encoding: Encoding, params: unknown, options?: GatewayRequestOptions): Promise<UniversalWebSocket>;
+    /** Refresh a credential rejected during this WebSocket handshake, if supported. */
+    refreshAuthToken?(ws: UniversalWebSocket): Promise<boolean>;
     proxyRequest(c: Context, actorRequest: Request, actorId: string): Promise<Response>;
     proxyWebSocket(c: Context, path: string, actorId: string, encoding: Encoding, params: unknown): Promise<Response>;
     buildGatewayUrl(target: GatewayTarget, options?: GatewayRequestOptions): Promise<string>;
@@ -842,12 +887,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;
@@ -1542,6 +1594,8 @@ declare class ActorHandleRaw {
      * Resolves the actor to get its unique actor ID.
      */
     resolve(): Promise<string>;
+    /** Issue a token scoped to this actor. Defaults to actor gateway read access. */
+    issueToken(options?: ActorIssueTokenOptions): Promise<IssuedToken>;
     /**
      * Returns the raw URL for routing traffic to the actor.
      */
@@ -1567,7 +1621,7 @@ declare class ActorHandleRaw {
 type ActorHandle<AD extends AnyActorDefinition> = Omit<ActorHandleRaw, "connect" | "send"> & {
     connect(params?: unknown, options?: ActorConnectOptions): ActorConn<AD>;
     resolve(): Promise<string>;
-} & ActorDefinitionQueueSend<AD> & ActorDefinitionActions<AD>;
+} & ActorDefinitionQueueSend<AD> & Omit<ActorDefinitionActions<AD>, keyof ActorHandleRaw>;
 
 /** Extract the actor registry from the registry definition. */
 type ExtractActorsFromRegistry<A extends Registry<any>> = A extends Registry<infer Actors> ? Actors : never;
@@ -1703,6 +1757,10 @@ interface ActorClientRuntimeOptions {
  */
 declare class ClientRaw {
     #private;
+    /** Issue namespace-scoped tokens with an explicit grant list. */
+    readonly auth: {
+        issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
+    };
     [ACTOR_CONNS_SYMBOL]: Set<ActorConnRaw>;
     /**
      * Creates an instance of Client.
@@ -1763,9 +1821,9 @@ declare class ClientRaw {
  *
  * @template A The actor registry type.
  */
-type Client<A extends Registry<any>> = ClientRaw & {
+type Client<A extends Registry<any>> = ClientRaw & Omit<{
     [K in keyof ExtractActorsFromRegistry<A>]: ActorAccessor<ExtractActorsFromRegistry<A>[K]>;
-};
+}, keyof ClientRaw>;
 
 /** @experimental State exposed by a durable workflow run handler to the Inspector. */
 type WorkflowState = "pending" | "running" | "sleeping" | "failed" | "completed" | "cancelled" | "rolling_back";
@@ -2115,6 +2173,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>>;
@@ -2355,6 +2417,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

@@ -2,6 +2,7 @@ import * as _rivet_dev_agent_os_core from '@rivet-dev/agent-os-core';
 import { AgentOs, JsonRpcNotification, PermissionRequest, CronEvent, AgentCapabilities, AgentInfo, JsonRpcResponse, AgentOsOptions, BatchReadResult, BatchWriteEntry, BatchWriteResult, ReaddirRecursiveOptions, DirEntry, AgentRegistryEntry, SpawnedProcessInfo, ProcessInfo, ProcessTreeNode, SessionModeState, SessionConfigOption, GetEventsOptions, SequencedEvent, PermissionReply, AgentType, CreateSessionOptions, SessionInfo, OpenShellOptions } from '@rivet-dev/agent-os-core';
 import { z as z$1 } from 'zod/v4';
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { Rivet } from '@rivetkit/engine-api-full';
 import { Context, Handler, Hono } from 'hono';
 import { UniversalWebSocket } from '@rivetkit/virtual-websocket';
 import * as _rivetkit_rivetkit_wasm from '@rivetkit/rivetkit-wasm';
@@ -272,7 +273,7 @@ declare const RegistryConfigSchema: z.ZodPipe<z.ZodObject<{
     endpoint: string | undefined;
     startServices: boolean;
     namespace: string;
-    token: string;
+    token: string | undefined;
     publicEndpoint: string | undefined;
     publicNamespace: string | undefined;
     publicToken: string | undefined;
@@ -445,6 +446,24 @@ declare class ActorDefinition<S, CP, CS, V, I, DB extends AnyDatabaseProvider, E
     get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q, R>;
 }
 
+/** Options for `client.auth.issueToken()`. `expiresIn` is in seconds. */
+type IssueTokenOptions = Pick<Rivet.AuthTokenCreateRequest, "subject" | "grants"> & {
+    expiresIn?: Rivet.AuthTokenCreateRequest["duration"];
+};
+/** Token timestamps are Unix milliseconds. */
+interface IssuedToken {
+    token: Rivet.AuthTokenCreateResponse["token"];
+    issuedAt: Rivet.AuthTokenCreateResponse["issuedTs"];
+    expiresAt: Rivet.AuthTokenCreateResponse["expiresTs"];
+}
+/** Resources that can be scoped to a single actor ID. */
+type ActorTokenResource = Extract<Rivet.AuthTokenGrant["resource"], "actor_gateway" | "actor" | "actor_kv">;
+type ActorTokenPermissions = Partial<Record<ActorTokenResource, Rivet.AuthTokenGrant["operations"]>>;
+/** Options for `actor.issueToken()`. Omit permissions for gateway read access only. */
+type ActorIssueTokenOptions = Pick<IssueTokenOptions, "subject" | "expiresIn"> & {
+    permissions?: ActorTokenPermissions;
+};
+
 declare const EncodingSchema: z$1.ZodEnum<{
     json: "json";
     cbor: "cbor";
@@ -543,6 +562,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;
 
@@ -553,6 +595,7 @@ interface GatewayRequestOptions {
     skipReadyWait?: boolean;
 }
 interface EngineControlClient {
+    issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
     getForId(input: GetForIdInput): Promise<ActorOutput | undefined>;
     getWithKey(input: GetWithKeyInput): Promise<ActorOutput | undefined>;
     getOrCreateWithKey(input: GetOrCreateWithKeyInput): Promise<ActorOutput>;
@@ -560,6 +603,8 @@ interface EngineControlClient {
     listActors(input: ListActorsInput): Promise<ActorOutput[]>;
     sendRequest(target: GatewayTarget, actorRequest: Request, options?: GatewayRequestOptions): Promise<Response>;
     openWebSocket(path: string, target: GatewayTarget, encoding: Encoding, params: unknown, options?: GatewayRequestOptions): Promise<UniversalWebSocket>;
+    /** Refresh a credential rejected during this WebSocket handshake, if supported. */
+    refreshAuthToken?(ws: UniversalWebSocket): Promise<boolean>;
     proxyRequest(c: Context, actorRequest: Request, actorId: string): Promise<Response>;
     proxyWebSocket(c: Context, path: string, actorId: string, encoding: Encoding, params: unknown): Promise<Response>;
     buildGatewayUrl(target: GatewayTarget, options?: GatewayRequestOptions): Promise<string>;
@@ -842,12 +887,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;
@@ -1542,6 +1594,8 @@ declare class ActorHandleRaw {
      * Resolves the actor to get its unique actor ID.
      */
     resolve(): Promise<string>;
+    /** Issue a token scoped to this actor. Defaults to actor gateway read access. */
+    issueToken(options?: ActorIssueTokenOptions): Promise<IssuedToken>;
     /**
      * Returns the raw URL for routing traffic to the actor.
      */
@@ -1567,7 +1621,7 @@ declare class ActorHandleRaw {
 type ActorHandle<AD extends AnyActorDefinition> = Omit<ActorHandleRaw, "connect" | "send"> & {
     connect(params?: unknown, options?: ActorConnectOptions): ActorConn<AD>;
     resolve(): Promise<string>;
-} & ActorDefinitionQueueSend<AD> & ActorDefinitionActions<AD>;
+} & ActorDefinitionQueueSend<AD> & Omit<ActorDefinitionActions<AD>, keyof ActorHandleRaw>;
 
 /** Extract the actor registry from the registry definition. */
 type ExtractActorsFromRegistry<A extends Registry<any>> = A extends Registry<infer Actors> ? Actors : never;
@@ -1703,6 +1757,10 @@ interface ActorClientRuntimeOptions {
  */
 declare class ClientRaw {
     #private;
+    /** Issue namespace-scoped tokens with an explicit grant list. */
+    readonly auth: {
+        issueToken(options: IssueTokenOptions): Promise<IssuedToken>;
+    };
     [ACTOR_CONNS_SYMBOL]: Set<ActorConnRaw>;
     /**
      * Creates an instance of Client.
@@ -1763,9 +1821,9 @@ declare class ClientRaw {
  *
  * @template A The actor registry type.
  */
-type Client<A extends Registry<any>> = ClientRaw & {
+type Client<A extends Registry<any>> = ClientRaw & Omit<{
     [K in keyof ExtractActorsFromRegistry<A>]: ActorAccessor<ExtractActorsFromRegistry<A>[K]>;
-};
+}, keyof ClientRaw>;
 
 /** @experimental State exposed by a durable workflow run handler to the Inspector. */
 type WorkflowState = "pending" | "running" | "sleeping" | "failed" | "completed" | "cancelled" | "rolling_back";
@@ -2115,6 +2173,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>>;
@@ -2355,6 +2417,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.19",
+  version: "2.3.21",
   description: "Lightweight libraries for building stateful actors on edge platforms",
   license: "Apache-2.0",
   keywords: [
@@ -633,6 +664,7 @@ var package_default = {
     "@rivet-dev/agent-os-core": "^0.1.1",
     "@rivet-dev/services": "^0.1.5",
     "@rivetkit/bare-ts": "^0.6.2",
+    "@rivetkit/engine-api-full": "workspace:*",
     "@rivetkit/engine-cli": "workspace:*",
     "@rivetkit/engine-envoy-protocol": "workspace:*",
     "@rivetkit/on-change": "6.0.1",
@@ -889,12 +921,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);
 }