@responsibleai/agent-hooks 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -5,7 +5,8 @@ TypeScript implementation of
 over the canonical Rust core (napi-rs native module): interception
 points, `AgentContextBuilder`, `Verdict` types, host-side
 `InterceptionEmitter` with the four composition profiles, the
-identity-provider seam, and the CTK runner.
+identity-provider seam, the host declaration loader, and the CTK
+runner.
 
 > **Trust model.** agent-hooks is a *cooperative contract*, not a security
 > boundary: the host framework is fully trusted, interceptors run in-process
@@ -44,11 +45,75 @@ const ctx = builder.preToolCall("tc-1", "http_get", { url });
 await emitter.emit(ctx); // throws InterceptionBlocked on a combined deny
 ```
 
+`register(interceptor, name?, at?)` also takes the points an
+interceptor runs at. At a point, `interceptors_registered`,
+`verdicts[].index` and `decided_by` count and index the interceptors
+bound there, in registration order.
+
+## Host declaration
+
+A host can load its configuration, declared surface and interceptor
+bindings from one JSON document (spec §7.7) instead of calling the
+setters. The document is a versioned contract,
+`agent-hooks-declaration/1.0`, separate from the wire version
+`agent-hooks/0.1`. The SDK exports the version it writes
+(`DECLARATION_VERSION`) and the set it accepts
+(`SUPPORTED_DECLARATION_VERSIONS`). A document of any other version is
+refused.
+
+```ts
+import {
+  HostDeclaration,
+  HostRegistry,
+  HostSurface,
+  InterceptionEmitter,
+} from "@responsibleai/agent-hooks";
+
+// What the code can honour. A document may select a subset, never more.
+const surface = HostSurface.fromCapabilities(["model_calls", "tool_calls", "host_declaration"]);
+
+// Kind resolvers turn a binding's `config` into an interceptor. A kind
+// is a lookup key the host names; the spec defines none.
+const registry = new HostRegistry(surface)
+  .kind("com.example.egress", (config, ctx) => new EgressGuard(config))
+  .approvalResolver("operator-queue", queue);
+
+const emitter = await InterceptionEmitter.fromDeclarationPath(
+  "agent-hooks.declaration.json",
+  registry,
+);
+```
+
+The three construction paths yield the same emitter and the same
+records: `fromDeclarationPath` reads a file, `fromDeclarationJson`
+takes the text, `fromDeclarationValue` takes a parsed object, and
+`fromDeclaration` takes a `HostDeclaration` (for example from
+`HostDeclaration.builder()`, one setter per member and `bind(...)` per
+binding). `emitter.declaration` is the resolved form with every default
+filled; `canonicalDeclaration(emitter.declaration)` is its RFC 8785
+canonical JSON, the equivalence oracle.
+
+A document that names anything the host cannot honour is refused at
+load, before any emission, with a `DeclarationError`. The error carries
+`code` (one of eleven `declaration_error:*` classes), `findings` (JSON
+pointer plus detail, never binding configuration) and, for
+`version_unsupported`, `accepted`. The Rust core runs every check, so
+the class is the same as in the other SDKs. An emitter built from a
+declaration is sealed: `register` and the setters throw
+`EmitterSealed`; `setRecordSink` and `takeRecords` stay allowed.
+Records from such an emitter carry `declaration:
+"agent-hooks-declaration/1.0"`; records from an emitter configured in
+code do not and are unchanged.
+
 **JavaScript value-domain caveat (spec §4.4):** `JSON.parse` rounds
 integers beyond 2^53 before any guard can run, so this SDK cannot claim
 the `int64_json`/`bigint_json` CTK capabilities — string-encode
 64-bit identifiers at the adapter boundary. Non-finite numbers are
-rejected fail-closed by a pre-serialization scan.
+rejected fail-closed by a pre-serialization scan. The same rounding
+applies to `bindings[].config`: the loader hands the core the validated
+text, so the load checks see the integers the file had, but the
+resolved form and a kind resolver receive JavaScript values.
+String-encode 64-bit values in binding configuration too.
 
 ## Native module deployment
 

package/binding.d.ts

@@ -27,6 +27,31 @@ export declare function ctkScriptedResolve(rulesJson: string, ctxJson: string, i
 
 export declare function ctkShouldSkip(vectorJson: string, harnessCapsJson: string): string
 
+/**
+ * Steps 2 to 10 of §7.7.6 against the wrapper's host description
+ * (`{surface, identity_providers, approval_resolvers,
+ * approval_redactors, kinds}`). Returns the resolved declaration JSON.
+ */
+export declare function declarationResolve(documentJson: string, hostJson: string): string
+
+/**
+ * Steps 2 to 8 of §7.7.6 against a code surface alone, no registry:
+ * what the CTK runner needs to read a harness's own document
+ * (§7.7.9). A surface that does not parse or that the core rejects is
+ * a wrapper defect and comes back as `marshal_error`, never as a
+ * refusal of the document.
+ */
+export declare function declarationResolveSurface(documentJson: string, surfaceJson: string): string
+
+/**
+ * Steps 2 to 7 of §7.7.6 over JSON text. Returns the validated
+ * document as JSON (verbatim, `$schema` included).
+ */
+export declare function declarationValidate(documentJson: string): string
+
+/** `{"current": "...", "supported": [...]}` (§7.7.2). */
+export declare function declarationVersions(): string
+
 export declare function finalize(ctxJson: string, verdictJson: string, mode: string, optionsJson: string): string
 
 export declare function specVersion(): string

package/binding.js

@@ -89,8 +89,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-android-arm64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -105,8 +105,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-android-arm-eabi')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -126,8 +126,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-win32-x64-gnu')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-win32-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -142,8 +142,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-win32-x64-msvc')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-win32-x64-msvc/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -159,8 +159,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-win32-ia32-msvc')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -175,8 +175,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-win32-arm64-msvc')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -194,8 +194,8 @@ function requireNative() {
     try {
       const binding = require('@responsibleai/agent-hooks-darwin-universal')
       const bindingPackageVersion = require('@responsibleai/agent-hooks-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -210,8 +210,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-darwin-x64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -226,8 +226,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-darwin-arm64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -246,8 +246,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-freebsd-x64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -262,8 +262,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-freebsd-arm64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -283,8 +283,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-x64-musl')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -299,8 +299,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-x64-gnu')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -317,8 +317,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-arm64-musl')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -333,8 +333,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-arm64-gnu')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -351,8 +351,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-arm-musleabihf')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -367,8 +367,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -385,8 +385,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-loong64-musl')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -401,8 +401,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-loong64-gnu')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -419,8 +419,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-riscv64-musl')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -435,8 +435,8 @@ function requireNative() {
         try {
           const binding = require('@responsibleai/agent-hooks-linux-riscv64-gnu')
           const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -452,8 +452,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-linux-ppc64-gnu')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -468,8 +468,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-linux-s390x-gnu')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -488,8 +488,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-openharmony-arm64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -504,8 +504,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-openharmony-x64')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -520,8 +520,8 @@ function requireNative() {
       try {
         const binding = require('@responsibleai/agent-hooks-openharmony-arm')
         const bindingPackageVersion = require('@responsibleai/agent-hooks-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.0-beta.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-beta.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -661,8 +661,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@responsibleai/agent-hooks-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '0.1.0-beta.1') {
-            throw new Error(`WASI binding package version mismatch, expected 0.1.0-beta.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-beta.2') {
+            throw new Error(`WASI binding package version mismatch, expected 0.1.0-beta.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@responsibleai/agent-hooks-wasm32-wasi')
@@ -787,6 +787,10 @@ module.exports.ctkAssert = nativeBinding.ctkAssert
 module.exports.ctkScriptedIntercept = nativeBinding.ctkScriptedIntercept
 module.exports.ctkScriptedResolve = nativeBinding.ctkScriptedResolve
 module.exports.ctkShouldSkip = nativeBinding.ctkShouldSkip
+module.exports.declarationResolve = nativeBinding.declarationResolve
+module.exports.declarationResolveSurface = nativeBinding.declarationResolveSurface
+module.exports.declarationValidate = nativeBinding.declarationValidate
+module.exports.declarationVersions = nativeBinding.declarationVersions
 module.exports.finalize = nativeBinding.finalize
 module.exports.specVersion = nativeBinding.specVersion
 module.exports.validateEnvelope = nativeBinding.validateEnvelope

package/dist/ctk/index.d.ts

@@ -5,11 +5,14 @@
  * Rust core; this module defines the `Harness` interface framework
  * adapters implement, plus the runner and reference harness that use it.
  */
-import type { ApprovalResolver, CompositionConfig, EnforcementMode, Interceptor, JsonValue } from "../index";
-export { loadVectors, runVector, runVectors, VectorResult } from "./runner";
-export { ReferenceHarness } from "./reference";
-/** Host-declared capability subset (§3.2). */
-export type Capability = "model_calls" | "tool_calls" | "parallel_tool_calls" | "streaming" | "multi_turn";
+import type { ApprovalResolver, CompositionConfig, EnforcementMode, HostRegistry, HostSurface, Interceptor, JsonValue } from "../index";
+export { assessHarness, loadVectors, runVector, runVectors, VectorResult, builderFromValue, provePaths, } from "./runner";
+export type { AssessedSurface } from "./runner";
+export { ReferenceHarness, REFERENCE_DECLARATION } from "./reference";
+/** Host-declared capability subset (§3.2, §13.1): the closed list of
+ * `conformance/vectors.schema.json` with `host_declaration` (§7.7.9).
+ * `buffered_output` is a value, not a presence, and is not listed. */
+export type Capability = "model_calls" | "tool_calls" | "parallel_tool_calls" | "streaming" | "multi_turn" | "int64_json" | "bigint_json" | "incremental_output" | "host_declaration";
 export type RunOutcome = "completed" | "blocked" | "suspended" | "error";
 /** Hermetic scripted run loaded from a CTK vector (wire-shaped). */
 export interface Scenario {
@@ -38,6 +41,17 @@ export interface Scenario {
         };
     }>;
 }
+/** What loading the vector's host declaration produced (§7.7.9), as
+ * the runner records it. */
+export interface LoadRecord {
+    outcome: "accepted" | "refused";
+    /** The `declaration_error:*` code on refusal. */
+    class?: string;
+    /** Whether the value, JSON, file and builder paths resolved to one
+     * canonical form (or refused with one class). */
+    paths_equivalent?: boolean;
+    detail?: string;
+}
 /** What `Harness.run` returns to the CTK runner. */
 export interface RunRecord {
     outcome: RunOutcome;
@@ -54,6 +68,9 @@ export interface RunRecord {
     /** Wire-shaped `InterceptionRecord`s (§10.3), one per emission, in
      * order. Enables `expect.records` assertions. */
     records: JsonValue[];
+    /** Set by the runner for vectors carrying `host_declaration`
+     * (§7.7.9); a harness never fills it. */
+    load?: LoadRecord;
 }
 /** The single interface a framework adapter implements for the CTK. */
 export interface Harness {
@@ -81,4 +98,26 @@ export interface Harness {
     setup(scenario: Scenario, interceptors: Interceptor[], resolver: ApprovalResolver | null, mode: EnforcementMode, composition: CompositionConfig, identityProvider: 'jcs-sha256' | 'ctk-fault' | null, redactForApproval?: string[]): void;
     run(): Promise<RunRecord>;
     teardown(): void;
+    /** The code surface (§7.7.4) a declaration is resolved against. When
+     * absent the runner derives it from `capabilities` and
+     * `toolSeamHostError` (`HostSurface.fromCapabilities`): the §3.2
+     * floor plus the model points iff `model_calls` plus the tool points
+     * iff `tool_calls`, every profile with every knob value. A host
+     * declaring `incremental_output` implements this to add its exposure
+     * bound; the derived surface alone is refused for such a host. */
+    hostSurface?(): HostSurface;
+    /** The host's own declaration document (§7.7.9), when it has one.
+     * The runner resolves it against the code surface and reads the
+     * capabilities and posture a run is assessed against from the
+     * resolved form, so what the CTK ran against is what a claim cites.
+     * Absent keeps the code-declared surface. */
+    declaration?(): JsonValue | undefined;
+    /** Wire one declaration vector (§7.7.9): the harness MUST build its
+     * emitter from `document` and `registry` through the loader
+     * (`InterceptionEmitter.fromDeclarationValue`) and let the
+     * `DeclarationError` propagate, never fall back to the field-based
+     * `setup`. The document and the registry carry the interceptors,
+     * resolver, composition and identity provider. Only harnesses
+     * declaring the `host_declaration` capability receive this call. */
+    setupDeclared?(scenario: Scenario, document: JsonValue, registry: HostRegistry): void;
 }

package/dist/ctk/index.js

@@ -9,10 +9,14 @@
  * adapters implement, plus the runner and reference harness that use it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferenceHarness = exports.runVectors = exports.runVector = exports.loadVectors = void 0;
+exports.REFERENCE_DECLARATION = exports.ReferenceHarness = exports.provePaths = exports.builderFromValue = exports.runVectors = exports.runVector = exports.loadVectors = exports.assessHarness = void 0;
 var runner_1 = require("./runner");
+Object.defineProperty(exports, "assessHarness", { enumerable: true, get: function () { return runner_1.assessHarness; } });
 Object.defineProperty(exports, "loadVectors", { enumerable: true, get: function () { return runner_1.loadVectors; } });
 Object.defineProperty(exports, "runVector", { enumerable: true, get: function () { return runner_1.runVector; } });
 Object.defineProperty(exports, "runVectors", { enumerable: true, get: function () { return runner_1.runVectors; } });
+Object.defineProperty(exports, "builderFromValue", { enumerable: true, get: function () { return runner_1.builderFromValue; } });
+Object.defineProperty(exports, "provePaths", { enumerable: true, get: function () { return runner_1.provePaths; } });
 var reference_1 = require("./reference");
 Object.defineProperty(exports, "ReferenceHarness", { enumerable: true, get: function () { return reference_1.ReferenceHarness; } });
+Object.defineProperty(exports, "REFERENCE_DECLARATION", { enumerable: true, get: function () { return reference_1.REFERENCE_DECLARATION; } });

package/dist/ctk/reference.d.ts

@@ -4,9 +4,19 @@
  * The simplest possible conformant agent loop; exists so the
  * CTK can self-test without a real framework. Port of
  * `sdk/python/python/agent_hooks/ctk/reference.py`.
+ *
+ * Every emitter it builds goes through the host declaration loader
+ * (§7.7): for a field-based vector it writes the vector's mode,
+ * composition and provider into a copy of its own document
+ * (`reference.declaration.json`) and binds the scripted interceptors
+ * through a `ctk.instance` kind, so the field-based vectors exercise
+ * the loader too.
  */
-import { ApprovalResolver, CompositionConfig, EnforcementMode, Interceptor } from "../index";
+import { ApprovalResolver, CompositionConfig, EnforcementMode, HostRegistry, HostSurface, Interceptor, JsonValue } from "../index";
 import type { Capability, Harness, RunRecord, Scenario } from "./index";
+/** The reference harness's own declaration (§7.7.9), with an explicit
+ * surface a claim can cite. */
+export declare const REFERENCE_DECLARATION: Readonly<Record<string, JsonValue>>;
 export declare class ReferenceHarness implements Harness {
     readonly name = "reference-agent";
     readonly capabilities: ReadonlySet<Capability>;
@@ -14,7 +24,11 @@ export declare class ReferenceHarness implements Harness {
     private emitter;
     private builder;
     private toolLog;
+    hostSurface(): HostSurface;
+    declaration(): JsonValue;
+    private startSession;
     setup(scenario: Scenario, interceptors: Interceptor[], resolver: ApprovalResolver | null, mode: EnforcementMode, composition: CompositionConfig, identityProvider: 'jcs-sha256' | 'ctk-fault' | null, redactForApproval?: string[]): void;
+    setupDeclared(scenario: Scenario, document: JsonValue, registry: HostRegistry): void;
     run(): Promise<RunRecord>;
     teardown(): void;
 }

package/dist/ctk/reference.declaration.json

@@ -0,0 +1,33 @@
+{
+    "$schema": "https://responsibleai.github.io/agent-hooks/schema/v0.1/host-declaration-1.0.schema.json",
+    "declaration": "agent-hooks-declaration/1.0",
+    "spec": "agent-hooks/0.1",
+    "id": "reference-agent",
+    "host": { "name": "reference-agent", "version": "0.1.0" },
+    "configuration": {
+        "mode": "enforce",
+        "composition": { "profile": "sequential/first_deny", "on_approval": "stop" },
+        "identity_provider": "jcs-sha256",
+        "approval": { "resolver": null, "redactor": null },
+        "posture": { "tool_seam_host_error": "continue" },
+        "timeouts": { "interceptor_ms": 5000, "approval_resolver_ms": 5000 },
+        "records": { "max_buffered": null }
+    },
+    "surface": {
+        "interception_points": [
+            "agent_startup", "input", "pre_model_call", "post_model_call",
+            "pre_tool_call", "post_tool_call", "output", "agent_shutdown"
+        ],
+        "capabilities": ["host_declaration", "model_calls", "tool_calls"],
+        "profiles": {
+            "sequential/first_deny": { "on_approval": ["resume", "stop"] },
+            "sequential/run_all": {},
+            "parallel/strictest": { "on_transform_conflict": ["approval", "deny"] },
+            "parallel/unanimous": { "on_disagreement": ["approval", "deny"] }
+        },
+        "buffered_output": true,
+        "declaration_versions": ["agent-hooks-declaration/1.0"]
+    },
+    "bindings": [],
+    "extensions": {}
+}