@purista/harness 1.2.6 → 1.5.1

package/dist/harness/defineHarness.d.ts

@@ -1,11 +1,13 @@
 import { z } from 'zod';
 import { type Logger } from '../logger/index.js';
-import type { ModelAlias, ModelCapability, TokenUsage } from '../ports/model-provider.js';
+import type { ModelAlias, ModelCapability, ObjectResponse, ToolCallSpec, ModelMessage, ModelToolSpec, TokenUsage, ModelCallOptions } from '../ports/model-provider.js';
 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 { ContextCheckpointStore } from '../ports/context-checkpoints.js';
+import type { ContextCheckpoint, ContextCheckpointQuery } from '../ports/context-checkpoints.js';
 import type { JsonValue } from '../models/json.js';
 import type { Message } from '../models/state.js';
 import type { RunStatus } from '../models/state.js';
@@ -13,6 +15,7 @@ import type { HarnessError } from '../errors/harness-error.js';
 import { type Sandbox } from '../sandbox/index.js';
 import type { ModelHandle } from '../models/registry.js';
 import { type AdapterCapability, type DurableRuntimeAdapter, type HarnessInspection } from '../ports/capabilities.js';
+import type { DurableStepOptions } from '../runtime/steps.js';
 /** Stable harness version string for diagnostics and generated documentation. */
 export { HARNESS_VERSION } from '../version.js';
 /** OpenTelemetry capture controls used by the harness. */
@@ -43,6 +46,32 @@ export interface HarnessDefaults {
      * `undefined` keeps all history, `0` keeps only system messages.
      */
     historyWindow?: number;
+    /** Default workflow child-agent delegation budgets. */
+    delegation?: DelegationDefaults;
+}
+/** Workflow child-agent delegation defaults. Delegation is disabled unless explicitly enabled. */
+export interface DelegationDefaults {
+    /**
+     * Enable workflow child-agent calls for workflows that do not declare their
+     * own `delegation` policy. Default: `false`.
+     */
+    enabled?: boolean;
+    /**
+     * Maximum child-agent calls one workflow run may start. Default: `32`.
+     * Set per workflow with `workflow.delegation.maxChildAgentCalls`.
+     */
+    maxChildAgentCalls?: number;
+    /**
+     * Maximum child-agent calls active at the same time inside one workflow run.
+     * Default: `8`.
+     */
+    maxParallelChildAgentCalls?: number;
+    /**
+     * Maximum local delegation depth. Default: `1`.
+     * Current harness workflows invoke leaf agents, so `1` allows normal
+     * workflow-to-agent calls and `0` disables child-agent delegation.
+     */
+    maxDepth?: number;
 }
 /** Top-level harness options passed to {@link defineHarness}. */
 export interface HarnessOptions {
@@ -333,30 +362,96 @@ export interface AgentContextMinimal<S extends BuilderState, I> {
     runId: string;
     history: ConversationHistory;
     memory: MemoryFacade;
+    checkpoints: ContextCheckpoints;
     metadata: Readonly<Record<string, JsonValue>>;
     metrics: Metrics;
 }
+/** Context passed before each default agent loop model call. */
+export interface AgentPrepareStepContext<S extends BuilderState, I> extends AgentContextMinimal<S, I> {
+    /** Zero-based model-call step in the default loop. */
+    step: number;
+    /** Model alias selected for this step before overrides are applied. */
+    model: keyof NonNullable<S['models']> & string;
+    /** Messages that would be sent to the model for this step. */
+    messages: readonly ModelMessage[];
+    /** Model-facing tools that would be available for this step. */
+    tools: readonly ModelToolSpec[];
+}
+/** Per-step overrides returned from `AgentDefinition.prepareStep`. */
+export interface AgentPrepareStepResult<S extends BuilderState> {
+    /** Optional model alias override for this model call. */
+    model?: keyof NonNullable<S['models']> & string;
+    /** Optional instruction override for this model call only. */
+    instructions?: string;
+    /** Optional model-facing tool names to keep active for this model call. */
+    activeTools?: readonly string[];
+    /** Optional message override for this model call only. */
+    messages?: readonly ModelMessage[];
+    /** Optional generation settings for this model call only. */
+    call?: ModelCallOptions;
+}
+/** Context passed after a default agent loop model call to decide whether to stop. */
+export interface AgentStopWhenContext<S extends BuilderState, I> extends AgentPrepareStepContext<S, I> {
+    /** Raw provider-normalized object response from the current model call. */
+    response: ObjectResponse<JsonValue>;
+    /** Tool calls requested by the current model response. */
+    toolCalls: readonly ToolCallSpec[];
+}
+/** Hook used to prepare each model call in the default agent loop. */
+export type AgentPrepareStep<S extends BuilderState, I> = (ctx: AgentPrepareStepContext<S, I>) => AgentPrepareStepResult<S> | Promise<AgentPrepareStepResult<S> | void> | void;
+/** Hook used to stop the default loop after a model call. */
+export type AgentStopWhen<S extends BuilderState, I> = (ctx: AgentStopWhenContext<S, I>) => boolean | Promise<boolean>;
+/** Run-bound facade for explicit long-horizon context checkpoints. */
+export interface ContextCheckpoints {
+    write(input: {
+        sequence: number;
+        kind: ContextCheckpoint['kind'];
+        payload: JsonValue;
+        metadata?: Record<string, JsonValue>;
+    }): Promise<void>;
+    list(query?: Omit<ContextCheckpointQuery, 'runId' | 'sessionId' | 'workflowId' | 'agentId' | 'signal'>): Promise<readonly ContextCheckpoint[]>;
+    read(ref: {
+        sequence: number;
+        kind: ContextCheckpoint['kind'];
+    }): Promise<ContextCheckpoint | undefined>;
+    delete(ref: {
+        sequence: number;
+        kind: ContextCheckpoint['kind'];
+    }): Promise<void>;
+}
 /** Full context passed to workflow handlers. */
 export interface WorkflowContext<S extends BuilderState, I, O> {
     input: I;
     agents: {
-        [K in keyof NonNullable<S['agents']>]: (input: AgentInput<S, K>, opts?: InvokeOptions) => Promise<AgentOutput<S, K>>;
+        [K in keyof NonNullable<S['agents']>]: (input: AgentInput<S, K>, opts?: WorkflowAgentInvokeOptions<S, K>) => Promise<AgentOutput<S, K>>;
     };
     models: ModelHandles<S>;
+    /** Harness logger scoped for workflow handler code (spec 10 `WorkflowContext`). */
+    log: Logger;
     signal: AbortSignal;
     runId: string;
     sessionId: string;
     metadata: Readonly<Record<string, JsonValue>>;
     memory: MemoryFacade;
+    checkpoints: ContextCheckpoints;
     metrics: Metrics;
     /**
      * Runs `fn` as a durable step. Under a durable invocation the output is
      * checkpointed and replayed on resume without re-running `fn`; otherwise it is
      * a transparent pass-through. See spec 10 "Durable steps".
      */
-    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>): Promise<T>;
+    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>, options?: DurableStepOptions): Promise<T>;
     output?: O;
 }
+/** Invoke options accepted by workflow-local child-agent calls. */
+export type WorkflowAgentInvokeOptions<S extends BuilderState, K extends keyof NonNullable<S['agents']>> = InvokeOptions & {
+    /**
+     * Optional model alias override for this child-agent call.
+     * The alias must exist on the harness model registry and be allowed by the
+     * workflow delegation policy.
+     */
+    model?: keyof NonNullable<S['models']> & string;
+};
 /** Full context passed to custom agent handlers. */
 export interface AgentContext<S extends BuilderState, I, O> extends AgentContextMinimal<S, I> {
     models: ModelHandles<S>;
@@ -375,12 +470,31 @@ export interface AgentDefinition<S extends BuilderState, I extends z.ZodTypeAny
     permissions?: AgentPermissions;
     onPermission?: OnPermission;
     maxSteps?: number;
+    /**
+     * Optional hook for per-round loop control in the default agent loop.
+     *
+     * @example
+     * ```ts
+     * prepareStep: ({ step }) => step === 0 ? { activeTools: ['lookup'] } : {}
+     * ```
+     */
+    prepareStep?: AgentPrepareStep<S, z.infer<I>>;
+    /**
+     * Optional hook that can stop the default loop after a model call.
+     *
+     * @example
+     * ```ts
+     * stopWhen: ({ step }) => step >= 2
+     * ```
+     */
+    stopWhen?: AgentStopWhen<S, z.infer<I>>;
     handler?: (ctx: AgentContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 }
 /** Workflow definition registered inline within `.workflows(...)`. */
 export interface WorkflowDefinition<S extends BuilderState, I extends z.ZodTypeAny = z.ZodTypeAny, O extends z.ZodTypeAny = z.ZodTypeAny> {
     input?: I;
     output?: O;
+    delegation?: WorkflowDelegationPolicy<S>;
     handler: (ctx: WorkflowContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 }
 type AgentSchemaFields = {
@@ -398,6 +512,8 @@ type AgentDefinitionResolved<S extends BuilderState, I extends z.ZodTypeAny, O e
     permissions?: AgentPermissions;
     onPermission?: OnPermission;
     maxSteps?: number;
+    prepareStep?: AgentPrepareStep<S, z.infer<I>>;
+    stopWhen?: AgentStopWhen<S, z.infer<I>>;
     handler?: (ctx: AgentContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 };
 type AgentDefinitionFor<S extends BuilderState, D> = D extends {
@@ -423,8 +539,26 @@ type WorkflowSchemaFields = {
 type WorkflowDefinitionResolved<S extends BuilderState, I extends z.ZodTypeAny, O extends z.ZodTypeAny> = {
     input?: I;
     output?: O;
+    delegation?: WorkflowDelegationPolicy<S>;
     handler: (ctx: WorkflowContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 };
+/** Policy for workflow-local child-agent delegation through `ctx.agents`. */
+export interface WorkflowDelegationPolicy<S extends BuilderState = BuilderState> {
+    /** Enable or disable child-agent calls for this workflow. A policy object without this field enables delegation. */
+    enabled?: boolean;
+    /** Child agent ids this workflow may call. Omit to allow all registered agents. */
+    agents?: readonly (keyof NonNullable<S['agents']> & string)[];
+    /** Per-run child-agent call limit. Overrides `defaults.delegation.maxChildAgentCalls`. */
+    maxChildAgentCalls?: number;
+    /** Per-run active child-agent call limit. Overrides `defaults.delegation.maxParallelChildAgentCalls`. */
+    maxParallelChildAgentCalls?: number;
+    /** Maximum local delegation depth. Overrides `defaults.delegation.maxDepth`. */
+    maxDepth?: number;
+    /** Model aliases allowed for every child-agent call in this workflow, including calls running on the agent's default `model`. */
+    modelAliases?: readonly (keyof NonNullable<S['models']> & string)[];
+    /** Per-child-agent model alias allowlists. These replace `modelAliases` for the named agent. */
+    agentModelAliases?: Partial<Record<keyof NonNullable<S['agents']> & string, readonly (keyof NonNullable<S['models']> & string)[]>>;
+}
 type WorkflowDefinitionFor<S extends BuilderState, D> = D extends {
     input: infer I extends z.ZodTypeAny;
     output: infer O extends z.ZodTypeAny;
@@ -576,11 +710,21 @@ export type RunEvent = {
     runId: string;
     agentId: string;
     at: string;
+    workflowId?: string;
+    parentAgentId?: string;
+    delegationCallId?: string;
+    delegationDepth?: number;
+    modelAlias?: string;
 } | {
     type: 'agent.finished';
     runId: string;
     agentId: string;
     at: string;
+    workflowId?: string;
+    parentAgentId?: string;
+    delegationCallId?: string;
+    delegationDepth?: number;
+    modelAlias?: string;
     output?: JsonValue;
     error?: SerializedError;
 } | {
@@ -657,6 +801,7 @@ export interface HarnessBuilder<S extends BuilderState = {}> {
     memory(adapter: MemoryAdapter): HarnessBuilder<S>;
     runtime(runtime: DurableRuntimeAdapter): HarnessBuilder<S>;
     workspaceStore(store: DurableWorkspaceStore): HarnessBuilder<S>;
+    checkpoints(store: ContextCheckpointStore): HarnessBuilder<S>;
     requires(capabilities: readonly AdapterCapability[]): HarnessBuilder<S>;
     defaults(defaults: HarnessDefaults): HarnessBuilder<S>;
     models<const M extends ModelsConfig>(models: M): HarnessBuilder<S & {
@@ -745,6 +890,7 @@ export interface HarnessBuilder<S extends BuilderState = {}> {
  *     summarize_ticket: {
  *       input: z.object({ ticket: z.string() }),
  *       output: z.string(),
+ *       delegation: { agents: ['summarize'] },
  *       handler: (ctx) => ctx.agents.summarize(ctx.input.ticket)
  *     }
  *   })

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 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 { 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, DurableStepOptions, DurableStepRetryPolicy, DurableStepRetrySetting, DurableRunLease, DurableRunStart, DurableRunStatus, DurableRuntime, DurableTerminalRunStatus, FinishRunPatch, InMemoryDurableRuntimeOptions, RunCheckpoint } from './runtime/index.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, AgentPrepareStep, AgentPrepareStepContext, AgentPrepareStepResult, AgentStopWhen, AgentStopWhenContext, 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()
+    };
+}