@responsibleai/agent-hooks 0.1.0-alpha.2

package/dist/ctk/reference.js

@@ -0,0 +1,124 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * 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`.
+ */
+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");
+class ReferenceHarness {
+    name = "reference-agent";
+    capabilities = new Set(["model_calls", "tool_calls"]);
+    scenario;
+    emitter;
+    builder;
+    toolLog = [];
+    setup(scenario, interceptors, resolver, mode, composition, identityProvider) {
+        this.scenario = scenario;
+        this.toolLog = [];
+        const em = new emitter_1.InterceptionEmitter(mode, resolver);
+        em.setComposition(composition);
+        em.setIdentityProvider(identityProvider);
+        for (const i of interceptors)
+            em.register(i);
+        this.emitter = em;
+        this.builder = new builder_1.AgentContextBuilder({
+            agentId: "ref-agent",
+            framework: "reference-agent",
+            sessionId: (0, node_crypto_1.randomUUID)(),
+        });
+    }
+    async run() {
+        const s = this.scenario;
+        const em = this.emitter;
+        const b = this.builder;
+        let outcome = "completed";
+        let final = null;
+        const tools = new Map((s.tools ?? []).map((t) => [t.name, t]));
+        const invokeTool = (name, args) => {
+            const spec = tools.get(name);
+            if (!spec)
+                throw new Error(`tool ${name} not in scenario`);
+            for (const bh of spec.behavior) {
+                if (!bh.when_args || JSON.stringify(bh.when_args) === JSON.stringify(args)) {
+                    return { value: bh.return, is_error: bh.is_error ?? false };
+                }
+            }
+            throw new Error(`tool ${name} invoked with ${JSON.stringify(args)}: no matching behavior`);
+        };
+        try {
+            await em.emit(b.agentStartup([...tools.keys()].sort()));
+            await em.emit(b.input(s.input.content, s.input.role));
+            let messages = [
+                { role: s.input.role, content: s.input.content },
+            ];
+            for (const step of s.model_script ?? []) {
+                const resp = step.respond;
+                const preCtx = b.preModelCall("mock", [...messages]);
+                await em.emit(preCtx);
+                messages = preCtx.messages;
+                await em.emit(b.postModelCall("mock", resp.content, resp.tool_calls, resp.finish_reason));
+                if (resp.tool_calls.length > 0) {
+                    for (const tc of resp.tool_calls) {
+                        try {
+                            const preTc = b.preToolCall(tc.id, tc.name, { ...tc.args });
+                            await em.emit(preTc);
+                            const args = preTc.tool_call.args;
+                            const { value, is_error } = invokeTool(tc.name, args);
+                            this.toolLog.push({ name: tc.name, args: { ...args } });
+                            await em.emit(b.postToolCall(tc.id, tc.name, { ...args }, value, is_error));
+                            messages.push({ role: "tool", content: value });
+                        }
+                        catch (e) {
+                            if (e instanceof index_1.InterceptionBlocked) {
+                                messages.push({ role: "tool", content: `blocked: ${e.result.verdict.reason}` });
+                            }
+                            else {
+                                throw e;
+                            }
+                        }
+                    }
+                    messages.push({ role: "assistant", content: resp.content ?? "" });
+                }
+                else {
+                    final = resp.content;
+                    break;
+                }
+            }
+            if (final !== null) {
+                const outCtx = b.output(final);
+                await em.emit(outCtx);
+                final = outCtx.output.content;
+            }
+        }
+        catch (e) {
+            if (e instanceof index_1.InterceptionBlocked) {
+                outcome = "blocked";
+                final = null;
+            }
+            else {
+                throw e;
+            }
+        }
+        await em.emitUnchecked(b.agentShutdown(outcome === "completed" ? "completed" : "error"));
+        return {
+            outcome,
+            final_output: final,
+            tool_invocations: this.toolLog,
+            identities: em.records.map((r) => [r.input_identity, r.enforced_identity]),
+            records: em.records,
+        };
+    }
+    teardown() {
+        // no-op
+    }
+}
+exports.ReferenceHarness = ReferenceHarness;

package/dist/ctk/runner.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { Harness } from "./index";
+/** TODO(stage-4): vectors still authored in the pre-P-003 five-verdict
+ * wire vocabulary (`warn`, `escalate`, `approval_resolver_missing`).
+ * Stage 4 rewrites them to the three-verdict shapes (§5.1); until then
+ * their scripted verdicts fail the §5 gate by design (fail closed) and
+ * no longer exercise the seam/warning semantics they were written for,
+ * so they are skipped here. */
+export interface VectorResult {
+    id: string;
+    title: 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>;
+export declare function runVectors(harnessFactory: () => Harness, vectors: JsonValue[]): Promise<VectorResult[]>;

package/dist/ctk/runner.js

@@ -0,0 +1,144 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadVectors = loadVectors;
+exports.runVector = runVector;
+exports.runVectors = runVectors;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const index_1 = require("../index");
+const native_1 = require("../native");
+function loadVectors(dir) {
+    const vectors = (0, node_fs_1.readdirSync)(dir)
+        .filter((f) => /^AH-CTK-.*\.json$/.test(f))
+        .sort()
+        .map((f) => JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, f), "utf8")));
+    if (vectors.length === 0) {
+        // A runner fed zero vectors reports 100% pass — a false
+        // conformance signal (§13.2). Fail loudly instead.
+        throw new Error(`no AH-CTK-*.json vectors found in ${dir}`);
+    }
+    return vectors;
+}
+/** Replays one `interceptor_script` rule list via the Rust core. */
+class ScriptedInterceptor {
+    rulesJson;
+    constructor(rules) {
+        this.rulesJson = JSON.stringify(rules);
+    }
+    intercept(ctx) {
+        const w = JSON.parse(native_1.native.ctkScriptedIntercept(this.rulesJson, JSON.stringify(ctx)));
+        if (w !== null && typeof w === "object" && "__ctk_fault__" in w) {
+            // NOW-10 fault injection: exercise §6.3 interceptor_failed.
+            throw new Error("ctk scripted fault: raise");
+        }
+        return w;
+    }
+}
+/** Wraps the scripted interceptor and records every ctx passed. */
+class RecordingInterceptor extends ScriptedInterceptor {
+    recorded = [];
+    intercept(ctx) {
+        this.recorded.push(JSON.parse(JSON.stringify(ctx)));
+        return super.intercept(ctx);
+    }
+}
+class ScriptedResolver {
+    rulesJson;
+    constructor(rules) {
+        this.rulesJson = JSON.stringify(rules);
+    }
+    resolve(req) {
+        // §10.1: identity may be null (null provider). The scripted engine
+        // works in strings; "" round-trips to null below.
+        const requestIdentity = req.context_identity ?? "";
+        const r = JSON.parse(native_1.native.ctkScriptedResolve(this.rulesJson, JSON.stringify(req.context), requestIdentity));
+        if (r !== null && typeof r === "object" && "__ctk_fault__" in r) {
+            // NOW-10 fault injection: exercise §9 approval_resolver_failed.
+            throw new Error("ctk scripted fault: raise");
+        }
+        if (r.context_identity === "" && req.context_identity === null) {
+            r.context_identity = null;
+        }
+        return r;
+    }
+}
+function runRecordToWire(rr) {
+    return JSON.stringify({
+        outcome: rr.outcome,
+        final_output: rr.final_output ?? null,
+        tool_invocations: rr.tool_invocations,
+        error: rr.error ?? null,
+        identities: rr.identities.map(([i, e]) => ({ input_identity: i, enforced_identity: e })),
+        records: rr.records,
+    });
+}
+async function runVector(harness, vector) {
+    const v = vector;
+    const vectorJson = JSON.stringify(vector);
+    const capsJson = JSON.stringify([...harness.capabilities].sort());
+    const skip = JSON.parse(native_1.native.ctkShouldSkip(vectorJson, capsJson));
+    if (skip !== null) {
+        return {
+            id: v.id,
+            title: v.title,
+            status: "skip",
+            detail: skip,
+            failures: [],
+        };
+    }
+    // Multi-interceptor vectors (§7.1 fold-through) use interceptor_scripts;
+    // single-interceptor vectors use interceptor_script. Only the FIRST
+    // interceptor records: expect.interceptions describes each emission as
+    // the first-registered interceptor saw it. An empty interceptor_scripts
+    // registers zero interceptors (§7 fail-closed vector).
+    const scripts = v.interceptor_scripts ?? [v.interceptor_script];
+    const first = scripts.length > 0 ? new RecordingInterceptor(scripts[0]) : null;
+    const interceptors = first ? [first] : [];
+    for (const s of scripts.slice(1))
+        interceptors.push(new ScriptedInterceptor(s));
+    const approval = v.approval_script;
+    // NB: [] is truthy in JS — an empty approval_script registers NO
+    // resolver (matches the Rust/Python runners; exercised by AH-CTK-032).
+    const resolver = approval && approval.length > 0 ? new ScriptedResolver(approval) : null;
+    const mode = (v.mode ?? "enforce");
+    // §13.2: composition vectors carry the profile/knobs they apply to;
+    // absent means the pre-P-003 default (`sequential/first_deny, stop`).
+    const composition = v.composition ?? index_1.Composition.default();
+    // §10.1: absent → the default provider; explicit null → unbound.
+    const identityProvider = 'identity_provider' in v ? v.identity_provider : 'jcs-sha256';
+    harness.setup(v.scenario, interceptors, resolver, mode, composition, identityProvider);
+    let rr;
+    try {
+        rr = await harness.run();
+    }
+    catch (e) {
+        return {
+            id: v.id,
+            title: v.title,
+            status: "fail",
+            detail: "",
+            failures: [`harness.run threw: ${e}`],
+        };
+    }
+    finally {
+        harness.teardown();
+    }
+    return JSON.parse(native_1.native.ctkAssert(vectorJson, JSON.stringify(first?.recorded ?? []), runRecordToWire(rr)));
+}
+async function runVectors(harnessFactory, vectors) {
+    const out = [];
+    for (const v of vectors) {
+        out.push(await runVector(harnessFactory(), v));
+    }
+    return out;
+}

package/dist/emitter.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Host-side emitter: dispatch context → interceptors → composition →
+ * combined verdict → record (§6–§10).
+ *
+ * Per-language orchestrator over the Rust core:
+ *
+ * - Interceptor dispatch (§7) and approval-seam resolution (§9) stay here
+ *   because they call back into user JS code.
+ * - Verdict validation (§5), transform application (§5.2, §7.4),
+ *   severity-max aggregation (§7.3, via `composeAggregate`), identity
+ *   computation (§10), and record building (§10.3) delegate to the Rust
+ *   core so behaviour is byte-identical across SDKs.
+ *
+ * Composition is host configuration (§7.1): the profile is set on the
+ * emitter (default `sequential/first_deny, on_approval: stop`) and
+ * recorded on every emission. "Parallel" profiles are implemented with
+ * 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
+ * {@link InterceptionEmitter.emit} **throws** {@link InterceptionBlocked}
+ * on any block — the ignorable-result variant is the explicitly named
+ * {@link InterceptionEmitter.emitUnchecked}.
+ *
+ * Concurrency (§12.2): emissions for different tool calls may interleave
+ * 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, InterceptionRecord, Interceptor } from "./index";
+/** §7 RECOMMENDED interceptor/resolver timeout (milliseconds). */
+export declare const DEFAULT_TIMEOUT_MS = 5000;
+export declare class InterceptionEmitter {
+    private readonly mode;
+    private readonly resolver;
+    private readonly timeoutMs;
+    private readonly interceptors;
+    private readonly _records;
+    private composition;
+    private identity;
+    /**
+     * `timeoutMs` bounds each interceptor `intercept()` and resolver
+     * `resolve()` call (§7, RECOMMENDED default 5000 ms); breach fails
+     * closed with `host_error:interceptor_timeout` (interceptor) or
+     * `host_error:approval_resolver_failed` (resolver). Only async work
+     * can be preempted — a synchronous interceptor that blocks the event
+     * 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. */
+    private withTimeout;
+    get records(): readonly InterceptionRecord[];
+    register(interceptor: Interceptor): this;
+    /** Declare the composition profile for subsequent emissions (§7.1). */
+    setComposition(composition: CompositionConfig): this;
+    /** Declare the identity provider (§10.1). Default `"jcs-sha256"`. */
+    setIdentityProvider(provider: IdentityProvider): this;
+    /** Run the emission and **throw** {@link InterceptionBlocked} if the
+     * guarded action must not proceed (§6). Primary entry point. */
+    emit(ctx: AgentContext): Promise<InterceptionRecord>;
+    /** Run the emission and return the record without throwing. The
+     * caller MUST inspect `proceeds` and halt the guarded action itself;
+     * prefer {@link emit}. */
+    emitUnchecked(ctx: AgentContext): Promise<InterceptionRecord>;
+    /** Profile dispatch (§7.4–§7.5). Returns the combined verdict and
+     * its record metadata. */
+    private dispatch;
+    /** Invoke one interceptor on its own copy of `ctx` (§7) and pass the
+     * result through the §5 gate. Never throws: every failure becomes the
+     * §6.3 synthesized deny. */
+    private invoke;
+    /** §5 gate: normalize a wire verdict or synthesize the §6.3 deny. The
+     * non-finite pre-scan runs first — JSON.stringify would silently
+     * corrupt NaN/±Infinity to null before the core could reject them. */
+    private gate;
+    /** `sequential/first_deny` (§7.4): fold-through, first deny
+     * short-circuits; a liftable deny consults the seam, then `stop` or
+     * `resume` per the knob.
+     *
+     * `perInterceptor` stays index-aligned with registration order (one
+     * entry per invoked interceptor, §10.3 summaries); `pool`
+     * additionally holds substituted resolutions for the §7.3 unions. */
+    private dispatchFirstDeny;
+    /** `sequential/run_all` (§7.4): everything runs, transforms fold
+     * through for visibility, severity-max aggregate; the seam is
+     * consulted at most once, only when the winner is liftable (which
+     * implies every deny in the emission is liftable — a single plain
+     * deny already won the severity order). */
+    private dispatchRunAll;
+    /** Parallel profiles (§7.5): isolated snapshots, no fold; serial
+     * dispatch (isolation semantics, not scheduling). */
+    private dispatchParallel;
+    /** Severity-max aggregation + winner handling, shared by `run_all`
+     * and both parallel profiles. Aggregation — including the §7.5
+     * transform-conflict and `parallel/unanimous` disagreement synthesis
+     * per the declared knobs — delegates to the core's
+     * `composeAggregate` so all SDKs agree; the seam consultation and
+     * transform application stay here (they call back into user JS). */
+    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). */
+    private identityOf;
+    /** Consult the approval seam for a liftable deny (§9), when the
+     * profile conditions allow it: `enforce` mode, not `agent_shutdown`,
+     * a resolver registered, and the verdict actually liftable. Enforces
+     * the echo rule and the §9 outcome/verdict consistency requirements. */
+    private consult;
+}