@purista/harness 1.0.0 → 1.2.0

package/dist/ports/workspace.d.ts

@@ -0,0 +1,177 @@
+import type { JsonValue } from '../models/json.js';
+import type { AdapterCapabilities, AdapterCapability } from './capabilities.js';
+import type { HarnessAdapterContext } from './harness-context.js';
+export type WorkspaceLifecycleState = 'active' | 'paused' | 'aborted' | 'cleanup_pending' | 'cleaned';
+export interface WorkspaceRetentionPolicy {
+    activeTtlMs?: number;
+    pausedTtlMs?: number;
+    terminalSuccessTtlMs?: number;
+    terminalFailureTtlMs?: number;
+    abortedTtlMs?: number;
+    orphanTtlMs?: number;
+    maxTtlMs?: number;
+    cleanupMode: 'adapter_automatic' | 'application_scheduled' | 'manual_only';
+}
+export interface WorkspaceEncryptionInfo {
+    encryptedAtRest: boolean;
+    keyScope: 'adapter' | 'tenant' | 'project' | 'application';
+    rotationSupported: boolean;
+    metadataEncrypted: boolean;
+}
+export interface WorkspaceQuotaPolicy {
+    maxWorkspaceBytes?: number;
+    maxWorkspaceFiles?: number;
+    maxSingleFileBytes?: number;
+    maxCheckpointPayloadBytes?: number;
+    maxSnapshotBytes?: number;
+    maxActiveWorkspaces?: number;
+    maxPausedWorkspaces?: number;
+    maxConcurrentResumes?: number;
+    maxWorkspaceAgeMs?: number;
+}
+export interface DurableWorkspacePolicy {
+    retention?: WorkspaceRetentionPolicy;
+    encryption?: WorkspaceEncryptionInfo;
+    quota?: WorkspaceQuotaPolicy;
+}
+export interface DurableWorkspaceStoreInfo {
+    id: string;
+    packageName: string;
+    capabilities: readonly AdapterCapability[];
+    policy: DurableWorkspacePolicy;
+}
+export interface WorkspaceStartOptions {
+    runId: string;
+    sessionId: string;
+    workflowId?: string;
+    agentId?: string;
+    workerId?: string;
+    attempt: number;
+    idempotencyKey: string;
+    metadata?: Record<string, JsonValue>;
+    policy?: Partial<DurableWorkspacePolicy>;
+    signal?: AbortSignal;
+}
+export interface WorkspaceHandle {
+    workspaceRef: string;
+    runId: string;
+    sessionId: string;
+    state: 'active';
+    startedAt: string;
+    attempt: number;
+    metadata?: Record<string, JsonValue>;
+}
+export interface WorkspacePauseOptions {
+    handle: WorkspaceHandle;
+    stepId: string;
+    sequence: number;
+    attempt: number;
+    checkpointPayload?: JsonValue;
+    reason: 'step_completed' | 'manual_pause' | 'timeout' | 'shutdown' | 'retry_boundary';
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}
+export interface WorkspaceCheckpoint {
+    workspaceRef: string;
+    checkpointRef: string;
+    snapshotRef?: string;
+    runId: string;
+    sessionId: string;
+    stepId: string;
+    sequence: number;
+    attempt: number;
+    committedAt: string;
+    expiresAt?: string;
+    sizeBytes?: number;
+    metadata?: Record<string, JsonValue>;
+}
+export interface WorkspaceResumeOptions {
+    workspaceRef: string;
+    checkpointRef?: string;
+    snapshotRef?: string;
+    runId: string;
+    sessionId: string;
+    attempt: number;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}
+export interface WorkspaceAbortOptions {
+    workspaceRef: string;
+    runId: string;
+    sessionId: string;
+    reason: 'cancelled' | 'failed' | 'superseded' | 'manual_abort';
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}
+export interface WorkspaceAbortResult {
+    workspaceRef: string;
+    state: 'aborted';
+    abortedAt: string;
+    cleanupEligibleAt?: string;
+}
+export interface WorkspaceCleanupOptions {
+    workspaceRef: string;
+    reason: 'terminal_success' | 'terminal_failure' | 'aborted' | 'expired' | 'orphan' | 'manual';
+    idempotencyKey: string;
+    signal?: AbortSignal;
+}
+export interface WorkspaceCleanupResult {
+    workspaceRef: string;
+    state: 'cleaned' | 'cleanup_pending';
+    deletedBytes?: number;
+    deletedFiles?: number;
+    completedAt?: string;
+    retryAfterMs?: number;
+    partial?: boolean;
+    remainingRefs?: readonly string[];
+}
+export interface WorkspaceInspectionOptions {
+    workspaceRef?: string;
+    checkpointRef?: string;
+    snapshotRef?: string;
+    signal?: AbortSignal;
+}
+export interface WorkspaceInspection {
+    workspaceRef: string;
+    state: WorkspaceLifecycleState;
+    checkpoints: readonly WorkspaceCheckpoint[];
+    currentCheckpointRef?: string;
+    retention?: WorkspaceRetentionPolicy;
+    quota?: WorkspaceQuotaPolicy;
+    encryption?: WorkspaceEncryptionInfo;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string;
+    cleanupEligibleAt?: string;
+    metadata?: Record<string, JsonValue>;
+}
+export interface DurableReplayCheckpoint {
+    runId: string;
+    sessionId: string;
+    workerId?: string;
+    leaseId?: string;
+    stepId: string;
+    sequence: number;
+    attempt: number;
+    checkpointRef: string;
+    workspaceRef?: string;
+    snapshotRef?: string;
+    runtimeCheckpointRef?: string;
+    schemaVersion: 1;
+    payload?: JsonValue;
+    payloadSizeBytes?: number;
+    committedAt: string;
+    expiresAt?: string;
+    metadata?: Record<string, JsonValue>;
+}
+export interface DurableWorkspaceStore extends AdapterCapabilities {
+    readonly info: DurableWorkspaceStoreInfo;
+    configureHarnessContext?(context: HarnessAdapterContext): void;
+    startWorkspace(opts: WorkspaceStartOptions): Promise<WorkspaceHandle>;
+    pauseWorkspace(opts: WorkspacePauseOptions): Promise<WorkspaceCheckpoint>;
+    resumeWorkspace(opts: WorkspaceResumeOptions): Promise<WorkspaceHandle>;
+    abortWorkspace(opts: WorkspaceAbortOptions): Promise<WorkspaceAbortResult>;
+    cleanupWorkspace(opts: WorkspaceCleanupOptions): Promise<WorkspaceCleanupResult>;
+    inspectWorkspace?(opts: WorkspaceInspectionOptions): Promise<WorkspaceInspection>;
+}
+export declare function validateDurableWorkspaceStore(adapter: DurableWorkspaceStore): void;

package/dist/ports/workspace.js

@@ -0,0 +1,32 @@
+import { HarnessConfigError } from '../errors/catalog.js';
+const adapterIdPattern = /^[a-z][a-z0-9_.-]{1,63}$/;
+export function validateDurableWorkspaceStore(adapter) {
+    if (!adapterIdPattern.test(adapter.info.id)) {
+        throw new HarnessConfigError('Workspace store id is invalid.', {
+            reason: 'invalid_workspace_store',
+            path: 'workspaceStore.info.id',
+            id: adapter.info.id
+        });
+    }
+    if (!adapter.info.packageName.trim()) {
+        throw new HarnessConfigError('Workspace store packageName is required.', {
+            reason: 'invalid_workspace_store',
+            path: 'workspaceStore.info.packageName',
+            id: adapter.info.id
+        });
+    }
+    if (!adapter.info.capabilities.includes('workspace_store.durable')) {
+        throw new HarnessConfigError('Workspace store must support workspace_store.durable.', {
+            reason: 'invalid_workspace_store',
+            path: 'workspaceStore.info.capabilities',
+            id: adapter.info.id
+        });
+    }
+    if (adapter.capabilities.length !== adapter.info.capabilities.length || adapter.capabilities.some((capability) => !adapter.info.capabilities.includes(capability))) {
+        throw new HarnessConfigError('Workspace store capabilities must match info.capabilities.', {
+            reason: 'invalid_workspace_store',
+            path: 'workspaceStore.capabilities',
+            id: adapter.info.id
+        });
+    }
+}

package/dist/runtime/durable.d.ts

@@ -1,6 +1,7 @@
 import type { AdapterCapability } from '../ports/capabilities.js';
 import type { JsonValue } from '../models/json.js';
 import type { RunStatus, SerializedError } from '../models/state.js';
+import type { DurableReplayCheckpoint } from '../ports/workspace.js';
 /** Non-terminal run status used while durable work can still be resumed. */
 export type DurableActiveRunStatus = 'running';
 /** Terminal run statuses that must never be resumed by a durable runtime. */
@@ -67,6 +68,8 @@ export interface RunCheckpoint {
     readonly sequence: number;
     /** JSON-serializable checkpoint payload. */
     readonly output?: JsonValue;
+    /** Optional durable workspace replay checkpoint linked to this runtime checkpoint. */
+    readonly replay?: DurableReplayCheckpoint;
     /** Adapter-neutral checkpoint metadata. */
     readonly metadata?: Record<string, JsonValue>;
     /** ISO timestamp for the commit. */

package/dist/runtime/durable.js

@@ -39,7 +39,8 @@ class InMemoryDurableRuntime {
         'runtime.checkpoint',
         'runtime.retry',
         'runtime.distributed_lock',
-        'runtime.resume_from_checkpoint'
+        'runtime.resume_from_checkpoint',
+        'runtime.workspace_checkpoint'
     ];
     runs = new Map();
     runLeases = new Map();

package/dist/sessions/index.d.ts

@@ -1,5 +1,6 @@
 import type { Logger } from '../logger/index.js';
 import type { Harness, HarnessDefaults, BuilderState, TelemetryOptions } from '../harness/defineHarness.js';
+import type { MemoryAdapter } from '../ports/memory.js';
 import type { HarnessInspection } from '../ports/capabilities.js';
 import type { Sandbox } from '../sandbox/index.js';
 import type { StateStore } from '../ports/state.js';
@@ -11,6 +12,7 @@ type HarnessDefinition<S extends BuilderState> = {
     telemetryShim?: TelemetryShim;
     state: StateStore;
     sandbox: Sandbox;
+    memory: MemoryAdapter;
     defaults: HarnessDefaults;
     models: NonNullable<S['models']>;
     tools: NonNullable<S['tools']>;