dyadic 1.3.1 → 1.7.0

package/dist/otel.d.ts

@@ -0,0 +1,103 @@
+type HrTime = [number, number];
+type TimeLike = HrTime | number | bigint | string | Date | null | undefined;
+type Attributes = Record<string, unknown>;
+export interface SpanContextLike {
+    traceId: string;
+    spanId: string;
+    traceFlags?: number;
+    traceState?: {
+        serialize(): string;
+    } | string;
+}
+export interface InstrumentationScopeLike {
+    name: string;
+    version?: string;
+    schemaUrl?: string;
+}
+/** The parts of an OpenTelemetry ReadableSpan the exporter reads (SDK 1.x and 2.x). */
+export interface ReadableSpanLike {
+    name: string;
+    kind?: number;
+    spanContext(): SpanContextLike;
+    /** SDK 2.x */
+    parentSpanContext?: SpanContextLike | null;
+    /** SDK 1.x */
+    parentSpanId?: string;
+    startTime?: TimeLike;
+    endTime?: TimeLike;
+    status?: {
+        code?: number;
+        message?: string;
+    };
+    attributes?: Attributes;
+    events?: {
+        name: string;
+        time?: TimeLike;
+        attributes?: Attributes;
+        droppedAttributesCount?: number;
+    }[];
+    links?: {
+        context: SpanContextLike;
+        attributes?: Attributes;
+        droppedAttributesCount?: number;
+    }[];
+    resource?: {
+        attributes?: Attributes;
+        schemaUrl?: string;
+    };
+    /** SDK 2.x */
+    instrumentationScope?: InstrumentationScopeLike;
+    /** SDK 1.x */
+    instrumentationLibrary?: InstrumentationScopeLike;
+    droppedAttributesCount?: number;
+    droppedEventsCount?: number;
+    droppedLinksCount?: number;
+}
+/** OpenTelemetry's ExportResult: code 0 is SUCCESS, 1 is FAILED. */
+export interface ExportResultLike {
+    code: 0 | 1;
+    error?: Error;
+}
+export interface SpanExporterOptions {
+    /** Send content attributes (prompts, outputs, tool arguments and results). Off by default. */
+    captureContent?: boolean;
+    /** Applied to every attribute value before it leaves the process; null sends values as they are. Default: redactSecrets. */
+    redact?: ((value: unknown) => unknown) | null;
+    /** Spans per request (the service takes up to 1,000). */
+    maxSpansPerRequest?: number;
+    /** Bytes per request (the service takes up to 4 MB). */
+    maxBytesPerRequest?: number;
+    /** Replaces the HTTP call (tests, a proxy). */
+    send?: (request: Record<string, unknown>) => Promise<unknown>;
+    onError?: (error: unknown, request?: Record<string, unknown>) => void;
+}
+interface OtlpSender {
+    blackbox: {
+        sendOtlp: (request: Record<string, unknown>) => Promise<unknown>;
+    };
+}
+export declare const isContentAttribute: (key: string) => boolean;
+/** One span (a ReadableSpan or the same shape) as an OTLP/JSON span. */
+export declare function spanToOtlp(span: ReadableSpanLike, options?: Pick<SpanExporterOptions, "captureContent" | "redact">): Record<string, unknown>;
+/** Spans as OTLP/JSON ExportTraceServiceRequests, grouped by resource and instrumentation scope, split to fit the service. */
+export declare function toOtlpRequests(spans: readonly ReadableSpanLike[], options?: Omit<SpanExporterOptions, "send" | "onError">): Record<string, unknown>[];
+/** An OpenTelemetry SpanExporter that sends to the Black Box (see the top of this file). Never throws into the app. */
+export declare class BlackBoxSpanExporter {
+    readonly stats: {
+        spans: number;
+        requests: number;
+        failedSpans: number;
+        rejectedSpans: number;
+    };
+    private readonly options;
+    private readonly send;
+    private readonly pending;
+    private stopped;
+    constructor(client: OtlpSender | null, options?: SpanExporterOptions);
+    export(spans: ReadableSpanLike[], resultCallback: (result: ExportResultLike) => void): void;
+    private deliver;
+    /** Resolves when every export in flight has been sent (or given up on). */
+    forceFlush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export {};

package/dist/otel.js

@@ -0,0 +1,305 @@
+// OpenTelemetry: send the spans your agent framework already makes to the Black Box.
+//
+//   import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+//   import { Dyadic, BlackBoxSpanExporter } from "dyadic";
+//
+//   const provider = new BasicTracerProvider({ spanProcessors: [new BatchSpanProcessor(new BlackBoxSpanExporter(new Dyadic()))] });
+//
+// Spans following the GenAI semantic conventions (gen_ai.operation.name: chat, execute_tool, invoke_agent, ...) or
+// OpenInference (openinference.span.kind) become model calls, tool calls and agents in the Black Box; others are kept
+// as generic spans. One run per trace. The exporter sends OTLP/JSON to POST /v1/blackbox/otlp/v1/traces through the
+// client (its transport and retries; the service dedupes by span id, so a resent batch is harmless) and needs nothing
+// from OpenTelemetry at runtime: it takes the SDK's ReadableSpan objects (1.x and 2.x), or anything shaped like them.
+// Like the recorder, it sends content attributes (gen_ai.input.messages, input.value, tool arguments and results, ...)
+// only with { captureContent: true }, and every value is redacted first (secrets, by default).
+import { redactSecrets } from "./blackbox.js";
+const SCOPE = "dyadic.blackbox.exporter";
+const MAX_SPANS = 1000;
+const MAX_BYTES = 4 * 1024 * 1024 - 64 * 1024;
+const LONG_STRING = 16 * 1024;
+const MAX_DEPTH = 16;
+// What a span or span event can carry of the conversation itself (GenAI semantic conventions, their older
+// prompt/completion forms, OpenInference). Everything else is metadata.
+const CONTENT_KEYS = new Set(["gen_ai.input.messages", "gen_ai.output.messages", "gen_ai.system_instructions", "gen_ai.tool.definitions",
+    "gen_ai.tool.call.arguments", "gen_ai.tool.call.result", "gen_ai.prompt", "gen_ai.completion", "gen_ai.event.content",
+    "tool.parameters", "input.value", "output.value", "llm.prompts", "llm.tools", "message.content"]);
+const CONTENT_PREFIXES = ["gen_ai.prompt.", "gen_ai.completion.", "llm.input_messages.", "llm.output_messages.", "llm.prompt_template.",
+    "retrieval.documents.", "reranker.input_documents.", "reranker.output_documents.", "embedding.embeddings."];
+export const isContentAttribute = (key) => CONTENT_KEYS.has(key) || CONTENT_PREFIXES.some((prefix) => key.startsWith(prefix));
+const encoder = new TextEncoder();
+const byteLength = (value) => encoder.encode(JSON.stringify(value)).length;
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
+/** An attribute value as OTLP/JSON's AnyValue. */
+function anyValue(value, depth = 0) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value === "string")
+        return { stringValue: value };
+    if (typeof value === "boolean")
+        return { boolValue: value };
+    if (typeof value === "bigint")
+        return { intValue: value.toString() };
+    if (typeof value === "number") {
+        if (Number.isSafeInteger(value))
+            return { intValue: String(value) };
+        return Number.isFinite(value) ? { doubleValue: value } : { stringValue: String(value) };
+    }
+    if (value instanceof Uint8Array)
+        return { bytesValue: base64(value) };
+    if (value instanceof ArrayBuffer)
+        return { bytesValue: base64(new Uint8Array(value)) };
+    if (depth >= MAX_DEPTH)
+        return { stringValue: "[nested too deeply]" };
+    if (Array.isArray(value))
+        return { arrayValue: { values: value.map((v) => anyValue(v, depth + 1)) } };
+    if (typeof value === "object") {
+        return { kvlistValue: { values: Object.entries(value).filter(([, v]) => v !== undefined)
+                    .map(([key, v]) => ({ key, value: anyValue(v, depth + 1) })) } };
+    }
+    return { stringValue: String(value) };
+}
+/** Nanoseconds since the epoch, as OTLP/JSON writes them: from an HrTime [s, ns], milliseconds, a Date or nanoseconds. */
+function nanos(time) {
+    if (Array.isArray(time))
+        return (BigInt(Math.trunc(time[0] || 0)) * BigInt(1e9) + BigInt(Math.trunc(time[1] || 0))).toString();
+    if (typeof time === "bigint")
+        return time.toString();
+    if (typeof time === "number" && Number.isFinite(time)) {
+        const ms = Math.trunc(time);
+        return (BigInt(ms) * BigInt(1e6) + BigInt(Math.round((time - ms) * 1e6))).toString();
+    }
+    if (time instanceof Date && !Number.isNaN(time.getTime()))
+        return (BigInt(time.getTime()) * BigInt(1e6)).toString();
+    if (typeof time === "string" && /^\d{1,20}$/.test(time))
+        return time;
+    return "0";
+}
+const hexId = (value, size) => {
+    const text = String(value ?? "").toLowerCase();
+    return new RegExp(`^[0-9a-f]{${size}}$`).test(text) && !/^0+$/.test(text) ? text : "";
+};
+const traceState = (context) => {
+    const state = context?.traceState;
+    if (!state)
+        return undefined;
+    try {
+        return (typeof state === "string" ? state : state.serialize()) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+class Converter {
+    constructor(captureContent, redact) {
+        this.captureContent = captureContent;
+        this.redact = redact;
+    }
+    /** A value through the redactor; the default one also redacts by the attribute's last segment, so credential-named
+     *  fields (…authorization, …api_key) are caught. JSON text (tool arguments, messages) is redacted inside and written back. */
+    value(key, value) {
+        if (!this.redact)
+            return value;
+        const field = key.split(".").pop() || key;
+        if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+            // Bytes aren't text to scan; a credential-named field is still withheld.
+            return this.redact === redactSecrets && redactSecrets({ [field]: "x" })[field] !== "x" ? "[REDACTED:field]" : value;
+        }
+        if (typeof value === "string" && /^\s*[[{]/.test(value) && value.length <= 1024 * 1024) {
+            try {
+                const parsed = JSON.parse(value);
+                const redacted = this.apply(field, parsed);
+                if (JSON.stringify(redacted) !== JSON.stringify(parsed))
+                    return typeof redacted === "string" ? redacted : JSON.stringify(redacted);
+                return this.apply(field, value);
+            }
+            catch { /* not JSON: a plain string */ }
+        }
+        return this.apply(field, value);
+    }
+    apply(field, value) {
+        const out = this.redact(value);
+        return this.redact === redactSecrets ? redactSecrets({ [field]: out })[field] : out;
+    }
+    attributes(values, content) {
+        const out = [];
+        for (const [key, raw] of Object.entries(values ?? {})) {
+            if (raw === undefined || raw === null)
+                continue;
+            if (isContentAttribute(key) && !(content && this.captureContent))
+                continue;
+            out.push({ key, value: anyValue(this.value(key, raw)) });
+        }
+        return out;
+    }
+    span(span) {
+        const shape = span;
+        const context = (typeof shape.spanContext === "function" ? span.spanContext() : (shape.spanContext ?? shape.context ?? {}));
+        const parent = span.parentSpanContext?.spanId ?? span.parentSpanId ?? "";
+        const kind = Number.isInteger(span.kind) && span.kind >= 0 && span.kind <= 4 ? span.kind + 1 : 1;
+        const status = { code: [0, 1, 2].includes(Number(span.status?.code)) ? Number(span.status?.code) : 0 };
+        if (span.status?.message)
+            status.message = String(this.value("status.message", String(span.status.message)));
+        const out = {
+            traceId: hexId(context.traceId, 32), spanId: hexId(context.spanId, 16), parentSpanId: hexId(parent, 16),
+            name: String(span.name ?? ""), kind, startTimeUnixNano: nanos(span.startTime), endTimeUnixNano: nanos(span.endTime),
+            attributes: this.attributes(span.attributes, true),
+            events: (span.events ?? []).map((event) => ({ timeUnixNano: nanos(event.time), name: String(event.name ?? ""),
+                attributes: this.attributes(event.attributes, true), ...(event.droppedAttributesCount ? { droppedAttributesCount: event.droppedAttributesCount } : {}) })),
+            links: (span.links ?? []).filter((link) => link?.context).map((link) => ({ traceId: hexId(link.context.traceId, 32), spanId: hexId(link.context.spanId, 16),
+                ...(traceState(link.context) ? { traceState: traceState(link.context) } : {}), attributes: this.attributes(link.attributes, false),
+                ...(typeof link.context.traceFlags === "number" ? { flags: link.context.traceFlags } : {}),
+                ...(link.droppedAttributesCount ? { droppedAttributesCount: link.droppedAttributesCount } : {}) })),
+            status,
+        };
+        if (traceState(context))
+            out.traceState = traceState(context);
+        if (typeof context.traceFlags === "number")
+            out.flags = context.traceFlags;
+        for (const field of ["droppedAttributesCount", "droppedEventsCount", "droppedLinksCount"])
+            if (span[field])
+                out[field] = span[field];
+        return out;
+    }
+}
+/** A span too big for one request: content first, then long strings, then its attributes, until it fits. */
+function shrink(span, limit) {
+    const strip = (items, test) => items.filter((item) => !test(item));
+    const steps = [
+        (s) => { s.attributes = strip(s.attributes, (a) => isContentAttribute(a.key)); s.events = s.events.map((e) => ({ ...e, attributes: strip(e.attributes, (a) => isContentAttribute(a.key)) })); },
+        (s) => {
+            const cut = (v) => typeof v?.stringValue === "string" && v.stringValue.length > LONG_STRING ? { stringValue: `${v.stringValue.slice(0, LONG_STRING)}…[truncated]` }
+                : v?.arrayValue ? { arrayValue: { values: v.arrayValue.values.map(cut) } } : v?.kvlistValue ? { kvlistValue: { values: v.kvlistValue.values.map((kv) => ({ ...kv, value: cut(kv.value) })) } } : v;
+            s.attributes = s.attributes.map((a) => ({ ...a, value: cut(a.value) }));
+            s.events = s.events.map((e) => ({ ...e, attributes: e.attributes.map((a) => ({ ...a, value: cut(a.value) })) }));
+        },
+        (s) => { s.droppedEventsCount = Number(s.droppedEventsCount ?? 0) + s.events.length; s.events = []; s.droppedLinksCount = Number(s.droppedLinksCount ?? 0) + s.links.length; s.links = []; },
+        (s) => { s.droppedAttributesCount = Number(s.droppedAttributesCount ?? 0) + s.attributes.length; s.attributes = []; },
+    ];
+    let current = span;
+    for (const step of steps) {
+        if (byteLength(current) <= limit)
+            break;
+        current = JSON.parse(JSON.stringify(current));
+        step(current);
+    }
+    if (current !== span)
+        current.attributes.push({ key: "dyadic.blackbox.truncated", value: { boolValue: true } });
+    return current;
+}
+/** One span (a ReadableSpan or the same shape) as an OTLP/JSON span. */
+export function spanToOtlp(span, options = {}) {
+    return new Converter(options.captureContent ?? false, options.redact === undefined ? redactSecrets : options.redact).span(span);
+}
+/** Spans as OTLP/JSON ExportTraceServiceRequests, grouped by resource and instrumentation scope, split to fit the service. */
+export function toOtlpRequests(spans, options = {}) {
+    const converter = new Converter(options.captureContent ?? false, options.redact === undefined ? redactSecrets : options.redact);
+    const maxSpans = Math.max(1, Math.min(MAX_SPANS, options.maxSpansPerRequest ?? MAX_SPANS));
+    const maxBytes = Math.max(16 * 1024, Math.min(MAX_BYTES, options.maxBytesPerRequest ?? MAX_BYTES));
+    const resources = new Map();
+    const requests = [];
+    let groups = new Map();
+    let count = 0, bytes = 64;
+    const close = () => {
+        if (!count)
+            return;
+        requests.push({ resourceSpans: [...groups.values()].map((group) => ({ ...group.resource, scopeSpans: [...group.scopes.values()].map((scope) => ({ ...scope })) })) });
+        groups = new Map();
+        count = 0;
+        bytes = 64;
+    };
+    for (const span of spans) {
+        let resource = span.resource ? resources.get(span.resource) : undefined;
+        if (!resource) {
+            const attributes = converter.attributes(span.resource?.attributes, false);
+            const value = { resource: { attributes }, ...(span.resource?.schemaUrl ? { schemaUrl: span.resource.schemaUrl } : {}) };
+            resource = { key: JSON.stringify(value), resource: value };
+            if (span.resource)
+                resources.set(span.resource, resource);
+        }
+        const library = span.instrumentationScope ?? span.instrumentationLibrary;
+        const scope = { name: library?.name || SCOPE, ...(library?.version ? { version: library.version } : {}) };
+        const scopeKey = JSON.stringify([scope, library?.schemaUrl ?? ""]);
+        let item = converter.span(span);
+        let size = byteLength(item) + 1;
+        const overhead = byteLength(resource.resource) + byteLength(scope) + 64;
+        if (size + overhead > maxBytes) {
+            item = shrink(item, maxBytes - overhead);
+            size = byteLength(item) + 1;
+        }
+        const group = groups.get(resource.key), fresh = (group ? 0 : byteLength(resource.resource)) + (group?.scopes.has(scopeKey) ? 0 : byteLength(scope) + 32);
+        if (count && (count + 1 > maxSpans || bytes + size + fresh > maxBytes))
+            close();
+        if (!groups.has(resource.key)) {
+            groups.set(resource.key, { resource: resource.resource, scopes: new Map() });
+            bytes += byteLength(resource.resource) + 32;
+        }
+        const scopes = groups.get(resource.key).scopes;
+        if (!scopes.has(scopeKey)) {
+            scopes.set(scopeKey, { scope, ...(library?.schemaUrl ? { schemaUrl: library.schemaUrl } : {}), spans: [] });
+            bytes += byteLength(scope) + 32;
+        }
+        scopes.get(scopeKey).spans.push(item);
+        count++;
+        bytes += size;
+    }
+    close();
+    return requests;
+}
+/** An OpenTelemetry SpanExporter that sends to the Black Box (see the top of this file). Never throws into the app. */
+export class BlackBoxSpanExporter {
+    constructor(client, options = {}) {
+        this.stats = { spans: 0, requests: 0, failedSpans: 0, rejectedSpans: 0 };
+        this.pending = new Set();
+        this.stopped = false;
+        const send = options.send ?? (client ? (request) => client.blackbox.sendOtlp(request) : null);
+        if (!send)
+            throw new Error("BlackBoxSpanExporter needs a Dyadic client or options.send");
+        this.send = send;
+        this.options = { ...options };
+    }
+    export(spans, resultCallback) {
+        if (this.stopped) {
+            resultCallback({ code: 1, error: new Error("BlackBoxSpanExporter has been shut down") });
+            return;
+        }
+        if (!spans?.length) {
+            resultCallback({ code: 0 });
+            return;
+        }
+        const task = Promise.resolve().then(() => this.deliver(spans)).then(() => resultCallback({ code: 0 }), (error) => resultCallback({ code: 1, error: error instanceof Error ? error : new Error(String(error)) }));
+        this.pending.add(task);
+        void task.finally(() => this.pending.delete(task));
+    }
+    async deliver(spans) {
+        let failure = null;
+        for (const request of toOtlpRequests(spans, this.options)) {
+            const size = request.resourceSpans.reduce((n, r) => n + r.scopeSpans.reduce((m, s) => m + s.spans.length, 0), 0);
+            try {
+                const answer = await this.send(request);
+                this.stats.requests++;
+                this.stats.spans += size;
+                this.stats.rejectedSpans += Number(answer?.partialSuccess?.rejectedSpans ?? 0) || 0;
+            }
+            catch (error) {
+                this.stats.failedSpans += size;
+                this.options.onError?.(error, request);
+                failure ?? (failure = error);
+            }
+        }
+        if (failure !== null)
+            throw failure;
+    }
+    /** Resolves when every export in flight has been sent (or given up on). */
+    async forceFlush() {
+        await Promise.allSettled([...this.pending]);
+    }
+    async shutdown() {
+        this.stopped = true;
+        await this.forceFlush();
+    }
+}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "dyadic",
-  "version": "1.3.1",
-  "description": "The official TypeScript and JavaScript SDK for the Dyadic API: runs with your own agents and functions, plus the OpenAI-compatible API.",
+  "version": "1.7.0",
+  "description": "The official TypeScript and JavaScript SDK for the Dyadic API: runs with your own agents and functions, plus the OpenAI-, Anthropic- and OpenRouter-compatible APIs.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist", "README.md", "CHANGELOG.md"],
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
   "engines": { "node": ">=18" },
   "license": "MIT",
   "homepage": "https://dyadic.app/developers/",
-  "scripts": { "build": "tsc", "pretest": "tsc", "test": "node --test test/client.test.js test/transport.test.js", "prepack": "tsc" },
-  "devDependencies": { "typescript": "5.6.3" }
+  "scripts": { "build": "tsc", "pretest": "tsc", "test": "node --test test/client.test.js test/transport.test.js test/blackbox.test.js test/otel.test.js test/api.test.js test/live.test.js test/plans.test.js test/compatible.test.js", "test:production": "tsc && node --test live_tests/production.test.js", "prepack": "tsc" },
+  "devDependencies": { "@opentelemetry/api": "1.9.1", "@opentelemetry/sdk-trace-base": "2.12.0", "typescript": "5.6.3" }
 }