@purista/harness 1.1.0 → 1.2.1

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/tools/index.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { SandboxNoExecutorError, ToolNotFoundError, ValidationError, serializeError } from '../errors/index.js';
+import { ulid } from '../ulid/index.js';
 export const BUILTIN_ALIAS_TO_CANONICAL = {
     bash: 'bash', Bash: 'bash',
     read: 'read', Read: 'read',
@@ -113,7 +114,7 @@ export async function invokeBuiltinTool(nameOrAlias, input, session, signal) {
 }
 export function toToolErrorMessage(toolCallId, error) {
     return {
-        id: `msg_${Date.now()}`,
+        id: `msg_${ulid()}`,
         sessionId: '',
         role: 'tool',
         content: '',

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';