@purista/harness 1.0.0 → 1.2.0

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/telemetry/shim.d.ts

@@ -1,5 +1,14 @@
 /** Attributes accepted by telemetry span/metric helpers. */
 export type SpanAttrs = Record<string, string | number | boolean | string[] | undefined>;
+/** Developer-facing metric helper exposed in handler contexts. */
+export interface Metrics {
+    /** Adds to a counter instrument. */
+    counter(name: string, value?: number, attrs?: SpanAttrs): void;
+    /** Records a histogram sample. */
+    histogram(name: string, value: number, attrs?: SpanAttrs): void;
+    /** Records the duration of an async operation in seconds. */
+    duration<T>(name: string, attrs: SpanAttrs | undefined, fn: () => Promise<T>): Promise<T>;
+}
 /** Minimal telemetry abstraction used by harness internals and integrations. */
 export interface TelemetryShim {
     /** Creates a span, executes `fn`, and closes the span with success/error status. */
@@ -10,6 +19,11 @@ export interface TelemetryShim {
     recordCounter(name: string, value: number, attrs: SpanAttrs): void;
     /** Injects the current active trace context into a W3C traceparent carrier. */
     currentTraceparent(): string | undefined;
+    /** Runs `fn` with the supplied W3C Trace Context as the active parent context. */
+    withTraceContext?<T>(carrier: {
+        traceparent: string;
+        tracestate?: string;
+    }, fn: () => Promise<T>): Promise<T>;
 }
 /** OpenTelemetry-backed implementation of {@link TelemetryShim}. */
 export declare class OtelTelemetryShim implements TelemetryShim {
@@ -21,6 +35,12 @@ export declare class OtelTelemetryShim implements TelemetryShim {
     recordHistogram(name: string, value: number, attrs: SpanAttrs): void;
     recordCounter(name: string, value: number, attrs: SpanAttrs): void;
     currentTraceparent(): string | undefined;
+    withTraceContext<T>(carrier: {
+        traceparent: string;
+        tracestate?: string;
+    }, fn: () => Promise<T>): Promise<T>;
 }
 /** Creates the default telemetry shim instance. */
 export declare function createTelemetryShim(): TelemetryShim;
+/** Creates a scoped metrics helper with default attributes merged into every metric. */
+export declare function createMetrics(telemetry: TelemetryShim, defaultAttrs?: SpanAttrs): Metrics;

package/dist/telemetry/shim.js

@@ -113,8 +113,36 @@ export class OtelTelemetryShim {
         propagation.inject(context.active(), carrier);
         return carrier['traceparent'];
     }
+    async withTraceContext(carrier, fn) {
+        const extracted = propagation.extract(context.active(), {
+            traceparent: carrier.traceparent,
+            ...(carrier.tracestate ? { tracestate: carrier.tracestate } : {})
+        });
+        return context.with(extracted, fn);
+    }
 }
 /** Creates the default telemetry shim instance. */
 export function createTelemetryShim() {
     return new OtelTelemetryShim();
 }
+/** Creates a scoped metrics helper with default attributes merged into every metric. */
+export function createMetrics(telemetry, defaultAttrs = {}) {
+    const merge = (attrs) => ({ ...defaultAttrs, ...(attrs ?? {}) });
+    return {
+        counter(name, value = 1, attrs) {
+            telemetry.recordCounter(name, value, merge(attrs));
+        },
+        histogram(name, value, attrs) {
+            telemetry.recordHistogram(name, value, merge(attrs));
+        },
+        async duration(name, attrs, fn) {
+            const started = Date.now();
+            try {
+                return await fn();
+            }
+            finally {
+                telemetry.recordHistogram(name, (Date.now() - started) / 1000, merge(attrs));
+            }
+        }
+    };
+}

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

@@ -0,0 +1,16 @@
+import type { MemoryAdapter, MemoryOpenContext, MemoryScope, MemoryStore } from '../ports/memory.js';
+/** Deterministic in-memory adapter for unit tests and adapter contract examples. */
+export declare class FakeMemoryAdapter implements MemoryAdapter {
+    readonly info: {
+        id: string;
+        packageName: string;
+        capabilities: readonly ["memory.kv", "memory.list", "memory.delete", "memory.search", "memory.run", "memory.session", "memory.agent", "memory.user", "memory.tenant", "memory.persistent"];
+    };
+    readonly capabilities: readonly ["memory.kv", "memory.list", "memory.delete", "memory.search", "memory.run", "memory.session", "memory.agent", "memory.user", "memory.tenant", "memory.persistent"];
+    readonly openedScopes: MemoryScope[];
+    private readonly values;
+    configureHarnessContext(): void;
+    open(scope: MemoryScope, _ctx: MemoryOpenContext): Promise<MemoryStore>;
+}
+/** Shared contract for memory adapters. */
+export declare function memoryAdapterContract(make: () => MemoryAdapter | Promise<MemoryAdapter>): void;

package/dist/testing/fakeMemoryAdapter.js

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+/** Deterministic in-memory adapter for unit tests and adapter contract examples. */
+export class FakeMemoryAdapter {
+    info = {
+        id: 'fake_memory',
+        packageName: '@purista/harness/testing',
+        capabilities: [
+            'memory.kv',
+            'memory.list',
+            'memory.delete',
+            'memory.search',
+            'memory.run',
+            'memory.session',
+            'memory.agent',
+            'memory.user',
+            'memory.tenant',
+            'memory.persistent'
+        ]
+    };
+    capabilities = this.info.capabilities;
+    openedScopes = [];
+    values = new Map();
+    configureHarnessContext() {
+        // Fake adapter does not need inherited services, but implements the hook so contract users can assert it is called.
+    }
+    async open(scope, _ctx) {
+        this.openedScopes.push(scope);
+        const prefix = scopeKey(scope);
+        return {
+            get: async (key, ctx) => {
+                ctx.signal.throwIfAborted();
+                return this.values.get(`${prefix}:${key}`);
+            },
+            set: async (key, value, ctx) => {
+                ctx.signal.throwIfAborted();
+                this.values.set(`${prefix}:${key}`, value);
+            },
+            delete: async (key, ctx) => {
+                ctx.signal.throwIfAborted();
+                this.values.delete(`${prefix}:${key}`);
+            },
+            list: async (ctx) => {
+                ctx.signal.throwIfAborted();
+                const keys = [...this.values.keys()]
+                    .filter((key) => key.startsWith(`${prefix}:`))
+                    .map((key) => key.slice(prefix.length + 1))
+                    .filter((key) => !ctx.opts?.prefix || key.startsWith(ctx.opts.prefix))
+                    .filter((key) => !ctx.opts?.cursor || key > ctx.opts.cursor)
+                    .sort()
+                    .slice(0, ctx.opts?.limit);
+                return keys.map((key) => ({ key }));
+            },
+            search: async (query, ctx) => {
+                ctx.signal.throwIfAborted();
+                return [...this.values.entries()]
+                    .filter(([key]) => key.startsWith(`${prefix}:`))
+                    .map(([key, value]) => ({ key: key.slice(prefix.length + 1), value, score: JSON.stringify(value).includes(query.text) ? 1 : 0 }))
+                    .filter((result) => result.score > 0)
+                    .sort((a, b) => (b.score ?? 0) - (a.score ?? 0) || a.key.localeCompare(b.key))
+                    .slice(0, query.limit);
+            }
+        };
+    }
+}
+/** Shared contract for memory adapters. */
+export function memoryAdapterContract(make) {
+    describe('memoryAdapterContract', () => {
+        it('round-trips scoped JSON values', async () => {
+            const adapter = await make();
+            const ctx = contractContext();
+            const store = await adapter.open({ kind: 'session', sessionId: 's1' }, ctx);
+            await store.set('foo', { a: 1 }, { ...ctx, scope: { kind: 'session', sessionId: 's1' }, operation: 'set' });
+            await expect(store.get('foo', { ...ctx, scope: { kind: 'session', sessionId: 's1' }, operation: 'get' })).resolves.toEqual({ a: 1 });
+        });
+        it('isolates scopes', async () => {
+            const adapter = await make();
+            const ctx = contractContext();
+            const one = await adapter.open({ kind: 'session', sessionId: 's1' }, ctx);
+            const two = await adapter.open({ kind: 'session', sessionId: 's2' }, ctx);
+            await one.set('foo', 'one', { ...ctx, scope: { kind: 'session', sessionId: 's1' }, operation: 'set' });
+            await expect(two.get('foo', { ...ctx, scope: { kind: 'session', sessionId: 's2' }, operation: 'get' })).resolves.toBeUndefined();
+        });
+    });
+}
+function scopeKey(scope) {
+    return [
+        scope.kind,
+        scope.tenantId,
+        scope.userId,
+        scope.sessionId,
+        scope.runId,
+        scope.workflowId,
+        scope.agentId
+    ].filter(Boolean).join(':');
+}
+function contractContext() {
+    const signal = new AbortController().signal;
+    return {
+        logger: { trace() { }, debug() { }, info() { }, warn() { }, error() { }, fatal() { }, child: () => contractContext().logger },
+        telemetry: {
+            span: async (_name, _attrs, fn) => fn({ setAttribute: () => undefined, setAttributes: () => undefined, addEvent: () => undefined, recordException: () => undefined, setStatus: () => undefined, end: () => undefined, spanContext: () => ({ traceId: '', spanId: '', traceFlags: 0 }), isRecording: () => false, updateName: () => undefined }),
+            recordHistogram() { },
+            recordCounter() { },
+            currentTraceparent: () => undefined
+        },
+        metrics: { counter() { }, histogram() { }, duration: async (_name, _attrs, fn) => fn() },
+        contentCaptureMode: 'NO_CONTENT',
+        signal
+    };
+}

package/dist/testing/index.d.ts

@@ -1,6 +1,11 @@
 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';
+export type { DeterministicScorerDefinition, ScorerResult, ScorerTarget } from '../eval/index.js';
 export { sandboxContract } from './sandboxContract.js';
 export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
 export { stateStoreContract } from './stateStoreContract.js';

package/dist/testing/index.js

@@ -1,7 +1,11 @@
 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';
 export { sandboxContract } from './sandboxContract.js';
 export { fakeSnapshotSandbox, sandboxSnapshotContract } from './sandboxSnapshot.js';
 export { stateStoreContract } from './stateStoreContract.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;