@apifuse/provider-sdk 2.2.0-beta.60 → 2.2.0-beta.62

package/dist/runtime/http-telemetry-binding.d.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from "../types.js";
+import { type HttpTelemetrySink } from "./http-telemetry.js";
+/** Return whether a host binding has at least one callable declared HTTP method. */
+export declare function isSupportedHttpBinding(value: unknown): value is HttpClient;
+/** Emit the unsupported-shape warning once for the process. */
+export declare function warnUnsupportedHttpBinding(): void;
+/** Route SDK transports inside a host binding through the same attempt collector. */
+export declare function scopedHttpTelemetry(existing: HttpTelemetrySink | undefined): HttpTelemetrySink | undefined;
+/** Observe opaque host calls without changing their arguments, receiver or returned promise. */
+export declare function bindHttpTelemetry(client: HttpClient, sink: HttpTelemetrySink): HttpClient;

package/dist/runtime/http-telemetry-binding.js

@@ -0,0 +1,152 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { httpTelemetryErrorCode } from "./http-telemetry.js";
+import { startHttpTelemetry } from "./http-telemetry-guard.js";
+import { proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, } from "./proxy-retry-policy.js";
+const scopes = new AsyncLocalStorage();
+const methods = new Set(["request", "get", "post", "put", "delete", "stream", "sse"]);
+const adapters = new WeakMap();
+let unsupportedShapeWarned = false;
+/** Return whether a host binding has at least one callable declared HTTP method. */
+export function isSupportedHttpBinding(value) {
+    if ((typeof value !== "object" && typeof value !== "function") || value === null)
+        return false;
+    for (const method of methods) {
+        try {
+            if (typeof Reflect.get(value, method) === "function")
+                return true;
+        }
+        catch {
+            // A hostile property getter is not a usable binding.
+        }
+    }
+    return false;
+}
+/** Emit the unsupported-shape warning once for the process. */
+export function warnUnsupportedHttpBinding() {
+    if (unsupportedShapeWarned)
+        return;
+    unsupportedShapeWarned = true;
+    try {
+        console.warn("[apifuse] http telemetry not attached; reason=unsupported_binding_shape");
+    }
+    catch {
+        // Warning output is diagnostic only and must not affect request handling.
+    }
+}
+/** Route SDK transports inside a host binding through the same attempt collector. */
+export function scopedHttpTelemetry(existing) {
+    const scope = scopes.getStore();
+    if (!scope)
+        return existing;
+    scope.nativeObserved = true;
+    if (!existing || existing === scope.sink)
+        return scope.sink;
+    return {
+        markTelemetryFailed: () => scope.sink.markTelemetryFailed?.(),
+        startRequest(options) {
+            const request = startHttpTelemetry(scope.sink, options.retryPreset);
+            const observer = startHttpTelemetry({
+                startRequest: (options) => existing.startRequest(options),
+                markTelemetryFailed() {
+                    scope.sink.markTelemetryFailed?.();
+                    existing.markTelemetryFailed?.();
+                },
+            }, options.retryPreset);
+            return {
+                recordAttempt(event) {
+                    request.recordAttempt(event);
+                    observer.recordAttempt(event);
+                },
+                finish(ms) {
+                    request.finish(ms);
+                    observer.finish(ms);
+                },
+                toTenantRetryPayload() {
+                    observer.toTenantRetryPayload();
+                    return request.toTenantRetryPayload();
+                },
+            };
+        },
+    };
+}
+/** Observe opaque host calls without changing their arguments, receiver or returned promise. */
+export function bindHttpTelemetry(client, sink) {
+    if ((typeof client === "object" && client !== null) || typeof client === "function") {
+        const existing = adapters.get(client);
+        if (existing) {
+            existing.sink = sink;
+            return existing.adapter;
+        }
+    }
+    const wrappers = new Map();
+    // An inheriting target also supports hosts whose own methods are frozen.
+    const adapter = new Proxy(Object.create(client), {
+        get(_target, property) {
+            const original = Reflect.get(client, property, client);
+            if (typeof property !== "string" || !methods.has(property) || typeof original !== "function")
+                return original;
+            const cached = wrappers.get(property);
+            if (cached?.original === original)
+                return cached.wrapped;
+            const wrapped = function (...args) {
+                // Direct calls keep the host receiver; explicit and unbound receivers pass through.
+                const receiver = this === adapter ? client : this;
+                const scope = { sink: state.sink, nativeObserved: false };
+                const started = performance.now();
+                const settled = (result, failed) => {
+                    if (scope.nativeObserved)
+                        return;
+                    const request = startHttpTelemetry(state.sink, undefined);
+                    request.observe(() => {
+                        const status = failed
+                            ? proxyTransportRetryErrorStatus(result)
+                            : result &&
+                                typeof result === "object" &&
+                                "status" in result &&
+                                typeof result.status === "number"
+                                ? result.status
+                                : undefined;
+                        request.recordAttempt({
+                            ms: performance.now() - started,
+                            proxyUsed: false,
+                            ...(status === undefined ? {} : { status }),
+                            ...(failed
+                                ? { e: httpTelemetryErrorCode(proxyTransportRetryErrorCode(result)) }
+                                : {}),
+                        });
+                    });
+                    request.finish(performance.now() - started);
+                };
+                return scopes.run(scope, () => {
+                    let result;
+                    try {
+                        result = Reflect.apply(original, receiver, args);
+                    }
+                    catch (error) {
+                        settled(error, true);
+                        throw error;
+                    }
+                    try {
+                        if (result instanceof Promise) {
+                            void Promise.prototype.then.call(result, (value) => settled(value, false), (error) => settled(error, true));
+                        }
+                        else
+                            settled(result, false);
+                    }
+                    catch (error) {
+                        // Promise subclasses may throw while a telemetry continuation is attached.
+                        startHttpTelemetry(state.sink, undefined).observe(() => {
+                            throw error;
+                        });
+                    }
+                    return result;
+                });
+            };
+            wrappers.set(property, { original, wrapped });
+            return wrapped;
+        },
+    });
+    const state = { sink, adapter };
+    adapters.set(adapter, state);
+    return adapter;
+}

package/dist/runtime/http-telemetry-guard.d.ts

@@ -0,0 +1,6 @@
+import type { HttpRetrySummary } from "../types.js";
+import { type HttpTelemetryRequestSink, type HttpTelemetrySink } from "./http-telemetry.js";
+/** Keep all public observers, including property access, outside transport failures. */
+export declare function startHttpTelemetry(sink: HttpTelemetrySink | undefined, retryPreset: HttpRetrySummary["preset"]): HttpTelemetryRequestSink & {
+    observe(callback: () => void): void;
+};

package/dist/runtime/http-telemetry-guard.js

@@ -0,0 +1,150 @@
+import { HttpTelemetryCollector, } from "./http-telemetry.js";
+const intrinsicPromiseThen = Promise.prototype.then;
+const ignoreObserverResult = () => { };
+/** Attach handlers only through the Promise intrinsic; never invoke a host thenable. */
+function absorbObserverPromise(value) {
+    let constructorDescriptor;
+    let shadowed = false;
+    try {
+        constructorDescriptor = Object.getOwnPropertyDescriptor(value, "constructor");
+        // Even the intrinsic `then` consults Symbol.species. An undefined constructor
+        // selects its intrinsic Promise without reading a subclass's species getter.
+        Object.defineProperty(value, "constructor", {
+            value: undefined,
+            configurable: constructorDescriptor?.configurable ?? true,
+        });
+        shadowed = true;
+    }
+    catch {
+        // Non-extensible ordinary promises can still accept intrinsic handlers.
+    }
+    try {
+        void intrinsicPromiseThen.call(value, ignoreObserverResult, ignoreObserverResult);
+    }
+    catch {
+        // A non-Promise thenable has no intrinsic rejection to absorb. Do not run it.
+    }
+    finally {
+        if (shadowed) {
+            try {
+                if (constructorDescriptor) {
+                    Object.defineProperty(value, "constructor", constructorDescriptor);
+                }
+                else {
+                    Reflect.deleteProperty(value, "constructor");
+                }
+            }
+            catch {
+                // Host object traps are also observer failures.
+            }
+        }
+    }
+}
+function isAsyncObserverReturn(value) {
+    if (!value || (typeof value !== "object" && typeof value !== "function"))
+        return false;
+    try {
+        if (!("then" in value) || typeof value.then !== "function")
+            return false;
+    }
+    catch {
+        // A rejected Promise can itself have a throwing `then` getter. Still absorb it.
+    }
+    absorbObserverPromise(value);
+    return true;
+}
+/** Keep all public observers, including property access, outside transport failures. */
+export function startHttpTelemetry(sink, retryPreset) {
+    let failed = false;
+    const fail = () => {
+        if (failed)
+            return;
+        failed = true;
+        try {
+            isAsyncObserverReturn(sink?.markTelemetryFailed?.());
+        }
+        catch {
+            // The failure reporter is itself an observer. Never recurse.
+        }
+    };
+    const observe = (callback) => {
+        try {
+            const result = callback();
+            if (isAsyncObserverReturn(result)) {
+                // The observer API is synchronous. Absorb invalid asynchronous returns too.
+                fail();
+                return undefined;
+            }
+            return result;
+        }
+        catch {
+            fail();
+            return undefined;
+        }
+    };
+    const result = observe(() => (sink ?? new HttpTelemetryCollector()).startRequest({ retryPreset }));
+    const request = observe(() => {
+        if (!result ||
+            typeof result.recordAttempt !== "function" ||
+            typeof result.finish !== "function" ||
+            typeof result.toTenantRetryPayload !== "function") {
+            fail();
+            return undefined;
+        }
+        return result;
+    });
+    return {
+        observe,
+        recordAttempt: (event) => {
+            observe(() => request?.recordAttempt(event));
+        },
+        finish: (ms) => {
+            observe(() => request?.finish(ms));
+        },
+        toTenantRetryPayload: () => {
+            if (failed)
+                return undefined;
+            return observe(() => {
+                const value = observe(() => request?.toTenantRetryPayload());
+                if (value === undefined)
+                    return undefined;
+                // Copy only validated primitive fields; never pass observer-owned objects on.
+                const { attempts, retries, preset, transport, lastErrorCode, lastStatus } = value;
+                if (!Number.isSafeInteger(attempts) ||
+                    attempts < 2 ||
+                    !Number.isSafeInteger(retries) ||
+                    (retries !== attempts - 1 &&
+                        !(attempts === Number.MAX_SAFE_INTEGER && retries === Number.MAX_SAFE_INTEGER)) ||
+                    transport !== "native" ||
+                    (preset !== undefined &&
+                        ![
+                            "off",
+                            "transport_transient",
+                            "safe_read",
+                            "aggressive_read",
+                            "rate_limit_aware",
+                        ].includes(preset)) ||
+                    (lastErrorCode !== undefined &&
+                        ![
+                            "transport_network_error",
+                            "transport_timeout",
+                            "transport_cancelled",
+                            "upstream_http_error",
+                            "other",
+                        ].includes(lastErrorCode)) ||
+                    (lastStatus !== undefined && (!Number.isSafeInteger(lastStatus) || lastStatus < 0))) {
+                    fail();
+                    return undefined;
+                }
+                return {
+                    attempts,
+                    retries,
+                    ...(preset === undefined ? {} : { preset }),
+                    transport,
+                    ...(lastErrorCode === undefined ? {} : { lastErrorCode }),
+                    ...(lastStatus === undefined ? {} : { lastStatus }),
+                };
+            });
+        },
+    };
+}

package/dist/runtime/http-telemetry.d.ts

@@ -0,0 +1,104 @@
+import type { HttpRetrySummary } from "../types.js";
+import { type ClosedEnum, type TelemetryContributor, type TenantNeutral } from "./request-telemetry.js";
+/** The same closed vocabulary used by tenant-visible meta.retry. */
+export type HttpTelemetryErrorCode = "transport_network_error" | "transport_timeout" | "transport_cancelled" | "upstream_http_error" | "other";
+export declare function httpTelemetryErrorCode(code: string | undefined): HttpTelemetryErrorCode;
+export type HttpTelemetryRetryPayload = {
+    attempts: number;
+    retries: number;
+    preset?: ClosedEnum<NonNullable<HttpRetrySummary["preset"]>>;
+    transport: ClosedEnum<HttpRetrySummary["transport"]>;
+    lastErrorCode?: ClosedEnum<HttpTelemetryErrorCode>;
+    /** Last failed attempt's status, preserving the existing meta.retry contract. */
+    lastStatus?: number;
+};
+export type HttpAttemptTelemetryEvent = {
+    ms: number;
+    proxyUsed: boolean;
+    status?: number;
+    e?: HttpTelemetryErrorCode;
+    /** A returned status-retry outcome, rather than a thrown transport error. */
+    statusRetry?: boolean;
+    /** Operator-only error text. Never projected into the header or tenant metadata. */
+    diagnostics?: {
+        name: string;
+        message: string;
+        cause?: {
+            name: string;
+            message: string;
+        };
+    };
+};
+export interface HttpTelemetryRequestSink {
+    recordAttempt(event: HttpAttemptTelemetryEvent): void;
+    /** Called once when the logical HTTP call settles; includes backoff time. */
+    finish(ms: number): void;
+    toTenantRetryPayload(): TenantNeutral<HttpTelemetryRetryPayload> | undefined;
+}
+export interface HttpTelemetrySink {
+    /** Optional, best-effort failure marker; called at most once per logical request. */
+    markTelemetryFailed?(): void;
+    /** Each call gets independent retry state, including concurrent calls. */
+    startRequest(options: {
+        retryPreset?: HttpRetrySummary["preset"];
+    }): HttpTelemetryRequestSink;
+}
+export type HttpAttemptSample = {
+    n: number;
+    ms: number;
+    status?: number;
+    e?: HttpTelemetryErrorCode;
+    diagnostics?: HttpAttemptTelemetryEvent["diagnostics"];
+};
+export type HttpTelemetryLogPayload = {
+    /** Observer failure; operator-only and never projected into the header. */
+    telemetryFailed?: true;
+    attempts: number;
+    retries: number;
+    timeouts: number;
+    proxyUsed: boolean;
+    /** Most recently completed attempt's status, including successful statuses. */
+    lastStatus?: number;
+    retryPreset?: HttpRetrySummary["preset"];
+    transport: HttpRetrySummary["transport"];
+    lastErrorCode?: HttpTelemetryErrorCode;
+    attemptSamples: HttpAttemptSample[];
+    dropped: number;
+    /** Sum of logical call durations, including retry delays. */
+    ms: number;
+    /** Most recent successful retried call; also the source of tenant meta.retry. */
+    retry?: HttpTelemetryRetryPayload;
+};
+export type HttpTelemetryHeaderPayload = {
+    attempts: number;
+    retries: number;
+    timeouts: number;
+    proxyUsed: boolean;
+    lastStatus?: number;
+    retryPreset?: ClosedEnum<NonNullable<HttpRetrySummary["preset"]>>;
+    transport: ClosedEnum<HttpRetrySummary["transport"]>;
+    lastErrorCode?: ClosedEnum<HttpTelemetryErrorCode>;
+    attemptSamples: {
+        n: number;
+        ms: number;
+        status?: number;
+        e?: ClosedEnum<HttpTelemetryErrorCode>;
+    }[];
+    dropped: number;
+    ms: number;
+    retry?: HttpTelemetryRetryPayload;
+};
+export declare class HttpTelemetryCollector implements HttpTelemetrySink, TelemetryContributor<HttpTelemetryLogPayload, HttpTelemetryHeaderPayload> {
+    #private;
+    readonly key: "http";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    markTelemetryFailed(): void;
+    startRequest(options: {
+        retryPreset?: HttpRetrySummary["preset"];
+    }): HttpTelemetryRequestSink;
+    toTenantRetryPayload(): TenantNeutral<HttpTelemetryRetryPayload> | undefined;
+    toLogPayload(): HttpTelemetryLogPayload | undefined;
+    toHeaderPayload(log: HttpTelemetryLogPayload): HttpTelemetryHeaderPayload;
+}

package/dist/runtime/http-telemetry.js

@@ -0,0 +1,190 @@
+import { Buffer } from "node:buffer";
+import { closedEnum, } from "./request-telemetry.js";
+export function httpTelemetryErrorCode(code) {
+    switch (code) {
+        case "transport_network_error":
+        case "transport_timeout":
+        case "transport_cancelled":
+        case "upstream_http_error":
+            return code;
+        default:
+            return "other";
+    }
+}
+const MAX_ATTEMPT_SAMPLES = 24;
+const MAX_DIAGNOSTIC_TEXT = 300;
+function integer(value) {
+    return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
+}
+function saturatingAdd(a, b) {
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return Number.MAX_SAFE_INTEGER;
+    return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+function boundedText(value, redact) {
+    let result;
+    try {
+        result = redact?.(value) ?? value;
+    }
+    catch {
+        return "[REDACTION_FAILED]";
+    }
+    // Detach caller text through independent UTF-16 storage, preserving lone surrogates.
+    const length = Math.min(result.length, MAX_DIAGNOSTIC_TEXT);
+    const units = Buffer.alloc(length * 2);
+    for (let index = 0; index < length; index++)
+        units.writeUInt16LE(result.charCodeAt(index), index * 2);
+    return units.toString("utf16le");
+}
+export class HttpTelemetryCollector {
+    key = "http";
+    #redact;
+    #telemetryFailed = false;
+    #attempts = 0;
+    #retries = 0;
+    #timeouts = 0;
+    #proxyUsed = false;
+    #lastStatus;
+    #retryPreset;
+    #lastErrorCode;
+    #samples = [];
+    #dropped = 0;
+    #ms = 0;
+    #retry;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    markTelemetryFailed() {
+        this.#telemetryFailed = true;
+    }
+    startRequest(options) {
+        const preset = options.retryPreset;
+        let attempts = 0;
+        let retries = 0;
+        let lastErrorCode;
+        let lastStatus;
+        let retry;
+        let finished = false;
+        return {
+            recordAttempt: (event) => {
+                if (attempts > 0) {
+                    retries = saturatingAdd(retries, 1);
+                    this.#retries = saturatingAdd(this.#retries, 1);
+                }
+                attempts = saturatingAdd(attempts, 1);
+                this.#attempts = saturatingAdd(this.#attempts, 1);
+                if (event.e === "transport_timeout")
+                    this.#timeouts = saturatingAdd(this.#timeouts, 1);
+                this.#proxyUsed ||= event.proxyUsed;
+                this.#retryPreset = preset;
+                if (event.status !== undefined)
+                    this.#lastStatus = integer(event.status);
+                if (event.e)
+                    this.#lastErrorCode = event.e;
+                if (this.#samples.length < MAX_ATTEMPT_SAMPLES) {
+                    const text = (value) => boundedText(value, this.#redact);
+                    this.#samples.push({
+                        n: attempts,
+                        ms: saturatingAdd(0, event.ms),
+                        ...(event.status === undefined ? {} : { status: integer(event.status) }),
+                        ...(event.e ? { e: event.e } : {}),
+                        ...(event.diagnostics
+                            ? {
+                                diagnostics: {
+                                    name: text(event.diagnostics.name),
+                                    message: text(event.diagnostics.message),
+                                    ...(event.diagnostics.cause
+                                        ? {
+                                            cause: {
+                                                name: text(event.diagnostics.cause.name),
+                                                message: text(event.diagnostics.cause.message),
+                                            },
+                                        }
+                                        : {}),
+                                },
+                            }
+                            : {}),
+                    });
+                }
+                else
+                    this.#dropped = saturatingAdd(this.#dropped, 1);
+                if (event.e) {
+                    lastStatus = event.status;
+                    // Historically status-retry outcomes set lastStatus only. Preserve those pins.
+                    if (!event.statusRetry)
+                        lastErrorCode = event.e;
+                }
+                else if (attempts > 1) {
+                    retry = {
+                        attempts,
+                        retries,
+                        ...(preset ? { preset: closedEnum(preset) } : {}),
+                        transport: closedEnum("native"),
+                        ...(lastErrorCode ? { lastErrorCode: closedEnum(lastErrorCode) } : {}),
+                        ...(lastStatus ? { lastStatus: integer(lastStatus) } : {}),
+                    };
+                    this.#retry = retry;
+                }
+            },
+            finish: (ms) => {
+                if (!finished && attempts > 0)
+                    this.#ms = saturatingAdd(this.#ms, ms);
+                finished = true;
+            },
+            toTenantRetryPayload: () => (!this.#telemetryFailed && retry ? { ...retry } : undefined),
+        };
+    }
+    toTenantRetryPayload() {
+        return !this.#telemetryFailed && this.#retry ? { ...this.#retry } : undefined;
+    }
+    toLogPayload() {
+        if (this.#attempts === 0 && !this.#telemetryFailed)
+            return undefined;
+        return {
+            ...(this.#telemetryFailed ? { telemetryFailed: true } : {}),
+            attempts: this.#attempts,
+            retries: this.#retries,
+            timeouts: this.#timeouts,
+            proxyUsed: this.#proxyUsed,
+            ...(this.#lastStatus === undefined ? {} : { lastStatus: this.#lastStatus }),
+            ...(this.#retryPreset ? { retryPreset: this.#retryPreset } : {}),
+            transport: "native",
+            ...(this.#lastErrorCode ? { lastErrorCode: this.#lastErrorCode } : {}),
+            attemptSamples: this.#samples.map((sample) => ({
+                ...sample,
+                ...(sample.diagnostics
+                    ? {
+                        diagnostics: {
+                            ...sample.diagnostics,
+                            ...(sample.diagnostics.cause ? { cause: { ...sample.diagnostics.cause } } : {}),
+                        },
+                    }
+                    : {}),
+            })),
+            dropped: this.#dropped,
+            ms: this.#ms,
+            ...(this.#retry ? { retry: { ...this.#retry } } : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            attempts: log.attempts,
+            retries: log.retries,
+            timeouts: log.timeouts,
+            proxyUsed: log.proxyUsed,
+            ...(log.lastStatus === undefined ? {} : { lastStatus: log.lastStatus }),
+            ...(log.retryPreset ? { retryPreset: closedEnum(log.retryPreset) } : {}),
+            transport: closedEnum(log.transport),
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            attemptSamples: log.attemptSamples.map(({ n, ms, status, e }) => ({
+                n,
+                ms,
+                ...(status === undefined ? {} : { status }),
+                ...(e ? { e: closedEnum(e) } : {}),
+            })),
+            dropped: log.dropped,
+            ms: log.ms,
+            ...(log.retry ? { retry: { ...log.retry } } : {}),
+        };
+    }
+}

package/dist/runtime/http.d.ts

@@ -1,9 +1,40 @@
 import type { ProxyResolutionOptions } from "../config/loader.js";
 import type { HttpClient, HttpRetrySummary } from "../types.js";
+import { type HttpTelemetrySink } from "./http-telemetry.js";
 export type HttpClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
     userAgent?: string;
     onRetrySummary?: (summary: HttpRetrySummary) => void;
+    /**
+     * Synchronous observer for HTTP attempts, retries, timeouts, status, duration,
+     * and observed proxy use. Observer failures never change transport behavior.
+     * All hooks and their property reads are guarded, including `onRetrySummary`
+     * and the failure reporter. Invalid asynchronous results are ignored and never
+     * awaited. Observer failures set the log-only `telemetryFailed` marker; the
+     * marker and redacted error diagnostics are excluded from headers and tenant
+     * metadata. Tenant `meta.retry` retains its existing response shape.
+     *
+     * After `ProviderEngine.attach`, the server wraps supported host HTTP bindings
+     * with the request collector. The adapter preserves arguments, direct-call,
+     * explicit `.call`/`.apply`, and unbound receivers, plus the original returned
+     * promise, response, stream, and error. Streams and SSE are observed at headers
+     * without consuming their bodies. SDK clients report every observed attempt
+     * and keep any observer configured here; routing is scoped to each call.
+     *
+     * Binding an existing adapter reuses its identity and replaces its collector:
+     * the latest bind receives subsequent calls, the earlier collector receives no
+     * further calls, and in-flight calls keep the collector captured at invocation.
+     * An opaque host invocation is one observed attempt with zero observed retries;
+     * its undisclosed retries and proxy settings cannot be inferred, and tenant
+     * `meta.retry` is omitted. Status, duration, and error class remain available
+     * in logs and telemetry headers.
+     *
+     * Non-object bindings and objects without a callable `request`, `get`, `post`,
+     * `put`, `delete`, `stream`, or `sse` method are left untouched, with no `http`
+     * telemetry sibling and one process-wide warning for this reason:
+     * `[apifuse] http telemetry not attached; reason=unsupported_binding_shape`.
+     */
+    httpTelemetry?: HttpTelemetrySink;
     signal?: AbortSignal;
 };
 export declare function createHttpClient(baseUrl?: string, clientOptions?: HttpClientOptions): HttpClient;