@withgateway/sdk 0.1.6 → 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
@@ -2996,33 +2996,74 @@ function toolResultText(content) {
2996
2996
  ).join("");
2997
2997
  return JSON.stringify(content ?? "");
2998
2998
  }
2999
+ var TURN_INPUT_MAX = 4e3;
2999
3000
  async function* observeClaude(stream, options) {
3000
3001
  const tracer = options.tracer ?? import_api3.trace.getTracer("@withgateway/sdk");
3001
- const root = tracer.startSpan(options.name, {
3002
- attributes: {
3003
- "openinference.span.kind": "AGENT",
3004
- ...options.input !== void 0 ? { "input.value": options.input } : {},
3005
- ...options.attributes ?? {}
3006
- }
3007
- });
3008
- const rootCtx = import_api3.trace.setSpan(import_api3.context.active(), root);
3009
- const openTools = /* @__PURE__ */ new Map();
3010
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 ?? "";
3011
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
+ };
3012
3030
  try {
3013
3031
  for await (const message of stream) {
3014
3032
  if (message?.type === "assistant") {
3015
- 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 = "";
3016
3052
  const toolUses = [];
3017
3053
  for (const block of message.message?.content ?? []) {
3018
3054
  if (block?.type === "text") {
3019
3055
  finalText += block.text;
3020
- turnText += block.text;
3056
+ text += block.text;
3021
3057
  }
3022
3058
  if (block?.type === "tool_use") {
3023
- 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
+ });
3024
3064
  }
3025
3065
  }
3066
+ turnText += text;
3026
3067
  const gen = tracer.startSpan(
3027
3068
  "assistant",
3028
3069
  {
@@ -3030,10 +3071,10 @@ async function* observeClaude(stream, options) {
3030
3071
  "openinference.span.kind": "LLM",
3031
3072
  "llm.model_name": model,
3032
3073
  "llm.provider": "anthropic",
3033
- "output.value": turnText || toolUses.map((t) => `\u2192 ${cleanToolName(t.name)}`).join(", ")
3074
+ "output.value": text || toolUses.map((t) => `\u2192 ${cleanToolName(t.name)}`).join(", ")
3034
3075
  }
3035
3076
  },
3036
- rootCtx
3077
+ childCtx
3037
3078
  );
3038
3079
  const usage = message.message?.usage;
3039
3080
  if (usage?.input_tokens != null)
@@ -3051,7 +3092,7 @@ async function* observeClaude(stream, options) {
3051
3092
  "input.value": JSON.stringify(t.input)
3052
3093
  }
3053
3094
  },
3054
- rootCtx
3095
+ childCtx
3055
3096
  );
3056
3097
  openTools.set(t.id, span);
3057
3098
  }
@@ -3061,13 +3102,17 @@ async function* observeClaude(stream, options) {
3061
3102
  if (Array.isArray(content)) {
3062
3103
  for (const block of content) {
3063
3104
  if (block?.type === "tool_result") {
3105
+ const resultText = toolResultText(block.content);
3064
3106
  const span = openTools.get(block.tool_use_id);
3065
3107
  if (span) {
3066
- span.setAttribute("output.value", toolResultText(block.content));
3108
+ span.setAttribute("output.value", resultText);
3067
3109
  span.setStatus({ code: import_api3.SpanStatusCode.OK });
3068
3110
  span.end();
3069
3111
  openTools.delete(block.tool_use_id);
3070
3112
  }
3113
+ if (options.perTurn && pendingTurnInput.length < TURN_INPUT_MAX) {
3114
+ pendingTurnInput += (pendingTurnInput ? "\n" : "") + resultText.slice(0, TURN_INPUT_MAX - pendingTurnInput.length);
3115
+ }
3071
3116
  }
3072
3117
  }
3073
3118
  }
@@ -3077,9 +3122,13 @@ async function* observeClaude(stream, options) {
3077
3122
  } finally {
3078
3123
  for (const span of openTools.values()) span.end();
3079
3124
  openTools.clear();
3080
- root.setAttribute("output.value", finalText);
3081
- root.setStatus({ code: import_api3.SpanStatusCode.OK });
3082
- 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
+ }
3083
3132
  }
3084
3133
  }
3085
3134