@atbash/atbash-langgraph 0.0.13 → 0.0.15-dev.0

package/LICENSE

@@ -0,0 +1,14 @@
+Atbash CLI — Proprietary Software License
+
+Copyright © 2026 Atbash. All rights reserved.
+
+The full license is available at https://atbash.ai/license
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Atbash.

package/README.md

@@ -45,6 +45,19 @@ addAtbashSafety(builder, {
 const app = builder.compile({ checkpointer: new MemorySaver() });
 ```
 
+`addAtbashSafety` rewrites every route into your tools node so it passes through
+`atbash_guard` first — a router that returns `"tools"`, a plain `agent -> tools` edge, or
+nothing at all. A checkpointer is required: `HOLD` pauses the run with `interrupt()`, and a
+hold that cannot pause is blocked.
+
+**Call order does not matter.** Routes you add *after* `addAtbashSafety` are rewritten too:
+the helper takes over `addEdge()` and `addConditionalEdges()` on your builder for the rest
+of the wiring. A route it cannot rewrite — a `Command()` destination declared with
+`addNode(..., { ends: ["tools"] })`, or a direct write to the builder's internals — makes
+`compile()` throw rather than run unjudged. The one case that fails at run time instead is a
+branch returning `new Send("tools", ...)`, which carries a payload that cannot be re-pointed;
+send it to `"atbash_guard"` instead.
+
 ## API
 
 ### `addAtbashSafety(builder, opts)`
@@ -61,7 +74,11 @@ Assumes your graph has nodes named `agent` and `tools`. If your layout differs,
 
 ### `createGuardNode(opts)`
 
-Creates the pre-tool safety node. Calls `client.auditToolCall()` for every tool call in the last AI message.
+Creates the pre-tool safety node. Calls `client.auditToolCall()` for every tool call in the last AI
+message that has no answering `ToolMessage` — the same calls a prebuilt `ToolNode` would run, so the
+guard and the executor cannot disagree about what is about to execute. Memory reads and writes are
+handed to the SDK's memory guard first; only a decision that positively allows takes a call out of
+the batch audit.
 
 Returns a node function that writes `atbashVerdict`, `atbashReason`, `atbashToolCallId` to state.
 
@@ -88,10 +105,12 @@ Optional: creates an `atbash_safety_check` LangChain tool for direct LLM access
 
 | Verdict | Meaning | Graph Behavior |
 |---|---|---|
-| `ALLOW` | Safe to proceed | Routes to `tools` node |
+| `ALLOW` | Safe to proceed, and `allow` is not `false` | Routes to `tools` node |
+| `SKIP` | Nothing pending to judge | Routes to `END` — never to `tools` |
 | `HOLD` | Needs human review | Graph interrupts; resume with `Command({ resume: "approve" })` |
 | `BLOCK` | Policy violation | Injects blocked `ToolMessage`; routes back to `agent` |
 | `ERROR` | Judge unreachable | Treated as `BLOCK` — fail closed |
+| anything else | Unrecognised, malformed, or tampered decision | Treated as `BLOCK` — fail closed |
 
 ## HOLD / Resume Pattern
 
@@ -111,6 +130,17 @@ if (isInterrupted(result)) {
 }
 ```
 
+The resume value is whatever you pass, so it is not treated as approval. The guard node
+re-executes from the top on resume: it re-submits the held action with `auditToolCall()` and
+releases it only on a positively matched `ALLOW` — either from that re-audit, or from
+`getJudgmentStatus()` on the judgment the re-audit returned. A still-pending hold, any other
+verdict, or an unreachable judge keeps it held.
+
+The `getJudgmentStatus()` half only fires if the backend returns the same `toolCallId` for a
+resubmitted action; if it mints a fresh id per submission, release happens entirely through the
+re-audit. Both routes require an explicit `ALLOW`, so either way approving from the dashboard
+and asking the agent to try again is the supported flow.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/index.d.ts

@@ -30,13 +30,13 @@ interface AtbashSafetyOptions {
     endpoint?: string;
     toolsNode?: string;
     agentNode?: string;
-    /** Agent workspace directory — `~` is expanded. Defaults to `process.cwd()`. */
+    /** Agent workspace directory - `~` is expanded. Defaults to `process.cwd()`. */
     workspaceDir?: string;
     /** Explicit MEMORY.md path. Overrides `workspaceDir/MEMORY.md`. */
     memoryFilePath?: string;
     /** How long (ms) to trust the local pointer between chain checks. Default 30000. */
     memorySyncTTLMs?: number;
-    /** Block memory reads when a rolled-back version scores below this (1–10). Default 1 = warn only. */
+    /** Block memory reads when a rolled-back version scores below this (1-10). Default 1 = warn only. */
     memoryRollbackMinScore?: number;
     /** Custom memory path patterns. Defaults to SDK built-ins. */
     memoryPathPatterns?: string[];
@@ -46,7 +46,7 @@ interface AtbashSafetyOptions {
     judgeVerifyPubKey?: string;
     /** Organization name for chain resolution (public vs private chain). */
     orgName?: string;
-    /** false = monitor mode: log but never block. Default true. */
+    /** false = monitor mode for the memory guard: log but never block. Default true. */
     enforce?: boolean;
     debug?: boolean;
 }

package/dist/index.js

@@ -21,16 +21,38 @@ var AtbashStateAnnotation = Annotation.Root({
 });
 
 // src/nodes/guardNode.ts
-import { MemoryIntegrityError } from "@atbash/sdk";
-import { ToolMessage } from "@langchain/core/messages";
-import { isGraphBubbleUp } from "@langchain/langgraph";
+import {
+  MemoryIntegrityError
+} from "@atbash/sdk";
+import { ToolMessage, isAIMessage } from "@langchain/core/messages";
+import { interrupt, isGraphBubbleUp } from "@langchain/langgraph";
+function pendingToolCalls(messages) {
+  const answered = new Set(
+    messages.filter((message) => message?.getType?.() === "tool").map((message) => message.tool_call_id)
+  );
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!message || !isAIMessage(message)) continue;
+    const calls = message.tool_calls ?? [];
+    return calls.filter((call) => call.id == null || !answered.has(call.id));
+  }
+  return [];
+}
+async function approvedOnResume(client, toolCallId) {
+  if (!toolCallId) return false;
+  try {
+    const status = await client.getJudgmentStatus(toolCallId);
+    return status.status === "answered" && status.verdict === "ALLOW";
+  } catch {
+    return false;
+  }
+}
 function createGuardNode(opts) {
   return async (state) => {
-    const lastMessage = state.messages[state.messages.length - 1];
-    const toolCalls = lastMessage?.tool_calls ?? [];
+    const toolCalls = pendingToolCalls(state.messages);
     if (toolCalls.length === 0) {
       return {
-        atbashVerdict: "ALLOW",
+        atbashVerdict: "SKIP",
         atbashReason: "No tool calls detected"
       };
     }
@@ -50,7 +72,7 @@ function createGuardNode(opts) {
             messages: toolCalls.map(
               (toolCall) => new ToolMessage({
                 tool_call_id: toolCall.id,
-                content: toolCall.id === tc.id ? `Memory guard error: ${reason}` : "Blocked \u2014 memory safety check failed for another tool call"
+                content: toolCall.id === tc.id ? `Memory guard error: ${reason}` : "Blocked - memory safety check failed for another tool call"
               })
             ),
             atbashVerdict: verdict,
@@ -60,16 +82,31 @@ function createGuardNode(opts) {
           };
         }
         if (memDecision !== null) {
-          if (memDecision.block) {
+          const decided = memDecision;
+          if (decided.block) {
             return {
               messages: toolCalls.map(
                 (toolCall) => new ToolMessage({
                   tool_call_id: toolCall.id,
-                  content: toolCall.id === tc.id ? `Memory write blocked by Atbash: ${memDecision.blockReason ?? ""}` : "Blocked \u2014 another tool call was blocked by memory safety"
+                  content: toolCall.id === tc.id ? `Memory write blocked by Atbash: ${decided.blockReason ?? ""}` : "Blocked - another tool call was blocked by memory safety"
                 })
               ),
               atbashVerdict: "BLOCK",
-              atbashReason: memDecision.blockReason ?? "memory write blocked",
+              atbashReason: decided.blockReason ?? "memory write blocked",
+              atbashToolCallId: null,
+              atbashConfidence: null
+            };
+          }
+          if (decided.allow !== true) {
+            return {
+              messages: toolCalls.map(
+                (toolCall) => new ToolMessage({
+                  tool_call_id: toolCall.id,
+                  content: toolCall.id === tc.id ? `BLOCKED by Atbash: unusable memory guard decision: ${decided.reason ?? "no reason"}` : "Blocked - memory safety returned an unusable decision for another tool call"
+                })
+              ),
+              atbashVerdict: "BLOCK",
+              atbashReason: decided.reason ?? "unusable memory guard decision",
               atbashToolCallId: null,
               atbashConfidence: null
             };
@@ -110,11 +147,26 @@ function createGuardNode(opts) {
       }
       if (decision.verdict === "HOLD") {
         const holdParts = [
-          "Action held for operator review. The agent will not be jailed \u2014 please approve or reject this request from the Atbash dashboard, then ask the agent to try again.",
+          "Action held for operator review. The agent will not be jailed - please approve or reject this request from the Atbash dashboard, then ask the agent to try again.",
           `Reason: ${decision.reason ?? ""}`
         ];
         if (decision.toolCallId) holdParts.push(`Tool Call ID: ${decision.toolCallId}`);
         const holdMessage = holdParts.join("\n");
+        interrupt({
+          verdict: "HOLD",
+          reason: decision.reason ?? "held for review",
+          toolCallId: decision.toolCallId ?? null,
+          message: holdMessage,
+          toolCalls: toolCalls.map(({ id, name, args }) => ({ id, name, args }))
+        });
+        if (await approvedOnResume(opts.client, decision.toolCallId)) {
+          return {
+            atbashVerdict: "ALLOW",
+            atbashReason: decision.reason,
+            atbashToolCallId: decision.toolCallId,
+            atbashConfidence: null
+          };
+        }
         return {
           messages: toolCalls.map(
             (toolCall) => new ToolMessage({
@@ -128,9 +180,26 @@ function createGuardNode(opts) {
           atbashConfidence: null
         };
       }
+      if (decision.verdict === "ALLOW" && decision.allow !== false) {
+        return {
+          atbashVerdict: "ALLOW",
+          atbashReason: decision.reason,
+          atbashToolCallId: decision.toolCallId,
+          atbashConfidence: null
+        };
+      }
+      const unusable = `BLOCKED by Atbash: unusable decision ${String(
+        decision.verdict
+      )}: ${decision.reason ?? "no reason"}`;
       return {
-        atbashVerdict: "ALLOW",
-        atbashReason: decision.reason,
+        messages: toolCalls.map(
+          (toolCall) => new ToolMessage({
+            tool_call_id: toolCall.id,
+            content: unusable
+          })
+        ),
+        atbashVerdict: "BLOCK",
+        atbashReason: decision.reason ?? "unusable Atbash decision",
         atbashToolCallId: decision.toolCallId,
         atbashConfidence: null
       };
@@ -185,9 +254,101 @@ import {
   shutdownTelemetry
 } from "@atbash/sdk";
 import { homedir } from "os";
+import { RunnableLambda } from "@langchain/core/runnables";
+import { END } from "@langchain/langgraph";
 function expandHome(p) {
   return p.replace(/^~(?=\/|$)/, homedir());
 }
+var GUARD_NODE = "atbash_guard";
+var AUDIT_NODE = "atbash_audit";
+var GUARDED_BRANCH = /* @__PURE__ */ Symbol.for("atbash.langgraph.guardedBranch");
+var SEALED = /* @__PURE__ */ Symbol.for("atbash.langgraph.sealed");
+function rewriteDestination(destination, toolsNode, hasEnds) {
+  if (destination && typeof destination === "object" && destination.node === toolsNode) {
+    throw new Error(
+      `Atbash cannot guard a Send() to "${toolsNode}" - send to "${GUARD_NODE}" instead.`
+    );
+  }
+  if (!hasEnds && destination === toolsNode) return GUARD_NODE;
+  return destination;
+}
+function wrapBranchPath(branch, toolsNode) {
+  const original = branch.path;
+  const hasEnds = branch.ends != null;
+  return RunnableLambda.from(async (input, config) => {
+    const result = await original.invoke(input, config);
+    return Array.isArray(result) ? result.map((destination) => rewriteDestination(destination, toolsNode, hasEnds)) : rewriteDestination(result, toolsNode, hasEnds);
+  });
+}
+function hasEdge(graph, from, to) {
+  return [...graph.edges].some(([start, end]) => start === from && end === to);
+}
+function isGuardedBranch(branch) {
+  return branch[GUARDED_BRANCH] === true;
+}
+function routeToolsThroughGuard(graph, toolsNode) {
+  for (const edge of [...graph.edges]) {
+    const [from, to] = edge;
+    if (to !== toolsNode || from === GUARD_NODE) continue;
+    graph.edges.delete(edge);
+    if (!hasEdge(graph, from, GUARD_NODE)) graph.edges.add([from, GUARD_NODE]);
+  }
+  for (const [source, branches] of Object.entries(graph.branches)) {
+    if (source === GUARD_NODE) continue;
+    for (const branch of Object.values(branches)) {
+      for (const [key, destination] of Object.entries(branch.ends ?? {})) {
+        if (destination === toolsNode) branch.ends[key] = GUARD_NODE;
+      }
+      if (isGuardedBranch(branch)) continue;
+      branch.path = wrapBranchPath(branch, toolsNode);
+      Object.defineProperty(branch, GUARDED_BRANCH, { value: true });
+    }
+  }
+}
+function assertGuardOwnsToolsNode(graph, toolsNode) {
+  const refuse = (source, kind) => {
+    throw new Error(
+      `Atbash: ${kind} from "${source}" reaches "${toolsNode}" directly, bypassing "${GUARD_NODE}" - route it to "${GUARD_NODE}" instead. addAtbashSafety() rewrites routes added through addEdge()/addConditionalEdges(); this one it cannot rewrite, and running it unjudged is not an option.`
+    );
+  };
+  for (const [from, to] of graph.edges) {
+    if (to === toolsNode && from !== GUARD_NODE) refuse(from, "an edge");
+  }
+  for (const [source, branches] of Object.entries(graph.branches)) {
+    if (source === GUARD_NODE) continue;
+    for (const branch of Object.values(branches)) {
+      for (const destination of Object.values(branch.ends ?? {})) {
+        if (destination === toolsNode) refuse(source, "a conditional edge");
+      }
+      if (!isGuardedBranch(branch)) refuse(source, "an unvetted conditional edge");
+    }
+  }
+  for (const [name, node] of Object.entries(graph.nodes)) {
+    if (name === GUARD_NODE) continue;
+    if (node?.ends?.includes(toolsNode)) refuse(name, "a Command route");
+  }
+}
+function sealRoutesIntoGuard(graph, toolsNode) {
+  if (graph[SEALED] === true) return;
+  Object.defineProperty(graph, SEALED, { value: true });
+  const addEdge = graph.addEdge.bind(graph);
+  const addConditionalEdges = graph.addConditionalEdges.bind(graph);
+  const compile = graph.compile.bind(graph);
+  graph.addEdge = (...args) => {
+    const result = addEdge(...args);
+    routeToolsThroughGuard(graph, toolsNode);
+    return result;
+  };
+  graph.addConditionalEdges = (...args) => {
+    const result = addConditionalEdges(...args);
+    routeToolsThroughGuard(graph, toolsNode);
+    return result;
+  };
+  graph.compile = (...args) => {
+    assertGuardOwnsToolsNode(graph, toolsNode);
+    return compile(...args);
+  };
+}
 function addAtbashSafety(builder, opts) {
   setupTelemetry({ enabled: true, source: "plugin:langgraph" });
   process.once("beforeExit", () => shutdownTelemetry());
@@ -216,13 +377,23 @@ function addAtbashSafety(builder, opts) {
   const graph = builder;
   const toolsNode = opts.toolsNode ?? "tools";
   const agentNode = opts.agentNode ?? "agent";
-  graph.addNode("atbash_guard", createGuardNode({ client, guardManager: guard }));
-  graph.addNode("atbash_audit", createAuditNode({ client }));
-  graph.addConditionalEdges("atbash_guard", (state) => {
-    return state.atbashVerdict === "ALLOW" ? toolsNode : agentNode;
-  });
-  graph.addEdge(toolsNode, "atbash_audit");
-  graph.addEdge("atbash_audit", agentNode);
+  routeToolsThroughGuard(graph, toolsNode);
+  const agentHasRoute = [...graph.edges].some(([from]) => from === agentNode) || graph.branches[agentNode] != null;
+  if (!agentHasRoute) graph.addEdge(agentNode, GUARD_NODE);
+  graph.addNode(GUARD_NODE, createGuardNode({ client, guardManager: guard }));
+  graph.addNode(AUDIT_NODE, createAuditNode({ client }));
+  graph.addConditionalEdges(
+    GUARD_NODE,
+    (state) => {
+      if (state.atbashVerdict === "ALLOW") return toolsNode;
+      if (state.atbashVerdict === "SKIP") return END;
+      return agentNode;
+    },
+    [toolsNode, agentNode, END]
+  );
+  graph.addEdge(toolsNode, AUDIT_NODE);
+  graph.addEdge(AUDIT_NODE, agentNode);
+  sealRoutesIntoGuard(graph, toolsNode);
   return builder;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/atbash-langgraph",
-  "version": "0.0.13",
+  "version": "0.0.15-dev.0",
   "description": "Atbash safety guard and audit nodes for LangGraph workflows",
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "atbash",
@@ -25,7 +26,11 @@
     "audit",
     "policy"
   ],
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Atbash-Ai/atbash-langgraph-plugin"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -33,11 +38,14 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "prepublishOnly": "npm run build"
+    "test": "tsc --noEmit && node test/build.mjs && vitest run && node --test test/guard-node.test.mjs test/graph.test.mjs",
+    "build": "node scripts/clean.mjs && tsup src/index.ts --format esm --dts --clean",
+    "verify:package": "node scripts/release.mjs --verify-current",
+    "release": "node scripts/release.mjs --channel latest",
+    "release:dev": "node scripts/release.mjs --channel dev"
   },
   "dependencies": {
-    "@atbash/sdk": "^0.7.0",
+    "@atbash/sdk": "0.10.11-dev.0",
     "zod": "^3.25.76"
   },
   "peerDependencies": {
@@ -48,7 +56,9 @@
     "@langchain/core": "^1.1.45",
     "@langchain/langgraph": "^1.3.0",
     "@types/node": "^25.7.0",
+    "semver": "7.8.5",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.6"
   }
 }