@purista/harness 1.0.0

package/dist/ports/base-model-provider.js

@@ -0,0 +1,343 @@
+import { ModelCapabilityError, ModelError, OperationCancelledError, OperationTimeoutError, HarnessError, sanitizeForLog, sanitizeProviderBody, sanitizeProviderMessage } from '../errors/index.js';
+/**
+ * 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 class BaseModelProvider {
+    id;
+    genAiSystem;
+    logger;
+    telemetry;
+    timeoutMs;
+    constructor(options) {
+        this.id = options.id;
+        this.genAiSystem = options.genAiSystem;
+        this.logger = options.logger;
+        this.telemetry = options.telemetry;
+        this.timeoutMs = options.timeoutMs;
+    }
+    /**
+     * 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) {
+        this.logger ??= context.logger;
+        this.telemetry ??= context.telemetry;
+        if (this.timeoutMs === undefined) {
+            this.timeoutMs = context.defaults.modelTimeoutMs;
+        }
+    }
+    text(req) {
+        return this.call('text', req, (next) => this.doText(next));
+    }
+    textStream(req) {
+        return this.stream('textStream', req, (next) => this.doTextStream(next));
+    }
+    object(req) {
+        return this.call('object', req, (next) => this.doObject(next));
+    }
+    objectStream(req) {
+        return this.stream('objectStream', req, (next) => this.doObjectStream(next));
+    }
+    embed(req) {
+        return this.call('embed', req, (next) => this.doEmbed(next));
+    }
+    rerank(req) {
+        return this.call('rerank', req, (next) => this.doRerank(next));
+    }
+    doText(_req) {
+        throw this.methodMissing('text');
+    }
+    doTextStream(_req) {
+        throw this.methodMissing('textStream');
+    }
+    doObject(_req) {
+        throw this.methodMissing('object');
+    }
+    doObjectStream(_req) {
+        throw this.methodMissing('objectStream');
+    }
+    doEmbed(_req) {
+        throw this.methodMissing('embed');
+    }
+    doRerank(_req) {
+        throw this.methodMissing('rerank');
+    }
+    normalizeError(error, method, req) {
+        if (error instanceof HarnessError)
+            return error;
+        if (req.signal.aborted || isAbortError(error)) {
+            return new OperationCancelledError('Model call was cancelled.', { scope: 'model' }, error);
+        }
+        const details = extractProviderErrorDetails(error);
+        const status = details.status;
+        const code = details.providerCode;
+        const reason = code === 'context_length_exceeded'
+            ? 'context_length_exceeded'
+            : status !== undefined
+                ? 'http_error'
+                : 'network';
+        return new ModelError(modelErrorMessage(details), {
+            provider: this.id,
+            model: req.model,
+            method,
+            ...(status !== undefined ? { status } : {}),
+            ...details,
+            reason
+        }, error);
+    }
+    async call(method, req, fn) {
+        req.signal.throwIfAborted();
+        const attrs = this.attrs(method, req);
+        const started = Date.now();
+        const execute = async (span) => {
+            const next = this.withTimeout(req, method);
+            try {
+                const operation = fn(next.req);
+                const result = await (next.timeoutPromise ? Promise.race([operation, next.timeoutPromise]) : operation);
+                this.telemetry?.recordHistogram('harness.model.duration', (Date.now() - started) / 1000, attrs);
+                this.recordUsage(method, req.model, result);
+                return result;
+            }
+            catch (error) {
+                const normalized = this.normalizeError(error, method, next.req);
+                span?.setAttributes?.(modelErrorTelemetryAttrs(normalized));
+                this.telemetry?.recordCounter('harness.model.errors', 1, { ...attrs, 'error.code': normalized.code });
+                this.logger?.error('Model provider call failed.', {
+                    provider: this.id,
+                    model: req.model,
+                    method,
+                    error: sanitizeForLog({ code: normalized.code, category: normalized.category, retriable: normalized.retriable, meta: normalized.meta })
+                });
+                throw normalized;
+            }
+            finally {
+                next.cleanup();
+            }
+        };
+        return this.telemetry ? this.telemetry.span(`harness.model.${method}`, attrs, execute) : execute();
+    }
+    stream(method, req, fn) {
+        req.signal.throwIfAborted();
+        const attrs = this.attrs(method, req);
+        const started = Date.now();
+        const iterate = async function* (span) {
+            const next = this.withTimeout(req, method);
+            try {
+                for await (const chunk of fn(next.req)) {
+                    next.req.signal.throwIfAborted();
+                    yield chunk;
+                }
+                this.telemetry?.recordHistogram('harness.model.duration', (Date.now() - started) / 1000, attrs);
+            }
+            catch (error) {
+                const normalized = this.normalizeError(error, method, next.req);
+                span?.setAttributes?.(modelErrorTelemetryAttrs(normalized));
+                this.telemetry?.recordCounter('harness.model.errors', 1, { ...attrs, 'error.code': normalized.code });
+                this.logger?.error('Model provider stream failed.', {
+                    provider: this.id,
+                    model: req.model,
+                    method,
+                    error: sanitizeForLog({ code: normalized.code, category: normalized.category, retriable: normalized.retriable, meta: normalized.meta })
+                });
+                throw normalized;
+            }
+            finally {
+                next.cleanup();
+            }
+        }.bind(this);
+        if (!this.telemetry)
+            return iterate();
+        return streamWithSpan(this.telemetry, `harness.model.${method}`, attrs, iterate);
+    }
+    withTimeout(req, method) {
+        if (!this.timeoutMs || this.timeoutMs <= 0) {
+            return { req, cleanup: () => undefined };
+        }
+        const controller = new AbortController();
+        const relay = () => controller.abort(req.signal.reason);
+        req.signal.addEventListener('abort', relay, { once: true });
+        let rejectTimeout;
+        const timeoutPromise = new Promise((_, reject) => { rejectTimeout = reject; });
+        const timeout = setTimeout(() => {
+            const error = new OperationTimeoutError('Model call timed out.', { scope: 'model', timeout_ms: this.timeoutMs });
+            controller.abort(error);
+            rejectTimeout?.(error);
+        }, this.timeoutMs);
+        return {
+            req: { ...req, signal: controller.signal },
+            timeoutPromise,
+            cleanup: () => {
+                clearTimeout(timeout);
+                req.signal.removeEventListener('abort', relay);
+            }
+        };
+    }
+    methodMissing(method) {
+        return new ModelCapabilityError('Model provider method is not implemented.', {
+            alias: this.id,
+            method,
+            reason: 'method_missing'
+        });
+    }
+    attrs(method, req) {
+        return {
+            'gen_ai.system': this.genAiSystem,
+            'gen_ai.request.model': req.model,
+            'model.provider': this.id,
+            'model.method': method
+        };
+    }
+    recordUsage(method, model, result) {
+        const usage = result.usage;
+        if (!usage)
+            return;
+        const attrs = { 'gen_ai.system': this.genAiSystem, 'gen_ai.request.model': model, 'model.provider': this.id, 'model.method': method };
+        this.telemetry?.recordCounter('harness.model.tokens.input', usage.inputTokens, attrs);
+        this.telemetry?.recordCounter('harness.model.tokens.output', usage.outputTokens, attrs);
+        this.telemetry?.recordCounter('harness.model.tokens.total', usage.totalTokens, attrs);
+    }
+}
+async function* streamWithSpan(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;
+}
+function isAbortError(error) {
+    const value = error;
+    return value?.name === 'AbortError' || value?.code === 'ABORT_ERR';
+}
+function modelErrorMessage(details) {
+    const parts = ['Model provider call failed'];
+    const qualifiers = [
+        details.status !== undefined ? `HTTP ${details.status}` : undefined,
+        details.providerCode,
+        details.providerType,
+        details.providerParam
+    ].filter((part) => Boolean(part));
+    if (qualifiers.length > 0)
+        parts.push(`(${qualifiers.join(', ')})`);
+    if (details.providerMessage)
+        parts.push(`: ${details.providerMessage.slice(0, 500)}`);
+    return `${parts.join('')}.`;
+}
+function modelErrorTelemetryAttrs(error) {
+    const meta = asRecord(error.meta);
+    return {
+        'harness.error.provider': stringTelemetryAttr(meta?.['provider']),
+        'harness.error.model': stringTelemetryAttr(meta?.['model']),
+        'harness.error.model_provider_status': numberTelemetryAttr(meta?.['status']),
+        'harness.error.model_provider_code': stringTelemetryAttr(meta?.['providerCode']),
+        'harness.error.model_provider_type': stringTelemetryAttr(meta?.['providerType']),
+        'harness.error.model_provider_param': stringTelemetryAttr(meta?.['providerParam']),
+        'harness.error.model_provider_request_id': stringTelemetryAttr(meta?.['providerRequestId']),
+        'harness.error.model_provider_message': stringTelemetryAttr(meta?.['providerMessage']),
+        'harness.error.model_provider_body': jsonTelemetryAttr(meta?.['providerBody'])
+    };
+}
+function stringTelemetryAttr(value) {
+    return typeof value === 'string' && value.length > 0 ? value.slice(0, 4000) : undefined;
+}
+function numberTelemetryAttr(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function jsonTelemetryAttr(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.stringify(value).slice(0, 8000);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractProviderErrorDetails(error) {
+    const record = asRecord(error);
+    if (!record)
+        return {};
+    const response = asRecord(record['response']);
+    const errorBody = asRecord(record['error']);
+    const headers = normalizeHeaders(record['headers'] ?? response?.['headers']);
+    const providerBody = sanitizeJsonLike(record['body'] ?? response?.['body'] ?? response?.['data'] ?? record['error']);
+    const status = numberField(record, 'status')
+        ?? numberField(record, 'statusCode')
+        ?? numberField(response, 'status')
+        ?? numberField(response, 'statusCode');
+    const providerCode = stringField(record, 'code') ?? stringField(errorBody, 'code');
+    const providerType = stringField(record, 'type') ?? stringField(errorBody, 'type');
+    const providerParam = stringField(record, 'param') ?? stringField(errorBody, 'param');
+    const providerRequestId = stringField(record, 'request_id')
+        ?? stringField(record, 'requestID')
+        ?? headers?.['x-request-id']
+        ?? headers?.['request-id'];
+    const providerMessageRaw = stringField(errorBody, 'message') ?? stringField(record, 'message');
+    const providerMessage = providerMessageRaw ? sanitizeProviderMessage(providerMessageRaw) : undefined;
+    return {
+        ...(status !== undefined ? { status } : {}),
+        ...(providerCode ? { providerCode } : {}),
+        ...(providerType ? { providerType } : {}),
+        ...(providerParam ? { providerParam } : {}),
+        ...(providerRequestId ? { providerRequestId } : {}),
+        ...(providerMessage ? { providerMessage } : {}),
+        ...(providerBody !== undefined ? { providerBody } : {})
+    };
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' ? value : undefined;
+}
+function stringField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function numberField(record, key) {
+    const value = record?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function normalizeHeaders(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    const headers = {};
+    for (const [key, headerValue] of Object.entries(record)) {
+        if (typeof headerValue === 'string' || typeof headerValue === 'number' || typeof headerValue === 'boolean') {
+            headers[key.toLowerCase()] = String(headerValue).slice(0, 2000);
+        }
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function sanitizeJsonLike(value) {
+    return sanitizeProviderBody(value);
+}

package/dist/ports/capabilities.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Stable capability ids declared by non-model harness adapters.
+ *
+ * Adapter capabilities describe setup-level behavior the harness may rely on.
+ * They are separate from `ModelCapability`, which describes model operations.
+ */
+export type AdapterCapability = 
+/** Sandbox supports filesystem access. */
+'sandbox.fs'
+/** Sandbox supports command execution. */
+ | 'sandbox.exec'
+/** Sandbox filesystem survives adapter-level close/reopen for the same session. */
+ | 'sandbox.persistent_fs'
+/** Sandbox can create durable snapshots. */
+ | 'sandbox.snapshot'
+/** Sandbox can resume a session from a durable snapshot. */
+ | 'sandbox.resume'
+/** Sandbox can snapshot and release active compute. */
+ | 'sandbox.hibernate'
+/** Runtime can commit stable checkpoints. */
+ | 'runtime.checkpoint'
+/** Runtime can retry durable boundaries. */
+ | 'runtime.retry'
+/** Runtime can coordinate distributed session/run ownership. */
+ | 'runtime.distributed_lock'
+/** Runtime can resume from committed checkpoints. */
+ | 'runtime.resume_from_checkpoint'
+/** Adapter can record feedback. */
+ | 'feedback.record';
+/** Data-only descriptor implemented by adapters that expose capability metadata. */
+export interface AdapterCapabilities {
+    readonly capabilities: readonly AdapterCapability[];
+}
+/** Adapter descriptor surfaced through `harness.inspect()`. */
+export interface AdapterInspection {
+    readonly kind: 'state' | 'sandbox' | 'runtime' | 'feedback' | 'model';
+    readonly id: string;
+    readonly capabilities: readonly AdapterCapability[];
+    readonly metadata?: Record<string, unknown>;
+}
+/** Data-only snapshot of resolved harness setup. */
+export interface HarnessInspection {
+    readonly name: string;
+    readonly capabilities: readonly AdapterCapability[];
+    readonly requiredCapabilities: readonly AdapterCapability[];
+    readonly adapters: readonly AdapterInspection[];
+}
+/** Optional durable runtime adapter surface for capability-gated setup. */
+export interface DurableRuntimeAdapter extends AdapterCapabilities {
+    readonly id?: string;
+}
+/** Result returned when comparing required and available adapter capabilities. */
+export interface AdapterCapabilityValidation {
+    readonly required: readonly AdapterCapability[];
+    readonly available: readonly AdapterCapability[];
+    readonly missing: readonly AdapterCapability[];
+    readonly ok: boolean;
+}
+/** Returns `true` when a value exposes an adapter capability descriptor. */
+export declare function hasAdapterCapabilities(value: unknown): value is AdapterCapabilities;
+/** Deduplicates capabilities while preserving first-seen order. */
+export declare function uniqueCapabilities(capabilities: readonly AdapterCapability[]): readonly AdapterCapability[];
+/** Returns the required capabilities that are not present in `available`. */
+export declare function missingCapabilities(required: readonly AdapterCapability[], available: readonly AdapterCapability[]): readonly AdapterCapability[];
+/** Aggregates effective capabilities from adapter descriptors. */
+export declare function collectAdapterCapabilities(adapters: readonly (AdapterCapabilities | undefined | null)[]): readonly AdapterCapability[];
+/** Compares required capabilities with the currently available capability set. */
+export declare function validateAdapterCapabilities(required: readonly AdapterCapability[], available: readonly AdapterCapability[]): AdapterCapabilityValidation;
+/** Throws when required adapter capabilities are missing. */
+export declare function assertAdapterCapabilities(required: readonly AdapterCapability[], available: readonly AdapterCapability[], message?: string): void;

package/dist/ports/capabilities.js

@@ -0,0 +1,38 @@
+/** Returns `true` when a value exposes an adapter capability descriptor. */
+export function hasAdapterCapabilities(value) {
+    return Boolean(value
+        && typeof value === 'object'
+        && Array.isArray(value.capabilities));
+}
+/** Deduplicates capabilities while preserving first-seen order. */
+export function uniqueCapabilities(capabilities) {
+    return [...new Set(capabilities)];
+}
+/** Returns the required capabilities that are not present in `available`. */
+export function missingCapabilities(required, available) {
+    const availableSet = new Set(available);
+    return uniqueCapabilities(required).filter((capability) => !availableSet.has(capability));
+}
+/** Aggregates effective capabilities from adapter descriptors. */
+export function collectAdapterCapabilities(adapters) {
+    return uniqueCapabilities(adapters.flatMap((adapter) => adapter?.capabilities ?? []));
+}
+/** Compares required capabilities with the currently available capability set. */
+export function validateAdapterCapabilities(required, available) {
+    const requiredCapabilities = uniqueCapabilities(required);
+    const availableCapabilities = uniqueCapabilities(available);
+    const missing = missingCapabilities(requiredCapabilities, availableCapabilities);
+    return {
+        required: requiredCapabilities,
+        available: availableCapabilities,
+        missing,
+        ok: missing.length === 0
+    };
+}
+/** Throws when required adapter capabilities are missing. */
+export function assertAdapterCapabilities(required, available, message = 'Required adapter capabilities are not available.') {
+    const result = validateAdapterCapabilities(required, available);
+    if (!result.ok) {
+        throw new Error(`${message} Missing: ${result.missing.join(', ')}`);
+    }
+}

package/dist/ports/feedback.d.ts

@@ -0,0 +1,29 @@
+import type { JsonValue } from '../models/json.js';
+/** Harness-native target that optional feedback can attach to. */
+export type FeedbackTarget = {
+    kind: 'run';
+    runId: string;
+} | {
+    kind: 'message';
+    sessionId: string;
+    messageId: string;
+} | {
+    kind: 'tool_call';
+    runId: string;
+    callId: string;
+} | {
+    kind: 'agent_invocation';
+    runId: string;
+    agentId: string;
+};
+/** Optional feedback signal associated with a harness-native target. */
+export interface FeedbackRecord {
+    id: string;
+    target: FeedbackTarget;
+    source: 'user' | 'application' | 'deterministic_rule' | 'evaluator' | 'human_review';
+    label: string;
+    score?: number;
+    comment?: string;
+    metadata?: Record<string, JsonValue>;
+    createdAt: string;
+}

package/dist/ports/feedback.js

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

package/dist/ports/harness-context.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from '../logger/index.js';
+import type { TelemetryShim } from '../telemetry/index.js';
+/** Harness-level context inherited by adapters registered with the harness. */
+export interface HarnessAdapterContext {
+    harnessName: string;
+    logger: Logger;
+    telemetry: TelemetryShim;
+    defaults: {
+        agentMaxIterations: number;
+        runTimeoutMs: number;
+        toolTimeoutMs: number;
+        skillTimeoutMs: number;
+        modelTimeoutMs: number;
+        historyWindow?: number;
+    };
+}
+/** Optional structural hook implemented by adapter base classes. */
+export interface HarnessContextConfigurable {
+    configureHarnessContext(context: HarnessAdapterContext): void;
+}

package/dist/ports/harness-context.js

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

package/dist/ports/index.d.ts

@@ -0,0 +1,6 @@
+export * from './model-provider.js';
+export * from './base-model-provider.js';
+export * from './state.js';
+export * from './harness-context.js';
+export * from './capabilities.js';
+export * from './feedback.js';

package/dist/ports/index.js

@@ -0,0 +1,6 @@
+export * from './model-provider.js';
+export * from './base-model-provider.js';
+export * from './state.js';
+export * from './harness-context.js';
+export * from './capabilities.js';
+export * from './feedback.js';