@responsibleai/agent-hooks 0.1.0-alpha.5 → 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
@@ -15,11 +16,15 @@ identity-provider seam, and the CTK runner.
 > before relying on it.
 
 ```bash
-# Not yet published to npm — install from source:
-git clone https://github.com/responsibleai/agent-hooks && cd agent-hooks/sdk/typescript
-npm install && npm run build   # builds the native module (needs a Rust toolchain)
+npm install @responsibleai/agent-hooks@alpha
 ```
 
+Keep the `@alpha` tag (or pin an exact published version) while the
+package is pre-release: npm's `latest` tag can lag the newest
+pre-release, so a plain `npm install` may fetch an older build. Check
+what the tags resolve to with
+`npm view @responsibleai/agent-hooks dist-tags`.
+
 ## Usage
 
 ```ts
@@ -40,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

@@ -1,5 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 export declare function applyTransform(targetJson: string, path: string, valueJson: string): string
 
 export declare function applyTransformCtx(ctxJson: string, path: string, valueJson: string): string
@@ -18,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