@glassflow-ai/rius 0.7.0 → 1.0.0

package/dist/index.d.ts

@@ -14,6 +14,17 @@ interface RiusOptions {
     endpoint?: string;
     apiKey?: string;
     serviceName?: string;
+    /**
+     * The running build's version, stamped on the resource as `service.version`.
+     * There is deliberately NO default: `service.name` already shows what a
+     * missing value costs, where the `unknown_service` placeholder merges every
+     * unconfigured process into one bucket. An absent version is a visibly
+     * absent version, so the resource simply omits the key.
+     *
+     * Resolution: this option, then `RIUS_SERVICE_VERSION`, then
+     * `service.version` inside `OTEL_RESOURCE_ATTRIBUTES`, then unset.
+     */
+    serviceVersion?: string;
     disabled?: boolean;
     sampleRate?: number;
     captureContent?: boolean;
@@ -22,6 +33,34 @@ interface RiusOptions {
     heartbeatInterval?: number;
     heartbeat?: boolean;
     agentName?: string;
+    /**
+     * A STABLE identifier for the agent this process is, stamped on the
+     * resource as `rius.main_agent.id`. A registry id or a hosted agent's ARN,
+     * NOT a transient in-memory or process-local id: a uuid minted at startup
+     * identifies a run, not an agent, and would split one agent into a fresh
+     * bucket per restart. `service.instance.id` already answers "which
+     * process". Absent by default and never defaulted.
+     *
+     * Resolution: this option, then `RIUS_MAIN_AGENT_ID`, then unset.
+     */
+    mainAgentId?: string;
+    /**
+     * A human-readable description of the agent this process is, stamped as
+     * `rius.main_agent.description`. This option, then
+     * `RIUS_MAIN_AGENT_DESCRIPTION`, then unset.
+     */
+    mainAgentDescription?: string;
+    /**
+     * The version of the AGENT DEFINITION this process runs — its prompt, tools
+     * and policy — stamped as `rius.main_agent.version`. Deliberately NOT
+     * `serviceVersion`, which is the version of the build hosting it: the two
+     * move independently, and neither is ever derived from the other.
+     *
+     * Resolution: this option, then `RIUS_MAIN_AGENT_VERSION`, then unset. The
+     * OTel environment is not consulted, unlike `serviceVersion`: no convention
+     * defines this key, so `OTEL_RESOURCE_ATTRIBUTES` cannot be carrying it.
+     */
+    mainAgentVersion?: string;
     partialSpans?: boolean;
     /** Seconds to debounce a pending-span snapshot after span start. */
     partialSpansDelay?: number;
@@ -31,6 +70,22 @@ interface RiusOptions {
      * one with `withSession()` instead, which overrides this default.
      */
     sessionId?: string;
+    /**
+     * What to do when another SDK already holds the OpenTelemetry global tracer
+     * provider at `init()` (`RIUS_BRIDGE_FOREIGN_PROVIDER`; off by default).
+     *
+     * Off, Rius keeps to its own provider: LLM spans started inside the other
+     * SDK's spans arrive without their parent, flagged `rius.parent.foreign`,
+     * counted in the heartbeat, and the first one logs a warning. On, Rius also
+     * exports the other SDK's spans (the parents), under Rius's resource
+     * identity and subject to Rius's sampling and content settings, and it never
+     * modifies what the other SDK exports. Either way the resource records the
+     * conflict as `rius.sdk.global_provider`.
+     *
+     * Off by default: exporting another SDK's spans is consent the caller gives
+     * explicitly.
+     */
+    bridgeForeignProvider?: boolean;
 }
 
 type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
@@ -174,8 +229,8 @@ interface SpanOptions {
     /**
      * The OpenTelemetry `SpanKind` FIELD (INTERNAL, CLIENT, …), orthogonal to
      * `kind` above, which is our taxonomy attribute. Conventions set it per
-     * operation — a remote tool call is CLIENT — so it is opt-in here and left
-     * at the tracer's default (INTERNAL) otherwise.
+     * operation, so by default it is derived from `kind` (see `otelSpanKind`);
+     * set this to override, as the MCP wrapper does for a remote tool call.
      */
     otelKind?: SpanKind$1;
     input?: unknown;
@@ -186,6 +241,85 @@ interface SpanOptions {
      * `withUser` around the handler.
      */
     userId?: string;
+    /**
+     * The tool name a TOOL span carries as `gen_ai.tool.name`. Defaults to the
+     * span name, which is what a caller who passes nothing meant back when the
+     * two were necessarily the same string. Pass it explicitly whenever the
+     * span name is not the bare tool name — and prefer passing it INSTEAD of a
+     * span name, which gets you the conventions' `execute_tool {tool}` name for
+     * free. With neither, the span is named `execute_tool` and carries no tool
+     * name: nothing is invented.
+     */
+    toolName?: string;
+    /**
+     * The id of the model's tool-call message this TOOL span answers, set as
+     * `gen_ai.tool.call.id`. Caller-supplied and nothing else: the id belongs
+     * to the assistant turn that requested the call, which the SDK never sees,
+     * so there is nothing to derive it from and it is omitted rather than
+     * invented. Scoped to TOOL, like `toolName`: on any other kind the key
+     * would claim a tool call that is not there.
+     */
+    toolCallId?: string;
+    /**
+     * What kind of tool this TOOL span ran, set as `gen_ai.tool.type` — the
+     * conventions' examples are `"function"`, `"extension"` and `"datastore"`.
+     * Caller-supplied, recorded verbatim, never guessed from the callable: a
+     * wrapped function is not automatically a `function` tool, since the same
+     * wrapper is what an agent-side extension call goes through. Scoped to
+     * TOOL, like `toolCallId`.
+     */
+    toolType?: string;
+    /**
+     * The index, collection or knowledge base a RETRIEVER span searched, set as
+     * `gen_ai.data_source.id`. Ignored on every other kind: the key means the
+     * target of a retrieval, and putting it elsewhere would make the attribute
+     * mean something different depending on the span. Omitted when not passed,
+     * never guessed.
+     */
+    dataSourceId?: string;
+    /**
+     * How many documents a RETRIEVER span asked for, set as
+     * `gen_ai.retrieval.top_k`. Ignored on every other kind. What came back is
+     * not an option here: it is unknown at span creation, so it is recorded
+     * afterwards with `Observation.setRetrievedDocuments`.
+     */
+    topK?: number;
+    /**
+     * The agent an AGENT span INVOKES, set as `gen_ai.agent.name`. That is what
+     * the key means on an invoke-agent span, where the conventions make it
+     * Conditionally Required; on an execute-tool span the same key means the
+     * agent DOING the call, which is why this is scoped to AGENT here. Unset,
+     * it falls back to the agent name `init()` was given. It is never taken
+     * from the span name, unlike the tool name: that fallback exists only
+     * because a tool's name and its span name were historically one string,
+     * and a wrong agent name mislabels every span beneath it. Ignored on every
+     * other kind, where the key would read as "the agent that produced this
+     * span" — which is what the resource attribute of the same name says.
+     *
+     * On the scoped surface this name also becomes the enclosing agent scope,
+     * so TOOL spans opened inside the callback carry it as the agent that
+     * EXECUTED them. See {@link startAsCurrentSpan}.
+     */
+    agentName?: string;
+    /**
+     * The invoked agent's identifier, set as `gen_ai.agent.id`. This key is for
+     * a HOSTED agent resource, such as a Bedrock agent ARN; the conventions
+     * advise against recording a transient in-memory instance id there, so an
+     * in-process agent leaves it unset. Ignored on every other kind.
+     */
+    agentId?: string;
+    /**
+     * The invoked agent's version, set as `gen_ai.agent.version`: the version of
+     * the agent DEFINITION this span invoked — its prompt, tools and policy.
+     * Taken verbatim; the conventions' own examples are `1.0.0` and
+     * `2025-05-01`, so there is no one format to hold callers to.
+     *
+     * Never derived from `service.version` (the build running this process) nor
+     * from the main-agent version (the agent this process IS): a process at one
+     * version can invoke agents at several others. Ignored on every other kind,
+     * like the name and the id it accompanies.
+     */
+    agentVersion?: string;
     /**
      * Identity attributes to set at span CREATION rather than after it. Pending
      * snapshots are built at start, so anything a caller would otherwise
@@ -202,6 +336,20 @@ declare class Observation {
     constructor(span: Span);
     setInput(value: unknown): this;
     setOutput(value: unknown): this;
+    /**
+     * Record what a retrieval returned, as `gen_ai.retrieval.documents`.
+     *
+     * The conventions define this as an array of objects, each with an optional
+     * `id` and an optional `score`. Identifiers and relevance, never document
+     * text, which is why it is not treated as content: it survives
+     * `captureContent: false` the way token counts do. Put the retrieved text in
+     * `setOutput` if you want it captured, and masking applies to it there.
+     *
+     * Unlike `dataSourceId` and `topK`, which describe the request and are
+     * passed at span creation, this is only knowable once the search has run, so
+     * it never reaches a pending snapshot.
+     */
+    setRetrievedDocuments(documents: unknown): this;
     /**
      * Set an arbitrary attribute. Primitives and homogeneous primitive arrays
      * are passed through as the OTel values they are; objects are JSON-encoded
@@ -210,9 +358,16 @@ declare class Observation {
      */
     setAttribute(key: string, value: unknown): this;
     /**
-     * Record an error on the span and set ERROR status. This is exactly what the
-     * `startAsCurrent*` helpers do on a thrown error, exposed so the manual
-     * `start*` path does not have to reach through `.span` to match it.
+     * Record an error on the span, set ERROR status and `error.type`. This is
+     * exactly what the `startAsCurrent*` helpers do on a thrown error, exposed
+     * so the manual `start*` path does not have to reach through `.span` to
+     * match it.
+     *
+     * `error.type` is Conditionally Required by the GenAI conventions on every
+     * span that ends in an error, and every helper's throw path funnels through
+     * here, so this is the one place that sets it. The error's name or class
+     * (see errorType), never the message: it must stay low-cardinality and free
+     * of echoed content.
      *
      * Accepts `unknown` because that is what a `catch` binding is; a non-Error
      * throwable is wrapped so `recordException` still gets a real Error.
@@ -225,19 +380,35 @@ declare class Observation {
 /**
  * Create a span and return a handle. You MUST call end() (or use `using`).
  * The span is parented to whatever is current but does NOT become current.
+ *
+ * Because it never becomes current, an AGENT span created here opens no
+ * agent scope: a TOOL span started while it is open falls back to the
+ * configured agent name for `gen_ai.agent.name` rather than naming this one.
+ * Use {@link startAsCurrentSpan} (or `observe`) where that matters.
+ *
+ * The name is optional: omit it and the span is named the way the GenAI
+ * conventions say to, `{operation} {target}` — `execute_tool get_weather`,
+ * `invoke_agent planner`, `retrieval docs-index` — from the attributes it is
+ * being created with. A name you pass always wins.
  */
 declare function startSpan(name: string, options?: SpanOptions): Observation;
+declare function startSpan(options?: SpanOptions): Observation;
 /** The body of a scoped span. */
 type SpanBody<T> = (observation: Observation) => Promise<T> | T;
 /**
  * Run `fn` with a new span active, so spans created inside it nest under this
  * one across async boundaries. Auto-ends, records exceptions, rethrows.
  *
- * `options` is optional, so the common case is `startAsCurrentSpan(name, fn)`
- * rather than `startAsCurrentSpan(name, {}, fn)`. The callback stays last.
+ * Both the name and `options` are optional, and the callback always comes
+ * last: `startAsCurrentSpan(name, fn)`, `startAsCurrentSpan(options, fn)` and
+ * `startAsCurrentSpan(fn)` all work, as does the full three-argument form.
+ * Omitting the name asks for the conventions' `{operation} {target}` name;
+ * see {@link startSpan}.
  */
 declare function startAsCurrentSpan<T>(name: string, fn: SpanBody<T>): Promise<T>;
 declare function startAsCurrentSpan<T>(name: string, options: SpanOptions, fn: SpanBody<T>): Promise<T>;
+declare function startAsCurrentSpan<T>(options: SpanOptions, fn: SpanBody<T>): Promise<T>;
+declare function startAsCurrentSpan<T>(fn: SpanBody<T>): Promise<T>;
 
 /**
  * Options for {@link startGeneration} and {@link startAsCurrentGeneration}:
@@ -248,17 +419,26 @@ interface GenerationOptions {
     provider?: string;
     input?: unknown;
     /**
-     * Request parameters, each recorded as `gen_ai.request.<key>` — for example
-     * `{ temperature: 0.2, max_tokens: 512 }`. Keys are passed through verbatim,
-     * so use the provider's own parameter names.
+     * Request parameters, for example `{ temperature: 0.2, max_tokens: 512 }`,
+     * recorded at span creation so they ride pending snapshots.
+     *
+     * A parameter the GenAI conventions define, under its canonical name or a
+     * recognised provider spelling (OpenAI's `max_completion_tokens`, Google's
+     * `maxOutputTokens`, a camelCase `topP`), is recorded under its canonical
+     * `gen_ai.request.*` key and only that one. Everything else is recorded
+     * under `rius.request.<key>`, this SDK's own namespace, with the key
+     * otherwise untouched. Values that are not scalars or homogeneous scalar
+     * arrays are JSON-encoded; `null` and `undefined` mean "not set" and are
+     * skipped. The `model` and `reasoningLevel` options win over a parameter
+     * that maps to the same key.
      */
     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.
+     * values. Provider-defined string, recorded verbatim. Passing
+     * `reasoning_effort` through `modelParameters` lands on the same key; this
+     * option wins when both are given.
      */
     reasoningLevel?: string;
     /**
@@ -271,6 +451,17 @@ interface GenerationOptions {
      * creation and, for the scoped variant, on every span opened inside it.
      */
     userId?: string;
+    /**
+     * The output modality requested of the model (`gen_ai.output.type`) —
+     * `"text"`, `"json"`, `"image"` or `"speech"` per the conventions, which
+     * make it Conditionally Required when the request asks for a specific
+     * output format. An option rather than a setter because it is a property of
+     * the REQUEST: known before the call, so it is set at span creation and
+     * reaches pending snapshots. The string is recorded verbatim, not validated
+     * against the four members: the enum is open, and a provider's own spelling
+     * is still what the caller asked for.
+     */
+    outputType?: string;
     /**
      * Operation name (`gen_ai.operation.name`); default `"chat"`. Set it for
      * `text_completion`, `embeddings` or `generate_content` calls, as the
@@ -282,11 +473,34 @@ interface GenerationOptions {
 declare class Generation extends Observation {
     private readonly provider?;
     private firstTokenRecorded;
+    /**
+     * Monotonic clock at construction, which is span creation for both
+     * `startGeneration` and the scoped form. The API `Span` exposes no start
+     * time, so this is what `recordFirstToken` measures the first chunk against.
+     */
+    private readonly startedAt;
+    /**
+     * The latest normalized input / output and the tool definitions, kept so
+     * `rius.context.sizes` can be computed from all three once, in {@link end}.
+     */
+    private inputMessages?;
+    private outputMessages?;
+    private tools?;
     /**
      * 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);
+    /**
+     * Computed once, as the span ends, rather than on every content write: a
+     * generation with tools, input and output would otherwise pay for it three
+     * times, and only the last result matters. Derived from the normalized
+     * messages BEFORE truncation, which is what makes it trustworthy when the
+     * content attributes are not.
+     */
+    private setContextSizes;
+    /** Ends the span after recording the context sizes; idempotent like the base. */
+    end(): void;
     /**
      * Record the request messages (`gen_ai.input.messages`), normalised to the
      * GenAI `{role, parts}` shape like the Python SDK does: bare strings, OpenAI
@@ -306,6 +520,15 @@ declare class Generation extends Observation {
      */
     setToolDefinitions(tools: unknown[]): this;
     setModel(model: string): this;
+    /**
+     * The provider's identifier for this completion (`gen_ai.response.id`) —
+     * OpenAI's `id`, Anthropic's `id`, and so on. A post-call setter and not a
+     * creation option for the reason `setModel` is one: the value arrives WITH
+     * the response, so no span can carry it at creation and no pending snapshot
+     * can either. Recorded verbatim; it is an opaque provider string, and it is
+     * not content, so it survives `captureContent: false`.
+     */
+    setResponseId(id: string): this;
     /**
      * Token usage (`gen_ai.usage.*`). Pass provider-reported values as-is;
      * never pre-add anything. Per the GenAI conventions, `inputTokens` is the
@@ -341,30 +564,93 @@ declare class Generation extends Observation {
      */
     setFinishReasons(reasons: string | string[]): this;
     /**
-     * The TTFT anchor: event time minus span start. Idempotent: only the
-     * first call records the event, so a streaming loop can call this
-     * unconditionally on every chunk without inflating the span. A no-op
-     * after the span has ended.
+     * Mark the arrival of the first streamed token. Records the
+     * `gen_ai.first_token` event (the timestamp the backend derives TTFT from)
+     * and, per the GenAI conventions, the derived
+     * `gen_ai.response.time_to_first_chunk` (seconds since span creation) plus
+     * `gen_ai.request.stream = true`: a first chunk arriving is what tells the
+     * SDK the request streamed. Idempotent: only the first call records, so a
+     * streaming loop can call this unconditionally on every chunk without
+     * inflating the span. A no-op after the span has ended.
      */
     recordFirstToken(): this;
 }
-/** Create a generation span and return a handle. You MUST call end(). */
+/**
+ * Create a generation span and return a handle. You MUST call end().
+ *
+ * The name is optional; omitted, the span is named `{operation} {model}`.
+ */
 declare function startGeneration(name: string, options?: GenerationOptions): Generation;
+declare function startGeneration(options?: GenerationOptions): Generation;
 /** The body of a scoped generation. */
 type GenerationBody<T> = (generation: Generation) => Promise<T> | T;
 /**
  * Run `fn` with a generation span active. Auto-ends, records exceptions.
  *
- * `options` is optional, so `startAsCurrentGeneration(name, fn)` works without
- * an empty object. The callback stays last.
+ * Both the name and `options` are optional and the callback stays last, so
+ * `startAsCurrentGeneration({ model: "gpt-4o" }, fn)` names the span
+ * `chat gpt-4o` for you.
  */
 declare function startAsCurrentGeneration<T>(name: string, fn: GenerationBody<T>): Promise<T>;
 declare function startAsCurrentGeneration<T>(name: string, options: GenerationOptions, fn: GenerationBody<T>): Promise<T>;
+declare function startAsCurrentGeneration<T>(options: GenerationOptions, fn: GenerationBody<T>): Promise<T>;
+declare function startAsCurrentGeneration<T>(fn: GenerationBody<T>): Promise<T>;
 
 /** Options for {@link observe}. */
 interface ObserveOptions {
     name?: string;
     kind?: SpanKind;
+    /**
+     * The tool name a TOOL-kind wrapper carries as `gen_ai.tool.name`. Defaults
+     * to the span name, so a wrapped function whose name IS the tool name needs
+     * nothing; pass it when the two differ.
+     */
+    toolName?: string;
+    /**
+     * The id of the model tool-call a TOOL-kind wrapper answers, set as
+     * `gen_ai.tool.call.id`. Only the caller has it — a wrapper sees the
+     * arguments, never the assistant message that produced them — so it is
+     * passed or omitted, never derived. Ignored on every other kind.
+     */
+    toolCallId?: string;
+    /**
+     * What kind of tool a TOOL-kind wrapper runs, set as `gen_ai.tool.type`
+     * (`"function"`, `"extension"`, `"datastore"`). Recorded verbatim and never
+     * inferred from the wrapped callable: the wrapper shape says nothing about
+     * where the tool actually executes. Ignored on every other kind.
+     */
+    toolType?: string;
+    /**
+     * The index, collection or knowledge base a RETRIEVER-kind wrapper searched,
+     * set as `gen_ai.data_source.id`. Ignored on every other kind.
+     */
+    dataSourceId?: string;
+    /**
+     * How many documents a RETRIEVER-kind wrapper asked for, set as
+     * `gen_ai.retrieval.top_k`. Ignored on every other kind.
+     */
+    topK?: number;
+    /**
+     * The agent an AGENT-kind wrapper invokes, set as `gen_ai.agent.name`.
+     * Unset, it falls back to the agent name `init()` was given; it is never
+     * taken from the wrapped function's name. Ignored on every other kind.
+     *
+     * It also scopes the call: TOOL spans opened while the wrapped function
+     * runs carry this name as the agent that EXECUTED them, which is what the
+     * same key means on an execute-tool span.
+     */
+    agentName?: string;
+    /**
+     * The invoked agent's identifier (`gen_ai.agent.id`). For a HOSTED agent
+     * resource such as a Bedrock agent ARN; an in-process agent leaves it unset.
+     */
+    agentId?: string;
+    /**
+     * The invoked agent's version (`gen_ai.agent.version`): the version of the
+     * agent definition, taken verbatim and never derived from the service
+     * version or from the version of the agent this process is.
+     */
+    agentVersion?: string;
     captureInput?: boolean;
     captureOutput?: boolean;
 }
@@ -448,6 +734,6 @@ declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T)
  */
 declare function withUser<T>(userId: string, fn: (userId: string) => T): T;
 
-declare const VERSION = "0.7.0";
+declare const VERSION = "1.0.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, withUser, withWorkspace };