@sema-agent/core/dist/core/runner/env-capability-census.d.ts

Stateless, task-oriented AI agent core

import type { ExecutionEnv } from "../../internal/harness.js";
import type { EngineNotice } from "../engine-notice.js";
/** One declaration whose value is not the shape its seat takes, with the type it actually carries. */
export interface MalformedCapabilityDeclaration {
    readonly key: string;
    readonly valueType: string;
    /** The shape the seat takes: a `capabilities.*` boolean, or an optional seam method. */
    readonly expected: "boolean" | "function";
}
/**
 * Every boolean capability this env DECLARES with a value that is not a boolean.
 *
 * The probe is the VALUE, not membership, because the value is what the readers get: a `capabilities`
 * that answers `has` and `get` differently (a Proxy) would otherwise hide from the census exactly the
 * value a reader goes on to act on. `undefined` is where absence lands — an absent key and an explicit
 * `undefined` are the same word to every reader, and both are the documented silent reading — so one
 * test covers both and the census needs no membership rule at all.
 *
 * TOTAL by construction: a diagnostic may not be the thing that fails a run. Every read of the adapter
 * can throw on a getter or a Proxy trap — the structural probe, the block acquisition and each key —
 * and a read that throws is itself a declaration nobody can use, so all three are reported rather than
 * raised (`unreadable`, under the key when there is one and under `capabilities` when the block itself
 * could not be had).
 *
 * What a snapshot cannot promise: this is taken once, at admission. An adapter whose capability values
 * CHANGE afterwards can hand a later reader something this census never saw; the declaration is
 * documented as a constant property of the adapter, and a mutable one is outside what any one-time
 * reading covers.
 */
export declare function malformedCapabilityDeclarations(env: ExecutionEnv): MalformedCapabilityDeclaration[];
/** Announce each malformed declaration once, to the operator who wired the adapter. */
export declare function announceMalformedCapabilities(env: ExecutionEnv, onNotice: ((notice: EngineNotice) => void) | undefined): void;