@purista/harness 1.1.0 → 1.2.1

package/dist/agents/index.js

@@ -1,10 +1,11 @@
 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';
 import { getMcpToolSpecs, invokeMcpTool, isMcpToolDefinition } from '../tools/mcp/runner.js';
+import { ulid } from '../ulid/index.js';
 function stringifyInput(input) { return typeof input === 'string' ? input : JSON.stringify(input); }
 function isReadonlyBuiltin(name) { return ['read', 'list', 'glob', 'grep'].includes(name); }
 async function checkPermission(agentId, runId, sessionId, def, toolName, input) {
@@ -76,6 +77,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,
@@ -89,13 +91,20 @@ async function runDefaultAgentInner(args) {
             metrics: args.metrics
         });
         const validated = parseAgentSchema(outputSchema, output, 'agent_output');
-        return { output: validated, emitted: [{ id: `msg_${Date.now()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() }] };
+        return { output: validated, emitted: [{ id: `msg_${ulid()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() }] };
     }
     const baseInstructions = typeof args.agent.instructions === 'function'
         ? args.agent.instructions({ input: parsedInput, runId: args.runId, sessionId: args.sessionId, history: { list: async () => args.history }, memory: args.memory, metadata: args.metadata ?? {}, metrics: args.metrics })
         : 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)
@@ -145,13 +154,13 @@ async function runDefaultAgentInner(args) {
         const toolCalls = response.toolCalls ?? [];
         if (toolCalls.length === 0) {
             const validated = parseAgentSchema(outputSchema, response.object, 'agent_output');
-            emitted.push({ id: `msg_${Date.now()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() });
+            emitted.push({ id: `msg_${ulid()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() });
             await args.emitEvent?.({ type: 'model.object', runId: args.runId, agentId: args.agentId, object: validated, usage: response.usage });
             await args.emitEvent?.({ type: 'agent.finished', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), output: validated });
             return { output: validated, emitted };
         }
         const assistantMsg = {
-            id: `msg_${Date.now()}_assistant`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: '', toolCalls,
+            id: `msg_${ulid()}_assistant`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: '', toolCalls,
             timestamp: new Date().toISOString()
         };
         emitted.push(assistantMsg);
@@ -171,7 +180,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' });
@@ -216,7 +228,7 @@ async function runDefaultAgentInner(args) {
             }
             await args.emitEvent?.({ type: 'tool.finished', runId: args.runId, agentId: args.agentId, toolId: canonical, callId: call.id, ...(result.output !== undefined ? { output: result.output } : {}), ...(result.error ? { error: result.error } : {}) });
             const toolMessage = {
-                id: `msg_${Date.now()}_${call.id}`,
+                id: `msg_${ulid()}_${call.id}`,
                 sessionId: args.sessionId,
                 runId: args.runId,
                 role: 'tool',
@@ -230,6 +242,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
+        });
+    }
+}