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

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": {}
+}

package/dist/ctk/reference.js

@@ -1,63 +1,115 @@
 "use strict";
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT License.
+// Copyright (c) Microsoft. All rights reserved.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReferenceHarness = exports.REFERENCE_DECLARATION = void 0;
 /**
  * Reference in-memory agent + harness.
  *
  * 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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferenceHarness = void 0;
 const node_crypto_1 = require("node:crypto");
 const index_1 = require("../index");
 const builder_1 = require("../builder");
 const emitter_1 = require("../emitter");
-const native_1 = require("../native");
+const runner_1 = require("./runner");
+const reference_declaration_json_1 = __importDefault(require("./reference.declaration.json"));
+/** The reference harness's own declaration (§7.7.9), with an explicit
+ * surface a claim can cite. */
+exports.REFERENCE_DECLARATION = Object.freeze(reference_declaration_json_1.default);
 class ReferenceHarness {
     name = "reference-agent";
-    capabilities = new Set(["model_calls", "tool_calls"]);
+    // host_declaration: every emitter is built through the loader.
+    // JSON.parse rounds integers beyond 2^53 before any guard can run,
+    // so neither int64_json nor bigint_json is declared (§4.4).
+    capabilities = new Set([
+        "model_calls",
+        "tool_calls",
+        "host_declaration",
+    ]);
     scenario;
     emitter;
     builder;
     toolLog = [];
-    setup(scenario, interceptors, resolver, mode, composition, identityProvider, redactForApproval = []) {
+    hostSurface() {
+        return index_1.HostSurface.fromCapabilities(this.capabilities, "continue");
+    }
+    declaration() {
+        return JSON.parse(JSON.stringify(exports.REFERENCE_DECLARATION));
+    }
+    startSession(scenario, emitter) {
         this.scenario = scenario;
         this.toolLog = [];
-        const em = new emitter_1.InterceptionEmitter(mode, resolver);
-        em.setComposition(composition);
-        if (redactForApproval.length > 0) {
-            // §9 redaction seam, CTK convention: each listed path is replaced
-            // with "[redacted]" via the §5.2/§4.3 transform machinery;
-            // unresolvable paths are left untouched.
-            em.setApprovalRedactor((ctx) => {
-                let out = JSON.stringify(ctx);
-                for (const path of redactForApproval) {
-                    try {
-                        out = native_1.native.applyTransformCtx(out, path, '"[redacted]"');
-                    }
-                    catch {
-                        /* unresolvable at this point — skip */
-                    }
-                }
-                return JSON.parse(out);
-            });
-        }
-        // §13.2: "ctk-fault" is a custom provider that throws, pinning the
-        // §10.1 provider-failure rule (deny context_invalid pre-dispatch).
-        em.setIdentityProvider(identityProvider === 'ctk-fault'
-            ? { name: 'ctk-fault', fn: () => { throw new Error('ctk scripted provider fault'); } }
-            : identityProvider);
-        for (const i of interceptors)
-            em.register(i);
-        this.emitter = em;
+        this.emitter = emitter;
         this.builder = new builder_1.AgentContextBuilder({
             agentId: "ref-agent",
             framework: "reference-agent",
             sessionId: (0, node_crypto_1.randomUUID)(),
         });
     }
+    setup(scenario, interceptors, resolver, mode, composition, identityProvider, redactForApproval = []) {
+        // Field-based vector: write the vector's configuration into a copy
+        // of the reference document and bind the interceptors by index
+        // through the `ctk.instance` kind.
+        const doc = this.declaration();
+        const cfg = doc["configuration"];
+        cfg["mode"] = mode;
+        cfg["composition"] = composition;
+        const registry = index_1.HostRegistry.forConformance(this.hostSurface());
+        if (identityProvider === "ctk-fault") {
+            // §13.2: "ctk-fault" is a custom provider that throws, pinning the
+            // §10.1 provider-failure rule (deny context_invalid pre-dispatch).
+            registry.identityProvider("ctk-fault", () => {
+                throw new Error("ctk scripted provider fault");
+            });
+        }
+        cfg["identity_provider"] = identityProvider;
+        const approval = { resolver: null, redactor: null };
+        if (resolver !== null) {
+            registry.approvalResolver("ctk-scripted", resolver);
+            approval["resolver"] = "ctk-scripted";
+        }
+        if (redactForApproval.length > 0) {
+            const paths = [...redactForApproval];
+            registry.approvalRedactor("ctk-redact", (ctx) => (0, runner_1.redactPaths)(ctx, paths));
+            approval["redactor"] = "ctk-redact";
+        }
+        cfg["approval"] = approval;
+        const slots = [...interceptors];
+        registry.kind("ctk.instance", (config, ctx) => {
+            const index = config?.["index"];
+            if (typeof index !== "number" || !Number.isInteger(index) || index < 0) {
+                throw new Error("config.index must be an unsigned integer");
+            }
+            const instance = slots[index];
+            if (instance === undefined) {
+                throw new Error(`no interceptor instance ${index} for binding ${ctx.id}`);
+            }
+            slots[index] = undefined;
+            return instance;
+        });
+        doc["bindings"] = interceptors.map((_, i) => ({
+            id: `interceptor-${i}`,
+            kind: "ctk.instance",
+            config: { index: i },
+        }));
+        this.startSession(scenario, emitter_1.InterceptionEmitter.fromDeclarationValue(doc, registry));
+    }
+    setupDeclared(scenario, document, registry) {
+        // A refusal (DeclarationError) propagates to the runner (§7.7.9).
+        this.startSession(scenario, emitter_1.InterceptionEmitter.fromDeclarationValue(document, registry));
+    }
     async run() {
         const s = this.scenario;
         const em = this.emitter;

package/dist/ctk/runner.d.ts

@@ -1,20 +1,40 @@
-/**
- * CTK runner: load vectors, drive a harness, assert `expect`.
- *
- * The assertion engine, capability skip check, and scripted
- * interceptor/resolver evaluation live in the Rust core (native.ctk*).
- * This module keeps only vector globbing, the recording wrapper, and
- * the orchestration loop that calls the native `Harness`.
- */
-import { JsonValue } from "../index";
+import { AgentContext, DeclarationBuilder, HostRegistry, JsonValue } from "../index";
 import type { Harness } from "./index";
 export interface VectorResult {
     id: string;
     title: string;
+    part?: string;
     status: "pass" | "fail" | "skip";
     detail: string;
     failures: string[];
 }
 export declare function loadVectors(dir: string): JsonValue[];
-export declare function runVector(harness: Harness, vector: JsonValue): Promise<VectorResult>;
+/** §9 redaction seam, CTK convention: each listed path is replaced
+ * with "[redacted]" via the §5.2/§4.3 transform machinery; a path that
+ * does not resolve at the escalating point is left untouched. */
+export declare function redactPaths(ctx: AgentContext, paths: readonly string[]): AgentContext;
+/** Rebuild a document through {@link DeclarationBuilder}, member by
+ * member (§7.7.7, the code path). Members the typed setters cannot
+ * express exactly (an unknown member, a wrong type) go through
+ * {@link DeclarationBuilder.raw}, so the result is validated like the
+ * file it came from. Mirrors the Rust runner's `builder_from_value`. */
+export declare function builderFromValue(doc: JsonValue): DeclarationBuilder;
+/** Resolve `doc` through the four construction paths (§7.7.7) and
+ * compare: value, JSON text, a temporary file and the builder. Equal
+ * canonical forms, or equal refusal classes, prove the paths
+ * equivalent. Returns `[equivalent, detail]`. */
+export declare function provePaths(doc: JsonValue, registry: HostRegistry, tag: string): Promise<[boolean, string]>;
+/** What a run assesses the harness against: its capabilities and
+ * posture, read from its resolved declaration when it ships one
+ * (§7.7.9) and from the Harness fields otherwise. */
+export interface AssessedSurface {
+    capabilities: string[];
+    posture: string;
+}
+/** Resolve the harness's own declaration against its code surface.
+ * Throws {@link DeclarationError} on refusal. {@link runVectors} calls
+ * this once before the first vector, as §7.7.9 asks; {@link runVector}
+ * calls it when no resolved surface is handed in. */
+export declare function assessHarness(harness: Harness): AssessedSurface;
+export declare function runVector(harness: Harness, vector: JsonValue, assessed?: AssessedSurface): Promise<VectorResult>;
 export declare function runVectors(harnessFactory: () => Harness, vectors: JsonValue[]): Promise<VectorResult[]>;