@purista/harness 1.2.6 → 1.5.1

package/dist/models/adapter-utils.d.ts

@@ -0,0 +1,52 @@
+import { ModelError } from '../errors/index.js';
+import type { JsonValue } from './json.js';
+import type { TokenUsage, ToolCallSpec } from '../ports/model-provider.js';
+/**
+ * Shared helpers for first-party model adapter packages.
+ *
+ * Adapters import these from `@purista/harness` so error shapes, token usage
+ * accounting, structured-JSON handling, and OpenAI-compatible stream tool-call
+ * accumulation stay identical across providers.
+ */
+/** Identifies the provider call an adapter helper acts on behalf of. */
+export interface AdapterCallContext {
+    provider: string;
+    model: string;
+    method: string;
+}
+/** Builds normalized token usage from optional provider token counts. */
+export declare function toTokenUsage(inputTokens?: number, outputTokens?: number, totalTokens?: number): TokenUsage;
+/**
+ * Replaces raw provider/model content with a redaction-safe descriptor.
+ *
+ * Raw strings are model output (POR-07 forbids logging/tracing them), so they
+ * collapse into `{ redacted, contentLength }`. Structured values pass through
+ * the provider-body redaction rules.
+ */
+export declare function redactProviderContent(body: unknown): unknown;
+/** Builds the shared `malformed_response` ModelError with a content-redacted provider body. */
+export declare function malformedResponseError(ctx: AdapterCallContext, message: string, body: unknown, cause: unknown): ModelError;
+/** Parses provider JSON output, throwing the shared malformed-response error on failure. */
+export declare function parseProviderJson(content: string, ctx: AdapterCallContext, message: string): JsonValue;
+/** Wraps not-yet-valid JSON fragments for partial object stream chunks. */
+export declare function safePartialJson(content: string): JsonValue;
+/** Drops the synthetic `harness_response` object tool from extracted tool calls. */
+export declare function withoutObjectTool(calls: ToolCallSpec[] | undefined): ToolCallSpec[] | undefined;
+/**
+ * Per-index accumulator for OpenAI-compatible streamed tool-call fragments.
+ *
+ * The first delta carries `index`/`id`/`function.name` with partial or empty
+ * arguments; later deltas carry only `index` and argument fragments. Fragments
+ * are concatenated by index and parsed once at stream end.
+ */
+export type StreamToolCallState = Map<number, {
+    id?: string;
+    name?: string;
+    args: string;
+}>;
+/** Creates an empty OpenAI-compatible stream tool-call accumulator. */
+export declare function createStreamToolCallState(): StreamToolCallState;
+/** Accumulates OpenAI-compatible `delta.tool_calls` fragments by index. */
+export declare function accumulateStreamToolCallDeltas(state: StreamToolCallState, deltas: unknown[]): void;
+/** Finalizes accumulated stream tool calls, parsing empty argument payloads as `{}`. */
+export declare function finalizeStreamToolCalls(state: StreamToolCallState, ctx: AdapterCallContext, malformedMessage: string): ToolCallSpec[];

package/dist/models/adapter-utils.js

@@ -0,0 +1,81 @@
+import { ModelError, sanitizeProviderBody } from '../errors/index.js';
+/** Builds normalized token usage from optional provider token counts. */
+export function toTokenUsage(inputTokens, outputTokens, totalTokens) {
+    const input = inputTokens ?? 0;
+    const output = outputTokens ?? 0;
+    return { inputTokens: input, outputTokens: output, totalTokens: totalTokens ?? input + output };
+}
+/**
+ * Replaces raw provider/model content with a redaction-safe descriptor.
+ *
+ * Raw strings are model output (POR-07 forbids logging/tracing them), so they
+ * collapse into `{ redacted, contentLength }`. Structured values pass through
+ * the provider-body redaction rules.
+ */
+export function redactProviderContent(body) {
+    if (typeof body === 'string')
+        return { redacted: true, contentLength: body.length };
+    return sanitizeProviderBody(body);
+}
+/** Builds the shared `malformed_response` ModelError with a content-redacted provider body. */
+export function malformedResponseError(ctx, message, body, cause) {
+    return new ModelError(message, {
+        provider: ctx.provider,
+        model: ctx.model,
+        method: ctx.method,
+        reason: 'malformed_response',
+        providerBody: redactProviderContent(body)
+    }, cause);
+}
+/** Parses provider JSON output, throwing the shared malformed-response error on failure. */
+export function parseProviderJson(content, ctx, message) {
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw malformedResponseError(ctx, message, content, error);
+    }
+}
+/** Wraps not-yet-valid JSON fragments for partial object stream chunks. */
+export function safePartialJson(content) {
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return { _partial: content };
+    }
+}
+/** Drops the synthetic `harness_response` object tool from extracted tool calls. */
+export function withoutObjectTool(calls) {
+    const filtered = calls?.filter((call) => call.name !== 'harness_response');
+    return filtered && filtered.length > 0 ? filtered : undefined;
+}
+/** Creates an empty OpenAI-compatible stream tool-call accumulator. */
+export function createStreamToolCallState() {
+    return new Map();
+}
+/** Accumulates OpenAI-compatible `delta.tool_calls` fragments by index. */
+export function accumulateStreamToolCallDeltas(state, deltas) {
+    for (const delta of deltas) {
+        const index = typeof delta?.index === 'number' ? delta.index : 0;
+        const existing = state.get(index) ?? { args: '' };
+        if (delta?.id)
+            existing.id = String(delta.id);
+        if (delta?.function?.name)
+            existing.name = String(delta.function.name);
+        if (typeof delta?.function?.arguments === 'string')
+            existing.args += delta.function.arguments;
+        state.set(index, existing);
+    }
+}
+/** Finalizes accumulated stream tool calls, parsing empty argument payloads as `{}`. */
+export function finalizeStreamToolCalls(state, ctx, malformedMessage) {
+    return [...state.entries()]
+        .sort((a, b) => a[0] - b[0])
+        .filter(([, call]) => call.id && call.name)
+        .map(([, call]) => ({
+        id: call.id,
+        name: call.name,
+        arguments: parseProviderJson(call.args || '{}', ctx, malformedMessage)
+    }));
+}

package/dist/models/registry.js

@@ -1,5 +1,6 @@
 import { ModelCapabilityError, ModelError } from '../errors/index.js';
 import { ATTR_GEN_AI_REQUEST_MODEL, ATTR_GEN_AI_RESPONSE_FINISH_REASONS, ATTR_GEN_AI_SYSTEM, ATTR_GEN_AI_TOKEN_TYPE, ATTR_GEN_AI_USAGE_INPUT_TOKENS, ATTR_GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_TOKEN_TYPE_VALUE_INPUT, GEN_AI_TOKEN_TYPE_VALUE_OUTPUT } from '@opentelemetry/semantic-conventions/incubating';
+import { pumpStreamThroughSpan } from './stream-pump.js';
 /**
  * Creates per-alias model handles that enforce capability gates before provider invocation.
  *
@@ -88,7 +89,7 @@ function createHandle(aliasKey, alias, options) {
                 model: alias.model,
                 input: req.input,
                 ...(req.dimensions !== undefined ? { dimensions: req.dimensions } : {}),
-                ...(req.call ? { call: req.call } : {}),
+                ...(mergeCallOptions(alias, req.call) ? { call: mergeCallOptions(alias, req.call) } : {}),
                 signal,
                 traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
             };
@@ -103,7 +104,7 @@ function createHandle(aliasKey, alias, options) {
                 query: req.query,
                 documents: req.documents,
                 ...(req.topN !== undefined ? { topN: req.topN } : {}),
-                ...(req.call ? { call: req.call } : {}),
+                ...(mergeCallOptions(alias, req.call) ? { call: mergeCallOptions(alias, req.call) } : {}),
                 signal,
                 traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
             };
@@ -157,7 +158,7 @@ function withModelStreamSpan(options, aliasKey, alias, method, ctx, fn) {
         return fn();
     const started = Date.now();
     const attrs = modelSpanAttrs(options, aliasKey, alias, method, ctx);
-    return streamWithTelemetry(options.telemetry, `chat ${alias.model}`, attrs, async function* (span) {
+    return pumpStreamThroughSpan(options.telemetry, `chat ${alias.model}`, attrs, async function* (span) {
         let lastUsage;
         let lastFinishReason;
         for await (const chunk of fn()) {
@@ -185,40 +186,6 @@ function withModelStreamSpan(options, aliasKey, alias, method, ctx, fn) {
         options.telemetry?.recordHistogram('gen_ai.client.operation.duration', (Date.now() - started) / 1000, attrs);
     });
 }
-async function* streamWithTelemetry(telemetry, name, attrs, iterate) {
-    const queue = [];
-    let done = false;
-    let failure;
-    let notify;
-    const wake = () => {
-        notify?.();
-        notify = undefined;
-    };
-    const producer = telemetry.span(name, attrs, async (span) => {
-        for await (const chunk of iterate(span)) {
-            queue.push(chunk);
-            wake();
-        }
-    }).catch((error) => {
-        failure = error;
-    }).finally(() => {
-        done = true;
-        wake();
-    });
-    while (!done || queue.length > 0) {
-        const next = queue.shift();
-        if (next !== undefined) {
-            yield next;
-            continue;
-        }
-        if (failure)
-            throw failure;
-        await new Promise((resolve) => { notify = resolve; });
-    }
-    await producer;
-    if (failure)
-        throw failure;
-}
 async function withModelSpan(options, aliasKey, alias, method, ctx, fn) {
     if (!options.telemetry)
         return fn();
@@ -335,10 +302,33 @@ function methodMissing(alias, method) {
 }
 /** Merges alias defaults with per-call overrides. */
 function mergeDefaults(alias, call) {
+    const retry = call?.retry ?? alias.defaults?.retry ?? alias.retry;
     const merged = {
         ...(alias.defaults ?? {}),
         ...(call ?? {}),
+        ...(retry !== undefined ? { retry } : {}),
+        providerOptions: {
+            ...(alias.providerOptions ?? {}),
+            ...(alias.defaults?.providerOptions ?? {}),
+            ...(call?.providerOptions ?? {})
+        }
+    };
+    const hasTopLevel = merged.temperature !== undefined
+        || merged.maxTokens !== undefined
+        || merged.topP !== undefined
+        || merged.stopSequences !== undefined
+        || merged.parallelToolCalls !== undefined
+        || merged.retry !== undefined
+        || Object.keys(merged.providerOptions ?? {}).length > 0;
+    return hasTopLevel ? merged : undefined;
+}
+function mergeCallOptions(alias, call) {
+    const retry = call?.retry ?? alias.defaults?.retry ?? alias.retry;
+    const merged = {
+        ...(call ?? {}),
+        ...(retry !== undefined ? { retry } : {}),
         providerOptions: {
+            ...(alias.providerOptions ?? {}),
             ...(alias.defaults?.providerOptions ?? {}),
             ...(call?.providerOptions ?? {})
         }
@@ -348,6 +338,7 @@ function mergeDefaults(alias, call) {
         || merged.topP !== undefined
         || merged.stopSequences !== undefined
         || merged.parallelToolCalls !== undefined
+        || merged.retry !== undefined
         || Object.keys(merged.providerOptions ?? {}).length > 0;
     return hasTopLevel ? merged : undefined;
 }

package/dist/models/stream-pump.d.ts

@@ -0,0 +1,16 @@
+import type { Span } from '@opentelemetry/api';
+import type { SpanAttrs, TelemetryShim } from '../telemetry/index.js';
+/**
+ * Bridges a span-scoped producer stream to a plain consumer `AsyncIterable`.
+ *
+ * The telemetry span must stay open for the full lifetime of the stream, so a
+ * producer task pulls chunks inside `telemetry.span(...)` and hands them to the
+ * consumer generator. Two guarantees keep this safe for model streams:
+ *
+ * - Backpressure: after pushing a chunk the producer waits until the consumer
+ *   has drained it, so a slow consumer never accumulates an unbounded queue.
+ * - Consumer abandonment: when the consumer stops early (break/return/throw),
+ *   the producer is woken, stops pulling, and closes the underlying iterator
+ *   so the provider stream is released instead of draining to completion.
+ */
+export declare function pumpStreamThroughSpan<T>(telemetry: TelemetryShim, name: string, attrs: SpanAttrs, iterate: (span: Span) => AsyncIterable<T>): AsyncIterable<T>;

package/dist/models/stream-pump.js

@@ -0,0 +1,77 @@
+/**
+ * Bridges a span-scoped producer stream to a plain consumer `AsyncIterable`.
+ *
+ * The telemetry span must stay open for the full lifetime of the stream, so a
+ * producer task pulls chunks inside `telemetry.span(...)` and hands them to the
+ * consumer generator. Two guarantees keep this safe for model streams:
+ *
+ * - Backpressure: after pushing a chunk the producer waits until the consumer
+ *   has drained it, so a slow consumer never accumulates an unbounded queue.
+ * - Consumer abandonment: when the consumer stops early (break/return/throw),
+ *   the producer is woken, stops pulling, and closes the underlying iterator
+ *   so the provider stream is released instead of draining to completion.
+ */
+export function pumpStreamThroughSpan(telemetry, name, attrs, iterate) {
+    return (async function* () {
+        const queue = [];
+        let producerDone = false;
+        let producerFailure;
+        let consumerAbandoned = false;
+        let notifyConsumer;
+        let notifyProducer;
+        const wakeConsumer = () => {
+            notifyConsumer?.();
+            notifyConsumer = undefined;
+        };
+        const wakeProducer = () => {
+            notifyProducer?.();
+            notifyProducer = undefined;
+        };
+        const producer = telemetry.span(name, attrs, async (span) => {
+            const iterator = iterate(span)[Symbol.asyncIterator]();
+            try {
+                while (!consumerAbandoned) {
+                    const next = await iterator.next();
+                    if (next.done)
+                        return;
+                    queue.push(next.value);
+                    wakeConsumer();
+                    // Backpressure: wait for consumer demand before pulling the next chunk.
+                    while (queue.length > 0 && !consumerAbandoned) {
+                        await new Promise((resolve) => { notifyProducer = resolve; });
+                    }
+                }
+            }
+            finally {
+                await iterator.return?.();
+            }
+        }).catch((error) => {
+            // Failures after consumer abandonment have no consumer left to observe them.
+            if (!consumerAbandoned)
+                producerFailure = error;
+        }).finally(() => {
+            producerDone = true;
+            wakeConsumer();
+        });
+        try {
+            while (true) {
+                if (queue.length > 0) {
+                    const chunk = queue.shift();
+                    wakeProducer();
+                    yield chunk;
+                    continue;
+                }
+                if (producerDone)
+                    break;
+                await new Promise((resolve) => { notifyConsumer = resolve; });
+            }
+            if (producerFailure)
+                throw producerFailure;
+        }
+        finally {
+            consumerAbandoned = true;
+            wakeProducer();
+            await producer;
+        }
+    })();
+}

package/dist/ports/base-model-provider.d.ts

@@ -54,4 +54,10 @@ export declare abstract class BaseModelProvider implements ModelProvider {
     private attrs;
     private recordUsage;
 }
-export {};
+/**
+ * Shared adapter helpers (`models/adapter-utils.js`) are part of the public
+ * model-provider surface so first-party adapter packages consume a single
+ * implementation. They are re-exported next to the adapter base class because
+ * the ports barrel is the public path for adapter authors.
+ */
+export * from '../models/adapter-utils.js';