@purista/harness 1.2.5 → 1.5.0

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. */
@@ -49,6 +127,17 @@ export interface ToolCallSpec {
     name: string;
     arguments: JsonValue;
 }
+/**
+ * Opaque provider wire items returned with a tool-call response and replayed
+ * verbatim on the follow-up request of the same turn (e.g. OpenAI Responses
+ * API reasoning items). Adapters only replay items tagged with their own
+ * provider id; foreign or empty items are ignored and the assistant turn is
+ * reconstructed provider-neutrally from `content`/`toolCalls`.
+ */
+export interface ProviderItems {
+    providerId: string;
+    items: JsonValue[];
+}
 /** Multimodal message content part. */
 export type ContentPart = 
 /** Plain text input content. */
@@ -119,6 +208,7 @@ export type ModelMessage = {
     role: 'assistant';
     content: string | ContentPart[];
     toolCalls?: ToolCallSpec[];
+    providerItems?: ProviderItems;
 } | {
     role: 'tool';
     toolCallId: string;
@@ -145,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. */
@@ -165,8 +265,10 @@ export interface TextRequest extends BaseRequest {
 export interface TextResponse {
     content: string;
     toolCalls?: ToolCallSpec[];
+    providerItems?: ProviderItems;
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
     raw?: unknown;
 }
 /** Stream chunk from text-stream generation. */
@@ -180,6 +282,8 @@ export type TextStreamChunk = {
     kind: 'finish';
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
+    providerItems?: ProviderItems;
 };
 /** Request for object/object-stream model methods. */
 export interface ObjectRequest<T extends JsonValue = JsonValue> extends BaseRequest {
@@ -191,8 +295,10 @@ export interface ObjectRequest<T extends JsonValue = JsonValue> extends BaseRequ
 export interface ObjectResponse<T extends JsonValue = JsonValue> {
     object: T;
     toolCalls?: ToolCallSpec[];
+    providerItems?: ProviderItems;
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
     raw?: unknown;
 }
 /** Stream chunk from structured object streaming. */
@@ -211,6 +317,8 @@ export type ObjectStreamChunk<T extends JsonValue = JsonValue> = {
     object: T;
     usage: TokenUsage;
     finishReason: FinishReason;
+    outcome?: ModelOutcome;
+    providerItems?: ProviderItems;
 };
 /** Request for embedding generation. */
 export interface EmbeddingRequest {
@@ -280,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/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()`) aborts `relaySignal`,
+ * so a run wired to it is cancelled promptly instead of blocking the consumer
+ * until the run finishes on its own.
  */
-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 {};