@atbash/atbash-langgraph 0.0.1

package/README.md

@@ -0,0 +1,134 @@
+# `@atbash/atbash-langgraph`
+
+Add Atbash as a safety guard inside a LangGraph workflow.
+
+This package adds a guard node before tool execution and an audit node after, using native LangGraph interrupt semantics for `HOLD` verdicts.
+
+## Installation
+
+```bash
+npm install @atbash/atbash-langgraph
+```
+
+Peer dependencies:
+
+```bash
+npm install @langchain/core @langchain/langgraph
+```
+
+## When To Use It
+
+Use this package when:
+
+- your app already uses LangGraph
+- your graph has a distinct `agent` phase and `tools` phase
+- you want `HOLD` to pause execution using LangGraph interrupt semantics
+- you want audit logging after the tool phase
+
+## Quick Start
+
+```ts
+import { loadAgent } from "@atbash/sdk";
+import { StateGraph, START, END, MemorySaver } from "@langchain/langgraph";
+import { AtbashStateAnnotation, addAtbashSafety } from "@atbash/atbash-langgraph";
+
+const builder = new StateGraph(AtbashStateAnnotation)
+  .addNode("agent", agentNode)
+  .addNode("tools", toolsNode)
+  .addEdge(START, "agent")
+  .addConditionalEdges("agent", routeAfterAgent);
+
+addAtbashSafety(builder, {
+  privkey: process.env.ATBASH_AGENT_PRIVKEY,
+});
+
+const app = builder.compile({ checkpointer: new MemorySaver() });
+```
+
+## API
+
+### `addAtbashSafety(builder, opts)`
+
+Convenience helper that wires `atbash_guard` and `atbash_audit` into your graph.
+
+Assumes your graph has nodes named `agent` and `tools`. If your layout differs, use `createGuardNode()` and `createAuditNode()` directly.
+
+| Option | Type | Description |
+|---|---|---|
+| `privkey` | `string` | Agent private key (falls back to `ATBASH_AGENT_PRIVKEY` env var) |
+| `agent` | `AgentAuth` | Pre-loaded agent (alternative to `privkey`) |
+| `endpoint` | `string` | Override Atbash endpoint |
+
+### `createGuardNode(opts)`
+
+Creates the pre-tool safety node. Calls `client.auditToolCall()` for every tool call in the last AI message.
+
+Returns a node function that writes `atbashVerdict`, `atbashReason`, `atbashToolCallId` to state.
+
+### `createAuditNode(opts)`
+
+Creates the post-tool audit node. Fire-and-forget call to `logToolCall()` — errors are suppressed so they never break the graph.
+
+### `AtbashStateAnnotation`
+
+Extends `MessagesAnnotation` with Atbash fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `atbashVerdict` | `string \| null` | Last verdict from the guard node |
+| `atbashReason` | `string \| null` | Reason from the judge |
+| `atbashToolCallId` | `string \| null` | Tool call ID for polling or HOLD resume |
+| `atbashConfidence` | `number \| null` | Confidence score |
+
+### `createJudgeTool(agent, endpoint?)`
+
+Optional: creates an `atbash_safety_check` LangChain tool for direct LLM access to the judge.
+
+## Verdict Handling
+
+| Verdict | Meaning | Graph Behavior |
+|---|---|---|
+| `ALLOW` | Safe to proceed | Routes to `tools` node |
+| `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 |
+
+## HOLD / Resume Pattern
+
+```ts
+import { Command, isInterrupted } from "@langchain/langgraph";
+
+const result = await app.invoke(input, config);
+
+if (isInterrupted(result)) {
+  const payload = result.__interrupt__[0]?.value;
+  // show payload to operator ...
+
+  const approved = await app.invoke(
+    new Command({ resume: "approve" }),
+    config,
+  );
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ATBASH_AGENT_PRIVKEY` | Yes (if not passing `agent`) | Your Atbash agent private key |
+| `ATBASH_ENDPOINT` | No | Override the default Atbash endpoint (`https://atbash.ai`) |
+
+## What This Package Does Not Do
+
+- It does not invent your graph structure.
+- It does not automatically find your tool node if you use a custom layout.
+- It does not execute operator review — it only exposes pause/resume mechanics.
+
+## Example
+
+A runnable example is in [`examples/langgraph-runtime-agent/`](./examples/langgraph-runtime-agent/).
+
+```bash
+npm install && npm run build
+ATBASH_AGENT_PRIVKEY=your_key_here node examples/langgraph-runtime-agent/run.mjs
+```

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import * as _langchain_core_messages from '@langchain/core/messages';
+import * as _langchain_langgraph from '@langchain/langgraph';
+import { StateGraph } from '@langchain/langgraph';
+import { AtbashClient, AgentAuth, ClientOpts } from '@atbash/sdk';
+import * as _langchain_core_tools from '@langchain/core/tools';
+import { z } from 'zod';
+
+declare const AtbashStateAnnotation: _langchain_langgraph.AnnotationRoot<{
+    atbashVerdict: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashReason: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashToolCallId: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashConfidence: _langchain_langgraph.BaseChannel<number | null, number | _langchain_langgraph.OverwriteValue<number | null> | null, unknown>;
+    messages: _langchain_langgraph.BaseChannel<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[], _langchain_langgraph.OverwriteValue<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[]> | _langchain_langgraph.Messages, unknown>;
+}>;
+type AtbashState = typeof AtbashStateAnnotation.State;
+
+interface GuardNodeOptions {
+    client: AtbashClient;
+}
+declare function createGuardNode(opts: GuardNodeOptions): (state: AtbashState) => Promise<Partial<AtbashState>>;
+
+interface AuditNodeOptions {
+    agent: AgentAuth;
+    clientOpts?: ClientOpts;
+}
+declare function createAuditNode(opts: AuditNodeOptions): (state: AtbashState) => Promise<Partial<AtbashState>>;
+
+interface AtbashSafetyOptions {
+    agent?: AgentAuth;
+    privkey?: string;
+    endpoint?: string;
+    toolsNode?: string;
+    agentNode?: string;
+}
+declare function addAtbashSafety(builder: StateGraph<AtbashState>, opts: AtbashSafetyOptions): StateGraph<_langchain_langgraph.StateType<{
+    atbashVerdict: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashReason: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashToolCallId: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashConfidence: _langchain_langgraph.BaseChannel<number | null, number | _langchain_langgraph.OverwriteValue<number | null> | null, unknown>;
+    messages: _langchain_langgraph.BaseChannel<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[], _langchain_langgraph.OverwriteValue<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[]> | _langchain_langgraph.Messages, unknown>;
+}>, _langchain_langgraph.StateType<{
+    atbashVerdict: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashReason: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashToolCallId: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashConfidence: _langchain_langgraph.BaseChannel<number | null, number | _langchain_langgraph.OverwriteValue<number | null> | null, unknown>;
+    messages: _langchain_langgraph.BaseChannel<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[], _langchain_langgraph.OverwriteValue<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[]> | _langchain_langgraph.Messages, unknown>;
+}>, Partial<_langchain_langgraph.StateType<{
+    atbashVerdict: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashReason: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashToolCallId: _langchain_langgraph.BaseChannel<string | null, string | _langchain_langgraph.OverwriteValue<string | null> | null, unknown>;
+    atbashConfidence: _langchain_langgraph.BaseChannel<number | null, number | _langchain_langgraph.OverwriteValue<number | null> | null, unknown>;
+    messages: _langchain_langgraph.BaseChannel<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[], _langchain_langgraph.OverwriteValue<_langchain_core_messages.BaseMessage<_langchain_core_messages.MessageStructure<_langchain_core_messages.MessageToolSet>, _langchain_core_messages.MessageType>[]> | _langchain_langgraph.Messages, unknown>;
+}>>, "__start__", _langchain_langgraph.StateDefinition, _langchain_langgraph.StateDefinition, _langchain_langgraph.StateDefinition, unknown, unknown, unknown>;
+
+declare function createJudgeTool(agent: AgentAuth, endpoint?: string): _langchain_core_tools.DynamicStructuredTool<z.ZodObject<{
+    action: z.ZodString;
+    context: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    action: string;
+    context: string;
+}, {
+    action: string;
+    context: string;
+}>, {
+    action: string;
+    context: string;
+}, {
+    action: string;
+    context: string;
+}, string, unknown, "atbash_safety_check">;
+
+export { type AtbashSafetyOptions, type AtbashState, AtbashStateAnnotation, type AuditNodeOptions, type GuardNodeOptions, addAtbashSafety, createAuditNode, createGuardNode, createJudgeTool };

package/dist/index.js

@@ -0,0 +1,174 @@
+// src/state.ts
+import { Annotation, MessagesAnnotation } from "@langchain/langgraph";
+var AtbashStateAnnotation = Annotation.Root({
+  ...MessagesAnnotation.spec,
+  atbashVerdict: Annotation({
+    reducer: (_current, update) => update,
+    default: () => null
+  }),
+  atbashReason: Annotation({
+    reducer: (_current, update) => update,
+    default: () => null
+  }),
+  atbashToolCallId: Annotation({
+    reducer: (_current, update) => update,
+    default: () => null
+  }),
+  atbashConfidence: Annotation({
+    reducer: (_current, update) => update,
+    default: () => null
+  })
+});
+
+// src/nodes/guardNode.ts
+import { ToolMessage } from "@langchain/core/messages";
+import { isGraphBubbleUp } from "@langchain/langgraph";
+function createGuardNode(opts) {
+  return async (state) => {
+    const lastMessage = state.messages[state.messages.length - 1];
+    const toolCalls = lastMessage?.tool_calls ?? [];
+    if (toolCalls.length === 0) {
+      return {
+        atbashVerdict: "ALLOW",
+        atbashReason: "No tool calls detected"
+      };
+    }
+    const actionText = toolCalls.map((toolCall) => `${toolCall.name}(${JSON.stringify(toolCall.args)})`).join("; ");
+    try {
+      const decision = await opts.client.auditToolCall({
+        toolName: toolCalls.map((t) => t.name).join(",") || "langgraph_batch",
+        args: toolCalls,
+        context: `LangGraph agent attempting: ${actionText}`
+      });
+      if (decision.verdict === "BLOCK" || decision.verdict === "ERROR") {
+        return {
+          messages: toolCalls.map(
+            (toolCall) => new ToolMessage({
+              tool_call_id: toolCall.id,
+              content: `BLOCKED by Atbash safety policy: ${decision.reason ?? "no reason"}`
+            })
+          ),
+          atbashVerdict: "BLOCK",
+          atbashReason: decision.reason ?? "blocked by Atbash",
+          atbashToolCallId: decision.toolCallId,
+          atbashConfidence: null
+        };
+      }
+      return {
+        atbashVerdict: "ALLOW",
+        atbashReason: decision.reason,
+        atbashToolCallId: decision.toolCallId,
+        atbashConfidence: null
+      };
+    } catch (error) {
+      if (isGraphBubbleUp(error)) {
+        throw error;
+      }
+      const reason = error instanceof Error ? error.message : "Safety check failed";
+      return {
+        messages: toolCalls.map(
+          (toolCall) => new ToolMessage({
+            tool_call_id: toolCall.id,
+            content: `Atbash safety check failed: ${reason}`
+          })
+        ),
+        atbashVerdict: "BLOCK",
+        atbashReason: reason,
+        atbashToolCallId: null,
+        atbashConfidence: null
+      };
+    }
+  };
+}
+
+// src/nodes/auditNode.ts
+import { logToolCall } from "@atbash/sdk";
+
+// src/utils.ts
+function truncateText(value, max = 500) {
+  return value.length <= max ? value : `${value.slice(0, max - 3)}...`;
+}
+
+// src/nodes/auditNode.ts
+function createAuditNode(opts) {
+  return async (state) => {
+    const lastMessage = state.messages[state.messages.length - 1];
+    const content = typeof lastMessage?.content === "string" ? lastMessage.content : JSON.stringify(lastMessage?.content ?? "");
+    try {
+      await logToolCall(
+        truncateText(content, 500),
+        "LangGraph tool execution completed",
+        opts.agent,
+        void 0,
+        void 0,
+        opts.clientOpts
+      );
+    } catch {
+    }
+    return {};
+  };
+}
+
+// src/builder.ts
+import {
+  createAtbashClient,
+  loadAgent
+} from "@atbash/sdk";
+function addAtbashSafety(builder, opts) {
+  const privkey = opts.privkey ?? process.env.ATBASH_AGENT_PRIVKEY;
+  const agent = opts.agent ?? loadAgent(privkey ?? "");
+  const clientOpts = opts.endpoint ? { endpoint: opts.endpoint } : void 0;
+  const client = createAtbashClient({
+    keyPair: { privKey: agent.privkey, pubKey: agent.pubkey },
+    judge: opts.endpoint ? { endpoint: opts.endpoint } : void 0
+  });
+  const graph = builder;
+  const toolsNode = opts.toolsNode ?? "tools";
+  const agentNode = opts.agentNode ?? "agent";
+  graph.addNode("atbash_guard", createGuardNode({ client }));
+  graph.addNode("atbash_audit", createAuditNode({ agent, clientOpts }));
+  graph.addConditionalEdges("atbash_guard", (state) => {
+    return state.atbashVerdict === "ALLOW" ? toolsNode : agentNode;
+  });
+  graph.addEdge(toolsNode, "atbash_audit");
+  graph.addEdge("atbash_audit", agentNode);
+  return builder;
+}
+
+// src/tools/judgeTool.ts
+import { judgeAction } from "@atbash/sdk";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+function createJudgeTool(agent, endpoint) {
+  return tool(
+    async ({ action, context }) => {
+      const result = await judgeAction(
+        action,
+        context,
+        agent,
+        endpoint ? { endpoint } : void 0
+      );
+      return JSON.stringify({
+        verdict: result.verdict,
+        reason: result.reason,
+        confidence: result.confidence,
+        tool_call_id: result.tool_call_id
+      });
+    },
+    {
+      name: "atbash_safety_check",
+      description: "Check whether an action is safe before executing it.",
+      schema: z.object({
+        action: z.string().describe("Action to evaluate"),
+        context: z.string().describe("Context for the action")
+      })
+    }
+  );
+}
+export {
+  AtbashStateAnnotation,
+  addAtbashSafety,
+  createAuditNode,
+  createGuardNode,
+  createJudgeTool
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@atbash/atbash-langgraph",
+  "version": "0.0.1",
+  "description": "Atbash safety guard and audit nodes for LangGraph workflows",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "atbash",
+    "langgraph",
+    "langchain",
+    "ai-safety",
+    "agent-safety",
+    "guard",
+    "audit",
+    "policy"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@atbash/sdk": "^0.3.20",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "@langchain/langgraph": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^1.1.45",
+    "@langchain/langgraph": "^1.3.0",
+    "@types/node": "^25.7.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}