@purista/harness 1.0.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './durable.js';
+export * from './steps.js';

package/dist/runtime/index.js

@@ -0,0 +1,2 @@
+export * from './durable.js';
+export * from './steps.js';

package/dist/runtime/steps.d.ts

@@ -0,0 +1,22 @@
+import type { JsonValue } from '../models/json.js';
+import type { DurableRunLease, DurableRuntime } from './durable.js';
+/** Durable workflow context that exposes explicit checkpoint boundaries. */
+export interface DurableWorkflowContext {
+    /** Current durable run lease. */
+    readonly lease: DurableRunLease;
+    /**
+     * Runs a JSON-serializable durable step and commits its output as a checkpoint.
+     *
+     * @example
+     * ```ts
+     * const prepared = await ctx.step('prepare-inputs', async () => ({ ok: true }))
+     * ```
+     */
+    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>): Promise<T>;
+}
+/** Error thrown when a durable step id is invalid or duplicated. */
+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;

package/dist/runtime/steps.js

@@ -0,0 +1,51 @@
+const STEP_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,128}$/;
+/** Error thrown when a durable step id is invalid or duplicated. */
+export class DurableStepError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DurableStepError';
+    }
+}
+/** Creates a durable workflow context bound to an acquired runtime lease. */
+export function createDurableWorkflowContext(runtime, lease) {
+    const completed = new Set();
+    return {
+        lease,
+        async step(stepId, fn) {
+            validateStepId(stepId);
+            if (completed.has(stepId)) {
+                throw new DurableStepError(`Duplicate durable step id "${stepId}".`);
+            }
+            completed.add(stepId);
+            const output = await fn();
+            assertJsonSerializable(output, stepId);
+            const sequence = (lease.checkpoint?.sequence ?? 0) + completed.size;
+            const checkpoint = {
+                runId: lease.runId,
+                sessionId: lease.sessionId,
+                leaseId: lease.leaseId,
+                workerId: lease.workerId,
+                stepId,
+                input: lease.start.input,
+                attempt: lease.attempt,
+                sequence,
+                output
+            };
+            await runtime.commitCheckpoint(checkpoint);
+            return output;
+        }
+    };
+}
+function validateStepId(stepId) {
+    if (!STEP_ID_PATTERN.test(stepId)) {
+        throw new DurableStepError(`Invalid durable step id "${stepId}".`);
+    }
+}
+function assertJsonSerializable(value, stepId) {
+    try {
+        JSON.stringify(value);
+    }
+    catch (error) {
+        throw new DurableStepError(`Durable step "${stepId}" returned a non-serializable value.`);
+    }
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,111 @@
+import type { DirEntry, ExecOptions, ExecResult, FileStat } from '../harness/types.js';
+import type { HarnessAdapterContext } from '../ports/harness-context.js';
+import type { AdapterCapabilities, AdapterCapability } from '../ports/capabilities.js';
+export interface SandboxSessionBase {
+    read(path: string): Promise<Uint8Array>;
+    readText(path: string, encoding?: 'utf-8'): Promise<string>;
+    write(path: string, data: Uint8Array | string): Promise<void>;
+    remove(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    list(path: string, opts?: {
+        recursive?: boolean;
+        glob?: string;
+    }): Promise<DirEntry[]>;
+    stat(path: string): Promise<FileStat>;
+    exists(path: string): Promise<boolean>;
+    mount(files: ReadonlyMap<string, Uint8Array | string>, atPath: string): Promise<void>;
+    readonly executor: 'available' | 'unavailable';
+    close(): Promise<void>;
+}
+export interface ExecCapableSandboxSession extends SandboxSessionBase {
+    readonly executor: 'available';
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+}
+export type SandboxSession = SandboxSessionBase & {
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+};
+type HasSandboxCapability<C extends readonly AdapterCapability[], K extends AdapterCapability> = K extends C[number] ? true : false;
+export type SandboxSessionFor<C extends readonly AdapterCapability[]> = HasSandboxCapability<C, 'sandbox.exec'> extends true ? ExecCapableSandboxSession : SandboxSessionBase & {
+    readonly executor: 'unavailable';
+};
+export interface Sandbox<C extends readonly AdapterCapability[] = readonly AdapterCapability[]> extends Partial<AdapterCapabilities> {
+    readonly capabilities?: C;
+    configureHarnessContext?(context: HarnessAdapterContext): void;
+    open(opts: {
+        sessionId: string;
+        runId: string;
+        signal?: AbortSignal;
+    }): Promise<SandboxSessionFor<C>>;
+}
+/** Result produced when a sandbox adapter records a restorable checkpoint. */
+export interface SnapshotResult {
+    /** Adapter-owned id used to resume the checkpoint later. */
+    readonly snapshotId: string;
+    /** Optional adapter metadata for observability or persistence records. */
+    readonly metadata?: Record<string, unknown>;
+}
+/** Options used to open a sandbox session from a prior snapshot. */
+export interface SandboxResumeOptions {
+    /** Snapshot id previously returned by `snapshot(...)` or `hibernate(...)`. */
+    readonly snapshotId: string;
+    /** Logical harness session id for the resumed sandbox session. */
+    readonly sessionId: string;
+    /** Harness run id requesting the resumed sandbox session. */
+    readonly runId: string;
+    /** Optional cancellation signal for adapters that support abortable resume. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Optional sandbox capability for creating durable session snapshots.
+ *
+ * @example
+ * ```ts
+ * if ('snapshot' in sandbox) {
+ *   const result = await sandbox.snapshot(session)
+ * }
+ * ```
+ */
+export interface SnapshotCapableSandbox {
+    snapshot(session: SandboxSession): Promise<SnapshotResult>;
+}
+/**
+ * Optional sandbox capability for opening sessions from durable snapshots.
+ *
+ * @example
+ * ```ts
+ * if ('resume' in sandbox) {
+ *   const session = await sandbox.resume({ snapshotId, sessionId, runId })
+ * }
+ * ```
+ */
+export interface ResumeCapableSandbox {
+    resume(opts: SandboxResumeOptions): Promise<SandboxSession>;
+}
+/**
+ * Optional sandbox capability for snapshotting and releasing active compute.
+ *
+ * @example
+ * ```ts
+ * if ('hibernate' in sandbox) {
+ *   const result = await sandbox.hibernate(session)
+ * }
+ * ```
+ */
+export interface HibernateCapableSandbox {
+    hibernate(session: SandboxSession): Promise<SnapshotResult>;
+}
+export declare function inMemorySandbox(): Sandbox<readonly ['sandbox.fs']>;
+export declare function bashSandbox(opts?: {
+    network?: {
+        allow?: string[];
+        deny?: string[];
+    };
+    executionLimits?: {
+        wallClockMs?: number;
+        memoryMb?: number;
+    };
+    python?: boolean;
+}): Sandbox<readonly ['sandbox.fs', 'sandbox.exec']>;
+export declare function autoDetectSandbox(): Sandbox<any>;
+export {};

package/dist/sandbox/index.js

@@ -0,0 +1,165 @@
+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);
+function now() { return new Date().toISOString(); }
+function normalizePath(input) {
+    if (!input.startsWith('/'))
+        throw new SandboxError('Invalid path', { reason: 'invalid_path' });
+    const normalized = path.posix.normalize(input);
+    if (!normalized.startsWith('/'))
+        throw new SandboxError('Invalid path', { reason: 'invalid_path' });
+    return normalized;
+}
+class MemorySandboxSession {
+    fs = new Map();
+    executor;
+    bashExec;
+    constructor(executor, bashExec) {
+        this.executor = executor;
+        this.bashExec = bashExec;
+        this.fs.set('/', { kind: 'directory', modifiedAt: now() });
+    }
+    ensureParent(filePath) {
+        const parts = normalizePath(filePath).split('/').filter(Boolean);
+        let current = '/';
+        for (let i = 0; i < parts.length - 1; i += 1) {
+            current = current === '/' ? `/${parts[i]}` : `${current}/${parts[i]}`;
+            if (!this.fs.has(current))
+                this.fs.set(current, { kind: 'directory', modifiedAt: now() });
+        }
+    }
+    async read(filePath) {
+        const node = this.fs.get(normalizePath(filePath));
+        if (!node || node.kind !== 'file')
+            throw new SandboxError('File not found', { reason: 'fs_failed' });
+        return node.data;
+    }
+    async readText(filePath) { return new TextDecoder().decode(await this.read(filePath)); }
+    async write(filePath, data) {
+        const p = normalizePath(filePath);
+        this.ensureParent(p);
+        this.fs.set(p, { kind: 'file', data: typeof data === 'string' ? new TextEncoder().encode(data) : data, modifiedAt: now() });
+    }
+    async remove(filePath, opts) {
+        const p = normalizePath(filePath);
+        if (opts?.recursive) {
+            for (const key of [...this.fs.keys()]) {
+                if (key === p || key.startsWith(`${p}/`))
+                    this.fs.delete(key);
+            }
+            return;
+        }
+        this.fs.delete(p);
+    }
+    async list(rootPath, opts) {
+        const root = normalizePath(rootPath);
+        const out = [];
+        for (const [k, v] of this.fs.entries()) {
+            if (k === root)
+                continue;
+            if (!k.startsWith(root === '/' ? '/' : `${root}/`))
+                continue;
+            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))
+                continue;
+            out.push({ name: k.split('/').at(-1) ?? '', path: k, kind: v.kind, ...(v.kind === 'file' ? { size: v.data.byteLength } : {}) });
+        }
+        return out.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async stat(filePath) {
+        const node = this.fs.get(normalizePath(filePath));
+        if (!node)
+            throw new SandboxError('Path not found', { reason: 'fs_failed' });
+        return { kind: node.kind, size: node.kind === 'file' ? node.data.byteLength : 0, modifiedAt: node.modifiedAt };
+    }
+    async exists(filePath) { return this.fs.has(normalizePath(filePath)); }
+    async mount(files, atPath) {
+        const base = normalizePath(atPath);
+        for (const [rel, data] of files.entries()) {
+            const relNorm = rel.startsWith('/') ? rel.slice(1) : rel;
+            await this.write(`${base}/${relNorm}`, data);
+        }
+    }
+    async exec(command, opts) {
+        if (this.executor === 'unavailable' || !this.bashExec)
+            throw new SandboxNoExecutorError('Sandbox executor unavailable.', { session_id: 'unknown' });
+        return this.bashExec(command, opts);
+    }
+    async close() { }
+}
+export function inMemorySandbox() {
+    return {
+        capabilities: ['sandbox.fs'],
+        async open() {
+            return new MemorySandboxSession('unavailable');
+        }
+    };
+}
+export function bashSandbox(opts) {
+    let justBash;
+    try {
+        justBash = require('just-bash');
+    }
+    catch {
+        throw new HarnessConfigError('just-bash is not installed', { reason: 'just_bash_not_installed' });
+    }
+    return {
+        capabilities: ['sandbox.fs', 'sandbox.exec'],
+        async open() {
+            const engine = justBash.createSandbox ? await justBash.createSandbox(opts) : new justBash.Bash({ ...opts, cwd: '/workspace' });
+            const exec = async (command, execOpts) => {
+                const started = Date.now();
+                if (execOpts?.signal?.aborted)
+                    throw new OperationCancelledError('Sandbox run was cancelled.', { scope: 'sandbox' });
+                if (!engine.exec)
+                    throw new HarnessConfigError('just-bash exec is unavailable', { reason: 'just_bash_exec_unavailable' });
+                const timeoutMs = execOpts?.timeoutMs;
+                const controller = timeoutMs && timeoutMs > 0 ? new AbortController() : undefined;
+                const signal = controller?.signal ?? execOpts?.signal;
+                const sourceSignal = execOpts?.signal;
+                let timeoutId;
+                let abortListener;
+                const abortPromise = sourceSignal?.addEventListener
+                    ? new Promise((_, reject) => {
+                        abortListener = () => {
+                            controller?.abort();
+                            reject(new OperationCancelledError('Sandbox run was cancelled.', { scope: 'sandbox' }));
+                        };
+                        sourceSignal.addEventListener('abort', abortListener, { once: true });
+                    })
+                    : undefined;
+                const timeoutPromise = timeoutMs && timeoutMs > 0
+                    ? new Promise((_, reject) => {
+                        timeoutId = setTimeout(() => {
+                            controller?.abort();
+                            reject(new OperationTimeoutError('Sandbox run timed out.', { scope: 'sandbox_run', timeout_ms: timeoutMs }));
+                        }, timeoutMs);
+                    })
+                    : undefined;
+                try {
+                    const runner = engine.exec(command, { cwd: execOpts?.cwd, env: execOpts?.env, stdin: execOpts?.stdin, signal });
+                    const result = await Promise.race([runner, abortPromise, timeoutPromise].filter(Boolean));
+                    return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', exitCode: result.exitCode ?? 0, durationSeconds: (Date.now() - started) / 1000 };
+                }
+                finally {
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    if (abortListener)
+                        sourceSignal?.removeEventListener?.('abort', abortListener);
+                }
+            };
+            return new MemorySandboxSession('available', exec);
+        }
+    };
+}
+export function autoDetectSandbox() {
+    try {
+        return bashSandbox();
+    }
+    catch {
+        return inMemorySandbox();
+    }
+}

package/dist/sessions/index.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from '../logger/index.js';
+import type { Harness, HarnessDefaults, BuilderState, TelemetryOptions } from '../harness/defineHarness.js';
+import type { HarnessInspection } from '../ports/capabilities.js';
+import type { Sandbox } from '../sandbox/index.js';
+import type { StateStore } from '../ports/state.js';
+import { type TelemetryShim } from '../telemetry/index.js';
+type HarnessDefinition<S extends BuilderState> = {
+    name: string;
+    logger: Logger;
+    telemetry?: TelemetryOptions;
+    telemetryShim?: TelemetryShim;
+    state: StateStore;
+    sandbox: Sandbox;
+    defaults: HarnessDefaults;
+    models: NonNullable<S['models']>;
+    tools: NonNullable<S['tools']>;
+    skills: NonNullable<S['skills']>;
+    agents: NonNullable<S['agents']>;
+    workflows: NonNullable<S['workflows']>;
+    inspection: HarnessInspection;
+};
+export declare function createSessionHarness<S extends BuilderState>(definition: HarnessDefinition<S>): Harness<S>;
+export {};