@glassflow-ai/rius 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -118,6 +118,7 @@ interface InitOptions extends RiusOptions {
 declare class RiusClient {
     private readonly provider;
     private readonly health?;
+    private readonly teardown;
     /** Resolves with the names of the auto-instrumentations that attached. */
     readonly ready: Promise<string[]>;
     private constructor();
@@ -145,9 +146,10 @@ declare class RiusClient {
  * {@link RiusClient.ready} if instrumentation must be attached before your
  * first span.
  *
- * The SDK installs no process exit hook: short-lived processes must call
+ * The SDK installs no exit hook for SPANS: short-lived processes must call
  * {@link RiusClient.flush} before exiting or spans still in the batch queue
- * are lost.
+ * are lost. (The heartbeat does register a `beforeExit` listener, only to
+ * send its final `stopped` ping; it flushes nothing.)
  */
 declare function init(options?: InitOptions): RiusClient;
 /** The SDK tracer. Scope name is wire-visible; do not parameterize it. */
@@ -170,6 +172,21 @@ declare enum SpanKind {
 interface SpanOptions {
     kind?: SpanKind;
     input?: unknown;
+    /**
+     * End-user identity (`user.id`). Sugar for `withUser`: set on this span at
+     * creation and, for the scoped variant, on every span opened inside it.
+     * To attribute a whole request, including auto-instrumented spans, prefer
+     * `withUser` around the handler.
+     */
+    userId?: string;
+    /**
+     * Identity attributes to set at span CREATION rather than after it. Pending
+     * snapshots are built at start, so anything a caller would otherwise
+     * `setAttribute` first thing (a tool name, say) belongs here to reach them.
+     * Content never does: it is not known at start and would bypass masking's
+     * assumptions about where content lives.
+     */
+    attributes?: Record<string, string>;
 }
 /** A handle over a span. Chainable setters; `end()` is idempotent. */
 declare class Observation {
@@ -178,6 +195,12 @@ declare class Observation {
     constructor(span: Span);
     setInput(value: unknown): this;
     setOutput(value: unknown): this;
+    /**
+     * Set an arbitrary attribute. Primitives and homogeneous primitive arrays
+     * are passed through as the OTel values they are; objects are JSON-encoded
+     * and bounded; `undefined` and `null` set nothing, since "no value" is not
+     * an empty string.
+     */
     setAttribute(key: string, value: unknown): this;
     /**
      * Record an error on the span and set ERROR status. This is exactly what the
@@ -223,19 +246,68 @@ interface GenerationOptions {
      * so use the provider's own parameter names.
      */
     modelParameters?: Record<string, unknown>;
+    /**
+     * Requested reasoning/thinking effort level
+     * (`gen_ai.request.reasoning.level`), e.g. OpenAI's `reasoning.effort`
+     * values. Provider-defined string, recorded verbatim. A first-class option
+     * because the `modelParameters` pass-through would spell the key
+     * `gen_ai.request.reasoning_level`, which is not the convention's name.
+     */
+    reasoningLevel?: string;
+    /**
+     * The request's tool/function definitions, recorded immediately via
+     * {@link Generation.setToolDefinitions} — verbatim, any provider shape.
+     */
+    tools?: unknown[];
+    /**
+     * End-user identity (`user.id`). Sugar for `withUser`: set on this span at
+     * creation and, for the scoped variant, on every span opened inside it.
+     */
+    userId?: string;
+    /**
+     * Operation name (`gen_ai.operation.name`); default `"chat"`. Set it for
+     * `text_completion`, `embeddings` or `generate_content` calls, as the
+     * Python SDK's `operation=` allows.
+     */
+    operation?: string;
 }
 /** An LLM call. Content uses gen_ai message keys, never input.value. */
 declare class Generation extends Observation {
+    private readonly provider?;
     private firstTokenRecorded;
+    /**
+     * The provider passed at creation; drives the Anthropic input-token summing
+     * in {@link setUsage}. A bare `new Generation(span)` has none and never sums.
+     */
+    constructor(span: ConstructorParameters<typeof Observation>[0], provider?: string | undefined);
+    /**
+     * Record the request messages (`gen_ai.input.messages`), normalised to the
+     * GenAI `{role, parts}` shape like the Python SDK does: bare strings, OpenAI
+     * dicts (including `tool_calls` and tool responses) and multimodal content
+     * lists are all accepted. Bare strings default to the `user` role.
+     */
     setInput(value: unknown): this;
+    /** Record the response messages (`gen_ai.output.messages`); bare strings default to `assistant`. */
     setOutput(value: unknown): this;
+    /**
+     * The request's tool/function definitions (`gen_ai.tool.definitions`).
+     * Serialized verbatim, in whatever shape the provider request used (OpenAI
+     * nests each tool under `function`, Anthropic uses top-level
+     * `name`/`input_schema`) — no normalization, so what is recorded is exactly
+     * what the model was shown. Definitions are content, not identity: they are
+     * masked/stripped under `captureContent: false` like messages are.
+     */
+    setToolDefinitions(tools: unknown[]): this;
     setModel(model: string): this;
     /**
-     * Token usage (`gen_ai.usage.*`). Pass provider-reported values as-is.
-     * Per the GenAI conventions, `inputTokens` is the total including cached
-     * tokens (the cache counts are subsets of it); providers that report an
-     * exclusive `inputTokens` (e.g. Anthropic) are detected and normalized by
-     * the backend, so no client-side arithmetic is needed.
+     * Token usage (`gen_ai.usage.*`). Pass provider-reported values as-is;
+     * never pre-add anything. Per the GenAI conventions, `inputTokens` is the
+     * total including cached tokens (the cache counts are subsets of it).
+     * Anthropic's API reports `input_tokens` excluding the cache counts, and
+     * the conventions require the instrumentation to do the summing, so when
+     * the generation's provider is `"anthropic"` the emitted total is
+     * `inputTokens` plus both cache counts. Every other provider is recorded
+     * verbatim.
      */
     setUsage(usage: {
         inputTokens?: number;
@@ -247,6 +319,13 @@ declare class Generation extends Observation {
          * (called "cache creation" by Anthropic).
          */
         cacheWriteInputTokens?: number;
+        /**
+         * Output tokens spent on reasoning / extended thinking. A subset of
+         * `outputTokens`, never in addition to it: providers already include
+         * reasoning tokens in the output total, so pass both as reported and
+         * do no arithmetic.
+         */
+        reasoningOutputTokens?: number;
     }): this;
     /**
      * Why generation stopped (`gen_ai.response.finish_reasons`), e.g. `"stop"`,
@@ -283,8 +362,10 @@ interface ObserveOptions {
     captureOutput?: boolean;
 }
 /**
- * Wrap a function so each call becomes a span. Returns a function with the
- * same signature, so call sites and types are unchanged.
+ * Wrap a function so each call becomes a span. The returned function takes
+ * the same parameters and always returns a Promise of the original's result
+ * (a synchronous function becomes asynchronous), so call sites need an
+ * `await` but no other change.
  *
  * A wrapper rather than a decorator on purpose: TypeScript decorators apply
  * only to class members, and most agent code is plain functions.
@@ -315,6 +396,51 @@ declare function observe<F extends (...args: never[]) => unknown>(fn: F, options
 declare function withSession<T>(fn: (sessionId: string) => T): T;
 declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T): T;
 
-declare const VERSION = "0.4.0";
+/**
+ * Users: attribute every span of a request to the end user it served.
+ *
+ * The caller supplies the id (`withUser` for a scope) and `UserSpanProcessor`
+ * stamps it as the `user.id` attribute on every span started in scope. That
+ * key is the one OpenInference defines, Langfuse reads natively, and the
+ * OpenTelemetry registry lists; the sink also accepts OTel's `enduser.id`
+ * from third-party instrumentors, but this SDK emits one name for one fact.
+ *
+ * Stamping happens in `onStart`, as for sessions: the sink derives its user
+ * column per span, and pending snapshots are built at span start from the
+ * identity allowlist, so an attribute set later would reach neither.
+ *
+ * Two deliberate differences from `withSession`:
+ *
+ * - No process-wide default and no environment variable. A user is a
+ *   property of a request, and a global default would attribute every
+ *   request a process ever handles to one person.
+ * - Nothing is minted when the caller passes nothing. A session without an
+ *   id is still a session; a span without a user is simply anonymous, and
+ *   the backend treats an empty user id as exactly that.
+ *
+ * The id rides OTel context, so scopes nest, unwind with the callback even
+ * on a throw, and follow async continuations the same way the active span
+ * does.
+ */
+
+/**
+ * Scope every span started inside `fn` to one end user.
+ *
+ * Pass the application's own identifier for the person the request serves.
+ * Prefer an opaque id over an email: it is stored on every span and shown
+ * in the console. When only sensitive identifiers exist, hash them first
+ * (OTel's `user.hash` / `enduser.pseudo.id` guidance). Nested scopes
+ * override outer ones. The id is passed to the callback so it can be logged
+ * alongside the work.
+ *
+ * ```typescript
+ * await withUser(request.userId, async () => {
+ *   await handle(request) // every span of the request carries user.id
+ * })
+ * ```
+ */
+declare function withUser<T>(userId: string, fn: (userId: string) => T): T;
+
+declare const VERSION = "0.6.0";
 
-export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, type WorkspaceExporterFactory, getTracer, init, observe, registerWorkspace, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession, withWorkspace };
+export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, type WorkspaceExporterFactory, getTracer, init, observe, registerWorkspace, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession, withUser, withWorkspace };

package/dist/index.d.ts

@@ -118,6 +118,7 @@ interface InitOptions extends RiusOptions {
 declare class RiusClient {
     private readonly provider;
     private readonly health?;
+    private readonly teardown;
     /** Resolves with the names of the auto-instrumentations that attached. */
     readonly ready: Promise<string[]>;
     private constructor();
@@ -145,9 +146,10 @@ declare class RiusClient {
  * {@link RiusClient.ready} if instrumentation must be attached before your
  * first span.
  *
- * The SDK installs no process exit hook: short-lived processes must call
+ * The SDK installs no exit hook for SPANS: short-lived processes must call
  * {@link RiusClient.flush} before exiting or spans still in the batch queue
- * are lost.
+ * are lost. (The heartbeat does register a `beforeExit` listener, only to
+ * send its final `stopped` ping; it flushes nothing.)
  */
 declare function init(options?: InitOptions): RiusClient;
 /** The SDK tracer. Scope name is wire-visible; do not parameterize it. */
@@ -170,6 +172,21 @@ declare enum SpanKind {
 interface SpanOptions {
     kind?: SpanKind;
     input?: unknown;
+    /**
+     * End-user identity (`user.id`). Sugar for `withUser`: set on this span at
+     * creation and, for the scoped variant, on every span opened inside it.
+     * To attribute a whole request, including auto-instrumented spans, prefer
+     * `withUser` around the handler.
+     */
+    userId?: string;
+    /**
+     * Identity attributes to set at span CREATION rather than after it. Pending
+     * snapshots are built at start, so anything a caller would otherwise
+     * `setAttribute` first thing (a tool name, say) belongs here to reach them.
+     * Content never does: it is not known at start and would bypass masking's
+     * assumptions about where content lives.
+     */
+    attributes?: Record<string, string>;
 }
 /** A handle over a span. Chainable setters; `end()` is idempotent. */
 declare class Observation {
@@ -178,6 +195,12 @@ declare class Observation {
     constructor(span: Span);
     setInput(value: unknown): this;
     setOutput(value: unknown): this;
+    /**
+     * Set an arbitrary attribute. Primitives and homogeneous primitive arrays
+     * are passed through as the OTel values they are; objects are JSON-encoded
+     * and bounded; `undefined` and `null` set nothing, since "no value" is not
+     * an empty string.
+     */
     setAttribute(key: string, value: unknown): this;
     /**
      * Record an error on the span and set ERROR status. This is exactly what the
@@ -223,19 +246,68 @@ interface GenerationOptions {
      * so use the provider's own parameter names.
      */
     modelParameters?: Record<string, unknown>;
+    /**
+     * Requested reasoning/thinking effort level
+     * (`gen_ai.request.reasoning.level`), e.g. OpenAI's `reasoning.effort`
+     * values. Provider-defined string, recorded verbatim. A first-class option
+     * because the `modelParameters` pass-through would spell the key
+     * `gen_ai.request.reasoning_level`, which is not the convention's name.
+     */
+    reasoningLevel?: string;
+    /**
+     * The request's tool/function definitions, recorded immediately via
+     * {@link Generation.setToolDefinitions} — verbatim, any provider shape.
+     */
+    tools?: unknown[];
+    /**
+     * End-user identity (`user.id`). Sugar for `withUser`: set on this span at
+     * creation and, for the scoped variant, on every span opened inside it.
+     */
+    userId?: string;
+    /**
+     * Operation name (`gen_ai.operation.name`); default `"chat"`. Set it for
+     * `text_completion`, `embeddings` or `generate_content` calls, as the
+     * Python SDK's `operation=` allows.
+     */
+    operation?: string;
 }
 /** An LLM call. Content uses gen_ai message keys, never input.value. */
 declare class Generation extends Observation {
+    private readonly provider?;
     private firstTokenRecorded;
+    /**
+     * The provider passed at creation; drives the Anthropic input-token summing
+     * in {@link setUsage}. A bare `new Generation(span)` has none and never sums.
+     */
+    constructor(span: ConstructorParameters<typeof Observation>[0], provider?: string | undefined);
+    /**
+     * Record the request messages (`gen_ai.input.messages`), normalised to the
+     * GenAI `{role, parts}` shape like the Python SDK does: bare strings, OpenAI
+     * dicts (including `tool_calls` and tool responses) and multimodal content
+     * lists are all accepted. Bare strings default to the `user` role.
+     */
     setInput(value: unknown): this;
+    /** Record the response messages (`gen_ai.output.messages`); bare strings default to `assistant`. */
     setOutput(value: unknown): this;
+    /**
+     * The request's tool/function definitions (`gen_ai.tool.definitions`).
+     * Serialized verbatim, in whatever shape the provider request used (OpenAI
+     * nests each tool under `function`, Anthropic uses top-level
+     * `name`/`input_schema`) — no normalization, so what is recorded is exactly
+     * what the model was shown. Definitions are content, not identity: they are
+     * masked/stripped under `captureContent: false` like messages are.
+     */
+    setToolDefinitions(tools: unknown[]): this;
     setModel(model: string): this;
     /**
-     * Token usage (`gen_ai.usage.*`). Pass provider-reported values as-is.
-     * Per the GenAI conventions, `inputTokens` is the total including cached
-     * tokens (the cache counts are subsets of it); providers that report an
-     * exclusive `inputTokens` (e.g. Anthropic) are detected and normalized by
-     * the backend, so no client-side arithmetic is needed.
+     * Token usage (`gen_ai.usage.*`). Pass provider-reported values as-is;
+     * never pre-add anything. Per the GenAI conventions, `inputTokens` is the
+     * total including cached tokens (the cache counts are subsets of it).
+     * Anthropic's API reports `input_tokens` excluding the cache counts, and
+     * the conventions require the instrumentation to do the summing, so when
+     * the generation's provider is `"anthropic"` the emitted total is
+     * `inputTokens` plus both cache counts. Every other provider is recorded
+     * verbatim.
      */
     setUsage(usage: {
         inputTokens?: number;
@@ -247,6 +319,13 @@ declare class Generation extends Observation {
          * (called "cache creation" by Anthropic).
          */
         cacheWriteInputTokens?: number;
+        /**
+         * Output tokens spent on reasoning / extended thinking. A subset of
+         * `outputTokens`, never in addition to it: providers already include
+         * reasoning tokens in the output total, so pass both as reported and
+         * do no arithmetic.
+         */
+        reasoningOutputTokens?: number;
     }): this;
     /**
      * Why generation stopped (`gen_ai.response.finish_reasons`), e.g. `"stop"`,
@@ -283,8 +362,10 @@ interface ObserveOptions {
     captureOutput?: boolean;
 }
 /**
- * Wrap a function so each call becomes a span. Returns a function with the
- * same signature, so call sites and types are unchanged.
+ * Wrap a function so each call becomes a span. The returned function takes
+ * the same parameters and always returns a Promise of the original's result
+ * (a synchronous function becomes asynchronous), so call sites need an
+ * `await` but no other change.
  *
  * A wrapper rather than a decorator on purpose: TypeScript decorators apply
  * only to class members, and most agent code is plain functions.
@@ -315,6 +396,51 @@ declare function observe<F extends (...args: never[]) => unknown>(fn: F, options
 declare function withSession<T>(fn: (sessionId: string) => T): T;
 declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T): T;
 
-declare const VERSION = "0.4.0";
+/**
+ * Users: attribute every span of a request to the end user it served.
+ *
+ * The caller supplies the id (`withUser` for a scope) and `UserSpanProcessor`
+ * stamps it as the `user.id` attribute on every span started in scope. That
+ * key is the one OpenInference defines, Langfuse reads natively, and the
+ * OpenTelemetry registry lists; the sink also accepts OTel's `enduser.id`
+ * from third-party instrumentors, but this SDK emits one name for one fact.
+ *
+ * Stamping happens in `onStart`, as for sessions: the sink derives its user
+ * column per span, and pending snapshots are built at span start from the
+ * identity allowlist, so an attribute set later would reach neither.
+ *
+ * Two deliberate differences from `withSession`:
+ *
+ * - No process-wide default and no environment variable. A user is a
+ *   property of a request, and a global default would attribute every
+ *   request a process ever handles to one person.
+ * - Nothing is minted when the caller passes nothing. A session without an
+ *   id is still a session; a span without a user is simply anonymous, and
+ *   the backend treats an empty user id as exactly that.
+ *
+ * The id rides OTel context, so scopes nest, unwind with the callback even
+ * on a throw, and follow async continuations the same way the active span
+ * does.
+ */
+
+/**
+ * Scope every span started inside `fn` to one end user.
+ *
+ * Pass the application's own identifier for the person the request serves.
+ * Prefer an opaque id over an email: it is stored on every span and shown
+ * in the console. When only sensitive identifiers exist, hash them first
+ * (OTel's `user.hash` / `enduser.pseudo.id` guidance). Nested scopes
+ * override outer ones. The id is passed to the callback so it can be logged
+ * alongside the work.
+ *
+ * ```typescript
+ * await withUser(request.userId, async () => {
+ *   await handle(request) // every span of the request carries user.id
+ * })
+ * ```
+ */
+declare function withUser<T>(userId: string, fn: (userId: string) => T): T;
+
+declare const VERSION = "0.6.0";
 
-export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, type WorkspaceExporterFactory, getTracer, init, observe, registerWorkspace, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession, withWorkspace };
+export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, type WorkspaceExporterFactory, getTracer, init, observe, registerWorkspace, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession, withUser, withWorkspace };