@purista/harness 1.0.0

package/dist/models/registry.js

@@ -0,0 +1,286 @@
+import { ModelCapabilityError } 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';
+/**
+ * Creates per-alias model handles that enforce capability gates before provider invocation.
+ *
+ * @example
+ * ```ts
+ * const registry = createModelRegistry({
+ *   assistant: { provider, model: 'gpt-4.1-mini', capabilities: ['text'] }
+ * })
+ * const out = await registry.assistant.text({ messages: [{ role: 'user', content: 'hi' }] }, new AbortController().signal)
+ * ```
+ */
+export function createModelRegistry(aliases, options = {}) {
+    return Object.fromEntries(Object.entries(aliases).map(([aliasKey, alias]) => [aliasKey, createHandle(aliasKey, alias, options)]));
+}
+function createHandle(aliasKey, alias, options) {
+    return {
+        text(req, signal, ctx) {
+            ensureCapabilities(aliasKey, alias, 'text', req);
+            if (!alias.provider.text)
+                throw methodMissing(aliasKey, 'text');
+            const fullReq = {
+                model: alias.model,
+                messages: req.messages,
+                ...(req.call ? { call: req.call } : {}),
+                ...(mergeDefaults(alias, req.call) ? { defaults: mergeDefaults(alias, req.call) } : {}),
+                ...(req.tools ? { tools: req.tools } : {}),
+                signal,
+                traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
+            };
+            return withModelSpan(options, aliasKey, alias, 'text', ctx, () => alias.provider.text(fullReq));
+        },
+        textStream(req, signal, ctx) {
+            ensureCapabilities(aliasKey, alias, 'text_stream', req);
+            if (!alias.provider.textStream)
+                throw methodMissing(aliasKey, 'textStream');
+            const fullReq = {
+                model: alias.model,
+                messages: req.messages,
+                ...(req.call ? { call: req.call } : {}),
+                ...(mergeDefaults(alias, req.call) ? { defaults: mergeDefaults(alias, req.call) } : {}),
+                ...(req.tools ? { tools: req.tools } : {}),
+                signal,
+                traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
+            };
+            return withModelStreamSpan(options, aliasKey, alias, 'text_stream', ctx, () => alias.provider.textStream(fullReq));
+        },
+        object(req, signal, ctx) {
+            ensureCapabilities(aliasKey, alias, 'object', req);
+            if (!alias.provider.object)
+                throw methodMissing(aliasKey, 'object');
+            const fullReq = {
+                model: alias.model,
+                messages: req.messages,
+                ...(req.call ? { call: req.call } : {}),
+                ...(mergeDefaults(alias, req.call) ? { defaults: mergeDefaults(alias, req.call) } : {}),
+                ...(req.tools ? { tools: req.tools } : {}),
+                schema: req.schema,
+                ...(req.schemaName ? { schemaName: req.schemaName } : {}),
+                signal,
+                traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
+            };
+            return withModelSpan(options, aliasKey, alias, 'object', ctx, () => alias.provider.object(fullReq));
+        },
+        objectStream(req, signal, ctx) {
+            ensureCapabilities(aliasKey, alias, 'object_stream', req);
+            if (!alias.provider.objectStream)
+                throw methodMissing(aliasKey, 'objectStream');
+            const fullReq = {
+                model: alias.model,
+                messages: req.messages,
+                ...(req.call ? { call: req.call } : {}),
+                ...(mergeDefaults(alias, req.call) ? { defaults: mergeDefaults(alias, req.call) } : {}),
+                ...(req.tools ? { tools: req.tools } : {}),
+                schema: req.schema,
+                ...(req.schemaName ? { schemaName: req.schemaName } : {}),
+                signal,
+                traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
+            };
+            return withModelStreamSpan(options, aliasKey, alias, 'object_stream', ctx, () => alias.provider.objectStream(fullReq));
+        },
+        embed(req, signal, ctx) {
+            ensureCapabilities(aliasKey, alias, 'embeddings', req);
+            if (!alias.provider.embed)
+                throw methodMissing(aliasKey, 'embed');
+            const fullReq = {
+                model: alias.model,
+                input: req.input,
+                ...(req.dimensions !== undefined ? { dimensions: req.dimensions } : {}),
+                ...(req.call ? { call: req.call } : {}),
+                signal,
+                traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
+            };
+            return withModelSpan(options, aliasKey, alias, 'embeddings', ctx, () => alias.provider.embed(fullReq));
+        },
+        rerank(req, signal, ctx) {
+            ensureCapabilities(aliasKey, alias, 'rerank', req);
+            if (!alias.provider.rerank)
+                throw methodMissing(aliasKey, 'rerank');
+            const fullReq = {
+                model: alias.model,
+                query: req.query,
+                documents: req.documents,
+                ...(req.topN !== undefined ? { topN: req.topN } : {}),
+                ...(req.call ? { call: req.call } : {}),
+                signal,
+                traceparent: req.traceparent ?? options.telemetry?.currentTraceparent()
+            };
+            return withModelSpan(options, aliasKey, alias, 'rerank', ctx, () => alias.provider.rerank(fullReq));
+        }
+    };
+}
+function withModelStreamSpan(options, aliasKey, alias, method, ctx, fn) {
+    if (!options.telemetry)
+        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) {
+        let lastUsage;
+        let lastFinishReason;
+        for await (const chunk of fn()) {
+            const current = chunk;
+            if (current.usage)
+                lastUsage = current.usage;
+            if (current.finishReason)
+                lastFinishReason = current.finishReason;
+            yield chunk;
+        }
+        if (lastUsage) {
+            span.setAttributes({
+                [ATTR_GEN_AI_USAGE_INPUT_TOKENS]: lastUsage.inputTokens,
+                [ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: lastUsage.outputTokens,
+                'gen_ai.usage.total_tokens': lastUsage.totalTokens
+            });
+            options.telemetry?.recordCounter('gen_ai.client.token.usage', lastUsage.inputTokens, { ...attrs, [ATTR_GEN_AI_TOKEN_TYPE]: GEN_AI_TOKEN_TYPE_VALUE_INPUT });
+            options.telemetry?.recordCounter('gen_ai.client.token.usage', lastUsage.outputTokens, { ...attrs, [ATTR_GEN_AI_TOKEN_TYPE]: GEN_AI_TOKEN_TYPE_VALUE_OUTPUT });
+        }
+        if (lastFinishReason)
+            span.setAttribute(ATTR_GEN_AI_RESPONSE_FINISH_REASONS, [lastFinishReason]);
+        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();
+    const started = Date.now();
+    const attrs = modelSpanAttrs(options, aliasKey, alias, method, ctx);
+    return options.telemetry.span(`chat ${alias.model}`, attrs, async (span) => {
+        const result = await fn();
+        const usage = result.usage;
+        const finishReason = result.finishReason;
+        if (usage) {
+            span.setAttributes({
+                [ATTR_GEN_AI_USAGE_INPUT_TOKENS]: usage.inputTokens,
+                [ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: usage.outputTokens,
+                'gen_ai.usage.total_tokens': usage.totalTokens
+            });
+            options.telemetry?.recordCounter('gen_ai.client.token.usage', usage.inputTokens, { ...attrs, [ATTR_GEN_AI_TOKEN_TYPE]: GEN_AI_TOKEN_TYPE_VALUE_INPUT });
+            options.telemetry?.recordCounter('gen_ai.client.token.usage', usage.outputTokens, { ...attrs, [ATTR_GEN_AI_TOKEN_TYPE]: GEN_AI_TOKEN_TYPE_VALUE_OUTPUT });
+        }
+        if (finishReason)
+            span.setAttribute(ATTR_GEN_AI_RESPONSE_FINISH_REASONS, [finishReason]);
+        options.telemetry?.recordHistogram('gen_ai.client.operation.duration', (Date.now() - started) / 1000, attrs);
+        return result;
+    });
+}
+function modelSpanAttrs(options, aliasKey, alias, method, ctx) {
+    return {
+        'harness.name': ctx?.harnessName ?? options.harnessName,
+        'harness.session.id': ctx?.sessionId,
+        'harness.run.id': ctx?.runId,
+        'harness.workflow.id': ctx?.workflowId,
+        'harness.agent.id': ctx?.agentId,
+        'harness.model.alias': aliasKey,
+        'harness.model.method': method,
+        [ATTR_GEN_AI_SYSTEM]: alias.provider.genAiSystem,
+        [ATTR_GEN_AI_REQUEST_MODEL]: alias.model,
+        'model.provider': alias.provider.id
+    };
+}
+/**
+ * Validates alias capabilities for the requested operation.
+ *
+ * Throws {@link ModelCapabilityError} when required capabilities are missing.
+ */
+function ensureCapabilities(aliasKey, alias, method, req) {
+    if (!alias.capabilities.includes(method)) {
+        throw new ModelCapabilityError('Model alias does not provide requested capability.', {
+            alias: aliasKey,
+            method,
+            reason: 'missing_capability'
+        });
+    }
+    if (req.tools && req.tools.length > 0 && !alias.capabilities.includes('tool_use')) {
+        throw new ModelCapabilityError('Model alias does not support tool use.', {
+            alias: aliasKey,
+            method,
+            reason: 'missing_capability'
+        });
+    }
+    const parts = (req.messages ?? []).flatMap((message) => Array.isArray(message.content) ? message.content : []);
+    const hasImageInput = parts.some((part) => part.kind === 'image' || part.kind === 'image_url');
+    if (hasImageInput && !alias.capabilities.includes('vision_input')) {
+        throw new ModelCapabilityError('Model alias does not support vision input.', {
+            alias: aliasKey,
+            method,
+            reason: 'missing_capability'
+        });
+    }
+    const hasAudioInput = parts.some((part) => part.kind === 'audio');
+    if (hasAudioInput && !alias.capabilities.includes('audio_input')) {
+        throw new ModelCapabilityError('Model alias does not support audio input.', {
+            alias: aliasKey,
+            method,
+            reason: 'missing_capability'
+        });
+    }
+    const hasFileInput = parts.some((part) => part.kind === 'file' || part.kind === 'file_url');
+    if (hasFileInput && !alias.capabilities.includes('file_input')) {
+        throw new ModelCapabilityError('Model alias does not support file input.', {
+            alias: aliasKey,
+            method,
+            reason: 'missing_capability'
+        });
+    }
+}
+/** Builds a standardized capability error when provider methods are missing. */
+function methodMissing(alias, method) {
+    return new ModelCapabilityError('Model provider method is not implemented.', {
+        alias,
+        method,
+        reason: 'method_missing'
+    });
+}
+/** Merges alias defaults with per-call overrides. */
+function mergeDefaults(alias, call) {
+    const merged = {
+        ...(alias.defaults ?? {}),
+        ...(call ?? {}),
+        providerOptions: {
+            ...(alias.defaults?.providerOptions ?? {}),
+            ...(call?.providerOptions ?? {})
+        }
+    };
+    const hasTopLevel = merged.temperature !== undefined
+        || merged.maxTokens !== undefined
+        || merged.topP !== undefined
+        || merged.stopSequences !== undefined
+        || Object.keys(merged.providerOptions ?? {}).length > 0;
+    return hasTopLevel ? merged : undefined;
+}

package/dist/models/state.d.ts

@@ -0,0 +1,64 @@
+import type { JsonValue } from './json.js';
+/** Session-level metadata persisted by a state store. */
+export interface SessionRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    runCount: number;
+    metadata?: Record<string, JsonValue>;
+}
+/** Message persisted in conversation history. */
+export interface Message {
+    id: string;
+    sessionId: string;
+    runId?: string;
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: JsonValue;
+    }>;
+    toolResults?: Array<{
+        toolCallId: string;
+        output?: JsonValue;
+        error?: SerializedError;
+    }>;
+    timestamp: string;
+}
+/** Run lifecycle status values.
+ * - `running`: active run in progress
+ * - `succeeded`: run completed successfully
+ * - `failed`: run completed with error
+ * - `cancelled`: run cancelled before completion
+ */
+export type RunStatus = 'running' | 'succeeded' | 'failed' | 'cancelled';
+/** Serialized error payload stored on run records. */
+export interface SerializedError {
+    code: string;
+    message: string;
+    category?: string;
+    retriable?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** Run record persisted by state stores. */
+export interface RunRecord {
+    id: string;
+    sessionId: string;
+    kind: 'workflow' | 'agent';
+    target: string;
+    startedAt: string;
+    finishedAt?: string;
+    status: RunStatus;
+    input?: JsonValue;
+    output?: JsonValue;
+    error?: SerializedError;
+}
+/** Event payload persisted for run replay or audit. */
+export interface PersistedRunEvent {
+    id: string;
+    runId: string;
+    at: string;
+    type: string;
+    payload: JsonValue;
+}

package/dist/models/state.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,56 @@
+import { HarnessError } from '../errors/index.js';
+import type { Logger } from '../logger/index.js';
+import type { EmbeddingRequest, EmbeddingResponse, ModelProvider, ObjectRequest, ObjectResponse, ObjectStreamChunk, RerankRequest, RerankResponse, TextRequest, TextResponse, TextStreamChunk } from './model-provider.js';
+import type { JsonValue } from '../models/json.js';
+import type { TelemetryShim } from '../telemetry/index.js';
+import type { HarnessAdapterContext } from './harness-context.js';
+export interface BaseModelProviderOptions {
+    id: string;
+    genAiSystem: string;
+    logger?: Logger;
+    telemetry?: TelemetryShim;
+    timeoutMs?: number;
+}
+type ProviderMethod = 'text' | 'textStream' | 'object' | 'objectStream' | 'embed' | 'rerank';
+type ProviderRequest = TextRequest | ObjectRequest | EmbeddingRequest | RerankRequest;
+/**
+ * Base class for model adapters.
+ *
+ * Adapter packages should map provider-specific requests/responses in protected
+ * `do*` methods. The base class owns cross-cutting harness behavior:
+ * cancellation, timeout, safe logs, metrics/spans, and error normalization.
+ */
+export declare abstract class BaseModelProvider implements ModelProvider {
+    readonly id: string;
+    readonly genAiSystem: string;
+    private logger;
+    private telemetry;
+    private timeoutMs;
+    protected constructor(options: BaseModelProviderOptions);
+    /**
+     * Called by the harness during composition so adapters automatically inherit
+     * harness-level logging, telemetry, and timeout defaults. Explicit adapter
+     * constructor options win over inherited values.
+     */
+    configureHarnessContext(context: HarnessAdapterContext): void;
+    text(req: TextRequest): Promise<TextResponse>;
+    textStream(req: TextRequest): AsyncIterable<TextStreamChunk>;
+    object<T extends JsonValue = JsonValue>(req: ObjectRequest<T>): Promise<ObjectResponse<T>>;
+    objectStream<T extends JsonValue = JsonValue>(req: ObjectRequest<T>): AsyncIterable<ObjectStreamChunk<T>>;
+    embed(req: EmbeddingRequest): Promise<EmbeddingResponse>;
+    rerank(req: RerankRequest): Promise<RerankResponse>;
+    protected doText(_req: TextRequest): Promise<TextResponse>;
+    protected doTextStream(_req: TextRequest): AsyncIterable<TextStreamChunk>;
+    protected doObject<T extends JsonValue = JsonValue>(_req: ObjectRequest<T>): Promise<ObjectResponse<T>>;
+    protected doObjectStream<T extends JsonValue = JsonValue>(_req: ObjectRequest<T>): AsyncIterable<ObjectStreamChunk<T>>;
+    protected doEmbed(_req: EmbeddingRequest): Promise<EmbeddingResponse>;
+    protected doRerank(_req: RerankRequest): Promise<RerankResponse>;
+    protected normalizeError(error: unknown, method: ProviderMethod, req: ProviderRequest): HarnessError;
+    private call;
+    private stream;
+    private withTimeout;
+    private methodMissing;
+    private attrs;
+    private recordUsage;
+}
+export {};