engineering-behavior-observatory 0.2.1

package/dist/src/normalization-integrity.d.ts

@@ -0,0 +1,128 @@
+import { type AdapterCapability, type AdapterCapabilityProfile, type NativeEvidenceReference, type NativeEvidenceResolver, type NormalizationInput, type NormalizationResult, type UniformEventFamily } from "./uniform-events.js";
+type DigestString = `sha256:${string}`;
+export type NormalizedNativeRecord = {
+    reference: NativeEvidenceReference;
+    nativeType: string;
+    digest: DigestString;
+};
+export type NormalizedContentReference = {
+    reference: NativeEvidenceReference;
+    digest: DigestString;
+};
+export type NormalizedDataset = NormalizationResult & {
+    schemaVersion: "ebo.normalized-dataset/v1";
+    runId: string;
+    attemptId: string;
+    adapter: {
+        id: string;
+        version: string;
+        harness: string;
+    };
+    capabilityProfile: AdapterCapabilityProfile;
+    nativeRecords: readonly NormalizedNativeRecord[];
+    contentReferences: readonly NormalizedContentReference[];
+};
+export type AdapterCoverageReport = {
+    schemaVersion: "ebo.adapter-coverage-report/v1";
+    runId: string;
+    attemptId: string;
+    adapter: NormalizedDataset["adapter"];
+    records: {
+        total: number;
+        mapped: number;
+        unmapped: number;
+    };
+    nativeTypes: ReadonlyArray<{
+        nativeType: string;
+        total: number;
+        mapped: number;
+        unmapped: number;
+    }>;
+    families: Record<UniformEventFamily, {
+        capability: AdapterCapability;
+        observedEvents: number;
+    }>;
+    evidence: AdapterCapabilityProfile["evidence"];
+};
+export type NormalizedDatasetInput<NativeRecord> = {
+    capture: NormalizationInput<NativeRecord>;
+    normalization: NormalizationResult;
+    capabilityProfile: AdapterCapabilityProfile;
+    adapterVersion: string;
+    nativeType(record: NativeRecord): string;
+    contentDigest?(reference: NativeEvidenceReference): DigestString | undefined;
+};
+export type ComparisonCapability = `family:${UniformEventFamily}` | `evidence:${keyof AdapterCapabilityProfile["evidence"]}`;
+export type ComparisonCandidate = {
+    id: string;
+    manifestDigest: DigestString;
+    adapterVersion: string;
+    task: {
+        id: string;
+        digest: DigestString;
+    };
+    fixture: {
+        id: string;
+        digest: DigestString;
+    };
+    model: {
+        id: string;
+        configurationDigest: DigestString;
+    };
+    harness: {
+        id: string;
+        version: string;
+        configurationDigest: DigestString;
+    };
+    assessmentMode: "observational" | "verified";
+    captureProfileDigest: DigestString;
+    budgetDigest: DigestString;
+    toolPolicyDigest: DigestString;
+    capabilityProfile: AdapterCapabilityProfile;
+};
+export type ComparisonRequest = {
+    schemaVersion: "ebo.comparison-request/v2";
+    measure: string;
+    left: ComparisonCandidate;
+    right: ComparisonCandidate;
+    policy: {
+        declaredDifferences: ReadonlyArray<"model" | "harness">;
+        requiredCapabilities: readonly ComparisonCapability[];
+    };
+};
+export type ComparisonReason = {
+    code: "task-mismatch" | "fixture-mismatch" | "material-configuration-mismatch" | "undeclared-model-difference" | "declared-model-difference" | "undeclared-harness-difference" | "declared-harness-difference" | "capability-unsupported" | "capability-partial";
+    dimension: string;
+    detail: string;
+};
+export type ComparisonReport = {
+    schemaVersion: "ebo.comparison-report/v2";
+    measure: string;
+    requestDigest: DigestString;
+    status: "supported" | "qualified-with-caveats" | "unsupported";
+    candidates: [string, string];
+    policy: ComparisonRequest["policy"];
+    reasons: readonly ComparisonReason[];
+};
+export type LegacyComparisonRequest = {
+    schemaVersion: "ebo.comparison-request/v1";
+    left: Omit<ComparisonCandidate, "manifestDigest">;
+    right: Omit<ComparisonCandidate, "manifestDigest">;
+    policy: ComparisonRequest["policy"];
+};
+export type LegacyComparisonReport = {
+    schemaVersion: "ebo.comparison-report/v1";
+    status: ComparisonReport["status"];
+    candidates: [string, string];
+    reasons: readonly ComparisonReason[];
+};
+export declare function describeNormalizedDataset<NativeRecord>(input: NormalizedDatasetInput<NativeRecord>): NormalizedDataset;
+export declare function createCapturedNativeEvidenceResolver<NativeRecord>(capture: NormalizationInput<NativeRecord>, fallback?: NativeEvidenceResolver): NativeEvidenceResolver;
+export declare function validateNormalizedDataset(dataset: NormalizedDataset, resolver: NativeEvidenceResolver): Promise<AdapterCoverageReport>;
+export declare function validateNormalizedCorpus(entries: ReadonlyArray<{
+    dataset: NormalizedDataset;
+    resolver: NativeEvidenceResolver;
+}>): Promise<readonly AdapterCoverageReport[]>;
+export declare function assessComparisonEligibility(request: ComparisonRequest): ComparisonReport;
+export declare function assessLegacyComparisonEligibility(request: LegacyComparisonRequest): LegacyComparisonReport;
+export {};

package/dist/src/normalization-integrity.js

@@ -0,0 +1,429 @@
+import { canonicalizeMetadata, digestMetadata, validateArtifact } from "./artifacts.js";
+import { UNIFORM_EVENT_FAMILIES, validateUniformEvents, } from "./uniform-events.js";
+export function describeNormalizedDataset(input) {
+    if (!["qualified", "qualified-with-gaps"].includes(input.capture.qualification)) {
+        throw new Error("Normalized datasets require capture-qualified evidence.");
+    }
+    const nativeRecords = input.capture.records.map(({ reference, record }) => ({
+        reference: structuredClone(reference),
+        nativeType: required(input.nativeType(record), "Native record type"),
+        digest: digestString(digestMetadata(record)),
+    }));
+    const nativeDigests = new Map(nativeRecords.map((record) => [referenceKey(record.reference), record.digest]));
+    const contentReferences = new Map();
+    for (const event of input.normalization.events) {
+        if (event.content.status !== "known")
+            continue;
+        for (const { nativeReference: reference } of event.content.value) {
+            const key = referenceKey(reference);
+            const containing = containingReference(reference);
+            const digest = nativeDigests.get(key)
+                ?? (containing === undefined ? undefined : nativeDigests.get(referenceKey(containing)))
+                ?? input.contentDigest?.(reference);
+            if (digest === undefined)
+                throw new Error(`Content reference ${formatReference(reference)} requires a trusted digest.`);
+            const existing = contentReferences.get(key);
+            if (existing !== undefined && existing.digest !== digest) {
+                throw new Error(`Content reference ${formatReference(reference)} has conflicting digests.`);
+            }
+            contentReferences.set(key, { reference: structuredClone(reference), digest });
+        }
+    }
+    return {
+        schemaVersion: "ebo.normalized-dataset/v1",
+        runId: input.capture.runId,
+        attemptId: input.capture.attemptId,
+        adapter: {
+            id: input.capabilityProfile.adapterId,
+            version: required(input.adapterVersion, "Adapter version"),
+            harness: input.capabilityProfile.harness,
+        },
+        capabilityProfile: structuredClone(input.capabilityProfile),
+        nativeRecords,
+        contentReferences: [...contentReferences.values()],
+        events: structuredClone(input.normalization.events),
+        unmapped: structuredClone(input.normalization.unmapped),
+    };
+}
+export function createCapturedNativeEvidenceResolver(capture, fallback) {
+    const records = new Map(capture.records.map(({ reference, record }) => [
+        referenceKey(reference),
+        {
+            record,
+            resolution: {
+                runId: capture.runId,
+                attemptId: capture.attemptId,
+                digest: digestString(digestMetadata(record)),
+            },
+        },
+    ]));
+    return {
+        async resolve(reference) {
+            const exact = records.get(referenceKey(reference));
+            if (exact !== undefined)
+                return exact.resolution;
+            const fallbackResolution = await fallback?.resolve(reference);
+            if (fallbackResolution) {
+                if (typeof fallbackResolution !== "boolean") {
+                    return fallbackResolution.runId === capture.runId && fallbackResolution.attemptId === capture.attemptId
+                        ? fallbackResolution
+                        : false;
+                }
+                const containing = containingNativeRecord(records, reference);
+                return containing !== undefined && resolvesJsonPointer(containing.record, reference.recordLocator)
+                    ? containing.resolution
+                    : false;
+            }
+            const containing = containingNativeRecord(records, reference);
+            if (containing !== undefined && resolvesJsonPointer(containing.record, reference.recordLocator)) {
+                return containing.resolution;
+            }
+            return false;
+        },
+    };
+}
+export async function validateNormalizedDataset(dataset, resolver) {
+    assertValidArtifact("normalized dataset", dataset);
+    if (dataset.adapter.id !== dataset.capabilityProfile.adapterId
+        || dataset.adapter.harness !== dataset.capabilityProfile.harness) {
+        throw new Error("Normalized dataset adapter identity does not match its capability profile.");
+    }
+    const recordByReference = new Map();
+    for (const record of dataset.nativeRecords) {
+        const key = referenceKey(record.reference);
+        if (recordByReference.has(key))
+            throw new Error("Normalized dataset contains duplicate native records.");
+        recordByReference.set(key, record);
+        const resolution = await resolver.resolve(record.reference);
+        if (resolution === false)
+            throw unresolved(record.reference);
+        if (typeof resolution === "boolean") {
+            throw new Error(`Native evidence reference ${formatReference(record.reference)} lacks run and digest integrity metadata.`);
+        }
+        assertResolution(dataset, record, resolution);
+    }
+    const contentByReference = new Map();
+    for (const content of dataset.contentReferences) {
+        const key = referenceKey(content.reference);
+        if (contentByReference.has(key))
+            throw new Error("Normalized dataset contains duplicate content references.");
+        contentByReference.set(key, content);
+    }
+    const usedContent = new Set();
+    for (const event of dataset.events) {
+        if (event.content.status !== "known")
+            continue;
+        for (const content of event.content.value) {
+            const key = referenceKey(content.nativeReference);
+            if (!contentByReference.has(key)) {
+                throw new Error(`Content reference ${formatReference(content.nativeReference)} has no expected digest.`);
+            }
+            usedContent.add(key);
+        }
+    }
+    if ([...contentByReference.keys()].some((key) => !usedContent.has(key))) {
+        throw new Error("Normalized dataset contains an unreferenced content digest.");
+    }
+    const ownedResolver = {
+        async resolve(reference) {
+            const resolution = await resolver.resolve(reference);
+            const expectedContent = contentByReference.get(referenceKey(reference));
+            return typeof resolution === "object"
+                && resolution.runId === dataset.runId
+                && resolution.attemptId === dataset.attemptId
+                && (expectedContent === undefined || resolution.digest === expectedContent.digest)
+                ? resolution
+                : false;
+        },
+    };
+    await validateUniformEvents(dataset.events, ownedResolver);
+    const mapped = new Set();
+    for (const event of dataset.events) {
+        if (event.runId !== dataset.runId || event.attemptId !== dataset.attemptId) {
+            throw new Error(`Uniform event "${event.id}" belongs to the wrong run or attempt.`);
+        }
+        if (event.source.harness !== dataset.adapter.harness) {
+            throw new Error(`Uniform event "${event.id}" belongs to the wrong harness.`);
+        }
+        const key = referenceKey(event.source.nativeReference);
+        const record = recordByReference.get(key);
+        if (record === undefined)
+            throw new Error(`Uniform event "${event.id}" does not identify a captured native record.`);
+        if (record.nativeType !== event.source.nativeType) {
+            throw new Error(`Uniform event "${event.id}" native type does not match its captured record.`);
+        }
+        if (!dataset.capabilityProfile.nativeTypes.includes(event.source.nativeType)) {
+            throw new Error(`Uniform event "${event.id}" uses undeclared native type "${event.source.nativeType}".`);
+        }
+        if (dataset.capabilityProfile.families[event.family].status === "unsupported") {
+            throw new Error(`Uniform event "${event.id}" uses unsupported event family "${event.family}".`);
+        }
+        assertEvidenceCapability(dataset.capabilityProfile.evidence.nativeOrder, event.nativeOrder.status, "nativeOrder");
+        assertEvidenceCapability(dataset.capabilityProfile.evidence.nativeTime, event.nativeTime.status, "nativeTime");
+        assertEvidenceCapability(dataset.capabilityProfile.evidence.parentage, event.relations.parent.status, "parentage");
+        assertEvidenceCapability(dataset.capabilityProfile.evidence.content, event.content.status, "content");
+        if (dataset.capabilityProfile.evidence.parentage.status === "unsupported" && event.relations.known.length > 0) {
+            throw new Error(`Uniform event "${event.id}" contradicts unsupported parentage.`);
+        }
+        mapped.add(key);
+    }
+    assertSourceLocalOrder(dataset);
+    const unmapped = new Set();
+    for (const entry of dataset.unmapped) {
+        const key = referenceKey(entry.reference);
+        if (unmapped.has(key))
+            throw new Error("Normalized dataset lists a native record as unmapped more than once.");
+        if (!recordByReference.has(key))
+            throw new Error("Normalized dataset lists an uncaptured native record as unmapped.");
+        unmapped.add(key);
+    }
+    for (const key of recordByReference.keys()) {
+        if (mapped.has(key) === unmapped.has(key)) {
+            throw new Error("Every native record must be mapped or explicitly retained as unmapped.");
+        }
+    }
+    return coverageReport(dataset, mapped, unmapped);
+}
+export async function validateNormalizedCorpus(entries) {
+    const attempts = new Set();
+    const events = new Set();
+    const reports = [];
+    for (const { dataset, resolver } of entries) {
+        if (attempts.has(dataset.attemptId))
+            throw new Error(`Normalized corpus contains duplicate attempt ID "${dataset.attemptId}".`);
+        attempts.add(dataset.attemptId);
+        for (const event of dataset.events) {
+            const key = JSON.stringify([dataset.attemptId, event.id]);
+            if (events.has(key))
+                throw new Error(`Normalized corpus contains duplicate event ID "${event.id}" in attempt "${dataset.attemptId}".`);
+            events.add(key);
+        }
+        reports.push(await validateNormalizedDataset(dataset, resolver));
+    }
+    return reports;
+}
+export function assessComparisonEligibility(request) {
+    assertValidArtifact("comparison request", request);
+    const blockers = [];
+    const caveats = [];
+    compareExact(request.left.task, request.right.task, "task", "task-mismatch", blockers);
+    compareExact(request.left.fixture, request.right.fixture, "fixture", "fixture-mismatch", blockers);
+    for (const [dimension, left, right] of [
+        ["assessment mode", request.left.assessmentMode, request.right.assessmentMode],
+        ["capture profile", request.left.captureProfileDigest, request.right.captureProfileDigest],
+        ["budget", request.left.budgetDigest, request.right.budgetDigest],
+        ["tool policy", request.left.toolPolicyDigest, request.right.toolPolicyDigest],
+    ]) {
+        if (left !== right)
+            blockers.push({
+                code: "material-configuration-mismatch",
+                dimension,
+                detail: `${dimension} differs between the proposed comparison candidates.`,
+            });
+    }
+    compareDeclaredCondition("model", request.left.model, request.right.model, request.policy.declaredDifferences, blockers, caveats);
+    compareDeclaredCondition("harness", request.left.harness, request.right.harness, request.policy.declaredDifferences, blockers, caveats);
+    if (request.left.harness.id === request.right.harness.id
+        && (request.left.capabilityProfile.adapterId !== request.right.capabilityProfile.adapterId
+            || request.left.adapterVersion !== request.right.adapterVersion)) {
+        blockers.push({
+            code: "material-configuration-mismatch",
+            dimension: "normalization adapter",
+            detail: "normalization adapter identity differs for the same harness condition.",
+        });
+    }
+    for (const capability of request.policy.requiredCapabilities) {
+        for (const candidate of [request.left, request.right]) {
+            const value = candidateCapability(candidate, capability);
+            if (value.status === "unsupported")
+                blockers.push({
+                    code: "capability-unsupported",
+                    dimension: capability,
+                    detail: `${candidate.id} does not support required capability ${capability}.`,
+                });
+            else if (value.status === "partial")
+                caveats.push({
+                    code: "capability-partial",
+                    dimension: capability,
+                    detail: `${candidate.id} only partially supports required capability ${capability}.`,
+                });
+        }
+    }
+    const reasons = [...blockers, ...caveats];
+    const report = {
+        schemaVersion: "ebo.comparison-report/v2",
+        measure: request.measure,
+        requestDigest: `sha256:${digestMetadata(request).value}`,
+        status: blockers.length > 0 ? "unsupported" : caveats.length > 0 ? "qualified-with-caveats" : "supported",
+        candidates: [request.left.id, request.right.id],
+        policy: structuredClone(request.policy),
+        reasons,
+    };
+    assertValidArtifact("comparison report", report);
+    return report;
+}
+export function assessLegacyComparisonEligibility(request) {
+    assertValidArtifact("comparison request", request);
+    const manifestDigest = `sha256:${"0".repeat(64)}`;
+    const report = assessComparisonEligibility({
+        ...structuredClone(request),
+        schemaVersion: "ebo.comparison-request/v2",
+        measure: "legacy-unspecified",
+        left: { ...structuredClone(request.left), manifestDigest },
+        right: { ...structuredClone(request.right), manifestDigest },
+    });
+    const legacy = {
+        schemaVersion: "ebo.comparison-report/v1",
+        status: report.status,
+        candidates: report.candidates,
+        reasons: report.reasons,
+    };
+    assertValidArtifact("comparison report", legacy);
+    return legacy;
+}
+function coverageReport(dataset, mapped, unmapped) {
+    const nativeTypes = new Map();
+    for (const record of dataset.nativeRecords) {
+        const counts = nativeTypes.get(record.nativeType) ?? { total: 0, mapped: 0, unmapped: 0 };
+        counts.total += 1;
+        if (mapped.has(referenceKey(record.reference)))
+            counts.mapped += 1;
+        else
+            counts.unmapped += 1;
+        nativeTypes.set(record.nativeType, counts);
+    }
+    const report = {
+        schemaVersion: "ebo.adapter-coverage-report/v1",
+        runId: dataset.runId,
+        attemptId: dataset.attemptId,
+        adapter: structuredClone(dataset.adapter),
+        records: { total: dataset.nativeRecords.length, mapped: mapped.size, unmapped: unmapped.size },
+        nativeTypes: [...nativeTypes].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([nativeType, counts]) => ({ nativeType, ...counts })),
+        families: Object.fromEntries(UNIFORM_EVENT_FAMILIES.map((family) => [family, {
+                capability: structuredClone(dataset.capabilityProfile.families[family]),
+                observedEvents: dataset.events.filter((event) => event.family === family).length,
+            }])),
+        evidence: structuredClone(dataset.capabilityProfile.evidence),
+    };
+    assertValidArtifact("adapter coverage report", report);
+    return report;
+}
+function assertResolution(dataset, record, resolution) {
+    if (resolution.runId !== dataset.runId || resolution.attemptId !== dataset.attemptId) {
+        throw new Error(`Native evidence reference ${formatReference(record.reference)} resolves to the wrong run or attempt.`);
+    }
+    if (resolution.digest !== record.digest) {
+        throw new Error(`Native evidence reference ${formatReference(record.reference)} has a digest mismatch.`);
+    }
+}
+function assertSourceLocalOrder(dataset) {
+    const last = new Map();
+    for (const event of dataset.events) {
+        if (event.nativeOrder.status !== "known")
+            continue;
+        const previous = last.get(event.nativeOrder.domain);
+        if (previous !== undefined && event.nativeOrder.value < previous) {
+            throw new Error(`Uniform event "${event.id}" violates source-local order domain "${event.nativeOrder.domain}".`);
+        }
+        last.set(event.nativeOrder.domain, event.nativeOrder.value);
+    }
+}
+function compareExact(left, right, dimension, code, blockers) {
+    if (canonicalizeMetadata(left) !== canonicalizeMetadata(right))
+        blockers.push({
+            code,
+            dimension,
+            detail: `${dimension} identity or digest differs between the proposed comparison candidates.`,
+        });
+}
+function compareDeclaredCondition(dimension, left, right, declared, blockers, caveats) {
+    if (canonicalizeMetadata(left) === canonicalizeMetadata(right))
+        return;
+    if (!declared.includes(dimension)) {
+        blockers.push({
+            code: dimension === "model" ? "undeclared-model-difference" : "undeclared-harness-difference",
+            dimension,
+            detail: `${dimension} differs but is not declared by the comparison policy.`,
+        });
+        return;
+    }
+    caveats.push({
+        code: dimension === "model" ? "declared-model-difference" : "declared-harness-difference",
+        dimension,
+        detail: `${dimension} differs as declared; results are qualified and do not establish causality.`,
+    });
+}
+function candidateCapability(candidate, capability) {
+    const [kind, name] = capability.split(":");
+    return kind === "family"
+        ? candidate.capabilityProfile.families[name]
+        : candidate.capabilityProfile.evidence[name];
+}
+function assertEvidenceCapability(capability, evidenceStatus, field) {
+    if ((capability.status === "unsupported") !== (evidenceStatus === "unsupported")
+        && capability.status !== "partial") {
+        throw new Error(`Adapter evidence capability contradicts event ${field}.`);
+    }
+}
+function assertValidArtifact(label, value) {
+    const errors = validateArtifact(label, value);
+    if (errors.length > 0)
+        throw new Error(errors.map(({ field, message }) => `${label} ${field}: ${message}`).join("\n"));
+}
+function digestString(digest) {
+    return `${digest.algorithm}:${digest.value}`;
+}
+function required(value, label) {
+    if (value.trim() === "")
+        throw new Error(`${label} is required.`);
+    return value;
+}
+function referenceKey(reference) {
+    return JSON.stringify([reference.artifactId, reference.recordLocator]);
+}
+function containingNativeRecord(records, reference) {
+    const containing = containingReference(reference);
+    return containing === undefined ? undefined : records.get(referenceKey(containing));
+}
+function containingReference(reference) {
+    const pointer = reference.recordLocator.indexOf("#");
+    const base = pointer > 0 ? reference.recordLocator.slice(0, pointer)
+        : pointer === 0 && reference.recordLocator.startsWith("#/") ? "#" : undefined;
+    return base === undefined ? undefined : { ...reference, recordLocator: base };
+}
+function resolvesJsonPointer(document, locator) {
+    const hash = locator.indexOf("#");
+    if (hash < 0)
+        return false;
+    const pointer = locator.slice(hash + 1);
+    if (pointer === "")
+        return true;
+    if (!pointer.startsWith("/"))
+        return false;
+    let current = document;
+    for (const encoded of pointer.slice(1).split("/")) {
+        if (/~(?:[^01]|$)/u.test(encoded))
+            return false;
+        const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (Array.isArray(current)) {
+            if (!/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= current.length)
+                return false;
+            current = current.at(Number(key));
+            continue;
+        }
+        if (typeof current !== "object" || current === null)
+            return false;
+        const property = Object.getOwnPropertyDescriptor(current, key);
+        if (property === undefined || !("value" in property))
+            return false;
+        current = property.value;
+    }
+    return true;
+}
+function formatReference(reference) {
+    return `${reference.artifactId}:${reference.recordLocator}`;
+}
+function unresolved(reference) {
+    return new Error(`Native evidence reference ${formatReference(reference)} is unresolved.`);
+}

package/dist/src/openhands-run.d.ts

@@ -0,0 +1,36 @@
+import { type OpenHandsCapture, type OpenHandsCaptureRequest } from "./openhands.js";
+import { type RunAttemptResult, type VerifierExecutionContext, type WorkspaceCoordinator } from "./lifecycle.js";
+import { type CaptureQualificationReport, type CapturedWorkspaceOutcome, type RunBundleDefinition, type RunManifest } from "./run-bundles.js";
+import type { NormalizationResult } from "./uniform-events.js";
+import type { VerifierResult } from "./verifiers.js";
+export type CaptureOpenHandsAgentServerVerifier = (context: VerifierExecutionContext, workspace: CapturedWorkspaceOutcome, workspacePath: string) => VerifierResult | Promise<VerifierResult>;
+export type OpenHandsAgentServerRunConfiguration = Omit<OpenHandsCaptureRequest, "runId" | "attemptId" | "startConversation" | "signal" | "onRecord"> & {
+    model: string;
+    startConversation: Record<string, unknown>;
+    serverWorkspacePath?: string;
+};
+export type CaptureOpenHandsAgentServerRunOptions = {
+    definition: RunBundleDefinition;
+    startingWorkspacePath: string;
+    workspace: WorkspaceCoordinator;
+    configuration: OpenHandsAgentServerRunConfiguration;
+    verifier?: CaptureOpenHandsAgentServerVerifier;
+    workspaceOutcomeExcludedDirectoryNames?: readonly string[];
+    workspaceOutcomeRespectsGitignore?: boolean;
+    workspaceOutcomeOmitsEmptyDirectories?: boolean;
+    signal?: AbortSignal;
+    maxWallClockMs?: number;
+    harnessBudgetMs?: number;
+    shutdownGraceMs?: number;
+};
+export type CaptureOpenHandsAgentServerRunResult = {
+    attempt: RunAttemptResult;
+    manifest: RunManifest;
+    qualification: CaptureQualificationReport;
+    capture?: OpenHandsCapture;
+    normalized?: NormalizationResult;
+    normalizationError?: string;
+    retainedWorkspacePath?: string;
+};
+/** Execute and retain one caller-configured OpenHands Agent Server attempt. */
+export declare function captureOpenHandsAgentServerRun(options: CaptureOpenHandsAgentServerRunOptions): Promise<CaptureOpenHandsAgentServerRunResult>;