@watchlight/sdk 0.1.0 → 0.2.0

package/README.md

@@ -81,6 +81,33 @@ for await (const msg of query({ prompt, options: { hooks } })) {
 The hook is fail-closed and never throws back to the SDK — a governance error
 denies the call. Every decision is audited.
 
+## LangChain / LangGraph.js
+
+Govern any LangChain `StructuredTool` (which is what LangGraph.js tools are) — the
+tool is authorized before it runs; denied tools throw and never execute.
+
+```ts
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+import { govern, governTool } from "@watchlight/sdk";
+
+govern.load("watchlight.policy.json");
+
+const search = governTool(
+  tool(async ({ query }) => webSearch(query), {
+    name: "web_search",
+    schema: z.object({ query: z.string() }),
+  }),
+  { intent: "research" }
+);
+
+// Pass `search` to your LangGraph ToolNode / createReactAgent as usual.
+```
+
+`governTool(tool, { intent })` returns a governed view (the original tool isn't
+mutated); `governTools(tools, { intentFor })` maps an array. Intent defaults to
+the tool's name. Fail-closed. `@langchain/core` is a peer dependency.
+
 ## Value-free audit
 
 `.watchlight/audit.jsonl` records **who / what intent / which tool / the

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { Scope } from "./attenuation";
 export { Scope, DE_MAX_DEPTH, AttenuationDenied, DevEditionCeiling } from "./attenuation";
 export { governedHooks } from "./claude-agent";
 export type { GovernedHooksOptions, GovernedHooksResult } from "./claude-agent";
+export { governTool, governTools } from "./langchain";
+export type { LangChainToolLike, GovernToolOptions, GovernToolsOptions, } from "./langchain";
 export type { GovernanceBackend, Decision, AuthorizeRequest } from "./backend";
 export { InProcessBackend, NetworkedBackend } from "./backend";
 /** Raised when the policy engine refuses a governed tool call (fail-closed). */

package/dist/index.js

@@ -49,7 +49,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.govern = exports.Watchlight = exports.Denied = exports.NetworkedBackend = exports.InProcessBackend = exports.governedHooks = exports.DevEditionCeiling = exports.AttenuationDenied = exports.DE_MAX_DEPTH = exports.Scope = void 0;
+exports.govern = exports.Watchlight = exports.Denied = exports.NetworkedBackend = exports.InProcessBackend = exports.governTools = exports.governTool = exports.governedHooks = exports.DevEditionCeiling = exports.AttenuationDenied = exports.DE_MAX_DEPTH = exports.Scope = void 0;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const attenuation_1 = require("./attenuation");
@@ -61,6 +61,9 @@ Object.defineProperty(exports, "AttenuationDenied", { enumerable: true, get: fun
 Object.defineProperty(exports, "DevEditionCeiling", { enumerable: true, get: function () { return attenuation_2.DevEditionCeiling; } });
 var claude_agent_1 = require("./claude-agent");
 Object.defineProperty(exports, "governedHooks", { enumerable: true, get: function () { return claude_agent_1.governedHooks; } });
+var langchain_1 = require("./langchain");
+Object.defineProperty(exports, "governTool", { enumerable: true, get: function () { return langchain_1.governTool; } });
+Object.defineProperty(exports, "governTools", { enumerable: true, get: function () { return langchain_1.governTools; } });
 var backend_2 = require("./backend");
 Object.defineProperty(exports, "InProcessBackend", { enumerable: true, get: function () { return backend_2.InProcessBackend; } });
 Object.defineProperty(exports, "NetworkedBackend", { enumerable: true, get: function () { return backend_2.NetworkedBackend; } });

package/dist/langchain.d.ts

@@ -0,0 +1,32 @@
+import { Watchlight } from "./index";
+/** The minimal shape of a LangChain `StructuredTool` this adapter needs. */
+export interface LangChainToolLike {
+    name: string;
+    invoke(input: unknown, config?: unknown): Promise<unknown>;
+    [k: string]: unknown;
+}
+export interface GovernToolOptions {
+    /** The governor to authorize against. Defaults to the shared `govern`. */
+    governor?: Watchlight;
+    /** Governance intent for this tool. Defaults to the tool's `name`. */
+    intent?: string;
+}
+export interface GovernToolsOptions {
+    governor?: Watchlight;
+    /** Map a tool name to a governance intent. Defaults to identity (intent =
+     *  tool name). */
+    intentFor?: (toolName: string) => string;
+}
+/**
+ * Wrap a LangChain / LangGraph.js tool so its `invoke` is authorized by the
+ * in-process engine before it runs. Returns a governed view of the tool (a
+ * Proxy) — pass it to your agent / `ToolNode` exactly like the original. The
+ * original tool is not mutated. Fail-closed: on anything but ALLOW, `invoke`
+ * throws `Denied` and the underlying tool never executes.
+ */
+export declare function governTool<T extends LangChainToolLike>(tool: T, opts?: GovernToolOptions): T;
+/**
+ * Govern an array of LangChain / LangGraph.js tools. `intentFor` maps each tool
+ * name to an intent (default: the tool name).
+ */
+export declare function governTools<T extends LangChainToolLike>(tools: T[], opts?: GovernToolsOptions): T[];

package/dist/langchain.js

@@ -0,0 +1,64 @@
+"use strict";
+// LangChain / LangGraph.js integration — govern a tool's execution with the
+// in-process engine. The TS counterpart of Python `watchlight.langgraph`.
+//
+//   import { tool } from "@langchain/core/tools";
+//   import { govern, governTool } from "@watchlight/sdk";
+//
+//   govern.load("watchlight.policy.json");
+//   const search = governTool(
+//     tool(async ({ query }) => webSearch(query), { name: "web_search", schema }),
+//     { intent: "research" }
+//   );
+//   // pass `search` to your LangGraph agent / ToolNode as usual.
+//
+// Before the tool runs, the engine authorizes (agent, intent, tool/<name>). ALLOW
+// runs it; anything else throws `Denied` and the tool body never executes —
+// denied before it runs. Fail-closed. Works for any LangChain `StructuredTool`
+// (which is what LangGraph.js tools are).
+//
+// This is glue: it intercepts the tool's `invoke`; the decision comes from the
+// engine (via the shared governor). No LangChain hard dependency — the adapter is
+// structurally typed against the tool's public shape, so `@langchain/core` stays
+// a peer you already have installed.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.governTool = governTool;
+exports.governTools = governTools;
+const index_1 = require("./index");
+/**
+ * Wrap a LangChain / LangGraph.js tool so its `invoke` is authorized by the
+ * in-process engine before it runs. Returns a governed view of the tool (a
+ * Proxy) — pass it to your agent / `ToolNode` exactly like the original. The
+ * original tool is not mutated. Fail-closed: on anything but ALLOW, `invoke`
+ * throws `Denied` and the underlying tool never executes.
+ */
+function governTool(tool, opts = {}) {
+    const governor = opts.governor ?? index_1.govern;
+    const intent = opts.intent ?? tool.name;
+    const name = tool.name;
+    return new Proxy(tool, {
+        get(target, prop, receiver) {
+            if (prop === "invoke") {
+                return async (input, config) => {
+                    const { allowed, reason } = await governor.check(intent, name);
+                    if (!allowed) {
+                        throw new index_1.Denied(name, intent, reason || "no matching policy");
+                    }
+                    return target.invoke(input, config);
+                };
+            }
+            // Delegate everything else to the real tool, bound to it so `this` stays
+            // correct and internal calls hit the real (un-governed) methods.
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+/**
+ * Govern an array of LangChain / LangGraph.js tools. `intentFor` maps each tool
+ * name to an intent (default: the tool name).
+ */
+function governTools(tools, opts = {}) {
+    const intentFor = opts.intentFor ?? ((n) => n);
+    return tools.map((t) => governTool(t, { governor: opts.governor, intent: intentFor(t.name) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchlight/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Watchlight Developer Edition govern glue for Node/TypeScript — declare intent, govern a tool with a fail-closed in-process policy decision, and get a value-free audit trail. Glue over @watchlight/engine; zero decision logic in JS.",
   "type": "commonjs",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/govern.test.mjs && node test/claude-agent.test.mjs && node test/graduation.test.mjs",
+    "test": "npm run build && node test/govern.test.mjs && node test/claude-agent.test.mjs && node test/graduation.test.mjs && node test/langchain.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [