@purista/harness 1.2.6 → 1.5.1

package/dist/ports/context-checkpoints.js

@@ -0,0 +1,33 @@
+import { HarnessConfigError } from '../errors/catalog.js';
+const adapterIdPattern = /^[a-z][a-z0-9_.-]{1,63}$/;
+/** Validates the context checkpoint adapter descriptor at harness build time. */
+export function validateContextCheckpointStore(adapter) {
+    if (!adapterIdPattern.test(adapter.info.id)) {
+        throw new HarnessConfigError('Context checkpoint store id is invalid.', {
+            reason: 'invalid_context_checkpoint_store',
+            path: 'checkpoints.info.id',
+            id: adapter.info.id
+        });
+    }
+    if (!adapter.info.packageName.trim()) {
+        throw new HarnessConfigError('Context checkpoint store packageName is required.', {
+            reason: 'invalid_context_checkpoint_store',
+            path: 'checkpoints.info.packageName',
+            id: adapter.info.id
+        });
+    }
+    if (!adapter.info.capabilities.includes('context_checkpoint.write')) {
+        throw new HarnessConfigError('Context checkpoint store must support context_checkpoint.write.', {
+            reason: 'invalid_context_checkpoint_store',
+            path: 'checkpoints.info.capabilities',
+            id: adapter.info.id
+        });
+    }
+    if (adapter.info.capabilities.some((capability) => !adapter.capabilities.includes(capability))) {
+        throw new HarnessConfigError('Context checkpoint store capabilities must include info.capabilities.', {
+            reason: 'invalid_context_checkpoint_store',
+            path: 'checkpoints.capabilities',
+            id: adapter.info.id
+        });
+    }
+}

package/dist/ports/index.d.ts

@@ -6,3 +6,4 @@ export * from './capabilities.js';
 export * from './feedback.js';
 export * from './memory.js';
 export * from './workspace.js';
+export * from './context-checkpoints.js';

package/dist/ports/index.js

@@ -6,3 +6,4 @@ export * from './capabilities.js';
 export * from './feedback.js';
 export * from './memory.js';
 export * from './workspace.js';
+export * from './context-checkpoints.js';

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

@@ -23,6 +23,80 @@ export type ModelCapability =
  | 'embeddings'
 /** Document reranking. */
  | 'rerank';
+/** Provider-neutral retry setting used by model aliases and per-call overrides. */
+export type ModelRetrySetting = boolean | ModelRetryPolicy;
+/** Transient failure classes that can be retried by the harness. */
+export interface ModelRetryOnPolicy {
+    /** Retry transport-level/network failures. Default: `true`. */
+    network?: boolean;
+    /** Retry model call timeouts. Default: `true`. */
+    timeout?: boolean;
+    /** Retry HTTP 429/rate-limit failures. Default: `true`. */
+    rateLimit?: boolean;
+    /** Retry HTTP 5xx/provider-unavailable failures. Default: `true`. */
+    serverError?: boolean;
+}
+/**
+ * Provider-neutral retry policy.
+ *
+ * The harness actively retries only inside `maxActiveElapsedMs` and
+ * `maxActiveDelayMs`. Longer provider retry instructions fail fast with
+ * `retryKind: 'none'` by default; `longRetry: 'defer'` classifies them as
+ * deferred retry errors carrying the provider-supplied `retryAfterMs`.
+ */
+export interface ModelRetryPolicy {
+    /** Total active attempts including the first call. Default: `3`. */
+    maxAttempts?: number;
+    /** Maximum wall-clock time spent in active retries. Default: `60_000`. */
+    maxActiveElapsedMs?: number;
+    /** Maximum single active sleep. Default: `20_000`. */
+    maxActiveDelayMs?: number;
+    /** Optional cap for deferred retry classification with `longRetry: 'defer'`. Default: unlimited. */
+    maxDeferredDelayMs?: number;
+    /** Honor provider Retry-After/reset headers when present. Default: `true`. */
+    respectRetryAfter?: boolean;
+    /** Base delay for exponential jitter when no provider delay exists. Default: `500`. */
+    minDelayMs?: number;
+    /** Maximum computed backoff delay. Default: `8_000`. */
+    maxDelayMs?: number;
+    /** Retryable failure classes. Omitted fields default to `true`. */
+    retryOn?: ModelRetryOnPolicy;
+    /**
+     * Handling for provider-instructed delays beyond `maxActiveDelayMs`:
+     * `'error'` fails immediately with `retryKind: 'none'`; `'defer'` fails with
+     * `retryKind: 'deferred'` plus the provider-supplied `retryAfterMs` so a
+     * queue/scheduler can retry later. Default: `'error'`.
+     */
+    longRetry?: 'error' | 'defer';
+}
+/** Normalized retry classification for provider failures. */
+export type ModelRetryKind = 'none' | 'active' | 'deferred';
+/** Structured provider outcome metadata preserved across adapters. */
+export interface ModelOutcome {
+    /** Normalized finish reason. */
+    finishReason: FinishReason;
+    /** Raw provider finish/stop/status reason when available. */
+    providerFinishReason?: string;
+    /** Raw provider status when it carries outcome semantics. */
+    providerStatus?: string;
+    /** Whether the outcome is eligible for retry under policy. */
+    retryable?: boolean;
+    /** Active/deferred retry classification when relevant. */
+    retryKind?: ModelRetryKind;
+    /** Provider-suggested or computed retry delay. */
+    retryAfterMs?: number;
+    /** Parsed provider rate-limit metadata. */
+    rateLimit?: ModelRateLimitInfo;
+    /** Extra provider-specific structured outcome details. */
+    details?: Record<string, JsonValue>;
+}
+/** Parsed, provider-neutral rate-limit metadata. */
+export interface ModelRateLimitInfo {
+    scope?: 'requests' | 'input_tokens' | 'output_tokens' | 'tokens' | 'unknown';
+    limit?: number;
+    remaining?: number;
+    resetAt?: string;
+}
 /** Default generation parameters applied per alias. */
 export interface ModelDefaults {
     temperature?: number;
@@ -31,6 +105,8 @@ export interface ModelDefaults {
     stopSequences?: string[];
     /** Whether providers should allow the model to emit multiple independent tool calls in one turn. */
     parallelToolCalls?: boolean;
+    /** Alias-level retry behavior inherited by model calls. Default: `true`. */
+    retry?: ModelRetrySetting;
     providerOptions?: Record<string, unknown>;
 }
 /** Per-call generation overrides. */
@@ -41,6 +117,8 @@ export interface ModelCallOptions {
     stopSequences?: string[];
     /** Overrides whether providers should allow multiple tool calls in one model turn. */
     parallelToolCalls?: boolean;
+    /** Per-call retry override. Default: alias retry setting, then `true`. */
+    retry?: ModelRetrySetting;
     providerOptions?: Record<string, unknown>;
 }
 /** Tool call envelope emitted by model adapters. */
@@ -157,10 +235,20 @@ export type FinishReason =
 'stop'
 /** Token budget reached. */
  | 'length'
+/** Context window reached before a valid answer could be produced. */
+ | 'context_limit'
 /** Model requested tool calls. */
  | 'tool_calls'
 /** Provider content filter interrupted generation. */
  | 'content_filter'
+/** Provider/model refused the requested output. */
+ | 'refusal'
+/** Provider asked the caller to resume/continue later. */
+ | 'pause'
+/** Provider produced malformed output or malformed tool use. */
+ | 'malformed'
+/** Cooperative cancellation interrupted generation. */
+ | 'cancelled'
 /** Provider or adapter error fallback. */
  | 'error';
 /** Tool declaration exposed to model adapters. */
@@ -180,6 +268,7 @@ export interface TextResponse {
     providerItems?: ProviderItems;
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
     raw?: unknown;
 }
 /** Stream chunk from text-stream generation. */
@@ -193,6 +282,7 @@ export type TextStreamChunk = {
     kind: 'finish';
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
     providerItems?: ProviderItems;
 };
 /** Request for object/object-stream model methods. */
@@ -208,6 +298,7 @@ export interface ObjectResponse<T extends JsonValue = JsonValue> {
     providerItems?: ProviderItems;
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
     raw?: unknown;
 }
 /** Stream chunk from structured object streaming. */
@@ -226,6 +317,7 @@ export type ObjectStreamChunk<T extends JsonValue = JsonValue> = {
     object: T;
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
     providerItems?: ProviderItems;
 };
 /** Request for embedding generation. */
@@ -296,5 +388,7 @@ export interface ModelAlias {
     model: string;
     capabilities: readonly ModelCapability[];
     defaults?: ModelDefaults;
+    /** Alias-level retry behavior. Default: `true`. */
+    retry?: ModelRetrySetting;
     providerOptions?: Record<string, unknown>;
 }

package/dist/runtime/durable.d.ts

@@ -121,6 +121,17 @@ export declare class DurableRunLeaseError extends Error {
 }
 /** Returns true when a durable run status is terminal. */
 export declare function isTerminalRunStatus(status: DurableRunStatus): status is DurableTerminalRunStatus;
+/**
+ * Returns true when a durable run status blocks resume. A `failed` run is
+ * terminal for reporting but stays resumable by a retry with the same run id
+ * (spec 22 §3); only `succeeded` and `cancelled` reject `startRun`.
+ */
+export declare function isResumeBlockingRunStatus(status: DurableRunStatus): boolean;
+/** Internal in-process FIFO mutex shared by durable runtime implementations. */
+export declare class AsyncMutex {
+    private current;
+    lock<T>(fn: () => Promise<T>): Promise<T>;
+}
 /**
  * Creates a self-contained in-memory durable runtime for tests and prototypes.
  *

package/dist/runtime/durable.js

@@ -16,7 +16,16 @@ export class DurableRunLeaseError extends Error {
 export function isTerminalRunStatus(status) {
     return status === 'succeeded' || status === 'failed' || status === 'cancelled';
 }
-class AsyncMutex {
+/**
+ * Returns true when a durable run status blocks resume. A `failed` run is
+ * terminal for reporting but stays resumable by a retry with the same run id
+ * (spec 22 §3); only `succeeded` and `cancelled` reject `startRun`.
+ */
+export function isResumeBlockingRunStatus(status) {
+    return status === 'succeeded' || status === 'cancelled';
+}
+/** Internal in-process FIFO mutex shared by durable runtime implementations. */
+export class AsyncMutex {
     current = Promise.resolve();
     async lock(fn) {
         const prev = this.current;
@@ -54,7 +63,9 @@ class InMemoryDurableRuntime {
     async startRun(record) {
         return this.withSessionLock(record.sessionId, async () => {
             const current = this.runs.get(record.runId);
-            if (current && isTerminalRunStatus(current.status)) {
+            // Only succeeded/cancelled block resume; a failed run is recorded
+            // terminal but stays resumable for a retry with the same run id.
+            if (current && isResumeBlockingRunStatus(current.status)) {
                 throw new DurableTerminalRunError(record.runId, current.status);
             }
             this.assertNoConflictingLease(record);
@@ -66,6 +77,8 @@ class InMemoryDurableRuntime {
             };
             if (current) {
                 state.attempt += 1;
+                state.status = 'running';
+                delete state.finished;
             }
             this.runs.set(record.runId, state);
             const lease = {

package/dist/runtime/sessionDurable.js

@@ -30,28 +30,47 @@ export async function beginDurableWorkflow(args) {
     });
     let handle;
     if (workspaceStore) {
-        const priorReplay = lease.checkpoint?.replay;
-        if (lease.resumed && priorReplay?.workspaceRef) {
-            handle = await workspaceStore.resumeWorkspace({
-                workspaceRef: priorReplay.workspaceRef,
-                ...(priorReplay.checkpointRef ? { checkpointRef: priorReplay.checkpointRef } : {}),
-                runId: lease.runId,
-                sessionId,
-                attempt: lease.attempt,
-                idempotencyKey: `${lease.runId}:${lease.attempt}:resume`,
-                signal
-            });
+        try {
+            const priorReplay = lease.checkpoint?.replay;
+            if (lease.resumed && priorReplay?.workspaceRef) {
+                handle = await workspaceStore.resumeWorkspace({
+                    workspaceRef: priorReplay.workspaceRef,
+                    ...(priorReplay.checkpointRef ? { checkpointRef: priorReplay.checkpointRef } : {}),
+                    runId: lease.runId,
+                    sessionId,
+                    attempt: lease.attempt,
+                    idempotencyKey: `${lease.runId}:${lease.attempt}:resume`,
+                    signal
+                });
+            }
+            else {
+                handle = await workspaceStore.startWorkspace({
+                    runId: lease.runId,
+                    sessionId,
+                    workflowId,
+                    workerId,
+                    attempt: lease.attempt,
+                    idempotencyKey: `${lease.runId}:start`,
+                    signal
+                });
+            }
         }
-        else {
-            handle = await workspaceStore.startWorkspace({
-                runId: lease.runId,
-                sessionId,
-                workflowId,
-                workerId,
-                attempt: lease.attempt,
-                idempotencyKey: `${lease.runId}:start`,
-                signal
-            });
+        catch (workspaceError) {
+            // The caller never receives the binding when the workspace phase fails,
+            // so release the acquired lease here or it stays locked for the TTL.
+            try {
+                await lease.release();
+            }
+            catch (releaseError) {
+                logger.warn('Failed to release durable lease after workspace failure.', {
+                    harness: harnessName,
+                    session_id: sessionId,
+                    run_id: lease.runId,
+                    workflow_id: workflowId,
+                    error: serializeError(releaseError)
+                });
+            }
+            throw workspaceError;
         }
     }
     const activeHandle = handle;
@@ -86,6 +105,12 @@ export async function beginDurableWorkflow(args) {
     const ctx = createDurableWorkflowContext(runtime, lease, onStepCommit ? { onStepCommit } : {});
     const autoCleanup = workspaceStore?.info.policy.retention?.cleanupMode === 'adapter_automatic';
     let settled = false;
+    // Stores that bind run sandboxes to active workspaces (localDirectoryWorkspaceStore)
+    // expose an unbind hook so the binding never outlives the durable run.
+    const releaseRunBinding = () => {
+        const candidate = workspaceStore;
+        candidate?.releaseRunBinding?.(lease.runId, sessionId);
+    };
     return {
         runId: lease.runId,
         attempt: lease.attempt,
@@ -116,6 +141,7 @@ export async function beginDurableWorkflow(args) {
             }
         },
         async dispose() {
+            releaseRunBinding();
             if (settled)
                 return;
             try {

package/dist/runtime/steps.d.ts

@@ -18,6 +18,26 @@ export interface DurableWorkflowContextOptions {
      */
     readonly onStepCommit?: (commit: DurableStepCommit) => Promise<DurableReplayCheckpoint | undefined>;
 }
+/** Retry policy for a single explicit workflow step. */
+export type DurableStepRetrySetting = boolean | DurableStepRetryPolicy;
+/** Provider-neutral retry policy for `ctx.step(...)` boundaries. */
+export interface DurableStepRetryPolicy {
+    /** Total attempts including the first call. Default: `3`. */
+    readonly maxAttempts?: number;
+    /** Base delay before retrying in milliseconds. Default: `100`. */
+    readonly minDelayMs?: number;
+    /** Maximum delay before retrying in milliseconds. Default: `1_000`. */
+    readonly maxDelayMs?: number;
+    /** Delay strategy. Default: `exponential`. */
+    readonly backoff?: 'fixed' | 'exponential';
+    /** Optional predicate to suppress retries for non-transient failures. */
+    readonly shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+}
+/** Per-call options for an explicit workflow step. */
+export interface DurableStepOptions {
+    /** Retry failed step functions before a checkpoint is committed. Default: no retry. */
+    readonly retry?: DurableStepRetrySetting;
+}
 /** Durable workflow context that exposes explicit checkpoint boundaries. */
 export interface DurableWorkflowContext {
     /** Current durable run lease. */
@@ -30,7 +50,7 @@ export interface DurableWorkflowContext {
      * const prepared = await ctx.step('prepare-inputs', async () => ({ ok: true }))
      * ```
      */
-    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>): Promise<T>;
+    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>, options?: DurableStepOptions): Promise<T>;
 }
 /** Error thrown when a durable step id is invalid or duplicated. */
 export declare class DurableStepError extends Error {
@@ -38,3 +58,4 @@ export declare class DurableStepError extends Error {
 }
 /** Creates a durable workflow context bound to an acquired runtime lease. */
 export declare function createDurableWorkflowContext(runtime: DurableRuntime, lease: DurableRunLease, options?: DurableWorkflowContextOptions): DurableWorkflowContext;
+export declare function runStepWithRetry<T>(fn: () => Promise<T>, retry: DurableStepRetrySetting | undefined): Promise<T>;

package/dist/runtime/steps.js

@@ -18,7 +18,7 @@ export function createDurableWorkflowContext(runtime, lease, options = {}) {
     let sequence = (lease.checkpoints ?? []).reduce((max, checkpoint) => Math.max(max, checkpoint.sequence), 0);
     return {
         lease,
-        async step(stepId, fn) {
+        async step(stepId, fn, stepOptions = {}) {
             validateStepId(stepId);
             if (completed.has(stepId)) {
                 throw new DurableStepError(`Duplicate durable step id "${stepId}".`);
@@ -29,7 +29,7 @@ export function createDurableWorkflowContext(runtime, lease, options = {}) {
             if (replay.has(stepId)) {
                 return replay.get(stepId);
             }
-            const output = await fn();
+            const output = await runStepWithRetry(fn, stepOptions.retry);
             assertJsonSerializable(output, stepId);
             sequence += 1;
             // Workspace state is written before the runtime checkpoint (spec 21 §10),
@@ -54,6 +54,57 @@ export function createDurableWorkflowContext(runtime, lease, options = {}) {
         }
     };
 }
+export async function runStepWithRetry(fn, retry) {
+    const policy = normalizeRetryPolicy(retry);
+    let attempt = 0;
+    let lastError;
+    while (attempt < policy.maxAttempts) {
+        attempt += 1;
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= policy.maxAttempts)
+                break;
+            if (policy.shouldRetry && !await policy.shouldRetry(error, attempt))
+                break;
+            await sleep(retryDelayMs(policy, attempt));
+        }
+    }
+    throw lastError;
+}
+function normalizeRetryPolicy(retry) {
+    if (!retry) {
+        return { maxAttempts: 1, minDelayMs: 0, maxDelayMs: 0, backoff: 'fixed' };
+    }
+    if (retry === true) {
+        return { maxAttempts: 3, minDelayMs: 100, maxDelayMs: 1_000, backoff: 'exponential' };
+    }
+    return {
+        maxAttempts: clampPositiveInteger(retry.maxAttempts ?? 3),
+        minDelayMs: Math.max(0, retry.minDelayMs ?? 100),
+        maxDelayMs: Math.max(0, retry.maxDelayMs ?? 1_000),
+        backoff: retry.backoff ?? 'exponential',
+        ...(retry.shouldRetry ? { shouldRetry: retry.shouldRetry } : {})
+    };
+}
+function clampPositiveInteger(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 1;
+}
+function retryDelayMs(policy, attempt) {
+    if (policy.maxDelayMs === 0)
+        return 0;
+    const base = policy.backoff === 'fixed'
+        ? policy.minDelayMs
+        : policy.minDelayMs * 2 ** Math.max(0, attempt - 1);
+    return Math.min(policy.maxDelayMs, base);
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function validateStepId(stepId) {
     if (!STEP_ID_PATTERN.test(stepId)) {
         throw new DurableStepError(`Invalid durable step id "${stepId}".`);

package/dist/sessions/index.d.ts

@@ -3,6 +3,7 @@ import type { RunEvent, Harness, HarnessDefaults, BuilderState, TelemetryOptions
 import type { MemoryAdapter } from '../ports/memory.js';
 import type { DurableRuntimeAdapter, HarnessInspection } from '../ports/capabilities.js';
 import type { DurableWorkspaceStore } from '../ports/workspace.js';
+import type { ContextCheckpointStore } from '../ports/context-checkpoints.js';
 import type { Sandbox } from '../sandbox/index.js';
 import type { StateStore } from '../ports/state.js';
 import { type TelemetryShim } from '../telemetry/index.js';
@@ -16,6 +17,7 @@ type HarnessDefinition<S extends BuilderState> = {
     memory: MemoryAdapter;
     runtime?: DurableRuntimeAdapter;
     workspaceStore?: DurableWorkspaceStore;
+    checkpoints?: ContextCheckpointStore;
     defaults: HarnessDefaults;
     models: NonNullable<S['models']>;
     tools: NonNullable<S['tools']>;
@@ -27,12 +29,21 @@ type HarnessDefinition<S extends BuilderState> = {
 /**
  * Relay run events from an in-process run to a stream consumer.
  *
- * The unread events live in a bounded queue: consumed events are removed (no
- * growing cursor over a shared array), and on overflow the oldest non-terminal
- * unread event is dropped and counted, so a slow consumer never silently skips
- * an unread event. Delivery is promise-notified rather than time-polled, so
- * there is no fixed per-event latency or periodic timer.
+ * The unread events live in a bounded queue (cap: STREAM_MAX_BUFFERED_EVENTS):
+ * consumed events are removed (no growing cursor over a shared array), and on
+ * overflow the oldest droppable unread event is dropped and counted, so a slow
+ * consumer never silently skips an event without an accompanying
+ * `stream.overflow` notice. Only `run.finished` is undroppable; all other
+ * event types — including `agent.finished` — may be evicted under pressure.
+ * If no droppable event exists when the queue is full, the incoming event is
+ * discarded (counted) rather than growing the queue past the cap. Delivery is
+ * promise-notified rather than time-polled, so there is no fixed per-event
+ * latency or periodic timer.
+ *
+ * Abandoning the stream (`break` / `iterator.return()`) only detaches that
+ * consumer. It does not abort `relaySignal`; callers must pass `opts.signal`
+ * when they intend to cancel the underlying run.
  */
-export declare function relayRunEvents(run: (onEvent: (event: RunEvent) => Promise<void>) => Promise<unknown>): AsyncIterable<RunEvent>;
+export declare function relayRunEvents(run: (onEvent: (event: RunEvent) => Promise<void>, relaySignal: AbortSignal) => Promise<unknown>): AsyncIterable<RunEvent>;
 export declare function createSessionHarness<S extends BuilderState>(definition: HarnessDefinition<S>): Harness<S>;
 export {};