@glassflow-ai/rius 0.2.4 → 0.3.0

package/dist/index.cjs

@@ -89,7 +89,10 @@ function resolveConfig(options = {}, env = process.env) {
     // on every heartbeat payload, so `??` would be wrong here.
     agentName: options.agentName || env.RIUS_AGENT_NAME || serviceName,
     partialSpans: options.partialSpans ?? bool("RIUS_PARTIAL_SPANS", env.RIUS_PARTIAL_SPANS, false),
-    partialSpansDelayMs: partialSpansDelaySeconds * 1e3
+    partialSpansDelayMs: partialSpansDelaySeconds * 1e3,
+    // Empty is unset, like agentName: a blank session id would group every
+    // span under the meaningless session "".
+    sessionId: options.sessionId || env.RIUS_SESSION_ID || void 0
   };
 }
 var DEFAULT_ENDPOINT, DEFAULT_SERVICE_NAME, HEARTBEAT_INTERVAL_MIN, HEARTBEAT_INTERVAL_MAX, DEFAULT_HEARTBEAT_INTERVAL, PARTIAL_SPANS_DELAY_MIN, PARTIAL_SPANS_DELAY_MAX, DEFAULT_PARTIAL_SPANS_DELAY, AFFIRMATIVE, NEGATIVE;
@@ -234,12 +237,11 @@ function httpTransport(url, headers) {
     }
   };
 }
-var import_node_crypto, import_node_module, PAYLOAD_VERSION, OPEN_TRACES_CAP, DEFAULT_PING_TIMEOUT_MS, DEFAULT_FINAL_PING_TIMEOUT_MS, SDK_VERSION, OpenRootSpanTracker, HeartbeatSender;
+var import_node_module, PAYLOAD_VERSION, OPEN_TRACES_CAP, DEFAULT_PING_TIMEOUT_MS, DEFAULT_FINAL_PING_TIMEOUT_MS, SDK_VERSION, OpenRootSpanTracker, HeartbeatSender;
 var init_heartbeat = __esm({
   "src/heartbeat.ts"() {
     "use strict";
     init_cjs_shims();
-    import_node_crypto = require("crypto");
     import_node_module = require("module");
     PAYLOAD_VERSION = 1;
     OPEN_TRACES_CAP = 32;
@@ -282,8 +284,8 @@ var init_heartbeat = __esm({
       }
     };
     HeartbeatSender = class {
-      /** Identity of one process lifetime, fresh per sender. */
-      instanceId = (0, import_node_crypto.randomUUID)();
+      /** Identity of one process lifetime; injected, shared with span resources. */
+      instanceId;
       agentName;
       tracker;
       intervalMs;
@@ -294,6 +296,7 @@ var init_heartbeat = __esm({
       stopped = false;
       deliveryWarned = false;
       constructor(opts) {
+        this.instanceId = opts.instanceId;
         this.agentName = opts.agentName;
         this.tracker = opts.tracker;
         this.intervalMs = opts.intervalMs;
@@ -353,15 +356,17 @@ function kindAttributes(kind) {
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
   return attributes;
 }
-var TRACER_NAME, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_REQUEST_PREFIX, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
+var TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_REQUEST_PREFIX, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
 var init_semconv = __esm({
   "src/semconv.ts"() {
     "use strict";
     init_cjs_shims();
     TRACER_NAME = "glassflow";
+    SERVICE_INSTANCE_ID = "service.instance.id";
     OPENINFERENCE_SPAN_KIND = "openinference.span.kind";
     INPUT_VALUE = "input.value";
     OUTPUT_VALUE = "output.value";
+    SESSION_ID = "session.id";
     GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
     GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
     GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
@@ -427,7 +432,10 @@ var init_semconv = __esm({
       OPENINFERENCE_SPAN_KIND,
       GEN_AI_OPERATION_NAME,
       GEN_AI_PROVIDER_NAME,
-      GEN_AI_TOOL_NAME
+      GEN_AI_TOOL_NAME,
+      // Identity, not content: a pending span must be groupable into its
+      // session while still running, that is the live view's whole point.
+      SESSION_ID
     ]);
     PENDING_IDENTITY_PREFIXES = [GEN_AI_REQUEST_PREFIX];
   }
@@ -968,6 +976,40 @@ var init_pending = __esm({
   }
 });
 
+// src/session.ts
+function withSession(sessionIdOrFn, maybeFn) {
+  const [sessionId, fn] = typeof sessionIdOrFn === "function" ? [(0, import_node_crypto.randomUUID)(), sessionIdOrFn] : [sessionIdOrFn, maybeFn];
+  return import_api5.context.with(import_api5.context.active().setValue(SESSION_KEY, sessionId), () => fn(sessionId));
+}
+var import_node_crypto, import_api5, SESSION_KEY, SessionSpanProcessor;
+var init_session = __esm({
+  "src/session.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_node_crypto = require("crypto");
+    import_api5 = require("@opentelemetry/api");
+    init_semconv();
+    SESSION_KEY = (0, import_api5.createContextKey)("rius-session-id");
+    SessionSpanProcessor = class {
+      constructor(defaultSessionId) {
+        this.defaultSessionId = defaultSessionId;
+      }
+      defaultSessionId;
+      onStart(span, parentContext) {
+        const value = parentContext.getValue(SESSION_KEY);
+        const sessionId = typeof value === "string" ? value : this.defaultSessionId;
+        if (sessionId !== void 0) span.setAttribute(SESSION_ID, sessionId);
+      }
+      onEnd(_span) {
+      }
+      async forceFlush() {
+      }
+      async shutdown() {
+      }
+    };
+  }
+});
+
 // src/client.ts
 function init(options = {}) {
   if (globalClient !== void 0) {
@@ -991,13 +1033,18 @@ function init(options = {}) {
       mask: config.mask
     }) : health;
     const batch = new import_sdk_trace_base.BatchSpanProcessor(exporter);
+    processors.add(new SessionSpanProcessor(config.sessionId));
     if (config.partialSpans) {
       processors.add(new PendingSpanProcessor(batch, { delayMs: config.partialSpansDelayMs }));
     }
     processors.add(batch);
   }
+  const instanceId = (0, import_node_crypto2.randomUUID)();
   const provider = new import_sdk_trace_node.NodeTracerProvider({
-    resource: (0, import_resources.resourceFromAttributes)({ [import_semantic_conventions.ATTR_SERVICE_NAME]: config.serviceName }),
+    resource: (0, import_resources.resourceFromAttributes)({
+      [import_semantic_conventions.ATTR_SERVICE_NAME]: config.serviceName,
+      [SERVICE_INSTANCE_ID]: instanceId
+    }),
     // Always ParentBased, with no AlwaysOn shortcut at rate 1. They are not
     // equivalent: ParentBased honours a remote UNSAMPLED parent and drops,
     // while AlwaysOn records regardless, producing children of a span the
@@ -1017,6 +1064,7 @@ function init(options = {}) {
       headers: authHeaders,
       intervalMs: config.heartbeatIntervalMs,
       agentName: config.agentName,
+      instanceId,
       tracker,
       transport: options.heartbeatTransport
     });
@@ -1031,14 +1079,15 @@ function init(options = {}) {
   return globalClient;
 }
 function getTracer() {
-  return import_api5.trace.getTracer(TRACER_NAME);
+  return import_api6.trace.getTracer(TRACER_NAME);
 }
-var import_api5, import_exporter_trace_otlp_proto, import_resources, import_sdk_trace_base, import_sdk_trace_node, import_semantic_conventions, sinks, heartbeats, createClient, RiusClient, globalClient;
+var import_node_crypto2, import_api6, import_exporter_trace_otlp_proto, import_resources, import_sdk_trace_base, import_sdk_trace_node, import_semantic_conventions, sinks, heartbeats, createClient, RiusClient, globalClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
     init_cjs_shims();
-    import_api5 = require("@opentelemetry/api");
+    import_node_crypto2 = require("crypto");
+    import_api6 = require("@opentelemetry/api");
     import_exporter_trace_otlp_proto = require("@opentelemetry/exporter-trace-otlp-proto");
     import_resources = require("@opentelemetry/resources");
     import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
@@ -1052,6 +1101,7 @@ var init_client = __esm({
     init_masking();
     init_pending();
     init_semconv();
+    init_session();
     sinks = /* @__PURE__ */ new WeakMap();
     heartbeats = /* @__PURE__ */ new WeakMap();
     RiusClient = class _RiusClient {
@@ -1095,7 +1145,7 @@ var init_client = __esm({
         } finally {
           if (globalClient === this) {
             globalClient = void 0;
-            import_api5.trace.disable();
+            import_api6.trace.disable();
           }
         }
       }
@@ -1117,7 +1167,8 @@ __export(index_exports, {
   startAsCurrentGeneration: () => startAsCurrentGeneration,
   startAsCurrentSpan: () => startAsCurrentSpan,
   startGeneration: () => startGeneration,
-  startSpan: () => startSpan
+  startSpan: () => startSpan,
+  withSession: () => withSession
 });
 module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
@@ -1233,8 +1284,9 @@ function observe(fn, options = {}) {
 
 // src/index.ts
 init_semconv();
+init_session();
 init_spans();
-var VERSION = "0.2.4";
+var VERSION = "0.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Generation,
@@ -1248,5 +1300,6 @@ var VERSION = "0.2.4";
   startAsCurrentGeneration,
   startAsCurrentSpan,
   startGeneration,
-  startSpan
+  startSpan,
+  withSession
 });

package/dist/index.d.cts

@@ -25,6 +25,12 @@ interface RiusOptions {
     partialSpans?: boolean;
     /** Seconds to debounce a pending-span snapshot after span start. */
     partialSpansDelay?: number;
+    /**
+     * Process-wide session id, stamped as `session.id` on every span. For
+     * one-run-per-process agents; a server handling many sessions scopes each
+     * one with `withSession()` instead, which overrides this default.
+     */
+    sessionId?: string;
 }
 
 type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
@@ -203,6 +209,30 @@ interface ObserveOptions {
  */
 declare function observe<F extends (...args: never[]) => unknown>(fn: F, options?: ObserveOptions): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
 
-declare const VERSION = "0.2.4";
+/**
+ * Scope every span started inside `fn` to one session id.
+ *
+ * Pass the application's own id (a conversation id, a job id) to correlate
+ * with it; omit it to mint a fresh UUID for the scope. Either way the scope's
+ * id is passed to the callback, so it can be logged or handed to the next
+ * turn. Nested scopes override outer ones, and an active scope overrides the
+ * `init({ sessionId })` default.
+ *
+ * There is deliberately no process-wide auto-generation: without an id the
+ * backend groups each trace as its own session, which stays true in a server
+ * handling many users, while an auto-minted global id would merge every user
+ * into one. A generated id is only ever scoped to an explicit callback, where
+ * "this is one session" is the caller's own claim.
+ *
+ * ```typescript
+ * await withSession(conversationId, async () => {
+ *   await handleTurn(message) // every span of the turn carries session.id
+ * })
+ * ```
+ */
+declare function withSession<T>(fn: (sessionId: string) => T): T;
+declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T): T;
+
+declare const VERSION = "0.3.0";
 
-export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, getTracer, init, observe, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan };
+export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, getTracer, init, observe, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession };

package/dist/index.d.ts

@@ -25,6 +25,12 @@ interface RiusOptions {
     partialSpans?: boolean;
     /** Seconds to debounce a pending-span snapshot after span start. */
     partialSpansDelay?: number;
+    /**
+     * Process-wide session id, stamped as `session.id` on every span. For
+     * one-run-per-process agents; a server handling many sessions scopes each
+     * one with `withSession()` instead, which overrides this default.
+     */
+    sessionId?: string;
 }
 
 type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
@@ -203,6 +209,30 @@ interface ObserveOptions {
  */
 declare function observe<F extends (...args: never[]) => unknown>(fn: F, options?: ObserveOptions): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
 
-declare const VERSION = "0.2.4";
+/**
+ * Scope every span started inside `fn` to one session id.
+ *
+ * Pass the application's own id (a conversation id, a job id) to correlate
+ * with it; omit it to mint a fresh UUID for the scope. Either way the scope's
+ * id is passed to the callback, so it can be logged or handed to the next
+ * turn. Nested scopes override outer ones, and an active scope overrides the
+ * `init({ sessionId })` default.
+ *
+ * There is deliberately no process-wide auto-generation: without an id the
+ * backend groups each trace as its own session, which stays true in a server
+ * handling many users, while an auto-minted global id would merge every user
+ * into one. A generated id is only ever scoped to an explicit callback, where
+ * "this is one session" is the caller's own claim.
+ *
+ * ```typescript
+ * await withSession(conversationId, async () => {
+ *   await handleTurn(message) // every span of the turn carries session.id
+ * })
+ * ```
+ */
+declare function withSession<T>(fn: (sessionId: string) => T): T;
+declare function withSession<T>(sessionId: string, fn: (sessionId: string) => T): T;
+
+declare const VERSION = "0.3.0";
 
-export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, getTracer, init, observe, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan };
+export { Generation, type GenerationBody, type GenerationOptions, type InitOptions, type Mask, Observation, type ObserveOptions, RiusClient, type RiusOptions, type SpanBody, SpanKind, type SpanOptions, VERSION, getTracer, init, observe, startAsCurrentGeneration, startAsCurrentSpan, startGeneration, startSpan, withSession };

package/dist/index.js

@@ -76,7 +76,10 @@ function resolveConfig(options = {}, env = process.env) {
     // on every heartbeat payload, so `??` would be wrong here.
     agentName: options.agentName || env.RIUS_AGENT_NAME || serviceName,
     partialSpans: options.partialSpans ?? bool("RIUS_PARTIAL_SPANS", env.RIUS_PARTIAL_SPANS, false),
-    partialSpansDelayMs: partialSpansDelaySeconds * 1e3
+    partialSpansDelayMs: partialSpansDelaySeconds * 1e3,
+    // Empty is unset, like agentName: a blank session id would group every
+    // span under the meaningless session "".
+    sessionId: options.sessionId || env.RIUS_SESSION_ID || void 0
   };
 }
 var DEFAULT_ENDPOINT, DEFAULT_SERVICE_NAME, HEARTBEAT_INTERVAL_MIN, HEARTBEAT_INTERVAL_MAX, DEFAULT_HEARTBEAT_INTERVAL, PARTIAL_SPANS_DELAY_MIN, PARTIAL_SPANS_DELAY_MAX, DEFAULT_PARTIAL_SPANS_DELAY, AFFIRMATIVE, NEGATIVE;
@@ -206,7 +209,6 @@ var init_exportHealth = __esm({
 });
 
 // src/heartbeat.ts
-import { randomUUID } from "crypto";
 import { createRequire } from "module";
 function httpTransport(url, headers) {
   return async (payload, timeoutMs) => {
@@ -269,8 +271,8 @@ var init_heartbeat = __esm({
       }
     };
     HeartbeatSender = class {
-      /** Identity of one process lifetime, fresh per sender. */
-      instanceId = randomUUID();
+      /** Identity of one process lifetime; injected, shared with span resources. */
+      instanceId;
       agentName;
       tracker;
       intervalMs;
@@ -281,6 +283,7 @@ var init_heartbeat = __esm({
       stopped = false;
       deliveryWarned = false;
       constructor(opts) {
+        this.instanceId = opts.instanceId;
         this.agentName = opts.agentName;
         this.tracker = opts.tracker;
         this.intervalMs = opts.intervalMs;
@@ -340,15 +343,17 @@ function kindAttributes(kind) {
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
   return attributes;
 }
-var TRACER_NAME, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_REQUEST_PREFIX, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
+var TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, GEN_AI_OPERATION_NAME, GEN_AI_PROVIDER_NAME, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_INPUT_MESSAGES, GEN_AI_OUTPUT_MESSAGES, GEN_AI_RESPONSE_FINISH_REASONS, GEN_AI_TOOL_NAME, GEN_AI_REQUEST_PREFIX, MCP_RESULT_TYPE, GEN_AI_FIRST_TOKEN_EVENT, SpanKind, OPERATION_BY_KIND, CONTENT_ATTRIBUTES, CONTENT_ATTRIBUTE_PREFIXES, CONTENT_ATTRIBUTE_SUFFIXES, GLASSFLOW_SPAN_PENDING, PENDING_IDENTITY_ATTRIBUTES, PENDING_IDENTITY_PREFIXES;
 var init_semconv = __esm({
   "src/semconv.ts"() {
     "use strict";
     init_esm_shims();
     TRACER_NAME = "glassflow";
+    SERVICE_INSTANCE_ID = "service.instance.id";
     OPENINFERENCE_SPAN_KIND = "openinference.span.kind";
     INPUT_VALUE = "input.value";
     OUTPUT_VALUE = "output.value";
+    SESSION_ID = "session.id";
     GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
     GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
     GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
@@ -414,7 +419,10 @@ var init_semconv = __esm({
       OPENINFERENCE_SPAN_KIND,
       GEN_AI_OPERATION_NAME,
       GEN_AI_PROVIDER_NAME,
-      GEN_AI_TOOL_NAME
+      GEN_AI_TOOL_NAME,
+      // Identity, not content: a pending span must be groupable into its
+      // session while still running, that is the live view's whole point.
+      SESSION_ID
     ]);
     PENDING_IDENTITY_PREFIXES = [GEN_AI_REQUEST_PREFIX];
   }
@@ -955,7 +963,42 @@ var init_pending = __esm({
   }
 });
 
+// src/session.ts
+import { randomUUID } from "crypto";
+import { context as apiContext, createContextKey } from "@opentelemetry/api";
+function withSession(sessionIdOrFn, maybeFn) {
+  const [sessionId, fn] = typeof sessionIdOrFn === "function" ? [randomUUID(), sessionIdOrFn] : [sessionIdOrFn, maybeFn];
+  return apiContext.with(apiContext.active().setValue(SESSION_KEY, sessionId), () => fn(sessionId));
+}
+var SESSION_KEY, SessionSpanProcessor;
+var init_session = __esm({
+  "src/session.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_semconv();
+    SESSION_KEY = createContextKey("rius-session-id");
+    SessionSpanProcessor = class {
+      constructor(defaultSessionId) {
+        this.defaultSessionId = defaultSessionId;
+      }
+      defaultSessionId;
+      onStart(span, parentContext) {
+        const value = parentContext.getValue(SESSION_KEY);
+        const sessionId = typeof value === "string" ? value : this.defaultSessionId;
+        if (sessionId !== void 0) span.setAttribute(SESSION_ID, sessionId);
+      }
+      onEnd(_span) {
+      }
+      async forceFlush() {
+      }
+      async shutdown() {
+      }
+    };
+  }
+});
+
 // src/client.ts
+import { randomUUID as randomUUID2 } from "crypto";
 import { trace } from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
 import { resourceFromAttributes } from "@opentelemetry/resources";
@@ -988,13 +1031,18 @@ function init(options = {}) {
       mask: config.mask
     }) : health;
     const batch = new BatchSpanProcessor(exporter);
+    processors.add(new SessionSpanProcessor(config.sessionId));
     if (config.partialSpans) {
       processors.add(new PendingSpanProcessor(batch, { delayMs: config.partialSpansDelayMs }));
     }
     processors.add(batch);
   }
+  const instanceId = randomUUID2();
   const provider = new NodeTracerProvider({
-    resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: config.serviceName }),
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: config.serviceName,
+      [SERVICE_INSTANCE_ID]: instanceId
+    }),
     // Always ParentBased, with no AlwaysOn shortcut at rate 1. They are not
     // equivalent: ParentBased honours a remote UNSAMPLED parent and drops,
     // while AlwaysOn records regardless, producing children of a span the
@@ -1014,6 +1062,7 @@ function init(options = {}) {
       headers: authHeaders,
       intervalMs: config.heartbeatIntervalMs,
       agentName: config.agentName,
+      instanceId,
       tracker,
       transport: options.heartbeatTransport
     });
@@ -1043,6 +1092,7 @@ var init_client = __esm({
     init_masking();
     init_pending();
     init_semconv();
+    init_session();
     sinks = /* @__PURE__ */ new WeakMap();
     heartbeats = /* @__PURE__ */ new WeakMap();
     RiusClient = class _RiusClient {
@@ -1208,8 +1258,9 @@ function observe(fn, options = {}) {
 
 // src/index.ts
 init_semconv();
+init_session();
 init_spans();
-var VERSION = "0.2.4";
+var VERSION = "0.3.0";
 export {
   Generation,
   Observation,
@@ -1222,5 +1273,6 @@ export {
   startAsCurrentGeneration,
   startAsCurrentSpan,
   startGeneration,
-  startSpan
+  startSpan,
+  withSession
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassflow-ai/rius",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "OpenTelemetry-native tracing for AI agents and LLM applications",
   "keywords": [
     "opentelemetry",