@anthropic-ai/foundry-sdk 0.3.1 → 0.4.1

package/src/internal/headers.ts

@@ -29,7 +29,9 @@ export type NullableHeaders = {
   nulls: Set<string>;
 };
 
-function* iterateHeaders(headers: HeadersLike): IterableIterator<readonly [string, string | null]> {
+function* iterateHeaders(
+  headers: HeadersLike,
+): IterableIterator<readonly [string, string | null | ClearSentinel]> {
   if (!headers) return;
 
   if (brand_privateNullableHeaders in headers) {
@@ -60,16 +62,43 @@ function* iterateHeaders(headers: HeadersLike): IterableIterator<readonly [strin
       if (value === undefined) continue;
 
       // Objects keys always overwrite older headers, they never append.
-      // Yield a null to clear the header before adding the new values.
+      // Yield the clear sentinel before adding the new values, so the
+      // consumer can tell this synthetic "clear-before-set" apart from a
+      // user's explicit `null` (= remove).
       if (shouldClear && !didClear) {
         didClear = true;
-        yield [name, null];
+        yield [name, clearSentinel];
       }
       yield [name, value];
     }
   }
 }
 
+/** Distinguishes iterateHeaders' synthetic clear-before-set from a user `null`. */
+const clearSentinel = Symbol('clear');
+type ClearSentinel = typeof clearSentinel;
+
+/**
+ * Headers whose values accumulate across {@link buildHeaders} sources instead
+ * of the later source's value replacing the earlier one. Values are
+ * comma-appended (deduplicated, order-preserving) into a single header line.
+ */
+export const APPEND_HEADERS: ReadonlySet<string> = new Set(['x-stainless-helper']);
+
+export const appendHeaderValue = (existing: string | null, addition: string): string => {
+  const tokens =
+    existing ?
+      existing
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean)
+    : [];
+  for (const tok of addition.split(',').map((t) => t.trim())) {
+    if (tok && !tokens.includes(tok)) tokens.push(tok);
+  }
+  return tokens.join(', ');
+};
+
 export const buildHeaders = (newHeaders: HeadersLike[]): NullableHeaders => {
   const targetHeaders = new Headers();
   const nullHeaders = new Set<string>();
@@ -77,9 +106,23 @@ export const buildHeaders = (newHeaders: HeadersLike[]): NullableHeaders => {
     const seenHeaders = new Set<string>();
     for (const [name, value] of iterateHeaders(headers)) {
       const lowerName = name.toLowerCase();
-      if (!seenHeaders.has(lowerName)) {
+      if (APPEND_HEADERS.has(lowerName)) {
+        // Accumulating headers ignore the synthetic clear-before-set; an
+        // explicit `null` (any source shape) is honored as removal.
+        if (value === clearSentinel) continue;
+        if (value === null) {
+          targetHeaders.delete(name);
+          nullHeaders.add(lowerName);
+        } else {
+          targetHeaders.set(name, appendHeaderValue(targetHeaders.get(name), value));
+          nullHeaders.delete(lowerName);
+        }
+        continue;
+      }
+      if (value === clearSentinel || !seenHeaders.has(lowerName)) {
         targetHeaders.delete(name);
         seenHeaders.add(lowerName);
+        if (value === clearSentinel) continue;
       }
       if (value === null) {
         targetHeaders.delete(name);

package/src/internal/message-stream-utils.ts

@@ -0,0 +1,30 @@
+import { partialParse } from '../_vendor/partial-json-parser/parser';
+
+export const JSON_BUF_PROPERTY = '__json_buf';
+
+/**
+ * Copies a tool-use block with an updated `__json_buf`, installing `.input` as
+ * a memoized getter so the partial-JSON parse happens on first read instead of
+ * on every delta.
+ */
+export function withLazyInput<T extends { input: unknown }>(prev: T, jsonBuf: string): T {
+  const next = {} as T;
+  for (const key of Object.keys(prev) as (keyof T)[]) {
+    if (key !== 'input') next[key] = prev[key];
+  }
+  Object.defineProperty(next, JSON_BUF_PROPERTY, { value: jsonBuf, enumerable: false, writable: true });
+  let input: unknown;
+  let parsed = false;
+  Object.defineProperty(next, 'input', {
+    enumerable: true,
+    configurable: true,
+    get() {
+      if (!parsed) {
+        input = jsonBuf ? partialParse(jsonBuf) : {};
+        parsed = true;
+      }
+      return input;
+    },
+  });
+  return next;
+}

package/src/internal/parse.ts

@@ -4,6 +4,7 @@ import type { FinalRequestOptions } from './request-options';
 import { Stream } from '../core/streaming';
 import { type BaseAnthropic } from '../client';
 import { formatRequestDetails, loggerFor } from './utils/log';
+import { releaseRequestSignal } from './request-signal';
 import type { AbstractPage } from '../core/pagination';
 
 export type APIResponseProps = {
@@ -55,7 +56,15 @@ export async function defaultParseResponse<T>(
 
     const text = await response.text();
     return text as unknown as T;
-  })();
+  })().finally(() => {
+    // The body is settled (or parsing threw), so the caller-signal abort
+    // listener has nothing left to cancel. Streams release in their own
+    // teardown; a raw Response (`__binaryResponse`) keeps the listener so
+    // aborting an in-flight download still works.
+    if (!props.options.stream && !props.options.__binaryResponse) {
+      releaseRequestSignal(props.controller);
+    }
+  });
   loggerFor(client).debug(
     `[${requestLogID}] response parsed`,
     formatRequestDetails({

package/src/internal/request-signal.ts

@@ -0,0 +1,68 @@
+/**
+ * Tracks the removal of the per-request abort listener that
+ * `fetchWithTimeout` attaches to a caller-provided signal, so the listener's
+ * lifetime matches the request instead of the signal.
+ *
+ * Without removal, a long-lived signal (e.g. one AbortController reused for
+ * a whole session) accumulates one `{ once: true }` listener plus its bound
+ * AbortController per HTTP attempt until the signal fires or is collected,
+ * and Node warns at the 11th listener. The listener must survive until the
+ * response body is settled - removing it when fetch resolves (headers) would
+ * break aborting an in-flight body read - so the code that finishes the body
+ * (response parsing, stream teardown, retry/error handling) calls
+ * `releaseRequestSignal` with the request's controller.
+ */
+const cleanups = new WeakMap<AbortController, () => void>();
+
+// Backstop for requests that never reach an explicit release point: a caller
+// that partially iterates a stream (or receives a raw binary Response) and
+// drops the reference never completes, errors, or cancels it, so the only
+// remaining lifecycle event is the response being collected. Finalization
+// timing is GC-driven and not guaranteed, so this only bounds abandonment -
+// the explicit release calls stay the primary cleanup. The held value must
+// not reference the response, or it could never be collected. Typed
+// structurally because the compiler lib is es2020.
+type AbandonmentRegistry = {
+  register(target: object, heldValue: AbortController, token: object): void;
+  unregister(token: object): void;
+};
+
+const registry: AbandonmentRegistry | null =
+  typeof (globalThis as any).FinalizationRegistry === 'function' ?
+    new (globalThis as any).FinalizationRegistry((controller: AbortController) =>
+      releaseRequestSignal(controller),
+    )
+  : null;
+
+// Module-scope factory so the cleanup closure captures exactly the signal and
+// the listener - built at the `fetchWithTimeout` call site it would share that
+// scope's context and retain the request body for as long as the cleanup is
+// held (same reason `_makeAbort` exists in client.ts).
+function makeCleanup(signal: AbortSignal, listener: () => void): () => void {
+  return () => signal.removeEventListener('abort', listener);
+}
+
+export function registerRequestSignalCleanup(
+  controller: AbortController,
+  signal: AbortSignal,
+  listener: () => void,
+): void {
+  cleanups.set(controller, makeCleanup(signal, listener));
+}
+
+// The registered target is the response BODY, not the Response: a caller can
+// keep a reader on the body and drop the Response wrapper (`.asResponse()`),
+// and the listener must survive for as long as anything can still read - the
+// body is what a live read keeps alive.
+export function armAbandonmentBackstop(body: object, controller: AbortController): void {
+  if (cleanups.has(controller)) registry?.register(body, controller, controller);
+}
+
+export function releaseRequestSignal(controller: AbortController): void {
+  const cleanup = cleanups.get(controller);
+  if (cleanup) {
+    cleanups.delete(controller);
+    registry?.unregister(controller);
+    cleanup();
+  }
+}

package/src/internal/stainless-helper-header.ts

@@ -0,0 +1,122 @@
+/**
+ * Single source of truth for the `x-stainless-helper` telemetry header — the
+ * key, the closed value vocabulary, and per-object helper tagging. The
+ * append-don't-clobber merge for the header itself lives in
+ * {@link import('../internal/headers').buildHeaders} via `APPEND_HEADERS`.
+ */
+
+/**
+ * Telemetry header naming the SDK helper(s) a request came from. Always this
+ * lowercase form; `buildHeaders` matches it case-insensitively for its append
+ * semantics, but a single canonical casing keeps every call site greppable.
+ */
+export const STAINLESS_HELPER_HEADER = 'x-stainless-helper';
+
+/** Telemetry header naming the SDK method (e.g. `stream`) in use. */
+export const STAINLESS_HELPER_METHOD_HEADER = 'x-stainless-helper-method';
+
+/**
+ * The closed set of helper telemetry tags, shared verbatim across SDKs. A
+ * typo at any call site is a type error rather than silently mistagged
+ * telemetry. Existing values keep their original spellings — telemetry
+ * consumers match on them, so renames lose history. New tags are hyphenated
+ * lowercase.
+ */
+export type StainlessHelperHeaderValue =
+  | 'BetaToolRunner'
+  | 'betaZodTool'
+  | 'compaction'
+  | 'environments-work-poller'
+  | 'environments-worker'
+  | 'fallback-refusal-middleware'
+  | 'mcpContent'
+  | 'mcpMessage'
+  | 'mcpResourceToContent'
+  | 'mcpResourceToFile'
+  | 'mcpTool'
+  | 'session-tool-runner';
+
+/**
+ * The `{ 'x-stainless-helper': value }` header dict, for passing into
+ * `buildHeaders` (which comma-appends `x-stainless-helper` across sources)
+ * or as `defaultHeaders`/per-request `headers`.
+ */
+export function helperHeader(value: StainlessHelperHeaderValue): { [STAINLESS_HELPER_HEADER]: string } {
+  return { [STAINLESS_HELPER_HEADER]: value };
+}
+
+/**
+ * Symbol used to mark objects created by SDK helpers for tracking.
+ * The value is the helper name (e.g., 'mcpTool', 'betaZodTool').
+ */
+export const SDK_HELPER_SYMBOL = Symbol('anthropic.sdk.stainlessHelper');
+
+type StainlessHelperObject = { [SDK_HELPER_SYMBOL]: string };
+
+export function wasCreatedByStainlessHelper(value: unknown): value is StainlessHelperObject {
+  return typeof value === 'object' && value !== null && SDK_HELPER_SYMBOL in value;
+}
+
+/**
+ * Collects helper names from tools and messages arrays.
+ * Returns a deduplicated array of helper names found.
+ */
+export function collectStainlessHelpers(
+  tools: readonly unknown[] | undefined,
+  messages: readonly unknown[] | undefined,
+): string[] {
+  const helpers = new Set<string>();
+
+  // Collect from tools
+  if (tools) {
+    for (const tool of tools) {
+      if (wasCreatedByStainlessHelper(tool)) {
+        helpers.add(tool[SDK_HELPER_SYMBOL]);
+      }
+    }
+  }
+
+  // Collect from messages and their content blocks
+  if (messages) {
+    for (const message of messages) {
+      if (wasCreatedByStainlessHelper(message)) {
+        helpers.add(message[SDK_HELPER_SYMBOL]);
+      }
+
+      const content = (message as { content?: unknown }).content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (wasCreatedByStainlessHelper(block)) {
+            helpers.add(block[SDK_HELPER_SYMBOL]);
+          }
+        }
+      }
+    }
+  }
+
+  return Array.from(helpers);
+}
+
+/**
+ * Builds x-stainless-helper header value from tools and messages.
+ * Returns an empty object if no helpers are found.
+ */
+export function stainlessHelperHeader(
+  tools: readonly unknown[] | undefined,
+  messages: readonly unknown[] | undefined,
+): { 'x-stainless-helper'?: string } {
+  const helpers = collectStainlessHelpers(tools, messages);
+  if (helpers.length === 0) return {};
+  return { [STAINLESS_HELPER_HEADER]: helpers.join(', ') };
+}
+
+/**
+ * Builds x-stainless-helper header value from a file object.
+ * Returns an empty object if the file is not marked with a helper.
+ */
+export function stainlessHelperHeaderFromFile(file: unknown): { 'x-stainless-helper'?: string } {
+  if (wasCreatedByStainlessHelper(file)) {
+    return { [STAINLESS_HELPER_HEADER]: file[SDK_HELPER_SYMBOL] };
+  }
+  return {};
+}