@strands-agents/sdk 1.9.0 → 1.10.0

package/dist/src/storage/s3-storage.js

@@ -0,0 +1,146 @@
+import { StorageError } from '../errors.js';
+import { namespace, normalizeKey, normalizePrefix } from './storage.js';
+const S3_PAGE_SIZE = 1000;
+/**
+ * Amazon S3 {@link Storage} backend.
+ *
+ * Stores each key as an S3 object under an optional prefix. The AWS SDK is loaded
+ * lazily on first use and declared as an optional peer dependency, so consumers that
+ * never construct an `S3Storage` are not required to install `@aws-sdk/client-s3`.
+ *
+ * @example
+ * ```typescript
+ * import { S3Storage } from '@strands-agents/sdk/storage'
+ *
+ * const storage = new S3Storage('my-bucket', { prefix: 'agents/' })
+ * await storage.write('sessions/abc/snapshot.json', bytes)
+ * ```
+ */
+export class S3Storage {
+    _bucket;
+    _prefix;
+    _region;
+    _client;
+    /**
+     * @param bucket - Target S3 bucket name
+     * @param config - Optional prefix, region, or pre-configured client
+     * @throws {@link StorageError} if both `region` and `s3Client` are provided
+     */
+    constructor(bucket, config) {
+        if (config?.s3Client && config.region) {
+            throw new StorageError('Cannot specify both s3Client and region. Configure the region on the S3Client instead.');
+        }
+        this._bucket = bucket;
+        this._prefix = config?.prefix ? config.prefix.split('/').filter(Boolean).join('/') + '/' : '';
+        this._region = config?.region;
+        this._client = config?.s3Client;
+    }
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the key is invalid or the upload fails
+     */
+    async write(key, data) {
+        const normalized = normalizeKey(key);
+        const client = await this._getClient();
+        const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+        try {
+            await client.send(new PutObjectCommand({ Bucket: this._bucket, Key: this._objectKey(normalized), Body: data }));
+        }
+        catch (error) {
+            throw new StorageError(`Failed to write '${normalized}' to S3 bucket '${this._bucket}'`, { cause: error });
+        }
+    }
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the key is invalid or the download fails
+     */
+    async read(key) {
+        const normalized = normalizeKey(key);
+        const client = await this._getClient();
+        const { GetObjectCommand } = await import('@aws-sdk/client-s3');
+        try {
+            const response = await client.send(new GetObjectCommand({ Bucket: this._bucket, Key: this._objectKey(normalized) }));
+            const body = await response.Body?.transformToByteArray();
+            return body ? new Uint8Array(body) : null;
+        }
+        catch (error) {
+            if (error instanceof Error && (error.name === 'NoSuchKey' || error.name === 'NotFound')) {
+                return null;
+            }
+            throw new StorageError(`Failed to read '${normalized}' from S3 bucket '${this._bucket}'`, { cause: error });
+        }
+    }
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the key is invalid or the delete request fails
+     */
+    async delete(key) {
+        const normalized = normalizeKey(key);
+        const client = await this._getClient();
+        const { DeleteObjectCommand } = await import('@aws-sdk/client-s3');
+        try {
+            await client.send(new DeleteObjectCommand({ Bucket: this._bucket, Key: this._objectKey(normalized) }));
+        }
+        catch (error) {
+            throw new StorageError(`Failed to delete '${normalized}' from S3 bucket '${this._bucket}'`, { cause: error });
+        }
+    }
+    /**
+     * Lists the keys whose names begin with `prefix`, sorted lexicographically.
+     *
+     * @param prefix - Key prefix to match. An empty string matches all keys.
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the prefix is invalid or the list request fails
+     */
+    async list(prefix) {
+        const normalized = normalizePrefix(prefix);
+        const client = await this._getClient();
+        const { ListObjectsV2Command } = await import('@aws-sdk/client-s3');
+        const listPrefix = `${this._prefix}${normalized}`;
+        const keys = [];
+        let continuationToken;
+        try {
+            do {
+                const response = await client.send(new ListObjectsV2Command({
+                    Bucket: this._bucket,
+                    Prefix: listPrefix,
+                    MaxKeys: S3_PAGE_SIZE,
+                    ContinuationToken: continuationToken,
+                }));
+                for (const object of response.Contents ?? []) {
+                    if (object.Key === undefined)
+                        continue;
+                    keys.push(this._prefix ? object.Key.slice(this._prefix.length) : object.Key);
+                }
+                continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+            } while (continuationToken);
+        }
+        catch (error) {
+            throw new StorageError(`Failed to list S3 bucket '${this._bucket}' under '${normalized}'`, { cause: error });
+        }
+        return keys.sort();
+    }
+    async _getClient() {
+        if (this._client)
+            return this._client;
+        const { S3Client } = await import('@aws-sdk/client-s3');
+        this._client = new S3Client(this._region ? { region: this._region } : {});
+        return this._client;
+    }
+    /** Returns a prefixed view of this storage without mutating the original. */
+    namespace(prefix) {
+        return namespace(this, prefix);
+    }
+    _objectKey(key) {
+        return `${this._prefix}${key}`;
+    }
+}
+//# sourceMappingURL=s3-storage.js.map

package/dist/src/storage/s3-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-storage.js","sourceRoot":"","sources":["../../../src/storage/s3-storage.ts"],"names":[],"mappings":"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"}

package/dist/src/storage/storage.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Symbol present on namespaced storage views. Constructs use this to detect
+ * whether the caller already scoped the storage, skipping the default prefix.
+ *
+ * @internal
+ */
+export declare const NAMESPACED: unique symbol;
+/**
+ * Validates and normalizes a storage key: collapses runs of `/`, strips leading
+ * and trailing `/`, and rejects empty keys and any `..` segment.
+ *
+ * @param key - The raw key to normalize
+ * @returns The normalized key
+ * @throws {@link StorageError} if the key is empty or contains a `..` segment
+ */
+export declare function normalizeKey(key: string): string;
+/**
+ * Normalizes a list prefix: collapses slash runs, strips leading slashes.
+ * Unlike a key, an empty prefix is valid and matches everything.
+ *
+ * @param prefix - The raw prefix to normalize
+ * @returns The normalized prefix
+ * @throws {@link StorageError} if the prefix contains a `..` segment
+ */
+export declare function normalizePrefix(prefix: string): string;
+/**
+ * A backend for storing and retrieving raw bytes under string keys.
+ *
+ * The interface is deliberately minimal — four operations over opaque `Uint8Array`
+ * values. Implementations must treat keys as opaque path-like strings (segments
+ * separated by `/`) and must round-trip the bytes they are given unchanged.
+ *
+ * The `ListQuery` type parameter controls what `list` accepts. It defaults to
+ * `string` (a key prefix), which every backend supports. Implementations may
+ * widen it to accept a richer query object (e.g. a DynamoDB partition/sort-key
+ * filter) while still accepting a plain string for SDK-internal callers.
+ *
+ * Implement this to add a custom backend; the SDK ships {@link InMemoryStorage},
+ * {@link LocalFileStorage}, and {@link S3Storage}.
+ */
+export interface Storage<ListQuery = string> {
+    /**
+     * Stores `data` under `key`, overwriting any existing value.
+     *
+     * @param key - Opaque, `/`-separated key identifying the value
+     * @param data - Raw bytes to persist
+     * @throws {@link StorageError} if the write fails
+     */
+    write(key: string, data: Uint8Array): Promise<void>;
+    /**
+     * Retrieves the bytes previously stored under `key`.
+     *
+     * @param key - The key to read
+     * @returns The stored bytes, or `null` if no value exists for `key`
+     * @throws {@link StorageError} if the read fails for a reason other than a missing key
+     */
+    read(key: string): Promise<Uint8Array | null>;
+    /**
+     * Deletes the value stored under `key`. A no-op if the key does not exist.
+     *
+     * @param key - The key to delete
+     * @throws {@link StorageError} if the delete fails
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists keys matching the given query.
+     *
+     * When `ListQuery` is `string` (the default), this is a prefix match — returns
+     * full keys (not the suffix after the prefix), sorted lexicographically. An empty
+     * string lists every key.
+     *
+     * Implementations may accept richer query objects (e.g. partition + sort-key filters)
+     * while still supporting a plain string prefix for SDK-internal callers.
+     *
+     * @param query - A string prefix or backend-specific query object
+     * @returns The matching keys, sorted ascending
+     * @throws {@link StorageError} if the listing fails
+     */
+    list(query: ListQuery): Promise<string[]>;
+    /**
+     * Returns a view of this storage with all keys prefixed by `prefix`.
+     * The original storage is not mutated.
+     *
+     * Optional — shipped backends implement this, custom backends may omit it.
+     *
+     * @param prefix - Prefix to prepend to all keys
+     * @returns A Storage view scoped to the given prefix
+     */
+    namespace?(prefix: string): Storage;
+}
+/**
+ * Returns a {@link Storage} view with all keys prefixed by `prefix`.
+ *
+ * Composable — calling `namespace()` on the result nests prefixes.
+ *
+ * @internal
+ * @param storage - The underlying storage to delegate to
+ * @param prefix - Prefix to prepend to all keys
+ * @returns A namespaced Storage view
+ */
+export declare function namespace(storage: Storage, prefix: string): Storage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/src/storage/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/storage/storage.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,MAAiD,CAAA;AAEjF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAShD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,OAAO,CAAC,SAAS,GAAG,MAAM;IACzC;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnD;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAE7C;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEzC;;;;;;;;OAQG;IACH,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAYnE"}

package/dist/src/storage/storage.js

@@ -0,0 +1,68 @@
+import { StorageError } from '../errors.js';
+/**
+ * Symbol present on namespaced storage views. Constructs use this to detect
+ * whether the caller already scoped the storage, skipping the default prefix.
+ *
+ * @internal
+ */
+export const NAMESPACED = Symbol.for('strands.storage.namespaced');
+/**
+ * Validates and normalizes a storage key: collapses runs of `/`, strips leading
+ * and trailing `/`, and rejects empty keys and any `..` segment.
+ *
+ * @param key - The raw key to normalize
+ * @returns The normalized key
+ * @throws {@link StorageError} if the key is empty or contains a `..` segment
+ */
+export function normalizeKey(key) {
+    const segments = key.split('/').filter(Boolean);
+    if (segments.length === 0) {
+        throw new StorageError('Storage key must not be empty');
+    }
+    if (segments.includes('..')) {
+        throw new StorageError(`Invalid storage key '${key}': '..' path segments are not allowed`);
+    }
+    return segments.join('/');
+}
+/**
+ * Normalizes a list prefix: collapses slash runs, strips leading slashes.
+ * Unlike a key, an empty prefix is valid and matches everything.
+ *
+ * @param prefix - The raw prefix to normalize
+ * @returns The normalized prefix
+ * @throws {@link StorageError} if the prefix contains a `..` segment
+ */
+export function normalizePrefix(prefix) {
+    const parts = prefix.split('/');
+    const segments = parts.filter(Boolean);
+    if (segments.includes('..')) {
+        throw new StorageError(`Invalid storage prefix '${prefix}': '..' path segments are not allowed`);
+    }
+    const joined = segments.join('/');
+    const normalized = parts[parts.length - 1] === '' && joined ? joined + '/' : joined;
+    return normalized;
+}
+/**
+ * Returns a {@link Storage} view with all keys prefixed by `prefix`.
+ *
+ * Composable — calling `namespace()` on the result nests prefixes.
+ *
+ * @internal
+ * @param storage - The underlying storage to delegate to
+ * @param prefix - Prefix to prepend to all keys
+ * @returns A namespaced Storage view
+ */
+export function namespace(storage, prefix) {
+    const normalized = normalizePrefix(prefix);
+    const p = normalized ? `${normalized}/` : '';
+    const view = {
+        write: (key, data) => storage.write(`${p}${key}`, data),
+        read: (key) => storage.read(`${p}${key}`),
+        delete: (key) => storage.delete(`${p}${key}`),
+        list: (query) => storage.list(`${p}${query}`).then((keys) => keys.map((key) => key.slice(p.length))),
+        namespace: (sub) => namespace(storage, `${p}${sub}`),
+        [NAMESPACED]: true,
+    };
+    return view;
+}
+//# sourceMappingURL=storage.js.map

package/dist/src/storage/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/storage/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAkB,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAA;AAEjF;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,YAAY,CAAC,+BAA+B,CAAC,CAAA;IACzD,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CAAC,wBAAwB,GAAG,uCAAuC,CAAC,CAAA;IAC5F,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC3B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACtC,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CAAC,2BAA2B,MAAM,uCAAuC,CAAC,CAAA;IAClG,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAA;IACnF,OAAO,UAAU,CAAA;AACnB,CAAC;AAwED;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,OAAgB,EAAE,MAAc;IACxD,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IAC1C,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAC5C,MAAM,IAAI,GAAqC;QAC7C,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,EAAE,IAAI,CAAC;QACvD,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC;QACzC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC;QAC7C,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QACpG,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC;QACpD,CAAC,UAAU,CAAC,EAAE,IAAI;KACnB,CAAA;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/src/telemetry/tracer.d.ts

@@ -135,6 +135,20 @@ export declare class Tracer {
      * or LANGFUSE_BASE_URL environment variables.
      */
     private readonly _isLangfuse;
+    /**
+     * Whether to record message content as span attributes instead of span events.
+     *
+     * True when the backend cannot read span events (Langfuse) or the opt-in is set via
+     * `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_span_attributes_only`. Per OpenTelemetry the span-event
+     * recording API is deprecated, and non-timestamped span details such as the canonical
+     * `gen_ai.*.messages` attributes should be recorded as span attributes instead. This flag is
+     * passed by the aggregated content paths (latest-convention `gen_ai.*` messages and the
+     * `memory.query`/`memory.content` events); it never reaches the legacy per-message events
+     * (which reuse a `content` key and would collide as attributes).
+     *
+     * @see https://opentelemetry.io/blog/2026/deprecating-span-events/
+     */
+    private readonly _spanAttributesOnly;
     /** In-memory execution trace state, collected independently of OTEL. */
     private readonly _traceState;
     /**
@@ -337,6 +351,10 @@ export declare class Tracer {
     private _endSpan;
     /**
      * Add an event to a span.
+     *
+     * Per OpenTelemetry the span-event recording API is deprecated. When `toSpanAttributes` is set,
+     * the attributes are recorded directly on the span and the event is skipped, so the content is
+     * recorded once rather than duplicated across both; otherwise the event is emitted.
      */
     private _addEvent;
     /**

package/dist/src/telemetry/tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/telemetry/tracer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../../src/telemetry/tracer.ts"],"names":[],"mappings":"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"}

package/dist/src/telemetry/tracer.js

@@ -141,6 +141,20 @@ export class Tracer {
      * or LANGFUSE_BASE_URL environment variables.
      */
     _isLangfuse;
+    /**
+     * Whether to record message content as span attributes instead of span events.
+     *
+     * True when the backend cannot read span events (Langfuse) or the opt-in is set via
+     * `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_span_attributes_only`. Per OpenTelemetry the span-event
+     * recording API is deprecated, and non-timestamped span details such as the canonical
+     * `gen_ai.*.messages` attributes should be recorded as span attributes instead. This flag is
+     * passed by the aggregated content paths (latest-convention `gen_ai.*` messages and the
+     * `memory.query`/`memory.content` events); it never reaches the legacy per-message events
+     * (which reuse a `content` key and would collide as attributes).
+     *
+     * @see https://opentelemetry.io/blog/2026/deprecating-span-events/
+     */
+    _spanAttributesOnly;
     /** In-memory execution trace state, collected independently of OTEL. */
     _traceState = { traces: [] };
     /**
@@ -158,6 +172,7 @@ export class Tracer {
         this._useLatestConventions = optInValues.has('gen_ai_latest_experimental');
         this._includeToolDefinitions = optInValues.has('gen_ai_tool_definitions');
         this._isLangfuse = Tracer._detectLangfuse();
+        this._spanAttributesOnly = this._isLangfuse || optInValues.has('gen_ai_span_attributes_only');
         // Get tracer from global API to ensure ground truth
         this._tracer = trace.getTracer(getServiceName());
     }
@@ -340,7 +355,7 @@ export class Tracer {
                             parts: [{ type: 'tool_call', name: tool.name, id: tool.toolUseId, arguments: tool.input }],
                         },
                     ], jsonReplacer),
-                });
+                }, this._spanAttributesOnly);
             }
             else {
                 this._addEvent(span, 'gen_ai.tool.message', {
@@ -384,7 +399,7 @@ export class Tracer {
                                 parts: [{ type: 'tool_call_response', id: toolResult.toolUseId, response: toolResult.content }],
                             },
                         ], jsonReplacer),
-                    });
+                    }, this._spanAttributesOnly);
                 }
                 else {
                     this._addEvent(span, 'gen_ai.choice', {
@@ -520,7 +535,7 @@ export class Tracer {
             if (options.maxSearchResults !== undefined)
                 attributes['memory.max_search_results'] = options.maxSearchResults;
             const span = this._startSpan({ name: 'memory.search', attributes, spanKind: SpanKind.INTERNAL });
-            this._addEvent(span, 'memory.query', { content: options.query }, this._isLangfuse);
+            this._addEvent(span, 'memory.query', { content: options.query }, this._spanAttributesOnly);
             return span;
         }
         catch (error) {
@@ -553,7 +568,7 @@ export class Tracer {
                         storeName: entry.storeName,
                         metadata: entry.metadata,
                     })), jsonReplacer),
-                }, this._isLangfuse);
+                }, this._spanAttributesOnly);
             }
             this._endSpan(span, attributes, options.error);
         }
@@ -581,7 +596,7 @@ export class Tracer {
                 spanKind: SpanKind.INTERNAL,
                 ...(options.forceRoot && { forceRoot: true }),
             });
-            this._addEvent(span, 'memory.content', { content: options.content }, this._isLangfuse);
+            this._addEvent(span, 'memory.content', { content: options.content }, this._spanAttributesOnly);
             return span;
         }
         catch (error) {
@@ -851,6 +866,10 @@ export class Tracer {
     }
     /**
      * Add an event to a span.
+     *
+     * Per OpenTelemetry the span-event recording API is deprecated. When `toSpanAttributes` is set,
+     * the attributes are recorded directly on the span and the event is skipped, so the content is
+     * recorded once rather than duplicated across both; otherwise the event is emitted.
      */
     _addEvent(span, eventName, eventAttributes, toSpanAttributes = false) {
         try {
@@ -863,10 +882,11 @@ export class Tracer {
                 if (value !== undefined && value !== null)
                     otelAttributes[key] = value;
             }
-            // Some backends (e.g. Langfuse) don't surface span events, so optionally promote the
-            // attributes onto the span where they remain visible.
+            // Some backends (e.g. Langfuse) don't surface span events, so record the attributes on the
+            // span instead of as an event.
             if (toSpanAttributes) {
                 span.setAttributes(otelAttributes);
+                return;
             }
             span.addEvent(eventName, otelAttributes);
         }
@@ -909,7 +929,7 @@ export class Tracer {
                 }));
                 this._addEvent(span, 'gen_ai.client.inference.operation.details', {
                     'gen_ai.input.messages': JSON.stringify(inputMessages, jsonReplacer),
-                });
+                }, this._spanAttributesOnly);
             }
             else {
                 for (const message of messages) {
@@ -982,7 +1002,7 @@ export class Tracer {
             if (this._useLatestConventions) {
                 this._addEvent(span, 'gen_ai.client.inference.operation.details', {
                     'gen_ai.output.messages': JSON.stringify([{ role: 'assistant', parts: [{ type: 'text', content: messageText }], finish_reason: finishReason }], jsonReplacer),
-                });
+                }, this._spanAttributesOnly);
             }
             else {
                 this._addEvent(span, 'gen_ai.choice', { message: messageText, finish_reason: finishReason });
@@ -1007,7 +1027,7 @@ export class Tracer {
                             finish_reason: finishReason,
                         },
                     ], jsonReplacer),
-                });
+                }, this._spanAttributesOnly);
             }
             else {
                 this._addEvent(span, 'gen_ai.choice', {
@@ -1061,7 +1081,7 @@ export class Tracer {
             const parts = Tracer._mapSystemPromptToOtelParts(systemPrompt);
             this._addEvent(span, 'gen_ai.client.inference.operation.details', {
                 'gen_ai.system_instructions': JSON.stringify(parts, jsonReplacer),
-            });
+            }, this._spanAttributesOnly);
         }
         else {
             // Normalize string prompts to an array of text blocks for consistent format