@responsibleai/agent-hooks 0.1.0-alpha.5 → 0.1.0-beta.2

package/dist/declaration.d.ts

@@ -0,0 +1,393 @@
+/**
+ * Host declaration document (spec §7.7): the loader, the registry it
+ * resolves against, and the builder for the code path.
+ *
+ * A declaration is one JSON object that fixes a host's configuration
+ * (§7.1, §8, §10.1, §13.1), its declared surface (§13.1) and its
+ * interceptor bindings. It is a versioned contract of its own
+ * (`agent-hooks-declaration/<major>.<minor>`, §7.7.2), separate from
+ * the wire version `SPEC_VERSION` and from the package version.
+ *
+ * Every normative check lives in the Rust core. This module does the
+ * two things only the wrapper can do: read a file (step 1 of §7.7.6)
+ * and run the host's kind resolvers (step 11, in `emitter.ts`). Steps
+ * 2 to 10 cross the native boundary as JSON text, so a document yields
+ * the same refusal class here as in every other SDK.
+ */
+import { AgentContext, ApprovalResolver, CompositionConfig, CompositionProfile, EnforcementMode, InterceptionPoint, Interceptor, JsonValue, OnApproval, SynthesisPolicy } from "./index";
+/** The declaration contract version this SDK writes and accepts
+ * (§7.7.2). A test pins it to the core's `declaration_versions()`. */
+export declare const DECLARATION_VERSION = "agent-hooks-declaration/1.0";
+/** Every contract version the loader accepts (§7.7.2). Any other
+ * `declaration` value is refused as `declaration_error:version_unsupported`. */
+export declare const SUPPORTED_DECLARATION_VERSIONS: readonly string[];
+/** Largest document the text and file paths accept, in bytes (§7.7.3). */
+export declare const MAX_DOCUMENT_BYTES: number;
+/** Deepest nesting the text paths accept (§7.7.3). */
+export declare const MAX_DEPTH = 32;
+/** Most entries in `bindings` (§7.7.3). */
+export declare const MAX_BINDINGS = 256;
+/** Longest binding `id`, registered name and document `id` (§7.7.3). */
+export declare const MAX_ID_LEN = 64;
+/** Longest binding `kind` (§7.7.5). */
+export declare const MAX_KIND_LEN = 128;
+/** Longest refusal detail (§7.7.3). */
+export declare const MAX_DETAIL_LEN = 512;
+/** Largest `timeout_ms`, `interceptor_ms` and `approval_resolver_ms` (§7.7.3). */
+export declare const MAX_TIMEOUT_MS = 3600000;
+/** The closed capability vocabulary a surface may name (§7.7.4). */
+export declare const CAPABILITIES: readonly string[];
+/** The eleven refusal classes (§7.7.6), in pipeline order. */
+export declare const DeclarationErrorClass: Readonly<{
+    readonly Unreadable: "declaration_error:unreadable";
+    readonly Malformed: "declaration_error:malformed";
+    readonly VersionUnsupported: "declaration_error:version_unsupported";
+    readonly SpecUnsupported: "declaration_error:spec_unsupported";
+    readonly UnknownField: "declaration_error:unknown_field";
+    readonly InvalidField: "declaration_error:invalid_field";
+    readonly Inconsistent: "declaration_error:inconsistent";
+    readonly SurfaceUnsupported: "declaration_error:surface_unsupported";
+    readonly ReferenceUnresolved: "declaration_error:reference_unresolved";
+    readonly KindUnknown: "declaration_error:kind_unknown";
+    readonly BindingRejected: "declaration_error:binding_rejected";
+}>;
+export type DeclarationErrorClass = (typeof DeclarationErrorClass)[keyof typeof DeclarationErrorClass];
+/** One problem a load step found: a JSON pointer into the document
+ * (`/bindings/1/kind`; the empty string is the root) and a detail that
+ * names members, kinds and ids but never binding configuration. */
+export interface Finding {
+    pointer: string;
+    detail: string;
+}
+/** A refused declaration (§7.7.6). Carries one class, every finding
+ * that step produced and, for `version_unsupported`, the accepted
+ * version set. Thrown by every construction path; never a verdict. */
+export declare class DeclarationError extends Error {
+    /** The namespaced code, `declaration_error:<class>`. */
+    readonly code: DeclarationErrorClass;
+    readonly findings: readonly Finding[];
+    readonly accepted: readonly string[];
+    constructor(
+    /** The namespaced code, `declaration_error:<class>`. */
+    code: DeclarationErrorClass, findings: readonly Finding[], accepted?: readonly string[]);
+    /** One finding under `code`. */
+    static single(code: DeclarationErrorClass, pointer: string, detail: string): DeclarationError;
+    /** Rebuild the error the core reported across the native boundary:
+     * `code` is the `declaration_error:*` string and `detail` the JSON
+     * `{"findings": [...], "accepted": [...]}`. */
+    static fromCore(code: string, detail: string): DeclarationError;
+    /** Copy `findings` with every detail truncated to {@link MAX_DETAIL_LEN}. */
+    private static bound;
+    /** `code: pointer: detail; pointer: detail` (the Rust `Display`). */
+    private static describe;
+}
+/** A host registry programming error: a duplicate or reserved name, or
+ * a code surface the core rejects. Distinct from
+ * {@link DeclarationError}: the document is not at fault. */
+export declare class HostRegistryError extends Error {
+    constructor(detail: string);
+}
+/** What the host does with the run after a `host_error:*` deny at the
+ * tool seam (§6.2, §13.1). */
+export type ToolSeamPosture = "continue" | "terminate";
+/** Whether a build bounds interceptor and resolver execution (§7).
+ * This SDK always does, in its own event loop. */
+export type TimeoutSupport = "bounded" | "unbounded";
+/** The knob values a host supports for one profile (§13.1). Only the
+ * knobs the profile consults are present. */
+export interface KnobSupport {
+    on_approval?: OnApproval[];
+    on_disagreement?: SynthesisPolicy[];
+    on_transform_conflict?: SynthesisPolicy[];
+}
+/** Every value of every knob the profile consults (§7.2). */
+export declare function fullKnobSupport(profile: CompositionProfile): KnobSupport;
+/** The informative `host` block of a document. */
+export interface HostInfo {
+    name: string;
+    version?: string;
+}
+/** What the host's code can honour (§7.7.4, §13.1): the one value the
+ * loader checks a document against and the CTK derives the harness
+ * surface from. A document may select a subset of this, never more.
+ * The shape is the core's `HostSurface` JSON form. */
+export interface HostSurface {
+    /** Points the host emits. Always includes the §3.2 floor. */
+    interception_points: InterceptionPoint[];
+    /** Closed vocabulary ({@link CAPABILITIES}). */
+    capabilities: string[];
+    /** Profiles and the knob values supported under each. */
+    profiles: Partial<Record<CompositionProfile, KnobSupport>>;
+    /** The posture the code implements (§13.1). */
+    tool_seam_host_error: ToolSeamPosture;
+    /** Whether the host may declare `buffered_output: false` (§12.1a). */
+    streams_unbuffered: boolean;
+    /** The §12.1a exposure bound the host enforces. Required when
+     * `capabilities` names `incremental_output`. */
+    exposure_bound?: string;
+    /** Whether this build bounds execution. Always `"bounded"` here:
+     * the emitter races every call against its timeout. */
+    interceptor_timeout: TimeoutSupport;
+    /** Contract versions the host accepts; a subset of
+     * {@link SUPPORTED_DECLARATION_VERSIONS}. */
+    declaration_versions: string[];
+}
+/** Constructors for {@link HostSurface}. The core validates the
+ * surface (floor, pairs, closed vocabularies) when a document is
+ * resolved against it; a surface that fails there is a
+ * {@link HostRegistryError}, never a refusal of the document. */
+export declare const HostSurface: Readonly<{
+    /** The smallest honest surface for this SDK: the lifecycle floor,
+     * `host_declaration`, every profile with every knob value, posture
+     * `continue`, buffered output, bounded timeouts and every accepted
+     * contract version. A host adds what its runtime does. */
+    sdkDefault(): HostSurface;
+    /** The surface the CTK derives from a harness's capability list and
+     * posture (§7.7.9): the floor plus the model points iff
+     * `model_calls` plus the tool points iff `tool_calls`. A list naming
+     * `incremental_output` needs {@link HostSurface.withExposureBound}
+     * on top, or the core refuses the surface. */
+    fromCapabilities(caps: Iterable<string>, posture?: ToolSeamPosture): HostSurface;
+    /** Add points (the model pair, the tool pair, or both). */
+    withPoints(surface: HostSurface, points: Iterable<InterceptionPoint>): HostSurface;
+    /** Add capabilities. */
+    withCapabilities(surface: HostSurface, caps: Iterable<string>): HostSurface;
+    /** State the §12.1a exposure bound an incremental host enforces. Also
+     * marks the host as able to declare `buffered_output: false`. */
+    withExposureBound(surface: HostSurface, bound: string): HostSurface;
+}>;
+/** What a kind resolver learns about the binding it builds (§7.7.5). */
+export interface BindingContext {
+    id: string;
+    kind: string;
+    /** The resolved `at` set, in lifecycle order. */
+    at: readonly InterceptionPoint[];
+    /** The resolved per-binding bound in milliseconds; `null` is unbounded. */
+    timeoutMs: number | null;
+    host: HostInfo | null;
+    declarationVersion: string;
+}
+/** Host code that turns one binding's `config` into one interceptor,
+ * or refuses it by throwing. The thrown message MUST NOT echo the
+ * config (§7.7.5); the loader never does. */
+export type KindResolver = (config: JsonValue, context: BindingContext) => Interceptor;
+/** The names a registry holds, derived from what was registered and
+ * never hand-written (§7.7.5). */
+export interface RegistryNames {
+    identity_providers: string[];
+    approval_resolvers: string[];
+    approval_redactors: string[];
+    kinds: string[];
+}
+/** Reference grammar for resolver and redactor names and binding ids:
+ * `^[a-z][a-z0-9_-]{0,63}$`. */
+export declare function validReference(s: string): boolean;
+/** Binding kind grammar (§7.7.5): dot-separated lowercase segments, at
+ * least two, at most 128 characters. */
+export declare function validKind(s: string): boolean;
+/** Everything a host registers in code for a declaration to reference
+ * (§7.7.5): the code surface, kind resolvers, custom identity
+ * providers, approval resolvers and approval redactors. One registry
+ * can build many emitters. */
+export declare class HostRegistry {
+    readonly surface: HostSurface;
+    private readonly allowReserved;
+    private readonly kinds;
+    private readonly identityProviders;
+    private readonly approvalResolvers;
+    private readonly approvalRedactors;
+    /** A registry over the given code surface. Kinds under the reserved
+     * `agent_hooks` and `ctk` segments are refused. */
+    constructor(surface: HostSurface, allowReserved?: boolean);
+    /** The conformance kit's registry: as the constructor, but the `ctk`
+     * kind segment may be registered. */
+    static forConformance(surface: HostSurface): HostRegistry;
+    /** Register a kind resolver. */
+    kind(kind: string, resolver: KindResolver): this;
+    /** Register a custom identity provider (§10.1 name rules apply). */
+    identityProvider(name: string, fn: (ctx: AgentContext) => string): this;
+    /** Register an approval resolver under a reference name. */
+    approvalResolver(name: string, resolver: ApprovalResolver): this;
+    /** Register an approval redactor under a reference name. */
+    approvalRedactor(name: string, fn: (ctx: AgentContext) => AgentContext): this;
+    /** The registered names, derived (§7.7.5). */
+    names(): RegistryNames;
+    /** The `host_json` the core's `declaration_resolve` takes: the surface
+     * plus the registered names. */
+    hostDescription(): string;
+    /** @internal */
+    kindResolver(kind: string): KindResolver | undefined;
+    /** @internal */
+    identityFn(name: string): ((ctx: AgentContext) => string) | undefined;
+    /** @internal */
+    approvalResolverRef(name: string): ApprovalResolver | undefined;
+    /** @internal */
+    redactorFn(name: string): ((ctx: AgentContext) => AgentContext) | undefined;
+    private static checkReference;
+}
+/** A declaration that passed steps 2 to 7 (§7.7.6): parsed, of an
+ * accepted version, closed, well-typed and internally consistent as
+ * stated. Not yet checked against any host; `InterceptionEmitter.
+ * fromDeclaration` does that. */
+export declare class HostDeclaration {
+    private readonly doc;
+    private readonly text;
+    /** `text` is the core's serialization of the validated document and
+     * is what every later core call receives, so integers beyond 2^53
+     * inside `bindings[].config` reach steps 8 to 10 as the file had
+     * them. `doc` is the JavaScript view of the same text. */
+    private constructor();
+    /** Step 1 then {@link HostDeclaration.fromJson}: open exactly `path`,
+     * require a regular file of at most {@link MAX_DOCUMENT_BYTES},
+     * strict UTF-8 without a byte-order mark, read once. */
+    static fromPath(path: string): Promise<HostDeclaration>;
+    /** Steps 2 to 7 over JSON text, in the core. */
+    static fromJson(text: string): HostDeclaration;
+    /** Steps 2 to 7 over an in-memory value: serialized and handed to
+     * {@link HostDeclaration.fromJson}, so size, depth and shape checks
+     * are the same code on every path. A non-finite number, which
+     * `JSON.stringify` would corrupt to `null`, is refused as
+     * `malformed` first. */
+    static fromValue(value: unknown): HostDeclaration;
+    /** A builder for the code path (§7.7.7). */
+    static builder(): DeclarationBuilder;
+    /** The document's own `declaration` value. */
+    get version(): string;
+    /** The validated document, verbatim (including `$schema`). A copy.
+     * Integers beyond 2^53 inside `bindings[].config` are rounded in this
+     * view; {@link HostDeclaration.toJson} keeps them exact. */
+    toValue(): Record<string, JsonValue>;
+    /** @internal The validated document as JSON text, as the core
+     * serialized it. */
+    toJson(): string;
+}
+/** Resolved configuration: every default filled (§7.7.3). */
+export interface ResolvedConfiguration {
+    mode: EnforcementMode;
+    composition: CompositionConfig;
+    identity_provider: string | null;
+    approval: {
+        resolver: string | null;
+        redactor: string | null;
+    };
+    posture: {
+        tool_seam_host_error: ToolSeamPosture;
+    };
+    timeouts: {
+        interceptor_ms: number | null;
+        approval_resolver_ms: number | null;
+    };
+    records: {
+        max_buffered: number | null;
+    };
+}
+/** Resolved surface (§7.7.4): the document's, or the code's when the
+ * document stated none. */
+export interface ResolvedSurface {
+    interception_points: InterceptionPoint[];
+    capabilities: string[];
+    profiles: Partial<Record<CompositionProfile, KnobSupport>>;
+    buffered_output: boolean;
+    exposure_bound?: string;
+    declaration_versions: string[];
+}
+/** One binding with `at` and `timeout_ms` filled. */
+export interface ResolvedBinding {
+    id: string;
+    kind: string;
+    config: JsonValue;
+    at: InterceptionPoint[];
+    timeout_ms: number | null;
+}
+/** The resolved declaration (§7.7.3 "Resolved form"): every default
+ * filled, composition knobs resolved exactly as §7.2 resolves them,
+ * `$schema` dropped, sets sorted. Its canonical JSON
+ * ({@link canonicalDeclaration}) is the equivalence oracle for the
+ * construction paths (§7.7.7). */
+export interface ResolvedDeclaration {
+    declaration: string;
+    spec: string;
+    id?: string;
+    host?: HostInfo;
+    configuration: ResolvedConfiguration;
+    surface: ResolvedSurface;
+    bindings: ResolvedBinding[];
+    extensions: Record<string, JsonValue>;
+}
+/** RFC 8785 canonical JSON of a resolved declaration (the core's
+ * `canonical_json`). */
+export declare function canonicalDeclaration(resolved: ResolvedDeclaration): string;
+/** Steps 8 to 10 of §7.7.6 (after steps 2 to 7 again, in the core):
+ * resolve a validated declaration against the registry's surface and
+ * names. Throws {@link DeclarationError} on refusal. */
+export declare function resolveDeclaration(declaration: HostDeclaration, registry: HostRegistry): ResolvedDeclaration;
+/** Steps 7 (on the filled surface) and 8 against a code surface alone,
+ * without a registry: what the CTK runner uses on a harness's own
+ * document to learn the surface a run is assessed against (§7.7.9). */
+export declare function resolveSurfaceOnly(declaration: HostDeclaration, surface: HostSurface): ResolvedDeclaration;
+/** The contract versions the core writes and accepts (§7.7.2). */
+export declare function declarationVersions(): {
+    current: string;
+    supported: string[];
+};
+/** Builds a declaration document in code, one setter per member
+ * (§7.7.7). {@link DeclarationBuilder.build} hands the document to
+ * {@link HostDeclaration.fromValue}, so the code path is validated by
+ * the same function, with the same classes, as a file. */
+export declare class DeclarationBuilder {
+    private readonly doc;
+    /** A builder with `declaration` set to {@link DECLARATION_VERSION}
+     * and an empty `bindings` array. */
+    constructor();
+    /** A builder with no member set at all, not even `declaration` or
+     * `bindings`. For harnesses that must express an incomplete
+     * document; a host wants the constructor. */
+    static empty(): DeclarationBuilder;
+    private configuration;
+    private configurationSub;
+    private surface;
+    private sub;
+    /** `declaration` (defaults to {@link DECLARATION_VERSION}). */
+    version(v: string): this;
+    spec(v: string): this;
+    id(v: string): this;
+    host(name: string, version?: string): this;
+    mode(mode: EnforcementMode): this;
+    /** The composition as the host states it. Knobs the profile does not
+     * consult are written out and refused by {@link build}, exactly as
+     * in a file. */
+    composition(c: CompositionConfig): this;
+    /** A name for `jcs-sha256` or a custom provider, `null` for
+     * identity-unbound. */
+    identityProvider(name: string | null): this;
+    approvalResolver(name: string | null): this;
+    approvalRedactor(name: string | null): this;
+    toolSeamHostError(posture: ToolSeamPosture): this;
+    /** `null` writes `null` (unbounded). */
+    interceptorTimeoutMs(ms: number | null): this;
+    /** `null` writes `null` (unbounded). */
+    approvalResolverTimeoutMs(ms: number | null): this;
+    /** `null` writes `null` (unbounded). */
+    maxBufferedRecords(n: number | null): this;
+    surfacePoints(points: Iterable<InterceptionPoint>): this;
+    surfaceCapabilities(caps: Iterable<string>): this;
+    /** Declare support for one profile and its knob values. */
+    surfaceProfile(profile: CompositionProfile, knobs: KnobSupport): this;
+    /** `buffered_output` and, when `false`, the required exposure bound. */
+    bufferedOutput(buffered: boolean, exposureBound?: string): this;
+    surfaceDeclarationVersions(versions: Iterable<string>): this;
+    /** Append one binding. `at` omitted binds at every surface point;
+     * `timeoutMs` omitted inherits the configured interceptor timeout,
+     * `null` writes `null` (unbounded), a number bounds. */
+    bind(id: string, kind: string, config?: JsonValue, at?: Iterable<InterceptionPoint>, timeoutMs?: number | null): this;
+    /** One `extensions` entry, kept verbatim. */
+    extension(key: string, value: JsonValue): this;
+    /** Set a top-level member verbatim. For members this builder has no
+     * setter for; the result is validated like any other document (an
+     * unknown member is refused as `unknown_field`). */
+    raw(key: string, value: JsonValue): this;
+    /** The document as built, before validation. A copy. */
+    toValue(): Record<string, JsonValue>;
+    /** Validate (steps 2 to 7) through {@link HostDeclaration.fromValue}. */
+    build(): HostDeclaration;
+}