@purista/harness 1.2.1 → 1.2.3

package/dist/runtime/sessionDurable.js

@@ -0,0 +1,135 @@
+import { serializeError } from '../errors/index.js';
+import { createDurableWorkflowContext } from './steps.js';
+/** Run-id format accepted for durable invocations. */
+export const DURABLE_RUN_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,200}$/;
+/** Narrows a configured runtime adapter to an executable durable runtime. */
+export function isExecutableDurableRuntime(runtime) {
+    if (!runtime || typeof runtime !== 'object')
+        return false;
+    const candidate = runtime;
+    return typeof candidate.startRun === 'function'
+        && typeof candidate.commitCheckpoint === 'function'
+        && typeof candidate.finishRun === 'function'
+        && typeof candidate.withSessionLock === 'function';
+}
+/**
+ * Acquires a durable runtime lease for a workflow run and, when a workspace
+ * store is configured, starts or resumes the durable workspace and links each
+ * new step checkpoint to a workspace checkpoint (spec 21 §16.1).
+ */
+export async function beginDurableWorkflow(args) {
+    const { runtime, workspaceStore, durable, sessionId, workflowId, input, signal, logger, harnessName } = args;
+    const workerId = durable.workerId ?? args.defaultWorkerId;
+    const lease = await runtime.startRun({
+        runId: durable.runId,
+        sessionId,
+        workerId,
+        stepId: durable.stepId ?? workflowId,
+        input,
+        ...(durable.attempt !== undefined ? { attempt: durable.attempt } : {})
+    });
+    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
+            });
+        }
+        else {
+            handle = await workspaceStore.startWorkspace({
+                runId: lease.runId,
+                sessionId,
+                workflowId,
+                workerId,
+                attempt: lease.attempt,
+                idempotencyKey: `${lease.runId}:start`,
+                signal
+            });
+        }
+    }
+    const activeHandle = handle;
+    const onStepCommit = workspaceStore && activeHandle
+        ? async (commit) => {
+            const checkpoint = await workspaceStore.pauseWorkspace({
+                handle: activeHandle,
+                stepId: commit.stepId,
+                sequence: commit.sequence,
+                attempt: commit.attempt,
+                reason: 'step_completed',
+                idempotencyKey: `${lease.runId}:${commit.attempt}:pause:${commit.stepId}`,
+                signal
+            });
+            return {
+                runId: lease.runId,
+                sessionId,
+                workerId,
+                leaseId: lease.leaseId,
+                stepId: commit.stepId,
+                sequence: commit.sequence,
+                attempt: commit.attempt,
+                checkpointRef: checkpoint.checkpointRef,
+                workspaceRef: checkpoint.workspaceRef,
+                ...(checkpoint.snapshotRef ? { snapshotRef: checkpoint.snapshotRef } : {}),
+                schemaVersion: 1,
+                committedAt: checkpoint.committedAt,
+                ...(checkpoint.expiresAt ? { expiresAt: checkpoint.expiresAt } : {})
+            };
+        }
+        : undefined;
+    const ctx = createDurableWorkflowContext(runtime, lease, onStepCommit ? { onStepCommit } : {});
+    const autoCleanup = workspaceStore?.info.policy.retention?.cleanupMode === 'adapter_automatic';
+    let settled = false;
+    return {
+        runId: lease.runId,
+        attempt: lease.attempt,
+        resumed: lease.resumed,
+        step: ctx.step,
+        async finishSuccess(output) {
+            await runtime.finishRun(lease.runId, { status: 'succeeded', output });
+            settled = true;
+            if (workspaceStore && activeHandle && autoCleanup) {
+                await workspaceStore.cleanupWorkspace({
+                    workspaceRef: activeHandle.workspaceRef,
+                    reason: 'terminal_success',
+                    idempotencyKey: `${lease.runId}:cleanup`
+                });
+            }
+        },
+        async finishCancelled(error) {
+            await runtime.finishRun(lease.runId, { status: 'cancelled', error: serializeError(error) });
+            settled = true;
+            if (workspaceStore && activeHandle) {
+                await workspaceStore.abortWorkspace({
+                    workspaceRef: activeHandle.workspaceRef,
+                    runId: lease.runId,
+                    sessionId,
+                    reason: 'cancelled',
+                    idempotencyKey: `${lease.runId}:abort`
+                });
+            }
+        },
+        async dispose() {
+            if (settled)
+                return;
+            try {
+                await lease.release();
+            }
+            catch (error) {
+                logger.warn('Failed to release durable lease for retry.', {
+                    harness: harnessName,
+                    session_id: sessionId,
+                    run_id: lease.runId,
+                    workflow_id: workflowId,
+                    error: serializeError(error)
+                });
+            }
+        }
+    };
+}

package/dist/runtime/steps.d.ts

@@ -1,5 +1,23 @@
 import type { JsonValue } from '../models/json.js';
+import type { DurableReplayCheckpoint } from '../ports/workspace.js';
 import type { DurableRunLease, DurableRuntime } from './durable.js';
+/** Metadata describing a new step checkpoint about to be committed. */
+export interface DurableStepCommit {
+    readonly stepId: string;
+    readonly sequence: number;
+    readonly attempt: number;
+    readonly output: JsonValue;
+}
+/** Optional hooks for binding durable steps to a durable workspace store. */
+export interface DurableWorkflowContextOptions {
+    /**
+     * Invoked before each NEW step checkpoint is committed (never on replay). The
+     * returned record is stored on the runtime checkpoint's `replay` field so a
+     * later resume can locate the durable workspace checkpoint. This enforces the
+     * "workspace state first, runtime checkpoint second" ordering (spec 21 §10).
+     */
+    readonly onStepCommit?: (commit: DurableStepCommit) => Promise<DurableReplayCheckpoint | undefined>;
+}
 /** Durable workflow context that exposes explicit checkpoint boundaries. */
 export interface DurableWorkflowContext {
     /** Current durable run lease. */
@@ -19,4 +37,4 @@ export declare class DurableStepError extends Error {
     constructor(message: string);
 }
 /** Creates a durable workflow context bound to an acquired runtime lease. */
-export declare function createDurableWorkflowContext(runtime: DurableRuntime, lease: DurableRunLease): DurableWorkflowContext;
+export declare function createDurableWorkflowContext(runtime: DurableRuntime, lease: DurableRunLease, options?: DurableWorkflowContextOptions): DurableWorkflowContext;

package/dist/runtime/steps.js

@@ -7,8 +7,15 @@ export class DurableStepError extends Error {
     }
 }
 /** Creates a durable workflow context bound to an acquired runtime lease. */
-export function createDurableWorkflowContext(runtime, lease) {
+export function createDurableWorkflowContext(runtime, lease, options = {}) {
     const completed = new Set();
+    // Committed step outputs from prior attempts, keyed by stepId. On resume,
+    // these steps replay their stored output instead of re-running side effects.
+    const replay = new Map();
+    for (const checkpoint of lease.checkpoints ?? []) {
+        replay.set(checkpoint.stepId, checkpoint.output);
+    }
+    let sequence = (lease.checkpoints ?? []).reduce((max, checkpoint) => Math.max(max, checkpoint.sequence), 0);
     return {
         lease,
         async step(stepId, fn) {
@@ -17,9 +24,19 @@ export function createDurableWorkflowContext(runtime, lease) {
                 throw new DurableStepError(`Duplicate durable step id "${stepId}".`);
             }
             completed.add(stepId);
+            // Durable replay: a step committed on a prior attempt returns its stored
+            // output without re-executing `fn()` or re-committing a checkpoint.
+            if (replay.has(stepId)) {
+                return replay.get(stepId);
+            }
             const output = await fn();
             assertJsonSerializable(output, stepId);
-            const sequence = (lease.checkpoint?.sequence ?? 0) + completed.size;
+            sequence += 1;
+            // Workspace state is written before the runtime checkpoint (spec 21 §10),
+            // and the returned reference is linked on the runtime checkpoint.
+            const replayCheckpoint = options.onStepCommit
+                ? await options.onStepCommit({ stepId, sequence, attempt: lease.attempt, output })
+                : undefined;
             const checkpoint = {
                 runId: lease.runId,
                 sessionId: lease.sessionId,
@@ -29,7 +46,8 @@ export function createDurableWorkflowContext(runtime, lease) {
                 input: lease.start.input,
                 attempt: lease.attempt,
                 sequence,
-                output
+                output,
+                ...(replayCheckpoint ? { replay: replayCheckpoint } : {})
             };
             await runtime.commitCheckpoint(checkpoint);
             return output;

package/dist/sandbox/index.d.ts

@@ -22,6 +22,40 @@ export interface ExecCapableSandboxSession extends SandboxSessionBase {
     readonly executor: 'available';
     exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
 }
+/** Options for spawning a long-lived process inside the sandbox. */
+export interface SpawnOptions {
+    /** Command arguments. */
+    args?: readonly string[];
+    /** Working directory inside the sandbox. */
+    cwd?: string;
+    /** Extra environment variables. */
+    env?: Record<string, string>;
+    /** Cancellation signal; aborting terminates the process. */
+    signal?: AbortSignal;
+}
+/** A long-lived process owned by a sandbox session with streaming stdio. */
+export interface SandboxProcess {
+    /** Writes a chunk to the process stdin. */
+    writeStdin(chunk: string): Promise<void>;
+    /** Decoded stdout chunks. Completes when the process exits. */
+    readonly stdout: AsyncIterable<string>;
+    /** Decoded stderr chunks. Completes when the process exits. */
+    readonly stderr: AsyncIterable<string>;
+    /** Resolves with the exit code when the process terminates. Never rejects. */
+    readonly exit: Promise<{
+        exitCode: number;
+        signal?: string;
+    }>;
+    /** Terminates the process. Idempotent. */
+    kill(signal?: 'SIGTERM' | 'SIGKILL'): Promise<void>;
+}
+/** Sandbox session that can host long-lived processes (`sandbox.spawn`). */
+export interface SpawnCapableSandboxSession extends SandboxSessionBase {
+    readonly executor: 'available';
+    spawn(command: string, opts?: SpawnOptions): Promise<SandboxProcess>;
+}
+/** Returns true when a sandbox session can spawn long-lived processes. */
+export declare function isSpawnCapableSession(session: SandboxSessionBase): session is SpawnCapableSandboxSession;
 export type SandboxSession = SandboxSessionBase & {
     exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
 };

package/dist/sandbox/index.js

@@ -2,6 +2,10 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { OperationCancelledError, OperationTimeoutError, HarnessConfigError, SandboxError, SandboxNoExecutorError } from '../errors/index.js';
 const require = createRequire(import.meta.url);
+/** Returns true when a sandbox session can spawn long-lived processes. */
+export function isSpawnCapableSession(session) {
+    return typeof session.spawn === 'function';
+}
 function now() { return new Date().toISOString(); }
 function normalizePath(input) {
     if (!input.startsWith('/'))
@@ -63,7 +67,7 @@ class MemorySandboxSession {
             const relative = root === '/' ? k.slice(1) : k.slice(root.length + 1);
             if (!opts?.recursive && relative.includes('/'))
                 continue;
-            if (opts?.glob && !new RegExp(opts.glob.replaceAll('.', '\\.').replaceAll('*', '.*')).test(k))
+            if (opts?.glob && !globToRegExp(opts.glob).test(k))
                 continue;
             out.push({ name: k.split('/').at(-1) ?? '', path: k, kind: v.kind, ...(v.kind === 'file' ? { size: v.data.byteLength } : {}) });
         }
@@ -155,11 +159,44 @@ export function bashSandbox(opts) {
         }
     };
 }
+/**
+ * Translate a glob to a fully-anchored RegExp matched against the absolute
+ * path. `*`/`**` match any characters and `?` matches a single character; all
+ * other regex metacharacters are escaped to literals so a pattern can never
+ * throw a `SyntaxError` or trigger catastrophic backtracking. Anchoring both
+ * ends fixes the previous over-match (e.g. `*.ts` no longer matches `a.tsx`).
+ */
+function globToRegExp(glob) {
+    let out = '^';
+    for (let i = 0; i < glob.length; i += 1) {
+        const char = glob[i];
+        if (char === '*') {
+            out += '.*';
+            if (glob[i + 1] === '*')
+                i += 1;
+        }
+        else if (char === '?') {
+            out += '.';
+        }
+        else if (/[.+^${}()|[\]\\]/.test(char)) {
+            out += `\\${char}`;
+        }
+        else {
+            out += char;
+        }
+    }
+    return new RegExp(`${out}$`);
+}
 export function autoDetectSandbox() {
     try {
         return bashSandbox();
     }
-    catch {
-        return inMemorySandbox();
+    catch (error) {
+        // Only fall back to the no-executor sandbox when just-bash is absent.
+        // A real configuration/init error must surface, not silently downgrade.
+        if (error instanceof HarnessConfigError && error.meta?.reason === 'just_bash_not_installed') {
+            return inMemorySandbox();
+        }
+        throw error;
     }
 }

package/dist/sessions/index.d.ts

@@ -1,7 +1,8 @@
 import type { Logger } from '../logger/index.js';
-import type { Harness, HarnessDefaults, BuilderState, TelemetryOptions } from '../harness/defineHarness.js';
+import type { RunEvent, Harness, HarnessDefaults, BuilderState, TelemetryOptions } from '../harness/defineHarness.js';
 import type { MemoryAdapter } from '../ports/memory.js';
-import type { HarnessInspection } from '../ports/capabilities.js';
+import type { DurableRuntimeAdapter, HarnessInspection } from '../ports/capabilities.js';
+import type { DurableWorkspaceStore } from '../ports/workspace.js';
 import type { Sandbox } from '../sandbox/index.js';
 import type { StateStore } from '../ports/state.js';
 import { type TelemetryShim } from '../telemetry/index.js';
@@ -13,6 +14,8 @@ type HarnessDefinition<S extends BuilderState> = {
     state: StateStore;
     sandbox: Sandbox;
     memory: MemoryAdapter;
+    runtime?: DurableRuntimeAdapter;
+    workspaceStore?: DurableWorkspaceStore;
     defaults: HarnessDefaults;
     models: NonNullable<S['models']>;
     tools: NonNullable<S['tools']>;
@@ -21,5 +24,15 @@ type HarnessDefinition<S extends BuilderState> = {
     workflows: NonNullable<S['workflows']>;
     inspection: HarnessInspection;
 };
+/**
+ * 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.
+ */
+export declare function relayRunEvents(run: (onEvent: (event: RunEvent) => Promise<void>) => Promise<unknown>): AsyncIterable<RunEvent>;
 export declare function createSessionHarness<S extends BuilderState>(definition: HarnessDefinition<S>): Harness<S>;
 export {};