@purista/harness 1.2.5 → 1.5.0

package/dist/harness/defineHarness.js

@@ -3,6 +3,7 @@ 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 { validateContextCheckpointStore } from '../ports/context-checkpoints.js';
 import { InMemoryStateStore } from '../state/in-memory.js';
 import { HarnessConfigError, SkillManifestError } from '../errors/catalog.js';
 import { BUILTIN_TOOL_NAMES } from '../tools/index.js';
@@ -47,6 +48,13 @@ class Builder {
         validateDurableWorkspaceStore(workspaceStore);
         return this.clone({ workspaceStore });
     }
+    checkpoints(checkpoints) {
+        if (this.configured.checkpoints) {
+            throw new HarnessConfigError('Context checkpoint store is already configured.', { reason: 'duplicate_adapter', path: 'checkpoints' });
+        }
+        validateContextCheckpointStore(checkpoints);
+        return this.clone({ checkpoints });
+    }
     requires(capabilities) {
         return this.clone({ requiredCapabilities: uniqueCapabilities(capabilities) });
     }
@@ -57,6 +65,9 @@ class Builder {
         if (defaults.maxParallelToolCalls !== undefined && (!Number.isInteger(defaults.maxParallelToolCalls) || defaults.maxParallelToolCalls < 1)) {
             throw new HarnessConfigError('maxParallelToolCalls must be a positive integer', { reason: 'invalid_defaults', path: 'defaults.maxParallelToolCalls' });
         }
+        validateDelegationBudget(defaults.delegation?.maxChildAgentCalls, 'defaults.delegation.maxChildAgentCalls', { min: 0 });
+        validateDelegationBudget(defaults.delegation?.maxParallelChildAgentCalls, 'defaults.delegation.maxParallelChildAgentCalls', { min: 1 });
+        validateDelegationBudget(defaults.delegation?.maxDepth, 'defaults.delegation.maxDepth', { min: 0 });
         return this.clone({ defaults });
     }
     models(models) {
@@ -87,6 +98,7 @@ class Builder {
         const resolved = typeof workflows === 'function'
             ? workflows({ workflow: (definition) => definition })
             : workflows;
+        this.validateWorkflowDelegationPolicies(resolved);
         return this.clone({ workflows: resolved });
     }
     build() {
@@ -95,11 +107,16 @@ class Builder {
             throw new HarnessConfigError('At least one model alias is required.', { reason: 'missing_models', path: 'models' });
         }
         this.validateToolSkillNamespace();
+        // Validated at build time (not in `.agents(...)`) because models may be
+        // declared later in the builder chain.
+        this.validateAgentModelAndToolReferences(models);
         const sandbox = this.configured.sandbox ?? autoDetectSandbox();
         const memory = this.configured.memory ?? sandboxMemory();
         validateMemoryAdapter(memory);
         if (this.configured.workspaceStore)
             validateDurableWorkspaceStore(this.configured.workspaceStore);
+        if (this.configured.checkpoints)
+            validateContextCheckpointStore(this.configured.checkpoints);
         const inspection = this.resolveInspection(this.options.name ?? 'agent-harness', sandbox, memory, models);
         const missing = missingCapabilities(inspection.requiredCapabilities, inspection.capabilities);
         if (missing.length > 0) {
@@ -118,6 +135,7 @@ class Builder {
             memory,
             ...(this.configured.runtime ? { runtime: this.configured.runtime } : {}),
             ...(this.configured.workspaceStore ? { workspaceStore: this.configured.workspaceStore } : {}),
+            ...(this.configured.checkpoints ? { checkpoints: this.configured.checkpoints } : {}),
             defaults: {
                 agentMaxIterations: this.configured.defaults?.agentMaxIterations ?? 16,
                 runTimeoutMs: this.configured.defaults?.runTimeoutMs ?? 600_000,
@@ -125,7 +143,8 @@ class Builder {
                 skillTimeoutMs: this.configured.defaults?.skillTimeoutMs ?? 60_000,
                 modelTimeoutMs: this.configured.defaults?.modelTimeoutMs ?? 300_000,
                 maxParallelToolCalls: this.configured.defaults?.maxParallelToolCalls ?? 8,
-                ...(this.configured.defaults?.historyWindow !== undefined ? { historyWindow: this.configured.defaults.historyWindow } : {})
+                ...(this.configured.defaults?.historyWindow !== undefined ? { historyWindow: this.configured.defaults.historyWindow } : {}),
+                ...(this.configured.defaults?.delegation ? { delegation: this.configured.defaults.delegation } : {})
             },
             models,
             tools: (this.configured.tools ?? {}),
@@ -175,6 +194,27 @@ class Builder {
             }
         }
     }
+    validateAgentModelAndToolReferences(models) {
+        const configuredTools = new Set(Object.keys(this.configured.tools ?? {}));
+        for (const [agentId, agent] of Object.entries(this.configured.agents ?? {})) {
+            if (!(agent.model in models)) {
+                throw new HarnessConfigError('Agent references an unknown model alias.', {
+                    reason: 'invalid_agent',
+                    path: `agents.${agentId}.model`,
+                    id: agent.model
+                });
+            }
+            for (const toolId of agent.tools ?? []) {
+                if (!configuredTools.has(toolId)) {
+                    throw new HarnessConfigError('Agent references an unknown tool.', {
+                        reason: 'invalid_agent',
+                        path: `agents.${agentId}.tools`,
+                        id: toolId
+                    });
+                }
+            }
+        }
+    }
     validateAgentSkillReferences(agents) {
         const configuredSkills = new Set(Object.keys(this.configured.skills ?? {}));
         for (const [agentId, agent] of Object.entries(agents)) {
@@ -189,6 +229,54 @@ class Builder {
             }
         }
     }
+    validateWorkflowDelegationPolicies(workflows) {
+        const configuredAgents = new Set(Object.keys(this.configured.agents ?? {}));
+        const configuredModels = new Set(Object.keys(this.configured.models ?? {}));
+        for (const [workflowId, workflow] of Object.entries(workflows)) {
+            const policy = workflow.delegation;
+            if (!policy)
+                continue;
+            validateDelegationBudget(policy.maxChildAgentCalls, `workflows.${workflowId}.delegation.maxChildAgentCalls`, { min: 0 });
+            validateDelegationBudget(policy.maxParallelChildAgentCalls, `workflows.${workflowId}.delegation.maxParallelChildAgentCalls`, { min: 1 });
+            validateDelegationBudget(policy.maxDepth, `workflows.${workflowId}.delegation.maxDepth`, { min: 0 });
+            for (const agentId of policy.agents ?? []) {
+                if (!configuredAgents.has(agentId)) {
+                    throw new HarnessConfigError('Workflow delegation policy references an unknown agent.', {
+                        reason: 'invalid_workflow',
+                        path: `workflows.${workflowId}.delegation.agents`,
+                        id: agentId
+                    });
+                }
+            }
+            for (const alias of policy.modelAliases ?? []) {
+                if (!configuredModels.has(alias)) {
+                    throw new HarnessConfigError('Workflow delegation policy references an unknown model alias.', {
+                        reason: 'invalid_workflow',
+                        path: `workflows.${workflowId}.delegation.modelAliases`,
+                        id: alias
+                    });
+                }
+            }
+            for (const [agentId, aliases] of Object.entries(policy.agentModelAliases ?? {})) {
+                if (!configuredAgents.has(agentId)) {
+                    throw new HarnessConfigError('Workflow delegation policy references an unknown agent.', {
+                        reason: 'invalid_workflow',
+                        path: `workflows.${workflowId}.delegation.agentModelAliases.${agentId}`,
+                        id: agentId
+                    });
+                }
+                for (const alias of aliases ?? []) {
+                    if (!configuredModels.has(alias)) {
+                        throw new HarnessConfigError('Workflow delegation policy references an unknown model alias.', {
+                            reason: 'invalid_workflow',
+                            path: `workflows.${workflowId}.delegation.agentModelAliases.${agentId}`,
+                            id: alias
+                        });
+                    }
+                }
+            }
+        }
+    }
     resolveInspection(name, sandbox, memory, models) {
         const adapters = [];
         const sandboxCapabilities = hasAdapterCapabilities(sandbox) ? uniqueCapabilities(sandbox.capabilities) : [];
@@ -224,6 +312,16 @@ class Builder {
                 }
             });
         }
+        if (this.configured.checkpoints) {
+            adapters.push({
+                kind: 'context_checkpoint',
+                id: this.configured.checkpoints.info.id,
+                capabilities: uniqueCapabilities(this.configured.checkpoints.info.capabilities),
+                metadata: {
+                    packageName: this.configured.checkpoints.info.packageName
+                }
+            });
+        }
         for (const [alias, model] of Object.entries(models)) {
             adapters.push({
                 kind: 'model',
@@ -253,6 +351,16 @@ function getAdapterId(adapter, fallback) {
     }
     return fallback;
 }
+function validateDelegationBudget(value, path, opts) {
+    if (value === undefined)
+        return;
+    if (!Number.isInteger(value) || value < opts.min) {
+        throw new HarnessConfigError(`${path} must be an integer >= ${opts.min}`, {
+            reason: 'invalid_defaults',
+            path
+        });
+    }
+}
 /**
  * Creates the chainable harness builder used to define a harness system.
  *
@@ -268,6 +376,7 @@ function getAdapterId(adapter, fallback) {
  *     summarize_ticket: {
  *       input: z.object({ ticket: z.string() }),
  *       output: z.string(),
+ *       delegation: { agents: ['summarize'] },
  *       handler: (ctx) => ctx.agents.summarize(ctx.input.ticket)
  *     }
  *   })

package/dist/index.d.ts

@@ -1,18 +1,38 @@
-export * from './errors/index.js';
-export * from './logger/index.js';
-export * from './telemetry/index.js';
-export * from './ulid/index.js';
-export * from './ports/index.js';
-export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isTerminalRunStatus } from './runtime/index.js';
+export { HarnessError, isHarnessError, HarnessConfigError, ValidationError, PermissionDeniedError, SandboxError, SandboxNoExecutorError, ModelError, ModelCapabilityError, ToolError, ToolNotFoundError, SkillNotFoundError, SkillManifestError, AgentNotFoundError, AgentLoopBudgetError, DelegationPolicyError, WorkflowNotFoundError, SessionNotFoundError, SessionBusyError, StateError, WorkspaceError, WorkspaceQuotaExceededError, WorkspaceCleanupError, OperationTimeoutError, OperationCancelledError, McpProtocolError, McpAuthError, InternalError, sanitizeProviderMessage, serializeError } from './errors/index.js';
+export type { ErrorCategory } from './errors/index.js';
+export { JsonLogger } from './logger/index.js';
+export type { Logger, LogLevel } from './logger/index.js';
+export type { Metrics, SpanAttrs, TelemetryShim } from './telemetry/index.js';
+export { ulid } from './ulid/index.js';
+export { HARNESS_VERSION } from './version.js';
+export { BaseModelProvider } from './ports/base-model-provider.js';
+export type { BaseModelProviderOptions } from './ports/base-model-provider.js';
+export type { BaseRequest, ContentPart, ContentPartKind, Embedding, EmbeddingRequest, EmbeddingResponse, FinishReason, ModelAlias, ModelCallOptions, ModelCapability, ModelDefaults, ModelFeatureSet, ModelMessage, ModelOutcome, ModelProvider, ModelProviderInfo, ModelRateLimitInfo, ModelRetryKind, ModelRetryOnPolicy, ModelRetryPolicy, ModelRetrySetting, ModelToolSpec, ObjectRequest, ObjectResponse, ObjectStreamChunk, OutputMode, ProviderItems, RerankDocument, RerankRequest, RerankResponse, RerankResult, TextRequest, TextResponse, TextStreamChunk, TokenUsage, ToolCallSpec } from './ports/model-provider.js';
+export type { ModelHandle, ModelInvokeContext } from './models/registry.js';
+export { accumulateStreamToolCallDeltas, createStreamToolCallState, finalizeStreamToolCalls, malformedResponseError, parseProviderJson, redactProviderContent, safePartialJson, toTokenUsage, withoutObjectTool } from './models/adapter-utils.js';
+export type { AdapterCallContext, StreamToolCallState } from './models/adapter-utils.js';
+export type { AdapterCapabilities, AdapterCapability, AdapterInspection, DurableRuntimeAdapter, HarnessInspection } from './ports/capabilities.js';
+export type { HarnessAdapterContext, HarnessContextConfigurable } from './ports/harness-context.js';
+export { StateStoreAdapterBase } from './ports/state.js';
+export type { StateStore } from './ports/state.js';
+export { InMemoryStateStore } from './state/in-memory.js';
+export type { JsonValue } from './models/json.js';
+export type { Message, PersistedRunEvent, RunRecord, RunStatus, SessionRecord } from './models/state.js';
+export type { MemoryAdapter, MemoryAdapterInfo, MemoryCapability, MemoryEntry, MemoryFacade, MemoryListOptions, MemoryOpenContext, MemoryOperation, MemoryOperationContext, MemoryScope, MemoryScopeKind, MemorySearchQuery, MemorySearchResult, MemoryStore, MemoryWriteOptions, SessionMemory } from './ports/memory.js';
+export { sandboxMemory } from './memory/sandbox/index.js';
+export type { FeedbackRecord, FeedbackTarget } from './ports/feedback.js';
+export type { DurableReplayCheckpoint, DurableWorkspacePolicy, DurableWorkspaceStore, DurableWorkspaceStoreInfo, WorkspaceAbortOptions, WorkspaceAbortResult, WorkspaceCheckpoint, WorkspaceCleanupOptions, WorkspaceCleanupResult, WorkspaceEncryptionInfo, WorkspaceHandle, WorkspaceInspection, WorkspaceInspectionOptions, WorkspaceLifecycleState, WorkspacePauseOptions, WorkspaceQuotaPolicy, WorkspaceResumeOptions, WorkspaceRetentionPolicy, WorkspaceStartOptions } from './ports/workspace.js';
+export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from './workspace/index.js';
+export type { ContextCheckpoint, ContextCheckpointQuery, ContextCheckpointRef, ContextCheckpointStore, ContextCheckpointStoreInfo } from './ports/context-checkpoints.js';
+export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isResumeBlockingRunStatus, isTerminalRunStatus } from './runtime/index.js';
 export type { DurableActiveRunStatus, DurableWorkflowContext, DurableWorkflowContextOptions, DurableStepCommit, DurableRunLease, DurableRunStart, DurableRunStatus, DurableRuntime, DurableTerminalRunStatus, FinishRunPatch, InMemoryDurableRuntimeOptions, RunCheckpoint } from './runtime/index.js';
-export * from './state/in-memory.js';
-export * from './models/json.js';
-export type { SessionRecord, Message, RunRecord, PersistedRunEvent, RunStatus } from './models/state.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';
+export { bashSandbox, inMemorySandbox } from './sandbox/index.js';
+export type { ExecCapableSandboxSession, HibernateCapableSandbox, ResumeCapableSandbox, Sandbox, SandboxProcess, SandboxResumeOptions, SandboxSession, SandboxSessionBase, SandboxSessionFor, SnapshotCapableSandbox, SnapshotResult, SpawnCapableSandboxSession, SpawnOptions } from './sandbox/index.js';
+export type { DirEntry, ExecOptions, ExecResult, FileStat } from './harness/types.js';
+export { localDirectorySandbox, localDirectoryWorkspaceStore, localDurableExecution, SqliteHarnessStorage, sqliteContextCheckpointStore, sqliteDurableRuntime, sqliteStateStore } from './local/index.js';
+export type { LocalDirectorySandboxOptions, LocalDirectoryWorkspaceStoreOptions, LocalDurableExecution, LocalDurableExecutionOptions, LocalDurableSandbox, LocalExecSandboxCapabilities, LocalFilesOnlySandboxCapabilities, LocalHostExecPolicy, SqliteContextCheckpointStoreOptions, SqliteDurableRuntimeOptions, SqliteStateStoreOptions } from './local/index.js';
+export { discoverSkills } from './skills/index.js';
+export { evaluateDeterministicScorer, evaluatePromptCandidates } from './eval/index.js';
+export type { CandidateScore, DeterministicScorerDefinition, EvaluatePromptCandidatesInput, EvaluationItem, PromptCandidate, ScorerResult, ScorerTarget } from './eval/index.js';
+export { defineHarness } from './harness/defineHarness.js';
+export type { AgentContext, AgentContextMinimal, AgentDefinition, AgentDefinitionHelpers, AgentInput, AgentInvoker, AgentOutput, AgentPermissions, AgentsConfig, BuilderState, BuiltinToolName, ContentCaptureMode, ContextCheckpoints, ConversationHistory, DelegationDefaults, DiscoveredSkills, DiscoverSkillsOptions, DurableInvokeOptions, Harness, HarnessBuilder, HarnessDefaults, HarnessOptions, InferTypes, InvokeOptions, McpAuth, McpHttpToolDefinition, McpStdioToolDefinition, ModelHandles, ModelsConfig, OnPermission, PermissionContext, PermissionDecision, PermissionMode, PermissionPolicy, ResolvedSkill, RunEvent, RunSummary, SerializedError, Session, SkillDefinition, SkillDiagnostic, SkillFrontmatter, SkillsConfig, SkillValidationMode, TelemetryFlavor, TelemetryOptions, ToolDefinition, ToolHandlerContext, ToolsConfig, TsToolDefinition, WorkflowAgentInvokeOptions, WorkflowContext, WorkflowDefinition, WorkflowDefinitionHelpers, WorkflowDelegationPolicy, WorkflowInput, WorkflowInvoker, WorkflowOutput, WorkflowsConfig } from './harness/defineHarness.js';

package/dist/index.js

@@ -1,16 +1,30 @@
-export * from './errors/index.js';
-export * from './logger/index.js';
-export * from './telemetry/index.js';
-export * from './ulid/index.js';
-export * from './ports/index.js';
-export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isTerminalRunStatus } from './runtime/index.js';
-export * from './state/in-memory.js';
-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';
+// Public surface of `@purista/harness`. The export lists below are locked by
+// specs/13-public-api.md and verified by test/public-api.test.ts — keep all
+// three in sync when changing any export.
+// Errors (specs/15-error-catalog.md)
+export { HarnessError, isHarnessError, HarnessConfigError, ValidationError, PermissionDeniedError, SandboxError, SandboxNoExecutorError, ModelError, ModelCapabilityError, ToolError, ToolNotFoundError, SkillNotFoundError, SkillManifestError, AgentNotFoundError, AgentLoopBudgetError, DelegationPolicyError, WorkflowNotFoundError, SessionNotFoundError, SessionBusyError, StateError, WorkspaceError, WorkspaceQuotaExceededError, WorkspaceCleanupError, OperationTimeoutError, OperationCancelledError, McpProtocolError, McpAuthError, InternalError, sanitizeProviderMessage, serializeError } from './errors/index.js';
+// Foundation: logger, telemetry shim types, ULID, version
+export { JsonLogger } from './logger/index.js';
+export { ulid } from './ulid/index.js';
+export { HARNESS_VERSION } from './version.js';
+// Model provider port
+export { BaseModelProvider } from './ports/base-model-provider.js';
+// Shared model adapter helpers (consumed by first-party provider packages)
+export { accumulateStreamToolCallDeltas, createStreamToolCallState, finalizeStreamToolCalls, malformedResponseError, parseProviderJson, redactProviderContent, safePartialJson, toTokenUsage, withoutObjectTool } from './models/adapter-utils.js';
+// State port + in-memory default
+export { StateStoreAdapterBase } from './ports/state.js';
+export { InMemoryStateStore } from './state/in-memory.js';
+export { sandboxMemory } from './memory/sandbox/index.js';
+export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from './workspace/index.js';
+// Durable runtime
+export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isResumeBlockingRunStatus, isTerminalRunStatus } from './runtime/index.js';
+// Sandbox port + default factories
+export { bashSandbox, inMemorySandbox } from './sandbox/index.js';
+// Local durable execution
+export { localDirectorySandbox, localDirectoryWorkspaceStore, localDurableExecution, SqliteHarnessStorage, sqliteContextCheckpointStore, sqliteDurableRuntime, sqliteStateStore } from './local/index.js';
+// Skills discovery
+export { discoverSkills } from './skills/index.js';
+// AI evaluation core
+export { evaluateDeterministicScorer, evaluatePromptCandidates } from './eval/index.js';
+// Builder, harness, session, and handler context types
+export { defineHarness } from './harness/defineHarness.js';

package/dist/local/index.d.ts

@@ -0,0 +1,36 @@
+import type { StateStore } from '../ports/state.js';
+import type { DurableRuntime } from '../runtime/durable.js';
+import type { DurableWorkspacePolicy, DurableWorkspaceStore } from '../ports/workspace.js';
+import type { ContextCheckpointStore } from '../ports/context-checkpoints.js';
+import { type LocalDurableSandbox, type LocalHostExecPolicy } from './local-sandbox.js';
+export type { LocalHostExecPolicy, LocalDirectorySandboxOptions, LocalDurableSandbox, LocalFilesOnlySandboxCapabilities, LocalExecSandboxCapabilities } from './local-sandbox.js';
+export type { LocalDirectoryWorkspaceStoreOptions } from './local-workspace.js';
+export type { SqliteDurableRuntimeOptions, SqliteContextCheckpointStoreOptions, SqliteStateStoreOptions } from './sqlite-storage.js';
+export { localDirectorySandbox } from './local-sandbox.js';
+export { localDirectoryWorkspaceStore } from './local-workspace.js';
+export { sqliteContextCheckpointStore, sqliteDurableRuntime, sqliteStateStore, SqliteHarnessStorage } from './sqlite-storage.js';
+export interface LocalDurableExecutionOptions {
+    /** Host directory used for SQLite files, active workspaces, and snapshots. */
+    root: string;
+    /** SQLite database file. Default: `${root}/runtime.sqlite`. */
+    databaseFile?: string;
+    /** Stable worker id reserved for future policies. */
+    workerId?: string;
+    /** Host command execution policy. Default: `false`. */
+    exec?: false | LocalHostExecPolicy;
+    /** Workspace retention/quota/encryption metadata reported by the store. */
+    policy?: Partial<DurableWorkspacePolicy>;
+    /** Lease takeover window for crashed workers. Default: `120_000`. */
+    leaseTtlMs?: number;
+}
+export interface LocalDurableExecution {
+    state: StateStore;
+    runtime: DurableRuntime;
+    /** Files-only by default; advertises `sandbox.exec` only when `exec` is configured (spec 22 §2). */
+    sandbox: LocalDurableSandbox;
+    workspaceStore: DurableWorkspaceStore;
+    checkpoints: ContextCheckpointStore;
+    close(): Promise<void>;
+}
+/** Creates the recommended local durable adapter bundle for single-host usage. */
+export declare function localDurableExecution(options: LocalDurableExecutionOptions): LocalDurableExecution;

package/dist/local/index.js

@@ -0,0 +1,24 @@
+import { resolve } from 'node:path';
+import { createLocalWorkspaceCoordinator, localDirectoryWorkspaceStore } from './local-workspace.js';
+import { localDirectorySandbox } from './local-sandbox.js';
+import { SqliteHarnessStorage, sqliteContextCheckpointStore, sqliteDurableRuntime, sqliteStateStore } from './sqlite-storage.js';
+export { localDirectorySandbox } from './local-sandbox.js';
+export { localDirectoryWorkspaceStore } from './local-workspace.js';
+export { sqliteContextCheckpointStore, sqliteDurableRuntime, sqliteStateStore, SqliteHarnessStorage } from './sqlite-storage.js';
+/** Creates the recommended local durable adapter bundle for single-host usage. */
+export function localDurableExecution(options) {
+    const root = resolve(options.root);
+    const coordinator = createLocalWorkspaceCoordinator();
+    const storage = new SqliteHarnessStorage({
+        file: options.databaseFile ?? resolve(root, 'runtime.sqlite'),
+        ...(options.leaseTtlMs !== undefined ? { leaseTtlMs: options.leaseTtlMs } : {})
+    });
+    return {
+        state: storage,
+        runtime: storage,
+        checkpoints: storage,
+        sandbox: localDirectorySandbox({ root, exec: options.exec ?? false, coordinator }),
+        workspaceStore: localDirectoryWorkspaceStore({ root, ...(options.policy ? { policy: options.policy } : {}), coordinator }),
+        close: () => storage.close()
+    };
+}

package/dist/local/local-sandbox.d.ts

@@ -0,0 +1,25 @@
+import type { ExecOptions, ExecResult } from '../harness/types.js';
+import type { Sandbox, SandboxSessionBase } from '../sandbox/index.js';
+import type { LocalWorkspaceCoordinator } from './local-workspace.js';
+export interface LocalHostExecPolicy {
+    env?: Record<string, string>;
+    allowCommands?: readonly string[];
+    timeoutMs?: number;
+}
+export interface LocalDirectorySandboxOptions {
+    root: string;
+    exec?: false | LocalHostExecPolicy;
+    coordinator?: LocalWorkspaceCoordinator;
+}
+/** Capability tuple advertised by the files-only local sandbox (spec 22 §2). */
+export type LocalFilesOnlySandboxCapabilities = readonly ['sandbox.fs', 'sandbox.persistent_fs'];
+/** Capability tuple advertised by the exec-enabled local sandbox (spec 22 §2). */
+export type LocalExecSandboxCapabilities = readonly ['sandbox.fs', 'sandbox.exec', 'sandbox.persistent_fs'];
+/** Sandbox shape returned by `localDirectorySandbox(...)` (spec 22 §2). */
+export type LocalDurableSandbox = Sandbox<LocalFilesOnlySandboxCapabilities> | Sandbox<LocalExecSandboxCapabilities>;
+/** Files-only session: `exec` is present but always throws `SandboxNoExecutorError`. */
+export type LocalFilesOnlySandboxSession = SandboxSessionBase & {
+    readonly executor: 'unavailable';
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+};
+export declare function localDirectorySandbox(options: LocalDirectorySandboxOptions): LocalDurableSandbox;