@purista/harness 1.1.0 → 1.2.0

package/dist/agents/index.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ATTR_GEN_AI_AGENT_ID, ATTR_GEN_AI_AGENT_NAME, ATTR_GEN_AI_TOOL_CALL_ID, ATTR_GEN_AI_TOOL_NAME, ATTR_GEN_AI_TOOL_TYPE } from '@opentelemetry/semantic-conventions/incubating';
-import { AgentLoopBudgetError, HarnessError, OperationCancelledError, OperationTimeoutError, PermissionDeniedError, ToolError, ToolNotFoundError, ValidationError, serializeError } from '../errors/index.js';
+import { AgentLoopBudgetError, HarnessConfigError, HarnessError, OperationCancelledError, OperationTimeoutError, PermissionDeniedError, ToolError, ToolNotFoundError, ValidationError, serializeError } from '../errors/index.js';
 import { createMetrics } from '../telemetry/index.js';
 import { buildSkillIndex, mountSkillsOnce } from '../skills/index.js';
 import { BUILTIN_ALIAS_TO_CANONICAL, getBuiltinToolSpecs, invokeBuiltinTool } from '../tools/index.js';
@@ -76,6 +76,7 @@ async function runDefaultAgentInner(args) {
         throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: args.agent.model } });
     const skillIds = args.agent.skills ?? [];
     await mountSkillsOnce(args.session, args.mountedSkills, args.skills, skillIds);
+    const activatedSkills = new Set();
     if (args.agent.handler) {
         const output = await args.agent.handler({
             input: parsedInput,
@@ -96,6 +97,13 @@ async function runDefaultAgentInner(args) {
         : args.agent.instructions;
     const instructions = `${baseInstructions}${buildSkillIndex(args.skills, skillIds)}`;
     const enabledBuiltins = args.agent.builtinTools === false ? [] : args.agent.builtinTools?.slice() ?? ['bash', 'read', 'write', 'edit', 'glob', 'grep', 'list'];
+    if (skillIds.length > 0 && !enabledBuiltins.includes('read')) {
+        throw new HarnessConfigError('Agents with skills require the read built-in tool for skill activation.', {
+            reason: 'skill_read_tool_missing',
+            path: `agents.${args.agentId}.builtinTools`,
+            id: args.agentId
+        });
+    }
     const builtinSpecs = getBuiltinToolSpecs(enabledBuiltins, args.session);
     const enabledCustomTools = new Set((args.agent.tools ?? []));
     const tsCustomSpecs = Object.entries(args.customTools)
@@ -171,7 +179,10 @@ async function runDefaultAgentInner(args) {
                         throw new PermissionDeniedError('Permission denied.', { tool_name: canonical, agent_id: args.agentId, reason: 'hook_deny' });
                     }
                     if (canonical in BUILTIN_ALIAS_TO_CANONICAL) {
-                        return { output: await withToolSignal(args.signal, args.toolTimeoutMs, (signal) => invokeBuiltinTool(canonical, input, withSandboxTelemetry(args, canonical), signal)) };
+                        const output = await withToolSignal(args.signal, args.toolTimeoutMs, (signal) => invokeBuiltinTool(canonical, input, withSandboxTelemetry(args, canonical), signal));
+                        if (canonical === 'read')
+                            markSkillActivation(input, args.skills, activatedSkills);
+                        return { output };
                     }
                     if (!enabledCustomTools.has(canonical)) {
                         throw new ToolNotFoundError('Tool is not allowed for this agent.', { tool_id: canonical, where: 'agent_allowlist' });
@@ -230,6 +241,19 @@ async function runDefaultAgentInner(args) {
         steps += 1;
     }
 }
+function markSkillActivation(input, skills, activated) {
+    if (!input || typeof input !== 'object')
+        return;
+    const readPath = input.path;
+    if (typeof readPath !== 'string')
+        return;
+    for (const skill of Object.values(skills)) {
+        if (readPath === `${skill.mountPath}/SKILL.md`) {
+            activated.add(skill.name);
+            return;
+        }
+    }
+}
 async function withToolSignal(parent, timeoutMs, fn) {
     parent.throwIfAborted();
     const controller = new AbortController();

package/dist/errors/catalog.d.ts

@@ -104,8 +104,9 @@ export declare class SkillNotFoundError extends HarnessError {
 export declare class SkillManifestError extends HarnessError {
     constructor(message: string, meta: {
         directory: string;
-        reason: 'missing_skill_md' | 'invalid_frontmatter' | 'name_mismatch' | 'directory_missing' | 'reserved_name';
+        reason: 'missing_skill_md' | 'invalid_frontmatter' | 'missing_description' | 'invalid_name' | 'name_mismatch' | 'directory_missing' | 'collision_shadowed' | 'untrusted_project_skill' | 'scan_limit_reached' | 'reserved_name';
         skill_id?: string;
+        source?: string;
     }, cause?: unknown);
 }
 /** Workflow referenced an unknown agent id. */
@@ -150,17 +151,49 @@ export declare class StateError extends HarnessError {
         memory_provider?: string;
     }, cause?: unknown);
 }
+/** Durable workspace lifecycle, consistency, inspection, or backend failure. */
+export declare class WorkspaceError extends HarnessError {
+    constructor(message: string, meta: {
+        reason: 'idempotency_conflict' | 'not_found' | 'aborted' | 'expired' | 'missing_checkpoint' | 'backend_failure' | 'unsupported_operation' | 'invalid_reference' | 'checkpoint_conflict' | 'cleanup_pending';
+        workspace_ref?: string;
+        checkpoint_ref?: string;
+        snapshot_ref?: string;
+        run_id?: string;
+        session_id?: string;
+    }, cause?: unknown);
+}
+/** Durable workspace quota would be or was exceeded. */
+export declare class WorkspaceQuotaExceededError extends HarnessError {
+    constructor(message: string, meta: {
+        quota: string;
+        limit?: number;
+        actual?: number;
+        partial?: boolean;
+        workspace_ref?: string;
+        run_id?: string;
+        session_id?: string;
+    }, cause?: unknown);
+}
+/** Durable workspace cleanup could not complete in the current attempt. */
+export declare class WorkspaceCleanupError extends HarnessError {
+    constructor(message: string, meta: {
+        reason: 'backend_failure' | 'partial_delete' | 'invalid_reference';
+        workspace_ref: string;
+        remaining_refs?: readonly string[];
+        retry_after_ms?: number;
+    }, cause?: unknown);
+}
 /** Timed execution budget expired. */
 export declare class OperationTimeoutError extends HarnessError {
     constructor(message: string, meta: {
-        scope: 'run' | 'model' | 'tool' | 'sandbox_run' | 'memory';
+        scope: 'run' | 'model' | 'tool' | 'sandbox_run' | 'memory' | 'workspace';
         timeout_ms: number;
     }, cause?: unknown);
 }
 /** Operation cancelled by abort signal or explicit cancellation path. */
 export declare class OperationCancelledError extends HarnessError {
     constructor(message: string, meta: {
-        scope: 'run' | 'workflow' | 'agent' | 'model' | 'tool' | 'sandbox' | 'memory';
+        scope: 'run' | 'workflow' | 'agent' | 'model' | 'tool' | 'sandbox' | 'memory' | 'workspace';
     }, cause?: unknown);
 }
 /** MCP transport/protocol failure. */

package/dist/errors/catalog.js

@@ -111,6 +111,25 @@ export class StateError extends HarnessError {
         super({ code: 'STATE_ERROR', category: 'state', retriable: true, message, meta, cause });
     }
 }
+/** Durable workspace lifecycle, consistency, inspection, or backend failure. */
+export class WorkspaceError extends HarnessError {
+    constructor(message, meta, cause) {
+        const retriable = meta.reason === 'backend_failure' || meta.reason === 'cleanup_pending';
+        super({ code: 'WORKSPACE_ERROR', category: 'workspace', retriable, message, meta, cause });
+    }
+}
+/** Durable workspace quota would be or was exceeded. */
+export class WorkspaceQuotaExceededError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'WORKSPACE_QUOTA_EXCEEDED', category: 'workspace', retriable: false, message, meta, cause });
+    }
+}
+/** Durable workspace cleanup could not complete in the current attempt. */
+export class WorkspaceCleanupError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'WORKSPACE_CLEANUP_ERROR', category: 'workspace', retriable: true, message, meta, cause });
+    }
+}
 /** Timed execution budget expired. */
 export class OperationTimeoutError extends HarnessError {
     constructor(message, meta, cause) {

package/dist/errors/harness-error.d.ts

@@ -22,6 +22,8 @@ export type ErrorCategory =
  | 'session'
 /** State-store persistence failures. */
  | 'state'
+/** Durable workspace lifecycle or backend failures. */
+ | 'workspace'
 /** Timeout budget failures. */
  | 'timeout'
 /** Cooperative cancellation events. */

package/dist/harness/defineHarness.d.ts

@@ -5,6 +5,7 @@ import type { StateStore } from '../ports/state.js';
 import type { Metrics, TelemetryShim } from '../telemetry/index.js';
 import type { HarnessAdapterContext } from '../ports/harness-context.js';
 import type { MemoryAdapter, MemoryFacade, SessionMemory } from '../ports/memory.js';
+import type { DurableWorkspaceStore } from '../ports/workspace.js';
 import type { JsonValue } from '../models/json.js';
 import type { Message } from '../models/state.js';
 import type { RunStatus } from '../models/state.js';
@@ -100,16 +101,47 @@ export interface PermissionContext {
 export type PermissionDecision = 'allow' | 'deny';
 /** Async permission hook used for interactive approvals or custom policy engines. */
 export type OnPermission = (ctx: PermissionContext) => Promise<PermissionDecision>;
+/** Skill frontmatter parsed from `SKILL.md`. */
+export interface SkillFrontmatter {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    'allowed-tools'?: string;
+}
+/** Validation mode for `SKILL.md` frontmatter. */
+export type SkillValidationMode = 'strict' | 'lenient';
+/** Diagnostic produced while parsing or discovering skills. */
+export interface SkillDiagnostic {
+    level: 'warn' | 'error';
+    code: 'missing_skill_md' | 'invalid_frontmatter' | 'missing_description' | 'invalid_name' | 'name_mismatch' | 'directory_missing' | 'collision_shadowed' | 'untrusted_project_skill' | 'scan_limit_reached';
+    message: string;
+    skillName?: string;
+    directory?: string;
+    source?: string;
+}
 /** Mounted skill metadata after frontmatter parsing. */
 export interface ResolvedSkill {
     /** Public skill id. */
     name: string;
     /** Short user-facing description from frontmatter. */
     description: string;
-    /** Optional skill version. */
-    version?: string;
     /** Absolute directory mounted into `/skills/<name>`. */
     directory: string;
+    /** Absolute path to the parsed `SKILL.md`. */
+    skillPath: string;
+    /** Absolute path exposed as the skill instruction file location. */
+    location: string;
+    /** Sandbox mount path for this skill. */
+    mountPath: `/skills/${string}`;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    allowedTools?: string;
+    trust: 'trusted' | 'project' | 'user';
+    source?: string;
+    diagnostics: readonly SkillDiagnostic[];
 }
 /** Conversation history accessor for a single session thread. */
 export interface ConversationHistory {
@@ -214,9 +246,32 @@ export type ToolsConfig = Record<string, ToolDefinition>;
 export interface SkillDefinition {
     /** Absolute path to the directory containing `SKILL.md`. */
     directory: string;
+    validationMode?: SkillValidationMode;
+    trust?: 'trusted' | 'project' | 'user';
+    source?: string;
 }
 /** Full skill registry shape. */
 export type SkillsConfig = Record<string, SkillDefinition>;
+/** Options for local Agent Skills discovery. */
+export interface DiscoverSkillsOptions {
+    projectRoot?: string;
+    clientName?: string;
+    includeProjectAgentsDir?: boolean;
+    includeProjectClientDir?: boolean;
+    includeUserAgentsDir?: boolean;
+    includeUserClientDir?: boolean;
+    includeClaudeCompatDir?: boolean;
+    includeAncestorProjectDirs?: boolean;
+    trustedProjectRoots?: readonly string[];
+    validationMode?: SkillValidationMode;
+    maxDepth?: number;
+    maxDirectories?: number;
+}
+/** Result of local Agent Skills discovery. */
+export interface DiscoveredSkills {
+    skills: SkillsConfig;
+    diagnostics: readonly SkillDiagnostic[];
+}
 /** Alias map passed to `.models(...)`. */
 export type ModelsConfig = Record<string, ModelAlias>;
 /** Builder-state accumulator used for type propagation across the fluent harness builder. */
@@ -559,6 +614,7 @@ export interface HarnessBuilder<S extends BuilderState = {}> {
     sandbox(sandbox?: Sandbox<any>): HarnessBuilder<S>;
     memory(adapter: MemoryAdapter): HarnessBuilder<S>;
     runtime(runtime: DurableRuntimeAdapter): HarnessBuilder<S>;
+    workspaceStore(store: DurableWorkspaceStore): HarnessBuilder<S>;
     requires(capabilities: readonly AdapterCapability[]): HarnessBuilder<S>;
     defaults(defaults: HarnessDefaults): HarnessBuilder<S>;
     models<const M extends ModelsConfig>(models: M): HarnessBuilder<S & {

package/dist/harness/defineHarness.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { JsonLogger } from '../logger/index.js';
 import { sandboxMemory } from '../memory/sandbox/index.js';
 import { validateMemoryAdapter } from '../ports/memory.js';
+import { validateDurableWorkspaceStore } from '../ports/workspace.js';
 import { InMemoryStateStore } from '../state/in-memory.js';
 import { HarnessConfigError } from '../errors/catalog.js';
 import { autoDetectSandbox } from '../sandbox/index.js';
@@ -38,6 +39,13 @@ class Builder {
     runtime(runtime) {
         return this.clone({ runtime });
     }
+    workspaceStore(workspaceStore) {
+        if (this.configured.workspaceStore) {
+            throw new HarnessConfigError('Workspace store is already configured.', { reason: 'duplicate_adapter', path: 'workspaceStore' });
+        }
+        validateDurableWorkspaceStore(workspaceStore);
+        return this.clone({ workspaceStore });
+    }
     requires(capabilities) {
         return this.clone({ requiredCapabilities: uniqueCapabilities(capabilities) });
     }
@@ -63,6 +71,7 @@ class Builder {
         const resolved = typeof agents === 'function'
             ? agents({ agent: (definition) => definition })
             : agents;
+        this.validateAgentSkillReferences(resolved);
         return this.clone({ agents: resolved });
     }
     workflows(workflows) {
@@ -79,6 +88,8 @@ class Builder {
         const sandbox = this.configured.sandbox ?? autoDetectSandbox();
         const memory = this.configured.memory ?? sandboxMemory();
         validateMemoryAdapter(memory);
+        if (this.configured.workspaceStore)
+            validateDurableWorkspaceStore(this.configured.workspaceStore);
         const inspection = this.resolveInspection(this.options.name ?? 'agent-harness', sandbox, memory, models);
         const missing = missingCapabilities(inspection.requiredCapabilities, inspection.capabilities);
         if (missing.length > 0) {
@@ -115,6 +126,20 @@ class Builder {
     clone(patch) {
         return new Builder(this.options, { ...this.configured, ...patch });
     }
+    validateAgentSkillReferences(agents) {
+        const configuredSkills = new Set(Object.keys(this.configured.skills ?? {}));
+        for (const [agentId, agent] of Object.entries(agents)) {
+            for (const skillId of agent.skills ?? []) {
+                if (!configuredSkills.has(skillId)) {
+                    throw new HarnessConfigError('Agent references an unknown skill.', {
+                        reason: 'invalid_agent',
+                        path: `agents.${agentId}.skills`,
+                        id: skillId
+                    });
+                }
+            }
+        }
+    }
     resolveInspection(name, sandbox, memory, models) {
         const adapters = [];
         const sandboxCapabilities = hasAdapterCapabilities(sandbox) ? uniqueCapabilities(sandbox.capabilities) : [];
@@ -139,6 +164,17 @@ class Builder {
                 capabilities: uniqueCapabilities(this.configured.runtime.capabilities)
             });
         }
+        if (this.configured.workspaceStore) {
+            adapters.push({
+                kind: 'workspace_store',
+                id: this.configured.workspaceStore.info.id,
+                capabilities: uniqueCapabilities(this.configured.workspaceStore.info.capabilities),
+                metadata: {
+                    packageName: this.configured.workspaceStore.info.packageName,
+                    policy: this.configured.workspaceStore.info.policy
+                }
+            });
+        }
         for (const [alias, model] of Object.entries(models)) {
             adapters.push({
                 kind: 'model',

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export type { SessionRecord, Message, RunRecord, PersistedRunEvent, RunStatus }
 export * from './models/registry.js';
 export * from './eval/index.js';
 export * from './memory/sandbox/index.js';
+export * from './skills/index.js';
 export * from './sandbox/index.js';
+export * from './workspace/index.js';
 export * from './tools/mcp/index.js';
 export * from './harness/defineHarness.js';

package/dist/index.js

@@ -9,6 +9,8 @@ export * from './models/json.js';
 export * from './models/registry.js';
 export * from './eval/index.js';
 export * from './memory/sandbox/index.js';
+export * from './skills/index.js';
 export * from './sandbox/index.js';
+export * from './workspace/index.js';
 export * from './tools/mcp/index.js';
 export * from './harness/defineHarness.js';

package/dist/ports/capabilities.d.ts

@@ -25,6 +25,28 @@ export type AdapterCapability =
  | 'runtime.distributed_lock'
 /** Runtime can resume from committed checkpoints. */
  | 'runtime.resume_from_checkpoint'
+/** Runtime checkpoint records can carry durable workspace references. */
+ | 'runtime.workspace_checkpoint'
+/** Runtime exposes checkpoint retention and expiry metadata. */
+ | 'runtime.checkpoint_retention'
+/** Workspace store persists state beyond process exit. */
+ | 'workspace_store.durable'
+/** Workspace store can produce stable checkpoints. */
+ | 'workspace_store.checkpoint'
+/** Workspace store can resume committed checkpoints. */
+ | 'workspace_store.resume'
+/** Workspace store can abort active or paused workspaces. */
+ | 'workspace_store.abort'
+/** Workspace store supports idempotent cleanup. */
+ | 'workspace_store.cleanup'
+/** Workspace store supports read-only inspection. */
+ | 'workspace_store.inspect'
+/** Workspace store exposes retention policy and expiry metadata. */
+ | 'workspace_store.retention'
+/** Workspace store enforces and reports quota policy. */
+ | 'workspace_store.quota'
+/** Workspace store encrypts checkpoint, snapshot, file, and metadata storage. */
+ | 'workspace_store.encrypted_storage'
 /** Adapter can record feedback. */
  | 'feedback.record'
 /** Memory adapter supports key/value reads and writes. */
@@ -55,7 +77,7 @@ export interface AdapterCapabilities {
 }
 /** Adapter descriptor surfaced through `harness.inspect()`. */
 export interface AdapterInspection {
-    readonly kind: 'state' | 'sandbox' | 'runtime' | 'feedback' | 'model' | 'memory';
+    readonly kind: 'state' | 'sandbox' | 'runtime' | 'workspace_store' | 'feedback' | 'model' | 'memory';
     readonly id: string;
     readonly capabilities: readonly AdapterCapability[];
     readonly metadata?: Record<string, unknown>;

package/dist/ports/index.d.ts

@@ -5,3 +5,4 @@ export * from './harness-context.js';
 export * from './capabilities.js';
 export * from './feedback.js';
 export * from './memory.js';
+export * from './workspace.js';

package/dist/ports/index.js

@@ -5,3 +5,4 @@ export * from './harness-context.js';
 export * from './capabilities.js';
 export * from './feedback.js';
 export * from './memory.js';
+export * from './workspace.js';

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/skills/index.d.ts

@@ -1,8 +1,9 @@
 import type { JsonValue } from '../models/json.js';
-import type { ResolvedSkill, SkillDefinition } from '../harness/defineHarness.js';
+import type { DiscoveredSkills, DiscoverSkillsOptions, ResolvedSkill, SkillDefinition } from '../harness/defineHarness.js';
 import type { SandboxSession } from '../sandbox/index.js';
 export declare function loadSkillsSync(skills: Record<string, SkillDefinition>): Record<string, ResolvedSkill>;
 export declare function loadSkills(skills: Record<string, SkillDefinition>): Promise<Record<string, ResolvedSkill>>;
 export declare function mountSkillsOnce(session: SandboxSession, mounted: Set<string>, skills: Record<string, ResolvedSkill>, skillIds: readonly string[]): Promise<void>;
 export declare function buildSkillIndex(skills: Record<string, ResolvedSkill>, ids: readonly string[]): string;
+export declare function discoverSkills(options?: DiscoverSkillsOptions): Promise<DiscoveredSkills>;
 export declare function assertSerializable(value: unknown): asserts value is JsonValue;

package/dist/skills/index.js

@@ -1,44 +1,177 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { parseDocument } from 'yaml';
 import { SkillManifestError, SkillNotFoundError } from '../errors/index.js';
-function parseFrontmatter(content) {
-    if (!content.startsWith('---\n'))
-        throw new SkillManifestError('Invalid SKILL.md frontmatter', { reason: 'invalid_frontmatter', directory: '' });
-    const end = content.indexOf('\n---\n', 4);
-    if (end < 0)
-        throw new SkillManifestError('Invalid SKILL.md frontmatter', { reason: 'invalid_frontmatter', directory: '' });
-    const raw = content.slice(4, end);
-    const body = content.slice(end + 5);
-    const frontmatter = {};
-    for (const line of raw.split('\n')) {
-        const idx = line.indexOf(':');
-        if (idx < 0)
-            continue;
-        frontmatter[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+const skillNamePattern = /^(?!-)(?!.*--)[a-z0-9-]{1,64}(?<!-)$/;
+const skippedDirectories = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.astro']);
+function diagnostic(code, message, opts = {}) {
+    return {
+        level: opts.level ?? 'error',
+        code,
+        message,
+        ...(opts.skillName ? { skillName: opts.skillName } : {}),
+        ...(opts.directory ? { directory: opts.directory } : {}),
+        ...(opts.source ? { source: opts.source } : {})
+    };
+}
+function throwManifest(diag, skillId, cause) {
+    throw new SkillManifestError(diag.message, {
+        reason: diag.code,
+        directory: diag.directory ?? '',
+        ...(skillId ? { skill_id: skillId } : {}),
+        ...(diag.source ? { source: diag.source } : {})
+    }, cause);
+}
+function extractFrontmatter(content, directory) {
+    if (!content.startsWith('---\n')) {
+        throwManifest(diagnostic('invalid_frontmatter', 'SKILL.md must start with YAML frontmatter.', { directory }));
+    }
+    const end = content.indexOf('\n---', 4);
+    if (end < 0) {
+        throwManifest(diagnostic('invalid_frontmatter', 'SKILL.md frontmatter is not terminated.', { directory }));
+    }
+    return content.slice(4, end);
+}
+function quoteColonScalars(raw) {
+    return raw.split('\n').map((line) => {
+        const match = /^([A-Za-z0-9_-]+):\s*(.+:.+)$/.exec(line);
+        if (!match)
+            return line;
+        const key = match[1] ?? '';
+        const value = match[2] ?? '';
+        const trimmed = value.trim();
+        if (trimmed.startsWith('"')
+            || trimmed.startsWith("'")
+            || trimmed.startsWith('|')
+            || trimmed.startsWith('>')
+            || trimmed.startsWith('{')
+            || trimmed.startsWith('[')) {
+            return line;
+        }
+        return `${key}: ${JSON.stringify(trimmed)}`;
+    }).join('\n');
+}
+function parseYamlFrontmatter(raw, mode, directory) {
+    const first = parseDocument(raw, { strict: true });
+    if (!first.errors.length)
+        return { value: first.toJSON(), diagnostics: [] };
+    if (mode === 'lenient') {
+        const retried = parseDocument(quoteColonScalars(raw), { strict: true });
+        if (!retried.errors.length) {
+            return {
+                value: retried.toJSON(),
+                diagnostics: [diagnostic('invalid_frontmatter', 'Lenient skill parsing repaired YAML scalar quoting.', { level: 'warn', directory })]
+            };
+        }
     }
-    return { frontmatter, body };
+    throwManifest(diagnostic('invalid_frontmatter', 'Invalid SKILL.md YAML frontmatter.', { directory }), undefined, first.errors[0]);
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function validateFrontmatter(value, mode, directory, expectedName, source) {
+    const data = asRecord(value);
+    const diagnostics = [];
+    const nameValue = data['name'];
+    const name = typeof nameValue === 'string' ? nameValue.trim() : '';
+    if (!skillNamePattern.test(name)) {
+        const diag = diagnostic('invalid_name', 'Skill name must be 1-64 lowercase ASCII letters, numbers, or hyphens with no leading, trailing, or consecutive hyphens.', { directory, source, skillName: name });
+        if (mode === 'strict')
+            throwManifest(diag, expectedName);
+        diagnostics.push(diag);
+        return undefined;
+    }
+    const descriptionValue = data['description'];
+    const description = typeof descriptionValue === 'string' ? descriptionValue.trim() : '';
+    if (description.length < 1 || description.length > 1024) {
+        const diag = diagnostic('missing_description', 'Skill description is required and must be 1-1024 characters.', { directory, source, skillName: name });
+        if (mode === 'strict')
+            throwManifest(diag, expectedName);
+        diagnostics.push(diag);
+        return undefined;
+    }
+    const parentName = path.basename(directory);
+    if (expectedName && expectedName !== name) {
+        const diag = diagnostic('name_mismatch', `Skill key "${expectedName}" must match frontmatter name "${name}".`, { directory, source, skillName: name, level: mode === 'strict' ? 'error' : 'warn' });
+        if (mode === 'strict')
+            throwManifest(diag, expectedName);
+        diagnostics.push(diag);
+    }
+    else if (!expectedName && parentName !== name) {
+        const diag = diagnostic('name_mismatch', `Skill directory "${parentName}" does not match frontmatter name "${name}".`, { directory, source, skillName: name, level: mode === 'strict' ? 'error' : 'warn' });
+        if (mode === 'strict')
+            throwManifest(diag, name);
+        diagnostics.push(diag);
+    }
+    const metadata = asRecord(data['metadata']);
+    const metadataOut = {};
+    for (const [key, val] of Object.entries(metadata)) {
+        if (typeof val === 'string')
+            metadataOut[key] = val;
+    }
+    return {
+        frontmatter: {
+            name,
+            description,
+            ...(typeof data['license'] === 'string' && data['license'].trim() ? { license: data['license'].trim() } : {}),
+            ...(typeof data['compatibility'] === 'string' && data['compatibility'].trim() ? { compatibility: data['compatibility'].trim() } : {}),
+            ...(Object.keys(metadataOut).length ? { metadata: metadataOut } : {}),
+            ...(typeof data['allowed-tools'] === 'string' && data['allowed-tools'].trim() ? { 'allowed-tools': data['allowed-tools'].trim() } : {})
+        },
+        diagnostics
+    };
+}
+function readSkill(directory, mode, expectedName, source) {
+    const stat = fs.existsSync(directory) ? fs.statSync(directory) : null;
+    if (!stat?.isDirectory()) {
+        const diag = diagnostic('directory_missing', 'Skill directory is missing.', { directory, source, skillName: expectedName });
+        if (mode === 'strict')
+            throwManifest(diag, expectedName);
+        return undefined;
+    }
+    const skillPath = path.resolve(directory, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+        const diag = diagnostic('missing_skill_md', 'Skill directory must contain SKILL.md.', { directory, source, skillName: expectedName });
+        if (mode === 'strict')
+            throwManifest(diag, expectedName);
+        return undefined;
+    }
+    const content = fs.readFileSync(skillPath, 'utf8');
+    const raw = extractFrontmatter(content, directory);
+    const parsed = parseYamlFrontmatter(raw, mode, directory);
+    const checked = validateFrontmatter(parsed.value, mode, directory, expectedName, source);
+    if (!checked)
+        return undefined;
+    const frontmatter = checked.frontmatter;
+    return {
+        name: frontmatter.name,
+        description: frontmatter.description,
+        directory: path.resolve(directory),
+        skillPath,
+        location: skillPath,
+        mountPath: `/skills/${frontmatter.name}`,
+        ...(frontmatter.license ? { license: frontmatter.license } : {}),
+        ...(frontmatter.compatibility ? { compatibility: frontmatter.compatibility } : {}),
+        ...(frontmatter.metadata ? { metadata: frontmatter.metadata } : {}),
+        ...(frontmatter['allowed-tools'] ? { allowedTools: frontmatter['allowed-tools'] } : {}),
+        trust: 'trusted',
+        ...(source ? { source } : {}),
+        diagnostics: [...parsed.diagnostics, ...checked.diagnostics]
+    };
 }
-function validateName(name) { return /^[a-z][a-z0-9-]*$/.test(name) && !/anthropic|claude|purista/i.test(name); }
 export function loadSkillsSync(skills) {
     const resolved = {};
     for (const [key, def] of Object.entries(skills)) {
-        const stat = fs.existsSync(def.directory) ? fs.statSync(def.directory) : null;
-        if (!stat?.isDirectory())
-            throw new SkillManifestError('Skill directory missing', { reason: 'directory_missing', directory: def.directory, skill_id: key });
-        const skillPath = path.join(def.directory, 'SKILL.md');
-        const content = fs.existsSync(skillPath) ? fs.readFileSync(skillPath, 'utf8') : null;
-        if (!content)
-            throw new SkillManifestError('missing SKILL.md', { reason: 'missing_skill_md', directory: def.directory, skill_id: key });
-        const { frontmatter } = parseFrontmatter(content);
-        const name = frontmatter['name'] ?? '';
-        const description = frontmatter['description'] ?? '';
-        if (!validateName(name) || description.length < 1 || description.length > 1024) {
-            throw new SkillManifestError('invalid frontmatter', { reason: 'invalid_frontmatter', directory: def.directory, skill_id: key });
-        }
-        if (name !== key)
-            throw new SkillManifestError('name mismatch', { reason: 'name_mismatch', directory: def.directory, skill_id: key });
-        resolved[key] = { name, description, directory: def.directory, ...(frontmatter['version'] ? { version: frontmatter['version'] } : {}) };
+        const skill = readSkill(path.resolve(def.directory), def.validationMode ?? 'strict', key, def.source);
+        if (!skill)
+            continue;
+        resolved[key] = {
+            ...skill,
+            trust: def.trust ?? 'trusted',
+            ...(def.source ? { source: def.source } : {})
+        };
     }
     return resolved;
 }
@@ -61,6 +194,9 @@ async function readDirRecursive(root) {
     return files;
 }
 export async function mountSkillsOnce(session, mounted, skills, skillIds) {
+    if (skillIds.length > 0 && typeof session.mount !== 'function') {
+        throw new SkillManifestError('Sandbox does not support skill mounting.', { reason: 'invalid_frontmatter', directory: '' });
+    }
     for (const skillId of skillIds) {
         if (mounted.has(skillId))
             continue;
@@ -68,15 +204,107 @@ export async function mountSkillsOnce(session, mounted, skills, skillIds) {
         if (!skill)
             throw new SkillNotFoundError('Skill not found.', { skill_id: skillId });
         const files = await readDirRecursive(skill.directory);
-        await session.mount(files, `/skills/${skillId}`);
+        await session.mount(files, skill.mountPath);
         mounted.add(skillId);
     }
 }
 export function buildSkillIndex(skills, ids) {
     if (ids.length === 0)
         return '';
-    const lines = ids.map((id) => `- ${skills[id]?.name ?? id}: ${skills[id]?.description ?? ''}`);
-    return `\n\nAvailable skills (read /skills/<name>/SKILL.md for full instructions):\n${lines.join('\n')}`;
+    const lines = ['', '', 'Available skills:'];
+    for (const id of ids) {
+        const skill = skills[id];
+        if (!skill)
+            continue;
+        lines.push(`- ${skill.name}: ${skill.description}`);
+        lines.push(`  Location: ${skill.mountPath}/SKILL.md`);
+        if (skill.compatibility)
+            lines.push(`  Compatibility: ${skill.compatibility}`);
+    }
+    lines.push('', 'Use the read tool to load /skills/<name>/SKILL.md when a skill is relevant.');
+    lines.push('Relative paths in a skill are relative to /skills/<name>/.');
+    return lines.join('\n');
+}
+function shouldSkipDirectory(name, clientName) {
+    if (skippedDirectories.has(name))
+        return true;
+    if (!name.startsWith('.'))
+        return false;
+    return name !== '.agents' && name !== '.claude' && (clientName ? name !== `.${clientName}` : true);
+}
+async function findSkillDirectories(root, opts) {
+    const out = [];
+    let visited = 0;
+    const walk = async (dir, depth) => {
+        if (visited >= opts.maxDirectories) {
+            opts.diagnostics.push(diagnostic('scan_limit_reached', 'Skill discovery directory limit reached.', { directory: dir }));
+            return;
+        }
+        visited += 1;
+        if (depth > opts.maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await fsp.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        if (entries.some((entry) => entry.isFile() && entry.name === 'SKILL.md')) {
+            out.push(dir);
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || shouldSkipDirectory(entry.name, opts.clientName))
+                continue;
+            await walk(path.join(dir, entry.name), depth + 1);
+        }
+    };
+    await walk(root, 0);
+    return out;
+}
+function addSkillConfig(target, name, def, diagnostics) {
+    if (target[name]) {
+        diagnostics.push(diagnostic('collision_shadowed', `Skill "${name}" was shadowed by a higher-precedence binding.`, { level: 'warn', skillName: name, directory: def.directory, source: def.source }));
+        return;
+    }
+    target[name] = def;
+}
+export async function discoverSkills(options = {}) {
+    const diagnostics = [];
+    const skills = {};
+    const validationMode = options.validationMode ?? 'lenient';
+    const maxDepth = options.maxDepth ?? 6;
+    const maxDirectories = options.maxDirectories ?? 2000;
+    const trustedRoots = new Set((options.trustedProjectRoots ?? []).map((root) => path.resolve(root)));
+    const projectRoot = path.resolve(options.projectRoot ?? process.env['PWD'] ?? '.');
+    const roots = [];
+    if (options.includeUserAgentsDir)
+        roots.push({ root: path.join(os.homedir(), '.agents', 'skills'), trust: 'user', source: 'user_agents', trusted: true });
+    if (options.includeUserClientDir && options.clientName)
+        roots.push({ root: path.join(os.homedir(), `.${options.clientName}`, 'skills'), trust: 'user', source: 'user_client', trusted: true });
+    if (options.includeProjectAgentsDir ?? true)
+        roots.push({ root: path.join(projectRoot, '.agents', 'skills'), trust: 'project', source: 'project_agents', trusted: trustedRoots.has(projectRoot) });
+    if (options.includeProjectClientDir && options.clientName)
+        roots.push({ root: path.join(projectRoot, `.${options.clientName}`, 'skills'), trust: 'project', source: 'project_client', trusted: trustedRoots.has(projectRoot) });
+    if (options.includeClaudeCompatDir)
+        roots.push({ root: path.join(projectRoot, '.claude', 'skills'), trust: 'project', source: 'project_claude', trusted: trustedRoots.has(projectRoot) });
+    for (const rootInfo of roots) {
+        if (!fs.existsSync(rootInfo.root))
+            continue;
+        if (rootInfo.trust === 'project' && !rootInfo.trusted) {
+            diagnostics.push(diagnostic('untrusted_project_skill', 'Project skill discovery root is not trusted.', { level: 'warn', directory: rootInfo.root, source: rootInfo.source }));
+            continue;
+        }
+        for (const directory of await findSkillDirectories(rootInfo.root, { maxDepth, maxDirectories, clientName: options.clientName, diagnostics })) {
+            const skill = readSkill(directory, validationMode, undefined, rootInfo.source);
+            if (!skill)
+                continue;
+            addSkillConfig(skills, skill.name, { directory, validationMode, trust: rootInfo.trust, source: rootInfo.source }, diagnostics);
+            diagnostics.push(...skill.diagnostics);
+        }
+    }
+    return { skills, diagnostics };
 }
 export function assertSerializable(value) {
     try {

package/dist/testing/durableWorkspaceStoreContract.d.ts

@@ -0,0 +1,3 @@
+import type { DurableWorkspaceStore } from '../ports/workspace.js';
+/** Shared Vitest contract for durable workspace store implementations. */
+export declare function durableWorkspaceStoreContract(make: () => DurableWorkspaceStore | Promise<DurableWorkspaceStore>): void;

package/dist/testing/durableWorkspaceStoreContract.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { validateDurableWorkspaceStore } from '../ports/workspace.js';
+/** Shared Vitest contract for durable workspace store implementations. */
+export function durableWorkspaceStoreContract(make) {
+    describe('durableWorkspaceStoreContract', () => {
+        it('validates metadata and round-trips checkpointed workspaces', async () => {
+            const adapter = await make();
+            validateDurableWorkspaceStore(adapter);
+            const signal = new AbortController().signal;
+            const handle = await adapter.startWorkspace({
+                sessionId: 'session-1',
+                runId: 'run-1',
+                agentId: 'agent-1',
+                attempt: 1,
+                idempotencyKey: 'start-1',
+                signal
+            });
+            const checkpoint = await adapter.pauseWorkspace({
+                handle,
+                stepId: 'step-1',
+                sequence: 1,
+                attempt: 1,
+                reason: 'step_completed',
+                idempotencyKey: 'pause-1',
+                signal
+            });
+            const resumed = await adapter.resumeWorkspace({
+                workspaceRef: handle.workspaceRef,
+                checkpointRef: checkpoint.checkpointRef,
+                sessionId: 'session-1',
+                runId: 'run-2',
+                attempt: 2,
+                idempotencyKey: 'resume-1',
+                signal
+            });
+            const inspection = await adapter.inspectWorkspace?.({ workspaceRef: resumed.workspaceRef, signal });
+            expect(resumed.workspaceRef).toBe(handle.workspaceRef);
+            expect(inspection?.checkpoints.map((item) => item.checkpointRef)).toEqual([checkpoint.checkpointRef]);
+        });
+    });
+}

package/dist/testing/index.d.ts

@@ -1,5 +1,7 @@
 export { FakeModelProvider } from './fakeModelProvider.js';
 export { FakeMemoryAdapter, memoryAdapterContract } from './fakeMemoryAdapter.js';
+export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from '../workspace/index.js';
+export { durableWorkspaceStoreContract } from './durableWorkspaceStoreContract.js';
 export { adapterCapabilitiesContract, fakeCapabilityAdapter, type FakeCapabilityAdapter } from './capabilities.js';
 export { createInMemoryFeedbackRecorder } from './feedback.js';
 export { evaluateDeterministicScorer } from '../eval/index.js';

package/dist/testing/index.js

@@ -1,6 +1,8 @@
 import { defineHarness } from '../harness/defineHarness.js';
 export { FakeModelProvider } from './fakeModelProvider.js';
 export { FakeMemoryAdapter, memoryAdapterContract } from './fakeMemoryAdapter.js';
+export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from '../workspace/index.js';
+export { durableWorkspaceStoreContract } from './durableWorkspaceStoreContract.js';
 export { adapterCapabilitiesContract, fakeCapabilityAdapter } from './capabilities.js';
 export { createInMemoryFeedbackRecorder } from './feedback.js';
 export { evaluateDeterministicScorer } from '../eval/index.js';

package/dist/workspace/in-memory.d.ts

@@ -0,0 +1,35 @@
+import type { DurableWorkspaceStore, WorkspaceAbortOptions, WorkspaceAbortResult, WorkspaceCheckpoint, WorkspaceCleanupOptions, WorkspaceCleanupResult, WorkspaceHandle, WorkspaceInspection, WorkspaceInspectionOptions, WorkspacePauseOptions, WorkspaceResumeOptions, WorkspaceStartOptions } from '../ports/workspace.js';
+/** In-process durable workspace store for local development, examples, and tests. */
+export declare class InMemoryDurableWorkspaceStore implements DurableWorkspaceStore {
+    readonly info: {
+        id: string;
+        packageName: string;
+        capabilities: readonly ["workspace_store.durable", "workspace_store.checkpoint", "workspace_store.resume", "workspace_store.abort", "workspace_store.cleanup", "workspace_store.inspect", "workspace_store.retention", "workspace_store.quota"];
+        policy: {
+            retention: {
+                pausedTtlMs: number;
+                terminalFailureTtlMs: number;
+                terminalSuccessTtlMs: number;
+                cleanupMode: "manual_only";
+            };
+            quota: {
+                maxActiveWorkspaces: number;
+                maxWorkspaceBytes: number;
+            };
+        };
+    };
+    readonly capabilities: readonly ["workspace_store.durable", "workspace_store.checkpoint", "workspace_store.resume", "workspace_store.abort", "workspace_store.cleanup", "workspace_store.inspect", "workspace_store.retention", "workspace_store.quota"];
+    private readonly workspaces;
+    private nextId;
+    configureHarnessContext(): 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>;
+    private findWorkspaceByCheckpoint;
+    private requireWorkspace;
+}
+/** Creates a fresh in-process durable workspace store. */
+export declare function inMemoryDurableWorkspaceStore(): DurableWorkspaceStore;

package/dist/workspace/in-memory.js

@@ -0,0 +1,142 @@
+/** In-process durable workspace store for local development, examples, and tests. */
+export class InMemoryDurableWorkspaceStore {
+    info = {
+        id: 'in_memory_workspace_store',
+        packageName: '@purista/harness',
+        capabilities: [
+            'workspace_store.durable',
+            'workspace_store.checkpoint',
+            'workspace_store.resume',
+            'workspace_store.abort',
+            'workspace_store.cleanup',
+            'workspace_store.inspect',
+            '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 }
+        }
+    };
+    capabilities = this.info.capabilities;
+    workspaces = new Map();
+    nextId = 1;
+    configureHarnessContext() { }
+    async startWorkspace(opts) {
+        opts.signal?.throwIfAborted();
+        const workspaceRef = `workspace_${this.nextId++}`;
+        const now = new Date().toISOString();
+        const metadata = { ...(opts.metadata ?? {}) };
+        const workspace = {
+            workspaceRef,
+            state: 'active',
+            runId: opts.runId,
+            sessionId: opts.sessionId,
+            attempt: opts.attempt,
+            createdAt: now,
+            updatedAt: now,
+            metadata,
+            checkpoints: []
+        };
+        this.workspaces.set(workspaceRef, workspace);
+        return { workspaceRef, runId: opts.runId, sessionId: opts.sessionId, state: 'active', startedAt: now, attempt: opts.attempt, metadata };
+    }
+    async pauseWorkspace(opts) {
+        opts.signal?.throwIfAborted();
+        const workspace = this.requireWorkspace(opts.handle.workspaceRef);
+        workspace.state = 'paused';
+        workspace.updatedAt = new Date().toISOString();
+        const checkpoint = {
+            workspaceRef: workspace.workspaceRef,
+            checkpointRef: `${workspace.workspaceRef}:checkpoint:${opts.sequence}`,
+            runId: workspace.runId,
+            sessionId: workspace.sessionId,
+            stepId: opts.stepId,
+            sequence: opts.sequence,
+            attempt: opts.attempt,
+            committedAt: workspace.updatedAt,
+            metadata: {
+                reason: opts.reason,
+                ...(opts.checkpointPayload !== undefined ? { checkpointPayload: opts.checkpointPayload } : {})
+            }
+        };
+        workspace.checkpoints.push(checkpoint);
+        return checkpoint;
+    }
+    async resumeWorkspace(opts) {
+        opts.signal?.throwIfAborted();
+        const workspace = this.requireWorkspace(opts.workspaceRef);
+        if (opts.checkpointRef && !workspace.checkpoints.some((checkpoint) => checkpoint.checkpointRef === opts.checkpointRef)) {
+            throw new Error(`Unknown workspace checkpoint: ${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
+        };
+    }
+    async abortWorkspace(opts) {
+        opts.signal?.throwIfAborted();
+        const workspace = this.requireWorkspace(opts.workspaceRef);
+        workspace.state = 'aborted';
+        workspace.updatedAt = new Date().toISOString();
+        return { workspaceRef: opts.workspaceRef, state: 'aborted', abortedAt: workspace.updatedAt };
+    }
+    async cleanupWorkspace(opts) {
+        opts.signal?.throwIfAborted();
+        const workspace = this.requireWorkspace(opts.workspaceRef);
+        workspace.state = 'cleaned';
+        workspace.updatedAt = new Date().toISOString();
+        this.workspaces.delete(opts.workspaceRef);
+        return { workspaceRef: opts.workspaceRef, state: 'cleaned', completedAt: workspace.updatedAt };
+    }
+    async inspectWorkspace(opts) {
+        opts.signal?.throwIfAborted();
+        const workspaceRef = opts.workspaceRef ?? this.findWorkspaceByCheckpoint(opts.checkpointRef);
+        const workspace = this.requireWorkspace(workspaceRef);
+        const latest = workspace.checkpoints.at(-1);
+        return {
+            workspaceRef: workspace.workspaceRef,
+            state: workspace.state,
+            checkpoints: workspace.checkpoints,
+            ...(latest ? { currentCheckpointRef: latest.checkpointRef } : {}),
+            retention: this.info.policy.retention,
+            quota: this.info.policy.quota,
+            createdAt: workspace.createdAt,
+            updatedAt: workspace.updatedAt,
+            metadata: workspace.metadata
+        };
+    }
+    findWorkspaceByCheckpoint(checkpointRef) {
+        if (!checkpointRef)
+            throw new Error('workspaceRef or checkpointRef is required.');
+        const found = [...this.workspaces.values()].find((workspace) => workspace.checkpoints.some((checkpoint) => checkpoint.checkpointRef === checkpointRef));
+        if (!found)
+            throw new Error(`Unknown workspace checkpoint: ${checkpointRef}`);
+        return found.workspaceRef;
+    }
+    requireWorkspace(workspaceRef) {
+        const workspace = this.workspaces.get(workspaceRef);
+        if (!workspace)
+            throw new Error(`Unknown workspace: ${workspaceRef}`);
+        return workspace;
+    }
+}
+/** Creates a fresh in-process durable workspace store. */
+export function inMemoryDurableWorkspaceStore() {
+    return new InMemoryDurableWorkspaceStore();
+}

package/dist/workspace/index.d.ts

@@ -0,0 +1 @@
+export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from './in-memory.js';

package/dist/workspace/index.js

@@ -0,0 +1 @@
+export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from './in-memory.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purista/harness",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Self-hosted enterprise agent harness for typed tools, agents, workflows, state, sandboxing, and telemetry.",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,8 @@
     "test:failure": "vitest run test/failure"
   },
   "dependencies": {
-    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -69,10 +70,10 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/context-async-hooks": "^2.7.1",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.1",
     "just-bash": "^3.0.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=24.15.0"