@withgateway/sdk 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -353,13 +353,22 @@ declare function observeAnthropic<T extends object>(client: T): T;
353
353
  * The Claude Agent SDK runs the agent in a separate `claude` CLI subprocess, so
354
354
  * there's nothing in-process to patch. What the app has is the message stream it
355
355
  * iterates. Wrap that stream with observeClaude() and it yields the same
356
- * messages unchanged while emitting spans on the Gateway provider:
356
+ * messages unchanged while emitting spans on the Gateway provider.
357
+ *
358
+ * Default (one trace per run):
357
359
  *
358
360
  * AGENT (root)
359
361
  * ├─ GENERATION per assistant turn (with per-turn token usage)
360
362
  * └─ TOOL per tool call (input from tool_use, output from the
361
363
  * matching tool_result, matched by id)
362
364
  *
365
+ * With `perTurn: true` (one trace PER ASSISTANT TURN — long agent runs read as
366
+ * a session of turn traces, the way a chat thread does):
367
+ *
368
+ * AGENT "<name> · turn N" (detached root; session/user attributes on every turn)
369
+ * ├─ GENERATION (that turn's usage + text)
370
+ * └─ TOOL per tool call in the turn
371
+ *
363
372
  * The TS equivalent of the Python SDK's claude-agent-sdk instrumentor.
364
373
  *
365
374
  * @example
@@ -372,7 +381,7 @@ declare function observeAnthropic<T extends object>(client: T): T;
372
381
  */
373
382
 
374
383
  interface ObserveClaudeOptions {
375
- /** Root span name (becomes the trace name). */
384
+ /** Root span name (becomes the trace name; per-turn mode appends `· turn N`). */
376
385
  name: string;
377
386
  /** Recorded as input.value on the root span → trace-level input. */
378
387
  input?: string;
@@ -385,10 +394,21 @@ interface ObserveClaudeOptions {
385
394
  */
386
395
  tracer?: Tracer;
387
396
  /**
388
- * Extra attributes for the ROOT span — e.g. gateway.session.id /
397
+ * Extra attributes for the root span(s) — e.g. gateway.session.id /
389
398
  * gateway.user.id to group runs into a session and attribute them to a user.
399
+ * In per-turn mode these ride EVERY turn root, so each turn trace maps to
400
+ * the session.
390
401
  */
391
402
  attributes?: Record<string, string>;
403
+ /**
404
+ * Emit one TRACE PER ASSISTANT TURN instead of a single trace for the whole
405
+ * run. Each turn's trace carries that turn's generation and tool calls; the
406
+ * turn's input is the run input (turn 1) or the tool results that fed it
407
+ * (later turns). Turn roots are detached (`root: true`), so they never nest
408
+ * under ambient spans. Combine with `attributes.gateway.session.id` to read
409
+ * a whole run as a session of turns.
410
+ */
411
+ perTurn?: boolean;
392
412
  }
393
413
  declare function observeClaude(stream: AsyncIterable<any>, options: ObserveClaudeOptions): AsyncGenerator<any>;
394
414
 
@@ -353,13 +353,22 @@ declare function observeAnthropic<T extends object>(client: T): T;
353
353
  * The Claude Agent SDK runs the agent in a separate `claude` CLI subprocess, so
354
354
  * there's nothing in-process to patch. What the app has is the message stream it
355
355
  * iterates. Wrap that stream with observeClaude() and it yields the same
356
- * messages unchanged while emitting spans on the Gateway provider:
356
+ * messages unchanged while emitting spans on the Gateway provider.
357
+ *
358
+ * Default (one trace per run):
357
359
  *
358
360
  * AGENT (root)
359
361
  * ├─ GENERATION per assistant turn (with per-turn token usage)
360
362
  * └─ TOOL per tool call (input from tool_use, output from the
361
363
  * matching tool_result, matched by id)
362
364
  *
365
+ * With `perTurn: true` (one trace PER ASSISTANT TURN — long agent runs read as
366
+ * a session of turn traces, the way a chat thread does):
367
+ *
368
+ * AGENT "<name> · turn N" (detached root; session/user attributes on every turn)
369
+ * ├─ GENERATION (that turn's usage + text)
370
+ * └─ TOOL per tool call in the turn
371
+ *
363
372
  * The TS equivalent of the Python SDK's claude-agent-sdk instrumentor.
364
373
  *
365
374
  * @example
@@ -372,7 +381,7 @@ declare function observeAnthropic<T extends object>(client: T): T;
372
381
  */
373
382
 
374
383
  interface ObserveClaudeOptions {
375
- /** Root span name (becomes the trace name). */
384
+ /** Root span name (becomes the trace name; per-turn mode appends `· turn N`). */
376
385
  name: string;
377
386
  /** Recorded as input.value on the root span → trace-level input. */
378
387
  input?: string;
@@ -385,10 +394,21 @@ interface ObserveClaudeOptions {
385
394
  */
386
395
  tracer?: Tracer;
387
396
  /**
388
- * Extra attributes for the ROOT span — e.g. gateway.session.id /
397
+ * Extra attributes for the root span(s) — e.g. gateway.session.id /
389
398
  * gateway.user.id to group runs into a session and attribute them to a user.
399
+ * In per-turn mode these ride EVERY turn root, so each turn trace maps to
400
+ * the session.
390
401
  */
391
402
  attributes?: Record<string, string>;
403
+ /**
404
+ * Emit one TRACE PER ASSISTANT TURN instead of a single trace for the whole
405
+ * run. Each turn's trace carries that turn's generation and tool calls; the
406
+ * turn's input is the run input (turn 1) or the tool results that fed it
407
+ * (later turns). Turn roots are detached (`root: true`), so they never nest
408
+ * under ambient spans. Combine with `attributes.gateway.session.id` to read
409
+ * a whole run as a session of turns.
410
+ */
411
+ perTurn?: boolean;
392
412
  }
393
413
  declare function observeClaude(stream: AsyncIterable<any>, options: ObserveClaudeOptions): AsyncGenerator<any>;
394
414
 
package/dist/index.d.mts CHANGED
@@ -6,8 +6,8 @@ export { DriftError, LocalTool, MissPolicy, REPLAY_ENVIRONMENT, RecordedToolCall
6
6
  export { GatewayAgentDescriptor, GatewaySecurity, GatewaySecurityConfig, GatewaySecurityContext, GatewaySecurityError, GatewayToolApprovalRequiredError, GatewayToolBlockedError, GatewayToolCallAuthorizeResponse, GatewayToolDescriptor, GatewayToolsetResolveResponse, SecureToolsOptions, gateway } from './security/index.mjs';
7
7
  export { DEFAULT_TIMEOUT_SECONDS, ENV_GATEWAY_HOST, ENV_GATEWAY_PUBLIC_KEY, ENV_GATEWAY_SECRET_KEY, LoadSessionOptions, SessionLoadError, SessionObservation, SessionRecording, SessionTrace, basicAuthHeader, loadSession, sessionObservationFromApi, sessions } from './sessions/index.mjs';
8
8
  export { UserProfile, UserProfileError, UserProfileUpdate, UsersClient, UsersClientConfig, UsersClientFromEnvConfig, users } from './users/index.mjs';
9
- import { _ as _tracingModule } from './index-DnowA8MG.mjs';
10
- export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-DnowA8MG.mjs';
9
+ import { _ as _tracingModule } from './index-CubrUmOe.mjs';
10
+ export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-CubrUmOe.mjs';
11
11
  import 'async_hooks';
12
12
  import '@opentelemetry/api';
13
13
  import '@opentelemetry/sdk-trace-base';
package/dist/index.d.ts CHANGED
@@ -6,8 +6,8 @@ export { DriftError, LocalTool, MissPolicy, REPLAY_ENVIRONMENT, RecordedToolCall
6
6
  export { GatewayAgentDescriptor, GatewaySecurity, GatewaySecurityConfig, GatewaySecurityContext, GatewaySecurityError, GatewayToolApprovalRequiredError, GatewayToolBlockedError, GatewayToolCallAuthorizeResponse, GatewayToolDescriptor, GatewayToolsetResolveResponse, SecureToolsOptions, gateway } from './security/index.js';
7
7
  export { DEFAULT_TIMEOUT_SECONDS, ENV_GATEWAY_HOST, ENV_GATEWAY_PUBLIC_KEY, ENV_GATEWAY_SECRET_KEY, LoadSessionOptions, SessionLoadError, SessionObservation, SessionRecording, SessionTrace, basicAuthHeader, loadSession, sessionObservationFromApi, sessions } from './sessions/index.js';
8
8
  export { UserProfile, UserProfileError, UserProfileUpdate, UsersClient, UsersClientConfig, UsersClientFromEnvConfig, users } from './users/index.js';
9
- import { _ as _tracingModule } from './index-DnowA8MG.js';
10
- export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-DnowA8MG.js';
9
+ import { _ as _tracingModule } from './index-CubrUmOe.js';
10
+ export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-CubrUmOe.js';
11
11
  import 'async_hooks';
12
12
  import '@opentelemetry/api';
13
13
  import '@opentelemetry/sdk-trace-base';
package/dist/index.js CHANGED
@@ -2696,22 +2696,19 @@ __export(tracing_exports, {
2696
2696
 
2697
2697
  // src/tracing/init.ts
2698
2698
  var ENV_VARS = {
2699
- HOST: ["GATEWAY_HOST", "GATEWAY_HOST"],
2700
- PUBLIC_KEY: ["GATEWAY_PUBLIC_KEY", "GATEWAY_PUBLIC_KEY"],
2701
- SECRET_KEY: ["GATEWAY_SECRET_KEY", "GATEWAY_SECRET_KEY"],
2702
- ENDPOINT: ["GATEWAY_OTLP_ENDPOINT", "GATEWAY_OTLP_ENDPOINT"]
2699
+ HOST: "GATEWAY_HOST",
2700
+ PUBLIC_KEY: "GATEWAY_PUBLIC_KEY",
2701
+ SECRET_KEY: "GATEWAY_SECRET_KEY",
2702
+ ENDPOINT: "GATEWAY_OTLP_ENDPOINT"
2703
2703
  };
2704
2704
  var DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces";
2705
2705
  var state = {
2706
2706
  initialized: false,
2707
2707
  provider: null
2708
2708
  };
2709
- function getEnv(keys) {
2710
- for (const key of keys) {
2711
- const value = process.env[key];
2712
- if (value) return value;
2713
- }
2714
- return void 0;
2709
+ function getEnv(key) {
2710
+ const value = process.env[key];
2711
+ return value ? value : void 0;
2715
2712
  }
2716
2713
  function log(message, ...args) {
2717
2714
  if (state.debug) {
@@ -2999,33 +2996,74 @@ function toolResultText(content) {
2999
2996
  ).join("");
3000
2997
  return JSON.stringify(content ?? "");
3001
2998
  }
2999
+ var TURN_INPUT_MAX = 4e3;
3002
3000
  async function* observeClaude(stream, options) {
3003
3001
  const tracer = options.tracer ?? import_api3.trace.getTracer("@withgateway/sdk");
3004
- const root = tracer.startSpan(options.name, {
3005
- attributes: {
3006
- "openinference.span.kind": "AGENT",
3007
- ...options.input !== void 0 ? { "input.value": options.input } : {},
3008
- ...options.attributes ?? {}
3009
- }
3010
- });
3011
- const rootCtx = import_api3.trace.setSpan(import_api3.context.active(), root);
3012
- const openTools = /* @__PURE__ */ new Map();
3013
3002
  const model = options.model ?? "claude";
3003
+ const openTools = /* @__PURE__ */ new Map();
3004
+ let root = null;
3005
+ let rootCtx = null;
3006
+ if (!options.perTurn) {
3007
+ root = tracer.startSpan(options.name, {
3008
+ attributes: {
3009
+ "openinference.span.kind": "AGENT",
3010
+ ...options.input !== void 0 ? { "input.value": options.input } : {},
3011
+ ...options.attributes ?? {}
3012
+ }
3013
+ });
3014
+ rootCtx = import_api3.trace.setSpan(import_api3.context.active(), root);
3015
+ }
3016
+ let turnRoot = null;
3017
+ let turnCtx = null;
3018
+ let turnIndex = 0;
3019
+ let turnText = "";
3020
+ let pendingTurnInput = options.input ?? "";
3014
3021
  let finalText = "";
3022
+ const endTurn = () => {
3023
+ if (!turnRoot) return;
3024
+ if (turnText) turnRoot.setAttribute("output.value", turnText);
3025
+ turnRoot.setStatus({ code: import_api3.SpanStatusCode.OK });
3026
+ turnRoot.end();
3027
+ turnRoot = null;
3028
+ turnCtx = null;
3029
+ };
3015
3030
  try {
3016
3031
  for await (const message of stream) {
3017
3032
  if (message?.type === "assistant") {
3018
- let turnText = "";
3033
+ if (options.perTurn) {
3034
+ for (const span of openTools.values()) span.end();
3035
+ openTools.clear();
3036
+ endTurn();
3037
+ turnIndex += 1;
3038
+ turnText = "";
3039
+ turnRoot = tracer.startSpan(`${options.name} \xB7 turn ${turnIndex}`, {
3040
+ root: true,
3041
+ attributes: {
3042
+ "openinference.span.kind": "AGENT",
3043
+ ...pendingTurnInput ? { "input.value": pendingTurnInput.slice(0, TURN_INPUT_MAX) } : {},
3044
+ ...options.attributes ?? {}
3045
+ }
3046
+ });
3047
+ turnCtx = import_api3.trace.setSpan(import_api3.context.active(), turnRoot);
3048
+ pendingTurnInput = "";
3049
+ }
3050
+ const childCtx = options.perTurn ? turnCtx : rootCtx;
3051
+ let text = "";
3019
3052
  const toolUses = [];
3020
3053
  for (const block of message.message?.content ?? []) {
3021
3054
  if (block?.type === "text") {
3022
3055
  finalText += block.text;
3023
- turnText += block.text;
3056
+ text += block.text;
3024
3057
  }
3025
3058
  if (block?.type === "tool_use") {
3026
- toolUses.push({ id: block.id, name: block.name, input: block.input });
3059
+ toolUses.push({
3060
+ id: block.id,
3061
+ name: block.name,
3062
+ input: block.input
3063
+ });
3027
3064
  }
3028
3065
  }
3066
+ turnText += text;
3029
3067
  const gen = tracer.startSpan(
3030
3068
  "assistant",
3031
3069
  {
@@ -3033,10 +3071,10 @@ async function* observeClaude(stream, options) {
3033
3071
  "openinference.span.kind": "LLM",
3034
3072
  "llm.model_name": model,
3035
3073
  "llm.provider": "anthropic",
3036
- "output.value": turnText || toolUses.map((t) => `\u2192 ${cleanToolName(t.name)}`).join(", ")
3074
+ "output.value": text || toolUses.map((t) => `\u2192 ${cleanToolName(t.name)}`).join(", ")
3037
3075
  }
3038
3076
  },
3039
- rootCtx
3077
+ childCtx
3040
3078
  );
3041
3079
  const usage = message.message?.usage;
3042
3080
  if (usage?.input_tokens != null)
@@ -3054,7 +3092,7 @@ async function* observeClaude(stream, options) {
3054
3092
  "input.value": JSON.stringify(t.input)
3055
3093
  }
3056
3094
  },
3057
- rootCtx
3095
+ childCtx
3058
3096
  );
3059
3097
  openTools.set(t.id, span);
3060
3098
  }
@@ -3064,13 +3102,17 @@ async function* observeClaude(stream, options) {
3064
3102
  if (Array.isArray(content)) {
3065
3103
  for (const block of content) {
3066
3104
  if (block?.type === "tool_result") {
3105
+ const resultText = toolResultText(block.content);
3067
3106
  const span = openTools.get(block.tool_use_id);
3068
3107
  if (span) {
3069
- span.setAttribute("output.value", toolResultText(block.content));
3108
+ span.setAttribute("output.value", resultText);
3070
3109
  span.setStatus({ code: import_api3.SpanStatusCode.OK });
3071
3110
  span.end();
3072
3111
  openTools.delete(block.tool_use_id);
3073
3112
  }
3113
+ if (options.perTurn && pendingTurnInput.length < TURN_INPUT_MAX) {
3114
+ pendingTurnInput += (pendingTurnInput ? "\n" : "") + resultText.slice(0, TURN_INPUT_MAX - pendingTurnInput.length);
3115
+ }
3074
3116
  }
3075
3117
  }
3076
3118
  }
@@ -3080,9 +3122,13 @@ async function* observeClaude(stream, options) {
3080
3122
  } finally {
3081
3123
  for (const span of openTools.values()) span.end();
3082
3124
  openTools.clear();
3083
- root.setAttribute("output.value", finalText);
3084
- root.setStatus({ code: import_api3.SpanStatusCode.OK });
3085
- root.end();
3125
+ if (options.perTurn) {
3126
+ endTurn();
3127
+ } else if (root) {
3128
+ root.setAttribute("output.value", finalText);
3129
+ root.setStatus({ code: import_api3.SpanStatusCode.OK });
3130
+ root.end();
3131
+ }
3086
3132
  }
3087
3133
  }
3088
3134