netzilo 4.3.14

package/README.md

@@ -0,0 +1,139 @@
+# netzilo (Node.js / TypeScript)
+
+Netzilo AI Detection & Response (AIDR) for Node.js / TypeScript
+
+Provides full governance for custom AI agents written in Node.js / TypeScript
+
+## How it works
+
+The Netzilo client is a native shared library loaded **in-process** via a
+native FFI binding. Every LLM prompt, model response, and tool call your
+agent makes can be evaluated — allowed, blocked, or redacted — against
+policy pulled live from your Netzilo management server. No daemon, no
+sidecar — nothing to stand up.
+
+## Install
+
+```bash
+npm install netzilo
+```
+
+Platform binaries are resolved automatically for macOS, Linux, and Windows —
+no compiler or extra setup needed.
+
+## Core API
+
+```ts
+import * as netzilo from "netzilo";
+
+await netzilo.start({
+  server: "https://srv.netzilo.com", // management server
+  pat: "nzl_...",                    // or setupKey: "..."
+  agentName: "my-agent",             // non-blocking
+});
+
+netzilo.isRunning();                                  // -> boolean: true once policy has synced (ready to govern)
+netzilo.mcpGatewayPort();                             // -> number: scanner gateway port in use (auto-picked)
+const { allowed, reason } = netzilo.isAllowed("Bash", { command: "rm -rf /" });
+netzilo.reportResult("Bash", "<stdout>");             // post-tool observability
+netzilo.flush();                                      // force-deliver buffered events to management
+netzilo.snapshot();                                   // force AIDR behavior-graph snapshot + delivery (else hourly/at-stop)
+netzilo.stop();                                       // graceful stop (snapshots graph + flushes events)
+```
+
+`isRunning()` returns `true` only after the initial policy sync — poll it
+before kicking off work. Evaluation runs **inside the process** —
+`evaluate()` calls the embedded engine directly, with no HTTP roundtrip and
+no local port to manage.
+
+## Advanced governance (`enableAdvancedGovernance: true`) — Linux only
+
+`wrapTool()` and manual `isAllowed()`/`checkPrompt()`/`checkResponse()` calls
+(below) govern at the tool/LLM-call boundary you wire them into, and work on
+macOS, Linux, and Windows. Advanced governance adds deep inspection of the
+agent's **own** outbound traffic — covering every prompt, response, and tool
+call (including from subprocesses and libraries you have no hook for), with
+full content analysis and semantic classification. It is currently only
+supported when your agent process runs on Linux; on macOS/Windows, leave
+`enableAdvancedGovernance` unset (default `false`) and rely on `wrapTool()` /
+manual gating:
+
+```ts
+await netzilo.start({ server: "...", pat: "...", agentName: "...", enableAdvancedGovernance: true });
+```
+
+It is fully automatic and requires **no root** and no changes to the host —
+the SDK prepares the process so the agent's traffic is inspected and
+continues to work normally. Inspected prompts/responses are analyzed and
+classified, emitting `semantic.event` records to your dashboard alongside the
+usual tool/LLM events. Default off; `wrapTool()` and manual gating work
+without it.
+
+For full HTTPS interception coverage of Node's built-in `fetch()`, also
+install `undici` (`npm install undici`) — normal npm hoisting makes it
+resolvable to netzilo automatically. Without it, HTTPS traffic still routes
+through standard proxy environment variables (covering subprocesses and
+proxy-aware libraries), but `fetch()` itself may bypass interception.
+Libraries that build their own `http.Agent` without consulting proxy env
+vars (e.g. `axios`/`got` without an explicit proxy agent) aren't
+automatically covered either — prefer `undici`'s `fetch()`, or wire your
+HTTP client's proxy option to `process.env.HTTPS_PROXY` /
+`process.env.ALL_PROXY` directly.
+
+## Framework integration
+
+There's no separate package or submodule to install — everything ships in
+`netzilo` itself.
+
+**One-liner, fire-and-forget** — for agents whose own LLM/egress/subprocess
+traffic should be inspected in-process, regardless of which framework issues
+it:
+
+```ts
+import { govern } from "netzilo";
+
+await govern(); // config from NETZILO_* env vars; non-blocking
+```
+
+**Gating a specific tool call** — every Node agent framework's "tool" is
+ultimately an async function the model calls with arguments. `wrapTool()`
+gates at that common boundary instead of binding to one framework's specific
+hook API (which drifts release to release):
+
+```ts
+import { wrapTool } from "netzilo/wrapTool";
+
+const getOrderStatus = wrapTool(
+  "get_order_status",
+  async (args: { orderId: string }) => fetchOrder(args.orderId)
+);
+
+// Register `getOrderStatus` with LangChain's tool(), the Vercel AI SDK's
+// tool(), or any framework's tool registry exactly as you would the
+// original function.
+```
+
+A blocked call throws `NetziloBlockedError`. A tool result that trips a
+redaction rule (e.g. an AWS key or PII pattern) is returned to the caller
+already sanitized.
+
+## Configuration
+
+`start()` / `govern()` accept an options object. Common keys:
+
+| Key | Description |
+|-----|-------------|
+| `server` | Your Netzilo management server URL. |
+| `pat` / `setupKey` | Credential used to enroll the agent. |
+| `agentName` | Identifier this agent reports as (used for event attribution). |
+| `mcpGatewayPort` | Optional; defaults to an auto-picked free port. `mcpGatewayPort: 0` disables governance. |
+| `enableAdvancedGovernance` | Optional (default off). Deep inspection of the agent's own outbound traffic with semantic classification. |
+| `logLevel` / `logFile` | Logging verbosity and destination. |
+
+## Notes
+
+The native binary is resolved automatically for your platform via an optional
+dependency selected at install time; `npm install netzilo` never downloads a
+binary for a platform you're not on.
+
+Netzilo is a commercial product. See <https://www.netzilo.com>.

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+export declare const DEFAULT_CONFIG_PATH: string;
+export interface StartOptions {
+    /** Management server URL (required on first login). Legacy alias: managementUrl. */
+    server?: string;
+    managementUrl?: string;
+    /** Non-interactive login — one of pat/setupKey required on first login. */
+    pat?: string;
+    setupKey?: string;
+    /** Peer/device name + event attribution (default: hostname). */
+    agentName?: string;
+    /** Config file path (default: ~/.netzilo-sdk/config.json). */
+    configPath?: string;
+    /** Scanner gateway port (default: an auto-picked free port). Set 0 to disable governance. */
+    mcpGatewayPort?: number;
+    /**
+     * Deep inspection of the agent's OWN outbound traffic (beyond framework
+     * hooks): full prompt/response and tool-call analysis with semantic
+     * classification. Default off; framework adapters govern without it.
+     */
+    enableAdvancedGovernance?: boolean;
+    socks5Port?: number;
+    webServPort?: number;
+    logLevel?: string;
+    logFile?: string;
+}
+/**
+ * Start the embedded client. Non-blocking; the client runs in a background
+ * goroutine inside the shared library.
+ *
+ * Returns 0 on launch, 1 if already running, 2 on bad config.
+ */
+export declare function start(opts?: StartOptions): Promise<number>;
+/**
+ * Port the in-process scanner (MCP) gateway is listening on. Auto-picked at
+ * start() unless one was passed explicitly. Returns 0 if not started or
+ * governance is disabled (mcpGatewayPort: 0).
+ */
+export declare function mcpGatewayPort(): number;
+/** Egress port used by advanced governance. Returns 0 if not started. */
+export declare function socks5Port(): number;
+/**
+ * Gracefully stop the client (context cancel). Safe to call repeatedly.
+ *
+ * Stop() flushes any buffered governance events to management first, so a
+ * short-lived embedded run delivers its events before teardown.
+ */
+export declare function stop(): number;
+/**
+ * Force an immediate push of buffered governance events to management.
+ *
+ * Events are normally delivered in the background (near-real-time in
+ * embedded mode); call this to guarantee delivery on demand. No-op on older
+ * bundled libraries without the export.
+ */
+export declare function flush(): void;
+/**
+ * Force an immediate AIDR session-graph snapshot + delivery to management.
+ *
+ * The behavior graph (agents -> tools -> prompts -> redactions) is otherwise
+ * only uploaded hourly and at shutdown. No-op on older bundled libraries.
+ */
+export declare function snapshot(): void;
+/** Whether the embedded client is currently running. */
+export declare function isRunning(): boolean;
+/**
+ * Current agent integrity level: 0=breached, 1=low, 2=medium (default), 3=high.
+ *
+ * Reflects whatever posture rules (set_integrity_level) or host integrity
+ * checks have set in-process.
+ */
+export declare function integrityLevel(): number;
+export type Action = "toolCall" | "toolResult" | "promptRequest" | "promptResponse";
+export interface EvaluateOptions {
+    args?: Record<string, unknown>;
+    output?: string;
+    prompt?: string;
+    response?: string;
+    history?: unknown[];
+    provider?: string;
+    model?: string;
+    durationMs?: number;
+    callId?: string;
+    source?: string;
+    serverName?: string;
+    serverUrl?: string;
+    callerPid?: number;
+}
+export interface Verdict {
+    action: "allow" | "block" | "require_approval";
+    reason?: string;
+    redacted?: boolean;
+    content?: string;
+    [key: string]: unknown;
+}
+/**
+ * Run one hook event through the in-process scanner + AIDR pipeline.
+ *
+ * action:
+ *   "toolCall"        pre-tool, may block            (args)
+ *   "toolResult"      post-tool, fire-and-forget      (output)
+ *   "promptRequest"   LLM prompt before send          (prompt, history)
+ *   "promptResponse"  LLM response before use         (response)
+ *
+ * Fails open ({action: "allow"}) if the scanner is not yet running.
+ */
+export declare function evaluate(action: Action, toolName?: string, opts?: EvaluateOptions): Verdict;
+/** Convenience pre-tool gate. Returns {allowed, reason}. */
+export declare function isAllowed(toolName: string, args?: Record<string, unknown>, opts?: Pick<EvaluateOptions, "callId" | "source" | "serverUrl" | "callerPid">): {
+    allowed: boolean;
+    reason: string;
+};
+/** Convenience post-tool observability report (never blocks). */
+export declare function reportResult(toolName: string, output: string, opts?: Pick<EvaluateOptions, "callId" | "source" | "callerPid">): void;
+/**
+ * Gate an outbound LLM prompt before it is sent to the model.
+ *
+ * Returns {allowed, reason, redactedPrompt}. redactedPrompt is non-null when
+ * the scanner sanitized the prompt — the caller should send that text instead.
+ */
+export declare function checkPrompt(prompt: string, opts?: Pick<EvaluateOptions, "history" | "provider" | "model" | "callId" | "source" | "callerPid">): {
+    allowed: boolean;
+    reason: string;
+    redactedPrompt: string | null;
+};
+/**
+ * Gate an LLM response before the agent consumes it.
+ *
+ * Returns {allowed, reason, redactedResponse}. redactedResponse is non-null
+ * when the scanner sanitized the response — the caller should use that text.
+ */
+export declare function checkResponse(response: string, opts?: Pick<EvaluateOptions, "prompt" | "provider" | "model" | "durationMs" | "callId" | "source" | "callerPid">): {
+    allowed: boolean;
+    reason: string;
+    redactedResponse: string | null;
+};
+/**
+ * One-call, fire-and-forget governance for any Node agent framework.
+ *
+ * Unlike a framework-specific adapter (which hooks that framework's tool-call
+ * boundary), govern() just starts the embedded client with advanced
+ * governance on — the agent's own LLM traffic, egress, and subprocess
+ * behavior are inspected in-process regardless of which framework issues
+ * them. Idempotent (no-op if already running). Config comes from NETZILO_*
+ * env vars, overridable via opts.
+ *
+ *     import { govern } from "netzilo";
+ *     await govern();
+ */
+export declare function govern(opts?: StartOptions): Promise<number>;

package/dist/index.js

@@ -0,0 +1,384 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG_PATH = void 0;
+exports.start = start;
+exports.mcpGatewayPort = mcpGatewayPort;
+exports.socks5Port = socks5Port;
+exports.stop = stop;
+exports.flush = flush;
+exports.snapshot = snapshot;
+exports.isRunning = isRunning;
+exports.integrityLevel = integrityLevel;
+exports.evaluate = evaluate;
+exports.isAllowed = isAllowed;
+exports.reportResult = reportResult;
+exports.checkPrompt = checkPrompt;
+exports.checkResponse = checkResponse;
+exports.govern = govern;
+/**
+ * netzilo — embed the full Netzilo client in-process for AI agent governance.
+ *
+ * The core module loads the bundled Netzilo shared library and exposes an API
+ * that mirrors the C exports (Start/Stop/IsRunning):
+ *
+ *     import * as netzilo from "netzilo";
+ *     netzilo.start({ server: "...", setupKey: "..." }); // non-blocking
+ *     netzilo.stop();                                     // graceful stop
+ *     netzilo.isRunning();                                // boolean
+ *     await netzilo.evaluate(...);                        // per-tool-call verdict, in-process (no HTTP)
+ *     await netzilo.isAllowed(...);                        // convenience: {allowed, reason}
+ *
+ * Framework adapters live in their own entry points under the same package —
+ * no separate installs — e.g. `import { govern } from "netzilo/langchain"`.
+ * They build on evaluate()/isAllowed() to gate tool calls at the framework
+ * boundary. With enableAdvancedGovernance=true, start() additionally governs
+ * the agent's own outbound traffic in depth (see probe.ts / trust.ts).
+ */
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const loader_1 = require("./loader");
+// Default config location — callers shouldn't have to specify it.
+exports.DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".netzilo-sdk", "config.json");
+// Ports actually used by the running client, filled in by start(). Exposed via
+// mcpGatewayPort()/socks5Port() so the host can route traffic / introspect.
+const resolvedPorts = { mcpGatewayPort: 0, socks5Port: 0 };
+// Config directory of the running client (dirname of configPath), set by
+// start(). Used by the advanced-governance setup to locate per-install state.
+let configDir = "";
+let exitHookRegistered = false;
+async function freePorts(n) {
+    // Pick n distinct currently-free localhost TCP ports. Servers are held
+    // listening simultaneously so the returned ports can't collide with each
+    // other, then closed for the client to bind.
+    const servers = [];
+    try {
+        for (let i = 0; i < n; i++) {
+            const server = net.createServer();
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(0, "127.0.0.1", () => resolve());
+            });
+            servers.push(server);
+        }
+        return servers.map((s) => s.address().port);
+    }
+    finally {
+        await Promise.all(servers.map((s) => new Promise((resolve) => {
+            s.close(() => resolve());
+        })));
+    }
+}
+/**
+ * Start the embedded client. Non-blocking; the client runs in a background
+ * goroutine inside the shared library.
+ *
+ * Returns 0 on launch, 1 if already running, 2 on bad config.
+ */
+async function start(opts = {}) {
+    const cfg = { config_path: opts.configPath || exports.DEFAULT_CONFIG_PATH };
+    const server = opts.server ?? opts.managementUrl;
+    if (server) {
+        cfg.management_url = server;
+    }
+    if (opts.pat)
+        cfg.pat = opts.pat;
+    if (opts.setupKey)
+        cfg.setup_key = opts.setupKey;
+    if (opts.agentName)
+        cfg.agent_name = opts.agentName;
+    if (opts.enableAdvancedGovernance !== undefined) {
+        cfg.enable_advanced_governance = opts.enableAdvancedGovernance;
+    }
+    if (opts.webServPort !== undefined)
+        cfg.web_serv_port = opts.webServPort;
+    if (opts.logLevel)
+        cfg.log_level = opts.logLevel;
+    if (opts.logFile)
+        cfg.log_file = opts.logFile;
+    // Auto-pick free ports for the scanner gateway and the advanced-governance
+    // egress when unset, so they never collide with Netzilo.app or a second SDK
+    // process. Pick both at once so they can't clash with each other. Pass an
+    // explicit port to override, or mcpGatewayPort: 0 to disable governance.
+    const needMcp = opts.mcpGatewayPort === undefined;
+    const needSocks = opts.socks5Port === undefined;
+    if (needMcp || needSocks) {
+        const picked = await freePorts((needMcp ? 1 : 0) + (needSocks ? 1 : 0));
+        let i = 0;
+        cfg.mcp_gateway_port = needMcp ? picked[i++] : opts.mcpGatewayPort;
+        cfg.socks5_port = needSocks ? picked[i++] : opts.socks5Port;
+    }
+    else {
+        cfg.mcp_gateway_port = opts.mcpGatewayPort;
+        cfg.socks5_port = opts.socks5Port;
+    }
+    // Advanced governance: publish the security-probe socket path BEFORE the
+    // native client starts so its receiver binds the exact path the probe
+    // connects to (no startup race). Linux-only; no-op otherwise. Gated on
+    // advanced mode — with it off, the probe socket is never primed and no
+    // hooks are installed.
+    if (cfg.enable_advanced_governance) {
+        const { primeSocketEnv } = await Promise.resolve().then(() => __importStar(require("./probe")));
+        primeSocketEnv(path.dirname(cfg.config_path));
+    }
+    const lib = (0, loader_1.load)();
+    const rc = lib.Start(JSON.stringify(cfg));
+    if (rc === 0) {
+        resolvedPorts.mcpGatewayPort = cfg.mcp_gateway_port || 0;
+        resolvedPorts.socks5Port = cfg.socks5_port || 0;
+        configDir = path.dirname(cfg.config_path);
+        if (!exitHookRegistered) {
+            exitHookRegistered = true;
+            // process 'exit' handlers must be synchronous; Stop() is a synchronous
+            // FFI call via koffi, so a plain handler here is sufficient.
+            process.on("exit", () => {
+                stop();
+            });
+        }
+        if (cfg.enable_advanced_governance) {
+            await enableAdvancedGovernance();
+        }
+    }
+    return rc;
+}
+/**
+ * Internal: prepare the process for deep inspection of the agent's own
+ * traffic. Idempotent; never throws (must not break the agent).
+ */
+async function enableAdvancedGovernance() {
+    if (!configDir) {
+        return;
+    }
+    try {
+        const { installTrust, installRouting } = await Promise.resolve().then(() => __importStar(require("./trust")));
+        await installTrust(configDir);
+        installRouting(resolvedPorts.socks5Port);
+        // Inject the userspace security probe (Linux only) so the agent's process
+        // + subprocess activity is reported to the native client's receiver,
+        // mirroring the macOS Endpoint Security extension. Only reached under
+        // advanced governance.
+        const { install: installProbe } = await Promise.resolve().then(() => __importStar(require("./probe")));
+        installProbe(configDir);
+    }
+    catch (err) {
+        // Advanced-governance setup must never break the agent.
+        // eslint-disable-next-line no-console
+        console.warn("netzilo: advanced governance setup failed:", err);
+    }
+}
+/**
+ * Port the in-process scanner (MCP) gateway is listening on. Auto-picked at
+ * start() unless one was passed explicitly. Returns 0 if not started or
+ * governance is disabled (mcpGatewayPort: 0).
+ */
+function mcpGatewayPort() {
+    return resolvedPorts.mcpGatewayPort;
+}
+/** Egress port used by advanced governance. Returns 0 if not started. */
+function socks5Port() {
+    return resolvedPorts.socks5Port;
+}
+/**
+ * Gracefully stop the client (context cancel). Safe to call repeatedly.
+ *
+ * Stop() flushes any buffered governance events to management first, so a
+ * short-lived embedded run delivers its events before teardown.
+ */
+function stop() {
+    const lib = (0, loader_1.load)();
+    const rc = lib.Stop();
+    resolvedPorts.mcpGatewayPort = 0;
+    resolvedPorts.socks5Port = 0;
+    // Undo advanced-governance traffic routing so a host process that keeps
+    // running after stop() doesn't route to the now-closed egress port.
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { uninstallRouting } = require("./trust");
+        uninstallRouting();
+    }
+    catch {
+        // stop() must never throw
+    }
+    // Stop injecting the probe into subprocesses spawned after stop().
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { uninstall: uninstallProbe } = require("./probe");
+        uninstallProbe();
+    }
+    catch {
+        // stop() must never throw
+    }
+    return rc;
+}
+/**
+ * Force an immediate push of buffered governance events to management.
+ *
+ * Events are normally delivered in the background (near-real-time in
+ * embedded mode); call this to guarantee delivery on demand. No-op on older
+ * bundled libraries without the export.
+ */
+function flush() {
+    (0, loader_1.load)().FlushEvents();
+}
+/**
+ * Force an immediate AIDR session-graph snapshot + delivery to management.
+ *
+ * The behavior graph (agents -> tools -> prompts -> redactions) is otherwise
+ * only uploaded hourly and at shutdown. No-op on older bundled libraries.
+ */
+function snapshot() {
+    (0, loader_1.load)().FlushSnapshot();
+}
+/** Whether the embedded client is currently running. */
+function isRunning() {
+    return (0, loader_1.load)().IsRunning() !== 0;
+}
+/**
+ * Current agent integrity level: 0=breached, 1=low, 2=medium (default), 3=high.
+ *
+ * Reflects whatever posture rules (set_integrity_level) or host integrity
+ * checks have set in-process.
+ */
+function integrityLevel() {
+    return (0, loader_1.load)().GetIntegrityLevel();
+}
+/**
+ * Run one hook event through the in-process scanner + AIDR pipeline.
+ *
+ * action:
+ *   "toolCall"        pre-tool, may block            (args)
+ *   "toolResult"      post-tool, fire-and-forget      (output)
+ *   "promptRequest"   LLM prompt before send          (prompt, history)
+ *   "promptResponse"  LLM response before use         (response)
+ *
+ * Fails open ({action: "allow"}) if the scanner is not yet running.
+ */
+function evaluate(action, toolName = "", opts = {}) {
+    const lib = (0, loader_1.load)();
+    const source = opts.source ?? "agentsdk";
+    const req = {
+        action,
+        tool_name: toolName,
+        server_name: opts.serverName ?? source,
+        call_id: opts.callId ?? "",
+        source,
+        server_url: opts.serverUrl ?? "",
+        caller_pid: opts.callerPid || process.pid,
+    };
+    if (opts.args !== undefined) {
+        req.args = opts.args;
+    }
+    if (opts.output !== undefined)
+        req.output = opts.output;
+    if (opts.prompt !== undefined)
+        req.prompt = opts.prompt;
+    if (opts.response !== undefined)
+        req.response = opts.response;
+    if (opts.history && opts.history.length) {
+        req.history = opts.history.map((h) => String(h));
+    }
+    if (opts.provider)
+        req.provider = opts.provider;
+    if (opts.model)
+        req.model = opts.model;
+    if (opts.durationMs)
+        req.duration_ms = opts.durationMs;
+    const raw = lib.Evaluate(JSON.stringify(req));
+    return raw ? JSON.parse(raw) : { action: "allow" };
+}
+/** Convenience pre-tool gate. Returns {allowed, reason}. */
+function isAllowed(toolName, args = {}, opts = {}) {
+    const verdict = evaluate("toolCall", toolName, { ...opts, args });
+    const action = verdict.action ?? "allow";
+    return { allowed: action === "allow", reason: verdict.reason ?? "" };
+}
+/** Convenience post-tool observability report (never blocks). */
+function reportResult(toolName, output, opts = {}) {
+    evaluate("toolResult", toolName, { ...opts, output });
+}
+/**
+ * Gate an outbound LLM prompt before it is sent to the model.
+ *
+ * Returns {allowed, reason, redactedPrompt}. redactedPrompt is non-null when
+ * the scanner sanitized the prompt — the caller should send that text instead.
+ */
+function checkPrompt(prompt, opts = {}) {
+    const v = evaluate("promptRequest", "", { ...opts, prompt });
+    const allowed = (v.action ?? "allow") === "allow";
+    const redactedPrompt = v.redacted ? v.content ?? null : null;
+    return { allowed, reason: v.reason ?? "", redactedPrompt };
+}
+/**
+ * Gate an LLM response before the agent consumes it.
+ *
+ * Returns {allowed, reason, redactedResponse}. redactedResponse is non-null
+ * when the scanner sanitized the response — the caller should use that text.
+ */
+function checkResponse(response, opts = {}) {
+    const v = evaluate("promptResponse", "", { ...opts, response });
+    const allowed = (v.action ?? "allow") === "allow";
+    const redactedResponse = v.redacted ? v.content ?? null : null;
+    return { allowed, reason: v.reason ?? "", redactedResponse };
+}
+/**
+ * One-call, fire-and-forget governance for any Node agent framework.
+ *
+ * Unlike a framework-specific adapter (which hooks that framework's tool-call
+ * boundary), govern() just starts the embedded client with advanced
+ * governance on — the agent's own LLM traffic, egress, and subprocess
+ * behavior are inspected in-process regardless of which framework issues
+ * them. Idempotent (no-op if already running). Config comes from NETZILO_*
+ * env vars, overridable via opts.
+ *
+ *     import { govern } from "netzilo";
+ *     await govern();
+ */
+async function govern(opts = {}) {
+    if (isRunning()) {
+        return 1;
+    }
+    const cfg = {
+        server: process.env.NETZILO_SERVER || "https://srv.netzilo.com",
+        agentName: process.env.NETZILO_AGENT_NAME,
+        enableAdvancedGovernance: process.env.NETZILO_ADVANCED !== "0",
+        logLevel: process.env.NETZILO_LOG_LEVEL || "info",
+        logFile: "console",
+        ...(process.env.NETZILO_SETUP_KEY ? { setupKey: process.env.NETZILO_SETUP_KEY } : {}),
+        ...(process.env.NETZILO_PAT ? { pat: process.env.NETZILO_PAT } : {}),
+        ...opts,
+    };
+    return start(cfg);
+}

package/dist/loader.d.ts

@@ -0,0 +1,21 @@
+export interface NetziloLib {
+    Start(configJSON: string): number;
+    Stop(): number;
+    IsRunning(): number;
+    /**
+     * Returns the decoded JSON string directly, or null. Evaluate's C return
+     * value is a heap-allocated char* that must be released with FreeString —
+     * bound as a koffi "disposable type" (see below), so koffi calls FreeString
+     * on the original pointer automatically right after decoding it to a JS
+     * string. Callers never see or manage the pointer.
+     */
+    Evaluate(reqJSON: string): string | null;
+    /** Absent on older bundled libraries; guarded with a no-op fallback. */
+    FlushEvents(): void;
+    FlushSnapshot(): void;
+    GetIntegrityLevel(): number;
+}
+export declare function load(): NetziloLib;
+/** Test-only: forget the cached binding so a fresh NETZILO_LIB_PATH can be picked up. */
+export declare function _resetForTests(): void;
+export declare function tmpDir(): string;