@orangecheck/agent-langgraph 1.1.3 → 1.1.5

package/README.md

@@ -65,7 +65,7 @@ Stamp's `content.hash` is a SHA-256 of:
 
 The `graph_state_hash` is itself a `sha256:<64-hex>` over the canonicalized graph state object. Two replays against the same persisted state produce the same hash; a divergent state (extra messages, mutated step counter, anything) produces a different hash and the action envelope will not match.
 
-Default `scope_exercised` is `langgraph:tool(verb=<verb>)`. Override via `scopeExercised`.
+Default `scope_exercised` is `langgraph:tool(verb="<verb>")`, the name quoted so it is read as written. Override via `scopeExercised`.
 
 ## API
 

package/dist/index.js

@@ -34,7 +34,12 @@ function toolCallActionId(agentAddress, signedAt, delegationId, scopeExercised,
   });
 }
 async function stampToolCall(input) {
-  const scopeExercised = input.scopeExercised ?? `langgraph:tool(verb=${input.call.verb})`;
+  const scopeExercised = input.scopeExercised ?? agentCore.canonicalizeScope({
+    product: "langgraph",
+    verb: "tool",
+    // A quoted value, read as written: a tool called "*" is that tool.
+    constraints: [{ key: "verb", op: "=", value: input.call.verb, quoted: true }]
+  });
   agentCore.assertScopeGranted(input.delegation, scopeExercised, "stampToolCall");
   const bytes = canonicalizeToolCall(input.call);
   return agentSigner.signAsAgent({

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["canonicalize","hexEncode","sha256","computeActionId","assertScopeGranted","signAsAgent"],"mappings":";;;;;;;AA0CO,SAAS,eAAe,KAAA,EAAwC;AACnE,EAAA,MAAM,GAAA,GAAMA,uBAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,SAAA,GAAYC,mBAAA,CAAUC,aAAA,CAAO,IAAI,WAAA,GAAc,MAAA,CAAO,GAAA,GAAM,IAAI,CAAC,CAAC,CAAA;AAC7E;AA4BO,SAAS,qBAAqB,CAAA,EAAkC;AACnE,EAAA,MAAM,KAAA,GAAQ;AAAA,IACV,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,SAAS,CAAA,CAAE,MAAA;AAAA,IACX,kBAAkB,CAAA,CAAE,cAAA;AAAA,IACpB,MAAM,CAAA,CAAE;AAAA,GACZ;AACA,EAAA,MAAM,GAAA,GAAMF,uBAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,MAAM,IAAI,CAAA;AAC9C;AAEO,SAAS,aAAa,CAAA,EAA8B;AACvD,EAAA,OAAO,YAAYC,mBAAA,CAAUC,aAAA,CAAO,oBAAA,CAAqB,CAAC,CAAC,CAAC,CAAA;AAChE;AAEO,SAAS,gBAAA,CACZ,YAAA,EACA,QAAA,EACA,YAAA,EACA,gBACA,CAAA,EACM;AACN,EAAA,OAAOC,yBAAA,CAAgB;AAAA,IACnB,OAAA,EAAS,YAAA;AAAA,IACT,YAAA,EAAc,aAAa,CAAC,CAAA;AAAA,IAC5B,cAAA,EAAgB,oBAAA,CAAqB,CAAC,CAAA,CAAE,UAAA;AAAA,IACxC,YAAA,EAAc,mDAAA;AAAA,IACd,SAAA,EAAW,QAAA;AAAA,IACX,aAAA,EAAe,YAAA;AAAA,IACf,eAAA,EAAiB;AAAA,GACpB,CAAA;AACL;AAkBA,eAAsB,cAAc,KAAA,EAAoD;AACpF,EAAA,MAAM,iBACF,KAAA,CAAM,cAAA,IAAkB,CAAA,oBAAA,EAAuB,KAAA,CAAM,KAAK,IAAI,CAAA,CAAA,CAAA;AAElE,EAAAC,4BAAA,CAAmB,KAAA,CAAM,UAAA,EAAY,cAAA,EAAgB,eAAe,CAAA;AAEpE,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,KAAA,CAAM,IAAI,CAAA;AAC7C,EAAA,OAAOC,uBAAA,CAAY;AAAA,IACf,OAAO,KAAA,CAAM,KAAA;AAAA,IACb,YAAY,KAAA,CAAM,UAAA;AAAA,IAClB,OAAA,EAAS,EAAE,IAAA,EAAM,YAAA,CAAa,MAAM,IAAI,CAAA,EAAG,MAAA,EAAQ,KAAA,CAAM,UAAA,EAAW;AAAA,IACpE,IAAA,EAAM,mDAAA;AAAA,IACN,cAAA;AAAA,IACA,UAAU,KAAA,CAAM;AAAA,GACnB,CAAA;AACL;AAwDO,SAAS,WACZ,KAAA,EACiC;AACjC,EAAA,OAAO;AAAA,IACH,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,OAAA,EAAS,OAAO,IAAA,EAAM,GAAA,KAAQ;AAC1B,MAAA,MAAM,IAAA,GAA0B;AAAA,QAC5B,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,MAAM,KAAA,CAAM,IAAA;AAAA,QACZ,IAAA;AAAA,QACA,cAAA,EAAgB,cAAA,CAAe,GAAA,CAAI,UAAU;AAAA,OACjD;AACA,MAAA,MAAM,MAAA,GAAS,MAAM,aAAA,CAAc;AAAA,QAC/B,OAAO,GAAA,CAAI,KAAA;AAAA,QACX,YAAY,GAAA,CAAI,UAAA;AAAA,QAChB;AAAA,OACH,CAAA;AACD,MAAA,MAAM,MAAA,GAAS,MAAM,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA;AACvC,MAAA,OAAO,EAAE,QAAQ,MAAA,EAAO;AAAA,IAC5B;AAAA,GACJ;AACJ","file":"index.js","sourcesContent":["// @orangecheck/agent-langgraph — wrap LangGraph tool-node executions in\n// OC Agent action envelopes.\n//\n// LangGraph's distinguishing feature is graph state: stateful agents\n// composed of typed nodes that share a persisted state object. The\n// compliance-relevant question becomes \"at what graph state did this\n// agent take this action?\" — and the answer must be cryptographically\n// bound to the action receipt.\n//\n// This adapter therefore canonicalizes (verb, args, callId, graph_state_hash)\n// — one extra field over the agent-mcp / agent-anthropic / agent-openai /\n// agent-vercel canonicalization. Two verifiers re-deriving the action from\n// a persisted graph snapshot compute the same envelope id only when the\n// snapshot's state-hash matches; tampered or out-of-order replay fails.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    assertScopeGranted,\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Graph state hashing\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Compute a stable hash of a LangGraph state object. Use canonical JSON\n * (RFC 8785) so reordered keys / repeated serializations produce the same\n * hash. Returns `sha256:<64-hex>`.\n *\n * Most LangGraph deployments persist the state object via a checkpointer\n * (in-memory, postgres, redis, etc.). The state-hash here is over the\n * checkpointer's serialized state at the moment the tool node fires.\n */\nexport function graphStateHash(state: Record<string, unknown>): string {\n    const str = canonicalize(state as unknown as Parameters<typeof canonicalize>[0]);\n    return 'sha256:' + hexEncode(sha256(new TextEncoder().encode(str + '\\n')));\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tool-call canonicalization\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface LangGraphToolCall {\n    /** Stable id assigned by your graph runtime for this tool invocation. */\n    callId: string;\n    /** Tool verb — typically the node name. */\n    verb: string;\n    /** JSON-serializable arguments to the tool node. */\n    args: Record<string, unknown>;\n    /** sha256:<64-hex> of the graph state at the moment of execution. */\n    graphStateHash: string;\n}\n\n/**\n * Produce the canonical bytes for a LangGraph tool call.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"args\":              <canonical JSON of args>,\n *     \"call_id\":           <callId>,\n *     \"graph_state_hash\":  <state hash>,\n *     \"verb\":              <verb>\n *   }\n */\nexport function canonicalizeToolCall(c: LangGraphToolCall): Uint8Array {\n    const canon = {\n        args: c.args,\n        call_id: c.callId,\n        graph_state_hash: c.graphStateHash,\n        verb: c.verb,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolCallHash(c: LangGraphToolCall): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolCall(c)));\n}\n\nexport function toolCallActionId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    c: LangGraphToolCall\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolCallHash(c),\n        content_length: canonicalizeToolCall(c).byteLength,\n        content_mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamping primitive\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AgentContext {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n}\n\nexport interface StampToolCallInput extends AgentContext {\n    call: LangGraphToolCall;\n    /** Defaults to `langgraph:tool(verb=<verb>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\nexport async function stampToolCall(input: StampToolCallInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? `langgraph:tool(verb=${input.call.verb})`;\n\n    assertScopeGranted(input.delegation, scopeExercised, 'stampToolCall');\n\n    const bytes = canonicalizeToolCall(input.call);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolCallHash(input.call), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ocToolNode — convenience wrapper\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface OcToolNodeInput<TArgs extends Record<string, unknown>, TResult> {\n    /** OC Agent verb under which this tool is exercised. */\n    verb: string;\n    /** Your real handler. Receives the same args your LangGraph tool node receives. */\n    execute: (args: TArgs) => Promise<TResult>;\n}\n\nexport interface OcToolNodeWrapped<TArgs extends Record<string, unknown>, TResult> {\n    verb: string;\n    /**\n     * The execute fn your LangGraph node calls. Receives args + a context\n     * object with the agent ref, delegation, callId, current graph state,\n     * and the current graph state.\n     */\n    execute: (\n        args: TArgs,\n        ctx: AgentContext & {\n            callId: string;\n            graphState: Record<string, unknown>;\n        }\n    ) => Promise<{\n        result: TResult;\n        action: ActionEnvelope;\n    }>;\n}\n\n/**\n * Wrap a LangGraph tool-node execute path so it produces an OC Agent\n * action envelope per call. The wrapper computes the graph_state_hash\n * inline from the supplied state object, so the verifier replaying the\n * graph against a persisted snapshot gets the same hash deterministically.\n *\n * Typical shape:\n *\n *   const createInvoice = ocToolNode({\n *     verb: 'invoice.create',\n *     execute: async (args) => myInvoiceCreateImpl(args),\n *   });\n *\n *   const graph = new StateGraph(MyState)\n *     .addNode('createInvoice', async (state) => {\n *       const args = pickToolArgs(state);\n *       const callId = state.lastToolCallId;\n *       const { result, action } = await createInvoice.execute(args, {\n *         agent, delegation, callId, graphState: state,\n *       });\n *       await audit.append(action);\n *       return mergeResultIntoState(state, result);\n *     });\n */\nexport function ocToolNode<TArgs extends Record<string, unknown>, TResult>(\n    input: OcToolNodeInput<TArgs, TResult>\n): OcToolNodeWrapped<TArgs, TResult> {\n    return {\n        verb: input.verb,\n        execute: async (args, ctx) => {\n            const call: LangGraphToolCall = {\n                callId: ctx.callId,\n                verb: input.verb,\n                args,\n                graphStateHash: graphStateHash(ctx.graphState),\n            };\n            const action = await stampToolCall({\n                agent: ctx.agent,\n                delegation: ctx.delegation,\n                call,\n            });\n            const result = await input.execute(args);\n            return { result, action };\n        },\n    };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["canonicalize","hexEncode","sha256","computeActionId","canonicalizeScope","assertScopeGranted","signAsAgent"],"mappings":"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","file":"index.js","sourcesContent":["// @orangecheck/agent-langgraph — wrap LangGraph tool-node executions in\n// OC Agent action envelopes.\n//\n// LangGraph's distinguishing feature is graph state: stateful agents\n// composed of typed nodes that share a persisted state object. The\n// compliance-relevant question becomes \"at what graph state did this\n// agent take this action?\" — and the answer must be cryptographically\n// bound to the action receipt.\n//\n// This adapter therefore canonicalizes (verb, args, callId, graph_state_hash)\n// — one extra field over the agent-mcp / agent-anthropic / agent-openai /\n// agent-vercel canonicalization. Two verifiers re-deriving the action from\n// a persisted graph snapshot compute the same envelope id only when the\n// snapshot's state-hash matches; tampered or out-of-order replay fails.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    assertScopeGranted,\n    canonicalize,\n    canonicalizeScope,\n    computeActionId,\n    hexEncode,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Graph state hashing\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Compute a stable hash of a LangGraph state object. Use canonical JSON\n * (RFC 8785) so reordered keys / repeated serializations produce the same\n * hash. Returns `sha256:<64-hex>`.\n *\n * Most LangGraph deployments persist the state object via a checkpointer\n * (in-memory, postgres, redis, etc.). The state-hash here is over the\n * checkpointer's serialized state at the moment the tool node fires.\n */\nexport function graphStateHash(state: Record<string, unknown>): string {\n    const str = canonicalize(state as unknown as Parameters<typeof canonicalize>[0]);\n    return 'sha256:' + hexEncode(sha256(new TextEncoder().encode(str + '\\n')));\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tool-call canonicalization\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface LangGraphToolCall {\n    /** Stable id assigned by your graph runtime for this tool invocation. */\n    callId: string;\n    /** Tool verb — typically the node name. */\n    verb: string;\n    /** JSON-serializable arguments to the tool node. */\n    args: Record<string, unknown>;\n    /** sha256:<64-hex> of the graph state at the moment of execution. */\n    graphStateHash: string;\n}\n\n/**\n * Produce the canonical bytes for a LangGraph tool call.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"args\":              <canonical JSON of args>,\n *     \"call_id\":           <callId>,\n *     \"graph_state_hash\":  <state hash>,\n *     \"verb\":              <verb>\n *   }\n */\nexport function canonicalizeToolCall(c: LangGraphToolCall): Uint8Array {\n    const canon = {\n        args: c.args,\n        call_id: c.callId,\n        graph_state_hash: c.graphStateHash,\n        verb: c.verb,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolCallHash(c: LangGraphToolCall): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolCall(c)));\n}\n\nexport function toolCallActionId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    c: LangGraphToolCall\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolCallHash(c),\n        content_length: canonicalizeToolCall(c).byteLength,\n        content_mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamping primitive\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AgentContext {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n}\n\nexport interface StampToolCallInput extends AgentContext {\n    call: LangGraphToolCall;\n    /** Defaults to `langgraph:tool(verb=\"<verb>\")` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\nexport async function stampToolCall(input: StampToolCallInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? canonicalizeScope({\n            product: 'langgraph',\n            verb: 'tool',\n            // A quoted value, read as written: a tool called \"*\" is that tool.\n            constraints: [{ key: 'verb', op: '=', value: input.call.verb, quoted: true }],\n        });\n\n    assertScopeGranted(input.delegation, scopeExercised, 'stampToolCall');\n\n    const bytes = canonicalizeToolCall(input.call);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolCallHash(input.call), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ocToolNode — convenience wrapper\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface OcToolNodeInput<TArgs extends Record<string, unknown>, TResult> {\n    /** OC Agent verb under which this tool is exercised. */\n    verb: string;\n    /** Your real handler. Receives the same args your LangGraph tool node receives. */\n    execute: (args: TArgs) => Promise<TResult>;\n}\n\nexport interface OcToolNodeWrapped<TArgs extends Record<string, unknown>, TResult> {\n    verb: string;\n    /**\n     * The execute fn your LangGraph node calls. Receives args + a context\n     * object with the agent ref, delegation, callId, current graph state,\n     * and the current graph state.\n     */\n    execute: (\n        args: TArgs,\n        ctx: AgentContext & {\n            callId: string;\n            graphState: Record<string, unknown>;\n        }\n    ) => Promise<{\n        result: TResult;\n        action: ActionEnvelope;\n    }>;\n}\n\n/**\n * Wrap a LangGraph tool-node execute path so it produces an OC Agent\n * action envelope per call. The wrapper computes the graph_state_hash\n * inline from the supplied state object, so the verifier replaying the\n * graph against a persisted snapshot gets the same hash deterministically.\n *\n * Typical shape:\n *\n *   const createInvoice = ocToolNode({\n *     verb: 'invoice.create',\n *     execute: async (args) => myInvoiceCreateImpl(args),\n *   });\n *\n *   const graph = new StateGraph(MyState)\n *     .addNode('createInvoice', async (state) => {\n *       const args = pickToolArgs(state);\n *       const callId = state.lastToolCallId;\n *       const { result, action } = await createInvoice.execute(args, {\n *         agent, delegation, callId, graphState: state,\n *       });\n *       await audit.append(action);\n *       return mergeResultIntoState(state, result);\n *     });\n */\nexport function ocToolNode<TArgs extends Record<string, unknown>, TResult>(\n    input: OcToolNodeInput<TArgs, TResult>\n): OcToolNodeWrapped<TArgs, TResult> {\n    return {\n        verb: input.verb,\n        execute: async (args, ctx) => {\n            const call: LangGraphToolCall = {\n                callId: ctx.callId,\n                verb: input.verb,\n                args,\n                graphStateHash: graphStateHash(ctx.graphState),\n            };\n            const action = await stampToolCall({\n                agent: ctx.agent,\n                delegation: ctx.delegation,\n                call,\n            });\n            const result = await input.execute(args);\n            return { result, action };\n        },\n    };\n}\n"]}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { sha256 } from '@noble/hashes/sha256';
-import { canonicalize, hexEncode, computeActionId, assertScopeGranted } from '@orangecheck/agent-core';
+import { canonicalize, hexEncode, computeActionId, canonicalizeScope, assertScopeGranted } from '@orangecheck/agent-core';
 import { signAsAgent } from '@orangecheck/agent-signer';
 
 // src/index.ts
@@ -32,7 +32,12 @@ function toolCallActionId(agentAddress, signedAt, delegationId, scopeExercised,
   });
 }
 async function stampToolCall(input) {
-  const scopeExercised = input.scopeExercised ?? `langgraph:tool(verb=${input.call.verb})`;
+  const scopeExercised = input.scopeExercised ?? canonicalizeScope({
+    product: "langgraph",
+    verb: "tool",
+    // A quoted value, read as written: a tool called "*" is that tool.
+    constraints: [{ key: "verb", op: "=", value: input.call.verb, quoted: true }]
+  });
   assertScopeGranted(input.delegation, scopeExercised, "stampToolCall");
   const bytes = canonicalizeToolCall(input.call);
   return signAsAgent({

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AA0CO,SAAS,eAAe,KAAA,EAAwC;AACnE,EAAA,MAAM,GAAA,GAAM,aAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,SAAA,GAAY,SAAA,CAAU,MAAA,CAAO,IAAI,WAAA,GAAc,MAAA,CAAO,GAAA,GAAM,IAAI,CAAC,CAAC,CAAA;AAC7E;AA4BO,SAAS,qBAAqB,CAAA,EAAkC;AACnE,EAAA,MAAM,KAAA,GAAQ;AAAA,IACV,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,SAAS,CAAA,CAAE,MAAA;AAAA,IACX,kBAAkB,CAAA,CAAE,cAAA;AAAA,IACpB,MAAM,CAAA,CAAE;AAAA,GACZ;AACA,EAAA,MAAM,GAAA,GAAM,aAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,MAAM,IAAI,CAAA;AAC9C;AAEO,SAAS,aAAa,CAAA,EAA8B;AACvD,EAAA,OAAO,YAAY,SAAA,CAAU,MAAA,CAAO,oBAAA,CAAqB,CAAC,CAAC,CAAC,CAAA;AAChE;AAEO,SAAS,gBAAA,CACZ,YAAA,EACA,QAAA,EACA,YAAA,EACA,gBACA,CAAA,EACM;AACN,EAAA,OAAO,eAAA,CAAgB;AAAA,IACnB,OAAA,EAAS,YAAA;AAAA,IACT,YAAA,EAAc,aAAa,CAAC,CAAA;AAAA,IAC5B,cAAA,EAAgB,oBAAA,CAAqB,CAAC,CAAA,CAAE,UAAA;AAAA,IACxC,YAAA,EAAc,mDAAA;AAAA,IACd,SAAA,EAAW,QAAA;AAAA,IACX,aAAA,EAAe,YAAA;AAAA,IACf,eAAA,EAAiB;AAAA,GACpB,CAAA;AACL;AAkBA,eAAsB,cAAc,KAAA,EAAoD;AACpF,EAAA,MAAM,iBACF,KAAA,CAAM,cAAA,IAAkB,CAAA,oBAAA,EAAuB,KAAA,CAAM,KAAK,IAAI,CAAA,CAAA,CAAA;AAElE,EAAA,kBAAA,CAAmB,KAAA,CAAM,UAAA,EAAY,cAAA,EAAgB,eAAe,CAAA;AAEpE,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,KAAA,CAAM,IAAI,CAAA;AAC7C,EAAA,OAAO,WAAA,CAAY;AAAA,IACf,OAAO,KAAA,CAAM,KAAA;AAAA,IACb,YAAY,KAAA,CAAM,UAAA;AAAA,IAClB,OAAA,EAAS,EAAE,IAAA,EAAM,YAAA,CAAa,MAAM,IAAI,CAAA,EAAG,MAAA,EAAQ,KAAA,CAAM,UAAA,EAAW;AAAA,IACpE,IAAA,EAAM,mDAAA;AAAA,IACN,cAAA;AAAA,IACA,UAAU,KAAA,CAAM;AAAA,GACnB,CAAA;AACL;AAwDO,SAAS,WACZ,KAAA,EACiC;AACjC,EAAA,OAAO;AAAA,IACH,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,OAAA,EAAS,OAAO,IAAA,EAAM,GAAA,KAAQ;AAC1B,MAAA,MAAM,IAAA,GAA0B;AAAA,QAC5B,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,MAAM,KAAA,CAAM,IAAA;AAAA,QACZ,IAAA;AAAA,QACA,cAAA,EAAgB,cAAA,CAAe,GAAA,CAAI,UAAU;AAAA,OACjD;AACA,MAAA,MAAM,MAAA,GAAS,MAAM,aAAA,CAAc;AAAA,QAC/B,OAAO,GAAA,CAAI,KAAA;AAAA,QACX,YAAY,GAAA,CAAI,UAAA;AAAA,QAChB;AAAA,OACH,CAAA;AACD,MAAA,MAAM,MAAA,GAAS,MAAM,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA;AACvC,MAAA,OAAO,EAAE,QAAQ,MAAA,EAAO;AAAA,IAC5B;AAAA,GACJ;AACJ","file":"index.mjs","sourcesContent":["// @orangecheck/agent-langgraph — wrap LangGraph tool-node executions in\n// OC Agent action envelopes.\n//\n// LangGraph's distinguishing feature is graph state: stateful agents\n// composed of typed nodes that share a persisted state object. The\n// compliance-relevant question becomes \"at what graph state did this\n// agent take this action?\" — and the answer must be cryptographically\n// bound to the action receipt.\n//\n// This adapter therefore canonicalizes (verb, args, callId, graph_state_hash)\n// — one extra field over the agent-mcp / agent-anthropic / agent-openai /\n// agent-vercel canonicalization. Two verifiers re-deriving the action from\n// a persisted graph snapshot compute the same envelope id only when the\n// snapshot's state-hash matches; tampered or out-of-order replay fails.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    assertScopeGranted,\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Graph state hashing\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Compute a stable hash of a LangGraph state object. Use canonical JSON\n * (RFC 8785) so reordered keys / repeated serializations produce the same\n * hash. Returns `sha256:<64-hex>`.\n *\n * Most LangGraph deployments persist the state object via a checkpointer\n * (in-memory, postgres, redis, etc.). The state-hash here is over the\n * checkpointer's serialized state at the moment the tool node fires.\n */\nexport function graphStateHash(state: Record<string, unknown>): string {\n    const str = canonicalize(state as unknown as Parameters<typeof canonicalize>[0]);\n    return 'sha256:' + hexEncode(sha256(new TextEncoder().encode(str + '\\n')));\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tool-call canonicalization\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface LangGraphToolCall {\n    /** Stable id assigned by your graph runtime for this tool invocation. */\n    callId: string;\n    /** Tool verb — typically the node name. */\n    verb: string;\n    /** JSON-serializable arguments to the tool node. */\n    args: Record<string, unknown>;\n    /** sha256:<64-hex> of the graph state at the moment of execution. */\n    graphStateHash: string;\n}\n\n/**\n * Produce the canonical bytes for a LangGraph tool call.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"args\":              <canonical JSON of args>,\n *     \"call_id\":           <callId>,\n *     \"graph_state_hash\":  <state hash>,\n *     \"verb\":              <verb>\n *   }\n */\nexport function canonicalizeToolCall(c: LangGraphToolCall): Uint8Array {\n    const canon = {\n        args: c.args,\n        call_id: c.callId,\n        graph_state_hash: c.graphStateHash,\n        verb: c.verb,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolCallHash(c: LangGraphToolCall): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolCall(c)));\n}\n\nexport function toolCallActionId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    c: LangGraphToolCall\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolCallHash(c),\n        content_length: canonicalizeToolCall(c).byteLength,\n        content_mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamping primitive\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AgentContext {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n}\n\nexport interface StampToolCallInput extends AgentContext {\n    call: LangGraphToolCall;\n    /** Defaults to `langgraph:tool(verb=<verb>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\nexport async function stampToolCall(input: StampToolCallInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? `langgraph:tool(verb=${input.call.verb})`;\n\n    assertScopeGranted(input.delegation, scopeExercised, 'stampToolCall');\n\n    const bytes = canonicalizeToolCall(input.call);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolCallHash(input.call), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ocToolNode — convenience wrapper\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface OcToolNodeInput<TArgs extends Record<string, unknown>, TResult> {\n    /** OC Agent verb under which this tool is exercised. */\n    verb: string;\n    /** Your real handler. Receives the same args your LangGraph tool node receives. */\n    execute: (args: TArgs) => Promise<TResult>;\n}\n\nexport interface OcToolNodeWrapped<TArgs extends Record<string, unknown>, TResult> {\n    verb: string;\n    /**\n     * The execute fn your LangGraph node calls. Receives args + a context\n     * object with the agent ref, delegation, callId, current graph state,\n     * and the current graph state.\n     */\n    execute: (\n        args: TArgs,\n        ctx: AgentContext & {\n            callId: string;\n            graphState: Record<string, unknown>;\n        }\n    ) => Promise<{\n        result: TResult;\n        action: ActionEnvelope;\n    }>;\n}\n\n/**\n * Wrap a LangGraph tool-node execute path so it produces an OC Agent\n * action envelope per call. The wrapper computes the graph_state_hash\n * inline from the supplied state object, so the verifier replaying the\n * graph against a persisted snapshot gets the same hash deterministically.\n *\n * Typical shape:\n *\n *   const createInvoice = ocToolNode({\n *     verb: 'invoice.create',\n *     execute: async (args) => myInvoiceCreateImpl(args),\n *   });\n *\n *   const graph = new StateGraph(MyState)\n *     .addNode('createInvoice', async (state) => {\n *       const args = pickToolArgs(state);\n *       const callId = state.lastToolCallId;\n *       const { result, action } = await createInvoice.execute(args, {\n *         agent, delegation, callId, graphState: state,\n *       });\n *       await audit.append(action);\n *       return mergeResultIntoState(state, result);\n *     });\n */\nexport function ocToolNode<TArgs extends Record<string, unknown>, TResult>(\n    input: OcToolNodeInput<TArgs, TResult>\n): OcToolNodeWrapped<TArgs, TResult> {\n    return {\n        verb: input.verb,\n        execute: async (args, ctx) => {\n            const call: LangGraphToolCall = {\n                callId: ctx.callId,\n                verb: input.verb,\n                args,\n                graphStateHash: graphStateHash(ctx.graphState),\n            };\n            const action = await stampToolCall({\n                agent: ctx.agent,\n                delegation: ctx.delegation,\n                call,\n            });\n            const result = await input.execute(args);\n            return { result, action };\n        },\n    };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AA2CO,SAAS,eAAe,KAAA,EAAwC;AACnE,EAAA,MAAM,GAAA,GAAM,aAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,SAAA,GAAY,SAAA,CAAU,MAAA,CAAO,IAAI,WAAA,GAAc,MAAA,CAAO,GAAA,GAAM,IAAI,CAAC,CAAC,CAAA;AAC7E;AA4BO,SAAS,qBAAqB,CAAA,EAAkC;AACnE,EAAA,MAAM,KAAA,GAAQ;AAAA,IACV,MAAM,CAAA,CAAE,IAAA;AAAA,IACR,SAAS,CAAA,CAAE,MAAA;AAAA,IACX,kBAAkB,CAAA,CAAE,cAAA;AAAA,IACpB,MAAM,CAAA,CAAE;AAAA,GACZ;AACA,EAAA,MAAM,GAAA,GAAM,aAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,MAAM,IAAI,CAAA;AAC9C;AAEO,SAAS,aAAa,CAAA,EAA8B;AACvD,EAAA,OAAO,YAAY,SAAA,CAAU,MAAA,CAAO,oBAAA,CAAqB,CAAC,CAAC,CAAC,CAAA;AAChE;AAEO,SAAS,gBAAA,CACZ,YAAA,EACA,QAAA,EACA,YAAA,EACA,gBACA,CAAA,EACM;AACN,EAAA,OAAO,eAAA,CAAgB;AAAA,IACnB,OAAA,EAAS,YAAA;AAAA,IACT,YAAA,EAAc,aAAa,CAAC,CAAA;AAAA,IAC5B,cAAA,EAAgB,oBAAA,CAAqB,CAAC,CAAA,CAAE,UAAA;AAAA,IACxC,YAAA,EAAc,mDAAA;AAAA,IACd,SAAA,EAAW,QAAA;AAAA,IACX,aAAA,EAAe,YAAA;AAAA,IACf,eAAA,EAAiB;AAAA,GACpB,CAAA;AACL;AAkBA,eAAsB,cAAc,KAAA,EAAoD;AACpF,EAAA,MAAM,cAAA,GACF,KAAA,CAAM,cAAA,IAAkB,iBAAA,CAAkB;AAAA,IACtC,OAAA,EAAS,WAAA;AAAA,IACT,IAAA,EAAM,MAAA;AAAA;AAAA,IAEN,WAAA,EAAa,CAAC,EAAE,GAAA,EAAK,MAAA,EAAQ,EAAA,EAAI,GAAA,EAAK,KAAA,EAAO,KAAA,CAAM,IAAA,CAAK,IAAA,EAAM,MAAA,EAAQ,MAAM;AAAA,GAC/E,CAAA;AAEL,EAAA,kBAAA,CAAmB,KAAA,CAAM,UAAA,EAAY,cAAA,EAAgB,eAAe,CAAA;AAEpE,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,KAAA,CAAM,IAAI,CAAA;AAC7C,EAAA,OAAO,WAAA,CAAY;AAAA,IACf,OAAO,KAAA,CAAM,KAAA;AAAA,IACb,YAAY,KAAA,CAAM,UAAA;AAAA,IAClB,OAAA,EAAS,EAAE,IAAA,EAAM,YAAA,CAAa,MAAM,IAAI,CAAA,EAAG,MAAA,EAAQ,KAAA,CAAM,UAAA,EAAW;AAAA,IACpE,IAAA,EAAM,mDAAA;AAAA,IACN,cAAA;AAAA,IACA,UAAU,KAAA,CAAM;AAAA,GACnB,CAAA;AACL;AAwDO,SAAS,WACZ,KAAA,EACiC;AACjC,EAAA,OAAO;AAAA,IACH,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,OAAA,EAAS,OAAO,IAAA,EAAM,GAAA,KAAQ;AAC1B,MAAA,MAAM,IAAA,GAA0B;AAAA,QAC5B,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,MAAM,KAAA,CAAM,IAAA;AAAA,QACZ,IAAA;AAAA,QACA,cAAA,EAAgB,cAAA,CAAe,GAAA,CAAI,UAAU;AAAA,OACjD;AACA,MAAA,MAAM,MAAA,GAAS,MAAM,aAAA,CAAc;AAAA,QAC/B,OAAO,GAAA,CAAI,KAAA;AAAA,QACX,YAAY,GAAA,CAAI,UAAA;AAAA,QAChB;AAAA,OACH,CAAA;AACD,MAAA,MAAM,MAAA,GAAS,MAAM,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA;AACvC,MAAA,OAAO,EAAE,QAAQ,MAAA,EAAO;AAAA,IAC5B;AAAA,GACJ;AACJ","file":"index.mjs","sourcesContent":["// @orangecheck/agent-langgraph — wrap LangGraph tool-node executions in\n// OC Agent action envelopes.\n//\n// LangGraph's distinguishing feature is graph state: stateful agents\n// composed of typed nodes that share a persisted state object. The\n// compliance-relevant question becomes \"at what graph state did this\n// agent take this action?\" — and the answer must be cryptographically\n// bound to the action receipt.\n//\n// This adapter therefore canonicalizes (verb, args, callId, graph_state_hash)\n// — one extra field over the agent-mcp / agent-anthropic / agent-openai /\n// agent-vercel canonicalization. Two verifiers re-deriving the action from\n// a persisted graph snapshot compute the same envelope id only when the\n// snapshot's state-hash matches; tampered or out-of-order replay fails.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    assertScopeGranted,\n    canonicalize,\n    canonicalizeScope,\n    computeActionId,\n    hexEncode,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Graph state hashing\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Compute a stable hash of a LangGraph state object. Use canonical JSON\n * (RFC 8785) so reordered keys / repeated serializations produce the same\n * hash. Returns `sha256:<64-hex>`.\n *\n * Most LangGraph deployments persist the state object via a checkpointer\n * (in-memory, postgres, redis, etc.). The state-hash here is over the\n * checkpointer's serialized state at the moment the tool node fires.\n */\nexport function graphStateHash(state: Record<string, unknown>): string {\n    const str = canonicalize(state as unknown as Parameters<typeof canonicalize>[0]);\n    return 'sha256:' + hexEncode(sha256(new TextEncoder().encode(str + '\\n')));\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Tool-call canonicalization\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface LangGraphToolCall {\n    /** Stable id assigned by your graph runtime for this tool invocation. */\n    callId: string;\n    /** Tool verb — typically the node name. */\n    verb: string;\n    /** JSON-serializable arguments to the tool node. */\n    args: Record<string, unknown>;\n    /** sha256:<64-hex> of the graph state at the moment of execution. */\n    graphStateHash: string;\n}\n\n/**\n * Produce the canonical bytes for a LangGraph tool call.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"args\":              <canonical JSON of args>,\n *     \"call_id\":           <callId>,\n *     \"graph_state_hash\":  <state hash>,\n *     \"verb\":              <verb>\n *   }\n */\nexport function canonicalizeToolCall(c: LangGraphToolCall): Uint8Array {\n    const canon = {\n        args: c.args,\n        call_id: c.callId,\n        graph_state_hash: c.graphStateHash,\n        verb: c.verb,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolCallHash(c: LangGraphToolCall): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolCall(c)));\n}\n\nexport function toolCallActionId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    c: LangGraphToolCall\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolCallHash(c),\n        content_length: canonicalizeToolCall(c).byteLength,\n        content_mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamping primitive\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AgentContext {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n}\n\nexport interface StampToolCallInput extends AgentContext {\n    call: LangGraphToolCall;\n    /** Defaults to `langgraph:tool(verb=\"<verb>\")` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\nexport async function stampToolCall(input: StampToolCallInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? canonicalizeScope({\n            product: 'langgraph',\n            verb: 'tool',\n            // A quoted value, read as written: a tool called \"*\" is that tool.\n            constraints: [{ key: 'verb', op: '=', value: input.call.verb, quoted: true }],\n        });\n\n    assertScopeGranted(input.delegation, scopeExercised, 'stampToolCall');\n\n    const bytes = canonicalizeToolCall(input.call);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolCallHash(input.call), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.langgraph-tool-call+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// ocToolNode — convenience wrapper\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface OcToolNodeInput<TArgs extends Record<string, unknown>, TResult> {\n    /** OC Agent verb under which this tool is exercised. */\n    verb: string;\n    /** Your real handler. Receives the same args your LangGraph tool node receives. */\n    execute: (args: TArgs) => Promise<TResult>;\n}\n\nexport interface OcToolNodeWrapped<TArgs extends Record<string, unknown>, TResult> {\n    verb: string;\n    /**\n     * The execute fn your LangGraph node calls. Receives args + a context\n     * object with the agent ref, delegation, callId, current graph state,\n     * and the current graph state.\n     */\n    execute: (\n        args: TArgs,\n        ctx: AgentContext & {\n            callId: string;\n            graphState: Record<string, unknown>;\n        }\n    ) => Promise<{\n        result: TResult;\n        action: ActionEnvelope;\n    }>;\n}\n\n/**\n * Wrap a LangGraph tool-node execute path so it produces an OC Agent\n * action envelope per call. The wrapper computes the graph_state_hash\n * inline from the supplied state object, so the verifier replaying the\n * graph against a persisted snapshot gets the same hash deterministically.\n *\n * Typical shape:\n *\n *   const createInvoice = ocToolNode({\n *     verb: 'invoice.create',\n *     execute: async (args) => myInvoiceCreateImpl(args),\n *   });\n *\n *   const graph = new StateGraph(MyState)\n *     .addNode('createInvoice', async (state) => {\n *       const args = pickToolArgs(state);\n *       const callId = state.lastToolCallId;\n *       const { result, action } = await createInvoice.execute(args, {\n *         agent, delegation, callId, graphState: state,\n *       });\n *       await audit.append(action);\n *       return mergeResultIntoState(state, result);\n *     });\n */\nexport function ocToolNode<TArgs extends Record<string, unknown>, TResult>(\n    input: OcToolNodeInput<TArgs, TResult>\n): OcToolNodeWrapped<TArgs, TResult> {\n    return {\n        verb: input.verb,\n        execute: async (args, ctx) => {\n            const call: LangGraphToolCall = {\n                callId: ctx.callId,\n                verb: input.verb,\n                args,\n                graphStateHash: graphStateHash(ctx.graphState),\n            };\n            const action = await stampToolCall({\n                agent: ctx.agent,\n                delegation: ctx.delegation,\n                call,\n            });\n            const result = await input.execute(args);\n            return { result, action };\n        },\n    };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-langgraph",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Wrap LangGraph tool nodes with OC Agent scope enforcement and emit a signed agent-action envelope per execution. Binds the action to the graph-state hash so verifiers replay the audit against the persisted graph snapshot.",
   "keywords": [
     "bitcoin",
@@ -52,8 +52,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@orangecheck/agent-core": "^2.9.0",
-    "@orangecheck/agent-signer": "^0.5.2"
+    "@orangecheck/agent-core": "^2.10.0",
+    "@orangecheck/agent-signer": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/src/default-scope.test.ts

@@ -0,0 +1,52 @@
+// The default exercised scope names the tool as a quoted value, so the name is
+// read as written: a tool called "*" is that tool, not every tool.
+import { describe, expect, it } from 'vitest';
+
+import { parseScope, verifyAction } from '@orangecheck/agent-core';
+import { createDelegation } from '@orangecheck/agent-signer';
+
+import { stampToolCall } from './index.js';
+
+const PRINCIPAL = 'bc1qprincipal000000000000000000000000000000';
+const AGENT = 'bc1qagent0000000000000000000000000000000000';
+const fakeSign = (address: string) => async (msg: string) =>
+    Buffer.from(`sig:${address}:${msg}`, 'utf8').toString('base64');
+const fakeVerify = async (msg: string, sig: string, address: string) =>
+    sig === Buffer.from(`sig:${address}:${msg}`, 'utf8').toString('base64');
+
+const stamp = async (scope: string, name: string) => {
+    const delegation = await createDelegation({
+        principal: { address: PRINCIPAL, signMessage: fakeSign(PRINCIPAL) },
+        agentAddress: AGENT,
+        scopes: [scope],
+        ttlMs: 60 * 60 * 1000,
+    });
+    const action = await stampToolCall({
+        agent: { address: AGENT, signMessage: fakeSign(AGENT) },
+        delegation,
+        call: { callId: 'c1', verb: name, args: {} },
+    });
+    const r = await verifyAction({ action, delegation, verifyBip322: fakeVerify, skipRevocationCheck: true });
+    return { action, ok: r.ok };
+};
+
+describe('the default exercised scope', () => {
+    it('quotes the name', async () => {
+        const { action, ok } = await stamp('langgraph:tool(verb=search)', 'search');
+        expect(action.scope_exercised).toBe('langgraph:tool(verb="search")');
+        expect(ok).toBe(true);
+    });
+
+    it('stamps a tool called "*" as that tool, not every tool', async () => {
+        const { action, ok } = await stamp('langgraph:tool(verb="*")', '*');
+        expect(action.scope_exercised).toBe('langgraph:tool(verb="*")');
+        expect(ok).toBe(true);
+    });
+
+    it('keeps scope punctuation in a name as part of the name', async () => {
+        const { action, ok } = await stamp('langgraph:tool(verb="a,b")', 'a,b');
+        const c = parseScope(action.scope_exercised).constraints[0];
+        expect(c).toEqual({ key: 'verb', op: '=', value: 'a,b', quoted: true });
+        expect(ok).toBe(true);
+    });
+});

package/src/index.ts

@@ -17,6 +17,7 @@ import { sha256 } from '@noble/hashes/sha256';
 import {
     assertScopeGranted,
     canonicalize,
+    canonicalizeScope,
     computeActionId,
     hexEncode,
     type DelegationEnvelope,
@@ -115,14 +116,19 @@ export interface AgentContext {
 
 export interface StampToolCallInput extends AgentContext {
     call: LangGraphToolCall;
-    /** Defaults to `langgraph:tool(verb=<verb>)` — the tightest admissible sub-scope. */
+    /** Defaults to `langgraph:tool(verb="<verb>")` — the tightest admissible sub-scope. */
     scopeExercised?: string;
     signedAt?: Date;
 }
 
 export async function stampToolCall(input: StampToolCallInput): Promise<ActionEnvelope> {
     const scopeExercised =
-        input.scopeExercised ?? `langgraph:tool(verb=${input.call.verb})`;
+        input.scopeExercised ?? canonicalizeScope({
+            product: 'langgraph',
+            verb: 'tool',
+            // A quoted value, read as written: a tool called "*" is that tool.
+            constraints: [{ key: 'verb', op: '=', value: input.call.verb, quoted: true }],
+        });
 
     assertScopeGranted(input.delegation, scopeExercised, 'stampToolCall');