@purista/harness 1.2.1 → 1.2.2

package/dist/workspace/in-memory.js

@@ -1,3 +1,12 @@
+import { OperationCancelledError, WorkspaceError, WorkspaceQuotaExceededError } from '../errors/index.js';
+const RETENTION = {
+    pausedTtlMs: 86_400_000,
+    terminalFailureTtlMs: 86_400_000,
+    terminalSuccessTtlMs: 0,
+    abortedTtlMs: 86_400_000,
+    cleanupMode: 'manual_only'
+};
+const QUOTA = { maxActiveWorkspaces: 100, maxWorkspaceBytes: 10_000_000, maxCheckpointPayloadBytes: 1_000_000 };
 /** In-process durable workspace store for local development, examples, and tests. */
 export class InMemoryDurableWorkspaceStore {
     info = {
@@ -13,25 +22,44 @@ export class InMemoryDurableWorkspaceStore {
             'workspace_store.retention',
             'workspace_store.quota'
         ],
-        policy: {
-            retention: {
-                pausedTtlMs: 86_400_000,
-                terminalFailureTtlMs: 86_400_000,
-                terminalSuccessTtlMs: 0,
-                cleanupMode: 'manual_only'
-            },
-            quota: { maxActiveWorkspaces: 100, maxWorkspaceBytes: 10_000_000 }
-        }
+        policy: { retention: RETENTION, quota: { maxActiveWorkspaces: QUOTA.maxActiveWorkspaces, maxWorkspaceBytes: QUOTA.maxWorkspaceBytes } }
     };
     capabilities = this.info.capabilities;
     workspaces = new Map();
+    startKeys = new Map();
+    opResults = new Map();
     nextId = 1;
     configureHarnessContext() { }
     async startWorkspace(opts) {
-        opts.signal?.throwIfAborted();
+        throwIfAborted(opts.signal);
+        // Idempotent start: a repeated key replays the same workspace; a key reused
+        // with a different identity is a conflict.
+        const prior = this.startKeys.get(opts.idempotencyKey);
+        if (prior) {
+            if (prior.runId !== opts.runId || prior.sessionId !== opts.sessionId) {
+                throw new WorkspaceError('Workspace start idempotency key reused with a different run/session.', {
+                    reason: 'idempotency_conflict',
+                    workspace_ref: prior.workspaceRef,
+                    run_id: opts.runId,
+                    session_id: opts.sessionId
+                });
+            }
+            const existing = this.workspaces.get(prior.workspaceRef);
+            if (existing)
+                return this.toHandle(existing);
+        }
+        const activeCount = [...this.workspaces.values()].filter((w) => w.state === 'active' || w.state === 'paused').length;
+        if (activeCount >= QUOTA.maxActiveWorkspaces) {
+            throw new WorkspaceQuotaExceededError('Active workspace quota exceeded.', {
+                quota: 'maxActiveWorkspaces',
+                limit: QUOTA.maxActiveWorkspaces,
+                actual: activeCount,
+                run_id: opts.runId,
+                session_id: opts.sessionId
+            });
+        }
         const workspaceRef = `workspace_${this.nextId++}`;
         const now = new Date().toISOString();
-        const metadata = { ...(opts.metadata ?? {}) };
         const workspace = {
             workspaceRef,
             state: 'active',
@@ -40,17 +68,42 @@ export class InMemoryDurableWorkspaceStore {
             attempt: opts.attempt,
             createdAt: now,
             updatedAt: now,
-            metadata,
-            checkpoints: []
+            metadata: { ...(opts.metadata ?? {}) },
+            checkpoints: [],
+            bytes: 0
         };
         this.workspaces.set(workspaceRef, workspace);
-        return { workspaceRef, runId: opts.runId, sessionId: opts.sessionId, state: 'active', startedAt: now, attempt: opts.attempt, metadata };
+        this.startKeys.set(opts.idempotencyKey, { workspaceRef, runId: opts.runId, sessionId: opts.sessionId });
+        return this.toHandle(workspace);
     }
     async pauseWorkspace(opts) {
-        opts.signal?.throwIfAborted();
-        const workspace = this.requireWorkspace(opts.handle.workspaceRef);
+        throwIfAborted(opts.signal);
+        const replay = this.opResults.get(opts.idempotencyKey);
+        if (replay)
+            return replay;
+        const workspace = this.requireLiveWorkspace(opts.handle.workspaceRef);
+        const payloadBytes = opts.checkpointPayload === undefined ? 0 : byteLength(opts.checkpointPayload);
+        if (payloadBytes > QUOTA.maxCheckpointPayloadBytes) {
+            throw new WorkspaceQuotaExceededError('Checkpoint payload exceeds the size quota.', {
+                quota: 'maxCheckpointPayloadBytes',
+                limit: QUOTA.maxCheckpointPayloadBytes,
+                actual: payloadBytes,
+                workspace_ref: workspace.workspaceRef
+            });
+        }
+        if (workspace.bytes + payloadBytes > QUOTA.maxWorkspaceBytes) {
+            throw new WorkspaceQuotaExceededError('Workspace byte quota exceeded.', {
+                quota: 'maxWorkspaceBytes',
+                limit: QUOTA.maxWorkspaceBytes,
+                actual: workspace.bytes + payloadBytes,
+                workspace_ref: workspace.workspaceRef
+            });
+        }
+        const committedAt = new Date().toISOString();
         workspace.state = 'paused';
-        workspace.updatedAt = new Date().toISOString();
+        workspace.updatedAt = committedAt;
+        workspace.bytes += payloadBytes;
+        const expiresAt = expiryFor('paused', committedAt);
         const checkpoint = {
             workspaceRef: workspace.workspaceRef,
             checkpointRef: `${workspace.workspaceRef}:checkpoint:${opts.sequence}`,
@@ -59,61 +112,101 @@ export class InMemoryDurableWorkspaceStore {
             stepId: opts.stepId,
             sequence: opts.sequence,
             attempt: opts.attempt,
-            committedAt: workspace.updatedAt,
+            committedAt,
+            ...(expiresAt ? { expiresAt } : {}),
+            sizeBytes: payloadBytes,
             metadata: {
                 reason: opts.reason,
                 ...(opts.checkpointPayload !== undefined ? { checkpointPayload: opts.checkpointPayload } : {})
             }
         };
         workspace.checkpoints.push(checkpoint);
+        this.opResults.set(opts.idempotencyKey, checkpoint);
         return checkpoint;
     }
     async resumeWorkspace(opts) {
-        opts.signal?.throwIfAborted();
-        const workspace = this.requireWorkspace(opts.workspaceRef);
+        throwIfAborted(opts.signal);
+        const replay = this.opResults.get(opts.idempotencyKey);
+        if (replay)
+            return replay;
+        const workspace = this.workspaces.get(opts.workspaceRef);
+        if (!workspace || workspace.state === 'cleaned') {
+            throw new WorkspaceError('Workspace not found.', { reason: 'not_found', workspace_ref: opts.workspaceRef });
+        }
+        if (workspace.state === 'aborted') {
+            throw new WorkspaceError('Workspace was aborted and cannot resume.', { reason: 'aborted', workspace_ref: opts.workspaceRef });
+        }
+        if (this.isExpired(workspace)) {
+            throw new WorkspaceError('Workspace has expired.', { reason: 'expired', workspace_ref: opts.workspaceRef });
+        }
         if (opts.checkpointRef && !workspace.checkpoints.some((checkpoint) => checkpoint.checkpointRef === opts.checkpointRef)) {
-            throw new Error(`Unknown workspace checkpoint: ${opts.checkpointRef}`);
+            throw new WorkspaceError('Workspace checkpoint not found.', { reason: 'missing_checkpoint', workspace_ref: opts.workspaceRef, checkpoint_ref: opts.checkpointRef });
         }
         workspace.state = 'active';
         workspace.runId = opts.runId;
         workspace.sessionId = opts.sessionId;
         workspace.attempt = opts.attempt;
         workspace.updatedAt = new Date().toISOString();
-        return {
-            workspaceRef: workspace.workspaceRef,
-            runId: workspace.runId,
-            sessionId: workspace.sessionId,
-            state: 'active',
-            startedAt: workspace.updatedAt,
-            attempt: workspace.attempt,
-            metadata: workspace.metadata
-        };
+        const handle = this.toHandle(workspace);
+        this.opResults.set(opts.idempotencyKey, handle);
+        return handle;
     }
     async abortWorkspace(opts) {
-        opts.signal?.throwIfAborted();
-        const workspace = this.requireWorkspace(opts.workspaceRef);
+        throwIfAborted(opts.signal);
+        const replay = this.opResults.get(opts.idempotencyKey);
+        if (replay)
+            return replay;
+        const workspace = this.workspaces.get(opts.workspaceRef);
+        if (!workspace || workspace.state === 'cleaned') {
+            throw new WorkspaceError('Workspace not found.', { reason: 'not_found', workspace_ref: opts.workspaceRef });
+        }
+        const abortedAt = new Date().toISOString();
         workspace.state = 'aborted';
-        workspace.updatedAt = new Date().toISOString();
-        return { workspaceRef: opts.workspaceRef, state: 'aborted', abortedAt: workspace.updatedAt };
+        workspace.updatedAt = abortedAt;
+        const cleanupEligibleAt = expiryFor('aborted', abortedAt);
+        const result = { workspaceRef: opts.workspaceRef, state: 'aborted', abortedAt, ...(cleanupEligibleAt ? { cleanupEligibleAt } : {}) };
+        this.opResults.set(opts.idempotencyKey, result);
+        return result;
     }
     async cleanupWorkspace(opts) {
-        opts.signal?.throwIfAborted();
-        const workspace = this.requireWorkspace(opts.workspaceRef);
+        throwIfAborted(opts.signal);
+        const replay = this.opResults.get(opts.idempotencyKey);
+        if (replay)
+            return replay;
+        const workspace = this.workspaces.get(opts.workspaceRef);
+        const completedAt = new Date().toISOString();
+        // Cleanup is idempotent: an already-cleaned (or unknown) workspace returns a
+        // terminal cleaned result rather than throwing.
+        if (!workspace || workspace.state === 'cleaned') {
+            const result = { workspaceRef: opts.workspaceRef, state: 'cleaned', completedAt, deletedBytes: 0, deletedFiles: 0 };
+            this.opResults.set(opts.idempotencyKey, result);
+            return result;
+        }
+        const deletedBytes = workspace.bytes;
+        const deletedFiles = workspace.checkpoints.length;
         workspace.state = 'cleaned';
-        workspace.updatedAt = new Date().toISOString();
-        this.workspaces.delete(opts.workspaceRef);
-        return { workspaceRef: opts.workspaceRef, state: 'cleaned', completedAt: workspace.updatedAt };
+        workspace.updatedAt = completedAt;
+        workspace.checkpoints = [];
+        workspace.bytes = 0;
+        const result = { workspaceRef: opts.workspaceRef, state: 'cleaned', completedAt, deletedBytes, deletedFiles };
+        this.opResults.set(opts.idempotencyKey, result);
+        return result;
     }
     async inspectWorkspace(opts) {
-        opts.signal?.throwIfAborted();
+        throwIfAborted(opts.signal);
         const workspaceRef = opts.workspaceRef ?? this.findWorkspaceByCheckpoint(opts.checkpointRef);
-        const workspace = this.requireWorkspace(workspaceRef);
+        const workspace = this.workspaces.get(workspaceRef);
+        if (!workspace) {
+            throw new WorkspaceError('Workspace not found.', { reason: 'not_found', workspace_ref: workspaceRef });
+        }
         const latest = workspace.checkpoints.at(-1);
+        const expiresAt = expiryFor(workspace.state, workspace.updatedAt);
         return {
             workspaceRef: workspace.workspaceRef,
             state: workspace.state,
             checkpoints: workspace.checkpoints,
             ...(latest ? { currentCheckpointRef: latest.checkpointRef } : {}),
+            ...(expiresAt ? { expiresAt, cleanupEligibleAt: expiresAt } : {}),
             retention: this.info.policy.retention,
             quota: this.info.policy.quota,
             createdAt: workspace.createdAt,
@@ -121,21 +214,71 @@ export class InMemoryDurableWorkspaceStore {
             metadata: workspace.metadata
         };
     }
+    toHandle(workspace) {
+        return {
+            workspaceRef: workspace.workspaceRef,
+            runId: workspace.runId,
+            sessionId: workspace.sessionId,
+            state: 'active',
+            startedAt: workspace.updatedAt,
+            attempt: workspace.attempt,
+            metadata: workspace.metadata
+        };
+    }
+    isExpired(workspace) {
+        const expiresAt = expiryFor(workspace.state, workspace.updatedAt);
+        return expiresAt !== undefined && Date.parse(expiresAt) <= Date.now();
+    }
     findWorkspaceByCheckpoint(checkpointRef) {
-        if (!checkpointRef)
-            throw new Error('workspaceRef or checkpointRef is required.');
+        if (!checkpointRef) {
+            throw new WorkspaceError('workspaceRef or checkpointRef is required.', { reason: 'invalid_reference' });
+        }
         const found = [...this.workspaces.values()].find((workspace) => workspace.checkpoints.some((checkpoint) => checkpoint.checkpointRef === checkpointRef));
-        if (!found)
-            throw new Error(`Unknown workspace checkpoint: ${checkpointRef}`);
+        if (!found) {
+            throw new WorkspaceError('Workspace checkpoint not found.', { reason: 'invalid_reference', checkpoint_ref: checkpointRef });
+        }
         return found.workspaceRef;
     }
-    requireWorkspace(workspaceRef) {
+    requireLiveWorkspace(workspaceRef) {
         const workspace = this.workspaces.get(workspaceRef);
-        if (!workspace)
-            throw new Error(`Unknown workspace: ${workspaceRef}`);
+        if (!workspace || workspace.state === 'cleaned') {
+            throw new WorkspaceError('Workspace not found.', { reason: 'not_found', workspace_ref: workspaceRef });
+        }
+        if (workspace.state === 'aborted') {
+            throw new WorkspaceError('Workspace was aborted.', { reason: 'aborted', workspace_ref: workspaceRef });
+        }
         return workspace;
     }
 }
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new OperationCancelledError('Workspace operation was cancelled.', { scope: 'workspace' });
+    }
+}
+function ttlForState(state) {
+    switch (state) {
+        case 'paused':
+            return RETENTION.pausedTtlMs;
+        case 'aborted':
+            return RETENTION.abortedTtlMs ?? RETENTION.terminalFailureTtlMs;
+        default:
+            return undefined;
+    }
+}
+function expiryFor(state, fromIso) {
+    const ttl = ttlForState(state);
+    if (ttl === undefined || ttl <= 0)
+        return undefined;
+    return new Date(Date.parse(fromIso) + ttl).toISOString();
+}
+function byteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
 /** Creates a fresh in-process durable workspace store. */
 export function inMemoryDurableWorkspaceStore() {
     return new InMemoryDurableWorkspaceStore();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purista/harness",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Self-hosted enterprise agent harness for typed tools, agents, workflows, state, sandboxing, and telemetry.",
   "type": "module",
   "main": "dist/index.js",

package/dist/harness/errors.d.ts

@@ -1,62 +0,0 @@
-import type { JsonValue } from './types.js';
-export declare class HarnessError extends Error {
-    code: string;
-    category: string;
-    retriable: boolean;
-    meta?: Record<string, JsonValue>;
-    constructor(message: string, opts: {
-        code: string;
-        category: string;
-        retriable: boolean;
-        meta?: Record<string, JsonValue>;
-    });
-}
-export declare class HarnessConfigError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class ValidationError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class PermissionDeniedError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class SandboxError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class SandboxNoExecutorError extends HarnessError {
-    constructor();
-}
-export declare class ModelError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class ToolError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class ToolNotFoundError extends HarnessError {
-    constructor(tool: string);
-}
-export declare class SkillManifestError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare class AgentLoopBudgetError extends HarnessError {
-    constructor();
-}
-export declare class SessionBusyError extends HarnessError {
-    constructor(reason?: string);
-}
-export declare class OperationTimeoutError extends HarnessError {
-    constructor(scope: string);
-}
-export declare class OperationCancelledError extends HarnessError {
-    constructor(scope: string);
-}
-export declare class InternalError extends HarnessError {
-    constructor(message: string, meta?: Record<string, JsonValue>);
-}
-export declare function serializeError(error: unknown): {
-    code: string;
-    category: string;
-    retriable: boolean;
-    message: string;
-    meta?: Record<string, JsonValue>;
-};

package/dist/harness/errors.js

@@ -1,67 +0,0 @@
-export class HarnessError extends Error {
-    code;
-    category;
-    retriable;
-    meta;
-    constructor(message, opts) {
-        super(message);
-        this.name = new.target.name;
-        this.code = opts.code;
-        this.category = opts.category;
-        this.retriable = opts.retriable;
-        if (opts.meta !== undefined)
-            this.meta = opts.meta;
-    }
-}
-function errorOptions(opts, meta) {
-    return meta === undefined ? opts : { ...opts, meta };
-}
-export class HarnessConfigError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'HARNESS_CONFIG_ERROR', category: 'config', retriable: false }, meta)); }
-}
-export class ValidationError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'VALIDATION_ERROR', category: 'validation', retriable: false }, meta)); }
-}
-export class PermissionDeniedError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'PERMISSION_DENIED', category: 'permission', retriable: false }, meta)); }
-}
-export class SandboxError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'SANDBOX_ERROR', category: 'sandbox', retriable: false }, meta)); }
-}
-export class SandboxNoExecutorError extends HarnessError {
-    constructor() { super('Sandbox executor unavailable', { code: 'SANDBOX_NO_EXECUTOR', category: 'sandbox', retriable: false }); }
-}
-export class ModelError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'MODEL_ERROR', category: 'model', retriable: true }, meta)); }
-}
-export class ToolError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'TOOL_ERROR', category: 'tool', retriable: true }, meta)); }
-}
-export class ToolNotFoundError extends HarnessError {
-    constructor(tool) { super(`Tool not found: ${tool}`, { code: 'TOOL_NOT_FOUND', category: 'tool', retriable: false, meta: { tool } }); }
-}
-export class SkillManifestError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'SKILL_MANIFEST_ERROR', category: 'config', retriable: false }, meta)); }
-}
-export class AgentLoopBudgetError extends HarnessError {
-    constructor() { super('Agent maxSteps exceeded', { code: 'AGENT_LOOP_BUDGET', category: 'agent', retriable: false, meta: { reason: 'iterations_exceeded' } }); }
-}
-export class SessionBusyError extends HarnessError {
-    constructor(reason = 'run_in_flight') { super('Session is busy', { code: 'SESSION_BUSY', category: 'session', retriable: true, meta: { reason } }); }
-}
-export class OperationTimeoutError extends HarnessError {
-    constructor(scope) { super('Operation timed out', { code: 'OPERATION_TIMEOUT', category: 'harness', retriable: true, meta: { scope } }); }
-}
-export class OperationCancelledError extends HarnessError {
-    constructor(scope) { super('Operation cancelled', { code: 'OPERATION_CANCELLED', category: 'harness', retriable: false, meta: { scope } }); }
-}
-export class InternalError extends HarnessError {
-    constructor(message, meta) { super(message, errorOptions({ code: 'INTERNAL_ERROR', category: 'internal', retriable: false }, meta)); }
-}
-export function serializeError(error) {
-    if (error instanceof HarnessError) {
-        const serialized = { code: error.code, category: error.category, retriable: error.retriable, message: error.message };
-        return error.meta === undefined ? serialized : { ...serialized, meta: error.meta };
-    }
-    return { code: 'INTERNAL_ERROR', category: 'internal', retriable: false, message: error instanceof Error ? error.message : String(error) };
-}