The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
fix(sdk): close unconsumed query streams and end their spans (#917)
Rudy Mizrahi Celeklic9b70331dee3
diff --git a/docs/changelog/sdk.mdx b/docs/changelog/sdk.mdxindex e7acc64d..44d6a961 100644--- a/docs/changelog/sdk.mdx+++ b/docs/changelog/sdk.mdx@@ -14,6 +14,7 @@ Stay up to date with the latest changes to the Beacon Observe SDK.- **Observed streams read through their own API keep their span** · An observed function returning a stream that has its own reading API, such as the Anthropic SDK's `client.messages.stream()` read with `finalMessage()` or events, a `ReadableStream` read with `getReader()`, or a Node stream sent through `pipe()`, never exported its span: the SDK replaced the stream with a wrapper that only `for await` went through, which also made `instanceof` checks on it fail. Such streams are now returned unchanged and their span ends when the function returns. Async generators and the Claude Agent SDK's `query()` are still traced until they are read to the end.- **Observe endpoints keep their query string** · An endpoint with query parameters, such as a gateway URL carrying a tenant or routing parameter, had `/v1/observe` appended after its query, so spans went to the wrong route without any error. The path is now added to the URL's path, and the query and fragment are kept. `Observe.initialize()` now throws for an endpoint that is not an absolute URL, instead of exporting to an unusable address.- **Spans from an observed stream nest under it** · Work an observed async generator does as it is read, such as tool or model calls, was recorded under whoever consumed the stream, so those spans appeared beside the stream's span instead of inside it. They are now its children, including work in the stream's cleanup.+- **Cancelling a query before reading it closes the query** · Calling `return()` or `throw()` on a query from `wrapClaudeAgentQuery` before its first message left the Claude Code process the query had already started running, and its span never ended. The query is now closed as the unwrapped one would be, and its span is exported.- **API key scoped to Beacon Cloud** · `ASYMPTOTE_API_KEY` is now sent only to Beacon Cloud: in hosted mode, or to an explicit OTLP endpoint on the same origin as the base URL. Previously a service with both `ASYMPTOTE_API_KEY` and a generic `OTEL_EXPORTER_OTLP_ENDPOINT` sent the key to that collector on every export. Caller-supplied `headers` are unchanged.- **HTTPS required for the API key** · `Observe.initialize()` now throws when the key would be sent to a non-loopback `http://` base URL. `http://localhost`, `http://127.0.0.1` and `http://[::1]` remain allowed for local stubs.diff --git a/packages/asymptote-sdk-js/src/index.ts b/packages/asymptote-sdk-js/src/index.tsindex 46642a49..bc55030a 100644--- a/packages/asymptote-sdk-js/src/index.ts+++ b/packages/asymptote-sdk-js/src/index.ts@@ -568,10 +568,45 @@ function finishResult<T>(result: T, span: Span, options?: ObserveOptions): unkno// cached so repeated reads return the same function. The proxy targets the wrapper rather// than the original, whose read-only properties would make a binding get trap invalid.const iterator = finishAsyncIterable(result, span);+ // return() or throw() on an unstarted async generator settles it without running its finally+ // block, so the span would never end and an already-created query (which owns the Claude CLI+ // process) would never be closed. Do both here.+ let started = false;+ async function closeUnstarted(settled: Promise<IteratorResult<unknown>>) {+ const close = (result as Partial<AsyncIterator<unknown>>).return;+ let outcome: IteratorResult<unknown>;+ try {+ outcome = await settled;+ } catch (error) {+ // The consumer's error takes precedence over a cleanup failure.+ await Promise.resolve(typeof close === "function" ? close.call(result) : undefined).catch(() => {});+ endSpanWithError(span, error);+ throw error;+ }+ try {+ if (typeof close === "function") await close.call(result);+ } catch (error) {+ endSpanWithError(span, error);+ throw error;+ }+ span.end();+ return outcome;+ }const methods = {- next: iterator.next.bind(iterator),- return: iterator.return.bind(iterator),- throw: iterator.throw.bind(iterator),+ next(value?: unknown) {+ started = true;+ return iterator.next(value);+ },+ return(value?: unknown) {+ if (started) return iterator.return(value);+ started = true;+ return closeUnstarted(iterator.return(value));+ },+ throw(error?: unknown) {+ if (started) return iterator.throw(error);+ started = true;+ return closeUnstarted(iterator.throw(error));+ },};const spanContext = trace.setSpan(context.active(), span);const tracedMethods = {diff --git a/packages/asymptote-sdk-js/src/stream-cancellation.test.ts b/packages/asymptote-sdk-js/src/stream-cancellation.test.tsnew file mode 100644index 00000000..0697f443--- /dev/null+++ b/packages/asymptote-sdk-js/src/stream-cancellation.test.ts@@ -0,0 +1,110 @@+import { SpanStatusCode } from "@opentelemetry/api";+import { InMemorySpanExporter } from "@opentelemetry/sdk-trace-base";+import { afterEach, expect, it } from "vitest";++import { flush, initialize, shutdown, wrapClaudeAgentQuery } from "./index.js";++afterEach(async () => { await shutdown(); });++function queryResource(close: () => Promise<IteratorResult<unknown> | void> = async () => {}) {+ let nextCalls = 0;+ let returnCalls = 0;+ const original = {+ [Symbol.asyncIterator]() { return this; },+ async next(): Promise<IteratorResult<string>> {+ nextCalls++;+ return { value: "message", done: false };+ },+ async return(value?: unknown): Promise<IteratorResult<unknown>> {+ returnCalls++;+ return await close() ?? { value, done: true };+ },+ async throw(error: unknown): Promise<IteratorResult<unknown>> { throw error; },+ };+ const exporter = new InMemorySpanExporter();+ initialize({ spanExporter: exporter, disableDefaultExporter: true, disableBatch: true });+ const stream = wrapClaudeAgentQuery(() => original)();+ return { stream, exporter, counts: () => ({ nextCalls, returnCalls }) };+}++it("closes an unstarted query resource and exports its span exactly once", async () => {+ const { stream, exporter, counts } = queryResource();+ expect(exporter.getFinishedSpans()).toHaveLength(0);+ expect(await stream.return(Promise.resolve("cancelled"))).toEqual({ value: "cancelled", done: true });+ expect(await stream.return("again")).toEqual({ value: "again", done: true });+ expect(await stream.next()).toEqual({ value: undefined, done: true });+ await flush();+ expect(counts()).toEqual({ nextCalls: 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+ expect(exporter.getFinishedSpans()[0]?.status.code).toBe(SpanStatusCode.UNSET);+});++it("awaits unstarted resource cleanup before return and queued next complete", async () => {+ let release!: () => void;+ const cleanup = new Promise<void>(resolve => { release = resolve; });+ const { stream, exporter, counts } = queryResource(() => cleanup);+ let returned = false;+ const returning = stream.return().then(value => { returned = true; return value; });+ const returningAgain = stream.return("again");+ const next = stream.next();+ await Promise.resolve();+ expect(returned).toBe(false);+ expect(exporter.getFinishedSpans()).toHaveLength(0);+ release();+ expect(await returning).toEqual({ value: undefined, done: true });+ expect(await returningAgain).toEqual({ value: "again", done: true });+ expect(await next).toEqual({ value: undefined, done: true });+ expect(counts()).toEqual({ nextCalls: 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+});++it("cleans up and records a consumer throw before the first next", async () => {+ const { stream, exporter, counts } = queryResource();+ const failure = new Error("consumer cancelled before reading");+ await expect(stream.throw(failure)).rejects.toBe(failure);+ expect(await stream.return()).toEqual({ value: undefined, done: true });+ expect(counts()).toEqual({ nextCalls: 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+ expect(exporter.getFinishedSpans()[0]?.status.code).toBe(SpanStatusCode.ERROR);+});++it("propagates cleanup failure and still ends the unstarted span once", async () => {+ const failure = new Error("query close failed");+ const { stream, exporter, counts } = queryResource(async () => { throw failure; });+ await expect(stream.return()).rejects.toBe(failure);+ await stream.return();+ expect(counts()).toEqual({ nextCalls: 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+ expect(exporter.getFinishedSpans()[0]?.status.code).toBe(SpanStatusCode.ERROR);+});++it.each([false, true])("preserves the consumer throw when cleanup rejects (started=%s)", async started => {+ const closeFailure = new Error("query close failed");+ const consumerFailure = new Error("consumer failed");+ const { stream, exporter, counts } = queryResource(async () => { throw closeFailure; });+ if (started) await stream.next();+ await expect(stream.throw(consumerFailure)).rejects.toBe(consumerFailure);+ expect(counts()).toEqual({ nextCalls: started ? 1 : 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+ expect(exporter.getFinishedSpans()[0]?.status).toEqual({ code: SpanStatusCode.ERROR, message: consumerFailure.message });+});++it.each([false, true])("preserves a rejected return value when cleanup rejects (started=%s)", async started => {+ const closeFailure = new Error("query close failed");+ const valueFailure = new Error("return value failed");+ const { stream, exporter, counts } = queryResource(async () => { throw closeFailure; });+ if (started) await stream.next();+ await expect(stream.return(Promise.reject(valueFailure))).rejects.toBe(valueFailure);+ expect(counts()).toEqual({ nextCalls: started ? 1 : 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+ expect(exporter.getFinishedSpans()[0]?.status).toEqual({ code: SpanStatusCode.ERROR, message: valueFailure.message });+});++it.each([false, true])("uses existing close semantics when source return yields (started=%s)", async started => {+ const { stream, exporter, counts } = queryResource(async () => ({ value: "cleanup yield", done: false }));+ if (started) await stream.next();+ expect(await stream.return("cancelled")).toEqual({ value: "cancelled", done: true });+ expect(await stream.next()).toEqual({ value: undefined, done: true });+ expect(counts()).toEqual({ nextCalls: started ? 1 : 0, returnCalls: 1 });+ expect(exporter.getFinishedSpans()).toHaveLength(1);+});