@purista/harness 1.2.6 → 1.5.0

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

@@ -1,4 +1,21 @@
 import { ModelCapabilityError, ModelError, OperationCancelledError, OperationTimeoutError, HarnessError, sanitizeForLog, sanitizeProviderBody, sanitizeProviderMessage } from '../errors/index.js';
+import { redactProviderContent } from '../models/adapter-utils.js';
+import { pumpStreamThroughSpan } from '../models/stream-pump.js';
+const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    maxActiveElapsedMs: 60_000,
+    maxActiveDelayMs: 20_000,
+    respectRetryAfter: true,
+    minDelayMs: 500,
+    maxDelayMs: 8_000,
+    longRetry: 'error',
+    retryOn: {
+        network: true,
+        timeout: true,
+        rateLimit: true,
+        serverError: true
+    }
+};
 /**
  * Base class for model adapters.
  *
@@ -71,8 +88,17 @@ export class BaseModelProvider {
         return this.logger;
     }
     normalizeError(error, method, req) {
+        if (error instanceof ModelError)
+            return withRedactedProviderBody(error);
         if (error instanceof HarnessError)
             return error;
+        // A base-enforced timeout aborts the request signal with the timeout error
+        // as reason. Provider SDKs surface that as a generic abort error, so the
+        // timeout classification must win over the cancellation classification to
+        // keep stream timeouts retry-eligible per spec 23.
+        if (req.signal.reason instanceof OperationTimeoutError) {
+            return req.signal.reason;
+        }
         if (req.signal.aborted || isAbortError(error)) {
             return new OperationCancelledError('Model call was cancelled.', { scope: 'model' }, error);
         }
@@ -81,9 +107,13 @@ export class BaseModelProvider {
         const code = details.providerCode;
         const reason = code === 'context_length_exceeded'
             ? 'context_length_exceeded'
-            : status !== undefined
-                ? 'http_error'
-                : 'network';
+            : status === 429
+                ? 'rate_limited'
+                : typeof status === 'number' && status >= 500
+                    ? 'provider_unavailable'
+                    : status !== undefined
+                        ? 'http_error'
+                        : 'network';
         return new ModelError(modelErrorMessage(details), {
             provider: this.id,
             model: req.model,
@@ -98,28 +128,51 @@ export class BaseModelProvider {
         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();
+            const retry = resolveRetryPolicy(req);
+            let attempt = 1;
+            while (true) {
+                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);
+                    const decision = retryDecision(normalized, retry, attempt, started);
+                    if (decision.action === 'retry') {
+                        this.telemetry?.recordCounter('harness.model.retries', 1, { ...attrs, 'harness.model.retry.reason': decision.reason });
+                        this.telemetry?.recordHistogram('harness.model.retry.delay', decision.delayMs / 1000, attrs);
+                        this.logger?.warn('Retrying model provider call.', {
+                            provider: this.id,
+                            model: req.model,
+                            method,
+                            attempt,
+                            nextAttempt: attempt + 1,
+                            delayMs: decision.delayMs,
+                            reason: decision.reason
+                        });
+                        next.cleanup();
+                        await sleep(decision.delayMs, req.signal);
+                        attempt += 1;
+                        continue;
+                    }
+                    const finalError = decorateRetryMeta(normalized, decision.retryKind, attempt, retry.maxAttempts, decision.delayMs);
+                    span?.setAttributes?.(modelErrorTelemetryAttrs(finalError));
+                    this.telemetry?.recordCounter('harness.model.errors', 1, { ...attrs, 'error.code': finalError.code });
+                    this.logger?.error('Model provider call failed.', {
+                        provider: this.id,
+                        model: req.model,
+                        method,
+                        error: sanitizeForLog({ code: finalError.code, category: finalError.category, retriable: finalError.retriable, meta: finalError.meta })
+                    });
+                    throw finalError;
+                }
+                finally {
+                    next.cleanup();
+                }
             }
         };
         return this.telemetry ? this.telemetry.span(`harness.model.${method}`, attrs, execute) : execute();
@@ -129,33 +182,59 @@ export class BaseModelProvider {
         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;
+            const retry = resolveRetryPolicy(req);
+            let attempt = 1;
+            let emitted = false;
+            while (true) {
+                const next = this.withTimeout(req, method);
+                try {
+                    for await (const chunk of fn(next.req)) {
+                        next.req.signal.throwIfAborted();
+                        emitted = true;
+                        yield chunk;
+                    }
+                    this.telemetry?.recordHistogram('harness.model.duration', (Date.now() - started) / 1000, attrs);
+                    return;
+                }
+                catch (error) {
+                    const normalized = this.normalizeError(error, method, next.req);
+                    const decision = emitted ? { action: 'fail', retryKind: 'none' } : retryDecision(normalized, retry, attempt, started);
+                    if (decision.action === 'retry') {
+                        this.telemetry?.recordCounter('harness.model.retries', 1, { ...attrs, 'harness.model.retry.reason': decision.reason });
+                        this.telemetry?.recordHistogram('harness.model.retry.delay', decision.delayMs / 1000, attrs);
+                        this.logger?.warn('Retrying model provider stream before first chunk.', {
+                            provider: this.id,
+                            model: req.model,
+                            method,
+                            attempt,
+                            nextAttempt: attempt + 1,
+                            delayMs: decision.delayMs,
+                            reason: decision.reason
+                        });
+                        next.cleanup();
+                        await sleep(decision.delayMs, req.signal);
+                        attempt += 1;
+                        continue;
+                    }
+                    const finalError = decorateRetryMeta(normalized, decision.retryKind, attempt, retry.maxAttempts, 'delayMs' in decision ? decision.delayMs : undefined);
+                    span?.setAttributes?.(modelErrorTelemetryAttrs(finalError));
+                    this.telemetry?.recordCounter('harness.model.errors', 1, { ...attrs, 'error.code': finalError.code });
+                    this.logger?.error('Model provider stream failed.', {
+                        provider: this.id,
+                        model: req.model,
+                        method,
+                        error: sanitizeForLog({ code: finalError.code, category: finalError.category, retriable: finalError.retriable, meta: finalError.meta })
+                    });
+                    throw finalError;
+                }
+                finally {
+                    next.cleanup();
                 }
-                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);
+        return pumpStreamThroughSpan(this.telemetry, `harness.model.${method}`, attrs, iterate);
     }
     withTimeout(req, method) {
         if (!this.timeoutMs || this.timeoutMs <= 0) {
@@ -168,6 +247,11 @@ export class BaseModelProvider {
             relay();
         let rejectTimeout;
         const timeoutPromise = new Promise((_, reject) => { rejectTimeout = reject; });
+        // Streams never race against this promise (they rely on the relayed signal
+        // abort), and unary calls may settle through the operation branch of the
+        // race. Mark the rejection as handled so a firing timer can never surface
+        // as an unhandled promise rejection.
+        timeoutPromise.catch(() => undefined);
         const timeout = setTimeout(() => {
             const error = new OperationTimeoutError('Model call timed out.', { scope: 'model', timeout_ms: this.timeoutMs });
             controller.abort(error);
@@ -207,40 +291,6 @@ export class BaseModelProvider {
         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';
@@ -270,7 +320,11 @@ function modelErrorTelemetryAttrs(error) {
         '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'])
+        'harness.error.model_provider_body': jsonTelemetryAttr(redactProviderContent(meta?.['providerBody'])),
+        'harness.error.model_retry_kind': stringTelemetryAttr(meta?.['retryKind']),
+        'harness.error.model_retry_after_ms': numberTelemetryAttr(meta?.['retryAfterMs']),
+        'harness.error.model_retry_attempt': numberTelemetryAttr(meta?.['retryAttempt']),
+        'harness.error.model_retry_max_attempts': numberTelemetryAttr(meta?.['retryMaxAttempts'])
     };
 }
 function stringTelemetryAttr(value) {
@@ -295,13 +349,22 @@ function extractProviderErrorDetails(error) {
         return {};
     const response = asRecord(record['response']);
     const errorBody = asRecord(record['error']);
-    const headers = normalizeHeaders(record['headers'] ?? response?.['headers']);
+    // AWS SDK v3 errors carry status/headers under `$metadata`/`$response`.
+    const awsMetadata = asRecord(record['$metadata']);
+    const awsResponse = asRecord(record['$response']);
+    const headers = normalizeHeaders(record['headers'] ?? response?.['headers'] ?? awsResponse?.['headers']);
+    const retryAfterMs = headers ? parseRetryAfterMs(headers) : undefined;
+    const rateLimit = headers ? parseRateLimit(headers) : undefined;
     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');
+        ?? numberField(response, 'statusCode')
+        ?? numberField(awsMetadata, 'httpStatusCode')
+        ?? (awsMetadata ? statusFromAwsErrorName(stringField(record, 'name')) : undefined);
+    const providerCode = stringField(record, 'code')
+        ?? stringField(errorBody, 'code')
+        ?? (awsMetadata ? stringField(record, 'name') : undefined);
     const providerType = stringField(record, 'type') ?? stringField(errorBody, 'type');
     const providerParam = stringField(record, 'param') ?? stringField(errorBody, 'param');
     const providerRequestId = stringField(record, 'request_id')
@@ -317,9 +380,40 @@ function extractProviderErrorDetails(error) {
         ...(providerParam ? { providerParam } : {}),
         ...(providerRequestId ? { providerRequestId } : {}),
         ...(providerMessage ? { providerMessage } : {}),
-        ...(providerBody !== undefined ? { providerBody } : {})
+        ...(providerBody !== undefined ? { providerBody } : {}),
+        ...(headers ? { providerHeaders: headers } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(rateLimit ? { rateLimit } : {})
     };
 }
+/**
+ * Well-known AWS SDK error names mapped to their HTTP-equivalent status so
+ * retry classification works even when `$metadata.httpStatusCode` is absent.
+ */
+const AWS_ERROR_NAME_STATUS = {
+    ThrottlingException: 429,
+    TooManyRequestsException: 429,
+    ModelNotReadyException: 429,
+    ServiceUnavailableException: 503,
+    InternalServerException: 500
+};
+function statusFromAwsErrorName(name) {
+    return name ? AWS_ERROR_NAME_STATUS[name] : undefined;
+}
+/**
+ * Adapter-built errors may carry raw provider/model content in
+ * `meta.providerBody`. Re-issue the error with a content-redacted body so logs,
+ * spans, and serialized errors never see raw output (POR-07).
+ */
+function withRedactedProviderBody(error) {
+    const meta = asRecord(error.meta);
+    if (!meta || meta['providerBody'] === undefined)
+        return error;
+    return new ModelError(error.message, {
+        ...meta,
+        providerBody: redactProviderContent(meta['providerBody'])
+    }, error.cause ?? error);
+}
 function asRecord(value) {
     return value !== null && typeof value === 'object' ? value : undefined;
 }
@@ -332,13 +426,35 @@ function numberField(record, key) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
 function normalizeHeaders(value) {
+    const headersLike = value;
+    if (headersLike?.forEach) {
+        const headers = {};
+        headersLike.forEach((headerValue, key) => {
+            const normalizedKey = key.toLowerCase();
+            if (!isSensitiveHeader(normalizedKey))
+                headers[normalizedKey] = String(headerValue).slice(0, 2000);
+        });
+        return Object.keys(headers).length > 0 ? headers : undefined;
+    }
+    if (headersLike?.entries) {
+        const headers = {};
+        for (const [key, headerValue] of headersLike.entries()) {
+            const normalizedKey = key.toLowerCase();
+            if (!isSensitiveHeader(normalizedKey))
+                headers[normalizedKey] = String(headerValue).slice(0, 2000);
+        }
+        return Object.keys(headers).length > 0 ? headers : undefined;
+    }
     const record = asRecord(value);
     if (!record)
         return undefined;
     const headers = {};
     for (const [key, headerValue] of Object.entries(record)) {
+        const normalizedKey = key.toLowerCase();
+        if (isSensitiveHeader(normalizedKey))
+            continue;
         if (typeof headerValue === 'string' || typeof headerValue === 'number' || typeof headerValue === 'boolean') {
-            headers[key.toLowerCase()] = String(headerValue).slice(0, 2000);
+            headers[normalizedKey] = String(headerValue).slice(0, 2000);
         }
     }
     return Object.keys(headers).length > 0 ? headers : undefined;
@@ -346,3 +462,184 @@ function normalizeHeaders(value) {
 function sanitizeJsonLike(value) {
     return sanitizeProviderBody(value);
 }
+function resolveRetryPolicy(req) {
+    const setting = req.call?.retry ?? ('defaults' in req ? req.defaults?.retry : undefined) ?? true;
+    if (setting === false) {
+        return { ...DEFAULT_RETRY_POLICY, maxAttempts: 1 };
+    }
+    if (setting === true || setting === undefined) {
+        return DEFAULT_RETRY_POLICY;
+    }
+    return {
+        ...DEFAULT_RETRY_POLICY,
+        ...setting,
+        maxAttempts: setting.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts,
+        maxActiveElapsedMs: setting.maxActiveElapsedMs ?? DEFAULT_RETRY_POLICY.maxActiveElapsedMs,
+        maxActiveDelayMs: setting.maxActiveDelayMs ?? DEFAULT_RETRY_POLICY.maxActiveDelayMs,
+        minDelayMs: setting.minDelayMs ?? DEFAULT_RETRY_POLICY.minDelayMs,
+        maxDelayMs: setting.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+        respectRetryAfter: setting.respectRetryAfter ?? DEFAULT_RETRY_POLICY.respectRetryAfter,
+        longRetry: setting.longRetry ?? DEFAULT_RETRY_POLICY.longRetry,
+        retryOn: {
+            ...DEFAULT_RETRY_POLICY.retryOn,
+            ...(setting.retryOn ?? {})
+        }
+    };
+}
+function isSensitiveHeader(key) {
+    return key === 'authorization'
+        || key === 'proxy-authorization'
+        || key === 'x-api-key'
+        || key === 'api-key'
+        || key === 'openai-api-key'
+        || key.endsWith('-api-key');
+}
+function retryDecision(error, policy, attempt, startedAt) {
+    if (attempt >= policy.maxAttempts)
+        return { action: 'fail', retryKind: 'none' };
+    const reason = retryReason(error, policy);
+    if (!reason)
+        return { action: 'fail', retryKind: 'none' };
+    const providerDelay = policy.respectRetryAfter ? retryAfterFromError(error) : undefined;
+    const delayMs = providerDelay ?? computedBackoffMs(policy, attempt);
+    const elapsed = Date.now() - startedAt;
+    if (delayMs > policy.maxActiveDelayMs || elapsed + delayMs > policy.maxActiveElapsedMs) {
+        // `longRetry: 'defer'` opts into the deferred classification for
+        // provider-instructed delays beyond the active budget; the default
+        // `'error'` fails immediately with `retryKind: 'none'`.
+        const deferredAllowed = policy.longRetry === 'defer'
+            && providerDelay !== undefined
+            && (policy.maxDeferredDelayMs === undefined || providerDelay <= policy.maxDeferredDelayMs);
+        if (deferredAllowed)
+            return { action: 'fail', retryKind: 'deferred', delayMs: providerDelay };
+        return { action: 'fail', retryKind: 'none' };
+    }
+    return { action: 'retry', delayMs, reason };
+}
+function retryReason(error, policy) {
+    if (error instanceof OperationTimeoutError)
+        return policy.retryOn.timeout ? 'timeout' : undefined;
+    if (!(error instanceof ModelError))
+        return undefined;
+    const meta = asRecord(error.meta);
+    const status = typeof meta?.['status'] === 'number' ? meta['status'] : undefined;
+    const reason = typeof meta?.['reason'] === 'string' ? meta['reason'] : undefined;
+    if ((reason === 'network' || status === 408 || status === 409) && policy.retryOn.network)
+        return reason ?? `http_${status}`;
+    if ((reason === 'rate_limited' || status === 429) && policy.retryOn.rateLimit)
+        return 'rate_limited';
+    if ((reason === 'provider_unavailable' || (typeof status === 'number' && status >= 500)) && policy.retryOn.serverError)
+        return 'provider_unavailable';
+    return undefined;
+}
+function retryAfterFromError(error) {
+    const meta = asRecord(error.meta);
+    const value = meta?.['retryAfterMs'];
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function computedBackoffMs(policy, attempt) {
+    const base = Math.min(policy.maxDelayMs, policy.minDelayMs * (2 ** Math.max(0, attempt - 1)));
+    const jitter = 0.75 + Math.random() * 0.25;
+    return Math.max(0, Math.floor(base * jitter));
+}
+function decorateRetryMeta(error, retryKind, attempt, maxAttempts, delayMs) {
+    if (!(error instanceof ModelError))
+        return error;
+    const meta = {
+        ...(error.meta ?? {}),
+        retryKind,
+        retryAttempt: attempt,
+        retryMaxAttempts: maxAttempts,
+        // `retryAfterMs` is only ever the provider-instructed delay carried by a
+        // deferred classification; synthetic harness backoff is never written here.
+        ...(retryKind === 'deferred' && delayMs !== undefined ? { retryAfterMs: delayMs } : {})
+    };
+    return new ModelError(error.message, meta, error.cause ?? error);
+}
+function parseRetryAfterMs(headers) {
+    const retryAfterMs = parsePositiveNumber(headers['retry-after-ms']);
+    if (retryAfterMs !== undefined)
+        return retryAfterMs;
+    const retryAfter = headers['retry-after'];
+    if (!retryAfter)
+        return undefined;
+    const seconds = parsePositiveNumber(retryAfter);
+    if (seconds !== undefined)
+        return seconds * 1000;
+    const date = Date.parse(retryAfter);
+    if (Number.isFinite(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}
+/**
+ * Parses the OpenAI/Azure (`x-ratelimit-*`) and Anthropic
+ * (`anthropic-ratelimit-*`) request and token header families. When several
+ * buckets are present the exhausted bucket (`remaining === 0`) wins so the
+ * reported scope identifies what was actually rate limited.
+ */
+function parseRateLimit(headers) {
+    const buckets = [
+        parseRateLimitBucket('requests', headers['x-ratelimit-limit-requests'] ?? headers['anthropic-ratelimit-requests-limit'], headers['x-ratelimit-remaining-requests'] ?? headers['anthropic-ratelimit-requests-remaining'], headers['anthropic-ratelimit-requests-reset'] ?? headers['x-ratelimit-reset-requests']),
+        parseRateLimitBucket('tokens', headers['x-ratelimit-limit-tokens'] ?? headers['anthropic-ratelimit-tokens-limit'], headers['x-ratelimit-remaining-tokens'] ?? headers['anthropic-ratelimit-tokens-remaining'], headers['anthropic-ratelimit-tokens-reset'] ?? headers['x-ratelimit-reset-tokens']),
+        parseRateLimitBucket('input_tokens', headers['anthropic-ratelimit-input-tokens-limit'], headers['anthropic-ratelimit-input-tokens-remaining'], headers['anthropic-ratelimit-input-tokens-reset']),
+        parseRateLimitBucket('output_tokens', headers['anthropic-ratelimit-output-tokens-limit'], headers['anthropic-ratelimit-output-tokens-remaining'], headers['anthropic-ratelimit-output-tokens-reset'])
+    ].filter((bucket) => bucket !== undefined);
+    if (buckets.length === 0)
+        return undefined;
+    return buckets.find((bucket) => bucket.remaining === 0) ?? buckets[0];
+}
+function parseRateLimitBucket(scope, limitHeader, remainingHeader, resetHeader) {
+    const limit = parsePositiveNumber(limitHeader);
+    const remaining = parsePositiveNumber(remainingHeader);
+    const resetAt = parseResetAt(resetHeader);
+    if (limit === undefined && remaining === undefined && resetAt === undefined)
+        return undefined;
+    return {
+        scope,
+        ...(limit !== undefined ? { limit } : {}),
+        ...(remaining !== undefined ? { remaining } : {}),
+        ...(resetAt ? { resetAt } : {})
+    };
+}
+function parsePositiveNumber(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+function parseResetAt(value) {
+    if (!value)
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : undefined;
+}
+/**
+ * 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';
+async function sleep(delayMs, signal) {
+    if (delayMs <= 0)
+        return;
+    if (signal.aborted)
+        throw new OperationCancelledError('Model retry was cancelled.', { scope: 'model' }, signal.reason);
+    await new Promise((resolve, reject) => {
+        let timeout;
+        const cleanup = () => {
+            if (timeout)
+                clearTimeout(timeout);
+            signal.removeEventListener('abort', onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new OperationCancelledError('Model retry was cancelled.', { scope: 'model' }, signal.reason));
+        };
+        timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, delayMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/ports/capabilities.d.ts

@@ -31,8 +31,12 @@ export type AdapterCapability =
  | 'runtime.workspace_checkpoint'
 /** Runtime exposes checkpoint retention and expiry metadata. */
  | 'runtime.checkpoint_retention'
-/** Workspace store persists state beyond process exit. */
+/** Runtime checkpoints, leases, and terminal state survive process exit. */
+ | 'runtime.persistent'
+/** Workspace store implements durable lifecycle and opaque checkpoint refs. */
  | 'workspace_store.durable'
+/** Workspace store persists state beyond process exit. */
+ | 'workspace_store.persistent'
 /** Workspace store can produce stable checkpoints. */
  | 'workspace_store.checkpoint'
 /** Workspace store can resume committed checkpoints. */
@@ -49,6 +53,16 @@ export type AdapterCapability =
  | 'workspace_store.quota'
 /** Workspace store encrypts checkpoint, snapshot, file, and metadata storage. */
  | 'workspace_store.encrypted_storage'
+/** Context checkpoint store can write checkpoints. */
+ | 'context_checkpoint.write'
+/** Context checkpoint store can read checkpoints. */
+ | 'context_checkpoint.read'
+/** Context checkpoint store can list checkpoints. */
+ | 'context_checkpoint.list'
+/** Context checkpoint store can delete checkpoints. */
+ | 'context_checkpoint.delete'
+/** Context checkpoint store survives adapter close/reopen. */
+ | 'context_checkpoint.persistent'
 /** Adapter can record feedback. */
  | 'feedback.record'
 /** Memory adapter supports key/value reads and writes. */
@@ -79,7 +93,7 @@ export interface AdapterCapabilities {
 }
 /** Adapter descriptor surfaced through `harness.inspect()`. */
 export interface AdapterInspection {
-    readonly kind: 'state' | 'sandbox' | 'runtime' | 'workspace_store' | 'feedback' | 'model' | 'memory';
+    readonly kind: 'state' | 'sandbox' | 'runtime' | 'workspace_store' | 'context_checkpoint' | 'feedback' | 'model' | 'memory';
     readonly id: string;
     readonly capabilities: readonly AdapterCapability[];
     readonly metadata?: Record<string, unknown>;

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

@@ -0,0 +1,63 @@
+import type { JsonValue } from '../models/json.js';
+import type { AdapterCapabilities, AdapterCapability } from './capabilities.js';
+import type { HarnessAdapterContext } from './harness-context.js';
+/** Typed long-horizon record written explicitly by workflow or agent code. */
+export interface ContextCheckpoint {
+    /** Stable run id this checkpoint belongs to. */
+    runId: string;
+    /** Stable session id this checkpoint belongs to. */
+    sessionId: string;
+    /** Workflow id when written from a workflow context. */
+    workflowId?: string;
+    /** Agent id when written from an agent context. */
+    agentId?: string;
+    /** Monotonic sequence selected by caller or policy. */
+    sequence: number;
+    /** Checkpoint purpose. */
+    kind: 'summary' | 'handoff' | 'goal_state';
+    /** JSON payload. Never emitted in harness telemetry. */
+    payload: JsonValue;
+    /** UTF-8 JSON payload size. */
+    payloadSizeBytes: number;
+    /** ISO timestamp. */
+    createdAt: string;
+    /** Privacy-safe operational metadata only. */
+    metadata?: Record<string, JsonValue>;
+}
+/** Stable reference to one context checkpoint. */
+export interface ContextCheckpointRef {
+    runId: string;
+    sessionId: string;
+    sequence: number;
+    kind: ContextCheckpoint['kind'];
+}
+/** Query accepted by context checkpoint stores. */
+export interface ContextCheckpointQuery {
+    runId?: string;
+    sessionId?: string;
+    workflowId?: string;
+    agentId?: string;
+    kind?: ContextCheckpoint['kind'];
+    limit?: number;
+    signal?: AbortSignal;
+}
+/** Data-only descriptor for a context checkpoint store. */
+export interface ContextCheckpointStoreInfo {
+    id: string;
+    packageName: string;
+    capabilities: readonly AdapterCapability[];
+}
+/** Adapter port for explicit context checkpoint persistence. */
+export interface ContextCheckpointStore extends AdapterCapabilities {
+    readonly info: ContextCheckpointStoreInfo;
+    configureHarnessContext?(context: HarnessAdapterContext): void;
+    write(checkpoint: ContextCheckpoint, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    list(query: ContextCheckpointQuery): Promise<readonly ContextCheckpoint[]>;
+    read(ref: ContextCheckpointRef): Promise<ContextCheckpoint | undefined>;
+    delete(ref: ContextCheckpointRef): Promise<void>;
+    close?(): Promise<void>;
+}
+/** Validates the context checkpoint adapter descriptor at harness build time. */
+export declare function validateContextCheckpointStore(adapter: ContextCheckpointStore): void;