@responsibleai/agent-hooks 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,47 @@
+# agent-hooks (TypeScript SDK)
+
+TypeScript implementation of
+[AGENT-HOOKS-0.1](https://github.com/responsibleai/agent-hooks/blob/main/spec/AGENT-HOOKS-0.1.md)
+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.
+
+> **Trust model.** agent-hooks is a *cooperative contract*, not a security
+> boundary: the host framework is fully trusted, interceptors run in-process
+> with full data access, and no complete-mediation claim is made. Read
+> [SECURITY.md](https://github.com/responsibleai/agent-hooks/blob/main/SECURITY.md)
+> and [spec §1.4](https://github.com/responsibleai/agent-hooks/blob/main/spec/AGENT-HOOKS-0.1.md#14-trust-model-and-non-goals)
+> 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)
+```
+
+## Usage
+
+```ts
+import { AgentContextBuilder, InterceptionEmitter, Verdict } from "@responsibleai/agent-hooks";
+
+const emitter = new InterceptionEmitter();
+emitter.register({
+  intercept(ctx) {
+    if (ctx.interception_point === "pre_tool_call" && ctx.tool_call.name === "rm") {
+      return { decision: "deny", reason: "dangerous" };
+    }
+    return { decision: "allow" };
+  },
+});
+
+const builder = new AgentContextBuilder({ agentId: "my-agent", framework: "my-fw", sessionId: "s-1" });
+const ctx = builder.preToolCall("tc-1", "http_get", { url });
+await emitter.emit(ctx); // throws InterceptionBlocked on a combined deny
+```
+
+**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.

package/binding.d.ts

@@ -0,0 +1,18 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export declare function specVersion(): string
+export declare function canonicalJson(valueJson: string): string
+export declare function contextIdentity(ctxJson: string): string
+export declare function validateVerdict(verdictJson: string): string
+export declare function applyTransform(targetJson: string, path: string, valueJson: string): string
+export declare function applyTransformCtx(ctxJson: string, path: string, valueJson: string): string
+export declare function validateTransformCtx(ctxJson: string, path: string, valueJson: string): string
+export declare function finalize(ctxJson: string, verdictJson: string, mode: string, optionsJson: string): string
+export declare function composeAggregate(compositionJson: string, verdictsJson: string): string
+export declare function ctkScriptedIntercept(rulesJson: string, ctxJson: string): string
+export declare function ctkScriptedResolve(rulesJson: string, ctxJson: string, identity: string): string
+export declare function ctkShouldSkip(vectorJson: string, harnessCapsJson: string): string
+export declare function ctkAssert(vectorJson: string, recordedJson: string, runRecordJson: string): string

package/binding.js

@@ -0,0 +1,327 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'agent-hooks.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.android-arm64.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'agent-hooks.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'agent-hooks.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'agent-hooks.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'agent-hooks.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'agent-hooks.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./agent-hooks.darwin-universal.node')
+      } else {
+        nativeBinding = require('@responsibleai/agent-hooks-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'agent-hooks.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.darwin-x64.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'agent-hooks.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'agent-hooks.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./agent-hooks.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@responsibleai/agent-hooks-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'agent-hooks.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./agent-hooks.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@responsibleai/agent-hooks-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'agent-hooks.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./agent-hooks.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@responsibleai/agent-hooks-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { specVersion, canonicalJson, contextIdentity, validateVerdict, applyTransform, applyTransformCtx, validateTransformCtx, finalize, composeAggregate, ctkScriptedIntercept, ctkScriptedResolve, ctkShouldSkip, ctkAssert } = nativeBinding
+
+module.exports.specVersion = specVersion
+module.exports.canonicalJson = canonicalJson
+module.exports.contextIdentity = contextIdentity
+module.exports.validateVerdict = validateVerdict
+module.exports.applyTransform = applyTransform
+module.exports.applyTransformCtx = applyTransformCtx
+module.exports.validateTransformCtx = validateTransformCtx
+module.exports.finalize = finalize
+module.exports.composeAggregate = composeAggregate
+module.exports.ctkScriptedIntercept = ctkScriptedIntercept
+module.exports.ctkScriptedResolve = ctkScriptedResolve
+module.exports.ctkShouldSkip = ctkShouldSkip
+module.exports.ctkAssert = ctkAssert

package/dist/builder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `AgentContext` construction (§4).
+ *
+ * Stateful per-session builder that owns the L0 envelope
+ * (agent/session/sequence) and exposes one method per interception
+ * point that fills L1 and sets `target`.
+ */
+import { AgentContext, JsonValue } from "./index";
+export declare class AgentContextBuilder {
+    private seq;
+    private readonly agent;
+    private readonly session;
+    constructor(opts: {
+        agentId: string;
+        framework: string;
+        sessionId: string;
+        agentName?: string;
+        agentVersion?: string;
+        sessionStartedAt?: string;
+    });
+    private envelope;
+    agentStartup(toolsRegistered: string[]): AgentContext;
+    input(content: JsonValue, role?: "user" | "system" | "external"): AgentContext;
+    preModelCall(modelId: string, messages: Array<{
+        role: string;
+        content: JsonValue;
+    }>): AgentContext;
+    postModelCall(modelId: string, content: JsonValue, toolCalls: Array<{
+        id: string;
+        name: string;
+        args: Record<string, JsonValue>;
+    }>, finishReason: string): AgentContext;
+    preToolCall(callId: string, name: string, args: Record<string, JsonValue>): AgentContext;
+    postToolCall(callId: string, name: string, args: Record<string, JsonValue>, value: JsonValue, isError?: boolean): AgentContext;
+    output(content: JsonValue): AgentContext;
+    agentShutdown(reason: "completed" | "error" | "cancelled"): AgentContext;
+}

package/dist/builder.js

@@ -0,0 +1,94 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * `AgentContext` construction (§4).
+ *
+ * Stateful per-session builder that owns the L0 envelope
+ * (agent/session/sequence) and exposes one method per interception
+ * point that fills L1 and sets `target`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentContextBuilder = void 0;
+const index_1 = require("./index");
+function now() {
+    return new Date().toISOString();
+}
+class AgentContextBuilder {
+    seq = 0;
+    agent;
+    session;
+    constructor(opts) {
+        this.agent = { id: opts.agentId, framework: opts.framework };
+        if (opts.agentName)
+            this.agent.name = opts.agentName;
+        if (opts.agentVersion)
+            this.agent.version = opts.agentVersion;
+        this.session = { id: opts.sessionId };
+        if (opts.sessionStartedAt)
+            this.session.started_at = opts.sessionStartedAt;
+    }
+    envelope(ip, target) {
+        const ctx = {
+            spec: index_1.SPEC_VERSION,
+            interception_point: ip,
+            timestamp: now(),
+            sequence: this.seq++,
+            agent: { ...this.agent },
+            session: { ...this.session },
+            target,
+        };
+        return ctx;
+    }
+    agentStartup(toolsRegistered) {
+        const agentInit = { tools_registered: [...toolsRegistered] };
+        const ctx = this.envelope(index_1.InterceptionPoint.AgentStartup, agentInit);
+        ctx.agent_init = agentInit;
+        return ctx;
+    }
+    input(content, role = "user") {
+        const inp = { content, role };
+        const ctx = this.envelope(index_1.InterceptionPoint.Input, inp);
+        ctx.input = inp;
+        return ctx;
+    }
+    preModelCall(modelId, messages) {
+        const ctx = this.envelope(index_1.InterceptionPoint.PreModelCall, messages);
+        ctx.model = { id: modelId };
+        ctx.messages = messages;
+        return ctx;
+    }
+    postModelCall(modelId, content, toolCalls, finishReason) {
+        const response = { content, tool_calls: toolCalls, finish_reason: finishReason };
+        const ctx = this.envelope(index_1.InterceptionPoint.PostModelCall, response);
+        ctx.model = { id: modelId };
+        ctx.response = response;
+        return ctx;
+    }
+    preToolCall(callId, name, args) {
+        const tc = { id: callId, name, args };
+        const ctx = this.envelope(index_1.InterceptionPoint.PreToolCall, args);
+        ctx.tool_call = tc;
+        return ctx;
+    }
+    postToolCall(callId, name, args, value, isError = false) {
+        const tr = { value, is_error: isError };
+        const ctx = this.envelope(index_1.InterceptionPoint.PostToolCall, value);
+        ctx.tool_call = { id: callId, name, args };
+        ctx.tool_result = tr;
+        return ctx;
+    }
+    output(content) {
+        const out = { content };
+        const ctx = this.envelope(index_1.InterceptionPoint.Output, out);
+        ctx.output = out;
+        return ctx;
+    }
+    agentShutdown(reason) {
+        const summary = { reason };
+        const ctx = this.envelope(index_1.InterceptionPoint.AgentShutdown, summary);
+        ctx.summary = summary;
+        return ctx;
+    }
+}
+exports.AgentContextBuilder = AgentContextBuilder;

package/dist/ctk/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Conformance Test Kit (§13.2).
+ *
+ * The assertion engine and scripted interceptor/resolver live in the
+ * 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";
+export type RunOutcome = "completed" | "blocked" | "suspended" | "error";
+/** Hermetic scripted run loaded from a CTK vector (wire-shaped). */
+export interface Scenario {
+    input: {
+        content: JsonValue;
+        role: "user" | "system" | "external";
+    };
+    tools?: Array<{
+        name: string;
+        schema?: Record<string, JsonValue>;
+        behavior: Array<{
+            when_args?: Record<string, JsonValue>;
+            return: JsonValue;
+            is_error?: boolean;
+        }>;
+    }>;
+    model_script?: Array<{
+        respond: {
+            content: JsonValue;
+            tool_calls: Array<{
+                id: string;
+                name: string;
+                args: Record<string, JsonValue>;
+            }>;
+            finish_reason: string;
+        };
+    }>;
+}
+/** What `Harness.run` returns to the CTK runner. */
+export interface RunRecord {
+    outcome: RunOutcome;
+    final_output: JsonValue | null;
+    tool_invocations: Array<{
+        name: string;
+        args: Record<string, JsonValue>;
+    }>;
+    error?: string;
+    /** `(input_identity, enforced_identity)` per interception, in order,
+     * from the harness's emitter (`null` under a `null` identity
+     * provider, §10.1). Enables `expect.identities_equal`. */
+    identities: Array<[string | null, string | null]>;
+    /** Wire-shaped `InterceptionRecord`s (§10.3), one per emission, in
+     * order. Enables `expect.records` assertions. */
+    records: JsonValue[];
+}
+/** The single interface a framework adapter implements for the CTK. */
+export interface Harness {
+    readonly name: string;
+    readonly capabilities: ReadonlySet<Capability>;
+    /** Wire the scenario's mock model + tools into the framework,
+     * register the interceptors and resolver, set the enforcement mode,
+     * the vector's composition profile (§7.1), and its identity provider
+     * (§10.1; vectors declare `"jcs-sha256"` or `null` — custom providers
+     * are functions and not vector-expressible). */
+    setup(scenario: Scenario, interceptors: Interceptor[], resolver: ApprovalResolver | null, mode: EnforcementMode, composition: CompositionConfig, identityProvider: 'jcs-sha256' | null): void;
+    run(): Promise<RunRecord>;
+    teardown(): void;
+}

package/dist/ctk/index.js

@@ -0,0 +1,18 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * Conformance Test Kit (§13.2).
+ *
+ * The assertion engine and scripted interceptor/resolver live in the
+ * Rust core; this module defines the `Harness` interface framework
+ * 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;
+var runner_1 = require("./runner");
+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; } });
+var reference_1 = require("./reference");
+Object.defineProperty(exports, "ReferenceHarness", { enumerable: true, get: function () { return reference_1.ReferenceHarness; } });

package/dist/ctk/reference.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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`.
+ */
+import { ApprovalResolver, CompositionConfig, EnforcementMode, Interceptor } from "../index";
+import type { Capability, Harness, RunRecord, Scenario } from "./index";
+export declare class ReferenceHarness implements Harness {
+    readonly name = "reference-agent";
+    readonly capabilities: ReadonlySet<Capability>;
+    private scenario;
+    private emitter;
+    private builder;
+    private toolLog;
+    setup(scenario: Scenario, interceptors: Interceptor[], resolver: ApprovalResolver | null, mode: EnforcementMode, composition: CompositionConfig, identityProvider: 'jcs-sha256' | null): void;
+    run(): Promise<RunRecord>;
+    teardown(): void;
+}