@glassflow-ai/rius 0.3.1 → 0.4.0

package/dist/index.cjs

@@ -356,7 +356,7 @@ function kindAttributes(kind) {
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
   return attributes;
 }
-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 TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, WORKSPACE_ROUTE, 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_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_WRITE_INPUT_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";
@@ -367,12 +367,15 @@ var init_semconv = __esm({
     INPUT_VALUE = "input.value";
     OUTPUT_VALUE = "output.value";
     SESSION_ID = "session.id";
+    WORKSPACE_ROUTE = "rius.workspace";
     GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
     GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
     GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
     GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
     GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
     GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+    GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens";
+    GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS = "gen_ai.usage.cache_write.input_tokens";
     GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages";
     GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages";
     GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons";
@@ -400,6 +403,12 @@ var init_semconv = __esm({
       OUTPUT_VALUE,
       GEN_AI_INPUT_MESSAGES,
       GEN_AI_OUTPUT_MESSAGES,
+      // Sensitive per the GenAI conventions (semconv-genai#431): tool definitions
+      // routinely embed proprietary prompt engineering, and sometimes credentials
+      // or internal URLs in parameter defaults. gen_ai.tool.name stays: it is
+      // identity, not content.
+      "gen_ai.tool.description",
+      "gen_ai.tool.definitions",
       "gen_ai.prompt",
       "gen_ai.completion",
       "llm.input_messages",
@@ -435,7 +444,10 @@ var init_semconv = __esm({
       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
+      SESSION_ID,
+      // Routing, not content: a crashed run's snapshot must land in the same
+      // workspace its final span would have. Stripped at export either way.
+      WORKSPACE_ROUTE
     ]);
     PENDING_IDENTITY_PREFIXES = [GEN_AI_REQUEST_PREFIX];
   }
@@ -1010,6 +1022,128 @@ var init_session = __esm({
   }
 });
 
+// src/workspace.ts
+function withWorkspace(alias, fn) {
+  if (!alias) throw new Error("workspace alias must be a non-empty string");
+  return import_api6.context.with(import_api6.context.active().setValue(WORKSPACE_KEY, alias), () => fn(alias));
+}
+function setGlobalRouting(routing) {
+  globalRouting = routing;
+}
+function registerWorkspace(alias, apiKey) {
+  if (globalRouting === void 0) {
+    throw new Error(
+      "[rius] workspace routing is not enabled: pass workspaces (an empty object is fine) to init() to opt in before registering destinations"
+    );
+  }
+  globalRouting.register(alias, apiKey);
+}
+var import_api6, WORKSPACE_KEY, WorkspaceSpanProcessor, RoutingSpanExporter, globalRouting;
+var init_workspace = __esm({
+  "src/workspace.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_api6 = require("@opentelemetry/api");
+    init_esm();
+    init_semconv();
+    WORKSPACE_KEY = (0, import_api6.createContextKey)("rius-workspace-alias");
+    WorkspaceSpanProcessor = class {
+      onStart(span, parentContext) {
+        const alias = parentContext.getValue(WORKSPACE_KEY);
+        if (typeof alias !== "string") return;
+        const parent = import_api6.trace.getSpan(parentContext);
+        const parentAlias = parent?.attributes?.[WORKSPACE_ROUTE];
+        if (parentAlias !== void 0 && parentAlias !== alias) {
+          console.warn(
+            `[rius] span "${span.name}" starts under workspace "${alias}" but its parent is stamped "${String(parentAlias)}"; a trace cannot straddle two workspaces (the backend derives the workspace from the API key). Switch workspaces at request boundaries, before the root span starts.`
+          );
+        }
+        span.setAttribute(WORKSPACE_ROUTE, alias);
+      }
+      onEnd(_span) {
+      }
+      async forceFlush() {
+      }
+      async shutdown() {
+      }
+    };
+    RoutingSpanExporter = class {
+      constructor(defaultExporter, factory, routes = {}) {
+        this.defaultExporter = defaultExporter;
+        this.factory = factory;
+        this.routes = new Map(Object.entries(routes));
+      }
+      defaultExporter;
+      factory;
+      routes;
+      exporters = /* @__PURE__ */ new Map();
+      warnedAliases = /* @__PURE__ */ new Set();
+      /** Add or replace a route. Replacing supports key rotation. */
+      register(alias, apiKey) {
+        if (!alias || !apiKey) {
+          throw new Error("workspace alias and apiKey must be non-empty strings");
+        }
+        this.routes.set(alias, apiKey);
+        this.warnedAliases.delete(alias);
+      }
+      export(spans, resultCallback) {
+        const groups = /* @__PURE__ */ new Map();
+        for (const span of spans) {
+          const attributes = span.attributes;
+          const raw = attributes[WORKSPACE_ROUTE];
+          let destination = this.defaultExporter;
+          if (raw !== void 0) {
+            delete attributes[WORKSPACE_ROUTE];
+            destination = this.resolve(String(raw));
+          }
+          const group = groups.get(destination);
+          if (group === void 0) groups.set(destination, [span]);
+          else group.push(span);
+        }
+        let pending = groups.size;
+        if (pending === 0) {
+          resultCallback({ code: ExportResultCode.SUCCESS });
+          return;
+        }
+        let failed;
+        for (const [exporter, group] of groups) {
+          exporter.export(group, (result) => {
+            if (result.code !== ExportResultCode.SUCCESS) failed = result;
+            pending -= 1;
+            if (pending === 0) resultCallback(failed ?? { code: ExportResultCode.SUCCESS });
+          });
+        }
+      }
+      resolve(alias) {
+        const apiKey = this.routes.get(alias);
+        if (apiKey === void 0) {
+          if (!this.warnedAliases.has(alias)) {
+            this.warnedAliases.add(alias);
+            console.warn(
+              `[rius] no workspace registered for alias "${alias}"; its spans go to the default destination. Register it with registerWorkspace("${alias}", apiKey) or in init({ workspaces }).`
+            );
+          }
+          return this.defaultExporter;
+        }
+        let exporter = this.exporters.get(apiKey);
+        if (exporter === void 0) {
+          exporter = this.factory(apiKey);
+          this.exporters.set(apiKey, exporter);
+        }
+        return exporter;
+      }
+      async forceFlush() {
+        await this.defaultExporter.forceFlush?.();
+        await Promise.all([...this.exporters.values()].map((e) => e.forceFlush?.()));
+      }
+      async shutdown() {
+        await this.defaultExporter.shutdown();
+        await Promise.all([...this.exporters.values()].map((e) => e.shutdown()));
+      }
+    };
+  }
+});
+
 // src/client.ts
 function init(options = {}) {
   if (globalClient !== void 0) {
@@ -1022,11 +1156,20 @@ function init(options = {}) {
   const processors = new DelegatingSpanProcessor();
   const authHeaders = config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {};
   let health;
+  let routing;
   if (!config.disabled) {
-    const base = options.spanExporter ?? new import_exporter_trace_otlp_proto.OTLPTraceExporter({
+    let base = options.spanExporter ?? new import_exporter_trace_otlp_proto.OTLPTraceExporter({
       url: `${config.endpoint}/v1/traces`,
       headers: config.apiKey ? authHeaders : void 0
     });
+    if (options.workspaces !== void 0) {
+      const factory = options.workspaceExporterFactory ?? ((apiKey) => new import_exporter_trace_otlp_proto.OTLPTraceExporter({
+        url: `${config.endpoint}/v1/traces`,
+        headers: { Authorization: `Bearer ${apiKey}` }
+      }));
+      routing = new RoutingSpanExporter(base, factory, options.workspaces);
+      base = routing;
+    }
     health = new ExportOutcomeExporter(base);
     const exporter = !config.captureContent || config.mask !== void 0 ? new MaskingSpanExporter(health, {
       captureContent: config.captureContent,
@@ -1034,6 +1177,9 @@ function init(options = {}) {
     }) : health;
     const batch = new import_sdk_trace_base.BatchSpanProcessor(exporter);
     processors.add(new SessionSpanProcessor(config.sessionId));
+    if (routing !== void 0) {
+      processors.add(new WorkspaceSpanProcessor());
+    }
     if (config.partialSpans) {
       processors.add(new PendingSpanProcessor(batch, { delayMs: config.partialSpansDelayMs }));
     }
@@ -1076,18 +1222,19 @@ function init(options = {}) {
     heartbeat = { sender, beforeExitHandler };
   }
   globalClient = createClient({ provider, processors, health, ready, heartbeat });
+  setGlobalRouting(routing);
   return globalClient;
 }
 function getTracer() {
-  return import_api6.trace.getTracer(TRACER_NAME);
+  return import_api7.trace.getTracer(TRACER_NAME);
 }
-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 import_node_crypto2, import_api7, 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_node_crypto2 = require("crypto");
-    import_api6 = require("@opentelemetry/api");
+    import_api7 = 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");
@@ -1102,6 +1249,7 @@ var init_client = __esm({
     init_pending();
     init_semconv();
     init_session();
+    init_workspace();
     sinks = /* @__PURE__ */ new WeakMap();
     heartbeats = /* @__PURE__ */ new WeakMap();
     RiusClient = class _RiusClient {
@@ -1145,7 +1293,8 @@ var init_client = __esm({
         } finally {
           if (globalClient === this) {
             globalClient = void 0;
-            import_api6.trace.disable();
+            setGlobalRouting(void 0);
+            import_api7.trace.disable();
           }
         }
       }
@@ -1164,11 +1313,13 @@ __export(index_exports, {
   getTracer: () => getTracer,
   init: () => init,
   observe: () => observe,
+  registerWorkspace: () => registerWorkspace,
   startAsCurrentGeneration: () => startAsCurrentGeneration,
   startAsCurrentSpan: () => startAsCurrentSpan,
   startGeneration: () => startGeneration,
   startSpan: () => startSpan,
-  withSession: () => withSession
+  withSession: () => withSession,
+  withWorkspace: () => withWorkspace
 });
 module.exports = __toCommonJS(index_exports);
 init_cjs_shims();
@@ -1194,6 +1345,13 @@ var Generation = class extends Observation {
     this.span.setAttribute(GEN_AI_RESPONSE_MODEL, model);
     return 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.
+   */
   setUsage(usage) {
     if (usage.inputTokens !== void 0) {
       this.span.setAttribute(GEN_AI_USAGE_INPUT_TOKENS, usage.inputTokens);
@@ -1201,6 +1359,12 @@ var Generation = class extends Observation {
     if (usage.outputTokens !== void 0) {
       this.span.setAttribute(GEN_AI_USAGE_OUTPUT_TOKENS, usage.outputTokens);
     }
+    if (usage.cacheReadInputTokens !== void 0) {
+      this.span.setAttribute(GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, usage.cacheReadInputTokens);
+    }
+    if (usage.cacheWriteInputTokens !== void 0) {
+      this.span.setAttribute(GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS, usage.cacheWriteInputTokens);
+    }
     return this;
   }
   /**
@@ -1286,7 +1450,8 @@ function observe(fn, options = {}) {
 init_semconv();
 init_session();
 init_spans();
-var VERSION = "0.3.1";
+init_workspace();
+var VERSION = "0.4.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Generation,
@@ -1297,9 +1462,11 @@ var VERSION = "0.3.1";
   getTracer,
   init,
   observe,
+  registerWorkspace,
   startAsCurrentGeneration,
   startAsCurrentSpan,
   startGeneration,
   startSpan,
-  withSession
+  withSession,
+  withWorkspace
 });

package/dist/index.d.cts

@@ -35,12 +35,80 @@ interface RiusOptions {
 
 type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
 
+/**
+ * Workspaces: route spans from one process to per-customer destinations.
+ *
+ * One client, one provider, one batch pipeline; the *destination* is a
+ * context-scoped property. `withWorkspace(alias, fn)` sets an OTel context
+ * key (exactly like `withSession`), `WorkspaceSpanProcessor` stamps it as a
+ * transient attribute at span start, and `RoutingSpanExporter` partitions
+ * each export batch by that attribute, strips it, and forwards every
+ * partition to the exporter registered for its alias. Spans started outside
+ * any scope go to the default destination.
+ *
+ * Because the alias rides OTel context, everything started in scope routes
+ * together: `observe` wrappers, generations, sessions, and spans created by
+ * auto-instrumentation. That is the property a second client could never
+ * give, which is why this SDK has no scoped-client mode at all.
+ *
+ * Two rules the design enforces or warns about:
+ *
+ * - The routing attribute never reaches the wire. The destination's API key
+ *   is what tells the backend which workspace a span belongs to; the alias
+ *   is process-local configuration, so the exporter strips it before
+ *   delegating.
+ * - One trace, one workspace. The backend derives the workspace from the API
+ *   key per request, so a trace split across scopes would come apart.
+ *   Starting a span under a different alias than its parent's logs a
+ *   warning; switch workspaces at request boundaries, not inside a trace.
+ */
+
+type WorkspaceExporterFactory = (apiKey: string) => SpanExporter;
+/**
+ * Scope every span started inside `fn` to one workspace destination.
+ *
+ * `alias` names a workspace registered via `init({ workspaces })` or
+ * `registerWorkspace()`; the scope's spans are exported with that
+ * workspace's API key. Scopes nest and follow async continuations the way
+ * all OTel context does, but a trace must stay inside one workspace: enter
+ * the scope at a request boundary, before the root span starts.
+ *
+ * ```typescript
+ * await withWorkspace("acme", async () => {
+ *   await handle(request) // every span of the request lands in acme's workspace
+ * })
+ * ```
+ */
+declare function withWorkspace<T>(alias: string, fn: (alias: string) => T): T;
+/**
+ * Add (or rotate the key of) a workspace destination on the global client.
+ *
+ * Requires `init({ workspaces })` to have opted into routing (an empty
+ * object opts in with no static routes). Spans started inside
+ * `withWorkspace(alias, ...)` are then exported with `apiKey`.
+ */
+declare function registerWorkspace(alias: string, apiKey: string): void;
+
 /** Options accepted by {@link init}, extending the shared configuration. */
 interface InitOptions extends RiusOptions {
     /** Inject an exporter instead of OTLP. The test seam; prefer this to mocking. */
     spanExporter?: SpanExporter;
     /** Override the heartbeat HTTP transport. The test seam; prefer this to mocking fetch. */
     heartbeatTransport?: HeartbeatTransport;
+    /**
+     * Enable multi-workspace routing: a map of alias to API key. Spans started
+     * inside `withWorkspace(alias, fn)` are exported with that workspace's
+     * key; spans outside any scope use the default `apiKey`. Pass `{}` to opt
+     * in with no static routes and register destinations later via
+     * `registerWorkspace()`. One trace must stay inside one workspace.
+     */
+    workspaces?: Record<string, string>;
+    /**
+     * Override how per-workspace exporters are built from an API key. The
+     * test seam, like `spanExporter`; defaults to the standard OTLP exporter
+     * against the configured endpoint.
+     */
+    workspaceExporterFactory?: WorkspaceExporterFactory;
 }
 /**
  * Handle over a configured tracer pipeline, returned by {@link init}.
@@ -162,9 +230,23 @@ declare class Generation extends Observation {
     setInput(value: unknown): this;
     setOutput(value: 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.
+     */
     setUsage(usage: {
         inputTokens?: number;
         outputTokens?: number;
+        /** Input tokens served from a provider-managed prompt cache. */
+        cacheReadInputTokens?: number;
+        /**
+         * Input tokens written to a provider-managed prompt cache
+         * (called "cache creation" by Anthropic).
+         */
+        cacheWriteInputTokens?: number;
     }): this;
     /**
      * Why generation stopped (`gen_ai.response.finish_reasons`), e.g. `"stop"`,
@@ -233,6 +315,6 @@ 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.3.1";
+declare const VERSION = "0.4.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, withSession };
+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 };

package/dist/index.d.ts

@@ -35,12 +35,80 @@ interface RiusOptions {
 
 type HeartbeatTransport = (payload: Record<string, unknown>, timeoutMs: number) => Promise<void>;
 
+/**
+ * Workspaces: route spans from one process to per-customer destinations.
+ *
+ * One client, one provider, one batch pipeline; the *destination* is a
+ * context-scoped property. `withWorkspace(alias, fn)` sets an OTel context
+ * key (exactly like `withSession`), `WorkspaceSpanProcessor` stamps it as a
+ * transient attribute at span start, and `RoutingSpanExporter` partitions
+ * each export batch by that attribute, strips it, and forwards every
+ * partition to the exporter registered for its alias. Spans started outside
+ * any scope go to the default destination.
+ *
+ * Because the alias rides OTel context, everything started in scope routes
+ * together: `observe` wrappers, generations, sessions, and spans created by
+ * auto-instrumentation. That is the property a second client could never
+ * give, which is why this SDK has no scoped-client mode at all.
+ *
+ * Two rules the design enforces or warns about:
+ *
+ * - The routing attribute never reaches the wire. The destination's API key
+ *   is what tells the backend which workspace a span belongs to; the alias
+ *   is process-local configuration, so the exporter strips it before
+ *   delegating.
+ * - One trace, one workspace. The backend derives the workspace from the API
+ *   key per request, so a trace split across scopes would come apart.
+ *   Starting a span under a different alias than its parent's logs a
+ *   warning; switch workspaces at request boundaries, not inside a trace.
+ */
+
+type WorkspaceExporterFactory = (apiKey: string) => SpanExporter;
+/**
+ * Scope every span started inside `fn` to one workspace destination.
+ *
+ * `alias` names a workspace registered via `init({ workspaces })` or
+ * `registerWorkspace()`; the scope's spans are exported with that
+ * workspace's API key. Scopes nest and follow async continuations the way
+ * all OTel context does, but a trace must stay inside one workspace: enter
+ * the scope at a request boundary, before the root span starts.
+ *
+ * ```typescript
+ * await withWorkspace("acme", async () => {
+ *   await handle(request) // every span of the request lands in acme's workspace
+ * })
+ * ```
+ */
+declare function withWorkspace<T>(alias: string, fn: (alias: string) => T): T;
+/**
+ * Add (or rotate the key of) a workspace destination on the global client.
+ *
+ * Requires `init({ workspaces })` to have opted into routing (an empty
+ * object opts in with no static routes). Spans started inside
+ * `withWorkspace(alias, ...)` are then exported with `apiKey`.
+ */
+declare function registerWorkspace(alias: string, apiKey: string): void;
+
 /** Options accepted by {@link init}, extending the shared configuration. */
 interface InitOptions extends RiusOptions {
     /** Inject an exporter instead of OTLP. The test seam; prefer this to mocking. */
     spanExporter?: SpanExporter;
     /** Override the heartbeat HTTP transport. The test seam; prefer this to mocking fetch. */
     heartbeatTransport?: HeartbeatTransport;
+    /**
+     * Enable multi-workspace routing: a map of alias to API key. Spans started
+     * inside `withWorkspace(alias, fn)` are exported with that workspace's
+     * key; spans outside any scope use the default `apiKey`. Pass `{}` to opt
+     * in with no static routes and register destinations later via
+     * `registerWorkspace()`. One trace must stay inside one workspace.
+     */
+    workspaces?: Record<string, string>;
+    /**
+     * Override how per-workspace exporters are built from an API key. The
+     * test seam, like `spanExporter`; defaults to the standard OTLP exporter
+     * against the configured endpoint.
+     */
+    workspaceExporterFactory?: WorkspaceExporterFactory;
 }
 /**
  * Handle over a configured tracer pipeline, returned by {@link init}.
@@ -162,9 +230,23 @@ declare class Generation extends Observation {
     setInput(value: unknown): this;
     setOutput(value: 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.
+     */
     setUsage(usage: {
         inputTokens?: number;
         outputTokens?: number;
+        /** Input tokens served from a provider-managed prompt cache. */
+        cacheReadInputTokens?: number;
+        /**
+         * Input tokens written to a provider-managed prompt cache
+         * (called "cache creation" by Anthropic).
+         */
+        cacheWriteInputTokens?: number;
     }): this;
     /**
      * Why generation stopped (`gen_ai.response.finish_reasons`), e.g. `"stop"`,
@@ -233,6 +315,6 @@ 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.3.1";
+declare const VERSION = "0.4.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, withSession };
+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 };

package/dist/index.js

@@ -343,7 +343,7 @@ function kindAttributes(kind) {
   if (operation !== void 0) attributes[GEN_AI_OPERATION_NAME] = operation;
   return attributes;
 }
-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 TRACER_NAME, SERVICE_INSTANCE_ID, OPENINFERENCE_SPAN_KIND, INPUT_VALUE, OUTPUT_VALUE, SESSION_ID, WORKSPACE_ROUTE, 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_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_WRITE_INPUT_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";
@@ -354,12 +354,15 @@ var init_semconv = __esm({
     INPUT_VALUE = "input.value";
     OUTPUT_VALUE = "output.value";
     SESSION_ID = "session.id";
+    WORKSPACE_ROUTE = "rius.workspace";
     GEN_AI_OPERATION_NAME = "gen_ai.operation.name";
     GEN_AI_PROVIDER_NAME = "gen_ai.provider.name";
     GEN_AI_REQUEST_MODEL = "gen_ai.request.model";
     GEN_AI_RESPONSE_MODEL = "gen_ai.response.model";
     GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens";
     GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens";
+    GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read.input_tokens";
+    GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS = "gen_ai.usage.cache_write.input_tokens";
     GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages";
     GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages";
     GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons";
@@ -387,6 +390,12 @@ var init_semconv = __esm({
       OUTPUT_VALUE,
       GEN_AI_INPUT_MESSAGES,
       GEN_AI_OUTPUT_MESSAGES,
+      // Sensitive per the GenAI conventions (semconv-genai#431): tool definitions
+      // routinely embed proprietary prompt engineering, and sometimes credentials
+      // or internal URLs in parameter defaults. gen_ai.tool.name stays: it is
+      // identity, not content.
+      "gen_ai.tool.description",
+      "gen_ai.tool.definitions",
       "gen_ai.prompt",
       "gen_ai.completion",
       "llm.input_messages",
@@ -422,7 +431,10 @@ var init_semconv = __esm({
       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
+      SESSION_ID,
+      // Routing, not content: a crashed run's snapshot must land in the same
+      // workspace its final span would have. Stripped at export either way.
+      WORKSPACE_ROUTE
     ]);
     PENDING_IDENTITY_PREFIXES = [GEN_AI_REQUEST_PREFIX];
   }
@@ -997,9 +1009,131 @@ var init_session = __esm({
   }
 });
 
+// src/workspace.ts
+import { context as apiContext2, createContextKey as createContextKey2, trace } from "@opentelemetry/api";
+function withWorkspace(alias, fn) {
+  if (!alias) throw new Error("workspace alias must be a non-empty string");
+  return apiContext2.with(apiContext2.active().setValue(WORKSPACE_KEY, alias), () => fn(alias));
+}
+function setGlobalRouting(routing) {
+  globalRouting = routing;
+}
+function registerWorkspace(alias, apiKey) {
+  if (globalRouting === void 0) {
+    throw new Error(
+      "[rius] workspace routing is not enabled: pass workspaces (an empty object is fine) to init() to opt in before registering destinations"
+    );
+  }
+  globalRouting.register(alias, apiKey);
+}
+var WORKSPACE_KEY, WorkspaceSpanProcessor, RoutingSpanExporter, globalRouting;
+var init_workspace = __esm({
+  "src/workspace.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_esm();
+    init_semconv();
+    WORKSPACE_KEY = createContextKey2("rius-workspace-alias");
+    WorkspaceSpanProcessor = class {
+      onStart(span, parentContext) {
+        const alias = parentContext.getValue(WORKSPACE_KEY);
+        if (typeof alias !== "string") return;
+        const parent = trace.getSpan(parentContext);
+        const parentAlias = parent?.attributes?.[WORKSPACE_ROUTE];
+        if (parentAlias !== void 0 && parentAlias !== alias) {
+          console.warn(
+            `[rius] span "${span.name}" starts under workspace "${alias}" but its parent is stamped "${String(parentAlias)}"; a trace cannot straddle two workspaces (the backend derives the workspace from the API key). Switch workspaces at request boundaries, before the root span starts.`
+          );
+        }
+        span.setAttribute(WORKSPACE_ROUTE, alias);
+      }
+      onEnd(_span) {
+      }
+      async forceFlush() {
+      }
+      async shutdown() {
+      }
+    };
+    RoutingSpanExporter = class {
+      constructor(defaultExporter, factory, routes = {}) {
+        this.defaultExporter = defaultExporter;
+        this.factory = factory;
+        this.routes = new Map(Object.entries(routes));
+      }
+      defaultExporter;
+      factory;
+      routes;
+      exporters = /* @__PURE__ */ new Map();
+      warnedAliases = /* @__PURE__ */ new Set();
+      /** Add or replace a route. Replacing supports key rotation. */
+      register(alias, apiKey) {
+        if (!alias || !apiKey) {
+          throw new Error("workspace alias and apiKey must be non-empty strings");
+        }
+        this.routes.set(alias, apiKey);
+        this.warnedAliases.delete(alias);
+      }
+      export(spans, resultCallback) {
+        const groups = /* @__PURE__ */ new Map();
+        for (const span of spans) {
+          const attributes = span.attributes;
+          const raw = attributes[WORKSPACE_ROUTE];
+          let destination = this.defaultExporter;
+          if (raw !== void 0) {
+            delete attributes[WORKSPACE_ROUTE];
+            destination = this.resolve(String(raw));
+          }
+          const group = groups.get(destination);
+          if (group === void 0) groups.set(destination, [span]);
+          else group.push(span);
+        }
+        let pending = groups.size;
+        if (pending === 0) {
+          resultCallback({ code: ExportResultCode.SUCCESS });
+          return;
+        }
+        let failed;
+        for (const [exporter, group] of groups) {
+          exporter.export(group, (result) => {
+            if (result.code !== ExportResultCode.SUCCESS) failed = result;
+            pending -= 1;
+            if (pending === 0) resultCallback(failed ?? { code: ExportResultCode.SUCCESS });
+          });
+        }
+      }
+      resolve(alias) {
+        const apiKey = this.routes.get(alias);
+        if (apiKey === void 0) {
+          if (!this.warnedAliases.has(alias)) {
+            this.warnedAliases.add(alias);
+            console.warn(
+              `[rius] no workspace registered for alias "${alias}"; its spans go to the default destination. Register it with registerWorkspace("${alias}", apiKey) or in init({ workspaces }).`
+            );
+          }
+          return this.defaultExporter;
+        }
+        let exporter = this.exporters.get(apiKey);
+        if (exporter === void 0) {
+          exporter = this.factory(apiKey);
+          this.exporters.set(apiKey, exporter);
+        }
+        return exporter;
+      }
+      async forceFlush() {
+        await this.defaultExporter.forceFlush?.();
+        await Promise.all([...this.exporters.values()].map((e) => e.forceFlush?.()));
+      }
+      async shutdown() {
+        await this.defaultExporter.shutdown();
+        await Promise.all([...this.exporters.values()].map((e) => e.shutdown()));
+      }
+    };
+  }
+});
+
 // src/client.ts
 import { randomUUID as randomUUID2 } from "crypto";
-import { trace } from "@opentelemetry/api";
+import { trace as trace2 } from "@opentelemetry/api";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import {
@@ -1020,11 +1154,20 @@ function init(options = {}) {
   const processors = new DelegatingSpanProcessor();
   const authHeaders = config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {};
   let health;
+  let routing;
   if (!config.disabled) {
-    const base = options.spanExporter ?? new OTLPTraceExporter({
+    let base = options.spanExporter ?? new OTLPTraceExporter({
       url: `${config.endpoint}/v1/traces`,
       headers: config.apiKey ? authHeaders : void 0
     });
+    if (options.workspaces !== void 0) {
+      const factory = options.workspaceExporterFactory ?? ((apiKey) => new OTLPTraceExporter({
+        url: `${config.endpoint}/v1/traces`,
+        headers: { Authorization: `Bearer ${apiKey}` }
+      }));
+      routing = new RoutingSpanExporter(base, factory, options.workspaces);
+      base = routing;
+    }
     health = new ExportOutcomeExporter(base);
     const exporter = !config.captureContent || config.mask !== void 0 ? new MaskingSpanExporter(health, {
       captureContent: config.captureContent,
@@ -1032,6 +1175,9 @@ function init(options = {}) {
     }) : health;
     const batch = new BatchSpanProcessor(exporter);
     processors.add(new SessionSpanProcessor(config.sessionId));
+    if (routing !== void 0) {
+      processors.add(new WorkspaceSpanProcessor());
+    }
     if (config.partialSpans) {
       processors.add(new PendingSpanProcessor(batch, { delayMs: config.partialSpansDelayMs }));
     }
@@ -1074,10 +1220,11 @@ function init(options = {}) {
     heartbeat = { sender, beforeExitHandler };
   }
   globalClient = createClient({ provider, processors, health, ready, heartbeat });
+  setGlobalRouting(routing);
   return globalClient;
 }
 function getTracer() {
-  return trace.getTracer(TRACER_NAME);
+  return trace2.getTracer(TRACER_NAME);
 }
 var sinks, heartbeats, createClient, RiusClient, globalClient;
 var init_client = __esm({
@@ -1093,6 +1240,7 @@ var init_client = __esm({
     init_pending();
     init_semconv();
     init_session();
+    init_workspace();
     sinks = /* @__PURE__ */ new WeakMap();
     heartbeats = /* @__PURE__ */ new WeakMap();
     RiusClient = class _RiusClient {
@@ -1136,7 +1284,8 @@ var init_client = __esm({
         } finally {
           if (globalClient === this) {
             globalClient = void 0;
-            trace.disable();
+            setGlobalRouting(void 0);
+            trace2.disable();
           }
         }
       }
@@ -1168,6 +1317,13 @@ var Generation = class extends Observation {
     this.span.setAttribute(GEN_AI_RESPONSE_MODEL, model);
     return 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.
+   */
   setUsage(usage) {
     if (usage.inputTokens !== void 0) {
       this.span.setAttribute(GEN_AI_USAGE_INPUT_TOKENS, usage.inputTokens);
@@ -1175,6 +1331,12 @@ var Generation = class extends Observation {
     if (usage.outputTokens !== void 0) {
       this.span.setAttribute(GEN_AI_USAGE_OUTPUT_TOKENS, usage.outputTokens);
     }
+    if (usage.cacheReadInputTokens !== void 0) {
+      this.span.setAttribute(GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, usage.cacheReadInputTokens);
+    }
+    if (usage.cacheWriteInputTokens !== void 0) {
+      this.span.setAttribute(GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS, usage.cacheWriteInputTokens);
+    }
     return this;
   }
   /**
@@ -1260,7 +1422,8 @@ function observe(fn, options = {}) {
 init_semconv();
 init_session();
 init_spans();
-var VERSION = "0.3.1";
+init_workspace();
+var VERSION = "0.4.0";
 export {
   Generation,
   Observation,
@@ -1270,9 +1433,11 @@ export {
   getTracer,
   init,
   observe,
+  registerWorkspace,
   startAsCurrentGeneration,
   startAsCurrentSpan,
   startGeneration,
   startSpan,
-  withSession
+  withSession,
+  withWorkspace
 };

package/package.json

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