@agentskit/harness 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,968 @@
+declare const STATES: readonly ["CLARIFYING", "PLANNED", "IMPLEMENTING", "VERIFYING", "AWAITING_HUMAN_APPROVAL", "AWAITING_AUTHORIZATION", "COMPLETE", "BLOCKED", "STALE", "CANCELLED", "SUPERSEDED"];
+declare const LEGAL_TRANSITIONS: {
+    readonly CLARIFYING: readonly ["PLANNED", "BLOCKED", "CANCELLED"];
+    readonly PLANNED: readonly ["IMPLEMENTING", "CLARIFYING", "STALE", "CANCELLED"];
+    readonly IMPLEMENTING: readonly ["VERIFYING", "CLARIFYING", "STALE", "CANCELLED"];
+    readonly VERIFYING: readonly ["AWAITING_HUMAN_APPROVAL", "BLOCKED", "STALE", "CANCELLED"];
+    readonly AWAITING_HUMAN_APPROVAL: readonly ["AWAITING_AUTHORIZATION", "COMPLETE", "BLOCKED", "IMPLEMENTING", "STALE", "CANCELLED"];
+    readonly AWAITING_AUTHORIZATION: readonly ["COMPLETE", "BLOCKED", "IMPLEMENTING", "STALE", "CANCELLED"];
+    readonly COMPLETE: readonly ["STALE", "SUPERSEDED"];
+    readonly BLOCKED: readonly ["SUPERSEDED"];
+    readonly STALE: readonly ["SUPERSEDED", "PLANNED"];
+    readonly CANCELLED: readonly ["SUPERSEDED"];
+    readonly SUPERSEDED: readonly [];
+};
+
+type HarnessErrorCode = 'HARNESS_ERROR' | 'INVALID_CONFIG' | 'INVALID_INPUT' | 'INVALID_STATE' | 'POLICY_BLOCKED' | 'CLARIFYING' | 'STALE' | 'WORKTREE_DIRTY' | 'ACTIVE_RUN' | 'NO_RUN' | 'HUMAN_APPROVAL_REQUIRED';
+declare class HarnessError extends Error {
+    readonly code: HarnessErrorCode;
+    constructor(message: string, code?: HarnessErrorCode);
+}
+
+interface ToolExecutionRequest {
+    readonly actionId: string;
+    readonly turnId: string;
+    readonly toolId: string;
+    readonly argumentsHash: string;
+    readonly arguments: unknown;
+    readonly signal: AbortSignal;
+}
+interface ToolDefinition {
+    readonly toolId: string;
+    readonly execute: (request: ToolExecutionRequest) => Promise<unknown> | unknown;
+}
+interface ToolRuntime {
+    execute(request: Omit<ToolExecutionRequest, 'signal'>): Promise<ToolExecutionResult>;
+}
+interface ProcessToolDefinition {
+    readonly toolId: string;
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+}
+interface DockerMount {
+    readonly source: string;
+    readonly target: string;
+    readonly readOnly?: boolean;
+}
+interface DockerToolDefinition {
+    readonly toolId: string;
+    readonly image: string;
+    readonly command: readonly string[];
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly mounts?: readonly DockerMount[];
+}
+interface DockerRuntimeEvidence {
+    readonly provider: 'docker';
+    readonly profileHash: string;
+    readonly image: string;
+    readonly imageDigest?: string;
+    readonly network: 'none';
+    readonly readOnlyRootFilesystem: true;
+    readonly noNewPrivileges: true;
+    readonly capabilities: 'drop-all';
+    readonly user: string;
+    readonly memoryLimit: string;
+    readonly cpus: string;
+    readonly pidsLimit: number;
+}
+type ToolExecutionResult = {
+    readonly status: 'completed';
+    readonly resultHash: string;
+    readonly durationMs: number;
+    readonly runtimeEvidence?: DockerRuntimeEvidence;
+} | {
+    readonly status: 'failed';
+    readonly errorCode: string;
+    readonly retryable: boolean;
+    readonly durationMs: number;
+    readonly runtimeEvidence?: DockerRuntimeEvidence;
+};
+declare const createToolRuntime: ({ tools, timeoutMs }: {
+    readonly tools: readonly ToolDefinition[];
+    readonly timeoutMs?: number;
+}) => ToolRuntime;
+declare const createProcessToolRuntime: ({ tools, timeoutMs, maxOutputBytes }: {
+    readonly tools: readonly ProcessToolDefinition[];
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+}) => ToolRuntime;
+declare const createDockerToolRuntime: ({ tools, timeoutMs, maxOutputBytes, dockerCommand, memoryLimit, cpus, pidsLimit, user, pull, }: {
+    readonly tools: readonly DockerToolDefinition[];
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+    readonly dockerCommand?: string;
+    readonly memoryLimit?: string;
+    readonly cpus?: number | string;
+    readonly pidsLimit?: number;
+    readonly user?: string;
+    readonly pull?: "never" | "missing" | "always";
+}) => ToolRuntime;
+
+declare const HARNESS_EVENT_SCHEMA_VERSION: 1;
+declare const EVENT_LOG_GENESIS: "GENESIS";
+declare const HARNESS_EVENT_TYPES: readonly ["run.created", "state.transitioned", "context.attached", "verification.completed", "approval.recorded", "authorization.recorded", "session.started", "session.resumed", "agent.turn.started", "policy.evaluated", "tool.approval.requested", "tool.approval.recorded", "tool.requested", "tool.execution.started", "tool.recovery.recorded", "tool.blocked", "tool.completed", "tool.failed", "session.ended"];
+type HarnessEventType = typeof HARNESS_EVENT_TYPES[number];
+interface HarnessEventPayloads {
+    readonly 'run.created': {
+        readonly project: string;
+        readonly baselineRevision: string;
+        readonly baselineStatusHash: string;
+    };
+    readonly 'state.transitioned': {
+        readonly from: RunState | null;
+        readonly to: RunState;
+        readonly actor: string;
+        readonly reason?: string;
+        readonly transitionIndex: number;
+    };
+    readonly 'context.attached': {
+        readonly providerId: string;
+        readonly sourceHash: string;
+        readonly snapshotHash: string;
+        readonly query: ContextQuery;
+    };
+    readonly 'verification.completed': {
+        readonly verificationDigest: string;
+        readonly checkCount: number;
+        readonly outcomeCount: number;
+        readonly totalDurationMs: number;
+        readonly budgetExceeded: boolean;
+    };
+    readonly 'approval.recorded': {
+        readonly decision: 'approved' | 'rejected';
+        readonly resultingState: RunState;
+        readonly verificationDigest: string;
+        readonly actor: 'human';
+        readonly sourceRevision: string;
+        readonly contractHash: string;
+    };
+    readonly 'authorization.recorded': {
+        readonly decision: 'approved' | 'rejected';
+        readonly resultingState: RunState;
+        readonly verificationDigest: string;
+        readonly actor: 'human';
+        readonly target: string;
+        readonly sourceRevision: string;
+        readonly contractHash: string;
+    };
+    readonly 'session.started': {
+        readonly adapterId: string;
+        readonly adapterVersion: string;
+        readonly capabilities: readonly string[];
+    };
+    readonly 'session.resumed': {
+        readonly recovery: 'event-log';
+    };
+    readonly 'agent.turn.started': {
+        readonly turnId: string;
+        readonly inputHash: string;
+    };
+    readonly 'policy.evaluated': {
+        readonly actionId: string;
+        readonly turnId: string;
+        readonly toolId: string;
+        readonly decision: 'allow' | 'block' | 'approve';
+        readonly policyId: string;
+        readonly reason: string;
+    };
+    readonly 'tool.approval.requested': {
+        readonly turnId: string;
+        readonly actionId: string;
+        readonly toolId: string;
+        readonly argumentsHash: string;
+        readonly policyId: string;
+        readonly reason: string;
+    };
+    readonly 'tool.approval.recorded': {
+        readonly turnId: string;
+        readonly actionId: string;
+        readonly toolId: string;
+        readonly argumentsHash: string;
+        readonly decision: 'approved' | 'rejected';
+        readonly actor: 'human';
+        readonly policyId: string;
+        readonly reason: string;
+    };
+    readonly 'tool.requested': {
+        readonly turnId: string;
+        readonly actionId: string;
+        readonly toolId: string;
+        readonly argumentsHash: string;
+    };
+    readonly 'tool.execution.started': {
+        readonly turnId: string;
+        readonly actionId: string;
+        readonly toolId: string;
+        readonly attempt: number;
+    };
+    readonly 'tool.recovery.recorded': {
+        readonly turnId: string;
+        readonly actionId: string;
+        readonly toolId: string;
+        readonly decision: 'retry' | 'abandon';
+        readonly actor: 'human';
+        readonly reason: string;
+    };
+    readonly 'tool.blocked': {
+        readonly turnId: string;
+        readonly actionId: string;
+        readonly toolId: string;
+        readonly policyId: string;
+        readonly reason: string;
+    };
+    readonly 'tool.completed': {
+        readonly actionId: string;
+        readonly resultHash: string;
+        readonly durationMs: number;
+        readonly runtimeEvidence?: DockerRuntimeEvidence;
+    };
+    readonly 'tool.failed': {
+        readonly actionId: string;
+        readonly errorCode: string;
+        readonly retryable: boolean;
+        readonly durationMs: number;
+        readonly runtimeEvidence?: DockerRuntimeEvidence;
+    };
+    readonly 'session.ended': {
+        readonly status: 'completed' | 'failed' | 'cancelled';
+    };
+}
+type HarnessEvent<K extends HarnessEventType = HarnessEventType> = K extends HarnessEventType ? {
+    readonly schemaVersion: typeof HARNESS_EVENT_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly sequence: number;
+    readonly at: string;
+    readonly sourceRevision: string;
+    readonly configHash: string;
+    readonly previousHash?: string;
+    readonly eventHash?: string;
+    readonly sessionId?: string;
+    readonly type: K;
+    readonly payload: HarnessEventPayloads[K];
+} : never;
+type HarnessEventInput<K extends HarnessEventType = HarnessEventType> = Omit<HarnessEvent<K>, 'schemaVersion' | 'sequence' | 'at'>;
+type HarnessEventListener<K extends HarnessEventType> = (event: HarnessEvent<K>) => void;
+interface EventStore {
+    append<K extends HarnessEventType>(event: HarnessEventInput<K>): HarnessEvent<K>;
+    read(runId: string): readonly HarnessEvent[];
+    verify(runId: string): EventLogVerification;
+}
+interface EventLogVerification {
+    readonly status: 'verified' | 'legacy';
+    readonly eventCount: number;
+    readonly headHash?: string;
+}
+interface EventLogLock {
+    readonly pid: number;
+    readonly at: string;
+}
+interface EventLogLockStatus {
+    readonly status: 'locked' | 'unlocked';
+    readonly path: string;
+    readonly lock?: EventLogLock;
+}
+interface EventLogLockRecovery {
+    readonly status: 'recovered' | 'unlocked';
+    readonly path: string;
+    readonly lock?: EventLogLock;
+}
+declare class FileEventStore implements EventStore {
+    private readonly stateDir;
+    constructor(stateDir: string);
+    append<K extends HarnessEventType>(event: HarnessEventInput<K>): HarnessEvent<K>;
+    private readUnlocked;
+    read(runId: string): readonly HarnessEvent[];
+    verify(runId: string): EventLogVerification;
+}
+declare const inspectEventLogLock: (stateDir: string, runId: string) => EventLogLockStatus;
+declare const recoverEventLogLock: ({ stateDir, runId, actor, maxAgeMs }: {
+    readonly stateDir: string;
+    readonly runId: string;
+    readonly actor: string;
+    readonly maxAgeMs?: number;
+}) => EventLogLockRecovery;
+
+declare const HARNESS_PLUGIN_API_VERSION: 1;
+type Disposer = () => void;
+interface PluginSlot<T> {
+    readonly id: string;
+}
+declare const createPluginSlot: <T>(id: string) => PluginSlot<T>;
+interface HarnessPluginContext {
+    readonly apiVersion: typeof HARNESS_PLUGIN_API_VERSION;
+    register<T>(slot: PluginSlot<T>, id: string, value: T): Disposer;
+    effect(disposer: Disposer): void;
+    on<K extends HarnessEventType>(type: K, listener: HarnessEventListener<K>): Disposer;
+}
+interface HarnessPlugin {
+    readonly id: string;
+    readonly version: string;
+    readonly apiVersion: typeof HARNESS_PLUGIN_API_VERSION;
+    readonly requires?: readonly string[];
+    readonly apply: (context: HarnessPluginContext) => void | Disposer;
+}
+interface PluginContribution<T> {
+    readonly pluginId: string;
+    readonly id: string;
+    readonly value: T;
+}
+interface PluginRegistry {
+    register(plugin: HarnessPlugin): void;
+    mount(): void;
+    emit<K extends HarnessEventType>(event: HarnessEvent<K>): void;
+    on<K extends HarnessEventType>(type: K, listener: HarnessEventListener<K>): Disposer;
+    contributions<T>(slot: PluginSlot<T>): readonly PluginContribution<T>[];
+    dispose(): void;
+}
+declare const createPluginRegistry: () => PluginRegistry;
+
+interface ContextQuery {
+    readonly query: string;
+    readonly scope?: readonly string[];
+    readonly sourceRevision?: string;
+}
+interface ContextReference {
+    readonly id: string;
+    readonly uri: string;
+    readonly title?: string;
+    readonly version?: string;
+    readonly contentHash?: string;
+}
+interface ContextSnapshot {
+    readonly providerId: string;
+    readonly query: ContextQuery;
+    readonly references: readonly ContextReference[];
+    readonly sourceHash: string;
+    readonly snapshotHash: string;
+    readonly resolvedAt: string;
+}
+interface ContextProvider {
+    readonly id: string;
+    readonly version: string;
+    readonly resolve: (query: ContextQuery) => Promise<ContextSnapshot>;
+}
+declare const hashContextSnapshot: ({ providerId, query, references, sourceHash }: Pick<ContextSnapshot, "providerId" | "query" | "references" | "sourceHash">) => string;
+declare const hashContextSnapshots: (snapshots: readonly ContextSnapshot[]) => string;
+declare const validateContextSnapshot: (value: unknown, index?: number) => ContextSnapshot;
+declare const readContextSnapshots: (path: string) => readonly ContextSnapshot[];
+declare const validateContextSnapshots: (snapshots: readonly ContextSnapshot[]) => readonly ContextSnapshot[];
+declare const CONTEXT_PROVIDER_SLOT: PluginSlot<ContextProvider>;
+
+declare const SURFACE_NAMES: readonly ["logic", "endpoint", "database", "cli", "mcp", "ui", "docs"];
+type SurfaceName = typeof SURFACE_NAMES[number];
+declare const CHECK_CATEGORIES: readonly ["build", "test", "lint", "logic", "endpoint", "database", "cli", "mcp", "ui", "docs", "custom"];
+type CheckCategory = typeof CHECK_CATEGORIES[number];
+declare const RUN_STATES: readonly ["CLARIFYING", "PLANNED", "IMPLEMENTING", "VERIFYING", "AWAITING_HUMAN_APPROVAL", "AWAITING_AUTHORIZATION", "COMPLETE", "BLOCKED", "STALE", "CANCELLED", "SUPERSEDED"];
+type RunState = typeof RUN_STATES[number];
+interface SurfaceRequirement {
+    readonly required: boolean;
+    readonly reason?: string;
+}
+interface ContractScope {
+    readonly inScope: readonly string[];
+    readonly outOfScope: readonly string[];
+}
+interface ContractOutcome {
+    readonly id: string;
+    readonly statement: string;
+    readonly checks: readonly string[];
+}
+interface TaskContract {
+    readonly intent: string;
+    readonly scope: ContractScope;
+    readonly ambiguities: readonly string[];
+    readonly outcomes: readonly ContractOutcome[];
+}
+interface VerificationCheck {
+    readonly id: string;
+    readonly category: CheckCategory;
+    readonly command: string;
+    readonly required: boolean;
+    readonly timeoutMs: number;
+    readonly execution?: 'real';
+    readonly capabilities?: readonly string[];
+    readonly evidence: 'structured';
+}
+interface TrackingConfig {
+    readonly required: boolean;
+    readonly target?: string;
+    readonly reason?: string;
+}
+interface BenchmarkBinding {
+    readonly suiteId: string;
+    readonly taskId: string;
+    readonly mode: 'harness';
+}
+interface VerificationConfig {
+    readonly schemaVersion: 1;
+    readonly project: string;
+    readonly root?: string;
+    readonly stateDir?: string;
+    readonly profile: string;
+    readonly contract: TaskContract;
+    readonly surfaces: Readonly<Record<SurfaceName, SurfaceRequirement>>;
+    readonly checks: readonly VerificationCheck[];
+    readonly tracking: TrackingConfig;
+    readonly budget?: {
+        readonly maxDurationMs?: number;
+    };
+    readonly cleanup?: {
+        readonly roots?: readonly string[];
+    };
+    readonly benchmark?: BenchmarkBinding;
+}
+interface LoadedConfig {
+    readonly absolute: string;
+    readonly root: string;
+    readonly stateDir: string;
+    readonly config: VerificationConfig;
+    readonly configHash: string;
+}
+interface SourceSnapshot {
+    readonly revision: string;
+    readonly status: string;
+    readonly statusHash: string;
+}
+interface EvidenceArtifact {
+    readonly type?: string;
+    readonly path: string;
+    readonly sha256: string;
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    } | string;
+}
+interface StructuredEvidence {
+    readonly status: string;
+    readonly criteria: readonly string[];
+    readonly capability?: string;
+    readonly artifacts?: readonly EvidenceArtifact[];
+    readonly [key: string]: unknown;
+}
+interface CheckResult {
+    readonly id: string;
+    readonly category: CheckCategory;
+    readonly status: 'pending' | 'passed' | 'failed';
+    readonly exitCode?: number;
+    readonly durationMs?: number;
+    readonly evidence?: StructuredEvidence;
+    readonly failures?: readonly string[];
+}
+interface RunOutcome extends ContractOutcome {
+    readonly status: 'pending' | 'passed' | 'failed';
+}
+interface EvidenceReference {
+    readonly checkId: string;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+interface VerificationRun {
+    readonly type: 'agentskit-harness-run';
+    readonly schemaVersion: 1;
+    readonly runId: string;
+    readonly project: string;
+    readonly state: RunState;
+    readonly configHash: string;
+    readonly contractHash: string;
+    readonly sourceRevision: string;
+    readonly sourceStatusHash: string;
+    readonly baseline: SourceSnapshot;
+    /** A human-approved plan, retained for backwards compatibility with v1 runs. */
+    readonly contractApproval?: {
+        readonly actor: 'human';
+        readonly at: string;
+        readonly contractHash: string;
+    };
+    /** An automated preparation is never an approval and cannot complete a run. */
+    readonly contractPreparation?: {
+        readonly actor: 'ci';
+        readonly at: string;
+        readonly contractHash: string;
+    };
+    readonly checks: readonly CheckResult[];
+    readonly outcomes: readonly RunOutcome[];
+    readonly transitions: readonly StateTransition[];
+    readonly evidenceReferences: readonly EvidenceReference[];
+    readonly contextSnapshots: readonly ContextSnapshot[];
+    readonly contextHash?: string;
+    readonly verificationDigest?: string;
+    readonly benchmark?: BenchmarkBinding;
+    readonly supersedes?: string;
+    readonly dirtyBaselineAuthorized?: boolean;
+    readonly metrics?: {
+        readonly totalDurationMs: number;
+        readonly budgetExceeded: boolean;
+    };
+    readonly humanApproval?: {
+        readonly actor: 'human';
+        readonly at: string;
+        readonly sourceRevision: string;
+        readonly contractHash: string;
+        readonly verificationDigest?: string;
+    };
+    readonly authorization?: {
+        readonly actor: 'human';
+        readonly at: string;
+        readonly target: string;
+        readonly sourceRevision: string;
+        readonly contractHash: string;
+        readonly verificationDigest?: string;
+    };
+}
+interface RunReconciliation {
+    readonly status: 'verified';
+    readonly runId: string;
+    readonly state: RunState;
+    readonly eventCount: number;
+    readonly headHash?: string;
+    readonly verificationDigest?: string;
+}
+interface StateTransition {
+    readonly from: RunState | null;
+    readonly to: RunState;
+    readonly at: string;
+    readonly actor?: string;
+    readonly reason?: string;
+}
+
+declare const validateConfig: (rawValue: unknown) => VerificationConfig;
+declare const loadConfig: (configPath?: string) => LoadedConfig;
+
+declare const transition: (run: Pick<VerificationRun, "state" | "transitions">, to: RunState, reason?: string, actor?: string) => Pick<VerificationRun, "state" | "transitions">;
+declare const assertHuman: (actor: string) => void;
+declare const approvedDecision: (decision: string) => boolean;
+
+declare const loadLatestRun: (stateDir: string) => VerificationRun | null;
+
+declare const planRun: ({ configPath, decision, actor, allowDirty, contextSnapshots }: {
+    readonly configPath: string;
+    readonly decision: string;
+    readonly actor?: string;
+    readonly allowDirty?: boolean;
+    readonly contextSnapshots?: readonly ContextSnapshot[];
+}) => Promise<VerificationRun>;
+declare const startRun: (loaded: LoadedConfig) => VerificationRun;
+declare const cancelRun: ({ configPath, runId, reason, actor }: {
+    readonly configPath: string;
+    readonly runId?: string;
+    readonly reason?: string;
+    readonly actor?: string;
+}) => Promise<VerificationRun>;
+declare const verifyRun: ({ configPath }: {
+    readonly configPath: string;
+}) => Promise<VerificationRun>;
+declare const reconcileRun: ({ configPath, runId }: {
+    readonly configPath: string;
+    readonly runId?: string;
+}) => Promise<RunReconciliation>;
+declare const approveRun: ({ configPath, runId, decision, actor }: {
+    readonly configPath: string;
+    readonly runId?: string;
+    readonly decision: string;
+    readonly actor?: string;
+}) => Promise<VerificationRun>;
+declare const authorizeRun: ({ configPath, runId, decision, actor }: {
+    readonly configPath: string;
+    readonly runId?: string;
+    readonly decision: string;
+    readonly actor?: string;
+}) => Promise<VerificationRun>;
+declare const retryRun: ({ configPath }: {
+    readonly configPath: string;
+}) => Promise<VerificationRun>;
+declare const cleanTaskArtifacts: (configPath: string) => {
+    readonly cleaned: readonly string[];
+};
+
+interface DocBridgeContextProviderOptions {
+    readonly root: string;
+    readonly indexPath?: string;
+}
+declare const createDocBridgeContextProvider: ({ root, indexPath }: DocBridgeContextProviderOptions) => ContextProvider;
+
+declare const BENCHMARK_SCHEMA_VERSION: 1;
+type BenchmarkObservationStatus = 'passed' | 'failed' | 'blocked' | 'not-run';
+type BenchmarkImprovementDirection = 'improved' | 'regressed' | 'unchanged' | 'unavailable';
+type BenchmarkConfidence = 'insufficient' | 'directional' | 'reliable';
+interface BenchmarkPolicy {
+    readonly minComparableTasks: number;
+    readonly maxDurationRegressionRate: number;
+    readonly minCompletedRunsPerTask: number;
+    readonly minBaselineSamplesPerTask: number;
+    readonly requireZeroEscapedIncomplete: boolean;
+}
+interface BenchmarkQualityGate {
+    readonly status: 'passed' | 'failed' | 'insufficient-data';
+    readonly confidence: BenchmarkConfidence;
+    readonly comparableTaskCount: number;
+    readonly policy: BenchmarkPolicy;
+    readonly durationRegressionTaskIds: readonly string[];
+    readonly escapedIncompleteTaskIds: readonly string[];
+    readonly reasons: readonly string[];
+}
+interface BenchmarkTask {
+    readonly id: string;
+    readonly title: string;
+    readonly acceptanceCriteria: readonly string[];
+    /** Product/runtime surfaces exercised by the task. */
+    readonly surfaces?: readonly SurfaceName[];
+    readonly kind?: string;
+    readonly prompt?: BenchmarkTaskFile;
+    readonly source?: BenchmarkTaskSource;
+    readonly scope?: BenchmarkTaskScope;
+}
+interface BenchmarkTaskFile {
+    readonly path: string;
+    readonly sha256: string;
+}
+interface BenchmarkTaskSource {
+    readonly repository: string;
+    readonly path: string;
+    readonly revision: string;
+}
+interface BenchmarkSuiteSource {
+    readonly repository: string;
+    readonly revision: string;
+    readonly taskDefinition: string;
+}
+interface BenchmarkTaskScope {
+    readonly read: readonly string[];
+    readonly write: readonly string[];
+}
+interface BenchmarkObservation {
+    readonly taskId: string;
+    readonly mode: 'baseline';
+    readonly status: BenchmarkObservationStatus;
+    readonly source: string;
+    readonly recordedAt: string;
+    readonly attempts?: number;
+    readonly durationMs?: number;
+    readonly durationSamplesMs?: readonly number[];
+    /** Fraction of repeated samples whose task artifact passed acceptance validation. */
+    readonly artifactAcceptanceRate?: number;
+    /** Fraction of repeated samples whose verification protocol completed. */
+    readonly protocolCompletionRate?: number;
+    readonly reviewMinutes?: number;
+    readonly escapedIncomplete?: number;
+    readonly evidence?: readonly BenchmarkObservationEvidence[];
+    readonly evidenceDigest?: string;
+}
+interface BenchmarkObservationEvidence {
+    readonly criterion: string;
+    readonly status: BenchmarkObservationStatus;
+    readonly source: string;
+}
+interface BenchmarkManifest {
+    readonly type: 'agentskit-harness-benchmark-manifest';
+    readonly schemaVersion: typeof BENCHMARK_SCHEMA_VERSION;
+    readonly suiteId: string;
+    readonly name: string;
+    readonly provenance?: BenchmarkSuiteSource;
+    readonly tasks: readonly BenchmarkTask[];
+    readonly observations: readonly BenchmarkObservation[];
+    readonly policy?: BenchmarkPolicy;
+}
+interface BenchmarkRun {
+    readonly runId: string;
+    readonly state: RunState;
+    readonly sourceRevision: string;
+    readonly configHash: string;
+    readonly contractHash: string;
+    readonly supersedes?: string;
+    readonly durationMs?: number;
+    readonly checks: {
+        readonly total: number;
+        readonly passed: number;
+        readonly failed: number;
+    };
+    readonly outcomes: {
+        readonly total: number;
+        readonly passed: number;
+        readonly failed: number;
+    };
+    readonly evidence: {
+        readonly total: number;
+        readonly attached: number;
+    };
+    /** Optional artifact outcome emitted by structured benchmark evidence. */
+    readonly artifactAcceptanceRate?: number;
+    readonly escapedIncomplete?: number;
+    readonly humanApproved: boolean;
+    readonly humanReviewMinutes?: number;
+    readonly authorized: boolean;
+    readonly benchmark?: BenchmarkBinding;
+}
+interface BenchmarkComparison {
+    readonly taskId: string;
+    readonly title: string;
+    readonly comparability: 'comparable' | 'missing-baseline' | 'baseline-not-run' | 'baseline-evidence-missing' | 'baseline-incomplete' | 'baseline-samples-insufficient' | 'harness-not-run' | 'harness-not-complete';
+    readonly comparable: boolean;
+    readonly baselineDeliveryComplete: boolean;
+    readonly baseline?: BenchmarkObservation;
+    readonly baselineEvidenceCoverageRate: number | null;
+    readonly baselineSampleCount: number;
+    readonly baselineArtifactAcceptanceRate: number | null;
+    readonly baselineProtocolCompletionRate: number | null;
+    readonly baselineMedianDurationMs?: number;
+    readonly improvement: {
+        readonly durationRate: number | null;
+        readonly duration: BenchmarkImprovementDirection;
+        readonly attemptsRate: number | null;
+        readonly attempts: BenchmarkImprovementDirection;
+        readonly reviewRate: number | null;
+        readonly review: BenchmarkImprovementDirection;
+        readonly artifactAcceptanceRate: number | null;
+        readonly artifactAcceptance: BenchmarkImprovementDirection;
+        readonly artifactAcceptanceDelta: number | null;
+        readonly protocolCompletionRate: number | null;
+        readonly protocolCompletion: BenchmarkImprovementDirection;
+        readonly protocolCompletionDelta: number | null;
+        readonly escapedIncompleteRate: number | null;
+        readonly escapedIncomplete: BenchmarkImprovementDirection;
+    };
+    readonly harness: {
+        readonly attempts: number;
+        readonly retryCount: number;
+        readonly completedRuns: number;
+        readonly durationSamplesMs: readonly number[];
+        readonly medianDurationMs?: number;
+        readonly latestState: RunState | 'NOT_RUN';
+        readonly latestRunId?: string;
+        readonly latestDurationMs?: number;
+        readonly checkPassRate: number | null;
+        readonly outcomePassRate: number | null;
+        readonly evidenceCoverageRate: number | null;
+        readonly artifactAcceptanceRate?: number;
+        readonly artifactAcceptanceSampleCount: number;
+        readonly protocolCompletionRate: number | null;
+        readonly protocolCompletionSampleCount: number;
+        readonly humanApproved: boolean;
+        readonly escapedIncomplete?: number;
+        readonly humanReviewMinutes?: number;
+    };
+    readonly confidence: BenchmarkConfidence;
+    readonly durationDeltaMs?: number;
+    readonly attemptDelta?: number;
+    readonly reviewDeltaMinutes?: number;
+    readonly escapedIncompleteDelta?: number;
+}
+interface BenchmarkSummary {
+    readonly totalRuns: number;
+    readonly stateCounts: Readonly<Record<RunState, number>>;
+    readonly completeRuns: number;
+    readonly retriedRuns: number;
+    readonly staleRuns: number;
+    readonly firstAttemptRuns: number;
+    readonly humanApprovedRuns: number;
+    readonly authorizedRuns: number;
+    readonly effectiveRunCount: number;
+    readonly effectiveCompleteRuns: number;
+    readonly effectiveCompletionRate: number | null;
+    readonly effectiveCheckPassRate: number | null;
+    readonly effectiveOutcomePassRate: number | null;
+    readonly effectiveEvidenceCoverageRate: number | null;
+    readonly checkPassRate: number | null;
+    readonly outcomePassRate: number | null;
+    readonly evidenceCoverageRate: number | null;
+    readonly firstAttemptApprovalRate: number | null;
+    readonly retryRate: number | null;
+    readonly staleRate: number | null;
+    readonly averageDurationMs: number | null;
+    readonly medianDurationMs: number | null;
+}
+interface BenchmarkReport {
+    readonly type: 'agentskit-harness-benchmark';
+    readonly schemaVersion: typeof BENCHMARK_SCHEMA_VERSION;
+    readonly stateDir: string;
+    readonly generatedAt: string;
+    readonly runs: readonly BenchmarkRun[];
+    readonly summary: BenchmarkSummary;
+    readonly manifest?: {
+        readonly suiteId: string;
+        readonly taskCount: number;
+        readonly baselineCount: number;
+        readonly comparableTaskCount: number;
+    };
+    readonly comparisons: readonly BenchmarkComparison[];
+    readonly qualityGate: BenchmarkQualityGate;
+}
+interface BenchmarkObservationInput {
+    readonly taskId: string;
+    readonly status: BenchmarkObservationStatus;
+    readonly source: string;
+    readonly recordedAt?: string;
+    readonly attempts?: number;
+    readonly durationMs?: number;
+    readonly durationSamplesMs?: readonly number[];
+    readonly artifactAcceptanceRate?: number;
+    readonly protocolCompletionRate?: number;
+    readonly reviewMinutes?: number;
+    readonly escapedIncomplete?: number;
+    readonly evidence?: readonly BenchmarkObservationEvidence[];
+    readonly evidenceDigest?: string;
+}
+declare const validateBenchmarkManifest: (value: unknown) => BenchmarkManifest;
+declare const loadBenchmarkManifest: (path: string) => BenchmarkManifest;
+declare const recordBenchmarkObservation: (path: string, input: BenchmarkObservationInput) => BenchmarkManifest;
+declare const benchmarkRuns: (stateDir: string, manifest?: BenchmarkManifest) => BenchmarkReport;
+
+type ExternalCodingBenchmarkStatus = 'ok' | 'partial' | 'fail' | 'timeout';
+interface ExternalCodingBenchmarkRow {
+    readonly providerId: string;
+    readonly status: ExternalCodingBenchmarkStatus;
+    readonly completenessScore: number;
+    readonly fileEditCount: number;
+    readonly summary: string;
+    readonly durationMs?: number;
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly costUsd?: number;
+    readonly successPassed?: boolean;
+}
+interface ExternalCodingBenchmarkReport {
+    readonly kind: string;
+    readonly prompt: string;
+    readonly dryRun: boolean;
+    readonly isolateWorktrees: boolean;
+    readonly repoRoot: string;
+    readonly rows: readonly ExternalCodingBenchmarkRow[];
+}
+/**
+ * Validates the stable report shape emitted by AgentsKit OS coding benchmarks.
+ * Provider heuristics remain observations; this function never grants human acceptance.
+ */
+declare const validateExternalCodingBenchmarkReport: (value: unknown) => ExternalCodingBenchmarkReport;
+
+interface PolicyRule {
+    readonly id: string;
+    readonly effect: 'allow' | 'block' | 'approve';
+    readonly toolIds: readonly string[];
+    readonly reason: string;
+}
+interface PolicyRequest {
+    readonly actionId: string;
+    readonly turnId: string;
+    readonly toolId: string;
+    readonly argumentsHash: string;
+}
+interface PolicyDecision {
+    readonly decision: 'allow' | 'block' | 'approve';
+    readonly policyId: string;
+    readonly reason: string;
+}
+interface PolicyGate {
+    evaluate(request: PolicyRequest): PolicyDecision;
+}
+declare const createPolicyGate: ({ rules }: {
+    readonly rules: readonly PolicyRule[];
+}) => PolicyGate;
+
+interface AgentAdapter {
+    readonly id: string;
+    readonly version: string;
+    readonly capabilities: readonly string[];
+}
+interface AgentSessionOptions {
+    readonly stateDir: string;
+    readonly run: VerificationRun;
+    readonly adapter: AgentAdapter;
+    readonly policy: PolicyGate;
+    readonly runtime: ToolRuntime;
+    readonly sessionId?: string;
+    readonly resume?: boolean;
+}
+interface SessionRecorder {
+    readonly sessionId: string;
+    startTurn(inputHash: string, turnId?: string): HarnessEvent<'agent.turn.started'>;
+    requestTool(input: {
+        readonly turnId: string;
+        readonly toolId: string;
+        readonly argumentsHash: string;
+        readonly actionId?: string;
+    }): HarnessEvent<'tool.requested'> | HarnessEvent<'tool.approval.requested'>;
+    approveTool(input: {
+        readonly actionId: string;
+        readonly decision: 'approved' | 'rejected';
+        readonly actor?: 'human';
+    }): HarnessEvent<'tool.requested'> | HarnessEvent<'tool.blocked'>;
+    recoverTool(input: {
+        readonly actionId: string;
+        readonly decision: 'retry' | 'abandon';
+        readonly actor?: 'human';
+    }): HarnessEvent<'tool.recovery.recorded'> | HarnessEvent<'tool.blocked'>;
+    completeTool(input: {
+        readonly actionId: string;
+        readonly resultHash: string;
+        readonly durationMs: number;
+        readonly runtimeEvidence?: ToolExecutionResult['runtimeEvidence'];
+    }): HarnessEvent<'tool.completed'>;
+    failTool(input: {
+        readonly actionId: string;
+        readonly errorCode: string;
+        readonly retryable: boolean;
+        readonly durationMs: number;
+        readonly runtimeEvidence?: ToolExecutionResult['runtimeEvidence'];
+    }): HarnessEvent<'tool.failed'>;
+    executeTool(input: {
+        readonly actionId: string;
+        readonly arguments: unknown;
+    }): Promise<ToolExecutionResult>;
+    end(status: 'completed' | 'failed' | 'cancelled'): HarnessEvent<'session.ended'>;
+}
+declare const createSessionRecorder: ({ stateDir, run, adapter, policy, runtime, sessionId, resume }: AgentSessionOptions) => SessionRecorder;
+
+declare const EVIDENCE_BUNDLE_SCHEMA_VERSION: 1;
+interface EvidenceBundleFile {
+    readonly path: string;
+    readonly sha256: string;
+    readonly contentBase64: string;
+}
+interface EvidenceBundleSignature {
+    readonly algorithm: 'ed25519';
+    readonly keyId: string;
+    readonly publicKeyPem: string;
+    readonly signatureBase64: string;
+}
+interface TrustedEvidenceKey {
+    readonly keyId: string;
+    readonly publicKeyPem: string;
+    readonly status: 'active' | 'revoked';
+}
+interface EvidenceBundle {
+    readonly type: 'agentskit-harness-evidence-bundle';
+    readonly schemaVersion: typeof EVIDENCE_BUNDLE_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly signerKeyId: string;
+    readonly sourceRevision: string;
+    readonly configHash: string;
+    readonly contractHash: string;
+    readonly verificationDigest: string;
+    readonly eventLog: EventLogVerification;
+    readonly files: readonly EvidenceBundleFile[];
+    readonly payloadHash: string;
+    readonly signature: EvidenceBundleSignature;
+}
+interface EvidenceBundleVerification {
+    readonly status: 'verified';
+    readonly runId: string;
+    readonly payloadHash: string;
+    readonly fileCount: number;
+    readonly signed: true;
+}
+declare const exportEvidenceBundle: ({ configPath, runId, outputPath, privateKeyPath, keyId }: {
+    readonly configPath: string;
+    readonly runId?: string;
+    readonly outputPath: string;
+    readonly privateKeyPath: string;
+    readonly keyId: string;
+}) => Promise<EvidenceBundle>;
+declare const verifyEvidenceBundle: (path: string, { trustedKeys }?: {
+    readonly trustedKeys?: readonly TrustedEvidenceKey[];
+}) => EvidenceBundleVerification;
+declare const readEvidenceTrustStore: (path: string) => readonly TrustedEvidenceKey[];
+
+export { type AgentAdapter, type AgentSessionOptions, BENCHMARK_SCHEMA_VERSION, type BenchmarkBinding, type BenchmarkComparison, type BenchmarkConfidence, type BenchmarkImprovementDirection, type BenchmarkManifest, type BenchmarkObservation, type BenchmarkObservationEvidence, type BenchmarkObservationInput, type BenchmarkObservationStatus, type BenchmarkPolicy, type BenchmarkQualityGate, type BenchmarkReport, type BenchmarkRun, type BenchmarkSuiteSource, type BenchmarkSummary, type BenchmarkTask, type BenchmarkTaskFile, type BenchmarkTaskScope, type BenchmarkTaskSource, CHECK_CATEGORIES, CONTEXT_PROVIDER_SLOT, type CheckCategory, type CheckResult, type ContextProvider, type ContextQuery, type ContextReference, type ContextSnapshot, type ContractOutcome, type ContractScope, type Disposer, type DockerMount, type DockerRuntimeEvidence, type DockerToolDefinition, EVENT_LOG_GENESIS, EVIDENCE_BUNDLE_SCHEMA_VERSION, type EventLogLock, type EventLogLockRecovery, type EventLogLockStatus, type EventLogVerification, type EventStore, type EvidenceArtifact, type EvidenceBundle, type EvidenceBundleFile, type EvidenceBundleSignature, type EvidenceBundleVerification, type EvidenceReference, type ExternalCodingBenchmarkReport, type ExternalCodingBenchmarkRow, type ExternalCodingBenchmarkStatus, FileEventStore, HARNESS_EVENT_SCHEMA_VERSION, HARNESS_EVENT_TYPES, HARNESS_PLUGIN_API_VERSION, HarnessError, type HarnessEvent, type HarnessEventInput, type HarnessEventListener, type HarnessEventPayloads, type HarnessEventType, type HarnessPlugin, type HarnessPluginContext, LEGAL_TRANSITIONS, type LoadedConfig, type PluginContribution, type PluginRegistry, type PluginSlot, type PolicyDecision, type PolicyGate, type PolicyRequest, type PolicyRule, type ProcessToolDefinition, RUN_STATES, type RunOutcome, type RunReconciliation, type RunState, STATES, SURFACE_NAMES, type SessionRecorder, type SourceSnapshot, type StateTransition, type StructuredEvidence, type SurfaceName, type SurfaceRequirement, type TaskContract, type ToolDefinition, type ToolExecutionRequest, type ToolExecutionResult, type ToolRuntime, type TrackingConfig, type TrustedEvidenceKey, type VerificationCheck, type VerificationConfig, type VerificationRun, approveRun, approvedDecision, assertHuman, authorizeRun, benchmarkRuns, cancelRun, cleanTaskArtifacts, createDocBridgeContextProvider, createDockerToolRuntime, createPluginRegistry, createPluginSlot, createPolicyGate, createProcessToolRuntime, createSessionRecorder, createToolRuntime, exportEvidenceBundle, hashContextSnapshot, hashContextSnapshots, inspectEventLogLock, loadBenchmarkManifest, loadConfig, loadLatestRun, planRun, readContextSnapshots, readEvidenceTrustStore, reconcileRun, recordBenchmarkObservation, recoverEventLogLock, retryRun, startRun, transition, validateBenchmarkManifest, validateConfig, validateContextSnapshot, validateContextSnapshots, validateExternalCodingBenchmarkReport, verifyEvidenceBundle, verifyRun };