@glassflow-ai/rius 0.5.0 → 0.6.1

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
@@ -231,6 +254,22 @@ interface GenerationOptions {
      * `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 {
@@ -241,8 +280,24 @@ declare class Generation extends Observation {
      * 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;
@@ -307,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.
@@ -339,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.5.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.1";
 
-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
@@ -231,6 +254,22 @@ interface GenerationOptions {
      * `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 {
@@ -241,8 +280,24 @@ declare class Generation extends Observation {
      * 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;
@@ -307,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.
@@ -339,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.5.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.1";
 
-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 };