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

package/dist/emitter.d.ts

@@ -17,8 +17,15 @@
  * serial dispatch over isolated snapshots — §7.2: parallel names
  * isolation semantics, not scheduling.
  *
- * Fail-closed defaults: an `enforce`-mode emission with zero registered
- * interceptors yields `deny host_error:no_interceptor` (§7), and
+ * An emitter can also be built from a host declaration document (§7.7)
+ * through {@link InterceptionEmitter.fromDeclaration} and the path, JSON
+ * and value forms. The document is validated and resolved by the Rust
+ * core; this module runs the host's kind resolvers (step 11 of §7.7.6),
+ * seals the emitter (§7.7.7) and stamps the contract version on every
+ * record (§7.7.8).
+ *
+ * Fail-closed defaults: an `enforce`-mode emission with zero interceptors
+ * bound at the point yields `deny host_error:no_interceptor` (§7), and
  * {@link InterceptionEmitter.emit} **throws** {@link InterceptionBlocked}
  * on any block — the ignorable-result variant is the explicitly named
  * {@link InterceptionEmitter.emitUnchecked}.
@@ -27,22 +34,52 @@
  * on the event loop; sequence assignment and record append are atomic on
  * a single JS thread. Sharing one emitter across workers is unsupported.
  */
-import { AgentContext, ApprovalResolver, CompositionConfig, EnforcementMode, IdentityProvider, EmitOutcome, InterceptionRecord, Interceptor } from "./index";
+import { AgentContext, ApprovalResolver, CompositionConfig, EnforcementMode, IdentityProvider, EmitOutcome, InterceptionPoint, InterceptionRecord, Interceptor } from "./index";
+import { HostDeclaration, HostRegistry, ResolvedDeclaration } from "./declaration";
 /** §7 RECOMMENDED interceptor/resolver timeout (milliseconds). */
 export declare const DEFAULT_TIMEOUT_MS = 5000;
+export declare class EmitterSealed extends Error {
+    constructor(what: string);
+}
+/** Envelope facts for {@link InterceptionEmitter.recordHostFailure}:
+ * what the host still knows about an emission whose context it could
+ * not construct (§10.3 "Host projection failure"). Everything is
+ * optional — an absent member records the §10.3 unknown value
+ * (`session_id: ""`, `sequence: -1`, `timestamp` absent). */
+export interface HostFailure {
+    /** Payload-free failure detail — an exception **type name** or a
+     * path, never the content that failed to project (§14 data
+     * minimization). Recorded as the verdict `message` (truncated by
+     * the §10.3 projection). */
+    detail?: string;
+    /** `session.id` of the failed emission, when the host knows it. */
+    session_id?: string;
+    /** The sequence number the failed emission would have carried. The
+     * host SHOULD consume the next number from its context source so
+     * records stay totally ordered within the session (§10.3). */
+    sequence?: number;
+    /** RFC 3339 event time, when the host has one. */
+    timestamp?: string;
+}
 export declare class InterceptionEmitter {
-    private readonly mode;
-    private readonly resolver;
-    private readonly timeoutMs;
     private readonly interceptors;
     private _records;
     private composition;
     private identity;
-    private readonly names;
     private approvalRedactor;
     private recordSink;
     private maxRecords;
     private _recordsDropped;
+    private readonly mode;
+    private resolver;
+    /** §7 emitter-wide interceptor bound; `null` disables enforcement. */
+    private timeoutMs;
+    /** §9 resolver bound (`approval_resolver_ms`, §7.7.3); `null` disables. */
+    private resolverTimeoutMs;
+    /** §7.7.7: a declaration-built emitter refuses reconfiguration. */
+    private sealed;
+    /** The resolved declaration this emitter was built from, if any. */
+    private _declaration;
     /**
      * `timeoutMs` bounds each interceptor `intercept()` and resolver
      * `resolve()` call (§7, RECOMMENDED default 5000 ms); breach fails
@@ -52,12 +89,43 @@ export declare class InterceptionEmitter {
      * loop cannot be interrupted. `timeoutMs: null` disables enforcement.
      */
     constructor(mode?: EnforcementMode, resolver?: ApprovalResolver | null, timeoutMs?: number | null);
-    /** Race `fn`'s result against the §7 timeout. */
+    /** Build an emitter from a validated declaration: steps 8 to 11 of
+     * §7.7.6 (resolve against the registry's surface and names in the
+     * core, then run every binding's kind resolver). The result is
+     * sealed (§7.7.7) and stamps `declaration` on every record (§7.7.8).
+     * Throws {@link DeclarationError} on refusal; no emitter exists then. */
+    static fromDeclaration(declaration: HostDeclaration, registry: HostRegistry): InterceptionEmitter;
+    /** {@link HostDeclaration.fromPath} then {@link fromDeclaration}. */
+    static fromDeclarationPath(path: string, registry: HostRegistry): Promise<InterceptionEmitter>;
+    /** {@link HostDeclaration.fromJson} then {@link fromDeclaration}. */
+    static fromDeclarationJson(text: string, registry: HostRegistry): InterceptionEmitter;
+    /** {@link HostDeclaration.fromValue} then {@link fromDeclaration}. */
+    static fromDeclarationValue(value: unknown, registry: HostRegistry): InterceptionEmitter;
+    /** The resolved declaration this emitter runs under, when it was
+     * built from one (§7.7.7). Its canonical JSON is the equivalence
+     * oracle for the construction paths. The value is frozen all the
+     * way down: writing through it has no effect on dispatch or records.
+     * `null` for an emitter configured in code. */
+    get declaration(): ResolvedDeclaration | null;
+    /** Step 11 and construction. Every reference is looked up again in
+     * the registry's own maps, so bookkeeping drift between the names the
+     * core checked and what the registry holds fails closed. */
+    private static fromResolved;
+    /** §7.7.7: a declaration-built emitter refuses reconfiguration;
+     * otherwise the declaration would not be what ran. */
+    private unsealed;
+    /** Race `fn`'s result against a timeout (§7). `limitMs: null` runs
+     * unbounded. */
     private withTimeout;
     get records(): readonly InterceptionRecord[];
     /** Register an interceptor, optionally with a host-chosen
-     * payload-free `name` recorded on `verdicts[].name` (§10.3). */
-    register(interceptor: Interceptor, name?: string): this;
+     * payload-free `name` recorded on `verdicts[].name` (§10.3) and the
+     * points it runs at (`at`; omitted = every point). At point P the
+     * interceptors that run are those bound there, in registration
+     * order; `interceptors_registered`, `verdicts[].index` and
+     * `decided_by` count and index that list (§7.7.8). Throws
+     * {@link EmitterSealed} on a declaration-built emitter. */
+    register(interceptor: Interceptor, name?: string, at?: Iterable<InterceptionPoint>): this;
     /**
      * Declare the composition profile for subsequent emissions (§7.1).
      * The profile and knob values are validated against the closed §7.2
@@ -88,7 +156,8 @@ export declare class InterceptionEmitter {
     /** Register a per-emission record callback (§10.3), invoked
      * synchronously after every emission before buffering; a sink
      * exception is swallowed (audit delivery is the host's liveness
-     * concern, not the control plane's). */
+     * concern, not the control plane's). Allowed on a sealed emitter: it
+     * changes where records go, not what they say (§7.7.7). */
     setRecordSink(sink: (record: InterceptionRecord) => void): this;
     /** Bound the in-memory record buffer: when full, the OLDEST record
      * is dropped and {@link recordsDropped} increments. Unbounded by
@@ -110,6 +179,33 @@ export declare class InterceptionEmitter {
      * caller MUST inspect `proceeds` and halt the guarded action itself;
      * prefer {@link emit}. */
     emitUnchecked(ctx: AgentContext): Promise<InterceptionRecord>;
+    /** §10.3/§11 host projection failure: synthesize and deliver the
+     * fail-closed record for an emission whose `AgentContext` the host
+     * could not construct at all — its own projection to the wire failed
+     * before anything existed to {@link emit} (e.g. a tool-call argument
+     * getter threw during to-wire conversion at the chat seam). Without
+     * this the host can only fail the action closed *recordless*; with
+     * it the trail stays complete under host-side faults.
+     *
+     * The record is the §10.3 rejection shape: the payload-free
+     * projection of a `deny host_error:context_invalid` carrying
+     * `failure.detail` (payload-free: a type name or path, never
+     * content) as its message; `null` identities under the declared
+     * provider; `decided_by: null`; no per-interceptor summaries (no
+     * interceptor ran); envelope members from {@link HostFailure}, with
+     * the §10.3 unknown values (`""`/`-1`) where absent. It takes the
+     * next slot in the record stream (sink, then buffer) like any
+     * emission. In `enforce` mode the host MUST still fail the action
+     * closed; in `evaluate_only` the record documents the host fault
+     * without implying enforcement (§8). */
+    recordHostFailure(point: InterceptionPoint, failure?: HostFailure): InterceptionRecord;
+    /** Deliver a record to the sink and the bounded buffer (§10.3). */
+    private deliver;
+    /** The interceptors bound at the context's point, in dispatch order
+     * (§7.7.8). */
+    private active;
+    /** The bound a registration runs under: its own, else the emitter's. */
+    private limit;
     /** Profile dispatch (§7.4–§7.5). Returns the combined verdict and
      * its record metadata. */
     private dispatch;
@@ -125,7 +221,7 @@ export declare class InterceptionEmitter {
      * short-circuits; a liftable deny consults the seam, then `stop` or
      * `resume` per the knob.
      *
-     * `perInterceptor` stays index-aligned with registration order (one
+     * `perInterceptor` stays index-aligned with dispatch order (one
      * entry per invoked interceptor, §10.3 summaries); `pool`
      * additionally holds substituted resolutions for the §7.3 unions. */
     private dispatchFirstDeny;
@@ -147,12 +243,12 @@ export declare class InterceptionEmitter {
     private aggregateAndConsult;
     /** Apply (enforce) or validate (evaluate_only) one transform (§7.4, §8). */
     private foldTransform;
-    /** The declared provider's output for `ctx` (§10.1); `null` iff the
-     * provider is `null`. Throws {@link AgentHooksCoreError} iff the
-     * provider rejected the context (§10.2 fail-closed value domain). */
     /** Custom-provider identity, or null when the provider fails (the
      * emission has already been decided at this point). */
     private tryCustomIdentity;
+    /** The declared provider's output for `ctx` (§10.1); `null` iff the
+     * provider is `null`. Throws {@link AgentHooksCoreError} iff the
+     * provider rejected the context (§10.2 fail-closed value domain). */
     private identityOf;
     /** Consult the approval seam for a liftable deny (§9), when the
      * profile conditions allow it: `enforce` mode, not `agent_shutdown`,