@sema-agent/core/dist/tools/artifact/conformance.d.ts

Stateless, task-oriented AI agent core

import { type ArtifactAction, type ArtifactHost, type ArtifactHostCapabilities, type ArtifactRef } from "../../core/artifact-host.js";
export interface ArtifactConformanceHooks {
    /** Make the host's NEXT write fail BEFORE its commit point (`arm`), then restore it (`disarm`). The atomicity vector
     *  runs only with this hook: the kit cannot reach inside an arbitrary host. */
    precommitFault?: {
        arm: () => void | Promise<void>;
        disarm: () => void | Promise<void>;
    };
    /** Save a new version of `ref`'s page from INSIDE the page — the version a plain `force` must not discard
     *  (`force_refused`). The force-refusal vector runs only with this hook. */
    pageSavedVersion?: (ref: ArtifactRef) => void | Promise<void>;
}
export interface ArtifactConformanceOptions {
    hooks?: ArtifactConformanceHooks;
    /** Run the at-limit POSITIVE arms of the byte-limit vector: they allocate and publish payloads of the declared
     *  sizes. Default `false` — reported `skipped`, named. The over-limit refusal arms always run. */
    largePayloads?: boolean;
    /** The run id the kit mounts (`onMount`) and calls under; default a fresh uuid. */
    runId?: string;
}
export type ArtifactConformanceStatus = "pass" | "fail" | "not_applicable" | "skipped";
export interface ArtifactConformanceVector {
    /** Stable id: a host's own conformance test keys on it. */
    id: string;
    describe: string;
    /** Every listed action must be declared for the vector to apply. */
    requiresActions: readonly ArtifactAction[];
    requiresMultiFile?: true;
    requiresHook?: keyof ArtifactConformanceHooks;
    requiresLargePayloads?: true;
}
export interface ArtifactConformanceResult {
    id: string;
    status: ArtifactConformanceStatus;
    /** What passed, what failed (the first violated expectation), or why the vector did not run. */
    detail: string;
}
export interface ArtifactConformanceReport {
    capabilities: ArtifactHostCapabilities;
    runId: string;
    results: readonly ArtifactConformanceResult[];
    passed: number;
    failed: number;
    notApplicable: number;
    skipped: number;
}
/** The full vector matrix (data; ids are stable). */
export declare const ARTIFACT_CONFORMANCE_VECTORS: readonly ArtifactConformanceVector[];
/** The vectors a host's DECLARATION covers (hook- and payload-gated vectors included: their gating is reported at run time). */
export declare function artifactConformanceVectors(host: ArtifactHost): ArtifactConformanceVector[];
/**
 * Drive `host` through every vector its declaration covers, sequentially, under one fresh run id (the host's
 * `onMount` is called first). Throws only when the declaration itself is invalid — every vector outcome, a thrown
 * host method included, is a row of the report.
 */
export declare function runArtifactConformance(host: ArtifactHost, opts?: ArtifactConformanceOptions): Promise<ArtifactConformanceReport>;